@vestra-player/sdk 1.5.9 → 1.5.11

package/dist/plugin/values.d.ts

@@ -0,0 +1,55 @@
+/** The player's limits on one property value, for {@link TestHost}. */
+import type { Json } from "../wire.ts";
+/**
+ * The player's limits on one property value (a `PropValue` as written
+ * by `View.set` or `View.bind`, or an initial property of a
+ * window, panel or settings page). The player's tests check that these
+ * agree with the player; {@link TestHost} enforces them the same way.
+ *
+ * A value over a limit is refused whole with code `limit` (the property
+ * keeps what it showed) and reported to `Scope.onError`: a write by
+ * `View.set` or `View.bind` as described there. As an initial property it
+ * makes `Window.show` reject; a panel or settings page opens without it and
+ * the failure goes to the plugin's `onError`.
+ *
+ * They bound the work one write costs the player's interface thread; they
+ * are not meant as list sizes to aim for. A list that can grow without
+ * bound (a playlist, a history) should send the rows near the view and say
+ * how many there are, not the whole list.
+ *
+ * @example
+ * ```ts
+ * 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;
+ * ```
+ *
+ * @since 1.5.10
+ */
+export declare const UI_VALUE_LIMITS: {
+    /** Nesting depth; the value itself is depth 0 (8). */
+    readonly depth: 8;
+    /**
+     * Values in all, counting every array, object, string, number, boolean
+     * and null, the value itself included; a Markdown document is one
+     * (16384).
+     */
+    readonly values: 16384;
+    /** Rows of one array (4096). */
+    readonly arrayRows: 4096;
+    /** UTF-8 bytes of one string or object field name (64 KiB). */
+    readonly stringBytes: number;
+    /**
+     * UTF-8 bytes of all strings and field names together, the text of the
+     * value's Markdown documents included (1 MiB).
+     */
+    readonly textBytes: number;
+};
+/**
+ * Why the player would refuse `value` (in wire form) as a property value,
+ * or `null`. The same checks, order and messages as the player's
+ * conversion (`host/src/ui_values.rs`). An image reference as the whole
+ * value is not counted (the player loads it instead).
+ */
+export declare function valueLimitProblem(value: Json): string | null;

package/dist/plugin/values.js

