update readme/docs

backlog/tasks/task-17 - Investigate-dynamic-overlay-window-sizing-and-decoupled-secondary-subtitle-bar.md

@@ -1,14 +1,18 @@
 ---
 id: TASK-17
 title: Investigate dynamic overlay window sizing and decoupled secondary subtitle bar
-status: To Do
+status: Done
-assignee: []
+assignee:
+  - codex
 created_date: '2026-02-12 02:27'
+updated_date: '2026-02-12 02:56'
 labels:
   - overlay
   - ux
   - investigation
 dependencies: []
+documentation:
+  - docs/overlay-window-sizing-investigation.md
 priority: high
 ---
 
@@ -20,8 +24,57 @@ Current visible and invisible overlays can both be enabled at once, but both win
 
 ## Acceptance Criteria
 <!-- AC:BEGIN -->
-- [ ] #1 Document current overlap/input conflict behavior when both overlays are enabled.
+- [x] #1 Document current overlap/input conflict behavior when both overlays are enabled.
-- [ ] #2 Prototype or design approach for content-bounded overlay window sizing for visible and invisible overlays.
+- [x] #2 Prototype or design approach for content-bounded overlay window sizing for visible and invisible overlays.
-- [ ] #3 Evaluate interaction model and technical constraints for a dedicated top secondary-subtitle bar independent from overlay visibility.
+- [x] #3 Evaluate interaction model and technical constraints for a dedicated top secondary-subtitle bar independent from overlay visibility.
-- [ ] #4 Define implementation plan with tradeoffs, edge cases (line wrapping, long lines, resize, multi-monitor, mpv style sync), and recommended path forward.
+- [x] #4 Define implementation plan with tradeoffs, edge cases (line wrapping, long lines, resize, multi-monitor, mpv style sync), and recommended path forward.
 <!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Baseline current behavior
+- Trace current visible/invisible overlay window creation and sizing behavior in main process and renderer paths.
+- Document why enabling both overlays causes overlap and input/hover conflict.
+
+2. Design content-bounded overlay sizing
+- Evaluate measurement sources (renderer DOM bounds vs main process approximations).
+- Define sizing algorithm (content bounds + padding + min/max + screen clamping) and update triggers.
+- Identify required IPC contracts and ownership boundaries.
+
+3. Design decoupled top secondary-subtitle bar
+- Define a dedicated top region/window independent from primary subtitle visibility.
+- Specify behavior for secondary subtitle display modes (hover/always/never) and pointer-event policy.
+
+4. Recommend phased implementation
+- Produce concrete file-level rollout steps, risks, edge cases (wrapping, long lines, resize, multi-monitor, style sync), and validation approach.
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Completed code-path investigation across overlay window creation/sizing, visibility gating, IPC mouse passthrough, and renderer interaction layers.
+
+Documented current conflict mechanism and architecture limitation: shared fullscreen bounds ownership across both overlay windows blocks safe simultaneous activation.
+
+Proposed renderer-driven content-bounds IPC model, per-window bounds ownership, and a dedicated secondary top-bar window with mode-specific behavior.
+
+Included phased implementation plan with risks and edge-case handling in docs/overlay-window-sizing-investigation.md.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Completed investigation and design for dynamic overlay window sizing and decoupled secondary subtitle rendering.
+
+What changed:
+- Added `docs/overlay-window-sizing-investigation.md` with a code-referenced analysis of current overlay behavior.
+- Documented why overlap/input conflicts emerge under simultaneous overlay activation: both windows are full-size and currently share bounds ownership semantics.
+- Designed a content-bounded sizing approach based on renderer-measured DOM bounds reported to main via IPC, with clamping, jitter guards, and fallback behavior.
+- Evaluated top-bar decoupling options and recommended a dedicated secondary overlay window for independent lifecycle, z-order, and pointer policy.
+- Defined a phased file-level implementation path and explicit edge-case handling (wrapping/long lines, resize churn, multi-monitor transitions, mpv style/render sync).
+
+Validation:
+- Investigation validated by tracing current runtime/services/renderer code paths; no runtime behavior changes were applied in this task.
+- No automated tests were run because this task produced design documentation only (no executable code changes).
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-19 - Enable-overlay-keybinds-whenever-app-runtime-is-active.md

@@ -0,0 +1,16 @@
+---
+id: TASK-19
+title: Enable overlay keybinds whenever app runtime is active
+status: To Do
+assignee: []
+created_date: '2026-02-12 08:47'
+labels: []
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Restored task after accidental cleanup. Ensure keybindings are available whenever the Electron runtime is active, while respecting focused overlay/input contexts that require local key handling.
+<!-- SECTION:DESCRIPTION:END -->

backlog/tasks/task-20 - Implement-content-bounded-overlay-windows-and-decoupled-secondary-top-bar.md

