@vestra-player/sdk 1.5.6 → 1.5.7

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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/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
@@ -1025,6 +1032,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

package/dist/plugin/testing.js

@@ -1385,6 +1385,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 +1746,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 +1777,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 +1890,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;
@@ -2922,6 +2960,7 @@ export class TestHost {
                 receivedFrames: 0,
                 videoFrames: 0,
                 released: false,
+                retired: false,
                 droppedWhileSelected: false,
                 path,
                 admitted: !tcp,
@@ -2988,6 +3027,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 +3058,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);

package/dist/plugin/types.d.ts

@@ -3002,9 +3002,15 @@ export interface Stream extends Disposable {
     /**
      * The stream stopped for a reason outside this plugin: `error` is null when
      * another source replaced it or the user closed it, otherwise the failure
-     * (`stream`, `invalid` for a bad frame, …). Not called when the plugin
-     * itself stops it (`stop()`, `dispose()`, deactivation): the promise of
-     * `stop()` is that notification.
+     * (`stream` with the player's text, `invalid` for a bad frame, …). Not
+     * called when the plugin itself stops it (`stop()`, `dispose()`,
+     * deactivation): the promise of `stop()` is that notification.
+     *
+     * The player retires a stream's producer as soon as it is replaced or
+     * closed; the SDK reads the player's state to tell that from a failure
+     * (before 1.5.7 a replaced or closed stream could get `unavailable`
+     * "producer absent"). Without `playback.read` a failure the SDK has not
+     * seen yet is reported as null.
      */
     onStop(listener: (error: PluginError | null) => void): Disposable;
     /**
@@ -3147,7 +3153,8 @@ export interface Player {
      * activation, pausing and acknowledgement. Frames travel over a local
      * connection the SDK sets up: a Unix socket on macOS and Linux, loopback
      * TCP with a token on Windows. Rejects with a {@link StreamStartError}
-     * (`timeout`), `stream` or `device`.
+     * (`timeout`), `stream`, `device`, or `replaced` when another source
+     * replaced it (or it was closed) before it ran.
      *
      * @example
      * ```ts
@@ -3937,6 +3944,14 @@ export interface FileResolverOptions {
 /**
  * What a file resolver returns: a stream, with the same frame contract as
  * {@link StreamOptions} (size limits, `frame()` on the audio clock).
+ *
+ * After `resolve` returns, the SDK starts the stream while the open waits.
+ * If that fails, the open fails with the player's words instead of the
+ * SDK's (the detail goes to the log): `device` "音频输出设备不可用",
+ * `timeout` "启动超时", `busy` "播放器正忙，请稍后重试", other start-up
+ * failures "无法启动播放". An error thrown by `frame()` keeps its message.
+ * To give your own text for a file you can tell is unusable (a bad header),
+ * check it in `resolve` and throw there.
  */
 export interface ResolvedStream {
     /** Always `"stream"`. */

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.6: full reference
+# @vestra-player/sdk 1.5.7: full reference
 
 > Everything needed to write a Vestra Player plugin (plugin API `vestra/1`): the guides, every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its documentation, and the complete source of the example plugins. Generated from the SDK's sources by scripts/llms.mjs; the short index is llms.txt.
 
@@ -2616,7 +2616,17 @@ interface Stream extends Disposable {
   /** The stream is producing frames. */
   readonly running: boolean;
   /**
-   * The stream stopped for a reason outside this plugin: `error` is null when another source replaced it or the user closed it, otherwise the failure (`stream`, `invalid` for a bad frame, …). Not called when the plugin itself stops it (`stop()`, `dispose()`, deactivation): the promise of `stop()` is that notification.
+   * The stream stopped for a reason outside this plugin: `error` is null when
+   * another source replaced it or the user closed it, otherwise the failure
+   * (`stream` with the player's text, `invalid` for a bad frame, …). Not
+   * called when the plugin itself stops it (`stop()`, `dispose()`,
+   * deactivation): the promise of `stop()` is that notification.
+   *
+   * The player retires a stream's producer as soon as it is replaced or
+   * closed; the SDK reads the player's state to tell that from a failure
+   * (before 1.5.7 a replaced or closed stream could get `unavailable`
+   * "producer absent"). Without `playback.read` a failure the SDK has not
+   * seen yet is reported as null.
    */
   onStop(listener: (error: PluginError | null) => void): Disposable;
   /**
@@ -2758,7 +2768,8 @@ interface Player {
    * activation, pausing and acknowledgement. Frames travel over a local
    * connection the SDK sets up: a Unix socket on macOS and Linux, loopback
    * TCP with a token on Windows. Rejects with a StreamStartError
-   * (`timeout`), `stream` or `device`.
+   * (`timeout`), `stream`, `device`, or `replaced` when another source
+   * replaced it (or it was closed) before it ran.
    */
   openStream(options: StreamOptions): Promise<Stream>;
   /** Pause or resume. */
@@ -3389,6 +3400,14 @@ interface FileResolverOptions {
 What a file resolver returns: a stream, with the same frame contract as
 StreamOptions (size limits, `frame()` on the audio clock).
 
+After `resolve` returns, the SDK starts the stream while the open waits.
+If that fails, the open fails with the player's words instead of the
+SDK's (the detail goes to the log): `device` "音频输出设备不可用",
+`timeout` "启动超时", `busy` "播放器正忙，请稍后重试", other start-up
+failures "无法启动播放". An error thrown by `frame()` keeps its message.
+To give your own text for a file you can tell is unusable (a bad header),
+check it in `resolve` and throw there.
+
 ```ts
 interface ResolvedStream {
   /** Always `"stream"`. */
@@ -4260,6 +4279,10 @@ 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 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 ("producer transport closed"). `stop()` closes the source first.
    */
@@ -4854,6 +4877,12 @@ class TestHost implements Transport {
    * @param phase - The phase to end in (default `"ready"`).
    */
   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 TestHost.producers.
+   * @param message - The player's failure text.
+   */
+  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 conflict. Resolves after the command ran; rejects when nothing is bound or the command is disabled or busy. Bindings use the reference syntax (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`); the player's core actions match first, and user overrides in `bindings.overlay` apply.
    */

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.6: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. llms-full.txt, next to this file, has every declaration, the guides and the examples; L<n> below are its line numbers.
+> @vestra-player/sdk 1.5.7: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. llms-full.txt, next to this file, has every declaration, the guides and the examples; L<n> below are its line numbers.
 
 **How plugins run**
 
@@ -150,8 +150,8 @@ test("shows the position", async () => {
 - [Concept: Windows, panels, settings pages, dialogs and the OSD](https://vestrasys.github.io/vestra-player-sdk/documents/Windows__panels__settings_pages__dialogs_and_the_OSD.html): L281–626
 - [How-to: Keep a slider responsive while dragging](https://vestrasys.github.io/vestra-player-sdk/documents/Keep_a_slider_responsive_while_dragging.html): L627–801
 - [How-to: Remember a window's state between runs](https://vestrasys.github.io/vestra-player-sdk/documents/Remember_a_window_s_state_between_runs.html): L802–931
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L932–4153
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html) (TestHost, startPlugin): L4154–5084
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L932–4172
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html) (TestHost, startPlugin): L4173–5113
 
 ## API
 
@@ -162,24 +162,24 @@ Where each module of `plugin` is declared:
 - plugin.windows: Windows L1554
 - plugin.panels: Panels L2005
 - plugin.dialogs: Dialogs L2287
-- plugin.player: Player L2716
-- plugin.video: VideoFilter L2964, VideoView L3027, RenderOptions L3069
-- plugin.audio: AudioFilter L2988
-- plugin.subtitles: Subtitles L3167
-- plugin.media: MediaCapture L3325
-- plugin.resolvers: Resolvers L3422
-- plugin.packages: Packages L3643
-- plugin.osd: Osd L2901
-- plugin.host: Host L2864
-- plugin.clipboard: Clipboard L3750
-- plugin.power: Power L3770
-- plugin.tools: Tools L3803
-- plugin.storage: Storage L3846
-- plugin.system: System L3869
-- plugin.secrets: Secrets L3887
+- plugin.player: Player L2726
+- plugin.video: VideoFilter L2975, VideoView L3038, RenderOptions L3080
+- plugin.audio: AudioFilter L2999
+- plugin.subtitles: Subtitles L3178
+- plugin.media: MediaCapture L3336
+- plugin.resolvers: Resolvers L3441
+- plugin.packages: Packages L3662
+- plugin.osd: Osd L2912
+- plugin.host: Host L2875
+- plugin.clipboard: Clipboard L3769
+- plugin.power: Power L3789
+- plugin.tools: Tools L3822
+- plugin.storage: Storage L3865
+- plugin.system: System L3888
+- plugin.secrets: Secrets L3906
 - plugin.window: MainWindow L2128
 - plugin.app: App L2209
-- plugin.bindings: Bindings L3720
+- plugin.bindings: Bindings L3739
 - plugin.ui: Ui L1441
 - plugin.timeline: Timeline L2085
 - plugin.drops: Drops L1851
@@ -190,14 +190,14 @@ Where each module of `plugin` is declared:
 
 Complete plugins with tests, in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples) and in llms-full.txt:
 
-- hello: The README Quick start: one menu command and an on-screen message. L5498–5587
-- blur: A tool window with one slider that blurs the playing video. L5588–5849
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L5850–6182
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L6183–6367
-- panel-menu: A sidebar panel with its own right-click menu. L6368–6573
-- menus: Radio menu items, separator groups and a menu item whose title changes. L6574–6733
-- theme-widgets: A tool window drawn with the player's theme and widgets. L6734–6897
-- markdown: A window that shows a Markdown document. L6898–7091
+- hello: The README Quick start: one menu command and an on-screen message. L5527–5616
+- blur: A tool window with one slider that blurs the playing video. L5617–5878
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L5879–6211
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L6212–6396
+- panel-menu: A sidebar panel with its own right-click menu. L6397–6602
+- menus: Radio menu items, separator groups and a menu item whose title changes. L6603–6762
+- theme-widgets: A tool window drawn with the player's theme and widgets. L6763–6926
+- markdown: A window that shows a Markdown document. L6927–7120
 
 ## Optional
 

package/package.json

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