@vestra-player/sdk 1.5.18 → 1.5.21

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 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.
+
+## 1.5.19
+
+Images in list rows, restarting a plugin, and keyframe step seeks (player 0.5.1). Additive; `apiVersion` stays `vestra/1`, and plugins that do not use the new members need no change. Requested by the plugin store (STORE-ROW-LOGO, STORE-RELOAD-BUILTIN) and the playback plugin (keyframe seeks); the online video plugins' search results need the same row images.
+
+- **`ImageRef` at any depth** (`PropData` includes `ImageRef`): an image from `ui.image` goes wherever the Slint type is `image`, also a field of a struct or a row of a model, for example `rows: [{ key, name, icon: plugin.ui.image(path) }]` with `struct Row { key: string, name: string, icon: image }`. Players before 0.5.1 refuse a nested image with `invalid`, as the SDK did until now. A nested image whose file fails the player's checks is drawn empty and the rest of the value is shown; a released image is refused at any depth. Rows with images update in place in the player (a `ListView` keeps its scroll position).
+- **`ui.image(path, { maxSide })`** and the new **`ImageOptions`**: decode the image scaled down, aspect kept, so that neither side is over `maxSide` (1–4096). Use about twice the drawn size for logos and thumbnails. Players before 0.5.1 refuse a reference with `maxSide`; without it the wire form is unchanged.
+- **Per-view image budget** (player 0.5.1): the images nested in one view's values may show at most 32 MB of decoded pixels together; a write past it is refused with `limit`. **`IMAGE_LIMITS`** (`@vestra-player/sdk/runtime` and `/testing`) lists the player's image limits.
+- **`ui.remoteImage(url, options?)`**: downloads an `https:` PNG or JPEG into `<dataDirectory>/.vestra-cache/images/` with the Markdown image rules (4 MB, 10 s, 4 at a time per plugin, a 32 MB cache refreshed after a day) and resolves with an `ImageRef`; rejects `unavailable` when the download fails. Works with any player; nested, with 0.5.1.
+- **`Packages.reload(id)`** (`plugins.manage`, player 0.5.1): stop a plugin and start it again from the same package with the same data, built-ins included; a stopped or failed one is just started. The disabled flag is never written. `invalid` for oneself or a disabled plugin, `missing` unknown, `busy` while it is being installed or reloaded; `packages.onChange` shows `starting`, then `running` or `failed`. Listed in `CAPABILITY_INFO["plugins.manage"].apis`.
+- **`Player.setStepSeek({ seconds, keyframes })`** (player 0.5.1): with `keyframes: true` the step seeks land on a keyframe (forward at or after position + step, backward at or before position − step, always moving), presses during a seek add up from the landed position, and 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. A non-boolean `keyframes` is `invalid`.
+- **`Host.run("seek-backward" | "seek-forward", { seconds })`** (player 0.5.1): one step seek of another step, with the core's checks, mode, accumulation and text. In keyframe mode it resolves once the seek has landed. `seconds` with another action, or outside 0.1–3600 in tenths, is `invalid`. Older players ignore `seconds`: set `"minPlayerVersion": "0.5.1"`.
+- **`TestHost`**: nested images are recorded in `host.images` (with `maxSide`); `ui.remoteImage` is served from `host.remoteImages`; `packages.reload` is modelled (`starting`, then `running`; `packageCalls` method `"reload"`); `stepSeekKeyframes`, the test data `keyframes` and the log `coreSeeks` model keyframe step seeks, and `host.run` takes `seconds`. The test host lands each press at once (the player completes presses that add up together, with one text).
+- Docs: *Windows, panels, settings pages* (images in rows), *Playback* (Step seeks: exact or keyframe); `llms.txt` and `llms-full.txt` regenerated.
+
 ## 1.5.18
 
 Fixes for Windows and for a vendored SDK, and built-ins that can no longer be disabled. `apiVersion` stays `vestra/1`; plugins that do not manage other plugins need no change.

