@vestra-player/sdk 1.5.21 → 1.5.24

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.5.24
+
+**Who must change: nobody.** Plugins built on earlier SDKs keep working unchanged: `when: "interlaced"` and `when: "all"` do what they did. Additive; `apiVersion` stays `vestra/1`. The addition needs player 0.5.4.
+
+- **`VideoNode` `{ kind: "deinterlace", when: "auto", output: "field" }`** (player 0.5.4; requested by the video plugin, DEINT-AUTO-1: user ruling of 2026-10-27, Auto deinterlacing must cost nothing on progressive files). The player's own deinterlacer instead of BWDIF in the chain: decided per frame from the decoder's interlaced flag, with the decoder's hardware deinterlacer where frames stay on the GPU, one output frame per field; progressive frames pass untouched. It needs no frames in memory, so a chain with only this node keeps zero-copy hardware decoding, where any other node switches to a copy back to memory. It runs before every plugin's chain wherever it is written, and it is shared: on while any plugin's chain has one, off when the last one is removed or its plugin stops. `output: "frame"` with it, or another `deinterlace` node in the same chain, fails with `invalid`. Processed snapshots and exports deinterlace the same frames with BWDIF at field rate. Players before 0.5.4 refuse `auto` with `invalid`, so set `"minPlayerVersion": "0.5.4"`.
+- **`TestHost`** validates the new value as the player does (`nodeProblem`).
+- Docs: *Processing* (ordering and side effects). `llms.txt` and `llms-full.txt` regenerated.
+
+## 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`.

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/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. */
@@ -3067,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.

package/dist/processing.d.ts

@@ -102,13 +102,35 @@ export type VideoNode =
     /** Mirror vertically. */
     flipV: boolean;
 }
-/** BWDIF; `field` doubles the frame rate. */
+/**
+ * Deinterlacing. `interlaced` and `all` are FFmpeg BWDIF in the chain;
+ * `field` doubles the frame rate.
+ *
+ * `when: "auto"` (player 0.5.4) is the player's own deinterlacer instead:
+ * decided per frame from the decoder's interlaced flag, with the decoder's
+ * hardware deinterlacer where frames stay on the GPU; progressive frames
+ * pass untouched. It needs no frames in memory, so a chain with only this
+ * node keeps zero-copy hardware decoding (any other node still needs a
+ * copy back to memory). It always outputs one frame per field, so it
+ * takes `output: "field"` only (`"frame"` fails with `invalid`). It runs
+ * before every plugin's chain wherever it is written, and is shared: on
+ * while any plugin's chain has one. A chain with it has no other
+ * `deinterlace` node. Snapshots and exports deinterlace the same frames
+ * with BWDIF at field rate. Players before 0.5.4 refuse `auto` with
+ * `invalid`.
+ */
  | {
     /** The node type. */
     kind: "deinterlace";
-    /** `interlaced`: only frames flagged interlaced; `all`: every frame. */
-    when: "interlaced" | "all";
-    /** One frame per frame, or one per field (double rate). */
+    /**
+     * `interlaced`: only frames flagged interlaced; `all`: every frame;
+     * `auto`: the player's deinterlacer, on frames flagged interlaced.
+     */
+    when: "interlaced" | "all" | "auto";
+    /**
+     * One frame per frame, or one per field (double rate); `when: "auto"`
+     * takes `field` only.
+     */
     output: "frame" | "field";
 }
 /** Crop to / pad to a display aspect; x, y place it (−1 left/top … 1 right/bottom). */

package/dist/processing.js

