@vestra-player/sdk 1.5.46 → 1.5.47

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.5.47
+
+**Who must change: nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability, no player version needed. The built-in command table follows player 0.6.0's new default keys: a plugin whose documentation or tests list the player's default keys (from `BUILTIN_COMMANDS`, or Escape, Enter, F11 and the side mouse buttons by hand) should update them.
+
+- **Player 0.6.0 default keys** (`BUILTIN_COMMANDS`, the generated key tables, `HostAction`): **Toggle Fullscreen** (`host/fullscreen`) is `Escape` only (up to 0.5.x `Enter`, `Alt+Enter`, `F11`); **Leave Fullscreen** (`host/exit-fullscreen`) has no default key (up to 0.5.x `Escape`); the new **Enter Fullscreen** (`host/enter-fullscreen`) has no default key and no menu row and is enabled only when windowed (Leave Fullscreen only in fullscreen); **Previous** is `PageUp`, `Mouse:X2` and **Next** `PageDown`, `Mouse:X1` (the side buttons swapped: back is next, forward is previous). The side buttons now fire anywhere in the main window or the floating sidebar window, except while a menu is open, not only over the video. `host.run` takes the same actions as before (`fullscreen` toggles). `TestHost`'s core actions use the new Previous / Next bindings.
+- **Rows that cannot change are not encoded again.** An update pass encodes every row of a bound array to find the changed ones; in a 20,000-row list that was about 40% of a click. A deep-frozen row (`Object.freeze` on it and on everything inside it: plain objects and arrays, no getters, no own `toJSON`; image and document handles allowed: they are immutable, their wire form is fixed when made, so they need no freezing) that the bind function returns again is now encoded once more and then taken from a cache kept by the row object (weakly: a row the plugin drops goes with its entry), with its limit counts. Rows that are not frozen, or hold a mutable part, are encoded on every pass as before, so changes made in place are still sent. To benefit, keep an unchanged row as the same frozen object and make a new one when it changes ([Arrays: only the changed rows are sent](docs/explanation/ui.md#arrays-only-the-changed-rows-are-sent)). Measured in the test host with the playlist at 20,000 rows memoized that way: a click from about 24 ms to about 14 ms to the rows write.
+- _Commands, menus and key bindings_: the example of a disabled command letting its key go no longer uses Escape on Leave Fullscreen.
+
 ## 1.5.46
 
 **Who must change: nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability. The new limits and the split writes take effect with player 0.6.0 (large lists P3); with older players arrays are sent whole as before and the old limits apply there. **A plugin that binds a whole long list depends on them: set `"minPlayerVersion": "0.6.0"`.**

package/dist/commands.js

@@ -265,8 +265,8 @@ 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:X1
-host | next | Playback ▸ Next | PageDown, Mouse:X2
+host | previous | Playback ▸ Previous | PageUp, Mouse:X2
+host | next | Playback ▸ Next | PageDown, Mouse:X1
 host | frame-back | Playback ▸ Seek ▸ Previous Frame | D
 host | frame-forward | Playback ▸ Seek ▸ Next Frame | F
 vestra.playback | keyframe-back | Playback ▸ Seek ▸ Previous Keyframe | Ctrl+Shift+ArrowLeft
@@ -492,7 +492,7 @@ vestra.audio | audio.normalize | Audio ▸ Processing ▸ Normalize | Shift+N
 vestra.audio | audio.clarity | Audio ▸ Processing ▸ Crystalizer | Shift+C
 vestra.audio | audio.reset | Audio ▸ Reset
 vestra.visualizer | audio-cover | Audio ▸ Show Album Cover for Audio Only
-host | fullscreen | Toggle Fullscreen | Enter, Alt+Enter, F11
+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
@@ -536,7 +536,8 @@ vestra.preferences | language.fr | Settings ▸ Language ▸ Français
 vestra.preferences | language.es | Settings ▸ Language ▸ Español
 vestra.info | info.about | About Vestra Player… | F1
 host | quit | Quit | Cmd+Q
-host | exit-fullscreen | (Leave Fullscreen) | Escape
+host | enter-fullscreen | (Enter Fullscreen)
+host | exit-fullscreen | (Leave Fullscreen)
 host | sidebar | (Toggle Sidebar)
 vestra.info | info.brief | (Brief Info) | Shift+Tab
 vestra.playlist | playlist.play | (Play) | Enter, P | panel

package/dist/plugin/bindings.d.ts

@@ -66,8 +66,11 @@ export declare const BINDING_INPUTS: Readonly<{
      */
     readonly named: readonly ["Space", "Enter", "Tab", "Escape", "Backspace", "Delete", "Insert", "Home", "End", "PageUp", "PageDown", "ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Plus", ...string[], "NumpadPlus", "NumpadMinus", "NumpadMultiply", "NumpadDivide", "NumpadEnter", "NumpadDecimal"];
     /**
-     * Mouse inputs on the video area. `:LeftHalf` and `:RightHalf` tell the
-     * halves of the video apart for a double click.
+     * Mouse inputs on the video area; the side buttons `Mouse:X1` (back) and
+     * `Mouse:X2` (forward) anywhere in the main window or the floating sidebar
+     * window, except while a menu is open (player 0.6.0).
+     * `:LeftHalf` and `:RightHalf` tell the halves of the video apart for a
+     * double click.
      */
     readonly mouse: readonly ["Mouse:LeftClick", "Mouse:LeftDoubleClick", "Mouse:LeftDoubleClick:LeftHalf", "Mouse:LeftDoubleClick:RightHalf", "Mouse:MiddleClick", "Mouse:X1", "Mouse:X2", "Mouse:WheelUp", "Mouse:WheelDown", "Mouse:WheelLeft", "Mouse:WheelRight"];
 }>;

package/dist/plugin/bindings.js

@@ -97,8 +97,11 @@ export const BINDING_INPUTS = Object.freeze({
         "NumpadDecimal",
     ],
     /**
-     * Mouse inputs on the video area. `:LeftHalf` and `:RightHalf` tell the
-     * halves of the video apart for a double click.
+     * Mouse inputs on the video area; the side buttons `Mouse:X1` (back) and
+     * `Mouse:X2` (forward) anywhere in the main window or the floating sidebar
+     * window, except while a menu is open (player 0.6.0).
+     * `:LeftHalf` and `:RightHalf` tell the halves of the video apart for a
+     * double click.
      */
     mouse: [
         "Mouse:LeftClick",

package/dist/plugin/testing.js

@@ -2254,7 +2254,7 @@ export class TestHost {
                 ["Playback", "Previous"],
                 202,
                 "domain",
-                ["PageUp", "Mouse:X1"],
+                ["PageUp", "Mouse:X2"],
                 false,
             ],
             [
@@ -2262,7 +2262,7 @@ export class TestHost {
                 ["Playback", "Next"],
                 203,
                 "domain",
-                ["PageDown", "Mouse:X2"],
+                ["PageDown", "Mouse:X1"],
                 false,
             ],
             [
@@ -4248,7 +4248,7 @@ export class TestHost {
                     throw new HostError("invalid", "seconds must be 0.1..3600 in tenths");
                 seconds = p.seconds;
             }
-            // SDK 1.5.21: the main window's Toggle Fullscreen, like Enter: in when
+            // SDK 1.5.21: the main window's Toggle Fullscreen, like Escape: in when
             // windowed, out when fullscreen, then `window.state`.
             if (p.action === "fullscreen") {
                 this.coreRuns.push("fullscreen");

package/dist/plugin/types.d.ts

@@ -999,9 +999,12 @@ export interface CommandOptions {
      * `Home`, `End`, `PageUp`, `PageDown`, `ArrowLeft`/`Right`/`Up`/`Down`,
      * `Plus`, any other single symbol as typed (`">"`, not `"Shift+."`),
      * `Numpad0`–`Numpad9`, `NumpadPlus`, `NumpadMinus`, `NumpadMultiply`,
-     * `NumpadDivide`, `NumpadEnter`, `NumpadDecimal`, and the video-area mouse
+     * `NumpadDivide`, `NumpadEnter`, `NumpadDecimal`, the video-area mouse
      * inputs `Mouse:LeftClick`, `Mouse:LeftDoubleClick[:LeftHalf|:RightHalf]`,
-     * `Mouse:MiddleClick`, `Mouse:X1`, `Mouse:X2`, `Mouse:WheelUp`/`Down`/`Left`/`Right`.
+     * `Mouse:MiddleClick`, `Mouse:WheelUp`/`Down`/`Left`/`Right`, and the side
+     * buttons `Mouse:X1` (back), `Mouse:X2` (forward), from 0.6.0 on anywhere
+     * in the main window or the floating sidebar window, except while a menu
+     * is open.
      *
      * Platforms: on macOS `Ctrl+X` fires for both ⌃X and ⌘X while `Cmd+X`
      * means ⌘X only; on Windows `Cmd` is the Windows logo key, so write
@@ -6061,13 +6064,13 @@ export interface Player {
  * | --- | --- | --- |
  * | `stop` | F4 | close the source |
  * | `play-pause` | Space, a left click on the video (player 0.5.2) | pause / resume, replay after the end |
- * | `previous` / `next` | PageUp, Mouse:X1 / PageDown, Mouse:X2 | ask the sequence provider |
+ * | `previous` / `next` | PageUp, Mouse:X2 / PageDown, Mouse:X1 (from 0.6.0; up to 0.5.x X1 was previous and X2 next) | ask the sequence provider |
  * | `frame-back` / `frame-forward` | D / F | `player.step("frame", …)` |
  * | `seek-backward` / `seek-forward` | ← / → | relative seek by `setStepSeek` seconds (or `host.run`'s `seconds`), exact or to keyframes as `setStepSeek` says |
  * | `rate-normal`, `rate-down`, `rate-up` | Z, X, C | 1×, ±0.1 within 0.25–4 |
  * | `volume-up` / `volume-down` | ↑ / ↓, wheel | ±5 (`volume-up` stops at 100) |
  * | `mute` | M | toggle mute |
- * | `fullscreen` | Enter, Alt+Enter, F11 | toggle the main window's fullscreen: enter it when windowed, leave it when fullscreen, as the Toggle Fullscreen command does (SDK 1.5.21, player 0.5.2; `unavailable` when the player has no window) |
+ * | `fullscreen` | Escape (from 0.6.0; up to 0.5.x Enter, Alt+Enter, F11) | toggle the main window's fullscreen: enter it when windowed, leave it when fullscreen, as the Toggle Fullscreen command does (SDK 1.5.21, player 0.5.2; `unavailable` when the player has no window) |
  *
  * In the binding overlay their keys are `host/<action>`. `fullscreen`
  * changes no playback state: read the result from `window.state.fullscreen`

package/dist/plugin/ui.js

@@ -83,8 +83,113 @@ const isPrimitive = (value) => value === null ||
     (typeof value === "number" && Number.isFinite(value));
 /** A row as `JSON.stringify` writes it inside an array. */
 const encodeRow = (row) => JSON.stringify(row) ?? "null";
+/** What a row's encoding holds: a Markdown document, an image. */
+const HAS_MARKDOWN = 1;
+const HAS_IMAGE = 2;
+const marksOf = (enc) => (enc.includes('"$vestraMarkdown"') ? HAS_MARKDOWN : 0) |
+    (enc.includes('"$vestraImage"') ? HAS_IMAGE : 0);
+/**
+ * Row encodings by row object, shared by every property (a row's JSON does
+ * not depend on where it is bound). Only rows that cannot change are kept
+ * ({@link settled}): a plugin that mutates its rows in place sees no
+ * difference, and one that keeps unchanged rows as the same deep-frozen
+ * objects skips encoding them on every pass. Weak: a row the plugin drops
+ * goes with its entry.
+ */
+const settledRows = new WeakMap();
+/**
+ * Frozen rows seen once. A frozen row is verified and kept on its second
+ * pass, so rows frozen afresh on every pass cost one set entry, not a
+ * verification each.
+ */
+const seenRows = new WeakSet();
+/** Frozen rows that can still change (a mutable part, a getter): never kept. */
+const unsettledRows = new WeakSet();
+/**
+ * `value` can never change what `JSON.stringify` writes for it: a primitive,
+ * an image or document handle (their wire form is fixed when made), or a
+ * frozen plain object or array whose own enumerable properties are data
+ * properties (no getter, no own `toJSON`) holding such values. Freezing
+ * fixes the properties and the prototype for good, so the answer holds as
+ * long as the object lives.
+ */
+function settled(value, depth) {
+    if (value === null || typeof value !== "object")
+        return typeof value !== "function";
+    if (value instanceof ImageHandle || value instanceof MarkdownHandle)
+        return true;
+    if (depth > UI_VALUE_LIMITS.depth || !Object.isFrozen(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    if (Array.isArray(value)
+        ? proto !== Array.prototype
+        : proto !== Object.prototype && proto !== null)
+        return false;
+    // An own `toJSON`, enumerable or not, is called by `JSON.stringify`.
+    if (Object.prototype.hasOwnProperty.call(value, "toJSON"))
+        return false;
+    for (const key of Object.keys(value)) {
+        const property = Object.getOwnPropertyDescriptor(value, key);
+        if (!property || !("value" in property))
+            return false;
+        if (!settled(property.value, depth + 1))
+            return false;
+    }
+    return true;
+}
+/** A row's encoding and marks, from {@link settledRows} when it is kept. */
+function rowEncoding(row, cache) {
+    if (cache && row !== null && typeof row === "object") {
+        // A kept row is frozen: looked up first, `isFrozen` only on a miss.
+        const kept = settledRows.get(row);
+        if (kept)
+            return kept;
+    }
+    if (cache &&
+        row !== null &&
+        typeof row === "object" &&
+        Object.isFrozen(row)) {
+        const enc = encodeRow(row);
+        const entry = { enc, marks: marksOf(enc) };
+        if (!seenRows.has(row))
+            seenRows.add(row);
+        else if (!unsettledRows.has(row)) {
+            if (settled(row, 1))
+                settledRows.set(row, entry);
+            else
+                unsettledRows.add(row);
+        }
+        return entry;
+    }
+    const enc = encodeRow(row);
+    return { enc, marks: marksOf(enc) };
+}
 /** Each row of an array as `JSON.stringify` writes it; a hole is `null`. */
-const encodeRows = (rows) => Array.from(rows, encodeRow);
+function encodeRows(rows) {
+    // A `toJSON` added to the shared prototypes would change any row's JSON:
+    // then nothing is taken from (or kept in) the cache.
+    const cache = !("toJSON" in Object.prototype) && !("toJSON" in Array.prototype);
+    const enc = [];
+    const marks = new Uint8Array(rows.length);
+    let markdown = false;
+    for (let i = 0; i < rows.length; i++) {
+        const row = rowEncoding(rows[i], cache);
+        enc[i] = row.enc;
+        marks[i] = row.marks;
+        if (row.marks & HAS_MARKDOWN)
+            markdown = true;
+    }
+    return { enc, marks, markdown, cache };
+}
+/** A row's limit counts, kept with its encoding when the row cannot change. */
+function rowCount(row, cache) {
+    const kept = cache && row !== null && typeof row === "object"
+        ? settledRows.get(row)
+        : undefined;
+    if (!kept)
+        return countRow(row);
+    return (kept.count ??= countRow(row));
+}
 function sameRows(a, b) {
     if (a.length !== b.length)
         return false;
@@ -102,7 +207,7 @@ function sentOf(value, patches) {
         return {
             kind: "rows",
             rows: {
-                enc: encodeRows(value),
+                enc: encodeRows(value).enc,
                 field: keyed?.field ?? null,
                 keys: keyed?.keys ?? null,
                 counts: [],
@@ -142,7 +247,7 @@ function tooLarge(key, ops) {
 function rowPatch(sent, next, rows) {
     if (sent.enc.length === 0)
         return null;
-    if (next.enc.some((row) => row.includes('"$vestraMarkdown"')))
+    if (next.markdown)
         return null;
     const nextKeyed = sent.field === null ? null : next.keyed();
     const keyed = nextKeyed !== null && nextKeyed.field === sent.field;
@@ -152,11 +257,12 @@ function rowPatch(sent, next, rows) {
     // A released image is refused wherever it is, as in a whole write: the
     // rows the patch does not carry are checked too (those holding images).
     for (let j = 0; j < rows.length; j++)
-        if (plan.from[j] >= 0 && next.enc[j].includes('"$vestraImage"'))
+        if (plan.from[j] >= 0 && next.marks[j] & HAS_IMAGE)
             wireValue(rows[j] ?? null);
     const counts = next.enc.map((_, j) => {
         const from = plan.from[j];
-        return (from >= 0 ? sent.counts[from] : undefined) ?? countRow(rows[j]);
+        return ((from >= 0 ? sent.counts[from] : undefined) ??
+            rowCount(rows[j], next.cache));
     });
     if (!withinLimits(counts))
         return null;
@@ -372,8 +478,10 @@ export class ViewBase {
         }
         if (Array.isArray(value) && this.#patches) {
             // Row by row: the same work as one `JSON.stringify`, and the rows to
-            // diff against those last sent.
-            const enc = encodeRows(value);
+            // diff against those last sent. Rows that cannot change (deep-frozen
+            // objects bound again, SDK 1.5.47) are taken from `settledRows`.
+            const encoded = encodeRows(value);
+            const { enc } = encoded;
             const signature = () => `[${enc.join(",")}]`;
             const changed = sent?.kind === "rows"
                 ? !sameRows(sent.rows.enc, enc)
@@ -386,7 +494,7 @@ export class ViewBase {
                 value,
                 changed,
                 signature,
-                rows: { enc, keyed },
+                rows: { ...encoded, keyed },
                 sent: (counts = []) => ({
                     kind: "rows",
                     rows: {
@@ -470,9 +578,7 @@ export class ViewBase {
         const seq = ++this.#seq;
         // Rows holding Markdown documents go whole, as before: the player
         // merges documents in place and takes no parts of them.
-        if (Array.isArray(value) &&
-            pending.rows &&
-            !pending.rows.enc.some((row) => row.includes(MARKDOWN_KEY))) {
+        if (Array.isArray(value) && pending.rows && !pending.rows.markdown) {
             const sizes = pending.rows.enc.map(jsonBytes);
             const count = prefixWithin(sizes, CHUNK_BYTES);
             if (count < value.length) {

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.46: full reference
+# @vestra-player/sdk 1.5.47: 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.
 
@@ -2630,8 +2630,8 @@ Every command the player (`host`) and its built-in plugins register when the pla
 | Copy to Clipboard ▸ Folder Path |  | `vestra.playback/copy-folder` |
 | Copy to Clipboard ▸ Full Path |  | `vestra.playback/copy-path` |
 | Playback ▸ Play/Pause | `Space`, `Mouse:LeftClick` | `host/play-pause` |
-| Playback ▸ Previous | `PageUp`, `Mouse:X1` | `host/previous` |
-| Playback ▸ Next | `PageDown`, `Mouse:X2` | `host/next` |
+| Playback ▸ Previous | `PageUp`, `Mouse:X2` | `host/previous` |
+| Playback ▸ Next | `PageDown`, `Mouse:X1` | `host/next` |
 | Playback ▸ Seek ▸ Previous Frame | `D` | `host/frame-back` |
 | Playback ▸ Seek ▸ Next Frame | `F` | `host/frame-forward` |
 | Playback ▸ Seek ▸ Previous Keyframe | `Ctrl+Shift+ArrowLeft` | `vestra.playback/keyframe-back` |
@@ -2857,7 +2857,7 @@ Every command the player (`host`) and its built-in plugins register when the pla
 | Audio ▸ Processing ▸ Crystalizer | `Shift+C` | `vestra.audio/audio.clarity` |
 | Audio ▸ Reset |  | `vestra.audio/audio.reset` |
 | Audio ▸ Show Album Cover for Audio Only |  | `vestra.visualizer/audio-cover` |
-| Toggle Fullscreen | `Enter`, `Alt+Enter`, `F11` | `host/fullscreen` |
+| Toggle Fullscreen | `Escape` | `host/fullscreen` |
 | Screen ▸ Picture-in-Picture |  | `vestra.window/pip` |
 | Screen ▸ Mini Size | ``` | `vestra.window/mini` |
 | Screen ▸ 0.5× | `1` | `vestra.window/size.0.5` |
@@ -2901,7 +2901,8 @@ Every command the player (`host`) and its built-in plugins register when the pla
 | Settings ▸ Language ▸ Español |  | `vestra.preferences/language.es` |
 | About Vestra Player… | `F1` | `vestra.info/info.about` |
 | Quit | `Cmd+Q` | `host/quit` |
-| Leave Fullscreen (not in the menu) | `Escape` | `host/exit-fullscreen` |
+| Enter Fullscreen (not in the menu) |  | `host/enter-fullscreen` |
+| Leave Fullscreen (not in the menu) |  | `host/exit-fullscreen` |
 | Toggle Sidebar (not in the menu) |  | `host/sidebar` |
 | Brief Info (not in the menu) | `Shift+Tab` | `vestra.info/info.brief` |
 | Play (not in the menu) | `Enter`, `P` (panel focus) | `vestra.playlist/playlist.play` |
@@ -2979,7 +2980,7 @@ A menu item shows the first of its keyboard bindings that is in effect.
 | `digits` | `0`–`9` | Digit keys of the main keyboard: `0` to `9`. |
 | `functionKeys` | `F1`–`F24` | Function keys: `F1` to `F24`. |
 | `named` | `Space`, `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `Insert`, `Home`, `End`, `PageUp`, `PageDown`, `ArrowLeft`, `ArrowRight`, `ArrowUp`, `ArrowDown`, `Plus`, `Numpad0`, `Numpad1`, `Numpad2`, `Numpad3`, `Numpad4`, `Numpad5`, `Numpad6`, `Numpad7`, `Numpad8`, `Numpad9`, `NumpadPlus`, `NumpadMinus`, `NumpadMultiply`, `NumpadDivide`, `NumpadEnter`, `NumpadDecimal` | Other named keys, matched by the physical key. `Plus` is the `+` key however it is typed; the `Numpad…` names are the numeric keypad only, never the main keyboard. |
-| `mouse` | `Mouse:LeftClick`, `Mouse:LeftDoubleClick`, `Mouse:LeftDoubleClick:LeftHalf`, `Mouse:LeftDoubleClick:RightHalf`, `Mouse:MiddleClick`, `Mouse:X1`, `Mouse:X2`, `Mouse:WheelUp`, `Mouse:WheelDown`, `Mouse:WheelLeft`, `Mouse:WheelRight` | Mouse inputs on the video area. `:LeftHalf` and `:RightHalf` tell the halves of the video apart for a double click. |
+| `mouse` | `Mouse:LeftClick`, `Mouse:LeftDoubleClick`, `Mouse:LeftDoubleClick:LeftHalf`, `Mouse:LeftDoubleClick:RightHalf`, `Mouse:MiddleClick`, `Mouse:X1`, `Mouse:X2`, `Mouse:WheelUp`, `Mouse:WheelDown`, `Mouse:WheelLeft`, `Mouse:WheelRight` | Mouse inputs on the video area; the side buttons `Mouse:X1` (back) and `Mouse:X2` (forward) anywhere in the main window or the floating sidebar window, except while a menu is open (player 0.6.0). `:LeftHalf` and `:RightHalf` tell the halves of the video apart for a double click. |
 
 #### Core actions
 
@@ -2989,8 +2990,8 @@ The player's own playback commands, which plugin.host.run runs by id (capability
 | --- | --- | --- |
 | `stop` | Close | `F4` |
 | `play-pause` | Playback ▸ Play/Pause | `Space`, `Mouse:LeftClick` |
-| `previous` | Playback ▸ Previous | `PageUp`, `Mouse:X1` |
-| `next` | Playback ▸ Next | `PageDown`, `Mouse:X2` |
+| `previous` | Playback ▸ Previous | `PageUp`, `Mouse:X2` |
+| `next` | Playback ▸ Next | `PageDown`, `Mouse:X1` |
 | `frame-back` | Playback ▸ Seek ▸ Previous Frame | `D` |
 | `frame-forward` | Playback ▸ Seek ▸ Next Frame | `F` |
 | `seek-backward` | Playback ▸ Seek ▸ Back 5 s | `ArrowLeft` |
@@ -3001,9 +3002,9 @@ The player's own playback commands, which plugin.host.run runs by id (capability
 | `volume-up` | Audio ▸ Volume + | `ArrowUp`, `Mouse:WheelUp` |
 | `volume-down` | Audio ▸ Volume − | `ArrowDown`, `Mouse:WheelDown` |
 | `mute` | Audio ▸ Mute | `M` |
-| `fullscreen` | Toggle Fullscreen | `Enter`, `Alt+Enter`, `F11` |
+| `fullscreen` | Toggle Fullscreen | `Escape` |
 
-The player also owns **Toggle Fullscreen** (`host/fullscreen`), **Leave Fullscreen** (`host/exit-fullscreen`, `Escape`, only in fullscreen) and **Quit** (`host/quit`), and **Toggle Sidebar** (`host/sidebar`, player 0.5.10: the bottom bar's sidebar button, outside the menu, no default key); their keys are in Built-in commands.
+The player also owns **Toggle Fullscreen** (`host/fullscreen`, `Escape` from player 0.6.0; up to 0.5.x `Enter`, `Alt+Enter` and `F11`), **Enter Fullscreen** (`host/enter-fullscreen`, player 0.6.0: no default key, outside the menu, enabled only when windowed), **Leave Fullscreen** (`host/exit-fullscreen`: no default key from player 0.6.0, up to 0.5.x `Escape`; outside the menu, enabled only in fullscreen) and **Quit** (`host/quit`), and **Toggle Sidebar** (`host/sidebar`, player 0.5.10: the bottom bar's sidebar button, outside the menu, no default key); their keys are in Built-in commands.
 
 #### Keys the system takes first
 
@@ -4106,7 +4107,7 @@ flowchart TB
 
 - **Where bindings apply.** Bindings belong to the main window: they fire while it or the floating sidebar window has focus. They do **not** fire in tool windows or the Options window; keys there are the Slint file's own business (a `FocusScope`, a default button). While a menu or a system dialog is open, bindings pause.
 - **Conflicts are not errors.** A binding that loses is written to the player's log and takes effect by itself when the winner goes away (its plugin stops, the user rebinds it). Tests can check `host.conflicts` (TestHost.conflicts).
-- **A disabled command lets its key go.** This is what makes context-dependent keys work: `Escape` bound to "Leave Fullscreen" does nothing outside fullscreen, so `Escape` reaches the focused control. Give `reason` to a command whose key should still be taken and explained while it is disabled.
+- **A disabled command lets its key go.** This is what makes context-dependent keys work: a command bound to `Delete` that is disabled while nothing is selected does nothing then, so `Delete` reaches the focused control (a text field deletes a character). Give `reason` to a command whose key should still be taken and explained while it is disabled.
 - **`repeat: true`** fires again on the keyboard's auto-repeat while the key is held; without it a binding fires once per press.
 - **Some keys never reach a binding.** The system takes some keys first, and the standard close keys close a tool window, the floating sidebar or the Options window before any binding sees them (in the main window they are ordinary keys). Keys the system takes first lists them; default bindings avoid them.
 
@@ -4119,7 +4120,7 @@ Key names describe keys, not characters, with two deliberate exceptions:
 - **Option combinations match the physical key**, so `Alt+O` fires for ⌥O although that key types `ø`, and dead keys (⌥E, ⌥N…) fire too. On layouts that need Option to type a symbol (German ⌥5 = ``, ⌥L = `@`), a binding for the typed symbol (`"["`, `"@"`) wins over one for the physical key (`Alt+5`).
 - **`Ctrl` is portable, `Cmd` is not.** On macOS `Ctrl+X` fires for both ⌃X and ⌘X, `Cmd+X` only for ⌘X. On Windows `Cmd` is the Windows logo key, which the system mostly keeps, so write `Ctrl+…` for a binding that works on both systems.
 
-Mouse bindings apply only over the video area. `Mouse:LeftDoubleClick:LeftHalf` and `:RightHalf` win over the plain double click; wheel bindings count accumulated scroll steps. The right button is reserved for the context menu, and a left drag in window mode moves the window instead of clicking. A `Mouse:LeftClick` fires on release, except when the same modifiers also have a double-click binding and the click's command is not checkable: then the player waits the system's double-click interval to tell a click from a double click. (A checkable command such as play/pause runs at once; a double click runs it twice, which restores its state, and the double-click binding still fires.) The player's defaults (player 0.5.2): a left click on the video is Play/Pause and nothing is bound to a double click (up to 0.5.1 a double click was Toggle Fullscreen); a click whose command is disabled does nothing.
+Mouse bindings apply only over the video area, except the side buttons `Mouse:X1` (back) and `Mouse:X2` (forward), which fire anywhere in the main window or the floating sidebar window, except while a menu is open, as in browsers (player 0.6.0; before, only over the video area). `Mouse:LeftDoubleClick:LeftHalf` and `:RightHalf` win over the plain double click; wheel bindings count accumulated scroll steps. The right button is reserved for the context menu, and a left drag in window mode moves the window instead of clicking. A `Mouse:LeftClick` fires on release, except when the same modifiers also have a double-click binding and the click's command is not checkable: then the player waits the system's double-click interval to tell a click from a double click. (A checkable command such as play/pause runs at once; a double click runs it twice, which restores its state, and the double-click binding still fires.) The player's defaults (player 0.5.2): a left click on the video is Play/Pause and nothing is bound to a double click (up to 0.5.1 a double click was Toggle Fullscreen); a click whose command is disabled does nothing.
 
 ##### The user's bindings
 
@@ -4144,7 +4145,7 @@ plugin.commands.add({
 
 #### The player's own commands
 
-The player registers some commands itself, with the owner `host`: **Toggle Fullscreen**, **Leave Fullscreen**, **Quit**, **Toggle Sidebar** (the bottom bar's sidebar button, player 0.5.10) and the core playback actions (play/pause, stop, previous/next, frame step, relative seek, speed, volume, mute). They exist whether or not any plugin runs, and the user rebinds them like any other command.
+The player registers some commands itself, with the owner `host`: **Toggle Fullscreen** (`Escape` from player 0.6.0), **Enter Fullscreen** and **Leave Fullscreen** (player 0.6.0: no default key, each enabled only where it acts), **Quit**, **Toggle Sidebar** (the bottom bar's sidebar button, player 0.5.10) and the core playback actions (play/pause, stop, previous/next, frame step, relative seek, speed, volume, mute). They exist whether or not any plugin runs, and the user rebinds them like any other command.
 
 A plugin button that does what a core action does should run that action with plugin.host.run (capability `commands`): it applies the same checks and shows the same on-screen text as the menu item and the key, so a bottom bar's play button and the Space key behave identically. The action ids, their menu places and default keys are in Reference: commands; what they do to playback is in Playback.
 
@@ -4650,6 +4651,8 @@ From player 0.6.0 and SDK 1.5.44, a changed array (a list's rows) is sent as the
 - **Your Slint code must not write into the rows of an array property** (`rows[i].selected = true` in a handler). A whole write used to overwrite such a change on the next update; a row patch touches only the rows whose value changed in your plugin, so the edited row keeps the Slint-side value until your value for that row changes. Send the event to the plugin with a callback and change the row there.
 - **`set()` with an unchanged array sends the whole array**, as `set()` always sends: use it to pull a list back to your rows. A bound array whose rows did not change sends nothing.
 
+To find the changed rows the SDK encodes every row of a bound array on each update pass, which in a list of tens of thousands of rows is most of a pass. From SDK 1.5.47 it skips that for rows it can prove unchanged: a **deep-frozen** row object (`Object.freeze` on the row and on every object and array inside it, plain objects and arrays only, no getters or own `toJSON`; image and document handles may sit inside: they are immutable, so they need no freezing) that the bind function returns again is encoded once and then taken from a cache kept by the row object. To use it in a long list, keep each row as the same frozen object while it does not change and make a new one when it does (memoize by the row's id and the fields it shows). Nothing else changes: rows that are not frozen, or that hold a mutable part, are encoded on every pass as before, so a plugin that changes its rows in place keeps working.
+
 ##### Two-way controls
 
 A control whose value both the user and the plugin change (a slider, a switch, a text field, a combo box) needs a **two-way binding to an `in-out` property**:
@@ -5817,6 +5820,7 @@ Every SDK release's CHANGELOG entry opens with who must change and what happens
 
 | Release | Who must change | Guide |
 | --- | --- | --- |
+| [1.5.47](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1547) | **Nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability, no player version needed. | — |
 | [1.5.46](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1546) | **Nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability. | — |
 | [1.5.45](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1545) | **Nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability, no player version needed. | — |
 | [1.5.44](https://github.com/vestrasys/vestra-player-sdk/blob/main/CHANGELOG.md#1544) | **Nobody.** No changes to the TypeScript API, `apiVersion` stays `vestra/1`, no new capability. | — |
@@ -6765,9 +6769,12 @@ interface CommandOptions {
    * `Home`, `End`, `PageUp`, `PageDown`, `ArrowLeft`/`Right`/`Up`/`Down`,
    * `Plus`, any other single symbol as typed (`">"`, not `"Shift+."`),
    * `Numpad0`–`Numpad9`, `NumpadPlus`, `NumpadMinus`, `NumpadMultiply`,
-   * `NumpadDivide`, `NumpadEnter`, `NumpadDecimal`, and the video-area mouse
+   * `NumpadDivide`, `NumpadEnter`, `NumpadDecimal`, the video-area mouse
    * inputs `Mouse:LeftClick`, `Mouse:LeftDoubleClick[:LeftHalf|:RightHalf]`,
-   * `Mouse:MiddleClick`, `Mouse:X1`, `Mouse:X2`, `Mouse:WheelUp`/`Down`/`Left`/`Right`.
+   * `Mouse:MiddleClick`, `Mouse:WheelUp`/`Down`/`Left`/`Right`, and the side
+   * buttons `Mouse:X1` (back), `Mouse:X2` (forward), from 0.6.0 on anywhere
+   * in the main window or the floating sidebar window, except while a menu
+   * is open.
    *
    * Platforms: on macOS `Ctrl+X` fires for both ⌃X and ⌘X while `Cmd+X`
    * means ⌘X only; on Windows `Cmd` is the Windows logo key, so write
@@ -11252,13 +11259,13 @@ and the main window's fullscreen toggle.
 | --- | --- | --- |
 | `stop` | F4 | close the source |
 | `play-pause` | Space, a left click on the video (player 0.5.2) | pause / resume, replay after the end |
-| `previous` / `next` | PageUp, Mouse:X1 / PageDown, Mouse:X2 | ask the sequence provider |
+| `previous` / `next` | PageUp, Mouse:X2 / PageDown, Mouse:X1 (from 0.6.0; up to 0.5.x X1 was previous and X2 next) | ask the sequence provider |
 | `frame-back` / `frame-forward` | D / F | `player.step("frame", …)` |
 | `seek-backward` / `seek-forward` | ← / → | relative seek by `setStepSeek` seconds (or `host.run`'s `seconds`), exact or to keyframes as `setStepSeek` says |
 | `rate-normal`, `rate-down`, `rate-up` | Z, X, C | 1×, ±0.1 within 0.25–4 |
 | `volume-up` / `volume-down` | ↑ / ↓, wheel | ±5 (`volume-up` stops at 100) |
 | `mute` | M | toggle mute |
-| `fullscreen` | Enter, Alt+Enter, F11 | toggle the main window's fullscreen: enter it when windowed, leave it when fullscreen, as the Toggle Fullscreen command does (SDK 1.5.21, player 0.5.2; `unavailable` when the player has no window) |
+| `fullscreen` | Escape (from 0.6.0; up to 0.5.x Enter, Alt+Enter, F11) | toggle the main window's fullscreen: enter it when windowed, leave it when fullscreen, as the Toggle Fullscreen command does (SDK 1.5.21, player 0.5.2; `unavailable` when the player has no window) |
 
 In the binding overlay their keys are `host/<action>`. `fullscreen`
 changes no playback state: read the result from `window.state.fullscreen`
@@ -17625,7 +17632,9 @@ const BINDING_INPUTS: Readonly<{
    * Other named keys, matched by the physical key. `Plus` is the `+` key however it is typed; the `Numpad…` names are the numeric keypad only, never the main keyboard.
    */
   readonly named: readonly ["Space", "Enter", "Tab", "Escape", "Backspace", "Delete", "Insert", "Home", "End", "PageUp", "PageDown", "ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Plus", ...string[], "NumpadPlus", "NumpadMinus", "NumpadMultiply", "NumpadDivide", "NumpadEnter", "NumpadDecimal"];
-  /** Mouse inputs on the video area. `:LeftHalf` and `:RightHalf` tell the halves of the video apart for a double click. */
+  /**
+   * Mouse inputs on the video area; the side buttons `Mouse:X1` (back) and `Mouse:X2` (forward) anywhere in the main window or the floating sidebar window, except while a menu is open (player 0.6.0). `:LeftHalf` and `:RightHalf` tell the halves of the video apart for a double click.
+   */
   readonly mouse: readonly ["Mouse:LeftClick", "Mouse:LeftDoubleClick", "Mouse:LeftDoubleClick:LeftHalf", "Mouse:LeftDoubleClick:RightHalf", "Mouse:MiddleClick", "Mouse:X1", "Mouse:X2", "Mouse:WheelUp", "Mouse:WheelDown", "Mouse:WheelLeft", "Mouse:WheelRight"];
 }>;
 ```

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.46: 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.47: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process (the player's built-in plugins share one). Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n>: a line of llms-full.txt (next to this file), which has every page, declaration and example.
 
 **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: L15484.
+**Test**: `tests/*.test.ts` with `node:test`, run by `vestra-plugin test`. `startPlugin(activate, { directory: new URL("..", import.meta.url) })` from `@vestra-player/sdk/testing` returns `{ host, stop }`, `host` an in-memory player (TestHost): act (`host.command(id).run()`, `host.press(key)`), `await host.settle()`, assert on `host.osd`, `host.window(id).props`… Guide: L1861–2021; TestHost: L15491.
 
 **Command line**
 
@@ -108,40 +108,40 @@ export default async function activate(plugin: Plugin) {
 - `limit`: A player-wide limit was reached, a property value is over the limits of PropValue
 - `reserved`: The id is `vestra` or starts with `vestra.`
 - `versionMismatch`: The package needs a newer player
-- Others: PluginError, llms-full.txt L5954.
+- Others: PluginError, llms-full.txt L5958.
 
 ## Reference
 
 - [llms-full.txt](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt), also node_modules/@vestra-player/sdk/llms-full.txt; pages: [site](https://vestrasys.github.io/vestra-player-sdk/).
 - Tutorials: Getting started L9–134; Add a window L135–213; Add settings and translations L214–367; Test, check, pack and publish L368–424; Write your own blur kernel L425–685
 - How-to: Control playback L686–854; Store a plugin's data L855–961; Load subtitles from a plugin L962–1074; Keep a slider responsive while dragging L1075–1262; Remember a window's state between runs L1263–1414; Offer a GPU rendering switch L1415–1540; Keep a command's state without keeping the plugin running L1541–1697; Translate a plugin L1698–1860; Test a plugin L1861–2021; Publish a plugin L2022–2123; Troubleshooting L2124–2217
-- Reference: Manifest L2218–2292; Capabilities L2293–2353; Limits L2354–2499; Commands, menus and bindings L2500–3025; Platforms L3026–3056; Theme L3057–3406; Command line L3407–3464; Error codes L3465–3512; Translations L3513–3605; Test host L3606–3792
-- Explanation: How a plugin runs L3793–3995; Commands, menus and key bindings L3996–4150; Playback state, controls and sources L4151–4310; Video and audio processing L4311–4431; Windows, panels, settings pages, dialogs and the OSD L4432–4694; GPU and software rendering L4695–4711; The player's Rust core L4712–5053; How the player runs and talks to plugins L5054–5393
-- Guidelines: Plugin rules L5394–5405; Interface guidelines L5406–5522; Menu guidelines L5523–5581
-- Upgrading: Migrate a plugin to English source text L5582–5731; Migrating off package rollback (1.5.16, removed in 1.5.17) L5732–5809; Who must change, release by release L5810–5876
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5877–15157
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L15158–18020
+- Reference: Manifest L2218–2292; Capabilities L2293–2353; Limits L2354–2499; Commands, menus and bindings L2500–3026; Platforms L3027–3057; Theme L3058–3407; Command line L3408–3465; Error codes L3466–3513; Translations L3514–3606; Test host L3607–3793
+- Explanation: How a plugin runs L3794–3996; Commands, menus and key bindings L3997–4151; Playback state, controls and sources L4152–4311; Video and audio processing L4312–4432; Windows, panels, settings pages, dialogs and the OSD L4433–4697; GPU and software rendering L4698–4714; The player's Rust core L4715–5056; How the player runs and talks to plugins L5057–5396
+- Guidelines: Plugin rules L5397–5408; Interface guidelines L5409–5525; Menu guidelines L5526–5584
+- Upgrading: Migrate a plugin to English source text L5585–5734; Migrating off package rollback (1.5.16, removed in 1.5.17) L5735–5812; Who must change, release by release L5813–5880
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L5881–15164
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L15165–18029
 
 ## API
 
 Where each `plugin.<module>` is declared:
 
-- Plugin L6293, Scope L6029, PluginError L5954, Disposable L5892
-- Commands L6883; When L6480; Windows L7829; Panels L9275; Dialogs L9945; Player L10686; video: VideoFilter L11566, VideoView L11666, RenderOptions L11753, VideoShaders L11831, VideoUpscaling L12189; audio: AudioFilter L11611; Subtitles L12425; media: MediaCapture L12829; Resolvers L13059; Packages L13461; Osd L11431; Host L11273; Clipboard L13790; Power L13877; Tools L13936; Storage L14088; System L14287; Secrets L14367; window: MainWindow L9592; App L9772; Rendering L14630; Bindings L13689; Ui L7175; Timeline L9504; Drops L8522; Appearance L8603; I18n L8836; Settings L9119.
+- Plugin L6297, Scope L6033, PluginError L5958, Disposable L5896
+- Commands L6890; When L6484; Windows L7836; Panels L9282; Dialogs L9952; Player L10693; video: VideoFilter L11573, VideoView L11673, RenderOptions L11760, VideoShaders L11838, VideoUpscaling L12196; audio: AudioFilter L11618; Subtitles L12432; media: MediaCapture L12836; Resolvers L13066; Packages L13468; Osd L11438; Host L11280; Clipboard L13797; Power L13884; Tools L13943; Storage L14095; System L14294; Secrets L14374; window: MainWindow L9599; App L9779; Rendering L14637; Bindings L13696; Ui L7182; Timeline L9511; Drops L8529; Appearance L8610; I18n L8843; Settings L9126.
 
 ## 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. L18455–18550
-- blur: A tool window with one slider that blurs the playing video. L18551–18818
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18819–19157
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L19158–19350
-- panel-menu: A sidebar panel with its own right-click menu. L19351–19565
-- menus: Radio menu items, separator groups and a menu item whose title changes. L19566–19731
-- theme-widgets: A tool window drawn with the player's theme and widgets. L19732–19901
-- markdown: A window that shows a Markdown document. L19902–20104
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L20105–20278
+- hello: The README Quick start: one menu command and an on-screen message. L18464–18559
+- blur: A tool window with one slider that blurs the playing video. L18560–18827
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L18828–19166
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L19167–19359
+- panel-menu: A sidebar panel with its own right-click menu. L19360–19574
+- menus: Radio menu items, separator groups and a menu item whose title changes. L19575–19740
+- theme-widgets: A tool window drawn with the player's theme and widgets. L19741–19910
+- markdown: A window that shows a Markdown document. L19911–20113
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L20114–20287
 
 ## Optional
 

package/package.json

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