@energy8platform/game-engine 0.34.2 → 0.35.0

package/dist/scene.cjs.js

@@ -2,6 +2,248 @@
 
 var pixi_js = require('pixi.js');
 
+// Scene composition: one scene doc extending another, and the diff between two resolved
+// docs expressed as patches.
+//
+// Why this exists: each game mode gets its OWN scene (base, free spins, a bonus screen), so
+// you open it in the editor and lay it out directly instead of guessing at overrides. But a
+// survey of nine shipped games found ~86% of modes are "the same board, re-skinned" — the
+// delta is usually a background texture, a music track and one or two HUD widgets. Without
+// inheritance every free-spins scene would be a copy of the base scene, and the two would
+// drift apart the first time anyone moved the reels.
+//
+// So: `free-spins.scene.json` declares `extends: "base.scene.json"` and carries only what
+// differs. And because no real game rebuilds its board when a mode starts — the reel system
+// is constructed once and lives for the whole scene — switching modes applies the DIFF to
+// the live scene rather than tearing it down.
+/** A node in an extending doc may delete an inherited node instead of overriding it. */
+const REMOVE_MARKER = '$remove';
+const clone = (v) => JSON.parse(JSON.stringify(v));
+/**
+ * Merge a child node over an inherited one. Only the fields the child states are replaced,
+ * so a free-spins scene that changes a background's texture keeps its layout, filters and
+ * everything else. `children` merge by id (see mergeChildren).
+ */
+function mergeNode(base, over) {
+    const out = { ...base };
+    if (over.type !== undefined && over.type !== base.type)
+        out.type = over.type;
+    if (over.name !== undefined)
+        out.name = over.name;
+    // Props merge key-wise, so `{ src: 'bg-fs' }` does not wipe a tint set in the base.
+    if (over.props)
+        out.props = { ...(base.props ?? {}), ...over.props };
+    if (over.layout !== undefined)
+        out.layout = over.layout;
+    if (over.responsive)
+        out.responsive = { ...(base.responsive ?? {}), ...over.responsive };
+    if (over.states)
+        out.states = { ...(base.states ?? {}), ...over.states };
+    if (over.mask !== undefined)
+        out.mask = over.mask;
+    if (over.filters !== undefined)
+        out.filters = over.filters;
+    if (over.visibleWhen !== undefined)
+        out.visibleWhen = over.visibleWhen;
+    if (over.anchorName !== undefined)
+        out.anchorName = over.anchorName;
+    out.children = mergeChildren(base.children, over.children);
+    if (out.children === undefined)
+        delete out.children;
+    return out;
+}
+/**
+ * Merge child lists by id. An id present in both is merged; an id only in the child is
+ * appended (so a mode can add a spins counter); `{id, type: '$remove'}` deletes an
+ * inherited node. Base order is preserved — z-order is structural, not incidental.
+ */
+function mergeChildren(base, over) {
+    if (!over)
+        return base ? clone(base) : undefined;
+    const byId = new Map();
+    for (const node of over)
+        byId.set(node.id, node);
+    const out = [];
+    for (const node of base ?? []) {
+        const patch = byId.get(node.id);
+        byId.delete(node.id);
+        if (patch?.type === REMOVE_MARKER)
+            continue;
+        out.push(patch ? mergeNode(clone(node), patch) : clone(node));
+    }
+    // Anything the child introduced that the base did not have, in the order it declared it.
+    for (const node of over) {
+        if (byId.has(node.id) && node.type !== REMOVE_MARKER)
+            out.push(clone(node));
+    }
+    return out.length ? out : undefined;
+}
+/**
+ * Resolve a doc's `extends` chain into a single self-contained doc. Docs without `extends`
+ * are returned as-is (cloned), so this is safe to call on everything.
+ */
+function resolveExtends(doc, opts) {
+    const maxDepth = opts.maxDepth ?? 8;
+    const chain = [];
+    const seen = new Set();
+    let cursor = doc;
+    while (cursor) {
+        chain.unshift(cursor);
+        const ref = cursor.extends;
+        if (!ref)
+            break;
+        if (seen.has(ref))
+            throw new Error(`scene "${doc.id}": extends cycle at "${ref}"`);
+        seen.add(ref);
+        if (chain.length > maxDepth)
+            throw new Error(`scene "${doc.id}": extends chain deeper than ${maxDepth}`);
+        const parent = opts.load(ref);
+        if (!parent)
+            throw new Error(`scene "${doc.id}": cannot resolve extends "${ref}"`);
+        cursor = parent;
+    }
+    // Fold base → … → child.
+    let out = clone(chain[0]);
+    for (let i = 1; i < chain.length; i++) {
+        const over = chain[i];
+        out = {
+            ...out,
+            id: over.id,
+            design: over.design ?? out.design,
+            root: mergeNode(out.root, over.root),
+        };
+    }
+    delete out.extends;
+    return out;
+}
+function index(doc) {
+    const map = new Map();
+    const walk = (node, parentId, i) => {
+        map.set(node.id, { node, parentId, index: i });
+        (node.children ?? []).forEach((c, ci) => walk(c, node.id, ci));
+    };
+    walk(doc.root, null, 0);
+    return map;
+}
+const same = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+/**
+ * The patches that turn `from` into `to`. Used to switch game modes without rebuilding: a
+ * node both docs share and agree on is never touched, so the reel system, its symbols and
+ * any running animation survive the transition.
+ *
+ * Order matters — removals first (ids can be reused), then additions parent-before-child,
+ * then property updates.
+ */
+function diffDocs(from, to) {
+    const a = index(from);
+    const b = index(to);
+    const patches = [];
+    // Removed: only the topmost node of a removed subtree — removing it takes the rest.
+    for (const [id, loc] of a) {
+        if (b.has(id))
+            continue;
+        const parentGone = loc.parentId !== null && !b.has(loc.parentId);
+        if (!parentGone)
+            patches.push({ op: 'remove-node', id });
+    }
+    // Added, parents before children so the parent exists when the child lands.
+    const addedRoots = [];
+    for (const [id, loc] of b) {
+        if (a.has(id))
+            continue;
+        if (loc.parentId !== null && !a.has(loc.parentId) && !b.get(loc.parentId))
+            continue;
+        // Skip nodes whose parent is itself new — they ride along inside the parent's subtree.
+        if (loc.parentId !== null && !a.has(loc.parentId))
+            continue;
+        addedRoots.push({ id, loc });
+    }
+    for (const { loc } of addedRoots) {
+        patches.push({ op: 'add-node', parent: loc.parentId, node: clone(loc.node), index: loc.index });
+    }
+    // Changed, for nodes present in both.
+    for (const [id, next] of b) {
+        const prev = a.get(id);
+        if (!prev)
+            continue;
+        if (!same(prev.node.props, next.node.props)) {
+            // Keys the new doc dropped must be cleared, or they would linger from the old mode.
+            const props = {};
+            for (const key of Object.keys(prev.node.props ?? {}))
+                props[key] = undefined;
+            Object.assign(props, next.node.props ?? {});
+            patches.push({ op: 'set-props', id, props });
+        }
+        if (!same(prev.node.layout, next.node.layout)) {
+            patches.push({ op: 'set-layout', id, layout: (next.node.layout ?? null) });
+        }
+        if (!same(prev.node.name, next.node.name)) {
+            patches.push({ op: 'set-name', id, name: next.node.name });
+        }
+    }
+    return patches;
+}
+
+// Field schemas — the authoring contract for a node type's props.
+//
+// Before this existed the inspector inferred a control from the CURRENT value, which meant
+// a prop that wasn't set yet had no row and no way to be added: a freshly added sprite had
+// `props:{}` and therefore no way to choose a texture at all. It also had no notion of an
+// enum, an asset or a node reference, and it round-tripped booleans through text.
+//
+// A schema is declared once by the contribution that owns the kind, and is used three ways:
+// the inspector renders from it, validation can check against it, and the agent reads the
+// same text as documentation (`doc`) — the plugin's docs and the agent's prompt stay one
+// thing, per docs/slot-ide.md §6.2.
+/** Shared field definitions, so every kind describes `alpha` the same way. */
+const ALPHA_FIELD = {
+    kind: 'number',
+    doc: 'Opacity, 0 = invisible, 1 = opaque.',
+    default: 1,
+    min: 0,
+    max: 1,
+    step: 0.05,
+    order: 90,
+};
+/** Fractions of a texture (0..1), used for both `region` (crop) and `inner` (frame hollow). */
+const fracBoxFields = (doc) => ({
+    kind: 'object',
+    doc,
+    order: 60,
+    fields: {
+        left: { kind: 'number', default: 0, min: 0, max: 1, step: 0.01 },
+        top: { kind: 'number', default: 0, min: 0, max: 1, step: 0.01 },
+        width: { kind: 'number', default: 1, min: 0, max: 1, step: 0.01 },
+        height: { kind: 'number', default: 1, min: 0, max: 1, step: 0.01 },
+    },
+});
+function schemaFieldRows(schema, props) {
+    const rows = [];
+    if (!schema)
+        return rows;
+    const visit = (fields, prefix, container) => {
+        const entries = Object.entries(fields).sort((a, b) => (a[1].order ?? 1000) - (b[1].order ?? 1000) || a[0].localeCompare(b[0]));
+        for (const [key, field] of entries) {
+            const path = prefix ? `${prefix}.${key}` : key;
+            const parent = container;
+            const value = parent && typeof parent === 'object' ? parent[key] : undefined;
+            if (field.kind === 'object' && field.fields) {
+                visit(field.fields, path, value);
+            }
+            else {
+                rows.push({ path, label: field.label ?? path, schema: field, value, unset: value === undefined });
+            }
+        }
+    };
+    visit(schema, '', props);
+    return rows;
+}
+/** Props present on the node that the schema doesn't describe (plugin extras, hand-written). */
+function extraPropKeys(schema, props) {
+    const known = new Set(Object.keys(schema ?? {}));
+    return Object.keys(props).filter((k) => !known.has(k));
+}
+
 // Pure layout core for scene-IR.
 //
 // `resolveLayoutRule` turns one LayoutRule into a Placement given a context of already
