@vestra-player/sdk 1.5.31 → 1.5.34

package/dist/plugin/testing.js

@@ -77,6 +77,7 @@ import { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, BUILTIN_COMMANDS, BUILTIN_SUBMENUS
 import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.js";
 import { OSD_LIMITS } from "./osd.js";
 import { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./services.js";
+import { SUBTITLE_LIMITS } from "./subtitles.js";
 import { BINDING_INPUTS } from "./bindings.js";
 import { THEME_PALETTES } from "../palettes.js";
 import { IMAGE_LIMITS, UI_VALUE_LIMITS, valueLimitProblem } from "./values.js";
@@ -104,6 +105,8 @@ export { OSD_LIMITS };
 export { SECRET_LIMITS };
 /** The player's limits on `plugin.storage.session`. */
 export { SESSION_STORAGE_LIMITS };
+/** The player's limits on loaded subtitle files, which the test host enforces as well. */
+export { SUBTITLE_LIMITS };
 /** The names bindings are made of. */
 export { BINDING_INPUTS };
 /** The colours of the player's palettes, by `Theme` token. */
@@ -307,6 +310,19 @@ const MAX_SIDEBAR_TABS = 8;
  *   await stop();
  * });
  * ```
+ *
+ * @remarks
+ * An in-memory player that speaks the real wire protocol, so the SDK's own
+ * logic runs as it does in the player; only the player side is simulated
+ * (no decoding, no Slint, no windows). Make one per test, preset it if the
+ * plugin reads something during activation, start the plugin with
+ * {@link startPlugin}, drive it, `settle()`, and assert on what it
+ * recorded.
+ *
+ * @capability None.
+ * @see [Test a plugin](../../docs/how-to/testing.md)
+ * @since 1.0.0
+ * @category Testing
  */
 export class TestHost {
     /**
@@ -416,6 +432,20 @@ export class TestHost {
      *
      * @param directory - The package directory (holding `locales/`).
      * @since 1.5.9
+     *
+     * @capability None.
+     *
+     * @example Load the translations after changing the language
+     * The test switches the host to German before starting the plugin and
+     * loads that catalog itself (`startPlugin` does the same). Texts are then
+     * shown in German.
+     * ```ts
+     * declare const host: TestHost;
+     * declare const directory: string;
+     * // ---cut---
+     * host.locale = "de";
+     * host.loadCatalog(directory); // locales/de.po (or de.json)
+     * ```
      */
     loadCatalog(directory) {
         this.#catalog = loadPackageCatalog(directory, this.locale);
@@ -441,6 +471,8 @@ export class TestHost {
      * ```
      *
      * @since 1.5.9
