@vestra-player/sdk 1.5.8 → 1.5.11

package/dist/player-runtime.d.ts

@@ -13,5 +13,7 @@ export { HostError } from "./wire.ts";
 export type { Json, Transport } from "./wire.ts";
 export { API_VERSION, CAPABILITIES } from "./capabilities.ts";
 export { COMMAND_LIMITS, MENU_IDS } from "./commands.ts";
+export { Catalog, HOST_ZH_HANS, LIST_SEPARATORS, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, renderText, scanSlint, TEXT_LIMITS, textKey, textProblem, } from "./i18n.ts";
 export { MANIFEST_FIELDS, MANIFEST_LIMITS } from "./manifest.ts";
 export { MARKDOWN_LIMITS } from "./plugin/markdown.ts";
+export { UI_VALUE_LIMITS } from "./plugin/values.ts";

package/dist/player-runtime.js

@@ -11,5 +11,7 @@ export { createPlugin } from "./plugin/index.js";
 export { HostError } from "./wire.js";
 export { API_VERSION, CAPABILITIES } from "./capabilities.js";
 export { COMMAND_LIMITS, MENU_IDS } from "./commands.js";
+export { Catalog, HOST_ZH_HANS, LIST_SEPARATORS, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, renderText, scanSlint, TEXT_LIMITS, textKey, textProblem, } from "./i18n.js";
 export { MANIFEST_FIELDS, MANIFEST_LIMITS } from "./manifest.js";
 export { MARKDOWN_LIMITS } from "./plugin/markdown.js";
+export { UI_VALUE_LIMITS } from "./plugin/values.js";

package/dist/plugin/appearance.js

@@ -1,6 +1,10 @@
 /** The player's palette (`plugin.appearance`; `ui.theme` to change it). */
 import { failure } from "./runtime.js";
 import { windowOf } from "./window.js";
+import { LOCALES } from "../i18n.js";
+const preference = (value) => value === "system" || LOCALES.includes(value)
+    ? value
+    : undefined;
 /** The palettes this SDK knows, the default first. */
 export const THEMES = ["vestra", "vestra-light"];
 /**
@@ -11,19 +15,28 @@ export const THEMES = ["vestra", "vestra-light"];
 class AppearanceService {
     #runtime;
     theme;
+    /** The saved interface language (the next start's). */
+    language;
     #listeners = new Set();
     #started = false;
     constructor(runtime) {
         this.#runtime = runtime;
         this.theme =
             windowOf(runtime).appearance ?? "vestra";
+        this.language = preference(windowOf(runtime).language) ?? "system";
     }
     start() {
         if (this.#started)
             return;
         this.#started = true;
         this.#runtime.on("appearance.changed", (data) => {
-            const theme = data?.theme;
+            const event = data;
+            const language = preference(event?.language);
+            if (language && language !== this.language) {
+                this.language = language;
+                this.#runtime.invalidate();
+            }
+            const theme = event?.theme;
             if (theme && THEMES.includes(theme))
                 this.accept(theme);
         });
@@ -65,5 +78,18 @@ export function appearance(scope) {
             await scope.runtime.host.appearance.set(theme);
             service().accept(theme);
         },
+        get language() {
+            service().start();
+            return service().language;
+        },
+        async setLanguage(language) {
+            if (!preference(language))
+                throw failure("invalid", `language is "system" or one of ${LOCALES.map((l) => `"${l}"`).join(", ")}`);
+            await scope.runtime.host.appearance.setLanguage(language);
+            if (service().language !== language) {
+                service().language = language;
+                scope.runtime.invalidate();
+            }
+        },
     };
 }

package/dist/plugin/bindings.js

@@ -110,6 +110,7 @@ export const bindingsApi = (scope) => ({
                 command: info.command,
                 title: info.title,
                 path: info.path,
+                key: info.key ?? null,
                 scope: info.scope,
                 defaults: info.defaults,
                 current: info.current,

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

@@ -0,0 +1,8 @@
+import type { ScopeImpl } from "./scope.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

@@ -0,0 +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,3 +1,14 @@
 import type { ScopeImpl } from "./scope.ts";
 import type { Osd } from "./types.ts";
+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,23 +1,78 @@
 /** On-screen display: a transient line and a persistent information block. */
 import { Latest } from "./runtime.js";
+import { failure } from "./runtime.js";
+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 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;
-    #last = null;
+    /** The last value sent, as JSON (`null` text: hidden). */
+    #last = JSON.stringify({ text: null });
     #disposed = false;
     constructor(scope) {
         if (scope.runtime.services.has("osd.panel"))
             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) => scope.runtime.host.osd.panel(text));
+        this.#pump = new Latest(({ text, args, maxColumns }) => scope.runtime.host.osd.panel(text, args, maxColumns));
         scope.add(this);
     }
