@vestra-player/sdk 1.5.48 → 1.5.49

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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.

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

@@ -3956,14 +3956,23 @@ export class TestHost {
                     !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 ?? []);
-            for (const binding of bindings)
+            const seen = new Set();
+            for (const binding of bindings.map(String)) {
+                let input;
                 try {
-                    canonical(String(binding));
+                    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))
@@ -3991,13 +4000,6 @@ export class TestHost {
                 this.commands.size + this.coreCommands.size + hostOnly.length >=
                     COMMAND_LIMITS.total)
                 throw new HostError("limit", "command registry limit reached");
-            // 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);
-            }
             const host = this;
             let sent = p.state;
             this.commands.set(id, {
@@ -5426,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.
@@ -5512,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,
@@ -1138,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.
@@ -1161,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
  *

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.48: 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,7 +2357,7 @@ The player bounds what one request may cost it. The limits are guards against ru
 
 #### Commands
 
-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).
+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 |
 | --- | --- | --- |
@@ -3841,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
@@ -4579,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 {
@@ -4591,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;
@@ -4614,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; }
     }
 }
 ```
@@ -5183,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
 
@@ -5491,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).
 
@@ -5827,6 +5832,7 @@ 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. | — |
@@ -6312,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,
@@ -6871,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.
@@ -6908,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
 
@@ -8464,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 {
@@ -8476,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;
@@ -8499,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; }
     }
 }
 ```
@@ -9403,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 {
@@ -9415,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;
@@ -9438,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; }
     }
 }
 ```
@@ -17151,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
@@ -19419,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
@@ -19521,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 {
@@ -19533,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;
@@ -19556,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.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.
+> @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: L15502.
+**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,7 +108,7 @@ 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 L5966.
+- Others: PluginError, llms-full.txt L5972.
 
 ## Reference
 
@@ -116,32 +116,32 @@ export default async function activate(plugin: Plugin) {
 - 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–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
+- 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 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.
+- 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. 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
+- 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.48",
+  "version": "1.5.49",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {