fix(hud): stop being born click-through, wait for the renderer to ask

[EtienneLescot]

Refs #266 — the HUD painted on screen, and every click, drag and button dead from the very first launch.

What was wrong

createHudOverlayWindow() asked for click-through twice: once at construction, and once from the renderer's mount effect (hud-overlay-ignore-mouse-events). Only the second one is safe.

On Windows, setIgnoreMouseEvents(true, { forward: true }) is not a Chromium hit-test — Electron installs a global WH_MOUSE_LL hook and reposts WM_MOUSEMOVE by hand (native_window_views_win.cc:678):

void NativeWindowViews::SetForwardMouseMessages(bool forward) {
  if (forward && !forwarding_mouse_messages_) {
    forwarding_mouse_messages_ = true;
    ...
    if (!mouse_hook_) {
      mouse_hook_ = SetWindowsHookEx(WH_MOUSE_LL, MouseHookProc, nullptr, 0);
    }
  }

That hook is the only route out of the state, and its install is latched:

• Chromium delivers no pointermove to a window it has made input-transparent, so the renderer can never ask to leave click-through on its own.
• The install sits behind !forwarding_mouse_messages_, so a later forward: true is a no-op. Electron only retries after a setIgnoreMouseEvents(false) (the ERROR_INVALID_HOOK_HANDLE branch, l.706) — which is precisely the call a dead hook prevents.

Deadlock. One hook refused, or silently revoked by Windows for overrunning LowLevelHooksTimeout (300 ms), and the bar is painted, inert, forever — with no user-reachable way back.

And construction is the worst moment to ask: that hook callback runs on the main thread, which at that point is still booting the app.

The change

One statement deleted. The renderer already asks, on mount, a frame or two later — over IPC, on a main thread that is provably pumping messages.

The failure mode inverts: if the ask never arrives, the bar stays clickable instead of becoming a ghost.

Cost — measured, ~85 ms

An invisible 820×560 rectangle can swallow one desktop click between ready-to-show and LaunchWindow's mount effect. Timed in the real app: 83 ms and 90 ms over two runs (a third read negative — an IPC still in flight from the destroyed HUD landing on the new window — and is discarded). LaunchWindow is a static import, not lazy, so that window does not stretch.

It can be closed to ~0 by asking from src/main.tsx at module scope, before React mounts. Deliberately not done: that moves the SetWindowsHookEx install earlier into the boot, back toward the busy main thread this PR is trying to get it away from. One swallowed click is recoverable; the deadlock is not.

One swallowed click, not a dragged HUD. The obvious worry is 2bc9d70 — the drag region that sat on the window root, which on Linux (no click-through) meant pressing empty space dragged the HUD from a spot the user was aiming past. That needed two ingredients, and the second is gone: the region now lives on the grab handle, and it is gated nativeDrag={isLinuxHud}, so on Windows/macOS there is no -webkit-app-region: drag in the HUD at all. .hudAnchor is pointer-events: none on top of that. Nothing in those 85 ms can move the window.

Not Windows-only, and what each platform sees

The deleted line ran on all three platforms. What changes:

• Windows / macOS — the HUD is a normal input target for those ~85 ms, then identical to before.
• Linux — end state unchanged. LaunchWindow gates on isLinuxHud and never requests click-through there, so this line was the only thing making the HUD input-transparent on Linux, transiently, until mount. Removing it removes a transient hole rather than opening one.

Nothing else depended on the state: setHudOverlayIgnoreMouseEvents has exactly two call sites, both in LaunchWindow.tsx. git log -S dates the deleted line to a bulk "ui revamp" commit — it was never a targeted fix for anything. The countdown overlay keeps its own setIgnoreMouseEvents(true) at construction on purpose: no forward, so no hook, no latch, and it is meant to stay click-through for its whole life.

Not verifiable here: macOS. No machine.

What this does not cover

A hook revoked mid-session still deadlocks. Closing that needs an independent wake-up in the main process (poll screen.getCursorScreenPoint() while click-through, ~12 lines). Left out on purpose — it addresses a symptom nobody has reported yet, and this PR targets the RC window.

Getting this into 1.9.0

Targets main, per AGENTS.md § PR & commit conventions. The RC window is open (1.9.0-rc.2), so shipping it in 1.9.0 means a cherry-pick onto release/v1.9.0 once this lands — which is what § Release branches asks for.

Verification

• biome check clean, tsc --noEmit clean.
• Playwright e2e on Windows — results in a comment below.
• The deadlock itself is not reproducible on demand (it needs the hook to be refused or revoked), so the e2e evidence is non-regression of the normal path: the HUD still goes click-through after mount, and the bar still takes clicks.

Summary by CodeRabbit

• Bug Fixes

  • Improved HUD mouse interaction handling during startup.
  • Click-through behavior is now enabled after the HUD is ready, helping prevent missed or unexpected mouse interactions.

• Tests

  • Added Windows-native coverage to verify the HUD’s click-through behavior and startup sequence.

[coderabbitai]

📝 Walkthrough

Walkthrough

The HUD no longer enables click-through during construction. The renderer now triggers the existing IPC flow, and a Windows-native E2E test verifies the deferred setIgnoreMouseEvents call.

Changes

HUD click-through handling

Layer / File(s)	Summary
Defer native mouse handling electron/windows.ts	HUD creation no longer calls setIgnoreMouseEvents before renderer initialization.
Verify renderer-driven click-through tests/e2e/windows-native-checklist.spec.ts	The Windows E2E test records native calls, verifies no construction-time call, checks the renderer request, and restores the patched method during cleanup.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant HUDCreation
  participant HUDRenderer
  participant IPC
  participant BrowserWindow
  HUDCreation->>BrowserWindow: Create HUD without mouse-event ignoring
  HUDRenderer->>IPC: Request click-through
  IPC->>BrowserWindow: setIgnoreMouseEvents(true, { forward: true })

Loading

Possibly related PRs

• getopenscreen/openscreen#43: Both modify electron/windows.ts and BrowserWindow behavior.
• getopenscreen/openscreen#110: Both modify HUD overlay mouse-event ignoring in electron/windows.ts.

Suggested reviewers: siddharthvaddem

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly describes the main HUD behavior change: delaying click-through until the renderer requests it.
Description check	✅ Passed	The description thoroughly covers the problem, solution, platform impact, risks, issue reference, and verification results.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/hud-born-click-through

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[EtienneLescot]

e2e run — Windows 11, real Electron app (dist-electron/main.js, HEADLESS=true)

Suite	Result	Signal for this PR
windows-native-checklist.spec.ts	2 passed, 2 failed	yes — real Electron main process
v4-shell.spec.ts + editor-smoke.spec.ts	5 passed	none (browser shim, no Electron main)
gif-export.spec.ts	not run	none

The 2 failures are #130, pre-existing. launch-open-video-button / launch-open-project-button appear nowhere in src/ — those two tests cannot pass on any commit.

gif-export could not run here, not "failed": this worktree has no native compositor addon (no *.node) and no vendored ffmpeg (no thirdparty/), so the export path has nothing to call. This PR touches no export code.

The test added in c6c6fca

The existing suite covers the HUD only from the renderer's side, which is exactly the side that cannot see this bug. The new one asserts both halves of the contract:

1. Nothing calls setIgnoreMouseEvents while the HUD is being constructed. The window is recreated through the app's own path (second-instance → showMainWindow → createHudOverlayWindow) with the native call taped, and the tape is read back with no await in between — so no renderer IPC can contaminate what is meant to be construction only.
2. The renderer still asks for it after mount — [true, { forward: true }] must land within 20 s.

Ablated, because a test that passes both ways proves nothing: restoring the deleted line turns duringConstruction into [[true, { forward: true }]] and assertion 1 fails.

✓ the HUD asks for click-through instead of being born with it (3.2s)   # with the fix
✗ expect(duringConstruction).toEqual([])                                # line restored

What the e2e cannot prove

Click-through is an OS window attribute; Playwright synthesizes input inside Chromium and never crosses the WS_EX_TRANSPARENT boundary. No Playwright test can observe a real click passing through — or failing to. And the deadlock itself needs SetWindowsHookEx to be refused or revoked, which is not reproducible on demand.

So the evidence here is: the construction-time call is gone (asserted, ablated), the renderer path that replaces it works in the real app (asserted), and nothing else regressed.

Note

No CI workflow runs Playwright (.github/workflows/ has no test:e2e / playwright reference), so this test is a local guard only. If you want a merge-blocking one, it belongs in the vitest suite — which needs an electron module mock the repo does not have yet (vi.mock("electron"): zero occurrences).