package/dist/capabilities.js

@@ -131,6 +131,7 @@ export const CAPABILITY_INFO = Object.freeze({
             "Packages.validate",
             "Packages.validateArchive",
             "Packages.setEnabled",
+            "Packages.reload",
             "Packages.uninstall",
         ],
         requires: [],

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
@@ -401,7 +401,6 @@ vestra.preferences | options | Settings ▸ Options… | F5
 vestra.hotkeys | keys | Settings ▸ Keyboard Shortcuts…
 vestra.hotkeys | mouse | Settings ▸ Mouse…
 vestra.hotkeys | ignore-defaults | Settings ▸ Ignore Default Shortcuts
-vestra.plugins | manage | Settings ▸ Plugin Manager…
 vestra.preferences | theme.vestra | Settings ▸ Appearance ▸ Vestra Dark
 vestra.preferences | theme.vestra-light | Settings ▸ Appearance ▸ Vestra Light
 vestra.visualizer | idle-logo | Settings ▸ Appearance ▸ Show Logo When Idle

package/dist/player-runtime.d.ts

@@ -20,4 +20,4 @@ export { THEME_PALETTES } from "./palettes.ts";
 export { Catalog, HOST_ZH_HANS, LIST_SEPARATORS, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, renderText, scanSlint, TEXT_LIMITS, textKey, textProblem, } from "./i18n.ts";
 export { MANIFEST_FIELDS, MANIFEST_LIMITS } from "./manifest.ts";
 export { MARKDOWN_LIMITS } from "./plugin/markdown.ts";
-export { UI_VALUE_LIMITS } from "./plugin/values.ts";
+export { IMAGE_LIMITS, UI_VALUE_LIMITS } from "./plugin/values.ts";

package/dist/player-runtime.js

@@ -18,4 +18,4 @@ export { THEME_PALETTES } from "./palettes.js";
 export { Catalog, HOST_ZH_HANS, LIST_SEPARATORS, LOCALES, MENU_KEYS, matchLocale, parsePo, rewriteSlint, renderText, scanSlint, TEXT_LIMITS, textKey, textProblem, } from "./i18n.js";
 export { MANIFEST_FIELDS, MANIFEST_LIMITS } from "./manifest.js";
 export { MARKDOWN_LIMITS } from "./plugin/markdown.js";
-export { UI_VALUE_LIMITS } from "./plugin/values.js";
+export { IMAGE_LIMITS, UI_VALUE_LIMITS } from "./plugin/values.js";

package/dist/plugin/markdown.d.ts

@@ -1,4 +1,5 @@
 import type { Json } from "../wire.ts";
+import type { Runtime } from "./runtime.ts";
 import type { ScopeImpl } from "./scope.ts";
 import type { MarkdownOptions, MarkdownRef } from "./types.ts";
 export declare const MARKDOWN_LIMITS: Readonly<{
@@ -37,4 +38,10 @@ export declare function httpsDownload(url: string, options: {
     maxBytes: number;
     signal: AbortSignal;
 }, fetchImpl?: typeof fetch): Promise<Uint8Array>;
+/**
+ * `ui.remoteImage`: the local copy of an `https:` image in
+ * `<dataDirectory>/.vestra-cache/images/` (the Markdown limits: 4 MB, 10 s,
+ * 4 at a time per plugin, 32 MB of cache, a day). Rejects `unavailable`.
+ */
+export declare function remoteImageFile(runtime: Runtime, url: string): Promise<string>;
 export declare function markdown(scope: ScopeImpl, text: string, options?: MarkdownOptions): Promise<MarkdownRef>;

package/dist/plugin/markdown.js

@@ -113,33 +113,12 @@ async function fetchImages(runtime, urls) {
         return {};
     const cache = join(data, ".vestra-cache", "markdown");
     await mkdir(cache, { recursive: true });
-    const download = runtime.local?.download ?? httpsDownload;
     const found = {};
     const queue = [...new Set(urls)].filter((u) => u.startsWith("https://"));
     const worker = async () => {
         for (let url = queue.shift(); url !== undefined; url = queue.shift()) {
-            const file = join(cache, createHash("sha256").update(url).digest("hex"));
             try {
-                const info = await stat(file).catch(() => null);
-                const now = Date.now();
-                if (info && now - info.mtimeMs < MARKDOWN_LIMITS.cacheMaxAgeMs) {
-                    const time = new Date(info.mtimeMs);
-                    await utimes(file, new Date(now), time).catch(() => { });
-                    found[url] = file;
-                    continue;
-                }
-                const bytes = await download(url, {
-                    maxBytes: MARKDOWN_LIMITS.imageBytes,
-                    signal: AbortSignal.timeout(MARKDOWN_LIMITS.imageTimeoutMs),
-                });
-                if (bytes.length > MARKDOWN_LIMITS.imageBytes)
-                    throw new Error("image too large");
-                if (!isPng(bytes) && !isJpeg(bytes))
-                    throw new Error("not a PNG or JPEG image");
-                const temporary = `${file}.${process.pid}.tmp`;
-                await writeFile(temporary, bytes);
-                await rename(temporary, file);
-                found[url] = file;
+                found[url] = (await cached(runtime, cache, url)).file;
             }
             catch {
                 // Shown as its alt text.
@@ -150,6 +129,67 @@ async function fetchImages(runtime, urls) {
     await trim(cache, new Set(Object.values(found)));
     return found;
 }
+/**
+ * The cached copy of `url` in `cache`, downloaded when missing or older than
+ * a day; throws why it could not be had. `fresh`: it was downloaded now.
+ */
+async function cached(runtime, cache, url) {
+    const file = join(cache, createHash("sha256").update(url).digest("hex"));
+    const info = await stat(file).catch(() => null);
+    const now = Date.now();
+    if (info && now - info.mtimeMs < MARKDOWN_LIMITS.cacheMaxAgeMs) {
+        const time = new Date(info.mtimeMs);
+        await utimes(file, new Date(now), time).catch(() => { });
+        return { file, fresh: false };
+    }
+    const download = runtime.local?.download ?? httpsDownload;
+    const bytes = await download(url, {
+        maxBytes: MARKDOWN_LIMITS.imageBytes,
+        signal: AbortSignal.timeout(MARKDOWN_LIMITS.imageTimeoutMs),
+    });
+    if (bytes.length > MARKDOWN_LIMITS.imageBytes)
+        throw new Error("image too large");
+    if (!isPng(bytes) && !isJpeg(bytes))
+        throw new Error("not a PNG or JPEG image");
+    const temporary = `${file}.${process.pid}.tmp`;
+    await writeFile(temporary, bytes);
+    await rename(temporary, file);
+    return { file, fresh: true };
+}
+/** `ui.remoteImage` downloads in flight and waiting, per plugin. */
+const slots = new WeakMap();
+/**
+ * `ui.remoteImage`: the local copy of an `https:` image in
+ * `<dataDirectory>/.vestra-cache/images/` (the Markdown limits: 4 MB, 10 s,
+ * 4 at a time per plugin, 32 MB of cache, a day). Rejects `unavailable`.
+ */
+export async function remoteImageFile(runtime, url) {
+    const data = runtime.dataDirectory;
+    if (!data)
+        throw failure("unavailable", "the plugin has no data directory");
+    const cache = join(data, ".vestra-cache", "images");
+    let slot = slots.get(runtime);
+    if (!slot)
+        slots.set(runtime, (slot = { active: 0, waiting: [] }));
+    const queue = slot;
+    if (queue.active >= MARKDOWN_LIMITS.concurrency)
+        await new Promise((go) => queue.waiting.push(go));
+    queue.active += 1;
+    try {
+        await mkdir(cache, { recursive: true });
+        const { file, fresh } = await cached(runtime, cache, url);
+        if (fresh)
+            await trim(cache, new Set([file]));
+        return file;
+    }
+    catch (error) {
+        throw failure("unavailable", `image ${url}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        queue.active -= 1;
+        queue.waiting.shift()?.();
+    }
+}
 /** Keep the cache under its size: drop the least recently used files not in use. */
 async function trim(cache, keep) {
     const files = [];

package/dist/plugin/packages.js

@@ -141,6 +141,11 @@ export const packages = (scope) => ({
             throw failure("invalid", "setEnabled takes an id and a boolean");
         await scope.runtime.host.packages.setEnabled(id, enabled);
     },
+    async reload(id) {
+        if (typeof id !== "string" || !id)
+            throw failure("invalid", "reload takes a plugin id");
+        await scope.runtime.host.packages.reload(id);
+    },
     uninstall: (id, options = {}) => change(scope, (requestId, revision) => scope.runtime.host.packages.uninstall(id, options.removeData === true, revision, requestId), id),
 });
 const info = (plugin) => Object.freeze({

package/dist/plugin/player.d.ts

@@ -4,6 +4,8 @@ import type { Runtime } from "./runtime.ts";
 import type { ScopeImpl } from "./scope.ts";
 import type { Conditional, Disposable, Player, PlayerState, PluginError } from "./types.ts";
 export declare const rawOf: (state: PlayerState) => SourceState | undefined;
+/** A step-seek length the player accepts: 0.1–3600 seconds in tenths. */
+export declare const validStep: (seconds: unknown) => seconds is number;
 export declare const sameStamp: (a: SourceStamp, b: SourceStamp) => boolean;
 export declare function abortError(): PluginError;
 /** One per plugin: the state store and the operation book client. */

package/dist/plugin/player.js

@@ -88,6 +88,12 @@ function decoding(hwdec) {
     return hwdec === "no" ? "software" : "hardware";
 }
 export const rawOf = (state) => raws.get(state);
+/** A step-seek length the player accepts: 0.1–3600 seconds in tenths. */
+export const validStep = (seconds) => typeof seconds === "number" &&
+    Number.isFinite(seconds) &&
+    seconds >= 0.1 &&
+    seconds <= 3600 &&
+    Math.abs(Math.round(seconds * 10) - seconds * 10) <= 1e-9;
 export const sameStamp = (a, b) => a.generation === b.generation && a.intentVersion === b.intentVersion;
 function sourceFailure(error) {
     return typeof error === "string"
@@ -529,13 +535,12 @@ export function player(scope) {
                 .refresh()
                 .catch(() => { });
         },
-        async setStepSeek({ seconds }) {
-            if (!Number.isFinite(seconds) ||
-                seconds < 0.1 ||
-                seconds > 3600 ||
-                Math.abs(Math.round(seconds * 10) - seconds * 10) > 1e-9)
+        async setStepSeek({ seconds, keyframes }) {
+            if (!validStep(seconds))
                 throw failure("invalid", "seconds must be 0.1–3600 in tenths");
-            await scope.runtime.host.step.setStepSeek(seconds);
+            if (keyframes !== undefined && typeof keyframes !== "boolean")
+                throw failure("invalid", "keyframes must be a boolean");
+            await scope.runtime.host.step.setStepSeek(seconds, keyframes);
         },
         async audioDevices() {
             const devices = await scope.runtime.host.audioOutput.devices();

package/dist/plugin/services.js

@@ -8,7 +8,7 @@ import { mkdir, open, rename, rm, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { failure } from "./runtime.js";
 import { systemServices } from "./local.js";
-import { playerOf } from "./player.js";
+import { playerOf, validStep } from "./player.js";
 const MAX_OUTPUT = 16 * 1024 * 1024;
 export const clipboard = (scope) => ({
     readText: () => scope.runtime.host.clipboard.readText(),
@@ -30,12 +30,20 @@ const ACTIONS = new Set([
     "volume-up",
     "volume-down",
     "mute",
+    "fullscreen",
 ]);
 export const host = (scope) => ({
-    async run(action) {
+    async run(action, options) {
         if (!ACTIONS.has(action))
             throw failure("invalid", `unknown host action ${String(action)}`);
-        await scope.runtime.host.host.run(action);
+        const seconds = options?.seconds;
+        if (options !== undefined) {
+            if (action !== "seek-backward" && action !== "seek-forward")
+                throw failure("invalid", `seconds applies only to seek-backward and seek-forward, not ${action}`);
+            if (!validStep(seconds))
+                throw failure("invalid", "seconds must be 0.1–3600 in tenths");
+        }
+        await scope.runtime.host.host.run(action, seconds);
         // Like the player's own controls: `player.state` shows the result.
         if (scope.runtime.can("playback.read"))
             await playerOf(scope.runtime)

package/dist/plugin/testing.d.ts

@@ -10,7 +10,7 @@ import { OSD_LIMITS } from "./osd.ts";
 import { SECRET_LIMITS } from "./services.ts";
 import { BINDING_INPUTS } from "./bindings.ts";
 import { THEME_PALETTES } from "../palettes.ts";
-import { UI_VALUE_LIMITS } from "./values.ts";
+import { IMAGE_LIMITS, UI_VALUE_LIMITS } from "./values.ts";
 import type { CommandDeclaration } from "../commands.ts";
 import type { SourceState } from "../source.ts";
 import type { SubtitleState } from "../subtitles.ts";
@@ -39,7 +39,7 @@ export { BINDING_INPUTS };
 /** The colours of the player's palettes, by `Theme` token. */
 export { THEME_PALETTES };
 /** The player's property value limits, which the test host enforces as well. */
-export { UI_VALUE_LIMITS };
+export { IMAGE_LIMITS, UI_VALUE_LIMITS };
 /**
  * The player's limits on one text value ({@link Text}, {@link TextList},
  * with everything nested in it), which the test host enforces as well:
@@ -618,14 +618,19 @@ export declare class TestHost implements Transport {
         title?: string | null;
     }[]): void;
     /**
-     * Runtime images written to views (`plugin.ui.image`), newest last. The
-     * SDK refuses images of released scopes before anything is sent.
+     * Runtime images written to views (`plugin.ui.image`,
+     * `plugin.ui.remoteImage`), whole values and (SDK 1.5.19) images nested
+     * in rows, newest last. The SDK refuses images of released scopes before
+     * anything is sent. The test host does not read the files, so it does not
+     * check the player's per-view budget (`IMAGE_LIMITS.viewBytes`).
      */
     readonly images: {
         /** The image file's path, as given to `ui.image`. */
         path: string;
         /** The SDK's reference number for that `ImageRef`. */
         ref: number;
+        /** Its `maxSide` option, when given. */
+        maxSide?: number;
     }[];
     /**
      * The file an image property shows, or `null` when the value is not a
@@ -1109,6 +1114,39 @@ export declare class TestHost implements Transport {
     constructor();
     /** The `player.setStepSeek` value in effect (default 5). */
     stepSeek: number;
+    /** The `player.setStepSeek` `keyframes` in effect (default `false`, SDK 1.5.19). */
+    stepSeekKeyframes: boolean;
+    /**
+     * Test data: the keyframe times (seconds, ascending) of the current
+     * source, for keyframe step seeks. `null` (the default): none modelled,
+     * and step seeks are exact even with `stepSeekKeyframes`.
+     *
+     * @example
+     * ```ts
+     * host.setSource({ phase: "ready", duration: 45, position: 12 });
+     * host.keyframes = [0, 10, 20, 30, 40];
+     * await plugin.player.setStepSeek({ seconds: 5, keyframes: true });
+     * await plugin.host.run("seek-forward");
+     * assert.equal(host.source.position, 20);
+     * assert.equal(host.osd.at(-1), "Forward 5 s: 00:20 / 00:45");
+     * ```
+     */
+    keyframes: number[] | null;
+    /**
+     * Every step seek the core ran (`seek-backward` / `seek-forward`, from a
+     * key, the menu or `host.run`), newest last: the step, whether it went to
+     * a keyframe, and where it landed.
+     */
+    readonly coreSeeks: {
+        /** `seek-backward` or `seek-forward`. */
+        action: string;
+        /** The step: `host.run`'s `seconds`, else `setStepSeek`'s. */
+        seconds: number;
+        /** It landed on a keyframe (`stepSeekKeyframes` and keyframes modelled). */
+        keyframes: boolean;
+        /** The new position. */
+        landed: number;
+    }[];
     /** Every `player.step`, newest last. */
     readonly steps: {
         /** `"frame"` or `"keyframe"`. */
@@ -1339,7 +1377,7 @@ export declare class TestHost implements Transport {
     /** Every `packages.setEnabled` / `uninstall` / `install`, newest last. */
     readonly packageCalls: {
         /** Which call. */
-        method: "setEnabled" | "uninstall" | "install";
+        method: "setEnabled" | "reload" | "uninstall" | "install";
         /** The target plugin id. */
         id: string;
         /** `setEnabled`'s value. */
@@ -1368,9 +1406,10 @@ export declare class TestHost implements Transport {
      */
     readonly candidates: Map<string, PackageManifest>;
     /**
-     * Remote Markdown images (`plugin.ui.markdown`): address → a local PNG or
-     * JPEG file served for it, or `null` for a failing download. Nothing is
-     * fetched from the network in tests; unknown addresses fail.
+     * Remote images (`plugin.ui.markdown`, `plugin.ui.remoteImage`): address
+     * → a local PNG or JPEG file served for it, or `null` for a failing
+     * download. Nothing is fetched from the network in tests; unknown
+     * addresses fail.
      */
     readonly remoteImages: Map<string, string | null>;
     /**

package/dist/plugin/testing.js

@@ -72,7 +72,8 @@ import { OSD_LIMITS } from "./osd.js";
 import { SECRET_LIMITS } from "./services.js";
 import { BINDING_INPUTS } from "./bindings.js";
 import { THEME_PALETTES } from "../palettes.js";
-import { UI_VALUE_LIMITS, valueLimitProblem } from "./values.js";
+import { IMAGE_LIMITS, UI_VALUE_LIMITS, valueLimitProblem } from "./values.js";
+import { validStep } from "./player.js";
 import { nodeProblem } from "../processing.js";
 import { RENDER_DEFAULTS, renderProblem, VIEW_DEFAULTS, viewProblem, } from "./view.js";
 import { createPlugin } from "./index.js";
@@ -97,7 +98,7 @@ export { BINDING_INPUTS };
 /** The colours of the player's palettes, by `Theme` token. */
 export { THEME_PALETTES };
 /** The player's property value limits, which the test host enforces as well. */
-export { UI_VALUE_LIMITS };
+export { IMAGE_LIMITS, UI_VALUE_LIMITS };
 /**
  * The player's limits on one text value ({@link Text}, {@link TextList},
  * with everything nested in it), which the test host enforces as well:
@@ -625,8 +626,11 @@ export class TestHost {
         this.emit("timeline.changed", { marks: this.timeline.marks });
     }
     /**
-     * Runtime images written to views (`plugin.ui.image`), newest last. The
-     * SDK refuses images of released scopes before anything is sent.
+     * Runtime images written to views (`plugin.ui.image`,
+     * `plugin.ui.remoteImage`), whole values and (SDK 1.5.19) images nested
+     * in rows, newest last. The SDK refuses images of released scopes before
+     * anything is sent. The test host does not read the files, so it does not
+     * check the player's per-view budget (`IMAGE_LIMITS.viewBytes`).
      */
     images = [];
     /**
@@ -700,14 +704,22 @@ export class TestHost {
         return kept;
     }
     #seeImages(values) {
-        for (const value of Object.values(values)) {
+        const see = (value) => {
             const path = this.imagePath(value);
-            if (path !== null)
+            if (path !== null) {
+                const { ref, maxSide } = value;
                 this.images.push({
                     path,
-                    ref: Number(value.ref),
+                    ref: Number(ref),
+                    ...(maxSide === undefined ? {} : { maxSide }),
                 });
-        }
+            }
+            else if (value !== null && typeof value === "object")
+                for (const item of Object.values(value))
+                    see(item);
+        };
+        for (const value of Object.values(values))
+            see(value);
     }
     // ------------------------------------------------------------ round 3b batch 2
     /** `drops.provide` registrations of this plugin, in order (`id` is the SDK's). */
@@ -1241,6 +1253,30 @@ export class TestHost {
     // ------------------------------------------------------------ core actions
     /** The `player.setStepSeek` value in effect (default 5). */
     stepSeek = 5;
+    /** The `player.setStepSeek` `keyframes` in effect (default `false`, SDK 1.5.19). */
+    stepSeekKeyframes = false;
+    /**
+     * Test data: the keyframe times (seconds, ascending) of the current
+     * source, for keyframe step seeks. `null` (the default): none modelled,
+     * and step seeks are exact even with `stepSeekKeyframes`.
+     *
+     * @example
+     * ```ts
+     * host.setSource({ phase: "ready", duration: 45, position: 12 });
+     * host.keyframes = [0, 10, 20, 30, 40];
+     * await plugin.player.setStepSeek({ seconds: 5, keyframes: true });
+     * await plugin.host.run("seek-forward");
+     * assert.equal(host.source.position, 20);
+     * assert.equal(host.osd.at(-1), "Forward 5 s: 00:20 / 00:45");
+     * ```
+     */
+    keyframes = null;
+    /**
+     * Every step seek the core ran (`seek-backward` / `seek-forward`, from a
+     * key, the menu or `host.run`), newest last: the step, whether it went to
+     * a keyframe, and where it landed.
+     */
+    coreSeeks = [];
     /** Every `player.step`, newest last. */
     steps = [];
     /** Every core action run (`host.run`, a core command, a pressed core binding), newest last. */
@@ -1339,7 +1375,7 @@ export class TestHost {
                 ["Playback", "Play/Pause"],
                 201,
                 "domain",
-                ["Space"],
+                ["Space", "Mouse:LeftClick"],
                 false,
             ],
             [
@@ -1470,7 +1506,7 @@ export class TestHost {
             this.coreCommands.set(`host/${id}`, command);
         }
     }
-    #runCore(action) {
+    #runCore(action, seconds) {
         const state = this.#coreState(action);
         if (!state.enabled)
             throw new HostError("unavailable", state.reason ?? "unavailable");
@@ -1512,13 +1548,36 @@ export class TestHost {
                 return;
             case "seek-backward":
             case "seek-forward": {
-                const delta = action === "seek-forward" ? this.stepSeek : -this.stepSeek;
+                const step = seconds ?? this.stepSeek;
+                const delta = action === "seek-forward" ? step : -step;
                 const base = s.position ?? 0;
-                const target = Math.max(0, Math.min(s.duration ?? Infinity, base + delta));
+                let target = Math.max(0, Math.min(s.duration ?? Infinity, base + delta));
+                // Keyframe mode, as the player: forward on the first keyframe at or
+                // after the target (none: the exact target), backward on the last at
+                // or before it; only sources with moving video that can seek.
+                const keyframes = this.stepSeekKeyframes &&
+                    this.keyframes !== null &&
+                    s.hasVideo !== false &&
+                    s.capabilities.seek;
+                if (keyframes && target !== base) {
+                    const keys = this.keyframes;
+                    target =
+                        delta > 0
+                            ? (keys.find((k) => k >= target) ?? target)
+                            : keys
+                                .filter((k) => k <= target)
+                                .reduce((a, k) => Math.max(a, k), 0);
+                }
                 this.#intent({
                     kind: "control",
                     control: { kind: "seek", seconds: target },
                 });
+                this.coreSeeks.push({
+                    action,
+                    seconds: step,
+                    keyframes,
+                    landed: target,
+                });
                 this.osd.push(this.#hostText(delta < 0 ? "Back {} s: {} / {}" : "Forward {} s: {} / {}", [Math.abs(delta), time(target), time(s.duration)]));
                 return;
             }
@@ -1886,9 +1945,10 @@ export class TestHost {
      */
     candidates = new Map();
     /**
-     * Remote Markdown images (`plugin.ui.markdown`): address → a local PNG or
-     * JPEG file served for it, or `null` for a failing download. Nothing is
-     * fetched from the network in tests; unknown addresses fail.
+     * Remote images (`plugin.ui.markdown`, `plugin.ui.remoteImage`): address
+     * → a local PNG or JPEG file served for it, or `null` for a failing
+     * download. Nothing is fetched from the network in tests; unknown
+     * addresses fail.
      */
     remoteImages = new Map();
     /**
@@ -2675,17 +2735,38 @@ export class TestHost {
                 "volume-up",
                 "volume-down",
                 "mute",
+                "fullscreen",
             ];
             if (!actions.includes(String(p.action)))
                 throw new HostError("invalid", `unknown host action ${p.action}`);
-            this.#runCore(String(p.action));
+            // SDK 1.5.19: one step seek of another step.
+            let seconds;
+            if (p.seconds !== undefined && p.seconds !== null) {
+                if (p.action !== "seek-backward" && p.action !== "seek-forward")
+                    throw new HostError("invalid", `seconds applies only to seek-backward and seek-forward, not ${p.action}`);
+                if (!validStep(p.seconds))
+                    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) => {
-            const seconds = Number(p.seconds);
-            if (!(seconds >= 0.1 && seconds <= 3600) ||
-                Math.abs(Math.round(seconds * 10) - seconds * 10) > 1e-9)
+            if (!validStep(p.seconds))
                 throw new HostError("invalid", "seconds must be 0.1..3600 in tenths");
-            this.stepSeek = seconds;
+            if (p.keyframes !== undefined &&
+                p.keyframes !== null &&
+                typeof p.keyframes !== "boolean")
+                throw new HostError("invalid", "keyframes must be a boolean");
+            // Written as a pair, as the player does.
+            this.stepSeek = p.seconds;
+            this.stepSeekKeyframes = p.keyframes === true;
         },
         "player.step": (p) => {
             this.#audioCondition(p.expected);
@@ -3174,6 +3255,28 @@ export class TestHost {
             entry.state = p.enabled === true ? "running" : "disabled";
             this.setPackages(this.packages);
         },
+        // As the player (SDK 1.5.19): stop and start again, built-ins included;
+        // `packages.changed` shows `starting`, then `running`.
+        "packages.reload": (p) => {
+            const id = String(p.id);
+            if (id === this.manifestId)
+                throw new HostError("invalid", "a plugin cannot reload itself");
+            const entry = this.packages.find((each) => each.id === id);
+            if (!entry)
+                throw new HostError("missing", `no plugin ${id}`);
+            if (entry.state === "starting")
+                throw new HostError("busy", "the package is being installed or reloaded");
+            if (entry.state === "disabled")
+                throw new HostError("invalid", `${id} is disabled: enable it instead of reloading it`);
+            this.packageCalls.push({ method: "reload", id });
+            entry.state = "starting";
+            entry.error = null;
+            this.setPackages(this.packages);
+            setTimeout(() => {
+                entry.state = "running";
+                this.setPackages(this.packages);
+            }, 0);
+        },
         "packages.validate": (p) => this.#validate(String(p.directory)),
         "packages.validateArchive": (p) => this.#validate(String(p.file)),
         "packages.install": (p) => {