@vestra-player/sdk 1.6.7 → 1.6.9

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.6.9
+
+**Who must change: nobody.** Additions only: timeline ranges, OSD messages with action buttons, a limits constant, a wire method and `TestHost` support, and documentation of a bottom bar's `content-full-width`. `apiVersion` stays `vestra/1`, no new capability (`timeline.marks`, `playback.read` and `ui.osd` cover them). A plugin that does not use them sends exactly what it sent before; `onChange` of `plugin.timeline` still runs only when the marks change. One that uses them needs player 0.7.6 (`"minPlayerVersion": "0.7.6"`): the player builds `plugin` from its own SDK, so on older players `setRanges` and `ranges` do not exist (a `TypeError`), and `osd.show` there takes no options.
+
+- **Timeline ranges** (player 0.7.6): `TimelineLayer.setRanges(ranges, { ifCurrent? })` puts spans of the media on the seek bar, each `{ start, end, style, title? }` with `style` `"selection"` (a span the user picked to act on, such as a clip to export; drawn in the accent colour) or `"region"` (a part of the media the plugin describes; drawn dimmer). A layer's marks and ranges are replaced on their own (`set` keeps the ranges, `setRanges` keeps the marks); disposing the layer, its scope or stopping the plugin removes both, and a new source clears every layer. At most 100 ranges per layer, `0 ≤ start < end`, `end` within the media, titles ≤ 100 characters (`TIMELINE_LIMITS`, new, with the marks' 1000); failures go to `onError` as for marks. `plugin.timeline.ranges` (new, `playback.read`) is every layer's ranges merged by start, with `TimelineRange` (`start`, `end`, `style`, `title`, `plugin`); read it in a binding to follow it. Wire: `timeline.setRanges` (needs `timeline.marks`), and `ranges` beside `marks` in `timeline.marks` and `timeline.changed`.
+- **OSD messages with actions** (player 0.7.6): `plugin.osd.show(text, args?, { actions })` ends the message in up to two buttons (`OsdAction`: `title`, translated like the text, 1–40 characters; `command`, the local id of one of the plugin's own commands). The message stays about 4 seconds instead of 2 and does not fade while the pointer is on it and moving (it goes 2 seconds after the pointer leaves or rests, and at the latest 30 seconds after it showed); a click runs the command as if picked from a menu and removes the message. It stays one line, and nothing in it is created or removed while the pointer moves. A newer message replaces it with its buttons; the buttons go when the plugin stops, and while they show the plugin is not stopped for being idle. `osd.show` rejects with `invalid` for more than two actions, a bad title or a command the plugin has not declared. `OSD_LIMITS` gains `actions` (2) and `actionChars` (40). Older players ignore `actions`.
+- **`TestHost`**: `timeline.rangeLayers`, `timeline.ranges` and `setTimelineRanges(pluginId, ranges)` (another plugin's ranges); `timeline.setRanges` checked as the player does; `osdActions` (each message's buttons, in step with `osd`) and `pressOsdAction(index)`, which runs the command like a click.
+- **A bottom bar's `content-full-width`** (player 0.7.6, docs only): a bar that drops controls of its own also reports its row with every control shown in `content-full-width`, a public `length` property declared like `content-min-width`. The player then gives plugin buttons only the width beyond it, so every plugin button moves to » before the bar drops a control, and narrowing the window never brings a button back. A bar with only `content-min-width` keeps the earlier rule. [Writing a bottom bar](docs/guidelines/interface.md#writing-a-bottom-bar) and [Reference: theme](docs/reference/theme.md#bar-buttons) say so.
+
+## 1.6.8
+
+**Who must change: nobody; authors of a bottom bar should move to `content-min-width`.** Documentation, a read-only Slint property and a removed CLI warning: no change to the TypeScript API, the wire or `TestHost`, `apiVersion` stays `vestra/1`, no new capability. A plugin's `button` declarations stay as they are. A bottom bar that still places `BarButtons` keeps working on player 0.7.6 (it shows that strip, and the player draws no second one); it is deprecated and goes in a later patch.
+
+- **The player places the bottom bar's button strip** (player 0.7.6, menu redesign step 3a). It draws the strip at the right end of the bottom slot, also when no plugin mounts a bottom bar (in a band of its own): the plugins' buttons, a » menu, the player's **Command Palette** (`host/palette`, a magnifier) and **Toggle Sidebar**. [Bottom-bar buttons](docs/explanation/commands.md#bottom-bar-buttons) now reads: buttons are ordered by `order`, then by plugin id; lower `order` comes first and stays visible longest; when the strip runs out of room, or more than 8 plugin buttons are declared, the remaining buttons move to the » menu, in the same order; a button is never dropped. Before player 0.7.6 a narrow strip lost its lowest orders first and the player left out all but the eight highest; `BAR_BUTTON_LIMITS.total` is now what the strip holds. [Reference: commands](docs/reference/commands.md#bottom-bar-buttons), [Reference: limits](docs/reference/limits.md#bottom-bar-buttons), `CommandButton`, `CommandOptions.button` and `BAR_BUTTON_LIMITS` say so.
+- **Writing a bottom bar** ([Interface guidelines](docs/guidelines/interface.md#writing-a-bottom-bar)): a bar places nothing. It reports the least width of its own controls in a `content-min-width` length property on the mounted component (the player gives the strip the rest, so the time label is never covered) and ends its row at the strip, reading `BarButtonsHost.width` (new, read only; `fixed` for an optional control kept ahead of plugin buttons) from `@vestra/bar-buttons.slint`. The file stays in the Slint library copy for that global; its `BarButtons` component is deprecated.
+- **`@vestra/bar-buttons.slint`** (the read-only copy of the player's widget library, synced): `BarButtonsHost` gains `width`, `fixed`, `shown` and `more` (out: the strip's width, the cells a bar must leave free (the player's own and the » cell), the plugin buttons in the strip, whether » shows) and the player's `palette`, `overflow` and `room`; the comments describe the player's strip and mark `BarButtons` deprecated.
+- **`vestra-plugin check` no longer warns** that a bottom bar does not place `BarButtons`: since player 0.7.6 that is the right thing to do.
+
 ## 1.6.7
 
 **Who must change: nobody.** The 1.6.6 release below, published again under a new number: its npm publish failed (the provenance transparency log returned 500, then 409 for the same tarball), so 1.6.6 never reached npm. Nothing else changed.

package/bin/vestra-plugin.mjs

@@ -81,7 +81,6 @@ import {
   basename,
   dirname,
   extname,
-  isAbsolute,
   join,
   relative,
   resolve,
@@ -363,10 +362,7 @@ async function check(target, report = null) {
   }
   say(`${target.name}: capabilities declared for every API use`);
   if (report) return;
-  for (const line of [
-    ...(await bottomBarWarnings(target)),
-    ...(await forWarnings(target)),
-  ])
+  for (const line of await forWarnings(target))
     console.log(`${target.name}: warning: ${line}`);
   // Translation warnings never fail the check.
   if (present(join(target.directory, "locales"))) {
@@ -432,85 +428,6 @@ function slintCode(text) {
   return out;
 }
 
-/** Whether `path` lies inside `directory` (not a sibling sharing its prefix). */
-function inside(directory, path) {
-  const rel = relative(resolve(directory), path);
-  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
-}
-
-/**
- * Whether the Slint file at `file` (relative to the plugin directory)
- * imports `BarButtons` from `@vestra/bar-buttons.slint`, itself or
- * through the plugin's own Slint files (relative paths, any depth, inside
- * the plugin directory). Local re-exports count as such files too:
- * `export { Row } from "row.slint"` and `export * from "row.slint"` are
- * followed, and `export { BarButtons } from "@vestra/bar-buttons.slint"` (or
- * `export * from` it) in a file the bar imports counts as placing it.
- * Comments do not count.
- */
-async function importsBarButtons(target, file, seen = new Set()) {
-  const path = resolve(target.directory, file);
-  if (seen.has(path) || !inside(target.directory, path)) return false;
-  seen.add(path);
-  const text = await readFile(path, "utf8").catch(() => null);
-  if (text === null) return false;
-  const code = slintCode(text);
-  // { names (or "*"), from }: imports, and re-exports with a source file.
-  const imports = [
-    ...code.matchAll(
-      /\b(?:import|export)\s*(?:(\*)\s*from\s*|\{([^}]*)\}\s*from\s*)?"([^"]+)"/g,
-    ),
-  ].map(([, star, names, from]) => ({ names: star ?? names ?? "", from }));
-  for (const { names, from } of imports)
-    if (
-      from === "@vestra/bar-buttons.slint" &&
-      (names === "*" ||
-        names
-          .split(",")
-          .some((name) => /^BarButtons(\s+as\s+[\w-]+)?$/.test(name.trim())))
-    )
-      return true;
-  for (const { from } of imports) {
-    if (
-      from.startsWith("@") ||
-      !from.endsWith(".slint") ||
-      from === "std-widgets.slint"
-    )
-      continue;
-    if (await importsBarButtons(target, join(dirname(file), from), seen))
-      return true;
-  }
-  return false;
-}
-
-/**
- * A plugin that mounts a bottom bar (`panels.mount("bottom", "<file>")`)
- * whose Slint file does not import `BarButtons` (`@vestra/bar-buttons.slint`),
- * itself or through its local imports: while it is the bottom bar, no
- * plugin's command button shows (SDK 1.5.29). The mount is read from the
- * source text: a literal file name in the call.
- */
-async function bottomBarWarnings(target) {
-  const { typescript: sources } = await sourceFiles(target);
-  const files = new Set();
-  for (const file of sources) {
-    const text = await readFile(join(target.directory, file), "utf8");
-    for (const match of text.matchAll(
-      /\.mount\(\s*["'`]bottom["'`]\s*,\s*["'`]([^"'`$]+)["'`]/g,
-    ))
-      files.add(match[1]);
-  }
-  const warnings = [];
-  for (const file of files) {
-    if (!present(join(target.directory, file))) continue;
-    if (await importsBarButtons(target, file)) continue;
-    warnings.push(
-      `${file} is a bottom bar without BarButtons (import { BarButtons } from "@vestra/bar-buttons.slint"): while it is mounted, the command buttons of every plugin (and the player's sidebar toggle) show nowhere; see docs/guidelines/interface.md#writing-a-bottom-bar`,
-    );
-  }
-  return warnings;
-}
-
 /**
  * A `for` over an array the plugin binds (an `in` or `in-out` property of
  * array type of a component or global in the same file), outside a

package/dist/api-requests.js

@@ -71,8 +71,12 @@ export const API_REQUESTS = Object.freeze({
     "Subtitles.remove": [{ method: "subtitles.remove" }, readsSubtitles],
     "Subtitles.setStyle": [{ method: "subtitles.style" }, readsSubtitles],
     "Timeline.marks": [{ method: "timeline.marks" }],
+    "Timeline.ranges": [{ method: "timeline.marks" }],
     "Timeline.onChange": [listen("timeline.changed")],
-    "Timeline.layer": [{ method: "timeline.set" }],
+    "Timeline.layer": [
+        { method: "timeline.set" },
+        { method: "timeline.setRanges" },
+    ],
     "MainWindow.onChange": [listen("window.state")],
     "MainWindow.setVideoArea": [{ method: "window.setVideoArea" }],
     "MainWindow.setAlwaysOnTop": [{ method: "window.setAlwaysOnTop" }],

package/dist/commands.d.ts

@@ -158,12 +158,11 @@ export declare const BAR_BUTTON_ICONS: readonly ["play", "pause", "stop", "back"
 /**
  * The player's limits on bottom-bar buttons (`CommandOptions.button`), the
  * same values as the player's (its tests check that they agree). A button
- * past `perPlugin` or `total` is left out: its command still registers and
- * its menu entry stays, and the player logs the button it left out
- * (`limit`). Which ones stay: each plugin's first declared button, then the
- * `total` highest by order, plugin id and declaration order: as in a narrow
- * strip, the lowest order goes first (equal orders: the smaller plugin id,
- * then the earlier declaration, goes first).
+ * past `perPlugin` has none (its command still registers and its menu entry
+ * stays). `total` is what the strip holds: the `total` lowest by order,
+ * plugin id and declaration order; the rest are in the strip's » menu, in
+ * the same order (older players keep the `total` highest and leave the
+ * others out).
  *
  * @since 1.5.29
  *
@@ -172,7 +171,7 @@ export declare const BAR_BUTTON_ICONS: readonly ["play", "pause", "stop", "back"
 export declare const BAR_BUTTON_LIMITS: {
     /** Buttons one plugin shows (1). */
     readonly perPlugin: 1;
-    /** Buttons the player shows, every plugin together, besides its own sidebar toggle (8). */
+    /** Buttons in the strip, every plugin together, besides the player's own (8); the rest are in its » menu. */
     readonly total: 8;
     /** The highest `order` (999; the lowest is 0). */
     readonly maxOrder: 999;

package/dist/commands.js

@@ -202,12 +202,11 @@ export const BAR_BUTTON_ICONS = [
 /**
  * The player's limits on bottom-bar buttons (`CommandOptions.button`), the
  * same values as the player's (its tests check that they agree). A button
- * past `perPlugin` or `total` is left out: its command still registers and
- * its menu entry stays, and the player logs the button it left out
- * (`limit`). Which ones stay: each plugin's first declared button, then the
- * `total` highest by order, plugin id and declaration order: as in a narrow
- * strip, the lowest order goes first (equal orders: the smaller plugin id,
- * then the earlier declaration, goes first).
+ * past `perPlugin` has none (its command still registers and its menu entry
+ * stays). `total` is what the strip holds: the `total` lowest by order,
+ * plugin id and declaration order; the rest are in the strip's » menu, in
+ * the same order (older players keep the `total` highest and leave the
+ * others out).
  *
  * @since 1.5.29
  *
@@ -216,7 +215,7 @@ export const BAR_BUTTON_ICONS = [
 export const BAR_BUTTON_LIMITS = {
     /** Buttons one plugin shows (1). */
     perPlugin: 1,
-    /** Buttons the player shows, every plugin together, besides its own sidebar toggle (8). */
+    /** Buttons in the strip, every plugin together, besides the player's own (8); the rest are in its » menu. */
     total: 8,
     /** The highest `order` (999; the lowest is 0). */
     maxOrder: 999,

package/dist/host-capabilities.js

@@ -300,7 +300,10 @@ export const HOST_CAPABILITIES = {
         },
         {
             label: "Show marks on the progress bar",
-            methods: [{ name: "timeline.set", needs: "timeline.marks" }],
+            methods: [
+                { name: "timeline.set", needs: "timeline.marks" },
+                { name: "timeline.setRanges", needs: "timeline.marks" },
+            ],
             name: "timeline.marks",
             requires: [],
             residency: "live",

package/dist/player-runtime.d.ts

@@ -16,6 +16,7 @@ export { HOST_CAPABILITIES } from "./host-capabilities.ts";
 export { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "./commands.ts";
 export { BINDING_INPUTS } from "./plugin/bindings.ts";
 export { OSD_LIMITS } from "./plugin/osd.ts";
+export { TIMELINE_LIMITS } from "./plugin/timeline.ts";
 export { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./plugin/services.ts";
 export { SUBTITLE_LIMITS } from "./plugin/subtitles.ts";
 export { VIDEO_PROCESSING_LIMITS } from "./processing.ts";

package/dist/player-runtime.js

@@ -14,6 +14,7 @@ export { HOST_CAPABILITIES } from "./host-capabilities.js";
 export { BAR_BUTTON_ICONS, BAR_BUTTON_LIMITS, BUILTIN_COMMANDS, BUILTIN_SUBMENUS, COMMAND_LIMITS, MENU_IDS, } from "./commands.js";
 export { BINDING_INPUTS } from "./plugin/bindings.js";
 export { OSD_LIMITS } from "./plugin/osd.js";
+export { TIMELINE_LIMITS } from "./plugin/timeline.js";
 export { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./plugin/services.js";
 export { SUBTITLE_LIMITS } from "./plugin/subtitles.js";
 export { VIDEO_PROCESSING_LIMITS } from "./processing.js";

package/dist/plugin/osd.d.ts

@@ -46,6 +46,10 @@ export declare const OSD_LIMITS: Readonly<{
     readonly minColumns: 8;
     /** The largest `OsdPanelOptions.maxColumns` (1000). */
     readonly maxColumns: 1000;
+    /** Action buttons of one `osd.show` message (`OsdShowOptions.actions`; player 0.7.6) (2). */
+    readonly actions: 2;
+    /** Characters of an action's title, as shown (40; at least 1 that is not white space). */
+    readonly actionChars: 40;
 }>;
 /**
  * Copy and check template arguments: an array or object of at most 16

package/dist/plugin/osd.js

@@ -47,7 +47,32 @@ export const OSD_LIMITS = Object.freeze({
     minColumns: 8,
     /** The largest `OsdPanelOptions.maxColumns` (1000). */
     maxColumns: 1000,
+    /** Action buttons of one `osd.show` message (`OsdShowOptions.actions`; player 0.7.6) (2). */
+    actions: 2,
+    /** Characters of an action's title, as shown (40; at least 1 that is not white space). */
+    actionChars: 40,
 });
+/** Copy and check `OsdShowOptions.actions`: what the SDK can check before the player does. */
+function osdActions(options) {
+    if (options === undefined || options === null)
+        return undefined;
+    if (typeof options !== "object")
+        throw failure("invalid", "options is an object");
+    const actions = options.actions;
+    if (actions === undefined)
+        return undefined;
+    if (!Array.isArray(actions) || actions.length > OSD_LIMITS.actions)
+        throw failure("invalid", `actions is a list of at most ${OSD_LIMITS.actions}`);
+    return actions.map((action, i) => {
+        const { title, command } = (action ?? {});
+        if (typeof command !== "string" || command === "")
+            throw failure("invalid", `actions[${i}].command is a command id`);
+        return {
+            title: shownText(title, undefined, `actions[${i}].title`),
+            command,
+        };
+    });
+}
 /**
  * Copy and check template arguments: an array or object of at most 16
  * strings, finite numbers, texts and lists (`TEXT_LIMITS`).
@@ -134,6 +159,6 @@ class PanelHandle {
     }
 }
 export const osd = (scope) => ({
-    show: async (text, args) => scope.runtime.host.osd.show(shownText(text, args), templateArgs(args)),
+    show: async (text, args, options) => scope.runtime.host.osd.show(shownText(text, args), templateArgs(args), osdActions(options)),
     panel: () => new PanelHandle(scope),
 });

package/dist/plugin/testing.d.ts

@@ -7,6 +7,7 @@ import type { BuiltinCommand, BuiltinSubmenu } from "../commands.ts";
 import { CAPABILITY_INFO, MESSAGE_LIMIT } from "../capabilities.ts";
 import type { CapabilityInfo } from "../capabilities.ts";
 import { OSD_LIMITS } from "./osd.ts";
+import { TIMELINE_LIMITS } from "./timeline.ts";
 import { SECRET_LIMITS, SESSION_STORAGE_LIMITS } from "./services.ts";
 import { SUBTITLE_LIMITS } from "./subtitles.ts";
 import { BINDING_INPUTS } from "./bindings.ts";
@@ -36,6 +37,8 @@ export type { CapabilityInfo };
 export { MESSAGE_LIMIT };
 /** The player's limits on the on-screen display. */
 export { OSD_LIMITS };
+/** The player's limits on a timeline layer. */
+export { TIMELINE_LIMITS };
 /** The player's limits on stored secrets. */
 export { SECRET_LIMITS };
 /** The player's limits on `plugin.storage.session`. */
@@ -647,6 +650,43 @@ export declare class TestHost implements Transport {
      * template and args the plugin sent are in `host.sent("osd.show")`.
      */
     readonly osd: string[];
+    /**
+     * The action buttons of each `osd.show` message, in step with `osd`
+     * (index for index): each button's title as shown and its command; `[]`
+     * for a message without actions (SDK 1.6.9).
+     */
+    readonly osdActions: {
+        /** The button title as shown, in the plugin's locale. */
+        title: string;
+        /** The local id of the plugin's command the button runs. */
+        command: string;
+    }[][];
+    /**
+     * Press button `index` of the newest OSD message, as the user does
+     * (player 0.7.6): its command runs as if picked from a menu, and settles.
+     * A disabled or busy command does nothing, as in the player.
+     *
+     * @param index - 0 or 1.
+     *
+     * @throws `Error` (rejects) The newest message has no button `index`.
+     *
+     * @example Press "Show in Folder" on the saved message
+     * The test checks the button the plugin put on its newest message, then
+     * presses it as the user would: the plugin's `reveal` command runs.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * assert.deepEqual(host.osdActions.at(-1), [
+     *   { title: "Show in Folder", command: "reveal" },
+     * ]);
+     * await host.pressOsdAction(0); // runs the plugin's `reveal` command
+     * ```
+     *
+     * @capability None.
+     * @since 1.6.9
+     */
+    pressOsdAction(index: number): Promise<void>;
     /** The text of this plugin's osd panel as shown, `null` when hidden. */
     osdPanel: string | null;
     /**
@@ -948,7 +988,65 @@ export declare class TestHost implements Transport {
             /** The mark's title, `null` without one. */
             title: string | null;
         }[];
+        /**
+         * Each plugin's ranges by plugin id; layers without ranges are absent
+         * (SDK 1.6.9).
+         */
+        rangeLayers: Map<string, {
+            /** Seconds from the start. */
+            start: number;
+            /** Seconds from the start, after `start`. */
+            end: number;
+            /** `"selection"` or `"region"`. */
+            style: string;
+            /** The range's title, `null` without one. */
+            title: string | null;
+        }[]>;
+        /** Every layer's ranges merged, sorted by start, with the plugin's id. */
+        readonly ranges: {
+            /** The manifest id of the plugin that published the range. */
+            plugin: string;
+            /** Seconds from the start. */
+            start: number;
+            /** Seconds from the start, after `start`. */
+            end: number;
+            /** `"selection"` or `"region"`. */
+            style: string;
+            /** The range's title, `null` without one. */
+            title: string | null;
+        }[];
     };
+    /**
+     * Simulate another plugin publishing its timeline ranges (or clearing
+     * them with `[]`); pushes `timeline.changed` when the plugin subscribed.
+     *
+     * @param pluginId - The other plugin's manifest id.
+     * @param ranges - All its ranges.
+     *
+     * @example Let another plugin publish a clip range
+     * The plugin under test sees a range another plugin put on the seek bar:
+     * `setTimelineRanges` stores that plugin's ranges and pushes
+     * `timeline.changed`, and `settle()` lets it arrive.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * host.setTimelineRanges("community.clips", [
+     *   { start: 40, end: 52.5, style: "selection", title: "Clip" },
+     * ]);
+     * await host.settle();
+     * assert.equal(plugin.timeline.ranges[0]?.plugin, "community.clips");
+     * ```
+     *
+     * @capability None.
+     * @since 1.6.9
+     */
+    setTimelineRanges(pluginId: string, ranges: {
+        start: number;
+        end: number;
+        style: string;
+        title?: string | null;
+    }[]): void;
     /**
      * Simulate another plugin publishing its timeline layer (or clearing it
      * with `[]`); pushes `timeline.changed` when the plugin subscribed.
@@ -2645,8 +2743,8 @@ export declare class TestHost implements Transport {
      * The plugin's bottom-bar buttons (`CommandOptions.button`) as the player
      * shows them: at most one, the first declared (`BAR_BUTTON_LIMITS`; a
      * later one stays a menu item only). Empty once the command is disposed.
-     * Whether the bar places them is the bar's business: the list is what
-     * the player hands to `BarButtons`.
+     * Whether one is in the strip or its » menu is the player's business
+     * (the room and the other plugins' buttons).
      *
      * @example Click the plugin's bottom-bar button in a test
      * The test finds the plugin's Store button, clicks it and checks that the