@@ -0,0 +1,117 @@
+/**
+ * The player's limits on one property value (a `PropValue` as written
+ * by `View.set` or `View.bind`, or an initial property of a
+ * window, panel or settings page). The player's tests check that these
+ * agree with the player; {@link TestHost} enforces them the same way.
+ *
+ * A value over a limit is refused whole with code `limit` (the property
+ * keeps what it showed) and reported to `Scope.onError`: a write by
+ * `View.set` or `View.bind` as described there. As an initial property it
+ * makes `Window.show` reject; a panel or settings page opens without it and
+ * the failure goes to the plugin's `onError`.
+ *
+ * They bound the work one write costs the player's interface thread; they
+ * are not meant as list sizes to aim for. A list that can grow without
+ * bound (a playlist, a history) should send the rows near the view and say
+ * how many there are, not the whole list.
+ *
+ * @example
+ * ```ts
+ * 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;
+ * ```
+ *
+ * @since 1.5.10
+ */
+export const UI_VALUE_LIMITS = {
+    /** Nesting depth; the value itself is depth 0 (8). */
+    depth: 8,
+    /**
+     * Values in all, counting every array, object, string, number, boolean
+     * and null, the value itself included; a Markdown document is one
+     * (16384).
+     */
+    values: 16384,
+    /** Rows of one array (4096). */
+    arrayRows: 4096,
+    /** UTF-8 bytes of one string or object field name (64 KiB). */
+    stringBytes: 64 * 1024,
+    /**
+     * UTF-8 bytes of all strings and field names together, the text of the
+     * value's Markdown documents included (1 MiB).
+     */
+    textBytes: 1024 * 1024,
+};
+const L = UI_VALUE_LIMITS;
+const bytes = (text) => Buffer.byteLength(text, "utf8");
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** Text of a Markdown document in wire form, or `null` for other JSON. */
+function documentText(value) {
+    if (!isObject(value))
+        return null;
+    const doc = value.$vestraMarkdown;
+    return isObject(doc) && typeof doc.text === "string" ? doc.text : null;
+}
+/**
+ * Why the player would refuse `value` (in wire form) as a property value,
+ * or `null`. The same checks, order and messages as the player's
+ * conversion (`host/src/ui_values.rs`). An image reference as the whole
+ * value is not counted (the player loads it instead).
+ */
+export function valueLimitProblem(value) {
+    if (isObject(value) && "$vestraImage" in value)
+        return null;
+    const budget = { values: 0, text: 0 };
+    const text = (s) => {
+        const n = bytes(s);
+        if (n > L.stringBytes)
+            return `UI string or field name exceeds ${L.stringBytes} bytes`;
+        if (budget.text + n > L.textBytes)
+            return `UI value text exceeds ${L.textBytes} total bytes`;
+        budget.text += n;
+        return null;
+    };
+    const walk = (value, depth) => {
+        if (depth > L.depth)
+            return `UI value depth exceeds ${L.depth} (root is depth 0)`;
+        if (budget.values === L.values)
+            return `UI value exceeds ${L.values} total nodes`;
+        budget.values += 1;
+        const doc = documentText(value);
+        if (doc !== null) {
+            const n = bytes(doc);
+            if (budget.text + n > L.textBytes)
+                return `UI value text exceeds ${L.textBytes} total bytes`;
+            budget.text += n;
+            return null;
+        }
+        if (typeof value === "string")
+            return text(value);
+        if (Array.isArray(value)) {
+            if (value.length > L.arrayRows)
+                return `UI array exceeds ${L.arrayRows} rows`;
+            if (value.length > L.values - budget.values)
+                return "UI array cannot fit in remaining node budget";
+            for (const item of value) {
+                const problem = walk(item, depth + 1);
+                if (problem)
+                    return problem;
+            }
+            return null;
+        }
+        if (isObject(value)) {
+            const entries = Object.entries(value);
+            if (entries.length > L.values - budget.values)
+                return "UI object cannot fit in remaining node budget";
+            for (const [name, item] of entries) {
+                const problem = text(name) ?? walk(item, depth + 1);
+                if (problem)
+                    return problem;
+            }
+        }
+        return null;
+    };
+    return walk(value, 0);
+}

package/dist/source-resolvers.d.ts

@@ -1,4 +1,3 @@
-/** Trusted extraction providers. Declarations cross JSON; handler code stays in JS. */
 import type { Transport } from "./wire.ts";
 /** One stream of a {@link ResolvedMedia}. */
 export type ResolvedResource = {

package/dist/source-resolvers.js

@@ -1,6 +1,14 @@
+/** Trusted extraction providers. Declarations cross JSON; handler code stays in JS. */
+import { isTextValue, textProblem } from "./i18n.js";
 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);
