@vestra-player/sdk 1.5.29 → 1.5.30

package/dist/plugin/values.d.ts

@@ -17,12 +17,36 @@ import type { Json } from "../wire.ts";
  * bound (a playlist, a history) should send the rows near the view and say
  * how many there are, not the whole list.
  *
- * @example
+ * @example Send a long playlist as a window of rows
+ * A list view shows any number of entries while each write stays small:
+ * the plugin sends only the rows around the scroll position plus the total,
+ * and the view reports where it scrolled to. After the `scrolled` handler
+ * returns, the SDK evaluates the `bind` function again and sends the new
+ * window. Each row object and each of its fields count as one value toward
+ * `values`, and so does the array holding them.
  * ```ts
+ * declare const entries: { title: string; duration: number }[];
+ * import type { View } from "@vestra-player/sdk";
+ * declare const list: View;
+ * // ---cut---
  * import { UI_VALUE_LIMITS } from "@vestra-player/sdk/testing";
  *
- * // 8 fields per row: 9 values (the row and its fields).
- * const window = Math.floor(UI_VALUE_LIMITS.values / 9) - 1;
+ * // 200 rows, or fewer if the limits were smaller: 2 fields per row make
+ * // 3 values (the row and its fields), plus 1 for the array.
+ * const size = Math.min(
+ *   200,
+ *   UI_VALUE_LIMITS.arrayRows,
+ *   Math.floor((UI_VALUE_LIMITS.values - 1) / 3),
+ * );
+ * let first = 0;
+ * list.bind(() => ({
+ *   total: entries.length,
+ *   rows: entries.slice(first, first + size),
+ * }));
+ * // The Slint view reports its first visible row; the window follows it.
+ * list.on("scrolled", (row: number) => {
+ *   first = Math.max(0, row - Math.floor(size / 2));
+ * });
  * ```
  *
  * @since 1.5.10

package/dist/plugin/values.js

@@ -15,12 +15,36 @@
  * bound (a playlist, a history) should send the rows near the view and say
  * how many there are, not the whole list.
  *
- * @example
+ * @example Send a long playlist as a window of rows
+ * A list view shows any number of entries while each write stays small:
+ * the plugin sends only the rows around the scroll position plus the total,
+ * and the view reports where it scrolled to. After the `scrolled` handler
+ * returns, the SDK evaluates the `bind` function again and sends the new
+ * window. Each row object and each of its fields count as one value toward
+ * `values`, and so does the array holding them.
  * ```ts
+ * declare const entries: { title: string; duration: number }[];
+ * import type { View } from "@vestra-player/sdk";
+ * declare const list: View;
+ * // ---cut---
  * import { UI_VALUE_LIMITS } from "@vestra-player/sdk/testing";
  *
- * // 8 fields per row: 9 values (the row and its fields).
- * const window = Math.floor(UI_VALUE_LIMITS.values / 9) - 1;
+ * // 200 rows, or fewer if the limits were smaller: 2 fields per row make
+ * // 3 values (the row and its fields), plus 1 for the array.
+ * const size = Math.min(
+ *   200,
+ *   UI_VALUE_LIMITS.arrayRows,
+ *   Math.floor((UI_VALUE_LIMITS.values - 1) / 3),
+ * );
+ * let first = 0;
+ * list.bind(() => ({
+ *   total: entries.length,
+ *   rows: entries.slice(first, first + size),
+ * }));
+ * // The Slint view reports its first visible row; the window follows it.
+ * list.on("scrolled", (row: number) => {
+ *   first = Math.max(0, row - Math.floor(size / 2));
+ * });
  * ```
  *
  * @since 1.5.10

package/dist/processing.d.ts

@@ -13,10 +13,17 @@ import type { Transport } from "./wire.ts";
  * rotation): a portrait video is upright before `transform` runs. At most
  * 64 nodes across all plugins.
  *
