@torrent-tv/proxy 2.88.3 → 2.88.4

package/test/subtitle-cue-framing.test.js

@@ -1,200 +1,200 @@
-/**
- * @file Two axes, kept apart: the framing a CONTAINER puts round a cue, and the
- * markup the CODEC puts inside it.
- *
- * Field 2026-09-03, an English track of an embedded `.mkv`: the viewer was
- * shown `21,0,Default,,0000,0000,0000,,I am the powerful Demon King of the
- * Sixth Heaven.` — the whole dialogue row, fields and all. The cause was one
- * function doing both jobs and deciding which framing it held by counting
- * commas: it expected the ten fields a row has in a FILE, a Matroska block
- * carries nine, so it returned the row untouched.
- *
- * What each check here pins is therefore not "ASS is stripped" but "the right
- * side answers": the container takes off what it put on, and the codec takes
- * off what it put in. The case that matters most is the last one — the same
- * line of dialogue, stored two ways, coming out identical.
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import { AviContainer } from "../services/media/container/AviContainer.js";
-import { MatroskaContainer } from "../services/media/container/MatroskaContainer.js";
-import { Mp4Container } from "../services/media/container/Mp4Container.js";
-import { SubtitleFileContainer } from "../services/media/container/SubtitleFileContainer.js";
-import { MarkupKind, TextSubtitleTrack } from "../services/media/tracks/TextSubtitleTrack.js";
-
-/** The line from the field report, as Matroska stores it. */
-const FIELD_BLOCK =
-  "21,0,Default,,0000,0000,0000,,I am the powerful Demon King of the Sixth Heaven. Good... Evil...";
-
-function block(text) {
-  return Buffer.from(text, "utf8");
-}
-
-test("a Matroska ASS block gives up its text and nothing else", () => {
-  // Nine fields exactly, and no comma in the dialogue: the shape that defeated
-  // the old field count and put the whole row on the viewer's screen.
-  assert.equal(
-    MatroskaContainer.cueTextOf(block(FIELD_BLOCK), "S_TEXT/ASS"),
-    "I am the powerful Demon King of the Sixth Heaven. Good... Evil..."
-  );
-});
-
-test("commas in the dialogue are dialogue, not fields", () => {
-  assert.equal(
-    MatroskaContainer.cueTextOf(block("7,0,Main,Nobunaga,0000,0000,0000,,Yes, of course, my lord"), "S_TEXT/ASS"),
-    "Yes, of course, my lord"
-  );
-});
-
-test("an SSA block is framed the same way as an ASS one", () => {
-  // SSA writes `Marked` where ASS writes `Layer`; the count is the same and so
-  // is the answer.
-  assert.equal(
-    MatroskaContainer.cueTextOf(block("3,,Default,,0000,0000,0000,,Toujours rien."), "S_TEXT/SSA"),
-    "Toujours rien."
-  );
-});
-
-test("a row too short to hold a text field yields nothing to show", () => {
-  assert.equal(MatroskaContainer.cueTextOf(block("21,0,Default,,0000"), "S_TEXT/ASS"), "");
-  assert.equal(MatroskaContainer.cueTextOf(block("21,0,Default,,0000,0000,0000,,"), "S_TEXT/ASS"), "");
-});
-
-test("a plain-text Matroska block is not touched at all", () => {
-  // `S_TEXT/UTF8` has no framing: the block IS the text, commas included.
-  const line = "Yes, of course, my lord";
-  assert.equal(MatroskaContainer.cueTextOf(block(line), "S_TEXT/UTF8"), line);
-  assert.equal(MatroskaContainer.cueTextOf(block(line), "S_TEXT/WEBVTT"), line);
-});
-
-test("an MP4 sample is unframed by the MP4, length prefix and all", () => {
-  const text = Buffer.from("Yes, of course, my lord", "utf8");
-  const sample = Buffer.concat([Buffer.from([0x00, text.length]), text]);
-  assert.equal(Mp4Container.cueTextOf(sample, "tx3g"), "Yes, of course, my lord");
-});
-
-test("a container with no framing of its own refuses to guess", () => {
-  // AVI declares no subtitle tracks, so no cue can reach it. If one ever did,
-  // the answer must be an error and not a guess at somebody else's framing.
-  assert.throws(() => AviContainer.cueTextOf(block("x"), "S_TEXT/ASS"), /cueTextOf not implemented/);
-});
-
-test("ASS markup is taken off wherever the text came from", () => {
-  assert.equal(TextSubtitleTrack.plainTextOf("{\\pos(640,620)}Hello{\\i1} there{\\i0}", "S_TEXT/ASS"), "Hello there");
-  assert.equal(TextSubtitleTrack.plainTextOf("First\\NSecond\\nThird", "S_TEXT/ASS"), "First\nSecond\nThird");
-  assert.equal(TextSubtitleTrack.plainTextOf("Wide\\hspace", "S_TEXT/ASS"), "Wide space");
-  // The same text under a codec that has no such markup keeps its characters.
-  assert.equal(TextSubtitleTrack.plainTextOf("{\\pos(1,2)}Hello", "S_TEXT/UTF8"), "{\\pos(1,2)}Hello");
-});
-
-test("a codec is known by any of its names", () => {
-  assert.equal(TextSubtitleTrack.markupKindOf("S_TEXT/ASS"), MarkupKind.ASS);
-  assert.equal(TextSubtitleTrack.markupKindOf(".ASS"), MarkupKind.ASS);
-  assert.equal(TextSubtitleTrack.markupKindOf("S_TEXT/UTF8"), MarkupKind.NONE);
-  assert.equal(TextSubtitleTrack.markupKindOf("wvtt"), MarkupKind.NONE);
-  // Unknown: shown as it is, rather than refused.
-  assert.equal(TextSubtitleTrack.markupKindOf("S_TEXT/SOMETHING"), MarkupKind.NONE);
-});
-
-test("a text track answers for its own markup", () => {
-  const track = new TextSubtitleTrack({ trackNumber: 3, declaredIndex: 0, codecId: "S_TEXT/ASS" });
-  assert.equal(track.markupKind, MarkupKind.ASS);
-  assert.equal(track.plainText("{\\be1}Готовьте лучников"), "Готовьте лучников");
-});
-
-test("a file states its own column order and is obeyed", () => {
-  // This `Format:` has no `Name` column, so the text is the ninth field and not
-  // the tenth. A reader that assumed a position would take the effect field as
-  // the line — which is the file-side form of the defect this suite is about.
-  const file = [
-    "[Script Info]",
-    "ScriptType: v4.00+",
-    "[Events]",
-    "Format: Layer, Start, End, Style, MarginL, MarginR, MarginV, Effect, Text",
-    "Dialogue: 0,0:00:01.00,0:00:03.50,Default,0000,0000,0000,,Ты видишь их?",
-    ""
-  ].join("\n");
-
-  const cues = new SubtitleFileContainer({ extension: ".ass" }).readCues(file);
-  assert.deepEqual(cues, [{ startSeconds: 1, endSeconds: 3.5, text: "Ты видишь их?" }]);
-});
-
-test("a dialogue row before any Format line is not guessed at", () => {
-  const file = ["[Events]", "Dialogue: 0,0:00:01.00,0:00:02.00,Default,,0,0,0,,Ignored", ""].join("\n");
-  assert.deepEqual(new SubtitleFileContainer({ extension: ".ass" }).readCues(file), []);
-});
-
-test("SubRip cues keep their words and lose their numbering", () => {
-  const file = [
-    "1",
-    "00:00:01,000 --> 00:00:03,500",
-    "Ты видишь их?",
-    "",
-    "2",
-    "00:01:02,250 --> 00:01:04,000",
-    "<i>Да.</i>",
-    "Но не столько вижу.",
-    ""
-  ].join("\n");
-
-  const cues = new SubtitleFileContainer({ extension: ".srt" }).readCues(file);
-  assert.deepEqual(cues, [
-    { startSeconds: 1, endSeconds: 3.5, text: "Ты видишь их?" },
-    { startSeconds: 62.25, endSeconds: 64, text: "<i>Да.</i>\nНо не столько вижу." }
-  ]);
-});
-
-test("a SubRip file with no blank line between cues does not swallow the ordinal", () => {
-  const file = [
-    "1",
-    "00:00:01,000 --> 00:00:02,000",
-    "First",
-    "2",
-    "00:00:03,000 --> 00:00:04,000",
-    "Second"
-  ].join("\n");
-
-  const cues = new SubtitleFileContainer({ extension: ".srt" }).readCues(file);
-  assert.deepEqual(cues.map((cue) => cue.text), ["First", "Second"]);
-});
-
-test("a WebVTT file is passed through, not taken apart", () => {
-  const file = "WEBVTT\n\nSTYLE\n::cue { color: yellow }\n\nintro\n00:00:01.000 --> 00:00:02.000\nHello\n";
-  assert.equal(SubtitleFileContainer.toVtt(file, ".vtt"), file);
-  assert.equal(new SubtitleFileContainer({ extension: ".vtt" }).readCues(file), null);
-});
-
-test("a format nothing here reads is refused rather than mangled", () => {
-  assert.equal(SubtitleFileContainer.toVtt("whatever", ".sup"), null);
-  assert.equal(SubtitleFileContainer.toVtt("whatever", ".ttml"), null);
-});
-
-test("one line of dialogue, two framings, one result", () => {
-  // The whole point of the split. The same ASS line stored in a Matroska block
-  // and in a file must reach the viewer identically, and neither path may know
-  // anything about the other.
-  const spoken = "Yes, of course, my lord";
-  const markup = `{\\pos(640,620)}${spoken}`;
-
-  const fromBlock = TextSubtitleTrack.finalizeCues(
-    [{
-      startSeconds: 1,
-      endSeconds: 3,
-      text: MatroskaContainer.cueTextOf(block(`21,0,Default,,0000,0000,0000,,${markup}`), "S_TEXT/ASS")
-    }],
-    "S_TEXT/ASS"
-  );
-
-  const fromFile = new SubtitleFileContainer({ extension: ".ass" }).readCues([
-    "[Events]",
-    "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
-    `Dialogue: 0,0:00:01.00,0:00:03.00,Default,,0000,0000,0000,,${markup}`,
-    ""
-  ].join("\n"));
-
-  assert.equal(fromBlock[0].text, spoken);
-  assert.equal(TextSubtitleTrack.finalizeCues(fromFile, ".ass")[0].text, spoken);
-  assert.equal(TextSubtitleTrack.cuesToVtt(fromBlock, "S_TEXT/ASS"), TextSubtitleTrack.cuesToVtt(fromFile, ".ass"));
-});
+/**
+ * @file Two axes, kept apart: the framing a CONTAINER puts round a cue, and the
+ * markup the CODEC puts inside it.
+ *
+ * Field 2026-09-03, an English track of an embedded `.mkv`: the viewer was
+ * shown `21,0,Default,,0000,0000,0000,,I am the powerful Demon King of the
+ * Sixth Heaven.` — the whole dialogue row, fields and all. The cause was one
+ * function doing both jobs and deciding which framing it held by counting
+ * commas: it expected the ten fields a row has in a FILE, a Matroska block
+ * carries nine, so it returned the row untouched.
+ *
+ * What each check here pins is therefore not "ASS is stripped" but "the right
+ * side answers": the container takes off what it put on, and the codec takes
+ * off what it put in. The case that matters most is the last one — the same
+ * line of dialogue, stored two ways, coming out identical.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { AviContainer } from "../services/media/container/AviContainer.js";
+import { MatroskaContainer } from "../services/media/container/MatroskaContainer.js";
+import { Mp4Container } from "../services/media/container/Mp4Container.js";
+import { SubtitleFileContainer } from "../services/media/container/SubtitleFileContainer.js";
+import { MarkupKind, TextSubtitleTrack } from "../services/media/tracks/TextSubtitleTrack.js";
+
+/** The line from the field report, as Matroska stores it. */
+const FIELD_BLOCK =
+  "21,0,Default,,0000,0000,0000,,I am the powerful Demon King of the Sixth Heaven. Good... Evil...";
+
+function block(text) {
+  return Buffer.from(text, "utf8");
+}
+
+test("a Matroska ASS block gives up its text and nothing else", () => {
+  // Nine fields exactly, and no comma in the dialogue: the shape that defeated
+  // the old field count and put the whole row on the viewer's screen.
+  assert.equal(
+    MatroskaContainer.cueTextOf(block(FIELD_BLOCK), "S_TEXT/ASS"),
+    "I am the powerful Demon King of the Sixth Heaven. Good... Evil..."
+  );
+});
+
+test("commas in the dialogue are dialogue, not fields", () => {
+  assert.equal(
+    MatroskaContainer.cueTextOf(block("7,0,Main,Nobunaga,0000,0000,0000,,Yes, of course, my lord"), "S_TEXT/ASS"),
+    "Yes, of course, my lord"
+  );
+});
+
+test("an SSA block is framed the same way as an ASS one", () => {
+  // SSA writes `Marked` where ASS writes `Layer`; the count is the same and so
+  // is the answer.
+  assert.equal(
+    MatroskaContainer.cueTextOf(block("3,,Default,,0000,0000,0000,,Toujours rien."), "S_TEXT/SSA"),
+    "Toujours rien."
+  );
+});
+
+test("a row too short to hold a text field yields nothing to show", () => {
+  assert.equal(MatroskaContainer.cueTextOf(block("21,0,Default,,0000"), "S_TEXT/ASS"), "");
+  assert.equal(MatroskaContainer.cueTextOf(block("21,0,Default,,0000,0000,0000,,"), "S_TEXT/ASS"), "");
+});
+
+test("a plain-text Matroska block is not touched at all", () => {
+  // `S_TEXT/UTF8` has no framing: the block IS the text, commas included.
+  const line = "Yes, of course, my lord";
+  assert.equal(MatroskaContainer.cueTextOf(block(line), "S_TEXT/UTF8"), line);
+  assert.equal(MatroskaContainer.cueTextOf(block(line), "S_TEXT/WEBVTT"), line);
+});
+
+test("an MP4 sample is unframed by the MP4, length prefix and all", () => {
+  const text = Buffer.from("Yes, of course, my lord", "utf8");
+  const sample = Buffer.concat([Buffer.from([0x00, text.length]), text]);
+  assert.equal(Mp4Container.cueTextOf(sample, "tx3g"), "Yes, of course, my lord");
+});
+
+test("a container with no framing of its own refuses to guess", () => {
+  // AVI declares no subtitle tracks, so no cue can reach it. If one ever did,
+  // the answer must be an error and not a guess at somebody else's framing.
+  assert.throws(() => AviContainer.cueTextOf(block("x"), "S_TEXT/ASS"), /cueTextOf not implemented/);
+});
+
+test("ASS markup is taken off wherever the text came from", () => {
+  assert.equal(TextSubtitleTrack.plainTextOf("{\\pos(640,620)}Hello{\\i1} there{\\i0}", "S_TEXT/ASS"), "Hello there");
+  assert.equal(TextSubtitleTrack.plainTextOf("First\\NSecond\\nThird", "S_TEXT/ASS"), "First\nSecond\nThird");
+  assert.equal(TextSubtitleTrack.plainTextOf("Wide\\hspace", "S_TEXT/ASS"), "Wide space");
+  // The same text under a codec that has no such markup keeps its characters.
+  assert.equal(TextSubtitleTrack.plainTextOf("{\\pos(1,2)}Hello", "S_TEXT/UTF8"), "{\\pos(1,2)}Hello");
+});
+
+test("a codec is known by any of its names", () => {
+  assert.equal(TextSubtitleTrack.markupKindOf("S_TEXT/ASS"), MarkupKind.ASS);
+  assert.equal(TextSubtitleTrack.markupKindOf(".ASS"), MarkupKind.ASS);
+  assert.equal(TextSubtitleTrack.markupKindOf("S_TEXT/UTF8"), MarkupKind.NONE);
+  assert.equal(TextSubtitleTrack.markupKindOf("wvtt"), MarkupKind.NONE);
+  // Unknown: shown as it is, rather than refused.
+  assert.equal(TextSubtitleTrack.markupKindOf("S_TEXT/SOMETHING"), MarkupKind.NONE);
+});
+
+test("a text track answers for its own markup", () => {
+  const track = new TextSubtitleTrack({ trackNumber: 3, declaredIndex: 0, codecId: "S_TEXT/ASS" });
+  assert.equal(track.markupKind, MarkupKind.ASS);
+  assert.equal(track.plainText("{\\be1}Готовьте лучников"), "Готовьте лучников");
+});
+
+test("a file states its own column order and is obeyed", () => {
+  // This `Format:` has no `Name` column, so the text is the ninth field and not
+  // the tenth. A reader that assumed a position would take the effect field as
+  // the line — which is the file-side form of the defect this suite is about.
+  const file = [
+    "[Script Info]",
+    "ScriptType: v4.00+",
+    "[Events]",
+    "Format: Layer, Start, End, Style, MarginL, MarginR, MarginV, Effect, Text",
+    "Dialogue: 0,0:00:01.00,0:00:03.50,Default,0000,0000,0000,,Ты видишь их?",
+    ""
+  ].join("\n");
+
+  const cues = new SubtitleFileContainer({ extension: ".ass" }).readCues(file);
+  assert.deepEqual(cues, [{ startSeconds: 1, endSeconds: 3.5, text: "Ты видишь их?" }]);
+});
+
+test("a dialogue row before any Format line is not guessed at", () => {
+  const file = ["[Events]", "Dialogue: 0,0:00:01.00,0:00:02.00,Default,,0,0,0,,Ignored", ""].join("\n");
+  assert.deepEqual(new SubtitleFileContainer({ extension: ".ass" }).readCues(file), []);
+});
+
+test("SubRip cues keep their words and lose their numbering", () => {
+  const file = [
+    "1",
+    "00:00:01,000 --> 00:00:03,500",
+    "Ты видишь их?",
+    "",
+    "2",
+    "00:01:02,250 --> 00:01:04,000",
+    "<i>Да.</i>",
+    "Но не столько вижу.",
+    ""
+  ].join("\n");
+
+  const cues = new SubtitleFileContainer({ extension: ".srt" }).readCues(file);
+  assert.deepEqual(cues, [
+    { startSeconds: 1, endSeconds: 3.5, text: "Ты видишь их?" },
+    { startSeconds: 62.25, endSeconds: 64, text: "<i>Да.</i>\nНо не столько вижу." }
+  ]);
+});
+
+test("a SubRip file with no blank line between cues does not swallow the ordinal", () => {
+  const file = [
+    "1",
+    "00:00:01,000 --> 00:00:02,000",
+    "First",
+    "2",
+    "00:00:03,000 --> 00:00:04,000",
+    "Second"
+  ].join("\n");
+
+  const cues = new SubtitleFileContainer({ extension: ".srt" }).readCues(file);
+  assert.deepEqual(cues.map((cue) => cue.text), ["First", "Second"]);
+});
+
+test("a WebVTT file is passed through, not taken apart", () => {
+  const file = "WEBVTT\n\nSTYLE\n::cue { color: yellow }\n\nintro\n00:00:01.000 --> 00:00:02.000\nHello\n";
+  assert.equal(SubtitleFileContainer.toVtt(file, ".vtt"), file);
+  assert.equal(new SubtitleFileContainer({ extension: ".vtt" }).readCues(file), null);
+});
+
+test("a format nothing here reads is refused rather than mangled", () => {
+  assert.equal(SubtitleFileContainer.toVtt("whatever", ".sup"), null);
+  assert.equal(SubtitleFileContainer.toVtt("whatever", ".ttml"), null);
+});
+
+test("one line of dialogue, two framings, one result", () => {
+  // The whole point of the split. The same ASS line stored in a Matroska block
+  // and in a file must reach the viewer identically, and neither path may know
+  // anything about the other.
+  const spoken = "Yes, of course, my lord";
+  const markup = `{\\pos(640,620)}${spoken}`;
+
+  const fromBlock = TextSubtitleTrack.finalizeCues(
+    [{
+      startSeconds: 1,
+      endSeconds: 3,
+      text: MatroskaContainer.cueTextOf(block(`21,0,Default,,0000,0000,0000,,${markup}`), "S_TEXT/ASS")
+    }],
+    "S_TEXT/ASS"
+  );
+
+  const fromFile = new SubtitleFileContainer({ extension: ".ass" }).readCues([
+    "[Events]",
+    "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
+    `Dialogue: 0,0:00:01.00,0:00:03.00,Default,,0000,0000,0000,,${markup}`,
+    ""
+  ].join("\n"));
+
+  assert.equal(fromBlock[0].text, spoken);
+  assert.equal(TextSubtitleTrack.finalizeCues(fromFile, ".ass")[0].text, spoken);
+  assert.equal(TextSubtitleTrack.cuesToVtt(fromBlock, "S_TEXT/ASS"), TextSubtitleTrack.cuesToVtt(fromFile, ".ass"));
+});

