@vestra-player/sdk 1.5.9 → 1.5.11

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.5.11
+
+**Text values: words mixed with data, translated by the player** (player 0.4.3). Additive; `apiVersion` stays `vestra/1`, and plugins that worked need no change. 1.5.9 and 1.5.10 were not published to npm; this release includes them. Round-2 i18n requests R2-audio-1, R2-video-1, R2-subtitles-1/2, R2-playlist-1/2, R2-store-1, R2-workshop-1, R2-nes-1, capture #1, P-2, the info and hotkeys export texts, timeline and subtitle titles: one mechanism. Guide: [Translate a plugin ▸ Text that mixes words and data](docs/how-to/i18n.md#text-that-mixes-words-and-data).
+
+- **`plugin.i18n.text(source, args?)`** returns a `Text`: plain, frozen data (`{ $vestraText, args }`), not a translation. The player translates `source` with the plugin's catalog and fills in `args` wherever it shows it. Arguments are data, or text values that are translated too, so a sentence can be built from translated parts without composing it in TypeScript.
+- **`plugin.i18n.list(items, style?)`** returns a `TextList`: items joined with the interface language's separator (`ListStyle`: `"list"` `, ` / `、`, `"clauses"` `, ` / `，`, `"semicolons"`, `"sentences"`, `"lines"`; `LIST_SEPARATORS` in `@vestra-player/sdk/testing`).
+- **Accepted wherever the player shows a plugin's text**: command `title`, `path` segments (the menu merges by the English rendering) and `reason`; `osd.show` and `OsdPanel.set` as the text or an argument (`TemplateArgs` now takes `TextArg`); every `dialogs.confirm` text; file dialog `title` and `saveFile`'s `fileName` (a string `fileName` stays data); property values where Slint has a `string`, at any depth (`PropData` takes `Text` and `TextList`), so a ComboBox model can mix fixed words and data; `TimelineLayer.set` mark titles; `subtitles.load({ title })`.
+- **`plugin.i18n.error(source, args?)`**: an `Error` (`TextError`) whose words the player shows translated when a file or web resolver's `resolve` throws it (also a stream failing while it starts): the open's failure and `player.state.error`. `message` is the English rendering.
+- **`plugin.i18n.resolve(value)`**: the translated string, for text that leaves the player only (clipboard, files). Never for the interface.
+- **`OsdPanel.set(text, args, { maxColumns })`** (`OsdPanelOptions`): the player cuts each line after translation (a wide character is two columns).
+- **`BindingInfo.key`**: the menu path's English keys, the same in every language (P-2). Find a command by its place in the menu with it, not with `path`.
+- **Limits** (`TEXT_LIMITS` in `@vestra-player/sdk/testing`): nesting 8, 1024 values in one text, 16 arguments per text, 256 items per list, 4096 bytes per source or string argument (template string arguments were 1024 bytes). A malformed value throws `invalid` where it is made, and the player refuses it with `invalid`. A property value's limits count a text value as the string it becomes.
+- **`vestra-plugin i18n extract`** collects the source of every `plugin.i18n.text(…)`, `error(…)` and `resolve("…")` call (also destructured: `const { text } = plugin.i18n`) and of a `{ $vestraText: "…" }` literal. Every source is collected, also one made only of placeholders and punctuation (`"{} ({})"`, which Chinese writes `"{}（{}）"`). It now reads fields spread into a call's options (`commands.add({ ...extra })`) by their types and reports the ones it cannot extract; before, it skipped them without a word. A field typed as a text value is not reported as "not a literal".
+- **Type note**: the option fields that now take a text value (`ConfirmOptions.message` and the other dialog texts, `CommandOptions.title`/`path`/`reason`, `CommandState.reason`, file dialog `title`/`fileName`, `TemplateArgs`) are wider types. Code that only passes them is unchanged; code that reads such a field back as a `string` (a helper that cuts `options.message`) needs a `typeof … === "string"` check.
+- **`TestHost`** shows text values as the player does: `FakeCommand.display` (and the non-enumerable `display.reason`), `host.osd`, `host.osdPanel` (cut to `maxColumns`), `host.confirmTexts`, new `host.fileDialogs` (`FileDialogText`), window, panel and settings page `props` (text values replaced by their strings; `host.sent(...)` keeps what the plugin sent), timeline titles, subtitle titles, a resolver's `TextError`, and `BindingInfo.key`. `host.translate` takes a text value too. It refuses malformed text values with the player's messages.
+
+## 1.5.10
+
+**Property value limits: documented, higher, enforced by `TestHost`, reported loudly** (player 0.4.3). A fix; `apiVersion` stays `vestra/1`, and plugins that worked need no change. 1.5.9 was not published to npm; this release includes its changes.
+
+- **`UI_VALUE_LIMITS`** in `@vestra-player/sdk/testing`: the player's limits on one property value, which used to appear only in the `PropValue` description. Raised in player 0.4.3 (older players in brackets): nesting depth 8, **16384 values** (4096), **4096 rows per array** (1024), 64 KiB per string or field name, 1 MiB of text. A list of 8-field rows is 9 values per row, so about 1800 rows fit (about 450 before). The player's tests check that the constant agrees with the player.
+- **`TestHost` enforces them** on `ui.open`, `ui.set`, `ui.mount`, `ui.setMount`, `settings.register` and `settings.set`, with the player's code and message. Before, it took any value, so a plugin whose list outgrew the limit passed its tests and showed a stale list in the player (D1: a 3000-row playlist). A test that writes a value over the limits now sees the failure in `onError` (or, for a tool window's initial property, a rejected `Window.show`).
+- **Failures say what they are.** A value over the limits fails with code **`limit`** (was `host`) and the message names the property (`rows: UI array exceeds 4096 rows`). A panel's or settings page's initial property over the limits is still left out (the panel mounts without it; a failed mount during activation would fail the plugin), but the player now reports it to `onError` instead of only writing its log.
+- **`ui.error` reaches `onError`.** The player reports failures nobody asked about: a callback whose arguments it could not convert, a property it could not show again when it rebuilt a panel or the Options window (an image file removed since), a detached sidebar it could not prepare. The SDK used to drop these; it now reports them to the root scope's `onError` with the player's code (`ui` from older players).
+- The player's runner (player 0.4.3) refuses a request longer than the player's 1 MiB message with `limit`; before, the player stopped the plugin.
+
 ## 1.5.9
 
 **Translations** (player 0.4.3). Additive; `apiVersion` stays `vestra/1`, and plugins written for 1.5.8 need no change. One test-visible change: a core action's `declaration.path` in `TestHost` is now the player's English key (read `display` for what the menu shows). The player now shows its interface in English, Simplified Chinese, Japanese, Korean, German, French or Spanish, chosen at start-up; a plugin writes every text in English and ships one gettext file per language. Plugins write no translation code: the player translates. Guides: [Translate a plugin](docs/how-to/i18n.md), [Migrate a plugin to English source text](docs/how-to/i18n-migration.md); example: `examples/i18n`.

