@vestra-player/sdk 1.5.6 → 1.5.8

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.5.8
+
+**Trial loading is removed; `resolvers.fileTypes`; the CLI under `--permission`.** `apiVersion` stays `vestra/1`. The removal breaks code that called `PackageCandidate.trial()`: only Vestra Player AI did, and it moves to installing (an install can be rolled back).
+
+- **Removed: `PackageCandidate.trial()`, the `PackageTrial` type, `PluginInfo.origin` `"trial"` and the error code `cleanup`** (only `PackageTrial.stop` used it). The player (0.4.2) no longer answers `packages.trial`, `packages.trialState`, `packages.trialStateByRequest` or `packages.stopTrial`, and never lists a plugin with origin `"trial"`. Trial loads only supported plugins using `commands`, `ui.window` and `events`, listed the plugin under another id (`<id>.trial.<n>`), and `trial()` returned before activation ended, so the feature was removed instead of extended. Check a package with `validate` and install it; `rollback` restores the previous version.
+- **`plugin.resolvers.fileTypes`** (player 0.4.2): the extensions some plugin's file resolver handles, lower case, sorted, each once, without who registered them; `[]` from older players. Reading needs no capability. **`plugin.resolvers.onFileTypesChange(listener)`** follows it when a file resolver comes or goes (needs `events`). For a playlist that accepts ROMs while an emulator plugin runs. `TestHost`: `host.fileTypes()` (this plugin's file resolvers plus `otherResolvers`) and `host.updateFileTypes()` after changing `otherResolvers`.
+- **`vestra-plugin` runs under Node's permission model** (`--permission`, with `--allow-child-process` for the type checker): looking for `node_modules/@types`, `tsconfig.json` and `.git` in parent folders it may not read threw `ERR_ACCESS_DENIED`; such a folder now counts as absent.
+- `Packages.validate`: the player (0.4.2) keeps the 32 most recent candidates and drops the oldest, whose `install` then fails with `stale`; before, the 33rd validation of a run failed with `busy` until the player restarted.
+
+## 1.5.7
+
+**Replaced or closed streams stop with `null`.** A fix; no API change, `apiVersion` stays `vestra/1`, any player.
+
+- **`Stream.onStop(null)` when another source replaced the stream or it was closed**, as documented. The player retires a stream's producer at once in both cases, and the SDK then passed the player's answer (`unavailable`, "producer absent") to `onStop` as an error. The SDK now reads the player's state to tell the two apart: replaced or closed is `null`; a failure is a `stream` error with the player's text (also when the player retired the producer right after failing it, which used to give "producer absent" too).
+- The same in the start-up paths: `openStream` replaced or closed before it ran rejects with `replaced` (was `unavailable`); a file resolver's stream replaced after the player selected it is a cancellation and no longer reaches `onError`.
+- **A file resolver's stream that cannot start after `resolve` returned** fails the open with Chinese text instead of the SDK's English (`"audio device is not ready: deviceLost"`): `device` "音频输出设备不可用", `timeout` "启动超时", `busy` "播放器正忙，请稍后重试", other start-up failures "无法启动播放"; the English detail goes to the plugin's log. The plugin never saw these errors, so the user read the SDK's words. An error thrown by `frame()` keeps its message; text for a file the plugin can judge (a bad header) belongs in `resolve`.
+- **`TestHost` retires producers like the player**: on `open`, `close`, another `openProvider` or resolved stream, a retired producer's `producer.state` answers `unavailable` and `producer.ack` `stale`. New `FakeProducer.retired`, and **`host.failStream(producerId, message)`** to fail the playing stream the way the player does (`phase: "error"` with `message`, producer retired). Tests that replaced a stream used to pass where the player failed.
+
 ## 1.5.6
 
 **A reference for AI assistants.** Documentation and packaging only; no API change, `apiVersion` stays `vestra/1`. (1.5.5 was not published to npm; this release includes its changes.)

package/bin/vestra-plugin.mjs

