@vestra-player/sdk 1.6.16 → 1.6.18

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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.
+
+- **`BUILTIN_COMMANDS`**: the top level is now Open File…, Open ▸, Close — **Play/Pause** (`host/play-pause`, from Playback ▸), Audio Track ▸, Subtitle Track ▸, **Snapshot ▸** (`vestra.capture`, from Video ▸) — Picture…, Audio…, Subtitles…, Playback…, Playlist, **Chapter and Bookmark List…** (`vestra.marks`, from Playback ▸ Chapters and Bookmarks ▸) — Toggle Fullscreen — Vestra Player AI…, Plugin Store… — **Command Palette…** (`host/palette`, in the menu now, with an ellipsis; `Ctrl+Shift+P` unchanged), **Options…** (`vestra.preferences`, from Settings ▸), About Vestra Player… — Quit. Open ▸ gains **Search and Download Subtitles…** (`vestra.subtitle-online`, from Subtitles ▸ Online Subtitles ▸). Everything else left the menu for the command palette, with ids, keys and categories unchanged: the player's Previous and Next (PageUp, PageDown, the side mouse buttons), Volume +, Volume − and Mute (the Audio panel has their controls); the playback plugin's Reopen, Copy to Clipboard ▸, Disable Screen Saver and the seek-bar hover items; the window plugin's Hide Pointer and the whole Screen ▸ menu; Playback ▸ Playlist ▸; Resume Playback ▸; the marks plugin's bookmark, chapter and A-B Loop items; Online Subtitle Settings…; the visualizer's Show Album Cover, Show Logo When Idle, Choose Logo Image… and Reset ▸ Idle Logo; Keyboard Shortcuts…, Mouse… and Ignore Default Shortcuts; Appearance ▸ and Language ▸; Playback Info, Playback Properties… and Check for Updates…. The table in [Reference: commands](docs/reference/commands.md) follows, with the new top level, its groups and orders (Toggle Fullscreen 810, Command Palette… 829).
+- **`BUILTIN_SUBMENUS`**: Open ▸ Recently Played, Audio Track, Subtitle Track and Snapshot (a top-level submenu now) remain; the Playback, Subtitles, Screen and Settings submenus and Copy to Clipboard are gone. The built-in menus (`@playback`, `@subtitles`, `@video`, `@audio`, `@screen`, `@settings`, `@reset`) stay valid for plugins at their fixed orders and are shown only while a command is in them.
+- **`TestHost`**: the core commands carry the player's menu places: Play/Pause at the top level (`["Play/Pause"]`, order 201), Previous, Next, the volume steps and Mute outside the menu, and the seek, frame and speed actions outside the menu as the player has had them since 1.6.15 (the test host kept their Playback ▸ Seek and Speed paths until now). A plugin item at `["Playback", "Seek", …]`, `["@playback", "Speed"]` or `["Audio", …]` is therefore accepted, as the player accepts it (1.5.48 listed `Playback ▸ Speed` as an item and `Audio ▸ Mute ▸ …` as conflicts: they were, while the player's items were there); `["Play/Pause"]`, `["Close"]` and an item below either are conflicts.
+
 ## 1.6.16
 
 **Who must change: nobody.** A data refresh for the player's four built-in panels (player 0.7.6) and one additive read; no API is removed, `apiVersion` stays `vestra/1`.
@@ -17,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.
@@ -37,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/commands.d.ts

@@ -208,10 +208,10 @@ export interface BuiltinSubmenu {
  * built-in plugins declare.
  *
  * @example Add an item to the built-in Snapshot submenu
- * "Copy Snapshot" appears in Video ▸ Snapshot next to the built-in capture
+ * "Copy Snapshot" appears in Snapshot ▸ next to the built-in capture
  * plugin's items. Paths merge by their English keys, so a command whose
- * path continues with the submenu's keys (`["Video", "Snapshot"]`, the menu
- * written as `@video`) lands in the same submenu whatever the interface
+ * path starts with the submenu's keys (`["Snapshot"]`, a top-level submenu
+ * since player 0.7.6) lands in the same submenu whatever the interface
  * language.
  * ```ts
  * import type { Plugin } from "@vestra-player/sdk";
@@ -223,8 +223,8 @@ export interface BuiltinSubmenu {
  * const snapshot = BUILTIN_SUBMENUS.find((menu) => menu.path.at(-1) === "Snapshot")!;
  * plugin.commands.add({
  *   id: "snapshot-to-clipboard",
- *   // ["@video", "Snapshot", "Copy Snapshot"]; @video stands for "Video".
- *   path: ["@video", ...snapshot.path.slice(1), "Copy Snapshot"],
+ *   // ["Snapshot", "Copy Snapshot"]
+ *   path: [...snapshot.path, "Copy Snapshot"],
  *   run: copySnapshot,
  * });
  * ```