+     *
+     * @capability None.
      */
     translate(text, args) {
         if (typeof text !== "string")
@@ -520,6 +552,24 @@ export class TestHost {
      *
      * @param language - `"system"` or a locale.
      * @since 1.5.9
+     *
+     * @capability None.
+     *
+     * @example Simulate the user choosing French for the next start
+     * The plugin hears that the saved interface language changed. The host
+     * pushes `appearance.changed`, which a plugin with `events` sees in
+     * `appearance.language` once it has read it and subscribed; this run's
+     * language does not change.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * void plugin.appearance.language; // read once: the SDK then follows it
+     * plugin.appearance.onChange(() => {}); // subscribes to appearance events
+     * host.setLanguage("fr");
+     * await host.settle();
+     * assert.equal(plugin.appearance.language, "fr");
+     * ```
      */
     setLanguage(language) {
         this.language = language;
@@ -713,6 +763,9 @@ export class TestHost {
      * await host.settle();
      * assert.equal(plugin.timeline.marks.length, 2);
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     setTimelineLayer(pluginId, marks) {
         if (marks.length)
@@ -755,6 +808,9 @@ export class TestHost {
      *   join(plugin.dataDirectory, "cover.png"),
      * );
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     imagePath(value) {
         const image = value;
@@ -865,6 +921,10 @@ export class TestHost {
      *   modifiers: { alt: true },
      * });
      * ```
+     *
+     * @capability None.
+     * @throws Never: files nobody takes are ignored, as in the player.
+     * @since 1.0.0
      */
     drop(paths, options = {}) {
         const modifiers = {
@@ -899,6 +959,24 @@ export class TestHost {
     /**
      * Simulate another plugin switching the palette: updates
      * {@link TestHost.appearance} and pushes `appearance.changed`.
+     *
+     * @capability None.
+     *
+     * @example Simulate another plugin switching to the light palette
+     * The plugin hears the palette change. The host updates `appearance` and
+     * pushes `appearance.changed` to a plugin that listens with `events`.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * const themes: ThemeId[] = [];
+     * plugin.appearance.onChange((theme) => themes.push(theme)); // subscribes (`events`)
+     * host.setAppearance("vestra-light");
+     * await host.settle();
+     * assert.deepEqual(themes, ["vestra-light"]);
+     * ```
+     *
+     * @since 1.0.0
      */
     setAppearance(theme) {
         this.appearance = theme;
@@ -935,6 +1013,9 @@ export class TestHost {
      * await host.settle();
      * assert.equal(page.props["step"], 10);
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     settingsPage(id) {
         const page = this.settings.pages.get(id);
@@ -947,6 +1028,23 @@ export class TestHost {
     /**
      * Simulate the backdrop's `effective` changing (`false`: a video frame
      * appeared; `true`: there is none again); pushed to the plugin.
+     *
+     * @capability None.
+     *
+     * @example Make a video picture replace the backdrop
+     * The plugin's backdrop hears that a video frame now covers it. `false`
+     * means a picture appeared; the change is pushed like the player's
+     * `window.state`.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.setBackdropEffective(false);
+     * await host.settle();
+     * assert.equal(plugin.panels.backdrop.state?.effective, false);
+     * ```
+     *
+     * @since 1.0.0
      */
     setBackdropEffective(effective) {
         if (this.backdrop)
@@ -986,6 +1084,8 @@ export class TestHost {
      * ```
      *
      * @since 1.5.2
+     *
+     * @capability None.
      */
     mountOther(slot, plugin, options = {}) {
         if (this.#others.has(plugin))
@@ -1009,6 +1109,21 @@ export class TestHost {
      * when its tab was current, the next tab (else the previous one) is.
      *
      * @since 1.5.2
+     *
+     * @capability None.
+     *
+     * @example Let the playlist's tab go away
+     * The other plugin's sidebar tab disappears and the plugin's own tab
+     * becomes current. When the removed tab was current, the next tab (else
+     * the previous one) becomes current, as in the player.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.unmountOther("vestra.playlist");
+     * await host.settle();
+     * assert.equal(host.layout.sidebar?.panels?.length, 1);
+     * ```
      */
     unmountOther(plugin) {
         const other = this.#others.get(plugin);
@@ -1027,6 +1142,20 @@ export class TestHost {
      * becomes the current tab. Pushed as a `window.state` change.
      *
      * @since 1.5.2
+     *
+     * @capability None.
+     *
+     * @example Click another plugin's sidebar tab
+     * The user switches the sidebar to the playlist; the plugin's panel is in
+     * a background tab now. The change is pushed as `window.state`.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.selectTab("vestra.playlist");
+     * await host.settle();
+     * assert.notEqual(host.layout.sidebar?.owner, 1); // the plugin under test is owner 1
+     * ```
      */
     selectTab(plugin) {
         const slot = this.layout.sidebar;
@@ -1077,6 +1206,24 @@ export class TestHost {
      * Simulate another plugin taking the display layer first (the plugin's
      * `video.view()` then fails with `conflict`), or, with `null`, releasing
      * it (values reset to the defaults).
+     *
+     * @capability None.
+     *
+     * @example Let another plugin own the display layer
+     * The plugin's `video.view()` fails with `conflict` because another plugin
+     * took the display layer first. `null` releases it again.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.setVideoViewOwner("someone.zoom");
+     * const view = plugin.video.view();
+     * view.set({ zoom: 2 });
+     * await host.settle();
+     * assert.equal(view.status.state, "failed");
+     * ```
+     *
+     * @since 1.0.0
      */
     setVideoViewOwner(pluginId) {
         this.videoView.owner = pluginId;
@@ -1093,6 +1240,24 @@ export class TestHost {
      * Simulate another plugin owning the render options (the plugin's
      * `video.render()` then fails with `conflict`), or, with `null`, releasing
      * them (values reset to the defaults).
+     *
+     * @capability None.
+     *
+     * @example Let another plugin own the render options
+     * The plugin's render options report `conflict` while another plugin owns
+     * them; `null` releases them and resets the values to the defaults.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.setVideoRenderOwner("someone.hdr");
+     * const render = plugin.video.render();
+     * render.set({ toneMapping: "bt.2390" });
+     * await host.settle();
+     * assert.equal(render.status.state, "failed");
+     * ```
+     *
+     * @since 1.0.0
      */
     setVideoRenderOwner(pluginId) {
         this.videoRender.owner = pluginId;
@@ -1120,6 +1285,9 @@ export class TestHost {
      * await host.settle();
      * assert.equal(render.status.state, "failed");
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     failVideoRender(code, message) {
         if (code === "unsupported")
@@ -1213,6 +1381,21 @@ export class TestHost {
      * What `plugin.resolvers.fileTypes` reports: the extensions of this
      * plugin's file resolvers and of {@link TestHost.otherResolvers}, sorted,
      * each once.
+     *
+     * @capability None.
+     *
+     * @example Check the file types a resolver adds
+     * The test checks the list the plugin will read as
+     * `resolvers.fileTypes`: the extensions of its own file resolvers and of
+     * `otherResolvers`, sorted, each once.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * assert.deepEqual(host.fileTypes(), ["ch8"]);
+     * ```
+     *
+     * @since 1.5.8
      */
     fileTypes() {
         const types = new Set();
@@ -1245,6 +1428,9 @@ export class TestHost {
      * await host.settle();
      * assert.deepEqual(plugin.resolvers.fileTypes, ["ch8"]);
      * ```
+     *
+     * @capability None.
+     * @since 1.5.8
      */
     updateFileTypes() {
         const types = this.fileTypes();
@@ -1338,7 +1524,11 @@ export class TestHost {
      * @since 1.5.25
      */
     sessionStorage = new Map();
-    /** What `plugin.app.system()` reports. */
+    /**
+     * What `plugin.app.system()` reports. Its `rendering` follows
+     * {@link TestHost.videoRender | videoRender.gpu} (`"gpu"` or
+     * `"software"`), so one switch covers the render options and the fact.
+     */
     systemInfo = {
         os: "macos",
         name: "macOS",
@@ -1393,6 +1583,11 @@ export class TestHost {
      * `"test.plugin"` by default).
      */
     manifestId = "test.plugin";
+    /**
+     * A fresh in-memory player: nothing open, no plugin, the player's core
+     * actions registered. Preset what the plugin reads during activation, then
+     * pass it to {@link startPlugin} as `host`.
+     */
     constructor() {
         this.subtitles = {
             presentation: {
@@ -1481,8 +1676,10 @@ export class TestHost {
     /**
      * One of the 14 core actions (`play-pause`, `stop`, `seek-forward`, ...)
      * that the test host registers like the player, as `host/<id>`. Throws for
-     * an unknown id. `run()` executes it with the player's checks and writes
-     * its on-screen text to {@link TestHost.osd}.
+     * an unknown id. `run()` executes it like its menu item: a disabled
+     * action rejects with `command`, as in the player (`plugin.host.run`
+     * rejects with `unavailable` instead); otherwise it runs with the
+     * player's checks and writes its on-screen text to {@link TestHost.osd}.
      *
      * @example Pause through the player's own action
      * The test pauses playback the way the Space key does and checks that the
@@ -1498,6 +1695,9 @@ export class TestHost {
      * assert.equal(host.source.paused, true);
      * assert.deepEqual(host.coreRuns, ["play-pause"]);
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     coreAction(id) {
         const command = this.coreCommands.get(`host/${id}`);
@@ -1703,6 +1903,10 @@ export class TestHost {
                 set state(_value) { },
                 revision: 1,
                 async run() {
+                    // Like the player's menu: a disabled or busy command does not run.
+                    const state = host.#coreState(id);
+                    if (state.busy || !state.enabled)
+                        throw new HostError("command", `host/${id} is ${state.busy ? "busy" : "disabled"}`);
                     await host.request("host.run", { action: id });
                     await host.settle();
                 },
@@ -1879,11 +2083,36 @@ export class TestHost {
      * assert.deepEqual(host.osd, ["Folder not found"]);
      * host.reset("system.openPath");
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     handle(method, handler) {
         this.#overrides.set(method, handler);
     }
-    /** Restore the default behaviour of a method replaced with {@link TestHost.handle}. */
+    /**
+     * Restore the default behaviour of a method replaced with {@link TestHost.handle}.
+     *
+     * @capability None.
+     *
+     * @example Restore the default answer after a simulated failure
+     * The first write fails, the second succeeds. `reset` removes the handler
+     * that `handle` installed, so the method is answered by the test host
+     * again.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.handle("clipboard.writeText", () => {
+     *   throw new HostError("failed", "denied");
+     * });
+     * await assert.rejects(plugin.clipboard.writeText("x"));
+     * host.reset("clipboard.writeText");
+     * await plugin.clipboard.writeText("x"); // the default handler again
+     * ```
+     *
+     * @since 1.0.0
+     */
     reset(method) {
         this.#overrides.delete(method);
     }
@@ -1896,6 +2125,22 @@ export class TestHost {
      *
      * @param event - The wire event name.
      * @param data - The event payload (wire-level shape).
+     *
+     * @capability None.
+     *
+     * @example Deliver a raw event the helpers do not cover
+     * The test pushes a `window.state` event after changing `layout` by hand.
+     * Like the player, the host delivers it only when the plugin subscribed;
+     * most tests use `setSource`, `setMainWindow` and the other helpers
+     * instead.
+     * ```ts
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.emit("window.state", {}); // no facts: the SDK reads window.state again
+     * await host.settle();
+     * ```
+     *
+     * @since 1.0.0
      */
     emit(event, data) {
         if ([
@@ -1935,6 +2180,9 @@ export class TestHost {
      * host.setSource({ phase: "ended", terminalReason: "natural" });
      * await host.settle();
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     setSource(patch) {
         this.source = {
@@ -1975,6 +2223,9 @@ export class TestHost {
      * assert.equal(plugin.window.state.fullscreen, true);
      * host.setMainWindow({ pictureInPicture: { supported: true, active: false } });
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     setMainWindow(patch) {
         const entering = patch.fullscreen !== undefined &&
@@ -1993,6 +2244,22 @@ export class TestHost {
      * The pointer reached the right edge in fullscreen (`true`) or left the
      * popped-out sidebar (`false`): the attached sidebar pops out or collapses
      * (reference §6.3). No effect outside fullscreen, when hidden or floating.
+     *
+     * @capability None.
+     *
+     * @example Pop the sidebar out in fullscreen
+     * The pointer reaches the right edge in fullscreen and the attached
+     * sidebar pops out over the video. Outside fullscreen, or with the
+     * sidebar hidden or floating, nothing happens.
+     * ```ts
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.setMainWindow({ fullscreen: true });
+     * host.popSidebar(true);
+     * await host.settle();
+     * ```
+     *
+     * @since 1.0.0
      */
     popSidebar(popped) {
         const sidebar = this.layout.sidebar;
@@ -2036,6 +2303,9 @@ export class TestHost {
      * await host.settle();
      * assert.equal(plugin.player.isCurrent(before), false);
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     openElsewhere(source, phase = "ready") {
         this.#intent({ kind: "open", source, startPaused: false });
@@ -2063,6 +2333,9 @@ export class TestHost {
      * const [producer] = host.producers.values();
      * host.failStream(producer!.id, "producer transport closed");
      * ```
+     *
+     * @capability None.
+     * @since 1.5.7
      */
     failStream(producerId, message) {
         const producer = this.producers.get(producerId);
@@ -2081,11 +2354,12 @@ export class TestHost {
      * the conflict rule orders them. A disabled command lets the key pass to
      * the next command bound to it (SDK 1.5.12, as player 0.4.3): the one it
      * shadowed, then the global scope. The first enabled one runs; `press`
-     * resolves after it ran (`"ran"`), or rejects when it is busy. When only
-     * disabled commands hold the key, the first one with a `reason` shows the
-     * reason on the OSD and eats the key (`"reason"`, see `host.osd`);
-     * without a reason the key goes on to the focused control (`"passed"`,
-     * nothing runs). Rejects when nothing is bound. Bindings use the
+     * resolves after it ran (`"ran"`). When only disabled commands hold the
+     * key, the first of them decides, as in the player: with a `reason` it
+     * shows the reason on the OSD and eats the key (`"reason"`, see
+     * `host.osd`); without one the key goes on to the focused control
+     * (`"passed"`, nothing runs). Unlike the player, which only logs a key
+     * that reaches a busy command, `press` then rejects, so a test notices. Rejects when nothing is bound. Bindings use the
      * reference syntax (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`), and user
      * overrides in `bindings.overlay` apply.
      *
@@ -2102,6 +2376,12 @@ export class TestHost {
      * await host.press("Ctrl+B"); // a global binding
      * await host.press("Delete", { panel: true }); // while the panel has focus
      * ```
+     *
+     * @capability None.
+     * @throws `command` (rejects) A `HostError`: the command that would run is
+     *   busy (the player only logs this).
+     * @throws `Error` (rejects) Nothing is bound to the key.
+     * @since 1.0.0
      */
     async press(binding, options = {}) {
         const claims = this.#claims();
@@ -2117,14 +2397,15 @@ export class TestHost {
             await command(enabled).run();
             return "ran";
         }
-        for (const id of ids) {
-            const reason = this.commands.has(id)
-                ? command(id).display.reason
-                : command(id).state.reason;
-            if (typeof reason === "string" && reason !== "") {
-                this.osd.push(reason);
-                return "reason";
-            }
+        // Like the player: only the first disabled command counts; without a
+        // reason the key goes on to the focused control.
+        const first = ids[0];
+        const reason = this.commands.has(first)
+            ? command(first).display.reason
+            : command(first).state.reason;
+        if (typeof reason === "string" && reason !== "") {
+            this.osd.push(reason);
+            return "reason";
         }
         return "passed";
     }
@@ -2232,6 +2513,9 @@ export class TestHost {
      * const rows = host.window("chat").props["messages"] as { body: Json }[];
      * assert.equal(host.markdown(rows[0]!.body)?.text, "**Hello**");
      * ```
+     *
+     * @capability None.
+     * @since 1.1.0
      */
     markdown(value) {
         const doc = value
@@ -2248,6 +2532,21 @@ export class TestHost {
     /**
      * Replace the plugin list and push `packages.changed` (another plugin
      * started, stopped, was installed or removed).
+     *
+     * @capability None.
+     *
+     * @example Simulate another plugin starting
+     * The plugin's store window hears that a plugin is running now. The list
+     * replaces `packages` and is pushed as `packages.changed`, which the
+     * plugin's `packages.onChange` listeners receive.
+     * ```ts
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.setPackages([...host.packages]); // edit a copy, then push it
+     * await host.settle();
+     * ```
+     *
+     * @since 1.0.0
      */
     setPackages(list) {
         this.packages = list;
@@ -2297,6 +2596,25 @@ export class TestHost {
      * Simulate another plugin calling `player.next()` / `previous()`: the host
      * asks this plugin's sequence provider. Rejects with `unavailable` when
      * there is no provider or its flag is false.
+     *
+     * @capability None.
+     * @throws `unavailable` (rejects) A `HostError`: there is no sequence
+     *   provider, or its flag is false.
+     *
+     * @example Ask the plugin's provider for the next item
+     * Another plugin calls `player.next()`; the host asks the plugin under
+     * test, which is the sequence provider, and the test checks what it
+     * opened.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * await host.step("next");
+     * await host.settle();
+     * assert.equal(host.source.source, "/media/b.mp4");
+     * ```
+     *
+     * @since 1.0.0
      */
     step(direction) {
         return this.request("sequence.step", { direction });
@@ -2304,6 +2622,23 @@ export class TestHost {
     /**
      * The plugin's command with this local id. Throws when it is not
      * registered (never added, or disposed).
+     *
+     * @capability None.
+     *
+     * @example Read a command's state after a change
+     * The test checks that Export becomes enabled once a file is ready. The
+     * record is updated as the plugin sends new state; read it after
+     * `settle()`.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.setSource({ phase: "ready", duration: 60 });
+     * await host.settle();
+     * assert.equal(host.command("export").state.enabled, true); // throws if not registered
+     * ```
+     *
+     * @since 1.0.0
      */
     command(id) {
         const command = this.commands.get(id);
@@ -2384,6 +2719,9 @@ export class TestHost {
      * await host.settle();
      * assert.equal(host.window("picture").props["brightness"], 0);
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     window(id) {
         const window = this.windows.get(id);
@@ -2409,6 +2747,9 @@ export class TestHost {
      * panel.emit("select", 2);
      * await host.settle();
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     mounted() {
         if (!this.panel)
@@ -2428,6 +2769,9 @@ export class TestHost {
      * // ---cut---
      * assert.deepEqual(host.sent("osd.show").at(-1), { text: "Saved" });
      * ```
+     *
+     * @capability None.
+     * @since 1.0.0
      */
     sent(method) {
         return this.calls
@@ -2477,6 +2821,10 @@ export class TestHost {
      *   await host.settle(20);
      * assert.equal(window.props["status-text"], expected);
      * ```
+     *
+     * @capability None.
+     * @throws Never.
+     * @since 1.0.0
      */
     async settle(ms = 0) {
         const deadline = Date.now() + ms;
@@ -2489,6 +2837,23 @@ export class TestHost {
     /**
      * Close the fake stream servers and delete the host's temporary
      * directories. `stop()` from {@link startPlugin} calls it.
+     *
+     * @capability None.
+     *
+     * @example Clean up a host that was never started
+     * A test that made a host but failed before `startPlugin` removes the
+     * host's temporary directories itself. `stop()` from `startPlugin` calls
+     * `close` for you otherwise.
+     * ```ts
+     * const host = new TestHost();
+     * try {
+     *   // … preset the host; the test fails here …
+     * } finally {
+     *   host.close(); // deletes the host's temporary data
+     * }
+     * ```
+     *
+     * @since 1.0.0
      */
     close() {
         for (const producer of this.producers.values())
@@ -2777,12 +3142,49 @@ export class TestHost {
             !["ready", "ended"].includes(this.source.phase))
             throw new HostError("unavailable", "audio tracks need ready media");
     }
-    #subtitleChange(expected) {
+    /** `stale` unless `expected` is the current subtitle stamp. */
+    #subtitleExpected(expected) {
         const stamp = this.subtitles.selection.stamp;
         const want = expected;
         if (want.generation !== stamp.generation ||
             want.revision !== stamp.revision)
             throw new HostError("stale", "subtitle selection changed");
+    }
+    /**
+     * The resources this plugin loaded into the current source (resource id →
+     * bytes), removed ones included: like the player, a removed track frees
+     * its place among the live tracks but not among the loads.
+     */
+    #subtitleResources = { generation: -1, bytes: new Map() };
+    #loadedSubtitles() {
+        const generation = this.source.stamp.generation;
+        if (this.#subtitleResources.generation !== generation)
+            this.#subtitleResources = { generation, bytes: new Map() };
+        return this.#subtitleResources.bytes;
+    }
+    /**
+     * The player's `SUBTITLE_LIMITS` for a new resource (`busy`, as the
+     * player reports them). External tracks in `subtitles.tracks` that this
+     * plugin did not load count as other plugins'. `totalBytes` is not
+     * modelled: one plugin's 4 files of at most 2 MiB stay below it, and the
+     * bytes of other plugins' tracks are unknown.
+     */
+    #subtitleRoom(resourceId) {
+        const loaded = this.#loadedSubtitles();
+        if (loaded.has(resourceId))
+            return;
+        const external = this.subtitles.tracks.filter((t) => t.target.kind === "external");
+        const own = external.filter((t) => t.target.kind === "external" && loaded.has(t.target.resourceId));
+        const others = external.length - own.length;
+        if (loaded.size >= SUBTITLE_LIMITS.loadsPerPlugin ||
+            loaded.size + others >= SUBTITLE_LIMITS.loads ||
+            own.length >= SUBTITLE_LIMITS.tracksPerPlugin ||
+            external.length >= SUBTITLE_LIMITS.tracks)
+            throw new HostError("busy", "subtitle resource or counter limit exceeded");
+    }
+    #subtitleChange(expected) {
+        this.#subtitleExpected(expected);
+        const stamp = this.subtitles.selection.stamp;
         this.subtitles.selection.stamp = {
             generation: this.source.stamp.generation,
             revision: stamp.revision + 1,
@@ -3101,7 +3503,10 @@ export class TestHost {
         },
         "storage.session.delete": (p) => void this.sessionStorage.delete(sessionKey(p.key)),
         "storage.session.keys": () => [...this.sessionStorage.keys()].sort(byCodePoint),
-        "app.system": () => structuredClone(this.systemInfo),
+        "app.system": () => ({
+            ...structuredClone(this.systemInfo),
+            rendering: this.videoRender.gpu ? "gpu" : "software",
+        }),
         "clipboard.readText": () => this.clipboard.text,
         "clipboard.writeText": (p) => {
             if (typeof p.text !== "string")
@@ -3785,9 +4190,24 @@ export class TestHost {
         "subtitles.upload.begin": (p) => {
             if (p.generation !== this.source.stamp.generation)
                 throw new HostError("stale", "source generation changed");
+            const expectedBytes = Number(p.expectedBytes);
+            if (!Number.isSafeInteger(expectedBytes) ||
+                expectedBytes < 1 ||
+                expectedBytes > SUBTITLE_LIMITS.fileBytes)
+                throw new HostError("invalid", `a subtitle file has 1..${SUBTITLE_LIMITS.fileBytes} bytes`);
+            // Like the player: a new source drops the old one's uploads. A commit
+            // the player refused leaves its upload for `subtitles.upload.discard`,
+            // which the SDK sends after any failed load.
+            for (const [id, upload] of this.uploads)
+                if (upload.generation !== undefined &&
+                    upload.generation !== this.source.stamp.generation)
+                    this.uploads.delete(id);
+            if (this.uploads.size >= SUBTITLE_LIMITS.uploadsPerPlugin)
+                throw new HostError("busy", "upload memory, owner or active-token limit reached");
             this.uploads.set(Number(p.uploadId), {
                 bytes: [],
-                expected: Number(p.expectedBytes),
+                expected: expectedBytes,
+                generation: this.source.stamp.generation,
             });
             return {
                 generation: p.generation,
@@ -3805,9 +4225,8 @@ export class TestHost {
         },
         "subtitles.upload.discard": (p) => void this.uploads.delete(Number(p.uploadId)),
         "subtitles.commit": (p) => {
-            const upload = this.uploads.get(Number(p.uploadId));
-            if (!upload)
-                throw new HostError("missing", "upload");
+            // The player's order: the request's own fields, then `stale`, then
+            // the upload and its content, then the limits.
             const format = p.format === "ass" ? "ass" : "srt";
             const select = p.select === "none"
                 ? "none"
@@ -3821,12 +4240,18 @@ export class TestHost {
                     : null;
             if (title !== null && ([...title].length < 1 || [...title].length > 200))
                 throw new HostError("invalid", "subtitle title needs 1..200 characters");
+            this.#subtitleExpected(p.expected);
+            const upload = this.uploads.get(Number(p.uploadId));
+            if (!upload)
+                throw new HostError("missing", "upload");
             const bytes = Buffer.concat(upload.bytes);
             if (format === "ass" &&
                 !(/\[Script Info\]/i.test(bytes.toString()) &&
                     /\[Events\]/i.test(bytes.toString())))
                 throw new HostError("invalid", "ASS requires [Script Info] and [Events] sections");
+            this.#subtitleRoom(String(p.resourceId));
             this.#subtitleChange(p.expected);
+            this.#loadedSubtitles().set(String(p.resourceId), bytes.length);
             const target = {
                 kind: "external",
                 owner: 1,
@@ -4138,6 +4563,16 @@ export class TestHost {
  *   }
  * });
  * ```
+ *
+ * @remarks
+ * The way into a plugin's tests: one call starts the plugin the way the
+ * player's runner does and returns the host to drive, the `plugin` object
+ * to call directly, and `stop` to end it like the player.
+ *
+ * @capability None.
+ * @see [Test a plugin](../../docs/how-to/testing.md)
+ * @since 1.0.0
+ * @category Testing
  */
 export async function startPlugin(activate, options = {}) {
     const host = options.host ?? new TestHost();