@vestra-player/sdk 1.5.20 → 1.5.23

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.5.23
+
+**Who must change: nobody.** Republishes 1.5.22 with a clean API documentation build; 1.5.22 was tagged but never published to npm: TypeDoc treats warnings as errors and failed on two `{@link}` labels in *Playback* that contained a brace (`Scrub.seek(seconds, { keyframes })`). Documentation only; the code is the same as 1.5.22 below.
+
+## 1.5.22
+
+**Who must change: nobody.** Plugins built on earlier SDKs keep working unchanged: a scrub without the new option seeks exactly, as before. Additive; `apiVersion` stays `vestra/1`. The addition needs player 0.5.3.
+
+- **`Scrub.seek(seconds, { keyframes?: boolean })`** (player 0.5.3; requested by the playback plugin for the seek bar, user ruling of 2026-10-27: the bar follows the same "Jump to keyframes only" switch as the arrow keys, PotPlayer style, no second exact seek). With `keyframes: true` the seek lands on the last keyframe at or before `seconds` (mpv `absolute+keyframes`) instead of decoding up to the exact frame: the picture appears in tens of milliseconds on any file, up to one keyframe interval before the target, and the reported position is the keyframe's. Omitted or `false`: exact, as before. The option goes on the wire only when true (`control: { kind: "seek", seconds, keyframes: true }`); players before 0.5.3 ignore the field and seek exactly, so set `"minPlayerVersion": "0.5.3"` when you rely on it. The player sends a repeated target of the same gesture only once while that seek is still running (a click is a press and a release), keyed on the target and the mode: an exact seek to the target of a keyframe seek is always sent.
+- **`TestHost.seeks`**: every seek a plugin submitted (`player.seek`, `Scrub.seek`), newest last, as `{ seconds, keyframes }`. The test host lands on the exact target in both modes; a non-boolean `keyframes` is `invalid`.
+- Docs: *Playback* (scrubs and the keyframe switch); *Windows, panels, settings pages* gains a pitfall: an `if` that flips under the pointer (a hover highlight created and destroyed on every hover change) rebuilds the window's accessibility tree and drops the video to 10–15 frames a second while the pointer moves; keep the element and change `visible` or `opacity`. `llms.txt` and `llms-full.txt` regenerated.
+
+## 1.5.21
+
+**Who must change: nobody.** Plugins built on earlier SDKs keep working unchanged; the additions need player 0.5.2. Additive and bug fixes; `apiVersion` stays `vestra/1`.
+
+- **`Host.run("fullscreen")`** (player 0.5.2; requested by the playback plugin for a bottom-bar button): toggles the main window's fullscreen exactly like the Toggle Fullscreen command (Enter, F11): in when windowed, out when fullscreen. Read the result from `window.state.fullscreen`. `unavailable` when the player has no window; players before 0.5.2 reject the id with `invalid`, so set `"minPlayerVersion": "0.5.2"`. `HostAction` gains `"fullscreen"`.
+- **Default mouse bindings** (player 0.5.2, user ruling): a left click on the video is Play/Pause (`Mouse:LeftClick`, fired on release) and nothing is bound to a double click; Toggle Fullscreen keeps `Enter`, `Alt+Enter`, `F11`. `BUILTIN_COMMANDS` says so. A plugin that declared `Mouse:LeftClick` itself is shadowed by the player's default, as for any key the player binds; users' own bindings are unchanged.
+- **`ToolTipArea` no longer swallows a press** (`slint/vestra/widgets.slint`, the player's widget library; bug fix): the tip was a `PopupWindow`, so while it showed, the first press anywhere only closed it, and it took the keyboard focus. It is now Slint's input-transparent tooltip: every press reaches the control under the pointer. It shows after about half a second (was 600 ms), and `showing` follows that delay closely. No API change.
+- **Icons `fullscreen` and `exit-fullscreen`** in `slint/vestra/icons.slint` (14 × 12, the V-Line style).
+- **`TestHost`**: `host.run("fullscreen")` flips `host.mainWindow.fullscreen` and emits `window.state` (recorded in `coreRuns`); `host/play-pause` declares `Space` and `Mouse:LeftClick`.
+- Docs: *Commands* (the player's mouse defaults), *Playback* (a fullscreen button), the Theme and widgets example (the tooltip); generated tables and `llms.txt` / `llms-full.txt` regenerated.
+
 ## 1.5.20
 
 Republishes 1.5.19, which was tagged but never published: its API documentation build failed (an example title and four undocumented `IMAGE_LIMITS` fields). Documentation only; the code is the same as 1.5.19 below.

package/dist/commands.js

@@ -142,7 +142,7 @@ 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
+host | play-pause | Playback ▸ Play/Pause | Space, Mouse:LeftClick
 host | previous | Playback ▸ Previous | PageUp, Mouse:X1
 host | next | Playback ▸ Next | PageDown, Mouse:X2
 host | frame-back | Playback ▸ Seek ▸ Previous Frame | D
@@ -372,7 +372,7 @@ vestra.visualizer | audio-cover | Audio ▸ Show Album Cover for Audio Only
 vestra.nes | nes.open | Emulator ▸ Open NES ROM…
 vestra.nes | nes.stop | Emulator ▸ Stop NES
 vestra.nes | nes.window | Emulator ▸ NES Tools…
-host | fullscreen | Toggle Fullscreen | Enter, Alt+Enter, F11, Mouse:LeftDoubleClick
+host | fullscreen | Toggle Fullscreen | Enter, Alt+Enter, F11
 vestra.window | pip | Screen ▸ Picture-in-Picture
 vestra.window | mini | Screen ▸ Mini Size | \`
 vestra.window | size.0.5 | Screen ▸ 0.5× | 1

package/dist/plugin/player.js

@@ -316,7 +316,7 @@ class ScrubHandle {
                 !(this.#pending && sameStamp(raw.stamp, this.#pending)))
                 this.end();
         });
-        this.#queue = new Latest(async (seconds) => {
+        this.#queue = new Latest(async ({ seconds, keyframes }) => {
             if (!this.#active)
                 throw superseded;
             const started = Date.now();
@@ -326,9 +326,15 @@ class ScrubHandle {
                 intentVersion: expected.intentVersion + 1,
             };
             try {
+                // `keyframes` goes on the wire only when set, so players before
+                // 0.5.3 (which ignore the field) see the same intent as before.
                 const ticket = await service.submit({
                     kind: "control",
-                    control: { kind: "seek", seconds },
+                    control: {
+                        kind: "seek",
+                        seconds,
+                        ...(keyframes ? { keyframes } : {}),
+                    },
                     expected,
                 });
                 if (!this.#active)
@@ -354,11 +360,11 @@ class ScrubHandle {
     get active() {
         return this.#active;
     }
-    seek(seconds) {
+    seek(seconds, options = {}) {
         if (!this.#active)
             return Promise.resolve(false);
         return this.#queue
-            .push(seconds)
+            .push({ seconds, keyframes: options.keyframes === true })
             .catch((error) => (error === superseded ? false : Promise.reject(error)));
     }
     end() {

package/dist/plugin/services.js

@@ -30,6 +30,7 @@ const ACTIONS = new Set([
     "volume-up",
     "volume-down",
     "mute",
+    "fullscreen",
 ]);
 export const host = (scope) => ({
     async run(action, options) {

package/dist/plugin/testing.d.ts

@@ -1147,6 +1147,18 @@ export declare class TestHost implements Transport {
         /** The new position. */
         landed: number;
     }[];
+    /**
+     * Every seek a plugin submitted (`player.seek`, `Scrub.seek`), newest
+     * last, with the mode it asked for. The test host lands on the exact
+     * target either way (the player lands a `keyframes` seek on the last
+     * keyframe at or before it); the core's step seeks are in `coreSeeks`.
+     */
+    readonly seeks: {
+        /** The target. */
+        seconds: number;
+        /** `Scrub.seek(seconds, { keyframes: true })` (SDK 1.5.22). */
+        keyframes: boolean;
+    }[];
     /** Every `player.step`, newest last. */
     readonly steps: {
         /** `"frame"` or `"keyframe"`. */

package/dist/plugin/testing.js

@@ -1277,6 +1277,13 @@ export class TestHost {
      * a keyframe, and where it landed.
      */
     coreSeeks = [];
+    /**
+     * Every seek a plugin submitted (`player.seek`, `Scrub.seek`), newest
+     * last, with the mode it asked for. The test host lands on the exact
+     * target either way (the player lands a `keyframes` seek on the last
+     * keyframe at or before it); the core's step seeks are in `coreSeeks`.
+     */
+    seeks = [];
     /** Every `player.step`, newest last. */
     steps = [];
     /** Every core action run (`host.run`, a core command, a pressed core binding), newest last. */
@@ -1375,7 +1382,7 @@ export class TestHost {
                 ["Playback", "Play/Pause"],
                 201,
                 "domain",
-                ["Space"],
+                ["Space", "Mouse:LeftClick"],
                 false,
             ],
             [
@@ -2735,6 +2742,7 @@ export class TestHost {
                 "volume-up",
                 "volume-down",
                 "mute",
+                "fullscreen",
             ];
             if (!actions.includes(String(p.action)))
                 throw new HostError("invalid", `unknown host action ${p.action}`);
@@ -2747,6 +2755,13 @@ 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
+            // windowed, out when fullscreen, then `window.state`.
+            if (p.action === "fullscreen") {
+                this.coreRuns.push("fullscreen");
+                this.setMainWindow({ fullscreen: !this.mainWindow.fullscreen });
+                return;
+            }
             this.#runCore(String(p.action), seconds);
         },
         "player.setStepSeek": (p) => {
@@ -3059,6 +3074,16 @@ export class TestHost {
         "source.state": () => this.source,
         "source.submit": (p) => {
             const intent = p.intent;
+            const control = intent.control;
+            if (intent.kind === "control" && control?.kind === "seek") {
+                if (control.keyframes !== undefined &&
+                    typeof control.keyframes !== "boolean")
+                    throw new HostError("invalid", "keyframes must be a boolean");
+                this.seeks.push({
+                    seconds: Number(control.seconds),
+                    keyframes: control.keyframes === true,
+                });
+            }
             const ticket = this.#intent(intent);
             const operation = Number(p.operationId);
             // A file this plugin's file resolver claims: pending until it answers.

package/dist/plugin/types.d.ts

@@ -3501,10 +3501,32 @@ export interface Media {
  */
 export interface Scrub {
     /**
-     * Resolves `true` when this exact target was applied, `false` when a newer
-     * target superseded it or the gesture ended. Rejects on a host failure.
+     * Seek within the gesture. Resolves `true` when this target was applied,
+     * `false` when a newer target superseded it or the gesture ended. Rejects
+     * on a host failure.
+     *
+     * `keyframes: true` (player 0.5.3, SDK 1.5.22): land on the last keyframe
+     * at or before `seconds` instead of decoding up to that exact frame. The
+     * picture appears at once on any file (tens of milliseconds instead of
+     * seconds on 4K video with keyframes far apart), up to one keyframe
+     * interval before the target; the position the player reports is the
+     * keyframe's. Use it when the user chose keyframe seeks (the same switch
+     * as {@link Player.setStepSeek}), and the exact seek otherwise. The player
+     * sends a repeated target of the same gesture only once while the seek is
+     * still running (a click is a press and a release), but an exact seek to
+     * the target of a keyframe seek is always sent. Omitted or `false`: exact,
+     * as before. Older players ignore the option and seek exactly: set
+     * `"minPlayerVersion": "0.5.3"` when you rely on it.
+     *
+     * @example
+     * ```ts
+     * const keyframes = true; // the plugin's own setting
+     * bar.on("dragMove", (seconds: number) => void scrub?.seek(seconds, { keyframes }));
+     * ```
      */
-    seek(seconds: number): Promise<boolean>;
+    seek(seconds: number, options?: {
+        keyframes?: boolean;
+    }): Promise<boolean>;
     /** False once anyone else changed the source; later seeks are ignored. */
     readonly active: boolean;
     /** End the gesture; later seeks resolve `false`. */
@@ -3828,10 +3850,11 @@ export interface Player {
      * step, backward on the last at or before position − step, and they
      * always move. Presses during a seek add up and continue from where it
      * landed; the on-screen text shows the landed time. Sources without moving
-     * video seek exactly. The seek bar, {@link Player.seek}, scrubs, chapters,
-     * loops and {@link Player.step} are unaffected. Omitted or `false`: exact
-     * seeks, as before. `seconds` and `keyframes` are written as a pair: the
-     * newest call sets both.
+     * video seek exactly. {@link Player.seek}, chapters, loops and
+     * {@link Player.step} are unaffected, and so is a scrub unless it asks for
+     * keyframes itself ({@link Scrub.seek} with `keyframes: true`, SDK 1.5.22).
+     * Omitted or `false`: exact seeks, as before. `seconds` and `keyframes`
+     * are written as a pair: the newest call sets both.
      *
      * Older players ignore `keyframes`: set `"minPlayerVersion": "0.5.1"` in
      * the manifest when you rely on it.
@@ -3877,22 +3900,28 @@ export interface Player {
     setAudioDevice(id: string | null): Promise<void>;
 }
 /**
- * The core's basic playback actions (menu commands owned by the player).
+ * The core's basic playback actions (menu commands owned by the player),
+ * and the main window's fullscreen toggle.
  *
  * | action | default bindings | behaviour |
  * | --- | --- | --- |
  * | `stop` | F4 | close the source |
- * | `play-pause` | Space | pause / resume, replay after the end |
+ * | `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 |
  * | `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) |
  *
- * In the binding overlay their keys are `host/<action>`.
+ * In the binding overlay their keys are `host/<action>`. `fullscreen`
+ * changes no playback state: read the result from `window.state.fullscreen`
+ * (`plugin.window.onChange`), which also changes when the user toggles it.
+ * Players before 0.5.2 reject it with `invalid`: set
+ * `"minPlayerVersion": "0.5.2"` when you use it.
  */
-export type HostAction = "play-pause" | "stop" | "previous" | "next" | "frame-back" | "frame-forward" | "seek-backward" | "seek-forward" | "rate-down" | "rate-up" | "rate-normal" | "volume-up" | "volume-down" | "mute";
+export type HostAction = "play-pause" | "stop" | "previous" | "next" | "frame-back" | "frame-forward" | "seek-backward" | "seek-forward" | "rate-down" | "rate-up" | "rate-normal" | "volume-up" | "volume-down" | "mute" | "fullscreen";
 /** `plugin.host`: the player's own core actions. */
 export interface Host {
     /**

package/dist/source.d.ts

@@ -30,6 +30,12 @@ export type SourceIntent = {
     } | {
         kind: "seek";
         seconds: number;
+        /**
+         * Land on the last keyframe at or before `seconds` instead of the
+         * exact time (player 0.5.3). Sent only when true: older players
+         * ignore the field and seek exactly.
+         */
+        keyframes?: boolean;
     } | {
         kind: "rate";
         rate: number;

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.20: full reference
+# @vestra-player/sdk 1.5.23: 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.
 
@@ -445,7 +445,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.)
+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.
 
 ##### The user's bindings
 
@@ -524,7 +524,7 @@ Without this rule, a "jump to bookmark" that arrives a moment late would seek a
 Two controls follow other rules because they are about the device or a gesture, not the source:
 
 - setOutput (volume and mute) is last-write-wins and resolves `false` when a newer value replaced it.
-- scrub() starts a drag gesture on a seek bar: each seek in the gesture is conditional on the previous one, only the newest target is kept, and any outside change ends the gesture. Use it for a slider instead of calling `seek` on every move.
+- scrub() starts a drag gesture on a seek bar: each seek in the gesture is conditional on the previous one, only the newest target is kept, and any outside change ends the gesture. Use it for a slider instead of calling `seek` on every move. Scrub.seek with `{ keyframes: true }` (player 0.5.3, SDK 1.5.22) lands on the last keyframe at or before the target instead of the exact frame; see Step seeks: exact or keyframe.
 
 #### Sources
 
@@ -579,16 +579,18 @@ The player's **Previous** and **Next** (menu, keys, the bottom bar) are not tied
 
 #### Core actions
 
-Play/pause, stop, previous/next, frame steps, relative seeks, speed, volume and mute are **core actions**: commands the player registers itself, so they work with no plugin running. plugin.host.run(action) runs one exactly as its menu item or key would, with the same checks and the same on-screen text. A plugin's play button should call `host.run("play-pause")` rather than `setPaused`, so that it behaves like the Space key in every case (restart after the end, the "Paused" message, disabled without a source).
+Play/pause, stop, previous/next, frame steps, relative seeks, speed, volume and mute are **core actions**: commands the player registers itself, so they work with no plugin running. plugin.host.run(action) runs one exactly as its menu item or key would, with the same checks and the same on-screen text. A plugin's play button should call `host.run("play-pause")` rather than `setPaused`, so that it behaves like the Space key in every case (restart after the end, the "Paused" message, disabled without a source). A fullscreen button calls `host.run("fullscreen")` (player 0.5.2), which toggles the main window like Enter; show the button's state from `window.state.fullscreen`.
 
 The difference from the `Player` methods: a `Player` control is a precise operation the plugin is responsible for (conditional, silent, its own error handling); a core action is the user's action, performed on the plugin's behalf. The action ids, menu places and default keys are in Reference: commands; how keys reach them is in Commands, menus and key bindings.
 
 ##### Step seeks: exact or keyframe
 
-← / → (`seek-backward` / `seek-forward`) seek by the step that player.setStepSeek sets (5 s by default). By default they land on the exact time, which on a file with keyframes far apart means decoding from the previous keyframe first: a visible stall on 4K video. `setStepSeek({ seconds, keyframes: true })` (player 0.5.1, SDK 1.5.19) makes them land on a keyframe instead: forward on the first keyframe at or after position + step, backward on the last at or before position − step, and every press moves. Presses during a seek add up and continue from where it landed, and the on-screen text shows the landed time. Sources without moving video still seek exactly. The seek bar, `player.seek`, scrubs, chapters, loops and `player.step` are never affected.
+← / → (`seek-backward` / `seek-forward`) seek by the step that player.setStepSeek sets (5 s by default). By default they land on the exact time, which on a file with keyframes far apart means decoding from the previous keyframe first: a visible stall on 4K video. `setStepSeek({ seconds, keyframes: true })` (player 0.5.1, SDK 1.5.19) makes them land on a keyframe instead: forward on the first keyframe at or after position + step, backward on the last at or before position − step, and every press moves. Presses during a seek add up and continue from where it landed, and the on-screen text shows the landed time. Sources without moving video still seek exactly. `player.seek`, chapters, loops and `player.step` are never affected.
 
 For more steps of your own (Ctrl+→ and the like), call `plugin.host.run("seek-forward", { seconds: 30 })`: the same checks, mode, accumulation and text as →. In keyframe mode it resolves once the seek has landed, so `player.state.position` is current afterwards; do not show your own text for it. Set `"minPlayerVersion": "0.5.1"` when you rely on either option: older players ignore them.
 
+A seek bar follows the same switch with Scrub.seek and its `keyframes` option, `scrub.seek(seconds, { keyframes })` (player 0.5.3, SDK 1.5.22): with `keyframes: true` every click and drag step lands on the last keyframe at or before the pointer, so the picture follows the pointer on any file (an exact seek decodes from the keyframe to the target first: seconds on 4K video with keyframes far apart, and a drag freezes); the position is up to one keyframe interval early, and that is what the player shows, as PotPlayer does. Do not seek twice (keyframes, then exactly): one mode per gesture, the user's choice. Older players ignore the option and seek exactly (`"minPlayerVersion": "0.5.3"` when you rely on it).
+
 ```ts
 const keyframes = true; // the plugin's own setting
 await plugin.player.setStepSeek({ seconds: 5, keyframes });
@@ -596,9 +598,13 @@ const seek = (delta: number) =>
   plugin.host.run(delta < 0 ? "seek-backward" : "seek-forward", {
     seconds: Math.abs(delta),
   });
+// The seek bar: one gesture per press, every click and drag step in the same mode.
+const scrub = plugin.player.scrub();
+await scrub.seek(27.6, { keyframes });
+scrub.end();
 ```
 
-In tests, `TestHost.keyframes` models the source's keyframes, and `host.coreSeeks` records each step seek with where it landed.
+In tests, `TestHost.keyframes` models the source's keyframes, `host.coreSeeks` records each step seek with where it landed, and `host.seeks` records each `player.seek` and `Scrub.seek` with the mode it asked for (the test host lands on the exact target in both modes).
 
 ## Concept: Video and audio processing
 
@@ -960,6 +966,7 @@ The API is the same on macOS and Windows; what differs is the system's own part:
 - **Hard-coded colours.** They do not follow the palette. Use `Theme.*`, and `Theme.danger` for errors.
 - **A `Ctrl+W` default binding.** It never fires in tool windows and floating panels. Pick another key.
 - **Two of a kind.** One panel per plugin, one backdrop per player, one OSD info block per plugin, one open dialog at a time (`busy`).
+- **An `if` that flips under the pointer.** `if touch.has-hover: Rectangle { … }` (a hover highlight, an accent bar, a tooltip-like box that follows the pointer) creates and destroys an element on every hover change. While a video plays, each such change costs the player's UI thread far more than a property change: the player's accessibility tree (screen readers, UI Automation) is rebuilt for the whole window each time, measured at 100–160 ms per hover on Windows, enough to drop the video to 10–15 frames a second while the pointer moves. Keep the element and change properties instead: `Rectangle { visible: touch.has-hover; … }` or `opacity:`. Use `if` for things that change rarely (a mode, a selection made with a click, a list that was loaded), never for something that follows the pointer or a hover.
 - **Slot state without `events`.** PanelSlot.state, appearance.theme and their `onChange` listeners follow other plugins and the user only with the `events` capability.
 
 #### Testing
@@ -2176,6 +2183,8 @@ The table lists the API whose documentation names a player version, newest last:
 | 0.4.2 | Resolvers.fileTypes, Resolvers.onFileTypesChange |
 | 0.4.3 | CommandOptions.path, PropValue, View.set, Appearance.setLanguage, TemplateArgs, Text, ConfirmOptions.args, OsdPanel.set, OsdPanelOptions.maxColumns, Osd.show |
 | 0.5.1 | ImageRef, ImageOptions.maxSide, PropValue, Ui.image, Ui.remoteImage, SlotState.reason, Panel.setInteraction, PlaybackStats.presentedFps, Player.setStepSeek, Host.run, Packages.reload |
+| 0.5.2 | HostAction |
+| 0.5.3 | Scrub.seek |
 
 The Slint library carries no version tags: `Theme.danger` needs player 0.3.0; `@vestra/icons.slint` and the palette `vestra-light` need 0.4.0 (Theme).
 
@@ -2410,7 +2419,7 @@ Every command the player (`host`) and its built-in plugins register when the pla
 | Copy to Clipboard ▸ File Name |  | `vestra.playback/copy-name` |
 | Copy to Clipboard ▸ Folder Path |  | `vestra.playback/copy-folder` |
 | Copy to Clipboard ▸ Full Path |  | `vestra.playback/copy-path` |
-| Playback ▸ Play/Pause | `Space` | `host/play-pause` |
+| Playback ▸ Play/Pause | `Space`, `Mouse:LeftClick` | `host/play-pause` |
 | Playback ▸ Previous | `PageUp`, `Mouse:X1` | `host/previous` |
 | Playback ▸ Next | `PageDown`, `Mouse:X2` | `host/next` |
 | Playback ▸ Seek ▸ Previous Frame | `D` | `host/frame-back` |
@@ -2640,7 +2649,7 @@ Every command the player (`host`) and its built-in plugins register when the pla
 | Emulator ▸ Open NES ROM… |  | `vestra.nes/nes.open` |
 | Emulator ▸ Stop NES |  | `vestra.nes/nes.stop` |
 | Emulator ▸ NES Tools… |  | `vestra.nes/nes.window` |
-| Toggle Fullscreen | `Enter`, `Alt+Enter`, `F11`, `Mouse:LeftDoubleClick` | `host/fullscreen` |
+| Toggle Fullscreen | `Enter`, `Alt+Enter`, `F11` | `host/fullscreen` |
 | Screen ▸ Picture-in-Picture |  | `vestra.window/pip` |
 | Screen ▸ Mini Size | ``` | `vestra.window/mini` |
 | Screen ▸ 0.5× | `1` | `vestra.window/size.0.5` |
@@ -2753,7 +2762,7 @@ The player's own playback commands, which plugin.host.run runs by id (capability
 | Action | Menu item | Default bindings |
 | --- | --- | --- |
 | `stop` | Close | `F4` |
-| `play-pause` | Playback ▸ Play/Pause | `Space` |
+| `play-pause` | Playback ▸ Play/Pause | `Space`, `Mouse:LeftClick` |
 | `previous` | Playback ▸ Previous | `PageUp`, `Mouse:X1` |
 | `next` | Playback ▸ Next | `PageDown`, `Mouse:X2` |
 | `frame-back` | Playback ▸ Seek ▸ Previous Frame | `D` |
@@ -2766,6 +2775,7 @@ 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` |
 
 The player also owns **Toggle Fullscreen** (`host/fullscreen`), **Leave Fullscreen** (`host/exit-fullscreen`, `Escape`, only in fullscreen) and **Quit** (`host/quit`); their keys are in Built-in commands.
 
@@ -2940,17 +2950,19 @@ Icon { name: "close"; width: 20px; height: 20px; }         // scaled
 | `add` | 10 × 10 | 1.5px |
 | `remove` | 10 × 10 | 1.5px |
 | `sort` | 10 × 10 | 1.5px |
+| `fullscreen` | 14 × 12 | 1.5px |
+| `exit-fullscreen` | 14 × 12 | 1.5px |
 
 #### Widgets
 
 `@vestra/widgets.slint`: compact controls drawn with the theme. Other controls come from `std-widgets.slint`.
 
-**`ToolTipArea`**: Hover for 600 ms to show `text` beside the pointer. The tip closes when the pointer leaves or presses; it shows again on the next hover.
+**`ToolTipArea`**: Hover for about half a second to show `text` beside the pointer. The tip closes when the pointer leaves, or presses on content that does not take the press itself; it shows again on the next hover. It is Slint's input-transparent tooltip: every press reaches the control under the pointer, and the tip does not take the keyboard focus. (Up to SDK 1.5.20 the tip was a PopupWindow, which swallowed the first press after it showed and took the focus while it was open.)
 
 | Member | Kind | Default | Note |
 | --- | --- | --- | --- |
 | `text` | in `string` |  |  |
-| `showing` | out `bool` |  | The tip is showing (read-only). |
+| `showing` | out `bool` |  | The tip is showing (read-only); it follows the tip's delay closely, not exactly. |
 
 **`Button`**: Dialog button: text (21px, or 18px when `small`), or an icon button when `text` is empty and `icon` holds Path data drawn in an icon-width × icon-height viewbox (filled, or 1.5px round-capped lines when `stroked`, as the @vestra/icons.slint set). The caller sizes icon buttons.
 
@@ -4944,8 +4956,27 @@ the gesture.
 
 ```ts
 interface Scrub {
-  /** Resolves `true` when this exact target was applied, `false` when a newer target superseded it or the gesture ended. Rejects on a host failure. */
-  seek(seconds: number): Promise<boolean>;
+  /**
+   * Seek within the gesture. Resolves `true` when this target was applied,
+   * `false` when a newer target superseded it or the gesture ended. Rejects
+   * on a host failure.
+   *
+   * `keyframes: true` (player 0.5.3, SDK 1.5.22): land on the last keyframe
+   * at or before `seconds` instead of decoding up to that exact frame. The
+   * picture appears at once on any file (tens of milliseconds instead of
+   * seconds on 4K video with keyframes far apart), up to one keyframe
+   * interval before the target; the position the player reports is the
+   * keyframe's. Use it when the user chose keyframe seeks (the same switch
+   * as Player.setStepSeek), and the exact seek otherwise. The player
+   * sends a repeated target of the same gesture only once while the seek is
+   * still running (a click is a press and a release), but an exact seek to
+   * the target of a keyframe seek is always sent. Omitted or `false`: exact,
+   * as before. Older players ignore the option and seek exactly: set
+   * `"minPlayerVersion": "0.5.3"` when you rely on it.
+   */
+  seek(seconds: number, options?: {
+    keyframes?: boolean;
+  }): Promise<boolean>;
   /** False once anyone else changed the source; later seeks are ignored. */
   readonly active: boolean;
   /** End the gesture; later seeks resolve `false`. */
@@ -5234,10 +5265,11 @@ interface Player {
    * step, backward on the last at or before position − step, and they
    * always move. Presses during a seek add up and continue from where it
    * landed; the on-screen text shows the landed time. Sources without moving
-   * video seek exactly. The seek bar, Player.seek, scrubs, chapters,
-   * loops and Player.step are unaffected. Omitted or `false`: exact
-   * seeks, as before. `seconds` and `keyframes` are written as a pair: the
-   * newest call sets both.
+   * video seek exactly. Player.seek, chapters, loops and
+   * Player.step are unaffected, and so is a scrub unless it asks for
+   * keyframes itself (Scrub.seek with `keyframes: true`, SDK 1.5.22).
+   * Omitted or `false`: exact seeks, as before. `seconds` and `keyframes`
+   * are written as a pair: the newest call sets both.
    *
    * Older players ignore `keyframes`: set `"minPlayerVersion": "0.5.1"` in
    * the manifest when you rely on it.
@@ -5278,23 +5310,29 @@ interface Player {
 
 ### HostAction
 
-The core's basic playback actions (menu commands owned by the player).
+The core's basic playback actions (menu commands owned by the player),
+and the main window's fullscreen toggle.
 
 | action | default bindings | behaviour |
 | --- | --- | --- |
 | `stop` | F4 | close the source |
-| `play-pause` | Space | pause / resume, replay after the end |
+| `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 |
 | `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) |
 
-In the binding overlay their keys are `host/<action>`.
+In the binding overlay their keys are `host/<action>`. `fullscreen`
+changes no playback state: read the result from `window.state.fullscreen`
+(`plugin.window.onChange`), which also changes when the user toggles it.
+Players before 0.5.2 reject it with `invalid`: set
+`"minPlayerVersion": "0.5.2"` when you use it.
 
 ```ts
-type HostAction = "play-pause" | "stop" | "previous" | "next" | "frame-back" | "frame-forward" | "seek-backward" | "seek-forward" | "rate-down" | "rate-up" | "rate-normal" | "volume-up" | "volume-down" | "mute";
+type HostAction = "play-pause" | "stop" | "previous" | "next" | "frame-back" | "frame-forward" | "seek-backward" | "seek-forward" | "rate-down" | "rate-up" | "rate-normal" | "volume-up" | "volume-down" | "mute" | "fullscreen";
 ```
 
 ### Host
@@ -7434,6 +7472,15 @@ class TestHost implements Transport {
     /** The new position. */
     landed: number;
   }[];
+  /**
+   * Every seek a plugin submitted (`player.seek`, `Scrub.seek`), newest last, with the mode it asked for. The test host lands on the exact target either way (the player lands a `keyframes` seek on the last keyframe at or before it); the core's step seeks are in `coreSeeks`.
+   */
+  readonly seeks: {
+    /** The target. */
+    seconds: number;
+    /** `Scrub.seek(seconds, { keyframes: true })` (SDK 1.5.22). */
+    keyframes: boolean;
+  }[];
   /** Every `player.step`, newest last. */
   readonly steps: {
     /** `"frame"` or `"keyframe"`. */
@@ -9730,7 +9777,7 @@ From top to bottom:
 - **The window.** A fixed `width`; `Theme.bg-panel` instead of a hard-coded colour, so the background follows the player's palette.
 - **The properties.** `level` is `in-out` because both the plugin and the user change it; `label` is only written by the plugin. `level-changed` reports a drag; `reset` reports the reset buttons.
 - **The layout.** `Theme.dialog-padding` and `Theme.font-body` give the spacing and text size of the player's dialogs.
-- **`ToolTipArea`** shows its `text` after the pointer rests on its content for 600 ms.
+- **`ToolTipArea`** shows its `text` after the pointer rests on its content for about half a second (600 ms before player 0.5.2). The tip never takes a press or the keyboard focus: a click goes to the control under the pointer even while the tip shows.
 - **The sliders** are bound _two-way_ to `level` with `<=>`, so dragging one moves the other at once, inside Slint. `changed` passes the value to the plugin. A one-way binding (`value: root.level`) would be broken by Slint the first time the user moved the slider. `panel: true` is the panel style; without it, the bar style.
 - **`Button`** with `text` is a dialog button; `small: true` is the 18-pixel one.
 - **Icon buttons** have no `text`; `icon` is SVG-style path data drawn in an `icon-width` × `icon-height` box (14×12 by default). `stroked: true` draws lines instead of filling. `checked` draws the icon in the accent colour.

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.20: 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. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n> are line numbers in llms-full.txt, next to this file: every page, declaration and example.
+> @vestra-player/sdk 1.5.23: 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. Everything a plugin creates (commands, windows, panels, filters, listeners…) is a handle that is released automatically when the plugin stops. L<n> are line numbers in llms-full.txt, next to this file: every page, declaration and example.
 
 **Rules**
 
@@ -33,7 +33,7 @@ my-plugin/
 }
 ```
 
-Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2120–2183.
+Fields: `id`, `version`, `apiVersion`, `entry`, `capabilities`, `name`, `author`, `punchline`, `description`, `tags`, `icon`, `readme`, `changelog`, `sourceUrl`, `license`, `minPlayerVersion`; unknown fields and capabilities are rejected. Rules and limits: L2127–2192.
 
 **main.ts**
 
@@ -76,9 +76,9 @@ export default async function activate(plugin: Plugin) {
 - `ui.settings`: Settings.page/show
 - `ui.theme`: Appearance.set/setLanguage
 - `secrets`: Secrets.get/set/delete
-- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme and packages.list. Details: L2184–2226.
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme and packages.list. Details: L2193–2235.
 
-**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` is a TestHost (an in-memory player): `host.setSource(…)`, `host.command(id).run()`, `host.press(key)`, `await host.settle()`, then assert on `host.osd`, `host.window(id).props`… Guide: L1606–1771; TestHost: L6845.
+**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` is a TestHost (an in-memory player): `host.setSource(…)`, `host.command(id).run()`, `host.press(key)`, `await host.settle()`, then assert on `host.osd`, `host.window(id).props`… Guide: L1613–1778; TestHost: L6883.
 
 **Command line**
 
@@ -106,39 +106,39 @@ 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 or another `apiVersion`
-- Others: PluginError, llms-full.txt L3122.
+- Others: PluginError, llms-full.txt L3134.
 
 ## Reference
 
 - [llms-full.txt](https://vestrasys.github.io/vestra-player-sdk/llms-full.txt), also node_modules/@vestra-player/sdk/llms-full.txt; the pages are on the [site](https://vestrasys.github.io/vestra-player-sdk/).
 - Tutorials: Getting started L9–214
-- Concepts: How a plugin runs L215–364; Commands, menus and key bindings L365–462; Playback state, controls and sources L463–602; Video and audio processing L603–680; Windows, panels, settings pages, dialogs and the OSD L681–968
-- How-to: Keep a slider responsive while dragging L969–1143; Remember a window's state between runs L1144–1273; Translate a plugin L1274–1457; Migrate a plugin to English source text L1458–1605; Test a plugin L1606–1771; Publish a plugin L1772–1860; Migrating off package rollback (1.5.16, removed in 1.5.17) L1861–1936
-- Guidelines: Interface guidelines L1937–2021; Menu guidelines L2022–2119
-- Reference: Manifest L2120–2183; Capabilities L2184–2226; Limits L2227–2321; Commands, menus and bindings L2322–2789; Platforms L2790–2818; Theme L2819–3023; Command line L3024–3079
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3080–6680
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6681–8045
+- Concepts: How a plugin runs L215–364; Commands, menus and key bindings L365–462; Playback state, controls and sources L463–608; Video and audio processing L609–686; Windows, panels, settings pages, dialogs and the OSD L687–975
+- How-to: Keep a slider responsive while dragging L976–1150; Remember a window's state between runs L1151–1280; Translate a plugin L1281–1464; Migrate a plugin to English source text L1465–1612; Test a plugin L1613–1778; Publish a plugin L1779–1867; Migrating off package rollback (1.5.16, removed in 1.5.17) L1868–1943
+- Guidelines: Interface guidelines L1944–2028; Menu guidelines L2029–2126
+- Reference: Manifest L2127–2192; Capabilities L2193–2235; Limits L2236–2330; Commands, menus and bindings L2331–2799; Platforms L2800–2828; Theme L2829–3035; Command line L3036–3091
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3092–6718
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6719–8092
 
 ## API
 
 Where each module of `plugin` (`plugin.<module>`) is declared:
 
-- Plugin L3314, Scope L3183, PluginError L3122, Disposable L3095
-- Commands L3526; Windows L3756; Panels L4399; Dialogs L4685; Player L5133; video: VideoFilter L5433, VideoView L5496, RenderOptions L5538; audio: AudioFilter L5457; Subtitles L5636; media: MediaCapture L5796; Resolvers L5901; Packages L6143; Osd L5369; Host L5300; Clipboard L6275; Power L6295; Tools L6328; Storage L6371; System L6394; Secrets L6412; window: MainWindow L4522; App L4603; Bindings L6245; Ui L3631; Timeline L4479; Drops L4055; Appearance L4084; I18n L4226; Settings L4332.
+- Plugin L3326, Scope L3195, PluginError L3134, Disposable L3107
+- Commands L3538; Windows L3768; Panels L4411; Dialogs L4697; Player L5164; video: VideoFilter L5471, VideoView L5534, RenderOptions L5576; audio: AudioFilter L5495; Subtitles L5674; media: MediaCapture L5834; Resolvers L5939; Packages L6181; Osd L5407; Host L5338; Clipboard L6313; Power L6333; Tools L6366; Storage L6409; System L6432; Secrets L6450; window: MainWindow L4534; App L4615; Bindings L6283; Ui L3643; Timeline L4491; Drops L4067; Appearance L4096; I18n L4238; Settings L4344.
 
 ## 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. L8469–8558
-- blur: A tool window with one slider that blurs the playing video. L8559–8820
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L8821–9153
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9154–9338
-- panel-menu: A sidebar panel with its own right-click menu. L9339–9544
-- menus: Radio menu items, separator groups and a menu item whose title changes. L9545–9704
-- theme-widgets: A tool window drawn with the player's theme and widgets. L9705–9868
-- markdown: A window that shows a Markdown document. L9869–10063
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L10064–10231
+- hello: The README Quick start: one menu command and an on-screen message. L8516–8605
+- blur: A tool window with one slider that blurs the playing video. L8606–8867
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L8868–9200
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9201–9385
+- panel-menu: A sidebar panel with its own right-click menu. L9386–9591
+- menus: Radio menu items, separator groups and a menu item whose title changes. L9592–9751
+- theme-widgets: A tool window drawn with the player's theme and widgets. L9752–9915
+- markdown: A window that shows a Markdown document. L9916–10110
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L10111–10278
 
 ## Optional
 

package/package.json

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

package/slint/vestra/icons.slint

@@ -45,6 +45,9 @@ export global Icons {
         if name == "add" { return "M 5 1.5 V 8.5 M 1.5 5 H 8.5"; }
         if name == "remove" { return "M 1.5 5 H 8.5"; }
         if name == "sort" { return "M 3 1.5 V 8.5 M 1.2 6.7 L 3 8.5 L 4.8 6.7 M 7 8.5 V 1.5 M 5.2 3.3 L 7 1.5 L 8.8 3.3"; }
+        // Four corners pointing out (enter) or in (leave), the default 14 × 12 box.
+        if name == "fullscreen" { return "M 1.5 4.5 V 1.5 H 4.5 M 9.5 1.5 H 12.5 V 4.5 M 12.5 7.5 V 10.5 H 9.5 M 4.5 10.5 H 1.5 V 7.5"; }
+        if name == "exit-fullscreen" { return "M 4.5 1.5 V 4.5 H 1.5 M 9.5 1.5 V 4.5 H 12.5 M 12.5 7.5 H 9.5 V 10.5 M 1.5 7.5 H 4.5 V 10.5"; }
         return "";
     }
     // Line width.

package/slint/vestra/widgets.slint

@@ -5,15 +5,20 @@
 import { TextEdit } from "std-widgets.slint";
 import { Theme } from "theme.slint";
 
-// Hover for 600 ms to show `text` beside the pointer. The tip closes when
-// the pointer leaves or presses; it shows again on the next hover.
+// Hover for about half a second to show `text` beside the pointer. The tip
+// closes when the pointer leaves, or presses on content that does not take
+// the press itself; it shows again on the next hover. It is Slint's
+// input-transparent tooltip: every press reaches the control under the
+// pointer, and the tip does not take the keyboard focus. (Up to SDK 1.5.20 the tip was a
+// PopupWindow, which swallowed the first press after it showed and took the
+// focus while it was open.)
 export component ToolTipArea {
     in property <string> text;
-    // The tip is showing (read-only).
+    // The tip is showing (read-only); it follows the tip's delay closely,
+    // not exactly.
     out property <bool> showing;
-    // Shown (or pressed) during this hover: wait for the pointer to leave.
-    // (Never assign the timer's `running`: that drops its binding, and the
-    // tip would show only once.)
+    // Pressed during this hover: no tip until the pointer leaves.
+    // (Never assign the timer's `running`: that drops its binding.)
     private property <bool> done;
     area := TouchArea {
         width: 100%; height: 100%;
@@ -22,40 +27,24 @@ export component ToolTipArea {
             if !self.has-hover {
                 root.done = false;
                 root.showing = false;
-                tip.close();
             }
         }
         pointer-event(event) => {
             if event.kind == PointerEventKind.down {
                 root.done = true;
                 root.showing = false;
-                tip.close();
             }
         }
-    }
-    Timer {
-        interval: 600ms;
-        running: area.has-hover && root.text != "" && !root.done;
-        triggered => {
-            root.done = true;
-            root.showing = true;
-            tip.show();
+        // Removing it closes an open tip.
+        if root.text != "" && !root.done: Tooltip {
+            // Interpolated text is plain: `*` or `_` in it are not markup.
+            text: @markdown("\{root.text}");
         }
     }
-    tip := PopupWindow {
-        x: area.mouse-x + 12px;
-        y: area.mouse-y + 16px;
-        close-policy: close-on-click-outside;
-        Rectangle {
-            background: Theme.bg-panel;
-            border-color: Theme.line;
-            border-width: 1px;
-            border-radius: Theme.radius-control;
-            HorizontalLayout {
-                padding-left: 5px; padding-right: 5px; padding-top: 2px; padding-bottom: 2px;
-                Text { text: root.text; color: Theme.text; font-size: Theme.font-body; }
-            }
-        }
+    Timer {
+        interval: 500ms;
+        running: area.has-hover && root.text != "" && !root.done && !root.showing;
+        triggered => { root.showing = true; }
     }
 }