package/dist/commands.js

@@ -234,10 +234,10 @@ export const BAR_BUTTON_LIMITS = {
  * built-in plugins declare.
  *
  * @example Add an item to the built-in Snapshot submenu
- * "Copy Snapshot" appears in Video ▸ Snapshot next to the built-in capture
+ * "Copy Snapshot" appears in Snapshot ▸ next to the built-in capture
  * plugin's items. Paths merge by their English keys, so a command whose
- * path continues with the submenu's keys (`["Video", "Snapshot"]`, the menu
- * written as `@video`) lands in the same submenu whatever the interface
+ * path starts with the submenu's keys (`["Snapshot"]`, a top-level submenu
+ * since player 0.7.6) lands in the same submenu whatever the interface
  * language.
  * ```ts
  * import type { Plugin } from "@vestra-player/sdk";
@@ -249,8 +249,8 @@ export const BAR_BUTTON_LIMITS = {
  * const snapshot = BUILTIN_SUBMENUS.find((menu) => menu.path.at(-1) === "Snapshot")!;
  * plugin.commands.add({
  *   id: "snapshot-to-clipboard",
- *   // ["@video", "Snapshot", "Copy Snapshot"]; @video stands for "Video".
- *   path: ["@video", ...snapshot.path.slice(1), "Copy Snapshot"],
+ *   // ["Snapshot", "Copy Snapshot"]
+ *   path: [...snapshot.path, "Copy Snapshot"],
  *   run: copySnapshot,
  * });
  * ```
