test(immersion): keep duplicate-line cleanup tests off disk

Each test built a fresh on-disk SQLite database, paying a schema-creation
fsync that is cheap locally but slow enough on CI runners that the 40-frame
karaoke case exceeded the 5s per-test timeout. The tests exercise cleanup SQL
rather than durability, so the database now stays in memory.

changes/ass-canonical-animation-lines.md

@@ -0,0 +1,5 @@
+type: fixed
+area: subtitles
+
+- Typeset ASS karaoke and animated signs no longer flood the primary overlay, subtitle sidebar, immersion history, or sentence mining with repeated glyph fragments or full-line color phases. Matching timed comments and full-line boundary events recover the complete authored line without merging ordinary repeated dialogue or separately positioned signs, and dialogue spoken while a song's animation is on screen is kept intact instead of being replaced by the lyric. Entrance and exit frames that run past the authored line timing still resolve to the clean line during lyric transitions, and dialogue spoken while a song's animation is on screen enters immersion and subtitle history without the fragment lines beside it.
+- The secondary subtitle overlay drops layered duplicate lines from animated tracks, so a short stack of repeated words collapses to its distinct lines even when the full karaoke heuristic does not apply.

changes/docs-site-index-hygiene.md

@@ -0,0 +1,5 @@
+type: internal
+area: docs
+
+- Excluded the `/main/` and `/v/<version>/` docs trees from search indexing with a self-referential canonical, `noindex,follow`, and a matching `X-Robots-Tag` header, so crawlers spend their budget on the current docs instead of ~30 archived copies of every page.
+- Restored `<lastmod>` dates in the docs sitemap, which were silently dropped because production builds render from an untracked release snapshot.

changes/fix-macos-fullscreen-modal-spaces.md

@@ -0,0 +1,5 @@
+type: fixed
+area: overlay
+
+- Dedicated overlay modals are prewarmed on macOS and Windows so shortcuts open them promptly on the first press. Windows now refreshes the hidden modal renderer between sessions to keep later modals interactive. On macOS, reused modals and the in-app stats window also open above fullscreen mpv on its current Space instead of appearing on another desktop or forcing a Space change.
+- Updated subtitle ASS observation to mpv's current `sub-text/ass` property, removing its deprecation warning.

changes/fix-mpv-ipc-connect-stall.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed the overlay getting stuck on "Overlay loading" forever when startup stalls: mpv IPC connection attempts now time out and retry, switching sockets aborts obsolete attempts, and the plugin replaces its spinner with an actionable error if overlay content is still not ready after 30 seconds.

changes/fix-windows-system-mouse-lag.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed system-wide mouse lag on Windows while SubMiner is running: the overlay no longer installs Electron's global mouse hook for click-through forwarding, and the mpv window tracker no longer blocks the app on repeated PowerShell command-line lookups.

changes/media-timing-review.md

@@ -1,4 +0,0 @@
-type: added
-area: mining
-
-- Added optional pre-generation timing review for word, sentence, and audio cards with a compact speech-weighted waveform, clearly labeled mined-line boundaries, drag and keyboard adjustments, audio preview with a sweeping playhead, exact screenshot and AVIF timing, cancellation choices that include keeping a card without media, and a session-only runtime toggle.

config.example.jsonc

@@ -523,7 +523,7 @@
   // ==========================================
   // AnkiConnect Integration
   // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
   // Shared AI provider transport settings are read from top-level ai and typically require restart.
   // Most other AnkiConnect settings still require restart.
   // ==========================================
@@ -569,7 +569,6 @@
       "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
       "normalizeAudio": true, // Normalize generated sentence audio loudness during media extraction. Changes apply live. Values: true | false
       "mirrorMpvVolume": true, // Apply mpv's current software volume curve to generated sentence audio. Changes apply live. Values: true | false
-      "reviewTiming": false, // Review and preview subtitle media timing before SubMiner creates or enriches a mined card. Values: true | false
       "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
       "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
       "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.

docs-site/.vitepress/config.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { extname, join, posix, resolve, sep } from 'node:path';
 import type { DefaultTheme, HeadConfig, TransformContext, UserConfig } from 'vitepress';
