@vestra-player/sdk 1.5.47 → 1.5.48

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.5.48
+
+**Who must change: nobody, but plugin tests may now fail.** No changes to the TypeScript API beyond new fields of `COMMAND_LIMITS`, `apiVersion` stays `vestra/1`, no new capability, no player version needed. `TestHost` now refuses the command declarations the player has always refused: a plugin test that starts failing shows a menu item, key or reason the real player already rejected (the command never appeared, or the plugin failed to activate). Fix the declaration, not the test.
+
+- **`TestHost` checks a command declaration as the player does** (`commands.register`, in the player's order, with its codes and messages):
+  - the local id: 1–128 bytes of ASCII letters, digits, `.`, `_` and `-` (`invalid`);
+  - the title (128 bytes), each path segment (80 bytes) and the group (80 bytes, default `"domain"`): not empty, no control character (C0, DEL and C1), no whitespace at either end (Unicode White_Space, as the player's `trim`). A text value is checked on its English rendering, which is also the key menus merge by. The message names the field: `invalid command: path segment requires 1..=80 bytes, no controls or surrounding whitespace`;
+  - at most 8 path segments, an `order` within ±1,000,000, bindings in the player's syntax, each once (`invalid`);
+  - the state's reason: at most 512 bytes as shown, the same text rules (`invalid` at registration; `command` on an update, as the player answers every refused update);
+  - a path that repeats another command's or is a submenu of one, or one of whose submenus is a command, the player's own commands included (`Audio ▸ Mute ▸ …`, `Playback ▸ Speed` as an item, `Quit`, `Toggle Fullscreen ▸ …`): `conflict` (`command conflict: menu path duplicates a command or collides with a leaf/group`). The total (`COMMAND_LIMITS.total`) counts all 19 of the player's own commands, Toggle Fullscreen, Enter and Leave Fullscreen, Quit and Toggle Sidebar included;
+  - an id registered twice: `conflict` (was `command`); an unknown `@` menu id, a bar button without a path or with an unknown icon, give the player's full messages;
+  - an update of a command that is not registered rejects with `command` (`command missing: owner 1 / <id>`; was a plain `Error`), a revision that is not a positive integer with `invalid` (`positive revision required`), and a stale one names the current revision.
+- **The seek items follow `setStepSeek`.** `host.coreAction("seek-backward")` and `seek-forward` carry the step in their path and title (`Playback ▸ Seek ▸ Back 2.5 s`), as the player registers them again when the step changes; they were fixed at 5 s.
+- **`COMMAND_LIMITS`** gains the player's declaration limits: `depth` (8), `idBytes` (128), `titleBytes` (128), `segmentBytes` (80), `groupBytes` (80), `reasonBytes` (512) and `order` (1,000,000), so the player's tests can check that they agree.
+- _Commands_: `CommandOptions` and `Commands.add` say which checks the player makes (`ready` rejects with `invalid`) and which `add` makes at once.
+
 ## 1.5.47
 
 **Who must change: nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability, no player version needed. The built-in command table follows player 0.6.0's new default keys: a plugin whose documentation or tests list the player's default keys (from `BUILTIN_COMMANDS`, or Escape, Enter, F11 and the side mouse buttons by hand) should update them.

package/dist/commands.d.ts

@@ -11,6 +11,9 @@ import type { ConditionJson } from "./plugin/when.ts";
  * already registered are unaffected, and disposing a command frees its slot
  * at once. {@link TestHost} enforces the same caps.
  *
+ * The other fields are the player's rules for one declaration (since
+ * 1.5.48): a command past them is refused with `invalid`, the same way.
+ *
  * For menus built from media content (tracks, chapters, presets), set your
  * own sensible display cap well below `perPlugin`.
  *
@@ -41,6 +44,53 @@ export declare const COMMAND_LIMITS: {
     readonly perPlugin: 160;
     /** Commands of every plugin plus the player's own, together (1024). */
     readonly total: 1024;
+    /**
+     * Segments of a menu path, the leaf included.
+     *
+     * @since 1.5.48
+     */
+    readonly depth: 8;
+    /**
+     * UTF-8 bytes of a command's local id: ASCII letters, digits, `.`,
+     * `_` and `-`.
+     *
+     * @since 1.5.48
+     */
+    readonly idBytes: 128;
+    /**
+     * UTF-8 bytes of a title, a text value counted by its English
+     * rendering. Like every command text: not empty, no control characters,
+     * no whitespace at either end.
+     *
+     * @since 1.5.48
+     */
+    readonly titleBytes: 128;
+    /**
+     * UTF-8 bytes of a menu path segment, a text value counted by its
+     * English rendering.
+     *
+     * @since 1.5.48
+     */
+    readonly segmentBytes: 80;
+    /**
+     * UTF-8 bytes of a group.
+     *
+     * @since 1.5.48
+     */
+    readonly groupBytes: 80;
+    /**
+     * UTF-8 bytes of a state's reason, as shown in the player's
+     * language.
+     *
+     * @since 1.5.48
+     */
+    readonly reasonBytes: 512;
+    /**
+     * The largest `order` either way: an order is within ±1,000,000.
+     *
+     * @since 1.5.48
+     */
+    readonly order: 1000000;
 };
 /**
  * The player's built-in top-level menus, by id. Write `@<id>` as the first

package/dist/commands.js

@@ -7,6 +7,9 @@
  * already registered are unaffected, and disposing a command frees its slot
  * at once. {@link TestHost} enforces the same caps.
  *
+ * The other fields are the player's rules for one declaration (since
+ * 1.5.48): a command past them is refused with `invalid`, the same way.
+ *
  * For menus built from media content (tracks, chapters, presets), set your
  * own sensible display cap well below `perPlugin`.
  *
@@ -37,6 +40,53 @@ export const COMMAND_LIMITS = {
     perPlugin: 160,
     /** Commands of every plugin plus the player's own, together (1024). */
     total: 1024,
+    /**
+     * Segments of a menu path, the leaf included.
+     *
+     * @since 1.5.48
+     */
+    depth: 8,
+    /**
+     * UTF-8 bytes of a command's local id: ASCII letters, digits, `.`,
+     * `_` and `-`.
+     *
+     * @since 1.5.48
+     */
+    idBytes: 128,
+    /**
+     * UTF-8 bytes of a title, a text value counted by its English
+     * rendering. Like every command text: not empty, no control characters,
+     * no whitespace at either end.
+     *
+     * @since 1.5.48
+     */
+    titleBytes: 128,
+    /**
+     * UTF-8 bytes of a menu path segment, a text value counted by its
+     * English rendering.
+     *
+     * @since 1.5.48
+     */
+    segmentBytes: 80,
+    /**
+     * UTF-8 bytes of a group.
+     *
+     * @since 1.5.48
+     */
+    groupBytes: 80,
+    /**
+     * UTF-8 bytes of a state's reason, as shown in the player's
+     * language.
+     *
+     * @since 1.5.48
+     */
+    reasonBytes: 512,
+    /**
+     * The largest `order` either way: an order is within ±1,000,000.
+     *
+     * @since 1.5.48
+     */
+    order: 1_000_000,
 };
 /**
  * The player's built-in top-level menus, by id. Write `@<id>` as the first

package/dist/plugin/testing.js

@@ -78,7 +78,7 @@ import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.js";
 import { OSD_LIMITS } from "./osd.js";
 import { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./services.js";
 import { SUBTITLE_LIMITS } from "./subtitles.js";
-import { BINDING_INPUTS } from "./bindings.js";
+import { BINDING_INPUTS, canonical } from "./bindings.js";
 import { THEME_PALETTES } from "../palettes.js";
 import { IMAGE_LIMITS, UI_VALUE_LIMITS, valueLimitProblem } from "./values.js";
 import { validStep } from "./player.js";
@@ -316,6 +316,64 @@ const TEST_ZH_HANS = {
 };
 /** The player's limit of sidebar tabs. */
 const MAX_SIDEBAR_TABS = 8;