@@ -19,7 +19,10 @@ const RULES = {
     deblock: { strength: ["weak", "strong"] },
     deband: { threshold: [0.003, 0.5], range: [1, 64] },
     transform: { rotate: [0, 90, 180, 270], flipH: BOOL, flipV: BOOL },
-    deinterlace: { when: ["interlaced", "all"], output: ["frame", "field"] },
+    deinterlace: {
+        when: ["interlaced", "all", "auto"],
+        output: ["frame", "field"],
+    },
     reframe: { mode: ["crop", "pad"], aspect: [0.25, 4], x: [-1, 1], y: [-1, 1] },
     frameBlend: { fps: [24, 120] },
     volume: { gainDb: [-60, 0] },
@@ -73,7 +76,15 @@ export function nodeProblem(stage, nodes) {
         if (node.kind === "frameBlend" &&
             !Number.isInteger(node.fps))
             return "frameBlend.fps must be an integer";
+        if (node.kind === "deinterlace" &&
+            node.when === "auto" &&
+            node.output !== "field")
+            return "deinterlace when auto outputs one frame per field: output must be field";
     }
+    const deinterlace = nodes.filter((node) => node.kind === "deinterlace");
+    if (deinterlace.length > 1 &&
+        deinterlace.some((node) => node.when === "auto"))
+        return "a chain with a deinterlace node when auto has no other deinterlace node";
     if (nodes.filter((node) => node.kind === "frameBlend").length > 1)
         return "only one frameBlend node across all plugins";
     return null;

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.21: full reference
+# @vestra-player/sdk 1.5.24: 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.
 
@@ -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
 
@@ -585,10 +585,12 @@ The difference from the `Player` methods: a `Player` control is a precise operat
 
 ##### 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
 
@@ -661,7 +667,8 @@ How smoothly the change shows depends on the field. Some fields, marked **live**
 
 - Video nodes act on the picture after the player has applied the container's rotation, so a portrait video is upright before a plugin's `transform` rotates it.
 - `frameBlend` (frame-rate conversion by blending) always runs **last**, after every plugin's chain, wherever it is written, so temporal filters such as denoise and deinterlace still see the original frames. It changes the frame rate of exports too, and costs a lot of CPU: decide from `stats()` whether to offer it.
-- Filters need frames in memory. While any plugin has a video chain, the player decodes in hardware with a copy back to memory instead of zero-copy decoding; when the last chain is removed it switches back. The decoder restarts at each switch, so the picture may pause briefly. stats().video.hwdec shows the decoder in use.
+- Filters need frames in memory. While any plugin has a video chain, the player decodes in hardware with a copy back to memory instead of zero-copy decoding; when the last chain is removed it switches back. The decoder restarts at each switch, so the picture may pause briefly. stats().video.hwdec shows the decoder in use. The one exception is the next item.
+- `{ kind: "deinterlace", when: "auto", output: "field" }` (player 0.5.4) is not a filter in the chain but the player's own deinterlacer. The player decides per frame: frames flagged interlaced are deinterlaced, at one frame per field, by the decoder's hardware deinterlacer where frames stay on the GPU (BWDIF otherwise); progressive frames pass untouched. It needs no frames in memory, so a chain with only this node keeps zero-copy decoding: this is the node for an "Auto" setting that must cost nothing on progressive files. It runs **first**, before every plugin's chain, wherever it is written, and it is shared: it stays on while any plugin's chain has one. `output: "frame"` fails with `invalid`, and so does another `deinterlace` node in the same chain; use `when: "interlaced"` (BWDIF in the chain, with a copy back to memory) for frame-rate output. Snapshots and exports deinterlace the same frames with BWDIF at field rate.
 
 #### The display layer
 
@@ -960,6 +967,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
@@ -2177,6 +2185,7 @@ The table lists the API whose documentation names a player version, newest last:
 | 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).
 
@@ -4948,8 +4957,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`. */
@@ -5238,10 +5266,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.
@@ -6533,13 +6562,29 @@ type VideoNode =
   /** Mirror vertically. */
   flipV: boolean;
 }
-/** BWDIF; `field` doubles the frame rate. */
+/**
+ * Deinterlacing. `interlaced` and `all` are FFmpeg BWDIF in the chain;
+ * `field` doubles the frame rate.
+ *
+ * `when: "auto"` (player 0.5.4) is the player's own deinterlacer instead:
+ * decided per frame from the decoder's interlaced flag, with the decoder's
+ * hardware deinterlacer where frames stay on the GPU; progressive frames
+ * pass untouched. It needs no frames in memory, so a chain with only this
+ * node keeps zero-copy hardware decoding (any other node still needs a
+ * copy back to memory). It always outputs one frame per field, so it
+ * takes `output: "field"` only (`"frame"` fails with `invalid`). It runs
+ * before every plugin's chain wherever it is written, and is shared: on
+ * while any plugin's chain has one. A chain with it has no other
+ * `deinterlace` node. Snapshots and exports deinterlace the same frames
+ * with BWDIF at field rate. Players before 0.5.4 refuse `auto` with
+ * `invalid`.
+ */
  | {
   /** The node type. */
   kind: "deinterlace";
-  /** `interlaced`: only frames flagged interlaced; `all`: every frame. */
-  when: "interlaced" | "all";
-  /** One frame per frame, or one per field (double rate). */
+  /** `interlaced`: only frames flagged interlaced; `all`: every frame; `auto`: the player's deinterlacer, on frames flagged interlaced. */
+  when: "interlaced" | "all" | "auto";
+  /** One frame per frame, or one per field (double rate); `when: "auto"` takes `field` only. */
   output: "frame" | "field";
 }
 /** Crop to / pad to a display aspect; x, y place it (−1 left/top … 1 right/bottom). */
@@ -7444,6 +7489,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"`. */

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.21: 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.24: 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–2184.
+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: L2128–2193.
 
 **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: L2185–2227.