@@ -26,6 +27,9 @@ function optionalEnv(value: string | undefined): string | undefined {
 const base = normalizeBase(optionalEnv(process.env.SUBMINER_DOCS_BASE) ?? '/');
 const outDir = optionalEnv(process.env.SUBMINER_DOCS_OUT_DIR);
 const docsSourceDir = optionalEnv(process.env.SUBMINER_DOCS_SOURCE_DIR) ?? process.cwd();
+// The tracked `docs-site/` checkout, which stays a git working tree even when
+// `docsSourceDir` points at an untracked release snapshot. Used for git lookups only.
+const repoDocsDir = optionalEnv(process.env.SUBMINER_DOCS_REPO_DIR) ?? process.cwd();
 const channel = normalizeChannel(optionalEnv(process.env.SUBMINER_DOCS_CHANNEL));
 const docsVersion = optionalEnv(process.env.SUBMINER_DOCS_VERSION);
 const latestStable = optionalEnv(process.env.SUBMINER_DOCS_LATEST_STABLE) ?? 'v0.18.0';
@@ -82,15 +86,18 @@ function pageToRoute(page: string): string | null {
   return route ? `/${route}` : '/';
 }
 
+// Only the root channel is indexable. `main` and every /v/<version>/ archive are
+// near-verbatim copies of it, so they own their URL via a self-referential canonical
+// and are excluded from the index instead of being consolidated onto root. Uniform
+// self-canonical plus noindex avoids mixing noindex with a cross-page canonical,
+// which Google treats as a conflicting signal.
+const isIndexableChannel = channel === 'stable-root';
+
 function pageToCanonicalHref(page: string): string | null {
   const route = pageToRoute(page);
   if (!route) return null;
 
-  if (channel === 'main') {
-    return `${DOCS_HOSTNAME}${canonicalRouteWithBase(route)}`;
-  }
-
-  if (channel === 'stable-archive' && docsVersion !== latestStable) {
+  if (!isIndexableChannel) {
     return `${DOCS_HOSTNAME}${canonicalRouteWithBase(route)}`;
   }
 
@@ -106,7 +113,9 @@ function transformPageHead({ page }: TransformContext): HeadConfig[] {
   const href = pageToCanonicalHref(page);
   const head: HeadConfig[] = href ? [['link', { rel: 'canonical', href }]] : [];
 
-  if (channel === 'main') {
+  // Crawlable so links still pass through, but out of the index: ~30 archived copies
+  // of every page otherwise soak up the crawl budget the current docs need.
+  if (!isIndexableChannel) {
     head.push(['meta', { name: 'robots', content: 'noindex,follow' }]);
   }
 
@@ -287,6 +296,39 @@ const versionItems = [
   })),
 ];
 
+function sitemapUrlToPage(url: string): string {
+  const route = url.replace(/\.html$/, '').replace(/^\/+|\/+$/g, '');
+  return route ? `${route}.md` : 'index.md';
+}
+
+// VitePress derives <lastmod> by running `git log` inside its source dir. Production
+// builds point that at an untracked snapshot of the release tag, so the lookup comes
+// back empty and the sitemap ships with no dates at all. Resolve it from the tracked
+// checkout at the ref being built instead.
+function lastModifiedFor(url: string): string | undefined {
+  const ref = docsVersion && docsVersion !== 'main' ? docsVersion : 'HEAD';
+  const result = spawnSync('git', ['log', '-1', '--format=%cI', ref, '--', sitemapUrlToPage(url)], {
+    cwd: repoDocsDir,
+    encoding: 'utf8',
+  });
+
+  return (result.status === 0 && result.stdout.trim()) || undefined;
+}
+
+// Only the root channel publishes a sitemap. Archived and `main` builds would emit
+// their own copies listing the same canonical URLs, which just advertises the
+// duplicate trees we are trying to keep out of the index.
+const sitemap: UserConfig['sitemap'] = isIndexableChannel
+  ? {
+      hostname: DOCS_HOSTNAME,
+      transformItems(items) {
+        return items
+          .filter((item) => item.url !== 'README' && item.url !== `${DOCS_HOSTNAME}/README`)
+          .map((item) => ({ ...item, lastmod: item.lastmod ?? lastModifiedFor(item.url) }));
+      },
+    }
+  : undefined;
+
 const nav: DefaultTheme.NavItem[] = [
   { text: 'Home', link: '/' },
   { text: 'Get Started', link: '/installation' },
@@ -419,14 +461,7 @@ const config: UserConfig = {
   appearance: 'dark',
   cleanUrls: true,
   metaChunk: true,
-  sitemap: {
-    hostname: DOCS_HOSTNAME,
-    transformItems(items) {
-      return items.filter(
-        (item) => item.url !== 'README' && item.url !== `${DOCS_HOSTNAME}/README`,
-      );
-    },
-  },
+  sitemap,
   transformHead: transformPageHead,
   lastUpdated: true,
   srcExclude: ['subagents/**', 'README.md'],

docs-site/README.md

@@ -38,8 +38,10 @@ bun run docs:dev
 The public docs root is stable-only:
 
 - `/` serves the latest stable release docs.
-- `/main/` serves development docs from `main` and is marked `noindex,follow`.
+- `/main/` serves development docs from `main`.
 - `/v/<version>/` serves stable release archives.
 - Prerelease tags do not update the docs site.
 
+Only `/` is indexable. `/main/` and every `/v/<version>/` page carries a self-referential canonical plus `noindex,follow`, and the generated `_headers` file repeats that as an `X-Robots-Tag`. They stay crawlable so their links still resolve, but ~30 archived copies of every page would otherwise consume the crawl budget the current docs need. Only the root build emits `sitemap.xml`, and its `<lastmod>` dates come from `git log` against the tracked checkout at the released tag, because the build renders from an untracked snapshot that VitePress cannot date itself.
+
 Keep Cloudflare Git auto-deploy disabled. The production deploy is `.github/workflows/docs-pages.yml`, which uploads `.tmp/docs-versioned-site` with `--branch main` so tag-triggered runs update Production instead of creating preview deployments.

docs-site/anki-integration.md

@@ -166,7 +166,6 @@ Audio is extracted from the video file using the subtitle's start and end timest
     "generateAudio": true,
     "normalizeAudio": true,      // normalize generated clip loudness
     "mirrorMpvVolume": true,     // apply the current mpv volume level
-    "reviewTiming": false,       // review and adjust timing before media generation
     "audioPadding": 0,           // optional seconds before and after subtitle timing
     "maxMediaDuration": 30       // cap total duration in seconds
   }
@@ -179,10 +178,6 @@ Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMine
 
 The audio is uploaded to Anki's media folder and inserted as `[sound:audio_<timestamp>.mp3]`.
 
-Set `media.reviewTiming` to `true` to pause playback and review each word, sentence, or audio card before its media is generated. The review opens with the subtitle range plus configured audio padding. Drag either edge of the clip to trim it, drag the middle to slide it without changing its length, or press anywhere else on the waveform to snap the nearer edge there. A focused edge also moves with the arrow keys, by 100 ms alone or 500 ms with Shift, and the 100 ms buttons do the same. Space previews the selection with a playhead that sweeps the clip, Enter confirms, and Escape cancels. The Earlier and Later buttons reveal another two seconds of available timeline without moving the selected clip. A speech-weighted waveform shows the mined subtitle as a tinted band with labeled line-start and line-end rails, making adjacent dialogue easier to distinguish. SubMiner uses a center channel when one carries dialogue, then falls back to a speech-band mono mix. Waveform analysis failure leaves the timing controls available. The confirmed range is exact: SubMiner does not apply audio padding a second time. Static screenshots use its midpoint, and animated AVIF clips use the full confirmed range.
-
-Canceling the review lets you keep editing, finish with the original timing, keep or create the card without audio or an image, or discard the card. Discard deletes an existing Yomitan or audio card and skips creation for a direct sentence card. Clipboard updates and stats-dashboard mining do not open timing review. Audio preview failure does not block confirmation or card creation. The option is disabled by default and hot-reloads. You can also toggle **Review Media Timing** for the current session from the runtime options palette (`Ctrl/Cmd+Shift+O`).
-
 ### Screenshots (Static)
 
 A single frame is captured at the current playback position.

docs-site/configuration.md

@@ -873,10 +873,9 @@ When config hot-reload updates shortcut/keybinding/style values, close and reope
 
 Use the runtime options palette to toggle settings live while SubMiner is running. These changes are session-only and reset on restart.
 
-Current runtime options cover automatic card updates, media timing review,
-known-word highlighting, known-word maturity coloring, N+1 annotation, JLPT
-underlines, frequency highlighting, known-word match mode, and Kiku field
-grouping mode.
+Current runtime options cover automatic card updates, known-word highlighting,
+known-word maturity coloring, N+1 annotation, JLPT underlines, frequency
+highlighting, known-word match mode, and Kiku field grouping mode.
 
 Annotation toggles only apply to new subtitle lines after the toggle. The currently displayed line is not re-tokenized in place.
 
@@ -968,7 +967,6 @@ Enable automatic Anki card creation and updates with media generation:
       "animatedCrf": 35,
       "normalizeAudio": true,
       "mirrorMpvVolume": true,
-      "reviewTiming": false,
       "audioPadding": 0,
       "fallbackDuration": 3,
       "maxMediaDuration": 30
@@ -1021,7 +1019,6 @@ This example is intentionally compact. The option table below documents availabl
 | `media.generateAudio`                             | `true`, `false`                             | Generate audio clips from video (default: `true`)                                                                                                                                                                               |
 | `media.normalizeAudio`                            | `true`, `false`                             | Normalize generated sentence-audio loudness during media extraction (default: `true`). Set to `false` to keep raw source loudness. Changes apply live.                                                                          |
 | `media.mirrorMpvVolume`                           | `true`, `false`                             | Apply mpv's cubic software-volume curve to each generated sentence-audio clip (default: `true`). This ignores mpv's separate mute state, falls back to unity scaling if volume cannot be read, and applies changes live.        |
-| `media.reviewTiming`                              | `true`, `false`                             | Pause playback and review word, sentence, and audio card timing before media generation (default: `false`). Clipboard updates and stats-dashboard mining do not open the review.                                                |
 | `media.generateImage`                             | `true`, `false`                             | Generate image/animation screenshots (default: `true`)                                                                                                                                                                          |
 | `media.imageType`                                 | `"static"`, `"avif"`                        | Image type: static screenshot or animated AVIF (default: `"static"`)                                                                                                                                                            |
 | `media.imageFormat`                               | `"jpg"`, `"png"`, `"webp"`                  | Image format (default: `"jpg"`)                                                                                                                                                                                                 |

docs-site/immersion-tracking.md

@@ -138,6 +138,8 @@ Karaoke openings and animated signs are authored as one subtitle event per anima
 
 Recording now collapses those runs as they happen, matching what the subtitle sidebar shows:
 
+- When a typeset ASS file stores a clean lyric or sign in a timed authoring comment, or in full-line events surrounding generated fragments, the matching complete line is recorded once. The repeated glyph or clip-animation frames are not recorded. Dialogue spoken while such an animation is on screen records as itself, without the fragment lines beside it.
+- When karaoke styling redraws the same complete lyric across consecutive color or highlight phases, those phases are combined into one line with their full timing. Repeated ordinary dialogue remains separate.
 - When the active subtitle source has been parsed, its cue list has already had duplicate events and animation bursts merged. A line landing inside a surviving cue but after that cue's start is a frame the sidebar merged away, and is not recorded.
 - When no parsed cue covers the live timing, including while a subtitle source is changing or shifted, the strict metadata-free rule applies: a run of identical, contiguous lines each shorter than 0.1s stops being recorded after a few frames. Runs are tracked per line of text, so dual-line karaoke (a kanji and a romaji line frame-flipped together) collapses both lines. Ordinary repeated dialogue, and lines held for a normal beat, always record.
 

docs-site/public/config.example.jsonc

@@ -523,7 +523,7 @@
   // ==========================================
   // AnkiConnect Integration
   // Automatic Anki updates and media generation options.
-  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
   // Shared AI provider transport settings are read from top-level ai and typically require restart.
   // Most other AnkiConnect settings still require restart.
   // ==========================================
@@ -569,7 +569,6 @@
       "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
       "normalizeAudio": true, // Normalize generated sentence audio loudness during media extraction. Changes apply live. Values: true | false
       "mirrorMpvVolume": true, // Apply mpv's current software volume curve to generated sentence audio. Changes apply live. Values: true | false
-      "reviewTiming": false, // Review and preview subtitle media timing before SubMiner creates or enriches a mined card. Values: true | false
       "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
       "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
       "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.

docs-site/seo.test.ts

@@ -56,34 +56,43 @@ test('main docs canonical uses /main/ and emits noindex', async () => {
     { rel: 'canonical', href: 'https://docs.subminer.moe/main/' },
   ]);
   expect(head).toContainEqual(['meta', { name: 'robots', content: 'noindex,follow' }]);
+  expect(mainDocsConfig.sitemap).toBeUndefined();
 
   process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
   process.env.SUBMINER_DOCS_BASE = previousBase;
 });
 
-test('latest stable archive canonical points to root equivalent', async () => {
-  const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
-  const previousBase = process.env.SUBMINER_DOCS_BASE;
-  const previousVersion = process.env.SUBMINER_DOCS_VERSION;
-  const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
-  process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
-  process.env.SUBMINER_DOCS_BASE = '/v/0.14.0/';
-  process.env.SUBMINER_DOCS_VERSION = 'v0.14.0';
-  process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
-  const { default: latestArchiveConfig } = await import('./.vitepress/config?latest-archive');
+test.each([
+  ['latest stable', 'v0.14.0', '/v/0.14.0/', 'https://docs.subminer.moe/v/0.14.0/usage'],
+  ['superseded', 'v0.12.0', '/v/0.12.0/', 'https://docs.subminer.moe/v/0.12.0/usage'],
+])(
+  '%s archive keeps a self-referential canonical and stays out of the index',
+  async (_label, version, base, expectedCanonical) => {
+    const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
+    const previousBase = process.env.SUBMINER_DOCS_BASE;
+    const previousVersion = process.env.SUBMINER_DOCS_VERSION;
+    const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
+    process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
+    process.env.SUBMINER_DOCS_BASE = base;
+    process.env.SUBMINER_DOCS_VERSION = version;
+    process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
+    try {
+      const { default: archiveConfig } = await import(`./.vitepress/config?archive-${version}`);
 
-  const head = await latestArchiveConfig.transformHead?.(makeTransformContext('usage.md'));
+      const head = await archiveConfig.transformHead?.(makeTransformContext('usage.md'));
 
-  expect(head).toContainEqual([
-    'link',
-    { rel: 'canonical', href: 'https://docs.subminer.moe/usage' },
-  ]);
-
-  process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
-  process.env.SUBMINER_DOCS_BASE = previousBase;
-  process.env.SUBMINER_DOCS_VERSION = previousVersion;
-  process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
-});
+      expect(head).toContainEqual(['link', { rel: 'canonical', href: expectedCanonical }]);
+      expect(head).toContainEqual(['meta', { name: 'robots', content: 'noindex,follow' }]);
+      // A sitemap here would advertise the archive tree we just excluded.
+      expect(archiveConfig.sitemap).toBeUndefined();
+    } finally {
+      process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
+      process.env.SUBMINER_DOCS_BASE = previousBase;
+      process.env.SUBMINER_DOCS_VERSION = previousVersion;
+      process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
+    }
+  },
+);
 
 test('stable archive theme links stay on the selected version', async () => {
   const previousCwd = process.cwd();
@@ -433,3 +442,22 @@ test('docs sitemap excludes duplicate README page from indexable URLs', async ()
 
   expect(transformedItems?.map((item) => item.url)).toEqual(['', 'usage']);
 });
+
+test('docs sitemap dates every URL from the tracked checkout', async () => {
+  const previousRepoDir = process.env.SUBMINER_DOCS_REPO_DIR;
+  // Production builds render from an untracked snapshot, so the date has to come from
+  // the real checkout rather than VitePress's own srcDir git lookup.
+  process.env.SUBMINER_DOCS_REPO_DIR = docsSiteDir;
+  try {
+    const { default: sitemapConfig } = await import('./.vitepress/config?sitemap-lastmod');
+
+    const items = await sitemapConfig.sitemap?.transformItems?.([{ url: '' }, { url: 'usage' }]);
+
+    expect(items).toHaveLength(2);
+    for (const item of items ?? []) {
+      expect(item.lastmod).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    }
+  } finally {
+    process.env.SUBMINER_DOCS_REPO_DIR = previousRepoDir;
+  }
+});

docs-site/subtitle-sidebar.md

@@ -12,6 +12,8 @@ When SubMiner parses the active subtitle source into a cue list, the sidebar bec
 - Clicking any cue seeks mpv to that timestamp.
 - The sidebar stays synchronized with the overlay - media transitions and subtitle source changes update both simultaneously.
 
+For typeset ASS karaoke and animated signs, SubMiner collapses generated animation frames and repeated full-line color phases before they reach the sidebar. It recovers a clean complete line from a matching timed authoring comment or from full-line events surrounding generated fragments. Ordinary ASS comments, editor notes, alternate lines, repeated dialogue, and separately positioned signs remain distinct.
+
 The sidebar only appears when a parsed cue list is available. External subtitle sources that SubMiner cannot parse (for example, embedded ASS tracks rendered directly by mpv) will not populate the sidebar.
 
 ## Layout Modes

docs/architecture/2026-03-15-renderer-performance-design.md

@@ -70,18 +70,25 @@ interface SubtitleCue {
   startTime: number; // seconds
   endTime: number; // seconds
   text: string; // plain text, decoded from the source format
+  source?: 'canonical-ass'; // recovered authored text for generated ASS animation
+  animationStartTime?: number; // full generated-frame envelope; entrance/exit frames
+  animationEndTime?: number; //   run past the authored timing, live matching uses this
 }
 ```
 
 **Supported formats:**
 
 - SRT/VTT: Regex-based parsing of timing lines + text content between timing blocks.
-- ASS: Parse `[Events]` section, extract `Dialogue:` lines, read the field order from the `Format:` row, and take everything after the Text field index as the text (Text can itself contain commas).
+- ASS: Parse the `[Events]` section, read the field order from the `Format:` row, and extract timed `Dialogue:` lines. Timed `Comment:` lines are normally ignored, but can supply canonical authored text when they match a nearby generated animation from the same style and actor. Text can itself contain commas.
 
 **ASS decoding.** The parser is where ASS text is decoded, once, via `assToPlainText()` in `src/core/services/ass-text.ts`. That decoder mirrors mpv's `ass_to_plaintext` so a cue read from a file reads identically to the same line arriving live on `sub-text`: `{...}` override blocks are markup, `\pN … \p0` vector drawing runs are dropped rather than shown as text, `\N`/`\n`/`\h` are the only escapes (`\{`, `\}` and `\\` are not), and an unclosed `{` is rendered verbatim. Every layer downstream — renderer, timing tracker, tokenizer, tokenization cache keys — receives plain text and uses `normalizePlainSubtitleText()` for whitespace only, so nothing decodes the same string twice and one authored line always maps to one cache key.
 
 **Duplicate collapsing.** Typeset scripts emit one `Dialogue:` event per animation frame, plus layered copies of the same line. The parser collapses identical text over an identical span unconditionally, and collapses contiguous same-text runs of at least three events when the run looks like an animation. For ASS that means shared style and actor plus authoring evidence: a temporal tag (`\t`, `\move`, `\k`/`\kf`/`\ko`/`\K`, or anything wrapped in `\t(...)`), an animated `Effect` column (`Karaoke`, `Banner`, `Scroll`), or override values that change across the run. Static tags shared by every event (`\pos`, an identical `\clip`) are not evidence. SRT/VTT carry no such metadata, so there collapsing needs at least five contiguous events all under 0.1s — the frame timing left behind by ASS-to-SRT conversion. The parser keeps this authoring metadata (style, actor, layer, `Effect`, parsed override commands, source order) private; `parseSubtitleCues()` returns only `SubtitleCue`.
 
+ASS scripts can also redraw one complete lyric for two or more long color/highlight phases. Those flush-timed phases collapse separately from short animation frames when they share text, style, actor, and layer and carry direct animation evidence, such as temporal tags or changing non-spatial overrides. Spatial command changes do not prove a phase, so separately positioned signs remain distinct.
+
+**Canonical animation recovery.** Some ASS producers keep the readable lyric or sign as a timed `Comment:` and generate hundreds of `Dialogue:` frames containing repeated glyphs or changing clip regions. Others retain the complete line as brief `Dialogue:` events around the generated fragments. A complete event is promoted only when nearby dialogue from the same style and actor forms a proven animation cluster and reconstructs its entire text in source order. The generated frames are then replaced by one cue marked `source: 'canonical-ass'`. This source marker lets the live primary-subtitle path prefer the clean authored text and timing for display, sidebar history, immersion recording, and mining, while unmatched editor notes and alternative translations remain ignored.
+
 #### Prefetch Service Lifecycle
 
 1. **Activation trigger:** When a subtitle track is activated (or changes), check if it's external via MPV's `track-list` property. If `external === true`, read the file via `external-filename` using the existing `loadSubtitleSourceText` infrastructure.

docs/architecture/subtitle-overlay-priming.md

@@ -129,7 +129,11 @@ coming and prefetching would otherwise idle for the rest of the cue.
   path, empty or stale bounding shapes produced invisible or clipped subtitles even though the
   overlay window remained mapped above mpv.
 - Pointer pass-through should continue to use `setIgnoreMouseEvents(true, { forward: true })` and
-  the Linux cursor-poll fallback, not bounding-shape clipping.
+  the Linux cursor-poll fallback, not bounding-shape clipping. Note that on Windows click-through
+  must go through `applyOverlayClickThrough()` (`src/core/services/overlay-click-through.ts`),
+  which omits `forward: true` there: Electron implements forwarding with a global low-level mouse
+  hook that lags mouse input system-wide whenever the main thread stalls; the Windows cursor poll
+  handles overlay wake-up instead.
 - Visible-overlay show/reset marks Linux pointer passthrough state dirty even when the logical
   interaction state is already inactive. The next cursor-poll tick must still reapply
   `setIgnoreMouseEvents(true, { forward: true })`; otherwise a newly shown Electron overlay can keep

package.json

@@ -2,7 +2,7 @@
   "name": "subminer",
   "productName": "SubMiner",
   "desktopName": "SubMiner.desktop",
-  "version": "0.19.3",
+  "version": "0.19.4-beta.1",
   "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
   "packageManager": "bun@1.3.5",
   "main": "dist/main-entry.js",

plugin/subminer/hover.lua

@@ -106,8 +106,11 @@ function M.create(ctx)
 
 	local function get_subtitle_ass_property()
 		local ass_text = mp.get_property("sub-text/ass")
-		if type(ass_text) == "string" and ass_text ~= "" then
-			return ass_text
+		if ass_text ~= nil then
+			if type(ass_text) == "string" and ass_text ~= "" then
+				return ass_text
+			end
+			return nil
 		end
 		ass_text = mp.get_property("sub-text-ass")
 		if type(ass_text) == "string" and ass_text ~= "" then

plugin/subminer/process.lua

@@ -7,6 +7,8 @@ local OVERLAY_RESTART_PING_MAX_ATTEMPTS = 20
 local OVERLAY_LOADING_OSD_PREFIX = "Overlay loading "
 local OVERLAY_LOADING_OSD_FRAMES = { "|", "/", "-", "\\" }
 local OVERLAY_LOADING_OSD_REFRESH_SECONDS = 0.18
+local OVERLAY_LOADING_OSD_DEADLINE_SECONDS = 30
+local OVERLAY_LOADING_OSD_TIMEOUT_MESSAGE = "Overlay did not become ready; check SubMiner logs"
 local AUTO_PLAY_READY_LOADING_OSD = "Loading subtitle tokenization..."
 local AUTO_PLAY_READY_READY_OSD = "Subtitle tokenization ready"
 local DEFAULT_AUTO_PLAY_READY_TIMEOUT_SECONDS = 30
@@ -265,10 +267,19 @@ function M.create(ctx)
 		state.overlay_loading_osd_timer = nil
 	end
 
+	local function clear_overlay_loading_osd_deadline()
+		local timeout = state.overlay_loading_osd_deadline
+		if timeout and timeout.kill then
+			timeout:kill()
+		end
+		state.overlay_loading_osd_deadline = nil
+	end
+
 	local function stop_overlay_loading_osd()
 		state.overlay_loading_osd_active = false
 		state.overlay_loading_osd_frame = 1
 		clear_overlay_loading_osd_timer()
+		clear_overlay_loading_osd_deadline()
 	end
 
 	local function start_overlay_loading_osd()
@@ -291,6 +302,21 @@ function M.create(ctx)
 				end
 			end)
 		end
+		if type(mp.add_timeout) == "function" then
+			state.overlay_loading_osd_deadline = mp.add_timeout(OVERLAY_LOADING_OSD_DEADLINE_SECONDS, function()
+				if not state.overlay_loading_osd_active then
+					return
+				end
+				state.overlay_loading_osd_deadline = nil
+				stop_overlay_loading_osd()
+				subminer_log(
+					"warn",
+					"process",
+					"Overlay loading deadline expired before the app reported content ready"
+				)
+				show_osd(OVERLAY_LOADING_OSD_TIMEOUT_MESSAGE, { force = true })
+			end)
+		end
 	end
 
 	local function disarm_auto_play_ready_gate(options)

plugin/subminer/session_bindings.lua

@@ -232,7 +232,7 @@ function M.create(ctx)
 		elseif action_id == "triggerFieldGrouping" then
 			return { "--trigger-field-grouping" }
 		elseif action_id == "triggerSubsync" then
-			return { "--trigger-subsync" }
+			return { "--session-action", '{"actionId":"triggerSubsync"}' }
 		elseif action_id == "mineSentence" then
 			return { "--mine-sentence" }
 		elseif action_id == "mineSentenceMultiple" then
@@ -251,7 +251,7 @@ function M.create(ctx)
 		elseif action_id == "markWatched" then
 			return { "--mark-watched" }
 		elseif action_id == "openRuntimeOptions" then
-			return { "--open-runtime-options" }
+			return { "--session-action", '{"actionId":"openRuntimeOptions"}' }
 		elseif action_id == "openJimaku" then
 			return { "--open-jimaku" }
 		elseif action_id == "openTsukihime" or action_id == "openAnimetosho" then
@@ -259,7 +259,7 @@ function M.create(ctx)
 		elseif action_id == "openYoutubePicker" then
 			return { "--open-youtube-picker" }
 		elseif action_id == "openSessionHelp" then
-			return { "--open-session-help" }
+			return { "--session-action", '{"actionId":"openSessionHelp"}' }
 		elseif action_id == "openCharacterDictionaryManager" then
 			return { "--session-action", '{"actionId":"openCharacterDictionaryManager"}' }
 		elseif action_id == "openControllerSelect" then

plugin/subminer/state.lua

@@ -26,6 +26,7 @@ function M.new()
 		auto_play_ready_initial_pause_ownership_consumed = false,
 		overlay_loading_osd_active = false,
 		overlay_loading_osd_timer = nil,
+		overlay_loading_osd_deadline = nil,
 		overlay_loading_osd_frame = 1,
 		pending_visible_overlay_hide_timer = nil,
 		pending_visible_overlay_hide_generation = 0,

plugin/subminer/ui.lua

@@ -4,6 +4,7 @@ function M.create(ctx)
 	local mp = ctx.mp
 	local input = ctx.input
 	local process = ctx.process
+	local state = ctx.state
 	local subminer_log = ctx.log.subminer_log
 	local show_osd = ctx.log.show_osd
 
@@ -93,7 +94,18 @@ function M.create(ctx)
 			if not ensure_binary_for_menu() then
 				return
 			end
-			process.run_control_command_async("open-session-help")
+			process.run_binary_command_async({
+				state.binary_path,
+				"--session-action",
+				'{"actionId":"openSessionHelp"}',
+			}, function(ok, result, error)
+				if ok then
+					return
+				end
+				local reason = error or (result and result.stderr) or "unknown error"
+				subminer_log("warn", "session-bindings", "Session action failed: " .. tostring(reason))
+				show_osd("Session action failed")
+			end)
 		end)
 	end
 

release/prerelease-notes.md

@@ -1,80 +1,52 @@
 > This is a prerelease build for testing. Stable changelog and docs-site updates remain pending until the final stable release.
 
-<!-- prerelease-base-version: 0.19.0 -->
+<!-- prerelease-base-version: 0.19.4 -->
 
 ## Highlights
 ### Added
-
-- **Sync Stats & History**
-  - New **Sync Stats & History** window (tray menu) and `subminer sync <host>` command keep mining stats and watch history in sync between machines over SSH, with saved devices, per-host sync direction, and live stage-by-stage progress.
-  - Merges are safe to repeat: data combines without duplicates, and hosts with auto-sync enabled sync automatically in the background on a schedule, reporting results as overlay notifications.
-  - Manual snapshot tools (create, merge, reveal, delete) and connection testing cover one-off transfers; Windows machines running the built-in OpenSSH Server work as sync remotes too, with no setup needed beyond SSH access. Power users can script transfers directly with `--push`/`--pull`, `--check`, `--snapshot`/`--merge`, and `--json` flags.
-
-- **TsukiHime Subtitle Downloads**
-  - Download Japanese and secondary-language subtitles for the current video directly from TsukiHime, mirroring the existing Jimaku flow.
-  - Press `Ctrl+Shift+T` to search by tabs for the primary and secondary languages; the matching release is found automatically from the video filename and loads straight into mpv, no API key required.
-
-- **Post-Playback History Menu**
-  - After a watch-history episode ends or mpv closes, the fzf/rofi launcher returns to that series with options to play the previous or next episode, rewatch, pick another episode, or quit SubMiner.
-  - Previous/Next continue across season directories, so you can binge a show without manually browsing folders.
-  - The menu shown right after picking a series from `subminer -H` now offers the previous episode too, matching the post-playback menu.
-
-- **Known-Word Highlighting by Anki Maturity**
-  - Subtitle highlights for known words can now be colored by Anki card maturity (new, learning, young, mature), similar to asbplayer. Enable it with `ankiConnect.knownWords.maturityEnabled`, or toggle it live during a session.
-  - The mature-interval threshold and the four tier colors are configurable, and the in-session help legend shows the active tier colors while maturity highlighting is on.
-  - Tiers follow Anki's own card state: a lapsed card correctly shows as learning rather than young, and a note is treated as mature if any of its cards are mature. Stats and other known-word tools stay accurate with this new data.
-
-- **Stats Library Entry Deletion**
-  - Added a "Delete Entry" action in the stats Library detail view that removes an entire title in one step: every episode, session, subtitle line, rollup, cover, and vocabulary count derived from it. Previously a mistaken entry had to be cleared episode by episode and still lingered in the Library.
-  - Delete progress (session, session group, episode, or full entry) now shows app-wide as a progress bar plus a status toast, staying visible across tabs and windows instead of disappearing when you switch away.
-  - Deletes are dramatically faster on large libraries, and opening the Vocabulary tab no longer stalls; the first launch after upgrading migrates the stats database in place to support this.
-
-### Changed
-
-- **Clipboard-Video Shortcut**
-  - The "append clipboard video to queue" shortcut is now configurable via `shortcuts.appendClipboardVideoToQueue` instead of being fixed.
+- **Library Merge and Move**
+  - Duplicate library cards for the same show can now be combined: select cards in the library grid, choose "Merge Selected," and pick which entry to keep. Sessions, mined cards, and watch time move over, and future episodes stay matched to the merged card.
+  - Episodes can be reassigned to a different library entry with a "→" button on the episode row, fixing cases where a file lands under the wrong title. Manual assignments survive later filename parsing, Jellyfin refreshes, and season repair.
+  - Exact AniList matches with compatible seasons now merge automatically, while fuzzy matches show up as a dismissible "Possible duplicate" prompt instead of merging without confirmation.
 
 ### Fixed
+- **Anki Audio Generation on Network Drives**
+  - Fixed sentence-audio generation timing out on slow network-mounted video files with many subtitle and font-attachment streams.
+  - Extraction now uses bounded probing and a two-minute budget, and failures show a clear error instead of a cryptic one.
+- **Duplicate Subtitle Line Stats**
+  - Fixed karaoke openings and animated signs (which record one subtitle event per animation frame) inflating word and kanji counts and skewing "Top Repeated Words." Ordinary repeated dialogue and rewatches are unaffected.
+  - Already-inflated stats can be cleaned up with the new "Duplicates" button in the Vocabulary tab, or `subminer stats cleanup --duplicate-lines` (supports `--dry-run` and `--lookback-days`). Only the affected subtitle lines and vocabulary counts are touched; watch time and lines-seen totals are untouched.
+- **Overlay Modals on macOS and Windows**
+  - Fixed overlay modals and the stats window opening on the wrong macOS Space, or forcing a Space switch, when mpv is fullscreen. They now open above fullscreen mpv on its current Space.
+  - Modals are now prewarmed on macOS and Windows so shortcuts open them promptly, and Windows keeps the hidden modal responsive between sessions.
+- **Wayland File Drag-and-Drop**
+  - Fixed dragging subtitle and video files from file managers like Thunar onto the overlay on native Wayland; dropped files are now resolved and sent to mpv.
+- **Windows Mouse Lag**
+  - Fixed system-wide mouse lag while SubMiner is running on Windows, caused by a global mouse hook and blocking window lookups during click-through tracking.
+- **Mining Clip Accuracy**
+  - Fixed mined audio and animated image clips sometimes capturing the wrong subtitle line when audio extraction was slow. The clip range is now locked in at the moment of lookup, so audio and image clips always match.
+- **Linux Notifications**
+  - Character dictionary progress notifications on Linux now update in place instead of flickering off and back on with every status change.
+- **Stats Delete Performance**
+  - Fixed stats deletes freezing the dashboard; deletes now reliably run off the main thread, with automatic retry if the delete worker crashes.
+  - Deletes, library merges/moves, and AniList reassignments are now much faster because totals are updated incrementally instead of rebuilt from scratch, and no longer erase lifetime totals older than the recent session history.
+  - Session deletes on large libraries dropped from minutes to milliseconds.
 
-- **Word Highlighting Accuracy**
-  - Fixed several incorrect word highlighting and annotation cases: inconsistent part-of-speech exclusions on merged quote-particle tokens, missing annotations for rare kanji, katakana punctuation wrongly treated as non-kana noise, and certain kanji vocabulary skipped for next-level ("N+1") highlighting.
-
-- **AniList Season Resolution**
-  - Season 2 and later episodes now resolve to the correct AniList entry by walking sequel relations instead of guessing from the title, so watch progress, the character dictionary, and cover art for later seasons no longer silently fall back to season 1.
-  - Manual AniList overrides now stay in effect for every episode in the same season (by folder and detected season), and setting an override now fixes both the character dictionary and AniList watch progress together instead of needing separate corrections.
-
-- **Startup Playback Pausing Too Early**
-  - Fixed playback resuming before subtitle processing finished warming up, which could briefly show untranslated subtitles right after opening a video.
-  - Most noticeable when resuming mid-episode or when a subtitle cue starts within the first couple of seconds.
-
-- **Linux AppImage Crash Notification on Quit**
-  - Fixed a spurious "Service Crash" desktop notification appearing after closing a video when running the Linux AppImage.
-  - If needed, the mount-keepalive behavior behind this fix can be disabled with `SUBMINER_NO_APPIMAGE_MOUNT_KEEPALIVE=1`.
-
-- **AnkiConnect Proxy Port Conflict**
-  - Fixed video playback failing to start when another process already held the configured AnkiConnect proxy port; SubMiner now shows a notification explaining how to resolve the conflict instead of crashing.
-
-- **Stats & Settings Reliability**
-  - Fixed session stats reporting zero known words after the known-word cache gained maturity tiers.
-  - Hardened the stats server against malformed requests, stalled AniList lookups, media mismatches during word mining, and missing Yomitan connections.
-  - AnkiConnect settings validation now preserves valid custom configurations while safely falling back on invalid values instead of failing.
-
-- **Stats Library Cover After Relink**
-  - Relinking a title to a different AniList entry now updates its cover art in the stats Library grid, not just the detail view, so unrelated titles no longer end up sharing the wrong cover.
-
-- **Rofi Menu Prompt Spacing**
-  - Rofi menu prompts now keep a space between the prompt label and the input field instead of crowding the search placeholder text.
+### Docs
+- **Feature Demos Page**
+  - Hidden the unfinished feature demos page from the documentation sidebar; it's still reachable by direct URL.
 
 ## What's Changed
 
-- feat(shortcuts): make clipboard-video-append shortcut configurable by @ksyasuda in #158
-- refactor(tokenizer): extract subtitle annotation filter into rule table by @ksyasuda in #162
-- refactor(tsukihime): swap Animetosho backend for TsukiHime API by @ksyasuda in #165
-- refactor: split anki-connect and stats-server resolvers into modules by @ksyasuda in #169
-- feat(launcher): add post-playback history menu with previous episode by @ksyasuda in #170
-- Anki maturity-based known-word highlighting by @ksyasuda in #172
-- fix(anilist): resolve later seasons via sequel relations, not title guessing by @ksyasuda in #173
-- feat(stats): add library entry deletion and app-wide delete progress by @ksyasuda in #174
+- feat(stats): add library entry merge and episode move by @ksyasuda in #190
+- fix(stats): stop counting duplicate typeset subtitle lines by @ksyasuda in #191
+- fix(media): tolerate slow MKV audio extraction by @ksyasuda in #195
+- fix(stats): subtract lifetime totals incrementally on delete by @ksyasuda in #196
+- fix(anki): snapshot mining media clip timing by @ksyasuda in #197
+- fix(notifications): replace Linux progress updates in place by @ksyasuda in #198
+- fix(overlay): support native Wayland file drag-and-drop by @ksyasuda in #199
+- fix(overlay): keep macOS modal windows on fullscreen Spaces by @ksyasuda in #200
+- fix(overlay): prevent Windows mouse lag during click-through tracking by @ksyasuda in #201
 
 ## Installation
 

scripts/build-versioned-docs.ts

@@ -35,6 +35,17 @@ const archiveCacheRoot = join(repoRoot, '.tmp/docs-versioned-archive-cache');
 const maxCloudflareFiles = 20_000;
 const maxCloudflareFileBytes = 25 * 1024 * 1024;
 
+// Cloudflare Pages header rules for the whole deployment. Mirrors the `noindex,follow`
+// meta tag the non-root channels emit, so the duplicate trees stay out of the index
+// even for responses a crawler takes without parsing the HTML.
+const deployHeaders = `# Generated by scripts/build-versioned-docs.ts. Do not edit by hand.
+/main/*
+  X-Robots-Tag: noindex, follow
+
+/v/*
+  X-Robots-Tag: noindex, follow
+`;
+
 function run(
   command: string,
   args: string[],
@@ -173,6 +184,7 @@ function buildDocs(options: {
       SUBMINER_DOCS_BASE: options.base,
       SUBMINER_DOCS_OUT_DIR: options.outDir,
       SUBMINER_DOCS_SOURCE_DIR: options.snapshotDocsSite,
+      SUBMINER_DOCS_REPO_DIR: currentDocsSite,
       SUBMINER_DOCS_CHANNEL: options.channel,
       SUBMINER_DOCS_VERSION: options.version ?? '',
       SUBMINER_DOCS_LATEST_STABLE: options.latestStable,
@@ -378,6 +390,7 @@ function main() {
   });
 
   writeFileSync(join(aggregateOutDir, 'versions.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+  writeFileSync(join(aggregateOutDir, '_headers'), deployHeaders);
   assertCloudflarePagesLimits(aggregateOutDir);
   const prunedArchives = pruneArchiveCacheGenerations({
     cacheRoot: archiveCacheRoot,

scripts/test-plugin-start-gate.lua

@@ -130,7 +130,9 @@ local function run_plugin_scenario(config)
 
 		function mp.add_timeout(seconds, callback)
 			recorded.timeouts[#recorded.timeouts + 1] = seconds
+			local delay = tonumber(seconds) or 0
 			local timeout = {
+				seconds = delay,
 				killed = false,
 				callback = callback,
 			}
@@ -138,7 +140,6 @@ local function run_plugin_scenario(config)
 				self.killed = true
 			end
 
-			local delay = tonumber(seconds) or 0
 			if callback and delay < 5 and not config.defer_timeouts then
 				callback()
 			end
@@ -514,6 +515,15 @@ local function has_timeout(timeouts, target)
 	return false
 end
 
+local function find_timeout_handle(recorded, target)
+	for _, timeout in ipairs(recorded.timeout_handles) do
+		if math.abs(timeout.seconds - target) < 0.0001 then
+			return timeout
+		end
+	end
+	return nil
+end
+
 local function env_has(call, target)
 	local env = (call and call.env) or {}
 	for _, value in ipairs(env) do
@@ -1636,6 +1646,8 @@ do
 		#recorded.periodic_timers == 1,
 		"auto-start visible overlay should refresh the early overlay loading OSD"
 	)
+	local overlay_loading_deadline = find_timeout_handle(recorded, 30)
+	assert_true(overlay_loading_deadline ~= nil, "overlay loading OSD should have a bounded deadline")
 	local overlay_loading_timer = recorded.periodic_timers[1]
 	recorded.periodic_timers[1].callback()
 	assert_true(
@@ -1670,6 +1682,46 @@ do
 		recorded.periodic_timers[1].killed == true,
 		"overlay loading ready should stop the early overlay loading OSD refresher"
 	)
+	assert_true(
+		overlay_loading_deadline.killed == true,
+		"overlay loading ready should cancel the bounded loading deadline"
+	)
+end
+
+do
+	local recorded, err = run_plugin_scenario({
+		defer_timeouts = true,
+		process_list = "",
+		option_overrides = {
+			binary_path = binary_path,
+			auto_start = "yes",
+			auto_start_visible_overlay = "yes",
+			osd_messages = false,
+			socket_path = "/tmp/subminer-socket",
+		},
+		input_ipc_server = "/tmp/subminer-socket",
+		media_title = "Random Movie",
+		files = {
+			[binary_path] = true,
+		},
+	})
+	assert_true(recorded ~= nil, "plugin failed to load for overlay loading deadline scenario: " .. tostring(err))
+	fire_event(recorded, "start-file")
+	local overlay_loading_deadline = find_timeout_handle(recorded, 30)
+	assert_true(overlay_loading_deadline ~= nil, "overlay loading deadline should be scheduled")
+	overlay_loading_deadline.callback()
+	assert_true(
+		recorded.periodic_timers[1].killed == true,
+		"overlay loading deadline should stop the loading spinner"
+	)
+	assert_true(
+		has_osd_message(recorded.osd, "SubMiner: Overlay did not become ready; check SubMiner logs"),
+		"overlay loading deadline should replace the spinner with actionable feedback"
+	)
+	assert_true(
+		has_log_containing(recorded.logs, "Overlay loading deadline expired"),
+		"overlay loading deadline should leave a diagnostic log entry"
+	)
 end
 
 do

src/anki-integration.ts

@@ -28,8 +28,6 @@ import {
   KikuMergePreviewResponse,
   NotificationOptions,
   type WordCardKind,
-  type MediaTimingReviewDecision,
-  type MediaTimingReviewRequest,
 } from './types/anki';
 import { AiConfig } from './types/integrations';
 import type { KnownWordMaturityTier } from './types/subtitle';
@@ -240,9 +238,6 @@ export class AnkiIntegration {
   private recordCardsMinedCallback: ((count: number, noteIds?: number[]) => void) | null = null;
   private knownWordCacheUpdatedCallback: (() => void) | null = null;
   private consumeSubtitleMiningContextCallback: (() => SubtitleMiningContext | null) | null = null;
-  private mediaTimingReviewCallback:
-    | ((request: MediaTimingReviewRequest) => Promise<MediaTimingReviewDecision>)
-    | null = null;
   private noteIdRedirects = new Map<number, number>();
   private trackedDuplicateNoteIds = new Map<number, number[]>();
   private getCachedMediaPath: MediaGenerationInputResolverOptions['getCachedMediaPath'] | null =
@@ -514,7 +509,6 @@ export class AnkiIntegration {
         findNotes: async (query, options) =>
           (await this.client.findNotes(query, options)) as number[],
         retrieveMediaFile: (filename) => this.client.retrieveMediaFile(filename),
-        deleteNotes: (noteIds) => this.client.deleteNotes(noteIds),
       },
       mediaGenerator: {
         generateAudio: (
@@ -572,7 +566,6 @@ export class AnkiIntegration {
       getEffectiveSentenceCardConfig: () => this.getEffectiveSentenceCardConfig(),
       getFallbackDurationSeconds: () => this.getFallbackDurationSeconds(),
       appendKnownWordsFromNoteInfo: (noteInfo) => this.appendKnownWordsFromNoteInfo(noteInfo),
-      removeKnownWordNote: (noteId) => this.removeKnownWordNote(noteId),
       isUpdateInProgress: () => this.updateInProgress,
       setUpdateInProgress: (value) => {
         this.updateInProgress = value;
@@ -588,7 +581,6 @@ export class AnkiIntegration {
       recordCardsMinedCallback: (count, noteIds) => {
         this.recordCardsMinedSafely(count, noteIds, 'card creation');
       },
-      reviewMediaTiming: (request) => this.reviewMediaTiming(request),
     });
   }
 
@@ -645,14 +637,12 @@ export class AnkiIntegration {
         notesInfo: async (noteIds) => (await this.client.notesInfo(noteIds)) as unknown,
         updateNoteFields: (noteId, fields) => this.client.updateNoteFields(noteId, fields),
         storeMediaFile: (filename, data) => this.client.storeMediaFile(filename, data),
-        deleteNotes: (noteIds) => this.client.deleteNotes(noteIds),
       },
       getConfig: () => this.config,
       getCurrentSubtitleText: () => this.mpvClient.currentSubText,
       getCurrentSubtitleStart: () => this.mpvClient.currentSubStart,
       getEffectiveSentenceCardConfig: () => this.getEffectiveSentenceCardConfig(),
       appendKnownWordsFromNoteInfo: (noteInfo) => this.appendKnownWordsFromNoteInfo(noteInfo),
-      removeKnownWordNote: (noteId) => this.removeKnownWordNote(noteId),
       extractFields: (fields) => this.extractFields(fields),
       findDuplicateNote: (expression, excludeNoteId, noteInfo) =>
         this.findDuplicateNote(expression, excludeNoteId, noteInfo),
@@ -690,7 +680,6 @@ export class AnkiIntegration {
       logWarn: (...args) => log.warn(args[0] as string, ...args.slice(1)),
       logInfo: (...args) => log.info(args[0] as string, ...args.slice(1)),
       logError: (...args) => log.error(args[0] as string, ...args.slice(1)),
-      reviewMediaTiming: (request) => this.reviewMediaTiming(request),
     });
   }
 
@@ -810,12 +799,6 @@ export class AnkiIntegration {
     }
   }
 
-  private removeKnownWordNote(noteId: number): void {
-    if (this.knownWordCache.removeNote(noteId)) {
-      this.notifyKnownWordCacheUpdated();
-    }
-  }
-
   private notifyKnownWordCacheUpdated(): void {
     if (!this.knownWordCacheUpdatedCallback) {
       return;
@@ -1056,7 +1039,7 @@ export class AnkiIntegration {
       videoPath,
       startTime,
       endTime,
-      context?.mediaPaddingSeconds ?? this.config.media?.audioPadding,
+      this.config.media?.audioPadding,
       resolveAudioStreamIndexForMediaGeneration(videoPath, this.mpvClient.currentAudioStreamIndex),
       this.config.media?.normalizeAudio !== false,
       await this.getMpvVolumeScale(),
@@ -1089,7 +1072,7 @@ export class AnkiIntegration {
         videoPath,
         mediaRange.startTime,
         mediaRange.endTime,
-        context?.mediaPaddingSeconds ?? this.config.media?.audioPadding,
+        this.config.media?.audioPadding,
         {
           fps: this.config.media?.animatedFps,
           maxWidth: this.config.media?.animatedMaxWidth,
@@ -1740,25 +1723,6 @@ export class AnkiIntegration {
     this.consumeSubtitleMiningContextCallback = callback;
   }
 
-  setMediaTimingReviewCallback(
-    callback: ((request: MediaTimingReviewRequest) => Promise<MediaTimingReviewDecision>) | null,
-  ): void {
-    this.mediaTimingReviewCallback = callback;
-  }
-
-  private async reviewMediaTiming(
-    request: Omit<MediaTimingReviewRequest, 'audioPadding' | 'maxMediaDuration'>,
-  ): Promise<MediaTimingReviewDecision> {
-    if (this.config.media?.reviewTiming !== true || !this.mediaTimingReviewCallback) {
-      return { action: 'use-original' };
-    }
-    return await this.mediaTimingReviewCallback({
-      ...request,
-      audioPadding: Math.max(0, this.config.media.audioPadding ?? 0),
-      maxMediaDuration: Math.max(0, this.config.media.maxMediaDuration ?? 30),
-    });
-  }
-
   resolveCurrentNoteId(noteId: number): number {
     let resolved = noteId;
     const seen = new Set<number>();

src/anki-integration/card-creation-manual-update.test.ts

@@ -85,7 +85,6 @@ function createManualUpdateService(overrides: Partial<CardCreationDeps> = {}): {
       },
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => Buffer.from('audio'),
@@ -130,7 +129,6 @@ function createManualUpdateService(overrides: Partial<CardCreationDeps> = {}): {
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -203,7 +201,6 @@ test('manual clipboard subtitle update marks Kiku word cards as word-and-sentenc
       storeMediaFile: async () => undefined,
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     getEffectiveSentenceCardConfig: () => ({
       model: 'Sentence',
@@ -251,7 +248,6 @@ test('manual clipboard subtitle update skips audio when sentence audio field is
       },
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
   });
 
@@ -339,7 +335,6 @@ test('manual clipboard subtitle update uses resolved mpv stream URLs for remote
       },
       findNotes: async () => [42],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (path) => {
@@ -388,98 +383,3 @@ test('createSentenceCard relies on Anki progress notification without standalone
   assert.deepEqual(progressMessages, ['Creating sentence card']);
   assert.deepEqual(statusMessages, []);
 });
-
-test('discarding an audio-card timing review deletes the note before evicting its cache entry', async () => {
-  const events: string[] = [];
-  const statusMessages: string[] = [];
-  const { service } = createManualUpdateService({
-    getMpvClient: () =>
-      ({
-        currentVideoPath: '/video.mp4',
-        currentSubText: '字幕',
-        currentSubStart: 4,
-        currentSubEnd: 6,
-        currentTimePos: 5,
-      }) as never,
-    client: {
-      addNote: async () => 0,
-      addTags: async () => undefined,
-      notesInfo: async () => [
-        {
-          noteId: 42,
-          fields: { Expression: { value: '単語' } },
-        },
-      ],
-      updateNoteFields: async () => undefined,
-      storeMediaFile: async () => undefined,
-      findNotes: async () => [42],
-      retrieveMediaFile: async () => '',
-      deleteNotes: async (noteIds) => {
-        events.push(`delete:${noteIds.join(',')}`);
-      },
-    },
-    reviewMediaTiming: async () => ({ action: 'discard' }),
-    removeKnownWordNote: (noteId) => {
-      events.push(`cache:${noteId}`);
-    },
-    showStatusNotification: (message) => {
-      statusMessages.push(message);
-    },
-  });
-
-  await service.markLastCardAsAudioCard();
-
-  assert.deepEqual(events, ['delete:42', 'cache:42']);
-  assert.deepEqual(statusMessages, ['Card deleted.']);
-});
-
-test('keeping an audio card without media skips generation and preserves the note', async () => {
-  let generatedAudio = false;
-  let deleted = false;
-  const updates: Array<{ noteId: number; fields: Record<string, string> }> = [];
-  const { service, storedMedia } = createManualUpdateService({
-    getMpvClient: () =>
-      ({
-        currentVideoPath: '/video.mp4',
-        currentSubText: '字幕',
-        currentSubStart: 4,
-        currentSubEnd: 6,
-        currentTimePos: 5,
-      }) as never,
-    client: {
-      addNote: async () => 0,
-      addTags: async () => undefined,
-      notesInfo: async () => [
-        {
-          noteId: 42,
-          fields: { Expression: { value: '単語' }, Sentence: { value: '' } },
-        },
-      ],
-      updateNoteFields: async (noteId, fields) => {
-        updates.push({ noteId, fields });
-      },
-      storeMediaFile: async () => undefined,
-      findNotes: async () => [42],
-      retrieveMediaFile: async () => '',
-      deleteNotes: async () => {
-        deleted = true;
-      },
-    },
-    mediaGenerator: {
-      generateAudio: async () => {
-        generatedAudio = true;
-        return Buffer.from('audio');
-      },
-      generateScreenshot: async () => null,
-      generateAnimatedImage: async () => null,
-    },
-    reviewMediaTiming: async () => ({ action: 'skip-media' }),
-  });
-
-  await service.markLastCardAsAudioCard();
-
-  assert.equal(generatedAudio, false);
-  assert.equal(deleted, false);
-  assert.deepEqual(storedMedia, []);
-  assert.deepEqual(updates, [{ noteId: 42, fields: { Sentence: '字幕' } }]);
-});

src/anki-integration/card-creation-sentence-media.test.ts

@@ -12,7 +12,6 @@ test('sentence card writes generated audio only to sentence audio field', async
   const storedMedia: string[] = [];
   const requestedProperties: string[] = [];
   const audioVolumeScales: Array<number | undefined> = [];
-  const audioRanges: Array<{ start: number; end: number; padding: number | undefined }> = [];
 
   const deps: CardCreationDeps = {
     getConfig: () =>
@@ -74,19 +73,17 @@ test('sentence card writes generated audio only to sentence audio field', async
       },
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (
         _path,
-        startTime,
-        endTime,
-        audioPadding,
+        _startTime,
+        _endTime,
+        _audioPadding,
         _audioStreamIndex,
         _normalizeAudio,
         volumeScale,
       ) => {
-        audioRanges.push({ start: startTime, end: endTime, padding: audioPadding });
         audioVolumeScales.push(volumeScale);
         return Buffer.from('audio');
       },
@@ -125,15 +122,17 @@ test('sentence card writes generated audio only to sentence audio field', async
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
-    reviewMediaTiming: async () => ({ action: 'confirm', startTime: 11.4, endTime: 14.2 }),
   };
 
-  const service = new CardCreationService(deps);
-  const created = await service.createSentenceCard('字幕', 12, 14, 'Subtitle');
+  const created = await new CardCreationService(deps).createSentenceCard(
+    '字幕',
+    12,
+    14,
+    'Subtitle',
+  );
 
   assert.equal(created, true);
   assert.deepEqual(addedFields[0], {
@@ -145,19 +144,7 @@ test('sentence card writes generated audio only to sentence audio field', async
   assert.equal(storedMedia.length, 1);
   assert.deepEqual(requestedProperties, ['volume']);
   assert.deepEqual(audioVolumeScales, [0.4 ** 3]);
-  assert.deepEqual(audioRanges, [{ start: 11.4, end: 14.2, padding: 0 }]);
   const mediaUpdate = updatedFields.find((fields) => 'SentenceAudio' in fields);
   assert.equal(mediaUpdate?.SentenceAudio, `[sound:${storedMedia[0]}]`);
   assert.equal('ExpressionAudio' in mediaUpdate!, false);
-
-  deps.reviewMediaTiming = async () => ({ action: 'discard' });
-  assert.equal(await service.createSentenceCard('作らない', 20, 22), false);
-  assert.equal(addedFields.length, 1);
-
-  deps.reviewMediaTiming = async () => ({ action: 'skip-media' });
-  assert.equal(await service.createSentenceCard('メディアなし', 30, 32), true);
-  assert.equal(addedFields.length, 2);
-  assert.equal(storedMedia.length, 1);
-  assert.deepEqual(audioRanges, [{ start: 11.4, end: 14.2, padding: 0 }]);
-  assert.deepEqual(requestedProperties, ['volume']);
 });

src/anki-integration/card-creation.test.ts

@@ -42,7 +42,6 @@ test('CardCreationService counts locally created sentence cards', async () => {
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -75,7 +74,6 @@ test('CardCreationService counts locally created sentence cards', async () => {
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -141,7 +139,6 @@ test('CardCreationService keeps updating after trackLastAddedNoteId throws', asy
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -176,7 +173,6 @@ test('CardCreationService keeps updating after trackLastAddedNoteId throws', asy
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => {
@@ -242,7 +238,6 @@ test('CardCreationService keeps updating after recordCardsMinedCallback throws',
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -277,7 +272,6 @@ test('CardCreationService keeps updating after recordCardsMinedCallback throws',
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     recordCardsMinedCallback: () => {
@@ -354,7 +348,6 @@ test('CardCreationService uses stream-open-filename for remote media generation'
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (path) => {
@@ -399,7 +392,6 @@ test('CardCreationService uses stream-open-filename for remote media generation'
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -462,7 +454,6 @@ test('CardCreationService does not use mpv stream indexes for ready cached YouTu
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async (path, _startTime, _endTime, _padding, audioStreamIndex) => {
@@ -504,7 +495,6 @@ test('CardCreationService does not use mpv stream indexes for ready cached YouTu
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -600,7 +590,6 @@ test('CardCreationService queues YouTube media when required cache is not ready'
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => {
@@ -645,7 +634,6 @@ test('CardCreationService queues YouTube media when required cache is not ready'
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -713,7 +701,6 @@ test('CardCreationService tracks pre-add duplicate note ids for kiku sentence ca
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -746,7 +733,6 @@ test('CardCreationService tracks pre-add duplicate note ids for kiku sentence ca
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,
@@ -804,7 +790,6 @@ test('CardCreationService does not track duplicate ids when pre-add lookup retur
       storeMediaFile: async () => undefined,
       findNotes: async () => [],
       retrieveMediaFile: async () => '',
-      deleteNotes: async () => undefined,
     },
     mediaGenerator: {
       generateAudio: async () => null,
@@ -837,7 +822,6 @@ test('CardCreationService does not track duplicate ids when pre-add lookup retur
     }),
     getFallbackDurationSeconds: () => 10,
     appendKnownWordsFromNoteInfo: () => undefined,
-    removeKnownWordNote: () => undefined,
     isUpdateInProgress: () => false,
     setUpdateInProgress: () => undefined,
     trackLastAddedNoteId: () => undefined,

src/anki-integration/card-creation.ts

@@ -3,13 +3,7 @@ import {
   getConfiguredWordFieldName,
   getPreferredWordValueFromExtractedFields,
 } from '../anki-field-config';
-import {
-  AnkiConnectConfig,
-  type CardKind,
-  type MediaTimingReviewDecision,
-  type MediaTimingReviewRequest,
-  type WordCardKind,
-} from '../types/anki';
+import { AnkiConnectConfig, type CardKind, type WordCardKind } from '../types/anki';
 import { createLogger } from '../logger';
 import type { MediaInput } from '../media-input';
 import { SubtitleTimingTracker } from '../subtitle-timing-tracker';
@@ -61,7 +55,6 @@ interface CardCreationClient {
   storeMediaFile(filename: string, data: Buffer): Promise<void>;
   findNotes(query: string, options?: { maxRetries?: number }): Promise<number[]>;
   retrieveMediaFile(filename: string): Promise<string>;
-  deleteNotes(noteIds: number[]): Promise<void>;
 }
 
 interface CardCreationMediaGenerator {
@@ -145,16 +138,12 @@ interface CardCreationDeps {
   };
   getFallbackDurationSeconds: () => number;
   appendKnownWordsFromNoteInfo: (noteInfo: CardCreationNoteInfo) => void;
-  removeKnownWordNote: (noteId: number) => void;
   isUpdateInProgress: () => boolean;
   setUpdateInProgress: (value: boolean) => void;
   trackLastAddedNoteId?: (noteId: number) => void;
   trackLastAddedDuplicateNoteIds?: (noteId: number, duplicateNoteIds: number[]) => void;
   findDuplicateNoteIds?: (expression: string, noteInfo: CardCreationNoteInfo) => Promise<number[]>;
   recordCardsMinedCallback?: (count: number, noteIds?: number[]) => void;
-  reviewMediaTiming?: (
-    request: Omit<MediaTimingReviewRequest, 'audioPadding' | 'maxMediaDuration'>,
-  ) => Promise<MediaTimingReviewDecision>;
 }
 
 export class CardCreationService {
@@ -271,7 +260,6 @@ export class CardCreationService {
           fields,
           this.deps.getConfig(),
         );
-
         const sentenceAudioField = this.getResolvedSentenceOnlyAudioFieldName(noteInfo);
         const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
         const sentenceField = sentenceCardConfig.sentenceField;
@@ -463,28 +451,6 @@ export class CardCreationService {
           this.deps.getConfig(),
         );
 
-        const timingDecision = this.deps.reviewMediaTiming
-          ? await this.deps.reviewMediaTiming({
-              kind: 'audio',
-              text: mpvClient.currentSubText,
-              startTime,
-              endTime,
-              noteId,
-            })
-          : ({ action: 'use-original' } as const);
-        if (timingDecision.action === 'discard') {
-          await this.deps.client.deleteNotes([noteId]);
-          this.deps.removeKnownWordNote(noteId);
-          this.deps.showStatusNotification('Card deleted.');
-          return;
-        }
-        const skipMedia = timingDecision.action === 'skip-media';
-        const exactReviewedRange = timingDecision.action === 'confirm';
-        if (timingDecision.action === 'confirm') {
-          startTime = timingDecision.startTime;
-          endTime = timingDecision.endTime;
-        }
-
         const updatedFields: Record<string, string> = {};
         const errors: string[] = [];
         let miscInfoFilename: string | null = null;
@@ -499,28 +465,25 @@ export class CardCreationService {
 
         const sentenceCardConfig = this.deps.getEffectiveSentenceCardConfig();
         const audioFieldName = sentenceCardConfig.audioField;
-        if (!skipMedia) {
-          try {
-            const audioFilename = this.generateAudioFilename();
-            const audioBuffer = await this.mediaGenerateAudio(
-              mpvClient.currentVideoPath,
-              startTime,
-              endTime,
-              exactReviewedRange ? 0 : undefined,
-            );
+        try {
+          const audioFilename = this.generateAudioFilename();
+          const audioBuffer = await this.mediaGenerateAudio(
+            mpvClient.currentVideoPath,
+            startTime,
+            endTime,
+          );
 
-            if (audioBuffer) {
-              await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
-              updatedFields[audioFieldName] = `[sound:${audioFilename}]`;
-              miscInfoFilename = audioFilename;
-            }
-          } catch (error) {
-            log.error('Failed to generate audio for audio card:', (error as Error).message);
-            errors.push('audio');
+          if (audioBuffer) {
+            await this.deps.client.storeMediaFile(audioFilename, audioBuffer);
+            updatedFields[audioFieldName] = `[sound:${audioFilename}]`;
+            miscInfoFilename = audioFilename;
           }
+        } catch (error) {
+          log.error('Failed to generate audio for audio card:', (error as Error).message);
+          errors.push('audio');
         }
 
-        if (!skipMedia && shouldGenerateImage(this.deps.getConfig())) {
+        if (shouldGenerateImage(this.deps.getConfig())) {
           try {
             const animatedLeadInSeconds = await this.deps.getAnimatedImageLeadInSeconds(noteInfo);
             const imageFilename = this.generateImageFilename();
@@ -529,7 +492,6 @@ export class CardCreationService {
               startTime,
               endTime,
               animatedLeadInSeconds,
-              exactReviewedRange,
             );
 
             const imageField = this.deps.getConfig().fields?.image;
@@ -602,28 +564,9 @@ export class CardCreationService {
 
     try {
       return await this.deps.withUpdateProgress('Creating sentence card', async () => {
-        const timingDecision = this.deps.reviewMediaTiming
-          ? await this.deps.reviewMediaTiming({
-              kind: 'sentence',
-              text: sentence,
-              startTime,
-              endTime,
-            })
-          : ({ action: 'use-original' } as const);
-        if (timingDecision.action === 'discard') {
-          this.deps.showStatusNotification('Card creation cancelled.');
-          return false;
-        }
-        const skipMedia = timingDecision.action === 'skip-media';
-        const exactReviewedRange = timingDecision.action === 'confirm';
-        if (timingDecision.action === 'confirm') {
-          startTime = timingDecision.startTime;
-          endTime = timingDecision.endTime;
-        }
-
         const config = this.deps.getConfig();
-        const generateAudio = !skipMedia && shouldGenerateAudio(config);
-        const generateImage = !skipMedia && shouldGenerateImage(config);
+        const generateAudio = shouldGenerateAudio(config);
+        const generateImage = shouldGenerateImage(config);
         const mediaResolverOptions = this.getMediaResolverOptions();
         const videoPath = generateImage
           ? await resolveMediaGenerationInput(mpvClient, 'video', mediaResolverOptions)
@@ -789,7 +732,6 @@ export class CardCreationService {
             generateAudio,
             generateImage,
             volumeScale,
-            ...(exactReviewedRange ? { mediaPaddingSeconds: 0 } : {}),
           });
           await this.deps.showNotification(noteId, label, 'media queued');
           return true;
@@ -805,12 +747,7 @@ export class CardCreationService {
           try {
             const audioFilename = this.generateAudioFilename();
             const audioBuffer = audioSourcePath
-              ? await this.mediaGenerateAudio(
-                  audioSourcePath,
-                  startTime,
-                  endTime,
-                  exactReviewedRange ? 0 : undefined,
-                )
+              ? await this.mediaGenerateAudio(audioSourcePath, startTime, endTime)
               : null;
 
             if (audioBuffer) {
@@ -828,13 +765,7 @@ export class CardCreationService {
         if (generateImage) {
           try {
             const imageFilename = this.generateImageFilename();
-            const imageBuffer = await this.generateImageBuffer(
-              videoPath!,
-              startTime,
-              endTime,
-              0,
-              exactReviewedRange,
-            );
+            const imageBuffer = await this.generateImageBuffer(videoPath!, startTime, endTime);
 
             const imageField = config.fields?.image;
             if (imageBuffer && imageField) {
@@ -902,7 +833,6 @@ export class CardCreationService {
     videoPath: MediaInput,
     startTime: number,
     endTime: number,
-    audioPaddingOverride?: number,
   ): Promise<Buffer | null> {
     const mpvClient = this.deps.getMpvClient();
     if (!mpvClient) {
@@ -913,7 +843,7 @@ export class CardCreationService {
       videoPath,
       startTime,
       endTime,
-      audioPaddingOverride ?? this.deps.getConfig().media?.audioPadding,
+      this.deps.getConfig().media?.audioPadding,
       resolveAudioStreamIndexForMediaGeneration(
         videoPath,
         mpvClient.currentAudioStreamIndex ?? undefined,
@@ -931,16 +861,13 @@ export class CardCreationService {
     startTime: number,
     endTime: number,
     animatedLeadInSeconds = 0,
-    exactReviewedRange = false,
   ): Promise<Buffer | null> {
     const mpvClient = this.deps.getMpvClient();
     if (!mpvClient) {
       return null;
     }
 
-    const timestamp = exactReviewedRange
-      ? startTime + (endTime - startTime) / 2
-      : mpvClient.currentTimePos || 0;
+    const timestamp = mpvClient.currentTimePos || 0;
 
     if (this.deps.getConfig().media?.imageType === 'avif') {
       let imageStart = startTime;
@@ -956,7 +883,7 @@ export class CardCreationService {
         videoPath,
         imageStart,
         imageEnd,
-        exactReviewedRange ? 0 : this.deps.getConfig().media?.audioPadding,
+        this.deps.getConfig().media?.audioPadding,
         {
           fps: this.deps.getConfig().media?.animatedFps,
           maxWidth: this.deps.getConfig().media?.animatedMaxWidth,

src/anki-integration/known-word-cache.test.ts

@@ -261,32 +261,6 @@ test('KnownWordCacheManager invalidates persisted cache when fields.word changes
   }
 });
 
-test('KnownWordCacheManager removes a deleted note from memory and persisted state', () => {
-  const config: AnkiConnectConfig = {
-    fields: { word: 'Word' },
-    knownWords: { highlightEnabled: true },
-  };
-  const { manager, statePath, cleanup } = createKnownWordCacheHarness(config);
-
-  try {
-    manager.appendFromNoteInfo({
-      noteId: 42,
-      fields: { Word: { value: '猫' } },
-    });
-
-    assert.equal(manager.removeNote(42), true);
-    assert.equal(manager.removeNote(42), false);
-    assert.equal(manager.isKnownWord('猫'), false);
-
-    const persisted = JSON.parse(fs.readFileSync(statePath, 'utf-8')) as {
-      notes?: Record<string, unknown>;
-    };
-    assert.deepEqual(persisted.notes, {});
-  } finally {
-    cleanup();
-  }
-});
-
 test('KnownWordCacheManager refresh incrementally reconciles deleted and edited note words', async () => {
   const config: AnkiConnectConfig = {
     fields: {

src/anki-integration/known-word-cache.ts

@@ -350,17 +350,6 @@ export class KnownWordCacheManager {
     return true;
   }
 
-  removeNote(noteId: number): boolean {
-    if (!this.noteEntriesById.has(noteId)) {
-      return false;
-    }
-
-    this.removeNoteSnapshot(noteId);
-    this.persistKnownWordCacheState();
-    log.info('Known-word cache removed deleted note', `noteId=${noteId}`);
-    return true;
-  }
-
   clearKnownWordCacheState(): void {
     this.clearInMemoryState();
     this.knownWordsStateKey = this.getKnownWordCacheStateKey();

src/anki-integration/note-update-workflow.test.ts

@@ -44,7 +44,6 @@ function createWorkflowHarness() {
         updates.push({ noteId, fields });
       },
       storeMediaFile: async () => undefined,
-      deleteNotes: async () => undefined,
     },
     getConfig: () => ({
       fields: {
@@ -62,7 +61,6 @@ function createWorkflowHarness() {
       kikuFieldGrouping: 'disabled' as const,
     }),
     appendKnownWordsFromNoteInfo: (_noteInfo: NoteUpdateWorkflowNoteInfo) => undefined,
-    removeKnownWordNote: (_noteId: number) => undefined,
     extractFields: (fields: Record<string, { value: string }>) => {
       const out: Record<string, string> = {};
       for (const [key, value] of Object.entries(fields)) {
@@ -594,104 +592,3 @@ test('NoteUpdateWorkflow queues media updates when YouTube cache is pending', as
   assert.equal(queuedUpdates[0]?.context, undefined);
   assert.deepEqual(harness.updates, [{ noteId: 42, fields: { Sentence: 'subtitle-text' } }]);
 });
-
-test('NoteUpdateWorkflow deletes an existing word card when timing review discards it', async () => {
-  const harness = createWorkflowHarness();
-  const deletedNoteIds: number[][] = [];
-  const removedKnownWordNoteIds: number[] = [];
-  let appendedKnownWords = false;
-  harness.deps.captureSubtitleMediaContext = () => ({
-    source: 'overlay',
-    text: 'subtitle-text',
-    startTime: 4,
-    endTime: 6,
-  });
-  harness.deps.client.deleteNotes = async (noteIds) => {
-    deletedNoteIds.push(noteIds);
-  };
-  harness.deps.appendKnownWordsFromNoteInfo = () => {
-    appendedKnownWords = true;
-  };
-  harness.deps.removeKnownWordNote = (noteId) => {
-    removedKnownWordNoteIds.push(noteId);
-  };
-  harness.deps.reviewMediaTiming = async () => ({ action: 'discard' });
-
-  await harness.workflow.execute(42);
-
-  assert.deepEqual(deletedNoteIds, [[42]]);
-  assert.deepEqual(removedKnownWordNoteIds, [42]);
-  assert.equal(appendedKnownWords, false);
-  assert.deepEqual(harness.updates, []);
-  assert.deepEqual(harness.notifications, []);
-});
-
-test('NoteUpdateWorkflow keeps the word card but skips media after timing review', async () => {
-  const harness = createWorkflowHarness();
-  const mediaCalls: string[] = [];
-  const deletedNoteIds: number[][] = [];
-  const queuedUpdates: unknown[] = [];
-  harness.deps.captureSubtitleMediaContext = () => ({
-    source: 'overlay',
-    text: 'subtitle-text',
-    startTime: 4,
-    endTime: 6,
-  });
-  harness.deps.getConfig = () => ({
-    fields: { sentence: 'Sentence', image: 'Picture' },
-    media: { generateAudio: true, generateImage: true },
-    behavior: {},
-  });
-  harness.deps.reviewMediaTiming = async () => ({ action: 'skip-media' });
-  harness.deps.generateAudio = async () => {
-    mediaCalls.push('audio');
-    return Buffer.from('audio');
-  };
-  harness.deps.generateImage = async () => {
-    mediaCalls.push('image');
-    return Buffer.from('image');
-  };
-  harness.deps.queuePendingYoutubeMediaUpdate = async (update) => {
-    queuedUpdates.push(update);
-    return true;
-  };
-  harness.deps.client.deleteNotes = async (noteIds) => {
-    deletedNoteIds.push(noteIds);
-  };
-
-  await harness.workflow.execute(42);
-
-  assert.deepEqual(mediaCalls, []);
-  assert.deepEqual(queuedUpdates, []);
-  assert.deepEqual(deletedNoteIds, []);
-  assert.deepEqual(harness.updates, [{ noteId: 42, fields: { Sentence: 'subtitle-text' } }]);
-  assert.deepEqual(harness.notifications, [{ noteId: 42, label: 'taberu' }]);
-});
-
-test('NoteUpdateWorkflow keeps cache unchanged and reports when deletion fails', async () => {
-  const harness = createWorkflowHarness();
-  const statusMessages: string[] = [];
-  let removedKnownWord = false;
-  harness.deps.captureSubtitleMediaContext = () => ({
-    source: 'overlay',
-    text: 'subtitle-text',
-    startTime: 4,
-    endTime: 6,
-  });
-  harness.deps.client.deleteNotes = async () => {
-    throw new Error('delete failed');
-  };
-  harness.deps.removeKnownWordNote = () => {
-    removedKnownWord = true;
-  };
-  harness.deps.showOsdNotification = (message) => {
-    statusMessages.push(message);
-  };
-  harness.deps.reviewMediaTiming = async () => ({ action: 'discard' });
-
-  await harness.workflow.execute(42);
-
-  assert.equal(removedKnownWord, false);
-  assert.deepEqual(statusMessages, ['Card deletion failed: delete failed']);
-  assert.ok(harness.warnings.length === 0);
-});

src/anki-integration/note-update-workflow.ts

@@ -1,12 +1,7 @@
 import { DEFAULT_ANKI_CONNECT_CONFIG } from '../config';
 import { getPreferredWordValueFromExtractedFields } from '../anki-field-config';
 import type { SubtitleMiningContext } from '../types/subtitle';
-import type {
-  CardKind,
-  MediaTimingReviewDecision,
-  MediaTimingReviewRequest,
-  WordCardKind,
-} from '../types/anki';
+import type { CardKind, WordCardKind } from '../types/anki';
 import { resolveWordCardKind } from './note-field-utils';
 
 export interface NoteUpdateWorkflowNoteInfo {
@@ -19,7 +14,6 @@ export interface NoteUpdateWorkflowDeps {
     notesInfo(noteIds: number[]): Promise<unknown>;
     updateNoteFields(noteId: number, fields: Record<string, string>): Promise<void>;
     storeMediaFile(filename: string, data: Buffer): Promise<void>;
-    deleteNotes(noteIds: number[]): Promise<void>;
   };
   getConfig: () => {
     fields?: {
@@ -49,7 +43,6 @@ export interface NoteUpdateWorkflowDeps {
     wordCardKind?: WordCardKind;
   };
   appendKnownWordsFromNoteInfo: (noteInfo: NoteUpdateWorkflowNoteInfo) => void;
-  removeKnownWordNote: (noteId: number) => void;
   extractFields: (fields: Record<string, { value: string }>) => Record<string, string>;
   findDuplicateNote: (
     expression: string,
@@ -109,9 +102,6 @@ export interface NoteUpdateWorkflowDeps {
   logWarn: (message: string, ...args: unknown[]) => void;
   logInfo: (message: string, ...args: unknown[]) => void;
   logError: (message: string, ...args: unknown[]) => void;
-  reviewMediaTiming?: (
-    request: Omit<MediaTimingReviewRequest, 'audioPadding' | 'maxMediaDuration'>,
-  ) => Promise<MediaTimingReviewDecision>;
 }
 
 function normalizeSubtitleContextText(text: string): string {
@@ -181,6 +171,7 @@ export class NoteUpdateWorkflow {
       }
 
       const noteInfo = notesInfo[0]!;
+      this.deps.appendKnownWordsFromNoteInfo(noteInfo);
       const fields = this.deps.extractFields(noteInfo.fields);
       const config = this.deps.getConfig();
 
@@ -216,48 +207,10 @@ export class NoteUpdateWorkflow {
       // Audio and image generation run sequentially and audio extraction can take tens of
       // seconds, so resolve the clip range exactly once up front; reading live mpv sub
       // timings per generator clips whichever line is on screen when each one starts.
-      let mediaTimingContext =
+      const mediaTimingContext =
         subtitleMiningContext ?? this.deps.captureSubtitleMediaContext?.() ?? null;
-      let skipMedia = false;
       const noteLabel = hasExpressionText ? expressionText : noteId;
 
-      if (mediaTimingContext) {
-        const timingDecision = this.deps.reviewMediaTiming
-          ? await this.deps.reviewMediaTiming({
-              kind: 'word',
-              text: mediaTimingContext.text,
-              startTime: mediaTimingContext.startTime,
-              endTime: mediaTimingContext.endTime,
-              noteId,
-            })
-          : ({ action: 'use-original' } as const);
-        if (timingDecision.action === 'discard') {
-          try {
-            await this.deps.client.deleteNotes([noteId]);
-          } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            this.deps.logError('Failed to delete discarded card:', message);
-            this.deps.showOsdNotification(`Card deletion failed: ${message}`);
-            return;
-          }
-          this.deps.removeKnownWordNote(noteId);
-          this.deps.showOsdNotification('Card deleted.');
-          return;
-        }
-        if (timingDecision.action === 'confirm') {
-          mediaTimingContext = {
-            ...mediaTimingContext,
-            startTime: timingDecision.startTime,
-            endTime: timingDecision.endTime,
-            mediaPaddingSeconds: 0,
-          };
-        } else if (timingDecision.action === 'skip-media') {
-          skipMedia = true;
-        }
-      }
-
-      this.deps.appendKnownWordsFromNoteInfo(noteInfo);
-
       const currentSubtitleText = subtitleMiningContext?.text ?? this.deps.getCurrentSubtitleText();
       if (sentenceField && currentSubtitleText) {
         const processedSentence = this.deps.processSentence(currentSubtitleText, fields);
@@ -286,8 +239,8 @@ export class NoteUpdateWorkflow {
         }
       }
 
-      const generateAudio = !skipMedia && config.media?.generateAudio !== false;
-      const generateImage = !skipMedia && config.media?.generateImage !== false;
+      const generateAudio = config.media?.generateAudio !== false;
+      const generateImage = config.media?.generateImage !== false;
       const mediaCacheQueued =
         (generateAudio || generateImage) && this.deps.queuePendingYoutubeMediaUpdate
           ? await this.deps.queuePendingYoutubeMediaUpdate({

src/anki-integration/pending-youtube-media-queue.ts

@@ -148,9 +148,6 @@ export class PendingYoutubeMediaQueue {
       generateAudio: shouldGenerateAudio(config),
       generateImage: shouldGenerateImage(config),
       volumeScale,
-      ...(job.context?.mediaPaddingSeconds !== undefined
-        ? { mediaPaddingSeconds: job.context.mediaPaddingSeconds }
-        : {}),
     });
     return true;
   }
@@ -278,7 +275,7 @@ export class PendingYoutubeMediaQueue {
           cachedMediaInput,
           job.startTime,
           job.endTime,
-          job.mediaPaddingSeconds ?? config.media?.audioPadding,
+          config.media?.audioPadding,
           undefined,
           config.media?.normalizeAudio !== false,
           job.volumeScale,
@@ -312,7 +309,6 @@ export class PendingYoutubeMediaQueue {
           job.startTime,
           job.endTime,
           animatedLeadInSeconds,
-          job.mediaPaddingSeconds,
         );
         if (imageBuffer) {
           await this.deps.client.storeMediaFile(imageFilename, imageBuffer);
@@ -373,7 +369,6 @@ export class PendingYoutubeMediaQueue {
     startTime: number,
     endTime: number,
     animatedLeadInSeconds = 0,
-    mediaPaddingSeconds?: number,
   ): Promise<Buffer | null> {
     const config = this.deps.getConfig();
     if (config.media?.imageType === 'avif') {
@@ -381,7 +376,7 @@ export class PendingYoutubeMediaQueue {
         videoPath,
         startTime,
         endTime,
-        mediaPaddingSeconds ?? config.media?.audioPadding,
+        config.media?.audioPadding,
         {
           fps: config.media?.animatedFps,
           maxWidth: config.media?.animatedMaxWidth,

src/anki-integration/pending-youtube-media.ts

@@ -10,7 +10,6 @@ export interface PendingYoutubeMediaUpdate {
   generateAudio: boolean;
   generateImage: boolean;
   volumeScale?: number;
-  mediaPaddingSeconds?: number;
 }
 
 function trimToNonEmptyString(value: unknown): string | null {

src/config/config.test.ts

@@ -2181,7 +2181,6 @@ test('runtime options registry is centralized', () => {
   const ids = RUNTIME_OPTION_REGISTRY.map((entry) => entry.id);
   assert.deepEqual(ids, [
     'anki.autoUpdateNewCards',
-    'anki.mediaReviewTiming',
     'subtitle.annotation.knownWords.highlightEnabled',
     'subtitle.annotation.knownWords.maturityEnabled',
     'subtitle.annotation.nPlusOne',

src/config/definitions/defaults-integrations.ts

@@ -54,7 +54,6 @@ export const INTEGRATIONS_DEFAULT_CONFIG: Pick<
       syncAnimatedImageToWordAudio: true,
       normalizeAudio: true,
       mirrorMpvVolume: true,
-      reviewTiming: false,
       audioPadding: 0,
       fallbackDuration: 3.0,
       maxMediaDuration: 30,

src/config/definitions/options-integrations.ts

@@ -196,14 +196,6 @@ export function buildIntegrationConfigOptionRegistry(
       description:
         "Apply mpv's current software volume curve to generated sentence audio. Changes apply live.",
     },
-    {
-      path: 'ankiConnect.media.reviewTiming',
-      kind: 'boolean',
-      defaultValue: defaultConfig.ankiConnect.media.reviewTiming,
-      description:
-        'Review and preview subtitle media timing before SubMiner creates or enriches a mined card.',
-      runtime: runtimeOptionById.get('anki.mediaReviewTiming'),
-    },
     {
       path: 'ankiConnect.media.generateImage',
       kind: 'boolean',

src/config/definitions/runtime-options.ts

@@ -19,20 +19,6 @@ export function buildRuntimeOptionRegistry(
         behavior: { autoUpdateNewCards: value === true },
       }),
     },
-    {
-      id: 'anki.mediaReviewTiming',
-      path: 'ankiConnect.media.reviewTiming',
-      label: 'Review Media Timing',
-      scope: 'ankiConnect',
-      valueType: 'boolean',
-      allowedValues: [true, false],
-      defaultValue: defaultConfig.ankiConnect.media.reviewTiming,
-      requiresRestart: false,
-      formatValueForOsd: (value) => (value === true ? 'On' : 'Off'),
-      toAnkiPatch: (value) => ({
-        media: { reviewTiming: value === true },
-      }),
-    },
     {
       id: 'subtitle.annotation.knownWords.highlightEnabled',
       path: 'ankiConnect.knownWords.highlightEnabled',

src/config/definitions/template-sections.ts

@@ -135,7 +135,7 @@ const INTEGRATION_TEMPLATE_SECTIONS: ConfigTemplateSection[] = [
     title: 'AnkiConnect Integration',
     description: ['Automatic Anki updates and media generation options.'],
     notes: [
-      'Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.',
+      'Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume, knownWords, nPlusOne, fields.word/audio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.',
       'Shared AI provider transport settings are read from top-level ai and typically require restart.',
       'Most other AnkiConnect settings still require restart.',
     ],

src/config/resolve/anki-connect.test.ts

@@ -21,34 +21,6 @@ function makeContext(ankiConnect: unknown): {
   return { context, warnings };
 }
 
-test('media timing review is disabled by default and accepts a boolean override', () => {
-  const defaultContext = makeContext({});
-  applyAnkiConnectResolution(defaultContext.context);
-  assert.equal(defaultContext.context.resolved.ankiConnect.media.reviewTiming, false);
-
-  const enabledContext = makeContext({ media: { reviewTiming: true } });
-  applyAnkiConnectResolution(enabledContext.context);
-  assert.equal(enabledContext.context.resolved.ankiConnect.media.reviewTiming, true);
-  assert.deepEqual(enabledContext.warnings, []);
-});
-
-test('modern media duration accepts zero as the disabled cap sentinel', () => {
-  const disabledCap = makeContext({ media: { maxMediaDuration: 0 } });
-  applyAnkiConnectResolution(disabledCap.context);
-  assert.equal(disabledCap.context.resolved.ankiConnect.media.maxMediaDuration, 0);
-  assert.deepEqual(disabledCap.warnings, []);
-
-  const invalidCap = makeContext({ media: { maxMediaDuration: -1 } });
-  applyAnkiConnectResolution(invalidCap.context);
-  assert.equal(
-    invalidCap.context.resolved.ankiConnect.media.maxMediaDuration,
-    DEFAULT_CONFIG.ankiConnect.media.maxMediaDuration,
-  );
-  assert.ok(
-    invalidCap.warnings.some((warning) => warning.path === 'ankiConnect.media.maxMediaDuration'),
-  );
-});
-
 test('modern invalid knownWords.highlightEnabled warns modern key and does not fallback to legacy', () => {
   const { context, warnings } = makeContext({
     nPlusOne: { highlightEnabled: true },

src/config/resolve/anki-connect/modern-media.ts

@@ -19,7 +19,6 @@ export function applyModernMediaResolution(
     'syncAnimatedImageToWordAudio',
     'normalizeAudio',
     'mirrorMpvVolume',
-    'reviewTiming',
   ] as const) {
     applyModernValue(
       context,
@@ -129,28 +128,18 @@ export function applyModernMediaResolution(
     'Expected non-negative number.',
   );
 
-  applyModernValue(
-    context,
-    media,
-    'fallbackDuration',
-    'ankiConnect.media.fallbackDuration',
-    asPositiveNumber,
-    DEFAULT_CONFIG.ankiConnect.media.fallbackDuration,
-    (value) => {
-      context.resolved.ankiConnect.media.fallbackDuration = value;
-    },
-    'Expected positive number.',
-  );
-  applyModernValue(
-    context,
-    media,
-    'maxMediaDuration',
-    'ankiConnect.media.maxMediaDuration',
-    asNonNegativeNumber,
-    DEFAULT_CONFIG.ankiConnect.media.maxMediaDuration,
-    (value) => {
-      context.resolved.ankiConnect.media.maxMediaDuration = value;
-    },
-    'Expected non-negative number.',
-  );
+  for (const key of ['fallbackDuration', 'maxMediaDuration'] as const) {
+    applyModernValue(
+      context,
+      media,
+      key,
+      `ankiConnect.media.${key}`,
+      asPositiveNumber,
+      DEFAULT_CONFIG.ankiConnect.media[key],
+      (value) => {
+        context.resolved.ankiConnect.media[key] = value;
+      },
+      'Expected positive number.',
+    );
+  }
 }

src/config/settings/registry.test.ts

@@ -352,7 +352,6 @@ test('settings registry marks safe live config paths as hot-reloadable', () => {
     'ankiConnect.deck',
     'ankiConnect.media.normalizeAudio',
     'ankiConnect.media.mirrorMpvVolume',
-    'ankiConnect.media.reviewTiming',
     'ankiConnect.knownWords.highlightEnabled',
     'ankiConnect.knownWords.refreshMinutes',
     'ankiConnect.knownWords.addMinedWordsImmediately',

src/config/settings/registry.ts

@@ -244,7 +244,6 @@ const LABEL_OVERRIDES: Record<string, string> = {
   'mpv.aniskipEnabled': 'Enable AniSkip',
   'mpv.aniskipButtonKey': 'AniSkip Button Key',
   'ankiConnect.media.mirrorMpvVolume': 'Mirror mpv Volume',
-  'ankiConnect.media.reviewTiming': 'Review Media Timing',
   'discordPresence.updateIntervalMs': 'Update Interval (ms)',
 };
 
@@ -695,7 +694,6 @@ function restartBehaviorForPath(path: string): ConfigSettingsRestartBehavior {
     path === 'ankiConnect.ai.enabled' ||
     path === 'ankiConnect.media.normalizeAudio' ||
     path === 'ankiConnect.media.mirrorMpvVolume' ||
-    path === 'ankiConnect.media.reviewTiming' ||
     path === 'ankiConnect.behavior.autoUpdateNewCards' ||
     path === 'ankiConnect.knownWords.highlightEnabled' ||
     path === 'ankiConnect.knownWords.refreshMinutes' ||

src/core/services/config-hot-reload.test.ts

@@ -33,7 +33,6 @@ test('classifyConfigHotReloadDiff treats safe nested config paths as hot-reloada
   next.ankiConnect.deck = 'Mining';
   next.ankiConnect.media.normalizeAudio = !prev.ankiConnect.media.normalizeAudio;
   next.ankiConnect.media.mirrorMpvVolume = !prev.ankiConnect.media.mirrorMpvVolume;
-  next.ankiConnect.media.reviewTiming = !prev.ankiConnect.media.reviewTiming;
   next.ankiConnect.behavior.autoUpdateNewCards = !prev.ankiConnect.behavior.autoUpdateNewCards;
   next.ankiConnect.knownWords.highlightEnabled = !prev.ankiConnect.knownWords.highlightEnabled;
   next.ankiConnect.knownWords.refreshMinutes = prev.ankiConnect.knownWords.refreshMinutes + 5;
@@ -70,7 +69,6 @@ test('classifyConfigHotReloadDiff treats safe nested config paths as hot-reloada
       'ankiConnect.deck',
       'ankiConnect.media.normalizeAudio',
       'ankiConnect.media.mirrorMpvVolume',
-      'ankiConnect.media.reviewTiming',
       'ankiConnect.behavior.autoUpdateNewCards',
       'ankiConnect.knownWords.highlightEnabled',
       'ankiConnect.knownWords.refreshMinutes',

src/core/services/config-hot-reload.ts

@@ -70,7 +70,6 @@ const HOT_RELOAD_EXACT_OR_PREFIX_PATHS = [
   'ankiConnect.deck',
   'ankiConnect.media.normalizeAudio',
   'ankiConnect.media.mirrorMpvVolume',
-  'ankiConnect.media.reviewTiming',
   'ankiConnect.behavior.autoUpdateNewCards',
   'ankiConnect.knownWords.highlightEnabled',
   'ankiConnect.knownWords.refreshMinutes',

src/core/services/immersion-tracker/__tests__/duplicate-line-cleanup.test.ts

@@ -1,7 +1,4 @@
 import assert from 'node:assert/strict';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
 import test from 'node:test';
 import { Database } from '../sqlite.js';
 import type { DatabaseSync } from '../sqlite.js';
@@ -21,17 +18,6 @@ interface SeedLine {
   createdMs?: number;
 }
 
-function makeDbPath(): string {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-duplicate-line-test-'));
-  return path.join(dir, 'immersion.sqlite');
-}
-
-function cleanupDbPath(dbPath: string): void {
-  const dir = path.dirname(dbPath);
-  if (!fs.existsSync(dir)) return;
-  fs.rmSync(dir, { recursive: true, force: true });
-}
-
 /** One episode, two sessions of it, and one word occurrence per seeded line. */
 function seed(db: DatabaseSync, lines: SeedLine[]): void {
   db.exec(`
@@ -82,12 +68,16 @@ function seed(db: DatabaseSync, lines: SeedLine[]): void {
   `);
 }
 
-function createDb(lines: SeedLine[]): { db: DatabaseSync; dbPath: string } {
-  const dbPath = makeDbPath();
-  const db = new Database(dbPath);
+/**
+ * These tests exercise the cleanup SQL, not durability. A fresh on-disk database per
+ * test pays a schema-creation fsync that is cheap on a local NVMe but slow enough on CI
+ * runners to blow the 5s per-test timeout, so the database stays in memory.
+ */
+function createDb(lines: SeedLine[]): { db: DatabaseSync } {
+  const db = new Database(':memory:');
   ensureSchema(db);
   seed(db, lines);
-  return { db, dbPath };
+  return { db };
 }
 
 /** A typeset line mpv reported once per animation frame. */
@@ -119,7 +109,7 @@ function wordFrequency(db: DatabaseSync): number {
 }
 
 test('a karaoke burst collapses to one line and gives back its word counts', () => {
-  const { db, dbPath } = createDb([
+  const { db } = createDb([
     ...karaokeFrames(1, '飛び上がる', 10_000, 40, 40),
     { session: 1, text: 'おはよう', startMs: 20_000, endMs: 22_000 },
   ]);
@@ -148,7 +138,6 @@ test('a karaoke burst collapses to one line and gives back its word counts', ()
     assert.equal(summary.samples[0]!.videoTitle, 'Ep 1');
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
@@ -160,7 +149,7 @@ test('ordinary repeated dialogue survives', () => {
     startMs: 5_000 + index * 800,
     endMs: 5_000 + (index + 1) * 800,
   }));
-  const { db, dbPath } = createDb(lines);
+  const { db } = createDb(lines);
 
   try {
     const summary = cleanupDuplicateSubtitleLines(db);
@@ -171,14 +160,13 @@ test('ordinary repeated dialogue survives', () => {
     assert.equal(wordFrequency(db), 6);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
 test('a long run of quarter-second frames is still a burst', () => {
   // Between the timing-only bound (0.1s) and the animation-frame bound (0.3s): heavier
   // typesetting lands here, and the run length is what makes it conclusive.
-  const { db, dbPath } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 6, 250));
+  const { db } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 6, 250));
 
   try {
     const summary = cleanupDuplicateSubtitleLines(db);
@@ -189,12 +177,11 @@ test('a long run of quarter-second frames is still a burst', () => {
     assert.equal(wordFrequency(db), 1);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
 test('a qualifying short-frame burst may end with one long hold frame', () => {
-  const { db, dbPath } = createDb([
+  const { db } = createDb([
     ...karaokeFrames(1, '飛び上がる', 10_000, 8, 40),
     { session: 1, text: '飛び上がる', startMs: 10_320, endMs: 12_320 },
   ]);
@@ -208,12 +195,11 @@ test('a qualifying short-frame burst may end with one long hold frame', () => {
     assert.equal(wordFrequency(db), 1);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
 test('a long event before the final frame prevents burst cleanup', () => {
-  const { db, dbPath } = createDb([
+  const { db } = createDb([
     ...karaokeFrames(1, '飛び上がる', 10_000, 5, 40),
     { session: 1, text: '飛び上がる', startMs: 10_200, endMs: 12_200 },
     { session: 1, text: '飛び上がる', startMs: 12_200, endMs: 12_240 },
@@ -226,12 +212,11 @@ test('a long event before the final frame prevents burst cleanup', () => {
     assert.equal(countLines(db), 7);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
 test('a run of frames longer than the animation bound survives', () => {
-  const { db, dbPath } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 6, 400));
+  const { db } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 6, 400));
 
   try {
     const summary = cleanupDuplicateSubtitleLines(db);
@@ -240,7 +225,6 @@ test('a run of frames longer than the animation bound survives', () => {
     assert.equal(countLines(db), 6);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
@@ -248,7 +232,7 @@ test('the four-frame residue the live gate stores is cleaned up', () => {
   // The streaming gate records the first four frames of a burst before the run is long
   // enough to recognise. Four contiguous identical events under the strict timing-only
   // bound are that residue, and no real dialogue.
-  const { db, dbPath } = createDb(karaokeFrames(1, '飛び上がる', 1_000, 4, 40));
+  const { db } = createDb(karaokeFrames(1, '飛び上がる', 1_000, 4, 40));
 
   try {
     const summary = cleanupDuplicateSubtitleLines(db);
@@ -259,14 +243,13 @@ test('the four-frame residue the live gate stores is cleaned up', () => {
     assert.equal(wordFrequency(db), 1);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
 test('a four-frame run above the strict frame bound survives', () => {
   // Long enough per event to be plausible dialogue; only a five-event run may use the
   // looser animation-frame bound.
-  const { db, dbPath } = createDb(karaokeFrames(1, '飛び上がる', 1_000, 4, 250));
+  const { db } = createDb(karaokeFrames(1, '飛び上がる', 1_000, 4, 250));
 
   try {
     const summary = cleanupDuplicateSubtitleLines(db);
@@ -275,14 +258,13 @@ test('a four-frame run above the strict frame bound survives', () => {
     assert.equal(countLines(db), 4);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
 test('an explicit minRunLength raises the bar', () => {
   // Five quarter-second frames qualify under the defaults; a cautious run asking for six
   // leaves them alone. Above the strict bound, so the residue rule stays out of it.
-  const { db, dbPath } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 5, 250));
+  const { db } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 5, 250));
 
   try {
     const preview = cleanupDuplicateSubtitleLines(db, { dryRun: true });
@@ -293,12 +275,11 @@ test('an explicit minRunLength raises the bar', () => {
     assert.equal(countLines(db), 5);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
 test('an explicit maxFrameSeconds tightens the frame bound', () => {
-  const { db, dbPath } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 6, 250));
+  const { db } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 6, 250));
 
   try {
     const summary = cleanupDuplicateSubtitleLines(db, { maxFrameSeconds: 0.2 });
@@ -307,13 +288,12 @@ test('an explicit maxFrameSeconds tightens the frame bound', () => {
     assert.equal(countLines(db), 6);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
 test('a non-finite maxFrameSeconds falls back to the default bound', () => {
   // Six normal-beat lines: Infinity must not turn every event into a "short frame".
-  const { db, dbPath } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 6, 800));
+  const { db } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 6, 800));
 
   try {
     const summary = cleanupDuplicateSubtitleLines(db, { maxFrameSeconds: Infinity });
@@ -322,12 +302,11 @@ test('a non-finite maxFrameSeconds falls back to the default bound', () => {
     assert.equal(countLines(db), 6);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
 test('sampleLimit zero removes bursts but reports no samples', () => {
-  const { db, dbPath } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 40, 40));
+  const { db } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 40, 40));
 
   try {
     const summary = cleanupDuplicateSubtitleLines(db, { sampleLimit: 0 });
@@ -337,12 +316,11 @@ test('sampleLimit zero removes bursts but reports no samples', () => {
     assert.equal(countLines(db), 1);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
 test('a short run below every threshold survives', () => {
-  const { db, dbPath } = createDb(karaokeFrames(1, '飛び上がる', 1_000, 3, 40));
+  const { db } = createDb(karaokeFrames(1, '飛び上がる', 1_000, 3, 40));
 
   try {
     const summary = cleanupDuplicateSubtitleLines(db);
@@ -351,7 +329,6 @@ test('a short run below every threshold survives', () => {
     assert.equal(countLines(db), 3);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
@@ -361,7 +338,7 @@ test('interleaved dual-line karaoke collapses each line to one row', () => {
   const kanji = karaokeFrames(1, '飛び上がる', 10_000, 20, 60);
   const romaji = karaokeFrames(1, 'tobiagaru', 10_001, 20, 60);
   const interleaved = [...kanji, ...romaji].sort((a, b) => a.startMs - b.startMs);
-  const { db, dbPath } = createDb(interleaved);
+  const { db } = createDb(interleaved);
 
   try {
     const summary = cleanupDuplicateSubtitleLines(db);
@@ -372,12 +349,11 @@ test('interleaved dual-line karaoke collapses each line to one row', () => {
     assert.equal(wordFrequency(db), 2);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
 test('the same line in a rewatch session is never merged into the first watch', () => {
-  const { db, dbPath } = createDb([
+  const { db } = createDb([
     ...karaokeFrames(1, '飛び上がる', 10_000, 6, 40),
     ...karaokeFrames(2, '飛び上がる', 10_000, 6, 40),
   ]);
@@ -392,12 +368,11 @@ test('the same line in a rewatch session is never merged into the first watch',
     assert.equal(wordFrequency(db), 2);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
 test('a gap between runs splits them', () => {
-  const { db, dbPath } = createDb([
+  const { db } = createDb([
     ...karaokeFrames(1, '飛び上がる', 10_000, 6, 40),
     ...karaokeFrames(1, '飛び上がる', 60_000, 6, 40),
   ]);
@@ -409,12 +384,11 @@ test('a gap between runs splits them', () => {
     assert.equal(countLines(db), 2);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
 test('a dry run reports what an apply would do and writes nothing', () => {
-  const { db, dbPath } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 40, 40));
+  const { db } = createDb(karaokeFrames(1, '飛び上がる', 10_000, 40, 40));
 
   try {
     const preview = cleanupDuplicateSubtitleLines(db, { dryRun: true });
@@ -430,14 +404,13 @@ test('a dry run reports what an apply would do and writes nothing', () => {
     assert.equal(countLines(db), 1);
   } finally {
     db.close();
-    cleanupDbPath(dbPath);
   }
 });
 
 test('the lookback window leaves older bursts alone', () => {
   const recentMs = BASE_MS;
   const oldMs = BASE_MS - 40 * DAY_MS;
-  const { db, dbPath } = createDb([
+  const { db } = createDb([
     ...karaokeFrames(1, '飛び上がる', 10_000, 6, 40).map((line) => ({
       ...line,
       createdMs: oldMs,
@@ -462,6 +435,5 @@ test('the lookback window leaves older bursts alone', () => {
   } finally {
     globalThis.__subminerTestNowMs = undefined;
     db.close();
-    cleanupDbPath(dbPath);
   }
 });

src/core/services/ipc.test.ts

@@ -648,28 +648,6 @@ test('registerIpcHandlers exposes playback window activation request', async ()
   assert.deepEqual(calls, ['activate']);
 });
 
-test('registerIpcHandlers accepts the keep-without-media timing decision', async () => {
-  const { registrar, handlers } = createFakeIpcRegistrar();
-  const requests: unknown[] = [];
-  registerIpcHandlers(
-    createRegisterIpcDeps({
-      resolveMediaTimingReview: async (request) => {
-        requests.push(request);
-        return { ok: true };
-      },
-    }),
-    registrar,
-  );
-
-  const handler = handlers.handle.get(IPC_CHANNELS.request.mediaTimingReviewResolve);
-  assert.ok(handler);
-  assert.deepEqual(
-    await handler!({}, { reviewId: 'review-1', decision: { action: 'skip-media' } }),
-    { ok: true },
-  );
-  assert.deepEqual(requests, [{ reviewId: 'review-1', decision: { action: 'skip-media' } }]);
-});
-
 test('registerIpcHandlers forwards yomitan lookup tracking commands to immersion tracker', () => {
   const { registrar, handlers } = createFakeIpcRegistrar();
   const calls: string[] = [];

src/core/services/ipc.ts

@@ -19,13 +19,6 @@ import type {
   YoutubePickerResolveRequest,
   YoutubePickerResolveResult,
 } from '../../types';
-import type {
-  MediaTimingReviewActionResult,
-  MediaTimingReviewPreviewRequest,
-  MediaTimingReviewResolveRequest,
-  MediaTimingReviewWaveformRequest,
-  MediaTimingReviewWaveformResult,
-} from '../../types/anki';
 import { IPC_CHANNELS, type OverlayHostedModal } from '../../shared/ipc/contracts';
 import {
   parseMpvCommand,
@@ -41,6 +34,7 @@ import {
   parseSubsyncManualRunRequest,
   parseYoutubePickerResolveRequest,
 } from '../../shared/ipc/validators';
+import { applyOverlayClickThrough } from './overlay-click-through';
 
 const { ipcMain } = electron;
 
@@ -105,16 +99,6 @@ export interface IpcServiceDeps {
   onYoutubePickerResolve: (
     request: YoutubePickerResolveRequest,
   ) => Promise<YoutubePickerResolveResult>;
-  previewMediaTimingReview?: (
-    request: MediaTimingReviewPreviewRequest,
-  ) => Promise<MediaTimingReviewActionResult>;
-  getMediaTimingReviewWaveform?: (
-    request: MediaTimingReviewWaveformRequest,
-  ) => Promise<MediaTimingReviewWaveformResult>;
-  stopMediaTimingReviewPreview?: (reviewId: string) => Promise<MediaTimingReviewActionResult>;
-  resolveMediaTimingReview?: (
-    request: MediaTimingReviewResolveRequest,
-  ) => MediaTimingReviewActionResult | Promise<MediaTimingReviewActionResult>;
   getAnkiConnectStatus: () => boolean;
   getRuntimeOptions: () => unknown;
   setRuntimeOption: (id: RuntimeOptionId, value: RuntimeOptionValue) => unknown;
@@ -238,69 +222,6 @@ function parseOverlayNotificationActionPayload(
   return { notificationId, actionId, ...(typeof noteId === 'number' ? { noteId } : {}) };
 }
 
-function parseMediaTimingReviewPreviewRequest(
-  payload: unknown,
-): MediaTimingReviewPreviewRequest | null {
-  if (!payload || typeof payload !== 'object') return null;
-  const record = payload as Record<string, unknown>;
-  if (
-    typeof record.reviewId !== 'string' ||
-    !record.reviewId ||
-    typeof record.startTime !== 'number' ||
-    !Number.isFinite(record.startTime) ||
-    typeof record.endTime !== 'number' ||
-    !Number.isFinite(record.endTime)
-  ) {
-    return null;
-  }
-  return {
-    reviewId: record.reviewId,
-    startTime: record.startTime,
-    endTime: record.endTime,
-  };
-}
-
-function parseMediaTimingReviewWaveformRequest(
-  payload: unknown,
-): MediaTimingReviewWaveformRequest | null {
-  return parseMediaTimingReviewPreviewRequest(payload);
-}
-
-function parseMediaTimingReviewResolveRequest(
-  payload: unknown,
-): MediaTimingReviewResolveRequest | null {
-  if (!payload || typeof payload !== 'object') return null;
-  const record = payload as Record<string, unknown>;
-  if (typeof record.reviewId !== 'string' || !record.reviewId) return null;
-  const decision = record.decision;
-  if (!decision || typeof decision !== 'object') return null;
-  const decisionRecord = decision as Record<string, unknown>;
-  if (
-    decisionRecord.action === 'use-original' ||
-    decisionRecord.action === 'skip-media' ||
-    decisionRecord.action === 'discard'
-  ) {
-    return { reviewId: record.reviewId, decision: { action: decisionRecord.action } };
-  }
-  if (
-    decisionRecord.action === 'confirm' &&
-    typeof decisionRecord.startTime === 'number' &&
-    Number.isFinite(decisionRecord.startTime) &&
-    typeof decisionRecord.endTime === 'number' &&
-    Number.isFinite(decisionRecord.endTime)
-  ) {
-    return {
-      reviewId: record.reviewId,
-      decision: {
-        action: 'confirm',
-        startTime: decisionRecord.startTime,
-        endTime: decisionRecord.endTime,
-      },
-    };
-  }
-  return null;
-}
-
 export interface IpcDepsRuntimeOptions {
   getMainWindow: () => WindowLike | null;
   getVisibleOverlayVisibility: () => boolean;
@@ -357,10 +278,6 @@ export interface IpcDepsRuntimeOptions {
   onYoutubePickerResolve: (
     request: YoutubePickerResolveRequest,
   ) => Promise<YoutubePickerResolveResult>;
-  previewMediaTimingReview?: IpcServiceDeps['previewMediaTimingReview'];
-  getMediaTimingReviewWaveform?: IpcServiceDeps['getMediaTimingReviewWaveform'];
-  stopMediaTimingReviewPreview?: IpcServiceDeps['stopMediaTimingReviewPreview'];
-  resolveMediaTimingReview?: IpcServiceDeps['resolveMediaTimingReview'];
   getAnkiConnectStatus: () => boolean;
   getRuntimeOptions: () => unknown;
   setRuntimeOption: (id: RuntimeOptionId, value: RuntimeOptionValue) => unknown;
@@ -454,10 +371,6 @@ export function createIpcDepsRuntime(options: IpcDepsRuntimeOptions): IpcService
       options.activatePlaybackWindowForOverlayInteraction ?? (() => false),
     runSubsyncManual: options.runSubsyncManual,
     onYoutubePickerResolve: options.onYoutubePickerResolve,
-    previewMediaTimingReview: options.previewMediaTimingReview,
-    getMediaTimingReviewWaveform: options.getMediaTimingReviewWaveform,
-    stopMediaTimingReviewPreview: options.stopMediaTimingReviewPreview,
-    resolveMediaTimingReview: options.resolveMediaTimingReview,
     getAnkiConnectStatus: options.getAnkiConnectStatus,
     getRuntimeOptions: options.getRuntimeOptions,
     setRuntimeOption: options.setRuntimeOption,
@@ -530,7 +443,13 @@ export function registerIpcHandlers(deps: IpcServiceDeps, ipc: IpcMainRegistrar
       const senderWindow =
         electron.BrowserWindow?.fromWebContents((event as IpcMainEvent).sender) ?? null;
       if (senderWindow && !senderWindow.isDestroyed()) {
-        senderWindow.setIgnoreMouseEvents(ignore, parsedOptions);
+        // Route forwarding requests through the platform-aware helper so Windows never
+        // installs Electron's global mouse hook (see overlay-click-through.ts).
+        if (ignore && parsedOptions?.forward) {
+          applyOverlayClickThrough(senderWindow);
+        } else {
+          senderWindow.setIgnoreMouseEvents(ignore, parsedOptions);
+        }
       }
       deps.onOverlayMouseInteractionChanged?.(!ignore, senderWindow);
     },
@@ -579,46 +498,6 @@ export function registerIpcHandlers(deps: IpcServiceDeps, ipc: IpcMainRegistrar
     },
   );
 
-  ipc.handle(
-    IPC_CHANNELS.request.mediaTimingReviewPreview,
-    async (_event: unknown, payload: unknown) => {
-      const request = parseMediaTimingReviewPreviewRequest(payload);
-      if (!request || !deps.previewMediaTimingReview) {
-        return { ok: false, message: 'Timing preview is unavailable.' };
-      }
-      return await deps.previewMediaTimingReview(request);
-    },
-  );
-  ipc.handle(
-    IPC_CHANNELS.request.mediaTimingReviewWaveform,
-    async (_event: unknown, payload: unknown) => {
-      const request = parseMediaTimingReviewWaveformRequest(payload);
-      if (!request || !deps.getMediaTimingReviewWaveform) {
-        return { ok: false, message: 'Timing waveform is unavailable.' };
-      }
-      return await deps.getMediaTimingReviewWaveform(request);
-    },
-  );
-  ipc.handle(
-    IPC_CHANNELS.request.mediaTimingReviewStopPreview,
-    async (_event: unknown, reviewId: unknown) => {
-      if (typeof reviewId !== 'string' || !reviewId || !deps.stopMediaTimingReviewPreview) {
-        return { ok: false, message: 'Timing preview is unavailable.' };
-      }
-      return await deps.stopMediaTimingReviewPreview(reviewId);
-    },
-  );
-  ipc.handle(
-    IPC_CHANNELS.request.mediaTimingReviewResolve,
-    async (_event: unknown, payload: unknown) => {
-      const request = parseMediaTimingReviewResolveRequest(payload);
-      if (!request || !deps.resolveMediaTimingReview) {
-        return { ok: false, message: 'Timing review is unavailable.' };
-      }
-      return await deps.resolveMediaTimingReview(request);
-    },
-  );
-
   ipc.on(IPC_CHANNELS.command.openYomitanSettings, () => {
     deps.openYomitanSettings();
   });

src/core/services/media-timing-preview.test.ts

@@ -1,191 +0,0 @@
-import assert from 'node:assert/strict';
-import { EventEmitter } from 'node:events';
-import net from 'node:net';
-import { describe, test } from 'node:test';
-import { buildMediaTimingPreviewArgs, MediaTimingPreviewSession } from './media-timing-preview';
-
-describe('buildMediaTimingPreviewArgs', () => {
-  test('creates a hidden audio-only reusable mpv session', () => {
-    const args = buildMediaTimingPreviewArgs('/tmp/review.sock', {
-      mediaPath: '/video/show.mkv',
-      audioTrackId: 3,
-      volume: 55,
-    });
-
-    assert.ok(args.includes('--no-video'));
-    assert.ok(args.includes('--force-window=no'));
-    assert.ok(args.includes('--idle=yes'));
-    assert.ok(args.includes('--pause=yes'));
-    assert.ok(args.includes('--input-ipc-server=/tmp/review.sock'));
-    assert.ok(args.includes('--aid=3'));
-    assert.ok(args.includes('--volume=55'));
-    assert.equal(args.at(-2), '--');
-    assert.equal(args.at(-1), '/video/show.mkv');
-  });
-
-  test('separates an option-like media path without adding optional audio arguments', () => {
-    const args = buildMediaTimingPreviewArgs('/tmp/review.sock', {
-      mediaPath: '--fullscreen',
-    });
-
-    assert.equal(args.at(-2), '--');
-    assert.equal(args.at(-1), '--fullscreen');
-    assert.equal(
-      args.some((arg) => arg.startsWith('--aid=')),
-      false,
-    );
-    assert.equal(
-      args.some((arg) => arg.startsWith('--volume=')),
-      false,
-    );
-  });
-});
-
-test('preview session handles socket errors after connecting', async () => {
-  const socket = new net.Socket();
-  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
-  child.kill = () => true;
-  const session = new MediaTimingPreviewSession({
-    platform: 'linux',
-    spawnProcess: () => child as never,
-    connectSocket: () => {
-      queueMicrotask(() => socket.emit('connect'));
-      return socket;
-    },
-    removeSocketFile: () => undefined,
-    createSocketPath: () => '/tmp/review.sock',
-  });
-
-  await session.start({ mediaPath: '/video/show.mkv' });
-  assert.doesNotThrow(() => socket.emit('error', new Error('pipe closed')));
-  await assert.rejects(session.play(1, 2), /not ready/);
-  session.dispose();
-});
-
-test('preview session keeps failed connection errors handled through destruction', async () => {
-  const socket = new EventEmitter() as EventEmitter & {
-    destroy: () => void;
-  };
-  socket.destroy = () => {
-    socket.emit('error', new Error('socket failed again while closing'));
-  };
-  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
-  child.kill = () => true;
-  const times = [0, 0, 0, 6_000];
-  const session = new MediaTimingPreviewSession({
-    platform: 'linux',
-    spawnProcess: () => child as never,
-    connectSocket: () => {
-      queueMicrotask(() => socket.emit('error', new Error('connection failed')));
-      return socket as never;
-    },
-    now: () => times.shift() ?? 6_000,
-    removeSocketFile: () => undefined,
-    createSocketPath: () => '/tmp/review.sock',
-  });
-
-  await assert.rejects(session.start({ mediaPath: '/video/show.mkv' }), /Timed out starting/);
-});
-
-test('preview session rejects a connection that finishes after disposal', async () => {
-  const socket = new net.Socket();
-  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
-  child.kill = () => true;
-  const session = new MediaTimingPreviewSession({
-    platform: 'linux',
-    spawnProcess: () => child as never,
-    connectSocket: () => socket,
-    removeSocketFile: () => undefined,
-    createSocketPath: () => '/tmp/review.sock',
-  });
-
-  const pendingStart = session.start({ mediaPath: '-playlist' });
-  session.dispose();
-  socket.emit('connect');
-
-  await assert.rejects(pendingStart, /closed/);
-  assert.equal(socket.destroyed, true);
-});
-
-test('preview session shares one startup across concurrent start calls', async () => {
-  const socket = new net.Socket();
-  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
-  child.kill = () => true;
-  let spawnCount = 0;
-  const session = new MediaTimingPreviewSession({
-    platform: 'linux',
-    spawnProcess: () => {
-      spawnCount += 1;
-      return child as never;
-    },
-    connectSocket: () => socket,
-    removeSocketFile: () => undefined,
-    createSocketPath: () => '/tmp/review.sock',
-  });
-
-  const firstStart = session.start({ mediaPath: '/video/show.mkv' });
-  const secondStart = session.start({ mediaPath: '/video/show.mkv' });
-  socket.emit('connect');
-
-  await Promise.all([firstStart, secondStart]);
-  assert.equal(spawnCount, 1);
-  session.dispose();
-});
-
-test('preview session can start again after a startup failure', async () => {
-  const socket = new net.Socket();
-  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
-  child.kill = () => true;
-  let spawnCount = 0;
-  const session = new MediaTimingPreviewSession({
-    platform: 'linux',
-    spawnProcess: () => {
-      spawnCount += 1;
-      if (spawnCount === 1) throw new Error('spawn failed');
-      return child as never;
-    },
-    connectSocket: () => {
-      queueMicrotask(() => socket.emit('connect'));
-      return socket;
-    },
-    removeSocketFile: () => undefined,
-    createSocketPath: () => '/tmp/review.sock',
-  });
-
-  await assert.rejects(session.start({ mediaPath: '/video/show.mkv' }), /spawn failed/);
-  await session.start({ mediaPath: '/video/show.mkv' });
-  assert.equal(spawnCount, 2);
-  session.dispose();
-});
-
-test('preview session bounds a connection attempt that never settles', async () => {
-  const child = new EventEmitter() as EventEmitter & { kill: () => boolean };
-  child.kill = () => true;
-  let nowMs = 0;
-  let connectAttempts = 0;
-  const session = new MediaTimingPreviewSession({
-    platform: 'linux',
-    spawnProcess: () => child as never,
-    connectSocket: () => {
-      connectAttempts += 1;
-      const socket = new net.Socket();
-      socket.destroy = (() => {
-        socket.emit('error', new Error('socket failed while timing out'));
-        return socket;
-      }) as typeof socket.destroy;
-      return socket;
-    },
-    now: () => {
-      const current = nowMs;
-      nowMs += 1_000;
-      return current;
-    },
-    schedule: (callback) => setTimeout(callback, 0),
-    cancelSchedule: (timeout) => clearTimeout(timeout),
-    removeSocketFile: () => undefined,
-    createSocketPath: () => '/tmp/review.sock',
-  });
-
-  await assert.rejects(session.start({ mediaPath: '/video/show.mkv' }), /Timed out starting/);
-  assert.equal(connectAttempts, 1);
-});

src/core/services/media-timing-preview.ts

@@ -1,311 +0,0 @@
-import { spawn, type ChildProcess } from 'child_process';
-import fs from 'fs';
-import net, { type Socket } from 'net';
-import os from 'os';
-import path from 'path';
-import { randomUUID } from 'crypto';
-
-const CONNECT_TIMEOUT_MS = 5_000;
-const CONNECT_ATTEMPT_TIMEOUT_MS = 500;
-const CONNECT_RETRY_MS = 40;
-
-export interface MediaTimingPreviewStartOptions {
-  mediaPath: string;
-  executablePath?: string;
-  audioTrackId?: number;
-  volume?: number;
-}
-
-type PreviewProcess = Pick<ChildProcess, 'kill' | 'once'>;
-
-interface MediaTimingPreviewDeps {
-  platform: NodeJS.Platform;
-  spawnProcess: (command: string, args: string[]) => PreviewProcess;
-  connectSocket: (socketPath: string) => Socket;
-  now: () => number;
-  schedule: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
-  cancelSchedule: (timeout: ReturnType<typeof setTimeout>) => void;
-  removeSocketFile: (socketPath: string) => void;
-  createSocketPath: () => string;
-}
-
-export function buildMediaTimingPreviewArgs(
-  socketPath: string,
-  options: MediaTimingPreviewStartOptions,
-): string[] {
-  const args = [
-    '--no-config',
-    '--no-video',
-    '--audio-display=no',
-    '--force-window=no',
-    '--idle=yes',
-    '--keep-open=yes',
-    '--pause=yes',
-    '--terminal=no',
-    '--msg-level=all=warn',
-    `--input-ipc-server=${socketPath}`,
-  ];
-  if (typeof options.audioTrackId === 'number' && Number.isInteger(options.audioTrackId)) {
-    args.push(`--aid=${options.audioTrackId}`);
-  }
-  if (typeof options.volume === 'number' && Number.isFinite(options.volume)) {
-    args.push(`--volume=${Math.max(0, options.volume)}`);
-  }
-  args.push('--', options.mediaPath);
-  return args;
-}
-
-function createDefaultSocketPath(): string {
-  const suffix = `${process.pid}-${randomUUID()}`;
-  return process.platform === 'win32'
-    ? `\\\\.\\pipe\\subminer-timing-preview-${suffix}`
-    : path.join(os.tmpdir(), `subminer-timing-preview-${suffix}.sock`);
-}
-
-function removePosixSocketFile(socketPath: string): void {
-  if (process.platform === 'win32') return;
-  try {
-    fs.unlinkSync(socketPath);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
-      throw error;
-    }
-  }
-}
-
-export class MediaTimingPreviewSession {
-  private readonly deps: MediaTimingPreviewDeps;
-  private socketPath: string | null = null;
-  private socket: Socket | null = null;
-  private process: PreviewProcess | null = null;
-  private startupError: Error | null = null;
-  private startPromise: Promise<void> | null = null;
-  private retryWait: {
-    timeout: ReturnType<typeof setTimeout>;
-    resolve: () => void;
-  } | null = null;
-  private disposed = false;
-
-  constructor(deps: Partial<MediaTimingPreviewDeps> = {}) {
-    this.deps = {
-      platform: process.platform,
-      spawnProcess: (command, args) => spawn(command, args, { stdio: 'ignore' }),
-      connectSocket: (socketPath) => net.createConnection(socketPath),
-      now: Date.now,
-      schedule: (callback, delayMs) => setTimeout(callback, delayMs),
-      cancelSchedule: (timeout) => clearTimeout(timeout),
-      removeSocketFile: removePosixSocketFile,
-      createSocketPath: createDefaultSocketPath,
-      ...deps,
-    };
-  }
-
-  async start(options: MediaTimingPreviewStartOptions): Promise<void> {
-    if (this.disposed) throw new Error('Preview session is closed');
-    if (this.socket) return;
-    if (this.startPromise) return await this.startPromise;
-
-    const startPromise = this.startOnce(options);
-    this.startPromise = startPromise;
-    try {
-      await startPromise;
-    } catch (error) {
-      this.releaseResources();
-      throw error;
-    } finally {
-      if (this.startPromise === startPromise) this.startPromise = null;
-    }
-  }
-
-  private async startOnce(options: MediaTimingPreviewStartOptions): Promise<void> {
-    const mediaPath = options.mediaPath.trim();
-    if (!mediaPath) throw new Error('No media source is available for preview');
-
-    const socketPath = this.deps.createSocketPath();
-    this.socketPath = socketPath;
-    if (this.deps.platform !== 'win32') {
-      this.deps.removeSocketFile(socketPath);
-    }
-
-    const command = options.executablePath?.trim() || 'mpv';
-    this.startupError = null;
-    const child = this.deps.spawnProcess(
-      command,
-      buildMediaTimingPreviewArgs(socketPath, { ...options, mediaPath }),
-    );
-    this.process = child;
-    child.once('error', (error) => {
-      if (this.process !== child) return;
-      this.startupError = error;
-    });
-    child.once('exit', () => {
-      if (this.process !== child) return;
-      if (!this.socket && !this.disposed && !this.startupError) {
-        this.startupError = new Error('The hidden mpv preview player exited during startup');
-      }
-      this.socket?.destroy();
-      this.socket = null;
-      this.process = null;
-    });
-
-    await this.connectWithRetry(socketPath);
-  }
-
-  async play(startTime: number, endTime: number): Promise<void> {
-    if (!this.socket || this.socket.destroyed) {
-      throw new Error('Preview player is not ready');
-    }
-    if (!Number.isFinite(startTime) || !Number.isFinite(endTime) || endTime <= startTime) {
-      throw new Error('Preview timing is invalid');
-    }
-
-    this.send(['set_property', 'pause', true]);
-    this.send(['set_property', 'ab-loop-a', startTime]);
-    this.send(['set_property', 'ab-loop-b', endTime]);
-    this.send(['seek', startTime, 'absolute+exact']);
-    this.send(['set_property', 'pause', false]);
-  }
-
-  async stop(): Promise<void> {
-    if (!this.socket || this.socket.destroyed) return;
-    this.send(['set_property', 'pause', true]);
-  }
-
-  dispose(): void {
-    if (this.disposed) return;
-    this.disposed = true;
-    this.releaseResources();
-  }
-
-  private releaseResources(): void {
-    this.cancelRetryWait();
-    try {
-      this.send(['quit']);
-    } catch {
-      // The process may already have exited.
-    }
-    this.socket?.end();
-    this.socket?.destroy();
-    this.socket = null;
-    const child = this.process;
-    this.process = null;
-    child?.kill();
-    if (this.socketPath && this.deps.platform !== 'win32') {
-      try {
-        this.deps.removeSocketFile(this.socketPath);
-      } catch {
-        // mpv may still be releasing the socket. The OS temp directory owns cleanup.
-      }
-    }
-    this.socketPath = null;
-  }
-
-  private send(command: Array<string | number | boolean>): void {
-    if (!this.socket || this.socket.destroyed) {
-      throw new Error('Preview player is not connected');
-    }
-    this.socket.write(`${JSON.stringify({ command })}\n`);
-  }
-
-  private async connectWithRetry(socketPath: string): Promise<void> {
-    const deadline = this.deps.now() + CONNECT_TIMEOUT_MS;
-    while (!this.disposed && this.deps.now() < deadline) {
-      if (this.startupError) {
-        throw this.startupError;
-      }
-      try {
-        const remainingMs = deadline - this.deps.now();
-        if (remainingMs <= 0) break;
-        const socket = await this.connectOnce(
-          socketPath,
-          Math.min(CONNECT_ATTEMPT_TIMEOUT_MS, remainingMs),
-        );
-        if (this.disposed) {
-          socket.destroy();
-          throw new Error('Preview session is closed');
-        }
-        this.socket = socket;
-        return;
-      } catch {
-        if (this.disposed) {
-          throw new Error('Preview session is closed');
-        }
-        const remainingMs = deadline - this.deps.now();
-        if (remainingMs <= 0) break;
-        await this.waitForRetry(Math.min(CONNECT_RETRY_MS, remainingMs));
-      }
-    }
-    if (this.startupError) {
-      throw this.startupError;
-    }
-    if (this.disposed) {
-      throw new Error('Preview session is closed');
-    }
-    throw new Error('Timed out starting the hidden mpv preview player');
-  }
-
-  private waitForRetry(delayMs: number): Promise<void> {
-    return new Promise<void>((resolve) => {
-      const timeout = this.deps.schedule(() => {
-        if (this.retryWait?.timeout === timeout) this.retryWait = null;
-        resolve();
-      }, delayMs);
-      this.retryWait = { timeout, resolve };
-    });
-  }
-
-  private cancelRetryWait(): void {
-    const pending = this.retryWait;
-    this.retryWait = null;
-    if (!pending) return;
-    this.deps.cancelSchedule(pending.timeout);
-    pending.resolve();
-  }
-
-  private connectOnce(socketPath: string, timeoutMs: number): Promise<Socket> {
-    return new Promise<Socket>((resolve, reject) => {
-      let timeout: ReturnType<typeof setTimeout> | null = null;
-      let settled = false;
-      const clearAttemptTimeout = (): void => {
-        if (timeout !== null) this.deps.cancelSchedule(timeout);
-        timeout = null;
-      };
-      const socket = this.deps.connectSocket(socketPath);
-      const onConnect = (): void => {
-        if (settled) return;
-        settled = true;
-        clearAttemptTimeout();
-        socket.off('error', onError);
-        socket.on('error', () => {
-          socket.destroy();
-          if (this.socket === socket) this.socket = null;
-        });
-        socket.once('close', () => {
-          if (this.socket === socket) this.socket = null;
-        });
-        resolve(socket);
-      };
-      const onError = (error: Error): void => {
-        if (settled) return;
-        settled = true;
-        clearAttemptTimeout();
-        socket.off('connect', onConnect);
-        socket.on('error', () => {});
-        socket.destroy();
-        reject(error);
-      };
-      socket.once('connect', onConnect);
-      socket.once('error', onError);
-      timeout = this.deps.schedule(() => {
-        if (settled) return;
-        settled = true;
-        timeout = null;
-        socket.off('connect', onConnect);
-        socket.off('error', onError);
-        socket.on('error', () => {});
-        socket.destroy();
-        reject(new Error('Timed out connecting to the hidden mpv preview player'));
-      }, timeoutMs);
-    });
-  }
-}

src/core/services/media-timing-waveform.test.ts

@@ -1,74 +0,0 @@
-import assert from 'node:assert/strict';
-import test from 'node:test';
-import {
-  buildSpeechWaveformArgs,
-  computeWaveformPeaks,
-  generateSpeechWaveform,
-} from './media-timing-waveform';
-
-function pcm(samples: number[]): Buffer {
-  const result = Buffer.alloc(samples.length * 2);
-  samples.forEach((sample, index) => result.writeInt16LE(sample, index * 2));
-  return result;
-}
-
-test('speech waveform maps the selected FFmpeg stream and visible range', () => {
-  const args = buildSpeechWaveformArgs(
-    {
-      mediaPath: '/video/show.mkv',
-      startTime: 8,
-      endTime: 15,
-      audioStreamIndex: 3,
-    },
-    'center',
-  );
-
-  assert.deepEqual(args.slice(args.indexOf('-ss'), args.indexOf('-t') + 2), [
-    '-ss',
-    '8',
-    '-i',
-    '/video/show.mkv',
-    '-t',
-    '7',
-  ]);
-  assert.deepEqual(args.slice(args.indexOf('-map'), args.indexOf('-map') + 2), ['-map', '0:3']);
-  assert.match(args[args.indexOf('-af') + 1] ?? '', /c0=FC/);
-});
-
-test('waveform peaks are normalized without flattening quieter sections', () => {
-  const peaks = computeWaveformPeaks(pcm([0, 1_000, -2_000, 4_000, -8_000, 16_000]), 3);
-
-  assert.equal(peaks.length, 3);
-  assert.ok((peaks[0] ?? 0) > 0);
-  assert.ok((peaks[0] ?? 0) < (peaks[1] ?? 0));
-  assert.ok((peaks[1] ?? 0) < (peaks[2] ?? 0));
-  assert.equal(peaks[2], 1);
-});
-
-test('speech waveform uses a mono downmix when the source has no center activity', async () => {
-  const calls: string[][] = [];
-  const peaks = await generateSpeechWaveform(
-    { mediaPath: '/video/show.mkv', startTime: 0, endTime: 2 },
-    async (args) => {
-      calls.push(args);
-      return calls.length === 1 ? pcm([0, 0, 0, 0]) : pcm([0, 4_000, -8_000, 16_000]);
-    },
-  );
-
-  assert.equal(calls.length, 2);
-  assert.match(calls[1]?.[calls[1].indexOf('-af') + 1] ?? '', /channel_layouts=mono/);
-  assert.equal(Math.max(...peaks), 1);
-});
-
-test('speech waveform keeps an active center channel without doing a second decode', async () => {
-  let calls = 0;
-  await generateSpeechWaveform(
-    { mediaPath: '/video/show.mkv', startTime: 0, endTime: 2 },
-    async () => {
-      calls += 1;
-      return pcm([0, 4_000, -8_000, 16_000]);
-    },
-  );
-
-  assert.equal(calls, 1);
-});

src/core/services/media-timing-waveform.ts

@@ -1,158 +0,0 @@
-import { spawn } from 'node:child_process';
-
-const WAVEFORM_SAMPLE_RATE = 8_000;
-const WAVEFORM_POINT_COUNT = 480;
-const WAVEFORM_TIMEOUT_MS = 15_000;
-const MAX_WAVEFORM_BYTES = 16 * 1024 * 1024;
-const SPEECH_FILTER = 'highpass=f=120,lowpass=f=4000';
-const CENTER_CHANNEL_FILTER = `pan=mono|c0=FC,${SPEECH_FILTER}`;
-const DOWNMIX_FILTER = `aformat=channel_layouts=mono,${SPEECH_FILTER}`;
-
-export interface SpeechWaveformOptions {
-  mediaPath: string;
-  startTime: number;
-  endTime: number;
-  audioStreamIndex?: number;
-}
-
-type RunFfmpeg = (args: string[]) => Promise<Buffer>;
-
-export function buildSpeechWaveformArgs(
-  options: SpeechWaveformOptions,
-  mode: 'center' | 'downmix',
-): string[] {
-  const duration = options.endTime - options.startTime;
-  const args = [
-    '-hide_banner',
-    '-nostdin',
-    '-loglevel',
-    'error',
-    '-ss',
-    String(options.startTime),
-    '-i',
-    options.mediaPath,
-    '-t',
-    String(duration),
-  ];
-  if (
-    options.audioStreamIndex !== undefined &&
-    Number.isInteger(options.audioStreamIndex) &&
-    options.audioStreamIndex >= 0
-  ) {
-    args.push('-map', `0:${options.audioStreamIndex}`);
-  }
-  args.push(
-    '-vn',
-    '-sn',
-    '-dn',
-    '-af',
-    mode === 'center' ? CENTER_CHANNEL_FILTER : DOWNMIX_FILTER,
-    '-ac',
-    '1',
-    '-ar',
-    String(WAVEFORM_SAMPLE_RATE),
-    '-f',
-    's16le',
-    'pipe:1',
-  );
-  return args;
-}
-
-function runFfmpeg(args: string[]): Promise<Buffer> {
-  return new Promise((resolve, reject) => {
-    const child = spawn('ffmpeg', args, { stdio: ['ignore', 'pipe', 'pipe'] });
-    const chunks: Buffer[] = [];
-    let byteLength = 0;
-    let stderr = '';
-    let settled = false;
-    const timeout = setTimeout(() => {
-      if (settled) return;
-      settled = true;
-      child.kill('SIGKILL');
-      reject(new Error(`FFmpeg waveform analysis timed out after ${WAVEFORM_TIMEOUT_MS}ms`));
-    }, WAVEFORM_TIMEOUT_MS);
-
-    const settle = (callback: () => void): void => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeout);
-      callback();
-    };
-
-    child.stdout.on('data', (chunk: Buffer) => {
-      if (settled) return;
-      byteLength += chunk.byteLength;
-      if (byteLength > MAX_WAVEFORM_BYTES) {
-        settle(() => {
-          child.kill('SIGKILL');
-          reject(new Error('The visible waveform range is too large to analyze.'));
-        });
-        return;
-      }
-      chunks.push(chunk);
-    });
-    child.stderr.setEncoding('utf8');
-    child.stderr.on('data', (chunk) => {
-      if (stderr.length < 4_000) stderr += String(chunk);
-    });
-    child.once('error', (error) => settle(() => reject(error)));
-    child.once('close', (code) => {
-      settle(() => {
-        if (code === 0) {
-          resolve(Buffer.concat(chunks, byteLength));
-          return;
-        }
-        reject(new Error(stderr.trim() || `FFmpeg exited with status ${code ?? 'unknown'}`));
-      });
-    });
-  });
-}
-
-export function computeWaveformPeaks(pcm: Buffer, pointCount = WAVEFORM_POINT_COUNT): number[] {
-  const sampleCount = Math.floor(pcm.byteLength / 2);
-  if (sampleCount === 0 || pointCount <= 0) return [];
-  const resolvedPointCount = Math.min(pointCount, sampleCount);
-  const peaks = Array.from({ length: resolvedPointCount }, () => 0);
-
-  for (let point = 0; point < resolvedPointCount; point += 1) {
-    const sampleStart = Math.floor((point * sampleCount) / resolvedPointCount);
-    const sampleEnd = Math.max(
-      sampleStart + 1,
-      Math.floor(((point + 1) * sampleCount) / resolvedPointCount),
-    );
-    let peak = 0;
-    for (let sample = sampleStart; sample < sampleEnd; sample += 1) {
-      peak = Math.max(peak, Math.abs(pcm.readInt16LE(sample * 2)) / 32_768);
-    }
-    peaks[point] = peak;
-  }
-
-  const sortedPeaks = [...peaks].sort((left, right) => left - right);
-  const referenceIndex = Math.min(sortedPeaks.length - 1, Math.floor(sortedPeaks.length * 0.95));
-  const referencePeak = Math.max(sortedPeaks[referenceIndex] ?? 0, 0.01);
-  return peaks.map(
-    (peak) => Math.round(Math.sqrt(Math.min(1, peak / referencePeak)) * 1_000) / 1_000,
-  );
-}
-
-function hasAudibleSamples(pcm: Buffer): boolean {
-  for (let offset = 0; offset + 1 < pcm.byteLength; offset += 2) {
-    if (Math.abs(pcm.readInt16LE(offset)) >= 164) return true;
-  }
-  return false;
-}
-
-export async function generateSpeechWaveform(
-  options: SpeechWaveformOptions,
-  execute: RunFfmpeg = runFfmpeg,
-): Promise<number[]> {
-  try {
-    const centerPcm = await execute(buildSpeechWaveformArgs(options, 'center'));
-    if (hasAudibleSamples(centerPcm)) return computeWaveformPeaks(centerPcm);
-  } catch {
-    // Sources without a named center channel can reject the center-only filter.
-  }
-
-  const downmixPcm = await execute(buildSpeechWaveformArgs(options, 'downmix'));
-  return computeWaveformPeaks(downmixPcm);
-}

src/core/services/mining.test.ts

@@ -125,6 +125,49 @@ test('mineSentenceCard creates sentence card from mpv subtitle state', async ()
   ]);
 });
 
+test('mineSentenceCard prefers a canonical primary subtitle snapshot', async () => {
+  const created: Array<{
+    sentence: string;
+    startTime: number;
+    endTime: number;
+    secondarySub?: string;
+  }> = [];
+
+  await mineSentenceCard({
+    ankiIntegration: {
+      updateLastAddedFromClipboard: async () => {},
+      triggerFieldGroupingForLastAddedCard: async () => {},
+      markLastCardAsAudioCard: async () => {},
+      createSentenceCard: async (sentence, startTime, endTime, secondarySub) => {
+        created.push({ sentence, startTime, endTime, secondarySub });
+        return true;
+      },
+    },
+    mpvClient: {
+      connected: true,
+      currentSubText: '今今今手手手',
+      currentSubStart: 11.4,
+      currentSubEnd: 11.8,
+      currentSecondarySubText: 'English subtitle',
+    },
+    primarySubtitle: {
+      text: '今　手にある物差しでは',
+      startTime: 11.13,
+      endTime: 13.83,
+    },
+    showMpvOsd: () => {},
+  });
+
+  assert.deepEqual(created, [
+    {
+      sentence: '今　手にある物差しでは',
+      startTime: 11.13,
+      endTime: 13.83,
+      secondarySub: 'English subtitle',
+    },
+  ]);
+});
+
 test('mineSentenceCard refreshes secondary subtitle text before creating card', async () => {
   const created: Array<{ sentence: string; secondarySub?: string }> = [];
   const requestedProperties: string[] = [];

src/core/services/mining.ts

@@ -131,8 +131,8 @@ function normalizeSecondarySubText(text: unknown, primaryText: string): string |
 
 async function getCurrentSecondarySubTextForSentenceCard(
   mpvClient: MpvClientLike,
+  primaryText: string,
 ): Promise<string | undefined> {
-  const primaryText = mpvClient.currentSubText;
   if (mpvClient.requestProperty) {
     try {
       const latestSecondaryText = await mpvClient.requestProperty('secondary-sub-text');
@@ -175,6 +175,7 @@ export async function markLastCardAsAudioCard(deps: {
 export async function mineSentenceCard(deps: {
   ankiIntegration: AnkiIntegrationLike | null;
   mpvClient: MpvClientLike | null;
+  primarySubtitle?: Pick<SubtitleMiningContext, 'text' | 'startTime' | 'endTime'>;
   showMpvOsd: (text: string) => void;
 }): Promise<boolean> {
   const anki = requireAnkiIntegration(deps.ankiIntegration, deps.showMpvOsd);
@@ -185,16 +186,17 @@ export async function mineSentenceCard(deps: {
     deps.showMpvOsd('MPV not connected');
     return false;
   }
-  if (!mpvClient.currentSubText) {
+  const primaryText = deps.primarySubtitle?.text ?? mpvClient.currentSubText;
+  if (!primaryText) {
     deps.showMpvOsd('No current subtitle');
     return false;
   }
 
-  const secondarySubText = await getCurrentSecondarySubTextForSentenceCard(mpvClient);
+  const secondarySubText = await getCurrentSecondarySubTextForSentenceCard(mpvClient, primaryText);
   return await anki.createSentenceCard(
-    mpvClient.currentSubText,
-    mpvClient.currentSubStart,
-    mpvClient.currentSubEnd,
+    primaryText,
+    deps.primarySubtitle?.startTime ?? mpvClient.currentSubStart,
+    deps.primarySubtitle?.endTime ?? mpvClient.currentSubEnd,
     secondarySubText,
   );
 }

src/core/services/mpv-properties.ts

@@ -53,7 +53,7 @@ const MPV_SUBTITLE_PROPERTY_OBSERVATIONS: string[] = [
   'sub-scale-by-window',
   'osd-height',
   'osd-dimensions',
-  'sub-text-ass',
+  'sub-text/ass',
   'sub-border-size',
   'sub-shadow-offset',
   'sub-ass-override',
@@ -74,7 +74,7 @@ const MPV_INITIAL_PROPERTY_REQUESTS: Array<MpvProtocolCommand> = [
     request_id: MPV_REQUEST_ID_SUBTEXT,
   },
   {
-    command: ['get_property', 'sub-text-ass'],
+    command: ['get_property', 'sub-text/ass'],
     request_id: MPV_REQUEST_ID_SUBTEXT_ASS,
   },
   {

src/core/services/mpv-protocol.test.ts

@@ -129,6 +129,28 @@ test('dispatchMpvProtocolMessage emits subtitle text on property change', async
   assert.deepEqual(state.events, [{ text: '字幕', isOverlayVisible: false }]);
 });
 
+test('dispatchMpvProtocolMessage emits ASS subtitle text from the current mpv property', async () => {
+  const { deps, state } = createDeps();
+
+  await dispatchMpvProtocolMessage(
+    { event: 'property-change', name: 'sub-text/ass', data: '{\\b1}字幕' },
+    deps,
+  );
+
+  assert.deepEqual(state.events, [{ text: '{\\b1}字幕' }]);
+});
+
+test('dispatchMpvProtocolMessage emits ASS subtitle text from the legacy mpv property', async () => {
+  const { deps, state } = createDeps();
+
+  await dispatchMpvProtocolMessage(
+    { event: 'property-change', name: 'sub-text-ass', data: '{\\b1}字幕' },
+    deps,
+  );
+
+  assert.deepEqual(state.events, [{ text: '{\\b1}字幕' }]);
+});
+
 test('dispatchMpvProtocolMessage emits subtitle track changes', async () => {
   const { deps, state } = createDeps({
     emitSubtitleTrackChange: (payload) => state.events.push(payload),

src/core/services/mpv-protocol.ts

@@ -248,7 +248,7 @@ export async function dispatchMpvProtocolMessage(
         isOverlayVisible: overlayVisible,
       });
       deps.setCurrentSubText(nextSubText);
-    } else if (msg.name === 'sub-text-ass') {
+    } else if (msg.name === 'sub-text/ass' || msg.name === 'sub-text-ass') {
       deps.emitSubtitleAssChange({ text: (msg.data as string) || '' });
     } else if (msg.name === 'sub-start') {
       deps.setCurrentSubStart((msg.data as number) || 0);

src/core/services/mpv-transport.test.ts

@@ -38,7 +38,15 @@ class ManualCloseSocket extends FakeSocket {
   }
 }
 
-const wait = () => new Promise((resolve) => setTimeout(resolve, 0));
+class HangingSocket extends FakeSocket {
+  override connect(path: string): void {
+    this.connectedPaths.push(path);
+    // Never emits 'connect', 'error', or 'close' on its own: models a named
+    // pipe dial that stalls indefinitely.
+  }
+}
+
+const wait = (ms = 0) => new Promise((resolve) => setTimeout(resolve, ms));
 
 test('getMpvReconnectDelay follows existing reconnect ramp', () => {
   assert.equal(getMpvReconnectDelay(0, true), 1000);
@@ -232,6 +240,75 @@ test('MpvSocketTransport.shutdown clears socket and lifecycle flags', async () =
   assert.deepEqual(events, []);
 });
 
+test('MpvSocketTransport aborts a hung connect after the timeout and allows a fresh dial', async () => {
+  const events: string[] = [];
+  const errors: Error[] = [];
+  const sockets: HangingSocket[] = [];
+  const transport = new MpvSocketTransport({
+    socketPath: '/tmp/mpv.sock',
+    connectTimeoutMs: 5,
+    onConnect: () => {
+      events.push('connect');
+    },
+    onData: () => {},
+    onError: (error) => {
+      events.push('error');
+      errors.push(error);
+    },
+    onClose: () => {
+      events.push('close');
+    },
+    socketFactory: () => {
+      const socket = new HangingSocket();
+      sockets.push(socket);
+      return socket as unknown as net.Socket;
+    },
+  });
+
+  transport.connect();
+  assert.equal(transport.isConnecting, true);
+
+  await wait(20);
+
+  assert.deepEqual(events, ['error', 'close']);
+  assert.match(errors[0]!.message, /connect timed out/);
+  assert.equal(sockets[0]!.destroyed, true);
+  assert.equal(transport.isConnecting, false);
+  assert.equal(transport.isConnected, false);
+
+  transport.connect();
+  assert.equal(transport.isConnecting, true);
+  assert.equal(sockets.length, 2);
+  assert.equal(sockets[1]!.connectedPaths.at(0), '/tmp/mpv.sock');
+
+  transport.shutdown();
+});
+
+test('MpvSocketTransport does not fire the connect timeout after a successful connect', async () => {
+  const events: string[] = [];
+  const transport = new MpvSocketTransport({
+    socketPath: '/tmp/mpv.sock',
+    connectTimeoutMs: 5,
+    onConnect: () => {
+      events.push('connect');
+    },
+    onData: () => {},
+    onError: () => {
+      events.push('error');
+    },
+    onClose: () => {
+      events.push('close');
+    },
+    socketFactory: () => new FakeSocket() as unknown as net.Socket,
+  });
+
+  transport.connect();
+  await wait(20);
+
+  assert.deepEqual(events, ['connect']);
+  assert.equal(transport.isConnected, true);
+});
+
 test('MpvSocketTransport ignores stale socket events after shutdown and reconnect', async () => {
   const events: string[] = [];
   const sockets: ManualCloseSocket[] = [];

src/core/services/mpv-transport.ts

@@ -62,6 +62,8 @@ interface MpvSocketTransportEvents {
   onClose: () => void;
 }
 
+export const MPV_CONNECT_TIMEOUT_MS = 5000;
+
 export interface MpvSocketTransportOptions {
   socketPath: string;
   onConnect: () => void;
@@ -69,13 +71,16 @@ export interface MpvSocketTransportOptions {
   onError: (error: Error) => void;
   onClose: () => void;
   socketFactory?: () => net.Socket;
+  connectTimeoutMs?: number;
 }
 
 export class MpvSocketTransport {
   private socketPath: string;
   private readonly callbacks: MpvSocketTransportEvents;
   private readonly socketFactory: () => net.Socket;
+  private readonly connectTimeoutMs: number;
   private socketRef: net.Socket | null = null;
+  private connectTimer: ReturnType<typeof setTimeout> | null = null;
   public socket: net.Socket | null = null;
   public connected = false;
   public connecting = false;
@@ -83,6 +88,7 @@ export class MpvSocketTransport {
   constructor(options: MpvSocketTransportOptions) {
     this.socketPath = options.socketPath;
     this.socketFactory = options.socketFactory ?? (() => new net.Socket());
+    this.connectTimeoutMs = options.connectTimeoutMs ?? MPV_CONNECT_TIMEOUT_MS;
     this.callbacks = {
       onConnect: options.onConnect,
       onData: options.onData,
@@ -91,6 +97,31 @@ export class MpvSocketTransport {
     };
   }
 
+  private clearConnectTimeout(): void {
+    if (this.connectTimer) {
+      clearTimeout(this.connectTimer);
+      this.connectTimer = null;
+    }
+  }
+
+  // A named-pipe/socket dial that neither connects nor errors would otherwise
+  // latch `connecting` forever and silently block every future connect().
+  private armConnectTimeout(socket: net.Socket): void {
+    this.clearConnectTimeout();
+    this.connectTimer = setTimeout(() => {
+      this.connectTimer = null;
+      if (this.socketRef !== socket || this.connected) return;
+      this.connecting = false;
+      this.callbacks.onError(
+        new Error(`MPV IPC connect timed out after ${this.connectTimeoutMs}ms: ${this.socketPath}`),
+      );
+      // Destroying the socket emits 'close', which drives the normal
+      // disconnect path (including reconnect scheduling) upstream.
+      socket.destroy();
+    }, this.connectTimeoutMs);
+    this.connectTimer.unref?.();
+  }
+
   setSocketPath(socketPath: string): void {
     this.socketPath = socketPath;
   }
@@ -111,6 +142,7 @@ export class MpvSocketTransport {
 
     socket.on('connect', () => {
       if (this.socketRef !== socket) return;
+      this.clearConnectTimeout();
       this.connected = true;
       this.connecting = false;
       this.callbacks.onConnect();
@@ -123,6 +155,7 @@ export class MpvSocketTransport {
 
     socket.on('error', (error: Error) => {
       if (this.socketRef !== socket) return;
+      this.clearConnectTimeout();
       this.connected = false;
       this.connecting = false;
       this.callbacks.onError(error);
@@ -130,12 +163,14 @@ export class MpvSocketTransport {
 
     socket.on('close', () => {
       if (this.socketRef !== socket) return;
+      this.clearConnectTimeout();
       this.connected = false;
       this.connecting = false;
       this.callbacks.onClose();
     });
 
     socket.connect(this.socketPath);
+    this.armConnectTimeout(socket);
   }
 
   send(payload: MpvSocketMessagePayload): boolean {
@@ -149,6 +184,7 @@ export class MpvSocketTransport {
   }
 
   shutdown(): void {
+    this.clearConnectTimeout();
     const socket = this.socketRef;
     this.socketRef = null;
     this.socket = null;

src/core/services/mpv.test.ts

@@ -1,5 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
 import {
   MpvIpcClient,
   MpvIpcClientDeps,
@@ -23,6 +24,18 @@ function makeDeps(overrides: Partial<MpvIpcClientProtocolDeps> = {}): MpvIpcClie
   };
 }
 
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function waitFor(predicate: () => boolean, timeoutMs = 2000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() >= deadline) {
+      throw new Error('Timed out waiting for MPV retry connection');
+    }
+    await wait(10);
+  }
+}
+
 function captureWarnLogs(run: () => void): string[] {
   const originalWarn = console.warn;
   const originalLogLevel = process.env.SUBMINER_LOG_LEVEL;
@@ -505,6 +518,17 @@ test('MpvIpcClient reconnect replays property subscriptions and initial state re
       (command as { command: unknown[] }).command[1] === 1 &&
       (command as { command: unknown[] }).command[2] === 'sub-text',
   );
+  const hasAssSubtitleSubscription = commands.some(
+    (command) =>
+      Array.isArray((command as { command: unknown[] }).command) &&
+      (command as { command: unknown[] }).command[0] === 'observe_property' &&
+      (command as { command: unknown[] }).command[2] === 'sub-text/ass',
+  );
+  const hasDeprecatedAssSubtitleProperty = commands.some(
+    (command) =>
+      Array.isArray((command as { command: unknown[] }).command) &&
+      (command as { command: unknown[] }).command.includes('sub-text-ass'),
+  );
   const hasPathRequest = commands.some(
     (command) =>
       Array.isArray((command as { command: unknown[] }).command) &&
@@ -514,6 +538,8 @@ test('MpvIpcClient reconnect replays property subscriptions and initial state re
 
   assert.equal(hasSecondaryVisibilityReset, true);
   assert.equal(hasTrackSubscription, true);
+  assert.equal(hasAssSubtitleSubscription, true);
+  assert.equal(hasDeprecatedAssSubtitleProperty, false);
   assert.equal(hasPathRequest, true);
 });
 
@@ -743,3 +769,117 @@ test('MpvIpcClient playNextSubtitle still auto-pauses at end while already playi
   assert.equal((client as any).pendingPauseAtSubEnd, true);
   assert.deepEqual(commands, [{ command: ['sub-seek', 1] }]);
 });
+
+class HangingTestSocket extends EventEmitter {
+  public connectedPaths: string[] = [];
+  public destroyed = false;
+
+  connect(path: string): void {
+    this.connectedPaths.push(path);
+    // Never resolves: models a stalled named-pipe dial.
+  }
+
+  write(): boolean {
+    return true;
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+  }
+}
+
+class RetryTestSocket extends EventEmitter {
+  public connectedPaths: string[] = [];
+  public destroyed = false;
+
+  constructor(private readonly shouldConnect: boolean) {
+    super();
+  }
+
+  connect(path: string): void {
+    this.connectedPaths.push(path);
+    if (this.shouldConnect) {
+      setTimeout(() => this.emit('connect'), 0);
+    }
+  }
+
+  write(): boolean {
+    return true;
+  }
+
+  destroy(): void {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.emit('close');
+  }
+}
+
+test('MpvIpcClient automatically retries the same socket path after a connect timeout', async () => {
+  const sockets: RetryTestSocket[] = [];
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  const originalLogLevel = process.env.SUBMINER_LOG_LEVEL;
+  const client = new MpvIpcClient(
+    '/tmp/mpv.sock',
+    makeDeps({
+      connectTimeoutMs: 5,
+      getReconnectTimer: () => reconnectTimer,
+      setReconnectTimer: (timer) => {
+        reconnectTimer = timer;
+      },
+      socketFactory: () => {
+        const socket = new RetryTestSocket(sockets.length > 0);
+        sockets.push(socket);
+        return socket as unknown as import('node:net').Socket;
+      },
+    }),
+  );
+
+  process.env.SUBMINER_LOG_LEVEL = 'error';
+  try {
+    client.connect();
+    await waitFor(() => client.connected);
+
+    assert.equal(sockets.length, 2);
+    assert.equal(sockets[0]!.destroyed, true);
+    assert.equal(sockets[0]!.connectedPaths.at(0), '/tmp/mpv.sock');
+    assert.equal(sockets[1]!.connectedPaths.at(0), '/tmp/mpv.sock');
+    assert.equal(client.connected, true);
+  } finally {
+    if (originalLogLevel === undefined) {
+      delete process.env.SUBMINER_LOG_LEVEL;
+    } else {
+      process.env.SUBMINER_LOG_LEVEL = originalLogLevel;
+    }
+    if (reconnectTimer) clearTimeout(reconnectTimer);
+    (client as any).transport.shutdown();
+  }
+});
+
+test('MpvIpcClient.setSocketPath aborts an in-flight connect so the next dial targets the new path', () => {
+  const sockets: HangingTestSocket[] = [];
+  const client = new MpvIpcClient(
+    '/tmp/mpv-old.sock',
+    makeDeps({
+      socketFactory: () => {
+        const socket = new HangingTestSocket();
+        sockets.push(socket);
+        return socket as unknown as import('node:net').Socket;
+      },
+    }),
+  );
+
+  client.connect();
+  assert.equal(sockets.length, 1);
+  assert.equal(sockets[0]!.connectedPaths.at(0), '/tmp/mpv-old.sock');
+  assert.equal((client as any).connecting, true);
+
+  client.setSocketPath('/tmp/mpv-new.sock');
+  assert.equal((client as any).connecting, false);
+  assert.equal(sockets[0]!.destroyed, true);
+
+  client.connect();
+  assert.equal(sockets.length, 2);
+  assert.equal(sockets[1]!.connectedPaths.at(0), '/tmp/mpv-new.sock');
+
+  (client as any).transport.shutdown();
+});

src/core/services/mpv.ts

@@ -9,7 +9,11 @@ import {
   splitMpvMessagesFromBuffer,
 } from './mpv-protocol';
 import { requestMpvInitialState, subscribeToMpvProperties } from './mpv-properties';
-import { scheduleMpvReconnect, MpvSocketTransport } from './mpv-transport';
+import {
+  scheduleMpvReconnect,
+  MpvSocketTransport,
+  MpvSocketTransportOptions,
+} from './mpv-transport';
 import { createLogger } from '../../logger';
 
 const logger = createLogger('main:mpv');
@@ -110,6 +114,8 @@ export interface MpvIpcClientProtocolDeps {
   shouldAutoLoadSecondarySubTrack?: (path: string) => boolean;
   shouldQuitOnMpvShutdown?: () => boolean;
   requestAppQuit?: () => void;
+  socketFactory?: MpvSocketTransportOptions['socketFactory'];
+  connectTimeoutMs?: number;
 }
 
 export interface MpvIpcClientDeps extends MpvIpcClientProtocolDeps {}
@@ -188,6 +194,8 @@ export class MpvIpcClient implements MpvClient {
 
     this.transport = new MpvSocketTransport({
       socketPath,
+      socketFactory: deps.socketFactory,
+      connectTimeoutMs: deps.connectTimeoutMs,
       onConnect: () => {
         this.connected = true;
         this.connecting = false;
@@ -289,6 +297,14 @@ export class MpvIpcClient implements MpvClient {
         previousSocketPath: this.socketPath,
         socketPath,
       });
+      if (this.connecting && !this.connected) {
+        // Abort the in-flight dial to the old path; otherwise the connecting
+        // latch turns every later connect() into a no-op while we hang on a
+        // stale socket.
+        logger.debug('Aborting in-flight MPV IPC connect for socket path change.');
+        this.transport.shutdown();
+        this.connecting = false;
+      }
     }
     this.socketPath = socketPath;
     this.transport.setSocketPath(socketPath);

src/core/services/overlay-click-through.test.ts

@@ -0,0 +1,21 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { applyOverlayClickThrough } from './overlay-click-through';
+
+test('applyOverlayClickThrough requests forwarding only off Windows', () => {
+  const calls: Array<{ ignore: boolean; forward: boolean }> = [];
+  const window = {
+    setIgnoreMouseEvents: (ignore: boolean, options?: { forward?: boolean }) => {
+      calls.push({ ignore, forward: options?.forward === true });
+    },
+  };
+
+  applyOverlayClickThrough(window, true);
+  applyOverlayClickThrough(window, false);
+
+  assert.deepEqual(calls, [
+    { ignore: true, forward: false },
+    { ignore: true, forward: true },
+  ]);
+});

src/core/services/overlay-click-through.ts

@@ -0,0 +1,27 @@
+type ClickThroughWindow = {
+  setIgnoreMouseEvents: (ignore: boolean, options?: { forward?: boolean }) => void;
+};
+
+/**
+ * Puts an overlay window into click-through mode. Forwarded mouse-move ({ forward: true }) is
+ * what lets renderer hover tracking wake a click-through overlay, but on Windows Electron
+ * implements it with a global WH_MOUSE_LL hook whose callback runs on the main-process message
+ * loop, so any main-thread stall delays mouse input system-wide (electron/electron#10183).
+ * Windows instead wakes the overlay via the main-process cursor poll
+ * (tickWindowsOverlayPointerInteraction), so no forwarding is requested there. macOS still
+ * needs forwarding for renderer hover tracking; Linux ignores the flag entirely
+ * (electron/electron#16777).
+ *
+ * Pass isWindowsPlatform when the caller already carries a platform flag (tests simulate
+ * platforms through it); otherwise the real process.platform decides.
+ */
+export function applyOverlayClickThrough(
+  window: ClickThroughWindow,
+  isWindowsPlatform?: boolean,
+): void {
+  if (isWindowsPlatform ?? process.platform === 'win32') {
+    window.setIgnoreMouseEvents(true);
+  } else {
+    window.setIgnoreMouseEvents(true, { forward: true });
+  }
+}

src/core/services/overlay-visibility.test.ts

@@ -848,7 +848,7 @@ test('Windows visible overlay stays click-through and binds to mpv while tracked
   } as never);
 
   assert.ok(calls.includes('opacity:0'));
-  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('mouse-ignore:true:plain'));
   assert.ok(calls.includes('show-inactive'));
   assert.ok(calls.includes('sync-windows-z-order'));
   assert.ok(!calls.includes('move-top'));
@@ -1060,7 +1060,7 @@ test('tracked Windows overlay refresh rebinds while already visible', () => {
     isWindowsPlatform: true,
   } as never);
 
-  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('mouse-ignore:true:plain'));
   assert.ok(calls.includes('sync-windows-z-order'));
   assert.ok(!calls.includes('move-top'));
   assert.ok(!calls.includes('show'));
@@ -1134,7 +1134,7 @@ test('forced passthrough still reapplies while visible on Windows', () => {
     forceMousePassthrough: true,
   } as never);
 
-  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('mouse-ignore:true:plain'));
   assert.ok(!calls.includes('always-on-top:false'));
   assert.ok(!calls.includes('move-top'));
   assert.ok(calls.includes('sync-windows-z-order'));
@@ -1339,7 +1339,7 @@ test('tracked Windows overlay rebinds without hiding when tracker focus changes'
 
   assert.ok(!calls.includes('always-on-top:false'));
   assert.ok(!calls.includes('move-top'));
-  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('mouse-ignore:true:plain'));
   assert.ok(calls.includes('sync-windows-z-order'));
   assert.ok(!calls.includes('ensure-level'));
   assert.ok(!calls.includes('enforce-order'));
@@ -1489,7 +1489,7 @@ test('tracked Windows overlay reshows click-through even if focus state is stale
     isWindowsPlatform: true,
   } as never);
 
-  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('mouse-ignore:true:plain'));
   assert.ok(calls.includes('show-inactive'));
   assert.ok(!calls.includes('show'));
 });
@@ -1532,7 +1532,7 @@ test('tracked Windows overlay binds above mpv even when tracker focus lags', ()
 
   assert.ok(!calls.includes('always-on-top:false'));
   assert.ok(!calls.includes('move-top'));
-  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('mouse-ignore:true:plain'));
   assert.ok(calls.includes('sync-windows-z-order'));
   assert.ok(!calls.includes('ensure-level'));
 });
@@ -2193,7 +2193,7 @@ test('Windows preserves visible overlay and rebinds to mpv while tracker transie
   assert.ok(!calls.includes('show'));
   assert.ok(!calls.includes('always-on-top:false'));
   assert.ok(!calls.includes('move-top'));
-  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('mouse-ignore:true:plain'));
   assert.ok(calls.includes('sync-windows-z-order'));
   assert.ok(!calls.includes('ensure-level'));
   assert.ok(calls.includes('sync-shortcuts'));

src/core/services/overlay-visibility.ts

@@ -1,6 +1,7 @@
 import type { BrowserWindow } from 'electron';
 import { BaseWindowTracker } from '../../window-trackers';
 import { WindowGeometry } from '../../types';
+import { applyOverlayClickThrough } from './overlay-click-through';
 import { OVERLAY_WINDOW_CONTENT_READY_FLAG } from './overlay-window-flags';
 
 const WINDOWS_OVERLAY_REVEAL_DELAY_MS = 48;
@@ -117,7 +118,7 @@ export function updateVisibleOverlayVisibility(args: {
       clearPendingWindowsOverlayReveal(mainWindow);
       setOverlayWindowOpacity(mainWindow, 0);
     }
-    mainWindow.setIgnoreMouseEvents(true, { forward: true });
+    applyOverlayClickThrough(mainWindow, args.isWindowsPlatform);
     releaseOverlayWindowLevel(mainWindow);
     mainWindow.hide();
     args.syncOverlayShortcuts();
@@ -215,7 +216,7 @@ export function updateVisibleOverlayVisibility(args: {
       shouldPreserveWindowsOverlayDuringFocusHandoff ||
       (hasWindowsForegroundProcessSignal && windowsForegroundProcessName === 'mpv');
     if (shouldIgnoreMouseEvents) {
-      mainWindow.setIgnoreMouseEvents(true, { forward: true });
+      applyOverlayClickThrough(mainWindow, args.isWindowsPlatform);
     } else {
       mainWindow.setIgnoreMouseEvents(false);
     }
@@ -263,7 +264,7 @@ export function updateVisibleOverlayVisibility(args: {
         if (hasNonNativeInputRegion) {
           mainWindow.setIgnoreMouseEvents(false);
         } else {
-          mainWindow.setIgnoreMouseEvents(true, { forward: true });
+          applyOverlayClickThrough(mainWindow, args.isWindowsPlatform);
         }
         if (args.isWindowsPlatform) {
           scheduleWindowsOverlayReveal(
@@ -424,7 +425,7 @@ export function updateVisibleOverlayVisibility(args: {
       return;
     }
     args.setTrackerNotReadyWarningShown(false);
-    mainWindow.setIgnoreMouseEvents(true, { forward: true });
+    applyOverlayClickThrough(mainWindow, args.isWindowsPlatform);
     releaseOverlayWindowLevel(mainWindow);
     mainWindow.hide();
     args.syncOverlayShortcuts();

src/core/services/overlay-window-config.test.ts

@@ -15,6 +15,32 @@ test('overlay window config explicitly disables renderer sandbox for preload com
   assert.equal(options.webPreferences?.backgroundThrottling, false);
 });
 
+test('macOS modal overlay uses a fullscreen auxiliary panel without changing the passive overlay', () => {
+  const visibleOptions = buildOverlayWindowOptions('visible', {
+    isDev: false,
+    platform: 'darwin',
+    yomitanSession: null,
+  });
+  const modalOptions = buildOverlayWindowOptions('modal', {
+    isDev: false,
+    platform: 'darwin',
+    yomitanSession: null,
+  });
+
+  assert.equal(visibleOptions.type, undefined);
+  assert.equal(modalOptions.type, 'panel');
+});
+
+test('non-macOS modal overlay remains a regular window', () => {
+  const options = buildOverlayWindowOptions('modal', {
+    isDev: false,
+    platform: 'linux',
+    yomitanSession: null,
+  });
+
+  assert.equal(options.type, undefined);
+});
+
 test('Linux visible overlay window allows compositor resize for mpv-sized placement', () => {
   const originalPlatformDescriptor = Object.getOwnPropertyDescriptor(process, 'platform');
 

src/core/services/overlay-window-flags.ts

@@ -1 +1,2 @@
 export const OVERLAY_WINDOW_CONTENT_READY_FLAG = '__subminerOverlayContentReady';
+export const OVERLAY_WINDOW_DOCUMENT_LOADED_FLAG = '__subminerOverlayDocumentLoaded';

src/core/services/overlay-window-options.ts

@@ -12,15 +12,17 @@ export function buildOverlayWindowOptions(
   options: {
     isDev: boolean;
     linuxX11FullscreenOverlay?: boolean;
+    platform?: NodeJS.Platform;
     yomitanSession?: Session | null;
   },
 ): BrowserWindowConstructorOptions {
-  const showNativeDebugFrame = process.platform === 'win32' && options.isDev;
-  const isLinuxVisibleOverlay = process.platform === 'linux' && kind === 'visible';
+  const platform = options.platform ?? process.platform;
+  const showNativeDebugFrame = platform === 'win32' && options.isDev;
+  const isLinuxVisibleOverlay = platform === 'linux' && kind === 'visible';
   const isLinuxFullscreenOverlay =
     isLinuxVisibleOverlay && options.linuxX11FullscreenOverlay === true;
   const shouldStartAlwaysOnTop =
-    !(process.platform === 'win32' && kind === 'visible') &&
+    !(platform === 'win32' && kind === 'visible') &&
     (!isLinuxVisibleOverlay || isLinuxFullscreenOverlay);
   const shouldAllowCompositorResize = isLinuxVisibleOverlay && !isLinuxFullscreenOverlay;
 
@@ -41,7 +43,10 @@ export function buildOverlayWindowOptions(
     hasShadow: false,
     focusable: !isLinuxFullscreenOverlay,
     acceptFirstMouse: true,
-    ...(process.platform === 'win32' ? { thickFrame: showNativeDebugFrame } : {}),
+    // A macOS panel is a fullscreen auxiliary window, so modal surfaces stay on the
+    // active mpv Space instead of opening on SubMiner's last regular desktop.
+    ...(platform === 'darwin' && kind === 'modal' ? { type: 'panel' as const } : {}),
+    ...(platform === 'win32' ? { thickFrame: showNativeDebugFrame } : {}),
     webPreferences: {
       preload: path.join(__dirname, '..', '..', 'preload.js'),
       contextIsolation: true,

src/core/services/overlay-window.ts

@@ -16,7 +16,10 @@ import {
 } from './hyprland-window-placement';
 import { buildOverlayWindowOptions, OVERLAY_WINDOW_TITLES } from './overlay-window-options';
 import { normalizeOverlayWindowBoundsForPlatform } from './overlay-window-bounds';
-import { OVERLAY_WINDOW_CONTENT_READY_FLAG } from './overlay-window-flags';
+import {
+  OVERLAY_WINDOW_CONTENT_READY_FLAG,
+  OVERLAY_WINDOW_DOCUMENT_LOADED_FLAG,
+} from './overlay-window-flags';
 export { OVERLAY_WINDOW_CONTENT_READY_FLAG } from './overlay-window-flags';
 
 const logger = createLogger('main:overlay-window');
@@ -133,6 +136,9 @@ export function createOverlayWindow(
   (window as BrowserWindow & { [OVERLAY_WINDOW_CONTENT_READY_FLAG]?: boolean })[
     OVERLAY_WINDOW_CONTENT_READY_FLAG
   ] = false;
+  (window as BrowserWindow & { [OVERLAY_WINDOW_DOCUMENT_LOADED_FLAG]?: boolean })[
+    OVERLAY_WINDOW_DOCUMENT_LOADED_FLAG
+  ] = false;
 
   if (!(process.platform === 'win32' && kind === 'visible')) {
     options.ensureOverlayWindowLevel(window);
@@ -144,11 +150,20 @@ export function createOverlayWindow(
   });
 
   window.webContents.on('did-finish-load', () => {
+    (window as BrowserWindow & { [OVERLAY_WINDOW_DOCUMENT_LOADED_FLAG]?: boolean })[
+      OVERLAY_WINDOW_DOCUMENT_LOADED_FLAG
+    ] = true;
     window.setTitle(OVERLAY_WINDOW_TITLES[kind]);
     options.onRuntimeOptionsChanged();
     options.onWindowDidFinishLoad?.();
   });
 
+  window.webContents.on('did-start-loading', () => {
+    (window as BrowserWindow & { [OVERLAY_WINDOW_DOCUMENT_LOADED_FLAG]?: boolean })[
+      OVERLAY_WINDOW_DOCUMENT_LOADED_FLAG
+    ] = false;
+  });
+
   window.webContents.on('page-title-updated', (event) => {
     event.preventDefault();
     window.setTitle(OVERLAY_WINDOW_TITLES[kind]);

src/core/services/stats-window-runtime.ts

@@ -57,7 +57,9 @@ export function shouldHideStatsWindowForInput(input: Electron.Input, toggleKey:
 export function buildStatsWindowOptions(options: {
   preloadPath: string;
   bounds?: WindowGeometry | null;
+  platform?: NodeJS.Platform;
 }): BrowserWindowConstructorOptions {
+  const platform = options.platform ?? process.platform;
   return {
     title: STATS_WINDOW_TITLE,
     x: options.bounds?.x,
@@ -73,6 +75,9 @@ export function buildStatsWindowOptions(options: {
     focusable: true,
     acceptFirstMouse: true,
     fullscreenable: false,
+    // Panels join fullscreen Spaces on macOS without moving the user back to the
+    // desktop where SubMiner last owned a regular application window.
+    ...(platform === 'darwin' ? { type: 'panel' as const } : {}),
     backgroundColor: '#24273a',
     show: false,
     webPreferences: {
@@ -84,6 +89,12 @@ export function buildStatsWindowOptions(options: {
   };
 }
 
+export function shouldPresentStatsWindowAfterLoad(
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  return platform === 'darwin';
+}
+
 export function resolveStatsWindowOuterBoundsForContent(
   window: StatsWindowBoundsController,
   target: WindowGeometry,

src/core/services/stats-window.test.ts

@@ -12,6 +12,7 @@ import {
   scheduleStatsWindowPostShowReconciles,
   showStatsNativeConfirmDialog,
   shouldHideStatsWindowForInput,
+  shouldPresentStatsWindowAfterLoad,
 } from './stats-window-runtime';
 
 test('buildStatsWindowOptions uses tracked overlay bounds and preload-friendly web preferences', () => {
@@ -40,6 +41,30 @@ test('buildStatsWindowOptions uses tracked overlay bounds and preload-friendly w
   assert.equal(options.webPreferences?.sandbox, true);
 });
 
+test('buildStatsWindowOptions uses a fullscreen auxiliary panel on macOS', () => {
+  const options = buildStatsWindowOptions({
+    preloadPath: '/tmp/preload-stats.js',
+    platform: 'darwin',
+  });
+
+  assert.equal(options.type, 'panel');
+});
+
+test('buildStatsWindowOptions remains a regular window off macOS', () => {
+  const options = buildStatsWindowOptions({
+    preloadPath: '/tmp/preload-stats.js',
+    platform: 'linux',
+  });
+
+  assert.equal(options.type, undefined);
+});
+
+test('stats panels present after document load on macOS', () => {
+  assert.equal(shouldPresentStatsWindowAfterLoad('darwin'), true);
+  assert.equal(shouldPresentStatsWindowAfterLoad('linux'), false);
+  assert.equal(shouldPresentStatsWindowAfterLoad('win32'), false);
+});
+
 test('shouldHideStatsWindowForInput matches Escape and configured bare toggle key', () => {
   assert.equal(
     shouldHideStatsWindowForInput(

src/core/services/stats-window.ts

@@ -13,6 +13,7 @@ import {
   scheduleStatsWindowPostShowReconciles,
   showStatsNativeConfirmDialog,
   shouldHideStatsWindowForInput,
+  shouldPresentStatsWindowAfterLoad,
   STATS_WINDOW_TITLE,
 } from './stats-window-runtime.js';
 import { ensureHyprlandWindowFloatingByTitle } from './hyprland-window-placement.js';
@@ -209,10 +210,15 @@ export function toggleStatsOverlay(options: StatsWindowOptions): void {
         options.onVisibilityChanged?.(false);
       }
     });
-    statsWindow.once('ready-to-show', () => {
+    const showInitialStatsWindow = () => {
       if (!statsWindow) return;
       showStatsWindow(statsWindow, options);
-    });
+    };
+    if (shouldPresentStatsWindowAfterLoad()) {
+      statsWindow.webContents.once('did-finish-load', showInitialStatsWindow);
+    } else {
+      statsWindow.once('ready-to-show', showInitialStatsWindow);
+    }
 
     statsWindow.on('blur', () => {
       if (!statsWindow || statsWindow.isDestroyed() || !statsWindow.isVisible()) {

src/core/services/subtitle-cue-dedup.ts

@@ -27,17 +27,188 @@ function cueKey(cue: SubtitleCue): string {
 
 /**
  * Identical text over an identical span is redundant however it was authored -- most
- * often a layered ASS event stacking a shadow copy under the visible one.
+ * often a layered ASS event stacking a shadow copy under the visible one. When one of
+ * the duplicates is a recovered canonical cue, that copy survives: dropping it would
+ * strip the `source` marker and animation envelope the live overlay substitutes on.
  */
 function collapseExactDuplicates(cues: AnnotatedSubtitleCue[]): AnnotatedSubtitleCue[] {
-  const seen = new Set<string>();
-  return cues.filter((cue) => {
+  const survivorByKey = new Map<string, AnnotatedSubtitleCue>();
+  const keysInOrder: string[] = [];
+  for (const cue of cues) {
     const key = cueKey(cue);
-    if (seen.has(key)) {
-      return false;
+    const existing = survivorByKey.get(key);
+    if (!existing) {
+      survivorByKey.set(key, cue);
+      keysInOrder.push(key);
+    } else if (!existing.source && cue.source) {
+      survivorByKey.set(key, cue);
     }
-    seen.add(key);
+  }
+  return keysInOrder.map((key) => survivorByKey.get(key)!);
+}
+
+const SPATIAL_ASS_OVERRIDE_COMMANDS = new Set([
+  'a',
+  'an',
+  'clip',
+  'iclip',
+  'move',
+  'org',
+  'pbo',
+  'pos',
+  'q',
+]);
+
+interface RepeatedPhaseRun {
+  cues: AnnotatedSubtitleCue[];
+  indices: number[];
+}
+
+// A changing override signature alone is weak: two ordinary repeats restyled with
+// different colors look identical to a phase pair. Real phase redraws carry a styling
+// stack over a full lyric line, and they exist to move a color/highlight boundary
+// *within* the line -- so every event also has an override block after visible text
+// began. An ordinary restyled repeat carries only a leading block and stays separate.
+const MIN_PHASE_EVIDENCE_OVERRIDES = 2;
+const MIN_PHASE_TEXT_LENGTH = 4;
+
+function hasMidLineOverrideBlock(rawText: string): boolean {
+  let sawVisibleText = false;
+  for (let i = 0; i < rawText.length; i += 1) {
+    if (rawText[i] === '{') {
+      const close = rawText.indexOf('}', i);
+      if (close === -1) {
+        // Unclosed brace renders as literal text; nothing after it is markup.
+        return false;
+      }
+      if (sawVisibleText) {
+        return true;
+      }
+      i = close;
+    } else if (!/\s/.test(rawText[i]!)) {
+      sawVisibleText = true;
+    }
+  }
+  return false;
+}
+
+function assStyleKey(cue: AnnotatedSubtitleCue): string {
+  return `${cue.style}\0${cue.name}\0${cue.layer}`;
+}
+
+function spatialOverrideSignature(cue: AnnotatedSubtitleCue): string {
+  return cue.overrides
+    .filter((command) => SPATIAL_ASS_OVERRIDE_COMMANDS.has(command.name.toLowerCase()))
+    .map((command) => `${command.name.toLowerCase()}(${command.args})`)
+    .join('|');
+}
+
+function hasStableSpatialOverrides(run: readonly AnnotatedSubtitleCue[]): boolean {
+  const firstSignature = spatialOverrideSignature(run[0]!);
+  return run.every((cue) => spatialOverrideSignature(cue) === firstSignature);
+}
+
+function hasDirectPhaseEvidence(run: readonly AnnotatedSubtitleCue[]): boolean {
+  // Phases redraw one authored line in place. Whatever the animation evidence, a run
+  // whose spatial placement changes is separate authored occurrences -- two flush
+  // same-text `\move` signs at different coordinates must never merge.
+  if (!hasStableSpatialOverrides(run)) {
+    return false;
+  }
+  if (run.every((cue) => hasAssTemporalOverride(cue.overrides))) {
     return true;
+  }
+  if (run.every((cue) => isAnimatedAssEffectKind(cue.effectKind))) {
+    return true;
+  }
+
+  const [first] = run;
+  return (
+    first!.text.replace(/\s+/gu, '').length >= MIN_PHASE_TEXT_LENGTH &&
+    run.every(
+      (cue) =>
+        cue.overrides.length >= MIN_PHASE_EVIDENCE_OVERRIDES &&
+        hasMidLineOverrideBlock(cue.rawText),
+    ) &&
+    run.some((cue) => cue.overrideSignature !== first!.overrideSignature)
+  );
+}
+
+function collectRepeatedPhaseRuns(cues: AnnotatedSubtitleCue[]): RepeatedPhaseRun[] {
+  const runs: RepeatedPhaseRun[] = [];
+  let start = 0;
+
+  while (start < cues.length) {
+    const first = cues[start]!;
+    const styleKey = assStyleKey(first);
+    let end = start;
+
+    while (end + 1 < cues.length) {
+      const current = cues[end]!;
+      const next = cues[end + 1]!;
+      const isFlush =
+        Math.abs(next.startTime - current.endTime) <= DUPLICATE_CUE_GAP_TOLERANCE_SECONDS;
+      if (
+        first.source === 'canonical-ass' ||
+        next.source === 'canonical-ass' ||
+        next.text !== first.text ||
+        assStyleKey(next) !== styleKey ||
+        !isFlush
+      ) {
+        break;
+      }
+      end += 1;
+    }
+
+    if (end > start) {
+      const indices = Array.from({ length: end - start + 1 }, (_, offset) => start + offset);
+      runs.push({
+        cues: indices.map((index) => cues[index]!),
+        indices,
+      });
+    }
+    start = end + 1;
+  }
+
+  return runs;
+}
+
+/**
+ * Some karaoke scripts redraw one complete lyric for each color/highlight phase. These
+ * events last far longer than animation frames, but are still one sidebar/history line.
+ * The events must prove themselves through direct animation metadata or changing
+ * non-spatial overrides. Plain repeated dialogue and separately positioned signs stay
+ * intact.
+ */
+function collapseAnimatedStylePhases(cues: AnnotatedSubtitleCue[]): AnnotatedSubtitleCue[] {
+  const runs = collectRepeatedPhaseRuns(cues);
+  if (runs.length === 0) {
+    return cues;
+  }
+
+  const dropped = new Set<number>();
+  const extendedEnd = new Map<number, number>();
+  for (const run of runs) {
+    if (!hasDirectPhaseEvidence(run.cues)) {
+      continue;
+    }
+
+    const [firstIndex, ...remainingIndices] = run.indices;
+    for (const index of remainingIndices) {
+      dropped.add(index);
+    }
+    extendedEnd.set(firstIndex!, Math.max(...run.cues.map((cue) => cue.endTime)));
+  }
+
+  if (dropped.size === 0) {
+    return cues;
+  }
+  return cues.flatMap((cue, index) => {
+    if (dropped.has(index)) {
+      return [];
+    }
+    const endTime = extendedEnd.get(index);
+    return endTime !== undefined ? [{ ...cue, endTime }] : [cue];
   });
 }
 
@@ -176,5 +347,8 @@ export function mergeDuplicateCues(
   cues: AnnotatedSubtitleCue[],
   format: SubtitleSourceFormat,
 ): AnnotatedSubtitleCue[] {
-  return collapseAnimationBursts(collapseExactDuplicates(cues), format);
+  const exactDeduplicated = collapseExactDuplicates(cues);
+  const phaseDeduplicated =
+    format === 'ass' ? collapseAnimatedStylePhases(exactDeduplicated) : exactDeduplicated;
+  return collapseAnimationBursts(phaseDeduplicated, format);
 }

src/core/services/subtitle-cue-parser.test.ts

@@ -327,6 +327,122 @@ test('parseSubtitleCues collapses per-frame karaoke duplicates into one cue', ()
   assert.equal(cues[0]!.text, '過ぎ去ってしまう瞬間を');
 });
 
+test('parseSubtitleCues collapses long full-line color phases', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 1,0:03:49.75,0:03:51.21,OPJP,,0,0,0,,{\\blur0.6\\c&H312D38&\\4c&HFFFFFF&}ちゃんと目を{\\4c&HD590FF&}合わせてよ',
+    'Dialogue: 1,0:03:51.21,0:03:52.25,OPJP,,0,0,0,,{\\blur0.6\\4c&H312D38&\\c&HFFFFFF&}ちゃんと目を{\\4c&HD590FF&}合わせてよ',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    {
+      startTime: 229.75,
+      endTime: 232.25,
+      text: 'ちゃんと目を合わせてよ',
+    },
+  ]);
+});
+
+test('parseSubtitleCues keeps ordinary repeated dialogue separate', () => {
+  // A single restyle tag on a repeated line is how ordinary dialogue gets decorated;
+  // it is not phase evidence, whatever the line length.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 1,0:00:01.00,0:00:02.00,OPJP,,0,0,0,,{\\c&H111111&}歌詞',
+    'Dialogue: 1,0:00:02.00,0:00:03.00,OPJP,,0,0,0,,{\\c&H222222&}歌詞',
+    'Dialogue: 1,0:00:04.00,0:00:05.00,OPJP,,0,0,0,,{\\c&H333333&}別の歌詞',
+    'Dialogue: 1,0:00:05.00,0:00:06.00,OPJP,,0,0,0,,{\\c&H444444&}別の歌詞',
+    'Dialogue: 8,0:00:07.00,0:00:08.00,Text - JP,,0,0,0,,えっ？',
+    'Dialogue: 8,0:00:08.00,0:00:09.00,Text - JP,,0,0,0,,えっ？',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    { startTime: 1, endTime: 2, text: '歌詞' },
+    { startTime: 2, endTime: 3, text: '歌詞' },
+    { startTime: 4, endTime: 5, text: '別の歌詞' },
+    { startTime: 5, endTime: 6, text: '別の歌詞' },
+    { startTime: 7, endTime: 8, text: 'えっ？' },
+    { startTime: 8, endTime: 9, text: 'えっ？' },
+  ]);
+});
+
+test('parseSubtitleCues keeps separately positioned temporal signs separate', () => {
+  // Two flush signs with the same text but different \move paths are separate authored
+  // occurrences, not phases of one redraw: temporal evidence alone must not merge them.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:02.00,Sign,,0,0,0,,{\\move(100,100,200,100)}立入禁止',
+    'Dialogue: 0,0:00:02.00,0:00:03.00,Sign,,0,0,0,,{\\move(500,400,600,400)}立入禁止',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    { startTime: 1, endTime: 2, text: '立入禁止' },
+    { startTime: 2, endTime: 3, text: '立入禁止' },
+  ]);
+});
+
+test('parseSubtitleCues keeps richly styled ordinary repeats separate', () => {
+  // Blur plus a changing color is still an ordinary restyle. Phase redraws are
+  // recognized by the color/highlight boundary moving *within* the line, which these
+  // leading-block-only events do not have.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:02.00,Dial,,0,0,0,,{\\blur0.4\\c&H111111&}待ってよ',
+    'Dialogue: 0,0:00:02.00,0:00:03.00,Dial,,0,0,0,,{\\blur0.4\\c&H222222&}待ってよ',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    { startTime: 1, endTime: 2, text: '待ってよ' },
+    { startTime: 2, endTime: 3, text: '待ってよ' },
+  ]);
+});
+
+test('parseSubtitleCues keeps canonical metadata when an identical plain cue exists', () => {
+  // A plain dialogue line can share exact timing and text with a recovered canonical
+  // cue from another style. The canonical copy must win the exact-duplicate collapse,
+  // or the live overlay loses the marker it substitutes on.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:05.00,0:00:08.00,Plain,,0,0,0,,ライン',
+    'Comment: 0,0:00:05.00,0:00:08.00,OP,,0,0,0,,ライン',
+    'Dialogue: 0,0:00:05.00,0:00:05.04,OP,,0,0,0,,{\\pos(1,1)\\clip(m 1 1)}ライン',
+    'Dialogue: 0,0:00:05.04,0:00:05.08,OP,,0,0,0,,{\\pos(1,1)\\clip(m 2 2)}ライン',
+    'Dialogue: 0,0:00:05.08,0:00:08.00,OP,,0,0,0,,{\\pos(1,1)\\clip(m 3 3)}ライン',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    {
+      startTime: 5,
+      endTime: 8,
+      text: 'ライン',
+      source: 'canonical-ass',
+      animationStartTime: 5,
+      animationEndTime: 8,
+    },
+  ]);
+});
+
+test('parseSubtitleCues keeps short styled repeats separate even with richer styling', () => {
+  // Two ordinary えっ lines restyled with different colors are two utterances, not two
+  // phases of one lyric: short text never satisfies the changing-override evidence path.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:01.00,0:00:02.00,Dial,,0,0,0,,{\\blur0.4\\c&H111111&}えっ',
+    'Dialogue: 0,0:00:02.00,0:00:03.00,Dial,,0,0,0,,{\\blur0.4\\c&H222222&}えっ',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    { startTime: 1, endTime: 2, text: 'えっ' },
+    { startTime: 2, endTime: 3, text: 'えっ' },
+  ]);
+});
+
 test('parseSubtitleCues keeps back-to-back plain dialogue repeats separate', () => {
   // Several characters greeting in turn: distinct utterances that happen to abut.
   const content = [
@@ -357,6 +473,194 @@ test('parseSubtitleCues collapses exact duplicate cues even without effect tags'
   assert.equal(cues.length, 1);
 });
 
+test('parseSubtitleCues replaces generated glyph animation with its timed canonical comment', () => {
+  // Aegisub automation commonly keeps the authored lyric as a Comment and emits
+  // multiple moving Dialogue layers for every glyph. This mirrors the MyGO ED script:
+  // three entrance copies followed by three exit copies for each character.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Comment: 0,0:00:01.20,0:00:03.80,ED_JP,,0,0,0,,{\\fad(480,480)}今　手にある',
+    'Dialogue: 0,0:00:00.80,0:00:01.50,ED_JP,,0,0,0,,{\\move(10,20,100,200)\\t(0,600,\\fscx100)}今',
+    'Dialogue: 0,0:00:00.80,0:00:01.50,ED_JP,,0,0,0,,{\\move(30,40,100,200)\\t(0,600,\\fscx100)}今',
+    'Dialogue: 0,0:00:00.80,0:00:01.50,ED_JP,,0,0,0,,{\\move(50,60,100,200)\\t(0,600,\\fscx100)}今',
+    'Dialogue: 1,0:00:01.40,0:00:04.20,ED_JP,,0,0,0,,{\\move(100,200,20,30)\\t(2000,2600,\\blur20)}今',
+    'Dialogue: 1,0:00:01.40,0:00:04.20,ED_JP,,0,0,0,,{\\move(100,200,40,50)\\t(2000,2600,\\blur20)}今',
+    'Dialogue: 1,0:00:01.40,0:00:04.20,ED_JP,,0,0,0,,{\\move(100,200,60,70)\\t(2000,2600,\\blur20)}今',
+    'Dialogue: 0,0:00:00.86,0:00:01.56,ED_JP,,0,0,0,,{\\move(10,20,140,200)\\t(0,600,\\fscx100)}手',
+    'Dialogue: 0,0:00:00.86,0:00:01.56,ED_JP,,0,0,0,,{\\move(30,40,140,200)\\t(0,600,\\fscx100)}手',
+    'Dialogue: 0,0:00:00.86,0:00:01.56,ED_JP,,0,0,0,,{\\move(50,60,140,200)\\t(0,600,\\fscx100)}手',
+    'Dialogue: 1,0:00:01.46,0:00:04.26,ED_JP,,0,0,0,,{\\move(140,200,20,30)\\t(2000,2600,\\blur20)}手',
+    'Dialogue: 1,0:00:01.46,0:00:04.26,ED_JP,,0,0,0,,{\\move(140,200,40,50)\\t(2000,2600,\\blur20)}手',
+    'Dialogue: 1,0:00:01.46,0:00:04.26,ED_JP,,0,0,0,,{\\move(140,200,60,70)\\t(2000,2600,\\blur20)}手',
+    'Dialogue: 0,0:00:00.92,0:00:01.62,ED_JP,,0,0,0,,{\\move(10,20,180,200)\\t(0,600,\\fscx100)}にある',
+    'Dialogue: 0,0:00:00.92,0:00:01.62,ED_JP,,0,0,0,,{\\move(30,40,180,200)\\t(0,600,\\fscx100)}にある',
+    'Dialogue: 0,0:00:00.92,0:00:01.62,ED_JP,,0,0,0,,{\\move(50,60,180,200)\\t(0,600,\\fscx100)}にある',
+    'Dialogue: 1,0:00:01.52,0:00:04.32,ED_JP,,0,0,0,,{\\move(180,200,20,30)\\t(2000,2600,\\blur20)}にある',
+    'Dialogue: 1,0:00:01.52,0:00:04.32,ED_JP,,0,0,0,,{\\move(180,200,40,50)\\t(2000,2600,\\blur20)}にある',
+    'Dialogue: 1,0:00:01.52,0:00:04.32,ED_JP,,0,0,0,,{\\move(180,200,60,70)\\t(2000,2600,\\blur20)}にある',
+    'Dialogue: 0,0:00:06.00,0:00:08.00,Dial_JP,,0,0,0,,普通の会話',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.deepEqual(cues, [
+    {
+      startTime: 1.2,
+      endTime: 3.8,
+      text: '今　手にある',
+      source: 'canonical-ass',
+      // Entrance frames start before and exit frames end after the authored timing.
+      animationStartTime: 0.8,
+      animationEndTime: 4.32,
+    },
+    { startTime: 6, endTime: 8, text: '普通の会話' },
+  ]);
+});
+
+test('parseSubtitleCues recovers a full Dialogue line surrounding generated fragments', () => {
+  // Some scripts do not retain the authored line as a Comment. Instead, brief entrance
+  // and exit events contain the complete line around a long run of generated syllables.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 1,0:00:01.00,0:00:01.15,ED Romaji,,0,0,0,fx,{\\move(100,40,60,40)}toki yo ugokidase',
+    'Dialogue: 1,0:00:01.15,0:00:03.00,ED Romaji,,0,0,0,fx,{\\t(0,300,\\c&HFFFFFF&)}to',
+    'Dialogue: 1,0:00:01.15,0:00:03.00,ED Romaji,,0,0,0,fx,{\\t(300,500,\\c&HFFFFFF&)}ki',
+    'Dialogue: 1,0:00:01.15,0:00:03.00,ED Romaji,,0,0,0,fx,{\\t(500,700,\\c&HFFFFFF&)}yo',
+    'Dialogue: 1,0:00:01.15,0:00:03.00,ED Romaji,,0,0,0,fx,{\\t(700,900,\\c&HFFFFFF&)}u',
+    'Dialogue: 1,0:00:01.15,0:00:03.00,ED Romaji,,0,0,0,fx,{\\t(900,1100,\\c&HFFFFFF&)}go',
+    'Dialogue: 1,0:00:01.15,0:00:03.00,ED Romaji,,0,0,0,fx,{\\t(1100,1300,\\c&HFFFFFF&)}ki',
+    'Dialogue: 1,0:00:01.15,0:00:03.00,ED Romaji,,0,0,0,fx,{\\t(1300,1500,\\c&HFFFFFF&)}da',
+    'Dialogue: 1,0:00:01.15,0:00:03.00,ED Romaji,,0,0,0,fx,{\\t(1500,1800,\\c&HFFFFFF&)}se',
+    'Dialogue: 1,0:00:03.00,0:00:03.15,ED Romaji,,0,0,0,fx,{\\move(60,40,20,40)}toki yo ugokidase',
+    'Dialogue: 0,0:00:06.00,0:00:08.00,Default,,0,0,0,,Ordinary dialogue',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    {
+      startTime: 1,
+      endTime: 3.15,
+      text: 'toki yo ugokidase',
+      source: 'canonical-ass',
+      animationStartTime: 1,
+      animationEndTime: 3.15,
+    },
+    { startTime: 6, endTime: 8, text: 'Ordinary dialogue' },
+  ]);
+});
+
+test('parseSubtitleCues does not promote a short animated fragment as a complete line', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 1,0:00:01.00,0:00:03.00,OP English,,0,0,0,,{\\pos(100,100)\\t(0,100,\\fscx120)}my',
+    'Dialogue: 2,0:00:01.00,0:00:03.00,OP English,,0,0,0,,{\\pos(100,100)\\t(0,100,\\fscx120)}my',
+    'Dialogue: 1,0:00:01.00,0:00:03.00,OP English,,0,0,0,,{\\pos(100,100)\\t(0,100,\\fscx120)}m',
+    'Dialogue: 2,0:00:01.00,0:00:03.00,OP English,,0,0,0,,{\\pos(100,100)\\t(0,100,\\fscx120)}m',
+    'Dialogue: 1,0:00:01.00,0:00:03.00,OP English,,0,0,0,,{\\pos(120,100)\\t(20,120,\\fscx120)}y',
+    'Dialogue: 2,0:00:01.00,0:00:03.00,OP English,,0,0,0,,{\\pos(120,100)\\t(20,120,\\fscx120)}y',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.equal(
+    cues.some((cue) => cue.source === 'canonical-ass'),
+    false,
+  );
+});
+
+test('parseSubtitleCues ignores timed comments without a matching animated dialogue cluster', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Comment: 0,0:00:01.00,0:00:03.00,Dial_JP,,0,0,0,,編集メモ',
+    'Comment: 0,0:00:04.00,0:00:06.00,Dial_JP,,0,0,0,,別案の字幕',
+    'Dialogue: 0,0:00:01.00,0:00:03.00,Dial_JP,,0,0,0,,通常の字幕',
+    'Dialogue: 0,0:00:04.00,0:00:06.00,Dial_JP,,0,0,0,,別案の字幕',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.deepEqual(cues, [
+    { startTime: 1, endTime: 3, text: '通常の字幕' },
+    { startTime: 4, endTime: 6, text: '別案の字幕' },
+  ]);
+});
+
+test('parseAssCues returns recovered canonical cues in chronological order', () => {
+  // Recovery appends recovered cues after surviving dialogue; the bare parseAssCues
+  // export must still come back time-ordered.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 0,0:00:06.00,0:00:08.00,Dial,,0,0,0,,あとのセリフ',
+    'Comment: 0,0:00:01.20,0:00:03.80,OP,,0,0,0,,雨が上がっても',
+    'Dialogue: 0,0:00:01.20,0:00:01.24,OP,,0,0,0,,{\\pos(1,1)\\clip(m 1 1)}雨が上がっても',
+    'Dialogue: 0,0:00:01.24,0:00:01.28,OP,,0,0,0,,{\\pos(1,1)\\clip(m 2 2)}雨が上がっても',
+    'Dialogue: 0,0:00:01.28,0:00:03.80,OP,,0,0,0,,{\\pos(1,1)\\clip(m 3 3)}雨が上がっても',
+  ].join('\n');
+
+  assert.deepEqual(
+    parseAssCues(content).map((cue) => cue.startTime),
+    [1.2, 6],
+  );
+});
+
+test('parseSubtitleCues withdraws a recovery whose owner is claimed by a later candidate', () => {
+  // The exit boundary event appears first in the file and recovers a canonical cue from
+  // its own small cluster. The entrance candidate then proves that exit event was a
+  // generated frame of the full animation; the earlier recovery is a duplicate of the
+  // same authored line and must not survive alongside it.
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Dialogue: 1,0:00:14.00,0:00:14.20,ED,,0,0,0,,{\\move(100,200,20,30)}ABCDEFGH',
+    'Dialogue: 1,0:00:13.50,0:00:14.50,ED,,0,0,0,,{\\t(0,300,\\c&HFFFFFF&)}ABC',
+    'Dialogue: 1,0:00:13.50,0:00:14.50,ED,,0,0,0,,{\\t(300,600,\\c&HFFFFFF&)}DEF',
+    'Dialogue: 1,0:00:13.50,0:00:14.50,ED,,0,0,0,,{\\t(600,900,\\c&HFFFFFF&)}GH',
+    'Dialogue: 0,0:00:10.00,0:00:10.20,ED,,0,0,0,,{\\move(10,20,100,200)}ABCDEFGH',
+    'Dialogue: 0,0:00:10.00,0:00:12.00,ED,,0,0,0,,{\\t(0,300,\\fscx100)}ABC',
+    'Dialogue: 0,0:00:10.00,0:00:12.00,ED,,0,0,0,,{\\t(300,600,\\fscx100)}DEF',
+    'Dialogue: 0,0:00:10.00,0:00:13.40,ED,,0,0,0,,{\\t(600,900,\\fscx100)}GH',
+  ].join('\n');
+
+  assert.deepEqual(parseSubtitleCues(content, 'test.ass'), [
+    {
+      startTime: 10,
+      endTime: 14.2,
+      text: 'ABCDEFGH',
+      source: 'canonical-ass',
+      animationStartTime: 10,
+      animationEndTime: 14.2,
+    },
+  ]);
+});
+
+test('parseSubtitleCues recovers canonical comments from generated clip frames', () => {
+  const content = [
+    '[Events]',
+    'Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text',
+    'Comment: 0,0:00:01.00,0:00:03.00,OP_JP,,0,0,0,,雨が上がっても',
+    'Dialogue: 0,0:00:01.00,0:00:01.04,OP_JP,,0,0,0,,{\\pos(960,1068)\\clip(m 1 1)}雨が上がっても',
+    'Dialogue: 0,0:00:01.04,0:00:01.08,OP_JP,,0,0,0,,{\\pos(960,1068)\\clip(m 2 2)}雨が上がっても',
+    'Dialogue: 0,0:00:01.08,0:00:03.00,OP_JP,,0,0,0,,{\\pos(960,1068)\\clip(m 3 3)}雨が上がっても',
+  ].join('\n');
+
+  const cues = parseSubtitleCues(content, 'test.ass');
+
+  assert.deepEqual(cues, [
+    {
+      startTime: 1,
+      endTime: 3,
+      text: '雨が上がっても',
+      source: 'canonical-ass',
+      animationStartTime: 1,
+      animationEndTime: 3,
+    },
+  ]);
+});
+
 test('parseSubtitleCues collapses tag-less animation frames in converted SRT', () => {
   // ASS -> SRT conversion drops override tags, so only the ~0.04s frame timing remains.
   const lines = ['1', '00:00:07,870 --> 00:00:07,910', 'Kaguya Wants to be Confessed to', ''];

src/core/services/subtitle-cue-parser.ts

@@ -6,12 +6,21 @@ import {
   type AssEffectKind,
   type AssOverrideCommand,
 } from './ass-text';
-import { mergeDuplicateCues } from './subtitle-cue-dedup';
+import { hasAssAnimationEvidence, mergeDuplicateCues } from './subtitle-cue-dedup';
 
 export interface SubtitleCue {
   startTime: number;
   endTime: number;
   text: string;
+  /** A complete authored line recovered from matching generated ASS animation events. */
+  source?: 'canonical-ass';
+  /**
+   * Full span of the generated animation events a canonical cue replaced. Entrance and
+   * exit frames routinely run past the authored `startTime`/`endTime`, so live-text
+   * matching must use this envelope while display and history keep the authored timing.
+   */
+  animationStartTime?: number;
+  animationEndTime?: number;
 }
 
 /**
@@ -19,7 +28,8 @@ export interface SubtitleCue {
  * Deduplication needs the authoring context -- which style the line belongs to, which
  * override commands it carries, whether the `Effect` column was set -- to tell a karaoke
  * burst apart from two characters saying the same word in turn. None of it is meaningful
- * outside the parser, so the public API stays `{startTime, endTime, text}`.
+ * outside the parser, so the public API exposes only timing, text, and the optional
+ * canonical-source marker used by live subtitle consumers.
  */
 export interface AnnotatedSubtitleCue extends SubtitleCue {
   /** Text exactly as authored, override blocks and all. */
@@ -70,7 +80,11 @@ function sanitizeSubtitleCueText(text: string): string {
 }
 
 function toPublicCues(cues: AnnotatedSubtitleCue[]): SubtitleCue[] {
-  return cues.map(({ startTime, endTime, text }) => ({ startTime, endTime, text }));
+  return cues.map(({ startTime, endTime, text, source, animationStartTime, animationEndTime }) =>
+    source
+      ? { startTime, endTime, text, source, animationStartTime, animationEndTime }
+      : { startTime, endTime, text },
+  );
 }
 
 function parseAnnotatedSrtCues(content: string): AnnotatedSubtitleCue[] {
@@ -138,7 +152,13 @@ export function parseSrtCues(content: string): SubtitleCue[] {
 const ASS_TIMING_PATTERN = /^(\d+):(\d{2}):(\d{2})\.(\d{1,2})$/;
 const ASS_FORMAT_PREFIX = 'Format:';
 const ASS_DIALOGUE_PREFIX = 'Dialogue:';
+const ASS_COMMENT_PREFIX = 'Comment:';
 const ASS_NAME_FIELD_ALIASES = ['name', 'actor'];
+const CANONICAL_MATCH_MARGIN_SECONDS = 1;
+const MIN_CANONICAL_ANIMATION_EVENTS = 3;
+// A tiny animated fragment can itself be composed from still smaller glyph events. It is
+// not enough evidence that the fragment represents an authored line boundary.
+const MIN_CANONICAL_DIALOGUE_TEXT_LENGTH = 4;
 
 function parseAssTimestamp(raw: string): number | null {
   const match = ASS_TIMING_PATTERN.exec(raw.trim());
@@ -166,10 +186,333 @@ function findFieldIndex(formatFields: string[], aliases: string[]): number {
   return -1;
 }
 
-function parseAnnotatedAssCues(content: string): AnnotatedSubtitleCue[] {
+interface ParsedAssEvents {
+  dialogue: AnnotatedSubtitleCue[];
+  comments: AnnotatedSubtitleCue[];
+}
+
+// Every candidate line re-reads the compacted text of each event in its window, so on
+// fragment-heavy scripts the same event compacts thousands of times without this cache.
+const compactMatchTextCache = new WeakMap<AnnotatedSubtitleCue, string>();
+
+function compactAssMatchText(text: string): string {
+  return text.replace(/\s+/gu, '');
+}
+
+function compactCueMatchText(cue: AnnotatedSubtitleCue): string {
+  let compact = compactMatchTextCache.get(cue);
+  if (compact === undefined) {
+    compact = compactAssMatchText(cue.text);
+    compactMatchTextCache.set(cue, compact);
+  }
+  return compact;
+}
+
+function assEventGroupKey(cue: AnnotatedSubtitleCue): string {
+  return `${cue.style}\0${cue.name}`;
+}
+
+/**
+ * Windowed lookup over one style/name group. Every candidate line queries its time
+ * neighborhood, and fragment-heavy scripts put thousands of candidates in one group, so
+ * a linear rescan per candidate is quadratic in practice. Events are sorted by start
+ * once; `prefixMaxEnd` lets the backward walk stop as soon as no earlier event can still
+ * reach the window.
+ */
+interface AssEventGroupIndex {
+  byStart: AnnotatedSubtitleCue[];
+  prefixMaxEnd: number[];
+}
+
+function buildAssEventGroupIndex(events: readonly AnnotatedSubtitleCue[]): AssEventGroupIndex {
+  const byStart = [...events].sort((a, b) => a.startTime - b.startTime || a.order - b.order);
+  const prefixMaxEnd: number[] = [];
+  let maxEnd = -Infinity;
+  for (const event of byStart) {
+    maxEnd = Math.max(maxEnd, event.endTime);
+    prefixMaxEnd.push(maxEnd);
+  }
+  return { byStart, prefixMaxEnd };
+}
+
+/** Group events overlapping `[startTime, endTime]`, returned in source order. */
+function eventsOverlappingWindow(
+  index: AssEventGroupIndex,
+  startTime: number,
+  endTime: number,
+): AnnotatedSubtitleCue[] {
+  const { byStart, prefixMaxEnd } = index;
+  let low = 0;
+  let high = byStart.length;
+  while (low < high) {
+    const mid = (low + high) >>> 1;
+    if (byStart[mid]!.startTime <= endTime) {
+      low = mid + 1;
+    } else {
+      high = mid;
+    }
+  }
+  const matches: AnnotatedSubtitleCue[] = [];
+  for (let i = low - 1; i >= 0 && prefixMaxEnd[i]! >= startTime; i -= 1) {
+    if (byStart[i]!.endTime >= startTime) {
+      matches.push(byStart[i]!);
+    }
+  }
+  return matches.sort((a, b) => a.order - b.order);
+}
+
+interface FragmentGroup {
+  text: string;
+  events: AnnotatedSubtitleCue[];
+}
+
+function fragmentPlacementAnchors(event: AnnotatedSubtitleCue): Set<string> {
+  const anchors = new Set<string>();
+  for (const command of event.overrides) {
+    const name = command.name.toLowerCase();
+    const args = command.args.split(',').map((value) => value.trim());
+    if (name === 'pos' && args.length >= 2) {
+      anchors.add(`pos:${args[0]},${args[1]}`);
+    } else if (name === 'move' && args.length >= 4) {
+      anchors.add(`move:${args[0]},${args[1]}`);
+      anchors.add(`move:${args[2]},${args[3]}`);
+    }
+  }
+  return anchors;
+}
+
+function isRepeatedFragmentCopy(
+  previous: AnnotatedSubtitleCue,
+  current: AnnotatedSubtitleCue,
+): boolean {
+  const previousAnchors = fragmentPlacementAnchors(previous);
+  if ([...fragmentPlacementAnchors(current)].some((anchor) => previousAnchors.has(anchor))) {
+    return true;
+  }
+  return (
+    previous.startTime === current.startTime &&
+    previous.endTime === current.endTime &&
+    previous.overrideSignature === current.overrideSignature
+  );
+}
+
+function groupConsecutiveAssFragments(events: readonly AnnotatedSubtitleCue[]): FragmentGroup[] {
+  const groups: FragmentGroup[] = [];
+  for (const event of events) {
+    const text = compactCueMatchText(event);
+    if (!text) {
+      continue;
+    }
+    const previous = groups.at(-1);
+    if (
+      previous?.text === text &&
+      previous.events.some((previousEvent) => isRepeatedFragmentCopy(previousEvent, event))
+    ) {
+      previous.events.push(event);
+    } else {
+      groups.push({ text, events: [event] });
+    }
+  }
+  return groups;
+}
+
+function findCanonicalFragmentEvents(
+  events: readonly AnnotatedSubtitleCue[],
+  canonicalText: string,
+): AnnotatedSubtitleCue[] {
+  const groups = groupConsecutiveAssFragments(events);
+  const matches = new Set<AnnotatedSubtitleCue>();
+
+  for (let start = 0; start < groups.length; start += 1) {
+    let combined = '';
+    for (let end = start; end < groups.length; end += 1) {
+      const group = groups[end]!;
+      // A complete rendered copy cannot prove that the neighboring events are its
+      // fragments. Exact full-line animation is handled separately for comments.
+      if (group.text.length >= canonicalText.length) {
+        break;
+      }
+      const next = combined + group.text;
+      if (!canonicalText.startsWith(next)) {
+        break;
+      }
+      combined = next;
+      if (combined !== canonicalText) {
+        continue;
+      }
+      for (let index = start; index <= end; index += 1) {
+        for (const event of groups[index]!.events) {
+          matches.add(event);
+        }
+      }
+      start = end;
+      break;
+    }
+  }
+
+  return [...matches];
+}
+
+function matchingAssAnimationEvents(options: {
+  candidate: AnnotatedSubtitleCue;
+  group: AssEventGroupIndex;
+  allowFullLineFrames: boolean;
+}): AnnotatedSubtitleCue[] {
+  const canonicalText = compactCueMatchText(options.candidate);
+  // The group index already restricts to the candidate's style and name.
+  const nearby = eventsOverlappingWindow(
+    options.group,
+    options.candidate.startTime - CANONICAL_MATCH_MARGIN_SECONDS,
+    options.candidate.endTime + CANONICAL_MATCH_MARGIN_SECONDS,
+  );
+  const fragments = findCanonicalFragmentEvents(nearby, canonicalText);
+  if (fragments.length >= MIN_CANONICAL_ANIMATION_EVENTS && hasAssAnimationEvidence(fragments)) {
+    return fragments;
+  }
+
+  if (!options.allowFullLineFrames) {
+    return [];
+  }
+  const fullLineFrames = nearby.filter((cue) => compactCueMatchText(cue) === canonicalText);
+  return fullLineFrames.length >= MIN_CANONICAL_ANIMATION_EVENTS &&
+    hasAssAnimationEvidence(fullLineFrames)
+    ? fullLineFrames
+    : [];
+}
+
+// Reductions rather than `Math.min(...events)`: one generated line can carry an
+// unbounded number of events, and spreading them all as arguments risks the engine's
+// argument-count limit.
+function earliestStartTime(events: readonly AnnotatedSubtitleCue[], seed = Infinity): number {
+  return events.reduce((earliest, event) => Math.min(earliest, event.startTime), seed);
+}
+
+function latestEndTime(events: readonly AnnotatedSubtitleCue[], seed = -Infinity): number {
+  return events.reduce((latest, event) => Math.max(latest, event.endTime), seed);
+}
+
+function includeCanonicalBoundaryEvents(options: {
+  candidate: AnnotatedSubtitleCue;
+  group: AssEventGroupIndex;
+  animationEvents: readonly AnnotatedSubtitleCue[];
+}): AnnotatedSubtitleCue[] {
+  const canonicalText = compactCueMatchText(options.candidate);
+  const startTime = earliestStartTime(options.animationEvents);
+  const endTime = latestEndTime(options.animationEvents);
+  return eventsOverlappingWindow(
+    options.group,
+    startTime - CANONICAL_MATCH_MARGIN_SECONDS,
+    endTime + CANONICAL_MATCH_MARGIN_SECONDS,
+  ).filter((cue) => compactCueMatchText(cue) === canonicalText);
+}
+
+function recoverCanonicalAssEvents({
+  dialogue,
+  comments,
+}: ParsedAssEvents): AnnotatedSubtitleCue[] {
+  const recovered: AnnotatedSubtitleCue[] = [];
+  const suppressed = new Set<AnnotatedSubtitleCue>();
+  // A recovery is only as good as its owning event. When a later candidate proves that
+  // an earlier candidate was itself a generated frame of its animation, the earlier
+  // recovery is a duplicate of the same authored line and must be withdrawn.
+  const recoveredByOwner = new Map<AnnotatedSubtitleCue, AnnotatedSubtitleCue>();
+  const withdrawn = new Set<AnnotatedSubtitleCue>();
+  const eventsByGroup = new Map<string, AnnotatedSubtitleCue[]>();
+  for (const cue of dialogue) {
+    const key = assEventGroupKey(cue);
+    const group = eventsByGroup.get(key);
+    if (group) {
+      group.push(cue);
+    } else {
+      eventsByGroup.set(key, [cue]);
+    }
+  }
+  const indexByGroup = new Map<string, AssEventGroupIndex>();
+  for (const [key, events] of eventsByGroup) {
+    indexByGroup.set(key, buildAssEventGroupIndex(events));
+  }
+  const emptyGroupIndex: AssEventGroupIndex = { byStart: [], prefixMaxEnd: [] };
+  const candidates = [
+    ...comments.map((cue) => ({ cue, kind: 'comment' as const })),
+    ...dialogue
+      .filter(
+        (cue) =>
+          compactCueMatchText(cue).length >= MIN_CANONICAL_DIALOGUE_TEXT_LENGTH &&
+          hasAssAnimationEvidence([cue]),
+      )
+      .sort((left, right) => right.text.length - left.text.length || left.order - right.order)
+      .map((cue) => ({ cue, kind: 'dialogue' as const })),
+  ];
+
+  for (const { cue: candidate, kind } of candidates) {
+    if (candidate.endTime <= candidate.startTime || suppressed.has(candidate)) {
+      continue;
+    }
+    const canonicalText = compactCueMatchText(candidate);
+    if (!canonicalText) {
+      continue;
+    }
+
+    const group = indexByGroup.get(assEventGroupKey(candidate)) ?? emptyGroupIndex;
+    const animationEvents = matchingAssAnimationEvents({
+      candidate,
+      group,
+      allowFullLineFrames: kind === 'comment',
+    });
+    if (animationEvents.length === 0) {
+      continue;
+    }
+
+    const boundaryEvents = includeCanonicalBoundaryEvents({
+      candidate,
+      group,
+      animationEvents,
+    });
+    const generatedEvents = [...new Set([...animationEvents, ...boundaryEvents])];
+    const animationStartTime = earliestStartTime(generatedEvents, candidate.startTime);
+    const animationEndTime = latestEndTime(generatedEvents, candidate.endTime);
+    const startTime = kind === 'comment' ? candidate.startTime : animationStartTime;
+    const endTime = kind === 'comment' ? candidate.endTime : animationEndTime;
+    const recoveredCue: AnnotatedSubtitleCue = {
+      ...candidate,
+      startTime,
+      endTime,
+      animationStartTime,
+      animationEndTime,
+      source: 'canonical-ass',
+    };
+    recovered.push(recoveredCue);
+    recoveredByOwner.set(candidate, recoveredCue);
+    for (const event of generatedEvents) {
+      suppressed.add(event);
+      if (event === candidate) {
+        continue;
+      }
+      const priorRecovery = recoveredByOwner.get(event);
+      if (priorRecovery) {
+        // No text is lost by withdrawing: a fragment claim means the withdrawn line is
+        // a contiguous piece of this candidate's text, and a boundary claim means the
+        // texts are equal, so the surviving canonical cue always contains it.
+        withdrawn.add(priorRecovery);
+      }
+    }
+  }
+
+  const survivingRecovered = recovered.filter((cue) => !withdrawn.has(cue));
+  if (survivingRecovered.length === 0) {
+    return dialogue;
+  }
+  return [...dialogue.filter((cue) => !suppressed.has(cue)), ...survivingRecovered].sort(
+    (a, b) => a.startTime - b.startTime || a.endTime - b.endTime || a.order - b.order,
+  );
+}
+
+function parseAnnotatedAssEvents(content: string): ParsedAssEvents {
   const cues: AnnotatedSubtitleCue[] = [];
+  const comments: AnnotatedSubtitleCue[] = [];
   const lines = content.split(/\r?\n/);
   let inEventsSection = false;
+  let eventOrder = 0;
   const fieldIndex = {
     start: -1,
     end: -1,
@@ -222,7 +565,12 @@ function parseAnnotatedAssCues(content: string): AnnotatedSubtitleCue[] {
       continue;
     }
 
-    if (!trimmed.startsWith(ASS_DIALOGUE_PREFIX)) {
+    const eventPrefix = trimmed.startsWith(ASS_DIALOGUE_PREFIX)
+      ? ASS_DIALOGUE_PREFIX
+      : trimmed.startsWith(ASS_COMMENT_PREFIX)
+        ? ASS_COMMENT_PREFIX
+        : null;
+    if (!eventPrefix) {
       continue;
     }
 
@@ -230,7 +578,7 @@ function parseAnnotatedAssCues(content: string): AnnotatedSubtitleCue[] {
       continue;
     }
 
-    const fields = trimmed.slice(ASS_DIALOGUE_PREFIX.length).split(',');
+    const fields = trimmed.slice(eventPrefix.length).split(',');
     if (
       fieldIndex.start >= fields.length ||
       fieldIndex.end >= fields.length ||
@@ -254,7 +602,7 @@ function parseAnnotatedAssCues(content: string): AnnotatedSubtitleCue[] {
     const effect = readField(fields, fieldIndex.effect);
     const layer = Number(readField(fields, fieldIndex.layer));
     const overrides = collectAssOverrideCommands(rawText);
-    cues.push({
+    const cue: AnnotatedSubtitleCue = {
       startTime,
       endTime,
       text,
@@ -266,11 +614,21 @@ function parseAnnotatedAssCues(content: string): AnnotatedSubtitleCue[] {
       effectKind: parseAssEffectField(effect),
       overrides,
       overrideSignature: assOverrideSignature(overrides),
-      order: cues.length,
-    });
+      order: eventOrder,
+    };
+    eventOrder += 1;
+    if (eventPrefix === ASS_COMMENT_PREFIX) {
+      comments.push(cue);
+    } else {
+      cues.push(cue);
+    }
   }
 
-  return cues;
+  return { dialogue: cues, comments };
+}
+
+function parseAnnotatedAssCues(content: string): AnnotatedSubtitleCue[] {
+  return recoverCanonicalAssEvents(parseAnnotatedAssEvents(content));
 }
 
 export function parseAssCues(content: string): SubtitleCue[] {

src/core/services/subtitle-line-dedup-gate.ts

@@ -15,7 +15,7 @@
  *    layer that keeps the two views consistent by construction.
  * 2. Otherwise (embedded track nobody parsed, a source whose timings mpv has shifted)
  *    fall back to timing alone. No authoring metadata is available live -- mpv delivers
- *    `sub-text-ass` after `sub-start`/`sub-end`, so any ASS text read here belongs to the
+ *    `sub-text/ass` after `sub-start`/`sub-end`, so any ASS text read here belongs to the
  *    previous event -- which puts this layer in the same position as the SRT path in
  *    `subtitle-cue-dedup`, and it uses that path's deliberately strict bounds.
  */

src/main-entry-runtime.test.ts

@@ -24,10 +24,17 @@ import {
   shouldForwardStartupArgvViaAppControl,
   applyBackgroundBootstrapCommandLineSwitches,
   applyEarlyLinuxCommandLineSwitches,
+  resolveAppControlHandoffTimeoutMs,
   resolveLinuxPasswordStoreValue,
   spawnDetachedApp,
 } from './main-entry-runtime';
 
+test('app-control handoffs allow for macOS application activation latency', () => {
+  assert.equal(resolveAppControlHandoffTimeoutMs('darwin'), 3000);
+  assert.equal(resolveAppControlHandoffTimeoutMs('linux'), 500);
+  assert.equal(resolveAppControlHandoffTimeoutMs('win32'), 500);
+});
+
 test('detached app launch policy stays in the startup runtime utilities', () => {
   const entrySource = fs.readFileSync(path.join(process.cwd(), 'src/main-entry.ts'), 'utf8');
   const runtimeSource = fs.readFileSync(

src/main-entry-runtime.ts

@@ -14,6 +14,8 @@ const TRANSPORTED_APP_ARGC_ENV = 'SUBMINER_APP_ARGC';
 const TRANSPORTED_APP_ARG_PREFIX = 'SUBMINER_APP_ARG_';
 const MAX_TRANSPORTED_APP_ARGS = 256;
 const APP_NAME = 'SubMiner';
+const DEFAULT_APP_CONTROL_HANDOFF_TIMEOUT_MS = 500;
+const MACOS_APP_CONTROL_HANDOFF_TIMEOUT_MS = 3000;
 const MPV_LONG_OPTIONS_WITH_SEPARATE_VALUES = new Set([
   '--alang',
   '--audio-file',
@@ -186,6 +188,14 @@ export function shouldForwardStartupArgvViaAppControl(
   return hasExplicitCommand(args);
 }
 
+export function resolveAppControlHandoffTimeoutMs(
+  platform: NodeJS.Platform = process.platform,
+): number {
+  return platform === 'darwin'
+    ? MACOS_APP_CONTROL_HANDOFF_TIMEOUT_MS
+    : DEFAULT_APP_CONTROL_HANDOFF_TIMEOUT_MS;
+}
+
 function readTransportedStartupArgs(env: NodeJS.ProcessEnv): string[] | null {
   const rawCount = env[TRANSPORTED_APP_ARGC_ENV];
   if (rawCount === undefined) {

src/main-entry.ts

@@ -9,6 +9,7 @@ import {
   normalizeLaunchMpvTargets,
   normalizeStartupArgv,
   applyEarlyLinuxCommandLineSwitches,
+  resolveAppControlHandoffTimeoutMs,
   sanitizeStartupEnv,
   sanitizeBackgroundEnv,
   sanitizeHelpEnv,
@@ -214,7 +215,7 @@ async function forwardStartupArgvViaAppControlIfAvailable(): Promise<boolean> {
 
   const result = await sendAppControlCommand(process.argv, {
     configDir: userDataPath,
-    timeoutMs: 500,
+    timeoutMs: resolveAppControlHandoffTimeoutMs(),
   });
   if (result.ok) {
     app.exit(0);

src/main.ts

@@ -235,6 +235,7 @@ import {
   createCycleSecondarySubModeRuntimeHandler,
 } from './main/runtime/domains/mpv';
 import { buildSubtitleTrackDiagnostics } from './main/runtime/mpv-track-diagnostics';
+import { resolveCanonicalPrimarySubtitle } from './main/runtime/primary-subtitle-text';
 import {
   createBuildCopyCurrentSubtitleMainDepsHandler,
   createBuildHandleMineSentenceDigitMainDepsHandler,
@@ -331,6 +332,7 @@ import {
   acquireYoutubeSubtitleTrack,
   acquireYoutubeSubtitleTracks,
 } from './core/services/youtube/generate';
+import { applyOverlayClickThrough } from './core/services/overlay-click-through';
 import { createYoutubeMediaCacheService } from './core/services/youtube/media-cache';
 import { resolveYoutubePlaybackUrl } from './core/services/youtube/playback-resolve';
 import { probeYoutubeTracks } from './core/services/youtube/track-probe';
@@ -462,10 +464,6 @@ import { createMainBootServices, type MainBootServicesResult } from './main/boot
 import { handleCliCommandRuntimeServiceWithContext } from './main/cli-runtime';
 import { createOverlayModalRuntimeService } from './main/overlay-runtime';
 import { createOverlayModalInputState } from './main/runtime/overlay-modal-input-state';
-import { MediaTimingPreviewSession } from './core/services/media-timing-preview';
-import { generateSpeechWaveform } from './core/services/media-timing-waveform';
-import { createMediaTimingReviewRuntime } from './main/runtime/media-timing-review';
-import { openMediaTimingReviewModal } from './main/runtime/media-timing-review-open';
 import { openYoutubeTrackPicker } from './main/runtime/youtube-picker-open';
 import { openRuntimeOptionsModal as openRuntimeOptionsModalRuntime } from './main/runtime/runtime-options-open';
 import { openJimakuModal as openJimakuModalRuntime } from './main/runtime/jimaku-open';
@@ -1809,10 +1807,42 @@ async function openYoutubeTrackPickerFromPlayback(): Promise<void> {
 let appTray: Tray | null = null;
 let tokenizeSubtitleDeferred: ((text: string) => Promise<SubtitleData>) | null = null;
 function withCurrentSubtitleTiming(payload: SubtitleData): SubtitleData {
+  const canonical = resolveCanonicalPrimarySubtitle({
+    liveText: payload.text,
+    currentTimeSec: Number(appState.mpvClient?.currentTimePos),
+    cues: appState.activeParsedSubtitleCues,
+  });
   return {
     ...payload,
-    startTime: appState.mpvClient?.currentSubStart ?? null,
-    endTime: appState.mpvClient?.currentSubEnd ?? null,
+    startTime: canonical?.startTime ?? appState.mpvClient?.currentSubStart ?? null,
+    endTime: canonical?.endTime ?? appState.mpvClient?.currentSubEnd ?? null,
+  };
+}
+
+function captureCurrentPrimarySubtitleMiningContext(): SubtitleMiningContext | null {
+  const canonical = resolveCanonicalPrimarySubtitle({
+    liveText: appState.mpvClient?.currentSubText ?? '',
+    currentTimeSec: Number(appState.mpvClient?.currentTimePos),
+    cues: appState.activeParsedSubtitleCues,
+  });
+  // Same validity bar as the live capture path: an unusable canonical span must fall
+  // back rather than hand mining an empty line or an inverted range.
+  const canonicalText = canonical?.text.trim();
+  if (
+    !canonical ||
+    !canonicalText ||
+    !Number.isFinite(canonical.startTime) ||
+    !Number.isFinite(canonical.endTime) ||
+    canonical.endTime <= canonical.startTime
+  ) {
+    return captureLiveSubtitleMiningContext(appState.mpvClient);
+  }
+  return {
+    source: 'overlay',
+    text: canonicalText,
+    startTime: canonical.startTime,
+    endTime: canonical.endTime,
+    capturedAtMs: Date.now(),
   };
 }
 function emitSubtitlePayload(payload: SubtitleData, options?: { resumePrefetch?: boolean }): void {
@@ -2801,19 +2831,6 @@ function createOverlayHostedModalOpenDeps(): {
   };
 }
 
-const mediaTimingReviewRuntime = createMediaTimingReviewRuntime({
-  getMpvClient: () => appState.mpvClient,
-  getCurrentMediaPath: () =>
-    appState.currentMediaPath?.trim() || appState.mpvClient?.currentVideoPath?.trim() || null,
-  getMpvExecutablePath: () =>
-    configService.getConfig().mpv.executablePath || process.env.SUBMINER_MPV_PATH?.trim() || '',
-  createPreviewSession: () => new MediaTimingPreviewSession(),
-  generateWaveform: (options) => generateSpeechWaveform(options),
-  openModal: (payload) => openMediaTimingReviewModal(createOverlayHostedModalOpenDeps(), payload),
-  showStatus: (message) =>
-    overlayNotificationsRuntime.showConfiguredStatusNotification(message, { variant: 'warning' }),
-});
-
 function openOverlayHostedModalWithOsd(
   openModal: (deps: ReturnType<typeof createOverlayHostedModalOpenDeps>) => Promise<boolean>,
   unavailableMessage: string,
@@ -5026,12 +5043,14 @@ function syncLinuxVisibleOverlayMpvFullscreenMode(fullscreen: boolean): void {
 
 function initializeOverlayRuntime(): void {
   initializeOverlayRuntimeHandler();
+  if (!(appState.initialArgs && isHeadlessInitialCommand(appState.initialArgs))) {
+    overlayModalRuntime.primeModalWindow();
+  }
   appState.ankiIntegration?.setRecordCardsMinedCallback(recordTrackedCardsMined);
   appState.ankiIntegration?.setKnownWordCacheUpdatedCallback(
     refreshCurrentSubtitleAfterKnownWordUpdate,
   );
   appState.ankiIntegration?.setSubtitleMiningContextConsumer(consumePendingSubtitleMiningContext);
-  appState.ankiIntegration?.setMediaTimingReviewCallback(mediaTimingReviewRuntime.requestReview);
   syncOverlayMpvSubtitleSuppression();
 }
 
@@ -5245,6 +5264,7 @@ const markLastCardAsAudioCardHandler = createMarkLastCardAsAudioCardHandler(
 const buildMineSentenceCardMainDepsHandler = createBuildMineSentenceCardMainDepsHandler({
   getAnkiIntegration: () => appState.ankiIntegration,
   getMpvClient: () => appState.mpvClient,
+  getPrimarySubtitle: () => captureCurrentPrimarySubtitleMiningContext(),
   showMpvOsd: (text) => overlayNotificationsRuntime.showConfiguredStatusNotification(text),
   mineSentenceCardCore,
   recordCardsMined: (count, noteIds) => {
@@ -5441,10 +5461,6 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
       showMpvOsd: (text: string) => showConfiguredPlaybackFeedback(text),
     },
     mainDeps: {
-      previewMediaTimingReview: (request) => mediaTimingReviewRuntime.previewRange(request),
-      getMediaTimingReviewWaveform: (request) => mediaTimingReviewRuntime.getWaveform(request),
-      stopMediaTimingReviewPreview: (reviewId) => mediaTimingReviewRuntime.stopPreview(reviewId),
-      resolveMediaTimingReview: (request) => mediaTimingReviewRuntime.resolveReview(request),
       getMainWindow: () => overlayManager.getMainWindow(),
       getVisibleOverlayVisibility: () => overlayManager.getVisibleOverlayVisible(),
       focusMainWindow: () => {
@@ -5478,9 +5494,6 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
         }
       },
       onOverlayModalClosed: (modal, senderWindow) => {
-        if (modal === 'media-timing-review') {
-          void mediaTimingReviewRuntime.dispose();
-        }
         if (modal === 'subtitle-sidebar' && senderWindow === overlayManager.getMainWindow()) {
           subtitleSidebarRequestedOpen = false;
         }
@@ -5491,7 +5504,7 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
           senderWindow === modalWindow &&
           !senderWindow.isDestroyed()
         ) {
-          senderWindow.setIgnoreMouseEvents(true, { forward: true });
+          applyOverlayClickThrough(senderWindow);
           senderWindow.hide();
         }
         handleOverlayModalClosedHandler(modal);
@@ -5565,9 +5578,7 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
       // live mpv sub timings at lookup time so media generation clips the mined line even
       // when extraction finishes long after playback has moved on.
       recordSubtitleMiningContext: (context) =>
-        recordSubtitleMiningContext(
-          context ?? captureLiveSubtitleMiningContext(appState.mpvClient),
-        ),
+        recordSubtitleMiningContext(context ?? captureCurrentPrimarySubtitleMiningContext()),
       quitApp: () => requestAppQuit(),
       toggleVisibleOverlay: () => toggleVisibleOverlay(),
       tokenizeCurrentSubtitle: async () => {
@@ -5836,9 +5847,6 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
         appState.ankiIntegration?.setSubtitleMiningContextConsumer(
           consumePendingSubtitleMiningContext,
         );
-        appState.ankiIntegration?.setMediaTimingReviewCallback(
-          mediaTimingReviewRuntime.requestReview,
-        );
       },
       getKnownWordCacheStatePath: () => path.join(USER_DATA_PATH, 'known-words-cache.json'),
       getCachedMediaPath: (currentVideoPath, kind) =>
@@ -6161,7 +6169,6 @@ const { createMainWindow: createMainWindowHandler, createModalWindow: createModa
           if (overlayManager.getModalWindow() !== window) {
             return;
           }
-          void mediaTimingReviewRuntime.dispose();
           overlayManager.setModalWindow(null);
         }
       },

src/main/dependencies.ts

@@ -62,10 +62,6 @@ export interface MainIpcRuntimeServiceDepsParams {
   onOverlayInteractiveHint?: IpcDepsRuntimeOptions['onOverlayInteractiveHint'];
   handleOverlayNotificationAction?: IpcDepsRuntimeOptions['handleOverlayNotificationAction'];
   onYoutubePickerResolve: IpcDepsRuntimeOptions['onYoutubePickerResolve'];
-  previewMediaTimingReview?: IpcDepsRuntimeOptions['previewMediaTimingReview'];
-  getMediaTimingReviewWaveform?: IpcDepsRuntimeOptions['getMediaTimingReviewWaveform'];
-  stopMediaTimingReviewPreview?: IpcDepsRuntimeOptions['stopMediaTimingReviewPreview'];
-  resolveMediaTimingReview?: IpcDepsRuntimeOptions['resolveMediaTimingReview'];
   openYomitanSettings: IpcDepsRuntimeOptions['openYomitanSettings'];
   quitApp: IpcDepsRuntimeOptions['quitApp'];
   toggleVisibleOverlay: IpcDepsRuntimeOptions['toggleVisibleOverlay'];
@@ -260,10 +256,6 @@ export function createMainIpcRuntimeServiceDeps(
     onOverlayInteractiveHint: params.onOverlayInteractiveHint,
     handleOverlayNotificationAction: params.handleOverlayNotificationAction,
     onYoutubePickerResolve: params.onYoutubePickerResolve,
-    previewMediaTimingReview: params.previewMediaTimingReview,
-    getMediaTimingReviewWaveform: params.getMediaTimingReviewWaveform,
-    stopMediaTimingReviewPreview: params.stopMediaTimingReviewPreview,
-    resolveMediaTimingReview: params.resolveMediaTimingReview,
     openYomitanSettings: params.openYomitanSettings,
     quitApp: params.quitApp,
     toggleVisibleOverlay: params.toggleVisibleOverlay,

src/main/overlay-runtime.test.ts

@@ -16,6 +16,7 @@ type MockWindow = {
   loading: boolean;
   url: string;
   contentReady: boolean;
+  documentLoaded: boolean;
   loadCallbacks: Array<() => void>;
   readyToShowCallbacks: Array<() => void>;
 };
@@ -31,6 +32,7 @@ function createMockWindow(): MockWindow & {
   getShowCount: () => number;
   getHideCount: () => number;
   show: () => void;
+  showInactive: () => void;
   hide: () => void;
   destroy: () => void;
   focus: () => void;
@@ -61,6 +63,7 @@ function createMockWindow(): MockWindow & {
     loading: false,
     url: 'file:///overlay/index.html?layer=modal',
     contentReady: true,
+    documentLoaded: true,
     loadCallbacks: [],
     readyToShowCallbacks: [],
   };
@@ -84,6 +87,10 @@ function createMockWindow(): MockWindow & {
       state.visible = true;
       state.showCount += 1;
     },
+    showInactive: () => {
+      state.visible = true;
+      state.showCount += 1;
+    },
     hide: () => {
       state.visible = false;
       state.hideCount += 1;
@@ -96,6 +103,10 @@ function createMockWindow(): MockWindow & {
       state.focused = true;
     },
     emitDidFinishLoad: () => {
+      state.documentLoaded = true;
+      (
+        window as typeof window & { __subminerOverlayDocumentLoaded?: boolean }
+      ).__subminerOverlayDocumentLoaded = true;
       const callbacks = state.loadCallbacks.splice(0);
       for (const callback of callbacks) {
         callback();
@@ -197,9 +208,22 @@ function createMockWindow(): MockWindow & {
     },
   });
 
+  Object.defineProperty(window, 'documentLoaded', {
+    get: () => state.documentLoaded,
+    set: (value: boolean) => {
+      state.documentLoaded = value;
+      (
+        window as typeof window & { __subminerOverlayDocumentLoaded?: boolean }
+      ).__subminerOverlayDocumentLoaded = value;
+    },
+  });
+
   (
     window as typeof window & { __subminerOverlayContentReady?: boolean }
   ).__subminerOverlayContentReady = state.contentReady;
+  (
+    window as typeof window & { __subminerOverlayDocumentLoaded?: boolean }
+  ).__subminerOverlayDocumentLoaded = state.documentLoaded;
 
   return window;
 }
@@ -259,6 +283,73 @@ test('sendToActiveOverlayWindow creates modal window lazily when absent', () =>
   assert.deepEqual(window.sent, [['jimaku:open']]);
 });
 
+for (const platform of ['darwin', 'win32'] as const) {
+  test(`primeModalWindow creates and warms a hidden modal on ${platform}`, () => {
+    const modalWindow = createMockWindow();
+    modalWindow.loading = true;
+    modalWindow.url = '';
+    modalWindow.contentReady = false;
+    modalWindow.documentLoaded = false;
+    let currentModal: ReturnType<typeof createMockWindow> | null = null;
+    let createCalls = 0;
+    const runtime = createOverlayModalRuntimeService(
+      {
+        getMainWindow: () => null,
+        getModalWindow: () => currentModal as never,
+        createModalWindow: () => {
+          createCalls += 1;
+          currentModal = modalWindow;
+          return modalWindow as never;
+        },
+        getModalGeometry: () => ({ x: 1, y: 2, width: 300, height: 200 }),
+        setModalWindowBounds: () => {},
+      },
+      { platform },
+    );
+
+    assert.equal(runtime.primeModalWindow(), true);
+    assert.equal(createCalls, 1);
+    assert.equal(modalWindow.isVisible(), false);
+
+    modalWindow.loading = false;
+    modalWindow.url = 'file:///overlay/index.html?layer=modal';
+    modalWindow.emitDidFinishLoad();
+    modalWindow.emitReadyToShow();
+    modalWindow.contentReady = true;
+
+    assert.equal(
+      runtime.sendToActiveOverlayWindow('session-help:open', undefined, {
+        restoreOnModalClose: 'session-help',
+        preferModalWindow: true,
+      }),
+      true,
+    );
+    assert.equal(createCalls, 1);
+    assert.equal(modalWindow.isVisible(), true);
+    assert.deepEqual(modalWindow.sent, [['session-help:open']]);
+  });
+}
+
+test('primeModalWindow leaves Linux modal creation lazy', () => {
+  let createCalls = 0;
+  const runtime = createOverlayModalRuntimeService(
+    {
+      getMainWindow: () => null,
+      getModalWindow: () => null,
+      createModalWindow: () => {
+        createCalls += 1;
+        return createMockWindow() as never;
+      },
+      getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
+      setModalWindowBounds: () => {},
+    },
+    { platform: 'linux' },
+  );
+
+  assert.equal(runtime.primeModalWindow(), false);
+  assert.equal(createCalls, 0);
+});
+
 test('sendToActiveOverlayWindow does not retain restore state when modal creation fails', () => {
   const runtime = createOverlayModalRuntimeService({
     getMainWindow: () => null,
@@ -301,7 +392,7 @@ test('sendToActiveOverlayWindow waits for blank modal URL before sending open co
   window.loading = false;
   window.url = 'file:///overlay/index.html?layer=modal';
   window.emitDidFinishLoad();
-  assert.deepEqual(window.sent, []);
+  assert.deepEqual(window.sent, [['runtime-options:open']]);
 
   window.contentReady = true;
   window.emitReadyToShow();
@@ -311,15 +402,18 @@ test('sendToActiveOverlayWindow waits for blank modal URL before sending open co
   assert.equal(window.getShowCount(), 1);
 });
 
-test('handleOverlayModalClosed hides modal window only after all pending modals close', () => {
+test('handleOverlayModalClosed keeps the modal window warm after all pending modals close', () => {
   const window = createMockWindow();
-  const runtime = createOverlayModalRuntimeService({
-    getMainWindow: () => null,
-    getModalWindow: () => window as never,
-    createModalWindow: () => window as never,
-    getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
-    setModalWindowBounds: () => {},
-  });
+  const runtime = createOverlayModalRuntimeService(
+    {
+      getMainWindow: () => null,
+      getModalWindow: () => window as never,
+      createModalWindow: () => window as never,
+      getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
+      setModalWindowBounds: () => {},
+    },
+    { platform: 'darwin' },
+  );
 
   runtime.sendToActiveOverlayWindow('runtime-options:open', undefined, {
     restoreOnModalClose: 'runtime-options',
@@ -342,7 +436,9 @@ test('handleOverlayModalClosed hides modal window only after all pending modals
   assert.equal(window.isDestroyed(), false);
 
   runtime.handleOverlayModalClosed('subsync');
-  assert.equal(window.isDestroyed(), true);
+  assert.equal(window.isDestroyed(), false);
+  assert.equal(window.isVisible(), false);
+  assert.equal(window.ignoreMouseEvents, true);
 });
 
 test('sendToActiveOverlayWindow prefers visible main overlay window for modal open', () => {
@@ -464,6 +560,46 @@ test('modal window path restores visible main overlay before modal input deactiv
   assert.deepEqual(events, ['state:true:visible:true', 'state:false:visible:true']);
 });
 
+test('macOS maps a new modal panel before focusing SubMiner and hiding the subtitle overlay', () => {
+  const mainWindow = createMockWindow();
+  mainWindow.visible = true;
+  const modalWindow = createMockWindow();
+  const events: string[] = [];
+  const showInactive = modalWindow.showInactive;
+  modalWindow.showInactive = () => {
+    events.push('show-inactive');
+    showInactive();
+  };
+  const hideMainWindow = mainWindow.hide;
+  mainWindow.hide = () => {
+    events.push('hide-main');
+    hideMainWindow();
+  };
+  const runtime = createOverlayModalRuntimeService(
+    {
+      getMainWindow: () => mainWindow as never,
+      getModalWindow: () => modalWindow as never,
+      createModalWindow: () => modalWindow as never,
+      getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
+      setModalWindowBounds: () => {},
+    },
+    {
+      platform: 'darwin',
+      focusApplication: () => events.push('focus-application'),
+    },
+  );
+
+  runtime.sendToActiveOverlayWindow('runtime-options:open', undefined, {
+    restoreOnModalClose: 'runtime-options',
+    preferModalWindow: true,
+  });
+  runtime.notifyOverlayModalOpened('runtime-options');
+
+  assert.deepEqual(events, ['show-inactive', 'focus-application', 'hide-main']);
+  assert.equal(modalWindow.isVisible(), true);
+  assert.equal(mainWindow.isVisible(), false);
+});
+
 test('modal window path runs final close handoff before modal input deactivates', () => {
   const mainWindow = createMockWindow();
   mainWindow.visible = true;
@@ -650,15 +786,18 @@ test('handleOverlayModalClosed is a no-op when no modal window can be targeted',
   assert.deepEqual(state, []);
 });
 
-test('handleOverlayModalClosed destroys modal window for single kiku modal', () => {
+test('handleOverlayModalClosed hides and retains modal window for single kiku modal', () => {
   const window = createMockWindow();
-  const runtime = createOverlayModalRuntimeService({
-    getMainWindow: () => null,
-    getModalWindow: () => window as never,
-    createModalWindow: () => window as never,
-    getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
-    setModalWindowBounds: () => {},
-  });
+  const runtime = createOverlayModalRuntimeService(
+    {
+      getMainWindow: () => null,
+      getModalWindow: () => window as never,
+      createModalWindow: () => window as never,
+      getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
+      setModalWindowBounds: () => {},
+    },
+    { platform: 'darwin' },
+  );
 
   runtime.sendToActiveOverlayWindow(
     'kiku:field-grouping-open',
@@ -669,7 +808,9 @@ test('handleOverlayModalClosed destroys modal window for single kiku modal', ()
   );
   runtime.handleOverlayModalClosed('kiku');
 
-  assert.equal(window.isDestroyed(), true);
+  assert.equal(window.isDestroyed(), false);
+  assert.equal(window.isVisible(), false);
+  assert.equal(window.ignoreMouseEvents, true);
   assert.equal(runtime.getRestoreVisibleOverlayOnModalClose().size, 0);
 });
 
@@ -719,8 +860,10 @@ test('modal fallback reveal skips showing window when content is not ready', asy
   assert.equal(window.ignoreMouseEvents, false);
 });
 
-test('sendToActiveOverlayWindow waits for modal ready-to-show before delivering open event', () => {
+test('sendToActiveOverlayWindow delivers on first modal load without waiting for ready-to-show', () => {
   const window = createMockWindow();
+  window.loading = true;
+  window.url = '';
   window.contentReady = false;
   const runtime = createOverlayModalRuntimeService({
     getMainWindow: () => null,
@@ -738,16 +881,100 @@ test('sendToActiveOverlayWindow waits for modal ready-to-show before delivering
 
   assert.equal(sent, true);
   assert.deepEqual(window.sent, []);
+  window.loading = false;
+  window.url = 'file:///overlay/index.html?layer=modal';
   window.emitDidFinishLoad();
-  assert.deepEqual(window.sent, []);
+  assert.deepEqual(window.sent, [['runtime-options:open']]);
 
   window.contentReady = true;
   window.emitReadyToShow();
   assert.deepEqual(window.sent, [['runtime-options:open']]);
 });
 
+test('sendToActiveOverlayWindow delivers when the modal loaded before listeners were registered', () => {
+  const window = createMockWindow();
+  window.contentReady = false;
+  const runtime = createOverlayModalRuntimeService({
+    getMainWindow: () => null,
+    getModalWindow: () => window as never,
+    createModalWindow: () => {
+      throw new Error('modal window should not be created when already present');
+    },
+    getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
+    setModalWindowBounds: () => {},
+  });
+
+  assert.equal(
+    runtime.sendToActiveOverlayWindow('runtime-options:open', undefined, {
+      restoreOnModalClose: 'runtime-options',
+    }),
+    true,
+  );
+  assert.deepEqual(window.sent, [['runtime-options:open']]);
+
+  window.contentReady = true;
+  window.emitReadyToShow();
+  assert.deepEqual(window.sent, [['runtime-options:open']]);
+});
+
+test('sendToActiveOverlayWindow does not infer document readiness from a pending file URL', () => {
+  const window = createMockWindow();
+  window.contentReady = false;
+  window.documentLoaded = false;
+  window.loading = false;
+  const runtime = createOverlayModalRuntimeService({
+    getMainWindow: () => null,
+    getModalWindow: () => window as never,
+    createModalWindow: () => {
+      throw new Error('modal window should not be created when already present');
+    },
+    getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
+    setModalWindowBounds: () => {},
+  });
+
+  assert.equal(
+    runtime.sendToActiveOverlayWindow('runtime-options:open', undefined, {
+      restoreOnModalClose: 'runtime-options',
+    }),
+    true,
+  );
+  assert.deepEqual(window.sent, []);
+
+  window.emitDidFinishLoad();
+  assert.deepEqual(window.sent, [['runtime-options:open']]);
+});
+
+test('sendToActiveOverlayWindow rejects stale content readiness during document reload', () => {
+  const window = createMockWindow();
+  window.contentReady = true;
+  window.documentLoaded = false;
+  window.loading = false;
+  const runtime = createOverlayModalRuntimeService({
+    getMainWindow: () => null,
+    getModalWindow: () => window as never,
+    createModalWindow: () => {
+      throw new Error('modal window should not be created when already present');
+    },
+    getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
+    setModalWindowBounds: () => {},
+  });
+
+  assert.equal(
+    runtime.sendToActiveOverlayWindow('session-help:open', undefined, {
+      restoreOnModalClose: 'session-help',
+    }),
+    true,
+  );
+  assert.deepEqual(window.sent, []);
+
+  window.emitDidFinishLoad();
+  assert.deepEqual(window.sent, [['session-help:open']]);
+});
+
 test('sendToActiveOverlayWindow flushes every queued load and ready listener before sending', () => {
   const window = createMockWindow();
+  window.loading = true;
+  window.url = '';
   window.contentReady = false;
   const runtime = createOverlayModalRuntimeService({
     getMainWindow: () => null,
@@ -773,29 +1000,73 @@ test('sendToActiveOverlayWindow flushes every queued load and ready listener bef
   );
   assert.deepEqual(window.sent, []);
 
+  window.loading = false;
+  window.url = 'file:///overlay/index.html?layer=modal';
   window.emitDidFinishLoad();
-  assert.deepEqual(window.sent, []);
+  assert.deepEqual(window.sent, [['runtime-options:open'], ['session-help:open']]);
 
   window.contentReady = true;
   window.emitReadyToShow();
   assert.deepEqual(window.sent, [['runtime-options:open'], ['session-help:open']]);
 });
 
-test('modal reopen creates a fresh window after close destroys the previous one', () => {
-  const firstWindow = createMockWindow();
-  const secondWindow = createMockWindow();
-  let currentModal: ReturnType<typeof createMockWindow> | null = firstWindow;
+test('modal reopen reuses the warm window and shows it immediately on macOS', () => {
+  const modalWindow = createMockWindow();
+  let createCalls = 0;
 
-  const runtime = createOverlayModalRuntimeService({
-    getMainWindow: () => null,
-    getModalWindow: () => currentModal as never,
-    createModalWindow: () => {
-      currentModal = secondWindow;
-      return secondWindow as never;
+  const runtime = createOverlayModalRuntimeService(
+    {
+      getMainWindow: () => null,
+      getModalWindow: () => modalWindow as never,
+      createModalWindow: () => {
+        createCalls += 1;
+        return modalWindow as never;
+      },
+      getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
+      setModalWindowBounds: () => {},
     },
-    getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
-    setModalWindowBounds: () => {},
+    { platform: 'darwin' },
+  );
+
+  runtime.sendToActiveOverlayWindow('runtime-options:open', undefined, {
+    restoreOnModalClose: 'runtime-options',
   });
+  runtime.notifyOverlayModalOpened('runtime-options');
+  runtime.handleOverlayModalClosed('runtime-options');
+
+  assert.equal(modalWindow.isDestroyed(), false);
+  assert.equal(modalWindow.isVisible(), false);
+
+  const sent = runtime.sendToActiveOverlayWindow('runtime-options:open', undefined, {
+    restoreOnModalClose: 'runtime-options',
+  });
+
+  assert.equal(sent, true);
+  assert.equal(createCalls, 0);
+  assert.equal(modalWindow.isVisible(), true);
+  assert.equal(modalWindow.getShowCount(), 2);
+});
+
+test('modal reopen on Windows uses a fresh prewarmed interactive window', () => {
+  const firstWindow = createMockWindow();
+  const replacementWindow = createMockWindow();
+  let currentModal = firstWindow;
+  let createCalls = 0;
+
+  const runtime = createOverlayModalRuntimeService(
+    {
+      getMainWindow: () => null,
+      getModalWindow: () => currentModal as never,
+      createModalWindow: () => {
+        createCalls += 1;
+        currentModal = replacementWindow;
+        return replacementWindow as never;
+      },
+      getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
+      setModalWindowBounds: () => {},
+    },
+    { platform: 'win32' },
+  );
 
   runtime.sendToActiveOverlayWindow('runtime-options:open', undefined, {
     restoreOnModalClose: 'runtime-options',
@@ -804,30 +1075,30 @@ test('modal reopen creates a fresh window after close destroys the previous one'
   runtime.handleOverlayModalClosed('runtime-options');
 
   assert.equal(firstWindow.isDestroyed(), true);
+  assert.equal(currentModal, replacementWindow);
+  assert.equal(replacementWindow.isVisible(), false);
+  assert.equal(createCalls, 1);
 
-  const sent = runtime.sendToActiveOverlayWindow('runtime-options:open', undefined, {
-    restoreOnModalClose: 'runtime-options',
+  const sent = runtime.sendToActiveOverlayWindow('session-help:open', undefined, {
+    restoreOnModalClose: 'session-help',
   });
 
   assert.equal(sent, true);
-  assert.equal(currentModal, secondWindow);
-  assert.equal(secondWindow.getShowCount(), 0);
+  assert.equal(createCalls, 1);
+  assert.equal(replacementWindow.isVisible(), true);
+  assert.equal(replacementWindow.ignoreMouseEvents, false);
+  assert.deepEqual(replacementWindow.sent, [['session-help:open']]);
 });
 
-test('modal reopen after close-destroy notifies state change on fresh window lifecycle', () => {
-  const firstWindow = createMockWindow();
-  const secondWindow = createMockWindow();
-  let currentModal: ReturnType<typeof createMockWindow> | null = firstWindow;
+test('modal reopen on the warm window notifies state change for each lifecycle', () => {
+  const modalWindow = createMockWindow();
   const state: boolean[] = [];
 
   const runtime = createOverlayModalRuntimeService(
     {
       getMainWindow: () => null,
-      getModalWindow: () => currentModal as never,
-      createModalWindow: () => {
-        currentModal = secondWindow;
-        return secondWindow as never;
-      },
+      getModalWindow: () => modalWindow as never,
+      createModalWindow: () => modalWindow as never,
       getModalGeometry: () => ({ x: 0, y: 0, width: 400, height: 300 }),
       setModalWindowBounds: () => {},
     },
@@ -835,6 +1106,7 @@ test('modal reopen after close-destroy notifies state change on fresh window lif
       onModalStateChange: (active: boolean): void => {
         state.push(active);
       },
+      platform: 'darwin',
     },
   );
 
@@ -845,7 +1117,7 @@ test('modal reopen after close-destroy notifies state change on fresh window lif
   runtime.handleOverlayModalClosed('runtime-options');
 
   assert.deepEqual(state, [true, false]);
-  assert.equal(firstWindow.isDestroyed(), true);
+  assert.equal(modalWindow.isDestroyed(), false);
 
   runtime.sendToActiveOverlayWindow('runtime-options:open', undefined, {
     restoreOnModalClose: 'runtime-options',
@@ -853,7 +1125,7 @@ test('modal reopen after close-destroy notifies state change on fresh window lif
   runtime.notifyOverlayModalOpened('runtime-options');
 
   assert.deepEqual(state, [true, false, true]);
-  assert.equal(currentModal, secondWindow);
+  assert.equal(modalWindow.isVisible(), true);
 });
 
 test('visible stale modal window is made interactive again before reopening', () => {

src/main/overlay-runtime.ts

@@ -2,7 +2,11 @@ import type { BrowserWindow } from 'electron';
 import type { OverlayHostedModal } from '../shared/ipc/contracts';
 import type { WindowGeometry } from '../types';
 import type { HyprlandPlacementStatus } from '../core/services/hyprland-window-placement';
-import { OVERLAY_WINDOW_CONTENT_READY_FLAG } from '../core/services/overlay-window-flags';
+import { applyOverlayClickThrough } from '../core/services/overlay-click-through';
+import {
+  OVERLAY_WINDOW_CONTENT_READY_FLAG,
+  OVERLAY_WINDOW_DOCUMENT_LOADED_FLAG,
+} from '../core/services/overlay-window-flags';
 
 const MODAL_REVEAL_FALLBACK_DELAY_MS = 250;
 // The dedicated modal window maps asynchronously on Wayland; a single reconcile can fire
@@ -39,6 +43,7 @@ export interface OverlayWindowResolver {
 }
 
 export interface OverlayModalRuntime {
+  primeModalWindow: () => boolean;
   sendToActiveOverlayWindow: (
     channel: string,
     payload?: unknown,
@@ -59,6 +64,8 @@ export interface OverlayModalRuntime {
 type RevealFallbackHandle = NonNullable<Parameters<typeof globalThis.clearTimeout>[0]>;
 
 export interface OverlayModalRuntimeOptions {
+  platform?: NodeJS.Platform;
+  focusApplication?: () => void;
   onModalStateChange?: (isActive: boolean) => void;
   onFinalModalClosed?: () => void;
   scheduleRevealFallback?: (callback: () => void, delayMs: number) => RevealFallbackHandle;
@@ -79,6 +86,11 @@ export function createOverlayModalRuntimeService(
   let pendingModalWindowReveal: BrowserWindow | null = null;
   let pendingModalWindowRevealTimeout: RevealFallbackHandle | null = null;
   const modalWindowBoundsReconcileGenerations = new WeakMap<BrowserWindow, number>();
+  const modalWindowPrimeListenersRegistered = new WeakSet<BrowserWindow>();
+  const platform = options.platform ?? process.platform;
+  const shouldPrimeModalWindow = platform === 'darwin' || platform === 'win32';
+  const reuseModalWindowAfterClose = platform === 'darwin';
+  const focusApplication = options.focusApplication ?? requestOverlayApplicationFocus;
   const scheduleRevealFallback = (callback: () => void, delayMs: number): RevealFallbackHandle =>
     (options.scheduleRevealFallback ?? globalThis.setTimeout)(callback, delayMs);
   const clearRevealFallback = (timeout: RevealFallbackHandle): void =>
@@ -134,7 +146,11 @@ export function createOverlayModalRuntimeService(
     }
     const overlayWindow = window as BrowserWindow & {
       [OVERLAY_WINDOW_CONTENT_READY_FLAG]?: boolean;
+      [OVERLAY_WINDOW_DOCUMENT_LOADED_FLAG]?: boolean;
     };
+    if (overlayWindow[OVERLAY_WINDOW_DOCUMENT_LOADED_FLAG] === false) {
+      return false;
+    }
     if (
       typeof overlayWindow[OVERLAY_WINDOW_CONTENT_READY_FLAG] === 'boolean' &&
       overlayWindow[OVERLAY_WINDOW_CONTENT_READY_FLAG] !== true
@@ -145,6 +161,50 @@ export function createOverlayModalRuntimeService(
     return currentURL !== '' && currentURL !== 'about:blank';
   };
 
+  const isWindowLoadedForIpc = (window: BrowserWindow): boolean => {
+    if (window.isDestroyed() || window.webContents.isLoading()) {
+      return false;
+    }
+    const overlayWindow = window as BrowserWindow & {
+      [OVERLAY_WINDOW_DOCUMENT_LOADED_FLAG]?: boolean;
+    };
+    if (overlayWindow[OVERLAY_WINDOW_DOCUMENT_LOADED_FLAG] !== true) {
+      return false;
+    }
+    const currentURL = window.webContents.getURL();
+    return currentURL !== '' && currentURL !== 'about:blank';
+  };
+
+  const markModalWindowPrimed = (window: BrowserWindow): void => {
+    if (deps.getModalWindow() !== window || !isWindowLoadedForIpc(window)) {
+      return;
+    }
+    modalWindowPrimedForImmediateShow = true;
+  };
+
+  const primeModalWindow = (): boolean => {
+    if (!shouldPrimeModalWindow) {
+      return false;
+    }
+    const modalWindow = resolveModalWindow();
+    if (!modalWindow) {
+      return false;
+    }
+
+    deps.setModalWindowBounds(deps.getModalGeometry());
+    if (isWindowReadyForIpc(modalWindow)) {
+      modalWindowPrimedForImmediateShow = true;
+      return true;
+    }
+
+    if (!modalWindowPrimeListenersRegistered.has(modalWindow)) {
+      modalWindowPrimeListenersRegistered.add(modalWindow);
+      modalWindow.webContents.once('did-finish-load', () => markModalWindowPrimed(modalWindow));
+      modalWindow.once('ready-to-show', () => markModalWindowPrimed(modalWindow));
+    }
+    return true;
+  };
+
   const elevateModalWindow = (window: BrowserWindow): void => {
     if (window.isDestroyed()) return;
     window.setAlwaysOnTop(true, 'screen-saver', 3);
@@ -205,16 +265,19 @@ export function createOverlayModalRuntimeService(
     }
 
     let delivered = false;
-    const deliverWhenReady = (): void => {
-      if (delivered || window.isDestroyed() || !isWindowReadyForIpc(window)) {
+    const deliver = (isReady: () => boolean): void => {
+      if (delivered || window.isDestroyed() || !isReady()) {
         return;
       }
       delivered = true;
       sendNow(window);
     };
 
-    window.webContents.once('did-finish-load', deliverWhenReady);
-    window.once('ready-to-show', deliverWhenReady);
+    // A hidden macOS panel may not emit ready-to-show until it is presented. The
+    // renderer can safely receive IPC as soon as its document has finished loading.
+    window.webContents.once('did-finish-load', () => deliver(() => isWindowLoadedForIpc(window)));
+    window.once('ready-to-show', () => deliver(() => isWindowReadyForIpc(window)));
+    deliver(() => isWindowLoadedForIpc(window));
   };
 
   const showModalWindow = (
@@ -224,13 +287,20 @@ export function createOverlayModalRuntimeService(
     } = { passThroughMouseEvents: false },
   ): void => {
     setWindowFocusable(window);
-    requestOverlayApplicationFocus();
-    if (!window.isVisible()) {
+    const wasVisible = window.isVisible();
+    if (!wasVisible && platform === 'darwin') {
+      // Mapping the panel first keeps it attached to mpv's active fullscreen Space.
+      window.showInactive();
+      focusApplication();
+    } else {
+      focusApplication();
+    }
+    if (!wasVisible && platform !== 'darwin') {
       window.show();
     }
     elevateModalWindow(window);
     if (options.passThroughMouseEvents) {
-      window.setIgnoreMouseEvents(true, { forward: true });
+      applyOverlayClickThrough(window, platform === 'win32');
     } else {
       window.setIgnoreMouseEvents(false);
     }
@@ -245,11 +315,11 @@ export function createOverlayModalRuntimeService(
 
   const ensureModalWindowInteractive = (window: BrowserWindow): void => {
     setWindowFocusable(window);
-    requestOverlayApplicationFocus();
     window.setIgnoreMouseEvents(false);
     elevateModalWindow(window);
 
     if (window.isVisible()) {
+      focusApplication();
       window.focus();
       window.webContents.focus();
       const reconcileGeneration = nextModalWindowBoundsReconcileGeneration(window);
@@ -291,7 +361,7 @@ export function createOverlayModalRuntimeService(
         mainWindowMousePassthroughForcedByModal = false;
         return;
       }
-      mainWindow.setIgnoreMouseEvents(true, { forward: true });
+      applyOverlayClickThrough(mainWindow, platform === 'win32');
       mainWindowMousePassthroughForcedByModal = true;
       return;
     }
@@ -447,9 +517,21 @@ export function createOverlayModalRuntimeService(
     if (restoreVisibleOverlayOnModalClose.size === 0) {
       clearPendingModalWindowReveal();
       if (modalWindow && !modalWindow.isDestroyed()) {
-        modalWindow.destroy();
+        if (reuseModalWindowAfterClose) {
+          applyOverlayClickThrough(modalWindow, false);
+          modalWindow.hide();
+          markModalWindowPrimed(modalWindow);
+        } else {
+          modalWindow.destroy();
+          modalWindowPrimedForImmediateShow = false;
+          // Reusing a transparent click-through BrowserWindow can leave later modal sessions
+          // non-interactive on Windows. Recycle the renderer after every close, then warm its
+          // replacement so the next shortcut still opens promptly.
+          if (platform === 'win32') {
+            primeModalWindow();
+          }
+        }
       }
-      modalWindowPrimedForImmediateShow = false;
       mainWindowMousePassthroughForcedByModal = false;
       setMainWindowVisibilityForModal(false);
       try {
@@ -478,17 +560,16 @@ export function createOverlayModalRuntimeService(
     }
 
     const modalWindow = deps.getModalWindow();
+    if (targetWindow.isVisible()) {
+      ensureModalWindowInteractive(targetWindow);
+    } else {
+      showModalWindow(targetWindow);
+    }
+
     if (modalWindow && !modalWindow.isDestroyed() && targetWindow === modalWindow) {
       setMainWindowMousePassthroughForModal(true);
       setMainWindowVisibilityForModal(true);
     }
-
-    if (targetWindow.isVisible()) {
-      ensureModalWindowInteractive(targetWindow);
-      return;
-    }
-
-    showModalWindow(targetWindow);
   };
 
   const waitForModalOpen = async (modal: OverlayHostedModal, timeoutMs: number): Promise<boolean> =>
@@ -515,6 +596,7 @@ export function createOverlayModalRuntimeService(
     });
 
   return {
+    primeModalWindow,
     sendToActiveOverlayWindow,
     openRuntimeOptionsPalette,
     openJimaku,

src/main/runtime/anki-actions-main-deps.test.ts

@@ -64,11 +64,17 @@ test('anki action main deps builders map callbacks', async () => {
   const mine = createBuildMineSentenceCardMainDepsHandler({
     getAnkiIntegration: () => ({ enabled: true }),
     getMpvClient: () => ({ connected: true }),
+    getPrimarySubtitle: () => ({ text: '正式な字幕', startTime: 1, endTime: 3 }),
     showMpvOsd: (text) => calls.push(`mine:${text}`),
     mineSentenceCardCore: async () => true,
     recordCardsMined: (count) => calls.push(`cards:${count}`),
   })();
   assert.deepEqual(mine.getMpvClient(), { connected: true });
+  assert.deepEqual(mine.getPrimarySubtitle?.(), {
+    text: '正式な字幕',
+    startTime: 1,
+    endTime: 3,
+  });
   mine.showMpvOsd('m');
   await mine.mineSentenceCardCore({
     ankiIntegration: { enabled: true },

src/main/runtime/anki-actions-main-deps.ts

@@ -1,4 +1,4 @@
-import type { createRefreshKnownWordCacheHandler } from './anki-actions';
+import type { createRefreshKnownWordCacheHandler, PrimarySubtitle } from './anki-actions';
 
 type RefreshKnownWordCacheMainDeps = Parameters<typeof createRefreshKnownWordCacheHandler>[0];
 
@@ -72,10 +72,12 @@ export function createBuildMarkLastCardAsAudioCardMainDepsHandler<TAnki>(deps: {
 export function createBuildMineSentenceCardMainDepsHandler<TAnki, TMpv>(deps: {
   getAnkiIntegration: () => TAnki;
   getMpvClient: () => TMpv;
+  getPrimarySubtitle?: () => PrimarySubtitle | null;
   showMpvOsd: (text: string) => void;
   mineSentenceCardCore: (options: {
     ankiIntegration: TAnki;
     mpvClient: TMpv;
+    primarySubtitle?: PrimarySubtitle;
     showMpvOsd: (text: string) => void;
   }) => Promise<boolean>;
   recordCardsMined: (count: number, noteIds?: number[]) => void;
@@ -83,10 +85,14 @@ export function createBuildMineSentenceCardMainDepsHandler<TAnki, TMpv>(deps: {
   return () => ({
     getAnkiIntegration: () => deps.getAnkiIntegration(),
     getMpvClient: () => deps.getMpvClient(),
+    ...(deps.getPrimarySubtitle
+      ? { getPrimarySubtitle: () => deps.getPrimarySubtitle?.() ?? null }
+      : {}),
     showMpvOsd: (text: string) => deps.showMpvOsd(text),
     mineSentenceCardCore: (options: {
       ankiIntegration: TAnki;
       mpvClient: TMpv;
+      primarySubtitle?: PrimarySubtitle;
       showMpvOsd: (text: string) => void;
     }) => deps.mineSentenceCardCore(options),
     recordCardsMined: (count: number, noteIds?: number[]) => deps.recordCardsMined(count, noteIds),

src/main/runtime/anki-actions.test.ts

@@ -87,3 +87,20 @@ test('mine sentence handler records mined cards only when core returns true', as
   await mineSentenceCard();
   assert.deepEqual(calls, ['osd:mine', 'osd:mine', 'cards:1']);
 });
+
+test('mine sentence handler forwards the canonical primary subtitle snapshot', async () => {
+  const primarySubtitle = { text: '正式な字幕', startTime: 1, endTime: 3 };
+  const mineSentenceCard = createMineSentenceCardHandler({
+    getAnkiIntegration: () => ({}),
+    getMpvClient: () => ({}),
+    getPrimarySubtitle: () => primarySubtitle,
+    showMpvOsd: () => {},
+    mineSentenceCardCore: async (options) => {
+      assert.equal(options.primarySubtitle, primarySubtitle);
+      return true;
+    },
+    recordCardsMined: () => {},
+  });
+
+  await mineSentenceCard();
+});

src/main/runtime/anki-actions.ts

@@ -2,6 +2,12 @@ type AnkiIntegrationLike = {
   refreshKnownWordCache: () => Promise<void>;
 };
 
+export type PrimarySubtitle = {
+  text: string;
+  startTime: number;
+  endTime: number;
+};
+
 export function createUpdateLastCardFromClipboardHandler<TAnki>(deps: {
   getAnkiIntegration: () => TAnki;
   readClipboardText: () => string;
@@ -69,18 +75,22 @@ export function createMarkLastCardAsAudioCardHandler<TAnki>(deps: {
 export function createMineSentenceCardHandler<TAnki, TMpv>(deps: {
   getAnkiIntegration: () => TAnki;
   getMpvClient: () => TMpv;
+  getPrimarySubtitle?: () => PrimarySubtitle | null;
   showMpvOsd: (text: string) => void;
   mineSentenceCardCore: (options: {
     ankiIntegration: TAnki;
     mpvClient: TMpv;
+    primarySubtitle?: PrimarySubtitle;
     showMpvOsd: (text: string) => void;
   }) => Promise<boolean>;
   recordCardsMined: (count: number, noteIds?: number[]) => void;
 }) {
   return async (): Promise<void> => {
+    const primarySubtitle = deps.getPrimarySubtitle?.();
     const created = await deps.mineSentenceCardCore({
       ankiIntegration: deps.getAnkiIntegration(),
       mpvClient: deps.getMpvClient(),
+      ...(primarySubtitle ? { primarySubtitle } : {}),
       showMpvOsd: deps.showMpvOsd,
     });
     if (created) {

src/main/runtime/autoplay-subtitle-priming-runtime.ts

@@ -1,6 +1,7 @@
 import type { SubtitleCue, SubtitleData } from '../../types';
 import { selectAutoplayStartupCue } from './autoplay-subtitle-primer';
 import { primeVisibleOverlaySubtitleFromMpv } from './current-subtitle-snapshot';
+import { resolvePrimarySubtitleText } from './primary-subtitle-text';
 import { resolveSubtitleSourcePath } from './subtitle-prefetch-source';
 
 const AUTOPLAY_SUBTITLE_PRIME_LOOKAHEAD_SECONDS = 2;
@@ -141,6 +142,16 @@ export function createAutoplaySubtitlePrimingRuntime(deps: AutoplaySubtitlePrimi
     return true;
   }
 
+  function resolveLivePrimarySubtitleText(text: string): string {
+    const client = deps.getMpvClient();
+    const currentTimeSec = Number(client?.currentTimePos ?? deps.getLastObservedTimePos());
+    return resolvePrimarySubtitleText({
+      liveText: text,
+      currentTimeSec,
+      cues: deps.getActiveParsedSubtitleCues(),
+    });
+  }
+
   async function primeCurrentSubtitleForAutoplay(mediaPath: string): Promise<void> {
     const client = deps.getMpvClient();
     if (!client?.connected || !isCurrentAutoplayMediaPath(mediaPath)) {
@@ -155,7 +166,8 @@ export function createAutoplaySubtitlePrimingRuntime(deps: AutoplaySubtitlePrimi
       );
       return null;
     });
-    const text = typeof subTextRaw === 'string' ? subTextRaw : '';
+    const liveText = typeof subTextRaw === 'string' ? subTextRaw : '';
+    const text = resolveLivePrimarySubtitleText(liveText);
     if (emitAutoplayPrimedSubtitle(mediaPath, text)) {
       return;
     }
@@ -175,6 +187,7 @@ export function createAutoplaySubtitlePrimingRuntime(deps: AutoplaySubtitlePrimi
   async function primeCurrentSubtitleForVisibleOverlay(): Promise<void> {
     await primeVisibleOverlaySubtitleFromMpv({
       getMpvClient: () => deps.getMpvClient(),
+      resolvePrimarySubtitleText: (text) => resolveLivePrimarySubtitleText(text),
       setCurrentSubText: (text) => {
         deps.setCurrentSubText(text);
       },

src/main/runtime/config-hot-reload-handlers.test.ts

@@ -156,7 +156,6 @@ test('createConfigHotReloadAppliedHandler applies only changed Anki media option
   const config = deepCloneConfig(DEFAULT_CONFIG);
   config.ankiConnect.media.normalizeAudio = false;
   config.ankiConnect.media.mirrorMpvVolume = false;
-  config.ankiConnect.media.reviewTiming = true;
   const ankiPatches: unknown[] = [];
 
   const applyHotReload = createConfigHotReloadAppliedHandler({
@@ -182,18 +181,10 @@ test('createConfigHotReloadAppliedHandler applies only changed Anki media option
     },
     config,
   );
-  applyHotReload(
-    {
-      hotReloadFields: ['ankiConnect.media.reviewTiming'],
-      restartRequiredFields: [],
-    },
-    config,
-  );
 
   assert.deepEqual(ankiPatches, [
     { media: { normalizeAudio: false } },
     { media: { mirrorMpvVolume: false } },
-    { media: { reviewTiming: true } },
   ]);
 });
 

src/main/runtime/config-hot-reload-handlers.ts

@@ -100,9 +100,6 @@ function buildAnkiRuntimeConfigPatch(
   if (diff.hotReloadFields.includes('ankiConnect.media.mirrorMpvVolume')) {
     mediaPatch.mirrorMpvVolume = config.ankiConnect.media.mirrorMpvVolume;
   }
-  if (diff.hotReloadFields.includes('ankiConnect.media.reviewTiming')) {
-    mediaPatch.reviewTiming = config.ankiConnect.media.reviewTiming;
-  }
   if (Object.keys(mediaPatch).length > 0) {
     patch.media = mediaPatch;
   }

src/main/runtime/current-subtitle-snapshot.ts

@@ -46,6 +46,7 @@ export async function resolveCurrentSubtitleForRenderer(deps: {
 export async function primeVisibleOverlaySubtitleFromMpv(deps: {
   getMpvClient: () => CurrentSubtitleMpvClient | null;
   setCurrentSubText: (text: string) => void;
+  resolvePrimarySubtitleText?: (text: string) => string;
   getCurrentSubtitleData: () => SubtitleData | null;
   consumeCachedSubtitle: (text: string) => SubtitleData | null;
   onSubtitleChange: (text: string) => void;
@@ -73,7 +74,8 @@ export async function primeVisibleOverlaySubtitleFromMpv(deps: {
     return;
   }
 
-  const text = typeof subTextRaw === 'string' ? subTextRaw : '';
+  const liveText = typeof subTextRaw === 'string' ? subTextRaw : '';
+  const text = deps.resolvePrimarySubtitleText?.(liveText) ?? liveText;
   deps.setCurrentSubText(text);
 
   const primeSecondarySubtitle = async (): Promise<void> => {

src/main/runtime/media-timing-review-open.ts

@@ -1,40 +0,0 @@
-import { IPC_CHANNELS, type OverlayHostedModal } from '../../shared/ipc/contracts';
-import type { MediaTimingReviewOpenPayload } from '../../types/anki';
-import { openOverlayHostedModal, retryOverlayModalOpen } from './overlay-hosted-modal-open';
-
-const MODAL: OverlayHostedModal = 'media-timing-review';
-
-export async function openMediaTimingReviewModal(
-  deps: {
-    ensureOverlayStartupPrereqs: () => void;
-    ensureOverlayWindowsReadyForVisibilityActions: () => void;
-    sendToActiveOverlayWindow: (
-      channel: string,
-      payload?: unknown,
-      runtimeOptions?: {
-        restoreOnModalClose?: OverlayHostedModal;
-        preferModalWindow?: boolean;
-      },
-    ) => boolean;
-    waitForModalOpen: (modal: OverlayHostedModal, timeoutMs: number) => Promise<boolean>;
-    logWarn: (message: string) => void;
-  },
-  payload: MediaTimingReviewOpenPayload,
-): Promise<boolean> {
-  return await retryOverlayModalOpen(
-    { waitForModalOpen: deps.waitForModalOpen, logWarn: deps.logWarn },
-    {
-      modal: MODAL,
-      timeoutMs: 1_500,
-      retryWarning:
-        'Media timing review did not acknowledge modal open; retrying the dedicated modal window.',
-      sendOpen: () =>
-        openOverlayHostedModal(deps, {
-          channel: IPC_CHANNELS.event.mediaTimingReviewOpen,
-          modal: MODAL,
-          payload,
-          preferModalWindow: true,
-        }),
-    },
-  );
-}

src/main/runtime/media-timing-review.test.ts

@@ -1,406 +0,0 @@
-import assert from 'node:assert/strict';
-import { describe, test } from 'node:test';
-import type { MediaTimingReviewOpenPayload } from '../../types/anki';
-import {
-  buildMediaTimingReviewPayload,
-  createMediaTimingReviewRuntime,
-} from './media-timing-review';
-
-describe('buildMediaTimingReviewPayload', () => {
-  test('starts from the padded range and leaves two seconds to drag on each side', () => {
-    const payload = buildMediaTimingReviewPayload(
-      {
-        kind: 'sentence',
-        text: '字幕',
-        startTime: 10,
-        endTime: 12,
-        audioPadding: 0.5,
-        maxMediaDuration: 30,
-      },
-      { reviewId: 'review-1', mediaDuration: 100 },
-    );
-
-    assert.equal(payload.selectionStartTime, 9.5);
-    assert.equal(payload.selectionEndTime, 12.5);
-    assert.equal(payload.timelineStartTime, 7.5);
-    assert.equal(payload.timelineEndTime, 14.5);
-  });
-
-  test('clamps the padded selection and timeline to media bounds', () => {
-    const payload = buildMediaTimingReviewPayload(
-      {
-        kind: 'word',
-        text: '字幕',
-        startTime: 0.2,
-        endTime: 9.8,
-        audioPadding: 1,
-        maxMediaDuration: 30,
-      },
-      { reviewId: 'review-2', mediaDuration: 10 },
-    );
-
-    assert.equal(payload.selectionStartTime, 0);
-    assert.equal(payload.selectionEndTime, 10);
-    assert.equal(payload.timelineStartTime, 0);
-    assert.equal(payload.timelineEndTime, 10);
-  });
-
-  test('keeps an uncapped selection when max media duration is disabled', () => {
-    const payload = buildMediaTimingReviewPayload(
-      {
-        kind: 'sentence',
-        text: '字幕',
-        startTime: 10,
-        endTime: 55,
-        audioPadding: 1,
-        maxMediaDuration: 0,
-      },
-      { reviewId: 'review-unlimited', mediaDuration: 100 },
-    );
-
-    assert.equal(payload.selectionStartTime, 9);
-    assert.equal(payload.selectionEndTime, 56);
-    assert.equal(payload.maxMediaDuration, 0);
-  });
-});
-
-async function startActiveMediaTimingReview(
-  options: {
-    maxMediaDuration?: number;
-    decisionTimeoutMs?: number;
-  } = {},
-) {
-  const previewCalls: Array<[number, number]> = [];
-  let publishPayload!: (payload: MediaTimingReviewOpenPayload) => void;
-  const openedPayload = new Promise<MediaTimingReviewOpenPayload>((resolve) => {
-    publishPayload = resolve;
-  });
-  const runtime = createMediaTimingReviewRuntime({
-    getMpvClient: () => ({
-      connected: true,
-      currentVideoPath: '/video/show.mkv',
-      requestProperty: async (name) => (name === 'duration' ? 100 : name === 'pause' ? true : null),
-      send: () => undefined,
-    }),
-    getCurrentMediaPath: () => '/video/show.mkv',
-    getMpvExecutablePath: () => 'mpv',
-    generateWaveform: async () => [],
-    decisionTimeoutMs: options.decisionTimeoutMs,
-    createPreviewSession: () => ({
-      start: async () => undefined,
-      play: async (startTime, endTime) => {
-        previewCalls.push([startTime, endTime]);
-      },
-      stop: async () => undefined,
-      dispose: () => undefined,
-    }),
-    openModal: async (payload) => {
-      publishPayload(payload);
-      return true;
-    },
-    showStatus: () => undefined,
-  });
-  const pendingDecision = runtime.requestReview({
-    kind: 'sentence',
-    text: '字幕',
-    startTime: 10,
-    endTime: 12,
-    audioPadding: 0,
-    maxMediaDuration: options.maxMediaDuration ?? 30,
-  });
-
-  return { runtime, payload: await openedPayload, pendingDecision, previewCalls };
-}
-
-test('media timing review pauses playback, resolves exact timing, and restores playing state', async () => {
-  const commands: Array<Array<string | number>> = [];
-  const previewCalls: Array<[number, number]> = [];
-  let runtime: ReturnType<typeof createMediaTimingReviewRuntime>;
-  runtime = createMediaTimingReviewRuntime({
-    getMpvClient: () => ({
-      connected: true,
-      currentVideoPath: '/video/show.mkv',
-      requestProperty: async (name) =>
-        ({ pause: false, duration: 100, aid: 2, volume: 60 })[
-          name as 'pause' | 'duration' | 'aid' | 'volume'
-        ],
-      send: ({ command }) => commands.push(command),
-    }),
-    getCurrentMediaPath: () => '/video/show.mkv',
-    getMpvExecutablePath: () => 'mpv',
-    generateWaveform: async () => [],
-    createPreviewSession: () => ({
-      start: async () => undefined,
-      play: async (startTime, endTime) => {
-        previewCalls.push([startTime, endTime]);
-      },
-      stop: async () => undefined,
-      dispose: () => undefined,
-    }),
-    openModal: async (payload) => {
-      queueMicrotask(() => {
-        void runtime
-          .previewRange({
-            reviewId: payload.reviewId,
-            startTime: 9.5,
-            endTime: 12.5,
-          })
-          .then(() => {
-            runtime.resolveReview({
-              reviewId: payload.reviewId,
-              decision: { action: 'confirm', startTime: 9.5, endTime: 12.5 },
-            });
-          });
-      });
-      return true;
-    },
-    showStatus: () => undefined,
-  });
-
-  const decision = await runtime.requestReview({
-    kind: 'word',
-    text: '字幕',
-    startTime: 10,
-    endTime: 12,
-    noteId: 42,
-    audioPadding: 0.5,
-    maxMediaDuration: 30,
-  });
-
-  assert.deepEqual(decision, { action: 'confirm', startTime: 9.5, endTime: 12.5 });
-  assert.deepEqual(commands, [
-    ['set_property', 'pause', 'yes'],
-    ['set_property', 'pause', 'no'],
-  ]);
-  assert.deepEqual(previewCalls, [[9.5, 12.5]]);
-});
-
-test('media timing review analyzes the visible range on the selected audio stream', async () => {
-  const waveformCalls: Array<{
-    mediaPath: string;
-    startTime: number;
-    endTime: number;
-    audioStreamIndex?: number;
-  }> = [];
-  let runtime: ReturnType<typeof createMediaTimingReviewRuntime>;
-  runtime = createMediaTimingReviewRuntime({
-    getMpvClient: () => ({
-      connected: true,
-      currentVideoPath: '/video/show.mkv',
-      currentAudioStreamIndex: 4,
-      requestProperty: async (name) => (name === 'duration' ? 100 : name === 'pause' ? true : null),
-      send: () => undefined,
-    }),
-    getCurrentMediaPath: () => '/video/show.mkv',
-    getMpvExecutablePath: () => 'mpv',
-    generateWaveform: async (options) => {
-      waveformCalls.push(options);
-      return [0.1, 0.8, 0.2];
-    },
-    createPreviewSession: () => ({
-      start: async () => undefined,
-      play: async () => undefined,
-      stop: async () => undefined,
-      dispose: () => undefined,
-    }),
-    openModal: async (payload) => {
-      const waveform = await runtime.getWaveform({
-        reviewId: payload.reviewId,
-        startTime: payload.timelineStartTime,
-        endTime: payload.timelineEndTime,
-      });
-      assert.deepEqual(waveform, { ok: true, peaks: [0.1, 0.8, 0.2] });
-      runtime.resolveReview({
-        reviewId: payload.reviewId,
-        decision: { action: 'use-original' },
-      });
-      return true;
-    },
-    showStatus: () => undefined,
-  });
-
-  await runtime.requestReview({
-    kind: 'sentence',
-    text: '字幕',
-    startTime: 10,
-    endTime: 12,
-    audioPadding: 0.5,
-    maxMediaDuration: 30,
-  });
-
-  assert.deepEqual(waveformCalls, [
-    {
-      mediaPath: '/video/show.mkv',
-      startTime: 7.5,
-      endTime: 14.5,
-      audioStreamIndex: 4,
-    },
-  ]);
-});
-
-test('media timing review rejects stale and out-of-range actions before allowing discard', async () => {
-  const { runtime, payload, pendingDecision, previewCalls } = await startActiveMediaTimingReview({
-    maxMediaDuration: 3,
-  });
-
-  assert.deepEqual(
-    await runtime.previewRange({ reviewId: 'stale-review', startTime: 10, endTime: 12 }),
-    { ok: false, message: 'This timing review is no longer active.' },
-  );
-  assert.deepEqual(
-    runtime.resolveReview({
-      reviewId: 'stale-review',
-      decision: { action: 'confirm', startTime: 10, endTime: 12 },
-    }),
-    { ok: false, message: 'This timing review is no longer active.' },
-  );
-  assert.deepEqual(
-    runtime.resolveReview({
-      reviewId: payload.reviewId,
-      decision: { action: 'confirm', startTime: 10, endTime: 14 },
-    }),
-    { ok: false, message: 'The selected timing range is invalid.' },
-  );
-  assert.deepEqual(
-    runtime.resolveReview({
-      reviewId: payload.reviewId,
-      decision: { action: 'confirm', startTime: 99, endTime: 100.5 },
-    }),
-    { ok: false, message: 'The selected timing range is invalid.' },
-  );
-  assert.deepEqual(
-    runtime.resolveReview({ reviewId: payload.reviewId, decision: { action: 'discard' } }),
-    { ok: true },
-  );
-  assert.deepEqual(await pendingDecision, { action: 'discard' });
-  assert.deepEqual(previewCalls, []);
-});
-
-test('media timing review watchdog falls back when the renderer stops responding', async () => {
-  const { pendingDecision } = await startActiveMediaTimingReview({ decisionTimeoutMs: 0 });
-
-  assert.deepEqual(await pendingDecision, { action: 'use-original' });
-});
-
-test('media timing review does not resume playback when the prior state is unavailable', async () => {
-  const commands: Array<Array<string | number>> = [];
-  let runtime: ReturnType<typeof createMediaTimingReviewRuntime>;
-  runtime = createMediaTimingReviewRuntime({
-    getMpvClient: () => ({
-      connected: true,
-      currentVideoPath: '/video/show.mkv',
-      requestProperty: async () => null,
-      send: ({ command }) => commands.push(command),
-    }),
-    getCurrentMediaPath: () => '/video/show.mkv',
-    getMpvExecutablePath: () => '',
-    generateWaveform: async () => [],
-    createPreviewSession: () => ({
-      start: async () => {
-        throw new Error('preview unavailable');
-      },
-      play: async () => undefined,
-      stop: async () => undefined,
-      dispose: () => undefined,
-    }),
-    openModal: async (payload) => {
-      queueMicrotask(() => {
-        runtime.resolveReview({
-          reviewId: payload.reviewId,
-          decision: { action: 'use-original' },
-        });
-      });
-      return true;
-    },
-    showStatus: () => undefined,
-  });
-
-  assert.deepEqual(
-    await runtime.requestReview({
-      kind: 'sentence',
-      text: '字幕',
-      startTime: 10,
-      endTime: 12,
-      audioPadding: 0,
-      maxMediaDuration: 30,
-    }),
-    { action: 'use-original' },
-  );
-  assert.deepEqual(commands, [['set_property', 'pause', 'yes']]);
-});
-
-test('media timing review restores playback when setup fails after pausing', async () => {
-  const commands: Array<Array<string | number>> = [];
-  const runtime = createMediaTimingReviewRuntime({
-    getMpvClient: () => ({
-      connected: true,
-      currentVideoPath: '/video/show.mkv',
-      requestProperty: async (name) => (name === 'pause' ? false : null),
-      send: ({ command }) => commands.push(command),
-    }),
-    getCurrentMediaPath: () => '/video/show.mkv',
-    getMpvExecutablePath: () => 'mpv',
-    generateWaveform: async () => [],
-    createPreviewSession: () => {
-      throw new Error('preview setup failed');
-    },
-    openModal: async () => true,
-    showStatus: () => undefined,
-  });
-
-  assert.deepEqual(
-    await runtime.requestReview({
-      kind: 'word',
-      text: '字幕',
-      startTime: 10,
-      endTime: 12,
-      audioPadding: 0,
-      maxMediaDuration: 30,
-    }),
-    { action: 'use-original' },
-  );
-  assert.deepEqual(commands, [
-    ['set_property', 'pause', 'yes'],
-    ['set_property', 'pause', 'no'],
-  ]);
-});
-
-test('disposing an open review settles it with original timing and restores playback', async () => {
-  const commands: Array<Array<string | number>> = [];
-  const runtime = createMediaTimingReviewRuntime({
-    getMpvClient: () => ({
-      connected: true,
-      currentVideoPath: '/video/show.mkv',
-      requestProperty: async (name) => (name === 'pause' ? false : null),
-      send: ({ command }) => commands.push(command),
-    }),
-    getCurrentMediaPath: () => '/video/show.mkv',
-    getMpvExecutablePath: () => 'mpv',
-    generateWaveform: async () => [],
-    createPreviewSession: () => ({
-      start: async () => undefined,
-      play: async () => undefined,
-      stop: async () => undefined,
-      dispose: () => undefined,
-    }),
-    openModal: async () => true,
-    showStatus: () => undefined,
-  });
-
-  const pending = runtime.requestReview({
-    kind: 'word',
-    text: '字幕',
-    startTime: 10,
-    endTime: 12,
-    audioPadding: 0,
-    maxMediaDuration: 30,
-  });
-  await new Promise<void>((resolve) => setImmediate(resolve));
-  await runtime.dispose();
-
-  assert.deepEqual(await pending, { action: 'use-original' });
-  assert.deepEqual(commands, [
-    ['set_property', 'pause', 'yes'],
-    ['set_property', 'pause', 'no'],
-  ]);
-});

src/main/runtime/media-timing-review.ts

@@ -1,346 +0,0 @@
-import { randomUUID } from 'crypto';
-import type {
-  MediaTimingReviewActionResult,
-  MediaTimingReviewDecision,
-  MediaTimingReviewOpenPayload,
-  MediaTimingReviewPreviewRequest,
-  MediaTimingReviewRequest,
-  MediaTimingReviewResolveRequest,
-  MediaTimingReviewWaveformRequest,
-  MediaTimingReviewWaveformResult,
-} from '../../types/anki';
-import type { SpeechWaveformOptions } from '../../core/services/media-timing-waveform';
-
-const INITIAL_TIMELINE_MARGIN_SECONDS = 2;
-const REVIEW_DECISION_TIMEOUT_MS = 5 * 60_000;
-
-interface ReviewMpvClient {
-  connected: boolean;
-  currentVideoPath: string;
-  currentAudioStreamIndex?: number | null;
-  requestProperty?: (name: string) => Promise<unknown>;
-  send: (payload: { command: Array<string | number> }) => void;
-}
-
-interface PreviewSession {
-  start(options: {
-    mediaPath: string;
-    executablePath?: string;
-    audioTrackId?: number;
-    volume?: number;
-  }): Promise<void>;
-  play(startTime: number, endTime: number): Promise<void>;
-  stop(): Promise<void>;
-  dispose(): void;
-}
-
-interface ActiveReview {
-  payload: MediaTimingReviewOpenPayload;
-  mediaPath: string;
-  audioStreamIndex?: number;
-  mpvClient: ReviewMpvClient;
-  restorePlayback: boolean;
-  preview: Promise<PreviewSession>;
-  resolve: (decision: MediaTimingReviewDecision) => void;
-}
-
-export interface MediaTimingReviewRuntimeDeps {
-  getMpvClient: () => ReviewMpvClient | null;
-  getCurrentMediaPath: () => string | null;
-  getMpvExecutablePath: () => string;
-  createPreviewSession: () => PreviewSession;
-  generateWaveform: (options: SpeechWaveformOptions) => Promise<number[]>;
-  decisionTimeoutMs?: number;
-  openModal: (payload: MediaTimingReviewOpenPayload) => Promise<boolean>;
-  showStatus: (message: string) => void;
-}
-
-function finiteNumber(value: unknown): number | null {
-  return typeof value === 'number' && Number.isFinite(value) ? value : null;
-}
-
-function booleanProperty(value: unknown): boolean | null {
-  if (typeof value === 'boolean') return value;
-  if (value === 'yes' || value === 1) return true;
-  if (value === 'no' || value === 0) return false;
-  return null;
-}
-
-function isValidMediaTimingRange(
-  payload: MediaTimingReviewOpenPayload,
-  startTime: number,
-  endTime: number,
-): boolean {
-  return (
-    Number.isFinite(startTime) &&
-    Number.isFinite(endTime) &&
-    startTime >= 0 &&
-    endTime > startTime &&
-    (payload.maxMediaDuration <= 0 || endTime - startTime <= payload.maxMediaDuration + 0.001) &&
-    (payload.mediaDuration === undefined || endTime <= payload.mediaDuration + 0.001)
-  );
-}
-
-export function buildMediaTimingReviewPayload(
-  request: MediaTimingReviewRequest,
-  options: { reviewId: string; mediaDuration?: number },
-): MediaTimingReviewOpenPayload {
-  const duration = finiteNumber(options.mediaDuration);
-  const maxTime = duration !== null && duration > 0 ? duration : Number.POSITIVE_INFINITY;
-  const paddedStart = Math.max(0, request.startTime - request.audioPadding);
-  let paddedEnd = Math.min(maxTime, request.endTime + request.audioPadding);
-  const maxMediaDuration = Math.max(0, request.maxMediaDuration);
-  if (maxMediaDuration > 0 && paddedEnd - paddedStart > maxMediaDuration) {
-    paddedEnd = paddedStart + maxMediaDuration;
-  }
-  if (paddedEnd <= paddedStart) {
-    paddedEnd = Math.min(maxTime, paddedStart + 0.1);
-  }
-
-  const timelineStartTime = Math.max(0, paddedStart - INITIAL_TIMELINE_MARGIN_SECONDS);
-  const timelineEndTime = Math.max(
-    paddedEnd,
-    Math.min(maxTime, paddedEnd + INITIAL_TIMELINE_MARGIN_SECONDS),
-  );
-
-  return {
-    reviewId: options.reviewId,
-    kind: request.kind,
-    text: request.text,
-    ...(request.noteId !== undefined ? { noteId: request.noteId } : {}),
-    originalStartTime: request.startTime,
-    originalEndTime: request.endTime,
-    selectionStartTime: paddedStart,
-    selectionEndTime: paddedEnd,
-    timelineStartTime,
-    timelineEndTime,
-    ...(duration !== null && duration > 0 ? { mediaDuration: duration } : {}),
-    maxMediaDuration,
-  };
-}
-
-export function createMediaTimingReviewRuntime(deps: MediaTimingReviewRuntimeDeps) {
-  let active: ActiveReview | null = null;
-  let reviewInProgress = false;
-  let pendingPauseRestore: ReviewMpvClient | null = null;
-
-  function restorePendingPlayback(): void {
-    const mpvClient = pendingPauseRestore;
-    pendingPauseRestore = null;
-    if (mpvClient?.connected) {
-      mpvClient.send({ command: ['set_property', 'pause', 'no'] });
-    }
-  }
-
-  async function runReview(request: MediaTimingReviewRequest): Promise<MediaTimingReviewDecision> {
-    const mpvClient = deps.getMpvClient();
-    const mediaPath =
-      deps.getCurrentMediaPath()?.trim() || mpvClient?.currentVideoPath?.trim() || '';
-    if (!mpvClient?.connected || !mediaPath) {
-      deps.showStatus('Timing review unavailable. Using the original subtitle timing.');
-      return { action: 'use-original' };
-    }
-
-    const [pauseRaw, durationRaw, audioTrackRaw, volumeRaw] = await Promise.all([
-      mpvClient.requestProperty?.('pause').catch(() => null) ?? null,
-      mpvClient.requestProperty?.('duration').catch(() => null) ?? null,
-      mpvClient.requestProperty?.('aid').catch(() => null) ?? null,
-      mpvClient.requestProperty?.('volume').catch(() => null) ?? null,
-    ]);
-    const pauseState = booleanProperty(pauseRaw);
-    mpvClient.send({ command: ['set_property', 'pause', 'yes'] });
-    pendingPauseRestore = pauseState === false ? mpvClient : null;
-
-    const payload = buildMediaTimingReviewPayload(request, {
-      reviewId: randomUUID(),
-      mediaDuration: finiteNumber(durationRaw) ?? undefined,
-    });
-    const previewSession = deps.createPreviewSession();
-    const preview = previewSession
-      .start({
-        mediaPath,
-        executablePath: deps.getMpvExecutablePath(),
-        audioTrackId: finiteNumber(audioTrackRaw) ?? undefined,
-        volume: finiteNumber(volumeRaw) ?? undefined,
-      })
-      .then(() => previewSession)
-      .catch((error) => {
-        previewSession.dispose();
-        throw error;
-      });
-    void preview.catch(() => {});
-
-    let resolveDecision!: (decision: MediaTimingReviewDecision) => void;
-    const decisionPromise = new Promise<MediaTimingReviewDecision>((resolve) => {
-      resolveDecision = resolve;
-    });
-    active = {
-      payload,
-      mediaPath,
-      ...(mpvClient.currentAudioStreamIndex !== null &&
-      mpvClient.currentAudioStreamIndex !== undefined
-        ? { audioStreamIndex: mpvClient.currentAudioStreamIndex }
-        : {}),
-      mpvClient,
-      restorePlayback: pendingPauseRestore === mpvClient,
-      preview,
-      resolve: resolveDecision,
-    };
-    pendingPauseRestore = null;
-
-    const opened = await deps.openModal(payload).catch(() => false);
-    if (!opened) {
-      await cleanupActiveReview();
-      deps.showStatus('Timing review could not open. Using the original subtitle timing.');
-      return { action: 'use-original' };
-    }
-
-    const decisionWatchdog = setTimeout(
-      () => resolveDecision({ action: 'use-original' }),
-      Math.max(0, deps.decisionTimeoutMs ?? REVIEW_DECISION_TIMEOUT_MS),
-    );
-    let decision: MediaTimingReviewDecision;
-    try {
-      decision = await decisionPromise;
-    } finally {
-      clearTimeout(decisionWatchdog);
-    }
-    await cleanupActiveReview();
-    return decision;
-  }
-
-  async function requestReview(
-    request: MediaTimingReviewRequest,
-  ): Promise<MediaTimingReviewDecision> {
-    if (active || reviewInProgress) {
-      deps.showStatus('Finish the current timing review before mining another card.');
-      return { action: 'use-original' };
-    }
-    reviewInProgress = true;
-    try {
-      return await runReview(request);
-    } catch {
-      await cleanupActiveReview();
-      restorePendingPlayback();
-      deps.showStatus('Timing review failed. Using the original subtitle timing.');
-      return { action: 'use-original' };
-    } finally {
-      reviewInProgress = false;
-    }
-  }
-
-  async function previewRange(
-    request: MediaTimingReviewPreviewRequest,
-  ): Promise<MediaTimingReviewActionResult> {
-    const current = active;
-    if (!current || request.reviewId !== current.payload.reviewId) {
-      return { ok: false, message: 'This timing review is no longer active.' };
-    }
-    if (!isValidMediaTimingRange(current.payload, request.startTime, request.endTime)) {
-      return { ok: false, message: 'The selected preview range is invalid.' };
-    }
-    try {
-      const previewSession = await current.preview;
-      await previewSession.play(request.startTime, request.endTime);
-      return { ok: true };
-    } catch (error) {
-      return {
-        ok: false,
-        message: `Audio preview unavailable: ${error instanceof Error ? error.message : String(error)}`,
-      };
-    }
-  }
-
-  async function getWaveform(
-    request: MediaTimingReviewWaveformRequest,
-  ): Promise<MediaTimingReviewWaveformResult> {
-    const current = active;
-    if (!current || request.reviewId !== current.payload.reviewId) {
-      return { ok: false, message: 'This timing review is no longer active.' };
-    }
-    if (
-      !Number.isFinite(request.startTime) ||
-      !Number.isFinite(request.endTime) ||
-      request.startTime < 0 ||
-      request.endTime <= request.startTime ||
-      (current.payload.mediaDuration !== undefined &&
-        request.endTime > current.payload.mediaDuration + 0.001)
-    ) {
-      return { ok: false, message: 'The waveform range is invalid.' };
-    }
-
-    try {
-      const peaks = await deps.generateWaveform({
-        mediaPath: current.mediaPath,
-        startTime: request.startTime,
-        endTime: request.endTime,
-        ...(current.audioStreamIndex !== undefined
-          ? { audioStreamIndex: current.audioStreamIndex }
-          : {}),
-      });
-      if (active !== current || peaks.length < 2 || peaks.some((peak) => !Number.isFinite(peak))) {
-        return { ok: false, message: 'Timing waveform is unavailable.' };
-      }
-      return { ok: true, peaks };
-    } catch {
-      return { ok: false, message: 'Timing waveform is unavailable.' };
-    }
-  }
-
-  async function stopPreview(reviewId: string): Promise<MediaTimingReviewActionResult> {
-    const current = active;
-    if (!current || reviewId !== current.payload.reviewId) {
-      return { ok: false, message: 'This timing review is no longer active.' };
-    }
-    try {
-      const previewSession = await current.preview;
-      await previewSession.stop();
-      return { ok: true };
-    } catch (error) {
-      return {
-        ok: false,
-        message: `Could not stop preview: ${error instanceof Error ? error.message : String(error)}`,
-      };
-    }
-  }
-
-  function resolveReview(request: MediaTimingReviewResolveRequest): MediaTimingReviewActionResult {
-    const current = active;
-    if (!current || request.reviewId !== current.payload.reviewId) {
-      return { ok: false, message: 'This timing review is no longer active.' };
-    }
-    if (request.decision.action === 'confirm') {
-      const { startTime, endTime } = request.decision;
-      if (!isValidMediaTimingRange(current.payload, startTime, endTime)) {
-        return { ok: false, message: 'The selected timing range is invalid.' };
-      }
-    }
-    current.resolve(request.decision);
-    return { ok: true };
-  }
-
-  async function cleanupActiveReview(): Promise<void> {
-    const current = active;
-    active = null;
-    if (!current) return;
-    void current.preview.then((session) => session.dispose()).catch(() => {});
-    if (current.restorePlayback && current.mpvClient.connected) {
-      current.mpvClient.send({ command: ['set_property', 'pause', 'no'] });
-    }
-  }
-
-  async function dispose(): Promise<void> {
-    active?.resolve({ action: 'use-original' });
-    await cleanupActiveReview();
-    restorePendingPlayback();
-  }
-
-  return {
-    requestReview,
-    previewRange,
-    getWaveform,
-    stopPreview,
-    resolveReview,
-    dispose,
-  };
-}

src/main/runtime/mpv-main-event-actions.test.ts

@@ -26,6 +26,29 @@ test('subtitle change handler updates state and forwards uncached text without r
   assert.deepEqual(calls, ['set:line', 'process:line', 'presence']);
 });
 
+test('subtitle change handler consistently forwards resolved canonical text', () => {
+  const calls: string[] = [];
+  const handler = createHandleMpvSubtitleChangeHandler({
+    resolveSubtitleText: () => '今　手にある物差しでは',
+    setCurrentSubText: (text) => calls.push(`set:${text}`),
+    getImmediateSubtitlePayload: (text) => {
+      calls.push(`lookup:${text}`);
+      return null;
+    },
+    broadcastSubtitle: () => {},
+    onSubtitleChange: (text) => calls.push(`process:${text}`),
+    refreshDiscordPresence: () => {},
+  });
+
+  handler({ text: '今今今手手手ににに' });
+
+  assert.deepEqual(calls, [
+    'set:今　手にある物差しでは',
+    'lookup:今　手にある物差しでは',
+    'process:今　手にある物差しでは',
+  ]);
+});
+
 test('subtitle change handler clears immediately for empty subtitle text', () => {
   const calls: string[] = [];
   const handler = createHandleMpvSubtitleChangeHandler({

src/main/runtime/mpv-main-event-actions.ts

@@ -4,7 +4,8 @@ type AnilistPostWatchRunOptions = {
   watchedSeconds?: number;
 };
 
-const SEEK_LIKE_TIME_DELTA_SECONDS = 2.5;
+/** Jump size that marks a time-pos change as a seek rather than normal playback. */
+export const SEEK_LIKE_TIME_DELTA_SECONDS = 2.5;
 
 function isSeekLikeTimeChange(previousTime: number | null, nextTime: number): boolean {
   if (previousTime === null || !Number.isFinite(previousTime) || !Number.isFinite(nextTime)) {
@@ -14,6 +15,7 @@ function isSeekLikeTimeChange(previousTime: number | null, nextTime: number): bo
 }
 
 export function createHandleMpvSubtitleChangeHandler(deps: {
+  resolveSubtitleText?: (text: string) => string;
   setCurrentSubText: (text: string) => void;
   getImmediateSubtitlePayload?: (text: string) => SubtitleData | null;
   emitImmediateSubtitle?: (payload: SubtitleData) => void;
@@ -22,7 +24,8 @@ export function createHandleMpvSubtitleChangeHandler(deps: {
   refreshDiscordPresence: () => void;
   logDebug?: (message: string) => void;
 }) {
-  return ({ text }: { text: string }): void => {
+  return ({ text: liveText }: { text: string }): void => {
+    const text = deps.resolveSubtitleText?.(liveText) ?? liveText;
     deps.setCurrentSubText(text);
     const immediatePayload = deps.getImmediateSubtitlePayload?.(text) ?? null;
     if (immediatePayload) {

src/main/runtime/mpv-main-event-bindings.ts

@@ -43,6 +43,7 @@ export function createBindMpvMainEventHandlersHandler(deps: {
   logSubtitleTimingError: (message: string, error: unknown) => void;
 
   setCurrentSubText: (text: string) => void;
+  resolveSubtitleText?: (text: string) => string;
   getImmediateSubtitlePayload?: (text: string) => SubtitleData | null;
   emitImmediateSubtitle?: (payload: SubtitleData) => void;
   broadcastSubtitle: (payload: SubtitleData) => void;
@@ -117,6 +118,7 @@ export function createBindMpvMainEventHandlersHandler(deps: {
       logError: (message, error) => deps.logSubtitleTimingError(message, error),
     });
     const handleMpvSubtitleChange = createHandleMpvSubtitleChangeHandler({
+      resolveSubtitleText: deps.resolveSubtitleText,
       setCurrentSubText: (text) => deps.setCurrentSubText(text),
       getImmediateSubtitlePayload: (text) => deps.getImmediateSubtitlePayload?.(text) ?? null,
       emitImmediateSubtitle: deps.emitImmediateSubtitle