@vestra-player/sdk 1.5.2 → 1.5.4

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,7 +110,10 @@ const readyCapabilities = {
     close: true,
     snapshotSource: true,
 };
-/** Refusals for a position another plugin holds: not activation failures (`startPlugin`). */
+/**
+ * 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);
@@ -757,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
@@ -850,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
@@ -1351,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
@@ -1450,9 +1482,16 @@ export class TestHost {
      */
     remoteImages = new Map();
     /**
-     * The Markdown document a property holds (its wire form read back), or
+     * The Markdown document a value holds (its wire form read back), or
      * `null` when the value is not one. `images` maps each remote address to
-     * the downloaded file.
+     * the downloaded file. Pass a whole property value or a field of one: a
+     * document nested in rows is read the same way.
+     *
+     * @example
+     * ```ts
+     * const rows = host.window("chat").props["messages"] as { body: Json }[];
+     * assert.equal(host.markdown(rows[0]!.body)?.text, "**Hello**");
+     * ```
      */
     markdown(value) {
         const doc = value
@@ -1682,14 +1721,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)
@@ -2277,8 +2468,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) {
@@ -2706,9 +2906,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";
@@ -2754,8 +2957,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;
                 });
             });
@@ -2786,8 +2988,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,
@@ -2889,7 +3090,8 @@ export async function startPlugin(activate, options = {}) {
     mkdirSync(data, { recursive: true });
     const instance = await createPlugin(host, manifest, directory, data, host.app);
     await activate(instance.plugin);
-    // Like the player: a position another plugin holds is not an activation failure.
+    // Like the player: a position or resolver another plugin holds is not an
+    // activation failure.
     for (;;) {
         try {
             await instance.activated();

package/dist/plugin/types.d.ts

@@ -562,18 +562,31 @@ export interface ImageRef {
     readonly __vestraImage: true;
 }
 /**
- * A Markdown document for `MarkdownView`, made by {@link Ui.markdown}.
+ * A Markdown document for `MarkdownView` or `MarkdownBlocks`, made by
+ * {@link Ui.markdown}.
  *
  * @remarks
- * Opaque, like {@link ImageRef}: pass it as the whole value of a
- * `[MarkdownBlock]` property (the `blocks` of `MarkdownView` from
- * `@vestra/markdown.slint`). It carries the text, the base address and the
- * local copies of its remote images; the player parses and draws it. It
- * belongs to the scope that created it: once that scope is disposed, writing
- * it fails with `invalid`.
- *
- * @player 0.2.0
- * @see {@link Ui.markdown}, {@link MarkdownOptions}
+ * Opaque, like {@link ImageRef}: pass it where the Slint type is
+ * `[MarkdownBlock]`: the whole value of such a property (the `blocks` of
+ * `MarkdownView` from `@vestra/markdown.slint`) or, from SDK 1.5.4, a
+ * `[MarkdownBlock]` field at any depth of a property value, such as the
+ * `body` of each row of a chat's message list. It carries the text, the
+ * base address and the local copies of its remote images; the player parses
+ * and draws it. Writing a document whose text did not change (a new
+ * reference for the same text included) costs the player no parsing, and a
+ * changed document updates only the blocks that changed. It belongs to the
+ * scope that created it: once that scope is disposed, writing it fails with
+ * `invalid`, wherever it is in the value.
+ *
+ * @example Chat messages, one document per row
+ * ```ts
+ * const chat = plugin.windows.create("ui/chat.slint");
+ * const body = await plugin.ui.markdown("**Hello**", { remoteImages: false });
+ * chat.set({ messages: [{ id: "m1", role: "assistant", body }] });
+ * ```
+ *
+ * @player 0.2.0; nested in a value: the player after 0.4.0
+ * @see {@link Ui.markdown}, {@link MarkdownOptions}, {@link PropValue}
  * @since 1.1.0
  * @category UI
  */
@@ -607,8 +620,9 @@ export interface MarkdownOptions {
     remoteImages?: boolean;
 }
 /**
- * The value of one Slint property: JSON, or an image or a Markdown document
- * as the whole value of a property.
+ * The value of one Slint property: JSON with Markdown documents at any
+ * depth ({@link PropData}), or an image as the whole value of an `image`
+ * property.
  *
  * @remarks
  * JSON becomes Slint values as you would expect: booleans for `bool`,
@@ -618,14 +632,37 @@ export interface MarkdownOptions {
  * is refused (Slint treats `_` and `-` as the same, so use camelCase or
  * kebab-case).
  *
- * Limits per value: nesting depth 8, 4096 values in total, 1024 rows per
- * array, 64 KiB per string and 1 MiB of text in total. A value over a limit
- * is a failed write (see {@link View}).
+ * A {@link MarkdownRef} goes where the Slint type is `[MarkdownBlock]`: the
+ * whole value, or a field at any depth (SDK 1.5.4; older players refuse a
+ * nested one). An {@link ImageRef} only as the whole value: nested in an
+ * array or object it is `invalid`.
+ *
+ * Limits per value: nesting depth 8, 4096 values in total (a document is
+ * one), 1024 rows per array, 64 KiB per string and 1 MiB of text in total,
+ * the text of its Markdown documents included (256 KB per document). A
+ * value over a limit is a failed write (see {@link View}).
  *
  * @since 1.0.0
  * @category UI
  */
-export type PropValue = Json | ImageRef | MarkdownRef;
+export type PropValue = PropData | ImageRef;
+/**
+ * JSON whose values may also be Markdown documents, at any depth: the part
+ * of {@link PropValue} that nests.
+ *
+ * @example A message list whose rows carry a document
+ * ```ts
+ * const messages: PropData = [
+ *   { id: "m1", role: "user", body: await plugin.ui.markdown("Hi") },
+ * ];
+ * ```
+ *
+ * @since 1.5.4
+ * @category UI
+ */
+export type PropData = null | boolean | number | string | MarkdownRef | PropData[] | {
+    [key: string]: PropData;
+};
 /**
  * Properties to write to a view, by name.
  *
@@ -2771,7 +2808,12 @@ export interface PlayerState {
     readonly kind: "media" | "stream";
     /** The source's life cycle. */
     readonly phase: "empty" | "loading" | "ready" | "ended" | "error";
-    /** Path or URL. */
+    /**
+     * Path or URL; `null` when empty. A generated stream started with
+     * {@link Player.openStream} has the opaque `producer://<n>` (do not parse
+     * it); one a file resolver generates ({@link FileResolverOptions}) keeps
+     * the path that was opened. Tell streams apart by `kind`, not by `source`.
+     */
     readonly source: string | null;
     /** Playback is paused. */
     readonly paused: boolean;
@@ -3087,7 +3129,9 @@ export interface Player {
      *
      * It does not wait for playback: use {@link Media.ready}. `paused` opens
      * it paused; aborting `signal` closes it. URLs matching a registered
-     * {@link Resolver} are resolved first.
+     * {@link Resolver} are resolved first, and so are local files of an
+     * extension a file resolver claims (the source is then a stream that
+     * plugin generates; `paused` reaches it).
      */
     open(source: string, options?: {
         paused?: boolean;
@@ -3811,8 +3855,13 @@ export interface MediaCapture {
      */
     capture(options?: CaptureOptions): Promise<Snapshot>;
 }
-/** Declaration of {@link Resolvers.add}. */
-export interface ResolverOptions {
+/**
+ * Declaration of {@link Resolvers.add}: a web resolver
+ * ({@link WebResolverOptions}) or a file resolver ({@link FileResolverOptions}).
+ */
+export type ResolverOptions = WebResolverOptions | FileResolverOptions;
+/** A resolver for web pages: `https://host/…` to playable stream URLs. */
+export interface WebResolverOptions {
     /** Local id, unique within the plugin. */
     id: string;
     /** URL schemes handled. */
@@ -3822,14 +3871,104 @@ export interface ResolverOptions {
     /** Turn a page URL into playable stream URLs. */
     resolve(url: string, signal: AbortSignal): Promise<ResolvedMedia>;
 }
+/**
+ * A resolver for local files by extension (SDK 1.5.3, player 0.4.1): when
+ * anyone opens such a file with {@link Player.open} (the Open dialog, the
+ * playlist, next / previous, the recent list, a drop that calls `open`),
+ * the player asks this plugin for a stream it generates instead of
+ * playing the file. Needs `source.resolve` and `producer.av`.
+ *
+ * @remarks
+ * The open keeps everything of the original call: its `ifCurrent`, its
+ * operation (the opener's `open` and `media.ready()` settle as for any
+ * file), `paused` (the stream starts paused), and its path as
+ * `state.source`, with `state.kind` `"stream"`. A thrown error fails that
+ * open: `phase` `"error"` with the error's message as `state.error`,
+ * word for word. The stream belongs to this plugin, as with
+ * {@link Player.openStream}.
+ *
+ * Cancellation: `signal` aborts when the open is replaced, closed
+ * (`player.close()`, F4) or times out (30 seconds), or this resolver is
+ * disposed. Cancelled after `resolve` returned but before the stream ran,
+ * the SDK releases the stream and never calls `started`.
+ *
+ * One extension has one resolver: another plugin's resolver for it makes
+ * {@link Resolver.ready} reject with `conflict` without failing activation
+ * (the player shows a warning). When this plugin stops, its extensions are
+ * free again and such files go to the player as before.
+ *
+ * @example
+ * ```ts
+ * const { readFile } = await import("node:fs/promises");
+ * // The plugin's own emulator: one frame per call.
+ * const emulator = (rom: Uint8Array): (() => StreamFrame) => {
+ *   const video = new Uint8Array(256 * 240 * 4).fill(rom[0] ?? 0);
+ *   return () => ({ video, audio: new Float32Array(1600) });
+ * };
+ * plugin.resolvers.add({
+ *   id: "nes",
+ *   extensions: ["nes"],
+ *   async resolve(path, signal) {
+ *     const frame = emulator(await readFile(path, { signal }));
+ *     return {
+ *       kind: "stream",
+ *       width: 256,
+ *       height: 240,
+ *       frame,
+ *       started: (stream) => stream.onStop((error) => error && plugin.osd.show(error.message)),
+ *     };
+ *   },
+ * });
+ * ```
+ */
+export interface FileResolverOptions {
+    /** Local id, unique within the plugin. */
+    id: string;
+    /**
+     * Lower case, without the dot: 1–16 entries of 1–16 lower-case letters or
+     * digits (not `"folder"`). Only absolute local paths match, by their
+     * extension in any case (`/roms/Game.NES`); URLs never do.
+     */
+    extensions: string[];
+    /** Read the file and describe the stream to generate for it. */
+    resolve(path: string, signal: AbortSignal): Promise<ResolvedStream>;
+}
+/**
+ * What a file resolver returns: a stream, with the same frame contract as
+ * {@link StreamOptions} (size limits, `frame()` on the audio clock).
+ */
+export interface ResolvedStream {
+    /** Always `"stream"`. */
+    kind: "stream";
+    /** Frame width in pixels. */
+    width: number;
+    /** Frame height in pixels. */
+    height: number;
+    /** Produce the next frame. Never called concurrently or while paused. */
+    frame(): StreamFrame;
+    /**
+     * Called with the running stream once the player plays it, synchronously
+     * after activation and before any {@link Stream.onStop}. Not called when
+     * the open was cancelled first. `stream.stop()` closes the source (if
+     * still current); the plugin stopping stops it too.
+     */
+    started?(stream: Stream): void;
+}
 /** A registered resolver. Disposing it unregisters it and aborts resolutions in flight. */
 export interface Resolver extends Disposable {
-    /** Resolves when the player registered it; rejects (e.g. `conflict`) otherwise. */
+    /**
+     * Resolves when the player registered it; rejects otherwise: `conflict`
+     * when another resolver has the extension or the scheme + host (another
+     * plugin's: activation goes on; this plugin's own: activation fails),
+     * `invalid` for a malformed declaration (a player before 0.4.1 also for
+     * `extensions`).
+     */
     readonly ready: Promise<void>;
 }
 /**
- * `plugin.resolvers`: turn web page URLs into playable streams. Needs
- * `source.resolve`.
+ * `plugin.resolvers`: turn web page URLs into playable streams, or local
+ * files into streams this plugin generates. Needs `source.resolve` (file
+ * resolvers also `producer.av`).
  *
  * @example
  * ```ts
@@ -3846,9 +3985,11 @@ export interface Resolver extends Disposable {
  */
 export interface Resolvers {
     /**
-     * Register a resolver. When anyone opens a matching URL the player calls
-     * `resolve`; `signal` aborts when the open is cancelled or replaced. One
-     * scheme + host pair has one resolver (`conflict` otherwise).
+     * 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;
 }
@@ -4029,10 +4170,18 @@ export interface PluginInfo {
  * @since 1.5.2
  */
 export interface PluginWarning {
-    /** `"slot-occupied"` or `"sequence-taken"`; a newer player may add codes. */
+    /**
+     * `"slot-occupied"`, `"sequence-taken"` or `"resolver-taken"` (player
+     * 0.4.1); a newer player may add codes.
+     */
     code: string;
     /** The panel position (`"bottom"`, `"sidebar"`, `"backdrop"`) for `slot-occupied`. */
     slot?: string;
+    /**
+     * What was taken, for `resolver-taken`: 「文件类型 .nes」 or the
+     * `scheme://host` of a web resolver.
+     */
+    target?: string;
     /** The manifest id of the plugin holding it (absent for a full sidebar). */
     owner?: string;
 }

package/dist/plugin/ui.js

@@ -31,18 +31,33 @@ export class ImageHandle {
         return { $vestraImage: this.path, ref: this.#ref };
     }
 }
-/** A property value as sent: images and documents in wire form; released ones refused. */
-function wireValue(value) {
+/**
+ * A property value as sent: images and documents in wire form, documents at
+ * any depth (released ones refused wherever they are); an image only as the
+ * whole value, like the player.
+ */
+function wireValue(value, nested = false) {
     if (value instanceof MarkdownHandle) {
         if (value.released)
             throw failure("invalid", "Markdown document was released with the scope that created it");
         return value.toJSON();
     }
-    if (!(value instanceof ImageHandle))
-        return value;
-    if (value.released)
-        throw failure("invalid", `image ${value.path} was released with the scope that created it`);
-    return value.toJSON();
+    if (value instanceof ImageHandle) {
+        if (nested)
+            throw failure("invalid", `image ${value.path}: an image reference must be the whole value of an image property`);
+        if (value.released)
+            throw failure("invalid", `image ${value.path} was released with the scope that created it`);
+        return value.toJSON();
+    }
+    if (Array.isArray(value))
+        return value.map((item) => wireValue(item, true));
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, item] of Object.entries(value))
+            out[key] = wireValue(item, true);
+        return out;
+    }
+    return value;
 }
 export const ui = (scope) => ({
     image(path) {