package/dist/commands.d.ts

@@ -1,5 +1,6 @@
 /** Finite candidate command registry. Host authenticates owner; no plugin supplies an owner id. */
 import type { Transport } from "./wire.ts";
+import type { ListJson, TextJson } from "./i18n.ts";
 /**
  * The player's command registry caps, the same values as the player's own
  * table (the player's tests check that they agree). They are runaway guards,
@@ -47,12 +48,14 @@ export type CommandState = {
     enabled: boolean;
     checked: boolean | null;
     busy: boolean;
-    reason: string | null;
+    /** Source text, or a text value (player 0.4.3). */
+    reason: string | TextJson | ListJson | null;
 };
 export type CommandDeclaration = {
-    title: string;
-    /** Complete primary menu path INCLUDING its leaf; empty = not in the main menu. */
-    path: string[];
+    /** Source text, or a text value (player 0.4.3). */
+    title: string | TextJson;
+    /** Complete primary menu path INCLUDING its leaf; empty = not in the main menu. Segments may be text values (player 0.4.3). */
+    path: (string | TextJson)[];
     /** Sibling order, ascending; a submenu takes its first command's order (a built-in menu keeps a fixed one). */
     order: number;
     /** Separator label: adjacent siblings of different groups get a line. */

package/dist/i18n-tools.js

@@ -26,7 +26,7 @@ export const pluralForms = (language) => ONE_FORM.has(language)
     : "nplurals=2; plural=(n != 1);";
 const slash = (path) => path.split(sep).join("/");
 const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
-const COMPOSED = 'user-visible text composed in TypeScript: pass a template with args (osd.show("Speed {}×", [rate])) or move it into Slint';
+const COMPOSED = 'user-visible text composed in TypeScript: pass a template with args (osd.show("Speed {}×", [rate]), plugin.i18n.text("Track {}", [n])) or move it into Slint';
 const DYNAMIC = (what) => `${what} is not a literal; its text cannot be extracted (use a string literal or an \`as const\` table)`;
 const SITES = {
     "Commands.add": { object: 0, fields: ["title", "reason"], path: true },
@@ -43,6 +43,9 @@ const SITES = {
     "Dialogs.openFiles": { object: 0, fields: ["title"] },
     "Dialogs.openDirectory": { object: 0, fields: ["title"] },
     "Dialogs.saveFile": { object: 0, fields: ["title"] },
+    "I18n.text": { argument: 0 },
+    "I18n.error": { argument: 0 },
+    "I18n.resolve": { argument: 0 },
 };
 /** Without the SDK's types: the module property names in front of the method. */
 const BY_NAME = {
@@ -55,6 +58,9 @@ const BY_NAME = {
     "dialogs.openFiles": "Dialogs.openFiles",
     "dialogs.openDirectory": "Dialogs.openDirectory",
     "dialogs.saveFile": "Dialogs.saveFile",
+    "i18n.text": "I18n.text",
+    "i18n.error": "I18n.error",
+    "i18n.resolve": "I18n.resolve",
 };
 const none = () => ({ values: [], dynamic: false, composed: false });
 const join2 = (a, b) => ({
@@ -125,6 +131,11 @@ class Extractor {
         for (const part of parts) {
             if (part.isStringLiteral())
                 result.values.push(part.value);
+            // A text value (`plugin.i18n.text(…)`): its source is extracted where
+            // it is made.
+            else if (part.getProperty("$vestraText") ||
+                part.getProperty("$vestraList"))
+                continue;
             else if (part.flags &
                 (ts.TypeFlags.Null |
                     ts.TypeFlags.Undefined |
@@ -249,10 +260,22 @@ class Extractor {
     /** `Interface.method` of a call to the SDK, if it is one of `SITES`. */
     #site(call) {
         const callee = call.expression;
-        if (!ts.isPropertyAccessExpression(callee))
+        const declaration = this.#checker?.getResolvedSignature(call)?.declaration;
+        if (!ts.isPropertyAccessExpression(callee)) {
+            // `const { text } = plugin.i18n; text("…")`: by the declaration.
+            if (declaration &&
+                !ts.isJSDocSignature(declaration) &&
+                declaration.parent &&
+                ts.isInterfaceDeclaration(declaration.parent) &&
+                declaration.name &&
+                ts.isIdentifier(declaration.name) &&
+                /\/plugin\/types\.(d\.)?ts$/.test(slash(declaration.getSourceFile().fileName))) {
+                const name = `${declaration.parent.name.text}.${declaration.name.text}`;
+                return name in SITES ? name : undefined;
+            }
             return undefined;
+        }
         const method = callee.name.text;
-        const declaration = this.#checker?.getResolvedSignature(call)?.declaration;
         if (declaration &&
             !ts.isJSDocSignature(declaration) &&
             declaration.parent &&
@@ -279,6 +302,13 @@ class Extractor {
         const visit = (node) => {
             if (ts.isCallExpression(node))
                 this.#call(node, file, source, text);
+            // A text value written as data: `{ $vestraText: "…" }`.
+            if (ts.isPropertyAssignment(node) &&
+                (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) &&
+                node.name.text === "$vestraText" &&
+                !ignored(node, text) &&
+                !ignored(statementOf(node), text))
+                this.#emit(this.values(node.initializer), node.initializer, file, source, "the source of a text", () => true, [...notesOf(statementOf(node), text), ...notesOf(node, text)]);
             if ((ts.isStringLiteral(node) ||
                 ts.isNoSubstitutionTemplateLiteral(node)) &&
                 CJK.test(node.text) &&
@@ -330,6 +360,32 @@ class Extractor {
             return;
         }
         for (const property of object.properties) {
+            if (ts.isSpreadAssignment(property)) {
+                // `{ ...extra }`: the spread object's fields, by their types; a
+                // field that is not a literal (or a text value) is reported.
+                const checker = this.#checker;
+                const at = source.getLineAndCharacterOfPosition(property.getStart(source)).line +
+                    1;
+                if (!checker) {
+                    this.finding(file, at, "dynamic", `fields spread into ${name} cannot be read without types; write ${fields.join(", ")} explicitly`);
+                    continue;
+                }
+                if (ignored(property, text))
+                    continue;
+                const type = checker.getTypeAtLocation(property.expression);
+                for (const field of fields) {
+                    const symbol = type.getProperty(field);
+                    if (!symbol)
+                        continue;
+                    if (field === "path") {
+                        this.finding(file, at, "dynamic", `a path spread into ${name} cannot be extracted; write path explicitly`);
+                        continue;
+                    }
+                    const fieldType = checker.getTypeOfSymbolAtLocation(symbol, property.expression);
+                    this.#emit(this.#fromType(fieldType), property, file, source, `${field} spread into ${name}`, () => true, statementNotes);
+                }
+                continue;
+            }
             const key = property.name &&
                 (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))
                 ? property.name.text

package/dist/i18n.d.ts

@@ -1,3 +1,4 @@
+import type { ListStyle, Locale } from "./plugin/types.ts";
 /**
  * The player's interface languages: English (the source language) first,
  * then the translations, as the player's own table (its tests check that
@@ -78,6 +79,83 @@ export declare function format(template: string, args: TemplateArgsValue): strin
  * number (`{n}` of a Slint plural is `"n"`). Translations must keep them.
  */
 export declare function placeholders(text: string): string[];
+/**
+ * The ways a `TextList` is joined (`ListStyle`), as the player
+ * joins them in each interface language (`LIST_SEPARATORS`).
+ */
+export declare const LIST_STYLES: readonly ListStyle[];
+/**
+ * The separator of each list style per interface language, as the player's
+ * table (`i18n::text::SEPARATORS`; its tests check that they agree).
+ */
+export declare const LIST_SEPARATORS: Readonly<Record<Locale, Readonly<Record<ListStyle, string>>>>;
+/**
+ * The player's limits on one text value (a
+ * {@link @vestra-player/sdk!Text | Text} or
+ * {@link @vestra-player/sdk!TextList | TextList} with everything nested in it), as the player's
+ * `i18n::text` (its tests check that they agree).
+ */
+export declare const TEXT_LIMITS: {
+    /** Nesting depth of texts and lists; the value itself is depth 0 (8). */
+    readonly depth: 8;
+    /** Texts, lists and arguments in all, the value itself included (1024). */
+    readonly nodes: 1024;
+    /** Arguments of one text (16). */
+    readonly args: 16;
+    /** Items of one list (256). */
+    readonly items: 256;
+    /** UTF-8 bytes of a source text or a string argument (4096). */
+    readonly stringBytes: 4096;
+};
+/** A translatable text on the wire: English source text and its arguments. */
+export type TextJson = {
+    $vestraText: string;
+    args?: ArgJson[] | {
+        [name: string]: ArgJson;
+    };
+};
+/** A list on the wire: items joined the interface language's way. */
+export type ListJson = {
+    $vestraList: ArgJson[];
+    style?: ListStyle;
+};
+/** An argument of a text: data (strings and numbers) or another text. */
+export type ArgJson = string | number | TextJson | ListJson;
+/** A text or list value (by its marker key). */
+export declare function isTextValue(value: unknown): value is TextJson | ListJson;
+/**
+ * Why the player would refuse a text value or template arguments, or
+ * `null`. `args` mode checks template arguments (an array or object of
+ * arguments) instead of one value. The same rules and messages as the
+ * player's `i18n::text::check`.
+ */
+export declare function textProblem(value: unknown, mode?: "value" | "args"): string | null;
+type TemplateArgsLike = readonly ArgJson[] | Readonly<Record<string, ArgJson>> | null;
+/**
+ * A text value as the player shows it: the source translated with the
+ * plugin's catalog and formatted with its (rendered) arguments; a list's
+ * items joined with the locale's separator.
+ */
+export declare function renderText(value: TextJson | ListJson, catalog: Catalog, locale: string): string;
+/**
+ * Template arguments with their texts rendered (for `format`): what the
+ * player fills a template with.
+ */
+export declare function renderTemplateArgs(args: TemplateArgsLike | undefined, catalog: Catalog, locale: string): TemplateArgsValue | undefined;
+/** The English rendering of a text value: the key a menu merges by. */
+export declare function textKey(value: TextJson | ListJson): string;
+/**
+ * A property value with every text value in it replaced by its shown
+ * string, as the player does before it hands the value to Slint. Returns
+ * a problem (`textProblem`) instead when a text value is malformed.
+ */
+export declare function resolveTexts<T>(value: T, catalog: Catalog, locale: string): {
+    value: T;
+} | {
+    problem: string;
+};
+/** Whether a value holds a text value anywhere (a cheap pre-check). */
+export declare function hasTexts(value: unknown): boolean;
 /** One `@tr("context" => "id" | "plural" % n, args…)` call. */
 export interface TrCall {
     context?: string;
@@ -128,3 +206,17 @@ export declare function menuKeys(path: readonly string[]): string[];
  * agree).
  */
 export declare const HOST_ZH_HANS: Readonly<Record<string, string>>;
+/**
+ * The catalog of a package directory for `locale`, as the player loads it:
+ * the compiled `locales/<lang>.json` of a built package, else the source
+ * `locales/<lang>.po`. Empty for English and without a file; a broken file
+ * throws.
+ */
+export declare function loadPackageCatalog(directory: string, locale: string): Catalog;
+/**
+ * Each line of `text` cut to `max` columns, ending with `…` when cut, as
+ * the player cuts an OSD panel's lines (`OsdPanelOptions.maxColumns`; the
+ * player measures with Unicode's East Asian Width, this is close to it).
+ */
+export declare function fitColumns(text: string, max: number): string;
+export {};

package/dist/i18n.js

@@ -8,6 +8,8 @@
  * Internal: the player's runner and tests reach it through
  * `@vestra-player/sdk/runtime`, `LOCALES` through `./testing`.
  */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 /**
  * The player's interface languages: English (the source language) first,
  * then the translations, as the player's own table (its tests check that
@@ -326,6 +328,254 @@ export function placeholders(text) {
         found.push(match[1]);
     return found.sort();
 }
+// ---------------------------------------------------------------- texts
+/**
+ * The ways a `TextList` is joined (`ListStyle`), as the player
+ * joins them in each interface language (`LIST_SEPARATORS`).
+ */
+export const LIST_STYLES = [
+    "list",
+    "clauses",
+    "semicolons",
+    "sentences",
+    "lines",
+];
+/**
+ * The separator of each list style per interface language, as the player's
+ * table (`i18n::text::SEPARATORS`; its tests check that they agree).
+ */
+export const LIST_SEPARATORS = {
+    en: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: "; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+    "zh-Hans": {
+        list: "、",
+        clauses: "，",
+        semicolons: "；",
+        sentences: "。",
+        lines: "\n",
+    },
+    ja: {
+        list: "、",
+        clauses: "、",
+        semicolons: "；",
+        sentences: "。",
+        lines: "\n",
+    },
+    ko: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: "; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+    de: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: "; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+    fr: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: " ; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+    es: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: "; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+};
+/**
+ * The player's limits on one text value (a
+ * {@link @vestra-player/sdk!Text | Text} or
+ * {@link @vestra-player/sdk!TextList | TextList} with everything nested in it), as the player's
+ * `i18n::text` (its tests check that they agree).
+ */
+export const TEXT_LIMITS = {
+    /** Nesting depth of texts and lists; the value itself is depth 0 (8). */
+    depth: 8,
+    /** Texts, lists and arguments in all, the value itself included (1024). */
+    nodes: 1024,
+    /** Arguments of one text (16). */
+    args: 16,
+    /** Items of one list (256). */
+    items: 256,
+    /** UTF-8 bytes of a source text or a string argument (4096). */
+    stringBytes: 4096,
+};
+const plainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** A text or list value (by its marker key). */
+export function isTextValue(value) {
+    return (plainObject(value) && ("$vestraText" in value || "$vestraList" in value));
+}
+const utf8 = (text) => new TextEncoder().encode(text).length;
+/**
+ * Why the player would refuse a text value or template arguments, or
+ * `null`. `args` mode checks template arguments (an array or object of
+ * arguments) instead of one value. The same rules and messages as the
+ * player's `i18n::text::check`.
+ */
+export function textProblem(value, mode = "value") {
+    let nodes = 0;
+    const L = TEXT_LIMITS;
+    const args = (list, depth) => {
+        const values = Array.isArray(list)
+            ? list
+            : plainObject(list)
+                ? Object.values(list)
+                : null;
+        if (!values)
+            return "args is an array or an object";
+        if (values.length > L.args)
+            return `args holds at most ${L.args} values`;
+        for (const item of values) {
+            const problem = arg(item, depth);
+            if (problem)
+                return problem;
+        }
+        return null;
+    };
+    const arg = (item, depth) => {
+        if (typeof item === "number")
+            return Number.isFinite(item) ? count() : "a number argument is finite";
+        if (typeof item === "string")
+            return utf8(item) > L.stringBytes
+                ? `a string argument is at most ${L.stringBytes} bytes`
+                : count();
+        if (isTextValue(item))
+            return text(item, depth + 1);
+        return "args are strings, numbers, texts and lists";
+    };
+    const count = () => ++nodes > L.nodes ? `a text holds at most ${L.nodes} values` : null;
+    const text = (item, depth) => {
+        if (depth > L.depth)
+            return `texts nest at most ${L.depth} deep`;
+        if (!plainObject(item))
+            return "a text is a $vestraText or $vestraList object";
+        const over = count();
+        if (over)
+            return over;
+        if ("$vestraText" in item) {
+            const keys = Object.keys(item);
+            if (keys.some((key) => key !== "$vestraText" && key !== "args"))
+                return "a text has only $vestraText and args";
+            const source = item.$vestraText;
+            if (typeof source !== "string" || source === "")
+                return "a text's source is a non-empty string";
+            if (utf8(source) > L.stringBytes)
+                return `a text's source is at most ${L.stringBytes} bytes`;
+            return item.args === undefined ? null : args(item.args, depth);
+        }
+        const keys = Object.keys(item);
+        if (keys.some((key) => key !== "$vestraList" && key !== "style"))
+            return "a list has only $vestraList and style";
+        const items = item.$vestraList;
+        if (!Array.isArray(items))
+            return "a list's items are an array";
+        if (items.length > L.items)
+            return `a list holds at most ${L.items} items`;
+        if (item.style !== undefined &&
+            !LIST_STYLES.includes(item.style))
+            return `a list's style is one of ${LIST_STYLES.join(", ")}`;
+        for (const entry of items) {
+            const problem = arg(entry, depth);
+            if (problem)
+                return problem;
+        }
+        return null;
+    };
+    return mode === "args" ? args(value, 0) : text(value, 0);
+}
+function renderArg(arg, r) {
+    return isTextValue(arg) ? renderValue(arg, r) : arg;
+}
+function renderValue(value, r) {
+    if ("$vestraText" in value) {
+        const template = r.catalog.text(value.$vestraText);
+        return format(template, renderArgs(value.args, r) ?? []);
+    }
+    const locale = LOCALES.includes(r.locale)
+        ? r.locale
+        : "en";
+    const separator = LIST_SEPARATORS[locale][value.style ?? "list"];
+    return value.$vestraList
+        .map((item) => String(argumentText(renderArg(item, r))))
+        .join(separator);
+}
+const argumentText = (value) => typeof value === "number" ? format("{}", [value]) : value;
+function renderArgs(args, r) {
+    if (args === undefined || args === null)
+        return undefined;
+    if (Array.isArray(args))
+        return args.map((arg) => renderArg(arg, r));
+    return Object.fromEntries(Object.entries(args).map(([name, arg]) => [name, renderArg(arg, r)]));
+}
+/**
+ * A text value as the player shows it: the source translated with the
+ * plugin's catalog and formatted with its (rendered) arguments; a list's
+ * items joined with the locale's separator.
+ */
+export function renderText(value, catalog, locale) {
+    return renderValue(value, { catalog, locale });
+}
+/**
+ * Template arguments with their texts rendered (for `format`): what the
+ * player fills a template with.
+ */
+export function renderTemplateArgs(args, catalog, locale) {
+    return renderArgs(args ?? undefined, { catalog, locale });
+}
+/** The English rendering of a text value: the key a menu merges by. */
+export function textKey(value) {
+    return renderValue(value, { catalog: new Catalog(), locale: "en" });
+}
+/**
+ * A property value with every text value in it replaced by its shown
+ * string, as the player does before it hands the value to Slint. Returns
+ * a problem (`textProblem`) instead when a text value is malformed.
+ */
+export function resolveTexts(value, catalog, locale) {
+    let problem = null;
+    const walk = (item) => {
+        if (problem)
+            return item;
+        if (isTextValue(item)) {
+            problem = textProblem(item);
+            return problem ? item : renderText(item, catalog, locale);
+        }
+        if (Array.isArray(item))
+            return item.map(walk);
+        if (plainObject(item)) {
+            // A runtime image or Markdown document stays as it is.
+            if ("$vestraImage" in item || "$vestraMarkdown" in item)
+                return item;
+            return Object.fromEntries(Object.entries(item).map(([key, entry]) => [key, walk(entry)]));
+        }
+        return item;
+    };
+    const out = walk(value);
+    return problem ? { problem } : { value: out };
+}
+/** Whether a value holds a text value anywhere (a cheap pre-check). */
+export function hasTexts(value) {
+    if (isTextValue(value))
+        return true;
+    if (Array.isArray(value))
+        return value.some(hasTexts);
+    if (plainObject(value))
+        return Object.values(value).some(hasTexts);
+    return false;
+}
 const lineEnd = (s, i) => {
     const found = s.slice(i).search(/[\n\r]/);
     return found < 0 ? s.length : i + found;
@@ -671,3 +921,52 @@ export const HOST_ZH_HANS = {
     "Not available in fullscreen": "全屏时不可用",
     "Picture-in-picture is not supported on this system": "此系统不支持画中画",
 };
+// ---------------------------------------------------------------- packages
+/**
+ * The catalog of a package directory for `locale`, as the player loads it:
+ * the compiled `locales/<lang>.json` of a built package, else the source
+ * `locales/<lang>.po`. Empty for English and without a file; a broken file
+ * throws.
+ */
+export function loadPackageCatalog(directory, locale) {
+    if (locale === "en")
+        return new Catalog();
+    const base = join(directory, "locales", locale);
+    if (existsSync(`${base}.json`)) {
+        const compiled = JSON.parse(readFileSync(`${base}.json`, "utf8"));
+        return new Catalog(compiled.messages ?? {});
+    }
+    if (existsSync(`${base}.po`))
+        return new Catalog(compileCatalog(locale, parsePo(readFileSync(`${base}.po`, "utf8")).entries).messages);
+    return new Catalog();
+}
+// ---------------------------------------------------------------- columns
+const WIDE = /[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꀀ-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦\u{1F300}-\u{1F64F}\u{1F900}-\u{1F9FF}\u{20000}-\u{3FFFD}]/u;
+const ZERO = /[\p{Mn}\p{Me}​-‏]/u;
+/** Columns of one character: 2 wide (East Asian), 0 combining, else 1. */
+const columnsOf = (c) => (ZERO.test(c) ? 0 : WIDE.test(c) ? 2 : 1);
+/**
+ * Each line of `text` cut to `max` columns, ending with `…` when cut, as
+ * the player cuts an OSD panel's lines (`OsdPanelOptions.maxColumns`; the
+ * player measures with Unicode's East Asian Width, this is close to it).
+ */
+export function fitColumns(text, max) {
+    return text
+        .split("\n")
+        .map((line) => {
+        let used = 0;
+        const chars = [...line];
+        if (chars.reduce((n, c) => n + columnsOf(c), 0) <= max)
+            return line;
+        let out = "";
+        for (const c of chars) {
+            const width = columnsOf(c);
+            if (used + width > max - 1)
+                break;
+            out += c;
+            used += width;
+        }
+        return `${out}…`;
+    })
+        .join("\n");
+}

package/dist/player-runtime.d.ts

@@ -13,6 +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, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, scanSlint, } from "./i18n.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,6 +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, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, scanSlint, } from "./i18n.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/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,