- * @example
+ * @example Brighten, sharpen and rotate the picture
+ * The video plays a little brighter and more saturated, slightly sharper
+ * and turned a quarter clockwise. The nodes run in array order; `set` sends
+ * the whole chain as this plugin's desired value (last write wins), and the
+ * player applies it to every source until it changes, needing
+ * `processing.video`, `playback.read` and `events`.
  * ```ts
  * const chain: VideoNode[] = [
+ *   // Live fields: moving them later changes the picture in place.
  *   { kind: "eq", brightness: 0.05, contrast: 1.1, saturation: 1.2, gamma: 1 },
+ *   // Not live: changing `amount` later rebuilds the stage (a one-frame stall).
  *   { kind: "sharpen", amount: 0.5, size: "small" },
  *   { kind: "transform", rotate: 90, flipH: false, flipV: false },
  * ];
@@ -160,12 +167,17 @@ export type VideoNode =
  * One node of an {@link AudioFilter} chain, by `kind`. Values outside the
  * ranges fail with `invalid`; "live" fields change in place while playing.
  *
- * @example
+ * @example Lift the voices and play in mono
+ * Speech around 1 kHz is 3 dB louder and both speakers play the same mixed
+ * channel. `set` sends this plugin's whole audio chain (the nodes in order,
+ * plus an optional `delayMs`); the player joins it with other plugins'
+ * chains and applies it to every source (`processing.audio`,
+ * `playback.read`, `events`).
  * ```ts
  * plugin.audio.filter("sound").set({
  *   nodes: [
- *     { kind: "equalizer", frequency: 1000, q: 1, gainDb: 3 },
- *     { kind: "channels", mode: "mono" },
+ *     { kind: "equalizer", frequency: 1000, q: 1, gainDb: 3 }, // +3 dB at 1 kHz
+ *     { kind: "channels", mode: "mono" }, // both channels get (L + R) / 2
  *   ],
  * });
  * ```

package/dist/source-resolvers.d.ts

@@ -11,15 +11,40 @@ export type ResolvedResource = {
  * stream(s) behind a page URL. Both streams must use identical `headers`;
  * different maps fail explicitly (nothing is dropped silently).
  *
- * @example
+ * @example Play a page whose video and audio are separate streams
+ * Opening a `https://video.example/…` page plays it with its title. When
+ * the user opens a URL whose scheme and host a web resolver declares, the
+ * player calls its `resolve(url, signal)`; the plugin looks up the streams
+ * and returns them, and the player plays `primary` with the separate
+ * `audio` track, sending the `headers` with every request for both.
  * ```ts
- * const media: ResolvedMedia = {
- *   kind: "media",
- *   originalUrl: url,
- *   title: "Talk",
- *   primary: { url: videoUrl, headers: { Referer: url } },
- *   audio: { url: audioUrl, headers: { Referer: url } },
- * };
+ * plugin.resolvers.add({
+ *   id: "video-example",
+ *   schemes: ["https"],
+ *   hosts: ["video.example"],
+ *   async resolve(url, signal) {
+ *     // The site's own API (made up here) names the streams of a page.
+ *     const api = `https://video.example/api/streams?page=${encodeURIComponent(url)}`;
+ *     const response = await fetch(api, { signal });
+ *     // The player shows a failed resolve's message to the user.
+ *     if (!response.ok)
+ *       throw new Error(`video.example answered ${response.status} for this page`);
+ *     const info = (await response.json()) as {
+ *       title: string;
+ *       video: string;
+ *       audio: string;
+ *     };
+ *     const headers = { Referer: url }; // identical for both streams
+ *     const media: ResolvedMedia = {
+ *       kind: "media",
+ *       originalUrl: url,
+ *       title: info.title,
+ *       primary: { url: info.video, headers },
+ *       audio: { url: info.audio, headers },
+ *     };
+ *     return media;
+ *   },
+ * });
  * ```
  */
 export type ResolvedMedia = {

package/dist/subtitles.d.ts

@@ -16,20 +16,30 @@ export type SubtitleStamp = {
 };
 /**
  * A subtitle style layer ({@link Subtitles.setStyle}). Sizes are at the
- * 1080p reference height and scale with the video. The effective style is
- * the layer of the plugin that set one last; it also applies to the
- * secondary subtitle.
+ * 1080p reference height and scale with the video. Each plugin has one
+ * layer; when several plugins set one, the effective style is the layer of
+ * the plugin whose manifest id sorts last (the order of the calls does not
+ * matter). It also applies to the secondary subtitle.
  *
- * @example
+ * @example Show large yellow subtitles a quarter second earlier
+ * Subtitles turn yellow at size 44 on a 60 % opaque box, 6 % above the
+ * bottom of the video, and appear 250 ms earlier. `refresh` reads the
+ * subtitle state from the player, whose `fonts` lists the font ids a style
+ * may name; `setStyle` then sends this plugin's style layer
+ * (`subtitles.control`, `subtitles.read`). It shows unless another plugin
+ * with a manifest id that sorts later has a layer too: the player picks the
+ * effective layer by manifest id, not by which call came last.
  * ```ts
