@vestra-player/sdk 1.6.17 → 1.6.18

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.6.18
+
+**Who must change: nobody.** Characterisation tests for the SDK refactor (step 0 of the plan, `doc/specs/sdk-refactor.md` §4.0 in the player repository); no API change, no wire change, `apiVersion` stays `vestra/1`.
+
+- **Golden wire traces** (`test/golden-traces.test.ts`): the ten examples, and the six built-ins named by the plan when `VESTRA_PLAYER` points at a player checkout, run one fixed script against `TestHost` (start, open a source, three state changes, one command, dispose); the `(method, params)` sequence, every `events.subscribe` line with its `mirror`/`why` marks (line numbers stripped) and the update-pass counts per phase are compared with `test/fixtures/traces/*.json`. Eight host scenarios (`host-*.json`) pin the test host's own edges: `disconnect()` with requests in flight, the `commands.keys` push after `commands.register` against `settle()`, `press`, `handle()`/`reset()`, a stream producer's temporary files, `startPlugin` with a `taken` conflict, the `VESTRA_PLUGIN_RESIDENCY=1` line and a host never started. `UPDATE_TRACES=1` rewrites them.
+- **API surface snapshot** (`scripts/api-surface.mjs`, `npm run api-surface -- --check|--update`, `test/api-surface.test.ts`): every exported declaration and member of the `.` and `./testing` entries (the declaration files package.json `exports` names), sorted, in `test/fixtures/api-surface.txt`.
+- **Pass counters**: `Runtime.counts` (internal, read-only: passes, full passes, safety passes, binding evaluations, view bind functions evaluated and skipped) for the SDK's own tests and benchmark; no behaviour change, nothing new on `Plugin` or `TestHost`.
+- **Benchmark** (`npm run bench`, `scripts/bench.mjs`): a 20,000-row keyed list with 1 % and 10 % row changes through the diff engine, 1,000 passes over 50 bound views and 100 commands, and the state-change-to-send latency; medians of five runs, baseline in `docs/maintaining.md`.
+- **`@vestra-player/sdk/testing` is split into modules** (step 1 of the refactor, batch A). **Who must change: nobody**: no API, behaviour or wire change. The single 7,600-line `src/plugin/testing.ts` is now the directory `src/plugin/testing/`: `index.ts` keeps the module page, every export and the one `TestHost` class with all its public members and doc comments; the class keeps its private state in one internal object (`internals.ts`) and delegates its wire handlers and longer methods to area modules (`transport`, `commands`, `declarations`, `core-actions`, `i18n`, `layout`, `osd`, `jobs`, `processing`, `media`, `services`). Error codes, messages and handler semantics are unchanged: every golden trace and host scenario, the API surface snapshot and the pass counts are identical, and the declarations (`dist/plugin/testing/index.d.ts`) equal the former `dist/plugin/testing.d.ts` apart from relative import paths. The `./testing` export now points at `dist/plugin/testing/index.js`; `dist/plugin/testing.js` stays as a re-export. The documentation tree (`dist/docs-tree.json.gz`) is unchanged.
+
 ## 1.6.17
 
 **Who must change: nobody.** Tables follow the slim context menu (B5): a data refresh of `BUILTIN_COMMANDS`, `BUILTIN_SUBMENUS` and the test host's core commands for the player's right-click menu (player 0.7.6); no API change, `apiVersion` stays `vestra/1`. A plugin whose tests compare a path or a key against the tables sees the player's current ones.
@@ -25,11 +35,13 @@
 - **Wire** (additive): `ui.setMount`, `ui.interaction`, `ui.menu` and `ui.unmount` take an optional `slot` naming the panel (without it: the plugin's only panel; `ui.unmount` without it removes every panel); `ui.callback` and `ui.preparing` carry the panel's `slot`, and `ui.callback` keeps `view: "$mount"`. Older players ignore `slot`.
 - **`BUILTIN_COMMANDS`**: the player's seek, frame and speed actions (`host/seek-backward`, `seek-forward`, `frame-back`, `frame-forward`, `rate-down`, `rate-up`, `rate-normal`) leave Playback ▸ Seek and Speed for the command palette (player 0.7.6, with the playback plugin's panel); their keys and categories stay.
 - **`TestHost`**: `panels` (by slot, in mount order) and `mounted(slot?)`; without a slot `mounted()` returns the only panel and throws when there are several. `panel` stays, as the last panel mounted. The handlers take `slot` as the player does; `ui.interaction` stores the locks without it.