package/test/subtitle-cue-source.test.js

@@ -1,102 +1,102 @@
-/**
- * @file WHAT answers a pull for subtitle cues — the walk, and nothing else.
- *
- * Field 2026-09-03, on `[HorribleSubs] Drifters - 04 [1080p].mkv`. The file had
- * been downloaded in an earlier sitting, so the torrent worker's cluster walk
- * found cues 1.5 s after the file was opened and pushed four batches — cursor 1
- * to 31, covering everything up to 81.7 s — before the browser had subscribed.
- * The browser's catch-up pull, which exists for exactly that case, answered a
- * seven-byte `WEBVTT` with `x-subtitle-covered-clusters: 0` against 283
- * indexed. So the viewer watched the first 82 s with no subtitles and the rest
- * of the episode with them.
- *
- * The pull was answered by something that could not read pieces. Whatever a
- * pull is handed, the walk decides what it may read from it, so every range
- * read as "not downloaded", nothing was walked, and an empty document came
- * back. An empty document is also the right answer for a file that holds no
- * cues yet, which is why nothing reported a failure.
- *
- * The thread stopped being the distinction on 2026-09-15 — the walk runs beside
- * the sessions now, handed which byte ranges of a file are downloaded whole —
- * but the property it was standing for did not: a pull is answered by the SAME
- * walk that pushes, its own figures travel back, and anything that cannot read
- * says so rather than answering emptily.
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import { SubtitleOrchestrator } from "../services/media/SubtitleOrchestrator.js";
-import { cuesHeldFor } from "../services/media/SubtitleCues.js";
-import { heldFileOver } from "./helpers/held-file.js";
-
-/** A torrent that cannot say which of itself is downloaded. */
-function mainThreadTorrent() {
-  return {
-    infoHash: "0".repeat(40),
-    name: "[HorribleSubs] Drifters - 04 [1080p].mkv",
-    sourceKey: "a".repeat(40),
-    files: [{ name: "[HorribleSubs] Drifters - 04 [1080p].mkv", length: 567_535_843, createReadStream: () => { throw new Error("not reached"); } }]
-  };
-}
-
-test("a pull is answered by the walk, and the walk's own figures travel back", async () => {
-  const asked = [];
-  const cues = {
-    async held(torrent, fileIndex, sourceKey, trackNumber) {
-      asked.push({ sourceKey, fileIndex, trackNumber });
-      return {
-        cues: [{ startSeconds: 5.4, endSeconds: 9.1, text: "So what if you brought them over?", seq: 1 }],
-        coveredClusters: 283,
-        indexedClusters: 283,
-        track: { codecId: "S_TEXT/ASS", codecPrivate: "", language: "" }
-      };
-    }
-  };
-
-  const orchestrator = new SubtitleOrchestrator({ forget() {} }, cues);
-  const held = await orchestrator.getCues(mainThreadTorrent(), 33, "a".repeat(40), 3);
-
-  assert.deepEqual(asked, [{ sourceKey: "a".repeat(40), fileIndex: 33, trackNumber: 3 }]);
-  assert.equal(held.cues.length, 1);
-  assert.equal(held.coveredClusters, 283, "the walk's own figure travels back, so the header cannot claim 0 of 283");
-  // The worker answers with the track's fields flat — only plain objects cross
-  // the boundary — and the caller reads them through `held.track`.
-  assert.equal(held.track.codecId, "S_TEXT/ASS");
-});
-
-test("the cursor of a pulled cue is the found-order the worker assigned", async () => {
-  // The browser mixes cursors from pulls and pushes. A second walk would start
-  // a second `seq` counter and the two would not be comparable — which is why
-  // both ends go through the one walk, with one per-file state.
-  const cues = {
-    async held() {
-      return {
-        cues: [
-          { startSeconds: 5.4, endSeconds: 9.1, text: "one", seq: 1 },
-          { startSeconds: 81.7, endSeconds: 84.0, text: "two", seq: 31 }
-        ],
-        coveredClusters: 12,
-        indexedClusters: 283,
-        track: { codecId: "S_TEXT/ASS", codecPrivate: "", language: "" }
-      };
-    }
-  };
-  const orchestrator = new SubtitleOrchestrator({ forget() {} }, cues);
-  const held = await orchestrator.getCues(mainThreadTorrent(), 33, "a".repeat(40), 3);
-  assert.deepEqual(held.cues.map((cue) => cue.seq), [1, 31]);
-});
-
-test("an orchestrator with no walk is refused, not answered emptily", async () => {
-  const orchestrator = new SubtitleOrchestrator({ forget() {} });
-  const held = await orchestrator.getCues(mainThreadTorrent(), 33, "a".repeat(40), 3);
-  assert.deepEqual(held, { cues: [], coveredClusters: 0, indexedClusters: 0, track: null });
-});
-
-test("the walk refuses a torrent that cannot say which pieces it holds", async () => {
-  // Called directly. Without this guard the answer is an empty list
-  // indistinguishable from a file with no cues, which is what hid the defect
-  // for a whole session.
-  const held = await cuesHeldFor(heldFileOver(mainThreadTorrent(), 33, "b".repeat(40)), 3);
-  assert.deepEqual(held, { cues: [], coveredClusters: 0, indexedClusters: 0, track: null });
-});
+/**
+ * @file WHAT answers a pull for subtitle cues — the walk, and nothing else.
+ *
+ * Field 2026-09-03, on `[HorribleSubs] Drifters - 04 [1080p].mkv`. The file had
+ * been downloaded in an earlier sitting, so the torrent worker's cluster walk
+ * found cues 1.5 s after the file was opened and pushed four batches — cursor 1
+ * to 31, covering everything up to 81.7 s — before the browser had subscribed.
+ * The browser's catch-up pull, which exists for exactly that case, answered a
+ * seven-byte `WEBVTT` with `x-subtitle-covered-clusters: 0` against 283
+ * indexed. So the viewer watched the first 82 s with no subtitles and the rest
+ * of the episode with them.
+ *
+ * The pull was answered by something that could not read pieces. Whatever a
+ * pull is handed, the walk decides what it may read from it, so every range
+ * read as "not downloaded", nothing was walked, and an empty document came
+ * back. An empty document is also the right answer for a file that holds no
+ * cues yet, which is why nothing reported a failure.
+ *
+ * The thread stopped being the distinction on 2026-09-15 — the walk runs beside
+ * the sessions now, handed which byte ranges of a file are downloaded whole —
+ * but the property it was standing for did not: a pull is answered by the SAME
+ * walk that pushes, its own figures travel back, and anything that cannot read
+ * says so rather than answering emptily.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { SubtitleOrchestrator } from "../services/media/SubtitleOrchestrator.js";
+import { cuesHeldFor } from "../services/media/SubtitleCues.js";
+import { heldFileOver } from "./helpers/held-file.js";
+
+/** A torrent that cannot say which of itself is downloaded. */
+function mainThreadTorrent() {
+  return {
+    infoHash: "0".repeat(40),
+    name: "[HorribleSubs] Drifters - 04 [1080p].mkv",
+    sourceKey: "a".repeat(40),
+    files: [{ name: "[HorribleSubs] Drifters - 04 [1080p].mkv", length: 567_535_843, createReadStream: () => { throw new Error("not reached"); } }]
+  };
+}
+
+test("a pull is answered by the walk, and the walk's own figures travel back", async () => {
+  const asked = [];
+  const cues = {
+    async held(torrent, fileIndex, sourceKey, trackNumber) {
+      asked.push({ sourceKey, fileIndex, trackNumber });
+      return {
+        cues: [{ startSeconds: 5.4, endSeconds: 9.1, text: "So what if you brought them over?", seq: 1 }],
+        coveredClusters: 283,
+        indexedClusters: 283,
+        track: { codecId: "S_TEXT/ASS", codecPrivate: "", language: "" }
+      };
+    }
+  };
+
+  const orchestrator = new SubtitleOrchestrator({ forget() {} }, cues);
+  const held = await orchestrator.getCues(mainThreadTorrent(), 33, "a".repeat(40), 3);
+
+  assert.deepEqual(asked, [{ sourceKey: "a".repeat(40), fileIndex: 33, trackNumber: 3 }]);
+  assert.equal(held.cues.length, 1);
+  assert.equal(held.coveredClusters, 283, "the walk's own figure travels back, so the header cannot claim 0 of 283");
+  // The worker answers with the track's fields flat — only plain objects cross
+  // the boundary — and the caller reads them through `held.track`.
+  assert.equal(held.track.codecId, "S_TEXT/ASS");
+});
+
+test("the cursor of a pulled cue is the found-order the worker assigned", async () => {
+  // The browser mixes cursors from pulls and pushes. A second walk would start
+  // a second `seq` counter and the two would not be comparable — which is why
+  // both ends go through the one walk, with one per-file state.
+  const cues = {
+    async held() {
+      return {
+        cues: [
+          { startSeconds: 5.4, endSeconds: 9.1, text: "one", seq: 1 },
+          { startSeconds: 81.7, endSeconds: 84.0, text: "two", seq: 31 }
+        ],
+        coveredClusters: 12,
+        indexedClusters: 283,
+        track: { codecId: "S_TEXT/ASS", codecPrivate: "", language: "" }
+      };
+    }
+  };
+  const orchestrator = new SubtitleOrchestrator({ forget() {} }, cues);
+  const held = await orchestrator.getCues(mainThreadTorrent(), 33, "a".repeat(40), 3);
+  assert.deepEqual(held.cues.map((cue) => cue.seq), [1, 31]);
+});
+
+test("an orchestrator with no walk is refused, not answered emptily", async () => {
+  const orchestrator = new SubtitleOrchestrator({ forget() {} });
+  const held = await orchestrator.getCues(mainThreadTorrent(), 33, "a".repeat(40), 3);
+  assert.deepEqual(held, { cues: [], coveredClusters: 0, indexedClusters: 0, track: null });
+});
+
+test("the walk refuses a torrent that cannot say which pieces it holds", async () => {
+  // Called directly. Without this guard the answer is an empty list
+  // indistinguishable from a file with no cues, which is what hid the defect
+  // for a whole session.
+  const held = await cuesHeldFor(heldFileOver(mainThreadTorrent(), 33, "b".repeat(40)), 3);
+  assert.deepEqual(held, { cues: [], coveredClusters: 0, indexedClusters: 0, track: null });
+});