@torrent-tv/proxy 2.83.3 → 2.83.5

package/test/read-survives-withdrawal.test.js

@@ -0,0 +1,164 @@
+/**
+ * @file A read whose piece is withdrawn under it waits, rather than failing.
+ *
+ * The store drops a piece once every reader is past it, and the claim is
+ * withdrawn with it, so the piece is fetched again. A read that meets the gap in
+ * between must therefore WAIT — until 2026-09-12 it threw, ffmpeg read the empty
+ * body as the end of the file, the encoder died, and the plan restarted it into
+ * the same emptiness: 2432 starts in 23 minutes and a viewer looking at a still
+ * picture for 92 minutes.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { readFragments } from "../services/torrent-worker/piece-reader.js";
+import { SharedPieceStore } from "../services/piece-store/shared-piece-store.js";
+
+const PIECE = 1024;
+const TOTAL = 4 * PIECE;
+
+/**
+ * A torrent of four pieces over a real store, whose `reside` can be made to
+ * answer "gone" for a chosen piece a chosen number of times — which is what the
+ * store does between dropping a piece and the swarm bringing it back.
+ *
+ * @param {{ emptyFor: number, times: number }} gap
+ */
+async function torrentWithAGap({ emptyFor, times }) {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "withdrawal-read-"));
+  const store = new SharedPieceStore(PIECE, {
+    length: TOTAL,
+    memoryBytes: 64 * PIECE,
+    path: directory,
+    name: "test",
+    files: [{ offset: 0, length: TOTAL, name: "file.bin" }]
+  });
+  for (let index = 0; index < 4; index += 1) {
+    const piece = Buffer.alloc(PIECE);
+    for (let at = 0; at < PIECE; at += 1) {
+      piece[at] = (index * PIECE + at) % 251;
+    }
+    await new Promise((resolve, reject) => {
+      store.put(index, piece, (error) => (error ? reject(error) : resolve()));
+    });
+  }
+
+  const held = new Set([0, 1, 2, 3]);
+  let left = times;
+  /** How many times the piece was asked of the store at all. */
+  let asked = 0;
+  // The gap is injected at the one method that answers "can you produce this
+  // piece" — subclassed rather than wrapped, because `findSharedStore` walks
+  // the chain looking for the real class and would find the real one behind a
+  // facade.
+  store.reside = async function resideWithAGap(index) {
+    if (index !== emptyFor) {
+      return SharedPieceStore.prototype.reside.call(this, index);
+    }
+    asked += 1;
+    if (left > 0) {
+      left -= 1;
+      // THE CLAIM GOES WITH THE BYTES. That is what makes the wait a wait for a
+      // download and not a wait for nothing, and it is what the withdrawal now
+      // does in production.
+      held.delete(index);
+      // Back a moment later, as the swarm brings it: the reader's own wait ends
+      // on the torrent's `verified` event.
+      setImmediate(() => {
+        held.add(index);
+        torrent.emit("verified", index);
+      });
+      return null;
+    }
+    return SharedPieceStore.prototype.reside.call(this, index);
+  };
+
+  const torrent = Object.assign(new EventEmitter(), {
+    pieceLength: PIECE,
+    store,
+    bitfield: { get: (index) => held.has(index) },
+    files: [{ offset: 0, length: TOTAL, name: "file.bin" }],
+    select() {},
+    critical() {}
+  });
+
+  return {
+    torrent,
+    clean: async () => {
+      store.destroy(() => undefined);
+      await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 20 });
+    },
+    asksFor: () => asked
+  };
+}
+
+/** Read a range as the worker does. */
+async function readRange(torrent, start, end) {
+  const collected = [];
+  for await (const fragment of readFragments({
+    torrent,
+    fileIndex: 0,
+    start,
+    end,
+    cancellation: { isCancelled: () => false }
+  })) {
+    const source = fragment.buffer
+      ? Buffer.from(fragment.buffer, fragment.offset, fragment.length)
+      : Buffer.alloc(0);
+    collected.push(Buffer.from(source));
+    fragment.release();
+  }
+  return Buffer.concat(collected);
+}
+
+function expectedBytes(absoluteStart, length) {
+  const expected = Buffer.alloc(length);
+  for (let at = 0; at < length; at += 1) {
+    expected[at] = (absoluteStart + at) % 251;
+  }
+  return expected;
+}
+
+test("a piece withdrawn once is asked for again and the read completes", async () => {
+  // Piece 0 is the case the field met: an encoder restart re-opens its input at
+  // byte 0, and byte 0 is behind every read head by then.
+  const { torrent, clean, asksFor } = await torrentWithAGap({ emptyFor: 0, times: 1 });
+  try {
+    const bytes = await readRange(torrent, 0, 2 * PIECE - 1);
+    assert.deepEqual(bytes, expectedBytes(0, 2 * PIECE), "the read returns the film, not an empty body");
+    assert.equal(asksFor(), 2, "the piece is asked for a second time, not given up on");
+  } finally {
+    await clean();
+  }
+});
+
+test("a piece that does not come back ends the read with a named error", async () => {
+  const { torrent, clean } = await torrentWithAGap({ emptyFor: 0, times: 5 });
+  try {
+    await assert.rejects(
+      () => readRange(torrent, 0, PIECE - 1),
+      // NOT "verified but absent": the claim has been withdrawn, so the honest
+      // statement is that the bytes did not come back.
+      /piece 0 was withdrawn from the store and did not come back/i,
+      "a second emptiness is a failure the caller must hear about"
+    );
+  } finally {
+    await clean();
+  }
+});
+
+test("every piece of a long read gets its own second chance", async () => {
+  // The allowance is per piece: a read of many pieces may legitimately meet the
+  // gap more than once, and one exhausted allowance must not condemn the rest.
+  const { torrent, clean } = await torrentWithAGap({ emptyFor: 2, times: 1 });
+  try {
+    const bytes = await readRange(torrent, 0, 4 * PIECE - 1);
+    assert.deepEqual(bytes, expectedBytes(0, 4 * PIECE));
+  } finally {
+    await clean();
+  }
+});