-    set(text) {
-        if (this.#disposed || text === this.#last)
+    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 ? null : shownText(text, args),
+                ...(text === null || args === undefined || args === null
+                    ? {}
+                    : { args: templateArgs(args) }),
+                ...(text === null || max === undefined ? {} : { maxColumns: max }),
+            };
+        }
+        catch (error) {
+            this.#scope.report(error);
+            return;
+        }
+        const key = JSON.stringify(value);
+        if (key === this.#last)
             return;
-        this.#last = text;
-        this.#pump.push(text).catch((error) => this.#scope.report(error));
+        this.#last = key;
+        this.#pump.push(value).catch((error) => this.#scope.report(error));
     }
     async dispose() {
         if (this.#disposed)
@@ -25,12 +80,12 @@ class PanelHandle {
         this.#disposed = true;
         this.#scope.forget(this);
         this.#scope.runtime.services.delete("osd.panel");
-        if (this.#last !== null)
-            await this.#pump.push(null).catch(() => { });
+        if (this.#last !== JSON.stringify({ text: null }))
+            await this.#pump.push({ text: null }).catch(() => { });
         this.#pump.stop();
     }
 }
 export const osd = (scope) => ({
-    show: (text) => scope.runtime.host.osd.show(text),
+    show: async (text, args) => scope.runtime.host.osd.show(shownText(text, args), templateArgs(args)),
     panel: () => new PanelHandle(scope),
 });

package/dist/plugin/packages.js

@@ -161,4 +161,14 @@ const info = (plugin) => Object.freeze({
         ...(warning.slot === undefined ? {} : { slot: warning.slot }),
         ...(warning.owner === undefined ? {} : { owner: warning.owner }),
     }))),
+    ...(plugin.display
+        ? {
+            display: Object.freeze({
+                name: plugin.display.name ?? null,
+                punchline: plugin.display.punchline ?? null,
+                description: plugin.display.description ?? null,
+                tags: Object.freeze([...(plugin.display.tags ?? [])]),
+            }),
+        }
+        : {}),
 });

package/dist/plugin/runtime.d.ts

@@ -1,5 +1,5 @@
 import type { Json, LocalServices, Transport, Wire } from "../wire.ts";
-import type { App, Disposable, PluginError, SystemInfo } from "./types.ts";
+import type { App, Disposable, Locale, PluginError, SystemInfo } from "./types.ts";
 export interface PluginManifest {
     id: string;
     capabilities: string[];
@@ -40,6 +40,8 @@ export declare class Runtime {
     readonly services: Map<string, unknown>;
     /** `plugin.app`, from the start-up handshake; `system()` asks the player. */
     readonly app: App;
+    /** `plugin.i18n.locale`, from the start-up handshake; English when unknown. */
+    readonly locale: Locale;
     constructor(transport: Transport, manifest: PluginManifest, directory: string, dataDirectory?: string, app?: unknown);
     can(capability: string): boolean;
     /** Lazily created singletons shared by every scope of this plugin. */

package/dist/plugin/runtime.js

@@ -1,5 +1,6 @@
 /** Shared machinery behind every scope: invocation, update passes, events. */
 import { createWire, HostError } from "../wire.js";
+import { LOCALES } from "../i18n.js";
 export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export function toError(error) {
     if (error instanceof Error) {
@@ -94,6 +95,8 @@ export class Runtime {
     services = new Map();
     /** `plugin.app`, from the start-up handshake; `system()` asks the player. */
     app;
+    /** `plugin.i18n.locale`, from the start-up handshake; English when unknown. */
+    locale;
     constructor(transport, manifest, directory, dataDirectory, app) {
         this.#transport = transport;
         this.dataDirectory = dataDirectory;
@@ -101,6 +104,9 @@ export class Runtime {
         this.host = createWire(transport);
         const host = this.host;
         this.app = appInfo(app, () => host.app.system());
+        this.locale = LOCALES.includes(transport.locale ?? "")
+            ? transport.locale
+            : "en";
         this.manifest = manifest;
         this.directory = directory;
         transport.on("ui.callback", (data) => {

package/dist/plugin/scope.d.ts

@@ -39,6 +39,7 @@ export declare class ScopeImpl implements Plugin {
     readonly drops: import("./types.ts").Drops;
     readonly appearance: import("./types.ts").Appearance;
     readonly settings: import("./types.ts").Settings;
+    readonly i18n: import("./types.ts").I18n;
     get app(): import("./types.ts").App;
     scope(): Scope;
     add<T extends Disposable>(item: T): T;

package/dist/plugin/scope.js

@@ -6,6 +6,7 @@ import { timeline } from "./timeline.js";
 import { drops } from "./drops.js";
 import { appearance } from "./appearance.js";
 import { settings } from "./settings.js";
+import { i18n } from "./language.js";
 import { player } from "./player.js";
 import { audioFilters, videoFilters } from "./filters.js";
 import { videoRender, videoView } from "./view.js";
@@ -69,6 +70,7 @@ export class ScopeImpl {
     drops = drops(this);
     appearance = appearance(this);
     settings = settings(this);
+    i18n = i18n(this);
     get app() {
         return this.runtime.app;
     }

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))