`, used for the "Connecting to Meld Studio…" notice.
+ *
+ * Every shipped inspector declares it as `
`, so it starts hidden. Reproducing that matters: an element seeded
+ * visible would make "the notice is showing" true before the runtime did
+ * anything, and the assertion could not fail.
+ */
+export class FakeDiv extends FakeElement {
+ constructor(display = "none") {
+ super();
+ this.style.display = display;
+ }
+}
+
+/** An `
`: its value is a plain string. */
+export class FakeInput extends FakeElement {
+ value = "";
+
+ /** Simulates the user typing a value and committing it. */
+ enter(value: string): void {
+ this.value = value;
+ this.dispatch("change");
+ }
+}
+
+/** A frame the property inspector sent to Stream Deck. */
+export type SentFrame = { event: string; context?: string; action?: string; payload?: unknown };
+
+/** Stand-in for the property inspector's Stream Deck socket. */
+export class FakePiSocket {
+ static latest: FakePiSocket | undefined;
+
+ readonly sent: SentFrame[] = [];
+ onopen?: () => void;
+ onmessage?: (event: { data: string }) => void;
+
+ constructor() {
+ FakePiSocket.latest = this;
+ }
+
+ /** Records an outbound frame. */
+ send(data: string): void {
+ this.sent.push(JSON.parse(data) as SentFrame);
+ }
+
+ /** Completes the connection, as the app does once the socket is up. */
+ open(): void {
+ this.onopen?.();
+ }
+
+ /**
+ * Delivers an inbound frame.
+ * @param message The message Stream Deck would send.
+ */
+ receive(message: unknown): void {
+ this.onmessage?.({ data: JSON.stringify(message) });
+ }
+
+ /** Every frame sent with the given event name. */
+ framesFor(event: string): SentFrame[] {
+ return this.sent.filter((frame) => frame.event === event);
+ }
+}
+
+/** The property-inspector runtime plus the fakes backing it. */
+export type PropertyInspector = {
+ /** The `MeldPI` object the inspectors call. */
+ MeldPI: Record
unknown> & {
+ bindSessionSelects(ids: string[], keepFilter?: (type: string, item: unknown) => boolean): void;
+ bindField(id: string, fallback?: string): void;
+ bindEditablePreset(
+ id: string,
+ presetId: string,
+ customRowId: string,
+ presets: string[],
+ fallback: string,
+ ): void;
+ watchConnection(loadingId: string): void;
+ getSettings(): Record;
+ patchSettings(patch: Record): void;
+ onSession(fn: (session: unknown) => void): void;
+ };
+ /** The socket the runtime opened. */
+ socket: FakePiSocket;
+ /** Registers an element under an id, as the inspector's markup would. */
+ element(id: string, element: T): T;
+ /** Pushes a session snapshot, as the plugin's ui-bridge does. */
+ pushSession(items: Record, connected?: boolean): void;
+ /** Delivers `didReceiveSettings`, as Stream Deck does after a write. */
+ pushSettings(settings: Record): void;
+};
+
+const MELD_PI_PATH = new URL("../../co.meldstudio.streamdeck.sdPlugin/ui/lib/meld-pi.js", import.meta.url);
+
+/**
+ * Loads the real property-inspector runtime against fake DOM and socket, and
+ * completes its Stream Deck registration handshake.
+ * @param settings Settings the action is configured with.
+ * @param actionUuid The action's manifest UUID.
+ */
+export function loadPropertyInspector(
+ settings: Record = {},
+ actionUuid = "co.meldstudio.streamdeck.toggle-layer",
+): PropertyInspector {
+ const elements = new Map();
+ const window: Record = {};
+ const document = {
+ getElementById: (id: string) => elements.get(id) ?? null,
+ createElement: (tag: string) => (tag === "option" ? new FakeOption() : new FakeSelect()),
+ };
+
+ const context = createContext({ window, document, WebSocket: FakePiSocket, console });
+ runInContext(readFileSync(MELD_PI_PATH, "utf8"), context, { filename: "meld-pi.js" });
+
+ const connect = window.connectElgatoStreamDeckSocket as (
+ port: number,
+ uuid: string,
+ registerEvent: string,
+ info: string,
+ actionInfo: string,
+ ) => void;
+ connect(0, "ctx-1", "registerPropertyInspector", "{}", JSON.stringify({ action: actionUuid, payload: { settings } }));
+
+ const socket = FakePiSocket.latest as FakePiSocket;
+
+ return {
+ MeldPI: window.MeldPI as PropertyInspector["MeldPI"],
+ socket,
+ element(id, element) {
+ elements.set(id, element);
+ return element;
+ },
+ pushSession(items, connected = true) {
+ socket.receive({
+ event: "sendToPropertyInspector",
+ payload: { event: "meld.session", items, connected },
+ });
+ },
+ pushSettings(next) {
+ socket.receive({ event: "didReceiveSettings", payload: { settings: next } });
+ },
+ };
+}
diff --git a/test/helpers/fake-stream-deck.ts b/test/helpers/fake-stream-deck.ts
new file mode 100644
index 0000000..ecb6c89
--- /dev/null
+++ b/test/helpers/fake-stream-deck.ts
@@ -0,0 +1,253 @@
+// Copyright (c) 2024 Meld Studio, Inc.
+// Licensed under the MIT license. See LICENSE file in the project root for details.
+//
+// A stand-in for the Stream Deck side of an action: fake key and dial instances
+// that record what the plugin painted, plus a `mount` helper that attaches them
+// to a real action so its render lifecycle can be driven directly.
+//
+// This deliberately fakes only what MeldAction touches. Everything below the
+// action — the Meld connection and session handling — is real code driven by a
+// result-level WebChannel fixture shaped like WebChannelAPI.md.
+
+import type { JsonObject } from "@elgato/utils";
+
+import type { MeldAction } from "../../src/actions/base.ts";
+
+/** Feedback payload passed to a dial's touchscreen. */
+export type Feedback = {
+ icon?: string;
+ title?: string;
+ value?: string;
+ indicator?: { value: number; enabled: boolean; bar_bg_c: string };
+};
+
+/**
+ * A fake visible action instance. Stands in for the SDK's `KeyAction` /
+ * `DialAction`, recording every paint so tests can assert on what the user
+ * would see.
+ */
+export class FakeActionInstance {
+ readonly id: string;
+
+ /** Every state pushed, in order. */
+ readonly states: (0 | 1)[] = [];
+ /** Every image pushed, in order. */
+ readonly images: (string | undefined)[] = [];
+ /** Every dial feedback pushed, in order. */
+ readonly feedbacks: Feedback[] = [];
+ /** Every settings migration persisted through the SDK action instance. */
+ readonly settingsWrites: T[] = [];
+
+ #settings: T;
+
+ constructor(id: string, settings: T) {
+ this.id = id;
+ this.#settings = settings;
+ }
+
+ /** The most recent state pushed, or `undefined` if none. */
+ get state(): 0 | 1 | undefined {
+ return this.states.at(-1);
+ }
+
+ /** The most recent image pushed, or `undefined` if none. */
+ get image(): string | undefined {
+ return this.images.at(-1);
+ }
+
+ /** The most recent dial feedback pushed, or `undefined` if none. */
+ get feedback(): Feedback | undefined {
+ return this.feedbacks.at(-1);
+ }
+
+ /** Replaces the settings the SDK would report for this instance. */
+ setLocalSettings(settings: T): void {
+ this.#settings = settings;
+ }
+
+ // --- The surface MeldAction uses -----------------------------------------
+
+ /** @returns The instance's current settings, as the SDK would. */
+ async getSettings(): Promise {
+ return this.#settings as unknown as U;
+ }
+
+ /** Records and applies a settings write, as Stream Deck would. */
+ async setSettings(settings: U): Promise {
+ this.#settings = settings as unknown as T;
+ this.settingsWrites.push(structuredClone(this.#settings));
+ }
+
+ /** Records a key state push. */
+ async setState(state: 0 | 1): Promise {
+ this.states.push(state);
+ }
+
+ /** Records a key image push. */
+ async setImage(image: string | undefined): Promise {
+ this.images.push(image);
+ }
+
+ /** Records a dial feedback push. */
+ async setFeedback(feedback: Feedback): Promise {
+ this.feedbacks.push(feedback);
+ }
+
+ /** Discards every recorded paint, so a test can assert on what follows. */
+ reset(): void {
+ this.states.length = 0;
+ this.images.length = 0;
+ this.feedbacks.length = 0;
+ }
+}
+
+/** The live visible set behind each mounted action's `actions` getter. */
+const mounted = new WeakMap[]>();
+
+/**
+ * Attaches fake instances to an action, replacing the SDK-backed `actions`
+ * getter that enumerates visible contexts.
+ *
+ * The set is live: {@link disappear} removes an instance from it before the
+ * action's handler runs, which is what the SDK does (it drops the context from
+ * its action store on a prepended willDisappear listener). A frozen set would
+ * let code that asks "is any instance still visible?" always answer yes.
+ * @param action The action under test.
+ * @param instances The instances visible to begin with.
+ */
+export function mount(action: MeldAction, instances: FakeActionInstance[]): void {
+ const live = [...instances] as unknown as FakeActionInstance[];
+ mounted.set(action, live);
+ Object.defineProperty(action, "actions", {
+ configurable: true,
+ get: () => live[Symbol.iterator](),
+ });
+}
+
+/**
+ * Makes an instance visible and delivers `willAppear`, as the app does.
+ * @param action The action under test.
+ * @param instance The appearing instance.
+ * @param settings Settings the SDK reports with the event.
+ * @param controller Whether the instance is a key or an encoder.
+ */
+export async function appear(
+ action: MeldAction,
+ instance: FakeActionInstance,
+ settings: T,
+ controller: "Keypad" | "Encoder" = "Keypad",
+): Promise {
+ const live = mounted.get(action);
+ if (live && !live.includes(instance as never)) {
+ live.push(instance as never);
+ }
+ await action.onWillAppear(willAppear(instance, settings, controller) as never);
+}
+
+/**
+ * Removes an instance from the visible set and delivers `willDisappear`.
+ * @param action The action under test.
+ * @param instance The disappearing instance.
+ */
+export async function disappear(
+ action: MeldAction,
+ instance: FakeActionInstance,
+): Promise {
+ const live = mounted.get(action);
+ const index = live?.indexOf(instance as never) ?? -1;
+ if (index >= 0) {
+ // Removed first: the SDK's store no longer yields the context by the time
+ // the plugin's handler runs.
+ live?.splice(index, 1);
+ }
+ await action.onWillDisappear({ action: instance, payload: { settings: {} } } as never);
+}
+
+/**
+ * Builds a `willAppear` event for a fake instance.
+ * @param instance The appearing instance.
+ * @param settings Settings the SDK reports with the event.
+ * @param controller Whether the instance is a key or an encoder.
+ */
+export function willAppear(
+ instance: FakeActionInstance,
+ settings: T,
+ controller: "Keypad" | "Encoder" = "Keypad",
+): { action: unknown; payload: { settings: T; controller: string } } {
+ instance.setLocalSettings(settings);
+ return { action: instance, payload: { settings, controller } };
+}
+
+/**
+ * Builds a `didReceiveSettings` event for a fake instance.
+ * @param instance The instance whose settings changed.
+ * @param settings The new settings.
+ */
+export function didReceiveSettings(
+ instance: FakeActionInstance,
+ settings: T,
+): { action: unknown; payload: { settings: T } } {
+ instance.setLocalSettings(settings);
+ return { action: instance, payload: { settings } };
+}
+
+/**
+ * Builds a key-press event for a fake instance.
+ * @param instance The pressed instance.
+ * @param settings Settings the SDK reports with the event.
+ */
+export function keyEvent(
+ instance: FakeActionInstance,
+ settings: T,
+): { action: unknown; payload: { settings: T } } {
+ return { action: instance, payload: { settings } };
+}
+
+/**
+ * Reconfigures a visible instance, as the property inspector does when the user
+ * changes a dropdown: Stream Deck persists the settings and delivers
+ * `didReceiveSettings` to the running action.
+ * @param action The action under test.
+ * @param instance The instance being reconfigured.
+ * @param settings The new settings.
+ */
+export async function retarget(
+ action: MeldAction,
+ instance: FakeActionInstance,
+ settings: T,
+): Promise {
+ await action.onDidReceiveSettings(didReceiveSettings(instance, settings) as never);
+}
+
+/**
+ * Presses a key: `keyDown` then `keyUp`, as the app always delivers them.
+ *
+ * Calling `onKeyUp` alone skips the dedupe-cache invalidation that every real
+ * press performs, so a key could appear to repaint correctly in a test while
+ * the shipped plugin suppressed the message.
+ * @param action The action under test.
+ * @param instance The pressed instance.
+ * @param settings Settings the SDK reports with the event.
+ */
+export async function press(
+ action: MeldAction,
+ instance: FakeActionInstance,
+ settings: T,
+): Promise {
+ action.onKeyDown(keyEvent(instance, settings) as never);
+ await action.onKeyUp?.(keyEvent(instance, settings) as never);
+}
+
+/**
+ * Builds a dial-rotate event for a fake instance.
+ * @param instance The rotated instance.
+ * @param settings Settings the SDK reports with the event.
+ * @param ticks Detents turned; negative is counter-clockwise.
+ */
+export function dialRotate(
+ instance: FakeActionInstance,
+ settings: T,
+ ticks: number,
+): { action: unknown; payload: { settings: T; ticks: number } } {
+ return { action: instance, payload: { settings, ticks } };
+}
diff --git a/test/helpers/mock-web-channel.ts b/test/helpers/mock-web-channel.ts
new file mode 100644
index 0000000..5bc6ea8
--- /dev/null
+++ b/test/helpers/mock-web-channel.ts
@@ -0,0 +1,457 @@
+// Copyright (c) 2024 Meld Studio, Inc.
+// Licensed under the MIT license. See LICENSE file in the project root for details.
+
+import { mock, type Mock } from "node:test";
+
+import type {
+ OpenWebChannel,
+ WebChannelCallbacks,
+ WebChannelHandle,
+} from "../../src/meld/connection.ts";
+import type { MeldObject, MeldSignal } from "../../src/meld/types.ts";
+import type { FakeLayer, FakeScene, FakeSession, FakeTrack, Scenario } from "./session-builder.ts";
+
+/** Meld's retriggerable session-save delay. */
+export const MELD_SESSION_DEBOUNCE_MS = 600;
+
+export type MockWebChannelOptions = {
+ omitMeldObject?: boolean;
+ stallHandshake?: boolean;
+ omitObserverApi?: boolean;
+ echoDelayMs?: number;
+ sessionDebounceMs?: number;
+};
+
+type RequiredMethod = NonNullable extends (...args: infer A) => infer R
+ ? (...args: A) => R
+ : never;
+
+/** Direct mocks for every Meld method used by the plugin. */
+export type MockMeldMethods = {
+ [K in
+ | "setClientName"
+ | "showScene"
+ | "setStagedScene"
+ | "showStagedScene"
+ | "toggleMute"
+ | "toggleMonitor"
+ | "toggleLayer"
+ | "toggleEffect"
+ | "toggleRecord"
+ | "toggleStream"
+ | "setGain"
+ | "setMuted"
+ | "setProperty"
+ | "registerTrackObserver"
+ | "unregisterTrackObserver"
+ | "callFunction"
+ | "callFunctionWithArgs"
+ | "sendCommand"
+ | "sendCommandWithArgs"
+ | "sendStreamEvent"
+ | "sendEvent"]: Mock>;
+};
+
+class MockSignal implements MeldSignal {
+ readonly #listeners = new Set<(...args: Args) => void>();
+
+ connect(callback: (...args: Args) => void): void {
+ this.#listeners.add(callback);
+ }
+
+ disconnect(callback: (...args: Args) => void): void {
+ this.#listeners.delete(callback);
+ }
+
+ emit(...args: Args): void {
+ for (const callback of [...this.#listeners]) callback(...args);
+ }
+}
+
+type Endpoint = { server?: MockWebChannel };
+const endpoints = new Map();
+let nextPort = 45_000;
+
+class MockAttempt implements WebChannelHandle {
+ readonly #callbacks: WebChannelCallbacks;
+ server?: MockWebChannel;
+ #closed = false;
+ #notifyClosed = false;
+
+ constructor(callbacks: WebChannelCallbacks, server?: MockWebChannel) {
+ this.#callbacks = callbacks;
+ if (server) {
+ this.server = server;
+ server.accept(this);
+ } else {
+ // A refused WebSocket cannot become connected merely because Meld starts
+ // later. It errors, closes, and a later reconnect creates a new attempt.
+ queueMicrotask(() => {
+ if (this.#closed) return;
+ this.#callbacks.error();
+ this.drop();
+ });
+ }
+ }
+
+ ready(meld: MeldObject | undefined): void {
+ queueMicrotask(() => {
+ if (!this.#closed && this.server) this.#callbacks.ready(meld);
+ });
+ }
+
+ drop(): void {
+ if (this.#closed) return;
+ this.#closed = true;
+ this.#notifyClosed = true;
+ this.server?.detach(this);
+ this.server = undefined;
+ queueMicrotask(() => {
+ if (!this.#notifyClosed) return;
+ this.#notifyClosed = false;
+ this.#callbacks.closed();
+ });
+ }
+
+ /** Caller teardown is intentionally silent, matching the production adapter. */
+ close(): void {
+ // Match the browser adapter: caller teardown detaches a remote close that is
+ // already queued but has not yet been delivered.
+ this.#notifyClosed = false;
+ if (this.#closed) return;
+ this.#closed = true;
+ this.server?.detach(this);
+ this.server = undefined;
+ }
+}
+
+/** Result-level opener injected into MeldConnection; no Qt frame is modelled. */
+export const openMockWebChannel: OpenWebChannel = (url, callbacks) => {
+ const endpoint = endpoints.get(Number(new URL(url).port));
+ return new MockAttempt(callbacks, endpoint?.server);
+};
+
+/**
+ * A controllable Meld result object plus a WebSocket-like lifecycle.
+ *
+ * Public methods are `node:test` mocks. Private state is deliberately separate
+ * from `meld.session`: callers see a new snapshot only when sessionChanged is
+ * published, just as they do across the real serialized WebChannel boundary.
+ */
+export class MockWebChannel {
+ readonly methods: MockMeldMethods;
+ readonly #options: MockWebChannelOptions;
+ readonly #attempts = new Set();
+ readonly #observers = new Map>();
+ readonly #pendingEchoes = new Set>();
+ readonly #sessionChanged = new MockSignal<[]>();
+ readonly #streamingChanged = new MockSignal<[]>();
+ readonly #recordingChanged = new MockSignal<[]>();
+ readonly #gainUpdated = new MockSignal<[string, number, boolean]>();
+
+ #state: FakeSession;
+ #gains: Record;
+ #streaming: boolean;
+ #recording: boolean;
+ #accepted = 0;
+ #port?: number;
+ #sessionTimer?: ReturnType;
+ #debounceOverride?: number;
+ readonly #meld: MeldObject;
+
+ constructor(scenario: Scenario, options: MockWebChannelOptions = {}) {
+ this.#state = structuredClone(scenario.session);
+ this.#gains = { ...scenario.gains };
+ this.#streaming = scenario.isStreaming;
+ this.#recording = scenario.isRecording;
+ this.#options = options;
+
+ this.methods = {
+ setClientName: mock.fn((_name: string) => {}),
+ showScene: mock.fn((sceneId: string) => this.showScene(sceneId)),
+ setStagedScene: mock.fn((sceneId: string) => this.#setStagedScene(sceneId)),
+ showStagedScene: mock.fn(() => this.#showStagedScene()),
+ toggleMute: mock.fn((trackId: string) => this.#toggleMute(trackId)),
+ toggleMonitor: mock.fn((trackId: string) => this.#toggleMonitor(trackId)),
+ toggleLayer: mock.fn((sceneId: string, layerId: string) => this.#toggleLayer(sceneId, layerId)),
+ toggleEffect: mock.fn((sceneId: string, layerId: string, effectId: string) =>
+ this.#toggleEffect(sceneId, layerId, effectId)),
+ toggleRecord: mock.fn(() => this.setRecording(!this.#recording)),
+ toggleStream: mock.fn(() => this.setStreaming(!this.#streaming)),
+ setGain: mock.fn((trackId: string, gain: number) => this.setGain(trackId, gain)),
+ setMuted: mock.fn((trackId: string, muted: boolean) => this.setMuted(trackId, muted)),
+ setProperty: mock.fn((objectId: string, propertyName: string, value: unknown) =>
+ this.#setProperty(objectId, propertyName, value)),
+ registerTrackObserver: mock.fn((context: string, trackId: string) =>
+ this.#registerTrackObserver(context, trackId)),
+ unregisterTrackObserver: mock.fn((context: string, trackId: string) =>
+ this.#unregisterTrackObserver(context, trackId)),
+ callFunction: mock.fn((layerId: string, command: string) => this.#callFunction(layerId, command)),
+ callFunctionWithArgs: mock.fn((layerId: string, command: string, _args: unknown[]) =>
+ this.#callFunction(layerId, command)),
+ sendCommand: mock.fn((_command: string) => {}),
+ sendCommandWithArgs: mock.fn((_commandName: string, _args: unknown[]) => {}),
+ sendStreamEvent: mock.fn((_type: string, _data?: unknown) => {}),
+ sendEvent: mock.fn((_event: string) => {}),
+ };
+
+ this.#meld = {
+ version: 3,
+ session: structuredClone(this.#state),
+ isStreaming: this.#streaming,
+ isRecording: this.#recording,
+ sessionChanged: this.#sessionChanged,
+ isStreamingChanged: this.#streamingChanged,
+ isRecordingChanged: this.#recordingChanged,
+ gainUpdated: options.omitObserverApi ? undefined : this.#gainUpdated,
+ ...this.methods,
+ };
+ if (options.omitObserverApi) {
+ this.#meld.registerTrackObserver = undefined;
+ this.#meld.unregisterTrackObserver = undefined;
+ }
+ }
+
+ get meld(): MeldObject {
+ return this.#meld;
+ }
+
+ /** Internal Meld state, useful for asserting the eventual command result. */
+ get session(): FakeSession {
+ return structuredClone(this.#state);
+ }
+
+ get clientCount(): number {
+ return this.#attempts.size;
+ }
+
+ get acceptedConnections(): number {
+ return this.#accepted;
+ }
+
+ get callCount(): number {
+ return Object.values(this.methods).reduce((sum, method) => sum + method.mock.callCount(), 0);
+ }
+
+ resetCalls(): void {
+ for (const method of Object.values(this.methods)) method.mock.resetCalls();
+ }
+
+ async listen(port: number): Promise {
+ const selected = port === 0 ? nextPort++ : port;
+ const endpoint = endpoints.get(selected);
+ if (endpoint?.server && endpoint.server !== this) {
+ throw new Error(`mock WebChannel port ${selected} is already in use`);
+ }
+ if (this.#port !== undefined && this.#port !== selected) {
+ throw new Error("a mock WebChannel instance cannot move between ports");
+ }
+ this.#port = selected;
+ endpoints.set(selected, { server: this });
+ return selected;
+ }
+
+ async close(): Promise {
+ for (const timer of this.#pendingEchoes) clearTimeout(timer);
+ this.#pendingEchoes.clear();
+ if (this.#sessionTimer) clearTimeout(this.#sessionTimer);
+ this.#sessionTimer = undefined;
+ this.#observers.clear();
+ if (this.#port !== undefined && endpoints.get(this.#port)?.server === this) endpoints.delete(this.#port);
+ for (const attempt of [...this.#attempts]) attempt.drop();
+ this.#port = undefined;
+ }
+
+ accept(attempt: MockAttempt): void {
+ this.#accepted++;
+ this.#attempts.add(attempt);
+ if (!this.#options.stallHandshake) attempt.ready(this.#options.omitMeldObject ? undefined : this.#meld);
+ }
+
+ detach(attempt: MockAttempt): void {
+ this.#attempts.delete(attempt);
+ }
+
+ loadScenario(scenario: Scenario): void {
+ this.#state = structuredClone(scenario.session);
+ this.#gains = { ...scenario.gains };
+ this.#streaming = scenario.isStreaming;
+ this.#recording = scenario.isRecording;
+ this.#observers.clear();
+ this.#publishSession();
+ this.#meld.isStreaming = this.#streaming;
+ this.#meld.isRecording = this.#recording;
+ this.#streamingChanged.emit();
+ this.#recordingChanged.emit();
+ }
+
+ setSessionDebounce(delayMs: number | undefined): void {
+ this.#debounceOverride = delayMs;
+ }
+
+ gainOf(trackId: string): number | undefined {
+ return this.#gains[trackId];
+ }
+
+ setStreaming(streaming: boolean): void {
+ this.#streaming = streaming;
+ this.#meld.isStreaming = streaming;
+ this.#streamingChanged.emit();
+ }
+
+ setRecording(recording: boolean): void {
+ this.#recording = recording;
+ this.#meld.isRecording = recording;
+ this.#recordingChanged.emit();
+ }
+
+ setGain(trackId: string, gain: number): void {
+ if (!this.#track(trackId)) return;
+ this.#gains[trackId] = Math.min(1, Math.max(0, gain));
+ this.#emitGain(trackId);
+ }
+
+ emitGainOnly(trackId: string, gain: number, muted: boolean): void {
+ this.#gains[trackId] = gain;
+ this.#gainUpdated.emit(trackId, gain, muted);
+ }
+
+ setMuted(trackId: string, muted: boolean): void {
+ const track = this.#track(trackId);
+ if (!track) return;
+ track.muted = muted;
+ this.#emitGain(trackId);
+ this.#publishSession();
+ }
+
+ showScene(sceneId: string): void {
+ const target = this.#scene(sceneId);
+ if (!target) return;
+ for (const item of Object.values(this.#state.items)) if (item.type === "scene") item.current = false;
+ target.current = true;
+ this.#publishSession();
+ }
+
+ #setStagedScene(sceneId: string): void {
+ const scene = this.#scene(sceneId);
+ if (!scene || scene.vertical || scene.current) return;
+ for (const item of Object.values(this.#state.items)) if (item.type === "scene") item.staged = false;
+ scene.staged = true;
+ this.#publishSessionNow();
+ }
+
+ #showStagedScene(): void {
+ const scenes = Object.values(this.#state.items).filter((item): item is FakeScene => item.type === "scene");
+ const current = scenes.find((scene) => scene.current);
+ const staged = scenes.find((scene) => scene.staged);
+ if (current) { current.current = false; current.staged = true; }
+ if (staged) { staged.staged = false; staged.current = true; }
+ this.#publishSessionNow();
+ }
+
+ #toggleMute(trackId: string): void {
+ const track = this.#track(trackId);
+ if (track) this.setMuted(trackId, !track.muted);
+ }
+
+ #toggleMonitor(trackId: string): void {
+ const track = this.#track(trackId);
+ if (!track) return;
+ track.monitoring = !track.monitoring;
+ this.#publishSession();
+ }
+
+ #toggleLayer(sceneId: string, layerId: string): void {
+ const layer = this.#layerIn(sceneId, layerId);
+ if (!layer) return;
+ layer.visible = !layer.visible;
+ layer.isEffectivelyVisible = layer.visible;
+ this.#publishSession();
+ }
+
+ #toggleEffect(sceneId: string, layerId: string, effectId: string): void {
+ if (!this.#layerIn(sceneId, layerId)) return;
+ const direct = this.#state.items[effectId];
+ const effect = direct?.type === "effect" && direct.parent === layerId ? direct : undefined;
+ if (!effect) return;
+ effect.enabled = !effect.enabled;
+ this.#publishSession();
+ }
+
+ #setProperty(objectId: string, propertyName: string, value: unknown): void {
+ const item = this.#state.items[objectId];
+ if (!item) return;
+ (item as unknown as Record)[propertyName] = value;
+ if (item.type === "track" && propertyName === "muted") this.#emitGain(objectId);
+ this.#publishSession();
+ }
+
+ #registerTrackObserver(context: string, trackId: string): void {
+ if (!this.#track(trackId)) return;
+ const contexts = this.#observers.get(trackId) ?? new Set();
+ contexts.add(context);
+ this.#observers.set(trackId, contexts);
+ this.#emitGain(trackId);
+ }
+
+ #unregisterTrackObserver(context: string, trackId: string): void {
+ const contexts = this.#observers.get(trackId);
+ contexts?.delete(context);
+ if (contexts?.size === 0) this.#observers.delete(trackId);
+ }
+
+ #callFunction(layerId: string, command: string): void {
+ const layer = this.#state.items[layerId];
+ if (layer?.type !== "layer" || layer.mediaSource === undefined) return;
+ if (command === "play") layer.isPlaying = true;
+ else if (command === "pause") layer.isPlaying = false;
+ else if (command !== "seekTo" && command !== "skipBack") return;
+ this.#publishSession();
+ }
+
+ #layerIn(sceneId: string, layerId: string): FakeLayer | undefined {
+ const layer = this.#state.items[layerId];
+ return this.#scene(sceneId) && layer?.type === "layer" && layer.parent === sceneId ? layer : undefined;
+ }
+
+ #track(id: string): FakeTrack | undefined {
+ const item = this.#state.items[id];
+ return item?.type === "track" ? item : undefined;
+ }
+
+ #scene(id: string): FakeScene | undefined {
+ const item = this.#state.items[id];
+ return item?.type === "scene" ? item : undefined;
+ }
+
+ #emitGain(trackId: string): void {
+ if (!this.#observers.has(trackId)) return;
+ const gain = this.#gains[trackId] ?? 0;
+ const muted = this.#track(trackId)?.muted ?? false;
+ const delay = this.#options.echoDelayMs ?? 0;
+ if (delay <= 0) return this.#gainUpdated.emit(trackId, gain, muted);
+ const timer = setTimeout(() => {
+ this.#pendingEchoes.delete(timer);
+ this.#gainUpdated.emit(trackId, gain, muted);
+ }, delay);
+ this.#pendingEchoes.add(timer);
+ }
+
+ #publishSessionNow(): void {
+ if (this.#sessionTimer) clearTimeout(this.#sessionTimer);
+ this.#sessionTimer = undefined;
+ this.#meld.session = structuredClone(this.#state);
+ this.#sessionChanged.emit();
+ }
+
+ #publishSession(): void {
+ const delay = this.#debounceOverride ?? this.#options.sessionDebounceMs ?? MELD_SESSION_DEBOUNCE_MS;
+ if (delay <= 0) return this.#publishSessionNow();
+ if (this.#sessionTimer) clearTimeout(this.#sessionTimer);
+ this.#sessionTimer = setTimeout(() => {
+ this.#sessionTimer = undefined;
+ this.#meld.session = structuredClone(this.#state);
+ this.#sessionChanged.emit();
+ }, delay);
+ }
+}
diff --git a/test/helpers/session-builder.ts b/test/helpers/session-builder.ts
new file mode 100644
index 0000000..9ee5267
--- /dev/null
+++ b/test/helpers/session-builder.ts
@@ -0,0 +1,260 @@
+// Copyright (c) 2024 Meld Studio, Inc.
+// Licensed under the MIT license. See LICENSE file in the project root for details.
+//
+// Builders for the session snapshot Meld Studio publishes over the WebChannel.
+//
+// The shapes here mirror Meld/StreamDeckMapper.cpp exactly — `sceneToMap`,
+// `layerToMap`, `effectsToMap` and `audioTrackToMap` — so a scenario built with
+// these helpers is indistinguishable from a real `mapper.filteredMap`. Note in
+// particular that a track carries NO `gain` field: gain reaches the plugin only
+// through the `gainUpdated` signal.
+
+/** The wire snapshot: `{ items: { : item } }`, as `map["items"]` produces. */
+export type FakeSession = { items: Record };
+
+/** Any item that can appear in the snapshot. */
+export type FakeItem = FakeScene | FakeLayer | FakeEffect | FakeTrack;
+
+/** Mirrors `sceneToMap`. */
+export type FakeScene = {
+ type: "scene";
+ name: string;
+ current: boolean;
+ staged: boolean;
+ vertical: boolean;
+ index: number;
+};
+
+/** Mirrors `layerToMap`. Optional fields appear only when the source object has them. */
+export type FakeLayer = {
+ type: "layer";
+ name: string;
+ parent: string;
+ index: number;
+ visible: boolean;
+ isEffectivelyVisible: boolean;
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+ rotation: number;
+ isPlaying?: boolean;
+ mediaSource?: string;
+ source?: string;
+ url?: string;
+ text?: string;
+};
+
+/** Mirrors `effectsToMap`. */
+export type FakeEffect = {
+ type: "effect";
+ name: string;
+ parent: string;
+ enabled: boolean;
+};
+
+/** Mirrors `audioTrackToMap`; `parent` is present only for scene-owned tracks. */
+export type FakeTrack = {
+ type: "track";
+ name: string;
+ muted: boolean;
+ monitoring: boolean;
+ parent?: string;
+};
+
+/** Gain lives outside the snapshot, exactly as it does in Meld. */
+export type TrackGain = { gain: number };
+
+/**
+ * A complete scenario: the snapshot plus the out-of-band state Meld keeps
+ * separately (per-track gain, and the streaming/recording flags).
+ */
+export type Scenario = {
+ name: string;
+ description: string;
+ session: FakeSession;
+ gains: Record;
+ isStreaming: boolean;
+ isRecording: boolean;
+};
+
+/**
+ * Generates a deterministic 32-char uppercase hex id, the format Meld uses.
+ * Deterministic so scenarios are reproducible between runs — but distinct per
+ * `seed`, so "a different Meld instance" really does mean all-new ids.
+ * @param seed Any string; the same seed always yields the same id.
+ */
+export function itemId(seed: string): string {
+ // FNV-1a, expanded to 128 bits by hashing four salted variants.
+ const block = (salt: string): string => {
+ let hash = 0x811c9dc5;
+ for (const char of `${salt}:${seed}`) {
+ hash ^= char.codePointAt(0) as number;
+ hash = Math.imul(hash, 0x01000193) >>> 0;
+ }
+ return hash.toString(16).padStart(8, "0");
+ };
+ return `${block("a")}${block("b")}${block("c")}${block("d")}`.toUpperCase();
+}
+
+/** Historical settings form accepted only long enough to migrate to a stable effect id. */
+export function indexedEffectId(layerId: string, index: number): string {
+ return `${layerId}-${index}`;
+}
+
+/** Fluent builder that assembles a scenario's snapshot in Meld's own shape. */
+export class SessionBuilder {
+ readonly #items: Record = {};
+ readonly #gains: Record = {};
+ readonly #namespace: string;
+ // Meld walks the horizontal and vertical scene models in separate loops, each
+ // numbering from 0, so a vertical twin can share an index with a horizontal
+ // scene. Two counters reproduce that rather than inventing unique indices.
+ #sceneIndex = 0;
+ #verticalSceneIndex = 0;
+
+ /**
+ * @param namespace Salts every generated id. Two builders with different
+ * namespaces never produce the same id even for identically-named items,
+ * which is what makes one scenario a genuinely different Meld instance from
+ * another rather than the same project reopened.
+ */
+ constructor(namespace: string) {
+ this.#namespace = namespace;
+ }
+
+ /** Namespaced id for an item, so scenarios cannot collide. */
+ #id(seed: string): string {
+ return itemId(`${this.#namespace}/${seed}`);
+ }
+
+ /**
+ * Adds a scene.
+ * @param name Display name; vertical scenes get Meld's " [Vertical]" suffix.
+ * @param options `current`/`staged` flags and whether it is a vertical scene.
+ */
+ scene(name: string, options: { current?: boolean; staged?: boolean; vertical?: boolean } = {}): string {
+ const id = this.#id(`scene:${name}:${options.vertical ? "v" : "h"}`);
+ this.#items[id] = {
+ type: "scene",
+ name: options.vertical ? `${name} [Vertical]` : name,
+ current: options.current ?? false,
+ staged: options.staged ?? false,
+ vertical: options.vertical ?? false,
+ index: options.vertical ? this.#verticalSceneIndex++ : this.#sceneIndex++,
+ };
+ return id;
+ }
+
+ /**
+ * Adds a layer to a scene.
+ * @param parent Owning scene id.
+ * @param name Layer name (Meld prefixes ancestors with "/" for nested layers).
+ * @param options Visibility, ordering, and any media/source extras.
+ */
+ layer(
+ parent: string,
+ name: string,
+ options: {
+ visible?: boolean;
+ index?: number;
+ mediaSource?: string;
+ isPlaying?: boolean;
+ source?: string;
+ url?: string;
+ text?: string;
+ } = {},
+ ): string {
+ const id = this.#id(`layer:${parent}:${name}`);
+ const visible = options.visible ?? true;
+ const layer: FakeLayer = {
+ type: "layer",
+ name,
+ parent,
+ index:
+ options.index ??
+ Object.values(this.#items).filter((i) => i.type === "layer" && i.parent === parent).length,
+ visible,
+ isEffectivelyVisible: visible,
+ x: 0,
+ y: 0,
+ width: 1920,
+ height: 1080,
+ rotation: 0,
+ };
+ // Meld only emits these keys when the underlying object exposes them.
+ if (options.mediaSource !== undefined) {
+ layer.mediaSource = options.mediaSource;
+ layer.isPlaying = options.isPlaying ?? false;
+ }
+ if (options.source !== undefined) {
+ layer.source = options.source;
+ }
+ if (options.url !== undefined) {
+ layer.url = options.url;
+ }
+ if (options.text !== undefined) {
+ layer.text = options.text;
+ }
+ this.#items[id] = layer;
+ return id;
+ }
+
+ /**
+ * Adds an effect to a layer.
+ *
+ * Effects are keyed by the stable id published by
+ * `effectsToMap(effect, map, effect->idString(), parent)`.
+ * @param parent Owning layer id.
+ * @param name Effect display name.
+ * @param options `enabled` state.
+ */
+ effect(parent: string, name: string, options: { enabled?: boolean } = {}): string {
+ const id = this.#id(`effect:${parent}:${name}`);
+ this.#items[id] = { type: "effect", name, parent, enabled: options.enabled ?? true };
+ return id;
+ }
+
+ /**
+ * Adds an audio track.
+ * @param name Track name (the replay clip's track is named "Replay Clip").
+ * @param options Mute/monitor state, owning layer, and starting gain.
+ */
+ track(name: string, options: { muted?: boolean; monitoring?: boolean; parent?: string; gain?: number } = {}): string {
+ const id = this.#id(`track:${name}`);
+ const track: FakeTrack = {
+ type: "track",
+ name,
+ muted: options.muted ?? false,
+ monitoring: options.monitoring ?? false,
+ };
+ if (options.parent !== undefined) {
+ track.parent = options.parent;
+ }
+ this.#items[id] = track;
+ // Gain is deliberately kept out of the snapshot, matching Meld.
+ this.#gains[id] = options.gain ?? 1;
+ return id;
+ }
+
+ /** Produces the finished scenario. */
+ build(name: string, description: string, flags: { streaming?: boolean; recording?: boolean } = {}): Scenario {
+ // Meld builds `items` as a QVariantMap, which Qt serializes with the keys in
+ // lexicographic order of the item id — so the wire order is unrelated to
+ // creation order, and types are interleaved. Anything that walks
+ // `Object.keys(items)` sees that order in production, so the fake must serve
+ // it too; insertion order would flatter code that depends on grouping.
+ const sorted: Record = {};
+ for (const id of Object.keys(this.#items).sort()) {
+ sorted[id] = this.#items[id];
+ }
+ return {
+ name,
+ description,
+ session: { items: structuredClone(sorted) },
+ gains: { ...this.#gains },
+ isStreaming: flags.streaming ?? false,
+ isRecording: flags.recording ?? false,
+ };
+ }
+}
diff --git a/test/media-show-scene.test.ts b/test/media-show-scene.test.ts
new file mode 100644
index 0000000..a2602ae
--- /dev/null
+++ b/test/media-show-scene.test.ts
@@ -0,0 +1,525 @@
+// Copyright (c) 2024 Meld Studio, Inc.
+// Licensed under the MIT license. See LICENSE file in the project root for details.
+//
+// Two actions whose keys must not lie about state they cannot confirm: the media
+// key through a reconnect blip, and the show-scene key when its stored scene
+// belongs to a Meld instance that is no longer running.
+
+import assert from "node:assert/strict";
+import { after, before, beforeEach, describe, test } from "node:test";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import { Media } from "../src/actions/media.ts";
+import { ShowScene } from "../src/actions/show-scene.ts";
+import { MeldConnection } from "../src/meld/connection.ts";
+import { type Scenario, SessionBuilder } from "./helpers/session-builder.ts";
+import { FakeActionInstance, keyEvent, mount, press, retarget, willAppear } from "./helpers/fake-stream-deck.ts";
+import { MockWebChannel, openMockWebChannel } from "./helpers/mock-web-channel.ts";
+
+/** A scene with a playing media layer. */
+function build(): { scenario: Scenario; ids: Record } {
+ const b = new SessionBuilder("ms");
+ const scene = b.scene("Live", { current: true });
+ const other = b.scene("Break");
+ const third = b.scene("Interlude");
+ const clip = b.layer(scene, "Clip", { mediaSource: "clip.mp4", isPlaying: true });
+ const clipB = b.layer(scene, "Clip B", { mediaSource: "other.mp4", isPlaying: true });
+ const track = b.track("Microphone", { gain: 0.6 });
+ return { scenario: b.build("ms", "media"), ids: { scene, other, third, clip, clipB, track } };
+}
+
+describe("Media and ShowScene", () => {
+ let server: MockWebChannel;
+ let connection: MeldConnection;
+ let ids: Record;
+ let port = 0;
+
+ before(async () => {
+ const built = build();
+ ids = built.ids;
+ server = new MockWebChannel(built.scenario);
+ port = await server.listen(0);
+ connection = new MeldConnection({ port, handshakeTimeoutMs: 300, reconnectMinMs: 100, openWebChannel: openMockWebChannel });
+ const ready = new Promise((resolve) => {
+ const off = connection.on("ready", () => {
+ off();
+ resolve();
+ });
+ });
+ connection.connect();
+ await ready;
+ });
+
+ after(async () => {
+ connection.dispose();
+ await server.close();
+ });
+
+ beforeEach(async () => {
+ server.loadScenario(build().scenario);
+ server.resetCalls();
+ await sleep(40);
+ });
+
+ test("the media key shows the playing state", async () => {
+ const action = new Media(connection);
+ const key = new FakeActionInstance("m", { scene: ids.scene, layer: ids.clip, action: "toggle" });
+ mount(action, [key]);
+ await action.onWillAppear(willAppear(key, { scene: ids.scene, layer: ids.clip, action: "toggle" }) as never);
+ await sleep(60);
+
+ assert.ok(key.image?.includes("pause"), `a playing clip shows the pause icon, got ${key.image}`);
+ });
+
+ test("a media press converges on the playback state Meld reports back", async () => {
+ // The press paints optimistically, but the authoritative answer arrives in
+ // the republished snapshot. Both must agree, or the key flips to the wrong
+ // icon shortly after every press.
+ const settings = { scene: ids.scene, layer: ids.clip, action: "toggle" };
+ const action = new Media(connection);
+ const key = new FakeActionInstance("m", settings);
+ mount(action, [key]);
+ await action.onWillAppear(willAppear(key, settings) as never);
+ await sleep(60);
+ assert.ok(key.image?.includes("pause"), "the clip starts playing");
+
+ // Toggle: playing -> paused.
+ await press(action, key, settings);
+ await sleep(150);
+ assert.equal(
+ (server.session.items[ids.clip] as { isPlaying: boolean }).isPlaying,
+ false,
+ "Meld should have paused the clip",
+ );
+ assert.ok(key.image?.includes("play"), `a paused clip shows the play icon, got ${key.image}`);
+
+ // And back again.
+ await press(action, key, settings);
+ await sleep(150);
+ assert.equal((server.session.items[ids.clip] as { isPlaying: boolean }).isPlaying, true);
+ assert.ok(key.image?.includes("pause"), `a playing clip shows the pause icon, got ${key.image}`);
+ });
+
+ test("two toggle presses inside Meld's debounce alternate rather than repeat", async () => {
+ // `isPlaying` only refreshes when Meld republishes the session, behind its
+ // autosave debounce. A second press in that window must act on the pending
+ // intent, not re-read the pre-press snapshot and send the same command.
+ const slow = new MockWebChannel(build().scenario, { sessionDebounceMs: 600 });
+ const slowPort = await slow.listen(0);
+ const slowConnection = new MeldConnection({ port: slowPort, reconnectMinMs: 100, openWebChannel: openMockWebChannel });
+ const slowIds = build().ids;
+
+ try {
+ const ready = new Promise((resolve) => {
+ const off = slowConnection.on("ready", () => {
+ off();
+ resolve();
+ });
+ });
+ slowConnection.connect();
+ await ready;
+
+ const settings = { scene: slowIds.scene, layer: slowIds.clip, action: "toggle" };
+ const action = new Media(slowConnection);
+ const key = new FakeActionInstance("m", settings);
+ mount(action, [key]);
+ await action.onWillAppear(willAppear(key, settings) as never);
+ await sleep(60);
+ slow.resetCalls();
+
+ await press(action, key, settings); // playing -> pause
+ await sleep(120);
+ await press(action, key, settings); // still inside the debounce
+ await sleep(120);
+
+ const members = slow.methods.callFunction.mock.calls.map((call) => call.arguments[1]);
+ assert.deepEqual(members, ["pause", "play"], "the second press must resume, not pause again");
+ assert.ok(key.image?.includes("pause"), "and the key shows the playing state it asked for");
+ } finally {
+ slowConnection.dispose();
+ await slow.close();
+ }
+ });
+
+ test("a pending press is dropped when the key is retargeted to another layer", async () => {
+ // The inspector can retarget a key seconds after a press, while the first
+ // clip's confirmation is still outstanding. Carrying that pending value over
+ // would show the inverse of the new clip's state and send the wrong command.
+ const slow = new MockWebChannel(build().scenario, { sessionDebounceMs: 600 });
+ const slowPort = await slow.listen(0);
+ const slowConnection = new MeldConnection({ port: slowPort, reconnectMinMs: 100, openWebChannel: openMockWebChannel });
+ const slowIds = build().ids;
+
+ try {
+ const ready = new Promise((resolve) => {
+ const off = slowConnection.on("ready", () => {
+ off();
+ resolve();
+ });
+ });
+ slowConnection.connect();
+ await ready;
+
+ const first = { scene: slowIds.scene, layer: slowIds.clip, action: "toggle" };
+ const action = new Media(slowConnection);
+ const key = new FakeActionInstance("m", first);
+ mount(action, [key]);
+ await action.onWillAppear(willAppear(key, first) as never);
+ await sleep(60);
+
+ await press(action, key, first); // clip -> paused (pending, unconfirmed)
+ await sleep(60);
+ slow.resetCalls();
+
+ // Retarget to the second media layer, which is playing.
+ const second = { scene: slowIds.scene, layer: slowIds.clipB, action: "toggle" };
+ await retarget(action, key, second);
+ await sleep(60);
+ assert.ok(key.image?.includes("pause"), `the new clip is playing, got ${key.image}`);
+
+ await press(action, key, second);
+ await sleep(80);
+ assert.deepEqual(
+ slow.methods.callFunction.mock.calls.at(-1)?.arguments,
+ [slowIds.clipB, "pause"],
+ "the press must act on the new layer's real state",
+ );
+ } finally {
+ slowConnection.dispose();
+ await slow.close();
+ }
+ });
+
+ test("a media press holds its icon across a retriggered autosave", async () => {
+ // The optimistic TTL has to outlast Meld's retriggerable debounce, or the
+ // key flips back to the pre-press icon and then forward again.
+ const slow = new MockWebChannel(build().scenario, { sessionDebounceMs: 600 });
+ const slowPort = await slow.listen(0);
+ const slowConnection = new MeldConnection({ port: slowPort, reconnectMinMs: 100, openWebChannel: openMockWebChannel });
+ const slowIds = build().ids;
+
+ try {
+ const ready = new Promise((resolve) => {
+ const off = slowConnection.on("ready", () => {
+ off();
+ resolve();
+ });
+ });
+ slowConnection.connect();
+ await ready;
+
+ const settings = { scene: slowIds.scene, layer: slowIds.clip, action: "toggle" };
+ const action = new Media(slowConnection);
+ const key = new FakeActionInstance("m", settings);
+ mount(action, [key]);
+ await action.onWillAppear(willAppear(key, settings) as never);
+ await sleep(60);
+
+ await press(action, key, settings); // playing -> paused
+ key.reset();
+ for (let i = 0; i < 6; i++) {
+ slow.setMuted(slowIds.track, i % 2 === 0);
+ await sleep(150);
+ }
+ await sleep(800);
+
+ assert.ok(
+ !key.images.some((image) => image?.includes("pause")),
+ `the key must not flip back to the pre-press icon; painted ${JSON.stringify(key.images)}`,
+ );
+ } finally {
+ slowConnection.dispose();
+ await slow.close();
+ }
+ });
+
+ test("restart uses Meld's own skip-back, which respects a clip's loop point", async () => {
+ const settings = { scene: ids.scene, layer: ids.clip, action: "restart" };
+ const action = new Media(connection);
+ const key = new FakeActionInstance("m", settings);
+ mount(action, [key]);
+ await action.onWillAppear(willAppear(key, settings) as never);
+ await sleep(60);
+
+ await press(action, key, settings);
+ await sleep(80);
+
+ // seekTo(0) would jump outside a trimmed clip's configured region.
+ assert.deepEqual(server.methods.callFunction.mock.calls.at(-1)?.arguments, [ids.clip, "skipBack"]);
+ assert.equal(server.methods.callFunctionWithArgs.mock.callCount(), 0);
+ });
+
+ test("fixed play and pause modes dispatch directly and paint uniform icons", async () => {
+ for (const mode of ["play", "pause"] as const) {
+ server.resetCalls();
+ const settings = { scene: ids.scene, layer: ids.clip, action: mode };
+ const action = new Media(connection);
+ const key = new FakeActionInstance(`media-${mode}`, settings);
+ mount(action, [key]);
+ await action.onWillAppear(willAppear(key, settings) as never);
+ await press(action, key, settings);
+
+ assert.deepEqual(server.methods.callFunction.mock.calls.at(-1)?.arguments, [ids.clip, mode]);
+ assert.ok(key.image?.includes(`media-controls-${mode}`), `${mode} should paint its fixed icon`);
+ }
+ });
+
+ test("a stale stored scene does not make the media key inert", async () => {
+ // Upgraded profiles can hold a scene from a previous selection. Meld's
+ // callFunction resolves the layer by id alone, so the key must keep working
+ // rather than silently doing nothing — the same tolerance the toggle actions
+ // apply to their stored chains.
+ const settings = { scene: ids.other, layer: ids.clip, action: "toggle" };
+ const action = new Media(connection);
+ const key = new FakeActionInstance("m", settings);
+ mount(action, [key]);
+ await action.onWillAppear(willAppear(key, settings) as never);
+ await sleep(60);
+ assert.ok(key.image?.includes("pause"), "the key must still reflect the playing clip");
+
+ await press(action, key, settings);
+ await sleep(150);
+ assert.deepEqual(server.methods.callFunction.mock.calls.at(-1)?.arguments, [ids.clip, "pause"]);
+ });
+
+ test("the media key holds its icon through a connection blip", async () => {
+ // The clip never stopped playing; flipping to "play" would tell the user it
+ // did, and it would stay wrong for the whole reconnect.
+ const action = new Media(connection);
+ const key = new FakeActionInstance("m", { scene: ids.scene, layer: ids.clip, action: "toggle" });
+ mount(action, [key]);
+ await action.onWillAppear(willAppear(key, { scene: ids.scene, layer: ids.clip, action: "toggle" }) as never);
+ await sleep(60);
+ const before = key.image;
+ key.reset();
+
+ const closed = new Promise