@vestra-player/sdk 1.5.4 → 1.5.7

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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.)
+
+- **`llms.txt` and `llms-full.txt`** ([llmstxt.org](https://llmstxt.org)) in the package, exported as `@vestra-player/sdk/llms.txt` and `@vestra-player/sdk/llms-full.txt` (in `node_modules/@vestra-player/sdk/`), and on the documentation site (`https://vestrasys.github.io/vestra-player-sdk/llms.txt`). For Vestra Player AI and other assistants that write plugins.
+  - `llms.txt` (about 10 KB): what a plugin is, the rules, the folder layout, a manifest with every field and the manifest limits, `activate`, every capability, a `TestHost` test, the command line, the common error codes, and the line numbers of each topic in the full file.
+  - `llms-full.txt` (about 300 KB): the guides (Getting started, the UI concept page, both how-tos), every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its description and its `@capability`, `@player`, `@param`, `@returns`, `@throws` and `@deprecated` tags, the internal types the API refers to, and each example's README, walkthrough and complete source (TypeScript, Slint, tests).
+  - Generated from the sources by `npm run docs:llms` (`scripts/llms.mjs`); CI fails when the committed files are stale.
+- **Getting started**: a "Rules for plugins" section (only the public SDK, `import type`, no other plugins, no system commands, macOS and Windows, your own id) and a manifest with every field.
+- `scripts/check-pack.mjs` allows the two files and checks that they name the package version; the install smoke test resolves both exports.
+
+## 1.5.5
+
+**Reserved `vestra.` ids** (player 0.4.1). Documentation only; no API change, `apiVersion` stays `vestra/1`.
+
+- Only the plugins built into the player are official plugins; the ids `vestra` and `vestra.*` (any case) are reserved for them. Every other plugin is a third-party plugin, including those hosted in the official plugin repository, and uses `<GitHub user or organization>.<plugin name>`.
+- `PluginError` lists the code `reserved`: `packages.validate`, `packages.validateArchive`, `PackageCandidate.trial` and `PackageCandidate.install` refuse a package with a reserved id. Development loads (`vestra-player --plugin DIR`) still accept one, with a warning, so built-in plugins can be developed; they are never installed.
 ## 1.5.4
 
 **Markdown in list rows** (the player after 0.4.0). Additive; `apiVersion` stays `vestra/1`, and plugins written for 1.5.3 need no change.

package/README.md

@@ -12,7 +12,8 @@
   <a href="https://vestrasys.github.io/vestra-player-sdk/">Documentation</a> ·
   <a href="https://vestrasys.github.io/vestra-player-sdk/documents/Getting_started.html">Getting started</a> ·
   <a href="https://github.com/vestrasys/vestra-player-sdk/tree/main/examples">Examples</a> ·
-  <a href="https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md">Changelog</a>
+  <a href="https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md">Changelog</a> ·
+  <a href="https://vestrasys.github.io/vestra-player-sdk/llms.txt">llms.txt</a>
 </p>
 ## Features
 
@@ -21,6 +22,7 @@
 - **Tests without the player**: `@vestra-player/sdk/testing` runs your plugin against an in-memory host with `node --test`.
 - **One command line tool**, `vestra-plugin`, to check, test, build and pack a `.vxp` package.
 - **The same API on macOS and Windows**; every plugin runs in its own Node.js 26 process that the player ships.
+- **A reference for AI assistants**: [`llms.txt`](https://vestrasys.github.io/vestra-player-sdk/llms.txt) (short index) and [`llms-full.txt`](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt) (every declaration, the guides and the examples), also in the package as `@vestra-player/sdk/llms.txt` and `@vestra-player/sdk/llms-full.txt`.
 
 ## Install
 

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

@@ -75,6 +75,7 @@ export interface Disposable {
  * | `backend-uncertain` | The player's backend blocked a filter stage; call `retry()`. |
  * | `cleanup` | {@link PackageTrial.stop} could not confirm cleanup; call it again. |
  * | `limit` | A player-wide limit was reached (for example the number of commands). |
+ * | `reserved` | {@link Packages.validate}, {@link PackageCandidate.trial}, {@link PackageCandidate.install}: the id is `vestra` or starts with `vestra.` (any case), which only the player's built-in plugins use (player 0.4.1). |
  * | `versionMismatch` | The package needs a newer player (`minPlayerVersion`) or another `apiVersion`. |
  * | `ui-prepare` | The player could not prepare a mounted panel or a settings page (its Slint file does not compile, a bound property is not declared, or another plugin's panel holds the slot); `message` has the diagnostics. |
  * | `ui` | The player could not apply a property to a tool window or a settings page, or could not build the Options window (a property the Slint file does not declare, a value of the wrong type); `message` has Slint's reason. |
@@ -3001,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;
     /**
@@ -3146,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
@@ -3936,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"`. */
@@ -4083,13 +4099,18 @@ export interface PackageCandidate {
     readonly manifest: PackageManifest;
     /** The checks the player ran. */
     readonly checks: string[];
-    /** Load it temporarily alongside the installed plugins. */
+    /**
+     * Load it temporarily alongside the installed plugins. A reserved id
+     * (`vestra.*`) fails with `reserved`.
+     */
     trial(): Promise<PackageTrial>;
     /**
      * Install it. The same source upgrades the installed plugin (its data
      * stays); another source fails with `conflict` unless `replace` is set;
      * a built-in id fails with `unsupported` (built-ins update with the
-     * player).
+     * player). A reserved id (`vestra` or `vestra.*`, which every built-in
+     * uses) fails with `reserved` (player 0.4.1; already when validated), as
+     * only the player installs built-in plugins.
      */
     install(options?: InstallOptions): Promise<PackageChange>;
 }
@@ -4197,12 +4218,17 @@ export interface PluginWarning {
  * ```
  */
 export interface Packages {
-    /** Validate a package directory (`plugins.manage`). */
+    /**
+     * Validate a package directory (`plugins.manage`). A package whose id is
+     * reserved for the built-in plugins (`vestra` or `vestra.*`) fails with
+     * `reserved` (player 0.4.1).
+     */
     validate(directory: string): Promise<PackageCandidate>;
     /**
      * Validate a `.vxp` package file (`plugins.manage`, player 0.2.0): the
      * same checks as {@link Packages.validate} after unpacking. Check the
-     * file's sha256 yourself before calling when you know it.
+     * file's sha256 yourself before calling when you know it. A reserved id
+     * fails with `reserved`, as in {@link Packages.validate}.
      */
     validateArchive(file: string): Promise<PackageCandidate>;
     /** Restore a plugin's previous version (`plugins.manage`). */