@vestra-player/sdk 1.5.39 → 1.5.41

package/dist/plugin/testing.js

@@ -86,6 +86,8 @@ import { nodeProblem, VIDEO_PROCESSING_LIMITS } from "../processing.js";
 import { shaderIdProblem, shaderListProblem } from "./shaders.js";
 import { RENDER_DEFAULTS, renderProblem, VIEW_DEFAULTS, viewProblem, } from "./view.js";
 import { createPlugin } from "./index.js";
+import { evaluate } from "./when.js";
+import { WAKE_EVENTS } from "./runtime.js";
 import { THEMES } from "./appearance.js";
 import { Catalog, format as formatTemplate, HOST_GROUPS, HOST_ZH_HANS, LOCALES, fitColumns, isTextValue, LIST_SEPARATORS, loadPackageCatalog, menuKeys, renderTemplateArgs, renderText, resolveTexts, TEXT_LIMITS, textKey, textProblem, } from "../i18n.js";
 /** Throw one of these from `host.handle(...)` to simulate a definite refusal. */
@@ -410,6 +412,16 @@ export class TestHost {
      * @since 1.5.38
      */
     listening = new Set();
+    /**
+     * Why the plugin listens to each event of {@link TestHost.listening}:
+     * every listener and every binding that reads its state, as the
+     * player's log says them (`a listener added at main.ts:12`,
+     * `command "Save" enabled is a function that reads plugin.player.state
+     * (main.ts:40) — use plugin.when`), in the order they came.
+     *
+     * @since 1.5.40
+     */
+    listeningWhy = new Map();
     /**
      * The player's source facts (phase, position, duration, paused, rate,
      * audio tracks, loop, ...). Wire-level shape; change it with
@@ -3525,6 +3537,79 @@ export class TestHost {
             },
         };
     }
+    /** A command's state as the player shows it: its conditions evaluated. */
+    #commandShown(sent, when) {
+        if (!when)
+            return sent;
+        const source = this.source;
+        const capabilities = source.capabilities;
+        const facts = {
+            phase: source.phase,
+            paused: source.paused,
+            kind: source.kind === "producer" ? "stream" : "media",
+            can: {
+                pause: capabilities.pause,
+                seek: capabilities.seek,
+                rate: capabilities.rate,
+                restart: capabilities.restart,
+                close: capabilities.close,
+                snapshot: capabilities.snapshotSource,
+                // As the player: the flags merged into the source state.
+                next: source.sequence?.next === true,
+                previous: source.sequence?.previous === true,
+            },
+            fullscreen: this.mainWindow.fullscreen,
+            theme: this.appearance,
+            language: this.language,
+        };
+        const shown = { ...sent };
+        if (when.enabled) {
+            shown.enabled = evaluate(when.enabled, facts);
+            if (shown.enabled && !shown.busy)
+                shown.reason = null;
+        }
+        if (when.checked)
+            shown.checked = evaluate(when.checked, facts);
+        return shown;
+    }
+    /**
+     * Why the player would keep this plugin running while nothing uses it
+     * (lazy activation, player 0.5.21), one line per reason, as the player's
+     * log says it: an event it listens to that is not one the player wakes
+     * it for (with what listens and where it was added), its mounted panel,
+     * its open windows. Empty: the player may stop it while idle and start
+     * it again on its next use. Filter chains, streams, jobs and the like
+     * (which also keep a plugin running) are not listed.
+     *
+     * @capability None.
+     * @since 1.5.40
+     *
+     * @example Check that a plugin can be stopped while idle
+     * The test fails if the plugin keeps running for no reason after it
+     * starts, and names the reason (a command whose `enabled` reads
+     * `plugin.player.state`, say: give it a `plugin.when` condition). The
+     * player stops such a plugin while nothing uses it and starts it again
+     * on its next use, so it costs no process meanwhile.
+     * ```ts
+     * import assert from "node:assert/strict";
+     * declare const host: TestHost;
+     * // ---cut---
+     * assert.deepEqual(host.keepsRunning, []);
+     * ```
+     */
+    get keepsRunning() {
+        const reasons = [];
+        for (const event of this.listening)
+            if (!WAKE_EVENTS.includes(event))
+                for (const why of this.listeningWhy.get(event) ?? ["a listener"])
+                    reasons.push(`listens to ${event}: ${why}`);
+        if (this.panel)
+            reasons.push("a mounted panel");
+        for (const [id, window] of this.windows)
+            if (window.visible)
+                reasons.push(`an open window (${id})`);
+        return reasons;
+    }
     #defaults = {
         "events.subscribe": (p) => {
             const event = String(p.event);
@@ -3533,10 +3618,15 @@ export class TestHost {
                 this.listening.delete(event);
             else
                 this.listening.add(event);
+            if (p.mirror !== true && Array.isArray(p.why))
+                this.listeningWhy.set(event, p.why.map(String));
+            else
+                this.listeningWhy.delete(event);
         },
         "events.unsubscribe": (p) => {
             this.subscriptions.delete(String(p.event));
             this.listening.delete(String(p.event));
+            this.listeningWhy.delete(String(p.event));
         },
         "commands.register": (p) => {
             const id = String(p.id);
@@ -3577,12 +3667,19 @@ export class TestHost {
             for (const segment of [declaration.title, ...(declaration.path ?? [])])
                 this.#declared(segment, "a menu text");
             this.#checkReason(p.state);
+            let sent = p.state;
             this.commands.set(id, {
                 declaration,
                 get display() {
                     return host.#display(declaration.path ?? [], declaration.title, this.state.reason);
                 },
-                state: p.state,
+                ...(p.when ? { when: p.when } : {}),
+                get state() {
+                    return host.#commandShown(sent, this.when);
+                },
+                set state(state) {
+                    sent = state;
+                },
                 revision: Number(p.revision),
                 async run() {
                     if (this.state.busy || !this.state.enabled)
@@ -3604,6 +3701,10 @@ export class TestHost {
             this.#checkReason(p.state);
             command.revision = Number(p.revision);
             command.state = p.state;
+            if (p.when)
+                command.when = p.when;
+            else
+                delete command.when;
             return { revision: command.revision };
         },
         "ui.open": (p) => {
@@ -4941,6 +5042,24 @@ export class TestHost {
         },
     };
 }
+/** Lines `vestra-plugin test` printed already (one per plugin and reasons). */
+const told = new Set();
+/**
+ * Under `vestra-plugin test` (`VESTRA_PLUGIN_RESIDENCY=1`): say once per
+ * test file why the plugin would keep running after it starts.
+ */
+function tellResidency(host) {
+    if (process.env.VESTRA_PLUGIN_RESIDENCY !== "1")
+        return;
+    const reasons = host.keepsRunning;
+    if (!reasons.length)
+        return;
+    const line = `${host.manifestId} keeps running while idle (lazy activation): ${reasons.join("; ")}`;
+    if (told.has(line))
+        return;
+    told.add(line);
+    console.log(`# ${line}`);
+}
 /**
  * Activate a plugin against a test host, the way the player's runner does:
  * build the `plugin` object, call `activate(plugin)`, wait for every
@@ -5052,6 +5171,7 @@ export async function startPlugin(activate, options = {}) {
         }
     }
     await host.settle();
+    tellResidency(host);
     return {
         /** The test host the plugin talks to. */
         host,

package/dist/plugin/types.d.ts

@@ -204,6 +204,13 @@ export type PluginError = Error & {
 export interface Scope extends Disposable {
     /** Menu commands and their default bindings (`commands`). */
     readonly commands: Commands;
+    /**
+     * Conditions on the player's own state for a command's `enabled` and
+     * `checked` (SDK 1.5.40, player 0.5.21): the player evaluates them, so
+     * the menu follows playback even while the plugin is stopped. See
+     * {@link When}.
+     */
+    readonly when: When;
     /** Tool windows from `.slint` files (`ui.window`). */
     readonly windows: Windows;
     /** Docked panels: bottom bar, sidebar and backdrop (`ui.mount`). */
@@ -580,6 +587,217 @@ export interface CommandState {
  * @category Commands
  */
 export type Bindable<T> = T | (() => T);
+/**
+ * A condition on the player's own state, from {@link Scope.when}, for a
+ * command's `enabled` or `checked`. The player evaluates it, again on
+ * every change of that state, whether or not the plugin runs.
+ *
+ * @remarks
+ * Combine conditions with `and`, `or` and `not`; each returns a new
+ * condition and leaves the original as it was. A condition is data: it
+ * reads nothing in the plugin and keeps no listener, so a plugin whose
+ * menu state is made of conditions may be stopped while idle (lazy
+ * activation) and its menu stays current. A function (see {@link Bindable})
+ * keeps working; one that reads `plugin.player.state` or another service's
+ * state keeps the plugin running so the SDK can evaluate it.
+ *
+ * @capability commands
+ *
+ * @example Enable an item while a frame can be saved
+ * "Save Snapshot" is greyed out with its reason unless a media file is
+ * open at a frame the player can capture. The condition is sent with the
+ * command and evaluated by the player, so the item follows playback even
+ * while the plugin is stopped; with an `enabled` condition the player
+ * shows the `reason` only while the item is disabled.
+ * ```ts
+ * declare function saveSnapshot(): Promise<void>;
+ * // ---cut---
+ * const { when } = plugin;
+ * plugin.commands.add({
+ *   id: "save",
+ *   path: ["@video", "Save Snapshot"],
+ *   enabled: when.can("snapshot").and(when.phase("ready", "ended"), when.stream.not()),
+ *   reason: "No frame to capture", // shown only while disabled
+ *   run: saveSnapshot,
+ * });
+ * ```
+ *
+ * @since 1.5.40
+ * @category Commands
+ */
+export interface Condition {
+    /**
+     * True when this condition and every one of `others` hold.
+     *
+     * @example Combine two conditions with and
+     * The item is enabled only while a file plays in fullscreen. `and`
+     * returns a new condition; `when.playing` itself is unchanged.
+     * ```ts
+     * const { when } = plugin;
+     * const playingFullscreen = when.playing.and(when.fullscreen);
+     * ```
+     *
+     * @capability None (the command it is given to needs `commands`).
+     * @since 1.5.40
+     */
+    and(...others: Condition[]): Condition;
+    /**
+     * True when this condition or one of `others` holds.
+     *
+     * @example Combine two conditions with or
+     * The item is enabled while a file plays or is paused. `or` returns a
+     * new condition that holds when either of the two holds.
+     * ```ts
+     * const { when } = plugin;
+     * const active = when.playing.or(when.paused);
+     * ```
+     *
+     * @capability None (the command it is given to needs `commands`).
+     * @since 1.5.40
+     */
+    or(...others: Condition[]): Condition;
+    /**
+     * True when this condition does not hold.
+     *
+     * @example Negate a condition with not
+     * An "Enter Fullscreen" item is enabled only outside fullscreen. `not`
+     * returns the opposite condition; the player evaluates it on every
+     * window change.
+     * ```ts
+     * const { when } = plugin;
+     * const windowed = when.fullscreen.not();
+     * ```
+     *
+     * @capability None (the command it is given to needs `commands`).
+     * @since 1.5.40
+     */
+    not(): Condition;
+}
+/**
+ * `plugin.when`: the vocabulary of conditions (SDK 1.5.40, player 0.5.21).
+ * It names only state the player owns: the source's phase, kind, pause
+ * and controls (the same names as {@link PlayerState}), fullscreen, the
+ * palette and the saved interface language.
+ *
+ * @remarks
+ * Give a condition as a command's `enabled` or `checked`
+ * ({@link CommandOptions}, {@link Command.set}). The player evaluates it
+ * and shows the result in menus, on keys and on bar buttons, again
+ * whenever that state changes, also while the plugin is stopped because
+ * nothing used it. With an `enabled` condition the player shows the
+ * command's `reason` only while the condition is false (or the command
+ * is busy), so a fixed reason is enough. Players before 0.5.21 have no
+ * `plugin.when` (declare `"minPlayerVersion": "0.5.21"`).
+ *
+ * State the vocabulary does not name (a plugin's own settings, an open
+ * window, a track list) stays a function or a value set with
+ * {@link Command.set}.
+ *
+ * @capability commands
+ *
+ * @example Check a palette item and follow the palette
+ * The Appearance submenu has one radio item per palette; the player
+ * checks the one in use, also after another plugin or the user changed
+ * it, and while this plugin is stopped. Nothing in the plugin listens to
+ * the palette.
+ * ```ts
+ * const { when } = plugin;
+ * for (const [id, title] of [["vestra", "Dark"], ["vestra-light", "Light"]] as const)
+ *   plugin.commands.add({
+ *     id: `theme.${id}`,
+ *     path: ["Settings", "Appearance", title],
+ *     radio: true,
+ *     checked: when.theme(id), // evaluated by the player, not the plugin
+ *     run: () => plugin.appearance.set(id),
+ *   });
+ * ```
+ *
+ * @since 1.5.40
+ * @category Commands
+ */
+export interface When {
+    /** A source is open: any phase but `empty` (loading, ready, ended, error). */
+    readonly open: Condition;
+    /** The source is loaded and can play (`phase` is `ready`). */
+    readonly ready: Condition;
+    /** The source is ready and not paused. */
+    readonly playing: Condition;
+    /** The source is ready and paused. */
+    readonly paused: Condition;
+    /** The source is a generated stream (`PlayerState.kind` is `stream`). */
+    readonly stream: Condition;
+    /** The main window is fullscreen. */
+    readonly fullscreen: Condition;
+    /**
+     * The source's `phase` is one of `phases`.
+     *
+     * @throws `TypeError` (throws) No phase, or one that is not a phase.
+     *
+     * @example Enable an item while a file is loaded or finished
+     * The item is enabled while the source is ready or has ended, as a
+     * snapshot needs a frame. The phases are those of `PlayerState.phase`.
+     * ```ts
+     * const { when } = plugin;
+     * const hasFrame = when.phase("ready", "ended");
+     * ```
+     *
+     * @capability None (the command it is given to needs `commands`).
+     * @since 1.5.40
+     */
+    phase(...phases: PlayerState["phase"][]): Condition;
+    /**
+     * The source allows `control`: `PlayerState.can[control]` is true.
+     *
+     * @throws `TypeError` (throws) `control` is not one of `PlayerState.can`.
+     *
+     * @example Enable a seek item only where seeking works
+     * "Jump to Middle" is greyed out on live streams that cannot seek.
+     * The player reads its own `can.seek` for the current source.
+     * ```ts
+     * const { when } = plugin;
+     * const seekable = when.can("seek");
+     * ```
+     *
+     * @capability None (the command it is given to needs `commands`).
+     * @since 1.5.40
+     */
+    can(control: keyof PlayerState["can"]): Condition;
+    /**
+     * The palette in use is `theme` (`plugin.appearance.theme`).
+     *
+     * @throws `TypeError` (throws) `theme` is not a palette of the player.
+     *
+     * @example Check the light palette's item
+     * The item carries a check mark while the light palette is in use,
+     * whoever switched to it.
+     * ```ts
+     * const { when } = plugin;
+     * const light = when.theme("vestra-light");
+     * ```
+     *
+     * @capability None (the command it is given to needs `commands`).
+     * @since 1.5.40
+     */
+    theme(theme: ThemeId): Condition;
+    /**
+     * The saved interface language is `language`
+     * (`plugin.appearance.language`: `"system"` or a locale).
+     *
+     * @throws `TypeError` (throws) `language` is not `"system"` or a locale.
+     *
+     * @example Check the Follow System item
+     * The item carries a check mark while the player follows the system's
+     * language; the player reads its own saved preference.
+     * ```ts
+     * const { when } = plugin;
+     * const followSystem = when.language("system");
+     * ```
+     *
+     * @capability None (the command it is given to needs `commands`).
+     * @since 1.5.40
+     */
+    language(language: LanguagePreference): Condition;
+}
 /**
  * A built-in top-level menu of the player, named in a command path as
  * `@<id>` or by its English key (see {@link CommandOptions.path}): Open,
@@ -620,9 +838,9 @@ export type BarButtonIcon = "play" | "pause" | "stop" | "back" | "forward" | "op
  * "…" removed) and its first key as the tooltip ("Plugin Store (F9)"),
  * `enabled`, `busy` and `reason` as the menu item has them: a disabled or
  * busy command's button is drawn disabled, its tooltip adds the reason, and
- * a click runs nothing. A command with `checked` shows its icon in the
- * accent colour while checked. A click runs the command exactly like a
- * click on its menu item.
+ * a click runs nothing. Every button's icon is drawn in the accent colour;
+ * a command with `checked` shows a small dot under its icon while checked.
+ * A click runs the command exactly like a click on its menu item.
  *
  * **Limits.** One button per plugin and eight in the player
  * (`BAR_BUTTON_LIMITS`): a button past them is left out (its command and
@@ -807,15 +1025,24 @@ export interface CommandOptions {
      * a button without a path.
      */
     button?: CommandButton;
-    /** Whether the command can run (default true). */
-    enabled?: Bindable<boolean>;
-    /** Check mark (or radio dot with `radio`); `null` (default) draws none. */
-    checked?: Bindable<boolean | null>;
+    /**
+     * Whether the command can run (default true): a value, a function, or a
+     * {@link Condition} the player evaluates (`plugin.when`, SDK 1.5.40).
+     */
+    enabled?: Bindable<boolean> | Condition;
+    /**
+     * Check mark (or radio dot with `radio`); `null` (default) draws none.
+     * A {@link Condition} (`plugin.when`, SDK 1.5.40) draws the mark while
+     * it holds.
+     */
+    checked?: Bindable<boolean | null> | Condition;
     /** Busy state (default false); the player does not call `run` while busy. */
     busy?: Bindable<boolean>;
     /**
      * Why the command is disabled or busy (shown to the user): English
      * source text, or a {@link Text} for one with data in it (SDK 1.5.11).
+     * With an `enabled` {@link Condition} the player shows it only while the
+     * condition is false or the command is busy, so a fixed text is enough.
      */
     reason?: Bindable<TextValue | null>;
     /**
@@ -894,7 +1121,10 @@ export interface Command extends Disposable {
      * @since 1.0.0
      */
     set(state: Partial<{
-        [K in keyof CommandState]: Bindable<CommandState[K]>;
+        [K in "busy" | "reason"]: Bindable<CommandState[K]>;
+    } & {
+        enabled: Bindable<boolean> | Condition;
+        checked: Bindable<boolean | null> | Condition;
     }>): void;
     /**
      * Resolves when the host has registered the command. Rejects with
@@ -8602,14 +8832,17 @@ export interface Bindings {
      */
     reset(ref?: BindingRef): Promise<void>;
     /**
-     * Declarations or overrides changed (read `list()` again). At most every 200 ms.
+     * The binding list changed (read `list()` again): a declaration or an
+     * override. At most every 200 ms; since player 0.5.21 only when the list
+     * itself changed, not when a plugin starts again with the same commands.
      *
      * @capability bindings.manage
      *
      * @example Refresh a key list when bindings change
      * The plugin's key list stays current when the user changes a key in the
-     * player or another plugin starts. The listener carries no data and runs
-     * at most every 200 ms; the plugin reads the table again with `list`.
+     * player or a plugin with other commands is installed. The listener
+     * carries no data and runs at most every 200 ms; the plugin reads the
+     * table again with `list`.
      * ```ts
      * declare function render(commands: BindingInfo[]): void;
      * // ---cut---

package/dist/plugin/ui.js

@@ -92,7 +92,8 @@ export class ViewBase {
     scope;
     handlers = new Map();
     #values = new Map();
-    #binders = new Set();
+    /** Each binding, with where the plugin added it (for the player's log). */
+    #binders = new Map();
     /** What the host currently shows, as far as this side knows. */
     #sent = new Map();
     /** Written by `set()`: sent even if equal to what was sent before. */
@@ -144,7 +145,7 @@ export class ViewBase {
         this.flush();
     }
     bind(props) {
-        this.#binders.add(props);
+        this.#binders.set(props, this.scope.runtime.callSite());
         this.scope.update();
         return this.scope.onDispose(() => {
             this.#binders.delete(props);
@@ -152,9 +153,10 @@ export class ViewBase {
     }
     /** Current desired properties (bound values win over earlier `set`). */
     snapshot() {
-        for (const binder of this.#binders) {
+        for (const [binder, site] of this.#binders) {
             try {
-                for (const [key, value] of Object.entries(encode(binder())))
+                const props = this.scope.runtime.reader("a view's bind", site, binder);
+                for (const [key, value] of Object.entries(encode(props)))
                     this.#values.set(key, value);
             }
             catch (error) {

package/dist/plugin/when.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `plugin.when`: conditions on the player's own state that the player
+ * evaluates for a command's `enabled` and `checked` (player 0.5.21). The
+ * wire form is `commands.register` / `commands.update` `when`.
+ */
+import type { Condition, LanguagePreference, PlayerState, ThemeId, When } from "./types.ts";
+/** A condition in the wire form: an object of exactly one key. */
+export type ConditionJson = {
+    phase: PlayerState["phase"][];
+} | {
+    paused: boolean;
+} | {
+    kind: PlayerState["kind"];
+} | {
+    can: keyof PlayerState["can"];
+} | {
+    fullscreen: boolean;
+} | {
+    theme: ThemeId;
+} | {
+    language: LanguagePreference;
+} | {
+    all: ConditionJson[];
+} | {
+    any: ConditionJson[];
+} | {
+    not: ConditionJson;
+};
+/** What conditions read, in the SDK's names. */
+export interface ConditionFacts {
+    phase: PlayerState["phase"];
+    paused: boolean;
+    kind: PlayerState["kind"];
+    can: Readonly<Record<string, boolean>>;
+    fullscreen: boolean;
+    theme: string;
+    language: string;
+}
+/** Whether `value` is a condition made by `plugin.when`. */
+export declare const isCondition: (value: unknown) => value is Condition;
+/** A condition's wire form; throws for anything else. */
+export declare function conditionJson(condition: Condition): ConditionJson;
+/** The one `plugin.when` (conditions hold no plugin state). */
+export declare const WHEN: When;
+/** Evaluate a wire condition as the player does (for the test host). */
+export declare function evaluate(json: ConditionJson, facts: ConditionFacts): boolean;

package/dist/plugin/when.js

@@ -0,0 +1,106 @@
+import { LOCALES } from "../i18n.js";
+import { THEMES } from "./appearance.js";
+const PHASES = [
+    "empty",
+    "loading",
+    "ready",
+    "ended",
+    "error",
+];
+const CONTROLS = [
+    "pause",
+    "seek",
+    "rate",
+    "restart",
+    "close",
+    "snapshot",
+    "next",
+    "previous",
+];
+class ConditionImpl {
+    #json;
+    constructor(json) {
+        this.#json = json;
+        Object.freeze(this);
+    }
+    and(...others) {
+        return new ConditionImpl({
+            all: [this.#json, ...others.map(conditionJson)],
+        });
+    }
+    or(...others) {
+        return new ConditionImpl({
+            any: [this.#json, ...others.map(conditionJson)],
+        });
+    }
+    not() {
+        return new ConditionImpl({ not: this.#json });
+    }
+    toJSON() {
+        return this.#json;
+    }
+    static json(condition) {
+        return condition.#json;
+    }
+}
+/** Whether `value` is a condition made by `plugin.when`. */
+export const isCondition = (value) => value instanceof ConditionImpl;
+/** A condition's wire form; throws for anything else. */
+export function conditionJson(condition) {
+    if (!(condition instanceof ConditionImpl))
+        throw new TypeError("a condition comes from plugin.when");
+    return ConditionImpl.json(condition);
+}
+const make = (json) => new ConditionImpl(json);
+/** The one `plugin.when` (conditions hold no plugin state). */
+export const WHEN = Object.freeze({
+    open: make({ not: { phase: ["empty"] } }),
+    ready: make({ phase: ["ready"] }),
+    playing: make({ all: [{ phase: ["ready"] }, { paused: false }] }),
+    paused: make({ all: [{ phase: ["ready"] }, { paused: true }] }),
+    stream: make({ kind: "stream" }),
+    fullscreen: make({ fullscreen: true }),
+    phase(...phases) {
+        if (!phases.length || phases.some((phase) => !PHASES.includes(phase)))
+            throw new TypeError(`phase is one or more of ${PHASES.join(", ")}`);
+        return make({ phase: [...phases] });
+    },
+    can(control) {
+        if (!CONTROLS.includes(control))
+            throw new TypeError(`can is one of ${CONTROLS.join(", ")}`);
+        return make({ can: control });
+    },
+    theme(theme) {
+        if (!THEMES.includes(theme))
+            throw new TypeError(`theme is ${THEMES.map((t) => `"${t}"`).join(" or ")}`);
+        return make({ theme });
+    },
+    language(language) {
+        if (language !== "system" &&
+            !LOCALES.includes(language))
+            throw new TypeError(`language is "system" or one of ${LOCALES.map((l) => `"${l}"`).join(", ")}`);
+        return make({ language });
+    },
+});
+/** Evaluate a wire condition as the player does (for the test host). */
+export function evaluate(json, facts) {
+    if ("phase" in json)
+        return json.phase.includes(facts.phase);
+    if ("paused" in json)
+        return facts.paused === json.paused;
+    if ("kind" in json)
+        return facts.kind === json.kind;
+    if ("can" in json)
+        return facts.can[json.can] === true;
+    if ("fullscreen" in json)
+        return facts.fullscreen === json.fullscreen;
+    if ("theme" in json)
+        return facts.theme === json.theme;
+    if ("language" in json)
+        return facts.language === json.language;
+    if ("all" in json)
+        return json.all.every((each) => evaluate(each, facts));
+    if ("any" in json)
+        return json.any.some((each) => evaluate(each, facts));
+    return !evaluate(json.not, facts);
+}