@vestra-player/sdk 1.5.2 → 1.5.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.5.3
+
+**File resolvers: local files as generated streams** (player 0.4.1). Additive; `apiVersion` stays `vestra/1`. Plugins that register one set `"minPlayerVersion": "0.4.1"`: an older player refuses the declaration (`invalid`).
+
+- **`resolvers.add({ id, extensions, resolve })`** (`FileResolverOptions`). When anyone opens a local file of those extensions with `player.open` (the Open dialog, the playlist, next / previous, the recent list), the player asks this plugin for a stream instead of playing the file. `resolve(path, signal)` returns a `ResolvedStream`: `{ kind: "stream", width, height, frame, started? }`, with the frame contract of `openStream`. Needs `source.resolve` and `producer.av`. `ResolverOptions` is now the union of `WebResolverOptions` (the existing form) and `FileResolverOptions`.
+  - The open keeps its arbitration: its `ifCurrent` and operation (the opener's `open` / `media.ready()` settle as usual), and `paused` reaches the stream's start. `state.source` stays the path, `state.kind` is `"stream"`.
+  - Cancellation: `signal` aborts when the open is replaced or closed (`player.close()` included), times out (30 s) or the resolver is disposed. Cancelled after `resolve` returned but before the stream ran, the SDK releases the stream and never calls `started`.
+  - `started(stream)` is called synchronously right after activation, before any `onStop`; the `Stream` is the same as `openStream`'s and belongs to the resolver's plugin.
+  - Extensions: 1–16 entries of 1–16 lower-case letters or digits, not `"folder"`; only absolute local paths match (any case), URLs never do.
+- **One extension, and one scheme + host pair, has one resolver.** Another plugin's makes `Resolver.ready` reject with `conflict` (reason `resolver-taken` on the wire), and that no longer fails activation, for web resolvers too (as for panels and the sequence since 1.5.2); the player shows a warning (`PluginInfo.warnings`: `code` `"resolver-taken"`, `owner`, the new `target`). The plugin's own second claim still fails activation.
+- **Resolver failures are sent as the error's message** (`error.message`, was `String(error)`, e.g. `"Error: …"`), and the player shows them word for word (it prefixed `resolver failed: `). This changes the failure text of web resolvers too.
+- **Docs**: `PlayerState.source` documents the naming of generated streams: `producer://<n>` (opaque) for `openStream`, the path for a file resolver's; tell streams apart by `kind`.
+- **`TestHost`** simulates file resolutions: opening a matching path (`player.open`, `openElsewhere`) sends `source.resolveRequest` and keeps the open pending; the answer selects the stream (or fails the open); any later source change cancels it (`source.resolveCancel`). `resolutions` lists the pending ones, `otherResolvers` simulates other plugins' registrations (conflicts). `startPlugin` does not fail activation for such a conflict. Web resolutions are still driven by the test (emit `source.resolveRequest`).
+- Internals: `openStream` is split into prepare / activate / abandon steps shared with file resolvers; the wire client (`sourceResolvers.register`) takes a `{ id, extensions }` declaration and a handler answer with the prepared producer.
+
 ## 1.5.2
 
 **Sidebar tabs** (the player after 0.4.0). Additive; `apiVersion` stays `vestra/1`, and plugins written for 1.5.1 need no change. The new members work against older players too (see each one).

package/dist/plugin/resolvers.js

@@ -1,10 +1,22 @@
-/** Source resolvers turn page URLs into stream URLs for `player.open`. */
-import { quiet } from "./runtime.js";
+/**
+ * Source resolvers: page URLs to stream URLs, or local files to a stream
+ * this plugin generates, for `player.open`.
+ */
+import { failure, quiet } from "./runtime.js";
+import { playerOf } from "./player.js";
+import { resolvedStream } from "./stream.js";
+const isFiles = (options) => "extensions" in options;
 export const resolvers = (scope) => ({
     add(options) {
-        const { resolve, ...declaration } = options;
         const runtime = scope.runtime;
-        const registration = runtime.host.sourceResolvers.register(declaration, ({ url, signal }) => resolve(url, signal));
+        const registration = isFiles(options)
+            ? runtime.host.sourceResolvers.register({ id: options.id, extensions: options.extensions }, async ({ url, signal }) => {
+                const stream = await options.resolve(url, signal);
+                if (stream?.kind !== "stream")
+                    throw failure("invalid", 'a file resolver returns { kind: "stream", width, height, frame }');
+                return resolvedStream(scope, playerOf(runtime), stream, signal);
+            })
+            : runtime.host.sourceResolvers.register({ id: options.id, schemes: options.schemes, hosts: options.hosts }, ({ url, signal }) => options.resolve(url, signal));
         let disposed = false;
         const handle = {
             ready: quiet(runtime

package/dist/plugin/stream.d.ts

@@ -1,4 +1,14 @@
 import type { PlayerService } from "./player.ts";
 import type { ScopeImpl } from "./scope.ts";
-import type { Stream, StreamOptions } from "./types.ts";
+import type { ResolvedProducer } from "../source-resolvers.ts";
+import type { ResolvedStream, Stream, StreamOptions } from "./types.ts";
 export declare function openStream(scope: ScopeImpl, service: PlayerService, options: StreamOptions): Promise<Stream>;
+/**
+ * A file resolver's stream (`ResolvedStream`): prepared and prerolled while
+ * the open waits, then handed to the host as the answer. Once the host
+ * selected it, the start control is acknowledged and `started` gets the
+ * running stream, synchronously, before any `onStop`. Cancelled before or
+ * during activation (the open was replaced or closed, the plugin stopped),
+ * the producer is released and `started` is never called.
+ */
+export declare function resolvedStream(scope: ScopeImpl, service: PlayerService, stream: ResolvedStream, signal: AbortSignal): Promise<ResolvedProducer>;

package/dist/plugin/stream.js

@@ -154,17 +154,11 @@ async function sendFrame(socket, frame, clock, epoch) {
         clock.advance(samples.length / 2);
     }
 }
-export async function openStream(scope, service, options) {
-    const host = service.runtime.host;
-    const check = () => {
-        if (options.signal?.aborted || scope.disposed)
-            throw abortError();
-    };
-    let prepared;
-    let socket;
-    let generation;
-    /** The request selecting the stream, once sent. */
-    let opened;
+/**
+ * Prepare a producer, connect and preroll it until the host could select it.
+ * `check` throws to give up (an abort); the producer is then released.
+ */
+async function prepare(host, options, check) {
     const bytes = options.width * options.height * 4;
     /** The plugin's frame, checked against the declared size. */
     const frame = () => {
@@ -173,103 +167,183 @@ export async function openStream(scope, service, options) {
             throw failure("invalid", `frame().video must be ${options.width}×${options.height}×4 = ${bytes} bytes of RGBA`);
         return next;
     };
+    let producer;
+    let socket;
     try {
         check();
         const spec = await host.producer.prepare({
             width: options.width,
             height: options.height,
         });
-        prepared = spec.producerId;
+        producer = spec.producerId;
         check();
         socket = await host.producer.connect(spec);
         check();
-        let epoch = spec.epoch;
-        let sample = 0;
-        let sequence = 0;
-        const clock = {
-            get sample() {
-                return sample;
-            },
-            advance: (n) => (sample += n),
-            nextSequence: () => sequence++,
+        const p = {
+            producer,
+            socket,
+            frame,
+            epoch: spec.epoch,
+            sample: 0,
+            sequence: 0,
         };
+        const clock = clockOf(p);
         // A prepared producer is paused at sample zero. Supply a frame at zero and
         // enough contiguous PCM before asking the host to select it.
-        while (sample < PREROLL) {
+        while (p.sample < PREROLL) {
             check();
-            await writeFrame(socket, frame(), clock, epoch);
+            await writeFrame(socket, frame(), clock, p.epoch);
         }
         for (const deadline = Date.now() + 10_000;; await sleep(10)) {
             check();
-            const state = await host.producer.state(prepared);
+            const state = await host.producer.state(producer);
             if (state.error)
                 throw failure("stream", state.error);
-            if (state.epoch !== epoch)
+            if (state.epoch !== p.epoch)
                 throw failure("stream", "producer epoch changed before activation");
             if (!["ok", "recoverableXrun", "deviceChanged"].includes(state.health))
                 throw failure("device", `audio device is not ready: ${state.health}`);
             if (state.acknowledged && state.receivedFrames >= 1024 && state.hasVideo)
-                break;
+                return p;
             if (Date.now() >= deadline)
                 throw timeout("prefill", "timed out preparing the first buffers");
         }
+    }
+    catch (error) {
+        socket?.close();
+        if (producer !== undefined)
+            await host.producer.release(producer).catch(() => { });
+        throw error;
+    }
+}
+const clockOf = (p) => ({
+    get sample() {
+        return p.sample;
+    },
+    advance: (n) => (p.sample += n),
+    nextSequence: () => p.sequence++,
+});
+/**
+ * Wait until the host runs the selected producer: acknowledge its start
+ * control. `selected` says whether the host has accepted the selection yet
+ * (`"selected"`: it has, and a producer no longer active was replaced);
+ * `check` throws to give up.
+ */
+async function activate(host, p, check, selected) {
+    for (const deadline = Date.now() + 10_000;; await sleep(10)) {
+        check();
+        const state = await host.producer.state(p.producer);
+        if (state.error)
+            throw failure("stream", state.error);
+        if (selected === "selected" && !state.active)
+            throw abortError();
+        if (state.pendingControl) {
+            p.epoch = state.pendingControl.epoch;
+            p.sample = state.pendingControl.baseSample;
+            p.sequence = 0;
+            await host.producer.ack(state.pendingControl);
+        }
+        if ((selected === "selected" || selected()) &&
+            state.active &&
+            !state.pendingControl &&
+            state.acknowledged &&
+            state.epoch === p.epoch)
+            return;
+        if (Date.now() >= deadline)
+            throw timeout("activation", "timed out waiting for stream activation");
+    }
+}
+/** Give a prepared producer up: its source (if still ours), connection, producer. */
+async function abandon(service, p, generation) {
+    // A cancelled open may already have selected this producer: close only
+    // that source, before its frame connection (as in `stop`).
+    if (generation !== undefined)
+        await service.closeIfCurrent(generation).catch(() => { });
+    p.socket.close();
+    await service.runtime.host.producer.release(p.producer).catch(() => { });
+}
+const handleOf = (scope, service, p, generation) => new StreamHandle(scope, service, {
+    producer: p.producer,
+    socket: p.socket,
+    generation,
+    frame: p.frame,
+    epoch: p.epoch,
+    sample: p.sample,
+    sequence: p.sequence,
+});
+export async function openStream(scope, service, options) {
+    const host = service.runtime.host;
+    const check = () => {
+        if (options.signal?.aborted || scope.disposed)
+            throw abortError();
+    };
+    const p = await prepare(host, options, check);
+    let generation;
+    /** The request selecting the stream. */
+    let opened;
+    try {
         let accepted = false;
+        let failed;
         opened = service
-            .submit({ kind: "openProvider", producerId: prepared, startPaused: false }, { accepted: (ticket) => (generation = ticket.stamp.generation) })
+            .submit({ kind: "openProvider", producerId: p.producer, startPaused: false }, { accepted: (ticket) => (generation = ticket.stamp.generation) })
             .then((ticket) => {
             generation = ticket.stamp.generation;
             accepted = true;
         });
-        let failed;
         opened.catch((error) => (failed = error));
         // Activation needs this side to acknowledge the host's start control.
-        for (const deadline = Date.now() + 10_000;; await sleep(10)) {
+        await activate(host, p, () => {
             check();
             if (failed)
                 throw failed;
-            const state = await host.producer.state(prepared);
-            if (state.error)
-                throw failure("stream", state.error);
-            if (state.pendingControl) {
-                epoch = state.pendingControl.epoch;
-                sample = state.pendingControl.baseSample;
-                sequence = 0;
-                await host.producer.ack(state.pendingControl);
-            }
-            if (accepted &&
-                state.active &&
-                !state.pendingControl &&
-                state.acknowledged &&
-                state.epoch === epoch)
-                break;
-            if (Date.now() >= deadline)
-                throw timeout("activation", "timed out waiting for stream activation");
-        }
-        const handle = new StreamHandle(scope, service, {
-            producer: prepared,
-            socket,
-            generation: generation,
-            frame,
-            epoch,
-            sample,
-            sequence,
-        });
-        prepared = undefined;
-        socket = undefined;
-        return handle;
+        }, () => accepted);
+        return handleOf(scope, service, p, generation);
     }
     catch (error) {
         // An abort can arrive before the host answered the selecting request: wait
         // for that answer so a source selected afterwards is still closed.
-        if (opened && prepared !== undefined)
-            await opened.catch(() => { });
-        // A cancelled open may already have selected this producer: close only
-        // that source, before its frame connection (as in `stop`).
-        if (generation !== undefined && prepared !== undefined)
-            await service.closeIfCurrent(generation).catch(() => { });
-        socket?.close();
-        if (prepared !== undefined)
-            await host.producer.release(prepared).catch(() => { });
+        await opened?.catch(() => { });
+        await abandon(service, p, generation);
         throw 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
+ * selected it, the start control is acknowledged and `started` gets the
+ * running stream, synchronously, before any `onStop`. Cancelled before or
+ * during activation (the open was replaced or closed, the plugin stopped),
+ * the producer is released and `started` is never called.
+ */
+export async function resolvedStream(scope, service, stream, signal) {
+    const host = service.runtime.host;
+    const p = await prepare(host, stream, () => {
+        if (signal.aborted || scope.disposed)
+            throw abortError();
+    });
+    return {
+        kind: "stream",
+        producerId: p.producer,
+        abandoned: () => abandon(service, p, undefined),
+        accepted: async ({ stamp }) => {
+            try {
+                await activate(host, p, () => {
+                    if (scope.disposed)
+                        throw abortError();
+                }, "selected");
+                // Replaced before it ran: the source is no longer this stream.
+                if (service.raw.stamp.generation > stamp.generation)
+                    throw abortError();
+            }
+            catch (error) {
+                await abandon(service, p, stamp.generation);
+                if (error.code !== "aborted")
+                    scope.report(error);
+                return;
+            }
+            const handle = handleOf(scope, service, p, stamp.generation);
+            if (stream.started)
+                scope.run(stream.started, handle);
+        },
+    };
+}

package/dist/plugin/testing.d.ts

@@ -744,6 +744,45 @@ export declare class TestHost implements Transport {
     }>;
     /** Registered source resolvers (`resolvers.add`) by id: their declarations. */
     readonly resolvers: Map<string, Json>;
+    /**
+     * Resolvers other plugins hold, as `resolvers.add` declares them plus the
+     * holder's id: a registration of this plugin that claims one of their
+     * extensions (or scheme + host pairs) is refused with `conflict`, which
+     * does not fail activation, like the player.
+     *
+     * @example
+     * ```ts
+     * const host = new TestHost();
+     * host.otherResolvers.push({ owner: "vestra.nes", extensions: ["nes"] });
+     * ```
+     */
+    readonly otherResolvers: {
+        /** The manifest id of the plugin holding them (shown in the refusal). */
+        owner: string;
+        /** File extensions it resolves (a file resolver), lower case, no dot. */
+        extensions?: string[];
+        /** URL schemes it resolves (a web resolver), with `hosts`. */
+        schemes?: string[];
+        /** Exact host names it resolves (a web resolver), with `schemes`. */
+        hosts?: string[];
+    }[];
+    /**
+     * File opens waiting for this plugin's file resolver (`extensions`), by
+     * request id: the path and how it was opened. Opening a matching path
+     * (`player.open`, {@link TestHost.openElsewhere}) sends
+     * `source.resolveRequest`; the answer selects the stream, fails the open
+     * or, once the source changed, is `stale`. Any later source change
+     * cancels it (`source.resolveCancel`). Web resolvers are not simulated:
+     * emit `source.resolveRequest` yourself.
+     */
+    readonly resolutions: Map<number, {
+        /** The id of this plugin's resolver asked (`resolvers.add` `id`). */
+        resolverId: string;
+        /** The path being opened, as sent to `resolve`. */
+        source: string;
+        /** The open asked for a paused start (`player.open(path, { paused })`). */
+        paused: boolean;
+    }>;
     /**
      * Answers for `dialogs.open` (paths, `null` = cancelled) and
      * `dialogs.confirm` (`{ confirmed, checked }`), consumed in order. A

package/dist/plugin/testing.js

@@ -61,7 +61,7 @@ import { mkdirSync, mkdtempSync, rmSync, statSync } from "node:fs";
 import { createServer } from "node:net";
 import { randomBytes } from "node:crypto";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { extname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { HostError } from "../wire.js";
 import { COMMAND_LIMITS, MENU_IDS } from "../commands.js";
@@ -110,7 +110,10 @@ const readyCapabilities = {
     close: true,
     snapshotSource: true,
 };
-/** Refusals for a position another plugin holds: not activation failures (`startPlugin`). */
+/**
+ * Refusals for a position or resolver another plugin holds: not activation
+ * failures (`startPlugin`).
+ */
 const takenErrors = new WeakSet();
 const taken = (message) => {
     const error = new HostError("conflict", message);
@@ -757,6 +760,29 @@ export class TestHost {
     producers = new Map();
     /** Registered source resolvers (`resolvers.add`) by id: their declarations. */
     resolvers = new Map();
+    /**
+     * Resolvers other plugins hold, as `resolvers.add` declares them plus the
+     * holder's id: a registration of this plugin that claims one of their
+     * extensions (or scheme + host pairs) is refused with `conflict`, which
+     * does not fail activation, like the player.
+     *
+     * @example
+     * ```ts
+     * const host = new TestHost();
+     * host.otherResolvers.push({ owner: "vestra.nes", extensions: ["nes"] });
+     * ```
+     */
+    otherResolvers = [];
+    /**
+     * File opens waiting for this plugin's file resolver (`extensions`), by
+     * request id: the path and how it was opened. Opening a matching path
+     * (`player.open`, {@link TestHost.openElsewhere}) sends
+     * `source.resolveRequest`; the answer selects the stream, fails the open
+     * or, once the source changed, is `stale`. Any later source change
+     * cancels it (`source.resolveCancel`). Web resolvers are not simulated:
+     * emit `source.resolveRequest` yourself.
+     */
+    resolutions = new Map();
     /**
      * Answers for `dialogs.open` (paths, `null` = cancelled) and
      * `dialogs.confirm` (`{ confirmed, checked }`), consumed in order. A
@@ -850,8 +876,12 @@ export class TestHost {
     #overrides = new Map();
     #listeners = new Map();
     #inFlight = 0;
-    #next = { snapshot: 0, job: 0, producer: 0, source: 0 };
+    #next = { snapshot: 0, job: 0, producer: 0, source: 0, resolution: 0 };
     #sourceBook = new Map();
+    /** The pending resolutions' stamps and operations (beside `resolutions`). */
+    #resolving = new Map();
+    /** The producer the source is (`openProvider`, a resolved stream). */
+    #selected = null;
     #scratch = mkdtempSync(join(tmpdir(), "vestra-test-host-"));
     /**
      * `plugin.dataDirectory`: a fresh empty temporary directory, removed with
@@ -1351,7 +1381,9 @@ export class TestHost {
      */
     openElsewhere(source, phase = "ready") {
         this.#intent({ kind: "open", source, startPaused: false });
-        this.setSource({ phase });
+        // A file this plugin's file resolver claims waits for its answer.
+        if (this.#resolve(source, false) === null)
+            this.setSource({ phase });
     }
     /**
      * Press a binding like the host's table would: panel-focus bindings first
@@ -1682,14 +1714,166 @@ export class TestHost {
             if (control.kind === "rate")
                 next.rate = Number(control.rate);
         }
+        if (intent.kind === "openProvider")
+            this.#selected = Number(intent.producerId);
+        if (intent.kind === "open" || intent.kind === "close")
+            this.#selected = null;
         this.source = next;
         this.subtitles.source = {
             generation: next.stamp.generation,
             phase: next.phase,
         };
         this.emit("source.state", this.source);
+        this.#cancelResolutions();
         return { ticket: { stamp: next.stamp, cycle: next.cycle, owner: 1 } };
     }
+    /** The file resolver of this plugin that claims `source`, if any. */
+    #fileResolver(source) {
+        if (source.includes("://") || !isAbsolute(source))
+            return null;
+        const extension = extname(source).slice(1).toLowerCase();
+        if (!extension)
+            return null;
+        for (const [id, declaration] of this.resolvers) {
+            const extensions = declaration.extensions;
+            if (extensions?.includes(extension))
+                return id;
+        }
+        return null;
+    }
+    /** Whether producer `id` is the player's source. */
+    #current(id) {
+        return (this.source.kind === "producer" &&
+            (this.#selected === id || this.source.source === `producer://${id}`));
+    }
+    /** Start resolving `source` for the open just made; its request id, or null. */
+    #resolve(source, paused, operation) {
+        const resolverId = this.#fileResolver(source);
+        if (resolverId === null)
+            return null;
+        const requestId = ++this.#next.resolution;
+        this.resolutions.set(requestId, { resolverId, source, paused });
+        this.#resolving.set(requestId, {
+            stamp: { ...this.source.stamp },
+            ...(operation === undefined ? {} : { operation }),
+        });
+        this.emit("source.resolveRequest", { requestId, resolverId, url: source });
+        return requestId;
+    }
+    /** Settle a resolution's open; `error` fails it. */
+    #settle(requestId, error) {
+        const operation = this.#resolving.get(requestId)?.operation;
+        this.resolutions.delete(requestId);
+        this.#resolving.delete(requestId);
+        if (operation === undefined)
+            return;
+        const entry = this.#sourceBook.get(operation);
+        this.#sourceBook.set(operation, error === undefined
+            ? { status: "completed", ticket: entry?.ticket ?? null }
+            : { status: "failed", error: { backend: error } });
+    }
+    /** Resolutions whose open is no longer the source (or whose resolver left). */
+    #cancelResolutions() {
+        const stamp = this.source.stamp;
+        for (const [requestId, resolution] of [...this.resolutions]) {
+            const pending = this.#resolving.get(requestId);
+            if (pending.stamp.generation === stamp.generation &&
+                pending.stamp.intentVersion === stamp.intentVersion &&
+                this.resolvers.has(resolution.resolverId))
+                continue;
+            this.#settle(requestId, "source resolution cancelled, expired or superseded");
+            this.emit("source.resolveCancel", {
+                requestId,
+                resolverId: resolution.resolverId,
+            });
+        }
+    }
+    /** `sourceResolvers.register`: the player's rules for both forms. */
+    #register(p) {
+        const id = String(p.id);
+        const extensions = p.extensions;
+        if (this.resolvers.has(id))
+            throw new HostError("conflict", "resolver id already registered");
+        if (extensions !== undefined) {
+            if (p.schemes !== undefined ||
+                p.hosts !== undefined ||
+                !Array.isArray(extensions) ||
+                extensions.length < 1 ||
+                extensions.length > 16 ||
+                extensions.some((e) => typeof e !== "string" ||
+                    !/^[a-z0-9]{1,16}$/.test(e) ||
+                    e === "folder"))
+                throw new HostError("invalid", "file resolvers take 1–16 file extensions (lower case, no dot, not folder)");
+        }
+        const claims = (other) => extensions?.find((e) => other.extensions?.includes(e)) ??
+            (other.hosts?.some((h) => p.hosts?.includes(h)) &&
+                other.schemes?.some((x) => p.schemes?.includes(x))
+                ? "host"
+                : undefined);
+        for (const own of this.resolvers.values())
+            if (claims(own))
+                throw new HostError("conflict", "already registered by this plugin");
+        for (const other of this.otherResolvers) {
+            const what = claims(other);
+            if (what) {
+                const target = what === "host" ? "这个网站" : `文件类型 .${what}`;
+                throw taken(`${target} 已由 ${other.owner} 解析`);
+            }
+        }
+        this.resolvers.set(id, p);
+    }
+    /** `sourceResolvers.respond` for a simulated file resolution. */
+    #respond(p) {
+        const requestId = Number(p.requestId);
+        const resolution = this.resolutions.get(requestId);
+        if (!resolution) {
+            // Web resolutions are not simulated: their answers are only recorded.
+            if (requestId > this.#next.resolution)
+                return null;
+            throw new HostError("stale", "resolution no longer pending");
+        }
+        const fail = (message) => {
+            this.#settle(requestId, message);
+            this.setSource({
+                phase: "error",
+                terminalReason: { failed: message },
+            });
+            throw new HostError("resolution", message);
+        };
+        if (typeof p.error === "string")
+            fail(p.error.trim() ? p.error.slice(0, 2048) : "resolver failed");
+        const result = (p.result ?? {});
+        const producer = this.producers.get(Number(result.producerId));
+        if (result.kind !== "stream")
+            fail("invalid resolved stream descriptor");
+        if (!producer || producer.released)
+            fail("unavailable: producer absent");
+        // Like openProvider, but the source keeps the path and `startPaused`.
+        this.#selected = producer.id;
+        producer.active = true;
+        producer.acknowledged = false;
+        producer.pending = {
+            producerId: producer.id,
+            epoch: producer.epoch + 1,
+            baseSample: producer.receivedFrames,
+            paused: resolution.paused,
+        };
+        this.#settle(requestId);
+        this.setSource({
+            kind: "producer",
+            phase: "ready",
+            paused: resolution.paused,
+            capabilities: {
+                pause: true,
+                seek: false,
+                rate: false,
+                restart: false,
+                close: true,
+                snapshotSource: false,
+            },
+        });
+        return { stamp: { ...this.source.stamp } };
+    }
     #processingState() {
         const list = (stage) => [...this.processing.resources]
             .filter(([, value]) => value.stage === stage)
@@ -2277,8 +2461,17 @@ export class TestHost {
         "source.state": () => this.source,
         "source.submit": (p) => {
             const intent = p.intent;
-            const result = { status: "completed", ...this.#intent(intent) };
-            this.#sourceBook.set(Number(p.operationId), result);
+            const ticket = this.#intent(intent);
+            const operation = Number(p.operationId);
+            // A file this plugin's file resolver claims: pending until it answers.
+            if (intent.kind === "open" &&
+                this.#resolve(String(intent.source), intent.startPaused === true, operation) !== null) {
+                const pending = { status: "pending", ...ticket };
+                this.#sourceBook.set(operation, pending);
+                return pending;
+            }
+            const result = { status: "completed", ...ticket };
+            this.#sourceBook.set(operation, result);
             // Selecting a provider asks it to acknowledge a start control.
             const producer = this.producers.get(Number(intent.producerId));
             if (intent.kind === "openProvider" && producer) {
@@ -2706,9 +2899,12 @@ export class TestHost {
             return { jobId: job.jobId, cancel: "requested" };
         },
         "jobs.operation": () => ({ status: "unknown" }),
-        "sourceResolvers.register": (p) => void this.resolvers.set(String(p.id), p),
-        "sourceResolvers.unregister": (p) => void this.resolvers.delete(String(p.id)),
-        "sourceResolvers.respond": () => null,
+        "sourceResolvers.register": (p) => void this.#register(p),
+        "sourceResolvers.unregister": (p) => {
+            this.resolvers.delete(String(p.id));
+            this.#cancelResolutions();
+        },
+        "sourceResolvers.respond": (p) => this.#respond(p),
         "producer.prepare": async () => {
             const id = ++this.#next.producer;
             const tcp = this.producerTransport === "tcp";
@@ -2754,8 +2950,7 @@ export class TestHost {
                 });
                 socket.on("error", () => { });
                 socket.on("close", () => {
-                    if (this.source.kind === "producer" &&
-                        this.source.source === `producer://${producer.id}`)
+                    if (this.#current(producer.id))
                         producer.droppedWhileSelected = true;
                 });
             });
@@ -2786,8 +2981,7 @@ export class TestHost {
             const producer = this.producers.get(Number(p.producerId));
             if (!producer)
                 throw new HostError("missing", "producer");
-            const current = this.source.kind === "producer" &&
-                this.source.source === `producer://${producer.id}`;
+            const current = this.#current(producer.id);
             return {
                 input: null,
                 pendingControl: producer.pending,
@@ -2889,7 +3083,8 @@ export async function startPlugin(activate, options = {}) {
     mkdirSync(data, { recursive: true });
     const instance = await createPlugin(host, manifest, directory, data, host.app);
     await activate(instance.plugin);
-    // Like the player: a position another plugin holds is not an activation failure.
+    // Like the player: a position or resolver another plugin holds is not an
+    // activation failure.
     for (;;) {
         try {
             await instance.activated();

package/dist/plugin/types.d.ts

@@ -2771,7 +2771,12 @@ export interface PlayerState {
     readonly kind: "media" | "stream";
     /** The source's life cycle. */
     readonly phase: "empty" | "loading" | "ready" | "ended" | "error";
-    /** Path or URL. */
+    /**
+     * Path or URL; `null` when empty. A generated stream started with
+     * {@link Player.openStream} has the opaque `producer://<n>` (do not parse
+     * it); one a file resolver generates ({@link FileResolverOptions}) keeps
+     * the path that was opened. Tell streams apart by `kind`, not by `source`.
+     */
     readonly source: string | null;
     /** Playback is paused. */
     readonly paused: boolean;
@@ -3087,7 +3092,9 @@ export interface Player {
      *
      * It does not wait for playback: use {@link Media.ready}. `paused` opens
      * it paused; aborting `signal` closes it. URLs matching a registered
-     * {@link Resolver} are resolved first.
+     * {@link Resolver} are resolved first, and so are local files of an
+     * extension a file resolver claims (the source is then a stream that
+     * plugin generates; `paused` reaches it).
      */
     open(source: string, options?: {
         paused?: boolean;
@@ -3811,8 +3818,13 @@ export interface MediaCapture {
      */
     capture(options?: CaptureOptions): Promise<Snapshot>;
 }
-/** Declaration of {@link Resolvers.add}. */
-export interface ResolverOptions {
+/**
+ * Declaration of {@link Resolvers.add}: a web resolver
+ * ({@link WebResolverOptions}) or a file resolver ({@link FileResolverOptions}).
+ */
+export type ResolverOptions = WebResolverOptions | FileResolverOptions;
+/** A resolver for web pages: `https://host/…` to playable stream URLs. */
+export interface WebResolverOptions {
     /** Local id, unique within the plugin. */
     id: string;
     /** URL schemes handled. */
@@ -3822,14 +3834,104 @@ export interface ResolverOptions {
     /** Turn a page URL into playable stream URLs. */
     resolve(url: string, signal: AbortSignal): Promise<ResolvedMedia>;
 }
+/**
+ * A resolver for local files by extension (SDK 1.5.3, player 0.4.1): when
+ * anyone opens such a file with {@link Player.open} (the Open dialog, the
+ * playlist, next / previous, the recent list, a drop that calls `open`),
+ * the player asks this plugin for a stream it generates instead of
+ * playing the file. Needs `source.resolve` and `producer.av`.
+ *
+ * @remarks
+ * The open keeps everything of the original call: its `ifCurrent`, its
+ * operation (the opener's `open` and `media.ready()` settle as for any
+ * file), `paused` (the stream starts paused), and its path as
+ * `state.source`, with `state.kind` `"stream"`. A thrown error fails that
+ * open: `phase` `"error"` with the error's message as `state.error`,
+ * word for word. The stream belongs to this plugin, as with
+ * {@link Player.openStream}.
+ *
+ * Cancellation: `signal` aborts when the open is replaced, closed
+ * (`player.close()`, F4) or times out (30 seconds), or this resolver is
+ * disposed. Cancelled after `resolve` returned but before the stream ran,
+ * the SDK releases the stream and never calls `started`.
+ *
+ * One extension has one resolver: another plugin's resolver for it makes
+ * {@link Resolver.ready} reject with `conflict` without failing activation
+ * (the player shows a warning). When this plugin stops, its extensions are
+ * free again and such files go to the player as before.
+ *
+ * @example
+ * ```ts
+ * const { readFile } = await import("node:fs/promises");
+ * // The plugin's own emulator: one frame per call.
+ * const emulator = (rom: Uint8Array): (() => StreamFrame) => {
+ *   const video = new Uint8Array(256 * 240 * 4).fill(rom[0] ?? 0);
+ *   return () => ({ video, audio: new Float32Array(1600) });
+ * };
+ * plugin.resolvers.add({
+ *   id: "nes",
+ *   extensions: ["nes"],
+ *   async resolve(path, signal) {
+ *     const frame = emulator(await readFile(path, { signal }));
+ *     return {
+ *       kind: "stream",
+ *       width: 256,
+ *       height: 240,
+ *       frame,
+ *       started: (stream) => stream.onStop((error) => error && plugin.osd.show(error.message)),
+ *     };
+ *   },
+ * });
+ * ```
+ */
+export interface FileResolverOptions {
+    /** Local id, unique within the plugin. */
+    id: string;
+    /**
+     * Lower case, without the dot: 1–16 entries of 1–16 lower-case letters or
+     * digits (not `"folder"`). Only absolute local paths match, by their
+     * extension in any case (`/roms/Game.NES`); URLs never do.
+     */
+    extensions: string[];
+    /** Read the file and describe the stream to generate for it. */
+    resolve(path: string, signal: AbortSignal): Promise<ResolvedStream>;
+}
+/**
+ * What a file resolver returns: a stream, with the same frame contract as
+ * {@link StreamOptions} (size limits, `frame()` on the audio clock).
+ */
+export interface ResolvedStream {
+    /** Always `"stream"`. */
+    kind: "stream";
+    /** Frame width in pixels. */
+    width: number;
+    /** Frame height in pixels. */
+    height: number;
+    /** Produce the next frame. Never called concurrently or while paused. */
+    frame(): StreamFrame;
+    /**
+     * Called with the running stream once the player plays it, synchronously
+     * after activation and before any {@link Stream.onStop}. Not called when
+     * the open was cancelled first. `stream.stop()` closes the source (if
+     * still current); the plugin stopping stops it too.
+     */
+    started?(stream: Stream): void;
+}
 /** A registered resolver. Disposing it unregisters it and aborts resolutions in flight. */
 export interface Resolver extends Disposable {
-    /** Resolves when the player registered it; rejects (e.g. `conflict`) otherwise. */
+    /**
+     * Resolves when the player registered it; rejects otherwise: `conflict`
+     * when another resolver has the extension or the scheme + host (another
+     * plugin's: activation goes on; this plugin's own: activation fails),
+     * `invalid` for a malformed declaration (a player before 0.4.1 also for
+     * `extensions`).
+     */
     readonly ready: Promise<void>;
 }
 /**
- * `plugin.resolvers`: turn web page URLs into playable streams. Needs
- * `source.resolve`.
+ * `plugin.resolvers`: turn web page URLs into playable streams, or local
+ * files into streams this plugin generates. Needs `source.resolve` (file
+ * resolvers also `producer.av`).
  *
  * @example
  * ```ts
@@ -3846,9 +3948,11 @@ export interface Resolver extends Disposable {
  */
 export interface Resolvers {
     /**
-     * Register a resolver. When anyone opens a matching URL the player calls
-     * `resolve`; `signal` aborts when the open is cancelled or replaced. One
-     * scheme + host pair has one resolver (`conflict` otherwise).
+     * Register a resolver. When anyone opens a matching URL or file the
+     * player calls `resolve`; `signal` aborts when the open is cancelled or
+     * replaced. One scheme + host pair, and one extension, has one resolver
+     * (`conflict` otherwise). A rejected `resolve` fails the open with the
+     * error's message.
      */
     add(options: ResolverOptions): Resolver;
 }
@@ -4029,10 +4133,18 @@ export interface PluginInfo {
  * @since 1.5.2
  */
 export interface PluginWarning {
-    /** `"slot-occupied"` or `"sequence-taken"`; a newer player may add codes. */
+    /**
+     * `"slot-occupied"`, `"sequence-taken"` or `"resolver-taken"` (player
+     * 0.4.1); a newer player may add codes.
+     */
     code: string;
     /** The panel position (`"bottom"`, `"sidebar"`, `"backdrop"`) for `slot-occupied`. */
     slot?: string;
+    /**
+     * What was taken, for `resolver-taken`: 「文件类型 .nes」 or the
+     * `scheme://host` of a web resolver.
+     */
+    target?: string;
     /** The manifest id of the plugin holding it (absent for a full sidebar). */
     owner?: string;
 }

package/dist/source-resolvers.d.ts

@@ -8,7 +8,7 @@ export type ResolvedResource = {
     headers?: Record<string, string>;
 };
 /**
- * What a resolver returns ({@link ResolverOptions.resolve}): the playable
+ * What a resolver returns ({@link WebResolverOptions.resolve}): the playable
  * stream(s) behind a page URL. Both streams must use identical `headers`;
  * different maps fail explicitly (nothing is dropped silently).
  *
@@ -35,21 +35,48 @@ export type ResolvedMedia = {
     /** A separate audio stream, when audio and video are split. */
     audio?: ResolvedResource;
 };
+/**
+ * A resolver declaration on the wire: a web resolver (`schemes` + `hosts`)
+ * or, from player 0.4.1, a file resolver (`extensions`), never both.
+ */
 export type SourceResolverDeclaration = {
     id: string;
     /** Finite initial contract: http and/or https, exact normalized host names. */
     schemes: ("http" | "https")[];
     hosts: string[];
+} | {
+    id: string;
+    /** Local files by extension: 1–16, lower-case letters or digits, no dot. */
+    extensions: string[];
+};
+/**
+ * A file resolver's answer as the handler gives it: the producer it prepared
+ * (sent to the host), `accepted` once the host selected it (with the stamp of
+ * the source it became) and `abandoned` when it never will be: the request
+ * was cancelled or answered too late. Exactly one of the two is called.
+ */
+export type ResolvedProducer = {
+    kind: "stream";
+    producerId: number;
+    accepted(reply: {
+        stamp: {
+            generation: number;
+            intentVersion: number;
+        };
+    }): Promise<void>;
+    abandoned(): Promise<void>;
 };
 export declare function sourceResolverClient(transport: Transport): {
-    /** Requires source.resolve. One registered host/scheme pair has one owner.
-     * Resolution shares source.submit arbitration and the original operation ID.
-     * This backend supports paired streams with identical header maps; different
-     * maps fail explicitly. No header is silently discarded or made global. */
+    /** Requires source.resolve. One registered host/scheme pair, and one file
+     * extension, has one owner (another plugin: `conflict`, reason
+     * `resolver-taken`). Resolution shares source.submit arbitration and the
+     * original operation ID. This backend supports paired streams with
+     * identical header maps; different maps fail explicitly. No header is
+     * silently discarded or made global. A failure is sent as its message. */
     register(declaration: SourceResolverDeclaration, handler: (request: {
         url: string;
         signal: AbortSignal;
-    }) => Promise<ResolvedMedia>): Promise<{
+    }) => Promise<ResolvedMedia | ResolvedProducer>): Promise<{
         dispose(): Promise<void>;
     }>;
 };

package/dist/source-resolvers.js

@@ -1,9 +1,14 @@
+const isProducer = (result) => result?.kind === "stream";
+/** The words of a failure, as the user will read them. */
+const reason = (error) => (error instanceof Error ? error.message : String(error)).slice(0, 2048);
 export function sourceResolverClient(transport) {
     return {
-        /** Requires source.resolve. One registered host/scheme pair has one owner.
-         * Resolution shares source.submit arbitration and the original operation ID.
-         * This backend supports paired streams with identical header maps; different
-         * maps fail explicitly. No header is silently discarded or made global. */
+        /** Requires source.resolve. One registered host/scheme pair, and one file
+         * extension, has one owner (another plugin: `conflict`, reason
+         * `resolver-taken`). Resolution shares source.submit arbitration and the
+         * original operation ID. This backend supports paired streams with
+         * identical header maps; different maps fail explicitly. No header is
+         * silently discarded or made global. A failure is sent as its message. */
         async register(declaration, handler) {
             const active = new Map();
             let disposed = false;
@@ -13,33 +18,56 @@ export function sourceResolverClient(transport) {
                     return;
                 const controller = new AbortController();
                 active.set(request.requestId, controller);
+                const live = () => !controller.signal.aborted && !disposed;
                 void (async () => {
+                    let result;
                     try {
-                        const result = await handler({
+                        result = await handler({
                             url: request.url,
                             signal: controller.signal,
                         });
-                        if (!controller.signal.aborted && !disposed) {
-                            await transport.request("sourceResolvers.respond", {
-                                requestId: request.requestId,
-                                result,
-                            });
-                        }
                     }
                     catch (error) {
-                        if (!controller.signal.aborted && !disposed) {
+                        if (live())
                             await transport
                                 .request("sourceResolvers.respond", {
                                 requestId: request.requestId,
-                                error: String(error).slice(0, 2048),
+                                error: reason(error),
                             })
                                 .catch(() => { });
+                        active.delete(request.requestId);
+                        return;
+                    }
+                    try {
+                        if (!isProducer(result)) {
+                            if (live())
+                                await transport.request("sourceResolvers.respond", {
+                                    requestId: request.requestId,
+                                    result,
+                                });
+                            return;
+                        }
+                        if (!live())
+                            return void (await result.abandoned());
+                        let reply;
+                        try {
+                            // Answered: the host no longer cancels this request.
+                            active.delete(request.requestId);
+                            reply = await transport.request("sourceResolvers.respond", {
+                                requestId: request.requestId,
+                                result: { kind: "stream", producerId: result.producerId },
+                            });
+                        }
+                        catch (error) {
+                            await result.abandoned();
+                            throw error;
                         }
+                        await result.accepted(reply);
                     }
                     finally {
                         active.delete(request.requestId);
                     }
-                })();
+                })().catch(() => { });
             });
             const offCancel = transport.on("source.resolveCancel", (value) => {
                 const request = value;

package/dist/wire.d.ts

@@ -593,7 +593,7 @@ export declare function createWire(transport: Transport): {
         register(declaration: import("./source-resolvers.ts").SourceResolverDeclaration, handler: (request: {
             url: string;
             signal: AbortSignal;
-        }) => Promise<import("./source-resolvers.ts").ResolvedMedia>): Promise<{
+        }) => Promise<import("./source-resolvers.ts").ResolvedMedia | import("./source-resolvers.ts").ResolvedProducer>): Promise<{
             dispose(): Promise<void>;
         }>;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {