@vestra-player/sdk 1.5.2 → 1.5.4

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 1.5.4
+
+**Markdown in list rows** (the player after 0.4.0). Additive; `apiVersion` stays `vestra/1`, and plugins written for 1.5.3 need no change.
+
+- **A `MarkdownRef` at any depth.** A document from `plugin.ui.markdown` may now be a field at any depth of a property value, wherever the Slint type is `[MarkdownBlock]`: for example the `body` of each row of a chat's `[Message]` list. Before, it could only be the whole value of a `[MarkdownBlock]` property. `PropValue` is now `PropData | ImageRef`, where the new **`PropData`** is JSON whose values may also be `MarkdownRef`s, at any depth. A released document is refused with `invalid` wherever it is in the value. An `ImageRef` stays a whole value only: nested in an array or object it is `invalid` (a type error in TypeScript, and refused by the SDK and the player). Older players refuse a nested document like any value they cannot convert.
+- **Limits:** a document still holds at most 256 KB of text, 4000 blocks and 64 images; all of a value's text, its documents' text included, counts toward the value's 1 MiB; each document is one of its 4096 values.
+- **`MarkdownBlocks`** (new in `@vestra/markdown.slint`): the blocks of a document without scrolling, as tall as their content, for your own layout or a `ListView` row. `in [MarkdownBlock] blocks`, `in bool code-copy` (default `false`), callbacks `link-clicked(string)` and `copy-code(string)`. `MarkdownView` is now a `ScrollView` around it and gains the same `code-copy` and `copy-code`; it looks as before.
+- **Code copy, opt in.** With `code-copy: true`, code blocks get a 复制 button that reports `copy-code(code)` with the block's text; the plugin copies it (`plugin.clipboard.writeText`). Off by default: views that do not set it look and behave as before.
+- **Cheaper updates** (player): writing a value again with unchanged documents does not parse them again (a new reference for the same text included), and a value with documents is updated in place where its shape allows: changed rows, rows added or removed at the end, and only the changed blocks of a changed document. Streaming a reply into the last row of a 200-message list therefore keeps the list, its scroll position and the other rows. Nothing to change in plugins.
+- `TestHost` keeps nested documents in the view's properties as they were sent; `host.markdown(value)` reads one back from a field (`host.markdown(rows[0].body)`).
+## 1.5.3
+
+**File resolvers: local files as generated streams** (player 0.4.1). Additive; `apiVersion` stays `vestra/1`. Plugins that register one set `"minPlayerVersion": "0.4.1"`: an older player refuses the declaration (`invalid`).
+
+- **`resolvers.add({ id, extensions, resolve })`** (`FileResolverOptions`). When anyone opens a local file of those extensions with `player.open` (the Open dialog, the playlist, next / previous, the recent list), the player asks this plugin for a stream instead of playing the file. `resolve(path, signal)` returns a `ResolvedStream`: `{ kind: "stream", width, height, frame, started? }`, with the frame contract of `openStream`. Needs `source.resolve` and `producer.av`. `ResolverOptions` is now the union of `WebResolverOptions` (the existing form) and `FileResolverOptions`.
+  - The open keeps its arbitration: its `ifCurrent` and operation (the opener's `open` / `media.ready()` settle as usual), and `paused` reaches the stream's start. `state.source` stays the path, `state.kind` is `"stream"`.
+  - Cancellation: `signal` aborts when the open is replaced or closed (`player.close()` included), times out (30 s) or the resolver is disposed. Cancelled after `resolve` returned but before the stream ran, the SDK releases the stream and never calls `started`.
+  - `started(stream)` is called synchronously right after activation, before any `onStop`; the `Stream` is the same as `openStream`'s and belongs to the resolver's plugin.
+  - Extensions: 1–16 entries of 1–16 lower-case letters or digits, not `"folder"`; only absolute local paths match (any case), URLs never do.
+- **One extension, and one scheme + host pair, has one resolver.** Another plugin's makes `Resolver.ready` reject with `conflict` (reason `resolver-taken` on the wire), and that no longer fails activation, for web resolvers too (as for panels and the sequence since 1.5.2); the player shows a warning (`PluginInfo.warnings`: `code` `"resolver-taken"`, `owner`, the new `target`). The plugin's own second claim still fails activation.
+- **Resolver failures are sent as the error's message** (`error.message`, was `String(error)`, e.g. `"Error: …"`), and the player shows them word for word (it prefixed `resolver failed: `). This changes the failure text of web resolvers too.
+- **Docs**: `PlayerState.source` documents the naming of generated streams: `producer://<n>` (opaque) for `openStream`, the path for a file resolver's; tell streams apart by `kind`.
+- **`TestHost`** simulates file resolutions: opening a matching path (`player.open`, `openElsewhere`) sends `source.resolveRequest` and keeps the open pending; the answer selects the stream (or fails the open); any later source change cancels it (`source.resolveCancel`). `resolutions` lists the pending ones, `otherResolvers` simulates other plugins' registrations (conflicts). `startPlugin` does not fail activation for such a conflict. Web resolutions are still driven by the test (emit `source.resolveRequest`).
+- Internals: `openStream` is split into prepare / activate / abandon steps shared with file resolvers; the wire client (`sourceResolvers.register`) takes a `{ id, extensions }` declaration and a handler answer with the prepared producer.
+
 ## 1.5.2
 
 **Sidebar tabs** (the player after 0.4.0). Additive; `apiVersion` stays `vestra/1`, and plugins written for 1.5.1 need no change. The new members work against older players too (see each one).

package/dist/plugin/resolvers.js

@@ -1,10 +1,22 @@
-/** Source resolvers turn page URLs into stream URLs for `player.open`. */
-import { quiet } from "./runtime.js";
+/**
+ * Source resolvers: page URLs to stream URLs, or local files to a stream
+ * this plugin generates, for `player.open`.
+ */
+import { failure, quiet } from "./runtime.js";
+import { playerOf } from "./player.js";
+import { resolvedStream } from "./stream.js";
+const isFiles = (options) => "extensions" in options;
 export const resolvers = (scope) => ({
     add(options) {
-        const { resolve, ...declaration } = options;
         const runtime = scope.runtime;
-        const registration = runtime.host.sourceResolvers.register(declaration, ({ url, signal }) => resolve(url, signal));
+        const registration = isFiles(options)
+            ? runtime.host.sourceResolvers.register({ id: options.id, extensions: options.extensions }, async ({ url, signal }) => {
+                const stream = await options.resolve(url, signal);
+                if (stream?.kind !== "stream")
+                    throw failure("invalid", 'a file resolver returns { kind: "stream", width, height, frame }');
+                return resolvedStream(scope, playerOf(runtime), stream, signal);
+            })
+            : runtime.host.sourceResolvers.register({ id: options.id, schemes: options.schemes, hosts: options.hosts }, ({ url, signal }) => options.resolve(url, signal));
         let disposed = false;
         const handle = {
             ready: quiet(runtime

package/dist/plugin/stream.d.ts

@@ -1,4 +1,14 @@
 import type { PlayerService } from "./player.ts";
 import type { ScopeImpl } from "./scope.ts";
-import type { Stream, StreamOptions } from "./types.ts";
+import type { ResolvedProducer } from "../source-resolvers.ts";
+import type { ResolvedStream, Stream, StreamOptions } from "./types.ts";
 export declare function openStream(scope: ScopeImpl, service: PlayerService, options: StreamOptions): Promise<Stream>;
+/**
+ * A file resolver's stream (`ResolvedStream`): prepared and prerolled while
+ * the open waits, then handed to the host as the answer. Once the host
+ * selected it, the start control is acknowledged and `started` gets the
+ * running stream, synchronously, before any `onStop`. Cancelled before or
+ * during activation (the open was replaced or closed, the plugin stopped),
+ * the producer is released and `started` is never called.
+ */
+export declare function resolvedStream(scope: ScopeImpl, service: PlayerService, stream: ResolvedStream, signal: AbortSignal): Promise<ResolvedProducer>;

package/dist/plugin/stream.js

@@ -154,17 +154,11 @@ async function sendFrame(socket, frame, clock, epoch) {
         clock.advance(samples.length / 2);
     }
 }
-export async function openStream(scope, service, options) {
-    const host = service.runtime.host;
-    const check = () => {
-        if (options.signal?.aborted || scope.disposed)
-            throw abortError();
-    };
-    let prepared;
-    let socket;
-    let generation;
-    /** The request selecting the stream, once sent. */
-    let opened;
+/**
+ * Prepare a producer, connect and preroll it until the host could select it.
+ * `check` throws to give up (an abort); the producer is then released.
+ */
+async function prepare(host, options, check) {
     const bytes = options.width * options.height * 4;
     /** The plugin's frame, checked against the declared size. */
     const frame = () => {
@@ -173,103 +167,183 @@ export async function openStream(scope, service, options) {
             throw failure("invalid", `frame().video must be ${options.width}×${options.height}×4 = ${bytes} bytes of RGBA`);
         return next;
     };
+    let producer;
+    let socket;
     try {
         check();
         const spec = await host.producer.prepare({
             width: options.width,
             height: options.height,
         });
-        prepared = spec.producerId;
+        producer = spec.producerId;
         check();
         socket = await host.producer.connect(spec);
         check();
-        let epoch = spec.epoch;
-        let sample = 0;
-        let sequence = 0;
-        const clock = {
-            get sample() {
-                return sample;
-            },
-            advance: (n) => (sample += n),
-            nextSequence: () => sequence++,
+        const p = {
+            producer,
+            socket,
+            frame,
+            epoch: spec.epoch,
+            sample: 0,
+            sequence: 0,
         };
+        const clock = clockOf(p);
         // A prepared producer is paused at sample zero. Supply a frame at zero and
         // enough contiguous PCM before asking the host to select it.
-        while (sample < PREROLL) {
+        while (p.sample < PREROLL) {
             check();
-            await writeFrame(socket, frame(), clock, epoch);
+            await writeFrame(socket, frame(), clock, p.epoch);
         }
         for (const deadline = Date.now() + 10_000;; await sleep(10)) {
             check();
-            const state = await host.producer.state(prepared);
+            const state = await host.producer.state(producer);
             if (state.error)
                 throw failure("stream", state.error);
-            if (state.epoch !== epoch)
+            if (state.epoch !== p.epoch)
                 throw failure("stream", "producer epoch changed before activation");
             if (!["ok", "recoverableXrun", "deviceChanged"].includes(state.health))
                 throw failure("device", `audio device is not ready: ${state.health}`);
             if (state.acknowledged && state.receivedFrames >= 1024 && state.hasVideo)
-                break;
+                return p;
             if (Date.now() >= deadline)
                 throw timeout("prefill", "timed out preparing the first buffers");
         }
+    }
+    catch (error) {
+        socket?.close();
+        if (producer !== undefined)
+            await host.producer.release(producer).catch(() => { });
+        throw error;
+    }
+}
+const clockOf = (p) => ({
+    get sample() {
+        return p.sample;
+    },
+    advance: (n) => (p.sample += n),
+    nextSequence: () => p.sequence++,
+});
+/**
+ * Wait until the host runs the selected producer: acknowledge its start
+ * control. `selected` says whether the host has accepted the selection yet
+ * (`"selected"`: it has, and a producer no longer active was replaced);
+ * `check` throws to give up.
+ */
+async function activate(host, p, check, selected) {
+    for (const deadline = Date.now() + 10_000;; await sleep(10)) {
+        check();
+        const state = await host.producer.state(p.producer);
+        if (state.error)
+            throw failure("stream", state.error);
+        if (selected === "selected" && !state.active)
+            throw abortError();
+        if (state.pendingControl) {
+            p.epoch = state.pendingControl.epoch;
+            p.sample = state.pendingControl.baseSample;
+            p.sequence = 0;
+            await host.producer.ack(state.pendingControl);
+        }
+        if ((selected === "selected" || selected()) &&
+            state.active &&
+            !state.pendingControl &&
+            state.acknowledged &&
+            state.epoch === p.epoch)
+            return;
+        if (Date.now() >= deadline)
+            throw timeout("activation", "timed out waiting for stream activation");
+    }
+}
+/** Give a prepared producer up: its source (if still ours), connection, producer. */
+async function abandon(service, p, generation) {
+    // A cancelled open may already have selected this producer: close only
+    // that source, before its frame connection (as in `stop`).
+    if (generation !== undefined)
+        await service.closeIfCurrent(generation).catch(() => { });
+    p.socket.close();
+    await service.runtime.host.producer.release(p.producer).catch(() => { });
+}
+const handleOf = (scope, service, p, generation) => new StreamHandle(scope, service, {
+    producer: p.producer,
+    socket: p.socket,
+    generation,
+    frame: p.frame,
+    epoch: p.epoch,
+    sample: p.sample,
+    sequence: p.sequence,
+});
+export async function openStream(scope, service, options) {
+    const host = service.runtime.host;
+    const check = () => {
+        if (options.signal?.aborted || scope.disposed)
+            throw abortError();
+    };
+    const p = await prepare(host, options, check);
+    let generation;
+    /** The request selecting the stream. */
+    let opened;
+    try {
         let accepted = false;
+        let failed;
         opened = service
-            .submit({ kind: "openProvider", producerId: prepared, startPaused: false }, { accepted: (ticket) => (generation = ticket.stamp.generation) })
+            .submit({ kind: "openProvider", producerId: p.producer, startPaused: false }, { accepted: (ticket) => (generation = ticket.stamp.generation) })
             .then((ticket) => {
             generation = ticket.stamp.generation;
             accepted = true;
         });
-        let failed;
         opened.catch((error) => (failed = error));
         // Activation needs this side to acknowledge the host's start control.
-        for (const deadline = Date.now() + 10_000;; await sleep(10)) {
+        await activate(host, p, () => {
             check();
             if (failed)
                 throw failed;
-            const state = await host.producer.state(prepared);
-            if (state.error)
-                throw failure("stream", state.error);
-            if (state.pendingControl) {
-                epoch = state.pendingControl.epoch;
-                sample = state.pendingControl.baseSample;
-                sequence = 0;
-                await host.producer.ack(state.pendingControl);
-            }
-            if (accepted &&
-                state.active &&
-                !state.pendingControl &&
-                state.acknowledged &&
-                state.epoch === epoch)
-                break;
-            if (Date.now() >= deadline)
-                throw timeout("activation", "timed out waiting for stream activation");
-        }
-        const handle = new StreamHandle(scope, service, {
-            producer: prepared,
-            socket,
-            generation: generation,
-            frame,
-            epoch,
-            sample,
-            sequence,
-        });
-        prepared = undefined;
-        socket = undefined;
-        return handle;
+        }, () => accepted);
+        return handleOf(scope, service, p, generation);
     }
     catch (error) {
         // An abort can arrive before the host answered the selecting request: wait
         // for that answer so a source selected afterwards is still closed.
-        if (opened && prepared !== undefined)
-            await opened.catch(() => { });
-        // A cancelled open may already have selected this producer: close only
-        // that source, before its frame connection (as in `stop`).
-        if (generation !== undefined && prepared !== undefined)
-            await service.closeIfCurrent(generation).catch(() => { });
-        socket?.close();
-        if (prepared !== undefined)
-            await host.producer.release(prepared).catch(() => { });
+        await opened?.catch(() => { });
+        await abandon(service, p, generation);
         throw error;
     }
 }
+/**
+ * A file resolver's stream (`ResolvedStream`): prepared and prerolled while
+ * the open waits, then handed to the host as the answer. Once the host
+ * selected it, the start control is acknowledged and `started` gets the
+ * running stream, synchronously, before any `onStop`. Cancelled before or
+ * during activation (the open was replaced or closed, the plugin stopped),
+ * the producer is released and `started` is never called.
+ */
+export async function resolvedStream(scope, service, stream, signal) {
+    const host = service.runtime.host;
+    const p = await prepare(host, stream, () => {
+        if (signal.aborted || scope.disposed)
+            throw abortError();
+    });
+    return {
+        kind: "stream",
+        producerId: p.producer,
+        abandoned: () => abandon(service, p, undefined),
+        accepted: async ({ stamp }) => {
+            try {
+                await activate(host, p, () => {
+                    if (scope.disposed)
+                        throw abortError();
+                }, "selected");
+                // Replaced before it ran: the source is no longer this stream.
+                if (service.raw.stamp.generation > stamp.generation)
+                    throw abortError();
+            }
+            catch (error) {
+                await abandon(service, p, stamp.generation);
+                if (error.code !== "aborted")
+                    scope.report(error);
+                return;
+            }
+            const handle = handleOf(scope, service, p, stamp.generation);
+            if (stream.started)
+                scope.run(stream.started, handle);
+        },
+    };
+}

package/dist/plugin/testing.d.ts

@@ -744,6 +744,45 @@ export declare class TestHost implements Transport {
     }>;
     /** Registered source resolvers (`resolvers.add`) by id: their declarations. */
     readonly resolvers: Map<string, Json>;
+    /**
+     * 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"] });
+     * ```
+     */
+    readonly otherResolvers: {
+        /** The manifest id of the plugin holding them (shown in the refusal). */
+        owner: string;
+        /** File extensions it resolves (a file resolver), lower case, no dot. */
+        extensions?: string[];
+        /** URL schemes it resolves (a web resolver), with `hosts`. */
+        schemes?: string[];
+        /** Exact host names it resolves (a web resolver), with `schemes`. */
+        hosts?: string[];
+    }[];
+    /**
+     * 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.
+     */
+    readonly resolutions: Map<number, {
+        /** The id of this plugin's resolver asked (`resolvers.add` `id`). */
+        resolverId: string;
+        /** The path being opened, as sent to `resolve`. */
+        source: string;
+        /** The open asked for a paused start (`player.open(path, { paused })`). */
+        paused: boolean;
+    }>;
     /**
      * Answers for `dialogs.open` (paths, `null` = cancelled) and
      * `dialogs.confirm` (`{ confirmed, checked }`), consumed in order. A
@@ -1089,9 +1128,16 @@ export declare class TestHost implements Transport {
      */
     readonly remoteImages: Map<string, string | null>;
     /**
-     * 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: Json | undefined): MarkdownWire | null;
     /**