@vestra-player/sdk 1.5.9 → 1.5.11

package/dist/plugin/commands.js

@@ -2,6 +2,7 @@
 import { failure, Latest, quiet } from "./runtime.js";
 import { checkBindings } from "./bindings.js";
 import { MENU_IDS } from "../commands.js";
+import { isTextValue, textProblem } from "../i18n.js";
 const value = (item) => typeof item === "function" ? item() : item;
 /** Validate options and build the wire declaration. */
 function declare(options) {
@@ -11,7 +12,18 @@ function declare(options) {
         throw failure("invalid", `command ${options.id}: title or path required`);
     if (path.length > 8)
         throw failure("invalid", `command ${options.id}: path has 1–8 segments`);
-    const menu = path[0]?.startsWith("@") ? path[0].slice(1) : null;
+    for (const segment of [title, ...path])
+        if (typeof segment !== "string") {
+            const problem = isTextValue(segment)
+                ? "$vestraList" in segment
+                    ? "a menu text is a string or a text, not a list"
+                    : textProblem(segment)
+                : "title and path segments are strings or texts";
+            if (problem)
+                throw failure("invalid", `command ${options.id}: ${problem}`);
+        }
+    const first = path[0];
+    const menu = typeof first === "string" && first.startsWith("@") ? first.slice(1) : null;
     if (menu !== null && !MENU_IDS.includes(menu))
         throw failure("invalid", `command ${options.id}: unknown menu id @${menu}; the built-in menus are ${MENU_IDS.map((id) => `@${id}`).join(", ")}`);
     if (menu !== null && path.length < 2)
@@ -21,8 +33,8 @@ function declare(options) {
         throw failure("invalid", `command ${options.id}: order must be an integer within ±1000000`);
     const bindings = [...(options.bindings ?? [])];
     return {
-        title,
-        path,
+        title: title,
+        path: path,
         order,
         group: options.group ?? "domain",
         radio: options.radio ?? false,
@@ -89,11 +101,19 @@ class CommandHandle {
         scope.add(this);
     }
     #state() {
+        const reason = value(this.#spec.reason);
+        if (reason !== null && typeof reason !== "string") {
+            const problem = isTextValue(reason)
+                ? textProblem(reason)
+                : "reason is a string, a text or null";
+            if (problem)
+                throw failure("invalid", `command ${this.id}: ${problem}`);
+        }
         return {
             enabled: value(this.#spec.enabled),
             checked: value(this.#spec.checked),
             busy: value(this.#spec.busy),
-            reason: value(this.#spec.reason),
+            reason,
         };
     }
     #sync() {

package/dist/plugin/index.js

@@ -1,4 +1,4 @@
-import { Runtime } from "./runtime.js";
+import { failure, Runtime } from "./runtime.js";
 import { ScopeImpl } from "./scope.js";
 import { playerOf } from "./player.js";
 import { windowOf } from "./window.js";
@@ -14,6 +14,14 @@ app) {
         timelineOf(runtime).init(),
     ]);
     const root = new ScopeImpl(runtime);
+    // Failures the plugin did not ask about: a property the player could not
+    // show when it rebuilt a panel or the Options window (an image removed
+    // since), a callback whose arguments it could not convert, a detached
+    // sidebar that could not be prepared. Older players send no code.
+    root.add(runtime.raw("ui.error", (data) => {
+        const { code, message } = (data ?? {});
+        root.report(failure(code ?? "ui", message ?? "user interface error"));
+    }));
     return {
         plugin: root,
         activated: () => runtime.activated(),

package/dist/plugin/language.d.ts

@@ -1,4 +1,8 @@
-/** `plugin.i18n`: the interface language of this run (read-only). */
 import type { ScopeImpl } from "./scope.ts";
-import type { I18n } from "./types.ts";
+import type { I18n, ListStyle, TemplateArgs, Text, TextArg, TextError, TextList } from "./types.ts";
+/** `plugin.i18n.text`: a plain, frozen text value (no translation here). */
+export declare function text(source: string, args?: TemplateArgs): Text;
+/** `plugin.i18n.list`: a plain, frozen list value. */
+export declare function list(items: readonly TextArg[], style?: ListStyle): TextList;
+export declare const error: (source: string, args?: TemplateArgs) => TextError;
 export declare const i18n: (scope: ScopeImpl) => I18n;

package/dist/plugin/language.js

@@ -1,5 +1,79 @@
+/** `plugin.i18n`: the interface language of this run and text values (read-only). */
+import { Catalog, isTextValue, LIST_STYLES, loadPackageCatalog, renderText, textKey, textProblem, } from "../i18n.js";
+import { failure } from "./runtime.js";
+/** Copy arguments (arrays and objects only; texts are already frozen). */
+const copyArgs = (args) => Array.isArray(args) ? Object.freeze([...args]) : Object.freeze({ ...args });
+/** `plugin.i18n.text`: a plain, frozen text value (no translation here). */
+export function text(source, args) {
+    const value = { $vestraText: source };
+    if (args !== undefined && args !== null)
+        value.args = copyArgs(args);
+    const problem = textProblem(value);
+    if (problem)
+        throw failure("invalid", `text: ${problem}`);
+    return Object.freeze(value);
+}
+/** `plugin.i18n.list`: a plain, frozen list value. */
+export function list(items, style) {
+    if (!Array.isArray(items))
+        throw failure("invalid", "list: items is an array");
+    if (style !== undefined &&
+        !LIST_STYLES.includes(style))
+        throw failure("invalid", `list: style is one of ${LIST_STYLES.join(", ")}`);
+    const value = {
+        $vestraList: Object.freeze([
+            ...items,
+        ]),
+        ...(style === undefined ? {} : { style }),
+    };
+    const problem = textProblem(value);
+    if (problem)
+        throw failure("invalid", `list: ${problem}`);
+    return Object.freeze(value);
+}
+/** `plugin.i18n.error`: an Error whose message the player shows translated. */
+class TextErrorImpl extends Error {
+    text;
+    constructor(value) {
+        super(textKey(value));
+        this.name = "TextError";
+        this.text = value;
+    }
+}
+export const error = (source, args) => new TextErrorImpl(text(source, args));
+/** The plugin's catalog for this run's language, read once per runtime. */
+const catalogs = new WeakMap();
+function catalogOf(scope) {
+    const runtime = scope.runtime;
+    let catalog = catalogs.get(runtime);
+    if (!catalog) {
+        try {
+            catalog = loadPackageCatalog(runtime.directory, runtime.locale);
+        }
+        catch (error) {
+            // As the player: a broken catalog is reported and treated as missing.
+            console.error(`[${scope.id}] i18n: ${error.message}`);
+            catalog = new Catalog();
+        }
+        catalogs.set(runtime, catalog);
+    }
+    return catalog;
+}
 export const i18n = (scope) => Object.freeze({
     get locale() {
         return scope.runtime.locale;
     },
+    text,
+    list,
+    error,
+    resolve(value) {
+        if (typeof value === "string")
+            return catalogOf(scope).text(value);
+        const problem = isTextValue(value)
+            ? textProblem(value)
+            : "resolve takes a string or a text value";
+        if (problem)
+            throw failure("invalid", `resolve: ${problem}`);
+        return renderText(value, catalogOf(scope), scope.runtime.locale);
+    },
 });

package/dist/plugin/osd.d.ts

@@ -1,6 +1,14 @@
 import type { ScopeImpl } from "./scope.ts";
 import type { Osd } from "./types.ts";
-import type { TemplateArgsJson } from "../wire.ts";
-/** Copy and check template arguments: an array or object of ≤ 16 strings and numbers. */
+import type { TemplateArgsJson, TextValueJson } from "../wire.ts";
+/**
+ * Copy and check template arguments: an array or object of at most 16
+ * strings, finite numbers, texts and lists (`TEXT_LIMITS`).
+ */
 export declare function templateArgs(args: unknown): TemplateArgsJson | undefined;
+/**
+ * Check a shown text (`osd.show`, dialogs): source text, or a text value
+ * that carries its own arguments (then `args` is not given).
+ */
+export declare function shownText(text: unknown, args: unknown, what?: string): TextValueJson;
 export declare const osd: (scope: ScopeImpl) => Osd;

package/dist/plugin/osd.js

@@ -1,24 +1,38 @@
 /** On-screen display: a transient line and a persistent information block. */
 import { Latest } from "./runtime.js";
 import { failure } from "./runtime.js";
-/** Copy and check template arguments: an array or object of ≤ 16 strings and numbers. */
+import { isTextValue, textProblem } from "../i18n.js";
+/**
+ * Copy and check template arguments: an array or object of at most 16
+ * strings, finite numbers, texts and lists (`TEXT_LIMITS`).
+ */
 export function templateArgs(args) {
     if (args === undefined || args === null)
         return undefined;
-    const values = Array.isArray(args)
-        ? args
-        : typeof args === "object"
-            ? Object.values(args)
-            : null;
-    if (!values ||
-        values.length > 16 ||
-        values.some((value) => !((typeof value === "number" && Number.isFinite(value)) ||
-            typeof value === "string")))
-        throw failure("invalid", "args is an array or object of at most 16 strings and finite numbers");
+    const problem = textProblem(args, "args");
+    if (problem)
+        throw failure("invalid", problem);
     return Array.isArray(args)
         ? [...args]
         : { ...args };
 }
+/**
+ * Check a shown text (`osd.show`, dialogs): source text, or a text value
+ * that carries its own arguments (then `args` is not given).
+ */
+export function shownText(text, args, what = "text") {
+    if (typeof text === "string")
+        return text;
+    if (isTextValue(text)) {
+        const problem = textProblem(text);
+        if (problem)
+            throw failure("invalid", `${what}: ${problem}`);
+        if (args !== undefined && args !== null)
+            throw failure("invalid", `${what} is a text value: its args go inside it, not in args`);
+        return text;
+    }
+    throw failure("invalid", `${what} is a string or a text value`);
+}
 class PanelHandle {
     #scope;
     #pump;
@@ -30,19 +44,24 @@ class PanelHandle {
             throw new Error("a plugin can have only one osd panel");
         scope.runtime.services.set("osd.panel", this);
         this.#scope = scope;
-        this.#pump = new Latest(({ text, args }) => scope.runtime.host.osd.panel(text, args));
+        this.#pump = new Latest(({ text, args, maxColumns }) => scope.runtime.host.osd.panel(text, args, maxColumns));
         scope.add(this);
     }
-    set(text, args) {
+    set(text, args, options = {}) {
         if (this.#disposed)
             return;
         let value;
         try {
+            const max = options?.maxColumns;
+            if (max !== undefined &&
+                !(Number.isInteger(max) && max >= 8 && max <= 1000))
+                throw failure("invalid", "maxColumns is an integer from 8 to 1000");
             value = {
-                text,
-                ...(text === null || args === undefined
+                text: text === null ? null : shownText(text, args),
+                ...(text === null || args === undefined || args === null
                     ? {}
                     : { args: templateArgs(args) }),
+                ...(text === null || max === undefined ? {} : { maxColumns: max }),
             };
         }
         catch (error) {
@@ -67,6 +86,6 @@ class PanelHandle {
     }
 }
 export const osd = (scope) => ({
-    show: async (text, args) => scope.runtime.host.osd.show(text, templateArgs(args)),
+    show: async (text, args) => scope.runtime.host.osd.show(shownText(text, args), templateArgs(args)),
     panel: () => new PanelHandle(scope),
 });

package/dist/plugin/subtitles.js

@@ -1,5 +1,6 @@
 /** Subtitle selection, external SRT resources and this plugin's style layer. */
 import { createHash } from "node:crypto";
+import { isTextValue, textProblem } from "../i18n.js";
 import { Latest, failure, sleep, uncertain } from "./runtime.js";
 import { abortError } from "./player.js";
 const raws = new WeakMap();
@@ -226,7 +227,14 @@ export function subtitles(scope) {
             if (select !== "primary" && select !== "secondary" && select !== "none")
                 throw failure("invalid", 'select must be "primary", "secondary" or "none"');
             const title = options?.title;
-            if (title !== undefined &&
+            // A text value (`plugin.i18n.text`) is checked here and its shown
+            // length by the player.
+            if (isTextValue(title)) {
+                const problem = textProblem(title);
+                if (problem)
+                    throw failure("invalid", `title: ${problem}`);
+            }
+            else if (title !== undefined &&
                 (typeof title !== "string" ||
                     [...title].length < 1 ||
                     [...title].length > 200))

package/dist/plugin/testing.d.ts

@@ -3,17 +3,36 @@ import { HostError } from "../wire.ts";
 import type { PackageManifest, PackageSource } from "./types.ts";
 import type { Json, LayoutSlot, LocalServices, PlaybackStats, Transport, WireSystemInfo } from "../wire.ts";
 import { COMMAND_LIMITS, MENU_IDS } from "../commands.ts";
+import { UI_VALUE_LIMITS } from "./values.ts";
 import type { CommandDeclaration } from "../commands.ts";
 import type { SourceState } from "../source.ts";
 import type { SubtitleState } from "../subtitles.ts";
 import type { RenderSettings, ViewSettings } from "./types.ts";
 import type { MediaJob } from "../media.ts";
-import type { LanguagePreference, Locale, Plugin, TemplateArgs, ThemeId } from "./types.ts";
-import { LOCALES } from "../i18n.ts";
+import type { LanguagePreference, Locale, Plugin, TemplateArgs, TextValue, ThemeId } from "./types.ts";
+import { LOCALES, LIST_SEPARATORS, TEXT_LIMITS } from "../i18n.ts";
 /** Throw one of these from `host.handle(...)` to simulate a definite refusal. */
 export { HostError };
 /** The player's command caps, which the test host enforces as well. */
 export { COMMAND_LIMITS, MENU_IDS };
+/** The player's property value limits, which the test host enforces as well. */
+export { UI_VALUE_LIMITS };
+/**
+ * The player's limits on one text value ({@link Text}, {@link TextList},
+ * with everything nested in it), which the test host enforces as well:
+ * nesting depth 8, 1024 texts, lists and arguments in all, 16 arguments per
+ * text, 256 items per list, 4096 bytes per source text or string argument.
+ *
+ * @since 1.5.11
+ */
+export { TEXT_LIMITS };
+/**
+ * The separator of each {@link ListStyle} per interface language, as the
+ * player joins a {@link TextList}.
+ *
+ * @since 1.5.11
+ */
+export { LIST_SEPARATORS };
 /**
  * The player's interface languages, English (the source) first, as the
  * player's own table: `["en", "zh-Hans", "ja", "ko", "de", "fr", "es"]`.
@@ -76,6 +95,19 @@ export interface FakeWindow {
      */
     userClose(): void;
 }
+/**
+ * A file dialog as the player shows it ({@link TestHost.fileDialogs}).
+ *
+ * @since 1.5.11
+ */
+export interface FileDialogText {
+    /** Which dialog. */
+    kind: "openFile" | "openFiles" | "openDirectory" | "saveFile";
+    /** Its title as shown, if the plugin gave one. */
+    title?: string;
+    /** The proposed file name as shown, if the plugin gave one. */
+    fileName?: string;
+}
 /**
  * A command the plugin registered with `plugin.commands.add`, as the test
  * host keeps it. Get one with {@link TestHost.command} (the plugin's own) or
@@ -110,6 +142,14 @@ export interface FakeCommand {
         title: string;
         /** Each segment of the path as shown; empty without a path. */
         path: string[];
+        /**
+         * The disabled or busy reason as shown, `null` without one (a plugin
+         * command's; not enumerable, so comparing `display` with
+         * `{ title, path }` still works).
+         *
+         * @since 1.5.11
+         */
+        reason?: string | null;
     };
     /** The command state the player last received (after the update pass). */
     state: {
@@ -119,8 +159,8 @@ export interface FakeCommand {
         checked: boolean | null;
         /** `true` while the plugin reports the command as busy. */
         busy: boolean;
-        /** The reason shown when the command is disabled or busy. */
-        reason: string | null;
+        /** The reason the plugin sent (source text or a text value; see `display.reason`). */
+        reason: TextValue | null;
     };
     /**
      * The state revision the player holds; increases with every state update
@@ -348,7 +388,7 @@ export declare class TestHost implements Transport {
      *
      * @since 1.5.9
      */
-    translate(text: string, args?: TemplateArgs): string;
+    translate(text: TextValue, args?: TemplateArgs): string;
     /**
      * The saved interface language (`plugin.appearance.language`), changed by
      * `appearance.setLanguage` or {@link TestHost.setLanguage}.
@@ -383,6 +423,15 @@ export declare class TestHost implements Transport {
         /** The checkbox, if any. */
         checkbox?: string;
     }[];
+    /**
+     * Every file dialog (`openFile`, `openFiles`, `openDirectory`,
+     * `saveFile`) as the player shows it: the title translated, a text file
+     * name translated, newest last. The options the plugin sent are in
+     * `host.sent("dialogs.open")`.
+     *
+     * @since 1.5.11
+     */
+    readonly fileDialogs: FileDialogText[];
     /** The sequence provider's flags, `null` without a provider. */
     sequence: {
         /** The provider's `canNext`, as last evaluated. */