@vestra-player/sdk 1.5.1 → 1.5.3

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # 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).
+
+- **Several sidebar panels.** A plugin mounting in the sidebar while another plugin's panel is there no longer fails: its `ready` resolves and the panel is a second tab. The player draws a 31px tab strip (the playlist's) above the current tab while there are two or more; with one panel nothing changes. Shown, hidden and floating apply to the whole sidebar. Tabs are labelled with the mount's `title` (else the plugin's name); built-in plugins' tabs come first, the playlist's is the first.
+- **`Panel.state`** (`PanelState`: `active`, `preferred`, `effective`, `reason`, `detached`) and **`Panel.onChange`**: the panel's own state. A panel in a background tab has `active: false`, `effective: false` and `reason: "otherTab"`. Older players report the position's state with `active: true`.
+- **`Panel.show()`** makes the panel's tab current and shows the sidebar; **`Panel.toggle()`** hides the sidebar when the panel's tab is shown, otherwise shows it (a background tab comes forward). Use them for a "Show my panel" command: `checked: () => !!list.state?.preferred && !!list.state?.active`. Older players: `setVisible(true)` / `toggle()` of the position.
+- **`PanelSlot.panels`** (`SlotPanel[]`: `plugin`, `title`, `active`) lists a position's tabs, `null` from older players; `PanelSlot.onChange` also runs when only the tabs change. **`PanelSlot.activate(plugin)`** switches the current tab (older players ignore it). `SlotState` is unchanged.
+- **The `tabbed` property.** If a sidebar panel's bridge global declares `in property <bool> tabbed`, the player sets it to `true` while it draws its tab strip, so a panel with a tab strip of its own (the playlist) hides it. Drop coordinates (`Panel.onDrop`) start below the strip.
+- **`Panel.showMenu`** in a background tab rejects with `unavailable`.
+- **Taken positions** (player 0.4.x after 0.4.0, documented now): the bottom bar and the backdrop take one panel; another plugin's mount there rejects `ready` with `conflict` (「底栏已被 vestra.playback 使用」), as does a ninth sidebar tab. This refusal, and `conflict` from `player.provideSequence` while another plugin provides next/previous, do not fail activation in the player: the plugin runs without its panel or sequence. Players 0.4.0 and older answered a taken bottom bar or sidebar with `ui-prepare` and failed the activation.
+- **`PluginInfo.warnings`** (`PluginWarning`: `code` `"slot-occupied"` or `"sequence-taken"`, `slot`, `owner`): what a running plugin was refused because another plugin holds it. Empty from older players.
+- **`TestHost`** models both: `host.mountOther(slot, plugin, { title })` and `host.unmountOther(plugin)` simulate another plugin's panel (a sidebar tab, or a taken bottom bar or backdrop: the plugin's mount then rejects with `conflict`), `host.selectTab(plugin)` the user clicking a tab; `host.layout.sidebar.panels` / `.owner` are the tabs and the current one, `layout.set` takes `active`. `startPlugin` does not fail on a taken position, like the player.
+- Examples: panel-menu no longer asks you not to load it with the playlist; it is a second tab there. Its list ends in a stretching filler: without it the rows' fixed heights capped the player's main window at its minimum height.
+
 ## 1.5.1
 
 Fix; no API or type changes.

package/dist/plugin/packages.js

@@ -220,4 +220,9 @@ const info = (plugin) => Object.freeze({
     builtin: plugin.builtin === true,
     source: plugin.source ? Object.freeze({ ...plugin.source }) : null,
     dataDirectory: plugin.dataDirectory ?? null,
+    warnings: Object.freeze((plugin.warnings ?? []).map((warning) => Object.freeze({
+        code: warning.code,
+        ...(warning.slot === undefined ? {} : { slot: warning.slot }),
+        ...(warning.owner === undefined ? {} : { owner: warning.owner }),
+    }))),
 });

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

@@ -238,9 +238,16 @@ export declare class TestHost implements Transport {
      * ```
      */
     readonly layout: {
-        /** The bottom bar position: `preferred`, `effective`, `reason`, `detached`. */
+        /**
+         * The bottom bar position: `preferred`, `effective`, `reason`,
+         * `detached`, `owner` and `panels` (its one panel).
+         */
         bottom: LayoutSlot | null;
-        /** The sidebar position: `preferred`, `effective`, `reason`, `detached`. */
+        /**
+         * The sidebar position: `preferred`, `effective`, `reason`, `detached`;
+         * `panels` are its tabs in order (`{ owner, plugin, title }`), `owner`
+         * the current tab's (the plugin under test is owner 1).
+         */
         sidebar: LayoutSlot | null;
     };
     /** Every `osd.show` text, newest last. */
@@ -554,6 +561,46 @@ export declare class TestHost implements Transport {
      * appeared; `true`: there is none again); pushed to the plugin.
      */
     setBackdropEffective(effective: boolean): void;
+    /**
+     * Simulate another plugin mounting a panel, before or after the plugin
+     * under test, as the player handles it: in the sidebar it is another tab
+     * (after the existing ones; the first panel's tab is current); the bottom
+     * bar and the backdrop take one panel, so the plugin's own mount there
+     * then rejects with `conflict` (not an activation failure, as in the
+     * player). Pushed as a `window.state` change.
+     *
+     * @param slot - The position.
+     * @param plugin - The other plugin's manifest id.
+     * @param options - `title`: its tab label (default: `plugin`).
+     *
+     * @example The playlist next to this plugin's sidebar panel
+     * ```ts
+     * const host = new TestHost();
+     * host.mountOther("sidebar", "vestra.playlist", { title: "播放列表" });
+     * const { plugin } = await startPlugin(activate, { host, directory });
+     * assert.equal(host.layout.sidebar?.panels?.length, 2);
+     * ```
+     *
+     * @since 1.5.2
+     */
+    mountOther(slot: "bottom" | "sidebar" | "backdrop", plugin: string, options?: {
+        title?: string;
+    }): void;
+    /**
+     * Simulate another plugin's panel going away ({@link TestHost.mountOther}):
+     * when its tab was current, the next tab (else the previous one) is.
+     *
+     * @since 1.5.2
+     */
+    unmountOther(plugin: string): void;
+    /**
+     * Simulate the user clicking a sidebar tab: `plugin`'s panel (the plugin
+     * under test's `manifestId`, or one of {@link TestHost.mountOther})
+     * becomes the current tab. Pushed as a `window.state` change.
+     *
+     * @since 1.5.2
+     */
+    selectTab(plugin: string): void;
     /**
      * The display layer (`plugin.video.view()`): who owns it (this plugin is
      * `manifestId`) and the values the player holds.
@@ -697,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