fix(hud): pass clicks through transparent recording overlay

[tanmayapex]

Description

Keep transparent regions of the recording HUD click-through while recording, without making the visible HUD controls, popovers, dragging, or webcam preview unclickable.

Problem and root cause

Starting a recording previously forced the native HUD window to accept mouse events. Because that transparent Electron window spans the work area on supported Windows versions, it intercepted input intended for the website or app underneath it.

The follow-up diagnosis found two additional timing windows in the live path:

• leaving HUD content waited 300 ms before restoring passthrough, and closing a popover waited 150 ms;
• Windows passthrough reassertion deliberately made the full-screen native HUD interactive for 50 ms before restoring the renderer-requested policy.

Those delays made website hover feel abnormal and allowed quick clicks to land on the invisible HUD during recording transitions.

Focused change

• Centralize supported-platform mouse policy in a tested helper and preserve the renderer request both in and out of recording.
• Restore native passthrough immediately once the pointer is outside the HUD and no popover or drag interaction is active.
• Reassert the Windows native transparency flag synchronously instead of exposing a timed full-screen interactive window.
• Keep the existing compact interactive fallback on platforms where HUD passthrough is unsupported.

Why this approach over #797

PR #797 limits its main passthrough change to macOS and introduces a platform-specific recording fallback. CodeRabbit still reports two unresolved functional issues there: its Linux path cannot meet its stated full-work-area contract, and its Windows fallback can expand to a 540-DIP interactive window when the webcam preview is visible and continue blocking underlying clicks.

This PR instead uses one policy for HUD bounds, window creation, mouse updates, reassertion, and recording transitions. It enables full-work-area click-through wherever the existing capability check supports it, including Windows 11+, preserves interactive controls, removes the native timing gaps discovered in live testing, and explicitly retains the existing fallback on unsupported platforms.

User impact

During recording, visible HUD controls remain interactive, while hover and clicks outside active HUD content return to the underlying website or application without an artificial delay.

Type of change

• Bug fix
• New feature
• Breaking change
• Documentation-only change

Testing

• npx tsc --noEmit
• npm run lint (passes with 21 existing advisory warnings outside the changed files)
• npm test (107 files passed; 1,014 tests passed; 1 skipped)
• npx biome check electron/hudOverlayBounds.ts electron/hudOverlayBounds.test.ts electron/windows.ts src/components/launch/hudMousePassthrough.ts src/components/launch/hudMousePassthrough.test.ts src/components/launch/hooks/useLaunchHudInteractionState.ts
• npm run i18n:check
• npx electron-builder --win
• npm run smoke:packaged-binaries

Regression tests cover supported recording passthrough, interactive requests, unsupported fallback windows, synchronous Windows reassertion, and idle-versus-active HUD interaction state.

Risk

The main risk is making visible HUD controls click-through too early. Passthrough is restored only when the pointer is outside the HUD and there is no open popover, HUD drag, webcam drag, or pending webcam pointer action. Focused tests cover every one of those guards.

Checklist

• The change is focused on the recording HUD input bug.
• Tests cover the regression, interaction guards, and platform fallback.
• Type checking, linting, tests, i18n validation, packaging, and packaged-binary smoke checks pass.
• The branch is based on the current upstream main.

Summary by CodeRabbit

• New Features

  • Recording HUD overlays now support click-through on compatible platforms while keeping controls, popovers, dragging, and webcam previews interactive.
  • Unsupported platforms retain the compact interactive overlay behavior.

• Bug Fixes

  • Preserved requested mouse interaction settings when recording starts or ends.
  • Improved consistency when initializing and updating the recording HUD.

• Tests

  • Added coverage for click-through behavior, interactive controls, and unsupported-platform fallbacks.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR defines tested HUD mouse policies and applies them across recording, source selection, initialization, reassertion, Electron window transitions, and renderer interaction state.

Changes

Recording HUD click-through

Layer / File(s)	Summary
HUD mouse policy and coverage docs/superpowers/specs/..., electron/hudOverlayBounds.ts, electron/hudOverlayBounds.test.ts	The design specifies supported-platform click-through and unsupported-platform fallback behavior. Shared functions resolve window behavior and generate reassertion commands. Tests cover both policies.
Electron HUD state integration docs/superpowers/plans/..., electron/windows.ts	Electron uses the shared policy for bounds, initialization, passthrough updates, focus, reassertion, and recording transitions. Recording preserves the requested mouse-ignore state.
Renderer idle-state restoration src/components/launch/hudMousePassthrough.ts, src/components/launch/hudMousePassthrough.test.ts, src/components/launch/hooks/useLaunchHudInteractionState.ts	The renderer restores passthrough only when no HUD, popover, drag, webcam, or pointer-down interaction is active. Delayed restoration logic is replaced with immediate guarded checks.

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

Possibly related PRs

• webadderallorg/Recordly#797: Directly overlaps the recording HUD mouse-policy and Electron integration changes.
• webadderallorg/Recordly#616: Modifies related HUD passthrough restoration and reassertion behavior.
• webadderallorg/Recordly#486: Overlaps the Electron HUD passthrough and reassertion flow.

Suggested reviewers: meiiie

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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 summarizes the primary change: enabling click-through behavior for transparent recording HUD regions.
Description check	✅ Passed	The description explains the problem, solution, impact, testing, risk, and checklist, with sufficient detail for review.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[coderabbitai]

🧹 Nitpick comments (1)

electron/hudOverlayBounds.test.ts (1)

80-111: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Cover both recording states.

recordingActive is part of the policy contract, but every new case passes true. Add one recordingActive: false case with the same requested state to verify that recording transitions do not override renderer requests.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@electron/hudOverlayBounds.test.ts` around lines 80 - 111, Extend the
resolveHudOverlayMousePolicy tests with a recordingActive: false case using the
same requested state, and assert that the renderer’s requested mouse policy
remains unchanged when recording is inactive. Keep the existing recordingActive:
true and unsupported-passthrough coverage intact.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@electron/hudOverlayBounds.test.ts`:
- Around line 80-111: Extend the resolveHudOverlayMousePolicy tests with a
recordingActive: false case using the same requested state, and assert that the
renderer’s requested mouse policy remains unchanged when recording is inactive.
Keep the existing recordingActive: true and unsupported-passthrough coverage
intact.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 402e5a85-c232-4bf6-b81f-321562097405

📥 Commits

Reviewing files that changed from the base of the PR and between 2a81da9 and 8adbd28.

📒 Files selected for processing (5)

• docs/superpowers/plans/2026-08-10-recording-hud-click-through.md
• docs/superpowers/specs/2026-08-10-recording-hud-click-through-design.md
• electron/hudOverlayBounds.test.ts
• electron/hudOverlayBounds.ts
• electron/windows.ts