package/test/source-files-route.test.js

@@ -0,0 +1,103 @@
+/**
+ * @file WHAT THE BROWSER IS TOLD IS IN A TORRENT.
+ *
+ * This is the one place the product answers it. The browser used to answer it
+ * as well — a list of video extensions in its parser and a second, shorter pair
+ * inside its picker — and the three had already diverged: measured 2026-09-12,
+ * `.dat` was offered there as video and not counted here, which also decides
+ * whether a sidecar whose name matches nothing can belong to the only video
+ * present.
+ *
+ * So the shape of this answer is a contract with the page, and the page shows
+ * what it is given without looking at a name.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { handleApiSourceFilesGet } from "../routes/api/sources/files/get.js";
+
+/**
+ * A request, a reply and the torrent behind them.
+ *
+ * @param {Array<{ path: string, length: number }>} files
+ * @returns {{ req: object, reply: object, sent: { body: object | null, code: number }, deps: object }}
+ */
+function harness(files) {
+  const sent = { body: null, code: 200 };
+  const reply = {
+    code(value) {
+      sent.code = value;
+      return reply;
+    },
+    send(body) {
+      sent.body = body;
+      return reply;
+    }
+  };
+  const deps = {
+    sourceRegistry: { get: () => ({ sourceType: "magnet", source: "magnet:?xt=urn:btih:abc" }) },
+    torrentPool: {
+      async getTorrent() {
+        return { name: "Drifters", infoHash: "abc", files };
+      }
+    }
+  };
+  return { req: { params: { sourceKey: "key" }, query: {} }, reply, sent, deps };
+}
+
+test("the files come back in reading order, each saying what it is", () => {
+  const { req, reply, sent, deps } = harness([
+    { path: "Drifters/ep 10.mkv", length: 9 },
+    { path: "Drifters/ep 2.mkv", length: 9 },
+    { path: "Drifters/Rus Sound/ep 2.mka", length: 2 },
+    { path: "Drifters/notes.nfo", length: 1 }
+  ]);
+
+  return handleApiSourceFilesGet(req, reply, deps).then(() => {
+    assert.equal(sent.code, 200);
+    assert.deepEqual(
+      sent.body.files.map((file) => [file.relativePath, file.kind]),
+      [
+        // Runs of digits compare as numbers, so 2 comes before 10; the torrent's
+        // own order is whatever the tool that made it chose.
+        ["ep 2.mkv", "video"],
+        ["ep 10.mkv", "video"],
+        ["notes.nfo", "other"],
+        ["Rus Sound/ep 2.mka", "audio"]
+      ]
+    );
+    // Relative to the torrent root: WebTorrent prefixes its own name to every
+    // path, and stripping it here means one rule in the product rather than two
+    // that can disagree.
+    assert.ok(sent.body.files.every((file) => !file.relativePath.startsWith("Drifters/")));
+  });
+});
+
+test("each picture is named with what belongs to it, by index", () => {
+  const { req, reply, sent, deps } = harness([
+    { path: "Drifters/ep 1.mkv", length: 9 },
+    { path: "Drifters/Rus Sound/ep 1.mka", length: 2 },
+    { path: "Drifters/Sub/ep 1.ass", length: 1 },
+    { path: "Drifters/ep 2.mkv", length: 9 }
+  ]);
+
+  return handleApiSourceFilesGet(req, reply, deps).then(() => {
+    assert.deepEqual(sent.body.items, [
+      { fileIndex: 0, audio: [1], subtitles: [2], images: [] },
+      { fileIndex: 3, audio: [], subtitles: [], images: [] }
+    ]);
+    // The files themselves are in the list above; saying them twice is how two
+    // copies of one fact start.
+    assert.ok(sent.body.items.every((item) => item.audio.every((one) => Number.isInteger(one))));
+  });
+});
+
+test("a torrent whose metadata has not arrived says so and lists nothing", () => {
+  const { req, reply, sent, deps } = harness([]);
+
+  return handleApiSourceFilesGet(req, reply, deps).then(() => {
+    assert.deepEqual(sent.body.files, []);
+    assert.deepEqual(sent.body.items, []);
+    assert.equal(sent.body.name, "Drifters");
+  });
+});