+/**
+ * The player's refusal of a declaration (commands.rs `CommandError`): code
+ * `invalid`, `conflict` or `limit`, its message prefixed as the player's.
+ */
+const commandInvalid = (message) => new HostError("invalid", `invalid command: ${message}`);
+const commandConflict = (message) => new HostError("conflict", `command conflict: ${message}`);
+/**
+ * The player's check of a command text (commands.rs `text`): 1 to `limit`
+ * UTF-8 bytes, no control character (`char::is_control`: C0, DEL and C1)
+ * and no whitespace at either end (`str::trim`: Unicode White_Space).
+ */
+function commandText(value, label, limit) {
+    const bytes = Buffer.byteLength(value, "utf8");
+    if (bytes === 0 ||
+        bytes > limit ||
+        /^\p{White_Space}|\p{White_Space}$/u.test(value) ||
+        /\p{Cc}/u.test(value))
+        throw commandInvalid(`${label} requires 1..=${limit} bytes, no controls or surrounding whitespace`);
+}
+/**
+ * A menu text (title or path segment) as the player keys it: a string as
+ * declared, a text value by its English rendering (capabilities/commands.rs
+ * `menu_text`).
+ */
+function menuTextKey(value) {
+    if (typeof value === "string")
+        return value;
+    if (!isTextValue(value))
+        throw new HostError("invalid", "title and path segments are strings or texts");
+    if ("$vestraList" in value)
+        throw new HostError("invalid", "a menu text is a string or a text, not a list");
+    const problem = textProblem(value);
+    if (problem)
+        throw new HostError("invalid", problem);
+    return textKey(value);
+}
+/**
+ * The declaration checks of the player's `Registry::register`, in its
+ * order, on the keyed title and path (`@<id>` already replaced).
+ */
+function checkDeclaration(id, title, path, declaration) {
+    commandText(id, "localId", COMMAND_LIMITS.idBytes);
+    if (!/^[A-Za-z0-9._-]+$/.test(id))
+        throw commandInvalid("localId permits ASCII letters, digits, '.', '_' and '-'");
+    commandText(title, "title", COMMAND_LIMITS.titleBytes);
+    if (path.length > COMMAND_LIMITS.depth)
+        throw commandInvalid(`menu path allows at most ${COMMAND_LIMITS.depth} segments`);
+    for (const segment of path)
+        commandText(segment, "path segment", COMMAND_LIMITS.segmentBytes);
+    const group = declaration.group ?? "domain";
+    if (typeof group !== "string")
+        throw new HostError("invalid", "group is a string");
+    commandText(group, "group", COMMAND_LIMITS.groupBytes);
+    const order = declaration.order ?? 0;
+    if (!Number.isInteger(order) ||
+        Math.abs(order) > COMMAND_LIMITS.order)
+        throw commandInvalid("order must be within ±1000000");
+}
 /**
  * An in-memory fake Vestra Player for plugin tests.
  *
@@ -927,8 +985,9 @@ export class TestHost {
     /** A command state's reason, refused as the player refuses it. */
     #checkReason(state) {
         const reason = state?.reason;