+- No capability: `tools`, `storage`, `system`, `app`, `ui` (images and Markdown), `i18n`, reading window.state, appearance.theme and packages.list. Details: L2194–2236.
 
-**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: L6855.
+**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: L1614–1779; TestHost: L6900.
 
 **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 L3126.
+- Others: PluginError, llms-full.txt L3135.
 
 ## 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–2184; Capabilities L2185–2227; Limits L2228–2322; Commands, menus and bindings L2323–2791; Platforms L2792–2820; Theme L2821–3027; Command line L3028–3083
-- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3084–6690
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6691–8055
+- 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–687; Windows, panels, settings pages, dialogs and the OSD L688–976
+- How-to: Keep a slider responsive while dragging L977–1151; Remember a window's state between runs L1152–1281; Translate a plugin L1282–1465; Migrate a plugin to English source text L1466–1613; Test a plugin L1614–1779; Publish a plugin L1780–1868; Migrating off package rollback (1.5.16, removed in 1.5.17) L1869–1944
+- Guidelines: Interface guidelines L1945–2029; Menu guidelines L2030–2127
+- Reference: Manifest L2128–2193; Capabilities L2194–2236; Limits L2237–2331; Commands, menus and bindings L2332–2800; Platforms L2801–2829; Theme L2830–3036; Command line L3037–3092
+- [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L3093–6735
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html): L6736–8109
 
 ## API
 
 Where each module of `plugin` (`plugin.<module>`) is declared:
 
-- Plugin L3318, Scope L3187, PluginError L3126, Disposable L3099
-- Commands L3530; Windows L3760; Panels L4403; Dialogs L4689; Player L5137; video: VideoFilter L5443, VideoView L5506, RenderOptions L5548; audio: AudioFilter L5467; Subtitles L5646; media: MediaCapture L5806; Resolvers L5911; Packages L6153; Osd L5379; Host L5310; Clipboard L6285; Power L6305; Tools L6338; Storage L6381; System L6404; Secrets L6422; window: MainWindow L4526; App L4607; Bindings L6255; Ui L3635; Timeline L4483; Drops L4059; Appearance L4088; I18n L4230; Settings L4336.
+- Plugin L3327, Scope L3196, PluginError L3135, Disposable L3108
+- Commands L3539; Windows L3769; Panels L4412; Dialogs L4698; Player L5165; video: VideoFilter L5472, VideoView L5535, RenderOptions L5577; audio: AudioFilter L5496; Subtitles L5675; media: MediaCapture L5835; Resolvers L5940; Packages L6182; Osd L5408; Host L5339; Clipboard L6314; Power L6334; Tools L6367; Storage L6410; System L6433; Secrets L6451; window: MainWindow L4535; App L4616; Bindings L6284; Ui L3644; Timeline L4492; Drops L4068; Appearance L4097; I18n L4239; Settings L4345.
 
 ## 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. L8479–8568
-- blur: A tool window with one slider that blurs the playing video. L8569–8830
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L8831–9163
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9164–9348
-- panel-menu: A sidebar panel with its own right-click menu. L9349–9554
-- menus: Radio menu items, separator groups and a menu item whose title changes. L9555–9714
-- theme-widgets: A tool window drawn with the player's theme and widgets. L9715–9878
-- markdown: A window that shows a Markdown document. L9879–10073
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L10074–10241
+- hello: The README Quick start: one menu command and an on-screen message. L8533–8622
+- blur: A tool window with one slider that blurs the playing video. L8623–8884
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L8885–9217
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L9218–9402
+- panel-menu: A sidebar panel with its own right-click menu. L9403–9608
+- menus: Radio menu items, separator groups and a menu item whose title changes. L9609–9768
+- theme-widgets: A tool window drawn with the player's theme and widgets. L9769–9932
+- markdown: A window that shows a Markdown document. L9933–10127
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L10128–10295
 
 ## Optional
 

package/package.json

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