@vestra-player/sdk 1.5.17 → 1.5.20

package/dist/plugin/testing.js

@@ -65,13 +65,15 @@ import { tmpdir } from "node:os";
 import { extname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { HostError } from "../wire.js";
+import { localSocketPath } from "./local.js";
 import { BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "../commands.js";
 import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.js";
 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";
@@ -96,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:
@@ -624,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 = [];
     /**
@@ -699,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). */
@@ -1013,8 +1026,9 @@ export class TestHost {
      */
     jobs = new Map();
     /**
-     * `openStream`'s transport: a Unix socket (macOS, Linux) or, with `"tcp"`,
-     * loopback TCP where the plugin must send the token first (Windows).
+     * `openStream`'s transport: a local stream (a Unix socket on macOS and
+     * Linux, a named pipe on Windows) or, with `"tcp"`, loopback TCP where the
+     * plugin must send the token first, as the player on Windows answers.
      * Set it before the plugin calls `openStream`.
      */
     producerTransport = "unix";
@@ -1239,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. */
@@ -1468,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");
@@ -1510,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;
             }
@@ -1884,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();
     /**
@@ -2676,14 +2738,27 @@ export class TestHost {
             ];
             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;
+            }
+            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);
@@ -3161,6 +3236,9 @@ export class TestHost {
             const entry = this.packages.find((each) => each.id === id);
             if (!entry)
                 throw new HostError("missing", `no plugin ${id}`);
+            // As the player (with SDK 1.5.18 on): users manage third-party plugins only.
+            if (entry.builtin && p.enabled === false)
+                throw new HostError("unsupported", `${id} is a built-in plugin: built-in plugins cannot be disabled`);
             this.packageCalls.push({
                 method: "setEnabled",
                 id,
@@ -3169,6 +3247,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) => {
@@ -3221,7 +3321,7 @@ export class TestHost {
             if (!entry)
                 throw new HostError("missing", `no plugin ${id}`);
             if (entry.builtin)
-                throw new HostError("unsupported", "built-in plugins can be disabled but not uninstalled");
+                throw new HostError("unsupported", "built-in plugins cannot be uninstalled");
             if (entry.origin !== "installed")
                 throw new HostError("unsupported", "only installed plugins can be uninstalled");
             this.packageCalls.push({
@@ -3436,7 +3536,8 @@ export class TestHost {
             const id = ++this.#next.producer;
             const tcp = this.producerTransport === "tcp";
             const token = tcp ? randomBytes(32) : null;
-            const path = join(this.#scratch, `producer-${id}.sock`);
+            // A Unix socket, or a named pipe on Windows (`localSocketPath`).
+            const path = localSocketPath(this.#scratch, `producer-${id}`);
             const producer = {
                 id,
                 receivedFrames: 0,

package/dist/plugin/types.d.ts

@@ -578,11 +578,12 @@ export interface Commands {
  * An image file for a Slint `image` property, made by {@link Ui.image}.
  *
  * @remarks
- * Opaque: pass it as the **whole** value of an `image` property with
- * {@link View.set} or {@link View.bind}; it cannot sit inside a struct or an
- * array. Making the reference does not read the file: the player checks and
- * decodes it each time a view uses it ({@link Ui.image} has the rules and
- * limits).
+ * Opaque: pass it where the Slint type is `image`, with {@link View.set} or
+ * {@link View.bind}: the whole value of an `image` property or, from SDK
+ * 1.5.19 (player 0.5.1), an `image` field at any depth, such as the logo of
+ * each row of a list. Making the reference does not read the file: the
+ * player checks and decodes it each time a view uses it ({@link Ui.image}
+ * has the rules and limits).
  *
  * A reference belongs to the {@link Scope} that created it. Once that scope
  * is disposed, writing the reference fails with `invalid` (reported to
@@ -596,6 +597,22 @@ export interface Commands {
  * await cover.show();
  * ```
  *
+ * @example A logo in each row
+ * ```slint
+ * export struct Row { key: string, name: string, icon: image }
+ * ```
+ * ```ts
+ * const items = [{ id: "a", name: "A", iconPath: `${plugin.dataDirectory}/a.png` }];
+ * const list = plugin.windows.create("ui/list.slint");
+ * list.bind(() => ({
+ *   rows: items.map((item) => ({
+ *     key: item.id,
+ *     name: item.name,
+ *     icon: plugin.ui.image(item.iconPath, { maxSide: 64 }),
+ *   })),
+ * }));
+ * ```
+ *
  * @see {@link Ui.image}, [Windows, panels, settings pages, dialogs and the OSD](../../docs/concepts/ui.md)
  * @since 1.0.0
  * @category UI
@@ -606,6 +623,24 @@ export interface ImageRef {
     /** Brand that marks the value as an image reference; never construct one yourself. */
     readonly __vestraImage: true;
 }
+/**
+ * Options of {@link Ui.image} and {@link Ui.remoteImage}.
+ *
+ * @since 1.5.19
+ * @category UI
+ */
+export interface ImageOptions {
+    /**
+     * Decode the image scaled down, aspect kept, so that neither side is over
+     * this many pixels (an integer 1–4096); smaller images stay as they are.
+     * Use about twice the drawn size (64 for a 32 px logo) so that it stays
+     * sharp on high-density screens. It keeps the decoded memory small: a
+     * 1024×1024 icon is 4 MB decoded, 16 KB at `maxSide: 64`.
+     *
+     * @player 0.5.1; older players refuse the reference (`invalid`).
+     */
+    maxSide?: number;
+}
 /**
  * A Markdown document for `MarkdownView` or `MarkdownBlocks`, made by
  * {@link Ui.markdown}.
@@ -665,9 +700,8 @@ export interface MarkdownOptions {
     remoteImages?: boolean;
 }
 /**
- * The value of one Slint property: JSON with Markdown documents at any
- * depth ({@link PropData}), or an image as the whole value of an `image`
- * property.
+ * The value of one Slint property: JSON with Markdown documents and images
+ * at any depth ({@link PropData}).
  *
  * @remarks
  * JSON becomes Slint values as you would expect: booleans for `bool`,
@@ -684,13 +718,20 @@ export interface MarkdownOptions {
  *
  * A {@link MarkdownRef} goes where the Slint type is `[MarkdownBlock]`: the
  * whole value, or a field at any depth (SDK 1.5.4; older players refuse a
- * nested one). An {@link ImageRef} only as the whole value: nested in an
- * array or object it is `invalid`.
+ * nested one). An {@link ImageRef} goes where the Slint type is `image`: the
+ * whole value, or a field at any depth (SDK 1.5.19, player 0.5.1; older
+ * players refuse a nested one with `invalid`). The images nested in the
+ * values of one view (a window, panel or settings page) may show at most
+ * 32 MB of decoded pixels together (`IMAGE_LIMITS.viewBytes` in
+ * `@vestra-player/sdk/runtime`): a write
+ * that would pass it is refused with `limit`; use
+ * {@link ImageOptions.maxSide} for small pictures such as logos and
+ * thumbnails.
  *
  * Limits per value (`UI_VALUE_LIMITS` in `@vestra-player/sdk/testing`,
  * player 0.4.3; older players: 4096 values and 1024 rows): nesting depth 8,
  * 16384 values in total (every array, object, string, number, boolean and
- * null counts, the value itself included; a document is one), 4096 rows
+ * null counts, the value itself included; a document or an image is one), 4096 rows
  * per array, 64 KiB per string or field name and 1 MiB of text in total,
  * field names and the text of its Markdown documents included (256 KB per
  * document). A list of rows with 8 fields is 9 values per row, so about
@@ -708,8 +749,8 @@ export interface MarkdownOptions {
  */
 export type PropValue = PropData | ImageRef;
 /**
- * JSON whose values may also be Markdown documents, at any depth: the part
- * of {@link PropValue} that nests.
+ * JSON whose values may also be Markdown documents and (SDK 1.5.19) images,
+ * at any depth: the part of {@link PropValue} that nests.
  *
  * @example A message list whose rows carry a document
  * ```ts
@@ -721,7 +762,7 @@ export type PropValue = PropData | ImageRef;
  * @since 1.5.4
  * @category UI
  */
-export type PropData = null | boolean | number | string | MarkdownRef | Text | TextList | PropData[] | {
+export type PropData = null | boolean | number | string | MarkdownRef | ImageRef | Text | TextList | PropData[] | {
     [key: string]: PropData;
 };
 /**
@@ -778,10 +819,13 @@ export interface Ui {
      * the main window being rebuilt): it must be inside this plugin's package
      * directory or {@link Plugin.dataDirectory} after following links, at most
      * 16 MB and 4096×4096 pixels, and PNG or JPEG by content (the extension
-     * does not matter). A failed check is a failed property write: `missing`
-     * for a file that does not exist, `invalid` otherwise. It goes to
-     * {@link Scope.onError} and the property keeps its previous image; in the
-     * initial properties of a tool window it makes {@link Window.show} reject.
+     * does not matter). A failed check of a whole-value image is a failed
+     * property write: `missing` for a file that does not exist, `invalid`
+     * otherwise. It goes to {@link Scope.onError} and the property keeps its
+     * previous image; in the initial properties of a tool window it makes
+     * {@link Window.show} reject. A nested image (a field of a row, SDK
+     * 1.5.19) that fails its check is drawn empty instead, and the rest of
+     * the value is shown, as a Markdown image shows its alt text.
      *
      * The player caches decoded images per plugin (up to 64 MB, least recently
      * used first) and does not watch files. Every call returns a new value, so
@@ -792,9 +836,12 @@ export interface Ui {
      *
      * @param path - Absolute path of the image file, inside the package
      *   directory or the data directory.
+     * @param options - `maxSide` (SDK 1.5.19, player 0.5.1): decode the image
+     *   scaled down, aspect kept, so that neither side is over it.
      * @returns A new {@link ImageRef}, owned by this scope.
      *
-     * @throws `invalid` (throws) `path` is not a non-empty string.
+     * @throws `invalid` (throws) `path` is not a non-empty string, or
+     *   `maxSide` is not an integer 1–4096.
      *
      * @example Show a thumbnail the plugin rendered
      * ```ts
@@ -807,7 +854,51 @@ export interface Ui {
      *
      * @since 1.0.0
      */
-    image(path: string): ImageRef;
+    image(path: string, options?: ImageOptions): ImageRef;
+    /**
+     * Download an `https:` PNG or JPEG image (a thumbnail, a repository's
+     * plugin icon) and reference the local copy, as {@link Ui.image} does.
+     *
+     * @remarks
+     * Downloads like {@link Ui.markdown}'s remote images: Node's `fetch` in
+     * this plugin's process, at most 4 MB and 10 s per image, 4 downloads at a
+     * time per plugin, into `<dataDirectory>/.vestra-cache/images/`; the cache
+     * keeps 32 MB and fetches an address again after 24 hours, so a list that
+     * shows the same thumbnails again reads them from disk.
+     *
+     * @capability None (the plugin process has network access).
+     * @player Any (the reference is an ordinary {@link ImageRef}); nested in a
+     *   value, player 0.5.1.
+     *
+     * @param url - The image's `https:` address.
+     * @param options - As for {@link Ui.image}.
+     * @returns The reference, owned by this scope, once the file is in the
+     *   cache.
+     *
+     * @throws `invalid` (rejects) `url` is not an `https:` address, or
+     *   `maxSide` is not an integer 1–4096.
+     * @throws `unavailable` (rejects) the download failed, timed out, was too
+     *   large, or is not a PNG or JPEG image; or the plugin has no data
+     *   directory.
+     *
+     * @example Search results with thumbnails
+     * ```ts
+     * const results = [{ title: "A", thumbnailUrl: "https://example.com/a.jpg" }];
+     * const placeholder = plugin.ui.image(`${plugin.dataDirectory}/blank.png`);
+     * const rows = await Promise.all(
+     *   results.map(async (r) => ({
+     *     title: r.title,
+     *     thumb: await plugin.ui
+     *       .remoteImage(r.thumbnailUrl, { maxSide: 320 })
+     *       .catch(() => placeholder),
+     *   })),
+     * );
+     * plugin.windows.create("ui/results.slint").set({ rows });
+     * ```
+     *
+     * @since 1.5.19
+     */
+    remoteImage(url: string, options?: ImageOptions): Promise<ImageRef>;
     /**
      * Prepare a Markdown document for `MarkdownView` (`@vestra/markdown.slint`).
      *
@@ -3729,9 +3820,25 @@ export interface Player {
      * The core's first-tier relative seek (`seek-backward` / `seek-forward`,
      * ← / →): 0.1–3600 seconds in tenths, default 5. The newest call of any
      * plugin wins; it reverts when that plugin stops.
+     *
+     * `keyframes: true` (player 0.5.1, SDK 1.5.19): the step seeks
+     * (`seek-backward` / `seek-forward`, including {@link Host.run} with
+     * `seconds` and the picture-in-picture skips) land on a keyframe instead
+     * of the exact time: forward on the first keyframe at or after position +
+     * 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.
+     *
+     * Older players ignore `keyframes`: set `"minPlayerVersion": "0.5.1"` in
+     * the manifest when you rely on it.
      */
     setStepSeek(options: {
         seconds: number;
+        keyframes?: boolean;
     }): Promise<void>;
     /**
      * The chapters of the current media (empty without media or chapters),
@@ -3778,7 +3885,7 @@ export interface Player {
  * | `play-pause` | Space | 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 |
+ * | `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 |
@@ -3802,6 +3909,31 @@ export interface Host {
      * ```
      */
     run(action: HostAction): Promise<void>;
+    /**
+     * One step seek of `seconds` (0.1–3600 in tenths) instead of the
+     * {@link Player.setStepSeek} step: the same checks, mode (exact or
+     * keyframes), accumulation and on-screen text as ← / →. Use it for more
+     * seek steps of your own (Ctrl+→ and the like) so that they add up with
+     * the core's and land the same way.
+     *
+     * In keyframe mode it resolves once the seek has landed (so
+     * `player.state.position` is current after the `await`); presses that add
+     * up resolve together, the last with the text. In exact mode it resolves
+     * once the seek is submitted, as before. `invalid` for `seconds` out of
+     * range.
+     *
+     * @player 0.5.1 (set `"minPlayerVersion": "0.5.1"`: older players ignore
+     * `seconds` and seek by the `setStepSeek` step)
+     * @since 1.5.19
+     *
+     * @example
+     * ```ts
+     * bar.on("forward30", () => plugin.host.run("seek-forward", { seconds: 30 }));
+     * ```
+     */
+    run(action: "seek-backward" | "seek-forward", options: {
+        seconds: number;
+    }): Promise<void>;
 }
 /**
  * This plugin's information block on the OSD: multi-line text over the
@@ -4733,8 +4865,9 @@ export interface PluginInfo {
      */
     directory: string;
     /**
-     * Shipped with the player: it can be disabled, not uninstalled or
-     * replaced. `false` from players before 0.2.0.
+     * Shipped with the player: it always runs; it cannot be disabled,
+     * uninstalled or replaced (older players, before SDK 1.5.18, let it be disabled).
+     * `false` from players before 0.2.0.
      */
     builtin: boolean;
     /** Where an installed plugin came from; `null` for development loads. */
@@ -4838,9 +4971,31 @@ export interface Packages {
      * Stop or start a plugin (`plugins.manage`). An installed plugin stays
      * disabled across launches; a development load only for this run.
      * `invalid` to disable oneself, `missing` unknown.
-     * `busy` while it is being installed.
+     * `busy` while it is being installed. `unsupported` to disable a built-in
+     * ({@link PluginInfo.builtin}): users manage third-party plugins only
+     * (players released with SDK 1.5.18 on; older ones disabled built-ins too).
      */
     setEnabled(id: string, enabled: boolean): Promise<void>;
+    /**
+     * Restart a plugin (`plugins.manage`): stop it and start it again from the
+     * same package with the same data directory, for example to recover one
+     * that misbehaves. Built-ins included. A stopped or failed plugin is just
+     * started. The disabled flag is never written, so a reload never leaves
+     * a plugin disabled.
+     *
+     * Resolves once the plugin is stopped and its start is scheduled; the
+     * player starts it as soon as the old process is gone (at most 20 s).
+     * Follow it with {@link Packages.onChange}: `starting`, then `running`,
+     * or `failed` with the reason.
+     *
+     * `invalid` for oneself or a disabled plugin (enable it instead),
+     * `missing` unknown, `busy` while it is being installed or reloaded.
+     *
+     * @player 0.5.1; older players reject it as an unknown request
+     * (`unsupported`).
+     * @since 1.5.19
+     */
+    reload(id: string): Promise<void>;
     /**
      * Remove an installed plugin (`plugins.manage`); `removeData` also deletes
      * its data directory, otherwise reinstalling it from the same source

package/dist/plugin/ui.d.ts

@@ -1,6 +1,6 @@
 import type { Json } from "../wire.ts";
 import type { ScopeImpl } from "./scope.ts";
-import type { Dialogs, Disposable, ImageRef, Panels, PropValue, Props, Ui, View, Windows } from "./types.ts";
+import type { Dialogs, Disposable, ImageOptions, ImageRef, Panels, PropValue, Props, Ui, View, Windows } from "./types.ts";
 /** Slint names are kebab-case; plugin code may use camelCase. */
 export declare const kebab: (name: string) => string;
 /**
@@ -13,11 +13,13 @@ export declare class ImageHandle implements ImageRef {
     #private;
     readonly path: string;
     readonly __vestraImage: true;
-    constructor(scope: ScopeImpl, path: string);
+    constructor(scope: ScopeImpl, path: string, maxSide?: number);
     /** Released with its scope: writing it is `invalid`. */
     get released(): boolean;
     toJSON(): Json;
 }
+/** `ImageOptions.maxSide`, checked: an integer 1–4096 or absent. */
+export declare function imageSide(options: ImageOptions | undefined): number | undefined;
 export declare const ui: (scope: ScopeImpl) => Ui;
 /** Property and callback plumbing shared by windows, panels and settings pages. */
 export declare abstract class ViewBase implements View {