@vestra-player/sdk 1.5.11 → 1.5.13

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.5.13
+
+**`i18n extract` keeps the translator's comments and writes the right number of plural forms.** A fix; `apiVersion` stays `vestra/1`.
+
+- Merging into a `locales/<lang>.po` kept only the header's text: comment lines before the header (`# Reviewed by an AI reviewer on 2026-10-25`, `# Translator: …`, `#, fuzzy`) and the translator's own `# ` comments on entries were dropped. Both are now kept as written (`parsePo` returns `headerComments`, entries carry `comments`; `writePo` writes them).
+- A plural entry has exactly `nplurals` `msgstr[n]` lines, from the file's `Plural-Forms` (or the language: one for `ja`, `ko`, `zh-Hans`). Before, every plural entry got an empty `msgstr[1]`, also in one-form languages; a merge now removes such an extra empty line (a filled one stays).
+
+## 1.5.12
+
+**Keys of disabled commands pass on; `i18n check` fails on stale catalogs; translator notes in tables; the Button follows its text.** A fix release; `apiVersion` stays `vestra/1`.
+
+- **`TestHost.press` matches the player (0.4.3) for disabled commands.** A disabled command no longer swallows its key: the key goes to the next command bound to it (the one it shadowed in a conflict, then the global scope after a panel binding). With only disabled commands left, the first one with a `reason` shows the reason on the OSD and eats the key; without a reason the key reaches the focused control. `press` now resolves with what happened, `"ran"`, `"reason"` (see `host.osd`) or `"passed"`, instead of rejecting for a disabled command; it still rejects when nothing is bound and when the command that runs is busy. A test that expected `press` to reject for a disabled command now gets `"passed"` or `"reason"`.
+- **`vestra-plugin i18n check` exits with 1** when `locales/messages.pot` is out of date, missing while `.po` files exist, or a `.po` lacks some of the template's messages, so CI catches a forgotten `extract`. Before, it printed these and exited 0. The other findings stay warnings, and `vestra-plugin check` still only prints them.
+- **`TRANSLATORS:` notes on `as const` table entries.** A comment before a property or element of an object or array literal under `as const` (at any depth) now reaches the translators like one at a call site; before, texts extracted through a table lost their notes.
+- **`slint/vestra/widgets.slint`** (the copy of the player's library): `Button`'s preferred width follows its label (the minimum width is unchanged), so a longer translated label widens the button instead of overflowing it.
+
 ## 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).

package/README.md

@@ -83,7 +83,7 @@ Complete, tested plugins in [`examples/`](https://github.com/vestrasys/vestra-pl
 | `vestra-plugin build [dir...] [--version x.y.z]`            | Writes `dist/`: types stripped, files copied, manifest versioned.          |
 | `vestra-plugin pack [dir...] [--version x.y.z] [--out dir]` | Builds, then packs `dist/` as `<id>-<version>.vxp`.                        |
 | `vestra-plugin i18n extract [dir...] [--locale lang]`       | Collects the texts to translate into `locales/`, keeping translations.     |
-| `vestra-plugin i18n check [dir...]`                         | Translation coverage and untranslatable text (warnings only).              |
+| `vestra-plugin i18n check [dir...]`                         | Translation coverage and untranslatable text; fails on stale catalogs.     |
 
 ## Compatibility
 

package/bin/vestra-plugin.mjs

@@ -29,7 +29,8 @@
  *   i18n check    coverage per language, placeholder and plural problems, a
  *                 stale messages.pot, and texts that cannot be translated
  *                 (composed in TypeScript, not literals, not English, Slint
- *                 text without @tr); warnings only, an unreadable .po fails
+ *                 text without @tr) as warnings; fails (exit 1) on a stale
+ *                 messages.pot, a .po missing messages, an unreadable file
  *
  * `check` prints the same i18n warnings when the plugin has locales/;
  * `build` compiles locales/<lang>.po to dist/locales/<lang>.json (the .po
@@ -430,7 +431,8 @@ async function i18nCheck(target) {
   dependencies(target);
   const { warnings, errors } = await i18nReport(target);
   for (const line of warnings) console.log(`${target.name}: i18n: ${line}`);
-  if (errors.length) fail(`${target.name}: ${errors.join("; ")}`);
+  // A stale messages.pot, a .po missing messages, an unreadable file.
+  if (errors.length) fail(`${target.name}: i18n: ${errors.join("; ")}`);
   if (!warnings.length) console.log(`${target.name}: i18n: no problems`);
 }
 

package/dist/i18n-tools.js

@@ -100,6 +100,34 @@ function ignored(node, text) {
         .slice(node.getFullStart(), node.getStart())
         .includes("i18n-ignore");
 }
+/**
+ * A string that is an entry (a property value or an element) of an object
+ * or array literal inside `… as const`, at any depth.
+ */
+function inConstTable(node) {
+    let current;
+    if (ts.isPropertyAssignment(node.parent) && node.parent.initializer === node)
+        current = node.parent.parent;
+    else if (ts.isArrayLiteralExpression(node.parent))
+        current = node.parent;
+    else
+        return false;
+    for (;;) {
+        const parent = current.parent;
+        if (ts.isAsExpression(parent) &&
+            ts.isTypeReferenceNode(parent.type) &&
+            ts.isIdentifier(parent.type.typeName) &&
+            parent.type.typeName.text === "const")
+            return true;
+        if (ts.isPropertyAssignment(parent))
+            current = parent.parent;
+        else if (ts.isArrayLiteralExpression(parent) ||
+            ts.isParenthesizedExpression(parent))
+            current = parent;
+        else
+            return false;
+    }
+}
 /** The statement (or class member) a node belongs to. */
 function statementOf(node) {
     let current = node;
@@ -111,6 +139,11 @@ function statementOf(node) {
 }
 class Extractor {
     found = [];
+    /**
+     * `TRANSLATORS:` notes on entries of `as const` tables, by text: a table
+     * entry is extracted through its literal type, which has no comments.
+     */
+    tableNotes = new Map();
     findings = [];
     #checker;
     constructor(checker) {
@@ -302,6 +335,20 @@ class Extractor {
         const visit = (node) => {
             if (ts.isCallExpression(node))
                 this.#call(node, file, source, text);
+            if ((ts.isStringLiteral(node) ||
+                ts.isNoSubstitutionTemplateLiteral(node)) &&
+                inConstTable(node)) {
+                // The comment sits before the entry: the property, or the element.
+                const entry = ts.isPropertyAssignment(node.parent) ? node.parent : node;
+                const notes = notesOf(entry, text);
+                if (notes.length) {
+                    const known = this.tableNotes.get(node.text) ?? [];
+                    for (const note of notes)
+                        if (!known.includes(note))
+                            known.push(note);
+                    this.tableNotes.set(node.text, known);
+                }
+            }
             // A text value written as data: `{ $vestraText: "…" }`.
             if (ts.isPropertyAssignment(node) &&
                 (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) &&
@@ -589,7 +636,10 @@ export function extract(options) {
         }
         if (occurrence.plural !== undefined && message.plural === undefined)
             message.plural = occurrence.plural;
-        for (const note of occurrence.notes)
+        const tableNotes = occurrence.context === undefined
+            ? (extractor.tableNotes.get(occurrence.id) ?? [])
+            : [];
+        for (const note of [...occurrence.notes, ...tableNotes])
             if (!message.notes.includes(note))
                 message.notes.push(note);
         if (!message.references.includes(reference))
@@ -598,10 +648,17 @@ export function extract(options) {
     const findings = extractor.findings.sort((a, b) => a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1);
     return { messages: [...messages.values()], findings };
 }
-const entryOf = (message) => {
+/** `msgstr[n]` lines a plural entry has: the header's `nplurals`, else the language's. */
+const formsOf = (language, header) => {
+    const declared = /nplurals\s*=\s*(\d+)/.exec(header ?? "")?.[1];
+    if (declared !== undefined && Number(declared) >= 1)
+        return Number(declared);
+    return ONE_FORM.has(language) ? 1 : 2;
+};
+const entryOf = (message, forms = 2) => {
     const entry = {
         id: message.id,
-        strings: message.plural === undefined ? [""] : ["", ""],
+        strings: message.plural === undefined ? [""] : Array(forms).fill(""),
         fuzzy: false,
         notes: [...message.notes],
         references: [...message.references],
@@ -619,7 +676,7 @@ export function template(manifest, messages) {
     const project = [manifest.id, manifest.version]
         .filter((part) => typeof part === "string")
         .join(" ");
-    return writePo(`Project-Id-Version: ${project}\nContent-Type: text/plain; charset=UTF-8\nContent-Transfer-Encoding: 8bit\n`, messages.map(entryOf));
+    return writePo(`Project-Id-Version: ${project}\nContent-Type: text/plain; charset=UTF-8\nContent-Transfer-Encoding: 8bit\n`, messages.map((message) => entryOf(message)));
 }
 /** The header of a new `<lang>.po`. */
 export const newHeader = (language) => `Language: ${language}\nContent-Type: text/plain; charset=UTF-8\nContent-Transfer-Encoding: 8bit\nPlural-Forms: ${pluralForms(language)}\n`;
@@ -637,20 +694,30 @@ export function merge(existing, language, messages) {
         old.set(keyOf(entry.context, entry.id), entry);
     const result = [];
     const present = new Set();
+    // A plural entry has exactly nplurals msgstr[n] (one for ja, ko,
+    // zh-Hans); extra empty ones are dropped, filled ones kept.
+    const forms = formsOf(language, parsed?.header ?? newHeader(language));
     let added = 0;
     let translated = 0;
     for (const message of messages) {
         const key = keyOf(message.context, message.id);
         present.add(key);
-        const entry = entryOf(message);
+        const entry = entryOf(message, forms);
         const before = old.get(key);
+        // The translator's own comments stay with their message.
+        if (before?.comments?.length)
+            entry.comments = [...before.comments];
         if (before && hasText(before)) {
             entry.strings = [...before.strings];
             if (message.plural === undefined)
                 entry.strings = [entry.strings[0]];
-            else
-                while (entry.strings.length < 2)
+            else {
+                while (entry.strings.length < forms)
                     entry.strings.push("");
+                while (entry.strings.length > forms &&
+                    entry.strings[entry.strings.length - 1] === "")
+                    entry.strings.pop();
+            }
             entry.fuzzy = before.fuzzy;
             entry.flags = [...before.flags];
         }
@@ -668,7 +735,7 @@ export function merge(existing, language, messages) {
         obsolete++;
     }
     return {
-        text: writePo(parsed?.header ?? newHeader(language), result),
+        text: writePo(parsed?.header ?? newHeader(language), result, parsed?.headerComments ?? []),
         total: messages.length,
         translated,
         added,
@@ -683,24 +750,26 @@ export function checkCatalogs(directory, messages, findings) {
     const pot = join(locales, "messages.pot");
     const keys = (entries) => new Set(entries.map((e) => `${keyOf(e.context, e.id)}\u0000${e.plural ?? ""}`));
     const wanted = keys(messages);
+    const files = existsSync(locales)
+        ? readdirSync(locales)
+            .filter((name) => name.endsWith(".po"))
+            .sort()
+        : [];
+    // A stale template or a .po without some of its messages fails
+    // `i18n check` (an error); `check` prints it like the warnings.
     if (!existsSync(pot))
-        warnings.push("locales/messages.pot is missing: run vestra-plugin i18n extract");
+        (files.length ? errors : warnings).push("locales/messages.pot is missing: run vestra-plugin i18n extract");
     else {
         try {
             const have = keys(parsePo(readFileSync(pot, "utf8")).entries);
             const same = have.size === wanted.size && [...wanted].every((key) => have.has(key));
             if (!same)
-                warnings.push("locales/messages.pot is out of date: run vestra-plugin i18n extract");
+                errors.push("locales/messages.pot is out of date: run vestra-plugin i18n extract");
         }
         catch (error) {
             errors.push(`locales/messages.pot: ${error.message}`);
         }
     }
-    const files = existsSync(locales)
-        ? readdirSync(locales)
-            .filter((name) => name.endsWith(".po"))
-            .sort()
-        : [];
     for (const name of files) {
         const language = name.slice(0, -3);
         if (language === "en") {
@@ -729,7 +798,7 @@ export function checkCatalogs(directory, messages, findings) {
         const inFile = keys(live);
         const missing = [...wanted].filter((key) => !inFile.has(key)).length;
         if (missing)
-            warnings.push(`locales/${name}: ${missing} ${missing === 1 ? "message is" : "messages are"} not in this file: run vestra-plugin i18n extract`);
+            errors.push(`locales/${name}: ${missing} ${missing === 1 ? "message is" : "messages are"} not in this file: run vestra-plugin i18n extract`);
         for (const entry of live) {
             entry.strings.forEach((text, form) => {
                 if (text === "")

package/dist/i18n.d.ts

@@ -25,16 +25,23 @@ export interface PoEntry {
     flags: string[];
     /** A `#~` entry: no longer in the source. */
     obsolete: boolean;
+    /** `# ` lines: the translator's own comments, kept as written. */
+    comments?: string[];
 }
 /** The catalog key: `msgid`, or `msgctxt` U+0004 `msgid`. */
 export declare const keyOf: (context: string | undefined, id: string) => string;
 /** Parse a `.po` (or `.pot`) file. Throws with the line number on errors. */
 export declare function parsePo(text: string): {
     header: string;
+    /** The comment lines before the header entry, as written (`# Reviewed…`, `#, fuzzy`). */
+    headerComments: string[];
     entries: PoEntry[];
 };
-/** Write a `.po` file: the header, then the entries in the given order. */
-export declare function writePo(header: string, entries: readonly PoEntry[]): string;
+/**
+ * Write a `.po` file: the header (after its comment lines, as written),
+ * then the entries in the given order.
+ */
+export declare function writePo(header: string, entries: readonly PoEntry[], headerComments?: readonly string[]): string;
 /** A message of a compiled catalog: a translation, or `[one, other]`. */
 export type CompiledMessage = string | [string, string];
 /**

package/dist/i18n.js

@@ -23,6 +23,9 @@ const translated = (entry) => !entry.fuzzy && !entry.obsolete && (entry.strings[
 export function parsePo(text) {
     const entries = [];
     let header = "";
+    let headerComments = [];
+    // Every comment line of the entry being read, as written.
+    let raw = [];
     const blank = () => ({
         id: "",
         strings: [],
@@ -39,11 +42,14 @@ export function parsePo(text) {
     let pending = blank();
     const finish = () => {
         if (started) {
-            if (entry.id === "" && entry.context === undefined)
+            if (entry.id === "" && entry.context === undefined) {
                 header = entry.strings[0] ?? "";
+                headerComments = raw;
+            }
             else
                 entries.push(entry);
         }
+        raw = [];
         entry = blank();
         started = false;
         field = "none";
@@ -66,8 +72,11 @@ export function parsePo(text) {
         else if (line.startsWith("#")) {
             if (started)
                 finish();
+            raw.push(lines[index].trimEnd());
             const body = line.slice(2).trim();
-            if (line.startsWith("#."))
+            if (line === "#" || line.startsWith("# "))
+                (pending.comments ??= []).push(line.slice(2));
+            else if (line.startsWith("#."))
                 pending.notes.push(body);
             else if (line.startsWith("#:"))
                 pending.references.push(...body.split(/\s+/).filter(Boolean));
@@ -135,7 +144,7 @@ export function parsePo(text) {
         field = next;
     }
     finish();
-    return { header, entries };
+    return { header, headerComments, entries };
 }
 function unquote(text, at) {
     if (text.length < 2 || !text.startsWith('"') || !text.endsWith('"'))
@@ -172,12 +181,19 @@ function field(keyword, text) {
         return `${keyword} ${poString(text)}`;
     return [`${keyword} ""`, ...parts.map(poString)].join("\n");
 }
-/** Write a `.po` file: the header, then the entries in the given order. */
-export function writePo(header, entries) {
-    const blocks = [`msgid ""\n${field("msgstr", header)}`];
+/**
+ * Write a `.po` file: the header (after its comment lines, as written),
+ * then the entries in the given order.
+ */
+export function writePo(header, entries, headerComments = []) {
+    const blocks = [
+        [...headerComments, `msgid ""`, field("msgstr", header)].join("\n"),
+    ];
     for (const entry of entries) {
         const prefix = entry.obsolete ? "#~ " : "";
         const lines = [];
+        for (const comment of entry.comments ?? [])
+            lines.push(comment === "" ? "#" : `# ${comment}`);
         for (const note of entry.notes)
             lines.push(`#. ${note}`);
         if (entry.references.length && !entry.obsolete)

package/dist/plugin/testing.d.ts

@@ -1242,11 +1242,20 @@ export declare class TestHost implements Transport {
     failStream(producerId: number, message: string): void;
     /**
      * Press a binding like the host's table would: panel-focus bindings first
-     * when `panel` is true, then global ones; the earliest registration wins a
-     * conflict. Resolves after the command ran; rejects when nothing is bound
-     * or the command is disabled or busy. Bindings use the reference syntax
-     * (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`); the player's core actions
-     * match first, and user overrides in `bindings.overlay` apply.
+     * when `panel` is true, then global ones; within a scope the earliest
+     * registration first (the player's own commands before the plugin's), as
+     * the conflict rule orders them. A disabled command lets the key pass to
+     * the next command bound to it (SDK 1.5.12, as player 0.4.3): the one it
+     * shadowed, then the global scope. The first enabled one runs; `press`
+     * resolves after it ran (`"ran"`), or rejects when it is busy. When only
+     * disabled commands hold the key, the first one with a `reason` shows the
+     * reason on the OSD and eats the key (`"reason"`, see `host.osd`);
+     * without a reason the key goes on to the focused control (`"passed"`,
+     * nothing runs). Rejects when nothing is bound. Bindings use the
+     * reference syntax (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`), and user
+     * overrides in `bindings.overlay` apply.
+     *
+     * @returns What the key did: `"ran"`, `"reason"` or `"passed"`.
      *
      * @example
      * ```ts
@@ -1256,7 +1265,7 @@ export declare class TestHost implements Transport {
      */
     press(binding: string, options?: {
         panel?: boolean;
-    }): Promise<void>;
+    }): Promise<"ran" | "reason" | "passed">;
     /**
      * Bindings declared by more than one command, each as
      * `[binding, winner, ...ignored]` (command ids; core actions as

package/dist/plugin/testing.js

@@ -1749,11 +1749,20 @@ export class TestHost {
     }
     /**
      * Press a binding like the host's table would: panel-focus bindings first
-     * when `panel` is true, then global ones; the earliest registration wins a
-     * conflict. Resolves after the command ran; rejects when nothing is bound
-     * or the command is disabled or busy. Bindings use the reference syntax
-     * (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`); the player's core actions
-     * match first, and user overrides in `bindings.overlay` apply.
+     * when `panel` is true, then global ones; within a scope the earliest
+     * registration first (the player's own commands before the plugin's), as
+     * the conflict rule orders them. A disabled command lets the key pass to
+     * the next command bound to it (SDK 1.5.12, as player 0.4.3): the one it
+     * shadowed, then the global scope. The first enabled one runs; `press`
+     * resolves after it ran (`"ran"`), or rejects when it is busy. When only
+     * disabled commands hold the key, the first one with a `reason` shows the
+     * reason on the OSD and eats the key (`"reason"`, see `host.osd`);
+     * without a reason the key goes on to the focused control (`"passed"`,
+     * nothing runs). Rejects when nothing is bound. Bindings use the
+     * reference syntax (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`), and user
+     * overrides in `bindings.overlay` apply.
+     *
+     * @returns What the key did: `"ran"`, `"reason"` or `"passed"`.
      *
      * @example
      * ```ts
@@ -1763,11 +1772,28 @@ export class TestHost {
      */
     async press(binding, options = {}) {
         const claims = this.#claims();
-        const id = (options.panel ? claims.get(`panel ${binding}`)?.[0] : undefined) ??
-            claims.get(`global ${binding}`)?.[0];
-        if (!id)
+        const ids = [
+            ...(options.panel ? (claims.get(`panel ${binding}`) ?? []) : []),
+            ...(claims.get(`global ${binding}`) ?? []),
+        ];
+        if (!ids.length)
             throw new Error(`test host: nothing is bound to ${binding}`);
-        await (this.coreCommands.get(id) ?? this.command(id)).run();
+        const command = (id) => this.coreCommands.get(id) ?? this.command(id);
+        const enabled = ids.find((id) => command(id).state.enabled);
+        if (enabled !== undefined) {
+            await command(enabled).run();
+            return "ran";
+        }
+        for (const id of ids) {
+            const reason = this.commands.has(id)
+                ? command(id).display.reason
+                : command(id).state.reason;
+            if (typeof reason === "string" && reason !== "") {
+                this.osd.push(reason);
+                return "reason";
+            }
+        }
+        return "passed";
     }
     /**
      * Bindings declared by more than one command, each as

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.11: full reference
+# @vestra-player/sdk 1.5.13: full reference
 
 > Everything needed to write a Vestra Player plugin (plugin API `vestra/1`): the guides, every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its documentation, and the complete source of the example plugins. Generated from the SDK's sources by scripts/llms.mjs; the short index is llms.txt.
 
@@ -5230,11 +5230,12 @@ class TestHost implements Transport {
    */
   failStream(producerId: number, message: string): void;
   /**
-   * Press a binding like the host's table would: panel-focus bindings first when `panel` is true, then global ones; the earliest registration wins a conflict. Resolves after the command ran; rejects when nothing is bound or the command is disabled or busy. Bindings use the reference syntax (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`); the player's core actions match first, and user overrides in `bindings.overlay` apply.
+   * Press a binding like the host's table would: panel-focus bindings first when `panel` is true, then global ones; within a scope the earliest registration first (the player's own commands before the plugin's), as the conflict rule orders them. A disabled command lets the key pass to the next command bound to it (SDK 1.5.12, as player 0.4.3): the one it shadowed, then the global scope. The first enabled one runs; `press` resolves after it ran (`"ran"`), or rejects when it is busy. When only disabled commands hold the key, the first one with a `reason` shows the reason on the OSD and eats the key (`"reason"`, see `host.osd`); without a reason the key goes on to the focused control (`"passed"`, nothing runs). Rejects when nothing is bound. Bindings use the reference syntax (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`), and user overrides in `bindings.overlay` apply.
+   * @returns What the key did: `"ran"`, `"reason"` or `"passed"`.
    */
   press(binding: string, options?: {
     panel?: boolean;
-  }): Promise<void>;
+  }): Promise<"ran" | "reason" | "passed">;
   /** Bindings declared by more than one command, each as `[binding, winner, ...ignored]` (command ids; core actions as `host/<id>`). Empty when there are none. */
   get conflicts(): string[][];
   /** The binding overlay `plugin.bindings.set` writes (`"<plugin>/<command>"` to inputs; preset it to simulate saved overrides). `press` honours it. */

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.11: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. llms-full.txt, next to this file, has every declaration, the guides and the examples; L<n> below are its line numbers.
+> @vestra-player/sdk 1.5.13: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. llms-full.txt, next to this file, has every declaration, the guides and the examples; L<n> below are its line numbers.
 
 **How plugins run**
 
@@ -121,7 +121,7 @@ test("shows the position", async () => {
 - `vestra-plugin build [dir...] [--version x.y.z]`: Writes `dist/`: types stripped, files copied, manifest versioned.
 - `vestra-plugin pack [dir...] [--version x.y.z] [--out dir]`: Builds, then packs `dist/` as `<id>-<version>.vxp`.
 - `vestra-plugin i18n extract [dir...] [--locale lang]`: Collects the texts to translate into `locales/`, keeping translations.
-- `vestra-plugin i18n check [dir...]`: Translation coverage and untranslatable text (warnings only).
+- `vestra-plugin i18n check [dir...]`: Translation coverage and untranslatable text; fails on stale catalogs.
 - `vestra-player --plugin <dir>` runs a plugin from source, no build needed.
 
 **Error codes** (`error.code`; branch on it, never on `message`)
@@ -153,7 +153,7 @@ test("shows the position", async () => {
 - [How-to: Keep a slider responsive while dragging](https://vestrasys.github.io/vestra-player-sdk/documents/Keep_a_slider_responsive_while_dragging.html): L627–801
 - [How-to: Remember a window's state between runs](https://vestrasys.github.io/vestra-player-sdk/documents/Remember_a_window_s_state_between_runs.html): L802–931
 - [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L932–4427
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html) (TestHost, startPlugin): L4428–5537
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html) (TestHost, startPlugin): L4428–5538
 
 ## API
 
@@ -193,15 +193,15 @@ Where each module of `plugin` is declared:
 
 Complete plugins with tests, in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples) and in llms-full.txt:
 
-- hello: The README Quick start: one menu command and an on-screen message. L5954–6043
-- blur: A tool window with one slider that blurs the playing video. L6044–6305
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L6306–6638
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L6639–6823
-- panel-menu: A sidebar panel with its own right-click menu. L6824–7029
-- menus: Radio menu items, separator groups and a menu item whose title changes. L7030–7189
-- theme-widgets: A tool window drawn with the player's theme and widgets. L7190–7353
-- markdown: A window that shows a Markdown document. L7354–7547
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L7548–7715
+- hello: The README Quick start: one menu command and an on-screen message. L5955–6044
+- blur: A tool window with one slider that blurs the playing video. L6045–6306
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L6307–6639
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L6640–6824
+- panel-menu: A sidebar panel with its own right-click menu. L6825–7030
+- menus: Radio menu items, separator groups and a menu item whose title changes. L7031–7190
+- theme-widgets: A tool window drawn with the player's theme and widgets. L7191–7354
+- markdown: A window that shows a Markdown document. L7355–7548
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L7549–7716
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.11",
+  "version": "1.5.13",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {

package/slint/vestra/widgets.slint

@@ -81,13 +81,17 @@ export component Button {
     min-height: root.icon-only ? root.icon-height : root.small ? Theme.button-small-height : Theme.button-height;
     min-width: root.icon-only ? root.icon-width : root.small ? Theme.button-small-min-width : Theme.button-min-width;
     preferred-height: self.min-height;
+    // A longer (translated) label widens the button instead of overflowing it.
+    preferred-width: root.icon-only ? self.min-width
+        : max(self.min-width, label.preferred-width + 2 * Theme.button-padding);
     accessible-role: button;
     accessible-label: root.text;
     accessible-enabled: root.enabled;
     accessible-checkable: root.icon-only;
     accessible-checked: root.checked;
     accessible-action-default => { if root.enabled { root.clicked(); } }
-    if !root.icon-only: Rectangle {
+    Rectangle {
+        visible: !root.icon-only;
         border-radius: Theme.radius-control;
         background: !root.enabled ? Theme.button-disabled
             : touch.pressed ? Theme.button-press
@@ -96,7 +100,7 @@ export component Button {
             padding-left: Theme.button-padding;
             padding-right: Theme.button-padding;
             alignment: center;
-            Text {
+            label := Text {
                 text: root.text;
                 color: root.enabled ? Theme.text-list : Theme.text-dim;
                 font-size: Theme.font-body;