@@ -261,31 +261,9 @@ export const BAR_BUTTON_LIMITS = {
  */
 export const BUILTIN_SUBMENUS = Object.freeze([
     { path: ["Open", "Recently Played"], plugins: ["vestra.history"] },
-    { path: ["Playback", "A-B Loop"], plugins: ["vestra.marks"] },
-    { path: ["Playback", "A-B Loop", "Loop Count"], plugins: ["vestra.marks"] },
-    { path: ["Playback", "Chapters and Bookmarks"], plugins: ["vestra.marks"] },
-    { path: ["Playback", "Playlist"], plugins: ["vestra.playlist"] },
-    { path: ["Playback", "Playlist", "Repeat"], plugins: ["vestra.playlist"] },
-    {
-        path: ["Playback", "Playlist", "When Opening a File"],
-        plugins: ["vestra.playlist"],
-    },
-    { path: ["Playback", "Resume Playback"], plugins: ["vestra.history"] },
-    {
-        path: ["Subtitles", "Online Subtitles"],
-        plugins: ["vestra.subtitle-online"],
-    },
-    { path: ["Video", "Snapshot"], plugins: ["vestra.capture"] },
-    { path: ["Screen", "Always on Top"], plugins: ["vestra.window"] },
-    { path: ["Screen", "When Playback Starts"], plugins: ["vestra.window"] },
-    {
-        path: ["Settings", "Appearance"],
-        plugins: ["vestra.preferences", "vestra.visualizer"],
-    },
-    { path: ["Settings", "Language"], plugins: ["vestra.preferences"] },
-    { path: ["Copy to Clipboard"], plugins: ["vestra.playback"] },
-    { path: ["Subtitle Track"], plugins: ["vestra.subtitles"] },
     { path: ["Audio Track"], plugins: ["vestra.audio"] },
+    { path: ["Subtitle Track"], plugins: ["vestra.subtitles"] },
+    { path: ["Snapshot"], plugins: ["vestra.capture"] },
 ]);
 /** owner | id | key path, or (title) outside the menu | bindings | panel */
 const BUILTIN_COMMAND_TABLE = `
@@ -293,136 +271,44 @@ vestra.playback | open | Open File… | Ctrl+O, F3
 vestra.playback | open-url | Open ▸ Open URL… | Ctrl+U
 vestra.playlist | playlist.open-folder | Open ▸ Open Folder… | F2
 vestra.subtitles | load | Open ▸ Open Subtitle… | Alt+O
+vestra.subtitles | load-secondary | Open ▸ Add Secondary Subtitle…
 vestra.audio | audio.load | Open ▸ Load External Audio…
+vestra.subtitle-online | search | Open ▸ Search and Download Subtitles…
 vestra.history | recent.empty | Open ▸ Recently Played ▸ (No Entries)
 vestra.history | recent.prune | Open ▸ Recently Played ▸ Remove Invalid Entries
 vestra.history | recent.clear | Open ▸ Recently Played ▸ Clear Entries
 vestra.history | recent.enabled | Open ▸ Recently Played ▸ Record Playback History
-vestra.subtitles | load-secondary | Open ▸ Add Secondary Subtitle…
 host | stop | Close | F4
-vestra.playback | reopen | Reopen Current/Last File | Ctrl+Y
-vestra.playback | copy-name | Copy to Clipboard ▸ File Name
-vestra.playback | copy-folder | Copy to Clipboard ▸ Folder Path
-vestra.playback | copy-path | Copy to Clipboard ▸ Full Path
-host | play-pause | Playback ▸ Play/Pause | Space, Mouse:LeftClick
-host | previous | Playback ▸ Previous | PageUp, Mouse:X2
-host | next | Playback ▸ Next | PageDown, Mouse:X1
-vestra.playlist | playlist.add | Playback ▸ Playlist ▸ Add Files…
-vestra.playlist | playlist.link | Playback ▸ Playlist ▸ Add Link…
-vestra.playlist | playlist.add-folder | Playback ▸ Playlist ▸ Add Folder…
-vestra.playlist | playlist.repeat-none | Playback ▸ Playlist ▸ Repeat ▸ Off
-vestra.playlist | playlist.repeat-all | Playback ▸ Playlist ▸ Repeat ▸ All
-vestra.playlist | playlist.repeat-one | Playback ▸ Playlist ▸ Repeat ▸ One
-vestra.playlist | playlist.shuffle | Playback ▸ Playlist ▸ Shuffle
-vestra.playlist | playlist.open-list | Playback ▸ Playlist ▸ Open List File…
-vestra.playlist | playlist.save-list | Playback ▸ Playlist ▸ Save List…
-vestra.playlist | playlist.open-mode-only | Playback ▸ Playlist ▸ When Opening a File ▸ Open Only That File
-vestra.playlist | playlist.open-mode-similar | Playback ▸ Playlist ▸ When Opening a File ▸ Add Similar Files
-vestra.playlist | playlist.open-mode-folder | Playback ▸ Playlist ▸ When Opening a File ▸ Add All Files in the Folder
-vestra.playlist | playlist.fast-advance | Playback ▸ Playlist ▸ Fast Advance to Next
-vestra.playlist | playlist.remember | Playback ▸ Playlist ▸ Remember List
-vestra.playlist | playlist.confirm-clear | Playback ▸ Playlist ▸ Confirm Before Removing All
-vestra.playback | prevent-sleep | Playback ▸ Disable Screen Saver While Playing
-vestra.window | hide-cursor | Playback ▸ Hide Pointer While Playing
-vestra.playback | hover-time | Playback ▸ Show Time on Seek Bar Hover
-vestra.playback | hover-thumbnail | Playback ▸ Show Thumbnail on Seek Bar Hover
-vestra.history | resume.off | Playback ▸ Resume Playback ▸ Don't Resume
-vestra.history | resume.auto | Playback ▸ Resume Playback ▸ Resume Automatically
-vestra.history | resume.ask | Playback ▸ Resume Playback ▸ Ask Every Time
-vestra.history | resume.audio | Playback ▸ Resume Playback ▸ Also Remember Audio Files
-vestra.history | resume.clear | Playback ▸ Resume Playback ▸ Clear All Saved Positions
-vestra.marks | marks.list | Playback ▸ Chapters and Bookmarks ▸ Chapter and Bookmark List… | H
-vestra.marks | marks.add | Playback ▸ Chapters and Bookmarks ▸ Add Bookmark | P
-vestra.marks | marks.previous | Playback ▸ Chapters and Bookmarks ▸ Previous Bookmark or Chapter | Shift+PageUp
-vestra.marks | marks.next | Playback ▸ Chapters and Bookmarks ▸ Next Bookmark or Chapter | Shift+PageDown
-vestra.marks | marks.previous-chapter | Playback ▸ Chapters and Bookmarks ▸ Previous Chapter | Ctrl+PageUp
-vestra.marks | marks.next-chapter | Playback ▸ Chapters and Bookmarks ▸ Next Chapter | Ctrl+PageDown
-vestra.marks | marks.seekbar | Playback ▸ Chapters and Bookmarks ▸ Show Marks on Seek Bar
-vestra.marks | ab.set-a | Playback ▸ A-B Loop ▸ Set Start Point | [
-vestra.marks | ab.clear-a | Playback ▸ A-B Loop ▸ Clear Start Point | {
-vestra.marks | ab.a-back | Playback ▸ A-B Loop ▸ Start Point Back 0.1 s | Ctrl+[
-vestra.marks | ab.a-forward | Playback ▸ A-B Loop ▸ Start Point Forward 0.1 s | Alt+[
-vestra.marks | ab.set-b | Playback ▸ A-B Loop ▸ Set End Point | ]
-vestra.marks | ab.clear-b | Playback ▸ A-B Loop ▸ Clear End Point | }
-vestra.marks | ab.b-back | Playback ▸ A-B Loop ▸ End Point Back 0.1 s | Ctrl+]
-vestra.marks | ab.b-forward | Playback ▸ A-B Loop ▸ End Point Forward 0.1 s | Alt+]
-vestra.marks | ab.back | Playback ▸ A-B Loop ▸ Move Range Back 0.1 s | Ctrl+Alt+[
-vestra.marks | ab.forward | Playback ▸ A-B Loop ▸ Move Range Forward 0.1 s | Ctrl+Alt+]
-vestra.marks | ab.segment | Playback ▸ A-B Loop ▸ Loop Current Chapter or Bookmark Range | Alt+\\
-vestra.marks | ab.toggle | Playback ▸ A-B Loop ▸ A-B Loop On/Off | \\
-vestra.marks | ab.count.endless | Playback ▸ A-B Loop ▸ Loop Count ▸ Endless
-vestra.marks | ab.count.1 | Playback ▸ A-B Loop ▸ Loop Count ▸ Once
-vestra.marks | ab.count.2 | Playback ▸ A-B Loop ▸ Loop Count ▸ 2 Times
-vestra.marks | ab.count.3 | Playback ▸ A-B Loop ▸ Loop Count ▸ 3 Times
-vestra.marks | ab.count.5 | Playback ▸ A-B Loop ▸ Loop Count ▸ 5 Times
-vestra.marks | ab.count.10 | Playback ▸ A-B Loop ▸ Loop Count ▸ 10 Times
-vestra.subtitle-online | search | Subtitles ▸ Online Subtitles ▸ Search and Download Subtitles…
-vestra.subtitle-online | settings | Subtitles ▸ Online Subtitles ▸ Online Subtitle Settings…
-vestra.subtitles | track-off | Subtitle Track ▸ Off
-vestra.capture | capture.save | Video ▸ Snapshot ▸ Save Current Frame | Ctrl+E
-vestra.capture | capture.panel | Video ▸ Snapshot ▸ Capture… | Alt+S
-vestra.capture | capture.copy | Video ▸ Snapshot ▸ Copy Current Frame | Ctrl+C
-vestra.capture | capture.burst | Video ▸ Snapshot ▸ Burst… | Ctrl+G
-vestra.capture | capture.clip | Video ▸ Snapshot ▸ Export Clip…
-host | volume-up | Audio ▸ Volume + | ArrowUp, Mouse:WheelUp
-host | volume-down | Audio ▸ Volume − | ArrowDown, Mouse:WheelDown
-host | mute | Audio ▸ Mute | M
-vestra.visualizer | audio-cover | Audio ▸ Show Album Cover for Audio Only
+host | play-pause | Play/Pause | Space, Mouse:LeftClick
 vestra.audio | audio.track.none | Audio Track ▸ No Audio Tracks
-host | fullscreen | Toggle Fullscreen | Escape
-vestra.window | pip | Screen ▸ Picture-in-Picture
-vestra.window | mini | Screen ▸ Mini Size | \`
-vestra.window | size.0.5 | Screen ▸ 0.5× | 1
-vestra.window | size.1 | Screen ▸ 1× | 2
-vestra.window | size.1.5 | Screen ▸ 1.5× | 3
-vestra.window | size.2 | Screen ▸ 2× | 4
-vestra.window | fit | Screen ▸ Fit to Video Aspect Ratio | 8
-vestra.window | auto.off | Screen ▸ When Playback Starts ▸ Don't Resize
-vestra.window | auto.0.5 | Screen ▸ When Playback Starts ▸ 0.5×
-vestra.window | auto.1 | Screen ▸ When Playback Starts ▸ 1×
-vestra.window | auto.1.5 | Screen ▸ When Playback Starts ▸ 1.5×
-vestra.window | auto.2 | Screen ▸ When Playback Starts ▸ 2×
-vestra.window | auto.fit | Screen ▸ When Playback Starts ▸ Fit to Video Aspect Ratio
-vestra.window | auto.once | Screen ▸ When Playback Starts ▸ Only Once
-vestra.window | top.cycle | Screen ▸ Always on Top ▸ Cycle Mode | Ctrl+T
-vestra.window | top.never | Screen ▸ Always on Top ▸ Never
-vestra.window | top.always | Screen ▸ Always on Top ▸ Always
-vestra.window | top.playing | Screen ▸ Always on Top ▸ While Playing
-vestra.window | top.fullscreen | Screen ▸ Always on Top ▸ While Playing in Fullscreen
+vestra.subtitles | track-off | Subtitle Track ▸ Off
+vestra.capture | capture.save | Snapshot ▸ Save Current Frame | Ctrl+E
+vestra.capture | capture.copy | Snapshot ▸ Copy Current Frame | Ctrl+C
+vestra.capture | capture.burst | Snapshot ▸ Burst… | Ctrl+G
+vestra.capture | capture.clip | Snapshot ▸ Export Clip…
+vestra.capture | capture.panel | Snapshot ▸ Capture… | Alt+S
 vestra.video | video.picture | Picture… | Alt+1
 vestra.audio | audio.workbench | Audio… | Alt+2
 vestra.subtitles | tune | Subtitles… | Alt+3
 vestra.playback | panel | Playback… | Alt+4
 vestra.playlist | playlist.visibility | Playlist | F6
-vestra.info | info.toggle | Playback Info | Tab
-vestra.info | info.properties | Playback Properties… | Ctrl+F1
+vestra.marks | marks.list | Chapter and Bookmark List… | H
+host | fullscreen | Toggle Fullscreen | Escape
 vestra.workshop | workshop.open | Vestra Player AI…
 vestra.store | open | Plugin Store…
-vestra.preferences | options | Settings ▸ Options… | F5
-vestra.hotkeys | keys | Settings ▸ Keyboard Shortcuts…
-vestra.hotkeys | mouse | Settings ▸ Mouse…
-vestra.hotkeys | ignore-defaults | Settings ▸ Ignore Default Shortcuts
-vestra.preferences | theme.vestra | Settings ▸ Appearance ▸ Vestra Dark
-vestra.preferences | theme.vestra-light | Settings ▸ Appearance ▸ Vestra Light
-vestra.visualizer | idle-logo | Settings ▸ Appearance ▸ Show Logo When Idle
-vestra.visualizer | choose-logo | Settings ▸ Appearance ▸ Choose Logo Image…
-vestra.preferences | language.system | Settings ▸ Language ▸ Follow System
-vestra.preferences | language.en | Settings ▸ Language ▸ English
-vestra.preferences | language.zh-Hans | Settings ▸ Language ▸ 简体中文
-vestra.preferences | language.ja | Settings ▸ Language ▸ 日本語
-vestra.preferences | language.ko | Settings ▸ Language ▸ 한국어
-vestra.preferences | language.de | Settings ▸ Language ▸ Deutsch
-vestra.preferences | language.fr | Settings ▸ Language ▸ Français
-vestra.preferences | language.es | Settings ▸ Language ▸ Español
-vestra.visualizer | reset-logo | Reset ▸ Idle Logo
+host | palette | Command Palette… | Ctrl+Shift+P
+vestra.preferences | options | Options… | F5
 vestra.info | info.about | About Vestra Player… | F1
-vestra.info | info.update | Check for Updates…
 host | quit | Quit | Cmd+Q
+host | previous | (Previous) | PageUp, Mouse:X2
+host | next | (Next) | PageDown, Mouse:X1
 host | enter-fullscreen | (Enter Fullscreen)
 host | exit-fullscreen | (Leave Fullscreen)
 host | sidebar | (Toggle Sidebar)
-host | palette | (Command Palette) | Ctrl+Shift+P
 host | adjust | (Adjust)
+host | volume-up | (Volume +) | ArrowUp, Mouse:WheelUp
+host | volume-down | (Volume −) | ArrowDown, Mouse:WheelDown
+host | mute | (Mute) | M
 host | frame-back | (Previous Frame) | D
 host | frame-forward | (Next Frame) | F
 host | seek-backward | (Back 5 s) | ArrowLeft
@@ -430,6 +316,98 @@ host | seek-forward | (Forward 5 s) | ArrowRight
 host | rate-normal | (Normal) | Z
 host | rate-down | (Slower 0.1) | X
 host | rate-up | (Faster 0.1) | C
+vestra.playback | reopen | (Reopen Current/Last File) | Ctrl+Y
+vestra.playback | copy-name | (File Name)
+vestra.playback | copy-folder | (Folder Path)
+vestra.playback | copy-path | (Full Path)
+vestra.playback | prevent-sleep | (Disable Screen Saver While Playing)
+vestra.playback | hover-time | (Show Time on Seek Bar Hover)
+vestra.playback | hover-thumbnail | (Show Thumbnail on Seek Bar Hover)
+vestra.window | hide-cursor | (Hide Pointer While Playing)
+vestra.window | pip | (Picture-in-Picture)
+vestra.window | mini | (Mini Size) | \`
+vestra.window | size.0.5 | (0.5×) | 1
+vestra.window | size.1 | (1×) | 2
+vestra.window | size.1.5 | (1.5×) | 3
+vestra.window | size.2 | (2×) | 4
+vestra.window | fit | (Fit to Video Aspect Ratio) | 8
+vestra.window | auto.off | (Don't Resize)
+vestra.window | auto.0.5 | (0.5×)
+vestra.window | auto.1 | (1×)
+vestra.window | auto.1.5 | (1.5×)
+vestra.window | auto.2 | (2×)
+vestra.window | auto.fit | (Fit to Video Aspect Ratio)
+vestra.window | auto.once | (Only Once)
+vestra.window | top.cycle | (Cycle Mode) | Ctrl+T
+vestra.window | top.never | (Never)
+vestra.window | top.always | (Always)
+vestra.window | top.playing | (While Playing)
+vestra.window | top.fullscreen | (While Playing in Fullscreen)
+vestra.playlist | playlist.add | (Add Files…)
+vestra.playlist | playlist.link | (Add Link…)
+vestra.playlist | playlist.add-folder | (Add Folder…)
+vestra.playlist | playlist.repeat-none | (Off)
+vestra.playlist | playlist.repeat-all | (All)
+vestra.playlist | playlist.repeat-one | (One)
+vestra.playlist | playlist.shuffle | (Shuffle)
+vestra.playlist | playlist.open-list | (Open List File…)
+vestra.playlist | playlist.save-list | (Save List…)
+vestra.playlist | playlist.open-mode-only | (Open Only That File)
+vestra.playlist | playlist.open-mode-similar | (Add Similar Files)
+vestra.playlist | playlist.open-mode-folder | (Add All Files in the Folder)
+vestra.playlist | playlist.fast-advance | (Fast Advance to Next)
+vestra.playlist | playlist.remember | (Remember List)
+vestra.playlist | playlist.confirm-clear | (Confirm Before Removing All)
+vestra.history | resume.off | (Don't Resume)
+vestra.history | resume.auto | (Resume Automatically)
+vestra.history | resume.ask | (Ask Every Time)
+vestra.history | resume.audio | (Also Remember Audio Files)
+vestra.history | resume.clear | (Clear All Saved Positions)
+vestra.marks | marks.add | (Add Bookmark) | P
+vestra.marks | marks.previous | (Previous Bookmark or Chapter) | Shift+PageUp
+vestra.marks | marks.next | (Next Bookmark or Chapter) | Shift+PageDown
+vestra.marks | marks.previous-chapter | (Previous Chapter) | Ctrl+PageUp
+vestra.marks | marks.next-chapter | (Next Chapter) | Ctrl+PageDown
+vestra.marks | marks.seekbar | (Show Marks on Seek Bar)
+vestra.marks | ab.set-a | (Set Start Point) | [
+vestra.marks | ab.clear-a | (Clear Start Point) | {
+vestra.marks | ab.a-back | (Start Point Back 0.1 s) | Ctrl+[
+vestra.marks | ab.a-forward | (Start Point Forward 0.1 s) | Alt+[
+vestra.marks | ab.set-b | (Set End Point) | ]
+vestra.marks | ab.clear-b | (Clear End Point) | }
+vestra.marks | ab.b-back | (End Point Back 0.1 s) | Ctrl+]
+vestra.marks | ab.b-forward | (End Point Forward 0.1 s) | Alt+]
+vestra.marks | ab.back | (Move Range Back 0.1 s) | Ctrl+Alt+[
+vestra.marks | ab.forward | (Move Range Forward 0.1 s) | Ctrl+Alt+]
+vestra.marks | ab.segment | (Loop Current Chapter or Bookmark Range) | Alt+\\
+vestra.marks | ab.toggle | (A-B Loop On/Off) | \\
+vestra.marks | ab.count.endless | (Endless)
+vestra.marks | ab.count.1 | (Once)
+vestra.marks | ab.count.2 | (2 Times)
+vestra.marks | ab.count.3 | (3 Times)
+vestra.marks | ab.count.5 | (5 Times)
+vestra.marks | ab.count.10 | (10 Times)
+vestra.subtitle-online | settings | (Online Subtitle Settings…)
+vestra.visualizer | audio-cover | (Show Album Cover for Audio Only)
+vestra.visualizer | idle-logo | (Show Logo When Idle)
+vestra.visualizer | choose-logo | (Choose Logo Image…)
+vestra.visualizer | reset-logo | (Idle Logo)
+vestra.hotkeys | keys | (Keyboard Shortcuts…)
+vestra.hotkeys | mouse | (Mouse…)
+vestra.hotkeys | ignore-defaults | (Ignore Default Shortcuts)
+vestra.preferences | theme.vestra | (Vestra Dark)
+vestra.preferences | theme.vestra-light | (Vestra Light)
+vestra.preferences | language.system | (Follow System)
+vestra.preferences | language.en | (English)
+vestra.preferences | language.zh-Hans | (简体中文)
+vestra.preferences | language.ja | (日本語)
+vestra.preferences | language.ko | (한국어)
+vestra.preferences | language.de | (Deutsch)
+vestra.preferences | language.fr | (Français)
+vestra.preferences | language.es | (Español)
+vestra.info | info.toggle | (Playback Info) | Tab
+vestra.info | info.properties | (Playback Properties…) | Ctrl+F1
+vestra.info | info.update | (Check for Updates…)
 vestra.audio | audio.track.cycle | (Cycle Tracks) | Alt+A
 vestra.audio | audio.channels.stereo | (Stereo)
 vestra.audio | audio.channels.left | (Left Channel)

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>;