@vestra-player/sdk 1.5.1 → 1.5.3

package/dist/plugin/testing.js

@@ -61,7 +61,7 @@ import { mkdirSync, mkdtempSync, rmSync, statSync } from "node:fs";
 import { createServer } from "node:net";
 import { randomBytes } from "node:crypto";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { extname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { HostError } from "../wire.js";
 import { COMMAND_LIMITS, MENU_IDS } from "../commands.js";
@@ -110,6 +110,23 @@ const readyCapabilities = {
     close: true,
     snapshotSource: true,
 };
+/**
+ * Refusals for a position or resolver another plugin holds: not activation
+ * failures (`startPlugin`).
+ */
+const takenErrors = new WeakSet();
+const taken = (message) => {
+    const error = new HostError("conflict", message);
+    takenErrors.add(error);
+    return error;
+};
+const SLOT_LABELS = {
+    bottom: "底栏",
+    sidebar: "侧栏",
+    backdrop: "视频背景",
+};
+/** The player's limit of sidebar tabs. */
+const MAX_SIDEBAR_TABS = 8;
 /**
  * An in-memory fake Vestra Player for plugin tests.
  *
@@ -531,6 +548,109 @@ export class TestHost {
             this.backdrop.effective = effective;
         this.emit("window.state", this.#windowFacts());
     }
+    #nextOwner = 2;
+    /** Owners of other plugins' panels, by plugin id ({@link TestHost.mountOther}). */
+    #others = new Map();
+    /**
+     * Simulate another plugin mounting a panel, before or after the plugin
+     * under test, as the player handles it: in the sidebar it is another tab
+     * (after the existing ones; the first panel's tab is current); the bottom
+     * bar and the backdrop take one panel, so the plugin's own mount there
+     * then rejects with `conflict` (not an activation failure, as in the
+     * player). Pushed as a `window.state` change.
+     *
+     * @param slot - The position.
+     * @param plugin - The other plugin's manifest id.
+     * @param options - `title`: its tab label (default: `plugin`).
+     *
+     * @example The playlist next to this plugin's sidebar panel
+     * ```ts
+     * const host = new TestHost();
+     * host.mountOther("sidebar", "vestra.playlist", { title: "播放列表" });
+     * const { plugin } = await startPlugin(activate, { host, directory });
+     * assert.equal(host.layout.sidebar?.panels?.length, 2);
+     * ```
+     *
+     * @since 1.5.2
+     */
+    mountOther(slot, plugin, options = {}) {
+        if (this.#others.has(plugin))
+            throw new Error(`${plugin} already has a panel`);
+        const owner = this.#nextOwner++;
+        if (slot === "backdrop") {
+            if (this.backdrop)
+                throw new Error("the backdrop is taken");
+            this.backdrop = { owner: plugin, effective: true };
+        }
+        else {
+            if (slot === "bottom" && this.layout.bottom)
+                throw new Error("the bottom bar is taken");
+            this.#addPanel(slot, { owner, plugin, title: options.title ?? plugin });
+        }
+        this.#others.set(plugin, { slot, owner });
+        this.emit("window.state", this.#windowFacts());
+    }
+    /**
+     * Simulate another plugin's panel going away ({@link TestHost.mountOther}):
+     * when its tab was current, the next tab (else the previous one) is.
+     *
+     * @since 1.5.2
+     */
+    unmountOther(plugin) {
+        const other = this.#others.get(plugin);
+        if (!other)
+            throw new Error(`${plugin} has no panel`);
+        this.#others.delete(plugin);
+        if (other.slot === "backdrop")
+            this.backdrop = null;
+        else
+            this.#removePanel(other.slot, other.owner);
+        this.emit("window.state", this.#windowFacts());
+    }
+    /**
+     * Simulate the user clicking a sidebar tab: `plugin`'s panel (the plugin
+     * under test's `manifestId`, or one of {@link TestHost.mountOther})
+     * becomes the current tab. Pushed as a `window.state` change.
+     *
+     * @since 1.5.2
+     */
+    selectTab(plugin) {
+        const slot = this.layout.sidebar;
+        const panel = slot?.panels?.find((entry) => entry.plugin === plugin);
+        if (!slot || !panel)
+            throw new Error(`${plugin} has no sidebar tab`);
+        slot.owner = panel.owner;
+        this.emit("window.state", this.#windowFacts());
+    }
+    #addPanel(slot, panel) {
+        const state = this.layout[slot];
+        if (state)
+            state.panels = [...(state.panels ?? []), panel];
+        else
+            this.layout[slot] = {
+                owner: panel.owner,
+                preferred: true,
+                effective: true,
+                reason: null,
+                detached: false,
+                panels: [panel],
+            };
+    }
+    #removePanel(slot, owner) {
+        const state = this.layout[slot];
+        if (!state)
+            return;
+        const panels = state.panels ?? [];
+        const index = panels.findIndex((panel) => panel.owner === owner);
+        const rest = panels.filter((panel) => panel.owner !== owner);
+        if (rest.length === 0) {
+            this.layout[slot] = null;
+            return;
+        }
+        state.panels = rest;
+        if (state.owner === owner)
+            state.owner = (rest[index] ?? rest[rest.length - 1]).owner;
+    }
     /**
      * The display layer (`plugin.video.view()`): who owns it (this plugin is
      * `manifestId`) and the values the player holds.
@@ -640,6 +760,29 @@ export class TestHost {
     producers = new Map();
     /** Registered source resolvers (`resolvers.add`) by id: their declarations. */
     resolvers = new Map();
+    /**
+     * Resolvers other plugins hold, as `resolvers.add` declares them plus the
+     * holder's id: a registration of this plugin that claims one of their
+     * extensions (or scheme + host pairs) is refused with `conflict`, which
+     * does not fail activation, like the player.
+     *
+     * @example
+     * ```ts
+     * const host = new TestHost();
+     * host.otherResolvers.push({ owner: "vestra.nes", extensions: ["nes"] });
+     * ```
+     */
+    otherResolvers = [];
+    /**
+     * File opens waiting for this plugin's file resolver (`extensions`), by
+     * request id: the path and how it was opened. Opening a matching path
+     * (`player.open`, {@link TestHost.openElsewhere}) sends
+     * `source.resolveRequest`; the answer selects the stream, fails the open
+     * or, once the source changed, is `stale`. Any later source change
+     * cancels it (`source.resolveCancel`). Web resolvers are not simulated:
+     * emit `source.resolveRequest` yourself.
+     */
+    resolutions = new Map();
     /**
      * Answers for `dialogs.open` (paths, `null` = cancelled) and
      * `dialogs.confirm` (`{ confirmed, checked }`), consumed in order. A
@@ -733,8 +876,12 @@ export class TestHost {
     #overrides = new Map();
     #listeners = new Map();
     #inFlight = 0;
-    #next = { snapshot: 0, job: 0, producer: 0, source: 0 };
+    #next = { snapshot: 0, job: 0, producer: 0, source: 0, resolution: 0 };
     #sourceBook = new Map();
+    /** The pending resolutions' stamps and operations (beside `resolutions`). */
+    #resolving = new Map();
+    /** The producer the source is (`openProvider`, a resolved stream). */
+    #selected = null;
     #scratch = mkdtempSync(join(tmpdir(), "vestra-test-host-"));
     /**
      * `plugin.dataDirectory`: a fresh empty temporary directory, removed with
@@ -1234,7 +1381,9 @@ export class TestHost {
      */
     openElsewhere(source, phase = "ready") {
         this.#intent({ kind: "open", source, startPaused: false });
-        this.setSource({ phase });
+        // A file this plugin's file resolver claims waits for its answer.
+        if (this.#resolve(source, false) === null)
+            this.setSource({ phase });
     }
     /**
      * Press a binding like the host's table would: panel-focus bindings first
@@ -1565,14 +1714,166 @@ export class TestHost {
             if (control.kind === "rate")
                 next.rate = Number(control.rate);
         }
+        if (intent.kind === "openProvider")
+            this.#selected = Number(intent.producerId);
+        if (intent.kind === "open" || intent.kind === "close")
+            this.#selected = null;
         this.source = next;
         this.subtitles.source = {
             generation: next.stamp.generation,
             phase: next.phase,
         };
         this.emit("source.state", this.source);
+        this.#cancelResolutions();
         return { ticket: { stamp: next.stamp, cycle: next.cycle, owner: 1 } };
     }
+    /** The file resolver of this plugin that claims `source`, if any. */
+    #fileResolver(source) {
+        if (source.includes("://") || !isAbsolute(source))
+            return null;
+        const extension = extname(source).slice(1).toLowerCase();
+        if (!extension)
+            return null;
+        for (const [id, declaration] of this.resolvers) {
+            const extensions = declaration.extensions;
+            if (extensions?.includes(extension))
+                return id;
+        }
+        return null;
+    }
+    /** Whether producer `id` is the player's source. */
+    #current(id) {
+        return (this.source.kind === "producer" &&
+            (this.#selected === id || this.source.source === `producer://${id}`));
+    }
+    /** Start resolving `source` for the open just made; its request id, or null. */
+    #resolve(source, paused, operation) {
+        const resolverId = this.#fileResolver(source);
+        if (resolverId === null)
+            return null;
+        const requestId = ++this.#next.resolution;
+        this.resolutions.set(requestId, { resolverId, source, paused });
+        this.#resolving.set(requestId, {
+            stamp: { ...this.source.stamp },
+            ...(operation === undefined ? {} : { operation }),
+        });
+        this.emit("source.resolveRequest", { requestId, resolverId, url: source });
+        return requestId;
+    }
+    /** Settle a resolution's open; `error` fails it. */
+    #settle(requestId, error) {
+        const operation = this.#resolving.get(requestId)?.operation;
+        this.resolutions.delete(requestId);
+        this.#resolving.delete(requestId);
+        if (operation === undefined)
+            return;
+        const entry = this.#sourceBook.get(operation);
+        this.#sourceBook.set(operation, error === undefined
+            ? { status: "completed", ticket: entry?.ticket ?? null }
+            : { status: "failed", error: { backend: error } });
+    }
+    /** Resolutions whose open is no longer the source (or whose resolver left). */
+    #cancelResolutions() {
+        const stamp = this.source.stamp;
+        for (const [requestId, resolution] of [...this.resolutions]) {
+            const pending = this.#resolving.get(requestId);
+            if (pending.stamp.generation === stamp.generation &&
+                pending.stamp.intentVersion === stamp.intentVersion &&
+                this.resolvers.has(resolution.resolverId))
+                continue;
+            this.#settle(requestId, "source resolution cancelled, expired or superseded");
+            this.emit("source.resolveCancel", {
+                requestId,
+                resolverId: resolution.resolverId,
+            });
+        }
+    }
+    /** `sourceResolvers.register`: the player's rules for both forms. */
+    #register(p) {
+        const id = String(p.id);
+        const extensions = p.extensions;
+        if (this.resolvers.has(id))
+            throw new HostError("conflict", "resolver id already registered");
+        if (extensions !== undefined) {
+            if (p.schemes !== undefined ||
+                p.hosts !== undefined ||
+                !Array.isArray(extensions) ||
+                extensions.length < 1 ||
+                extensions.length > 16 ||
+                extensions.some((e) => typeof e !== "string" ||
+                    !/^[a-z0-9]{1,16}$/.test(e) ||
+                    e === "folder"))
+                throw new HostError("invalid", "file resolvers take 1–16 file extensions (lower case, no dot, not folder)");
+        }
+        const claims = (other) => extensions?.find((e) => other.extensions?.includes(e)) ??
+            (other.hosts?.some((h) => p.hosts?.includes(h)) &&
+                other.schemes?.some((x) => p.schemes?.includes(x))
+                ? "host"
+                : undefined);
+        for (const own of this.resolvers.values())
+            if (claims(own))
+                throw new HostError("conflict", "already registered by this plugin");
+        for (const other of this.otherResolvers) {
+            const what = claims(other);
+            if (what) {
+                const target = what === "host" ? "这个网站" : `文件类型 .${what}`;
+                throw taken(`${target} 已由 ${other.owner} 解析`);
+            }
+        }
+        this.resolvers.set(id, p);
+    }
+    /** `sourceResolvers.respond` for a simulated file resolution. */
+    #respond(p) {
+        const requestId = Number(p.requestId);
+        const resolution = this.resolutions.get(requestId);
+        if (!resolution) {
+            // Web resolutions are not simulated: their answers are only recorded.
+            if (requestId > this.#next.resolution)
+                return null;
+            throw new HostError("stale", "resolution no longer pending");
+        }
+        const fail = (message) => {
+            this.#settle(requestId, message);
+            this.setSource({
+                phase: "error",
+                terminalReason: { failed: message },
+            });
+            throw new HostError("resolution", message);
+        };
+        if (typeof p.error === "string")
+            fail(p.error.trim() ? p.error.slice(0, 2048) : "resolver failed");
+        const result = (p.result ?? {});
+        const producer = this.producers.get(Number(result.producerId));
+        if (result.kind !== "stream")
+            fail("invalid resolved stream descriptor");
+        if (!producer || producer.released)
+            fail("unavailable: producer absent");
+        // Like openProvider, but the source keeps the path and `startPaused`.
+        this.#selected = producer.id;
+        producer.active = true;
+        producer.acknowledged = false;
+        producer.pending = {
+            producerId: producer.id,
+            epoch: producer.epoch + 1,
+            baseSample: producer.receivedFrames,
+            paused: resolution.paused,
+        };
+        this.#settle(requestId);
+        this.setSource({
+            kind: "producer",
+            phase: "ready",
+            paused: resolution.paused,
+            capabilities: {
+                pause: true,
+                seek: false,
+                rate: false,
+                restart: false,
+                close: true,
+                snapshotSource: false,
+            },
+        });
+        return { stamp: { ...this.source.stamp } };
+    }
     #processingState() {
         const list = (stage) => [...this.processing.resources]
             .filter(([, value]) => value.stage === stage)
