diff --git a/backlog/tasks/task-260 - Fix-macOS-overlay-subtitle-sidebar-passthrough-without-requiring-a-subtitle-hover-cycle.md b/backlog/tasks/task-260 - Fix-macOS-overlay-subtitle-sidebar-passthrough-without-requiring-a-subtitle-hover-cycle.md index be4f964..8631261 100644 --- a/backlog/tasks/task-260 - Fix-macOS-overlay-subtitle-sidebar-passthrough-without-requiring-a-subtitle-hover-cycle.md +++ b/backlog/tasks/task-260 - Fix-macOS-overlay-subtitle-sidebar-passthrough-without-requiring-a-subtitle-hover-cycle.md @@ -3,9 +3,11 @@ id: TASK-260 title: >- Fix macOS overlay subtitle sidebar passthrough without requiring a subtitle hover cycle -status: To Do -assignee: [] +status: Done +assignee: + - '@codex' created_date: '2026-03-31 00:58' +updated_date: '2026-03-31 01:01' labels: - bug - macos @@ -35,7 +37,31 @@ On macOS, opening the overlay-layout subtitle sidebar should allow click-through ## Acceptance Criteria -- [ ] #1 With the overlay-layout subtitle sidebar open on macOS, areas outside the sidebar pass clicks through immediately after open without requiring a prior subtitle hover. -- [ ] #2 When no subtitle line is currently visible, opening the subtitle sidebar still leaves non-sidebar overlay regions click-through on macOS. -- [ ] #3 Regression coverage exercises the first-open/idle passthrough path so overlay interactivity does not depend on a later hover cycle. +- [x] #1 With the overlay-layout subtitle sidebar open on macOS, areas outside the sidebar pass clicks through immediately after open without requiring a prior subtitle hover. +- [x] #2 When no subtitle line is currently visible, opening the subtitle sidebar still leaves non-sidebar overlay regions click-through on macOS. +- [x] #3 Regression coverage exercises the first-open/idle passthrough path so overlay interactivity does not depend on a later hover cycle. + +## Implementation Plan + + +1. Add/adjust focused overlay visibility regressions for the tracked macOS visible overlay so the default idle state stays click-through instead of forcing mouse interaction. +2. Update main-process visible overlay visibility sync to keep the tracked macOS overlay passive by default and let renderer hover/sidebar state opt into interaction. +3. Run focused verification for overlay visibility and any dependent runtime tests, then update task notes/criteria/final summary with the confirmed outcome. + + +## Implementation Notes + + +Investigation points to a main-process override on macOS: renderer sidebar open path already requests mouse passthrough outside the panel, but visible-overlay visibility sync still hard-sets the tracked overlay window interactive on macOS (`mouse-ignore:false`). Window-tracker focus/visibility resync can therefore undo renderer passthrough until a later hover cycle re-applies it. + +Added a failing regression in `src/core/services/overlay-visibility.test.ts` showing the tracked macOS visible overlay was still forced interactive by main-process visibility sync (`mouse-ignore:false`) instead of staying forwarded click-through. + +Updated `src/core/services/overlay-visibility.ts` so tracked macOS visible overlays now default to `setIgnoreMouseEvents(true, { forward: true })`, matching the renderer-side passthrough model and preventing window-tracker/focus resync from undoing idle sidebar clickthrough. + + +## Final Summary + + +Fixed the macOS subtitle-sidebar passthrough regression by changing tracked visible-overlay startup/visibility sync to stay click-through by default in the main process. Previously `updateVisibleOverlayVisibility` forced the macOS overlay window interactive, which could override renderer sidebar passthrough until a later hover cycle repaired it. Added a regression in `src/core/services/overlay-visibility.test.ts` and verified with `bun test src/core/services/overlay-visibility.test.ts`, `bun test src/renderer/modals/subtitle-sidebar.test.ts src/renderer/handlers/mouse.test.ts`, and `bun run typecheck`. + diff --git a/changes/261-macos-overlay-passthrough.md b/changes/261-macos-overlay-passthrough.md new file mode 100644 index 0000000..0ecdcfe --- /dev/null +++ b/changes/261-macos-overlay-passthrough.md @@ -0,0 +1,5 @@ +type: fixed +area: overlay + +- Keep tracked macOS visible overlays click-through by default so subtitle sidebar passthrough works immediately without requiring a subtitle hover cycle first. +- Add regression coverage for the macOS visible-overlay passthrough default. diff --git a/src/core/services/overlay-visibility.test.ts b/src/core/services/overlay-visibility.test.ts index a992828..b43d7d7 100644 --- a/src/core/services/overlay-visibility.test.ts +++ b/src/core/services/overlay-visibility.test.ts @@ -238,7 +238,7 @@ test('visible overlay stays hidden while a modal window is active', () => { assert.ok(!calls.includes('update-bounds')); }); -test('macOS tracked visible overlay stays visible without passively stealing focus', () => { +test('macOS tracked visible overlay stays click-through without passively stealing focus', () => { const { window, calls } = createMainWindowRecorder(); const tracker: WindowTrackerStub = { isTracking: () => true, @@ -270,7 +270,7 @@ test('macOS tracked visible overlay stays visible without passively stealing foc isWindowsPlatform: false, } as never); - assert.ok(calls.includes('mouse-ignore:false:plain')); + assert.ok(calls.includes('mouse-ignore:true:forward')); assert.ok(calls.includes('show')); assert.ok(!calls.includes('focus')); }); diff --git a/src/core/services/overlay-visibility.ts b/src/core/services/overlay-visibility.ts index 080b232..c74e6bb 100644 --- a/src/core/services/overlay-visibility.ts +++ b/src/core/services/overlay-visibility.ts @@ -37,7 +37,7 @@ export function updateVisibleOverlayVisibility(args: { const showPassiveVisibleOverlay = (): void => { const forceMousePassthrough = args.forceMousePassthrough === true; - if (args.isWindowsPlatform || forceMousePassthrough) { + if (args.isMacOSPlatform || args.isWindowsPlatform || forceMousePassthrough) { mainWindow.setIgnoreMouseEvents(true, { forward: true }); } else { mainWindow.setIgnoreMouseEvents(false);