@@ -34,7 +34,7 @@
  */
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync as exists } from "node:fs";
 import {
   cp,
   mkdir,
@@ -110,6 +110,20 @@ async function json(path, fallback) {
 }
 
 /** A module from the plugin's project first, else the SDK's own dependencies. */
+/**
+ * Whether a path exists. Under Node's permission model (`--permission`)
+ * `existsSync` throws for a path outside the allowed ones; such a path
+ * counts as absent, as for a user who cannot read it.
+ */
+function present(path) {
+  try {
+    return exists(path);
+  } catch (error) {
+    if (error?.code === "ERR_ACCESS_DENIED") return false;
+    throw error;
+  }
+}
+
 function resolveFrom(directory, specifier) {
   for (const base of [directory, sdkRoot]) {
     try {
@@ -139,7 +153,7 @@ async function typescript() {
 async function plugin(path) {
   const directory = resolve(path);
   const name = relative(process.cwd(), directory) || basename(directory);
-  if (!existsSync(join(directory, "manifest.json")))
+  if (!present(join(directory, "manifest.json")))
     fail(`${name}: no manifest.json in ${directory}`);
   const manifest = await json(join(directory, "manifest.json"));
   const { problems, hints } = manifestProblems(manifest, directory);
@@ -165,7 +179,7 @@ function displayFiles(target) {
     const field = name === "README.md" ? "readme" : "changelog";
     if (
       target.manifest[field] === undefined &&
-      existsSync(join(target.directory, name))
+      present(join(target.directory, name))
     )
       files.add(name);
   }
@@ -200,7 +214,7 @@ function dependencies(target) {
   };
   if (
     !Object.keys(deps).length ||
-    existsSync(join(target.directory, "node_modules"))
+    present(join(target.directory, "node_modules"))
   )
     return;
   console.log(`${target.name}: installing dependencies (npm ci)`);
@@ -221,7 +235,7 @@ function* upwards(directory) {
   for (let current = directory; ;) {
     yield current;
     const parent = dirname(current);
-    if (parent === current || existsSync(join(current, ".git"))) return;
+    if (parent === current || present(join(current, ".git"))) return;
     current = parent;
   }
 }
@@ -235,13 +249,13 @@ function checkConfig(target, sources) {
   const roots = [];
   for (const directory of upwards(target.directory)) {
     const types = join(directory, "node_modules/@types");
-    if (existsSync(types)) roots.push(types);
+    if (present(types)) roots.push(types);
   }
   const node = resolveFrom(target.directory, "@types/node/package.json");
   if (node) roots.push(dirname(dirname(node)));
   const base = [...upwards(target.directory)]
     .map((directory) => join(directory, "tsconfig.json"))
-    .find((file) => existsSync(file));
+    .find((file) => present(file));
   return {
     ...(base ? { extends: base } : {}),
     compilerOptions: {
@@ -262,7 +276,7 @@ async function check(target) {
   const own = (await files(target.directory)).filter(
     (file) => isTypeScript(file) || file.endsWith(".mts"),
   );
-  const tests = existsSync(join(target.directory, "tests"))
+  const tests = present(join(target.directory, "tests"))
     ? (await readdir(join(target.directory, "tests")))
         .filter(isTypeScript)
         .map((file) => join("tests", file))
@@ -308,7 +322,7 @@ function entries(target) {
   const entry = target.manifest.entry.replace(/^dist\//, "");
   const candidates = [entry.replace(/\.js$/, ".ts"), entry];
   const found = candidates.find((file) =>
-    existsSync(join(target.directory, file)),
+    present(join(target.directory, file)),
   );
   if (!found)
     fail(`${target.name}: entry ${target.manifest.entry} has no source file`);
@@ -454,7 +468,7 @@ async function build(target, flag) {
 
 async function test(target) {
   const directory = join(target.directory, "tests");
-  const tests = existsSync(directory)
+  const tests = present(directory)
     ? (await readdir(directory))
         .filter((file) => /\.test\.(ts|mjs)$/.test(file))
         .sort()

package/dist/commands.d.ts

@@ -20,8 +20,7 @@ import type { Transport } from "./wire.ts";
  */
 export declare const COMMAND_LIMITS: {
     /**
-     * Commands one plugin instance may have at the same time (160). A trial
-     * package is its own instance.
+     * Commands one plugin instance may have at the same time (160).
      */
     readonly perPlugin: 160;
     /** Commands of every plugin plus the player's own, together (1024). */

package/dist/commands.js

@@ -18,8 +18,7 @@
  */
 export const COMMAND_LIMITS = {
     /**
-     * Commands one plugin instance may have at the same time (160). A trial
-     * package is its own instance.
+     * Commands one plugin instance may have at the same time (160).
      */
     perPlugin: 160,
     /** Commands of every plugin plus the player's own, together (1024). */

package/dist/plugin/packages.js

@@ -1,4 +1,4 @@
-/** Package validation, trial loading and install/rollback (`plugins.manage`). */
+/** Package validation and install/rollback (`plugins.manage`). */
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
 import { failure, sleep, uncertain } from "./runtime.js";
@@ -9,51 +9,6 @@ const TERMINAL = [
     "failedDegraded",
     "tooLate",
 ];
-const STARTING = ["preparing", "activating", "starting"];
-class TrialHandle {
-    #scope;
-    #record;
-    #stopped;
-    constructor(scope, record) {
-        this.#scope = scope;
-        this.#record = record;
-        scope.add(this);
-    }
-    get status() {
-        return this.#record.status;
-    }
-    /**
-     * Concurrent calls share one stop; a confirmed stop is final. A failed one
-     * (code `cleanup`: the host did not confirm cleanup) is forgotten, so the
-     * next call sends a new stop to the host.
-     */
-    stop() {
-        const host = this.#scope.runtime.host.packages;
-        if (this.#stopped)
-            return this.#stopped;
-        const stopping = (async () => {
-            this.#record = await host.stopTrial(this.#record.trialId);
-            while (!this.#record.cleanupConfirmed &&
-                this.#record.status !== "stopped" &&
-                this.#record.status !== "failed") {
-                await sleep(250);
-                this.#record = await host.trialState(this.#record.trialId);
-            }
-            if (!this.#record.cleanupConfirmed)
-                throw failure("cleanup", `trial cleanup not confirmed: ${this.#record.status}`);
-        })();
-        this.#stopped = stopping;
-        stopping.catch(() => {
-            if (this.#stopped === stopping)
-                this.#stopped = undefined;
-        });
-        return stopping;
-    }
-    async dispose() {
-        this.#scope.forget(this);
-        await this.stop().catch(() => { });
-    }
-}
 class ChangeHandle {
     #scope;
     #id;
@@ -123,24 +78,6 @@ async function change(scope, submit, id) {
     }
     return new ChangeHandle(scope, operation);
 }
-async function trial(scope, runtime, token) {
-    const host = runtime.host.packages;
-    const requestId = randomUUID();
-    let record;
-    try {
-        record = await host.trial(token, requestId);
-    }
-    catch (error) {
-        if (!uncertain(error))
-            throw error;
-        record = await host.trialStateByRequest(requestId);
-    }
-    while (STARTING.includes(record.status)) {
-        await sleep(250);
-        record = await host.trialState(record.trialId);
-    }
-    return new TrialHandle(scope, record);
-}
 function installOptions(options) {
     if (options === undefined)
         return {};
@@ -171,7 +108,6 @@ function candidate(scope, directory, checked) {
         digest: checked.digest,
         manifest: checked.manifest,
         checks: checked.checks,
-        trial: () => trial(scope, runtime, checked.token),
         install: async (options) => {
             const wire = installOptions(options);
             return change(scope, (requestId, revision) => runtime.host.packages.install(checked.token, revision, requestId, wire), checked.manifest.id);

package/dist/plugin/resolvers.js

@@ -5,8 +5,72 @@
 import { failure, quiet } from "./runtime.js";
 import { playerOf } from "./player.js";
 import { resolvedStream } from "./stream.js";
+import { windowOf } from "./window.js";
 const isFiles = (options) => "extensions" in options;
+const sameTypes = (a, b) => a.length === b.length && a.every((type, i) => type === b[i]);
+/**
+ * One per plugin: the list comes with the `window.state` read before
+ * activation (`[]` from older players) and is read again when the plugin
+ * first uses it; with `events`, `resolvers.fileTypes` keeps it current.
+ */
+class FileTypesService {
+    #runtime;
+    types;
+    #listeners = new Set();
+    #started = false;
+    constructor(runtime) {
+        this.#runtime = runtime;
+        this.types = Object.freeze([...(windowOf(runtime).fileTypes ?? [])]);
+    }
+    start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#runtime.on("resolvers.fileTypes", (data) => {
+            const types = data?.fileTypes;
+            if (Array.isArray(types) && types.every((t) => typeof t === "string"))
+                this.accept(types);
+        });
+        // What changed between the start-up read and the subscription.
+        const window = windowOf(this.#runtime);
+        void window.read().then(() => {
+            if (window.fileTypes)
+                this.accept(window.fileTypes, this.#runtime.can("events"));
+        });
+    }
+    /** `notify`: false without `events`, whose listeners never fire. */
+    accept(types, notify = true) {
+        if (sameTypes(types, this.types))
+            return;
+        this.types = Object.freeze([...types]);
+        if (notify)
+            for (const listener of [...this.#listeners])
+                listener([...types]);
+        this.#runtime.invalidate();
+    }
+    watch(listener) {
+        this.#listeners.add(listener);
+        return { dispose: async () => void this.#listeners.delete(listener) };
+    }
+}
+const fileTypesOf = (runtime) => runtime.service("fileTypes", () => new FileTypesService(runtime));
 export const resolvers = (scope) => ({
+    get fileTypes() {
+        const service = fileTypesOf(scope.runtime);
+        service.start();
+        return service.types;
+    },
+    onFileTypesChange(listener) {
+        const service = fileTypesOf(scope.runtime);
+        service.start();
+        const watch = service.watch((types) => scope.run(listener, types));
+        return scope.add({
+            dispose: async () => {
+                scope.forget(watch);
+                await watch.dispose();
+            },
+        });
+    },
     add(options) {
         const runtime = scope.runtime;
         const registration = isFiles(options)

package/dist/plugin/stream.js

@@ -79,7 +79,8 @@ class StreamHandle {
                 }, 5);
         }
         catch (error) {
-            void this.#end(toError(error));
+            const retired = await retirement(this.#service, this.#generation, error);
+            void this.#end(retired === undefined ? toError(error) : retired);
         }
     }
     async #render() {
@@ -131,6 +132,28 @@ class StreamHandle {
         await this.stop().catch(() => { });
     }
 }
+/**
+ * The player retires a producer the moment another source replaces it or
+ * the source closes, and after it failed, so its `producer.state` then
+ * answers `unavailable` (and `producer.ack` `stale`). The player's state
+ * says which: `null` (replaced or closed), the failure with the player's
+ * words, or `undefined` when the error is not a retirement.
+ */
+async function retirement(service, generation, error) {
+    const code = error?.code;
+    if (code !== "unavailable" && code !== "stale")
+        return undefined;
+    const readable = service.runtime.can("playback.read");
+    if (readable)
+        await service.refresh().catch(() => { });
+    const raw = service.raw;
+    if (raw.stamp.generation !== generation || raw.phase === "empty")
+        return null;
+    if (raw.phase === "error")
+        return failure("stream", service.state.error ?? "无法打开此媒体");
+    // Without `playback.read` the state may be behind: no failure was seen.
+    return readable ? undefined : null;
+}
 /** Start-up timeouts say which step ran out of time. */
 function timeout(stage, message) {
     return Object.assign(failure("timeout", message), { stage });
@@ -303,10 +326,40 @@ export async function openStream(scope, service, options) {
         // An abort can arrive before the host answered the selecting request: wait
         // for that answer so a source selected afterwards is still closed.
         await opened?.catch(() => { });
+        // Read before closing: replaced during activation is not a failure.
+        const retired = generation === undefined
+            ? undefined
+            : await retirement(service, generation, error);
         await abandon(service, p, generation);
-        throw error;
+        if (retired === null)
+            throw failure("replaced", "另一个来源已替换此媒体");
+        throw retired ?? error;
     }
 }
+/**
+ * What the user reads when a file resolver's stream cannot start. The
+ * player shows the answer as the open's failure, and the plugin never sees
+ * these errors: they happen after `resolve` returned. The SDK's and the
+ * player's own codes get the player's words; the detail goes to the log.
+ * An error the plugin threw from `frame()` keeps its own words.
+ */
+const START_TEXT = {
+    device: "音频输出设备不可用",
+    timeout: "启动超时",
+    busy: "播放器正忙，请稍后重试",
+    stream: "无法启动播放",
+    producer: "无法启动播放",
+    unavailable: "无法启动播放",
+    invalid: "无法启动播放",
+};
+function startFailure(scope, error) {
+    const code = error?.code;
+    const text = code === undefined ? undefined : START_TEXT[code];
+    if (text === undefined)
+        return error;
+    console.error(`[${scope.id}] file resolver stream did not start:`, error.message);
+    return Object.assign(failure(code, text), { cause: error });
+}
 /**
  * A file resolver's stream (`ResolvedStream`): prepared and prerolled while
  * the open waits, then handed to the host as the answer. Once the host
@@ -320,6 +373,8 @@ export async function resolvedStream(scope, service, stream, signal) {
     const p = await prepare(host, stream, () => {
         if (signal.aborted || scope.disposed)
             throw abortError();
+    }).catch((error) => {
+        throw startFailure(scope, error);
     });
     return {
         kind: "stream",
@@ -336,9 +391,12 @@ export async function resolvedStream(scope, service, stream, signal) {
                     throw abortError();
             }
             catch (error) {
+                // Replaced or closed before it ran is a cancellation, not a failure.
+                const retired = await retirement(service, stamp.generation, error);
                 await abandon(service, p, stamp.generation);
-                if (error.code !== "aborted")
-                    scope.report(error);
+                const reported = retired === undefined ? error : retired;
+                if (reported && reported.code !== "aborted")
+                    scope.report(reported);
                 return;
             }
             const handle = handleOf(scope, service, p, stamp.generation);

package/dist/plugin/testing.d.ts

@@ -117,6 +117,13 @@ export interface FakeProducer {
     videoFrames: number;
     /** `true` once the plugin released the producer (stream stopped or disposed). */
     released: boolean;
+    /**
+     * `true` once the player retired the producer, as the real player does at
+     * once: another source replaced it (`open`, another stream, a resolved
+     * file), the source was closed, or {@link TestHost.failStream} failed it.
+     * A retired producer's `producer.state` answers `unavailable`.
+     */
+    retired: boolean;
     /**
      * `true` if the frame connection closed while this stream was still the
      * player's source: the player reports that as a playback failure
@@ -766,6 +773,27 @@ export declare class TestHost implements Transport {
         /** Exact host names it resolves (a web resolver), with `schemes`. */
         hosts?: string[];
     }[];
+    /**
+     * What `plugin.resolvers.fileTypes` reports: the extensions of this
+     * plugin's file resolvers and of {@link TestHost.otherResolvers}, sorted,
+     * each once.
+     */
+    fileTypes(): string[];
+    /**
+     * Push `resolvers.fileTypes` when {@link TestHost.fileTypes} changed:
+     * called after this plugin's resolvers come and go; call it yourself
+     * after changing {@link TestHost.otherResolvers} (another plugin started
+     * or stopped).
+     *
+     * @example
+     * ```ts
+     * host.otherResolvers.push({ owner: "vestra.nes", extensions: ["nes"] });
+     * host.updateFileTypes();
+     * await host.settle();
+     * assert.deepEqual(plugin.resolvers.fileTypes, ["nes"]);
+     * ```
+     */
+    updateFileTypes(): void;
     /**
      * File opens waiting for this plugin's file resolver (`extensions`), by
      * request id: the path and how it was opened. Opening a matching path
@@ -1025,6 +1053,22 @@ export declare class TestHost implements Transport {
      * ```
      */
     openElsewhere(source: string, phase?: SourceState["phase"]): void;
+    /**
+     * Simulate a generated stream failing in the player (its audio device
+     * lost, its frame connection broken), like the player: the source fails
+     * with `message` (`phase: "error"`) and the producer is retired at once.
+     * The stream's `onStop` listeners get a `stream` error with `message`.
+     *
+     * @param producerId - The producer, from {@link TestHost.producers}.
+     * @param message - The player's failure text.
+     *
+     * @example
+     * ```ts
+     * const [producer] = host.producers.values();
+     * host.failStream(producer.id, "producer transport closed");
+     * ```
+     */
+    failStream(producerId: number, message: string): void;
     /**
      * Press a binding like the host's table would: panel-focus bindings first
      * when `panel` is true, then global ones; the earliest registration wins a
@@ -1072,7 +1116,7 @@ export declare class TestHost implements Transport {
         /** Its version, `null` when unknown. */
         version: string | null;
         /** Where it was loaded from. */
-        origin: "installed" | "development" | "trial";
+        origin: "installed" | "development";
         /** Its run state. */
         state: "starting" | "running" | "disabled" | "failed" | "stopped";
         /** Why it failed (`state: "failed"`). */

package/dist/plugin/testing.js

@@ -773,6 +773,43 @@ export class TestHost {
      * ```
      */
     otherResolvers = [];
+    /**
+     * What `plugin.resolvers.fileTypes` reports: the extensions of this
+     * plugin's file resolvers and of {@link TestHost.otherResolvers}, sorted,
+     * each once.
+     */
+    fileTypes() {
+        const types = new Set();
+        for (const declaration of [
+            ...this.resolvers.values(),
+            ...this.otherResolvers,
+        ])
+            for (const type of declaration.extensions ?? [])
+                types.add(type);
+        return [...types].sort();
+    }
+    #sentTypes = "[]";
+    /**
+     * Push `resolvers.fileTypes` when {@link TestHost.fileTypes} changed:
+     * called after this plugin's resolvers come and go; call it yourself
+     * after changing {@link TestHost.otherResolvers} (another plugin started
+     * or stopped).
+     *
+     * @example
+     * ```ts
+     * host.otherResolvers.push({ owner: "vestra.nes", extensions: ["nes"] });
+     * host.updateFileTypes();
+     * await host.settle();
+     * assert.deepEqual(plugin.resolvers.fileTypes, ["nes"]);
+     * ```
+     */
+    updateFileTypes() {
+        const types = this.fileTypes();
+        if (JSON.stringify(types) === this.#sentTypes)
+            return;
+        this.#sentTypes = JSON.stringify(types);
+        this.emit("resolvers.fileTypes", { fileTypes: types });
+    }
     /**
      * File opens waiting for this plugin's file resolver (`extensions`), by
      * request id: the path and how it was opened. Opening a matching path
@@ -1361,6 +1398,7 @@ export class TestHost {
             videoArea: { ...this.mainWindow.videoArea },
             pictureInPicture: { ...this.mainWindow.pictureInPicture },
             appearance: this.appearance,
+            fileTypes: this.fileTypes(),
         };
     }
     /**
@@ -1385,6 +1423,31 @@ export class TestHost {
         if (this.#resolve(source, false) === null)
             this.setSource({ phase });
     }
+    /**
+     * Simulate a generated stream failing in the player (its audio device
+     * lost, its frame connection broken), like the player: the source fails
+     * with `message` (`phase: "error"`) and the producer is retired at once.
+     * The stream's `onStop` listeners get a `stream` error with `message`.
+     *
+     * @param producerId - The producer, from {@link TestHost.producers}.
+     * @param message - The player's failure text.
+     *
+     * @example
+     * ```ts
+     * const [producer] = host.producers.values();
+     * host.failStream(producer.id, "producer transport closed");
+     * ```
+     */
+    failStream(producerId, message) {
+        const producer = this.producers.get(producerId);
+        if (!producer || !this.#current(producerId))
+            throw new Error(`producer ${producerId} is not the player's source`);
+        this.setSource({
+            phase: "error",
+            terminalReason: { failed: message },
+        });
+        producer.retired = true;
+    }
     /**
      * Press a binding like the host's table would: panel-focus bindings first
      * when `panel` is true, then global ones; the earliest registration wins a
@@ -1721,6 +1784,10 @@ export class TestHost {
             if (control.kind === "rate")
                 next.rate = Number(control.rate);
         }
+        // Like the player: the selected producer is retired as soon as another
+        // source replaces it or the source closes.
+        if (["open", "openProvider", "close"].includes(String(intent.kind)))
+            this.#retireSelected(intent.kind === "openProvider" ? Number(intent.producerId) : null);
         if (intent.kind === "openProvider")
             this.#selected = Number(intent.producerId);
         if (intent.kind === "open" || intent.kind === "close")
@@ -1748,6 +1815,14 @@ export class TestHost {
         }
         return null;
     }
+    /** Retire the producer that is the player's source, unless it is `keep`. */
+    #retireSelected(keep) {
+        for (const producer of this.producers.values())
+            if (producer.id !== keep &&
+                !producer.retired &&
+                this.#current(producer.id))
+                producer.retired = true;
+    }
     /** Whether producer `id` is the player's source. */
     #current(id) {
         return (this.source.kind === "producer" &&
@@ -1853,9 +1928,10 @@ export class TestHost {
         const producer = this.producers.get(Number(result.producerId));
         if (result.kind !== "stream")
             fail("invalid resolved stream descriptor");
-        if (!producer || producer.released)
+        if (!producer || producer.released || producer.retired)
             fail("unavailable: producer absent");
         // Like openProvider, but the source keeps the path and `startPaused`.
+        this.#retireSelected(producer.id);
         this.#selected = producer.id;
         producer.active = true;
         producer.acknowledged = false;
@@ -2645,8 +2721,6 @@ export class TestHost {
             const entry = this.packages.find((each) => each.id === id);
             if (!entry)
                 throw new HostError("missing", `no plugin ${id}`);
-            if (entry.origin === "trial")
-                throw new HostError("unsupported", "a trial is stopped with its handle");
             this.packageCalls.push({
                 method: "setEnabled",
                 id,
@@ -2906,10 +2980,14 @@ export class TestHost {
             return { jobId: job.jobId, cancel: "requested" };
         },
         "jobs.operation": () => ({ status: "unknown" }),
-        "sourceResolvers.register": (p) => void this.#register(p),
+        "sourceResolvers.register": (p) => {
+            this.#register(p);
+            this.updateFileTypes();
+        },
         "sourceResolvers.unregister": (p) => {
             this.resolvers.delete(String(p.id));
             this.#cancelResolutions();
+            this.updateFileTypes();
         },
         "sourceResolvers.respond": (p) => this.#respond(p),
         "producer.prepare": async () => {
@@ -2922,6 +3000,7 @@ export class TestHost {
                 receivedFrames: 0,
                 videoFrames: 0,
                 released: false,
+                retired: false,
                 droppedWhileSelected: false,
                 path,
                 admitted: !tcp,
@@ -2988,6 +3067,8 @@ export class TestHost {
             const producer = this.producers.get(Number(p.producerId));
             if (!producer)
                 throw new HostError("missing", "producer");
+            if (producer.retired || producer.released)
+                throw new HostError("unavailable", "producer absent");
             const current = this.#current(producer.id);
             return {
                 input: null,
@@ -3017,6 +3098,8 @@ export class TestHost {
             const producer = this.producers.get(Number(control.producerId));
             if (!producer)
                 throw new HostError("missing", "producer");
+            if (producer.retired || producer.released)
+                throw new HostError("stale", "producer control changed");
             producer.pending = null;
             producer.acknowledged = true;
             producer.epoch = Number(control.epoch);