@vestra-player/sdk 1.6.16 → 1.6.18

package/dist/plugin/testing/media.js

@@ -0,0 +1,615 @@
+/**
+ * The source and what plays: `source.*` intents and resolvers, playback,
+ * subtitles and audio.
+ *
+ * Part of `TestHost` (`./index.ts`): functions over the host and its private
+ * state (`Internals`, `./internals.ts`) that the class delegates to.
+ * Internal to the SDK; not exported from `@vestra-player/sdk/testing`.
+ */
+import { extname, isAbsolute } from "node:path";
+import { HostError } from "../../wire.js";
+import { SUBTITLE_LIMITS } from "../subtitles.js";
+import { isTextValue } from "../../i18n.js";
+import { taken } from "./transport.js";
+import { declaredText, hostText } from "./i18n.js";
+import { timelineChanged } from "./layout.js";
+export function initialSource() {
+    return {
+        kind: "media",
+        container: null,
+        audioTracks: null,
+        stamp: { generation: 0, intentVersion: 0 },
+        cycle: 0,
+        eventSequence: 0,
+        phase: "empty",
+        source: null,
+        loadingOwner: null,
+        terminalReason: null,
+        paused: false,
+        position: null,
+        duration: null,
+        capabilities: {
+            pause: false,
+            seek: false,
+            rate: false,
+            restart: false,
+            close: false,
+            snapshotSource: false,
+        },
+        output: { volume: 100, muted: false },
+        rate: 1,
+    };
+}
+export const readyCapabilities = {
+    pause: true,
+    seek: true,
+    rate: true,
+    restart: true,
+    close: true,
+    snapshotSource: true,
+};
+export function sourceIntent(host, inner, intent) {
+    const expected = intent.expected;
+    const stamp = host.source.stamp;
+    if (expected &&
+        (expected.generation !== stamp.generation ||
+            expected.intentVersion !== stamp.intentVersion))
+        throw new HostError("stale", "stale");
+    const next = {
+        ...host.source,
+        stamp: { ...stamp, intentVersion: stamp.intentVersion + 1 },
+        eventSequence: host.source.eventSequence + 1,
+    };
+    if (intent.kind === "open" || intent.kind === "openProvider") {
+        next.stamp.generation++;
+        next.cycle++;
+        next.kind = intent.kind === "open" ? "media" : "producer";
+        next.source =
+            intent.kind === "open"
+                ? String(intent.source)
+                : `producer://${intent.producerId}`;
+        next.phase = intent.kind === "open" ? "loading" : "ready";
+        next.paused = intent.startPaused === true;
+        next.position = null;
+        next.duration = null;
+        next.terminalReason = null;
+        next.capabilities = { ...readyCapabilities };
+        next.loop = null; // a new source clears the A-B loop
+        if (host.timeline.layers.size || host.timeline.rangeLayers.size) {
+            host.timeline.layers.clear(); // and every timeline layer
+            host.timeline.rangeLayers.clear();
+            queueMicrotask(() => timelineChanged(host, inner));
+        }
+    }
+    else if (intent.kind === "close") {
+        if (!host.source.source)
+            throw new HostError("invalid", "noSource");
+        Object.assign(next, {
+            phase: "empty",
+            source: null,
+            position: null,
+            duration: null,
+            terminalReason: "stopped",
+        });
+    }
+    else if (intent.kind === "restart") {
+        next.cycle++;
+        Object.assign(next, {
+            phase: "ready",
+            position: 0,
+            paused: false,
+            terminalReason: null,
+        });
+    }
+    else if (intent.kind === "control") {
+        if (!host.source.source)
+            throw new HostError("invalid", "noSource");
+        const control = intent.control;
+        if (control.kind === "pause")
+            next.paused = control.paused === true;
+        if (control.kind === "seek")
+            next.position = Number(control.seconds);
+        if (control.kind === "rate")
+            next.rate = Number(control.rate);
+    }
+    // Like the player: the selected producer is retired as soon as another
+    // source replaces it or the source closes.
+    if (["open", "openProvider", "close"].includes(String(intent.kind)))
+        retireSelected(host, inner, intent.kind === "openProvider" ? Number(intent.producerId) : null);
+    if (intent.kind === "openProvider")
+        inner.selected = Number(intent.producerId);
+    if (intent.kind === "open" || intent.kind === "close")
+        inner.selected = null;
+    host.source = next;
+    host.subtitles.source = {
+        generation: next.stamp.generation,
+        phase: next.phase,
+    };
+    host.emit("source.state", host.source);
+    cancelResolutions(host, inner);
+    return { ticket: { stamp: next.stamp, cycle: next.cycle, owner: 1 } };
+}
+/** The file resolver of this plugin that claims `source`, if any. */
+export function fileResolver(host, _inner, source) {
+    if (source.includes("://") || !isAbsolute(source))
+        return null;
+    const extension = extname(source).slice(1).toLowerCase();
+    if (!extension)
+        return null;
+    for (const [id, declaration] of host.resolvers) {
+        const extensions = declaration.extensions;
+        if (extensions?.includes(extension))
+            return id;
+    }
+    return null;
+}
+/** Retire the producer that is the player's source, unless it is `keep`. */
+export function retireSelected(host, inner, keep) {
+    for (const producer of host.producers.values())
+        if (producer.id !== keep &&
+            !producer.retired &&
+            isCurrentProducer(host, inner, producer.id))
+            producer.retired = true;
+}
+/** Whether producer `id` is the player's source. */
+export function isCurrentProducer(host, inner, id) {
+    return (host.source.kind === "producer" &&
+        (inner.selected === id || host.source.source === `producer://${id}`));
+}
+/** Start resolving `source` for the open just made; its request id, or null. */
+export function startResolution(host, inner, source, paused, operation) {
+    const resolverId = fileResolver(host, inner, source);
+    if (resolverId === null)
+        return null;
+    const requestId = ++inner.next.resolution;
+    host.resolutions.set(requestId, { resolverId, source, paused });
+    inner.resolving.set(requestId, {
+        stamp: { ...host.source.stamp },
+        ...(operation === undefined ? {} : { operation }),
+    });
+    host.emit("source.resolveRequest", { requestId, resolverId, url: source });
+    return requestId;
+}
+/** Settle a resolution's open; `error` fails it. */
+export function settleResolution(host, inner, requestId, error) {
+    const operation = inner.resolving.get(requestId)?.operation;
+    host.resolutions.delete(requestId);
+    inner.resolving.delete(requestId);
+    if (operation === undefined)
+        return;
+    const entry = inner.sourceBook.get(operation);
+    inner.sourceBook.set(operation, error === undefined
+        ? { status: "completed", ticket: entry?.ticket ?? null }
+        : { status: "failed", error: { backend: error } });
+}
+/** Resolutions whose open is no longer the source (or whose resolver left). */
+export function cancelResolutions(host, inner) {
+    const stamp = host.source.stamp;
+    for (const [requestId, resolution] of [...host.resolutions]) {
+        const pending = inner.resolving.get(requestId);
+        if (pending.stamp.generation === stamp.generation &&
+            pending.stamp.intentVersion === stamp.intentVersion &&
+            host.resolvers.has(resolution.resolverId))
+            continue;
+        settleResolution(host, inner, requestId, "source resolution cancelled, expired or superseded");
+        host.emit("source.resolveCancel", {
+            requestId,
+            resolverId: resolution.resolverId,
+        });
+    }
+}
+/** `sourceResolvers.register`: the player's rules for both forms. */
+export function registerResolver(host, inner, p) {
+    const id = String(p.id);
+    const extensions = p.extensions;
+    if (host.resolvers.has(id))
+        throw new HostError("conflict", "resolver id already registered");
+    if (extensions !== undefined) {
+        if (p.schemes !== undefined ||
+            p.hosts !== undefined ||
+            !Array.isArray(extensions) ||
+            extensions.length < 1 ||
+            extensions.length > 16 ||
+            extensions.some((e) => typeof e !== "string" ||
+                !/^[a-z0-9]{1,16}$/.test(e) ||
+                e === "folder"))
+            throw new HostError("invalid", "file resolvers take 1–16 file extensions (lower case, no dot, not folder)");
+    }
+    const claims = (other) => extensions?.find((e) => other.extensions?.includes(e)) ??
+        (other.hosts?.some((h) => p.hosts?.includes(h)) &&
+            other.schemes?.some((x) => p.schemes?.includes(x))
+            ? "host"
+            : undefined);
+    for (const own of host.resolvers.values())
+        if (claims(own))
+            throw new HostError("conflict", "already registered by this plugin");
+    for (const other of host.otherResolvers) {
+        const what = claims(other);
+        if (what) {
+            const target = what === "host"
+                ? hostText(host, inner, "this site")
+                : hostText(host, inner, "File type .{}", [what]);
+            throw taken(hostText(host, inner, "{} is resolved by {}", [target, other.owner]));
+        }
+    }
+    host.resolvers.set(id, p);
+}
+/** `sourceResolvers.respond` for a simulated file resolution. */
+export function respondResolution(host, inner, p) {
+    const requestId = Number(p.requestId);
+    const resolution = host.resolutions.get(requestId);
+    if (!resolution) {
+        // Web resolutions are not simulated: their answers are only recorded.
+        if (requestId > inner.next.resolution)
+            return null;
+        throw new HostError("stale", "resolution no longer pending");
+    }
+    const fail = (message) => {
+        settleResolution(host, inner, requestId, message);
+        host.setSource({
+            phase: "error",
+            terminalReason: { failed: message },
+        });
+        throw new HostError("resolution", message);
+    };
+    // A text value (`plugin.i18n.error`) is shown translated, like the player.
+    const error = isTextValue(p.error)
+        ? declaredText(host, inner, p.error, "error")
+        : p.error;
+    if (typeof error === "string")
+        fail(error.trim() ? [...error].slice(0, 2048).join("") : "resolver failed");
+    const result = (p.result ?? {});
+    const producer = host.producers.get(Number(result.producerId));
+    if (result.kind !== "stream")
+        fail("invalid resolved stream descriptor");
+    if (!producer || producer.released || producer.retired)
+        fail("unavailable: producer absent");
+    // Like openProvider, but the source keeps the path and `startPaused`.
+    retireSelected(host, inner, producer.id);
+    inner.selected = producer.id;
+    producer.active = true;
+    producer.acknowledged = false;
+    producer.pending = {
+        producerId: producer.id,
+        epoch: producer.epoch + 1,
+        baseSample: producer.receivedFrames,
+        paused: resolution.paused,
+    };
+    settleResolution(host, inner, requestId);
+    host.setSource({
+        kind: "producer",
+        phase: "ready",
+        paused: resolution.paused,
+        capabilities: {
+            pause: true,
+            seek: false,
+            rate: false,
+            restart: false,
+            close: true,
+            snapshotSource: false,
+        },
+    });
+    return { stamp: { ...host.source.stamp } };
+}
+/** Audio track calls need ready media and the source the caller saw. */
+export function audioCondition(host, _inner, expected) {
+    const want = expected;
+    const stamp = host.source.stamp;
+    if (want &&
+        (want.generation !== stamp.generation ||
+            want.intentVersion !== stamp.intentVersion))
+        throw new HostError("stale", "source changed");
+    if (host.source.kind !== "media" ||
+        !["ready", "ended"].includes(host.source.phase))
+        throw new HostError("unavailable", "audio tracks need ready media");
+}
+/** `stale` unless `expected` is the current subtitle stamp. */
+export function subtitleExpected(host, _inner, expected) {
+    const stamp = host.subtitles.selection.stamp;
+    const want = expected;
+    if (want.generation !== stamp.generation || want.revision !== stamp.revision)
+        throw new HostError("stale", "subtitle selection changed");
+}
+export function loadedSubtitles(host, inner) {
+    const generation = host.source.stamp.generation;
+    if (inner.subtitleResources.generation !== generation)
+        inner.subtitleResources = { generation, bytes: new Map() };
+    return inner.subtitleResources.bytes;
+}
+/**
+ * The player's `SUBTITLE_LIMITS` for a new resource (`busy`, as the
+ * player reports them). External tracks in `subtitles.tracks` that this
+ * plugin did not load count as other plugins'. `totalBytes` is not
+ * modelled: one plugin's 4 files of at most 2 MiB stay below it, and the
+ * bytes of other plugins' tracks are unknown.
+ */
+export function subtitleRoom(host, inner, resourceId) {
+    const loaded = loadedSubtitles(host, inner);
+    if (loaded.has(resourceId))
+        return;
+    const external = host.subtitles.tracks.filter((t) => t.target.kind === "external");
+    const own = external.filter((t) => t.target.kind === "external" && loaded.has(t.target.resourceId));
+    const others = external.length - own.length;
+    if (loaded.size >= SUBTITLE_LIMITS.loadsPerPlugin ||
+        loaded.size + others >= SUBTITLE_LIMITS.loads ||
+        own.length >= SUBTITLE_LIMITS.tracksPerPlugin ||
+        external.length >= SUBTITLE_LIMITS.tracks)
+        throw new HostError("busy", "subtitle resource or counter limit exceeded");
+}
+export function subtitleChange(host, inner, expected) {
+    subtitleExpected(host, inner, expected);
+    const stamp = host.subtitles.selection.stamp;
+    host.subtitles.selection.stamp = {
+        generation: host.source.stamp.generation,
+        revision: stamp.revision + 1,
+    };
+}
+/** Implements `TestHost.setSource`. */
+export function setSource(host, _inner, patch) {
+    host.source = {
+        ...host.source,
+        ...patch,
+        eventSequence: host.source.eventSequence + 1,
+    };
+    if (patch.phase && patch.phase !== "empty" && !patch.capabilities)
+        host.source.capabilities = { ...readyCapabilities };
+    host.subtitles.source = {
+        generation: host.source.stamp.generation,
+        phase: host.source.phase,
+    };
+    host.emit("source.state", host.source);
+    // Like the player (reference §6.3): loading shows the backdrop.
+    if (patch.phase === "loading" && host.backdrop && !host.backdrop.effective)
+        host.setBackdropEffective(true);
+}
+/** The default handlers of this area's wire methods, by method name. */
+export function mediaHandlers(host, inner) {
+    return {
+        "playback.stats": () => host.stats,
+        "audio.addTrack": (p) => {
+            audioCondition(host, inner, p.expected);
+            const path = String(p.path);
+            if (!path.startsWith("/") || path.includes("://"))
+                throw new HostError("invalid", "path must be an existing absolute file");
+            const tracks = host.source.audioTracks ?? [];
+            const track = {
+                trackId: Math.max(0, ...tracks.map((t) => t.trackId)) + 1,
+                streamIndex: null,
+                selected: p.select !== false,
+                external: true,
+                codec: null,
+                title: path.split("/").pop() ?? null,
+                language: null,
+            };
+            host.setSource({
+                audioTracks: [
+                    ...tracks.map((t) => ({
+                        ...t,
+                        selected: track.selected ? false : t.selected,
+                    })),
+                    track,
+                ],
+            });
+            return track;
+        },
+        "audio.selectTrack": (p) => {
+            audioCondition(host, inner, p.expected);
+            const tracks = host.source.audioTracks ?? [];
+            if (!tracks.some((t) => t.trackId === p.id))
+                throw new HostError("invalid", "no such audio track");
+            host.setSource({
+                audioTracks: tracks.map((t) => ({
+                    ...t,
+                    selected: t.trackId === p.id,
+                })),
+            });
+        },
+        "source.state": () => host.source,
+        "source.submit": (p) => {
+            const intent = p.intent;
+            const control = intent.control;
+            if (intent.kind === "control" && control?.kind === "seek") {
+                if (control.keyframes !== undefined &&
+                    typeof control.keyframes !== "boolean")
+                    throw new HostError("invalid", "keyframes must be a boolean");
+                host.seeks.push({
+                    seconds: Number(control.seconds),
+                    keyframes: control.keyframes === true,
+                });
+            }
+            const ticket = sourceIntent(host, inner, intent);
+            const operation = Number(p.operationId);
+            // A file this plugin's file resolver claims: pending until it answers.
+            if (intent.kind === "open" &&
+                startResolution(host, inner, String(intent.source), intent.startPaused === true, operation) !== null) {
+                const pending = { status: "pending", ...ticket };
+                inner.sourceBook.set(operation, pending);
+                return pending;
+            }
+            const result = { status: "completed", ...ticket };
+            inner.sourceBook.set(operation, result);
+            // Selecting a provider asks it to acknowledge a start control.
+            const producer = host.producers.get(Number(intent.producerId));
+            if (intent.kind === "openProvider" && producer) {
+                producer.acknowledged = false;
+                producer.pending = {
+                    producerId: producer.id,
+                    epoch: producer.epoch + 1,
+                    baseSample: producer.receivedFrames,
+                    paused: false,
+                };
+            }
+            return result;
+        },
+        "source.operation": (p) => {
+            const result = inner.sourceBook.get(Number(p.operationId));
+            if (!result)
+                throw new HostError("unknown-expired", "UnknownExpired");
+            return result;
+        },
+        "playback.set": (p) => {
+            if (p.property === "volume")
+                host.source.output = { ...host.source.output, volume: Number(p.value) };
+            if (p.property === "muted")
+                host.source.output = { ...host.source.output, muted: p.value === true };
+            host.source = {
+                ...host.source,
+                eventSequence: host.source.eventSequence + 1,
+            };
+        },
+        "subtitles.state": () => structuredClone(host.subtitles),
+        "subtitles.select": (p) => {
+            const target = p.target;
+            const same = (a, b) => a != null && JSON.stringify(a) === JSON.stringify(b);
+            if (p.role === "secondary") {
+                if (same(target, host.subtitles.selection.target))
+                    throw new HostError("invalid", "secondary equals the primary");
+                const track = host.subtitles.tracks.find((t) => same(t.target, target));
+                if (track && track.text === false)
+                    throw new HostError("invalid", "a bitmap subtitle cannot be secondary");
+                subtitleChange(host, inner, p.expected);
+                host.subtitles.selection.secondary = target;
+                return structuredClone(host.subtitles);
+            }
+            if (same(target, host.subtitles.selection.secondary))
+                throw new HostError("invalid", "primary equals the secondary");
+            subtitleChange(host, inner, p.expected);
+            host.subtitles.selection.target = target;
+            return structuredClone(host.subtitles);
+        },
+        "player.audioDevices": () => structuredClone(host.audioDevices),
+        "player.setAudioDevice": (p) => {
+            const requested = p.id === null ? null : String(p.id);
+            const present = host.audioDevices.some((d) => d.id === requested);
+            host.setSource({
+                audioOutput: { requested, active: present ? requested : null },
+            });
+        },
+        "subtitles.style": (p) => {
+            subtitleChange(host, inner, p.expected);
+            host.subtitles.presentation.revision++;
+            host.subtitles.presentation.effective = p.style
+                ? {
+                    owner: 1,
+                    manifestId: host.manifestId,
+                    revision: Number(p.revision),
+                    style: p.style,
+                }
+                : null;
+            return structuredClone(host.subtitles);
+        },
+        "subtitles.upload.begin": (p) => {
+            if (p.generation !== host.source.stamp.generation)
+                throw new HostError("stale", "source generation changed");
+            const expectedBytes = Number(p.expectedBytes);
+            if (!Number.isSafeInteger(expectedBytes) ||
+                expectedBytes < 1 ||
+                expectedBytes > SUBTITLE_LIMITS.fileBytes)
+                throw new HostError("invalid", `a subtitle file has 1..${SUBTITLE_LIMITS.fileBytes} bytes`);
+            // Like the player: a new source drops the old one's uploads. A commit
+            // the player refused leaves its upload for `subtitles.upload.discard`,
+            // which the SDK sends after any failed load.
+            for (const [id, upload] of host.uploads)
+                if (upload.generation !== undefined &&
+                    upload.generation !== host.source.stamp.generation)
+                    host.uploads.delete(id);
+            if (host.uploads.size >= SUBTITLE_LIMITS.uploadsPerPlugin)
+                throw new HostError("busy", "upload memory, owner or active-token limit reached");
+            host.uploads.set(Number(p.uploadId), {
+                bytes: [],
+                expected: expectedBytes,
+                generation: host.source.stamp.generation,
+            });
+            return {
+                generation: p.generation,
+                expectedBytes: p.expectedBytes,
+                receivedBytes: 0,
+                complete: false,
+            };
+        },
+        "subtitles.upload.append": (p) => {
+            const upload = host.uploads.get(Number(p.uploadId));
+            if (!upload)
+                throw new HostError("missing", "upload");
+            upload.bytes.push(Buffer.from(String(p.base64), "base64"));
+            return {};
+        },
+        "subtitles.upload.discard": (p) => void host.uploads.delete(Number(p.uploadId)),
+        "subtitles.commit": (p) => {
+            // The player's order: the request's own fields, then `stale`, then
+            // the upload and its content, then the limits.
+            const format = p.format === "ass" ? "ass" : "srt";
+            const select = p.select === "none"
+                ? "none"
+                : p.select === "secondary"
+                    ? "secondary"
+                    : "primary";
+            const title = isTextValue(p.title)
+                ? declaredText(host, inner, p.title, "title")
+                : typeof p.title === "string"
+                    ? p.title
+                    : null;
+            if (title !== null && ([...title].length < 1 || [...title].length > 200))
+                throw new HostError("invalid", "subtitle title needs 1..200 characters");
+            subtitleExpected(host, inner, p.expected);
+            const upload = host.uploads.get(Number(p.uploadId));
+            if (!upload)
+                throw new HostError("missing", "upload");
+            const bytes = Buffer.concat(upload.bytes);
+            if (format === "ass" &&
+                !(/\[Script Info\]/i.test(bytes.toString()) &&
+                    /\[Events\]/i.test(bytes.toString())))
+                throw new HostError("invalid", "ASS requires [Script Info] and [Events] sections");
+            subtitleRoom(host, inner, String(p.resourceId));
+            subtitleChange(host, inner, p.expected);
+            loadedSubtitles(host, inner).set(String(p.resourceId), bytes.length);
+            const target = {
+                kind: "external",
+                owner: 1,
+                resourceId: String(p.resourceId),
+                contentRevision: 1,
+            };
+            host.subtitles.tracks.push({
+                target,
+                title: title ??
+                    hostText(host, inner, format === "ass" ? "External ASS" : "External SRT"),
+                language: null,
+                styleSupported: true,
+                styleReason: null,
+                codec: format === "ass" ? "ass" : "webvtt",
+                text: true,
+                streamIndex: null,
+            });
+            if (select === "primary")
+                host.subtitles.selection.target = target;
+            if (select === "secondary")
+                host.subtitles.selection.secondary = target;
+            host.subtitleLoads.push({ format, title, select, bytes });
+            host.uploads.delete(Number(p.uploadId));
+            return structuredClone(host.subtitles);
+        },
+        "subtitles.remove": (p) => {
+            subtitleChange(host, inner, p.expected);
+            host.subtitles.tracks = host.subtitles.tracks.filter((t) => t.target.kind !== "external" || t.target.resourceId !== p.resourceId);
+            const selected = host.subtitles.selection.target;
+            if (selected?.kind === "external" && selected.resourceId === p.resourceId)
+                host.subtitles.selection.target = null;
+            const secondary = host.subtitles.selection.secondary;
+            if (secondary?.kind === "external" &&
+                secondary.resourceId === p.resourceId)
+                host.subtitles.selection.secondary = null;
+            return structuredClone(host.subtitles);
+        },
+        "subtitles.operation": () => ({ status: "unknown" }),
+        "sourceResolvers.register": (p) => {
+            registerResolver(host, inner, p);
+            host.updateFileTypes();
+        },
+        "sourceResolvers.unregister": (p) => {
+            host.resolvers.delete(String(p.id));
+            cancelResolutions(host, inner);
+            host.updateFileTypes();
+        },
+        "sourceResolvers.respond": (p) => respondResolution(host, inner, p),
+    };
+}

