@vestra-player/sdk 1.5.6 → 1.5.8

package/dist/plugin/types.d.ts

@@ -73,9 +73,8 @@ export interface Disposable {
  * | `timeout` | A time limit ran out (`openStream` start-up, `tools.run`, `system.*` after 10 s). |
  * | `stream`, `device` | `openStream`: the producer failed / the audio device is not ready. |
  * | `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). |
+ * | `reserved` | {@link Packages.validate}, {@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. |
@@ -195,7 +194,7 @@ export interface Scope extends Disposable {
     readonly media: MediaCapture;
     /** Page-URL to stream-URL resolvers (`source.resolve`). */
     readonly resolvers: Resolvers;
-    /** The installed plugins; validation, trials, installs (`plugins.manage` for changes). */
+    /** The installed plugins; validation, installs (`plugins.manage` for changes). */
     readonly packages: Packages;
     /** On-screen messages over the video (`ui.osd`). */
     readonly osd: Osd;
@@ -320,8 +319,7 @@ export interface Plugin extends Scope {
     readonly id: string;
     /**
      * A writable directory for this plugin's own files (settings, remembered
-     * folders). Kept across restarts, disabling and upgrades; a trial gets a
-     * temporary one. Write files atomically: to a temporary name, then rename.
+     * folders). Kept across restarts, disabling and upgrades. Write files atomically: to a temporary name, then rename.
      * Throws `unavailable` when the player provided none.
      *
      * Location: `~/Library/Application Support/Vestra/plugin-data/<id>/` on
@@ -3002,9 +3000,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 +3151,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 +3942,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"`. */
@@ -3993,6 +4006,47 @@ export interface Resolvers {
      * error's message.
      */
     add(options: ResolverOptions): Resolver;
+    /**
+     * The extensions some plugin's file resolver handles (SDK 1.5.8, player
+     * 0.4.2): lower case, without the dot, sorted, each once; not who
+     * registered them. Reading needs no capability; `[]` from older players.
+     * Without `events` it is the list from when the plugin first read it.
+     * Use it to accept such files beside the player's own media types, for
+     * example in a playlist's drop or folder scan.
+     *
+     * @example
+     * ```ts
+     * const MEDIA = ["mp4", "mkv", "mp3"];
+     * const accepted = (path: string) => {
+     *   const extension = path.split(".").pop()?.toLowerCase() ?? "";
+     *   return MEDIA.includes(extension) || plugin.resolvers.fileTypes.includes(extension);
+     * };
+     * ```
+     *
+     * @capability None.
+     * @player 0.4.2
+     * @since 1.5.8
+     */
+    readonly fileTypes: readonly string[];
+    /**
+     * {@link Resolvers.fileTypes} changed: a file resolver was added, or its
+     * plugin stopped. Needs `events`; without it the listener never fires.
+     *
+     * @param listener - Receives the new list.
+     * @returns A handle that removes the listener.
+     *
+     * @example
+     * ```ts
+     * plugin.resolvers.onFileTypesChange((types) => {
+     *   void plugin.osd.show(`Also accepted: ${types.join(", ")}`);
+     * });
+     * ```
+     *
+     * @capability `events`
+     * @player 0.4.2
+     * @since 1.5.8
+     */
+    onFileTypesChange(listener: (types: string[]) => void): Disposable;
 }
 /**
  * The manifest of a package, as validated. The display fields and
@@ -4084,11 +4138,6 @@ export interface PackageCandidate {
     readonly manifest: PackageManifest;
     /** The checks the player ran. */
     readonly checks: string[];
-    /**
-     * 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;
@@ -4099,17 +4148,6 @@ export interface PackageCandidate {
      */
     install(options?: InstallOptions): Promise<PackageChange>;
 }
-/** A trial load of a package. Disposing it stops the trial and waits for cleanup. */
-export interface PackageTrial extends Disposable {
-    /** The trial's status as the player reports it. */
-    readonly status: string;
-    /**
-     * Stop and wait until the host confirmed cleanup. Rejects with code
-     * `cleanup` when the host stopped the trial without confirming cleanup;
-     * calling `stop()` again then asks the host again.
-     */
-    stop(): Promise<void>;
-}
 /** The progress of an install, rollback or uninstall. */
 export type PackageChangeStatus = "preparing" | "activating" | "restoring" | "committed" | "cancelled" | "failed" | "failedDegraded" | "tooLate";
 /**
@@ -4134,8 +4172,8 @@ export interface PluginInfo {
     id: string;
     /** Version, `null` when unknown. */
     version: string | null;