+const reason = (error) => {
+    // `plugin.i18n.error(…)`: the player shows the text translated.
+    const text = error?.text;
+    if (error instanceof Error && isTextValue(text) && !textProblem(text))
+        return text;
+    return (error instanceof Error ? error.message : String(error)).slice(0, 2048);
+};
 export function sourceResolverClient(transport) {
     return {
         /** Requires source.resolve. One registered host/scheme pair, and one file

package/dist/subtitles.d.ts

@@ -1,4 +1,5 @@
 /** Subtitle wire types; source pixels and renderer confirmation remain distinct. */
+import type { TextJson } from "./i18n.ts";
 import type { Transport } from "./wire.ts";
 export type SubtitleTrack = {
     kind: "embedded";
@@ -169,7 +170,8 @@ export declare function subtitleClient(transport: Transport): {
         expected: SubtitleStamp;
         inputOrigin?: SubtitleTrack;
         format?: "srt" | "ass";
-        title?: string;
+        /** Source text is data; a text value is shown translated (player 0.4.3). */
+        title?: string | TextJson;
         select?: "primary" | "secondary" | "none";
     }) => Promise<SubtitleState>;
     select: (target: SubtitleTrack | null, expected: SubtitleStamp, operationId: number, role?: "primary" | "secondary") => Promise<SubtitleState>;

package/dist/wire.d.ts

@@ -1,4 +1,5 @@
 import type { SourceAudioTrack, SourceStamp } from "./source.ts";
+import type { ArgJson, ListJson, TextJson } from "./i18n.ts";
 export type { ResolvedMedia, ResolvedResource, SourceResolverDeclaration, } from "./source-resolvers.ts";
 /** Working contract. Trusted plugin runtime, not a permissions sandbox. */
 export declare const API_VERSION: "vestra/1";
@@ -141,6 +142,8 @@ export interface BindingTable {
         command: string;
         title: string;
         path: string[] | null;
+        /** The path's keys (player 0.4.3). */
+        key?: string[] | null;
         scope: "global" | "panel";
         defaults: string[];
         current: string[];
@@ -287,10 +290,15 @@ export interface WireSystemInfo {
         primary: boolean;
     }[];
 }
-/** Template arguments on the wire (`osd.show`, `osd.panel`, `dialogs.confirm`). */
-export type TemplateArgsJson = (string | number)[] | {
-    [name: string]: string | number;
+/**
+ * Template arguments on the wire (`osd.show`, `osd.panel`, `dialogs.confirm`,
+ * a text's `args`): data, or text values (player 0.4.3).
+ */
+export type TemplateArgsJson = ArgJson[] | {
+    [name: string]: ArgJson;
 };
+/** A text the player shows: source text, or a text value (player 0.4.3). */
+export type TextValueJson = string | TextJson | ListJson;
 export interface Transport {
     request<T>(method: string, params?: Json): Promise<T>;
     on(event: string, listener: (data: unknown) => void): () => void;
@@ -320,8 +328,8 @@ export declare function createWire(transport: Transport): {
     dialogs: {
         open: (options: {
             kind: "openFile" | "openFiles" | "openDirectory" | "saveFile";
-            title?: string;
-            fileName?: string;
+            title?: TextValueJson;
+            fileName?: TextValueJson;
         }) => Promise<{
             cancelled: boolean;
             paths: string[];
@@ -423,7 +431,7 @@ export declare function createWire(transport: Transport): {
         set: (marks: {
             time: number;
             kind: string;
-            title?: string;
+            title?: string | TextJson;
         }[], sourceId?: number) => Promise<{
             applied: boolean;
         }>;
@@ -494,8 +502,8 @@ export declare function createWire(transport: Transport): {
     };
     /** `text` is a template in the plugin's catalog, formatted with `args` (player 0.4.3). */
     osd: {
-        show: (text: string, args?: TemplateArgsJson) => Promise<void>;
-        panel: (text: string | null, args?: TemplateArgsJson) => Promise<void>;
+        show: (text: TextValueJson, args?: TemplateArgsJson) => Promise<void>;
+        panel: (text: TextValueJson | null, args?: TemplateArgsJson, maxColumns?: number) => Promise<void>;
     };
     layout: {
         state: () => Promise<{
@@ -666,7 +674,7 @@ export declare function createWire(transport: Transport): {
             expected: import("./subtitles.ts").SubtitleStamp;
             inputOrigin?: import("./subtitles.ts").SubtitleTrack;
             format?: "srt" | "ass";
-            title?: string;
+            title?: string | TextJson;
             select?: "primary" | "secondary" | "none";
         }) => Promise<import("./subtitles.ts").SubtitleState>;
         select: (target: import("./subtitles.ts").SubtitleTrack | null, expected: import("./subtitles.ts").SubtitleStamp, operationId: number, role?: "primary" | "secondary") => Promise<import("./subtitles.ts").SubtitleState>;

package/dist/wire.js

@@ -199,9 +199,10 @@ export function createWire(transport) {
                 text,
                 ...(args === undefined ? {} : { args }),
             }),
-            panel: (text, args) => transport.request("osd.panel", {
+            panel: (text, args, maxColumns) => transport.request("osd.panel", {
                 text,
                 ...(args === undefined ? {} : { args }),
+                ...(maxColumns === undefined ? {} : { maxColumns }),
             }),
         },
         layout: {