chore: commit remaining docs and project updates

OVERLAY_POSITIONING_FLOW.md

@@ -0,0 +1,53 @@
+# Overlay Positioning Flow
+
+## 1) Window Bounds Flow (visible + invisible Electron windows)
+
+```mermaid
+flowchart LR
+  A[Platform backend selection<br/>src/window-trackers/index.ts] --> B[Tracker emits geometry<br/>onWindowFound/onGeometryChange]
+  B --> C[updateOverlayBounds<br/>src/main.ts]
+  C --> D[mainWindow.setBounds]
+  C --> E[invisibleWindow.setBounds]
+```
+
+## 2) Invisible Subtitle Layout Flow (mpv render metrics -> DOM layout)
+
+```mermaid
+flowchart LR
+  A[mpv property changes<br/>sub-pos, sub-font-size, osd-dimensions, etc.] --> B[MpvIpcClient parses events<br/>src/main.ts]
+  B --> C[updateMpvSubtitleRenderMetrics<br/>src/main.ts]
+  C --> D[broadcast mpv-subtitle-render-metrics:set]
+  D --> E[preload onMpvSubtitleRenderMetrics<br/>src/preload.ts]
+  E --> F[renderer receives metrics event<br/>src/renderer/renderer.ts]
+  F --> G[applyInvisibleSubtitleLayoutFromMpvMetrics]
+  G --> H[subtitleContainer/subtitleRoot inline styles updated]
+```
+
+## 3) Visible Subtitle Manual Position Flow
+
+```mermaid
+flowchart LR
+  A[User right-click drags subtitle] --> B[setupDragging<br/>src/renderer/renderer.ts]
+  B --> C[applyYPercent]
+  C --> D[saveSubtitlePosition IPC]
+  D --> E[saveSubtitlePosition in main<br/>src/main.ts]
+  E --> F[load/broadcast subtitle-position:set]
+  F --> G[applyStoredSubtitlePosition in renderer]
+```
+
+## 4) Fallback Bounds Flow (tracker not ready)
+
+```mermaid
+flowchart LR
+  A[windowTracker exists but not tracking] --> B["screen.getDisplayNearestPoint(cursor)"]
+  B --> C[display.workArea]
+  C --> D[updateOverlayBounds]
+```
+
+## Key Files
+
+- `src/main.ts`
+- `src/renderer/renderer.ts`
+- `src/preload.ts`
+- `src/window-trackers/base-tracker.ts`
+- `src/window-trackers/index.ts`