-    /** From the install library, a `--plugin` development load, or a trial. */
-    origin: "installed" | "development" | "trial";
+    /** From the install library, or a `--plugin` development load. */
+    origin: "installed" | "development";
     /** Run state. */
     state: "starting" | "running" | "disabled" | "failed" | "stopped";
     /** Why it failed (`state: "failed"`). */
@@ -4151,7 +4189,7 @@ export interface PluginInfo {
      * replaced. `false` from players before 0.2.0.
      */
     builtin: boolean;
-    /** Where an installed plugin came from; `null` for development loads and trials. */
+    /** Where an installed plugin came from; `null` for development loads. */
     source: PackageSource | null;
     /**
      * Its data directory (`plugin.dataDirectory` of that plugin); `null` when
@@ -4207,6 +4245,10 @@ export interface Packages {
      * 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).
+     *
+     * The player keeps the 32 most recent candidates of all plugins; an
+     * older one's `install` fails with `stale` (validate again). Before
+     * player 0.4.2 the 33rd validation of a run failed with `busy` instead.
      */
     validate(directory: string): Promise<PackageCandidate>;
     /**
@@ -4225,7 +4267,7 @@ export interface Packages {
     /**
      * Stop or start a plugin (`plugins.manage`). An installed plugin stays
      * disabled across launches; a development load only for this run.
-     * `invalid` to disable oneself, `unsupported` for a trial, `missing` unknown.
+     * `invalid` to disable oneself, `missing` unknown.
      * `busy` while it is being installed.
      */
     setEnabled(id: string, enabled: boolean): Promise<void>;
@@ -4233,7 +4275,7 @@ export interface Packages {
      * Remove an installed plugin (`plugins.manage`); `removeData` also deletes
      * its data directory, otherwise reinstalling it from the same source
      * reconnects to its data. Its user bindings stay (as orphans).
-     * `unsupported` for built-ins, development loads and trials, `missing`
+     * `unsupported` for built-ins and development loads, `missing`
      * unknown, `invalid` for oneself.
      */
     uninstall(id: string, options?: {

package/dist/plugin/window.d.ts

@@ -19,6 +19,8 @@ export declare class WindowService {
     start(): void;
     /** The palette, as the `window.state` reply carried it (`plugin.appearance`). */
     appearance: string | undefined;
+    /** The file resolvers' extensions, as the reply carried them (`plugin.resolvers.fileTypes`). */
+    fileTypes: string[] | undefined;
     accept(facts: WindowFacts): void;
     read(): Promise<void>;
     watch(listener: (state: WindowState) => void): {

package/dist/plugin/window.js

@@ -52,9 +52,13 @@ export class WindowService {
     }
     /** The palette, as the `window.state` reply carried it (`plugin.appearance`). */
     appearance;
+    /** The file resolvers' extensions, as the reply carried them (`plugin.resolvers.fileTypes`). */
+    fileTypes;
     accept(facts) {
         if (facts.appearance)
             this.appearance = facts.appearance;
+        if (Array.isArray(facts.fileTypes))
+            this.fileTypes = [...facts.fileTypes];
         const next = view(facts);
         if (JSON.stringify(next) === JSON.stringify(this.state))
             return;

package/dist/wire.d.ts

@@ -25,12 +25,6 @@ export interface PackageValidation {
     checks: string[];
     trustedExecution: true;
 }
-export interface PackageTrial {
-    trialId: number;
-    activationOwner?: number;
-    status: string;
-    cleanupConfirmed?: boolean;
-}
 export interface InstalledPackage {
     revision: number;
     current: null | {
@@ -102,7 +96,7 @@ export declare class HostError extends Error {
 export interface PackageInfo {
     id: string;
     version: string | null;
-    origin: "installed" | "development" | "trial";
+    origin: "installed" | "development";
     state: "starting" | "running" | "disabled" | "failed" | "stopped";
     error: string | null;
     capabilities: string[];
@@ -175,6 +169,8 @@ export interface WindowFacts {
     };
     /** The palette (`plugin.appearance`), with the `window.state` reply; a newer player may name a palette this SDK does not list. */
     appearance?: string;
+    /** The file resolvers' extensions (`plugin.resolvers.fileTypes`; player 0.4.2). */
+    fileTypes?: string[];
 }
 /** One timeline mark as the player merges them (`timeline.marks`). */
 export interface WireMark {
@@ -530,11 +526,6 @@ export declare function createWire(transport: Transport): {
         validate: (directory: string, apiVersion?: string) => Promise<PackageValidation>;
         /** Player 0.2.0: a `.vxp` file. */
         validateArchive: (file: string) => Promise<PackageValidation>;
-        /** `requestId` recovers a lost first reply in this owner session. */
-        trial: (token: string, requestId: string) => Promise<PackageTrial>;
-        trialStateByRequest: (requestId: string) => Promise<PackageTrial>;
-        trialState: (trialId: number) => Promise<PackageTrial>;
-        stopTrial: (trialId: number) => Promise<PackageTrial>;
         installed: (id: string) => Promise<InstalledPackage>;
         /** `source` and `replace` are sent only when given (player 0.2.0). */
         install: (token: string, expectedRevision: number, requestId: string, options?: {

package/dist/wire.js

@@ -258,16 +258,6 @@ export function createWire(transport) {
             validateArchive: (file) => transport.request("packages.validateArchive", {
                 file,
             }),
-            /** `requestId` recovers a lost first reply in this owner session. */
-            trial: (token, requestId) => transport.request("packages.trial", {
-                token,
-                requestId,
-            }),
-            trialStateByRequest: (requestId) => transport.request("packages.trialStateByRequest", {
-                requestId,
-            }),
-            trialState: (trialId) => transport.request("packages.trialState", { trialId }),
-            stopTrial: (trialId) => transport.request("packages.stopTrial", { trialId }),
             installed: (id) => transport.request("packages.installed", { id }),
             /** `source` and `replace` are sent only when given (player 0.2.0). */
             install: (token, expectedRevision, requestId, options = {}) => transport.request("packages.install", {

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.6: full reference
+# @vestra-player/sdk 1.5.8: 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.
 
@@ -124,7 +124,7 @@ A manifest with every field. `id`, `apiVersion`, `entry` and `capabilities` are
 }
 ```
 
-Unknown fields, unknown capabilities and paths that leave the package directory (including through symbolic links) are rejected. The id's characters are ASCII letters, digits, `.`, `-` and `_`; the official plugin repository additionally requires `<GitHub user or organization>.<plugin name>`. The `vestra.` prefix (and the id `vestra`, in any case) is reserved for the plugins built into the player: from player 0.4.1 the player refuses to install or trial such a package (`reserved`). Every other plugin is a third-party plugin, including those hosted in the official repository.
+Unknown fields, unknown capabilities and paths that leave the package directory (including through symbolic links) are rejected. The id's characters are ASCII letters, digits, `.`, `-` and `_`; the official plugin repository additionally requires `<GitHub user or organization>.<plugin name>`. The `vestra.` prefix (and the id `vestra`, in any case) is reserved for the plugins built into the player: from player 0.4.1 the player refuses to install such a package (`reserved`). Every other plugin is a third-party plugin, including those hosted in the official repository.
 
 | Capability                             | Opens                                                                                                   |
 | -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
@@ -998,9 +998,8 @@ change).
 | `timeout` | A time limit ran out (`openStream` start-up, `tools.run`, `system.*` after 10 s). |
 | `stream`, `device` | `openStream`: the producer failed / the audio device is not ready. |
 | `backend-uncertain` | The player's backend blocked a filter stage; call `retry()`. |
-| `cleanup` | PackageTrial.stop could not confirm cleanup; call it again. |
 | `limit` | A player-wide limit was reached (for example the number of commands). |
-| `reserved` | Packages.validate, PackageCandidate.trial, 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). |
+| `reserved` | Packages.validate, 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. |
@@ -1080,7 +1079,7 @@ interface Scope extends Disposable {
   readonly media: MediaCapture;
   /** Page-URL to stream-URL resolvers (`source.resolve`). */
   readonly resolvers: Resolvers;
-  /** The installed plugins; validation, trials, installs (`plugins.manage` for changes). */
+  /** The installed plugins; validation, installs (`plugins.manage` for changes). */
   readonly packages: Packages;
   /** On-screen messages over the video (`ui.osd`). */
   readonly osd: Osd;
@@ -1174,8 +1173,7 @@ interface Plugin extends Scope {
   readonly id: string;
   /**
    * A writable directory for this plugin's own files (settings, remembered
-   * folders). Kept across restarts, disabling and upgrades; a trial gets a
-   * temporary one. Write files atomically: to a temporary name, then rename.
+   * folders). Kept across restarts, disabling and upgrades. Write files atomically: to a temporary name, then rename.
    * Throws `unavailable` when the player provided none.
    *
    * Location: `~/Library/Application Support/Vestra/plugin-data/<id>/` on
@@ -2616,7 +2614,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 +2766,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 +3398,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"`. */
@@ -3431,6 +3448,20 @@ interface Resolvers {
    * 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;
+  /**
+   * The extensions some plugin's file resolver handles (SDK 1.5.8, player 0.4.2): lower case, without the dot, sorted, each once; not who registered them. Reading needs no capability; `[]` from older players. Without `events` it is the list from when the plugin first read it. Use it to accept such files beside the player's own media types, for example in a playlist's drop or folder scan.
+   * @capability None.
+   * @player 0.4.2
+   */
+  readonly fileTypes: readonly string[];
+  /**
+   * Resolvers.fileTypes changed: a file resolver was added, or its plugin stopped. Needs `events`; without it the listener never fires.
+   * @param listener - Receives the new list.
+   * @returns A handle that removes the listener.
+   * @capability `events`
+   * @player 0.4.2
+   */
+  onFileTypesChange(listener: (types: string[]) => void): Disposable;
 }
 ```
 
@@ -3536,8 +3567,6 @@ interface PackageCandidate {
   readonly manifest: PackageManifest;
   /** The checks the player ran. */
   readonly checks: string[];
-  /** 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). 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.
    */
@@ -3545,21 +3574,6 @@ interface PackageCandidate {
 }
 ```
 
-### PackageTrial
-
-A trial load of a package. Disposing it stops the trial and waits for cleanup.
-
-```ts
-interface PackageTrial extends Disposable {
-  /** The trial's status as the player reports it. */
-  readonly status: string;
-  /**
-   * Stop and wait until the host confirmed cleanup. Rejects with code `cleanup` when the host stopped the trial without confirming cleanup; calling `stop()` again then asks the host again.
-   */
-  stop(): Promise<void>;
-}
-```
-
 ### PackageChangeStatus
 
 The progress of an install, rollback or uninstall.
@@ -3598,8 +3612,8 @@ interface PluginInfo {
   id: string;
   /** Version, `null` when unknown. */
   version: string | null;
-  /** From the install library, a `--plugin` development load, or a trial. */
-  origin: "installed" | "development" | "trial";
+  /** From the install library, or a `--plugin` development load. */
+  origin: "installed" | "development";
   /** Run state. */
   state: "starting" | "running" | "disabled" | "failed" | "stopped";
   /** Why it failed (`state: "failed"`). */
@@ -3612,7 +3626,7 @@ interface PluginInfo {
   previousVersion: string | null;
   /** Shipped with the player: it can be disabled, not uninstalled or replaced. `false` from players before 0.2.0. */
   builtin: boolean;
-  /** Where an installed plugin came from; `null` for development loads and trials. */
+  /** Where an installed plugin came from; `null` for development loads. */
   source: PackageSource | null;
   /** Its data directory (`plugin.dataDirectory` of that plugin); `null` when the player has none. The path's layout is not part of the API. */
   dataDirectory: string | null;
@@ -3648,7 +3662,13 @@ need no capability; everything else needs `plugins.manage`.
 ```ts
 interface Packages {
   /**
-   * 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 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).
+   *
+   * The player keeps the 32 most recent candidates of all plugins; an
+   * older one's `install` fails with `stale` (validate again). Before
+   * player 0.4.2 the 33rd validation of a run failed with `busy` instead.
    */
   validate(directory: string): Promise<PackageCandidate>;
   /**
@@ -3662,11 +3682,11 @@ interface Packages {
   /** The new list after any start, stop, failure, install or uninstall. No capability. */
   onChange(listener: (plugins: PluginInfo[]) => void): Disposable;
   /**
-   * Stop or start a plugin (`plugins.manage`). An installed plugin stays disabled across launches; a development load only for this run. `invalid` to disable oneself, `unsupported` for a trial, `missing` unknown. `busy` while it is being installed.
+   * Stop or start a plugin (`plugins.manage`). An installed plugin stays disabled across launches; a development load only for this run. `invalid` to disable oneself, `missing` unknown. `busy` while it is being installed.
    */
   setEnabled(id: string, enabled: boolean): Promise<void>;
   /**
-   * Remove an installed plugin (`plugins.manage`); `removeData` also deletes its data directory, otherwise reinstalling it from the same source reconnects to its data. Its user bindings stay (as orphans). `unsupported` for built-ins, development loads and trials, `missing` unknown, `invalid` for oneself.
+   * Remove an installed plugin (`plugins.manage`); `removeData` also deletes its data directory, otherwise reinstalling it from the same source reconnects to its data. Its user bindings stay (as orphans). `unsupported` for built-ins and development loads, `missing` unknown, `invalid` for oneself.
    */
   uninstall(id: string, options?: {
     removeData?: boolean;
@@ -4260,6 +4280,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.
    */
@@ -4698,6 +4722,12 @@ class TestHost implements Transport {
     /** Exact host names it resolves (a web resolver), with `schemes`. */
     hosts?: string[];
   }[];
+  /** What `plugin.resolvers.fileTypes` reports: the extensions of this plugin's file resolvers and of TestHost.otherResolvers, sorted, each once. */
+  fileTypes(): string[];
+  /**
+   * Push `resolvers.fileTypes` when TestHost.fileTypes changed: called after this plugin's resolvers come and go; call it yourself after changing TestHost.otherResolvers (another plugin started or stopped).
+   */
+  updateFileTypes(): void;
   /**
    * File opens waiting for this plugin's file resolver (`extensions`), by request id: the path and how it was opened. Opening a matching path (`player.open`, 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.
    */
@@ -4854,6 +4884,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.
    */
@@ -4876,7 +4912,7 @@ class TestHost implements Transport {
     /** Its version, `null` when unknown. */
     version: string | null;
     /** Where it was loaded from. */
-    origin: "installed" | "development" | "trial";
+    origin: "installed" | "development";
     /** Its run state. */
     state: "starting" | "running" | "disabled" | "failed" | "stopped";
     /** Why it failed (`state: "failed"`). */
@@ -5030,7 +5066,7 @@ own sensible display cap well below `perPlugin`.
 
 ```ts
 const COMMAND_LIMITS: {
-  /** Commands one plugin instance may have at the same time (160). A trial package is its own instance. */
+  /** Commands one plugin instance may have at the same time (160). */
   readonly perPlugin: 160;
   /** Commands of every plugin plus the player's own, together (1024). */
   readonly total: 1024;

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.8: 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**
 
@@ -136,7 +136,7 @@ test("shows the position", async () => {
 - `aborted`: An `AbortSignal` fired
 - `timeout`: A time limit ran out
 - `limit`: A player-wide limit was reached
-- `reserved`: Packages.validate, PackageCandidate.trial, PackageCandidate.install: the id is `vestra` or starts with `vestra.`, which only the player's built-in plugins use
+- `reserved`: Packages.validate, PackageCandidate.install: the id is `vestra` or starts with `vestra.`, which only the player's built-in plugins use
 - `versionMismatch`: The package needs a newer player or another `apiVersion`
 - `ui-prepare`: The player could not prepare a mounted panel or a settings page
 - `ui`: The player could not apply a property to a tool window or a settings page, or could not build the Options window
@@ -150,54 +150,54 @@ 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–4173
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html) (TestHost, startPlugin): L4174–5120
 
 ## API
 
 Where each module of `plugin` is declared:
 
-- Plugin L1152, Scope L1023, PluginError L974, Disposable L947
-- plugin.commands: Commands L1349
-- 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.window: MainWindow L2128
-- plugin.app: App L2209
-- plugin.bindings: Bindings L3720
-- plugin.ui: Ui L1441
-- plugin.timeline: Timeline L2085
-- plugin.drops: Drops L1851
-- plugin.appearance: Appearance L1880
-- plugin.settings: Settings L1938
+- Plugin L1151, Scope L1022, PluginError L974, Disposable L947
+- plugin.commands: Commands L1347
+- plugin.windows: Windows L1552
+- plugin.panels: Panels L2003
+- plugin.dialogs: Dialogs L2285
+- plugin.player: Player L2724
+- plugin.video: VideoFilter L2973, VideoView L3036, RenderOptions L3078
+- plugin.audio: AudioFilter L2997
+- plugin.subtitles: Subtitles L3176
+- plugin.media: MediaCapture L3334
+- plugin.resolvers: Resolvers L3439
+- plugin.packages: Packages L3657
+- plugin.osd: Osd L2910
+- plugin.host: Host L2873
+- plugin.clipboard: Clipboard L3770
+- plugin.power: Power L3790
+- plugin.tools: Tools L3823
+- plugin.storage: Storage L3866
+- plugin.system: System L3889
+- plugin.secrets: Secrets L3907
+- plugin.window: MainWindow L2126
+- plugin.app: App L2207
+- plugin.bindings: Bindings L3740
+- plugin.ui: Ui L1439
+- plugin.timeline: Timeline L2083
+- plugin.drops: Drops L1849
+- plugin.appearance: Appearance L1878
+- plugin.settings: Settings L1936
 
 ## Examples
 
 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. L5534–5623
+- blur: A tool window with one slider that blurs the playing video. L5624–5885
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L5886–6218
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L6219–6403
+- panel-menu: A sidebar panel with its own right-click menu. L6404–6609
+- menus: Radio menu items, separator groups and a menu item whose title changes. L6610–6769
+- theme-widgets: A tool window drawn with the player's theme and widgets. L6770–6933
+- markdown: A window that shows a Markdown document. L6934–7127
 
 ## Optional
 

package/package.json

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