-        if (reason !== null && reason !== undefined)
-            this.#declared(reason, "reason");
+        return reason !== null && reason !== undefined
+            ? this.#declared(reason, "reason")
+            : null;
     }
     /**
      * Row patches (player 0.6.0): the `seq` of each property's last write, by
@@ -2341,19 +2400,36 @@ export class TestHost {
             ["mute", ["Audio", "Mute"], 503, "domain", ["M"], false],
         ];
         const host = this;
-        for (const [id, path, order, group, bindings, repeat, radio] of table) {
+        for (const [id, fixed, order, group, bindings, repeat, radio] of table) {
+            // The seek items carry the step (`setStepSeek`): the player
+            // registers them again when it changes (core_actions.rs `seek_title`).
+            const seek = id === "seek-forward"
+                ? "Forward"
+                : id === "seek-backward"
+                    ? "Back"
+                    : null;
+            const pathOf = () => seek === null
+                ? fixed
+                : [
+                    ...fixed.slice(0, -1),
+                    `${seek} ${String(Math.round(host.stepSeek * 1000) / 1000)} s`,
+                ];
+            const declaration = {
+                order,
+                group,
+                radio: radio ?? false,
+                bindings,
+                repeat,
+            };
+            Object.defineProperties(declaration, {
+                title: { get: () => pathOf().at(-1), enumerable: true },
+                path: { get: pathOf, enumerable: true },
+            });
             const command = {
-                declaration: {
-                    title: path.at(-1),
-                    path,
-                    order,
-                    group,
-                    radio: radio ?? false,
-                    bindings,
-                    repeat,
-                },
+                declaration,
                 // The player's own words in the player's language.
                 get display() {
+                    const path = pathOf();
                     const leaf = path.at(-1);
                     const step = /^(Back|Forward) (\S+) s$/.exec(leaf);
                     const title = step
@@ -3834,43 +3910,95 @@ export class TestHost {
         },
         "commands.register": (p) => {
             const id = String(p.id);
-            // The player's built-in menu ids (MENU_IDS) in the first path segment.
-            const path = (p.declaration?.path ?? []).map(String);
-            const menu = path[0]?.startsWith("@") ? path[0].slice(1) : null;
+            // The player's checks, in its order (capabilities/commands.rs
+            // `register`, then commands.rs `Registry::register`), with its codes
+            // and messages.
+            if (!Number.isInteger(p.revision) || Number(p.revision) <= 0)
+                throw new HostError("invalid", "positive revision required");
+            // The reason is checked (and shown) when it arrives.
+            const reason = this.#checkReason(p.state);
+            const declaration = p.declaration;
+            const button = declaration.button;
+            const maxOrder = BAR_BUTTON_LIMITS.maxOrder;
+            // Player 0.5.10: a bar button is { icon, order }, its order 0–999,
+            // its icon a name or an image of the plugin.
+            if (button !== undefined && button !== null) {
+                if (typeof button !== "object" ||
+                    Array.isArray(button) ||
+                    !Object.keys(button).every((key) => key === "icon" || key === "order"))
+                    throw new HostError("invalid", "button is { icon, order }");
+                const { icon, order } = button;
+                if (!Number.isInteger(order) || +order < 0 || +order > maxOrder)
+                    throw new HostError("invalid", `button order must be an integer 0–${maxOrder}`);
+                if (typeof icon !== "string" && this.imagePath(icon) === null)
+                    throw new HostError("invalid", "button icon is an icon name or an image from plugin.ui.image");
+            }
+            // Text values in the title and path are keyed by their English
+            // rendering; the built-in menu ids (MENU_IDS) and the player's old
+            // Chinese menu titles by the menus' keys.
+            const title = menuTextKey(declaration.title);
+            const declared = (declaration.path ?? []);
+            if (!Array.isArray(declared))
+                throw new HostError("invalid", "path is a list of menu texts");
+            const keys = declared.map(menuTextKey);
+            const menu = keys[0]?.startsWith("@") ? keys[0].slice(1) : null;
             if (menu !== null && !MENU_IDS.includes(menu))
-                throw new HostError("invalid", `unknown menu id @${menu}`);
-            if (menu !== null && path.length < 2)
-                throw new HostError("invalid", `menu id @${menu} needs an item after it`);
+                throw commandInvalid(`unknown menu id @${menu}; the built-in menus are ${MENU_IDS.map((known) => `@${known}`).join(", ")}`);
+            if (menu !== null && keys.length < 2)
+                throw commandInvalid(`menu id @${menu} needs an item after it`);
+            const path = menuKeys(keys);
+            checkDeclaration(id, title, path, declaration);
+            if (button !== undefined && button !== null) {
+                if (path.length === 0)
+                    throw commandInvalid("button needs a menu path: a bar button is also a menu item");
+                const { icon } = button;
+                if (typeof icon === "string" &&
+                    !BAR_BUTTON_ICONS.includes(icon))
+                    throw commandInvalid(`unknown button icon ${JSON.stringify(icon)}: a name of @vestra/icons.slint (${BAR_BUTTON_ICONS.join(", ")}) or an image from plugin.ui.image`);
+            }
+            const bindings = (declaration.bindings ?? []);
+            for (const binding of bindings)
+                try {
+                    canonical(String(binding));
+                }
+                catch (error) {
+                    throw commandInvalid(error.message);
+                }
+            if (reason !== null)
+                commandText(reason, "reason", COMMAND_LIMITS.reasonBytes);
             if (this.commands.has(id))
-                throw new HostError("command", "owner/localId already registered");
-            // The player's caps (COMMAND_LIMITS): the total counts the core commands too.
+                throw commandConflict("owner/localId already registered");
+            // The player's own commands beside the core actions (host/actions.rs
+            // `host_declarations`: Toggle Fullscreen, Quit and three outside the
+            // menu), which take part in conflicts and the total like any other.
+            const hostOnly = BUILTIN_COMMANDS.filter((row) => row.owner === "host" && !this.coreCommands.has(`host/${row.id}`));
+            // A path may not repeat another command's (the player's own
+            // included) nor be a submenu of one, or one of its submenus.
+            if (path.length > 0)
+                for (const existing of [
+                    ...hostOnly.map((row) => row.path),
+                    ...[...this.coreCommands.values()].map((command) => command.declaration.path),
+                    ...[...this.commands.values()].map((command) => menuKeys((command.declaration.path ?? []).map(menuTextKey))),
+                ]) {
+                    const shared = Math.min(existing.length, path.length);
+                    if (existing.length > 0 &&
+                        existing.slice(0, shared).every((s, i) => s === path[i]))
+                        throw commandConflict("menu path duplicates a command or collides with a leaf/group");
+                }
+            // The player's caps (COMMAND_LIMITS): the total counts all of the
+            // player's own commands too.
             if (this.commands.size >= COMMAND_LIMITS.perPlugin ||
-                this.commands.size + this.coreCommands.size >= COMMAND_LIMITS.total)
+                this.commands.size + this.coreCommands.size + hostOnly.length >=
+                    COMMAND_LIMITS.total)
                 throw new HostError("limit", "command registry limit reached");
-            const host = this;
-            const declaration = p.declaration;
-            // Player 0.5.10: a bar button needs a path, an order 0–999 and a
-            // known icon or an image of the plugin.
-            if (declaration.button !== undefined) {
-                const { icon, order } = declaration.button;
-                if (path.length === 0)
-                    throw new HostError("invalid", "button needs a menu path");
-                if (!Number.isInteger(order) ||
-                    order < 0 ||
-                    order > BAR_BUTTON_LIMITS.maxOrder)
-                    throw new HostError("invalid", `button order must be an integer 0–${BAR_BUTTON_LIMITS.maxOrder}`);
-                if (typeof icon === "string") {
-                    if (!BAR_BUTTON_ICONS.includes(icon))
-                        throw new HostError("invalid", `unknown button icon "${icon}"`);
-                }
-                else if (this.imagePath(icon) === null)
-                    throw new HostError("invalid", "button icon is an icon name or an image from plugin.ui.image");
+            // The binding table: each input once per command.
+            const seen = new Set();
+            for (const binding of bindings.map(String)) {
+                if (seen.has(binding))
+                    throw new HostError("invalid", `binding ${binding} is listed twice`);
+                seen.add(binding);
             }
-            // Like the player: the menu texts and the reason are checked (and
-            // shown) when they arrive.
-            for (const segment of [declaration.title, ...(declaration.path ?? [])])
-                this.#declared(segment, "a menu text");
-            this.#checkReason(p.state);
+            const host = this;
             let sent = p.state;
             this.commands.set(id, {
                 declaration,
@@ -3899,10 +4027,25 @@ export class TestHost {
                 throw new HostError("missing", `command ${p.id} is not registered`);
         },
         "commands.update": (p) => {
-            const command = this.command(String(p.id));
+            // The request itself, as the player reads it (capabilities/commands.rs
+            // `parsed`): `invalid`.
+            if (!Number.isInteger(p.revision) || Number(p.revision) <= 0)
+                throw new HostError("invalid", "positive revision required");
+            const reason = this.#checkReason(p.state);
+            // The registry's refusals of an update (commands.rs `Registry::update`)
+            // all come back as `command`; the test host's one plugin is owner 1.
+            const command = this.commands.get(String(p.id));
+            if (!command)
+                throw new HostError("command", `command missing: owner 1 / ${p.id}`);
             if (Number(p.revision) <= command.revision)
-                throw new HostError("command", `stale command revision ${p.revision}`);
-            this.#checkReason(p.state);
+                throw new HostError("command", `stale command revision ${p.revision}; current is ${command.revision}`);
+            if (reason !== null)
+                try {
+                    commandText(reason, "reason", COMMAND_LIMITS.reasonBytes);
+                }
+                catch (error) {
+                    throw new HostError("command", error.message);
+                }
             command.revision = Number(p.revision);
             command.state = p.state;
             if (p.when)

package/dist/plugin/types.d.ts

@@ -917,7 +917,9 @@ export interface CommandButton {
  * give it an order in the menu's range (Video: 400–499).
  *
  * {@link Commands.add} throws `invalid` synchronously for a bad path,
- * order, group or binding. The same path registered twice, or a path that
+ * order or binding; the player refuses an empty or overlong text, a control
+ * character or whitespace at either end (`COMMAND_LIMITS`) with
+ * `invalid` (through `ready`). The same path registered twice, or a path that
  * is both an item and a submenu, fails with `conflict` (through `ready`).
  *
  * @see {@link Commands.add}, [Commands, menus and key bindings](../../docs/explanation/commands.md)
@@ -1190,8 +1192,15 @@ export interface Commands {
      * lists, presets) in a child {@link Scope} and rebuild it.
      *
      * @throws `invalid` synchronously for a malformed path (including an
-     *   unknown `@` menu id), order, group or binding; `conflict` for an id this
+     *   unknown `@` menu id), order or binding; `conflict` for an id this
      *   plugin has already declared and not disposed.
+     * @throws `invalid` (`ready` rejects; during activation, activation
+     *   fails) for a text the player refuses: an id, title, path segment,
+     *   group or reason that is empty, longer than its `COMMAND_LIMITS`
+     *   bytes (a text value counted by its English rendering), has a control
+     *   character or whitespace at either end, or an id with other characters
+     *   than ASCII letters, digits, `.`, `_` and `-`. `TestHost`
+     *   refuses the same (SDK 1.5.48).
      *
      * @example Pause playback from a menu item
      * Playback ▸ Pause (and Ctrl+P) pauses and resumes, shows a check mark

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.47: full reference
+# @vestra-player/sdk 1.5.48: 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.
 
@@ -2357,12 +2357,19 @@ The player bounds what one request may cost it. The limits are guards against ru
 
 #### Commands
 
-A command added past a limit fails with code `limit` (its `ready` rejects; during activation, activation fails). Commands already registered are unaffected, and disposing one frees its slot at once.
+A command added past `perPlugin` or `total` fails with code `limit` (its `ready` rejects; during activation, activation fails). Commands already registered are unaffected, and disposing one frees its slot at once. A declaration past the other limits fails with `invalid` the same way (SDK 1.5.48: `TestHost` refuses it too).
 
 | Limit | Value | Meaning |
 | --- | --- | --- |
 | `COMMAND_LIMITS.perPlugin` | 160 | Commands one plugin instance may have at the same time. |
 | `COMMAND_LIMITS.total` | 1024 | Commands of every plugin plus the player's own, together. |
+| `COMMAND_LIMITS.depth` | 8 | Segments of a menu path, the leaf included. |
+| `COMMAND_LIMITS.idBytes` | 128 | UTF-8 bytes of a command's local id: ASCII letters, digits, `.`, `_` and `-`. |
+| `COMMAND_LIMITS.titleBytes` | 128 | UTF-8 bytes of a title, a text value counted by its English rendering. Like every command text: not empty, no control characters, no whitespace at either end. |
+| `COMMAND_LIMITS.segmentBytes` | 80 | UTF-8 bytes of a menu path segment, a text value counted by its English rendering. |
+| `COMMAND_LIMITS.groupBytes` | 80 | UTF-8 bytes of a group. |
+| `COMMAND_LIMITS.reasonBytes` | 512 | UTF-8 bytes of a state's reason, as shown in the player's language. |
+| `COMMAND_LIMITS.order` | 1000000 | The largest `order` either way: an order is within ±1,000,000. |
 
 #### Bottom-bar buttons
 
@@ -5820,6 +5827,7 @@ Every SDK release's CHANGELOG entry opens with who must change and what happens
 
 | Release | Who must change | Guide |
 | --- | --- | --- |
+| [1.5.48](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1548) | **Nobody, but plugin tests may now fail.** No changes to the TypeScript API beyond new fields of `COMMAND_LIMITS`, `apiVersion` stays `vestra/1`, no new capability, no player version needed. | — |
 | [1.5.47](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1547) | **Nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability, no player version needed. | — |
 | [1.5.46](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1546) | **Nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability. | — |
 | [1.5.45](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1545) | **Nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability, no player version needed. | — |
@@ -6701,7 +6709,9 @@ an item without `order` moves the whole menu to the top; to avoid that,
 give it an order in the menu's range (Video: 400–499).
 
 Commands.add throws `invalid` synchronously for a bad path,
-order, group or binding. The same path registered twice, or a path that
+order or binding; the player refuses an empty or overlong text, a control
+character or whitespace at either end (`COMMAND_LIMITS`) with
+`invalid` (through `ready`). The same path registered twice, or a path that
 is both an item and a submenu, fails with `conflict` (through `ready`).
 
 ```ts
@@ -6911,7 +6921,8 @@ interface Commands {
    *
    * Titles and paths cannot change in place: put changing items (track
    * lists, presets) in a child Scope and rebuild it.
-   * @throws invalid synchronously for a malformed path (including an unknown `@` menu id), order, group or binding; `conflict` for an id this plugin has already declared and not disposed.
+   * @throws invalid synchronously for a malformed path (including an unknown `@` menu id), order or binding; `conflict` for an id this plugin has already declared and not disposed.
+   * @throws invalid (`ready` rejects; during activation, activation fails) for a text the player refuses: an id, title, path segment, group or reason that is empty, longer than its `COMMAND_LIMITS` bytes (a text value counted by its English rendering), has a control character or whitespace at either end, or an id with other characters than ASCII letters, digits, `.`, `_` and `-`. `TestHost` refuses the same (SDK 1.5.48).
    * @capability commands
    * @example Pause playback from a menu item
    * Playback ▸ Pause (and Ctrl+P) pauses and resumes, shows a check mark
@@ -17314,6 +17325,9 @@ fails; later the failure goes to `Scope.onError`), commands
 already registered are unaffected, and disposing a command frees its slot
 at once. TestHost enforces the same caps.
 
+The other fields are the player's rules for one declaration (since
+1.5.48): a command past them is refused with `invalid`, the same way.
+
 For menus built from media content (tracks, chapters, presets), set your
 own sensible display cap well below `perPlugin`.
 
@@ -17323,6 +17337,22 @@ const COMMAND_LIMITS: {
   readonly perPlugin: 160;
   /** Commands of every plugin plus the player's own, together (1024). */
   readonly total: 1024;