@@ -1710,8 +2011,18 @@ export class TestHost {
         "ui.mount": (p) => {
             if (this.panel)
                 throw new HostError("conflict", "owner already mounted");
-            if (p.slot === "backdrop" && this.backdrop)
-                throw new HostError("conflict", "another plugin shows the backdrop");
+            // Like the player: one panel in the bottom bar and the backdrop, tabs
+            // in the sidebar (up to 8).
+            const holder = p.slot === "backdrop"
+                ? this.backdrop?.owner
+                : p.slot === "bottom"
+                    ? this.layout.bottom?.panels?.[0]?.plugin
+                    : undefined;
+            if (holder !== undefined || (p.slot === "bottom" && this.layout.bottom))
+                throw taken(`${SLOT_LABELS[String(p.slot)]}已被 ${holder} 使用`);
+            if (p.slot === "sidebar" &&
+                (this.layout.sidebar?.panels?.length ?? 0) >= MAX_SIDEBAR_TABS)
+                throw taken(`侧栏最多 ${MAX_SIDEBAR_TABS} 个页签`);
             this.#seeImages(p.properties);
             const host = this;
             this.panel = {
@@ -1734,25 +2045,25 @@ export class TestHost {
                 return { status: "ready", prepareMs: 0, shellGeneration: 1 };
             }
             const slot = String(p.slot);
-            this.layout[slot] = {
+            this.#addPanel(slot, {
                 owner: 1,
-                preferred: true,
-                effective: true,
-                reason: null,
-                detached: false,
-            };
+                plugin: this.manifestId,
+                title: typeof p.title === "string" && p.title ? p.title : this.manifestId,
+            });
             return { status: "ready", prepareMs: 0, shellGeneration: 1 };
         },
         "ui.unmount": () => {
             if (this.panel?.slot === "backdrop")
                 this.backdrop = null;
             else if (this.panel)
-                this.layout[this.panel.slot] = null;
+                this.#removePanel(this.panel.slot, 1);
             this.panel = null;
         },
         "ui.menu": (p) => {
             if (!this.panel)
                 throw new HostError("unavailable", "panel not shown");
+            if (this.panel.slot === "sidebar" && this.layout.sidebar?.owner !== 1)
+                throw new HostError("unavailable", "the panel's tab is not the current one");
             const items = p.items;
             for (const id of items)
                 if (id !== null && !this.commands.has(id))
@@ -1773,6 +2084,12 @@ export class TestHost {
                 throw new HostError("missing", "no panel at this position");
             if (p.detached !== undefined && slot === "bottom")
                 throw new HostError("invalid", "the bottom bar cannot be detached");
+            if (p.active !== undefined && p.active !== null) {
+                const panel = state.panels?.find((entry) => entry.plugin === p.active);
+                if (!panel)
+                    throw new HostError("missing", `${String(p.active)} has no panel at this position`);
+                state.owner = panel.owner;
+            }
             if (typeof p.visible === "boolean") {
                 state.preferred = p.visible;
                 state.effective = p.visible;
@@ -2144,8 +2461,17 @@ export class TestHost {
         "source.state": () => this.source,
         "source.submit": (p) => {
             const intent = p.intent;
-            const result = { status: "completed", ...this.#intent(intent) };
-            this.#sourceBook.set(Number(p.operationId), result);
+            const ticket = this.#intent(intent);
+            const operation = Number(p.operationId);
+            // A file this plugin's file resolver claims: pending until it answers.
+            if (intent.kind === "open" &&
+                this.#resolve(String(intent.source), intent.startPaused === true, operation) !== null) {
+                const pending = { status: "pending", ...ticket };
+                this.#sourceBook.set(operation, pending);
+                return pending;
+            }
+            const result = { status: "completed", ...ticket };
+            this.#sourceBook.set(operation, result);
             // Selecting a provider asks it to acknowledge a start control.
             const producer = this.producers.get(Number(intent.producerId));
             if (intent.kind === "openProvider" && producer) {
@@ -2573,9 +2899,12 @@ export class TestHost {
             return { jobId: job.jobId, cancel: "requested" };
         },
         "jobs.operation": () => ({ status: "unknown" }),
-        "sourceResolvers.register": (p) => void this.resolvers.set(String(p.id), p),
-        "sourceResolvers.unregister": (p) => void this.resolvers.delete(String(p.id)),
-        "sourceResolvers.respond": () => null,
+        "sourceResolvers.register": (p) => void this.#register(p),
+        "sourceResolvers.unregister": (p) => {
+            this.resolvers.delete(String(p.id));
+            this.#cancelResolutions();
+        },
+        "sourceResolvers.respond": (p) => this.#respond(p),
         "producer.prepare": async () => {
             const id = ++this.#next.producer;
             const tcp = this.producerTransport === "tcp";
@@ -2621,8 +2950,7 @@ export class TestHost {
                 });
                 socket.on("error", () => { });
                 socket.on("close", () => {
-                    if (this.source.kind === "producer" &&
-                        this.source.source === `producer://${producer.id}`)
+                    if (this.#current(producer.id))
                         producer.droppedWhileSelected = true;
                 });
             });
@@ -2653,8 +2981,7 @@ export class TestHost {
             const producer = this.producers.get(Number(p.producerId));
             if (!producer)
                 throw new HostError("missing", "producer");
-            const current = this.source.kind === "producer" &&
-                this.source.source === `producer://${producer.id}`;
+            const current = this.#current(producer.id);
             return {
                 input: null,
                 pendingControl: producer.pending,
@@ -2756,7 +3083,18 @@ export async function startPlugin(activate, options = {}) {
     mkdirSync(data, { recursive: true });
     const instance = await createPlugin(host, manifest, directory, data, host.app);
     await activate(instance.plugin);
-    await instance.activated();
+    // Like the player: a position or resolver another plugin holds is not an
+    // activation failure.
+    for (;;) {
+        try {
+            await instance.activated();
+            break;
+        }
+        catch (error) {
+            if (!(error instanceof Error && takenErrors.has(error)))
+                throw error;
+        }
+    }
     await host.settle();
     return {
         /** The test host the plugin talks to. */