+ * const { fonts } = await plugin.subtitles.refresh();
+ * if (!fonts.length) return; // no font to name: leave the style alone
  * const style: SubtitleStyle = {
- *   fontId: plugin.subtitles.state!.fonts[0]!.id,
- *   fontSize: 44,
+ *   fontId: fonts[0]!.id, // a font the player offers
+ *   fontSize: 44, // at the 1080p reference height; scales with the video
  *   color: "yellow",
  *   outline: 2,
- *   marginPercent: 6,
- *   offsetMs: -250,
- *   box: 60,
+ *   marginPercent: 6, // bottom margin, % of the video height
+ *   offsetMs: -250, // negative: shown earlier
+ *   box: 60, // background box opacity
  * };
  * await plugin.subtitles.setStyle(style);
  * ```

package/dist/wire.d.ts

@@ -71,16 +71,25 @@ export interface UiCallback {
  * `timeout`, `aborted`, `limit` (a player limit such as the command count),
  * `disabled` (the plugin is stopping).
  *
- * @example
+ * @example Simulate the player refusing a clipboard write in a test
+ * The test proves the plugin sees a refused write as an error with code
+ * `failed`. `host.handle` replaces the test host's handler for one request
+ * method; the `HostError` it throws travels back like the player's own
+ * refusal, so the call rejects with that `code` and is not retried.
+ * `host.reset` puts the default handler back for later steps.
  * ```ts
+ * import assert from "node:assert/strict";
  * import { HostError, startPlugin } from "@vestra-player/sdk/testing";
+ * import activate from "../main.ts";
  *
- * const { host, plugin, stop } = await startPlugin(activate, { directory });
+ * const { host, plugin, stop } = await startPlugin(activate, {
+ *   directory: new URL("..", import.meta.url),
+ * });
  * host.handle("clipboard.writeText", () => {
  *   throw new HostError("failed", "the system refused the write");
  * });
  * await assert.rejects(plugin.clipboard.writeText("x"), { code: "failed" });
- * host.reset("clipboard.writeText");
+ * host.reset("clipboard.writeText"); // writes succeed again
  * await stop();
  * ```
  */

package/dist/wire.js

@@ -31,16 +31,25 @@ export const API_VERSION = "vestra/1";
  * `timeout`, `aborted`, `limit` (a player limit such as the command count),
  * `disabled` (the plugin is stopping).
  *
- * @example
+ * @example Simulate the player refusing a clipboard write in a test
+ * The test proves the plugin sees a refused write as an error with code
+ * `failed`. `host.handle` replaces the test host's handler for one request
+ * method; the `HostError` it throws travels back like the player's own
+ * refusal, so the call rejects with that `code` and is not retried.
+ * `host.reset` puts the default handler back for later steps.
  * ```ts
+ * import assert from "node:assert/strict";
  * import { HostError, startPlugin } from "@vestra-player/sdk/testing";
+ * import activate from "../main.ts";
  *
- * const { host, plugin, stop } = await startPlugin(activate, { directory });
+ * const { host, plugin, stop } = await startPlugin(activate, {
+ *   directory: new URL("..", import.meta.url),
+ * });
  * host.handle("clipboard.writeText", () => {
  *   throw new HostError("failed", "the system refused the write");
  * });
  * await assert.rejects(plugin.clipboard.writeText("x"), { code: "failed" });
- * host.reset("clipboard.writeText");
+ * host.reset("clipboard.writeText"); // writes succeed again
  * await stop();
  * ```
  */