@vestra-player/sdk 1.5.7 → 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

@@ -1,4 +1,4 @@
-/** Package validation, trial loading and install/rollback (`plugins.manage`). */
+/** Package validation and install/rollback (`plugins.manage`). */
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
 import { failure, sleep, uncertain } from "./runtime.js";
@@ -9,51 +9,6 @@ const TERMINAL = [
     "failedDegraded",
     "tooLate",
 ];
-const STARTING = ["preparing", "activating", "starting"];
-class TrialHandle {
-    #scope;
-    #record;
-    #stopped;
-    constructor(scope, record) {
-        this.#scope = scope;
-        this.#record = record;
-        scope.add(this);
-    }
-    get status() {
-        return this.#record.status;
-    }
-    /**
-     * Concurrent calls share one stop; a confirmed stop is final. A failed one
-     * (code `cleanup`: the host did not confirm cleanup) is forgotten, so the
-     * next call sends a new stop to the host.
-     */
-    stop() {
-        const host = this.#scope.runtime.host.packages;
-        if (this.#stopped)
-            return this.#stopped;
-        const stopping = (async () => {
-            this.#record = await host.stopTrial(this.#record.trialId);
-            while (!this.#record.cleanupConfirmed &&
-                this.#record.status !== "stopped" &&
-                this.#record.status !== "failed") {
-                await sleep(250);
-                this.#record = await host.trialState(this.#record.trialId);
-            }
-            if (!this.#record.cleanupConfirmed)
-                throw failure("cleanup", `trial cleanup not confirmed: ${this.#record.status}`);
-        })();
-        this.#stopped = stopping;
-        stopping.catch(() => {
-            if (this.#stopped === stopping)
-                this.#stopped = undefined;
-        });
-        return stopping;
-    }
-    async dispose() {
-        this.#scope.forget(this);
-        await this.stop().catch(() => { });
-    }
-}
 class ChangeHandle {
     #scope;
     #id;
@@ -123,24 +78,6 @@ async function change(scope, submit, id) {
     }
     return new ChangeHandle(scope, operation);
 }
-async function trial(scope, runtime, token) {
-    const host = runtime.host.packages;
-    const requestId = randomUUID();
-    let record;
-    try {
-        record = await host.trial(token, requestId);
-    }
-    catch (error) {
-        if (!uncertain(error))
-            throw error;
-        record = await host.trialStateByRequest(requestId);
-    }
-    while (STARTING.includes(record.status)) {
-        await sleep(250);
-        record = await host.trialState(record.trialId);
-    }
-    return new TrialHandle(scope, record);
-}
 function installOptions(options) {
     if (options === undefined)
         return {};
@@ -171,7 +108,6 @@ function candidate(scope, directory, checked) {
         digest: checked.digest,
         manifest: checked.manifest,
         checks: checked.checks,
-        trial: () => trial(scope, runtime, checked.token),
         install: async (options) => {
             const wire = installOptions(options);
             return change(scope, (requestId, revision) => runtime.host.packages.install(checked.token, revision, requestId, wire), checked.manifest.id);
@@ -225,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/resolvers.js

@@ -5,8 +5,72 @@
 import { failure, quiet } from "./runtime.js";
 import { playerOf } from "./player.js";
 import { resolvedStream } from "./stream.js";
+import { windowOf } from "./window.js";
 const isFiles = (options) => "extensions" in options;
+const sameTypes = (a, b) => a.length === b.length && a.every((type, i) => type === b[i]);
+/**
+ * One per plugin: the list comes with the `window.state` read before
+ * activation (`[]` from older players) and is read again when the plugin
+ * first uses it; with `events`, `resolvers.fileTypes` keeps it current.
+ */
+class FileTypesService {
+    #runtime;
+    types;
+    #listeners = new Set();
+    #started = false;
+    constructor(runtime) {
+        this.#runtime = runtime;
+        this.types = Object.freeze([...(windowOf(runtime).fileTypes ?? [])]);
+    }
+    start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        this.#runtime.on("resolvers.fileTypes", (data) => {
+            const types = data?.fileTypes;
+            if (Array.isArray(types) && types.every((t) => typeof t === "string"))
+                this.accept(types);
+        });
+        // What changed between the start-up read and the subscription.
+        const window = windowOf(this.#runtime);
+        void window.read().then(() => {
+            if (window.fileTypes)
+                this.accept(window.fileTypes, this.#runtime.can("events"));
+        });
+    }
+    /** `notify`: false without `events`, whose listeners never fire. */
+    accept(types, notify = true) {
+        if (sameTypes(types, this.types))
+            return;
+        this.types = Object.freeze([...types]);
+        if (notify)
+            for (const listener of [...this.#listeners])
+                listener([...types]);
+        this.#runtime.invalidate();
+    }
+    watch(listener) {
+        this.#listeners.add(listener);
+        return { dispose: async () => void this.#listeners.delete(listener) };
+    }
+}
+const fileTypesOf = (runtime) => runtime.service("fileTypes", () => new FileTypesService(runtime));
 export const resolvers = (scope) => ({
+    get fileTypes() {
+        const service = fileTypesOf(scope.runtime);
+        service.start();
+        return service.types;
+    },
+    onFileTypesChange(listener) {
+        const service = fileTypesOf(scope.runtime);
+        service.start();
+        const watch = service.watch((types) => scope.run(listener, types));
+        return scope.add({
+            dispose: async () => {
+                scope.forget(watch);
+                await watch.dispose();
+            },
+        });
+    },
     add(options) {
         const runtime = scope.runtime;
         const registration = isFiles(options)

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. */
@@ -773,6 +895,27 @@ export declare class TestHost implements Transport {
         /** Exact host names it resolves (a web resolver), with `schemes`. */
         hosts?: string[];
     }[];
+    /**
+     * What `plugin.resolvers.fileTypes` reports: the extensions of this
+     * plugin's file resolvers and of {@link TestHost.otherResolvers}, sorted,
+     * each once.
+     */
+    fileTypes(): string[];
+    /**
+     * Push `resolvers.fileTypes` when {@link TestHost.fileTypes} changed:
+     * called after this plugin's resolvers come and go; call it yourself
+     * after changing {@link TestHost.otherResolvers} (another plugin started
+     * or stopped).
+     *
+     * @example
+     * ```ts
+     * host.otherResolvers.push({ owner: "vestra.nes", extensions: ["nes"] });
+     * host.updateFileTypes();
+     * await host.settle();
+     * assert.deepEqual(plugin.resolvers.fileTypes, ["nes"]);
+     * ```
+     */
+    updateFileTypes(): void;
     /**
      * File opens waiting for this plugin's file resolver (`extensions`), by
      * request id: the path and how it was opened. Opening a matching path
@@ -1095,7 +1238,7 @@ export declare class TestHost implements Transport {
         /** Its version, `null` when unknown. */
         version: string | null;
         /** Where it was loaded from. */
-        origin: "installed" | "development" | "trial";
+        origin: "installed" | "development";
         /** Its run state. */
         state: "starting" | "running" | "disabled" | "failed" | "stopped";
         /** Why it failed (`state: "failed"`). */
@@ -1320,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;