@vestra-player/sdk 1.5.47 → 1.5.49

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.5.49
+
+**Who must change: nobody.** No changes to the plugin API (`@vestra-player/sdk/runtime` gains the additive `RuntimeOptions` and an optional sixth `createPlugin` argument), `apiVersion` stays `vestra/1`, no new capability, no player version needed, and the player's runner needs no change. **Behaviour change, approved by the maintainer (2026-11-01):** in the player, a command declaration it refuses during activation no longer fails the whole plugin. What `commands.add` checks itself (an unknown `@` menu id, more than 8 path segments, an `order` out of range, a malformed or repeated binding, a bad `button`, a reason text of the wrong shape) still throws from `add`. A plugin whose `activate` relied on that failure (none is known) now runs without the refused command.
+
+- **A refused command declaration is skipped, not fatal.** When the player answers a `commands.add` made during activation with `invalid`, `conflict` or `limit` (a text over its limit, a path another command has, too many commands), the SDK logs it with the command id and the player's message (`[<plugin>] command <id> skipped, the player refused it (conflict): …`), skips that command and lets the rest of the plugin activate: its other commands, panels, settings pages and resolvers register and the player gets `runtime.ready`. Before, the first refusal made activation fail (`runtime.failed`) and the plugin's menus and panels were withdrawn. The command's `ready` still rejects, and the error reaches the scope's `onError` once activation completes, so a listener added anywhere in `activate` hears it. This is how a slot, sequence or resolver another plugin holds was already treated, and how VS Code treats a bad contribution (logged, the extension activates). Other failures during activation (`capability`, a timeout, an error of the player) still fail it, and a refusal after activation goes to `onError` as before.
+- **A refused command sends no updates.** After a definite refusal of its registration, later state changes (`set`, a binding) send nothing, instead of updates the player answers with `command missing`; dispose it to declare the id again.
+- **`TestHost` refuses a binding listed twice as player 0.6.1 does.** The player now checks a command's bindings with its binding table (`Table::canonical`) inside the registration: each binding parsed and each input once, compared as parsed inputs, before the reason, the id and path conflicts and the limits, with the `invalid command: ` prefix (`invalid command: binding F3 is listed twice`). `TestHost` answered it without the prefix and only after the conflict and limit checks; it now gives the same answer in the same order.
+- **`TestHost` stays strict.** `startPlugin` still rejects when a command declaration is refused during activation, so a plugin's tests show the bad declaration. Fix the declaration, not the test. (`createPlugin` in `@vestra-player/sdk/runtime` takes `{ strictDeclarations }`; `startPlugin` sets it, the player's runner does not.)
+- _Docs_: [Example: Panel menu](docs/examples/panel-menu.md) draws its list in a `ListView` instead of a `for` in a `VerticalLayout`; the [interface guidelines](docs/guidelines/interface.md#panels) gain **Long lists use `ListView`**. `Command.ready`, `Commands`, `Plugin`, `startPlugin`, [The plugin model](docs/explanation/plugins.md), [Host and Node](docs/explanation/host-and-node.md) and [Limits](docs/reference/limits.md) describe the new activation rule.
+
+## 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/player-runtime.d.ts

@@ -8,7 +8,7 @@
  * @packageDocumentation
  */
 export { createPlugin } from "./plugin/index.ts";
-export type { PluginInstance, PluginManifest } from "./plugin/index.ts";
+export type { PluginInstance, PluginManifest, RuntimeOptions, } from "./plugin/index.ts";
 export { HostError } from "./wire.ts";
 export type { Json, Transport } from "./wire.ts";
 export { API_VERSION, CAPABILITIES, CAPABILITY_INFO, MESSAGE_LIMIT, } from "./capabilities.ts";

package/dist/plugin/commands.js

@@ -1,5 +1,5 @@
 /** Menu commands: declaration, state sync (revisions hidden) and dispatch. */
-import { failure, Latest, quiet } from "./runtime.js";
+import { failure, Latest, quiet, uncertain } from "./runtime.js";
 import { checkBindings } from "./bindings.js";
 import { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, MENU_IDS } from "../commands.js";
 import { ImageHandle } from "./ui.js";
@@ -100,6 +100,10 @@ class CommandHandle {
     #last = "";
     #disposed = false;
     #registered = false;
+    /** Its entry in `runtime.commands` (a later handle may own the id). */
+    #run = () => { };
+    /** The player refused the declaration: no state updates follow. */
+    #refused = false;
     #pump;
     #label;
     /** Where the plugin added it, for the player's log. */
@@ -124,10 +128,20 @@ class CommandHandle {
         // registration itself is revision 1, so every later state follows it.
         const previous = removing(runtime).get(this.id);
         this.#pump = new Latest(async ({ state, when }) => {
+            if (this.#refused)
+                return;
             const revision = ++this.#revision;
             if (revision === 1) {
                 await previous;
-                await runtime.host.commands.register(this.id, 1, declaration, state, when);
+                try {
+                    await runtime.host.commands.register(this.id, 1, declaration, state, when);
+                }
+                catch (error) {
+                    // A definite refusal: the player has no such command to update.
+                    if (!uncertain(error))
+                        this.#refused = true;
+                    throw error;
+                }
                 this.#registered = true;
             }
             else
@@ -136,12 +150,13 @@ class CommandHandle {
         const initial = this.#state();
         this.#last = JSON.stringify(initial);
         this.ready = quiet(runtime
-            .starting(this.#pump.push(initial), (error) => scope.report(error))
+            .declaring(this.#pump.push(initial), `command ${this.id}`, (error) => scope.report(error))
             .then(() => { }));
-        runtime.commands.set(this.id, () => {
+        this.#run = () => {
             if (!this.#disposed)
                 scope.run(options.run);
-        });
+        };
+        runtime.commands.set(this.id, this.#run);
         this.#binding = runtime.bind(() => this.#sync());
         scope.add(this);
     }
@@ -177,7 +192,7 @@ class CommandHandle {
         return Object.keys(when).length ? { state, when } : { state };
     }
     #sync() {
-        if (this.#disposed)
+        if (this.#disposed || this.#refused)
             return;
         const state = this.#state();
         const encoded = JSON.stringify(state);
@@ -196,7 +211,8 @@ class CommandHandle {
         this.#disposed = true;
         this.#scope.forget(this);
         const runtime = this.#scope.runtime;
-        runtime.commands.delete(this.id);
+        if (runtime.commands.get(this.id) === this.#run)
+            runtime.commands.delete(this.id);
         this.#pump.stop();
         // Removed from the menu once registered. Recorded before any await, so an
         // immediate re-add of the same id registers after this removal.

package/dist/plugin/index.d.ts

@@ -6,16 +6,23 @@
  * @internal
  */
 import type { Transport } from "../wire.ts";
-import type { PluginManifest } from "./runtime.ts";
+import type { PluginManifest, RuntimeOptions } from "./runtime.ts";
 import type { Plugin } from "./types.ts";
 export type * from "./types.ts";
-export type { PluginManifest };
+export type { PluginManifest, RuntimeOptions };
 export interface PluginInstance {
     plugin: Plugin;
-    /** Wait for registrations started during activation; rejects if one failed. */
+    /**
+     * Wait for registrations started during activation; rejects if one failed.
+     * A command declaration the player refused is not a failure (it is
+     * logged, skipped and reported to `onError`) unless
+     * `RuntimeOptions.strictDeclarations` is set.
+     */
     activated(): Promise<void>;
     dispose(): Promise<void>;
 }
 export declare function createPlugin(transport: Transport, manifest: PluginManifest, directory: string, dataDirectory?: string, 
 /** `plugin.app` (the runner passes the player's `VESTRA_APP_INFO`). */
-app?: unknown): Promise<PluginInstance>;
+app?: unknown, 
+/** `TestHost` sets `strictDeclarations`; the player's runner does not. */
+options?: RuntimeOptions): Promise<PluginInstance>;

package/dist/plugin/index.js

@@ -5,8 +5,10 @@ import { windowOf } from "./window.js";
 import { timelineOf } from "./timeline.js";
 export async function createPlugin(transport, manifest, directory, dataDirectory, 
 /** `plugin.app` (the runner passes the player's `VESTRA_APP_INFO`). */
-app) {
-    const runtime = new Runtime(transport, manifest, directory, dataDirectory, app);
+app, 
+/** `TestHost` sets `strictDeclarations`; the player's runner does not. */
+options) {
+    const runtime = new Runtime(transport, manifest, directory, dataDirectory, app, options);
     // Player, window and timeline state are synchronous for plugins: read them first.
     await Promise.all([
         playerOf(runtime).init(),

package/dist/plugin/runtime.d.ts

@@ -37,6 +37,15 @@ export type Change = ReadonlyMap<string, ReadonlySet<string>>;
  * without `update()`) still shows within about this long.
  */
 export declare const SAFETY_PASS_MS = 1000;
+/** How the plugin is run: the player's runner, or `TestHost`. */
+export interface RuntimeOptions {
+    /**
+     * A declaration the player refuses during activation fails activation
+     * (`startPlugin`, so a plugin's tests show it) instead of being logged,
+     * reported to `onError` and skipped (the player's runner).
+     */
+    strictDeclarations?: boolean;
+}
 export declare const same: (a: Json | undefined, b: Json | undefined) => boolean;
 /** One value in flight, only the newest waiting. Each push learns its fate. */
 export declare class Latest<T> {
@@ -74,7 +83,7 @@ export declare class Runtime {
      * property writes). Not part of the plugin API; empty for older players.
      */
     readonly features: ReadonlySet<string>;
-    constructor(transport: Transport, manifest: PluginManifest, directory: string, dataDirectory?: string, app?: unknown);
+    constructor(transport: Transport, manifest: PluginManifest, directory: string, dataDirectory?: string, app?: unknown, options?: RuntimeOptions);
     can(capability: string): boolean;
     /** Lazily created singletons shared by every scope of this plugin. */
     service<T>(name: string, create: () => T): T;
@@ -83,6 +92,16 @@ export declare class Runtime {
      * plugin reports ready; later ones report failures to their scope.
      */
     starting<T>(work: Promise<T>, report: (error: unknown) => void): Promise<T>;
+    /**
+     * A declaration the player checks on its own (`what`: "command x"),
+     * started like `starting`. In the player's runner a refusal of it during
+     * activation (`invalid`, `conflict`, `limit`) does not fail the plugin:
+     * it is logged, skipped and reported to the scope once activation
+     * completes, so an `onError` added anywhere in `activate` hears it (SDK
+     * 1.5.49; VS Code logs a bad contribution and activates the extension).
+     * Under `strictDeclarations` (TestHost) it fails activation as before.
+     */
+    declaring<T>(work: Promise<T>, what: string, report: (error: unknown) => void): Promise<T>;
     activated(): Promise<void>;
     bind(evaluate: () => void): Disposable;
     /**

package/dist/plugin/runtime.js

@@ -86,6 +86,16 @@ function merge(into, from) {
  * without `update()`) still shows within about this long.
  */
 export const SAFETY_PASS_MS = 1000;
+/**
+ * The player's answers to a declaration that refuse that one declaration
+ * (a command's path, texts or count): during activation they skip it
+ * instead of failing the plugin (`Runtime.declaring`, SDK 1.5.49).
+ */
+const DECLARATION_REFUSALS = new Set([
+    "invalid",
+    "conflict",
+    "limit",
+]);
 export const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 /** One value in flight, only the newest waiting. Each push learns its fate. */
 export class Latest {
@@ -149,6 +159,10 @@ export class Runtime {
     /** Registrations that activation must wait for before reporting ready. */
     startup = new Set();
     #activating = true;
+    /** `RuntimeOptions.strictDeclarations`. */
+    #strict;
+    /** Declarations skipped during activation: reported once it completes. */
+    #refusals = [];
     #transport;
     /** Each binding with the events whose state it read last time (held). */
     #bindings = new Map();
@@ -187,8 +201,9 @@ export class Runtime {
      * property writes). Not part of the plugin API; empty for older players.
      */
     features;
-    constructor(transport, manifest, directory, dataDirectory, app) {
+    constructor(transport, manifest, directory, dataDirectory, app, options = {}) {
         this.#transport = transport;
+        this.#strict = options.strictDeclarations ?? false;
         this.dataDirectory = dataDirectory;
         this.local = transport.local;
         this.host = createWire(transport);
@@ -233,6 +248,32 @@ export class Runtime {
         work.catch(() => { });
         return work;
     }
+    /**
+     * A declaration the player checks on its own (`what`: "command x"),
+     * started like `starting`. In the player's runner a refusal of it during
+     * activation (`invalid`, `conflict`, `limit`) does not fail the plugin:
+     * it is logged, skipped and reported to the scope once activation
+     * completes, so an `onError` added anywhere in `activate` hears it (SDK
+     * 1.5.49; VS Code logs a bad contribution and activates the extension).
+     * Under `strictDeclarations` (TestHost) it fails activation as before.
+     */
+    declaring(work, what, report) {
+        if (!this.#activating || this.#strict)
+            return this.starting(work, report);
+        const settled = work.then(() => { }, (error) => {
+            if (!(error instanceof HostError) ||
+                !DECLARATION_REFUSALS.has(error.code))
+                throw error;
+            console.error(`[${this.manifest.id}] ${what} skipped, the player refused it (${error.code}): ${error.message}`);
+            this.#refusals.push(() => report(error));
+        });
+        // Observed now: `activated()` may come after `activate` awaits, and
+        // its `allSettled` still sees the rejection.
+        settled.catch(() => { });
+        this.startup.add(settled);
+        work.catch(() => { });
+        return work;
+    }
     async activated() {
         while (this.startup.size) {
             const pending = [...this.startup];
@@ -242,6 +283,8 @@ export class Runtime {
                     throw result.reason;
         }
         this.#activating = false;
+        for (const report of this.#refusals.splice(0))
+            report();
     }
     bind(evaluate) {
         const held = new Map();

package/dist/plugin/testing.d.ts

@@ -2728,8 +2728,11 @@ export declare class TestHost implements Transport {
  *
  * Rejects when `manifest.json` cannot be read or parsed, when `activate`
  * throws, or when a registration made during activation fails (for example
- * `limit`, `conflict`, `invalid`), which is when the player would fail the
- * activation.
+ * `limit`, `conflict`, `invalid`). Stricter than the player's runner for
+ * commands (SDK 1.5.49): there the SDK logs a command declaration the
+ * player refuses during activation, skips it and activates the rest of the
+ * plugin (`onError` hears it); `startPlugin` fails, so a test shows the
+ * bad declaration.
  *
  * @param activate - The plugin's default-exported `activate` function.
  * @param options - Where the plugin lives and how to start it.

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,97 @@ 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`);
+            }
+            // The binding table's `Table::canonical` (player 0.6.1): each binding
+            // parsed, and each input once, compared parsed, before the reason,
+            // conflicts and limits.
+            const bindings = (declaration.bindings ?? []);
+            const seen = new Set();
+            for (const binding of bindings.map(String)) {
+                let input;
+                try {
+                    input = canonical(binding);
+                }
+                catch (error) {
+                    throw commandInvalid(error.message);
+                }
+                if (seen.has(input))
+                    throw commandInvalid(`binding ${binding} is listed twice`);
+                seen.add(input);
+            }
+            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");
-            }
-            // 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);
             let sent = p.state;
             this.commands.set(id, {
                 declaration,
@@ -3899,10 +4029,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)
@@ -5283,8 +5428,11 @@ function tellResidency(host) {
  *
  * Rejects when `manifest.json` cannot be read or parsed, when `activate`
  * throws, or when a registration made during activation fails (for example
- * `limit`, `conflict`, `invalid`), which is when the player would fail the
- * activation.
+ * `limit`, `conflict`, `invalid`). Stricter than the player's runner for
+ * commands (SDK 1.5.49): there the SDK logs a command declaration the
+ * player refuses during activation, skips it and activates the rest of the
+ * plugin (`onError` hears it); `startPlugin` fails, so a test shows the
+ * bad declaration.
  *
  * @param activate - The plugin's default-exported `activate` function.
  * @param options - Where the plugin lives and how to start it.
@@ -5369,7 +5517,10 @@ export async function startPlugin(activate, options = {}) {
     const instance = await createPlugin(host, manifest, directory, data, 
     // Like the player: protocol additions it takes (`app.features` set on
     // the host replaces them, e.g. `[]` for an older player's behaviour).
-    { features: [PATCH_FEATURE], ...host.app });
+    { features: [PATCH_FEATURE], ...host.app }, 
+    // Unlike the player's runner, which logs a refused command declaration
+    // and activates the rest: a plugin's tests show the refusal.
+    { strictDeclarations: true });
     await activate(instance.plugin);
     // Like the player: a position or resolver another plugin holds is not an
     // activation failure.

package/dist/plugin/types.d.ts

@@ -487,7 +487,11 @@ export interface Scope extends Disposable {
  * Registrations started during activation (commands, panels, resolvers,
  * subscriptions) do not need to be awaited: the plugin is reported ready
  * once they all succeed, and activation fails if `activate` throws or any
- * of them fails. The entry module must **default-export** `activate`.
+ * of them fails. A command declaration the player refuses is the exception
+ * (SDK 1.5.49): the SDK logs and skips it, its `ready` rejects and
+ * {@link Scope.onError} hears it, the rest of the plugin activates
+ * (`startPlugin` still fails on it). The entry module must
+ * **default-export** `activate`.
  *
  * Stopping: the player first revokes everything the plugin owns on its side
  * (menus, windows, panels, filters, subtitle layers, snapshots, jobs,
@@ -917,7 +921,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)
@@ -1136,8 +1142,21 @@ export interface Command extends Disposable {
      * Resolves when the host has registered the command. Rejects with
      * `conflict` (path already taken), `invalid` or `limit` (more than 160
      * commands in this plugin, or 1024 in the whole player). You rarely need
-     * to await it: during activation a failure fails activation, later it
-     * goes to {@link Scope.onError}.
+     * to await it: the refusal goes to {@link Scope.onError}. During
+     * activation the SDK, in the plugin's process, logs the refusal with the
+     * command id and the player's message, skips the command and lets the
+     * rest of the plugin activate (SDK 1.5.49; before, the refusal failed
+     * activation); the error reaches `onError` once activation completes,
+     * so a listener added anywhere in `activate` hears it. `startPlugin`
+     * stays strict: there a refusal during activation fails it, so tests
+     * show the bad declaration. Any other failure during activation
+     * (`capability`, no answer) fails activation.
+     *
+     * Only the player's answer is skipped. What {@link Commands.add} checks
+     * itself still throws from `add` (an unknown `@` menu id, more than 8
+     * path segments, an `order` out of range, a malformed binding or one
+     * listed twice, a bad `button`, a reason text of the wrong shape, an id
+     * already declared), and fails activation unless the plugin catches it.
      *
      * @throws `conflict` (rejects) Another command already has this menu path,
      *   or the path would be both a menu item and a submenu.
@@ -1159,8 +1178,9 @@ export interface Command extends Disposable {
  * when the user picks the item, presses a key or clicks the button.
  * Commands of all plugins merge into the player's menus by their English
  * path keys. Registration is asynchronous: `add` returns at once, and
- * {@link Command.ready} reports the player's answer (during activation a
- * refusal fails activation).
+ * {@link Command.ready} reports the player's answer (during activation
+ * the SDK logs a refusal and skips that command, SDK 1.5.49;
+ * `startPlugin` fails on it). What `add` checks itself throws from `add`.
  *
  * @capability commands
  *
@@ -1190,8 +1210,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.49: 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 and `onError` hears it; during activation the SDK logs and skips that command and the rest of the plugin activates, SDK 1.5.49, while `startPlugin` 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
 
@@ -3834,6 +3841,10 @@ When the player starts the plugin:
 
 You do not need to `await` those registrations. `commands.add`, `panels.mount` and `resolvers.add` return their handle at once and register in the background; their `ready` promise is there for the rare case that you want to wait. **Activation fails** when `activate` throws or rejects, or when one of those registrations fails. A registration made later, after activation, cannot fail activation any more: its failure goes to `onError`.
 
+A command declaration the player refuses (`invalid`, `conflict` or `limit`: a bad text, a path another command has, too many commands) does not fail activation either (SDK 1.5.49). The SDK, in the plugin's process, logs it with the command id and the player's message, skips that command and lets the rest of the plugin activate, like VS Code with a bad contribution; the command's `ready` rejects and `onError` hears the refusal once activation completes. `startPlugin` stays strict: there the refusal fails the start, so your tests show the bad declaration.
+
+This covers only the player's answer. What `commands.add` checks itself still throws from `add`: an unknown `@` menu id, more than 8 path segments, an `order` out of range, a malformed binding or one listed twice, a bad `button`, a reason text of the wrong shape, an id already declared. Uncaught, such a throw fails activation like any other exception in `activate`.
+
 Some refusals are deliberately not failures, because they depend on which other plugins are installed: a bottom bar or backdrop that another plugin's panel already holds, the next/previous sequence that another plugin provides, a file type or web host that another plugin already resolves. The plugin keeps running without that part, the player tells the user, and the plugin manager shows it as a warning (PluginInfo.warnings). The player's built-in plugins register first, so they win these contests at start-up.
 
 #### Handles and scopes
@@ -4572,6 +4583,7 @@ A tool window (Window), a panel (Panel) and a settings page (SettingsPage) all s
 - **A panel or settings page file exports one component and one global.** The player composes your component into a window it owns (the main window, the floating sidebar window, the Options window), so the component instance is not a stable address: a new instance is made whenever the main window is rebuilt or the sidebar moves to or from its floating window. The **global** is the bridge: properties and callbacks are declared on it, the component reads and calls them (`ListBridge.rows`, `ListBridge.select(index)`), and the plugin talks to the global. The SDK finds the two names from the file's `export component` and `export global` lines.
 
 ```slint
+import { ListView } from "std-widgets.slint";
 import { Theme } from "@vestra/theme.slint";
 
 export global ListBridge {
@@ -4584,7 +4596,9 @@ export global ListBridge {
 export component ListPanel inherits Rectangle {
     background: Theme.bg-list;
     min-width: 200px;
-    VerticalLayout {
+    // A ListView builds only the rows in view and scrolls the rest, so the
+    // list costs the same with three rows or thirty thousand.
+    ListView {
         for row[index] in ListBridge.rows: Rectangle {
             height: 20px;
             background: index == ListBridge.selected ? Theme.selected-bg : transparent;
@@ -4607,9 +4621,6 @@ export component ListPanel inherits Rectangle {
                 }
             }
         }
-        // Takes the space below the rows. Without it the layout's maximum
-        // height (three 20px rows) would cap the player's main window.
-        Rectangle { vertical-stretch: 1; }
     }
 }
 ```
@@ -5176,7 +5187,7 @@ self.activations.begin(owner, self.now_ms() + 15_000)?;
 
 Source: src/host/src/packages/package_manager.rs
 
-`boot.ts` sends `runtime.ready` only after `activate` returned and every registration started during activation succeeded (a slot, sequence or resolver another plugin holds does not count as a failure). Otherwise it sends `runtime.failed` with a `code`. A failure or a missed deadline stops the plugin, and the plugin manager lists it as failed with the message. At start-up the installed plugins are started from a queue, about 25 ms of process spawning per UI tick, so the window stays responsive while they come up.
+`boot.ts` sends `runtime.ready` only after `activate` returned and every registration started during activation succeeded (a slot, sequence or resolver another plugin holds does not count as a failure, and the SDK skips a command declaration the player refuses with `invalid`, `conflict` or `limit`: it logs it and reports it to `onError`, SDK 1.5.49). Otherwise it sends `runtime.failed` with a `code`. A failure or a missed deadline stops the plugin, and the plugin manager lists it as failed with the message. At start-up the installed plugins are started from a queue, about 25 ms of process spawning per UI tick, so the window stays responsive while they come up.
 
 #### The wire protocol
 
@@ -5484,6 +5495,7 @@ Use the layout of Theme: small adjustment windows: the same width, row height, l
 - **No status or path lines in a panel.** Messages go to the OSD; a full path is a tooltip on its row.
 - **Show state with colour, not words.** As in the player's playlist: what is playing in `Theme.playing` (with a thin bar at the left, Theme: layouts), what was played in `Theme.text-played`, the selection on `Theme.selected-bg`. A failed item gets the `failed` icon at the end of its row and an OSD message.
 - **Lists are plain**: single-line rows, background `Theme.bg-list`, no cards, no stripes, no rounded rows; scroll bars come from `std-widgets.slint` so they follow the palette.
+- **Long lists use `ListView`.** A list whose length the user decides (a playlist, search results, files, messages) goes in a `ListView` from `std-widgets.slint`, with the `for` inside it: it creates only the rows in view, so a list of thousands of rows scrolls as smoothly as one of ten. A `for` in a layout builds every row up front. Keep a bare `for` for a short list of a fixed size, such as a row of buttons. Example: Panel menu is a panel list drawn this way.
 - **Commands of a panel go into its right-click menu**, made of the plugin's commands (panel.showMenu); see Menus.
 - **The bottom bar is icons only**: no text buttons, no source path, no status text (the source name is in the window title, status is an OSD message).
 
@@ -5820,6 +5832,8 @@ Every SDK release's CHANGELOG entry opens with who must change and what happens
 
 | Release | Who must change | Guide |
 | --- | --- | --- |
+| [1.5.49](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1549) | **Nobody.** No changes to the plugin API (`@vestra-player/sdk/runtime` gains the additive `RuntimeOptions` and an optional sixth `createPlugin` argument), `apiVersion` stays `vestra/1`, no new capability, no player version needed, and the player's runner needs no change. | — |
+| [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. | — |
@@ -6304,7 +6318,11 @@ initial player, window and timeline state, then calls `activate(plugin)`.
 Registrations started during activation (commands, panels, resolvers,
 subscriptions) do not need to be awaited: the plugin is reported ready
 once they all succeed, and activation fails if `activate` throws or any
-of them fails. The entry module must **default-export** `activate`.
+of them fails. A command declaration the player refuses is the exception
+(SDK 1.5.49): the SDK logs and skips it, its `ready` rejects and
+Scope.onError hears it, the rest of the plugin activates
+(`startPlugin` still fails on it). The entry module must
+**default-export** `activate`.
 
 Stopping: the player first revokes everything the plugin owns on its side
 (menus, windows, panels, filters, subtitle layers, snapshots, jobs,
@@ -6701,7 +6719,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
@@ -6861,7 +6881,24 @@ interface Command extends Disposable {
     checked: Bindable<boolean | null> | Condition;
   }>): void;
   /**
-   * Resolves when the host has registered the command. Rejects with `conflict` (path already taken), `invalid` or `limit` (more than 160 commands in this plugin, or 1024 in the whole player). You rarely need to await it: during activation a failure fails activation, later it goes to Scope.onError.
+   * Resolves when the host has registered the command. Rejects with
+   * `conflict` (path already taken), `invalid` or `limit` (more than 160
+   * commands in this plugin, or 1024 in the whole player). You rarely need
+   * to await it: the refusal goes to Scope.onError. During
+   * activation the SDK, in the plugin's process, logs the refusal with the
+   * command id and the player's message, skips the command and lets the
+   * rest of the plugin activate (SDK 1.5.49; before, the refusal failed
+   * activation); the error reaches `onError` once activation completes,
+   * so a listener added anywhere in `activate` hears it. `startPlugin`
+   * stays strict: there a refusal during activation fails it, so tests
+   * show the bad declaration. Any other failure during activation
+   * (`capability`, no answer) fails activation.
+   *
+   * Only the player's answer is skipped. What Commands.add checks
+   * itself still throws from `add` (an unknown `@` menu id, more than 8
+   * path segments, an `order` out of range, a malformed binding or one
+   * listed twice, a bad `button`, a reason text of the wrong shape, an id
+   * already declared), and fails activation unless the plugin catches it.
    * @throws conflict (rejects) Another command already has this menu path, or the path would be both a menu item and a submenu.
    * @throws capability (rejects) The manifest does not declare `commands`.
    * @throws invalid (rejects) The player refused the declaration.
@@ -6898,8 +6935,9 @@ the menu, the binding table and the user's key overrides: it calls `run`
 when the user picks the item, presses a key or clicks the button.
 Commands of all plugins merge into the player's menus by their English
 path keys. Registration is asynchronous: `add` returns at once, and
-Command.ready reports the player's answer (during activation a
-refusal fails activation).
+Command.ready reports the player's answer (during activation
+the SDK logs a refusal and skips that command, SDK 1.5.49;
+`startPlugin` fails on it). What `add` checks itself throws from `add`.
 
 - @capability commands
 
@@ -6911,7 +6949,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
@@ -8453,6 +8492,7 @@ panel.on("contextMenu", (x: number, y: number) =>
 `ui/panel.slint`:
 
 ```slint
+import { ListView } from "std-widgets.slint";
 import { Theme } from "@vestra/theme.slint";
 
 export global ListBridge {
@@ -8465,7 +8505,9 @@ export global ListBridge {
 export component ListPanel inherits Rectangle {
     background: Theme.bg-list;
     min-width: 200px;
-    VerticalLayout {
+    // A ListView builds only the rows in view and scrolls the rest, so the
+    // list costs the same with three rows or thirty thousand.
+    ListView {
         for row[index] in ListBridge.rows: Rectangle {
             height: 20px;
             background: index == ListBridge.selected ? Theme.selected-bg : transparent;
@@ -8488,9 +8530,6 @@ export component ListPanel inherits Rectangle {
                 }
             }
         }
-        // Takes the space below the rows. Without it the layout's maximum
-        // height (three 20px rows) would cap the player's main window.
-        Rectangle { vertical-stretch: 1; }
     }
 }
 ```
@@ -9392,6 +9431,7 @@ panel.bind(() => ({ rows: items, selected }));
 `ui/panel.slint`:
 
 ```slint
+import { ListView } from "std-widgets.slint";
 import { Theme } from "@vestra/theme.slint";
 
 export global ListBridge {
@@ -9404,7 +9444,9 @@ export global ListBridge {
 export component ListPanel inherits Rectangle {
     background: Theme.bg-list;
     min-width: 200px;
-    VerticalLayout {
+    // A ListView builds only the rows in view and scrolls the rest, so the
+    // list costs the same with three rows or thirty thousand.
+    ListView {
         for row[index] in ListBridge.rows: Rectangle {
             height: 20px;
             background: index == ListBridge.selected ? Theme.selected-bg : transparent;
@@ -9427,9 +9469,6 @@ export component ListPanel inherits Rectangle {
                 }
             }
         }
-        // Takes the space below the rows. Without it the layout's maximum
-        // height (three 20px rows) would cap the player's main window.
-        Rectangle { vertical-stretch: 1; }
     }
 }
 ```
@@ -17140,8 +17179,11 @@ undeclared capability fail with `capability`, as in the player.
 
 Rejects when `manifest.json` cannot be read or parsed, when `activate`
 throws, or when a registration made during activation fails (for example
-`limit`, `conflict`, `invalid`), which is when the player would fail the
-activation.
+`limit`, `conflict`, `invalid`). Stricter than the player's runner for
+commands (SDK 1.5.49): there the SDK logs a command declaration the
+player refuses during activation, skips it and activates the rest of the
+plugin (`onError` hears it); `startPlugin` fails, so a test shows the
+bad declaration.
 
 The way into a plugin's tests: one call starts the plugin the way the
 player's runner does and returns the host to drive, the `plugin` object
@@ -17314,6 +17356,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 +17368,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;
 };
 ```
 
@@ -19389,7 +19450,7 @@ Add a window teaches the view surface panels share with tool windows; the rules
 - **The global `ListBridge`** holds the properties and callbacks. A panel is part of the player's main window, and the player makes a new instance of the component whenever it rebuilds that window. The global stays put, so the plugin talks to it, not to the component.
   - `rows` is the list (an array in TypeScript) and `selected` the selected index.
   - `select(int)` reports a click; `context-menu(float, float)` asks for the menu at a point.
-- **The component** inherits `Rectangle`, not `Window`: the player places it. `for row[index] in ListBridge.rows` draws one 20-pixel row per item; the selected row gets `Theme.selected-bg`.
+- **The component** inherits `Rectangle`, not `Window`: the player places it. A `ListView` from `std-widgets.slint` fills it; `for row[index] in ListBridge.rows` inside it gives one 20-pixel row per item, and the selected row gets `Theme.selected-bg`. The `ListView` creates only the rows in view and scrolls the rest, so the panel stays cheap however long the list grows; a bare `for` in a layout would build every row up front (and `vestra-plugin check` warns about one over a bound array).
 - **The `TouchArea`** of each row: any button going down selects the row. The right button coming up asks for the menu, at the pointer's position in the window (`absolute-position` is the row's position, `mouse-x`/`mouse-y` the pointer's position in it, and `/ 1px` makes a plain number).
 
 #### The code
@@ -19491,6 +19552,7 @@ export default async function activate(plugin: Plugin) {
 #### examples/panel-menu/ui/panel.slint
 
 ```slint
+import { ListView } from "std-widgets.slint";
 import { Theme } from "@vestra/theme.slint";
 
 export global ListBridge {
@@ -19503,7 +19565,9 @@ export global ListBridge {
 export component ListPanel inherits Rectangle {
     background: Theme.bg-list;
     min-width: 200px;
-    VerticalLayout {
+    // A ListView builds only the rows in view and scrolls the rest, so the
+    // list costs the same with three rows or thirty thousand.
+    ListView {
         for row[index] in ListBridge.rows: Rectangle {
             height: 20px;
             background: index == ListBridge.selected ? Theme.selected-bg : transparent;
@@ -19526,9 +19590,6 @@ export component ListPanel inherits Rectangle {
                 }
             }
         }
-        // Takes the space below the rows. Without it the layout's maximum
-        // height (three 20px rows) would cap the player's main window.
-        Rectangle { vertical-stretch: 1; }
     }
 }
 ```

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.49: 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: L15530.
 
 **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 L5972.
 
 ## 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–4007; Commands, menus and key bindings L4008–4162; Playback state, controls and sources L4163–4322; Video and audio processing L4323–4443; Windows, panels, settings pages, dialogs and the OSD L4444–4708; GPU and software rendering L4709–4725; The player's Rust core L4726–5067; How the player runs and talks to plugins L5068–5407
+- Guidelines: Plugin rules L5408–5419; Interface guidelines L5420–5537; Menu guidelines L5538–5596
+- Upgrading: Migrate a plugin to English source text L5597–5746; Migrating off package rollback (1.5.16, removed in 1.5.17) L5747–5824; Who must change, release by release L5825–5894
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5895–15203
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L15204–18090
 
 ## 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 L6311, Scope L6047, PluginError L5972, Disposable L5910
+- Commands L6927; When L6502; Windows L7875; Panels L9321; Dialogs L9991; Player L10732; video: VideoFilter L11612, VideoView L11712, RenderOptions L11799, VideoShaders L11877, VideoUpscaling L12235; audio: AudioFilter L11657; Subtitles L12471; media: MediaCapture L12875; Resolvers L13105; Packages L13507; Osd L11477; Host L11319; Clipboard L13836; Power L13923; Tools L13982; Storage L14134; System L14333; Secrets L14413; window: MainWindow L9638; App L9818; Rendering L14676; Bindings L13735; Ui L7221; Timeline L9550; Drops L8568; Appearance L8649; I18n L8882; Settings L9165.
 
 ## 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. L18525–18620
+- blur: A tool window with one slider that blurs the playing video. L18621–18888
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18889–19227
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L19228–19420
+- panel-menu: A sidebar panel with its own right-click menu. L19421–19635
+- menus: Radio menu items, separator groups and a menu item whose title changes. L19636–19801
+- theme-widgets: A tool window drawn with the player's theme and widgets. L19802–19971
+- markdown: A window that shows a Markdown document. L19972–20174
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L20175–20348
 
 ## Optional
 

package/package.json

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