@energy8platform/game-engine 0.33.4 → 0.33.7

package/dist/scene.esm.js

@@ -270,22 +270,47 @@ function evalVisibleWhen(expr, vars) {
 // schema (validation + inspector autogen) and an `agentDoc` (the plugin's documentation
 // and the agent's prompt are the same text).
 /** Merge built-ins with plugin contributions; later plugins may override earlier kinds. */
-function createSceneRegistry(plugins = [], builtins = []) {
+function createSceneRegistry(plugins = [], builtins = [], builtinFilters = []) {
     const nodeTypes = new Map();
     const prefabs = new Map();
+    const filterKinds = new Map();
     for (const contribution of builtins)
         nodeTypes.set(contribution.kind, contribution);
+    for (const contribution of builtinFilters)
+        filterKinds.set(contribution.kind, contribution);
     for (const plugin of plugins) {
         for (const contribution of plugin.nodeTypes ?? [])
             nodeTypes.set(contribution.kind, contribution);
         for (const prefab of plugin.prefabs ?? [])
             prefabs.set(prefab.name, prefab);
+        for (const contribution of plugin.filterKinds ?? [])
+            filterKinds.set(contribution.kind, contribution);
     }
     return {
         nodeType: (kind) => nodeTypes.get(kind),
         prefab: (name) => prefabs.get(name),
+        filterKind: (kind) => filterKinds.get(kind),
         kinds: () => [...nodeTypes.keys()],
         prefabNames: () => [...prefabs.keys()],
+        filterKindNames: () => [...filterKinds.keys()],
+        palette() {
+            const entries = [];
+            for (const c of nodeTypes.values()) {
+                if (!c.defaults)
+                    continue; // hide dispatch-only kinds (prefab)
+                entries.push({ kind: c.kind, label: c.defaults.label ?? c.kind, isPrefab: false, agentDoc: c.agentDoc, defaults: c.defaults });
+            }
+            for (const p of prefabs.values()) {
+                entries.push({
+                    kind: p.name,
+                    label: p.defaults?.label ?? p.name,
+                    isPrefab: true,
+                    agentDoc: p.agentDoc,
+                    defaults: p.defaults ?? {},
+                });
+            }
+            return entries;
+        },
     };
 }
 
@@ -2923,13 +2948,14 @@ function emptyBoard(cfg) {
 // Built-in node contributions: the core vocabulary every scene doc can rely on.
 // Everything else (ropes, meters, particles, game HUDs) arrives as a ScenePlugin through
 // the same contribution shape — built-ins get no special powers.
-const num = (v, fallback) => (typeof v === 'number' && Number.isFinite(v) ? v : fallback);
+const num$1 = (v, fallback) => (typeof v === 'number' && Number.isFinite(v) ? v : fallback);
 const str = (v, fallback) => (typeof v === 'string' ? v : fallback);
 // ── container / layer ───────────────────────────────────────────────────────────────
 function containerContribution(kind) {
     return {
         kind,
         agentDoc: 'Grouping node; order of children = z-order. Keep it un-laid-out (identity) unless you move a whole group. With props.space {width,height} it becomes a nested coordinate space: descendants lay out inside that fixed design space and its own rule places the space (cover → the diorama idiom). Natural size = space size, else 0×0.',
+        defaults: { label: kind === 'layer' ? 'Layer' : 'Container', props: {} },
         create(node) {
             const view = new Container();
             return {
@@ -2941,7 +2967,7 @@ function containerContribution(kind) {
                         : { width: 0, height: 0 };
                 },
                 applyProps(props) {
-                    view.alpha = num(props.alpha, 1);
+                    view.alpha = num$1(props.alpha, 1);
                 },
             };
         },
@@ -2951,18 +2977,23 @@ function containerContribution(kind) {
 const rectContribution = {
     kind: 'rect',
     agentDoc: 'Solid rounded rectangle: plates behind text, dimmers, and mask targets (reference its id from another node\'s `mask`). Props: width, height, fill, alpha, radius, stroke {color,width}.',
+    defaults: {
+        label: 'Rectangle',
+        props: { width: 200, height: 120, fill: '#3355aa', radius: 12 },
+        layout: { mode: 'viewport-fraction', xFrac: 0.5, yFrac: 0.5, anchor: [0.5, 0.5] },
+    },
     create(node) {
         const g = new Graphics();
         let size = { width: 0, height: 0 };
         const draw = (props) => {
-            const width = num(props.width, 100);
-            const height = num(props.height, 100);
-            const radius = num(props.radius, 0);
+            const width = num$1(props.width, 100);
+            const height = num$1(props.height, 100);
+            const radius = num$1(props.radius, 0);
             size = { width, height };
             g.clear();
             g.roundRect(0, 0, width, height, radius).fill({
                 color: str(props.fill, '#ffffff'),
-                alpha: num(props.alpha, 1),
+                alpha: num$1(props.alpha, 1),
             });
             const stroke = props.stroke;
             if (stroke) {
@@ -3002,7 +3033,7 @@ function spriteInstance(node, ctx) {
         // Visual props go on the wrapper (the node's view) so tint/alpha are observable and
         // patchable on the node itself; the inner sprite only carries texture + flip.
         wrapper.tint = p.tint ?? 0xffffff;
-        wrapper.alpha = num(p.alpha, 1);
+        wrapper.alpha = num$1(p.alpha, 1);
         const flip = p.flipX === true;
         sprite.scale.x = flip ? -1 : 1;
         sprite.position.x = flip ? sprite.texture.width : 0;
@@ -3017,6 +3048,11 @@ function spriteInstance(node, ctx) {
 const spriteContribution = {
     kind: 'sprite',
     agentDoc: 'Static art. Props: src (texture alias), tint, alpha. Natural size = texture size; use layout to place/scale.',
+    defaults: {
+        label: 'Sprite',
+        props: {},
+        layout: { mode: 'viewport-fraction', xFrac: 0.5, yFrac: 0.5, anchor: [0.5, 0.5] },
+    },
     create: spriteInstance,
 };
 const reelFrameContribution = {
@@ -3028,17 +3064,22 @@ const reelFrameContribution = {
 const textContribution = {
     kind: 'text',
     agentDoc: 'Vector text (labels, logos-as-type). Props: text, fontSize, fill, fontFamily, fontWeight, align, letterSpacing. For rolling win numbers prefer a bitmapNumber/prefab, not text.',
+    defaults: {
+        label: 'Text',
+        props: { text: 'Text', fontSize: 48, fill: '#ffffff', fontWeight: 'bold' },
+        layout: { mode: 'viewport-fraction', xFrac: 0.5, yFrac: 0.5, anchor: [0.5, 0.5] },
+    },
     create(node) {
         const props = node.props ?? {};
         const view = new Text({
             text: str(props.text, ''),
             style: {
                 fontFamily: str(props.fontFamily, 'Arial, sans-serif'),
-                fontSize: num(props.fontSize, 32),
+                fontSize: num$1(props.fontSize, 32),
                 fill: props.fill ?? '#ffffff',
                 fontWeight: props.fontWeight ?? 'normal',
                 align: props.align ?? 'left',
-                letterSpacing: num(props.letterSpacing, 0),
+                letterSpacing: num$1(props.letterSpacing, 0),
             },
         });
         return {
@@ -3048,9 +3089,9 @@ const textContribution = {
                 if (p.text !== undefined)
                     view.text = str(p.text, '');
                 view.style.fill = p.fill ?? '#ffffff';
-                view.style.fontSize = num(p.fontSize, 32);
-                view.style.letterSpacing = num(p.letterSpacing, 0);
-                view.alpha = num(p.alpha, 1);
+                view.style.fontSize = num$1(p.fontSize, 32);
+                view.style.letterSpacing = num$1(p.letterSpacing, 0);
+                view.alpha = num$1(p.alpha, 1);
             },
         };
     },
@@ -3066,8 +3107,8 @@ const animatedSpriteContribution = {
         const apply = (p) => {
             const sheet = p.sheet;
             const alias = str(sheet?.alias, '');
-            const cols = num(sheet?.cols, 1);
-            const rows = num(sheet?.rows, 1);
+            const cols = num$1(sheet?.cols, 1);
+            const rows = num$1(sheet?.rows, 1);
             const full = alias ? ctx.texture(alias) : Texture.EMPTY;
             const frames = [];
             if (full !== Texture.EMPTY && cols > 0 && rows > 0) {
@@ -3081,14 +3122,14 @@ const animatedSpriteContribution = {
             }
             animated?.destroy();
             animated = new AnimatedSprite(frames.length ? frames : [Texture.EMPTY]);
-            animated.animationSpeed = num(p.fps, 12) / 60;
+            animated.animationSpeed = num$1(p.fps, 12) / 60;
             animated.loop = true;
-            const frame = Math.min(num(p.frame, 0), animated.totalFrames - 1);
+            const frame = Math.min(num$1(p.frame, 0), animated.totalFrames - 1);
             if (p.playing === true)
                 animated.gotoAndPlay(Math.max(0, frame));
             else
                 animated.gotoAndStop(Math.max(0, frame));
-            animated.alpha = num(p.alpha, 1);
+            animated.alpha = num$1(p.alpha, 1);
             view.removeChildren();
             view.addChild(animated);
             size = { width: animated.textures.length ? animated.textures[0].width : 0, height: animated.textures.length ? animated.textures[0].height : 0 };
@@ -3129,17 +3170,21 @@ const reelGridContribution = {
             system.setBoard(board.map((column) => column.map((cell) => (typeof cell === 'string' ? { symbol: cell } : cell))));
         };
         setBoard(props.board);
-        // The reel system's local content does not start at (0,0) (cells/decoration extend
-        // around the geometry origin), so align it inside a wrapper: measure() re-reads the
-        // real local bounds each layout and keeps the wrapper's (0,0) = content top-left.
+        // The reel system's local content does not start at (0,0) (cells center on geometry
+        // positions), so align it inside a wrapper. The origin comes from the STATIC geometry
+        // (first cell center − half cell), never from getLocalBounds — animated cells hang
+        // far outside the window mid-spin and a bounds-based origin would drift the grid.
         const wrapper = new Container();
         wrapper.addChild(system.view);
-        let contentOrigin = { x: 0, y: 0 };
+        const contentOrigin = { x: 0, y: 0 };
         const syncContent = () => {
-            const lb = system.view.getLocalBounds();
-            contentOrigin = { x: lb.x, y: lb.y };
-            system.view.position.set(-lb.x, -lb.y);
-            return { width: lb.width, height: lb.height };
+            const geom = system.grid.geometry;
+            const first = system.grid.cellPosition(0, 0);
+            const cell = system.config.grid.cellSize;
+            contentOrigin.x = first.x - cell / 2;
+            contentOrigin.y = first.y - cell / 2;
+            system.view.position.set(-contentOrigin.x, -contentOrigin.y);
+            return { width: geom.gridW, height: geom.gridH };
         };
         const instance = {
             view: wrapper,
@@ -3170,6 +3215,19 @@ const prefabContribution = {
         return prefab.create(node.props ?? {}, ctx);
     },
 };
+/** Core filter kinds; heavier looks (bloom etc.) arrive as plugins carrying their deps. */
+const BUILTIN_FILTER_KINDS = [
+    {
+        kind: 'blur',
+        agentDoc: 'Gaussian blur: {kind:"blur", strength, quality}. Shadow/glow layers idiom.',
+        create(spec) {
+            return new BlurFilter({
+                strength: typeof spec.strength === 'number' ? spec.strength : 4,
+                quality: typeof spec.quality === 'number' ? spec.quality : 3,
+            });
+        },
+    },
+];
 const BUILTIN_NODE_TYPES = [
     containerContribution('container'),
     containerContribution('layer'),
@@ -3261,7 +3319,7 @@ function validateSceneDoc(doc, registry) {
 const MAX_LAYOUT_PASSES = 5;
 function createSceneFromDoc(doc, opts = {}) {
     const log = opts.log ?? ((msg) => console.warn(`[scene] ${msg}`));
-    const registry = createSceneRegistry(opts.plugins ?? [], BUILTIN_NODE_TYPES);
+    const registry = createSceneRegistry(opts.plugins ?? [], BUILTIN_NODE_TYPES, BUILTIN_FILTER_KINDS);
     const errors = validateSceneDoc(doc, registry);
     if (errors.length > 0) {
         const detail = errors.map((e) => (e.nodeId ? `[${e.nodeId}] ${e.message}` : e.message)).join('\n  ');
@@ -3296,6 +3354,27 @@ function createSceneFromDoc(doc, opts = {}) {
             throw new Error(`scene node "${node.id}" (${node.type}) failed to create: ${err.message}`);
         }
         parentView.addChild(instance.view);
+        if (node.filters?.length) {
+            const filters = node.filters
+                .map((spec) => {
+                const contribution = registry.filterKind(spec.kind);
+                if (!contribution) {
+                    warnOnce(`filter:${spec.kind}`, `unknown filter kind "${spec.kind}" on "${node.id}" — no plugin contributes it`);
+                    return null;
+                }
+                try {
+                    return contribution.create(spec);
+                }
+                catch (err) {
+                    // Filters need a GPU context — degrade gracefully in headless runs.
+                    warnOnce(`filter-fail:${spec.kind}`, `filter "${spec.kind}" failed to create: ${err.message}`);
+                    return null;
+                }
+            })
+                .filter((f) => f !== null);
+            if (filters.length)
+                instance.view.filters = filters;
+        }
         const runtime = {
             node,
             instance,
@@ -3464,8 +3543,15 @@ function createSceneFromDoc(doc, opts = {}) {
                 const eff = effectiveNode(runtime.node, orientation, runtime.state);
                 const natural = runtime.instance.measure();
                 const rule = eff.layout;
+                // `space:'viewport'` resolves against the live viewport even inside a nested
+                // space, then converts into the space's coordinates (screen-pin at a space depth).
+                const viewportSpace = rule?.space === 'viewport' && frame !== null;
+                if (viewportSpace && !frame.bounds) {
+                    next.push(runtime); // need the space root's global rect first
+                    continue;
+                }
                 const resolution = rule
-                    ? resolveLayoutRule(rule, natural, layoutCtx(frame))
+                    ? resolveLayoutRule(rule, natural, layoutCtx(viewportSpace ? null : frame))
                     : {
                         placement: {
                             x: parentOriginX,
@@ -3480,7 +3566,21 @@ function createSceneFromDoc(doc, opts = {}) {
                     next.push(runtime);
                     continue;
                 }
-                const p = resolution.placement;
+                let p = resolution.placement;
+                if (viewportSpace) {
+                    if (frameOf(frame) !== null) {
+                        warnOnce(`vspace:${runtime.node.id}`, `space:'viewport' inside a nested space is unsupported ("${runtime.node.id}")`);
+                    }
+                    else {
+                        p = {
+                            ...p,
+                            x: (p.x - frame.bounds.x) / frame.worldScaleX,
+                            y: (p.y - frame.bounds.y) / frame.worldScaleY,
+                            scaleX: p.scaleX / frame.worldScaleX,
+                            scaleY: p.scaleY / frame.worldScaleY,
+                        };
+                    }
+                }
                 const view = runtime.instance.view;
                 view.position.set((p.x - parentOriginX) / parentScaleX, (p.y - parentOriginY) / parentScaleY);
                 view.scale.set(p.scaleX / parentScaleX, p.scaleY / parentScaleY);
@@ -3538,6 +3638,61 @@ function createSceneFromDoc(doc, opts = {}) {
         }
         return undefined;
     };
+    /** Locate a node's parent doc-node + its index in that parent's children. */
+    const locate = (id) => {
+        const walk = (node) => {
+            const kids = node.children ?? [];
+            for (let i = 0; i < kids.length; i++) {
+                if (kids[i].id === id)
+                    return { parent: node, index: i };
+                const hit = walk(kids[i]);
+                if (hit)
+                    return hit;
+            }
+            return undefined;
+        };
+        return walk(doc.root);
+    };
+    const collectIds = (node, out = []) => {
+        out.push(node.id);
+        for (const child of node.children ?? [])
+            collectIds(child, out);
+        return out;
+    };
+    /** Deep-clone a subtree, suffixing every id/anchorName so it stays unique in the doc. */
+    const cloneWithSuffix = (node, suffix) => {
+        const clone = JSON.parse(JSON.stringify(node));
+        const remap = (n) => {
+            n.id = `${n.id}${suffix}`;
+            if (n.anchorName)
+                n.anchorName = `${n.anchorName}${suffix}`;
+            n.children?.forEach(remap);
+        };
+        remap(clone);
+        return clone;
+    };
+    /** Build a freshly-inserted subtree under an existing parent runtime, at a child index. */
+    const buildInto = (node, parentRuntime, index) => {
+        const before = parentRuntime.instance.view.children.length;
+        build(node, parentRuntime, parentRuntime.instance.view);
+        // build appended to the end — move the new view to the requested child index.
+        const view = runtimes.get(node.id).instance.view;
+        const clampedIndex = Math.max(0, Math.min(index, before));
+        parentRuntime.instance.view.setChildIndex(view, clampedIndex);
+    };
+    const destroyRuntimeTree = (id) => {
+        const runtime = runtimes.get(id);
+        if (!runtime)
+            return;
+        for (const descendantId of collectIds(runtime.node)) {
+            const r = runtimes.get(descendantId);
+            if (r) {
+                r.instance.destroy?.();
+                runtimes.delete(descendantId);
+            }
+        }
+        runtime.instance.view.removeFromParent();
+    };
     const setVar = (name, value) => {
         vars[name] = value;
         relayout();
@@ -3581,6 +3736,72 @@ function createSceneFromDoc(doc, opts = {}) {
                 return setState(patch.id, patch.state);
             case 'set-var':
                 return setVar(patch.name, patch.value);
+            case 'add-node': {
+                const parentRuntime = runtimes.get(patch.parent);
+                if (!parentRuntime)
+                    return warnOnce(`add:${patch.parent}`, `add-node: unknown parent "${patch.parent}"`);
+                const clash = collectIds(patch.node).find((id) => runtimes.has(id));
+                if (clash)
+                    return warnOnce(`add-clash:${clash}`, `add-node: id "${clash}" already exists`);
+                if (!registry.nodeType(patch.node.type)) {
+                    return warnOnce(`add-kind:${patch.node.type}`, `add-node: unknown type "${patch.node.type}"`);
+                }
+                (parentRuntime.node.children ??= []).splice(patch.index ?? parentRuntime.node.children.length, 0, patch.node);
+                buildInto(patch.node, parentRuntime, patch.index ?? Number.MAX_SAFE_INTEGER);
+                wireMasks();
+                break;
+            }
+            case 'remove-node': {
+                if (patch.id === doc.root.id)
+                    return warnOnce('rm-root', 'remove-node: cannot remove the root');
+                const loc = locate(patch.id);
+                if (!loc)
+                    return warnOnce(`rm:${patch.id}`, `remove-node: unknown node "${patch.id}"`);
+                destroyRuntimeTree(patch.id);
+                loc.parent.children.splice(loc.index, 1);
+                wireMasks();
+                break;
+            }
+            case 'move-node': {
+                if (patch.id === doc.root.id)
+                    return warnOnce('mv-root', 'move-node: cannot move the root');
+                const loc = locate(patch.id);
+                const source = findNode(doc.root, patch.id);
+                const parentRuntime = runtimes.get(patch.parent);
+                if (!loc || !source)
+                    return warnOnce(`mv:${patch.id}`, `move-node: unknown node "${patch.id}"`);
+                if (!parentRuntime)
+                    return warnOnce(`mv-p:${patch.parent}`, `move-node: unknown parent "${patch.parent}"`);
+                if (collectIds(source).includes(patch.parent)) {
+                    return warnOnce(`mv-cycle:${patch.id}`, `move-node: cannot move "${patch.id}" into itself/its descendant "${patch.parent}"`);
+                }
+                // `index` is the FINAL position in the destination's children (post-removal).
+                const [node] = loc.parent.children.splice(loc.index, 1);
+                destroyRuntimeTree(patch.id); // rebuild the moved subtree under the new parent
+                const dest = (parentRuntime.node.children ??= []);
+                const targetIndex = Math.max(0, Math.min(patch.index ?? dest.length, dest.length));
+                dest.splice(targetIndex, 0, node);
+                buildInto(node, parentRuntime, targetIndex);
+                wireMasks();
+                break;
+            }
+            case 'duplicate-node': {
+                if (patch.id === doc.root.id)
+                    return warnOnce('dup-root', 'duplicate-node: cannot duplicate the root');
+                const loc = locate(patch.id);
+                const source = findNode(doc.root, patch.id);
+                if (!loc || !source)
+                    return warnOnce(`dup:${patch.id}`, `duplicate-node: unknown node "${patch.id}"`);
+                let suffix = '-copy';
+                while (collectIds(source).some((id) => runtimes.has(`${id}${suffix}`)))
+                    suffix += '2';
+                const clone = cloneWithSuffix(source, suffix);
+                const parentRuntime = runtimes.get(loc.parent.id);
+                loc.parent.children.splice(loc.index + 1, 0, clone);
+                buildInto(clone, parentRuntime, loc.index + 1);
+                wireMasks();
+                break;
+            }
         }
         relayout();
     };
@@ -3601,6 +3822,12 @@ function createSceneFromDoc(doc, opts = {}) {
         setState,
         patch: applyPatch,
         doc: () => doc,
+        palette: () => registry.palette(),
+        resetProps() {
+            for (const runtime of runtimes.values())
+                runtime.appliedProps = 'stale';
+            relayout();
+        },
         destroy() {
             for (const runtime of runtimes.values())
                 runtime.instance.destroy?.();
@@ -3610,5 +3837,1107 @@ function createSceneFromDoc(doc, opts = {}) {
     };
 }
 
-export { BUILTIN_NODE_TYPES, createSceneFromDoc, createSceneRegistry, dependencyOf, edgePoint, effectiveNode, evalVisibleWhen, orientationOf, placementBounds, resolveLayoutRule, validateSceneDoc };
+// Inner-hollow calibrator gizmo: drag the four edges of a frame's declared hollow
+// (props.inner fractions) directly on the canvas. Every drag is a set-props ScenePatch,
+// so the grid bound with frame-fraction use:'inner' re-fits LIVE while you drag — this
+// replaces the hand-measured FRAME_INNER/FRAME_CUT constants every studied game carries.
+const MIN_FRAC = 0.05;
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+/** Pure edge-drag math: `frac` is the pointer position normalized to the frame rect axis. */
+function dragInnerEdge(inner, edge, frac) {
+    const right = inner.left + inner.width;
+    const bottom = inner.top + inner.height;
+    switch (edge) {
+        case 'left': {
+            const left = clamp(frac, 0, right - MIN_FRAC);
+            return { ...inner, left, width: right - left };
+        }
+        case 'right': {
+            const r = clamp(frac, inner.left + MIN_FRAC, 1);
+            return { ...inner, width: r - inner.left };
+        }
+        case 'top': {
+            const top = clamp(frac, 0, bottom - MIN_FRAC);
+            return { ...inner, top, height: bottom - top };
+        }
+        case 'bottom': {
+            const b = clamp(frac, inner.top + MIN_FRAC, 1);
+            return { ...inner, height: b - inner.top };
+        }
+    }
+}
+const HANDLE = 14;
+function createInnerCalibrator(opts) {
+    const { handle, nodeId } = opts;
+    const applyPatch = opts.applyPatch ?? handle.patch;
+    const view = new Container();
+    const g = new Graphics();
+    view.addChild(g);
+    const handles = new Map();
+    for (const edge of ['left', 'right', 'top', 'bottom']) {
+        const h = new Graphics();
+        h.eventMode = 'static';
+        h.cursor = edge === 'left' || edge === 'right' ? 'ew-resize' : 'ns-resize';
+        h.on('pointerdown', (e) => {
+            e.stopPropagation();
+            dragging = edge;
+            // Capture moves everywhere only WHILE dragging — otherwise stay click-through.
+            view.hitArea = new Rectangle(-1e6, -1e6, 2e6, 2e6);
+        });
+        handles.set(edge, h);
+        view.addChild(h);
+    }
+    let dragging = null;
+    const docInner = () => {
+        const walk = (n) => {
+            if (n.id === nodeId)
+                return n;
+            for (const c of n.children ?? []) {
+                const hit = walk(c);
+                if (hit)
+                    return hit;
+            }
+            return undefined;
+        };
+        const inner = walk(handle.doc().root)?.props?.inner;
+        return inner && typeof inner.left === 'number' ? inner : undefined;
+    };
+    const frameBounds = () => {
+        const target = handle.node(nodeId);
+        if (!target)
+            return undefined;
+        const b = target.getBounds();
+        return new Rectangle(b.x, b.y, b.width, b.height);
+    };
+    const refresh = () => {
+        g.clear();
+        const bounds = frameBounds();
+        const inner = docInner();
+        if (!bounds || !inner) {
+            for (const h of handles.values())
+                h.clear();
+            return;
+        }
+        const rx = bounds.x + inner.left * bounds.width;
+        const ry = bounds.y + inner.top * bounds.height;
+        const rw = inner.width * bounds.width;
+        const rh = inner.height * bounds.height;
+        g.rect(bounds.x, bounds.y, bounds.width, bounds.height).stroke({ color: 0xffa02f, width: 1, alpha: 0.5 });
+        g.rect(rx, ry, rw, rh).fill({ color: 0x4dd0ff, alpha: 0.08 });
+        g.rect(rx, ry, rw, rh).stroke({ color: 0x4dd0ff, width: 2, alpha: 0.9 });
+        const mid = {
+            left: [rx, ry + rh / 2],
+            right: [rx + rw, ry + rh / 2],
+            top: [rx + rw / 2, ry],
+            bottom: [rx + rw / 2, ry + rh],
+        };
+        for (const [edge, h] of handles) {
+            const [cx, cy] = mid[edge];
+            h.clear();
+            h.rect(cx - HANDLE / 2, cy - HANDLE / 2, HANDLE, HANDLE).fill({ color: 0x4dd0ff });
+            h.rect(cx - HANDLE / 2, cy - HANDLE / 2, HANDLE, HANDLE).stroke({ color: 0x06283d, width: 2 });
+            h.hitArea = new Rectangle(cx - HANDLE, cy - HANDLE, HANDLE * 2, HANDLE * 2);
+        }
+    };
+    view.eventMode = 'static';
+    view.on('pointermove', (e) => {
+        if (!dragging)
+            return;
+        const bounds = frameBounds();
+        const inner = docInner();
+        if (!bounds || !inner)
+            return;
+        const frac = dragging === 'left' || dragging === 'right'
+            ? (e.global.x - bounds.x) / bounds.width
+            : (e.global.y - bounds.y) / bounds.height;
+        const next = dragInnerEdge(inner, dragging, Math.round(frac * 1000) / 1000);
+        applyPatch({ op: 'set-props', id: nodeId, props: { inner: next } });
+        opts.onChange?.(next);
+        refresh();
+    });
+    const endDrag = () => {
+        dragging = null;
+        view.hitArea = null;
+    };
+    view.on('pointerup', endDrag);
+    view.on('pointerupoutside', endDrag);
+    refresh();
+    return {
+        view,
+        refresh,
+        destroy() {
+            view.destroy({ children: true });
+        },
+    };
+}
+
+// Pure transform math for the canvas gizmo: turn a drag into a new LayoutRule, writing
+// the RIGHT field for the rule's kind — the thing the user asked for ("resize on the
+// canvas, not just the sidebar"). Resize maps to a rule's natural size lever:
+//   • widthFrac/heightFrac (viewport-fraction) or wFrac/hFrac (frame-fraction) — per-axis;
+//   • otherwise a uniform `scale` (absolute / cover / grid-cell / pin / plain fraction).
+// The engine re-places the node by its own anchor after the lever changes, so the anchor
+// stays pinned for free — no position juggling here. Rotation writes `rotation`.
+/** Which size lever a rule exposes — decides how a resize drag is interpreted. */
+function sizeLever(rule) {
+    if (rule.mode === 'viewport-fraction' && (rule.widthFrac !== undefined || rule.heightFrac !== undefined))
+        return 'wh-frac';
+    if (rule.mode === 'frame-fraction' && (rule.wFrac !== undefined || rule.hFrac !== undefined))
+        return 'wh-box';
+    if (rule.mode === 'frame-fraction')
+        return 'none'; // point placement inside a frame — no size
+    return 'scale';
+}
+const clampFactor = (f) => (Number.isFinite(f) && f > 0.01 ? f : 0.01);
+const round4 = (n) => Math.round(n * 1e4) / 1e4;
+/**
+ * Multiply a rule's size lever by (factorX, factorY). Corners pass equal factors (uniform);
+ * edges pass 1 on the untouched axis. Uniform levers (`scale`) use factorX.
+ */
+function resizeRule(rule, factorX, factorY) {
+    const fx = clampFactor(factorX);
+    const fy = clampFactor(factorY);
+    const next = JSON.parse(JSON.stringify(rule));
+    switch (sizeLever(rule)) {
+        case 'wh-frac': {
+            const r = next;
+            if (r.widthFrac !== undefined)
+                r.widthFrac = round4(r.widthFrac * fx);
+            if (r.heightFrac !== undefined)
+                r.heightFrac = round4(r.heightFrac * fy);
+            break;
+        }
+        case 'wh-box': {
+            const r = next;
+            if (r.wFrac !== undefined)
+                r.wFrac = round4(r.wFrac * fx);
+            if (r.hFrac !== undefined)
+                r.hFrac = round4(r.hFrac * fy);
+            break;
+        }
+        case 'scale': {
+            const r = next;
+            r.scale = round4((r.scale ?? 1) * fx);
+            break;
+        }
+    }
+    return next;
+}
+function setRuleRotation(rule, radians) {
+    const next = JSON.parse(JSON.stringify(rule));
+    next.rotation = round4(radians);
+    return next;
+}
+/** Nudge a rule's final pixel offset by a screen delta already converted to design units. */
+function nudgeRule(rule, dxDesign, dyDesign) {
+    const next = JSON.parse(JSON.stringify(rule));
+    next.pxNudge = { x: Math.round((next.pxNudge?.x ?? 0) + dxDesign), y: Math.round((next.pxNudge?.y ?? 0) + dyDesign) };
+    return next;
+}
+/** Screen position of each handle for a bounding box. */
+function handlePoint(box, id) {
+    const { x, y, width: w, height: h } = box;
+    const cx = x + w / 2;
+    const cy = y + h / 2;
+    switch (id) {
+        case 'nw': return { x, y };
+        case 'n': return { x: cx, y };
+        case 'ne': return { x: x + w, y };
+        case 'e': return { x: x + w, y: cy };
+        case 'se': return { x: x + w, y: y + h };
+        case 's': return { x: cx, y: y + h };
+        case 'sw': return { x, y: y + h };
+        case 'w': return { x, y: cy };
+        case 'rotate': return { x: cx, y: y - 28 };
+    }
+}
+/**
+ * Resize factors from dragging a handle, using the OPPOSITE edge/corner as the fixed
+ * reference — the intuitive "grab a corner, drag out, it grows" feel.
+ */
+function resizeFactors(startBox, handle, pointer) {
+    const left = startBox.x;
+    const right = startBox.x + startBox.width;
+    const top = startBox.y;
+    const bottom = startBox.y + startBox.height;
+    const w = startBox.width || 1;
+    const h = startBox.height || 1;
+    const westX = () => Math.abs(pointer.x - right) / w; // dragging the west side, east fixed
+    const eastX = () => Math.abs(pointer.x - left) / w;
+    const northY = () => Math.abs(pointer.y - bottom) / h;
+    const southY = () => Math.abs(pointer.y - top) / h;
+    switch (handle) {
+        case 'w': return { factorX: westX(), factorY: 1 };
+        case 'e': return { factorX: eastX(), factorY: 1 };
+        case 'n': return { factorX: 1, factorY: northY() };
+        case 's': return { factorX: 1, factorY: southY() };
+        case 'nw': {
+            const f = uniform(westX(), northY());
+            return { factorX: f, factorY: f };
+        }
+        case 'ne': {
+            const f = uniform(eastX(), northY());
+            return { factorX: f, factorY: f };
+        }
+        case 'sw': {
+            const f = uniform(westX(), southY());
+            return { factorX: f, factorY: f };
+        }
+        case 'se': {
+            const f = uniform(eastX(), southY());
+            return { factorX: f, factorY: f };
+        }
+        default: return { factorX: 1, factorY: 1 };
+    }
+}
+/** Corner resize keeps aspect — use the diagonal ratio of the two per-axis factors. */
+function uniform(a, b) {
+    return Math.sqrt(Math.max(0.0001, a) * Math.max(0.0001, b));
+}
+
+// Transform gizmo — the on-canvas resize / rotate / move manipulator for the selected
+// node. Generalizes the frame calibrator: 8 resize handles + a rotate handle, and a body
+// drag to move. Every gesture emits ONE set-layout ScenePatch (orientation-aware), so a
+// mouse transform and an agent/inspector transform are the same operation. Live bounds are
+// re-read each frame, so the gizmo follows the node as the engine relayouts.
+const CORNERS = ['nw', 'n', 'ne', 'e', 'se', 's', 'sw', 'w'];
+const HS = 9; // handle size
+function createTransformGizmo(opts) {
+    const { handle, app } = opts;
+    const applyPatch = opts.applyPatch ?? handle.patch;
+    const getOrientation = opts.getOrientation ?? (() => 'landscape');
+    // pxNudge lives in the placement (parent/space) coordinate system, which maps to screen
+    // by the parent's world scale — so screen delta ÷ parent-world-scale = design units.
+    const dpp = (id) => {
+        if (opts.designPerPixel)
+            return opts.designPerPixel(id);
+        const parent = handle.node(id)?.parent;
+        const s = parent?.worldTransform?.a ?? 1;
+        return s !== 0 ? 1 / s : 1;
+    };
+    const layer = new Container();
+    layer.eventMode = 'static';
+    app.stage.addChild(layer);
+    const frame = new Graphics();
+    layer.addChild(frame);
+    const handleGfx = new Map();
+    for (const id of [...CORNERS, 'rotate']) {
+        const g = new Graphics();
+        g.eventMode = 'static';
+        g.cursor = id === 'rotate' ? 'grab' : cursorFor(id);
+        g.on('pointerdown', (e) => onDown(id, e));
+        handleGfx.set(id, g);
+        layer.addChild(g);
+    }
+    // A transparent body catcher for move-drags (below the handles).
+    const body = new Graphics();
+    body.eventMode = 'static';
+    body.cursor = 'move';
+    body.on('pointerdown', (e) => onDown('body', e));
+    layer.addChildAt(body, 1);
+    let nodeId = null;
+    let drag = null;
+    const findDocNode = (id, node = handle.doc().root) => {
+        if (node.id === id)
+            return node;
+        for (const child of node.children ?? []) {
+            const hit = findDocNode(id, child);
+            if (hit)
+                return hit;
+        }
+        return undefined;
+    };
+    /** Effective layout rule for the current orientation (base or portrait/landscape override). */
+    const effectiveRule = (id) => {
+        const node = findDocNode(id);
+        if (!node)
+            return {};
+        const o = getOrientation();
+        const override = node.responsive?.[o]?.layout;
+        return override ? { rule: override, orientation: o } : { rule: node.layout };
+    };
+    const boxOf = (id) => {
+        const view = handle.node(id);
+        if (!view || !view.visible)
+            return null;
+        const b = view.getBounds();
+        return { x: b.x, y: b.y, width: b.width, height: b.height };
+    };
+    const onDown = (h, e) => {
+        e.stopPropagation();
+        if (!nodeId)
+            return;
+        const box = boxOf(nodeId);
+        const { rule, orientation } = effectiveRule(nodeId);
+        if (!box || !rule)
+            return;
+        const center = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+        drag = {
+            handle: h,
+            startBox: box,
+            baseRule: JSON.parse(JSON.stringify(rule)),
+            orientation,
+            start: { x: e.global.x, y: e.global.y },
+            center,
+            startAngle: Math.atan2(e.global.y - center.y, e.global.x - center.x),
+        };
+    };
+    const onMove = (e) => {
+        if (!drag || !nodeId)
+            return;
+        let rule;
+        if (drag.handle === 'body') {
+            const s = dpp(nodeId);
+            rule = nudgeRule(drag.baseRule, (e.global.x - drag.start.x) * s, (e.global.y - drag.start.y) * s);
+        }
+        else if (drag.handle === 'rotate') {
+            const angle = Math.atan2(e.global.y - drag.center.y, e.global.x - drag.center.x);
+            rule = setRuleRotation(drag.baseRule, (drag.baseRule.rotation ?? 0) + (angle - drag.startAngle));
+        }
+        else {
+            if (sizeLever(drag.baseRule) === 'none')
+                return; // point-placed frame-fraction: nothing to size
+            const { factorX, factorY } = resizeFactors(drag.startBox, drag.handle, { x: e.global.x, y: e.global.y });
+            rule = resizeRule(drag.baseRule, factorX, factorY);
+        }
+        applyPatch({ op: 'set-layout', id: nodeId, layout: rule, orientation: drag.orientation });
+    };
+    const onUp = () => {
+        drag = null;
+    };
+    app.stage.on('pointermove', onMove);
+    app.stage.on('pointerup', onUp);
+    app.stage.on('pointerupoutside', onUp);
+    const redraw = () => {
+        const box = nodeId ? boxOf(nodeId) : null;
+        frame.clear();
+        body.clear();
+        if (!box) {
+            for (const g of handleGfx.values())
+                g.clear();
+            body.hitArea = null;
+            return;
+        }
+        frame.rect(box.x, box.y, box.width, box.height).stroke({ color: 0x4dd0ff, width: 1.5, alpha: 0.9 });
+        // rotate stem
+        const rot = handlePoint(box, 'rotate');
+        frame.moveTo(box.x + box.width / 2, box.y).lineTo(rot.x, rot.y).stroke({ color: 0x4dd0ff, width: 1, alpha: 0.6 });
+        body.rect(box.x, box.y, box.width, box.height).fill({ color: 0xffffff, alpha: 0.001 });
+        body.hitArea = new Rectangle(box.x, box.y, box.width, box.height);
+        const sizable = sizeLever(nodeId ? effectiveRule(nodeId).rule ?? drag?.baseRule ?? {} : {}) !== 'none';
+        for (const id of [...CORNERS, 'rotate']) {
+            const g = handleGfx.get(id);
+            g.clear();
+            if (id !== 'rotate' && !sizable)
+                continue; // hide resize handles when the rule can't size
+            const p = handlePoint(box, id);
+            if (id === 'rotate')
+                g.circle(p.x, p.y, HS / 1.6).fill({ color: 0x4dd0ff }).stroke({ color: 0x06283d, width: 2 });
+            else
+                g.rect(p.x - HS / 2, p.y - HS / 2, HS, HS).fill({ color: 0x4dd0ff }).stroke({ color: 0x06283d, width: 2 });
+            g.hitArea = new Rectangle(p.x - HS, p.y - HS, HS * 2, HS * 2);
+        }
+    };
+    app.ticker.add(redraw);
+    const fakeEvent = (x, y) => ({ global: { x, y }, stopPropagation() { } });
+    return {
+        attach(id) {
+            nodeId = id;
+            redraw();
+        },
+        refresh: redraw,
+        drag(h, from, to) {
+            onDown(h, fakeEvent(from.x, from.y));
+            onMove(fakeEvent(to.x, to.y));
+            onUp();
+        },
+        destroy() {
+            app.ticker.remove(redraw);
+            app.stage.off('pointermove', onMove);
+            app.stage.off('pointerup', onUp);
+            app.stage.off('pointerupoutside', onUp);
+            layer.destroy({ children: true });
+        },
+    };
+}
+function cursorFor(id) {
+    switch (id) {
+        case 'nw':
+        case 'se': return 'nwse-resize';
+        case 'ne':
+        case 'sw': return 'nesw-resize';
+        case 'n':
+        case 's': return 'ns-resize';
+        case 'e':
+        case 'w': return 'ew-resize';
+        default: return 'default';
+    }
+}
+
+/**
+ * Base class for all scenes.
+ * Provides a root PixiJS Container and lifecycle hooks.
+ *
+ * @example
+ * ```ts
+ * class MenuScene extends Scene {
+ *   async onEnter() {
+ *     const bg = Sprite.from('menu-bg');
+ *     this.container.addChild(bg);
+ *   }
+ *
+ *   onUpdate(dt: number) {
+ *     // per-frame logic
+ *   }
+ *
+ *   onResize(width: number, height: number) {
+ *     // reposition UI
+ *   }
+ * }
+ * ```
+ */
+class Scene {
+    container;
+    constructor() {
+        this.container = new Container();
+        this.container.label = this.constructor.name;
+    }
+}
+
+// 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()],
+    };
+}
+
+// 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 || rt.instant)
+            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 || rt.instant || 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 forEachStep = {
+    kind: 'forEach',
+    agentDoc: "Fan out over a ctx collection: {items:'$jars', as:'jar', mode:'parallel', staggerMs:90, steps:[…]}. Nested steps read `$jar` / `$jarIndex`. THE primitive for staggered jar flights, per-cell transmutes, cascade histories — validated on 3 games.",
+    async run(raw, rt) {
+        const step = raw;
+        const items = rt.resolve(step.items);
+        if (!Array.isArray(items))
+            return rt.log(`forEach: items did not resolve to an array (${String(step.items)})`);
+        const as = step.as ?? 'item';
+        const stagger = num(step.staggerMs, 0);
+        const runtimes = items.map((item, index) => rt.child({ [as]: item, [`${as}Index`]: index }));
+        if ((step.mode ?? 'sequential') === 'parallel') {
+            await Promise.all(runtimes.map(async (child, index) => {
+                if (stagger > 0 && index > 0)
+                    await rt.wait(stagger * index);
+                await child.run(step.steps);
+            }));
+        }
+        else {
+            for (let index = 0; index < runtimes.length; index++) {
+                if (stagger > 0 && index > 0)
+                    await rt.wait(stagger);
+                await runtimes[index].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,
+    forEachStep,
+    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.do === 'forEach') {
+            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 lastCtx = new Map();
+    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 = {}, fireOpts) => {
+        const steps = doc.on[event];
+        const start = performance.now();
+        const entries = [];
+        const replay = fireOpts?.replay;
+        const run = {
+            skipped: false,
+            instant: !!replay,
+            haltAfter: replay?.untilEntry ?? -1,
+            halted: false,
+            releases: new Set(),
+        };
+        active.add(run);
+        if (!replay)
+            lastCtx.set(event, ctx);
+        const trace = (entry) => {
+            const full = { t: Math.round(performance.now() - start), ...entry };
+            entries.push(full);
+            if (run.haltAfter >= 0 && entries.length - 1 >= run.haltAfter)
+                run.halted = true;
+            if (!run.instant)
+                opts.onTrace?.(event, full);
+        };
+        const makeRuntime = (ctxLocal) => {
+            const rtLocal = {
+                scene: opts.scene,
+                ctx: ctxLocal,
+                audio,
+                get skipped() {
+                    return run.skipped;
+                },
+                get instant() {
+                    return run.instant;
+                },
+                get turbo() {
+                    return turbo;
+                },
+                wait(ms) {
+                    // Instant runs still yield a macrotask — a plugin polling `while(!done) await wait()`
+                    // must not starve the event loop the animation it awaits runs on.
+                    if (run.instant)
+                        return new Promise((resolve) => setTimeout(resolve, 0));
+                    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 || run.instant)
+                        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) {
+                        if (run.halted)
+                            return;
+                        const contribution = registry.step(step.do);
+                        if (!contribution)
+                            continue; // validated; defensive
+                        trace({
+                            do: step.do,
+                            node: typeof step.node === 'string' ? step.node : undefined,
+                        });
+                        // trace() may flip `halted` on THIS entry — the halting step still executes
+                        // (scrub = "the state right after step N"); the loop stops before the next one.
+                        await contribution.run(step, rtLocal);
+                    }
+                },
+                resolve(value) {
+                    if (typeof value === 'string' && value.startsWith('$')) {
+                        return value
+                            .slice(1)
+                            .split('.')
+                            .reduce((acc, key) => acc?.[key], ctxLocal);
+                    }
+                    return value;
+                },
+                when(expr) {
+                    const bare = /^\s*([A-Za-z_$][\w$]*)\s*$/.exec(expr);
+                    if (bare)
+                        return Boolean(ctxLocal[bare[1]]);
+                    const result = evalVisibleWhen(expr, ctxLocal);
+                    if (result === undefined) {
+                        log(`unsupported when "${expr}" — treated as false`);
+                        return false;
+                    }
+                    return result;
+                },
+                child: (ctxPatch) => makeRuntime({ ...ctxLocal, ...ctxPatch }),
+                trace,
+                view: (id) => opts.scene.node(id),
+                log,
+                codeRef: (ref) => opts.code?.[ref],
+                playCue(name, action) {
+                    if (run.instant)
+                        return; // scrub replays stay silent
+                    if (action === 'stop')
+                        return audio.stop(name);
+                    const resolved = resolveCue(name);
+                    if (resolved)
+                        audio.play(resolved);
+                },
+            };
+            return rtLocal;
+        };
+        const rt = makeRuntime(ctx);
+        try {
+            if (!steps)
+                log(`fire("${event}") — no steps declared`);
+            else
+                await rt.run(steps);
+        }
+        finally {
+            active.delete(run);
+        }
+        return {
+            event,
+            turbo,
+            skipped: run.skipped,
+            ...(replay ? { haltedAtEntry: Math.min(run.haltAfter, entries.length - 1) } : {}),
+            durationMs: Math.round(performance.now() - start),
+            entries,
+        };
+    };
+    return {
+        fire,
+        replay(event, untilEntry) {
+            const ctx = lastCtx.get(event);
+            if (!ctx)
+                log(`replay("${event}") before any fire — running with an empty ctx`);
+            // Scrub = doc baseline + steps 0..N. Without the reset, leftovers of the previous
+            // full run (steps > N) would bleed into the pose.
+            opts.scene.resetProps();
+            return fire(event, ctx ?? {}, { replay: { untilEntry } });
+        },
+        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();
+        },
+    };
+}
+
+// DocScene — the host bridge: a Scene + SlotSceneController whose presentation is
+// entirely doc-driven. It builds the display tree from scene.json, lays out on the
+// host's design-unit resize, and translates every host lifecycle hook into a flow-IR
+// event (serialized, so spinStart/result/enterMode never interleave). Sound cues route
+// to the REAL SceneApi.audio. With this class a game's `scenes` list entry becomes
+//   { key: 'game', scene: createDocScene({ scene: sceneJson, flow: flowJson, … }) }
+// and the game ships no GameScene code for whatever the docs express.
+/** Build the createSlotGame `scenes` list from a StageDoc — every entry a DocScene. */
+function buildDocScenes(stage, shared) {
+    return stage.scenes.map((entry) => ({
+        key: entry.key,
+        scene: new DocScene({ ...shared, scene: entry.scene, flow: entry.flow, advanceOnTap: entry.advanceOnTap }),
+        skipOnReplay: entry.skipOnReplay,
+    }));
+}
+/** Cue channel 'music' routes to playMusic/stopMusic; everything else to play(). */
+function sceneAudioAdapter(api, log) {
+    const musicCues = new Set();
+    return {
+        play(cue) {
+            const audio = api()?.audio;
+            if (!audio)
+                return log(`audio cue "${cue.cue}" before onCreate — dropped`);
+            if (cue.channel === 'music') {
+                musicCues.add(cue.cue);
+                audio.playMusic(cue.src);
+            }
+            else {
+                audio.play(cue.src, { loop: cue.loop, speed: cue.rate, volume: cue.volume });
+            }
+        },
+        stop(cueName) {
+            const audio = api()?.audio;
+            if (!audio)
+                return;
+            if (musicCues.has(cueName))
+                audio.stopMusic();
+            // Looped sfx stop is not addressable through SceneAudio yet — flows should prefer
+            // short one-shots for sfx and music channel for anything long-lived.
+        },
+    };
+}
+class DocScene extends Scene {
+    opts;
+    api = null;
+    handle_ = null;
+    runner_ = null;
+    chain = Promise.resolve();
+    lastSize = { width: 0, height: 0 };
+    log;
+    constructor(opts) {
+        super();
+        this.opts = opts;
+        this.log = opts.log ?? ((m) => console.warn(`[doc-scene] ${m}`));
+    }
+    /** The live scene handle (inspector/agent attachment). Null before onEnter. */
+    get scene() {
+        return this.handle_;
+    }
+    get flow() {
+        return this.runner_;
+    }
+    // ── Scene lifecycle ────────────────────────────────────────────────────────
+    onEnter(data) {
+        const goto = data?.goto;
+        const sceneOpts = {
+            plugins: this.opts.plugins,
+            resolveSymbol: this.opts.resolveSymbol,
+            vars: { mode: 'BASE', ...(this.opts.vars ?? {}) },
+            log: this.log,
+        };
+        if (this.opts.texture)
+            sceneOpts.texture = this.opts.texture;
+        this.handle_ = createSceneFromDoc(this.opts.scene, sceneOpts);
+        this.container.addChild(this.handle_.view);
+        if (this.lastSize.width > 0)
+            this.handle_.layout(this.lastSize.width, this.lastSize.height);
+        if (this.opts.flow) {
+            this.runner_ = createFlowRunner(this.opts.flow, {
+                scene: this.handle_,
+                plugins: this.opts.flowPlugins,
+                code: this.opts.code,
+                audio: sceneAudioAdapter(() => this.api, this.log),
+                onTrace: this.opts.onTrace,
+                log: this.log,
+            });
+        }
+        // Taps feed `wait until:'tap'` flows; with advanceOnTap they also switch scenes.
+        this.container.eventMode = 'static';
+        this.container.on('pointertap', () => {
+            this.runner_?.tap();
+            if (this.opts.advanceOnTap)
+                goto?.(this.opts.advanceOnTap);
+        });
+        if (this.opts.flow?.on['enter'])
+            void this.fire('enter');
+    }
+    onResize(width, height) {
+        this.lastSize = { width, height };
+        this.handle_?.layout(width, height);
+        this.container.hitArea = { contains: (x, y) => x >= 0 && y >= 0 && x <= width && y <= height };
+    }
+    onDestroy() {
+        this.runner_?.destroy();
+        this.handle_?.destroy();
+        this.runner_ = null;
+        this.handle_ = null;
+    }
+    // ── SlotSceneController → flow events (serialized) ─────────────────────────
+    fire(event, ctx) {
+        const next = this.chain.then(() => this.runner_?.fire(event, ctx)).catch((err) => {
+            this.log(`flow "${event}" failed: ${String(err)}`);
+        });
+        this.chain = next;
+        return next;
+    }
+    ctxOf(result, ctx) {
+        if (this.opts.resultCtx)
+            return this.opts.resultCtx(result, ctx);
+        return {
+            ...result,
+            win: result.totalWin,
+            mode: ctx.mode,
+            action: ctx.action,
+            bet: ctx.bet,
+        };
+    }
+    onCreate(api) {
+        this.api = api;
+        this.runner_?.setTurbo((this.opts.turboFactor ?? ((l) => 1 + l))(api.turbo));
+    }
+    onSpinStart() {
+        void this.fire('spinStart');
+    }
+    async onSpin(result, ctx) {
+        await this.fire('result', this.ctxOf(result, ctx));
+    }
+    async onEnterMode(result, ctx) {
+        this.handle_?.setVar('mode', ctx.mode);
+        await this.fire('enterMode', this.ctxOf(result, ctx));
+    }
+    async onExitMode(result, ctx) {
+        await this.fire('exitMode', this.ctxOf(result, ctx));
+        this.handle_?.setVar('mode', 'BASE');
+    }
+    onSpinEnd(result, ctx) {
+        void this.fire('spinEnd', this.ctxOf(result, ctx));
+    }
+    onSkip() {
+        this.runner_?.skip();
+    }
+    onTurboChanged(level) {
+        this.runner_?.setTurbo((this.opts.turboFactor ?? ((l) => 1 + l))(level));
+    }
+}
+function createDocScene(opts) {
+    return new DocScene(opts);
+}
+
+export { BUILTIN_FILTER_KINDS, BUILTIN_NODE_TYPES, DocScene, buildDocScenes, createDocScene, createInnerCalibrator, createSceneFromDoc, createSceneRegistry, createTransformGizmo, dependencyOf, dragInnerEdge, edgePoint, effectiveNode, evalVisibleWhen, handlePoint, nudgeRule, orientationOf, placementBounds, resizeFactors, resizeRule, resolveLayoutRule, setRuleRotation, sizeLever, validateSceneDoc };
 //# sourceMappingURL=scene.esm.js.map