@vestra-player/sdk 1.5.8 → 1.5.11

package/dist/plugin/ui.js

@@ -1,4 +1,6 @@
 /** Tool windows, docked panels and system dialogs. */
+import { shownText, templateArgs } from "./osd.js";
+import { isTextValue } from "../i18n.js";
 import { readFileSync } from "node:fs";
 import { basename, extname, resolve } from "node:path";
 import { failure, Latest, quiet } from "./runtime.js";
@@ -646,15 +648,27 @@ export const panels = (scope) => ({
 });
 export const dialogs = (scope) => {
     const open = async (kind, options = {}) => {
-        const result = await scope.runtime.host.dialogs.open({ kind, ...options });
+        const result = await scope.runtime.host.dialogs.open({
+            kind,
+            ...(options.title === undefined
+                ? {}
+                : { title: shownText(options.title, undefined, "title") }),
+            ...(options.fileName === undefined
+                ? {}
+                : { fileName: shownText(options.fileName, undefined, "fileName") }),
+        });
         return result.cancelled ? [] : result.paths;
     };
     return {
         async confirm(options) {
-            const { message, detail, confirm, cancel, destructive, checkbox } = options ?? {};
-            const length = (text, min, max) => typeof text === "string" &&
-                [...text].length >= min &&
-                [...text].length <= max;
+            const { message, detail, confirm, cancel, destructive, checkbox, args } = options ?? {};
+            const values = templateArgs(args);
+            // A string's length is checked here; a text value's (shown) length by
+            // the player.
+            const length = (text, min, max) => isTextValue(text) ||
+                (typeof text === "string" &&
+                    [...text].length >= min &&
+                    [...text].length <= max);
             if (!length(message, 1, 200) ||
                 !length(confirm, 1, 40) ||
                 (detail !== undefined && !length(detail, 0, 2000)) ||
@@ -662,13 +676,18 @@ export const dialogs = (scope) => {
                 (checkbox !== undefined && !length(checkbox, 1, 40)) ||
                 (destructive !== undefined && typeof destructive !== "boolean"))
                 throw failure("invalid", "confirm needs message 1–200, confirm/cancel/checkbox 1–40, detail ≤ 2000 characters");
+            // `args` fills the string templates; a text value carries its own.
+            const shown = (text, what) => shownText(text, undefined, what);
             const answer = await scope.runtime.host.dialogs.confirm({
-                message,
-                confirm,
-                ...(detail === undefined ? {} : { detail }),
-                ...(cancel === undefined ? {} : { cancel }),
+                message: shown(message, "message"),
+                confirm: shown(confirm, "confirm"),
+                ...(detail === undefined ? {} : { detail: shown(detail, "detail") }),
+                ...(cancel === undefined ? {} : { cancel: shown(cancel, "cancel") }),
                 ...(destructive === undefined ? {} : { destructive }),
-                ...(checkbox === undefined ? {} : { checkbox }),
+                ...(checkbox === undefined
+                    ? {}
+                    : { checkbox: shown(checkbox, "checkbox") }),
+                ...(values === undefined ? {} : { args: values }),
             });
             return {
                 confirmed: answer.confirmed === true,

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/plugin/window.d.ts

@@ -21,6 +21,8 @@ export declare class WindowService {
     appearance: string | undefined;
     /** The file resolvers' extensions, as the reply carried them (`plugin.resolvers.fileTypes`). */
     fileTypes: string[] | undefined;
+    /** The saved interface language, as the reply carried it (`plugin.appearance.language`). */
+    language: string | undefined;
     accept(facts: WindowFacts): void;
     read(): Promise<void>;
     watch(listener: (state: WindowState) => void): {

package/dist/plugin/window.js

@@ -54,9 +54,13 @@ export class WindowService {
     appearance;
     /** The file resolvers' extensions, as the reply carried them (`plugin.resolvers.fileTypes`). */
     fileTypes;
+    /** The saved interface language, as the reply carried it (`plugin.appearance.language`). */
+    language;
     accept(facts) {
         if (facts.appearance)
             this.appearance = facts.appearance;
+        if (facts.language)
+            this.language = facts.language;
         if (Array.isArray(facts.fileTypes))
             this.fileTypes = [...facts.fileTypes];
         const next = view(facts);

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";
@@ -112,6 +113,13 @@ export interface PackageInfo {
         slot?: string;
         owner?: string;
     }[];
+    /** The manifest's display texts in the interface language (player 0.4.3). */
+    display?: {
+        name: string | null;
+        punchline: string | null;
+        description: string | null;
+        tags: string[];
+    };
 }
 /** Where an installed package came from (`packages.install` `source`). */
 export type WireSource = {
@@ -134,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[];
@@ -171,6 +181,10 @@ export interface WindowFacts {
     appearance?: string;
     /** The file resolvers' extensions (`plugin.resolvers.fileTypes`; player 0.4.2). */
     fileTypes?: string[];
+    /** The saved interface language, `"system"` or a locale (player 0.4.3). */
+    language?: string;
+    /** The interface language of this run (player 0.4.3). */
+    locale?: string;
 }
 /** One timeline mark as the player merges them (`timeline.marks`). */
 export interface WireMark {
@@ -276,11 +290,25 @@ export interface WireSystemInfo {
         primary: boolean;
     }[];
 }
+/**
+ * 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;
     /** Replaces the real local services (test host). */
     local?: LocalServices;
+    /**
+     * The interface language of this run (`plugin.i18n.locale`): the runner
+     * passes the player's `VESTRA_LOCALE`, the test host its `locale`.
+     */
+    locale?: string;
 }
 export declare function createWire(transport: Transport): {
     processing: {
@@ -300,12 +328,13 @@ 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[];
         }>;
+        /** Message and detail are templates formatted with `args` (player 0.4.3). */
         confirm: (options: {
             [key: string]: Json;
         }) => Promise<{
@@ -351,6 +380,8 @@ export declare function createWire(transport: Transport): {
     /** The palette (`ui.theme` to change it). */
     appearance: {
         set: (theme: string) => Promise<void>;
+        /** The interface language for the next start (player 0.4.3). */
+        setLanguage: (language: string) => Promise<void>;
     };
     /** Settings pages in the player's options window (`ui.settings`). */
     settings: {
@@ -400,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;
         }>;
@@ -469,9 +500,10 @@ export declare function createWire(transport: Transport): {
         } | null) => Promise<void>;
         step: (direction: "next" | "previous") => Promise<void>;
     };
+    /** `text` is a template in the plugin's catalog, formatted with `args` (player 0.4.3). */
     osd: {
-        show: (text: string) => Promise<void>;
-        panel: (text: string | null) => Promise<void>;
+        show: (text: TextValueJson, args?: TemplateArgsJson) => Promise<void>;
+        panel: (text: TextValueJson | null, args?: TemplateArgsJson, maxColumns?: number) => Promise<void>;
     };
     layout: {
         state: () => Promise<{
@@ -642,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

@@ -69,6 +69,7 @@ export function createWire(transport) {
         commands: commandClient(transport),
         dialogs: {
             open: (options) => transport.request("dialogs.open", options),
+            /** Message and detail are templates formatted with `args` (player 0.4.3). */
             confirm: (options) => transport.request("dialogs.confirm", options),
         },
         /** The main window: its state, size, level, pointer hiding and picture-in-picture. */
@@ -99,6 +100,8 @@ export function createWire(transport) {
         /** The palette (`ui.theme` to change it). */
         appearance: {
             set: (theme) => transport.request("appearance.set", { theme }),
+            /** The interface language for the next start (player 0.4.3). */
+            setLanguage: (language) => transport.request("appearance.setLanguage", { language }),
         },
         /** Settings pages in the player's options window (`ui.settings`). */
         settings: {
@@ -190,9 +193,17 @@ export function createWire(transport) {
             set: (flags) => transport.request("sequence.set", { flags }),
             step: (direction) => transport.request("sequence.step", { direction }),
         },
+        /** `text` is a template in the plugin's catalog, formatted with `args` (player 0.4.3). */
         osd: {
-            show: (text) => transport.request("osd.show", { text }),
-            panel: (text) => transport.request("osd.panel", { text }),
+            show: (text, args) => transport.request("osd.show", {
+                text,
+                ...(args === undefined ? {} : { args }),
+            }),
+            panel: (text, args, maxColumns) => transport.request("osd.panel", {
+                text,
+                ...(args === undefined ? {} : { args }),
+                ...(maxColumns === undefined ? {} : { maxColumns }),
+            }),
         },
         layout: {
             state: () => transport.request("layout.state"),