package/dist/plugin/testing/osd.d.ts

@@ -0,0 +1,4 @@
+import type { TestHost } from "./index.ts";
+import type { Handler, Internals } from "./internals.ts";
+/** The default handlers of this area's wire methods, by method name. */
+export declare function osdHandlers(host: TestHost, inner: Internals): Record<string, Handler>;

package/dist/plugin/testing/osd.js

@@ -0,0 +1,57 @@
+/**
+ * On-screen messages and the OSD panel (`osd.show`, `osd.panel`).
+ *
+ * Part of `TestHost` (`./index.ts`): functions over the host and its private
+ * state (`Internals`, `./internals.ts`) that the class delegates to.
+ * Internal to the SDK; not exported from `@vestra-player/sdk/testing`.
+ */
+import { HostError } from "../../wire.js";
+import { OSD_LIMITS } from "../osd.js";
+import { fitColumns } from "../../i18n.js";
+import { shownText } from "./i18n.js";
+/** The default handlers of this area's wire methods, by method name. */
+export function osdHandlers(host, inner) {
+    return {
+        "osd.show": (p) => {
+            const text = shownText(host, inner, p.text, p.args, "text").replace(/[\n\r]/g, " ");
+            if (!text.trim() || [...text].length > OSD_LIMITS.messageChars)
+                throw new HostError("invalid", `osd text needs 1..${OSD_LIMITS.messageChars} characters`);
+            // Player 0.7.6: up to 2 buttons, each a command of this plugin.
+            const sent = p.actions;
+            if (sent !== undefined &&
+                (!Array.isArray(sent) || sent.length > OSD_LIMITS.actions))
+                throw new HostError("invalid", `actions is a list of at most ${OSD_LIMITS.actions}`);
+            const actions = (sent ?? []).map((action) => {
+                const title = shownText(host, inner, action.title, undefined, "title").replace(/[\n\r]/g, " ");
+                if (!title.trim() || [...title].length > OSD_LIMITS.actionChars)
+                    throw new HostError("invalid", `an action title needs 1..=${OSD_LIMITS.actionChars} characters`);
+                const command = String(action.command);
+                if (!host.commands.has(command))
+                    throw new HostError("invalid", `${command} is not a command of this plugin`);
+                return { title, command };
+            });
+            host.osd.push(text);
+            host.osdActions.push(actions);
+        },
+        "osd.panel": (p) => {
+            if (p.text === null)
+                return void (host.osdPanel = null);
+            const max = p.maxColumns;
+            if (max !== undefined &&
+                !(Number.isInteger(max) &&
+                    Number(max) >= OSD_LIMITS.minColumns &&
+                    Number(max) <= OSD_LIMITS.maxColumns))
+                throw new HostError("invalid", `maxColumns is an integer from ${OSD_LIMITS.minColumns} to ${OSD_LIMITS.maxColumns}`);
+            const shown = shownText(host, inner, p.text, p.args, "text");
+            const text = max === undefined ? shown : fitColumns(shown, Number(max));
+            // As the player: \n separates lines, a trailing one ends the last.
+            const lines = text.split("\n");
+            if (text.endsWith("\n"))
+                lines.pop();
+            if (Buffer.byteLength(text) > OSD_LIMITS.panelBytes ||
+                lines.length > OSD_LIMITS.panelLines)
+                throw new HostError("invalid", `osd panel allows ${OSD_LIMITS.panelLines} lines, ${OSD_LIMITS.panelBytes} bytes`);
+            host.osdPanel = text;
+        },
+    };
+}