package/test/stream-route.test.js

@@ -19,11 +19,11 @@ import { handleStreamGet } from "../routes/stream/get.js";
  * Minimal stand-ins for the parts of Fastify and the pool this route touches.
  *
  * @param {{ method: string, range?: string }} request
- * @returns {{ req: object, reply: object, sent: object, opened: string[], claims: number }}
+ * @returns {{ req: object, reply: object, sent: object, opened: string[], state: object }}
  */
 function harness({ method, range }) {
   const opened = [];
-  const state = { claims: 0, prioritized: [] };
+  const state = { prioritized: [] };
 
   const sent = { code: 200, headers: {}, body: undefined, called: false };
   const reply = {
@@ -71,10 +71,6 @@ function harness({ method, range }) {
     async getTorrent() {
       return { files: [file], sourceKey: "key" };
     },
-    acquireFile() {
-      state.claims += 1;
-      return () => undefined;
-    },
     prioritizeByteRange(_torrent, fileIndex, byteStart, _windowBytes, options) {
       state.prioritized.push({ byteStart, wholeFileRead: options?.wholeFileRead === true });
     }
@@ -96,7 +92,7 @@ test("HEAD reports the size without opening a read", async () => {
   await handleStreamGet(req, reply, deps);
 
   assert.deepEqual(opened, [], "HEAD started a read of the file");
-  assert.equal(state.claims, 0, "HEAD claimed the file it never read");
+  assert.deepEqual(state.prioritized, [], "HEAD asked the swarm for a read it never made");
   // The real size, not the zero Fastify substitutes for an empty payload — the
   // keyframe index reads this header and treats 0 as "no index".
   assert.equal(sent.headers["content-length"], "5869669065");
@@ -182,5 +178,5 @@ test("a file this proxy does not have whole still goes to the torrent", async ()
   const { req, reply, state, deps } = harness({ method: "GET", range: "bytes=0-99" });
   deps.torrentPool.wholeFiles = new Map([["other/7", { path: "/nowhere", length: 1, name: "x" }]]);
   await handleStreamGet(req, reply, deps);
-  assert.equal(state.claims, 1, "the ordinary path was not taken");
+  assert.equal(state.prioritized.length, 1, "the ordinary path was not taken");
 });

package/test/swarm-follows-readers.test.js

@@ -11,17 +11,30 @@
  * The rule is not a limit on connections. While anybody is reading, every one is
  * worth keeping: the one that has delivered nothing yet may deliver next.
  *
- * AND IT IS ACTED ON AT THE DEPARTURE ITSELF. The first version asked every
- * five seconds whether anybody was reading, and a torrent added three seconds
- * earlier answered no — its edges still being read, its plan still being built.
- * It left the swarm with 741 connections let go, and nothing rejoined it:
- * rejoining waits for a reader, and the reader was waiting for the header the
- * swarm had been fetching. Playback did not start at all.
+ * AND IT IS ASKED OF WHAT HAS BEEN STATED, never of a count of readers. The
+ * first version asked every five seconds whether anybody was READING, and a
+ * torrent added three seconds earlier answered no — its edges still being read,
+ * its plan still being built. It left the swarm with 741 connections let go,
+ * and nothing rejoined it: rejoining waited for a reader, and the reader was
+ * waiting for the header the swarm had been fetching. Playback did not start at
+ * all.
+ *
+ * The question now is whether anything is WANTED of it, which the priority map,
+ * the ends of an open file and a stopped read all answer — and which is true
+ * from the moment a torrent is opened.
  */
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { leaveSwarm, rejoinSwarm } from "../services/torrent-pool.js";
+import {
+  isWanted,
+  leaveSwarm,
+  rejoinSwarm,
+  stateFileEdges,
+  swarmDecisionFor
+} from "../services/torrent-pool.js";
+import { demandFor, forgetTorrent } from "../services/download/registry.js";
+import { Urgency } from "../services/demand/index.js";
 
 /**
  * A torrent that records what was done to it. Only the surface the rule
@@ -81,12 +94,81 @@ test("the reader that comes back takes the swarm with it", () => {
   assert.equal(rejoinSwarm(torrent), false, "a torrent already in its swarm was resumed again");
 });
 
-test("a torrent nobody has read yet is never asked to leave", () => {
-  // The field failure of 2026-09-11 is closed by WHERE this is called from, not
-  // by anything inside it: leaving is a consequence of the last claim being
-  // released, and a torrent being opened has released nothing. There is no pass
-  // that can ask it.
+test("a torrent whose metadata has not arrived is wanted, whatever is stated", () => {
+  // THE FIELD FAILURE OF 2026-09-11, as a question rather than as a mechanism.
+  // A torrent being added has no list of files, so nothing can name a byte of
+  // it — and it is being fetched precisely because somebody asked for it.
   const torrent = torrentWith(103);
-  assert.equal(torrent.paused, false);
-  assert.equal(torrent._peers.size, 103);
+  torrent.files = [];
+  assert.equal(isWanted(torrent), true);
+});
+
+test("a torrent with files and nothing stated for them is wanted by nobody", () => {
+  const torrent = torrentWith(4);
+  try {
+    assert.equal(isWanted(torrent), false);
+  } finally {
+    forgetTorrent(torrent);
+  }
+});
+
+test("anything stated makes it wanted, and the last withdrawal ends that", () => {
+  const torrent = torrentWith(4);
+  try {
+    // The ends of a file being opened, which is the first thing said about a
+    // torrent anybody has picked and the reason it stays in its swarm through
+    // the seconds when nothing else can say anything about it.
+    stateFileEdges(torrent, 0, Urgency.TAIL);
+    assert.equal(isWanted(torrent), true);
+
+    const { register } = demandFor(torrent);
+    register.withdraw("file-edges:0:head");
+    assert.equal(isWanted(torrent), true, "one end of it is still wanted");
+    register.withdraw("file-edges:0:tail");
+    assert.equal(isWanted(torrent), false);
+  } finally {
+    forgetTorrent(torrent);
+  }
+});
+
+test("a torrent that has been destroyed is wanted by nobody", () => {
+  const torrent = torrentWith(1);
+  torrent.destroyed = true;
+  assert.equal(isWanted(torrent), false);
+});
+
+test("a torrent something is wanted of keeps its swarm and is off the clock", () => {
+  assert.deepEqual(
+    swarmDecisionFor({ wanted: true, everWanted: true }),
+    { swarm: "take", onTheClock: false }
+  );
+  assert.deepEqual(
+    swarmDecisionFor({ wanted: true, everWanted: false }),
+    { swarm: "take", onTheClock: false }
+  );
+});
+
+test("a swarm is let go on a DEPARTURE, never on a beginning", () => {
+  // The whole of the 2.83.1 failure in one line: a torrent that has never been
+  // wanted is one being opened — its metadata has just landed, the file list is
+  // on its way to the person choosing, and nothing has had a chance to state
+  // anything about it yet. Taking its swarm away there destroyed 741
+  // connections it needed a minute later.
+  assert.deepEqual(
+    swarmDecisionFor({ wanted: false, everWanted: false }),
+    { swarm: "leave alone", onTheClock: true }
+  );
+  assert.deepEqual(
+    swarmDecisionFor({ wanted: false, everWanted: true }),
+    { swarm: "let go", onTheClock: true }
+  );
+});
+
+test("whatever happens to the swarm, an unwanted torrent is on the idle clock", () => {
+  // Including the one nobody has ever wanted: a file list fetched and never
+  // played used to be held for the life of the process, because the only thing
+  // that started the clock was a reader letting go.
+  for (const everWanted of [true, false]) {
+    assert.equal(swarmDecisionFor({ wanted: false, everWanted }).onTheClock, true);
+  }
 });

package/test/torrent-contents.test.js

@@ -0,0 +1,235 @@
+/**
+ * @file What one torrent says is in it: its pictures, what belongs to each, and
+ * the order a person reads them in.
+ *
+ * The fixtures are real releases. `Drifters` ships twelve episodes in the root
+ * with a Russian soundtrack per episode under `Rus Sound/` and a subtitle file
+ * per episode under `Sub/[group]/`; the single-film shape ships one `.mkv` with
+ * a dub whose name has nothing in common with it. Both are the cases the
+ * pairing rules beside this were written against, and this file is about what
+ * is built ON them — the grouping, the order and the leftovers.
+ *
+ * Measured on the survey collection, 2026-09-12, and recorded here because it
+ * is what says the grouping is not an invention: 134 torrents, 44 of them with
+ * more than one picture, 1357 items and 421 files paired to one. Not a single
+ * file was paired to two pictures, and in all 1357 the grouping agreed with the
+ * per-picture call it replaces.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { TorrentContents, contentsOf } from "../services/torrent/Contents.js";
+
+/**
+ * The Drifters torrent, as WebTorrent reports it: every path prefixed with the
+ * torrent's own name, and the episodes in the order the tool that made it chose
+ * — which is not the order anybody reads them in.
+ *
+ * @param {number[]} episodes
+ * @returns {Array<{ path: string, name: string, length: number }>}
+ */
+function driftersFiles(episodes) {
+  const files = [];
+  const push = (relative, length) => {
+    const name = relative.slice(relative.lastIndexOf("/") + 1);
+    files.push({ path: `Drifters/${relative}`, name, length });
+  };
+  for (const episode of episodes) {
+    const stem = `[HorribleSubs] Drifters - ${String(episode).padStart(2, "0")} [1080p]`;
+    push(`Sub/[Stan WarHammer & Nesitach]/${stem}.ass`, 29_000);
+    push(`Rus Sound/${stem}.mka`, 30_000_000);
+    push(`${stem}.mkv`, 566_000_000);
+  }
+  return files;
+}
+
+test("every picture is an item, with its own sound and subtitles on it", () => {
+  const contents = new TorrentContents({ files: driftersFiles([1, 2]), name: "Drifters" });
+
+  assert.equal(contents.videoCount, 2);
+  assert.equal(contents.items.length, 2);
+  const [first, second] = contents.items;
+  assert.match(first.name, / - 01 /);
+  assert.match(second.name, / - 02 /);
+  assert.deepEqual(
+    first.audio.map((file) => file.name),
+    ["[HorribleSubs] Drifters - 01 [1080p].mka"]
+  );
+  assert.deepEqual(
+    first.subtitles.map((file) => file.name),
+    ["[HorribleSubs] Drifters - 01 [1080p].ass"]
+  );
+  // The sound of episode 1 must never appear on the picture of episode 2: the
+  // wrong pairing is silent everywhere downstream.
+  assert.deepEqual(
+    second.audio.map((file) => file.name),
+    ["[HorribleSubs] Drifters - 02 [1080p].mka"]
+  );
+});
+
+test("items come out in the order a person reads them, not the torrent's own", () => {
+  // A real release lists its episodes 08, 06, 07, 01 — the order of whatever
+  // tool made the torrent, routinely by size.
+  const contents = new TorrentContents({ files: driftersFiles([8, 6, 10, 2]), name: "Drifters" });
+
+  assert.deepEqual(
+    contents.items.map((item) => item.name.match(/ - (\d+) /)[1]),
+    ["02", "06", "08", "10"]
+  );
+});
+
+test("runs of digits are compared as numbers, so 2 comes before 10", () => {
+  const files = [
+    { path: "Show/ep10.mkv", name: "ep10.mkv", length: 9 },
+    { path: "Show/ep2.mkv", name: "ep2.mkv", length: 9 }
+  ];
+  const contents = new TorrentContents({ files, name: "Show" });
+
+  assert.deepEqual(
+    contents.items.map((item) => item.name),
+    ["ep2.mkv", "ep10.mkv"]
+  );
+});
+
+test("an item keeps the torrent's own index, whatever order it is read in", () => {
+  const contents = new TorrentContents({ files: driftersFiles([8, 2]), name: "Drifters" });
+
+  // Episode 2 is read first and is the fifth file of the torrent.
+  assert.equal(contents.items[0].fileIndex, 5);
+  assert.equal(contents.items[1].fileIndex, 2);
+});
+
+test("a file is answered for by the item it belongs to, as a picture or as a part", () => {
+  const contents = new TorrentContents({ files: driftersFiles([1]), name: "Drifters" });
+  const [item] = contents.items;
+
+  assert.equal(contents.itemOf(item.fileIndex), item);
+  assert.equal(contents.itemOf(item.audio[0].fileIndex), item);
+  assert.equal(contents.itemOf(item.subtitles[0].fileIndex), item);
+  assert.equal(contents.itemOf(404), null);
+});
+
+test("what belongs beside one picture is answered from what was decided once", () => {
+  const contents = new TorrentContents({ files: driftersFiles([1, 2]), name: "Drifters" });
+  const [first] = contents.items;
+
+  const beside = contents.sidecarsOf(first.fileIndex);
+  assert.deepEqual(beside.audio, first.audio);
+  assert.deepEqual(beside.subtitles, first.subtitles);
+  // Asked about a file that is not a picture, the answer is nothing rather than
+  // the item that file happens to sit in: the question is "what goes beside
+  // this picture", and a soundtrack is not one.
+  assert.deepEqual(contents.sidecarsOf(first.audio[0].fileIndex), {
+    audio: [],
+    subtitles: [],
+    images: []
+  });
+});
+
+test("a torrent with one picture takes the dub whose name has nothing in common", () => {
+  const files = [
+    { path: "Film/Film.2024.1080p.mkv", name: "Film.2024.1080p.mkv", length: 4_000_000_000 },
+    { path: "Film/Rus Sound/dub.mka", name: "dub.mka", length: 30_000_000 }
+  ];
+  const contents = new TorrentContents({ files, name: "Film" });
+
+  assert.equal(contents.items.length, 1);
+  assert.deepEqual(
+    contents.items[0].audio.map((file) => file.name),
+    ["dub.mka"]
+  );
+  assert.deepEqual(contents.leftovers, []);
+});
+
+test("what belongs to no picture is listed as such, and nothing is lost", () => {
+  // `.nfo` is the release's own note and belongs to nothing. A `.txt` would
+  // NOT do here: the pairing layer counts it among the subtitle formats, and a
+  // torrent with one picture takes every sidecar there is.
+  const files = [
+    { path: "Film/Film.mkv", name: "Film.mkv", length: 9 },
+    { path: "Film/release.nfo", name: "release.nfo", length: 1 },
+    { path: "Film/Screens/unrelated.jpg", name: "unrelated.jpg", length: 1 }
+  ];
+  const contents = new TorrentContents({ files, name: "Film" });
+
+  assert.deepEqual(
+    contents.leftovers.map((file) => file.relativePath),
+    ["release.nfo", "Screens/unrelated.jpg"]
+  );
+  const accounted =
+    contents.items.length +
+    contents.items.reduce(
+      (count, item) => count + item.audio.length + item.subtitles.length + item.images.length,
+      0
+    ) +
+    contents.leftovers.length;
+  assert.equal(accounted, files.length);
+});
+
+test("a torrent whose metadata has not arrived says it holds nothing", () => {
+  const contents = new TorrentContents({ files: [], name: "" });
+
+  assert.deepEqual(contents.items, []);
+  assert.deepEqual(contents.leftovers, []);
+  assert.equal(contents.videoCount, 0);
+  assert.equal(contents.itemOf(0), null);
+});
+
+test("the answer is worked out once per torrent, and again when its files arrive", () => {
+  const torrent = { name: "Drifters", files: [] };
+
+  const empty = contentsOf(torrent);
+  assert.equal(contentsOf(torrent), empty, "asking twice must not work it out twice");
+
+  // A magnet has no files until its metadata lands, which happens exactly once.
+  torrent.files = driftersFiles([1]);
+  const full = contentsOf(torrent);
+  assert.notEqual(full, empty);
+  assert.equal(full.items.length, 1);
+  assert.equal(contentsOf(torrent), full);
+});
+
+test("folders order before names, so seasons stay together", () => {
+  const files = [
+    { path: "Show/Season 2/ep 1.mkv", length: 9 },
+    { path: "Show/Season 10/ep 1.mkv", length: 9 },
+    { path: "Show/Season 1/ep 2.mkv", length: 9 },
+    { path: "Show/Season 1/ep 1.mkv", length: 9 }
+  ];
+  const contents = new TorrentContents({ files, name: "Show" });
+
+  assert.deepEqual(
+    contents.items.map((item) => item.relativePath),
+    ["Season 1/ep 1.mkv", "Season 1/ep 2.mkv", "Season 2/ep 1.mkv", "Season 10/ep 1.mkv"]
+  );
+});
+
+test("every file is described by what it is, in the order a person reads them", () => {
+  // What the browser is given. It used to answer this itself — a list of video
+  // extensions in its parser and a second, shorter pair inside its picker —
+  // against this one, and the three had already diverged.
+  const files = [
+    { path: "Film/notes.nfo", length: 1 },
+    { path: "Film/cover.jpg", length: 2 },
+    { path: "Film/film.mkv", length: 9 },
+    { path: "Film/Rus Sound/dub.mka", length: 3 },
+    { path: "Film/Sub/film.ass", length: 1 }
+  ];
+  const contents = new TorrentContents({ files, name: "Film" });
+
+  assert.deepEqual(
+    contents.files().map((file) => [file.relativePath, file.kind]),
+    [
+      ["cover.jpg", "image"],
+      ["film.mkv", "video"],
+      ["notes.nfo", "other"],
+      ["Rus Sound/dub.mka", "audio"],
+      ["Sub/film.ass", "subtitle"]
+    ]
+  );
+  assert.deepEqual(
+    contents.files().map((file) => file.fileIndex),
+    [1, 2, 0, 3, 4],
+    "the torrent's own numbers travel with them"
+  );
+});