@vestra-player/sdk 1.5.8 → 1.5.9

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

@@ -0,0 +1,4 @@
+/** `plugin.i18n`: the interface language of this run (read-only). */
+import type { ScopeImpl } from "./scope.ts";
+import type { I18n } from "./types.ts";
+export declare const i18n: (scope: ScopeImpl) => I18n;

package/dist/plugin/language.js

@@ -0,0 +1,5 @@
+export const i18n = (scope) => Object.freeze({
+    get locale() {
+        return scope.runtime.locale;
+    },
+});

package/dist/plugin/osd.d.ts

@@ -1,3 +1,6 @@
 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. */
+export declare function templateArgs(args: unknown): TemplateArgsJson | undefined;
 export declare const osd: (scope: ScopeImpl) => Osd;

package/dist/plugin/osd.js

@@ -1,23 +1,59 @@
 /** 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. */
+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");
+    return Array.isArray(args)
+        ? [...args]
+        : { ...args };
+}
 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 }) => scope.runtime.host.osd.panel(text, args));
         scope.add(this);
     }
-    set(text) {
-        if (this.#disposed || text === this.#last)
+    set(text, args) {
+        if (this.#disposed)
+            return;
+        let value;
+        try {
+            value = {
+                text,
+                ...(text === null || args === undefined
+                    ? {}
+                    : { args: templateArgs(args) }),
+            };
+        }
+        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 +61,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(text, 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/testing.d.ts

@@ -8,11 +8,28 @@ 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 { Plugin, ThemeId } from "./types.ts";
+import type { LanguagePreference, Locale, Plugin, TemplateArgs, ThemeId } from "./types.ts";
+import { LOCALES } 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 interface languages, English (the source) first, as the
+ * player's own table: `["en", "zh-Hans", "ja", "ko", "de", "fr", "es"]`.
+ *
+ * @example
+ * ```ts
+ * import { LOCALES } from "@vestra-player/sdk/testing";
+ *
+ * for (const locale of LOCALES.slice(1)) {
+ *   const { host, stop } = await startPlugin(activate, { directory, locale });
+ *   assert.notEqual(host.command("open").display.title, "Open…");
+ *   await stop();
+ * }
+ * ```
+ */
+export { LOCALES };
 type Handler = (params: Record<string, Json>) => unknown;
 type Call = {
     method: string;
@@ -80,6 +97,20 @@ export interface FakeCommand {
      * versions.
      */
     declaration: CommandDeclaration;
+    /**
+     * What the menu shows, as the player shows it in the test host's
+     * {@link TestHost.locale}: the title and each path segment translated with
+     * the plugin's catalog (the player's own menus in the player's words), the
+     * keys normalized (`@video` is "Video").
+     *
+     * @since 1.5.9
+     */
+    readonly display: {
+        /** The menu text of the item. */
+        title: string;
+        /** Each segment of the path as shown; empty without a path. */
+        path: string[];
+    };
     /** The command state the player last received (after the update pass). */
     state: {
         /** `false` when the plugin disabled the command. */
@@ -257,10 +288,101 @@ export declare class TestHost implements Transport {
          */
         sidebar: LayoutSlot | null;
     };
-    /** Every `osd.show` text, newest last. */
+    /**
+     * Every `osd.show` text as the player shows it (translated with the
+     * plugin's catalog and formatted with its args), newest last. The
+     * template and args the plugin sent are in `host.sent("osd.show")`.
+     */
     readonly osd: string[];
-    /** The text of this plugin's osd panel, `null` when hidden. */
+    /** The text of this plugin's osd panel as shown, `null` when hidden. */
     osdPanel: string | null;
+    /**
+     * The interface language the test host plays (`plugin.i18n.locale`), `"en"`
+     * by default. Set it before {@link startPlugin} (or pass its `locale`
+     * option): the plugin's catalog for it is read from the package's
+     * `locales/` then, and the menus ({@link FakeCommand.display}), OSD
+     * messages, dialog texts, settings page and panel titles show its
+     * translations, the way the player shows them.
+     *
+     * The player's own texts (core actions' messages and menus, its
+     * refusals) are English, or the player's Simplified Chinese for
+     * `"zh-Hans"`. While `locale` was never set they stay in Chinese, as
+     * players up to 0.4.2 showed them, so tests written for SDK 1.5.8 keep
+     * passing; set `locale` to test what a user sees now.
+     *
+     * @example
+     * ```ts
+     * const { host, stop } = await startPlugin(activate, { directory, locale: "zh-Hans" });
+     * assert.deepEqual(host.command("blur").display.path, ["视频", "模糊…"]);
+     * await stop();
+     * ```
+     *
+     * @since 1.5.9
+     */
+    get locale(): Locale;
+    set locale(locale: Locale);
+    /**
+     * Read the plugin's translations for {@link TestHost.locale} from a
+     * package directory, as the player would (`locales/<locale>.json` of a
+     * built package, else the source `locales/<locale>.po`); `startPlugin`
+     * does this. None for English; a missing file means none; a broken `.po`
+     * throws.
+     *
+     * @param directory - The package directory (holding `locales/`).
+     * @since 1.5.9
+     */
+    loadCatalog(directory: string): void;
+    /**
+     * A text of the plugin as the player shows it: translated with the
+     * plugin's catalog ({@link TestHost.loadCatalog}), then formatted with
+     * `args` when given.
+     *
+     * @param text - English source text or template.
+     * @param args - Values for its placeholders.
+     * @returns The shown text.
+     *
+     * @example
+     * ```ts
+     * assert.equal(host.translate("Speed {}×", [2]), "倍速 2×");
+     * ```
+     *
+     * @since 1.5.9
+     */
+    translate(text: string, args?: TemplateArgs): string;
+    /**
+     * The saved interface language (`plugin.appearance.language`), changed by
+     * `appearance.setLanguage` or {@link TestHost.setLanguage}.
+     *
+     * @since 1.5.9
+     */
+    language: LanguagePreference;
+    /**
+     * Simulate another plugin (or the user) saving the interface language:
+     * pushes `appearance.changed`.
+     *
+     * @param language - `"system"` or a locale.
+     * @since 1.5.9
+     */
+    setLanguage(language: LanguagePreference): void;
+    /**
+     * Every `dialogs.confirm` as the player shows it: its texts translated
+     * (message and detail formatted with `args`), newest last. The options
+     * the plugin sent are in {@link TestHost.confirms}.
+     *
+     * @since 1.5.9
+     */
+    readonly confirmTexts: {
+        /** The question. */
+        message: string;
+        /** The text under it, if any. */
+        detail?: string;
+        /** The confirm button. */
+        confirm: string;
+        /** The cancel button (the player's "Cancel" by default). */
+        cancel: string;
+        /** The checkbox, if any. */
+        checkbox?: string;
+    }[];
     /** The sequence provider's flags, `null` without a provider. */
     sequence: {
         /** The provider's `canNext`, as last evaluated. */
@@ -1341,6 +1463,14 @@ export declare function startPlugin(activate: (plugin: Plugin) => unknown, optio
     host?: TestHost;
     /** Use an existing directory as `plugin.dataDirectory` (to test a restart). */
     dataDirectory?: string;
+    /**
+     * The interface language to play ({@link TestHost.locale}): the plugin's
+     * `locales/<locale>.po` (or `.json`) in `directory` is loaded and its
+     * menus, messages and titles show translated. Default: the host's.
+     *
+     * @since 1.5.9
+     */
+    locale?: Locale;
 }): Promise<{
     /** The test host the plugin talks to. */
     host: TestHost;