+
 ## 1.6.14
 
 **Who must change: nobody.** A data refresh: `BUILTIN_COMMANDS` lists the built-in capture plugin's commands as the player registers them since its capture tab; no API change, `apiVersion` stays `vestra/1`.
 
 - **`BUILTIN_COMMANDS`**: `vestra.capture` has **Video ▸ Snapshot ▸ Capture…** (Alt+S), which opens its sidebar tab; Save/Copy Rendered Frame, Save Current Frame As…, Export Tasks…, the capture formats, Snapshot Settings…, Snapshot Folder… and Open Snapshot Folder left the menu for the command palette, and new palette commands came: Export Clip Range (Ctrl+Shift+E), Save and Copy Video Frame Only, Show Last Capture in Folder, Copy Last Snapshot, Set Clip Start, Set Clip End and Export Last 30 Seconds (Ctrl+Shift+R). A plugin that checks a key or menu path against the table (`vestra-plugin check`, `TestHost`) sees the player's current ones.
+
 ## 1.6.13
 
 **Who must change: plugin tests that toggle a column in fullscreen.** In fullscreen `toggle()` now only switches the column on or off (user ruling 2026-11-08); a test that asserted `effective: true` after toggling a column on in fullscreen now sees `effective: false`, `reason: "fullscreen"` (on, revealed by the right edge). Plugin code needs no change; `apiVersion` stays `vestra/1`, and the wire gains one optional field.
@@ -45,6 +57,7 @@
 - **`Panel.toggle` and `PanelSlot.toggle` slide a collapsed column out.** In fullscreen a sidebar or adjust column the user wants shown is collapsed at the right edge (`reason: "fullscreen"`). Toggling it then turned it off; it now shows it, which player 0.7.6 answers by sliding the column out, as its own Adjust button and Alt+1…4 do. Toggling a column that is on screen still turns it off. With players before 0.7.6 a show of a collapsed column changes nothing on screen, as before.
 - **[adjust-panel](docs/examples/adjust-panel.md)** declares `events`: without it `plugin.player.state` changes only after the plugin's own calls, so a panel activated before a file was opened stayed disabled at 1×. A new test opens the file after activation. Its presets are four (0.5×, 1×, 1.5×, 2×), which fit the adjust column at its least width. No other example reads `player.state` without `events`.
 - **A development warning for state followed without `events`.** A plugin that registers an `onChange` or a `bind` whose function reads changing state (`player.state`, a panel position, and the like) without the `events` capability gets one line in its log, once per plugin: changes made elsewhere never reach it. Only a warning; behaviour is unchanged. `TestHost` already behaved like the player here (it delivers `source.state` and the other state events only to a plugin that subscribed, which needs `events`): a new test pins that down. The example's old tests passed because they opened the file before starting the plugin or did not check `enabled`. No SDK example or test relied on the opposite, so nobody must change.
+
 ## 1.6.11
 
 **Who must change: nobody.** Additions only: a mount slot, a panel position, a button icon and `TestHost` support; `apiVersion` stays `vestra/1`, no new capability. A plugin that mounts `"adjust"` sets `minPlayerVersion` to `0.7.6`: older players refuse the slot (`invalid`), which fails the activation like any refused mount.

package/dist/plugin/runtime.d.ts

@@ -37,6 +37,30 @@ export type Change = ReadonlyMap<string, ReadonlySet<string>>;
  * without `update()`) still shows within about this long.
  */
 export declare const SAFETY_PASS_MS = 1000;
