fix(overlay): show plain subtitle line immediately on tokenization cache miss (#184 )

fix(streaming): keep subtitle tokenization prefetch warm for full episodes (#183 )
fix(logging): surface subtitle processing debug/warn logs (#182 )
2026-11-13 16:46:08 -08:00 · 2026-08-04 01:55:52 -07:00 · 2026-08-03 21:22:18 -07:00 · 2026-08-03 20:44:39 -07:00
32 changed files with 938 additions and 83 deletions
@@ -26,7 +26,7 @@
        "eslint": "^10.8.0",
        "prettier": "^3.8.1",
        "typescript": "^5.9.3",
-        "undici": "7.28.0",
+        "undici": "7.29.0",
      },
    },
  },
@@ -36,8 +36,9 @@
  "overrides": {
    "@xmldom/xmldom": "0.8.13",
    "app-builder-lib": "26.15.3",
-    "brace-expansion": "5.0.8",
+    "brace-expansion": "5.0.9",
    "electron-builder-squirrel-windows": "26.15.3",
+    "fast-uri": "3.1.5",
    "form-data": "4.0.6",
    "ip-address": "10.2.0",
    "js-yaml": "4.3.0",
@@ -46,6 +47,7 @@
    "picomatch": "4.0.4",
    "tar": "7.5.21",
    "tmp": "0.2.7",
+    "undici": "7.29.0",
  },
  "packages": {
    "@discordjs/collection": ["@discordjs/collection@2.1.1", "", {}, "sha512-LiSusze9Tc7qF03sLCujF5iZp7K+vRNEDBZ86FT9aQAv3vxMLihUvKvpsCWiQ2DJq1tVckopKm1rxomgNUc9hg=="],
@@ -266,7 +268,7 @@

    "boolean": ["boolean@3.2.0", "", {}, "sha512-d0II/GO9uf9lfUHH2BQsjxzRJZBdsjgsBiW4BvhWk/3qoKwQFjIDVN19PfX8F2D/r9PCMTtLWjYVCFrpeYUzsw=="],

-    "brace-expansion": ["brace-expansion@5.0.8", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-JZyDyq3D4AUifKTPOB7DELf6XsB3WdPuNxCtob1vFXPsSXhdAiHBWJ/tJ8HAc9aH84BK+5JFZLNkJKx3G9kzQg=="],
+    "brace-expansion": ["brace-expansion@5.0.9", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg=="],

    "buffer-from": ["buffer-from@1.1.2", "", {}, "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ=="],

@@ -404,7 +406,7 @@

    "fast-levenshtein": ["fast-levenshtein@2.0.6", "", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="],

-    "fast-uri": ["fast-uri@3.1.4", "", {}, "sha512-8JnbkQ4juDyvYs4mgFGQqg4yCYtFDtUtmp2QIQq11ZZe5CFQ5wcqm1rqDgAh/QdMySuBnPzMUiJUNZG5N/AiQw=="],
+    "fast-uri": ["fast-uri@3.1.5", "", {}, "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw=="],

    "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],

@@ -714,7 +716,7 @@

    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],

-    "undici": ["undici@7.28.0", "", {}, "sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA=="],
+    "undici": ["undici@7.29.0", "", {}, "sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw=="],

    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],

@@ -754,8 +756,6 @@

    "@discordjs/rest/discord-api-types": ["discord-api-types@0.38.43", "", {}, "sha512-sSoBf/nK6m7BGtw65mi+QBuvEWaHE8MMziFLqWL+gT6ME/BLg34dRSVKS3Husx40uU06bvxUc3/X+D9Y6/zAbw=="],

-    "@discordjs/rest/undici": ["undici@6.27.0", "", {}, "sha512-YmfV3YnEDzXRC5lZ2jWtWWHKGUm1zIt8AhesR1tens+HTNv+YZlN/dp6G727LOvMJ8xjP9Be7Y2Sdr96LDm+pg=="],
-
    "@discordjs/util/discord-api-types": ["discord-api-types@0.38.43", "", {}, "sha512-sSoBf/nK6m7BGtw65mi+QBuvEWaHE8MMziFLqWL+gT6ME/BLg34dRSVKS3Husx40uU06bvxUc3/X+D9Y6/zAbw=="],

    "@electron/asar/commander": ["commander@5.1.0", "", {}, "sha512-P0CysNDQ7rtVw4QIQtm+MRxV66vKFSvlsQvGYXZWR3qFU0jlMKHZZZgw8e+8DSah4UDKMqnknRDQz+xuQXQ/Zg=="],
@@ -808,8 +808,6 @@

    "node-gyp/env-paths": ["env-paths@2.2.1", "", {}, "sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A=="],

-    "node-gyp/undici": ["undici@6.27.0", "", {}, "sha512-YmfV3YnEDzXRC5lZ2jWtWWHKGUm1zIt8AhesR1tens+HTNv+YZlN/dp6G727LOvMJ8xjP9Be7Y2Sdr96LDm+pg=="],
-
    "node-gyp/which": ["which@6.0.1", "", { "dependencies": { "isexe": "^4.0.0" }, "bin": { "node-which": "bin/which.js" } }, "sha512-oGLe46MIrCRqX7ytPUf66EAYvdeMIZYn3WaocqqKZAxrBpkqHfL/qvTyJ/bTk5+AqHCjXmrv3CEWgy368zhRUg=="],

    "pkijs/@noble/hashes": ["@noble/hashes@1.4.0", "", {}, "sha512-V1JJ1WTRUqHHrOSh597hURcMqVKVGL/ea3kv0gSnEdsEZ0/+VyPghM1lMNGc00z7CIQorSvbKpuJkxvuHbvdbg=="],
@@ -0,0 +1,4 @@
+type: fixed
+area: logging
+
+- Background startup now respects the configured logging level when `--log-level` is not explicitly provided.
@@ -0,0 +1,4 @@
+type: internal
+area: dependencies
+
+- Patched three high-severity dependency advisories flagged by `bun audit`: `undici` (cross-user information disclosure via degenerate private cache directives), `brace-expansion` (denial of service via unbounded intermediate arrays), and `fast-uri` (host confusion via backslash authority introducer).
@@ -0,0 +1,7 @@
+type: fixed
+area: streaming
+
+- Jellyfin playback now seeds the subtitle tokenization prefetch straight from the subtitle file it downloads, instead of waiting on an mpv track-selection event that could be missed or coalesced and leave a whole episode tokenizing line by line.
+- Streamed media no longer drops its parsed subtitle cues when the active subtitle track briefly cannot be resolved, such as when cycling onto a subtitle track embedded in the stream.
+- Subtitle prefetching now runs to the end of a file instead of stopping as soon as the tokenization cache fills, so the back half of an episode no longer gets tokenized line by line during playback. Previously the cache was also never cleared between episodes, so the stall carried over to every later title in a session.
+- Raised the tokenization cache from 256 to 2500 lines. It is now purely a memory bound rather than a limit on how much gets prefetched, and it leaves room for lines that repeat across episodes so openings and endings stay warm between titles.
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Subtitle lines no longer wait for tokenization to finish before appearing, even when the previous line is still being processed. On a tokenization cache miss, the plain line is shown immediately at its cue time and upgrades in place once tokens and annotations are ready; stale results cannot replace newer cues, and the basic plain-text websocket no longer receives a duplicate event for the annotation-only upgrade. A failed tokenization is no longer cached as the plain line, so a repeated line gets another chance at annotations instead of staying plain for the rest of the session.
@@ -149,7 +149,7 @@ Once Jellyfin is configured, the tray menu includes `Jellyfin Discovery` for sta

 - `--log-level` controls logger verbosity.
 - `--dev` and `--debug` are app/dev-mode switches; they are not log-level aliases.
- `--background` defaults to quieter logging (`warn`) unless `--log-level` is set.
+- `--background` starts at the default quieter logging level (`warn`), then follows `logging.level` after config loads. An explicit `--log-level` remains the override.
 - `--background` launched from a terminal detaches and returns the prompt; stop it with tray Quit or `SubMiner.AppImage --stop` (`SubMiner.exe --stop` on Windows).
 - Linux desktop launcher starts SubMiner with `--background` by default (via electron-builder `linux.executableArgs`).
 - On Hyprland and other Wayland compositors, the tray icon appears only when your panel provides a StatusNotifier/AppIndicator tray host.
@@ -64,7 +64,7 @@ Use the basic subtitle websocket when you only need the current subtitle line as
 - **Client auth:** none
 - **Reconnects:** client-managed

-When a client connects, SubMiner immediately sends the latest subtitle payload if one is available. After that, it pushes a new message each time the current subtitle changes.
+When a client connects, SubMiner immediately sends the latest subtitle payload if one is available. After that, it pushes a new message each time the current subtitle changes. Annotation-only upgrades do not repeat the same line on this basic stream.

 #### Message shape

@@ -96,6 +96,8 @@ Use the annotation websocket for custom clients that want the same structured to

 In practice, if you are building a new client, prefer `annotationWebsocket` unless you specifically need compatibility with an existing `websocket` consumer.

+On a tokenization cache miss, this stream first sends the cue as plain text with an empty `tokens` array, then sends the annotated replacement when tokenization finishes. Treat each message as the complete current state, replacing the previous payload.
+
 #### Message shape

 ```json
@@ -3,7 +3,7 @@
 # Subtitle Overlay Priming

 Status: active
-Last verified: 2026-06-14
+Last verified: 2026-08-04
 Owner: Kyle Yasuda
 Read when: debugging subtitle state or blank Linux/X11 overlay windows when the visible overlay is shown or recreated

@@ -47,18 +47,31 @@ subtitles do not draw.
   `emitSubtitle(payload)` and `refreshCurrentSubtitle(text)`, then prime secondary subtitles.
 6. Tokenization cache hit: call `consumeCachedSubtitle(text)`, `onSubtitleChange(text)`, and
   `emitSubtitle(cachedPayload)`, then prime secondary subtitles.
-7. Cache miss: call `refreshCurrentSubtitle(text)` and let normal tokenization emit the final
-   payload.
+7. Cache miss: call `refreshCurrentSubtitle(text)`. Normal processing emits a plain payload
+   synchronously, then replaces it with the tokenized payload when ready.

 In `src/main.ts`, both `onSubtitleChange` and `refreshCurrentSubtitle` pause
 `subtitlePrefetchService`, notify it with `onSeek(lastObservedTimePos)`, and then call the matching
 `subtitleProcessingController` method. This gives the visible overlay priority over background
 prefetch work and re-centers prefetch around the live playback time.

+## Live Cue Delivery
+
+- A tokenization cache miss emits the plain cue synchronously. Tokenization remains serialized so
+  live work does not contend for Yomitan state.
+- If a newer cue arrives while an older line is still tokenizing, the newer plain cue or empty
+  clear payload is emitted immediately. The older tokenization result is dropped before it can
+  replace the current cue.
+- The current cue upgrades in place when its tokens and annotations are ready. This can reflow text
+  or character images, but cue visibility does not wait for that work.
+
 ## Emitted State

- `emitSubtitle(payload)` maps to `emitSubtitlePayload(payload)`, which sends the normal
-  annotated subtitle payload to overlay windows and subtitle websocket listeners.
+- `emitSubtitle(payload)` maps to `emitSubtitlePayload(payload)`. Overlay windows and annotation
+  websocket listeners receive both the immediate plain cue and its later annotation upgrade.
+- The basic subtitle websocket receives the immediate plain cue only. Because its serialized
+  payload discards annotations, the later upgrade would be an identical duplicate and is skipped
+  when text and cue timing match.
 - Secondary priming reads mpv `secondary-sub-text`, stores it in
  `mpvClient.currentSecondarySubText`, and broadcasts `secondary-subtitle:set` to overlay windows.
 - If secondary `requestProperty` fails, the primary flow stays complete and only a debug line is
@@ -84,8 +84,9 @@
  "overrides": {
    "@xmldom/xmldom": "0.8.13",
    "app-builder-lib": "26.15.3",
-    "brace-expansion": "5.0.8",
+    "brace-expansion": "5.0.9",
    "electron-builder-squirrel-windows": "26.15.3",
+    "fast-uri": "3.1.5",
    "form-data": "4.0.6",
    "ip-address": "10.2.0",
    "js-yaml": "4.3.0",
@@ -93,7 +94,8 @@
    "minimatch": "10.2.5",
    "picomatch": "4.0.4",
    "tar": "7.5.21",
-    "tmp": "0.2.7"
+    "tmp": "0.2.7",
+    "undici": "7.29.0"
  },
  "keywords": [
    "anki",
@@ -125,7 +127,7 @@
    "@types/ws": "^8.18.1",
    "electron": "42.6.0",
    "electron-builder": "26.15.3",
-    "undici": "7.28.0",
+    "undici": "7.29.0",
    "esbuild": "^0.25.12",
    "eslint": "^10.8.0",
    "prettier": "^3.8.1",
@@ -1,5 +1,9 @@
 export { Texthooker } from './texthooker';
-export { hasMpvWebsocketPlugin, SubtitleWebSocket } from './subtitle-ws';
+export {
+  hasMpvWebsocketPlugin,
+  isSubtitleAnnotationUpgrade,
+  SubtitleWebSocket,
+} from './subtitle-ws';
 export { registerGlobalShortcuts } from './shortcut';
 export { createIpcDepsRuntime, registerIpcHandlers } from './ipc';
 export { shortcutMatchesInputForLocalFallback } from './shortcut-fallback';
@@ -205,7 +205,7 @@ test('runStartupBootstrapRuntime skips lifecycle when generate-config flow handl
  assert.deepEqual(calls, ['setLog:warn:cli', 'forceX11', 'enforceWayland']);
 });

-test('runStartupBootstrapRuntime enables quiet background mode by default', () => {
+test('runStartupBootstrapRuntime lets config govern background log level by default', () => {
  const calls: string[] = [];
  const args = makeArgs({ background: true });

@@ -222,7 +222,7 @@ test('runStartupBootstrapRuntime enables quiet background mode by default', () =
  });

  assert.equal(result.backgroundMode, true);
-  assert.deepEqual(calls, ['setLog:warn:cli', 'forceX11', 'enforceWayland', 'startLifecycle']);
+  assert.deepEqual(calls, ['forceX11', 'enforceWayland', 'startLifecycle']);
 });

 test('runStartupBootstrapRuntime enables quiet update mode by default', () => {
@@ -45,7 +45,7 @@ export function runStartupBootstrapRuntime(

  if (initialArgs.logLevel) {
    deps.setLogLevel(initialArgs.logLevel, 'cli');
-  } else if (initialArgs.background || initialArgs.update) {
+  } else if (initialArgs.update) {
    deps.setLogLevel('warn', 'cli');
  }

@@ -74,7 +74,6 @@ test('prefetch service tokenizes priority window cues and caches them', async ()
    preCacheTokenization: (text, data) => {
      cached.set(text, data);
    },
-    isCacheFull: () => false,
    priorityWindowSize: 3,
  });

@@ -91,32 +90,38 @@ test('prefetch service tokenizes priority window cues and caches them', async ()
  assert.ok(cached.has('line-2'));
 });

-test('prefetch service stops when cache is full', async () => {
+test('prefetch service warms every cue even when the cache evicts along the way', async () => {
  const cues = makeCues(20);
-  let tokenizeCalls = 0;
-  let cacheSize = 0;
+  const tokenized: string[] = [];
+  // Stand-in for the LRU: only the last 5 entries survive, so later cues evict earlier ones.
+  const cache = new Set<string>();

  const service = createSubtitlePrefetchService({
    cues,
    tokenizeSubtitle: async (text) => {
-      tokenizeCalls += 1;
+      tokenized.push(text);
      return { text, tokens: [] };
    },
-    preCacheTokenization: () => {
-      cacheSize += 1;
+    preCacheTokenization: (text) => {
+      cache.add(text);
+      while (cache.size > 5) {
+        const oldest = cache.values().next().value;
+        if (oldest === undefined) break;
+        cache.delete(oldest);
+      }
    },
-    isCacheFull: () => cacheSize >= 5,
+    hasCachedTokenization: (text) => cache.has(text),
    priorityWindowSize: 3,
  });

  service.start(0);
-  for (let i = 0; i < 30; i += 1) {
+  for (let i = 0; i < 60; i += 1) {
    await flushMicrotasks();
  }
  service.stop();

-  // Should have stopped at 5 (cache full), not tokenized all 20
-  assert.ok(tokenizeCalls <= 6, `Expected <= 6 tokenize calls, got ${tokenizeCalls}`);
+  assert.equal(tokenized.length, 20, `Expected all 20 cues warmed, got ${tokenized.length}`);
+  assert.equal(new Set(tokenized).size, 20, 'Each cue is tokenized at most once per run');
 });

 test('prefetch service can be stopped mid-flight', async () => {
@@ -130,7 +135,6 @@ test('prefetch service can be stopped mid-flight', async () => {
      return { text, tokens: [] };
    },
    preCacheTokenization: () => {},
-    isCacheFull: () => false,
    priorityWindowSize: 3,
  });

@@ -159,7 +163,6 @@ test('prefetch service onSeek re-prioritizes from new position', async () => {
    preCacheTokenization: (text) => {
      cachedTexts.push(text);
    },
-    isCacheFull: () => false,
    priorityWindowSize: 3,
  });

@@ -183,7 +186,7 @@ test('prefetch service onSeek re-prioritizes from new position', async () => {
  assert.ok(hasPostSeekCue, 'Should have cached cues after seek position');
 });

-test('prefetch service still warms the priority window when cache is full', async () => {
+test('prefetch service warms the priority window ahead of the rest of the file', async () => {
  const cues = makeCues(20);
  const cachedTexts: string[] = [];

@@ -193,7 +196,6 @@ test('prefetch service still warms the priority window when cache is full', asyn
    preCacheTokenization: (text) => {
      cachedTexts.push(text);
    },
-    isCacheFull: () => true,
    priorityWindowSize: 3,
  });

@@ -217,7 +219,6 @@ test('prefetch service pause/resume halts and continues tokenization', async ()
      return { text, tokens: [] };
    },
    preCacheTokenization: () => {},
-    isCacheFull: () => false,
    priorityWindowSize: 3,
  });

@@ -255,7 +256,6 @@ test('prefetch service skips cues already present in tokenization cache', async
    },
    preCacheTokenization: () => {},
    hasCachedTokenization: (text) => text === 'line-0' || text === 'line-1',
-    isCacheFull: () => false,
    priorityWindowSize: 3,
  });

@@ -285,7 +285,6 @@ test('prefetch service deduplicates repeated cue text within a run', async () =>
      return { text, tokens: [] };
    },
    preCacheTokenization: () => {},
-    isCacheFull: () => false,
    priorityWindowSize: 3,
  });

@@ -7,7 +7,6 @@ export interface SubtitlePrefetchServiceDeps {
  tokenizeSubtitle: (text: string) => Promise<SubtitleData | null>;
  preCacheTokenization: (text: string, data: SubtitleData) => void;
  hasCachedTokenization?: (text: string) => boolean;
-  isCacheFull: () => boolean;
  priorityWindowSize?: number;
 }

@@ -57,11 +56,14 @@ export function createSubtitlePrefetchService(
  let paused = false;
  let currentRunId = 0;

+  // A run is a single bounded pass over one file's cues, deduped by `warmedKeys` and by
+  // `hasCachedTokenization`, so the worst case is one tokenization per cue. The cache is
+  // an LRU and bounds its own memory, so a full cache is not a reason to stop warming;
+  // stopping there used to leave the tail of longer media permanently uncached.
  async function tokenizeCueList(
    cuesToProcess: SubtitleCue[],
    runId: number,
    warmedKeys: Set<string>,
-    options: { allowWhenCacheFull?: boolean } = {},
  ): Promise<void> {
    for (const cue of cuesToProcess) {
      if (stopped || runId !== currentRunId) {
@@ -77,10 +79,6 @@ export function createSubtitlePrefetchService(
        return;
      }

-      if (!options.allowWhenCacheFull && deps.isCacheFull()) {
-        return;
-      }
-
      const cacheKey = normalizeSubtitleCacheKey(cue.text);
      if (!cacheKey || warmedKeys.has(cacheKey) || deps.hasCachedTokenization?.(cue.text)) {
        if (cacheKey) {
@@ -110,7 +108,7 @@ export function createSubtitlePrefetchService(

    // Phase 1: Priority window
    const priorityCues = computePriorityWindow(cues, currentTimeSeconds, windowSize);
-    await tokenizeCueList(priorityCues, runId, warmedKeys, { allowWhenCacheFull: true });
+    await tokenizeCueList(priorityCues, runId, warmedKeys);

    if (stopped || runId !== currentRunId) {
      return;
@@ -0,0 +1,159 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import type { SubtitleData } from '../../types';
+import { createSubtitleProcessingController } from './subtitle-processing-controller';
+
+function flushMicrotasks(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+test('new subtitle emits plain immediately without parallel tokenization or a stale overwrite', async () => {
+  const emitted: SubtitleData[] = [];
+  const resolvers = new Map<string, (value: SubtitleData | null) => void>();
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) =>
+      await new Promise<SubtitleData | null>((resolve) => {
+        resolvers.set(text, resolve);
+      }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('first');
+  controller.onSubtitleChange('second');
+
+  assert.deepEqual(emitted, [
+    { text: 'first', tokens: null },
+    { text: 'second', tokens: null },
+  ]);
+  assert.equal(resolvers.has('second'), false);
+
+  const resolveFirst = resolvers.get('first');
+  assert.ok(resolveFirst);
+  resolveFirst({ text: 'first', tokens: [] });
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [
+    { text: 'first', tokens: null },
+    { text: 'second', tokens: null },
+  ]);
+  assert.equal(resolvers.has('second'), true);
+
+  const resolveSecond = resolvers.get('second');
+  assert.ok(resolveSecond);
+  resolveSecond({ text: 'second', tokens: [] });
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [
+    { text: 'first', tokens: null },
+    { text: 'second', tokens: null },
+    { text: 'second', tokens: [] },
+  ]);
+});
+
+test('subtitle clears immediately while previous tokenization remains pending', async () => {
+  const emitted: SubtitleData[] = [];
+  let resolveTokenization: ((value: SubtitleData | null) => void) | undefined;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async () =>
+      await new Promise<SubtitleData | null>((resolve) => {
+        resolveTokenization = resolve;
+      }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('first');
+  controller.onSubtitleChange('');
+
+  assert.deepEqual(emitted, [
+    { text: 'first', tokens: null },
+    { text: '', tokens: null },
+  ]);
+
+  assert.ok(resolveTokenization);
+  resolveTokenization({ text: 'first', tokens: [] });
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [
+    { text: 'first', tokens: null },
+    { text: '', tokens: null },
+  ]);
+});
+
+test('returning to an uncached completed line emits it while another line is pending', async () => {
+  const emitted: SubtitleData[] = [];
+  let resolvePending: ((value: SubtitleData | null) => void) | undefined;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => {
+      if (text === 'A') {
+        return { text, tokens: [] };
+      }
+      return await new Promise<SubtitleData | null>((resolve) => {
+        resolvePending = resolve;
+      });
+    },
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('A');
+  await flushMicrotasks();
+  controller.invalidateTokenizationCache();
+  controller.onSubtitleChange('B');
+  controller.onSubtitleChange('A');
+
+  assert.deepEqual(emitted.at(-1), { text: 'A', tokens: null });
+  assert.ok(resolvePending);
+  resolvePending({ text: 'B', tokens: [] });
+});
+
+test('ABA subtitle changes reuse the matching first tokenization only after A is current again', async () => {
+  const emitted: SubtitleData[] = [];
+  const tokenizeCalls: string[] = [];
+  const resolvers: Array<(value: SubtitleData | null) => void> = [];
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => {
+      tokenizeCalls.push(text);
+      return await new Promise<SubtitleData | null>((resolve) => {
+        resolvers.push(resolve);
+      });
+    },
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('A');
+  controller.onSubtitleChange('B');
+  controller.onSubtitleChange('A');
+  const resolveFirst = resolvers[0];
+  assert.ok(resolveFirst);
+  resolveFirst({ text: 'A', tokens: [{ value: 1 } as never] });
+  await flushMicrotasks();
+
+  assert.deepEqual(tokenizeCalls, ['A']);
+  assert.deepEqual(emitted, [
+    { text: 'A', tokens: null },
+    { text: 'B', tokens: null },
+    { text: 'A', tokens: null },
+    { text: 'A', tokens: [{ value: 1 } as never] },
+  ]);
+});
+
+test('cached next subtitle does not downgrade to plain while processing is busy', async () => {
+  const emitted: SubtitleData[] = [];
+  let resolveTokenization: ((value: SubtitleData | null) => void) | undefined;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) =>
+      await new Promise<SubtitleData | null>((resolve) => {
+        resolveTokenization = () => resolve({ text, tokens: [] });
+      }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.preCacheTokenization('cached', { text: 'cached', tokens: [] });
+  controller.onSubtitleChange('pending');
+  controller.onSubtitleChange('cached');
+
+  assert.deepEqual(emitted, [{ text: 'pending', tokens: null }]);
+  assert.ok(resolveTokenization);
+  resolveTokenization({ text: 'pending', tokens: [] });
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [
+    { text: 'pending', tokens: null },
+    { text: 'cached', tokens: [] },
+  ]);
+});
@@ -7,18 +7,138 @@ function flushMicrotasks(): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, 0));
 }

-test('subtitle processing emits tokenized payload when tokenization succeeds', async () => {
+test('subtitle processing emits plain payload immediately on cache miss, then tokenized payload', async () => {
  const emitted: SubtitleData[] = [];
  const controller = createSubtitleProcessingController({
    tokenizeSubtitle: async (text) => ({ text, tokens: [] }),
    emitSubtitle: (payload) => emitted.push(payload),
  });

+  controller.onSubtitleChange('字幕');
+  assert.deepEqual(emitted, [{ text: '字幕', tokens: null }]);
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [
+    { text: '字幕', tokens: null },
+    { text: '字幕', tokens: [] },
+  ]);
+});
+
+test('cache invalidation during pending tokenization does not re-emit the plain payload', async () => {
+  const emitted: SubtitleData[] = [];
+  const resolvers: Array<(value: SubtitleData | null) => void> = [];
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) =>
+      await new Promise<SubtitleData | null>((resolve) => {
+        resolvers.push(() => resolve({ text, tokens: [{ value: resolvers.length } as never] }));
+      }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('行');
+  assert.deepEqual(emitted, [{ text: '行', tokens: null }]);
+
+  controller.invalidateTokenizationCache();
+  resolvers[0]?.({ text: '行', tokens: [] });
+  await flushMicrotasks();
+  // Retry for the new generation is now pending; still no duplicate plain emit.
+  assert.deepEqual(emitted, [{ text: '行', tokens: null }]);
+
+  resolvers[1]?.({ text: '行', tokens: [] });
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [
+    { text: '行', tokens: null },
+    { text: '行', tokens: [{ value: 2 } as never] },
+  ]);
+});
+
+test('failed refresh does not downgrade an already emitted tokenized subtitle', async () => {
+  const emitted: SubtitleData[] = [];
+  let tokenizeCalls = 0;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => {
+      tokenizeCalls += 1;
+      if (tokenizeCalls > 1) {
+        throw new Error('tokenizer gone');
+      }
+      return { text, tokens: [] };
+    },
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('行');
+  await flushMicrotasks();
+  controller.invalidateTokenizationCache();
+  controller.refreshCurrentSubtitle();
+  await flushMicrotasks();
+
+  assert.equal(tokenizeCalls, 2);
+  assert.deepEqual(emitted, [
+    { text: '行', tokens: null },
+    { text: '行', tokens: [] },
+  ]);
+});
+
+test('null-tokenization refresh does not downgrade an already emitted tokenized subtitle', async () => {
+  const emitted: SubtitleData[] = [];
+  let tokenizeCalls = 0;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => {
+      tokenizeCalls += 1;
+      return tokenizeCalls > 1 ? null : { text, tokens: [] };
+    },
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('行');
+  await flushMicrotasks();
+  controller.invalidateTokenizationCache();
+  controller.refreshCurrentSubtitle();
+  await flushMicrotasks();
+
+  assert.equal(tokenizeCalls, 2);
+  assert.deepEqual(emitted, [
+    { text: '行', tokens: null },
+    { text: '行', tokens: [] },
+  ]);
+});
+
+test('subtitle processing does not emit plain payload for cached lines', async () => {
+  const emitted: SubtitleData[] = [];
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => ({ text, tokens: [] }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.preCacheTokenization('字幕', { text: '字幕', tokens: [] });
  controller.onSubtitleChange('字幕');
  await flushMicrotasks();
  assert.deepEqual(emitted, [{ text: '字幕', tokens: [] }]);
 });

+test('subtitle processing shows plain line while tokenization is still pending', async () => {
+  const emitted: SubtitleData[] = [];
+  let resolveTokenization: ((value: SubtitleData | null) => void) | undefined;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) =>
+      await new Promise<SubtitleData | null>((resolve) => {
+        resolveTokenization = () => resolve({ text, tokens: [] });
+      }),
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('遅い行');
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [{ text: '遅い行', tokens: null }]);
+
+  assert.ok(resolveTokenization);
+  resolveTokenization({ text: '遅い行', tokens: [] });
+  await flushMicrotasks();
+  assert.deepEqual(emitted, [
+    { text: '遅い行', tokens: null },
+    { text: '遅い行', tokens: [] },
+  ]);
+});
+
 test('subtitle processing drops stale tokenization and delivers latest subtitle only once', async () => {
  const emitted: SubtitleData[] = [];
  let firstResolve: ((value: SubtitleData | null) => void) | undefined;
@@ -41,7 +161,11 @@ test('subtitle processing drops stale tokenization and delivers latest subtitle
  await flushMicrotasks();
  await flushMicrotasks();

-  assert.deepEqual(emitted, [{ text: 'second', tokens: [] }]);
+  assert.deepEqual(emitted, [
+    { text: 'first', tokens: null },
+    { text: 'second', tokens: null },
+    { text: 'second', tokens: [] },
+  ]);
 });

 test('subtitle processing skips duplicate subtitle emission', async () => {
@@ -60,7 +184,10 @@ test('subtitle processing skips duplicate subtitle emission', async () => {
  controller.onSubtitleChange('same');
  await flushMicrotasks();

-  assert.equal(emitted.length, 1);
+  assert.deepEqual(emitted, [
+    { text: 'same', tokens: null },
+    { text: 'same', tokens: [] },
+  ]);
  assert.equal(tokenizeCalls, 1);
 });

@@ -84,7 +211,9 @@ test('subtitle processing reuses cached tokenization for repeated subtitle text'

  assert.equal(tokenizeCalls, 2);
  assert.deepEqual(emitted, [
+    { text: 'first', tokens: null },
    { text: 'first', tokens: [] },
+    { text: 'second', tokens: null },
    { text: 'second', tokens: [] },
    { text: 'first', tokens: [] },
  ]);
@@ -100,7 +229,48 @@ test('subtitle processing falls back to plain subtitle when tokenization returns
  controller.onSubtitleChange('fallback');
  await flushMicrotasks();

+  assert.deepEqual(
+    emitted,
+    [{ text: 'fallback', tokens: null }],
+    'plain payload should not be re-emitted when tokenization yields nothing new',
+  );
+});
+
+test('null tokenization is not cached and a later cue retries tokenization', async () => {
+  const emitted: SubtitleData[] = [];
+  const callsByText = new Map<string, number>();
+  let failNext = true;
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => {
+      callsByText.set(text, (callsByText.get(text) ?? 0) + 1);
+      if (text === 'fallback' && failNext) {
+        failNext = false;
+        return null;
+      }
+      return { text, tokens: [] };
+    },
+    emitSubtitle: (payload) => emitted.push(payload),
+  });
+
+  controller.onSubtitleChange('fallback');
+  await flushMicrotasks();
+
+  assert.equal(callsByText.get('fallback'), 1);
+  assert.equal(
+    controller.hasCachedSubtitle('fallback'),
+    false,
+    'plain fallback must not be cached when tokenization yields nothing',
+  );
  assert.deepEqual(emitted, [{ text: 'fallback', tokens: null }]);
+
+  controller.onSubtitleChange('other');
+  await flushMicrotasks();
+  controller.onSubtitleChange('fallback');
+  await flushMicrotasks();
+
+  assert.equal(callsByText.get('fallback'), 2, 'later cue should retry tokenization');
+  assert.equal(controller.hasCachedSubtitle('fallback'), true);
+  assert.deepEqual(emitted.at(-1), { text: 'fallback', tokens: [] });
 });

 test('subtitle processing ignores duplicate current subtitle refresh without cache invalidation', async () => {
@@ -120,7 +290,10 @@ test('subtitle processing ignores duplicate current subtitle refresh without cac
  await flushMicrotasks();

  assert.equal(tokenizeCalls, 1);
-  assert.deepEqual(emitted, [{ text: 'same', tokens: [] }]);
+  assert.deepEqual(emitted, [
+    { text: 'same', tokens: null },
+    { text: 'same', tokens: [] },
+  ]);
 });

 test('subtitle processing coalesces refresh requests while current subtitle is processing', async () => {
@@ -146,7 +319,10 @@ test('subtitle processing coalesces refresh requests while current subtitle is p
  await flushMicrotasks();

  assert.equal(tokenizeCalls, 1);
-  assert.deepEqual(emitted, [{ text: 'same', tokens: [] }]);
+  assert.deepEqual(emitted, [
+    { text: 'same', tokens: null },
+    { text: 'same', tokens: [] },
+  ]);
 });

 test('subtitle processing refresh re-tokenizes after cache invalidation', async () => {
@@ -168,6 +344,7 @@ test('subtitle processing refresh re-tokenizes after cache invalidation', async

  assert.equal(tokenizeCalls, 2);
  assert.deepEqual(emitted, [
+    { text: 'same', tokens: null },
    { text: 'same', tokens: [{ value: 1 } as never] },
    { text: 'same', tokens: [{ value: 2 } as never] },
  ]);
@@ -183,7 +360,10 @@ test('subtitle processing refresh can use explicit text override', async () => {
  controller.refreshCurrentSubtitle('initial');
  await flushMicrotasks();

-  assert.deepEqual(emitted, [{ text: 'initial', tokens: [] }]);
+  assert.deepEqual(emitted, [
+    { text: 'initial', tokens: null },
+    { text: 'initial', tokens: [] },
+  ]);
 });

 test('subtitle processing cache invalidation only affects future subtitle events', async () => {
@@ -205,10 +385,10 @@ test('subtitle processing cache invalidation only affects future subtitle events
  await flushMicrotasks();

  assert.equal(callsByText.get('same'), 1);
-  assert.equal(emitted.length, 3);
+  assert.equal(emitted.length, 5);

  controller.invalidateTokenizationCache();
-  assert.equal(emitted.length, 3);
+  assert.equal(emitted.length, 5);

  controller.onSubtitleChange('different');
  await flushMicrotasks();
@@ -308,25 +488,54 @@ test('hasCachedSubtitle checks prefetched entries without consuming them', async
  assert.equal(controller.hasCachedSubtitle('猫\nです'), false);
 });

-test('isCacheFull returns false when cache is below limit', () => {
+test('cache keeps every entry while below the limit', () => {
  const controller = createSubtitleProcessingController({
-    tokenizeSubtitle: async (text) => ({ text, tokens: null }),
+    tokenizeSubtitle: async (text) => ({ text, tokens: [] }),
    emitSubtitle: () => {},
+    cacheLimit: 8,
  });

-  assert.equal(controller.isCacheFull(), false);
+  for (let i = 0; i < 8; i += 1) {
+    controller.preCacheTokenization(`line-${i}`, { text: `line-${i}`, tokens: [] });
+  }
+
+  assert.deepEqual(
+    Array.from({ length: 8 }, (_, i) => controller.hasCachedSubtitle(`line-${i}`)),
+    Array.from({ length: 8 }, () => true),
+  );
 });

-test('isCacheFull returns true when cache reaches limit', async () => {
+test('cache evicts least recently used entries once the limit is reached', () => {
+  const controller = createSubtitleProcessingController({
+    tokenizeSubtitle: async (text) => ({ text, tokens: [] }),
+    emitSubtitle: () => {},
+    cacheLimit: 3,
+  });
+
+  for (const line of ['a', 'b', 'c']) {
+    controller.preCacheTokenization(line, { text: line, tokens: [] });
+  }
+  // Touching 'a' makes 'b' the eviction candidate.
+  controller.consumeCachedSubtitle('a');
+  controller.preCacheTokenization('d', { text: 'd', tokens: [] });
+
+  assert.equal(controller.hasCachedSubtitle('b'), false);
+  assert.deepEqual(
+    ['a', 'c', 'd'].map((line) => controller.hasCachedSubtitle(line)),
+    [true, true, true],
+  );
+});
+
+test('default cache limit covers a full-length title without evicting', () => {
  const controller = createSubtitleProcessingController({
    tokenizeSubtitle: async (text) => ({ text, tokens: [] }),
    emitSubtitle: () => {},
  });

-  // Fill cache to the 256 limit
-  for (let i = 0; i < 256; i += 1) {
+  for (let i = 0; i < 2000; i += 1) {
    controller.preCacheTokenization(`line-${i}`, { text: `line-${i}`, tokens: [] });
  }

-  assert.equal(controller.isCacheFull(), true);
+  assert.equal(controller.hasCachedSubtitle('line-0'), true);
+  assert.equal(controller.hasCachedSubtitle('line-1999'), true);
 });
@@ -5,8 +5,17 @@ export interface SubtitleProcessingControllerDeps {
  emitSubtitle: (payload: SubtitleData) => void;
  logDebug?: (message: string) => void;
  now?: () => number;
+  cacheLimit?: number;
 }

+/**
+ * Pure memory bound on the LRU, not a coverage limit: prefetching runs to the end of a
+ * file regardless of cache pressure. Sized to hold a feature-length title (a 24-minute
+ * episode runs 300-400 lines, a 2-hour film ~2000) plus room for lines that repeat across
+ * episodes of a series, so openings and endings stay warm between titles.
+ */
+export const DEFAULT_SUBTITLE_TOKENIZATION_CACHE_LIMIT = 2500;
+
 export interface SubtitleProcessingController {
  onSubtitleChange: (text: string) => void;
  refreshCurrentSubtitle: (textOverride?: string) => void;
@@ -14,7 +23,6 @@ export interface SubtitleProcessingController {
  preCacheTokenization: (text: string, data: SubtitleData) => void;
  consumeCachedSubtitle: (text: string) => SubtitleData | null;
  hasCachedSubtitle: (text: string) => boolean;
-  isCacheFull: () => boolean;
 }

 export function normalizeSubtitleCacheKey(text: string): string {
@@ -24,9 +32,15 @@ export function normalizeSubtitleCacheKey(text: string): string {
 export function createSubtitleProcessingController(
  deps: SubtitleProcessingControllerDeps,
 ): SubtitleProcessingController {
-  const SUBTITLE_TOKENIZATION_CACHE_LIMIT = 256;
+  const SUBTITLE_TOKENIZATION_CACHE_LIMIT =
+    deps.cacheLimit && deps.cacheLimit > 0
+      ? deps.cacheLimit
+      : DEFAULT_SUBTITLE_TOKENIZATION_CACHE_LIMIT;
  let latestText = '';
  let lastEmittedText = '';
+  // Tracks the latest provisional plain emit across rapid changes and loop retries
+  // so the same line is never shown plain twice.
+  let lastPlainEmittedText: string | null = null;
  let cacheGeneration = 0;
  let lastEmittedGeneration = 0;
  let processing = false;
@@ -70,9 +84,12 @@ export function createSubtitleProcessingController(
        const startedAtMs = now();

        if (!text.trim()) {
-          deps.emitSubtitle({ text, tokens: null });
+          if (lastPlainEmittedText !== text) {
+            deps.emitSubtitle({ text, tokens: null });
+          }
          lastEmittedText = text;
          lastEmittedGeneration = generation;
+          lastPlainEmittedText = null;
          break;
        }

@@ -82,11 +99,25 @@ export function createSubtitleProcessingController(
          if (cachedTokenized) {
            output = cachedTokenized;
          } else {
+            // Cache miss: show the plain line on time; the tokenized payload
+            // upgrades it once ready. Skipped on refreshes of an already
+            // emitted line so downstream consumers never see a downgrade.
+            if (text !== lastEmittedText && text !== lastPlainEmittedText) {
+              deps.emitSubtitle({ text, tokens: null });
+              lastPlainEmittedText = text;
+            }
            const tokenized = await deps.tokenizeSubtitle(text);
+            // A null result is a transient tokenizer failure, not a verdict on
+            // the line: caching the plain fallback would pin it untokenized for
+            // every later occurrence.
            if (tokenized) {
              output = tokenized;
+              // A result computed before an invalidation must not repopulate the
+              // fresh cache, or the retry below would serve the stale entry.
+              if (generation === cacheGeneration) {
+                setCachedTokenization(text, tokenized);
+              }
            }
-            setCachedTokenization(text, output);
          }
        } catch (error) {
          deps.logDebug?.(`Subtitle tokenization failed: ${(error as Error).message}`);
@@ -107,9 +138,16 @@ export function createSubtitleProcessingController(
          continue;
        }

-        deps.emitSubtitle(output);
+        // An untokenized result adds nothing when this line was already shown,
+        // either provisionally or as an earlier full emit (failed refresh) —
+        // emitting it would duplicate or downgrade what is on screen.
+        const plainAlreadyShown = lastPlainEmittedText === text || lastEmittedText === text;
+        if (!(output.tokens === null && output.text === text && plainAlreadyShown)) {
+          deps.emitSubtitle(output);
+        }
        lastEmittedText = text;
        lastEmittedGeneration = generation;
+        lastPlainEmittedText = null;
        deps.logDebug?.(
          `Subtitle tokenization delivered; elapsed=${now() - startedAtMs}ms, staleDrops=${staleDropCount}`,
        );
@@ -136,6 +174,14 @@ export function createSubtitleProcessingController(
        return;
      }
      latestText = text;
+      if (
+        processing &&
+        text !== lastPlainEmittedText &&
+        !tokenizationCache.has(normalizeSubtitleCacheKey(text))
+      ) {
+        deps.emitSubtitle({ text, tokens: null });
+        lastPlainEmittedText = text;
+      }
      processLatest();
    },
    refreshCurrentSubtitle: (textOverride?: string) => {
@@ -169,13 +215,11 @@ export function createSubtitleProcessingController(
      latestText = text;
      lastEmittedText = text;
      lastEmittedGeneration = cacheGeneration;
+      lastPlainEmittedText = null;
      return cached;
    },
    hasCachedSubtitle: (text: string) => {
      return tokenizationCache.has(normalizeSubtitleCacheKey(text));
    },
-    isCacheFull: () => {
-      return tokenizationCache.size >= SUBTITLE_TOKENIZATION_CACHE_LIMIT;
-    },
  };
 }
@@ -1,6 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import {
+  isSubtitleAnnotationUpgrade,
  serializeInitialSubtitleWebsocketMessage,
  serializeSubtitleMarkup,
  serializeSubtitleWebsocketMessage,
@@ -13,6 +14,40 @@ const frequencyOptions = {
  mode: 'banded' as const,
 };

+test('annotation upgrade requires matching text and cue timing', () => {
+  const current: SubtitleData = {
+    text: '字幕',
+    tokens: null,
+    startTime: 10,
+    endTime: 12,
+  };
+
+  assert.equal(
+    isSubtitleAnnotationUpgrade(current, {
+      ...current,
+      tokens: [],
+    }),
+    true,
+  );
+  assert.equal(
+    isSubtitleAnnotationUpgrade(current, {
+      ...current,
+      tokens: [],
+      startTime: 11,
+    }),
+    false,
+  );
+  assert.equal(
+    isSubtitleAnnotationUpgrade(current, {
+      ...current,
+      text: '次の字幕',
+      tokens: [],
+    }),
+    false,
+  );
+  assert.equal(isSubtitleAnnotationUpgrade(current, current), false);
+});
+
 test('serializeSubtitleMarkup escapes plain text and preserves line breaks', () => {
  const payload: SubtitleData = {
    text: 'a < b\nx & y',
@@ -20,6 +20,20 @@ export type SubtitleWebsocketFrequencyOptions = {

 export type SubtitleWebsocketPayloadMode = 'plain' | 'annotated';

+export function isSubtitleAnnotationUpgrade(
+  current: SubtitleData | null,
+  next: SubtitleData,
+): boolean {
+  return (
+    current !== null &&
+    current.tokens === null &&
+    next.tokens !== null &&
+    current.text === next.text &&
+    current.startTime === next.startTime &&
+    current.endTime === next.endTime
+  );
+}
+
 type SubtitleWebsocketMessageOptions = {
  payloadMode?: SubtitleWebsocketPayloadMode;
 };
@@ -295,6 +295,7 @@ import {
  importYomitanDictionaryFromZip,
  initializeOverlayAnkiIntegration as initializeOverlayAnkiIntegrationCore,
  initializeOverlayRuntime as initializeOverlayRuntimeCore,
+  isSubtitleAnnotationUpgrade,
  isOverlayWindowContentReady,
  jellyfinTicksToSecondsRuntime,
  listJellyfinItemsRuntime,
@@ -1817,6 +1818,8 @@ function withCurrentSubtitleTiming(payload: SubtitleData): SubtitleData {
 }
 function emitSubtitlePayload(payload: SubtitleData): void {
  const timedPayload = withCurrentSubtitleTiming(payload);
+  const currentSubtitleData = appState.currentSubtitleData;
+  const isAnnotationUpgrade = isSubtitleAnnotationUpgrade(currentSubtitleData, timedPayload);
  const frequencyDictionary = configService.getConfig().subtitleStyle.frequencyDictionary;
  const frequencyOptions = {
    enabled: frequencyDictionary.enabled,
@@ -1825,7 +1828,9 @@ function emitSubtitlePayload(payload: SubtitleData): void {
  };
  appState.currentSubtitleData = timedPayload;
  overlayManager.broadcastToOverlayWindows('subtitle:set', timedPayload);
-  subtitleWsService.broadcast(timedPayload, frequencyOptions);
+  if (!isAnnotationUpgrade) {
+    subtitleWsService.broadcast(timedPayload, frequencyOptions);
+  }
  annotationSubtitleWsService.broadcast(timedPayload, frequencyOptions);
  autoplayReadyGate.maybeSignalPluginAutoplayReady(timedPayload, { forceWhilePaused: true });
  subtitlePrefetchService?.resume();
@@ -1955,7 +1960,6 @@ const subtitlePrefetchInitController = createSubtitlePrefetchInitController({
    subtitleProcessingController.preCacheTokenization(text, data);
  },
  hasCachedTokenization: (text) => subtitleProcessingController.hasCachedSubtitle(text),
-  isCacheFull: () => subtitleProcessingController.isCacheFull(),
  logInfo: (message) => logger.info(message),
  logWarn: (message) => logger.warn(message),
  onParsedSubtitleCuesChanged: (cues, sourceKey) => {
@@ -1982,15 +1986,22 @@ const resolveActiveSubtitleSidebarSourceHandler = createResolveActiveSubtitleSid
  getFfmpegPath: () => configService.getConfig().subsync.ffmpeg_path.trim() || 'ffmpeg',
  extractInternalSubtitleTrack: (ffmpegPath, videoPath, track) =>
    extractInternalSubtitleTrackToTempFile(ffmpegPath, videoPath, track),
+  logDebug: (message) => logger.debug(message),
 });

 const refreshSubtitlePrefetchFromActiveTrackHandler =
  createRefreshSubtitlePrefetchFromActiveTrackHandler({
    getMpvClient: () => appState.mpvClient,
    getLastObservedTimePos: () => lastObservedTimePos,
-    shouldKeepExistingCuesOnMissingSource: (videoPath) => isYoutubeMediaPath(videoPath),
+    // Remote media has no extractable on-disk track to fall back to, so a transient
+    // resolve miss (sid briefly 'no', a cycle onto an embedded stream track) would
+    // otherwise drop a working cue list for the rest of the episode.
+    shouldKeepExistingCuesOnMissingSource: (videoPath) =>
+      isYoutubeMediaPath(videoPath) || isRemoteMediaPath(videoPath),
    subtitlePrefetchInitController,
    resolveActiveSubtitleSidebarSource: (input) => resolveActiveSubtitleSidebarSourceHandler(input),
+    logDebug: (message) => logger.debug(message),
+    logWarn: (message) => logger.warn(message),
  });

 const subtitlePrefetchRuntime = {
@@ -2994,6 +3005,8 @@ const {
        streamIndex,
        delaySeconds,
      }),
+    initSubtitlePrefetch: (sourcePath) =>
+      subtitlePrefetchRuntime.refreshSubtitleSidebarFromSource(sourcePath),
    logDebug: (message, error) => {
      logger.debug(message, error);
    },
@@ -4366,6 +4379,7 @@ const {
    refreshDiscordPresence: () => {
      discordPresenceRuntime.publishDiscordPresence();
    },
+    logSubtitleProcessingDebug: (message: string) => logger.debug(message),
    ensureImmersionTrackerInitialized: () => {
      ensureImmersionTrackerStarted();
    },
@@ -176,6 +176,29 @@ test('subtitle sidebar media path tag is assigned after prefetch succeeds', () =
  );
 });

+test('remote media keeps parsed cues when the active subtitle source cannot be resolved', () => {
+  const source = readMainSource();
+  const actionBlock = source.match(
+    /createRefreshSubtitlePrefetchFromActiveTrackHandler\(\{(?<body>[\s\S]*?)\n  \}\);/,
+  )?.groups?.body;
+
+  assert.ok(actionBlock);
+  assert.match(actionBlock, /isYoutubeMediaPath\(videoPath\) \|\| isRemoteMediaPath\(videoPath\)/);
+});
+
+test('jellyfin subtitle preload seeds the tokenization prefetch directly', () => {
+  const source = readMainSource();
+  const actionBlock = source.match(
+    /preloadJellyfinExternalSubtitlesMainDeps:\s*\{(?<body>[\s\S]*?)\n  \},/,
+  )?.groups?.body;
+
+  assert.ok(actionBlock);
+  assert.match(
+    actionBlock,
+    /initSubtitlePrefetch: \(sourcePath\) =>\s*subtitlePrefetchRuntime\.refreshSubtitleSidebarFromSource\(sourcePath\),/,
+  );
+});
+
 test('update overlay notification action triggers install flow', () => {
  const source = readMainSource();
  const runtimeSource = readSource('src/main/runtime/overlay-notifications-runtime.ts');
@@ -590,6 +613,35 @@ test('subtitle broadcasts share one frequency options snapshot per emitted paylo
  );
 });

+test('annotation upgrades skip the duplicate basic websocket event', () => {
+  const source = readMainSource();
+  const emitBlock = source.match(
+    /function emitSubtitlePayload\(payload: SubtitleData\): void \{(?<body>[\s\S]*?)\n\}/,
+  )?.groups?.body;
+
+  assert.ok(emitBlock);
+  assert.match(
+    emitBlock,
+    /const isAnnotationUpgrade = isSubtitleAnnotationUpgrade\(currentSubtitleData, timedPayload\);/,
+  );
+  assert.match(
+    emitBlock,
+    /if \(!isAnnotationUpgrade\) \{\s+subtitleWsService\.broadcast\(timedPayload, frequencyOptions\);\s+\}/,
+  );
+  assert.equal(
+    (emitBlock.match(/overlayManager\.broadcastToOverlayWindows\('subtitle:set'/g) ?? []).length,
+    1,
+  );
+  assert.equal(
+    (
+      emitBlock.match(
+        /annotationSubtitleWsService\.broadcast\(timedPayload, frequencyOptions\)/g,
+      ) ?? []
+    ).length,
+    1,
+  );
+});
+
 test('websocket frequency options callbacks each read one configuration snapshot', () => {
  const source = readMainSource();
  const subtitleBlock = source.match(
@@ -28,6 +28,9 @@ export function createBuildPreloadJellyfinExternalSubtitlesMainDepsHandler(
      ? (itemId, streamIndex, delaySeconds) =>
          deps.saveSubtitleDelay!(itemId, streamIndex, delaySeconds)
      : undefined,
+    initSubtitlePrefetch: deps.initSubtitlePrefetch
+      ? (sourcePath) => deps.initSubtitlePrefetch!(sourcePath)
+      : undefined,
    logDebug: (message: string, error: unknown) => deps.logDebug(message, error),
  });
 }
@@ -40,6 +40,9 @@ function makeDeps(overrides: {
  >[0]['setActiveSubtitleDelayKey'];
  loadSubtitleSourceText?: (source: string) => Promise<string>;
  saveSubtitleDelay?: (itemId: string, streamIndex: number, delaySeconds: number) => void;
+  initSubtitlePrefetch?: Parameters<
+    typeof createPreloadJellyfinExternalSubtitlesHandler
+  >[0]['initSubtitlePrefetch'];
  logDebug?: Parameters<typeof createPreloadJellyfinExternalSubtitlesHandler>[0]['logDebug'];
 }) {
  return {
@@ -58,6 +61,7 @@ function makeDeps(overrides: {
    setActiveSubtitleDelayKey: overrides.setActiveSubtitleDelayKey,
    loadSubtitleSourceText: overrides.loadSubtitleSourceText,
    saveSubtitleDelay: overrides.saveSubtitleDelay,
+    initSubtitlePrefetch: overrides.initSubtitlePrefetch,
    logDebug: overrides.logDebug ?? (() => {}),
  };
 }
@@ -134,6 +138,92 @@ test('preload jellyfin subtitles caches external tracks locally and chooses japa
  ]);
 });

+test('preload jellyfin subtitles starts prefetch for the selected japanese track', async () => {
+  const prefetched: string[] = [];
+  const preload = createPreloadJellyfinExternalSubtitlesHandler(
+    makeDeps({
+      listJellyfinSubtitleTracks: async () => [
+        { index: 0, language: 'jpn', title: 'Japanese', deliveryUrl: 'https://sub/a.srt' },
+        { index: 1, language: 'eng', title: 'English', deliveryUrl: 'https://sub/b.srt' },
+      ],
+      getMpvClient: () => ({
+        requestProperty: async () => [
+          {
+            type: 'sub',
+            id: 5,
+            lang: 'jpn',
+            title: 'Japanese',
+            external: true,
+            'external-filename': '/tmp/subminer-jellyfin-subtitles/0.srt',
+          },
+          {
+            type: 'sub',
+            id: 6,
+            lang: 'eng',
+            title: 'English',
+            external: true,
+            'external-filename': '/tmp/subminer-jellyfin-subtitles/1.srt',
+          },
+        ],
+      }),
+      cacheSubtitleTrack: async (track) => ({
+        path: `/tmp/subminer-jellyfin-subtitles/${track.index}.srt`,
+        cleanupDir: '/tmp/subminer-jellyfin-subtitles',
+      }),
+      initSubtitlePrefetch: (sourcePath) => {
+        prefetched.push(sourcePath);
+      },
+    }),
+  );
+
+  await preload({ session, clientInfo, itemId: 'item-1' });
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.deepEqual(prefetched, ['/tmp/subminer-jellyfin-subtitles/0.srt']);
+});
+
+test('preload jellyfin subtitles survives prefetch start failures', async () => {
+  const logs: string[] = [];
+  const commands: Array<Array<string | number>> = [];
+  const preload = createPreloadJellyfinExternalSubtitlesHandler(
+    makeDeps({
+      listJellyfinSubtitleTracks: async () => [
+        { index: 0, language: 'jpn', title: 'Japanese', deliveryUrl: 'https://sub/a.srt' },
+      ],
+      getMpvClient: () => ({
+        requestProperty: async () => [
+          {
+            type: 'sub',
+            id: 5,
+            lang: 'jpn',
+            title: 'Japanese',
+            external: true,
+            'external-filename': '/tmp/subminer-jellyfin-subtitles/0.srt',
+          },
+        ],
+      }),
+      sendMpvCommand: (command) => commands.push(command),
+      cacheSubtitleTrack: async (track) => ({
+        path: `/tmp/subminer-jellyfin-subtitles/${track.index}.srt`,
+        cleanupDir: '/tmp/subminer-jellyfin-subtitles',
+      }),
+      initSubtitlePrefetch: async () => {
+        throw new Error('parse failed');
+      },
+      logDebug: (message) => logs.push(message),
+    }),
+  );
+
+  await preload({ session, clientInfo, itemId: 'item-1' });
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.deepEqual(logs, ['Failed to start subtitle prefetch for Jellyfin subtitle']);
+  assert.ok(
+    commands.some((command) => command[0] === 'set_property' && command[1] === 'sid'),
+    'subtitle selection still happens when prefetch start fails',
+  );
+});
+
 test('preload jellyfin subtitles stages tracks without temporary subtitle selection', async () => {
  const commands: Array<Array<string | number>> = [];
  const preload = createPreloadJellyfinExternalSubtitlesHandler(
@@ -320,6 +320,7 @@ export function createPreloadJellyfinExternalSubtitlesHandler(deps: {
  setActiveSubtitleDelayKey?: (key: JellyfinSubtitleDelayKey | null) => void;
  loadSubtitleSourceText?: (source: string) => Promise<string>;
  saveSubtitleDelay?: (itemId: string, streamIndex: number, delaySeconds: number) => boolean | void;
+  initSubtitlePrefetch?: (sourcePath: string) => void | Promise<void>;
  logDebug: (message: string, error: unknown) => void;
 }): PreloadJellyfinExternalSubtitlesHandler {
  const activeCacheDirs = new Set<string>();
@@ -329,6 +330,18 @@ export function createPreloadJellyfinExternalSubtitlesHandler(deps: {
    deps.sendMpvCommand(['set_property', 'sub-delay', 0]);
  }

+  // mpv's sid property-change is the only thing that normally starts prefetching, so a
+  // coalesced or missed event leaves the whole episode uncached. The downloaded path is
+  // known here, so seed the pipeline directly instead of waiting on the observer.
+  function startSubtitlePrefetchForCachedTrack(sourcePath: string): void {
+    if (!deps.initSubtitlePrefetch) return;
+    void Promise.resolve()
+      .then(() => deps.initSubtitlePrefetch!(sourcePath))
+      .catch((error) => {
+        deps.logDebug('Failed to start subtitle prefetch for Jellyfin subtitle', error);
+      });
+  }
+
  function cleanupActiveCache(): void {
    const dirs = [...activeCacheDirs];
    if (dirs.length === 0) return;
@@ -438,6 +451,7 @@ export function createPreloadJellyfinExternalSubtitlesHandler(deps: {
            }
          }
          deps.sendMpvCommand(['set_property', 'sid', japanesePrimaryId]);
+          startSubtitlePrefetchForCachedTrack(selectedCachedTrack.path);
        } else {
          deps.setActiveSubtitleDelayKey?.(null);
          resetManagedSubtitleDelay();
@@ -70,6 +70,24 @@ test('subtitle change handler broadcasts cached annotated payload immediately wh
  ]);
 });

+test('subtitle change handler logs debug when a cached payload is emitted immediately', () => {
+  const debugs: string[] = [];
+  const handler = createHandleMpvSubtitleChangeHandler({
+    setCurrentSubText: () => {},
+    getImmediateSubtitlePayload: (text) => (text ? { text, tokens: [] } : null),
+    broadcastSubtitle: () => {},
+    onSubtitleChange: () => {},
+    refreshDiscordPresence: () => {},
+    logDebug: (message) => debugs.push(message),
+  });
+
+  handler({ text: 'キャッシュ済みの行' });
+  handler({ text: '' });
+
+  assert.equal(debugs.length, 1);
+  assert.match(debugs[0]!, /cached subtitle/);
+});
+
 test('subtitle change handler emits cached annotation after forwarding the subtitle change', () => {
  const calls: string[] = [];
  const handler = createHandleMpvSubtitleChangeHandler({
@@ -20,11 +20,15 @@ export function createHandleMpvSubtitleChangeHandler(deps: {
  broadcastSubtitle: (payload: SubtitleData) => void;
  onSubtitleChange: (text: string) => void;
  refreshDiscordPresence: () => void;
+  logDebug?: (message: string) => void;
 }) {
  return ({ text }: { text: string }): void => {
    deps.setCurrentSubText(text);
    const immediatePayload = deps.getImmediateSubtitlePayload?.(text) ?? null;
    if (immediatePayload) {
+      deps.logDebug?.(
+        `[subtitle-processing] emitted cached subtitle immediately (${text.length} chars)`,
+      );
      deps.onSubtitleChange(text);
      (deps.emitImmediateSubtitle ?? deps.broadcastSubtitle)(immediatePayload);
    } else {
@@ -47,6 +47,7 @@ export function createBindMpvMainEventHandlersHandler(deps: {
  emitImmediateSubtitle?: (payload: SubtitleData) => void;
  broadcastSubtitle: (payload: SubtitleData) => void;
  onSubtitleChange: (text: string) => void;
+  logSubtitleProcessingDebug?: (message: string) => void;
  refreshDiscordPresence: () => void;

  setCurrentSubAssText: (text: string) => void;
@@ -123,6 +124,9 @@ export function createBindMpvMainEventHandlersHandler(deps: {
        : undefined,
      broadcastSubtitle: (payload) => deps.broadcastSubtitle(payload),
      onSubtitleChange: (text) => deps.onSubtitleChange(text),
+      logDebug: deps.logSubtitleProcessingDebug
+        ? (message) => deps.logSubtitleProcessingDebug?.(message)
+        : undefined,
      refreshDiscordPresence: () => deps.refreshDiscordPresence(),
    });
    const handleMpvSubtitleAssChange = createHandleMpvSubtitleAssChangeHandler({
@@ -54,6 +54,7 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
  getImmediateSubtitlePayload?: (text: string) => SubtitleData | null;
  emitImmediateSubtitle?: (payload: SubtitleData) => void;
  onSubtitleChange: (text: string) => void;
+  logSubtitleProcessingDebug?: (message: string) => void;
  onSubtitleTrackChange?: (sid: number | null) => void;
  onSubtitleTrackListChange?: (trackList: unknown[] | null) => void;
  updateCurrentMediaPath: (path: string) => void;
@@ -155,6 +156,9 @@ export function createBuildBindMpvMainEventHandlersMainDepsHandler(deps: {
    broadcastSubtitle: (payload: SubtitleData) =>
      deps.broadcastToOverlayWindows('subtitle:set', payload),
    onSubtitleChange: (text: string) => deps.onSubtitleChange(text),
+    logSubtitleProcessingDebug: deps.logSubtitleProcessingDebug
+      ? (message: string) => deps.logSubtitleProcessingDebug!(message)
+      : undefined,
    onSubtitleTrackChange: deps.onSubtitleTrackChange
      ? (sid: number | null) => deps.onSubtitleTrackChange!(sid)
      : undefined,
@@ -54,7 +54,6 @@ test('latest subtitle prefetch init wins over stale async loads', async () => {
    }),
    tokenizeSubtitle: async () => null,
    preCacheTokenization: () => {},
-    isCacheFull: () => false,
    logInfo: () => {},
    logWarn: () => {},
  });
@@ -99,7 +98,6 @@ test('cancelPendingInit prevents an in-flight load from attaching a stale servic
    }),
    tokenizeSubtitle: async () => null,
    preCacheTokenization: () => {},
-    isCacheFull: () => false,
    logInfo: () => {},
    logWarn: () => {},
  });
@@ -137,7 +135,6 @@ test('subtitle prefetch init publishes parsed cues and clears them on cancel', a
    }),
    tokenizeSubtitle: async () => null,
    preCacheTokenization: () => {},
-    isCacheFull: () => false,
    logInfo: () => {},
    logWarn: () => {},
    onParsedSubtitleCuesChanged: (cues) => {
@@ -181,7 +178,6 @@ test('subtitle prefetch init publishes the provided stable source key instead of
    }),
    tokenizeSubtitle: async () => null,
    preCacheTokenization: () => {},
-    isCacheFull: () => false,
    logInfo: () => {},
    logWarn: () => {},
    onParsedSubtitleCuesChanged: (_cues, source) => {
@@ -222,7 +218,6 @@ test('subtitle prefetch init clears parsed cues when initialization fails', asyn
    }),
    tokenizeSubtitle: async () => null,
    preCacheTokenization: () => {},
-    isCacheFull: () => false,
    logInfo: () => {},
    logWarn: () => {},
    onParsedSubtitleCuesChanged: (cues) => {
@@ -234,3 +229,25 @@ test('subtitle prefetch init clears parsed cues when initialization fails', asyn

  assert.deepEqual(cueUpdates, [null]);
 });
+
+test('subtitle prefetch init logs a warning when the source parses to zero cues', async () => {
+  const warnings: string[] = [];
+  const controller = createSubtitlePrefetchInitController({
+    getCurrentService: () => null,
+    setCurrentService: () => {},
+    loadSubtitleSourceText: async () => 'not really subtitles',
+    parseSubtitleCues: (): SubtitleCue[] => [],
+    createSubtitlePrefetchService: () => {
+      throw new Error('should not create a service without cues');
+    },
+    tokenizeSubtitle: async () => null,
+    preCacheTokenization: () => {},
+    logInfo: () => {},
+    logWarn: (message) => warnings.push(message),
+  });
+
+  await controller.initSubtitlePrefetch('/tmp/broken.ass', 0);
+
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0]!, /\[subtitle-prefetch\].*0 cues.*\/tmp\/broken\.ass/);
+});
@@ -14,7 +14,6 @@ export interface SubtitlePrefetchInitControllerDeps {
  tokenizeSubtitle: (text: string) => Promise<SubtitleData | null>;
  preCacheTokenization: (text: string, data: SubtitleData) => void;
  hasCachedTokenization?: (text: string) => boolean;
-  isCacheFull: () => boolean;
  logInfo: (message: string) => void;
  logWarn: (message: string) => void;
  onParsedSubtitleCuesChanged?: (cues: SubtitleCue[] | null, sourceKey: string | null) => void;
@@ -59,6 +58,9 @@ export function createSubtitlePrefetchInitController(
      const cues = deps.parseSubtitleCues(content, sourcePath);
      if (revision !== initRevision || cues.length === 0) {
        if (revision === initRevision) {
+          deps.logWarn(
+            `[subtitle-prefetch] parsed 0 cues from ${sourcePath}; prefetch disabled for this source`,
+          );
          deps.onParsedSubtitleCuesChanged?.(null, null);
        }
        return;
@@ -69,7 +71,6 @@ export function createSubtitlePrefetchInitController(
        tokenizeSubtitle: (text) => deps.tokenizeSubtitle(text),
        preCacheTokenization: (text, data) => deps.preCacheTokenization(text, data),
        hasCachedTokenization: (text) => deps.hasCachedTokenization?.(text) ?? false,
-        isCacheFull: () => deps.isCacheFull(),
      });

      if (revision !== initRevision) {
@@ -130,3 +130,121 @@ test('subtitle prefetch runtime does not extract internal subtitle tracks from r
  assert.equal(resolved, null);
  assert.equal(extracted, false);
 });
+
+test('subtitle prefetch refresh logs a warning when source resolution throws', async () => {
+  const warnings: string[] = [];
+  const refresh = createRefreshSubtitlePrefetchFromActiveTrackHandler({
+    getMpvClient: () => ({
+      connected: true,
+      requestProperty: async (name) => (name === 'path' ? '/media/video.mkv' : null),
+    }),
+    getLastObservedTimePos: () => 0,
+    subtitlePrefetchInitController: {
+      cancelPendingInit: () => {},
+      initSubtitlePrefetch: async () => {},
+    },
+    resolveActiveSubtitleSidebarSource: async () => {
+      throw new Error('ffmpeg ENOENT');
+    },
+    logWarn: (message) => warnings.push(message),
+  });
+
+  await refresh();
+
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0]!, /\[subtitle-prefetch\].*ffmpeg ENOENT/);
+});
+
+test('subtitle prefetch refresh logs debug when mpv client is not connected', async () => {
+  const debugs: string[] = [];
+  const refresh = createRefreshSubtitlePrefetchFromActiveTrackHandler({
+    getMpvClient: () => null,
+    getLastObservedTimePos: () => 0,
+    subtitlePrefetchInitController: {
+      cancelPendingInit: () => {},
+      initSubtitlePrefetch: async () => {},
+    },
+    resolveActiveSubtitleSidebarSource: async () => null,
+    logDebug: (message) => debugs.push(message),
+  });
+
+  await refresh();
+
+  assert.equal(debugs.length, 1);
+  assert.match(debugs[0]!, /\[subtitle-prefetch\].*not connected/);
+});
+
+test('subtitle prefetch refresh logs debug when no subtitle source resolves', async () => {
+  const debugs: string[] = [];
+  const cancels: number[] = [];
+  const refresh = createRefreshSubtitlePrefetchFromActiveTrackHandler({
+    getMpvClient: () => ({
+      connected: true,
+      requestProperty: async (name) => (name === 'path' ? '/media/video.mkv' : null),
+    }),
+    getLastObservedTimePos: () => 0,
+    subtitlePrefetchInitController: {
+      cancelPendingInit: () => {
+        cancels.push(1);
+      },
+      initSubtitlePrefetch: async () => {},
+    },
+    resolveActiveSubtitleSidebarSource: async () => null,
+    logDebug: (message) => debugs.push(message),
+  });
+
+  await refresh();
+
+  assert.deepEqual(cancels, [1]);
+  assert.equal(debugs.length, 1);
+  assert.match(debugs[0]!, /\[subtitle-prefetch\].*no active subtitle source/);
+});
+
+test('subtitle source resolver logs debug when internal track extraction is unavailable', async () => {
+  const debugs: string[] = [];
+  const resolveSource = createResolveActiveSubtitleSidebarSourceHandler({
+    getFfmpegPath: () => 'ffmpeg',
+    extractInternalSubtitleTrack: async () => null,
+    logDebug: (message) => debugs.push(message),
+  });
+
+  const resolved = await resolveSource({
+    currentExternalFilenameRaw: null,
+    currentTrackRaw: {
+      type: 'sub',
+      id: 3,
+      'ff-index': 7,
+      codec: 'hdmv_pgs_subtitle',
+    },
+    trackListRaw: [],
+    sidRaw: 3,
+    videoPath: '/media/video.mkv',
+  });
+
+  assert.equal(resolved, null);
+  assert.equal(debugs.length, 1);
+  assert.match(debugs[0]!, /\[subtitle-prefetch\].*extraction.*hdmv_pgs_subtitle/);
+});
+
+test('subtitle source resolver logs debug when no active subtitle track is selected', async () => {
+  const debugs: string[] = [];
+  const resolveSource = createResolveActiveSubtitleSidebarSourceHandler({
+    getFfmpegPath: () => 'ffmpeg',
+    extractInternalSubtitleTrack: async () => {
+      throw new Error('should not extract without a track');
+    },
+    logDebug: (message) => debugs.push(message),
+  });
+
+  const resolved = await resolveSource({
+    currentExternalFilenameRaw: null,
+    currentTrackRaw: null,
+    trackListRaw: [],
+    sidRaw: null,
+    videoPath: '/media/video.mkv',
+  });
+
+  assert.equal(resolved, null);
+  assert.equal(debugs.length, 1);
+  assert.match(debugs[0]!, /\[subtitle-prefetch\].*no active subtitle track/);
+});
@@ -86,6 +86,7 @@ export function createResolveActiveSubtitleSidebarSourceHandler(deps: {
    videoPath: string,
    track: MpvSubtitleTrackLike,
  ) => Promise<{ path: string; cleanup: () => Promise<void> } | null>;
+  logDebug?: (message: string) => void;
 }) {
  return async (input: {
    currentExternalFilenameRaw: unknown;
@@ -104,6 +105,7 @@ export function createResolveActiveSubtitleSidebarSourceHandler(deps: {

    const track = getActiveSubtitleTrack(input.currentTrackRaw, input.trackListRaw, input.sidRaw);
    if (!track) {
+      deps.logDebug?.('[subtitle-prefetch] no active subtitle track selected yet');
      return null;
    }

@@ -114,6 +116,7 @@ export function createResolveActiveSubtitleSidebarSourceHandler(deps: {
    }

    if (isRemoteMediaPath(input.videoPath)) {
+      deps.logDebug?.('[subtitle-prefetch] skipping internal subtitle extraction for remote media');
      return null;
    }

@@ -123,6 +126,9 @@ export function createResolveActiveSubtitleSidebarSourceHandler(deps: {
      track,
    );
    if (!extracted) {
+      deps.logDebug?.(
+        `[subtitle-prefetch] internal subtitle extraction unavailable (codec=${String(track.codec ?? 'unknown')}, ff-index=${String(track['ff-index'] ?? 'unknown')})`,
+      );
      return null;
    }

@@ -144,10 +150,13 @@ export function createRefreshSubtitlePrefetchFromActiveTrackHandler(deps: {
  resolveActiveSubtitleSidebarSource: (
    input: Parameters<ReturnType<typeof createResolveActiveSubtitleSidebarSourceHandler>>[0],
  ) => Promise<ActiveSubtitleSidebarSource | null>;
+  logDebug?: (message: string) => void;
+  logWarn?: (message: string) => void;
 }) {
  return async (): Promise<void> => {
    const client = deps.getMpvClient();
    if (!client?.connected) {
+      deps.logDebug?.('[subtitle-prefetch] skipped refresh: mpv client not connected');
      return;
    }

@@ -162,6 +171,7 @@ export function createRefreshSubtitlePrefetchFromActiveTrackHandler(deps: {
        ]);
      const videoPath = typeof videoPathRaw === 'string' ? videoPathRaw : '';
      if (!videoPath) {
+        deps.logDebug?.('[subtitle-prefetch] skipped refresh: no media path');
        deps.subtitlePrefetchInitController.cancelPendingInit();
        return;
      }
@@ -175,8 +185,14 @@ export function createRefreshSubtitlePrefetchFromActiveTrackHandler(deps: {
      });
      if (!resolvedSource) {
        if (deps.shouldKeepExistingCuesOnMissingSource?.(videoPath) === true) {
+          deps.logDebug?.(
+            '[subtitle-prefetch] no active subtitle source resolved; keeping existing cues',
+          );
          return;
        }
+        deps.logDebug?.(
+          '[subtitle-prefetch] no active subtitle source resolved; cancelling prefetch',
+        );
        deps.subtitlePrefetchInitController.cancelPendingInit();
        return;
      }
@@ -190,8 +206,12 @@ export function createRefreshSubtitlePrefetchFromActiveTrackHandler(deps: {
      } finally {
        await resolvedSource.cleanup?.();
      }
-    } catch {
-      // Skip refresh when the track query fails.
+    } catch (error) {
+      deps.logWarn?.(
+        `[subtitle-prefetch] failed to refresh from active track: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
    }
  };
 }
Author	SHA1	Message	Date
sudacode	fe4dacc1e7	fix(overlay): show plain subtitle line immediately on tokenization cache miss (#184 )	2026-08-04 01:55:52 -07:00
sudacode	b08cd0db35	fix(streaming): keep subtitle tokenization prefetch warm for full episodes (#183 )	2026-08-03 21:22:18 -07:00
sudacode	bffb1c5982	fix(logging): surface subtitle processing debug/warn logs (#182 )	2026-08-03 20:44:39 -07:00