@energy8platform/game-engine 0.33.2 → 0.33.4

package/dist/flow.cjs.js

@@ -0,0 +1,770 @@
+'use strict';
+
+var pixi_js = require('pixi.js');
+
+// Flow step registry — the same contribution shape as scene node types (§6.2): kind +
+// runtime executor + schema/agentDoc for tooling. Core steps are built-ins registered
+// through it; games and plugins add their own `do` kinds without touching the runner.
+function createFlowStepRegistry(plugins = [], builtins = []) {
+    const steps = new Map();
+    for (const contribution of builtins)
+        steps.set(contribution.kind, contribution);
+    for (const plugin of plugins) {
+        for (const contribution of plugin.steps ?? [])
+            steps.set(contribution.kind, contribution);
+    }
+    return {
+        step: (kind) => steps.get(kind),
+        kinds: () => [...steps.keys()],
+    };
+}
+
+// Pure layout core for scene-IR.
+//
+// `resolveLayoutRule` turns one LayoutRule into a Placement given a context of already
+// laid-out rects. It is renderer-free and side-effect-free so every positioning idiom the
+// games hand-rolled (viewport fractions, frame-hollow binding, cell badges, pins) is unit
+// tested without Pixi. The interpreter (engine.ts) owns pass ordering; this module owns math.
+/**
+ * Evaluate a `visibleWhen` micro-expression: `<var> <op> <literal>` with
+ * `=== !== >= <= > <`. Unknown shapes evaluate to visible (with the engine warning once) —
+ * richer conditions belong in flow or code, not in the scene doc.
+ */
+function evalVisibleWhen(expr, vars) {
+    const m = /^\s*([A-Za-z_$][\w$]*)\s*(===|!==|>=|<=|>|<)\s*(.+?)\s*$/.exec(expr);
+    if (!m)
+        return undefined;
+    const [, name, op, rawLit] = m;
+    let lit;
+    try {
+        lit = JSON.parse(rawLit.replace(/^'(.*)'$/s, '"$1"'));
+    }
+    catch {
+        return undefined;
+    }
+    const value = vars[name];
+    switch (op) {
+        case '===':
+            return value === lit;
+        case '!==':
+            return value !== lit;
+        case '>=':
+            return Number(value) >= Number(lit);
+        case '<=':
+            return Number(value) <= Number(lit);
+        case '>':
+            return Number(value) > Number(lit);
+        case '<':
+            return Number(value) < Number(lit);
+    }
+    return undefined;
+}
+
+/**
+ * Collection of easing functions for use with Tween and Timeline.
+ *
+ * All functions take a progress value t (0..1) and return the eased value.
+ */
+const Easing = {
+    linear: (t) => t,
+    easeInQuad: (t) => t * t,
+    easeOutQuad: (t) => t * (2 - t),
+    easeInOutQuad: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
+    easeInCubic: (t) => t * t * t,
+    easeOutCubic: (t) => --t * t * t + 1,
+    easeInOutCubic: (t) => t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1,
+    easeInQuart: (t) => t * t * t * t,
+    easeOutQuart: (t) => 1 - --t * t * t * t,
+    easeInOutQuart: (t) => t < 0.5 ? 8 * t * t * t * t : 1 - 8 * --t * t * t * t,
+    easeInSine: (t) => 1 - Math.cos((t * Math.PI) / 2),
+    easeOutSine: (t) => Math.sin((t * Math.PI) / 2),
+    easeInOutSine: (t) => -(Math.cos(Math.PI * t) - 1) / 2,
+    easeInExpo: (t) => (t === 0 ? 0 : Math.pow(2, 10 * t - 10)),
+    easeOutExpo: (t) => (t === 1 ? 1 : 1 - Math.pow(2, -10 * t)),
+    easeInOutExpo: (t) => t === 0
+        ? 0
+        : t === 1
+            ? 1
+            : t < 0.5
+                ? Math.pow(2, 20 * t - 10) / 2
+                : (2 - Math.pow(2, -20 * t + 10)) / 2,
+    easeInBack: (t) => {
+        const c1 = 1.70158;
+        const c3 = c1 + 1;
+        return c3 * t * t * t - c1 * t * t;
+    },
+    easeOutBack: (t) => {
+        const c1 = 1.70158;
+        const c3 = c1 + 1;
+        return 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2);
+    },
+    easeInOutBack: (t) => {
+        const c1 = 1.70158;
+        const c2 = c1 * 1.525;
+        return t < 0.5
+            ? (Math.pow(2 * t, 2) * ((c2 + 1) * 2 * t - c2)) / 2
+            : (Math.pow(2 * t - 2, 2) * ((c2 + 1) * (t * 2 - 2) + c2) + 2) / 2;
+    },
+    easeOutBounce: (t) => {
+        const n1 = 7.5625;
+        const d1 = 2.75;
+        if (t < 1 / d1)
+            return n1 * t * t;
+        if (t < 2 / d1)
+            return n1 * (t -= 1.5 / d1) * t + 0.75;
+        if (t < 2.5 / d1)
+            return n1 * (t -= 2.25 / d1) * t + 0.9375;
+        return n1 * (t -= 2.625 / d1) * t + 0.984375;
+    },
+    easeInBounce: (t) => 1 - Easing.easeOutBounce(1 - t),
+    easeInOutBounce: (t) => t < 0.5
+        ? (1 - Easing.easeOutBounce(1 - 2 * t)) / 2
+        : (1 + Easing.easeOutBounce(2 * t - 1)) / 2,
+    easeOutElastic: (t) => {
+        const c4 = (2 * Math.PI) / 3;
+        return t === 0
+            ? 0
+            : t === 1
+                ? 1
+                : Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * c4) + 1;
+    },
+    easeInElastic: (t) => {
+        const c4 = (2 * Math.PI) / 3;
+        return t === 0
+            ? 0
+            : t === 1
+                ? 1
+                : -Math.pow(2, 10 * t - 10) * Math.sin((t * 10 - 10.75) * c4);
+    },
+};
+
+/**
+ * Lightweight tween system integrated with PixiJS Ticker.
+ * Zero external dependencies — no GSAP required.
+ *
+ * All tweens return a Promise that resolves on completion.
+ *
+ * @example
+ * ```ts
+ * // Fade in a sprite
+ * await Tween.to(sprite, { alpha: 1, y: 100 }, 500, Easing.easeOutBack);
+ *
+ * // Move and wait
+ * await Tween.to(sprite, { x: 500 }, 300);
+ *
+ * // From a starting value
+ * await Tween.from(sprite, { scale: 0, alpha: 0 }, 400);
+ * ```
+ */
+class Tween {
+    static _tweens = [];
+    static _tickerAdded = false;
+    /**
+     * Animate properties from current values to target values.
+     *
+     * @param target - Object to animate (Sprite, Container, etc.)
+     * @param props - Target property values
+     * @param duration - Duration in milliseconds
+     * @param easing - Easing function (default: easeOutQuad)
+     * @param onUpdate - Progress callback (0..1)
+     */
+    static to(target, props, duration, easing, onUpdate) {
+        // A destroyed (Pixi) target has null transform fields — skip rather than throw. This guards
+        // animations whose target is torn down mid-flight (e.g. a reel grid rebuilt during a spin).
+        if (target == null || target.destroyed)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            // Capture starting values
+            const from = {};
+            for (const key of Object.keys(props)) {
+                from[key] = Tween.getProperty(target, key);
+            }
+            const tween = {
+                target,
+                from,
+                to: { ...props },
+                duration: Math.max(1, duration),
+                easing: easing ?? Easing.easeOutQuad,
+                elapsed: 0,
+                delay: 0,
+                resolve,
+                onUpdate,
+            };
+            Tween._tweens.push(tween);
+            Tween.ensureTicker();
+        });
+    }
+    /**
+     * Animate properties from given values to current values.
+     */
+    static from(target, props, duration, easing, onUpdate) {
+        if (target == null || target.destroyed)
+            return Promise.resolve();
+        // Capture current values as "to"
+        const to = {};
+        for (const key of Object.keys(props)) {
+            to[key] = Tween.getProperty(target, key);
+            Tween.setProperty(target, key, props[key]);
+        }
+        return Tween.to(target, to, duration, easing, onUpdate);
+    }
+    /**
+     * Animate from one set of values to another.
+     */
+    static fromTo(target, fromProps, toProps, duration, easing, onUpdate) {
+        if (target == null || target.destroyed)
+            return Promise.resolve();
+        // Set starting values
+        for (const key of Object.keys(fromProps)) {
+            Tween.setProperty(target, key, fromProps[key]);
+        }
+        return Tween.to(target, toProps, duration, easing, onUpdate);
+    }
+    /**
+     * Wait for a given duration (useful in timelines).
+     * Uses PixiJS Ticker for consistent timing with other tweens.
+     */
+    static delay(ms) {
+        return new Promise((resolve) => {
+            let elapsed = 0;
+            const onTick = (ticker) => {
+                elapsed += ticker.deltaMS;
+                if (elapsed >= ms) {
+                    pixi_js.Ticker.shared.remove(onTick);
+                    resolve();
+                }
+            };
+            pixi_js.Ticker.shared.add(onTick);
+        });
+    }
+    /**
+     * Kill all tweens on a target.
+     */
+    static killTweensOf(target) {
+        Tween._tweens = Tween._tweens.filter((tw) => {
+            if (tw.target === target) {
+                tw.resolve();
+                return false;
+            }
+            return true;
+        });
+    }
+    /**
+     * Kill all active tweens.
+     */
+    static killAll() {
+        for (const tw of Tween._tweens) {
+            tw.resolve();
+        }
+        Tween._tweens.length = 0;
+    }
+    /** Number of active tweens */
+    static get activeTweens() {
+        return Tween._tweens.length;
+    }
+    /**
+     * Reset the tween system — kill all tweens and remove the ticker.
+     * Useful for cleanup between game instances, tests, or hot-reload.
+     */
+    static reset() {
+        for (const tw of Tween._tweens) {
+            tw.resolve();
+        }
+        Tween._tweens.length = 0;
+        if (Tween._tickerAdded) {
+            pixi_js.Ticker.shared.remove(Tween.tick);
+            Tween._tickerAdded = false;
+        }
+    }
+    // ─── Internal ──────────────────────────────────────────
+    static ensureTicker() {
+        if (Tween._tickerAdded)
+            return;
+        Tween._tickerAdded = true;
+        pixi_js.Ticker.shared.add(Tween.tick);
+    }
+    static tick = (ticker) => {
+        const dt = ticker.deltaMS;
+        const completed = [];
+        for (const tw of Tween._tweens) {
+            // target torn down mid-tween → finish it quietly
+            if (tw.target?.destroyed) {
+                completed.push(tw);
+                continue;
+            }
+            tw.elapsed += dt;
+            if (tw.elapsed < tw.delay)
+                continue;
+            const raw = Math.min((tw.elapsed - tw.delay) / tw.duration, 1);
+            const t = tw.easing(raw);
+            // Interpolate each property
+            for (const key of Object.keys(tw.to)) {
+                const start = tw.from[key];
+                const end = tw.to[key];
+                const value = start + (end - start) * t;
+                Tween.setProperty(tw.target, key, value);
+            }
+            tw.onUpdate?.(raw);
+            if (raw >= 1) {
+                completed.push(tw);
+            }
+        }
+        // Remove completed tweens
+        for (const tw of completed) {
+            const idx = Tween._tweens.indexOf(tw);
+            if (idx !== -1)
+                Tween._tweens.splice(idx, 1);
+            tw.resolve();
+        }
+        // Remove ticker when no active tweens
+        if (Tween._tweens.length === 0 && Tween._tickerAdded) {
+            pixi_js.Ticker.shared.remove(Tween.tick);
+            Tween._tickerAdded = false;
+        }
+    };
+    /**
+     * Get a potentially nested property (supports 'scale.x', 'position.y', etc.)
+     */
+    static getProperty(target, key) {
+        const parts = key.split('.');
+        let obj = target;
+        for (let i = 0; i < parts.length - 1; i++) {
+            obj = obj?.[parts[i]];
+        }
+        return obj?.[parts[parts.length - 1]] ?? 0;
+    }
+    /**
+     * Set a potentially nested property.
+     */
+    static setProperty(target, key, value) {
+        const parts = key.split('.');
+        let obj = target;
+        for (let i = 0; i < parts.length - 1; i++) {
+            obj = obj?.[parts[i]];
+        }
+        if (obj == null)
+            return;
+        obj[parts[parts.length - 1]] = value;
+    }
+}
+
+// packages/game-engine/src/slot/anim/easing-map.ts
+/** Resolve a descriptor's string easing name to the engine's easing function. */
+const EASING_BY_NAME = {
+    linear: Easing.linear,
+    easeInQuad: Easing.easeInQuad,
+    easeOutQuad: Easing.easeOutQuad,
+    easeInOutQuad: Easing.easeInOutQuad,
+    easeInCubic: Easing.easeInCubic,
+    easeOutCubic: Easing.easeOutCubic,
+    easeInOutCubic: Easing.easeInOutCubic,
+    easeInBack: Easing.easeInBack,
+    easeOutBack: Easing.easeOutBack,
+    easeInOutBack: Easing.easeInOutBack,
+    easeOutBounce: Easing.easeOutBounce,
+    easeInBounce: Easing.easeInBounce,
+    easeOutElastic: Easing.easeOutElastic,
+    easeInSine: Easing.easeInSine,
+    easeOutSine: Easing.easeOutSine,
+    easeInOutSine: Easing.easeInOutSine,
+};
+/** Resolve an easing name to a function, falling back to easeOutQuad. */
+function easingByName(name) {
+    return (name && EASING_BY_NAME[name]) || Easing.easeOutQuad;
+}
+
+// Built-in flow steps. Presentation writes (tween/setProps/countUp) target live
+// instances/views — never the scene doc (the doc stays the persistable SSOT); runtime
+// state changes (setVar/setState) go through the scene handle like any agent patch.
+const num = (v, fallback) => (typeof v === 'number' && Number.isFinite(v) ? v : fallback);
+function formatValue(value, format) {
+    const rounded = Math.round(value);
+    if (format === 'space')
+        return String(rounded).replace(/\B(?=(\d{3})+(?!\d))/g, ' ');
+    return String(rounded);
+}
+const tweenStep = {
+    kind: 'tween',
+    agentDoc: 'Animate numeric view properties of a scene node (alpha, x, y, rotation; scale animates both axes). Transient — the doc is untouched, and any relayout (setVar/setState/resize) re-asserts layout-owned props (x/y/scale/rotation) from the doc. Persist a move via a set-layout patch, not a tween. Turbo divides ms; skip jumps to the end values.',
+    async run(raw, rt) {
+        const step = raw;
+        const view = rt.view(step.node);
+        if (!view)
+            return rt.log(`tween: unknown node "${step.node}"`);
+        const to = {};
+        for (const [key, value] of Object.entries(step.to))
+            to[key] = num(rt.resolve(value), 0);
+        const applyFinal = () => {
+            for (const [key, value] of Object.entries(to)) {
+                if (key === 'scale')
+                    view.scale.set(value);
+                else
+                    view[key] = value;
+            }
+        };
+        if (rt.skipped)
+            return applyFinal();
+        const { scale, ...rest } = to;
+        const jobs = [];
+        if (Object.keys(rest).length > 0) {
+            jobs.push(Tween.to(view, rest, step.ms / rt.turbo, easingByName(step.ease)));
+        }
+        if (scale !== undefined) {
+            jobs.push(Tween.to(view.scale, { x: scale, y: scale }, step.ms / rt.turbo, easingByName(step.ease)));
+        }
+        // A skip during flight must land on the end state: race the tween against skip-release.
+        await Promise.race([Promise.all(jobs), rt.wait(step.ms + 50)]);
+        if (rt.skipped) {
+            Tween.killTweensOf(view);
+            Tween.killTweensOf(view.scale);
+            applyFinal();
+        }
+    },
+};
+const soundStep = {
+    kind: 'sound',
+    agentDoc: 'Play/stop a cue from flow.cues (rotation/jitter handled by the runner). Never reference audio files directly.',
+    run(raw, rt) {
+        const step = raw;
+        rt.playCue(step.cue, step.action ?? 'play');
+    },
+};
+const setStateStep = {
+    kind: 'setState',
+    agentDoc: "Switch a node's named state (frame anticipation/bonus look). Same operation the inspector and agent use.",
+    run(raw, rt) {
+        const step = raw;
+        rt.scene.setState(step.node, step.state);
+    },
+};
+const setVarStep = {
+    kind: 'setVar',
+    agentDoc: "Set a runtime var driving visibleWhen (e.g. mode). Use for mode transitions ('setVar mode free_spins').",
+    run(raw, rt) {
+        const step = raw;
+        rt.scene.setVar(step.name, rt.resolve(step.value));
+    },
+};
+const setPropsStep = {
+    kind: 'setProps',
+    agentDoc: 'Transient prop write on the live instance (badge values, board swaps during presentation). The scene doc is NOT modified.',
+    run(raw, rt) {
+        const step = raw;
+        const instance = rt.scene.instance(step.node);
+        if (!instance?.applyProps)
+            return rt.log(`setProps: node "${step.node}" has no applyProps`);
+        const props = {};
+        for (const [key, value] of Object.entries(step.props))
+            props[key] = rt.resolve(value);
+        const node = findDocNode(rt, step.node);
+        instance.applyProps({ ...(node?.props ?? {}), ...props });
+    },
+};
+function findDocNode(rt, id) {
+    const walk = (n) => {
+        if (n.id === id)
+            return n;
+        for (const child of n.children ?? []) {
+            const hit = walk(child);
+            if (hit)
+                return hit;
+        }
+        return undefined;
+    };
+    return walk(rt.scene.doc().root);
+}
+const countUpStep = {
+    kind: 'countUp',
+    agentDoc: "Animated number roll on an instance prop (default 'value' — badge prefabs). `to` may be '$win' (ctx ref). Turbo shortens, skip jumps to the final value.",
+    async run(raw, rt) {
+        const step = raw;
+        const instance = rt.scene.instance(step.node);
+        if (!instance?.applyProps)
+            return rt.log(`countUp: node "${step.node}" has no applyProps`);
+        const node = findDocNode(rt, step.node);
+        const prop = step.prop ?? 'value';
+        const from = num(rt.resolve(step.from), 0);
+        const to = num(rt.resolve(step.to), 0);
+        const ms = num(step.ms, 1000) / rt.turbo;
+        const apply = (value) => instance.applyProps({ ...(node?.props ?? {}), [prop]: formatValue(value, step.format) });
+        if (rt.skipped || ms <= 0)
+            return apply(to);
+        const start = performance.now();
+        while (!rt.skipped) {
+            const k = Math.min(1, (performance.now() - start) / ms);
+            apply(from + (to - from) * (1 - Math.pow(1 - k, 2)));
+            if (k >= 1)
+                return;
+            await rt.wait(16);
+        }
+        apply(to);
+    },
+};
+const waitStep = {
+    kind: 'wait',
+    agentDoc: "Pause: {ms} (turbo-scaled) or {until:'tap'} (released by tap or skip). Prefer explicit waits over baking delays into tweens.",
+    async run(raw, rt) {
+        const step = raw;
+        if (step.until === 'tap')
+            return rt.waitTap();
+        return rt.wait(num(step.ms, 0));
+    },
+};
+const ifStep = {
+    kind: 'if',
+    agentDoc: "Branch on the fire() ctx: {when:'win >= 100', then:[…], else:[…]}. Bare name = truthy check.",
+    async run(raw, rt) {
+        const step = raw;
+        await rt.run(rt.when(step.when) ? step.then : (step.else ?? []));
+    },
+};
+const parallelStep = {
+    kind: 'parallel',
+    agentDoc: 'Run tracks concurrently and await them all: {steps: [[…], […]]}. Each track is an independent sequence.',
+    async run(raw, rt) {
+        const step = raw;
+        await Promise.all(step.steps.map((track) => rt.run(track)));
+    },
+};
+const seqStep = {
+    kind: 'seq',
+    agentDoc: 'Nested sequence (grouping inside parallel tracks).',
+    async run(raw, rt) {
+        const step = raw;
+        await rt.run(step.steps);
+    },
+};
+const codeStep = {
+    kind: 'code',
+    agentDoc: 'Escape hatch: named choreography registered in createFlowRunner({code}). Use when the step vocabulary genuinely cannot express it — then consider a plugin step.',
+    async run(raw, rt) {
+        const step = raw;
+        const handler = rt.codeRef(step.ref);
+        if (!handler)
+            return rt.log(`code: unknown ref "${step.ref}"`);
+        await handler(rt, step.args ?? {});
+    },
+};
+const BUILTIN_FLOW_STEPS = [
+    tweenStep,
+    soundStep,
+    setStateStep,
+    setVarStep,
+    setPropsStep,
+    countUpStep,
+    waitStep,
+    ifStep,
+    parallelStep,
+    seqStep,
+    codeStep,
+];
+
+// Flow-IR interpreter: createFlowRunner(flowDoc, { scene, … }).fire(event, ctx) executes
+// the event's steps and returns a Trace.
+//
+// Skip semantics (first-class, docs/slot-ide.md §1.7): skip() does NOT cancel a run — it
+// makes the remaining steps complete in zero time. Waits resolve instantly, tweens and
+// count-ups jump to their end values, taps release. The flow always reaches its settled
+// state; three of the studied games lacked exactly this. Turbo divides every duration.
+const noopAudio = { play: () => { }, stop: () => { } };
+function validateFlowDoc(doc, registry) {
+    const errors = [];
+    if (doc.version !== 1)
+        errors.push(`unsupported flow doc version ${String(doc.version)}`);
+    const visit = (step, path) => {
+        if (!registry.step(step.do)) {
+            errors.push(`${path}: unknown step "${step.do}" — no plugin contributes it. Registered: ${registry.kinds().join(', ')}`);
+            return;
+        }
+        if (step.do === 'if') {
+            step.then.forEach((s, i) => visit(s, `${path}.then[${i}]`));
+            (step.else ?? []).forEach((s, i) => visit(s, `${path}.else[${i}]`));
+        }
+        else if (step.do === 'parallel') {
+            step.steps.forEach((track, ti) => track.forEach((s, i) => visit(s, `${path}[${ti}][${i}]`)));
+        }
+        else if (step.do === 'seq') {
+            step.steps.forEach((s, i) => visit(s, `${path}.steps[${i}]`));
+        }
+        else if (step.do === 'sound') {
+            const cue = step.cue;
+            if (!doc.cues?.[cue])
+                errors.push(`${path}: sound cue "${cue}" is not declared in flow.cues`);
+        }
+    };
+    for (const [event, steps] of Object.entries(doc.on ?? {})) {
+        steps.forEach((step, i) => visit(step, `on.${event}[${i}]`));
+    }
+    return errors;
+}
+function createFlowRunner(doc, opts) {
+    const log = opts.log ?? ((msg) => console.warn(`[flow] ${msg}`));
+    const registry = createFlowStepRegistry(opts.plugins ?? [], BUILTIN_FLOW_STEPS);
+    const errors = validateFlowDoc(doc, registry);
+    if (errors.length > 0)
+        throw new Error(`flow doc "${doc.id}" is invalid:\n  ${errors.join('\n  ')}`);
+    const audio = opts.audio ?? noopAudio;
+    let turbo = 1;
+    const rotation = new Map();
+    const tapWaiters = new Set();
+    const active = new Set();
+    const resolveCue = (name) => {
+        const def = doc.cues?.[name];
+        if (!def)
+            return undefined;
+        const sources = Array.isArray(def.src) ? def.src : [def.src];
+        let index = 0;
+        if (def.rotate && sources.length > 1) {
+            index = (rotation.get(name) ?? 0) % sources.length;
+            rotation.set(name, index + 1);
+        }
+        const jitter = def.jitter ?? 0;
+        return {
+            cue: name,
+            src: sources[index],
+            channel: def.channel ?? 'sfx',
+            loop: def.loop ?? false,
+            rate: jitter ? 1 + (Math.random() * 2 - 1) * jitter : 1,
+            volume: def.volume ?? 1,
+        };
+    };
+    const fire = async (event, ctx = {}) => {
+        const steps = doc.on[event];
+        const start = performance.now();
+        const entries = [];
+        const run = { skipped: false, releases: new Set() };
+        active.add(run);
+        const trace = (entry) => {
+            const full = { t: Math.round(performance.now() - start), ...entry };
+            entries.push(full);
+            opts.onTrace?.(event, full);
+        };
+        const rt = {
+            scene: opts.scene,
+            ctx,
+            audio,
+            get skipped() {
+                return run.skipped;
+            },
+            get turbo() {
+                return turbo;
+            },
+            wait(ms) {
+                if (run.skipped || ms <= 0)
+                    return Promise.resolve();
+                return new Promise((resolve) => {
+                    const timer = setTimeout(() => {
+                        run.releases.delete(release);
+                        resolve();
+                    }, ms / turbo);
+                    const release = () => {
+                        clearTimeout(timer);
+                        resolve();
+                    };
+                    run.releases.add(release);
+                });
+            },
+            waitTap() {
+                if (run.skipped)
+                    return Promise.resolve();
+                return new Promise((resolve) => {
+                    const release = () => {
+                        tapWaiters.delete(release);
+                        run.releases.delete(release);
+                        resolve();
+                    };
+                    tapWaiters.add(release);
+                    run.releases.add(release);
+                });
+            },
+            async run(list) {
+                for (const step of list) {
+                    const contribution = registry.step(step.do);
+                    if (!contribution)
+                        continue; // validated; defensive
+                    trace({
+                        do: step.do,
+                        node: typeof step.node === 'string' ? step.node : undefined,
+                    });
+                    await contribution.run(step, rt);
+                }
+            },
+            resolve(value) {
+                if (typeof value === 'string' && value.startsWith('$')) {
+                    return value
+                        .slice(1)
+                        .split('.')
+                        .reduce((acc, key) => acc?.[key], ctx);
+                }
+                return value;
+            },
+            when(expr) {
+                const bare = /^\s*([A-Za-z_$][\w$]*)\s*$/.exec(expr);
+                if (bare)
+                    return Boolean(ctx[bare[1]]);
+                const result = evalVisibleWhen(expr, ctx);
+                if (result === undefined) {
+                    log(`unsupported when "${expr}" — treated as false`);
+                    return false;
+                }
+                return result;
+            },
+            trace,
+            view: (id) => opts.scene.node(id),
+            log,
+            codeRef: (ref) => opts.code?.[ref],
+            playCue(name, action) {
+                if (action === 'stop')
+                    return audio.stop(name);
+                const resolved = resolveCue(name);
+                if (resolved)
+                    audio.play(resolved);
+            },
+        };
+        try {
+            if (!steps)
+                log(`fire("${event}") — no steps declared`);
+            else
+                await rt.run(steps);
+        }
+        finally {
+            active.delete(run);
+        }
+        return {
+            event,
+            turbo,
+            skipped: run.skipped,
+            durationMs: Math.round(performance.now() - start),
+            entries,
+        };
+    };
+    return {
+        fire,
+        skip() {
+            for (const run of active) {
+                run.skipped = true;
+                for (const release of [...run.releases])
+                    release();
+                run.releases.clear();
+            }
+        },
+        setTurbo(factor) {
+            turbo = Math.max(0.1, factor);
+        },
+        tap() {
+            for (const release of [...tapWaiters])
+                release();
+        },
+        events: () => Object.keys(doc.on ?? {}),
+        destroy() {
+            this.skip();
+            active.clear();
+        },
+    };
+}
+
+exports.BUILTIN_FLOW_STEPS = BUILTIN_FLOW_STEPS;
+exports.createFlowRunner = createFlowRunner;
+exports.createFlowStepRegistry = createFlowStepRegistry;
+exports.validateFlowDoc = validateFlowDoc;
+//# sourceMappingURL=flow.cjs.js.map