@vestra-player/sdk 1.5.1 → 1.5.3

package/dist/source-resolvers.d.ts

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

package/dist/source-resolvers.js

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

package/dist/wire.d.ts

@@ -112,6 +112,12 @@ export interface PackageInfo {
     builtin?: boolean;
     source?: WireSource | null;
     dataDirectory?: string | null;
+    /** What the plugin was refused because another plugin holds it (player 0.4.x, after 0.4.0). */
+    warnings?: {
+        code: string;
+        slot?: string;
+        owner?: string;
+    }[];
 }
 /** Where an installed package came from (`packages.install` `source`). */
 export type WireSource = {
@@ -182,13 +188,24 @@ export interface LayoutBackdrop {
     owner: number;
     effective: boolean;
 }
+/** One panel of a position, in tab order (`LayoutSlot.panels`). */
+export interface LayoutPanel {
+    owner: number;
+    /** The manifest id of the plugin that mounted it. */
+    plugin: string;
+    /** The tab label: the mount's `title`, else the plugin's name. */
+    title: string;
+}
 /** One position (bottom bar or sidebar) as `layout.state` reports it. */
 export interface LayoutSlot {
+    /** The current tab's panel (the only panel of the bottom bar). */
     owner: number;
     preferred: boolean;
     effective: boolean;
     reason: "userHidden" | "space" | "fullscreen" | "idle" | null;
     detached: boolean;
+    /** The position's panels in tab order; absent from players without sidebar tabs (0.4.0 and older). */
+    panels?: LayoutPanel[];
 }
 export interface PlaybackStats {
     backend: string;
@@ -470,6 +487,8 @@ export declare function createWire(transport: Transport): {
             slot: "bottom" | "sidebar";
             visible?: boolean;
             detached?: boolean;
+            /** The plugin id of the panel whose tab becomes the current one. */
+            active?: string;
         }) => Promise<void>;
     };
     events: {
@@ -574,7 +593,7 @@ export declare function createWire(transport: Transport): {
         register(declaration: import("./source-resolvers.ts").SourceResolverDeclaration, handler: (request: {
             url: string;
             signal: AbortSignal;
-        }) => Promise<import("./source-resolvers.ts").ResolvedMedia>): Promise<{
+        }) => Promise<import("./source-resolvers.ts").ResolvedMedia | import("./source-resolvers.ts").ResolvedProducer>): Promise<{
             dispose(): Promise<void>;
         }>;
     };

package/package.json

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