@@ -12,11 +254,10 @@ function orientationOf(width, height, portraitFactor = 1) {
     return width < height * portraitFactor ? 'portrait' : 'landscape';
 }
 /** Base node + orientation override + active state override (state wins), for one frame. */
-function effectiveNode(node, orientation, state, mode) {
-    // Layer order: base → orientation → mode → active state (later wins).
+function effectiveNode(node, orientation, state) {
+    // Layer order: base → orientation → active state (later wins).
     const layers = [
         node.responsive?.[orientation],
-        mode ? node.modes?.[mode] : undefined,
         state ? node.states?.[state] : undefined,
     ];
     let layout = node.layout;
@@ -2955,12 +3196,51 @@ function emptyBoard(cfg) {
 // Everything else (ropes, meters, particles, game HUDs) arrives as a ScenePlugin through
 // the same contribution shape — built-ins get no special powers.
 const num$1 = (v, fallback) => (typeof v === 'number' && Number.isFinite(v) ? v : fallback);
+/** Word wrapping: without it a caption runs straight off the card it belongs to. */
+function wrapStyle(p) {
+    const width = p.wrapWidth;
+    if (typeof width !== 'number' || width <= 0)
+        return {};
+    return {
+        wordWrap: true,
+        wordWrapWidth: width,
+        breakWords: p.breakWords === true,
+        ...(typeof p.lineHeight === 'number' ? { lineHeight: p.lineHeight } : {}),
+    };
+}
+/** Pixi's text drop shadow, from the doc's `dropShadow` object (absent → no shadow). */
+function dropShadowStyle(spec) {
+    if (!spec || typeof spec !== 'object')
+        return {};
+    const d = spec;
+    return {
+        dropShadow: {
+            color: typeof d.color === 'string' ? d.color : '#000000',
+            blur: num$1(d.blur, 4),
+            distance: num$1(d.distance, 3),
+            angle: num$1(d.angle, Math.PI / 6),
+            alpha: num$1(d.alpha, 1),
+        },
+    };
+}
 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.',
+        schema: {
+            space: {
+                kind: 'object',
+                doc: 'Turn this container into a nested coordinate space of that design size; descendants lay out inside it and this node\'s own rule places the space (cover → the diorama idiom).',
+                order: 10,
+                fields: {
+                    width: { kind: 'number', default: 1920, min: 1, step: 1 },
+                    height: { kind: 'number', default: 1080, min: 1, step: 1 },
+                },
+            },
+            alpha: ALPHA_FIELD,
+        },
         defaults: { label: kind === 'layer' ? 'Layer' : 'Container', props: {} },
         create(node) {
             const view = new pixi_js.Container();
@@ -2983,6 +3263,22 @@ 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}.',
+    schema: {
+        width: { kind: 'number', doc: 'Width in this node\'s coordinate space.', default: 100, min: 0, step: 1, order: 10 },
+        height: { kind: 'number', doc: 'Height in this node\'s coordinate space.', default: 100, min: 0, step: 1, order: 11 },
+        fill: { kind: 'color', doc: 'Fill colour.', default: '#ffffff', order: 20 },
+        radius: { kind: 'number', doc: 'Corner radius in px (0 = square).', default: 0, min: 0, step: 1, order: 30 },
+        stroke: {
+            kind: 'object',
+            doc: 'Optional outline.',
+            order: 40,
+            fields: {
+                color: { kind: 'color', default: '#000000' },
+                width: { kind: 'number', default: 1, min: 0, step: 1 },
+            },
+        },
+        alpha: ALPHA_FIELD,
+    },
     defaults: {
         label: 'Rectangle',
         props: { width: 200, height: 120, fill: '#3355aa', radius: 12 },
@@ -3051,11 +3347,22 @@ function spriteInstance(node, ctx) {
         applyProps: apply,
     };
 }
+const SPRITE_SCHEMA = {
+    src: { kind: 'asset', accept: 'image', doc: 'Texture alias from the asset manifest.', order: 1 },
+    tint: { kind: 'color', doc: 'Multiplies the texture colour; white = untinted.', default: '#ffffff', order: 20 },
+    flipX: { kind: 'boolean', doc: 'Mirror horizontally.', default: false, order: 30 },
+    region: fracBoxFields('Crop to a sub-rectangle of the texture, in fractions (0..1) — used to slice one atlas into left/right halves.'),
+    alpha: ALPHA_FIELD,
+};
 const spriteContribution = {
     kind: 'sprite',
     agentDoc: 'Static art. Props: src (texture alias), tint, alpha. Natural size = texture size; use layout to place/scale.',
+    schema: SPRITE_SCHEMA,
     defaults: {
         label: 'Sprite',
+        // Deliberately empty: a fresh sprite is invisible until it has a texture, and the fix
+        // for that is that `src` is now a picker in the inspector the moment it is selected.
+        // (A placeholder tint would only survive to discolour the art the user then picks.)
         props: {},
         layout: { mode: 'viewport-fraction', xFrac: 0.5, yFrac: 0.5, anchor: [0.5, 0.5] },
     },
@@ -3064,12 +3371,46 @@ const spriteContribution = {
 const reelFrameContribution = {
     kind: 'reelFrame',
     agentDoc: 'The reel frame art. Declare where its hollow is once in props.inner {left,top,width,height} (fractions of the texture); the grid then binds with layout {mode:"frame-fraction", frame:<this id>, use:"inner"} — never restate the numbers.',
+    schema: {
+        ...SPRITE_SCHEMA,
+        inner: fracBoxFields('Where the frame\'s hollow is, in fractions of the texture. Grids bind to it with {mode:"frame-fraction", use:"inner"} instead of restating numbers.'),
+    },
+    defaults: {
+        label: 'Reel frame',
+        props: { inner: { left: 0.06, top: 0.08, width: 0.88, height: 0.84 } },
+        layout: { mode: 'viewport-fraction', xFrac: 0.5, yFrac: 0.5, widthFrac: 0.8, anchor: [0.5, 0.5] },
+    },
     create: spriteInstance,
 };
 // ── text ────────────────────────────────────────────────────────────────────────────
 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.',
+    schema: {
+        text: { kind: 'text', doc: 'The string to draw.', default: '', order: 1 },
+        fontSize: { kind: 'number', doc: 'Size in this node\'s coordinate space.', default: 32, min: 1, step: 1, order: 10 },
+        fill: { kind: 'color', doc: 'Text colour.', default: '#ffffff', order: 11 },
+        fontFamily: { kind: 'text', doc: 'CSS font stack. The font must be preloaded by the game.', default: 'Arial, sans-serif', order: 20 },
+        fontWeight: { kind: 'enum', options: ['normal', 'bold'], default: 'normal', order: 21 },
+        align: { kind: 'enum', options: ['left', 'center', 'right'], default: 'left', order: 22 },
+        letterSpacing: { kind: 'number', default: 0, step: 1, order: 30 },
+        wrapWidth: { kind: 'number', doc: 'Wrap the text at this width (design px). Unset = one line.', min: 0, step: 10, order: 32 },
+        lineHeight: { kind: 'number', doc: 'Line spacing when wrapped.', min: 0, step: 1, order: 33 },
+        breakWords: { kind: 'boolean', doc: 'Allow breaking inside a long word.', default: false, order: 34 },
+        dropShadow: {
+            kind: 'object',
+            doc: 'Soft shadow behind the glyphs — what lifts a prompt off a busy background.',
+            order: 40,
+            fields: {
+                color: { kind: 'color', default: '#000000' },
+                blur: { kind: 'number', default: 4, min: 0, step: 1 },
+                distance: { kind: 'number', default: 3, min: 0, step: 1 },
+                angle: { kind: 'number', doc: 'Radians; default is down-right.', default: Math.PI / 6, step: 0.1 },
+                alpha: { kind: 'number', default: 1, min: 0, max: 1, step: 0.05 },
+            },
+        },
+        alpha: ALPHA_FIELD,
+    },
     defaults: {
         label: 'Text',
         props: { text: 'Text', fontSize: 48, fill: '#ffffff', fontWeight: 'bold' },
@@ -3086,6 +3427,8 @@ const textContribution = {
                 fontWeight: props.fontWeight ?? 'normal',
                 align: props.align ?? 'left',
                 letterSpacing: num$1(props.letterSpacing, 0),
+                ...dropShadowStyle(props.dropShadow),
+                ...wrapStyle(props),
             },
         });
         return {
@@ -3097,6 +3440,15 @@ const textContribution = {
                 view.style.fill = p.fill ?? '#ffffff';
                 view.style.fontSize = num$1(p.fontSize, 32);
                 view.style.letterSpacing = num$1(p.letterSpacing, 0);
+                const shadow = dropShadowStyle(p.dropShadow);
+                view.style.dropShadow = shadow.dropShadow ?? false;
+                const wrap = wrapStyle(p);
+                view.style.wordWrap = wrap.wordWrap ?? false;
+                if (wrap.wordWrapWidth !== undefined)
+                    view.style.wordWrapWidth = wrap.wordWrapWidth;
+                if (wrap.lineHeight !== undefined)
+                    view.style.lineHeight = wrap.lineHeight;
+                view.style.breakWords = wrap.breakWords ?? false;
                 view.alpha = num$1(p.alpha, 1);
             },
         };
@@ -3106,6 +3458,27 @@ const textContribution = {
 const animatedSpriteContribution = {
     kind: 'animatedSprite',
     agentDoc: 'Frame animation from a grid spritesheet. Props: sheet {alias, cols, rows}, frame (static frame index, default 0), fps + playing:true for an ambient loop. Choreographed playback belongs to flow/animation clips, not here.',
+    schema: {
+        sheet: {
+            kind: 'object',
+            doc: 'A grid spritesheet: one image cut into cols x rows equal frames.',
+            order: 1,
+            fields: {
+                alias: { kind: 'asset', accept: 'spritesheet', doc: 'Sheet texture alias.' },
+                cols: { kind: 'number', default: 1, min: 1, step: 1 },
+                rows: { kind: 'number', default: 1, min: 1, step: 1 },
+            },
+        },
+        frame: { kind: 'number', doc: 'Static frame shown when not playing.', default: 0, min: 0, step: 1, order: 10 },
+        fps: { kind: 'number', doc: 'Playback rate when playing.', default: 12, min: 0, step: 1, order: 11 },
+        playing: { kind: 'boolean', doc: 'Loop continuously. Choreographed playback belongs in flow, not here.', default: false, order: 12 },
+        alpha: ALPHA_FIELD,
+    },
+    defaults: {
+        label: 'Animated sprite',
+        props: { sheet: { cols: 1, rows: 1 }, frame: 0, fps: 12 },
+        layout: { mode: 'viewport-fraction', xFrac: 0.5, yFrac: 0.5, anchor: [0.5, 0.5] },
+    },
     create(node, ctx) {
         const view = new pixi_js.Container();
         let animated = null;
@@ -3152,6 +3525,21 @@ const animatedSpriteContribution = {
 // ── reelGrid ────────────────────────────────────────────────────────────────────────
 const reelGridContribution = {
     kind: 'reelGrid',
+    schema: {
+        preset: {
+            kind: 'enum',
+            doc: 'Named reel-system preset; `config` layers on top of it.',
+            options: Object.keys(PRESETS),
+            order: 1,
+        },
+        config: { kind: 'json', doc: 'Partial ReelSystemConfig override (columns, rows, spin motion, anticipation, tumble...).', order: 10 },
+        board: { kind: 'json', doc: 'Symbol ids as string[][], column-major — the statically shown board.', order: 20 },
+    },
+    defaults: {
+        label: 'Reel grid',
+        props: { preset: Object.keys(PRESETS)[0] },
+        layout: { mode: 'viewport-fraction', xFrac: 0.5, yFrac: 0.5, widthFrac: 0.6, anchor: [0.5, 0.5] },
+    },
     agentDoc: 'The reel window, delegating to createReelSystem. Props: preset (named ReelSystemConfig preset), config (DeepPartial override), board (string[][] of symbol ids, column-major). Bind into the frame hollow with {mode:"frame-fraction", frame:"<frameId>", use:"inner"}. Needs `resolveSymbol` passed to createSceneFromDoc.',
     create(node, ctx) {
         if (!ctx.resolveSymbol) {
@@ -3225,6 +3613,10 @@ const prefabContribution = {
 const BUILTIN_FILTER_KINDS = [
     {
         kind: 'blur',
+        schema: {
+            strength: { kind: 'number', doc: 'Blur radius.', default: 8, min: 0, step: 1 },
+            quality: { kind: 'number', doc: 'Passes — higher is smoother and costlier.', default: 4, min: 1, step: 1 },
+        },
         agentDoc: 'Gaussian blur: {kind:"blur", strength, quality}. Shadow/glow layers idiom.',
         create(spec) {
             return new pixi_js.BlurFilter({
@@ -3440,10 +3832,9 @@ function createSceneFromDoc(doc, opts = {}) {
         lastWidth = width;
         lastHeight = height;
         const orientation = orientationOf(width, height, opts.portraitFactor ?? 1);
-        const mode = typeof vars.mode === 'string' ? vars.mode : null;
-        // Phase 1 — effective props (base + orientation + mode + state), applied before measuring.
+        // Phase 1 — effective props (base + orientation + state), applied before measuring.
         for (const runtime of [...runtimes.values()]) {
-            const eff = effectiveNode(runtime.node, orientation, runtime.state, mode);
+            const eff = effectiveNode(runtime.node, orientation, runtime.state);
             runtime.visibleBase = eff.visible;
             const space = eff.props.space;
             runtime.spaceSize =
@@ -3547,7 +3938,7 @@ function createSceneFromDoc(doc, opts = {}) {
                 const parentOriginY = parentIsFrame ? 0 : (runtime.parent?.bounds?.y ?? 0);
                 const parentScaleX = parentIsFrame ? 1 : (runtime.parent?.worldScaleX ?? 1);
                 const parentScaleY = parentIsFrame ? 1 : (runtime.parent?.worldScaleY ?? 1);
-                const eff = effectiveNode(runtime.node, orientation, runtime.state, mode);
+                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
@@ -3714,29 +4105,48 @@ function createSceneFromDoc(doc, opts = {}) {
         runtime.state = state;
         relayout();
     };
+    /** Warn (once per key) and report the rejection back to the caller. */
+    const reject = (key, msg) => {
+        warnOnce(key, msg);
+        return { ok: false, error: msg };
+    };
     const applyPatch = (patch) => {
+        // Each case fills this with the patch that puts the doc back exactly as it was — the
+        // editor's undo stack simply replays it. Captured BEFORE the mutation, necessarily.
+        let inverse;
         switch (patch.op) {
             case 'set-props': {
                 const node = findNode(doc.root, patch.id);
                 if (!node)
-                    return warnOnce(`patch:${patch.id}`, `patch: unknown node "${patch.id}"`);
-                if (patch.mode) {
-                    node.modes = { ...(node.modes ?? {}) };
-                    const over = node.modes[patch.mode] ?? {};
-                    node.modes[patch.mode] = { ...over, props: { ...(over.props ?? {}), ...patch.props } };
-                }
-                else {
-                    node.props = { ...(node.props ?? {}), ...patch.props };
-                }
+                    return reject(`patch:${patch.id}`, `patch: unknown node "${patch.id}"`);
+                // Undo restores each touched key to what it held — `undefined` for keys that were
+                // absent, which the prop readers treat as "not set" and JSON.stringify drops.
+                const before = node.props ?? {};
+                const prev = {};
+                for (const key of Object.keys(patch.props))
+                    prev[key] = before[key];
+                inverse = { op: 'set-props', id: patch.id, props: prev };
+                node.props = { ...(node.props ?? {}), ...patch.props };
                 break;
             }
             case 'set-layout': {
                 const node = findNode(doc.root, patch.id);
                 if (!node)
-                    return warnOnce(`patch:${patch.id}`, `patch: unknown node "${patch.id}"`);
-                if (patch.mode) {
-                    node.modes = { ...(node.modes ?? {}) };
-                    node.modes[patch.mode] = { ...(node.modes[patch.mode] ?? {}), layout: patch.layout };
+                    return reject(`patch:${patch.id}`, `patch: unknown node "${patch.id}"`);
+                // Undo puts back the rule that occupied this exact slot — `null` when the slot did
+                // not exist, so undoing an edit that CREATED an override removes it again.
+                const prevRule = patch.orientation ? node.responsive?.[patch.orientation]?.layout : node.layout;
+                inverse = {
+                    op: 'set-layout',
+                    id: patch.id,
+                    layout: prevRule ? JSON.parse(JSON.stringify(prevRule)) : null,
+                    orientation: patch.orientation,
+                };
+                if (patch.layout === null) {
+                    if (patch.orientation)
+                        delete node.responsive?.[patch.orientation]?.layout;
+                    else
+                        delete node.layout;
                 }
                 else if (patch.orientation) {
                     node.responsive = { ...(node.responsive ?? {}) };
@@ -3750,31 +4160,57 @@ function createSceneFromDoc(doc, opts = {}) {
                 }
                 break;
             }
-            case 'set-state':
-                return setState(patch.id, patch.state);
-            case 'set-var':
-                return setVar(patch.name, patch.value);
+            case 'set-name': {
+                const node = findNode(doc.root, patch.id);
+                if (!node)
+                    return reject(`patch:${patch.id}`, `patch: unknown node "${patch.id}"`);
+                inverse = { op: 'set-name', id: patch.id, name: node.name };
+                if (patch.name === undefined || patch.name === '')
+                    delete node.name;
+                else
+                    node.name = patch.name;
+                break;
+            }
+            case 'set-state': {
+                // Runtime-only, so the previous value lives on the runtime, not in the doc.
+                const prevState = runtimes.get(patch.id)?.state ?? null;
+                setState(patch.id, patch.state);
+                return { ok: true, inverse: { op: 'set-state', id: patch.id, state: prevState } };
+            }
+            case 'set-var': {
+                const prevVar = vars[patch.name];
+                setVar(patch.name, patch.value);
+                return { ok: true, inverse: { op: 'set-var', name: patch.name, value: prevVar } };
+            }
             case 'add-node': {
                 const parentRuntime = runtimes.get(patch.parent);
                 if (!parentRuntime)
-                    return warnOnce(`add:${patch.parent}`, `add-node: unknown parent "${patch.parent}"`);
+                    return reject(`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`);
+                    return reject(`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}"`);
+                    return reject(`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();
+                inverse = { op: 'remove-node', id: patch.node.id };
                 break;
             }
             case 'remove-node': {
                 if (patch.id === doc.root.id)
-                    return warnOnce('rm-root', 'remove-node: cannot remove the root');
+                    return reject('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}"`);
+                    return reject(`rm:${patch.id}`, `remove-node: unknown node "${patch.id}"`);
+                // The whole subtree goes with it, so undo needs a deep copy taken before the splice.
+                inverse = {
+                    op: 'add-node',
+                    parent: loc.parent.id,
+                    node: JSON.parse(JSON.stringify(loc.parent.children[loc.index])),
+                    index: loc.index,
+                };
                 destroyRuntimeTree(patch.id);
                 loc.parent.children.splice(loc.index, 1);
                 wireMasks();
@@ -3782,17 +4218,18 @@ function createSceneFromDoc(doc, opts = {}) {
             }
             case 'move-node': {
                 if (patch.id === doc.root.id)
-                    return warnOnce('mv-root', 'move-node: cannot move the root');
+                    return reject('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}"`);
+                    return reject(`mv:${patch.id}`, `move-node: unknown node "${patch.id}"`);
                 if (!parentRuntime)
-                    return warnOnce(`mv-p:${patch.parent}`, `move-node: unknown parent "${patch.parent}"`);
+                    return reject(`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}"`);
+                    return reject(`mv-cycle:${patch.id}`, `move-node: cannot move "${patch.id}" into itself/its descendant "${patch.parent}"`);
                 }
+                inverse = { op: 'move-node', id: patch.id, parent: loc.parent.id, index: loc.index };
                 // `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
@@ -3805,11 +4242,11 @@ function createSceneFromDoc(doc, opts = {}) {
             }
             case 'duplicate-node': {
                 if (patch.id === doc.root.id)
-                    return warnOnce('dup-root', 'duplicate-node: cannot duplicate the root');
+                    return reject('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}"`);
+                    return reject(`dup:${patch.id}`, `duplicate-node: unknown node "${patch.id}"`);
                 let suffix = '-copy';
                 while (collectIds(source).some((id) => runtimes.has(`${id}${suffix}`)))
                     suffix += '2';
@@ -3818,10 +4255,12 @@ function createSceneFromDoc(doc, opts = {}) {
                 loc.parent.children.splice(loc.index + 1, 0, clone);
                 buildInto(clone, parentRuntime, loc.index + 1);
                 wireMasks();
+                inverse = { op: 'remove-node', id: clone.id };
                 break;
             }
         }
         relayout();
+        return { ok: true, inverse };
     };
     return {
         view: rootView,
@@ -3841,6 +4280,20 @@ function createSceneFromDoc(doc, opts = {}) {
         patch: applyPatch,
         doc: () => doc,
         palette: () => registry.palette(),
+        schemas() {
+            const out = {};
+            for (const kind of registry.kinds()) {
+                const schema = registry.nodeType(kind)?.schema;
+                if (schema)
+                    out[kind] = schema;
+            }
+            for (const name of registry.prefabNames()) {
+                const schema = registry.prefab(name)?.schema;
+                if (schema)
+                    out[`prefab:${name}`] = schema;
+            }
+            return out;
+        },
         resetProps() {
             for (const runtime of runtimes.values())
                 runtime.appliedProps = 'stale';
@@ -4155,7 +4608,10 @@ function createTransformGizmo(opts) {
     layer.addChildAt(body, 1);
     let nodeId = null;
     let drag = null;
-    const getMode = () => opts.getMode?.() ?? null;
+    /** Press origin, to tell a click apart from a drag on pointerup. */
+    let downAt = null;
+    let moved = false;
+    const DRAG_SLOP = 4; // px before a press counts as a drag
     const findDocNode = (id, node = handle.doc().root) => {
         if (node.id === id)
             return node;
@@ -4167,18 +4623,13 @@ function createTransformGizmo(opts) {
         return undefined;
     };
     /**
-     * Effective layout rule + which override an edit should target. Editing in a non-base
-     * mode targets that mode's override (so base and free_spins are edited independently);
-     * otherwise the current orientation override, else base.
+     * Effective layout rule + which override an edit should target: the current orientation's
+     * override when one exists, else the base rule.
      */
     const effectiveRule = (id) => {
         const node = findDocNode(id);
         if (!node)
             return { target: {} };
-        const mode = getMode();
-        if (mode && mode !== 'base') {
-            return { rule: node.modes?.[mode]?.layout ?? node.layout, target: { mode } };
-        }
         const o = getOrientation();
         const override = node.responsive?.[o]?.layout;
         return override ? { rule: override, target: { orientation: o } } : { rule: node.layout, target: {} };
@@ -4199,6 +4650,9 @@ function createTransformGizmo(opts) {
         if (!box || !rule)
             return;
         const center = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+        downAt = { x: e.global.x, y: e.global.y, handle: h, alt: e.altKey };
+        moved = false;
+        opts.onGestureStart?.();
         drag = {
             handle: h,
             startBox: box,
@@ -4212,6 +4666,11 @@ function createTransformGizmo(opts) {
     const onMove = (e) => {
         if (!drag || !nodeId)
             return;
+        if (!moved && downAt && (Math.abs(e.global.x - downAt.x) > DRAG_SLOP || Math.abs(e.global.y - downAt.y) > DRAG_SLOP)) {
+            moved = true;
+        }
+        if (!moved)
+            return; // a press that has not travelled yet is still a potential click
         let rule;
         if (drag.handle === 'body') {
             const s = dpp(nodeId);
@@ -4227,10 +4686,20 @@ function createTransformGizmo(opts) {
             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.target.orientation, mode: drag.target.mode });
+        applyPatch({ op: 'set-layout', id: nodeId, layout: rule, orientation: drag.target.orientation });
     };
     const onUp = () => {
+        if (drag)
+            opts.onGestureEnd?.();
         drag = null;
+        // Body press that never moved = a selection click, not a move.
+        if (downAt && !moved && downAt.handle === 'body') {
+            const { x, y, alt } = downAt;
+            downAt = null;
+            opts.onBodyClick?.(x, y, alt);
+            return;
+        }
+        downAt = null;
     };
     app.stage.on('pointermove', onMove);
     app.stage.on('pointerup', onUp);
@@ -4273,6 +4742,24 @@ function createTransformGizmo(opts) {
             redraw();
         },
         refresh: redraw,
+        nudge(dxScreen, dyScreen) {
+            if (!nodeId)
+                return;
+            const { rule, target } = effectiveRule(nodeId);
+            if (!rule)
+                return;
+            // Bracketed as a gesture so it lands on the undo stack as exactly one step.
+            opts.onGestureStart?.();
+            const s = dpp(nodeId);
+            applyPatch({
+                op: 'set-layout',
+                id: nodeId,
+                layout: nudgeRule(rule, dxScreen * s, dyScreen * s),
+                orientation: target.orientation,
+            });
+            opts.onGestureEnd?.();
+            redraw();
+        },
         drag(h, from, to) {
             onDown(h, fakeEvent(from.x, from.y));
             onMove(fakeEvent(to.x, to.y));
@@ -4360,6 +4847,12 @@ function formatValue(value, format) {
 }
 const tweenStep = {
     kind: 'tween',
+    schema: {
+        node: { kind: 'nodeRef', doc: 'Scene node to animate.', order: 1 },
+        to: { kind: 'json', doc: 'Target numeric view props, e.g. {"alpha":1,"y":40}.', order: 10 },
+        ms: { kind: 'number', doc: 'Duration; scaled by turbo, zero under skip.', default: 300, min: 0, step: 10, order: 20 },
+        ease: { kind: 'text', doc: 'Easing name from the Easing table.', default: 'linear', order: 30 },
+    },
     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;
@@ -4398,6 +4891,10 @@ const tweenStep = {
 };
 const soundStep = {
     kind: 'sound',
+    schema: {
+        cue: { kind: 'enum', doc: 'A cue declared in the doc\'s `cues`.', options: [], order: 1 },
+        action: { kind: 'enum', options: ['play', 'stop'], default: 'play', order: 10 },
+    },
     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;
@@ -4406,6 +4903,10 @@ const soundStep = {
 };
 const setStateStep = {
     kind: 'setState',
+    schema: {
+        node: { kind: 'nodeRef', doc: 'Node whose named variant changes.', order: 1 },
+        state: { kind: 'text', doc: 'A state declared on that node; empty clears it.', order: 10 },
+    },
     agentDoc: "Switch a node's named state (frame anticipation/bonus look). Same operation the inspector and agent use.",
     run(raw, rt) {
         const step = raw;
@@ -4414,6 +4915,10 @@ const setStateStep = {
 };
 const setVarStep = {
     kind: 'setVar',
+    schema: {
+        name: { kind: 'text', doc: 'Runtime var name (drives visibleWhen).', order: 1 },
+        value: { kind: 'text', doc: 'Literal, or a $ctx reference.', order: 10 },
+    },
     agentDoc: "Set a runtime var driving visibleWhen (e.g. mode). Use for mode transitions ('setVar mode free_spins').",
     run(raw, rt) {
         const step = raw;
@@ -4422,6 +4927,10 @@ const setVarStep = {
 };
 const setPropsStep = {
     kind: 'setProps',
+    schema: {
+        node: { kind: 'nodeRef', order: 1 },
+        props: { kind: 'json', doc: 'Props to merge onto the node.', order: 10 },
+    },
     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;
@@ -4450,6 +4959,14 @@ function findDocNode(rt, id) {
 }
 const countUpStep = {
     kind: 'countUp',
+    schema: {
+        node: { kind: 'nodeRef', doc: 'Node holding the number (a text or a prefab).', order: 1 },
+        prop: { kind: 'text', default: 'value', order: 5 },
+        from: { kind: 'text', doc: 'Start value; literal or $ctx. Defaults to the current one.', order: 10 },
+        to: { kind: 'text', doc: 'End value; literal or $ctx (e.g. $win).', order: 11 },
+        ms: { kind: 'number', default: 1000, min: 0, step: 50, order: 20 },
+        format: { kind: 'enum', options: ['int', 'space'], order: 30 },
+    },
     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;
@@ -4477,6 +4994,10 @@ const countUpStep = {
 };
 const waitStep = {
     kind: 'wait',
+    schema: {
+        ms: { kind: 'number', doc: 'Pause; scaled by turbo, released by skip.', default: 300, min: 0, step: 10, order: 1 },
+        until: { kind: 'enum', doc: "'tap' waits for the player instead of a duration.", options: ['tap'], order: 10 },
+    },
     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;
@@ -4487,6 +5008,9 @@ const waitStep = {
 };
 const ifStep = {
     kind: 'if',
+    schema: {
+        when: { kind: 'text', doc: 'Guard: `<ctxField> <op> <literal>`, e.g. `win >= 20`.', order: 1 },
+    },
     agentDoc: "Branch on the fire() ctx: {when:'win >= 100', then:[…], else:[…]}. Bare name = truthy check.",
     async run(raw, rt) {
         const step = raw;
@@ -4495,6 +5019,7 @@ const ifStep = {
 };
 const parallelStep = {
     kind: 'parallel',
+    schema: {},
     agentDoc: 'Run tracks concurrently and await them all: {steps: [[…], […]]}. Each track is an independent sequence.',
     async run(raw, rt) {
         const step = raw;
@@ -4503,6 +5028,7 @@ const parallelStep = {
 };
 const seqStep = {
     kind: 'seq',
+    schema: {},
     agentDoc: 'Nested sequence (grouping inside parallel tracks).',
     async run(raw, rt) {
         const step = raw;
@@ -4511,6 +5037,12 @@ const seqStep = {
 };
 const forEachStep = {
     kind: 'forEach',
+    schema: {
+        items: { kind: 'text', doc: 'A $ctx array to walk, e.g. $cascadeSteps.', order: 1 },
+        as: { kind: 'text', doc: 'Name each element binds to inside ($item by default).', default: 'item', order: 10 },
+        mode: { kind: 'enum', options: ['sequential', 'parallel'], default: 'sequential', order: 20 },
+        staggerMs: { kind: 'number', doc: 'Delay between elements.', default: 0, min: 0, step: 10, order: 30 },
+    },
     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;
@@ -4538,6 +5070,10 @@ const forEachStep = {
 };
 const codeStep = {
     kind: 'code',
+    schema: {
+        ref: { kind: 'text', doc: 'Key in the host-provided `code` map — the escape hatch.', order: 1 },
+        args: { kind: 'json', order: 10 },
+    },
     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;
@@ -4562,6 +5098,73 @@ const BUILTIN_FLOW_STEPS = [
     codeStep,
 ];
 
+// Flow as a graph: stable step ids, and the layout that turns a flow event into nodes and
+// edges for the canvas editor.
+//
+// The IR is a TREE (a step list, with `seq`/`parallel`/`if`/`forEach` nesting more lists),
+// not a free DAG — control flow is strictly structural, there are no jumps. So the canvas
+// draws a nested flow diagram rather than a general node soup: consecutive steps chain
+// left to right, and a container is a box its children are laid out inside. That is the
+// honest picture of what actually runs; a flat DAG would have to invent joins the runtime
+// does not have.
+//
+// Layout is automatic by default so an existing flow.json opens as a readable graph with
+// no migration. A step only gets `ui: {x, y}` once someone drags it.
+/** Child lists a container step owns, by kind. `parallel` holds a list PER track. */
+function containerTracks(step) {
+    const kind = step.do;
+    if (kind === 'parallel') {
+        const tracks = step.steps;
+        return Array.isArray(tracks) && Array.isArray(tracks[0]) ? tracks : [];
+    }
+    if (kind === 'seq' || kind === 'forEach') {
+        const list = step.steps;
+        return Array.isArray(list) ? [list] : [];
+    }
+    if (kind === 'if') {
+        const s = step;
+        return [s.then ?? [], s.else ?? []];
+    }
+    return [];
+}
+/**
+ * Give every step a stable id, in place-ish (returns the same doc object). Ids are only
+ * assigned where missing, so re-running is a no-op and saved ids survive.
+ */
+function ensureStepIds(doc, prefix = 's') {
+    const used = new Set();
+    const collect = (list) => {
+        for (const step of list) {
+            if (typeof step.id === 'string')
+                used.add(step.id);
+            for (const track of containerTracks(step))
+                collect(track);
+        }
+    };
+    for (const list of Object.values(doc.on))
+        collect(list);
+    let n = 0;
+    const fresh = () => {
+        let id;
+        do {
+            id = `${prefix}${++n}`;
+        } while (used.has(id));
+        used.add(id);
+        return id;
+    };
+    const assign = (list) => {
+        for (const step of list) {
+            if (typeof step.id !== 'string' || step.id === '')
+                step.id = fresh();
+            for (const track of containerTracks(step))
+                assign(track);
+        }
+    };
+    for (const list of Object.values(doc.on))
+        assign(list);
+    return doc;
+}
+
 // Flow-IR interpreter: createFlowRunner(flowDoc, { scene, … }).fire(event, ctx) executes
 // the event's steps and returns a Trace.
 //
@@ -4603,6 +5206,8 @@ function validateFlowDoc(doc, registry) {
 function createFlowRunner(doc, opts) {
     const log = opts.log ?? ((msg) => console.warn(`[flow] ${msg}`));
     const registry = createFlowStepRegistry(opts.plugins ?? [], BUILTIN_FLOW_STEPS);
+    // Hand-written docs omit ids; assign them once so traces and the canvas can address steps.
+    ensureStepIds(doc);
     const errors = validateFlowDoc(doc, registry);
     if (errors.length > 0)
         throw new Error(`flow doc "${doc.id}" is invalid:\n  ${errors.join('\n  ')}`);
@@ -4710,6 +5315,9 @@ function createFlowRunner(doc, opts) {
                             continue; // validated; defensive
                         trace({
                             do: step.do,
+                            // Which step this came from, so the canvas can highlight it and a scrub can
+                            // point at it — `do` alone cannot tell two identical tweens apart.
+                            stepId: typeof step.id === 'string' ? step.id : undefined,
                             node: typeof step.node === 'string' ? step.node : undefined,
                         });
                         // trace() may flip `halted` on THIS entry — the halting step still executes
@@ -4775,6 +5383,10 @@ function createFlowRunner(doc, opts) {
     };
     return {
         fire,
+        stepKinds: () => registry.kinds().map((kind) => {
+            const c = registry.step(kind);
+            return { kind, schema: c?.schema, agentDoc: c?.agentDoc };
+        }),
         replay(event, untilEntry) {
             const ctx = lastCtx.get(event);
             if (!ctx)
@@ -4816,9 +5428,16 @@ function createFlowRunner(doc, opts) {
 // 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) => ({
+    // Mode views are not host scenes — they belong to the scene they extend.
+    const modeScenes = {};
+    for (const entry of stage.scenes)
+        if (entry.mode)
+            modeScenes[entry.mode] = entry.scene;
+    return stage.scenes
+        .filter((entry) => !entry.mode)
+        .map((entry) => ({
         key: entry.key,
-        scene: new DocScene({ ...shared, scene: entry.scene, flow: entry.flow, advanceOnTap: entry.advanceOnTap }),
+        scene: new DocScene({ ...shared, scene: entry.scene, modeScenes, flow: entry.flow, advanceOnTap: entry.advanceOnTap }),
         skipOnReplay: entry.skipOnReplay,
     }));
 }
@@ -4941,16 +5560,48 @@ class DocScene extends Scene {
     onSpinStart() {
         void this.fire('spinStart');
     }
+    /** The resolved doc currently on screen, so a mode switch diffs from the right baseline. */
+    activeDoc_ = null;
+    activeDocId_ = null;
     async onSpin(result, ctx) {
         await this.fire('result', this.ctxOf(result, ctx));
     }
     async onEnterMode(result, ctx) {
         this.handle_?.setVar('mode', ctx.mode);
+        this.applySceneFor(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');
+        this.applySceneFor(null); // back to the base scene
+    }
+    /**
+     * Move the live scene to the doc for `mode` (null = the base scene) by applying the diff.
+     * A no-op when the mode has no scene of its own, which is the common case: most modes
+     * differ only in what flow does.
+     */
+    applySceneFor(mode) {
+        const target = mode ? this.opts.modeScenes?.[mode] : this.opts.scene;
+        if (!target || !this.handle_)
+            return;
+        const resolved = this.resolveDoc(target);
+        if (resolved.id === this.activeDocId_)
+            return;
+        for (const patch of diffDocs(this.activeDoc_ ?? this.opts.scene, resolved)) {
+            const result = this.handle_.patch(patch);
+            if (result.ok === false)
+                this.opts.log?.(`mode scene "${resolved.id}": ${result.error}`);
+        }
+        this.activeDoc_ = resolved;
+        this.activeDocId_ = resolved.id;
+    }
+    /** Fold a doc's `extends` chain, looking parents up among the scenes this game declared. */
+    resolveDoc(doc) {
+        const pool = { [this.opts.scene.id]: this.opts.scene, ...(this.opts.modeScenes ?? {}) };
+        return resolveExtends(doc, {
+            load: (ref) => pool[ref] ?? Object.values(pool).find((d) => d.id === ref),
+        });
     }
     onSpinEnd(result, ctx) {
         void this.fire('spinEnd', this.ctxOf(result, ctx));
@@ -4966,9 +5617,11 @@ function createDocScene(opts) {
     return new DocScene(opts);
 }
 
+exports.ALPHA_FIELD = ALPHA_FIELD;
 exports.BUILTIN_FILTER_KINDS = BUILTIN_FILTER_KINDS;
 exports.BUILTIN_NODE_TYPES = BUILTIN_NODE_TYPES;
 exports.DocScene = DocScene;
+exports.REMOVE_MARKER = REMOVE_MARKER;
 exports.buildDocScenes = buildDocScenes;
 exports.createDocScene = createDocScene;
 exports.createInnerCalibrator = createInnerCalibrator;
@@ -4976,17 +5629,22 @@ exports.createSceneFromDoc = createSceneFromDoc;
 exports.createSceneRegistry = createSceneRegistry;
 exports.createTransformGizmo = createTransformGizmo;
 exports.dependencyOf = dependencyOf;
+exports.diffDocs = diffDocs;
 exports.dragInnerEdge = dragInnerEdge;
 exports.edgePoint = edgePoint;
 exports.effectiveNode = effectiveNode;
 exports.evalVisibleWhen = evalVisibleWhen;
+exports.extraPropKeys = extraPropKeys;
+exports.fracBoxFields = fracBoxFields;
 exports.handlePoint = handlePoint;
 exports.nudgeRule = nudgeRule;
 exports.orientationOf = orientationOf;
 exports.placementBounds = placementBounds;
 exports.resizeFactors = resizeFactors;
 exports.resizeRule = resizeRule;
+exports.resolveExtends = resolveExtends;
 exports.resolveLayoutRule = resolveLayoutRule;
+exports.schemaFieldRows = schemaFieldRows;
 exports.setRuleRotation = setRuleRotation;
 exports.sizeLever = sizeLever;
 exports.validateSceneDoc = validateSceneDoc;