@vestra-player/sdk 1.6.18 → 1.6.19

package/dist/plugin/view/panel.js

@@ -0,0 +1,178 @@
+/** Docked panels (`plugin.panels`): one Slint component per position. */
+import { Latest } from "../latest.js";
+import { failure, quiet } from "../errors.js";
+import { dropsOf } from "../drops.js";
+import { exported, ViewBase } from "./base.js";
+import { backdrop, layoutOf, slot } from "./layout.js";
+class PanelHandle extends ViewBase {
+    ready;
+    #slot;
+    #mounted = false;
+    #locks = { focused: false, dragging: false, popupOpen: false };
+    #interaction;
+    constructor(scope, slot, file, options) {
+        // One panel per slot (SDK 1.6.15, player 0.7.6; a player before 0.7.6
+        // refuses a second panel with `conflict`).
+        if (scope.runtime.views.has(`panel:${slot}`))
+            throw new Error(`this plugin already has a panel in the ${slot}`);
+        super(scope);
+        this.#slot = slot;
+        const runtime = scope.runtime;
+        runtime.views.set(`panel:${slot}`, (callback, args) => this.dispatch(callback, args));
+        this.#interaction = new Latest((locks) => runtime.host.ui.interaction(locks, this.#named()));
+        const component = options.component ?? exported(runtime.directory, file, "component");
+        const global = options.global ?? exported(runtime.directory, file, "global");
+        scope.add(this);
+        this.ready = runtime
+            .starting((async () => {
+            // Let handlers and bindings declared right after mount() join in.
+            await Promise.resolve();
+            const properties = this.wired(this.snapshot());
+            await runtime.host.ui.mount({
+                slot,
+                file,
+                component,
+                global,
+                ...(options.title === undefined ? {} : { title: options.title }),
+                properties,
+            });
+            this.#mounted = true;
+            this.shown(properties);
+            this.flush();
+            // The position's state changed: refresh it if this plugin reads it.
+            await layoutOf(runtime).refresh();
+        })(), (error) => scope.report(error))
+            .then(() => { });
+        quiet(this.ready);
+    }
+    live() {
+        return this.#mounted && !this.closed;
+    }
+    /**
+     * The slot to name in a request about this panel: only while the plugin
+     * has panels in more than one slot (the player then needs it); a plugin
+     * with one panel sends what it always sent.
+     */
+    #named() {
+        const panels = [...this.scope.runtime.views.keys()].filter((key) => key.startsWith("panel:"));
+        return panels.length > 1 ? this.#slot : undefined;
+    }
+    write(property, write) {
+        return this.scope.runtime.host.ui.setMount(property, write, this.#named());
+    }
+    get state() {
+        const service = layoutOf(this.scope.runtime);
+        service.start();
+        return this.live()
+            ? panelState(service.state, this.#slot, this.scope.runtime.manifest.id)
+            : null;
+    }
+    onChange(listener) {
+        const scope = this.scope;
+        let last = JSON.stringify(this.state);
+        const watch = layoutOf(scope.runtime).watch(() => {
+            const state = this.state;
+            const next = JSON.stringify(state);
+            if (next === last)
+                return;
+            last = next;
+            scope.run(listener, state);
+        });
+        return scope.add({
+            dispose: async () => {
+                scope.forget(watch);
+                await watch.dispose();
+            },
+        });
+    }
+    async show() {
+        await this.ready;
+        if (this.#slot === "backdrop")
+            throw failure("invalid", "the player shows the backdrop by itself");
+        await layoutOf(this.scope.runtime).set(this.#slot, {
+            active: this.scope.runtime.manifest.id,
+            visible: true,
+        });
+    }
+    async toggle() {
+        await this.ready;
+        if (this.#slot === "backdrop")
+            throw failure("invalid", "the player shows the backdrop by itself");
+        await layoutOf(this.scope.runtime).read();
+        const state = this.state;
+        // A switch, the same in every mode (user ruling 2026-11-08): off when
+        // on and current, else on at this tab. `reveal: false`: in fullscreen
+        // nothing pops out, the right edge reveals it (player 0.7.6; older
+        // players ignore it and pop it out).
+        if (state?.preferred && state.active)
+            await layoutOf(this.scope.runtime).set(this.#slot, { visible: false });
+        else
+            await layoutOf(this.scope.runtime).set(this.#slot, {
+                active: this.scope.runtime.manifest.id,
+                visible: true,
+                reveal: false,
+            });
+    }
+    async showMenu(items, at) {
+        await this.ready;
+        await this.scope.runtime.host.ui.menu(items.map((item) => item?.id ?? null), at.x, at.y, this.#named());
+    }
+    onDrop(listener) {
+        const watch = dropsOf(this.scope.runtime).listen(this.scope, (event) => this.scope.run(listener, event));
+        return this.scope.add({ dispose: () => watch.dispose() });
+    }
+    setInteraction(locks) {
+        Object.assign(this.#locks, locks);
+        this.#interaction
+            .push({ ...this.#locks })
+            .catch((error) => this.scope.report(error));
+    }
+    async dispose() {
+        if (this.closed)
+            return;
+        this.scope.forget(this);
+        this.#interaction.stop();
+        if (this.#mounted)
+            await this.scope.runtime.host.ui.unmount(this.#named()).catch(() => { });
+        this.#mounted = false;
+        await this.release();
+        this.scope.runtime.views.delete(`panel:${this.#slot}`);
+        // Listeners of `onChange` hear `null`.
+        this.scope.runtime.invalidate();
+        await layoutOf(this.scope.runtime).refresh();
+    }
+}
+/** One panel's view of its position (`Panel.state`). */
+function panelState(layout, slot, plugin) {
+    if (slot === "backdrop")
+        return (layout.backdrop && {
+            active: true,
+            preferred: true,
+            effective: layout.backdrop.effective,
+            reason: null,
+            detached: false,
+        });
+    const state = layout[slot];
+    if (!state)
+        return null;
+    // Players without tabs (no `panels`): the position holds this panel only.
+    const panels = layout.tabs[slot];
+    const own = panels?.find((panel) => panel.plugin === plugin);
+    if (panels && !own)
+        return null;
+    const active = own?.active ?? true;
+    return {
+        active,
+        preferred: state.preferred,
+        effective: state.effective && active,
+        reason: active ? state.reason : "otherTab",
+        detached: state.detached,
+    };
+}
+export const panels = (scope) => ({
+    mount: (position, file, options = {}) => new PanelHandle(scope, position, file, options),
+    bottom: slot(scope, "bottom"),
+    sidebar: slot(scope, "sidebar"),
+    adjust: slot(scope, "adjust"),
+    backdrop: backdrop(scope),
+});

package/dist/plugin/view/window.d.ts

@@ -0,0 +1,3 @@
+import type { ScopeImpl } from "../scope.ts";
+import type { Windows } from "../types.ts";
+export declare const windows: (scope: ScopeImpl) => Windows;

package/dist/plugin/view/window.js

@@ -0,0 +1,99 @@
+/** Tool windows (`plugin.windows`): one Slint window per handle. */
+import { basename, extname } from "node:path";
+import { failure } from "../errors.js";
+import { ViewBase } from "./base.js";
+import { kebab } from "./writer.js";
+class WindowHandle extends ViewBase {
+    #id;
+    #file;
+    #opened = false;
+    #queue = Promise.resolve();
+    constructor(scope, file, id) {
+        if (scope.runtime.views.has(id))
+            throw failure("conflict", `window ${id} already exists; pass a distinct id`);
+        super(scope);
+        this.#file = file;
+        this.#id = id;
+        scope.runtime.views.set(id, (callback, args) => this.dispatch(callback, args));
+        // The user closed it with the title bar: the host already dropped it.
+        this.#closedByUser = scope.runtime.raw("ui.closed", (data) => {
+            if (data.view !== this.#id || !this.#opened)
+                return;
+            this.#opened = false;
+            for (const listener of [...this.#closeListeners])
+                this.scope.run(listener);
+            this.scope.update();
+        });
+        scope.add(this);
+    }
+    #closeListeners = new Set();
+    #closedByUser;
+    onClose(listener) {
+        this.#closeListeners.add(listener);
+        return this.scope.onDispose(() => {
+            this.#closeListeners.delete(listener);
+        });
+    }
+    get opened() {
+        return this.#opened;
+    }
+    live() {
+        return this.#opened && !this.closed;
+    }
+    write(property, write) {
+        return this.scope.runtime.host.ui.set(this.#id, property, write);
+    }
+    on(callback, handler) {
+        // The host forwards only callbacks named when the window opens.
+        if (this.#opened && !this.handlers.has(kebab(callback)))
+            throw new Error(`bind window handler ${callback} before the first show()`);
+        return super.on(callback, handler);
+    }
+    /** Window RPCs run strictly in order; a failure does not block later calls. */
+    #serial(task) {
+        const next = this.#queue.then(task, task);
+        this.#queue = next.catch(() => { });
+        return next;
+    }
+    show() {
+        return this.#serial(async () => {
+            if (this.closed)
+                return;
+            const ui = this.scope.runtime.host.ui;
+            if (this.#opened)
+                return ui.show(this.#id, true);
+            const initial = this.wired(this.snapshot(), true);
+            await ui.open(this.#id, this.#file, initial, [...this.handlers.keys()]);
+            this.#opened = true;
+            this.shown(initial);
+            this.flush();
+        });
+    }
+    hide() {
+        return this.#serial(async () => {
+            if (this.#opened)
+                await this.scope.runtime.host.ui.show(this.#id, false);
+        });
+    }
+    close() {
+        return this.#serial(async () => {
+            if (!this.#opened)
+                return;
+            this.#opened = false;
+            await this.scope.runtime.host.ui.close(this.#id);
+        });
+    }
+    async dispose() {
+        if (this.closed)
+            return;
+        this.scope.forget(this);
+        await this.close().catch(() => { });
+        await this.release();
+        await this.#closedByUser.dispose();
+        this.#closeListeners.clear();
+        this.scope.runtime.views.delete(this.#id);
+    }
+}
+export const windows = (scope) => ({
+    create: (file, options) => new WindowHandle(scope, file, options?.id ?? basename(file, extname(file))),
+});

package/dist/plugin/view/writer.d.ts

@@ -0,0 +1,58 @@
+import type { Json, PropertyWrite } from "../../wire.ts";
+import type { PropValue, Props } from "../types.ts";
+/** Slint names are kebab-case; plugin code may use camelCase. */
+export declare const kebab: (name: string) => string;
+export declare const encode: (props: Props) => {
+    [k: string]: PropValue;
+};
+/** Where a {@link ViewWriter}'s writes go, and what it asks of its view. */
+export interface WriterTarget {
+    /** The view shows its properties: writes may be sent. */
+    live(): boolean;
+    /** Send one property write to the player. */
+    write(property: string, write: PropertyWrite): Promise<void>;
+    /** Report a failure (the plugin's error handler and the player's log). */
+    report(error: unknown): void;
+    /** The player takes row patches (and `seq` on whole writes). */
+    patches(): boolean;
+}
+/**
+ * One view's properties: their values now, what the player shows as far as
+ * this side knows, and the writes that bring the one to the other.
+ */
+export declare class ViewWriter {
+    #private;
+    constructor(target: WriterTarget);
+    /**
+     * Initial properties in wire form. A released image is left out (the
+     * property keeps its default) and reported, like a failed write. With a
+     * player that takes row patches, the arrays of one request carry at most
+     * {@link CHUNK_BYTES} of rows together (SDK 1.5.46): an array over that
+     * goes with its first rows, and the first flush sends the rest as patches.
+     * An array over the value limits is refused here, as the player would
+     * refuse it whole: left out and reported (a panel, a settings page), or,
+     * with `refuse` (a window's `show`), thrown.
+     */
+    wired(values: Record<string, PropValue>, refuse?: boolean): Record<string, Json>;
+    /** `View.set`: each value is sent once even if equal to what was sent. */
+    set(props: Props): void;
+    /** A bound value (Slint name): sent by the next flush if it changed. */
+    assign(key: string, value: PropValue): void;
+    /** Every property's value now, by Slint name. */
+    values(): Record<string, PropValue>;
+    /** The host already shows these values (e.g. sent as initial properties). */
+    shown(values: Record<string, Json>): void;
+    /**
+     * Send what changed. A bound value is sent when it differs from the last one
+     * sent; a `set()` value is always sent once. Nothing is resent merely
+     * because a callback arrived, so text the user typed into an in-out
+     * property survives other callbacks (call `set()` to pull a control back).
+     * A failed bound value is not repeated until it changes; an explicit `set()`
+     * is, after a back-off (0.25 s doubling to 30 s). Only the first failure of
+     * a failing streak is reported, so an error handler that writes a status to
+     * a broken view cannot spin.
+     */
+    flush(): void;
+    /** The view closed: no retry after a back-off. */
+    stop(): void;
+}