@@ -0,0 +1,16 @@
+---
+id: TASK-20
+title: Implement content-bounded overlay windows and decoupled secondary top bar
+status: To Do
+assignee: []
+created_date: '2026-02-12 08:47'
+labels: []
+dependencies: []
+priority: high
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Restored parent task after accidental cleanup. Track the overlay sizing redesign and secondary top-bar decoupling initiative.
+<!-- SECTION:DESCRIPTION:END -->

backlog/tasks/task-20.1 - Refactor-overlay-runtime-to-use-per-layer-window-bounds-ownership.md

@@ -0,0 +1,17 @@
+---
+id: TASK-20.1
+title: Refactor overlay runtime to use per-layer window bounds ownership
+status: To Do
+assignee: []
+created_date: '2026-02-12 08:47'
+labels: []
+dependencies: []
+parent_task_id: TASK-20
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Restored subtask after accidental cleanup.
+<!-- SECTION:DESCRIPTION:END -->

backlog/tasks/task-20.2 - Add-renderer-to-main-IPC-contract-for-measured-overlay-content-bounds.md

@@ -0,0 +1,17 @@
+---
+id: TASK-20.2
+title: Add renderer-to-main IPC contract for measured overlay content bounds
+status: To Do
+assignee: []
+created_date: '2026-02-12 08:47'
+labels: []
+dependencies: []
+parent_task_id: TASK-20
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Restored subtask after accidental cleanup.
+<!-- SECTION:DESCRIPTION:END -->

backlog/tasks/task-20.3 - Implement-content-bounded-sizing-algorithm-for-visible-and-invisible-overlay-windows.md

@@ -0,0 +1,19 @@
+---
+id: TASK-20.3
+title: >-
+  Implement content-bounded sizing algorithm for visible and invisible overlay
+  windows
+status: To Do
+assignee: []
+created_date: '2026-02-12 08:47'
+labels: []
+dependencies: []
+parent_task_id: TASK-20
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Restored subtask after accidental cleanup.
+<!-- SECTION:DESCRIPTION:END -->

subminer

@@ -77,6 +77,7 @@ interface Args {
   youtubeAudioLangs: string[];
   youtubeWhisperSourceLanguage: string;
   useTexthooker: boolean;
+  autoStartOverlay: boolean;
   texthookerOnly: boolean;
   useRofi: boolean;
   logLevel: LogLevel;
@@ -146,6 +147,7 @@ Options:
   -v, --verbose          Enable verbose/debug logging
       --log-level LEVEL  Set log level: debug, info, warn, error
   -R, --rofi             Use rofi file browser instead of fzf for video selection
+  -S, --start-overlay    Auto-start SubMiner overlay after MPV socket is ready
   -T, --no-texthooker    Disable texthooker-ui server
       --texthooker       Launch only texthooker page (no MPV/overlay workflow)
   -h, --help             Show this help message
@@ -170,6 +172,7 @@ Examples:
   ${scriptName} video.mkv              # Play with subminer profile
   ${scriptName} -p gpu-hq video.mkv    # Play with gpu-hq profile
   ${scriptName} -b x11 video.mkv       # Force x11 backend
+  ${scriptName} -S video.mkv           # Start overlay immediately after MPV launch
   ${scriptName} --texthooker           # Launch only texthooker page
 `;
 }
@@ -1380,6 +1383,7 @@ function parseArgs(
     youtubeAudioLangs,
     youtubeWhisperSourceLanguage: inferWhisperLanguage(primarySubLangs, "ja"),
     useTexthooker: true,
+    autoStartOverlay: false,
     texthookerOnly: false,
     useRofi: false,
     logLevel: "info",
@@ -1573,6 +1577,12 @@ function parseArgs(
       continue;
     }
 
+    if (arg === "-S" || arg === "--start-overlay") {
+      parsed.autoStartOverlay = true;
+      i += 1;
+      continue;
+    }
+
     if (arg === "-T" || arg === "--no-texthooker") {
       parsed.useTexthooker = false;
       i += 1;
@@ -2029,9 +2039,10 @@ async function main(): Promise<void> {
     });
   }
 
-  const shouldStartOverlay = args.startOverlay || pluginRuntimeConfig.autoStartOverlay;
+  const ready = await waitForSocket(mpvSocketPath);
+  const shouldStartOverlay =
+    args.startOverlay || args.autoStartOverlay || pluginRuntimeConfig.autoStartOverlay;
   if (shouldStartOverlay) {
-    const ready = await waitForSocket(mpvSocketPath);
     if (ready) {
       log(
         "info",
@@ -2046,11 +2057,17 @@ async function main(): Promise<void> {
       );
     }
     await startOverlay(appPath, args, mpvSocketPath);
+  } else if (ready) {
+    log(
+      "info",
+      args.logLevel,
+      "MPV IPC socket ready, overlay auto-start disabled (use y-s to start)",
+    );
   } else {
     log(
       "info",
       args.logLevel,
-      "SubMiner overlay auto-start disabled; not launching overlay process",
+      "MPV IPC socket not ready yet, overlay auto-start disabled (use y-s to start)",
     );
   }