+  /** Segments of a menu path, the leaf included. */
+  readonly depth: 8;
+  /** UTF-8 bytes of a command's local id: ASCII letters, digits, `.`, `_` and `-`. */
+  readonly idBytes: 128;
+  /**
+   * UTF-8 bytes of a title, a text value counted by its English rendering. Like every command text: not empty, no control characters, no whitespace at either end.
+   */
+  readonly titleBytes: 128;
+  /** UTF-8 bytes of a menu path segment, a text value counted by its English rendering. */
+  readonly segmentBytes: 80;
+  /** UTF-8 bytes of a group. */
+  readonly groupBytes: 80;
+  /** UTF-8 bytes of a state's reason, as shown in the player's language. */
+  readonly reasonBytes: 512;
+  /** The largest `order` either way: an order is within ±1,000,000. */
+  readonly order: 1000000;
 };
 ```
 

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.47: 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 (the player's built-in plugins share one). Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n>: a line of llms-full.txt (next to this file), which has every page, declaration and example.
+> @vestra-player/sdk 1.5.48: 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 (the player's built-in plugins share one). Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n>: a line of llms-full.txt (next to this file), which has every page, declaration and example.
 
 **Rules**
 
@@ -80,7 +80,7 @@ export default async function activate(plugin: Plugin) {
 - `video.upscaling`: VideoUpscaling.state/set/onChange
 - No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme, packages.list and rendering.state. Details: L2293–2353.
 
-**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`, `host` an in-memory player (TestHost): act (`host.command(id).run()`, `host.press(key)`), `await host.settle()`, assert on `host.osd`, `host.window(id).props`… Guide: L1861–2021; TestHost: L15491.
+**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`, `host` an in-memory player (TestHost): act (`host.command(id).run()`, `host.press(key)`), `await host.settle()`, assert on `host.osd`, `host.window(id).props`… Guide: L1861–2021; TestHost: L15502.
 
 **Command line**
 
@@ -108,40 +108,40 @@ export default async function activate(plugin: Plugin) {
 - `limit`: A player-wide limit was reached, a property value is over the limits of PropValue
 - `reserved`: The id is `vestra` or starts with `vestra.`
 - `versionMismatch`: The package needs a newer player
-- Others: PluginError, llms-full.txt L5958.
+- Others: PluginError, llms-full.txt L5966.
 
 ## Reference
 
 - [llms-full.txt](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt), also node_modules/@vestra-player/sdk/llms-full.txt; pages: [site](https://vestrasys.github.io/vestra-player-sdk/).
 - Tutorials: Getting started L9–134; Add a window L135–213; Add settings and translations L214–367; Test, check, pack and publish L368–424; Write your own blur kernel L425–685
 - How-to: Control playback L686–854; Store a plugin's data L855–961; Load subtitles from a plugin L962–1074; Keep a slider responsive while dragging L1075–1262; Remember a window's state between runs L1263–1414; Offer a GPU rendering switch L1415–1540; Keep a command's state without keeping the plugin running L1541–1697; Translate a plugin L1698–1860; Test a plugin L1861–2021; Publish a plugin L2022–2123; Troubleshooting L2124–2217
-- Reference: Manifest L2218–2292; Capabilities L2293–2353; Limits L2354–2499; Commands, menus and bindings L2500–3026; Platforms L3027–3057; Theme L3058–3407; Command line L3408–3465; Error codes L3466–3513; Translations L3514–3606; Test host L3607–3793
-- Explanation: How a plugin runs L3794–3996; Commands, menus and key bindings L3997–4151; Playback state, controls and sources L4152–4311; Video and audio processing L4312–4432; Windows, panels, settings pages, dialogs and the OSD L4433–4697; GPU and software rendering L4698–4714; The player's Rust core L4715–5056; How the player runs and talks to plugins L5057–5396
-- Guidelines: Plugin rules L5397–5408; Interface guidelines L5409–5525; Menu guidelines L5526–5584
-- Upgrading: Migrate a plugin to English source text L5585–5734; Migrating off package rollback (1.5.16, removed in 1.5.17) L5735–5812; Who must change, release by release L5813–5880
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5881–15164
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L15165–18029
+- Reference: Manifest L2218–2292; Capabilities L2293–2353; Limits L2354–2506; Commands, menus and bindings L2507–3033; Platforms L3034–3064; Theme L3065–3414; Command line L3415–3472; Error codes L3473–3520; Translations L3521–3613; Test host L3614–3800
+- Explanation: How a plugin runs L3801–4003; Commands, menus and key bindings L4004–4158; Playback state, controls and sources L4159–4318; Video and audio processing L4319–4439; Windows, panels, settings pages, dialogs and the OSD L4440–4704; GPU and software rendering L4705–4721; The player's Rust core L4722–5063; How the player runs and talks to plugins L5064–5403
+- Guidelines: Plugin rules L5404–5415; Interface guidelines L5416–5532; Menu guidelines L5533–5591
+- Upgrading: Migrate a plugin to English source text L5592–5741; Migrating off package rollback (1.5.16, removed in 1.5.17) L5742–5819; Who must change, release by release L5820–5888
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5889–15175
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L15176–18059
 
 ## API
 
 Where each `plugin.<module>` is declared:
 
-- Plugin L6297, Scope L6033, PluginError L5958, Disposable L5896
-- Commands L6890; When L6484; Windows L7836; Panels L9282; Dialogs L9952; Player L10693; video: VideoFilter L11573, VideoView L11673, RenderOptions L11760, VideoShaders L11838, VideoUpscaling L12196; audio: AudioFilter L11618; Subtitles L12432; media: MediaCapture L12836; Resolvers L13066; Packages L13468; Osd L11438; Host L11280; Clipboard L13797; Power L13884; Tools L13943; Storage L14095; System L14294; Secrets L14374; window: MainWindow L9599; App L9779; Rendering L14637; Bindings L13696; Ui L7182; Timeline L9511; Drops L8529; Appearance L8610; I18n L8843; Settings L9126.
+- Plugin L6305, Scope L6041, PluginError L5966, Disposable L5904
+- Commands L6900; When L6492; Windows L7847; Panels L9293; Dialogs L9963; Player L10704; video: VideoFilter L11584, VideoView L11684, RenderOptions L11771, VideoShaders L11849, VideoUpscaling L12207; audio: AudioFilter L11629; Subtitles L12443; media: MediaCapture L12847; Resolvers L13077; Packages L13479; Osd L11449; Host L11291; Clipboard L13808; Power L13895; Tools L13954; Storage L14106; System L14305; Secrets L14385; window: MainWindow L9610; App L9790; Rendering L14648; Bindings L13707; Ui L7193; Timeline L9522; Drops L8540; Appearance L8621; I18n L8854; Settings L9137.
 
 ## Examples
 
 Tested plugins in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples):
 
-- hello: The README Quick start: one menu command and an on-screen message. L18464–18559
-- blur: A tool window with one slider that blurs the playing video. L18560–18827
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18828–19166
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L19167–19359
-- panel-menu: A sidebar panel with its own right-click menu. L19360–19574
-- menus: Radio menu items, separator groups and a menu item whose title changes. L19575–19740
-- theme-widgets: A tool window drawn with the player's theme and widgets. L19741–19910
-- markdown: A window that shows a Markdown document. L19911–20113
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L20114–20287
+- hello: The README Quick start: one menu command and an on-screen message. L18494–18589
+- blur: A tool window with one slider that blurs the playing video. L18590–18857
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18858–19196
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L19197–19389
+- panel-menu: A sidebar panel with its own right-click menu. L19390–19604
+- menus: Radio menu items, separator groups and a menu item whose title changes. L19605–19770
+- theme-widgets: A tool window drawn with the player's theme and widgets. L19771–19940
+- markdown: A window that shows a Markdown document. L19941–20143
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L20144–20317
 
 ## Optional
 

package/package.json

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