+/**
+ * Read-only counters of the update passes, for the SDK's own
+ * characterisation tests and benchmark (`test/golden-traces.test.ts`,
+ * `scripts/bench.mjs`): how many passes ran, how many were full, how many
+ * bindings and view bind functions (parts) were evaluated or skipped. Not
+ * part of the plugin API; counting changes no behaviour.
+ */
+export interface PassCounts {
+    /** Passes run (`Runtime.#run`), precise and full. */
+    passes: number;
+    /** Of them, full passes (every binding evaluated). */
+    fullPasses: number;
+    /** Bindings evaluated (`Runtime.#evaluate`). */
+    evaluations: number;
+    /** View bind functions evaluated inside a binding (`Runtime.part`). */
+    parts: number;
+    /** View bind functions a precise pass skipped (`Runtime.part`). */
+    skippedParts: number;
+    /**
+     * Full passes the safety timer requested (`SAFETY_PASS_MS` after a
+     * precise pass skipped something), counted when the timer fires.
+     */
+    safetyPasses: number;
+}
 /** How the plugin is run: the player's runner, or `TestHost`. */
 export interface RuntimeOptions {
     /**
@@ -72,6 +96,8 @@ export declare class Runtime {
     readonly local: LocalServices | undefined;
     /** Registrations that activation must wait for before reporting ready. */
     readonly startup: Set<Promise<unknown>>;
+    /** Pass counters, read by the SDK's own tests and benchmark ({@link PassCounts}). */
+    readonly counts: PassCounts;
     readonly views: Map<string, (callback: string, args: Json[]) => void>;
     readonly commands: Map<string, () => void>;
     readonly services: Map<string, unknown>;

package/dist/plugin/runtime.js

@@ -209,6 +209,15 @@ export class Runtime {
     #skipped = false;
     /** The plugin was disposed: no safety pass is armed any more. */
     #stopped = false;
+    /** Pass counters, read by the SDK's own tests and benchmark ({@link PassCounts}). */
+    counts = {
+        passes: 0,
+        fullPasses: 0,
+        evaluations: 0,
+        parts: 0,
+        skippedParts: 0,
+        safetyPasses: 0,
+    };
     #events = new Map();
     /** The missing `events` warning was given (once per plugin). */
     #warnedEvents = false;
@@ -389,6 +398,7 @@ export class Runtime {
         const outerDeps = this.#deps;
         if (last && this.#pass && !affected(last.deps, this.#pass)) {
             this.#skipped = true;
+            this.counts.skippedParts++;
             if (outerReads)
                 for (const [event, why] of last.reads)
                     if (!outerReads.has(event))
@@ -397,6 +407,7 @@ export class Runtime {
                 merge(outerDeps, last.deps);
             return undefined;
         }
+        this.counts.parts++;
         const reads = new Map();
         const deps = new Map();
         this.#reads = outerReads && reads;
@@ -512,6 +523,7 @@ export class Runtime {
         this.#reads = reads;
         this.#deps = deps;
         this.#reader = undefined;
+        this.counts.evaluations++;
         try {
             evaluate();
         }
@@ -570,6 +582,9 @@ export class Runtime {
         const change = this.#pending;
         this.#full = false;
         this.#pending = new Map();
+        this.counts.passes++;
+        if (full)
+            this.counts.fullPasses++;
         if (full) {
             clearTimeout(this.#safety);
             this.#safety = undefined;
@@ -596,6 +611,7 @@ export class Runtime {
         if (this.#skipped && !this.#safety && !this.#stopped) {
             this.#safety = setTimeout(() => {
                 this.#safety = undefined;
+                this.counts.safetyPasses++;
                 this.invalidate();
             }, SAFETY_PASS_MS);
             this.#safety.unref?.();

package/dist/plugin/testing/commands.d.ts

@@ -0,0 +1,65 @@
+import type { Json } from "../../wire.ts";
+import type { CommandWhen } from "../../commands.ts";
+import type { FakeCommand, FakeBarButton, TestHost } from "./index.ts";
+import type { Handler, Internals } from "./internals.ts";
+/** A command state's reason, refused as the player refuses it. */
+export declare function checkReason(host: TestHost, inner: Internals, state: Json | undefined): string | null;
+export declare function bindingClaims(host: TestHost, inner: Internals): Map<string, string[]>;
+/** `host/<id>` for core commands, `<manifest id>/<id>` for the plugin's. */
+export declare function bindingKey(host: TestHost, _inner: Internals, id: string): string;
+/**
+ * `commands.keys` as the player answers it: each of the plugin's own
+ * commands, and the player's core commands as `host/<id>` (SDK 1.6.16),
+ * with the labels of the keys it holds now (the overlay, else its
+ * defaults; not a key an earlier command holds), as menus write them on
+ * `systemInfo.os`.
+ */
+export declare function commandKeys(host: TestHost, inner: Internals): {
+    keys: Record<string, string[]>;
+    revision: number;
+};
+/** Push `commands.keys` when the labels changed and the plugin listens. */
+export declare function keysChanged(host: TestHost, inner: Internals): void;
+export declare function splitCommandKey(_host: TestHost, _inner: Internals, key: string): {
+    plugin: string;
+    command: string;
+};
+export declare function bindingTable(host: TestHost, inner: Internals): {
+    commands: {
+        title: string;
+        path: string[] | null;
+        key: string[] | null;
+        category: string | null;
+        scope: "panel" | "global";
+        defaults: string[];
+        current: string[];
+        overridden: boolean;
+        shadowed: {
+            input: string;
+            by: {
+                plugin: string;
+                command: string;
+            };
+        }[];
+        labels: string[];
+        plugin: string;
+        command: string;
+    }[];
+    orphans: {
+        ref: {
+            plugin: string;
+            command: string;
+        };
+        inputs: string[];
+    }[];
+};
+/** A command's state as the player shows it: its conditions evaluated. */
+export declare function commandShown(host: TestHost, _inner: Internals, sent: FakeCommand["state"], when: CommandWhen | undefined): FakeCommand["state"];
+/** Implements `TestHost.press`. */
+export declare function press(host: TestHost, inner: Internals, binding: string, options?: {
+    panel?: boolean;
+}): Promise<"ran" | "reason" | "passed">;
+/** Implements `TestHost.barButtons`. */
+export declare function barButtons(host: TestHost, _inner: Internals): readonly FakeBarButton[];
+/** The default handlers of this area's wire methods, by method name. */
+export declare function commandsHandlers(host: TestHost, inner: Internals): Record<string, Handler>;

package/dist/plugin/testing/commands.js

@@ -0,0 +1,412 @@
+/**
+ * Plugin commands and key bindings: `commands.*` and `bindings.*`, the
+ * binding table, conflicts and the bar buttons.
+ *
+ * Part of `TestHost` (`./index.ts`): functions over the host and its private
+ * state (`Internals`, `./internals.ts`) that the class delegates to.
+ * Internal to the SDK; not exported from `@vestra-player/sdk/testing`.
+ */
+import { HostError } from "../../wire.js";
+import { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, BUILTIN_COMMANDS, COMMAND_LIMITS, MENU_IDS, } from "../../commands.js";
+import { canonical, keyLabel } from "../bindings.js";
+import { evaluate } from "../when.js";
+import { menuKeys, textKey } from "../../i18n.js";
+import { commandInvalid, commandConflict, commandText, menuTextKey, checkDeclaration, } from "./declarations.js";
+import { declaredText, commandDisplay } from "./i18n.js";
+/** A command state's reason, refused as the player refuses it. */
+export function checkReason(host, inner, state) {
+    const reason = state?.reason;
+    return reason !== null && reason !== undefined
+        ? declaredText(host, inner, reason, "reason")
+        : null;
+}
+export function bindingClaims(host, inner) {
+    const claims = new Map();
+    // The player's own commands win a conflict, as in the binding table.
+    for (const [id, { declaration }] of [
+        ...host.coreCommands,
+        ...host.commands,
+    ]) {
+        const scope = declaration.focus ? "panel" : "global";
+        // The user overlay (`bindings.set`) replaces a command's own bindings.
+        const overridden = host.bindings.overlay.get(bindingKey(host, inner, id));
+        for (const binding of overridden ?? declaration.bindings ?? []) {
+            const key = `${scope} ${binding}`;
+            claims.set(key, [...(claims.get(key) ?? []), id]);
+        }
+    }
+    return claims;
+}
+/** `host/<id>` for core commands, `<manifest id>/<id>` for the plugin's. */
+export function bindingKey(host, _inner, id) {
+    return host.coreCommands.has(id) ? id : `${host.manifestId}/${id}`;
+}
+/**
+ * `commands.keys` as the player answers it: each of the plugin's own
+ * commands, and the player's core commands as `host/<id>` (SDK 1.6.16),
+ * with the labels of the keys it holds now (the overlay, else its
+ * defaults; not a key an earlier command holds), as menus write them on
+ * `systemInfo.os`.
+ */
+export function commandKeys(host, inner) {
+    const claims = bindingClaims(host, inner);
+    const mac = host.systemInfo.os === "macos";
+    const keys = {};
+    for (const [id, { declaration }] of [
+        ...host.commands,
+        ...host.coreCommands,
+    ]) {
+        const scope = declaration.focus ? "panel" : "global";
+        const current = host.bindings.overlay.get(bindingKey(host, inner, id)) ??
+            declaration.bindings ??
+            [];
+        const labels = [];
+        for (const input of current) {
+            if (claims.get(`${scope} ${input}`)?.[0] !== id)
+                continue;
+            const label = keyLabel(input, mac);
+            if (label !== null && !labels.includes(label))
+                labels.push(label);
+        }
+        keys[id] = labels;
+    }
+    return { keys, revision: inner.keysRevision };
+}
+/** Push `commands.keys` when the labels changed and the plugin listens. */
+export function keysChanged(host, inner) {
+    inner.keysRevision++;
+    if (!host.subscriptions.has("commands.keys"))
+        return;
+    const now = commandKeys(host, inner);
+    const text = JSON.stringify(now.keys);
+    if (text === inner.keysSent)
+        return;
+    inner.keysSent = text;
+    host.emit("commands.keys", now);
+}
+export function splitCommandKey(_host, _inner, key) {
+    const at = key.indexOf("/");
+    return { plugin: key.slice(0, at), command: key.slice(at + 1) };
+}
+export function bindingTable(host, inner) {
+    const claims = bindingClaims(host, inner);
+    const commands = [...host.coreCommands, ...host.commands].map(([id, { declaration }]) => {
+        const key = bindingKey(host, inner, id);
+        const scope = declaration.focus ? "panel" : "global";
+        const current = host.bindings.overlay.get(key) ?? declaration.bindings;
+        const shown = host.commands.get(id) ?? host.coreCommands.get(id);
+        return {
+            ...splitCommandKey(host, inner, key),
+            // What the user sees, like the player's binding table.
+            title: shown?.display.title ?? String(declaration.title),
+            path: declaration.path?.length
+                ? (shown?.display.path ?? declaration.path.map(String))
+                : null,
+            key: declaration.path?.length
+                ? menuKeys(declaration.path.map((segment) => typeof segment === "string" ? segment : textKey(segment)))
+                : null,
+            // Player 0.7.6: the category as shown, `null` without one.
+            category: shown?.display.category ?? null,
+            scope: scope,
+            defaults: declaration.bindings,
+            current,
+            overridden: host.bindings.overlay.has(key),
+            shadowed: current.flatMap((input) => {
+                const winner = claims.get(`${scope} ${input}`)?.[0];
+                return !winner || winner === id
+                    ? []
+                    : [
+                        {
+                            input,
+                            by: splitCommandKey(host, inner, bindingKey(host, inner, winner)),
+                        },
+                    ];
+            }),
+            labels: [...current],
+        };
+    });
+    const declared = new Set(commands.map((c) => `${c.plugin}/${c.command}`));
+    const orphans = [...host.bindings.overlay]
+        .filter(([key]) => !declared.has(key))
+        .map(([key, inputs]) => ({
+        ref: splitCommandKey(host, inner, key),
+        inputs,
+    }));
+    return { commands, orphans };
+}
+/** A command's state as the player shows it: its conditions evaluated. */
+export function commandShown(host, _inner, sent, when) {
+    if (!when)
+        return sent;
+    const source = host.source;
+    const capabilities = source.capabilities;
+    const facts = {
+        phase: source.phase,
+        paused: source.paused,
+        kind: source.kind === "producer" ? "stream" : "media",
+        can: {
+            pause: capabilities.pause,
+            seek: capabilities.seek,
+            rate: capabilities.rate,
+            restart: capabilities.restart,
+            close: capabilities.close,
+            snapshot: capabilities.snapshotSource,
+            // As the player: the flags merged into the source state.
+            next: source.sequence?.next === true,
+            previous: source.sequence?.previous === true,
+        },
+        fullscreen: host.mainWindow.fullscreen,
+        theme: host.appearance,
+        language: host.language,
+    };
+    const shown = { ...sent };
+    if (when.enabled) {
+        shown.enabled = evaluate(when.enabled, facts);
+        if (shown.enabled && !shown.busy)
+            shown.reason = null;
+    }
+    if (when.checked)
+        shown.checked = evaluate(when.checked, facts);
+    return shown;
+}
+/** Implements `TestHost.press`. */
+export async function press(host, inner, binding, options = {}) {
+    const claims = bindingClaims(host, inner);
+    const ids = [
+        ...(options.panel ? (claims.get(`panel ${binding}`) ?? []) : []),
+        ...(claims.get(`global ${binding}`) ?? []),
+    ];
+    if (!ids.length)
+        throw new Error(`test host: nothing is bound to ${binding}`);
+    const command = (id) => host.coreCommands.get(id) ?? host.command(id);
+    const enabled = ids.find((id) => command(id).state.enabled);
+    if (enabled !== undefined) {
+        await command(enabled).run();
+        return "ran";
+    }
+    // Like the player: only the first disabled command counts; without a
+    // reason the key goes on to the focused control.
+    const first = ids[0];
+    const reason = host.commands.has(first)
+        ? command(first).display.reason
+        : command(first).state.reason;
+    if (typeof reason === "string" && reason !== "") {
+        host.osd.push(reason);
+        return "reason";
+    }
+    return "passed";
+}
+/** Implements `TestHost.barButtons`. */
+export function barButtons(host, _inner) {
+    return [...host.commands]
+        .filter(([, command]) => command.declaration.button !== undefined)
+        .slice(0, BAR_BUTTON_LIMITS.perPlugin)
+        .map(([id, command]) => {
+        const button = command.declaration.button;
+        const image = typeof button.icon !== "string";
+        const reason = command.display.reason;
+        const title = command.display.title.replace(/(…|\.\.\.)\s*$/, "");
+        const enabled = command.state.enabled && !command.state.busy;
+        return Object.freeze({
+            command: id,
+            icon: image
+                ? String(button.icon.$vestraImage)
+                : button.icon,
+            image,
+            order: button.order,
+            enabled,
+            checked: command.state.checked === true,
+            tooltip: !enabled && reason ? `${title}\n${reason}` : title,
+            async click() {
+                const current = host.commands.get(id);
+                if (current !== command)
+                    throw new HostError("missing", `command ${id} is gone`);
+                await current.run();
+            },
+        });
+    });
+}
+/** The default handlers of this area's wire methods, by method name. */
+export function commandsHandlers(host, inner) {
+    return {
+        "commands.register": (p) => {
+            const id = String(p.id);
+            // 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 = checkReason(host, inner, 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" && host.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 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);
+            // Player 0.7.6: the category, keyed like a menu text.
+            const category = declaration.category === undefined || declaration.category === null
+                ? null
+                : menuTextKey(declaration.category);
+            checkDeclaration(id, title, path, declaration, category);
+            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 (host.commands.has(id))
+                throw commandConflict("owner/localId already registered");
+            // The player's own commands beside the core actions (host/actions.rs
+            // `host_declarations`: Toggle Fullscreen, Command Palette…, Quit and
+            // four outside the menu), which take part in conflicts and the total
+            // like any other.
+            const hostOnly = BUILTIN_COMMANDS.filter((row) => row.owner === "host" && !host.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),
+                    ...[...host.coreCommands.values()].map((command) => command.declaration.path),
+                    ...[...host.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 (host.commands.size >= COMMAND_LIMITS.perPlugin ||
+                host.commands.size + host.coreCommands.size + hostOnly.length >=
+                    COMMAND_LIMITS.total)
+                throw new HostError("limit", "command registry limit reached");
+            let sent = p.state;
+            host.commands.set(id, {
+                declaration,
+                get display() {
+                    return commandDisplay(host, inner, declaration.path ?? [], declaration.title, this.state.reason, declaration.category ?? null);
+                },
+                ...(p.when ? { when: p.when } : {}),
+                get state() {
+                    return commandShown(host, inner, sent, this.when);
+                },
+                set state(state) {
+                    sent = state;
+                },
+                revision: Number(p.revision),
+                async run() {
+                    if (this.state.busy || !this.state.enabled)
+                        throw new HostError("command", `${id} is ${this.state.busy ? "busy" : "disabled"}`);
+                    host.emit("commands.execute", { id, revision: this.revision });
+                    await host.settle();
+                },
+            });
+            // The player pushes the new command's keys after the answer.
+            queueMicrotask(() => keysChanged(host, inner));
+            return { revision: 1 };
+        },
+        "commands.unregister": (p) => {
+            if (!host.commands.delete(String(p.id)))
+                throw new HostError("missing", `command ${p.id} is not registered`);
+            queueMicrotask(() => keysChanged(host, inner));
+        },
+        // Player 0.7.6: the labels of the plugin's own commands.
+        "commands.keys": () => {
+            const now = commandKeys(host, inner);
+            inner.keysSent = JSON.stringify(now.keys);
+            return now;
+        },
+        "commands.update": (p) => {
+            // 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 = checkReason(host, inner, 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 = host.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}; 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)
+                command.when = p.when;
+            else
+                delete command.when;
+            return { revision: command.revision };
+        },
+        "bindings.list": () => bindingTable(host, inner),
+        "bindings.set": (p) => {
+            const key = `${p.plugin}/${p.command}`;
+            const known = bindingTable(host, inner).commands.some((c) => `${c.plugin}/${c.command}` === key);
+            if (!known && !host.bindings.overlay.has(key))
+                throw new HostError("missing", `no command ${key}`);
+            host.bindings.overlay.set(key, [...p.inputs]);
+            host.emit("bindings.changed", null);
+            keysChanged(host, inner);
+        },
+        "bindings.reset": (p) => {
+            if (p.plugin === undefined)
+                host.bindings.overlay.clear();
+            else
+                host.bindings.overlay.delete(`${p.plugin}/${p.command}`);
+            host.emit("bindings.changed", null);
+            keysChanged(host, inner);
+        },
+    };
+}

package/dist/plugin/testing/core-actions.d.ts

@@ -0,0 +1,39 @@
+import type { TestHost } from "./index.ts";
+import type { Handler, Internals } from "./internals.ts";
+export declare function coreFacts(host: TestHost, _inner: Internals): {
+    ready: boolean;
+    ended: boolean;
+    toggle: boolean;
+    step: boolean;
+    rate: boolean;
+    close: boolean;
+};
+/** Why one frame that way is impossible (B07), or null; the player's rules. */
+export declare function frameCheck(host: TestHost, inner: Internals, forward: boolean): string | null;
+/** The same enabled rules and reasons as the player's core actions. */
+export declare function coreState(host: TestHost, inner: Internals, action: string): {
+    enabled: boolean;
+    checked: boolean | null;
+    busy: boolean;
+    reason: string | null;
+};
+export declare function registerCoreActions(host: TestHost, inner: Internals): void;
+export declare function runCore(host: TestHost, inner: Internals, action: string, seconds?: number): void;
+export declare function windowFacts(host: TestHost, _inner: Internals): {
+    fullscreen: boolean;
+    maximized: boolean;
+    videoArea: {
+        width: number;
+        height: number;
+    };
+    pictureInPicture: {
+        supported: boolean;
+        active: boolean;
+    };
+    appearance: import("../types.ts").ThemeId;
+    fileTypes: string[];
+    language: import("../types.ts").LanguagePreference;
+    locale: import("../types.ts").Locale;
+};
+/** The default handlers of this area's wire methods, by method name. */
+export declare function coreActionsHandlers(host: TestHost, inner: Internals): Record<string, Handler>;