@energy8platform/game-engine 0.34.2 → 0.35.0

package/dist/scene-devtools.esm.js

@@ -1,5 +1,44 @@
 import { Container, Graphics, Rectangle, Point } from 'pixi.js';
 
+// 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. */
+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 helpers behind the scene inspector — kept renderer/DOM-free so the control
 // inference and layout-field enumeration are unit-testable and reusable (the same
 // mapping later feeds schema-driven autogen and the agent's docs).
@@ -35,7 +74,9 @@ function layoutFieldSpecs(rule) {
             out.push(path === 'mode' ? { path, label, kind: 'readonly', value } : { path, label, kind: 'text', value });
         }
         else if (typeof value === 'boolean') {
-            out.push({ path, label, kind: 'text', value: String(value) });
+            // Must stay a real boolean: the engine tests rules with `=== false`
+            // (e.g. scaleWithGrid), so writing back the string "false" silently inverts behaviour.
+            out.push({ path, label, kind: 'boolean', value });
         }
         else if (Array.isArray(value)) {
             value.forEach((item, i) => visit(item, `${path}.${i}`, `${label}[${i}]`));
@@ -105,6 +146,12 @@ const STYLE$2 = `
 .e8si-json { display: block; width: calc(100% - 20px); margin: 2px 10px; min-height: 52px; font: 11px/1.4 ui-monospace, monospace; }
 .e8si-apply { margin: 4px 10px; padding: 3px 10px; background: #18213d; color: #dfe6f5; border: 1px solid #2b3866; border-radius: 6px; cursor: pointer; }
 .e8si-empty { padding: 10px; color: #7d8ab0; }
+.e8si-unset label { opacity: 0.6; font-style: italic; }
+.e8si-unset input, .e8si-unset select { opacity: 0.75; }
+.e8si-clear { flex: none; background: none; border: 0; color: #55617f; cursor: pointer; font: inherit; padding: 0 2px; }
+.e8si-clear:hover { color: #dfe6f5; }
+.e8si-thumb { flex: none; width: 30px; height: 24px; object-fit: contain; border-radius: 4px;
+  background: repeating-conic-gradient(#161d33 0% 25%, #0d1428 0% 50%) 0 / 8px 8px; }
 .e8si-badge { display: inline-block; padding: 0 6px; border: 1px solid #2b3866; border-radius: 8px; color: #9fb0d8; font-size: 10px; }
 `;
 function createSceneInspector(opts) {
@@ -271,12 +318,17 @@ function createSceneInspector(opts) {
                 }
                 else {
                     const input = document.createElement('input');
-                    input.type = spec.kind === 'number' ? 'number' : 'text';
+                    const isBool = spec.kind === 'boolean';
+                    input.type = isBool ? 'checkbox' : spec.kind === 'number' ? 'number' : 'text';
                     if (spec.step !== undefined)
                         input.step = String(spec.step);
-                    input.value = String(spec.value);
+                    if (isBool)
+                        input.checked = spec.value === true;
+                    else
+                        input.value = String(spec.value);
                     input.addEventListener('change', () => {
-                        const raw = spec.kind === 'number' ? Number(input.value) : input.value;
+                        // Booleans must round-trip as booleans — the engine compares with `=== false`.
+                        const raw = isBool ? input.checked : spec.kind === 'number' ? Number(input.value) : input.value;
                         if (spec.kind === 'number' && !Number.isFinite(raw))
                             return;
                         patchAndRefresh({
@@ -291,76 +343,225 @@ function createSceneInspector(opts) {
                 inspHost.appendChild(wrap);
             }
         }
-        // Props — base props, schema-less control inference.
+        // Props — driven by the kind's schema, so EVERY authorable field has a row (including
+        // ones not set yet) with the right control: an asset picker for textures, a node picker
+        // for references, a select for enums. Props the schema doesn't know about still show up,
+        // inferred from their value, so hand-written and plugin extras stay editable.
         const props = node.props ?? {};
-        const propKeys = Object.keys(props);
-        if (propKeys.length > 0) {
+        const schemaKey = node.type === 'prefab' ? `prefab:${String(props.prefab ?? '')}` : node.type;
+        const schema = handle.schemas()[schemaKey];
+        const rows = schemaFieldRows(schema, props);
+        const extras = extraPropKeys(schema, props).filter((k) => !(node.type === 'prefab' && k === 'prefab'));
+        if (rows.length > 0 || extras.length > 0) {
             const propsTitle = document.createElement('h3');
             propsTitle.textContent = 'Props';
             propsTitle.className = 'e8si-sec';
             inspHost.appendChild(propsTitle);
-            for (const key of propKeys) {
-                const value = props[key];
-                const kind = propControlKind(value);
-                if (kind === 'json') {
-                    const wrap = field(key);
-                    inspHost.appendChild(wrap);
-                    const area = document.createElement('textarea');
-                    area.className = 'e8si-json';
-                    area.value = JSON.stringify(value, null, 1);
-                    const apply = document.createElement('button');
-                    apply.className = 'e8si-apply';
-                    apply.textContent = `apply ${key}`;
-                    apply.addEventListener('click', () => {
-                        try {
-                            patchAndRefresh({ op: 'set-props', id, props: { [key]: JSON.parse(area.value) } });
-                        }
-                        catch {
-                            apply.textContent = `apply ${key} — invalid JSON`;
-                        }
-                    });
-                    inspHost.append(area, apply);
-                    continue;
+            /** Write a (possibly nested) prop path. set-props merges at the top level only. */
+            const writePath = (path, value) => {
+                const parts = path.split('.');
+                if (parts.length === 1) {
+                    patchAndRefresh({ op: 'set-props', id, props: { [path]: value } });
+                    return;
                 }
-                const wrap = field(key);
-                if (kind === 'boolean') {
-                    const input = document.createElement('input');
-                    input.type = 'checkbox';
-                    input.checked = value === true;
-                    input.addEventListener('change', () => patchAndRefresh({ op: 'set-props', id, props: { [key]: input.checked } }));
-                    wrap.appendChild(input);
+                const [head, ...rest] = parts;
+                const root = { ...(props[head] ?? {}) };
+                let cursor = root;
+                for (let i = 0; i < rest.length - 1; i++) {
+                    cursor[rest[i]] = { ...(cursor[rest[i]] ?? {}) };
+                    cursor = cursor[rest[i]];
                 }
-                else if (kind === 'color') {
-                    const color = document.createElement('input');
-                    color.type = 'color';
-                    color.value = String(value).slice(0, 7);
-                    const text = document.createElement('input');
-                    text.type = 'text';
-                    text.value = String(value);
-                    const push = (v) => patchAndRefresh({ op: 'set-props', id, props: { [key]: v } });
-                    color.addEventListener('input', () => {
-                        text.value = color.value;
-                        push(color.value);
-                    });
-                    text.addEventListener('change', () => push(text.value));
-                    wrap.append(color, text);
+                cursor[rest[rest.length - 1]] = value;
+                patchAndRefresh({ op: 'set-props', id, props: { [head]: root } });
+            };
+            for (const row of rows) {
+                const wrap = field(row.label);
+                const label = wrap.querySelector('label');
+                if (label && row.schema.doc)
+                    label.title = `${row.path} — ${row.schema.doc}`;
+                // An unset field shows its default, dimmed: "not set" must not read as "zero".
+                if (row.unset)
+                    wrap.classList.add('e8si-unset');
+                const shown = row.unset ? row.schema.default : row.value;
+                const control = buildControl(row.schema, shown, (v) => writePath(row.path, v));
+                wrap.append(...control);
+                if (!row.unset && row.schema.default !== undefined) {
+                    const clear = document.createElement('button');
+                    clear.className = 'e8si-clear';
+                    clear.textContent = '\u00d7';
+                    clear.title = `Reset to the default (${JSON.stringify(row.schema.default)})`;
+                    clear.addEventListener('click', () => writePath(row.path, undefined));
+                    wrap.appendChild(clear);
                 }
-                else {
-                    const input = document.createElement('input');
-                    input.type = kind === 'number' ? 'number' : 'text';
-                    input.value = String(value);
-                    input.addEventListener('change', () => {
-                        const raw = kind === 'number' ? Number(input.value) : input.value;
-                        if (kind === 'number' && !Number.isFinite(raw))
-                            return;
-                        patchAndRefresh({ op: 'set-props', id, props: { [key]: raw } });
-                    });
-                    wrap.appendChild(input);
+                inspHost.appendChild(wrap);
+            }
+            for (const key of extras)
+                renderInferred(key, props[key]);
+        }
+        /** Build the control(s) for one schema field. */
+        function buildControl(spec, value, commit) {
+            if (spec.kind === 'asset') {
+                const list = (opts.assets?.() ?? []).filter((a) => {
+                    if (spec.accept === 'audio')
+                        return a.kind === 'audio';
+                    if (spec.accept === undefined)
+                        return true;
+                    return a.kind !== 'audio'; // image / spritesheet are both textures
+                });
+                const select = document.createElement('select');
+                const blank = document.createElement('option');
+                blank.value = '';
+                blank.textContent = list.length ? '\u2014 pick asset \u2014' : '(no asset manifest)';
+                select.appendChild(blank);
+                for (const a of list) {
+                    const o = document.createElement('option');
+                    o.value = a.alias;
+                    o.textContent = a.alias;
+                    select.appendChild(o);
+                }
+                const current = value === undefined ? '' : String(value);
+                if (current && !list.some((a) => a.alias === current)) {
+                    const o = document.createElement('option');
+                    o.value = current;
+                    o.textContent = `${current} (missing)`;
+                    select.appendChild(o);
+                }
+                select.value = current;
+                select.addEventListener('change', () => commit(select.value === '' ? undefined : select.value));
+                const out = [select];
+                const hit = list.find((a) => a.alias === current);
+                if (hit && opts.assetUrl) {
+                    const img = document.createElement('img');
+                    img.className = 'e8si-thumb';
+                    img.src = opts.assetUrl(hit.path);
+                    img.alt = current;
+                    out.push(img);
+                }
+                return out;
+            }
+            if (spec.kind === 'nodeRef') {
+                const select = document.createElement('select');
+                const blank = document.createElement('option');
+                blank.value = '';
+                blank.textContent = '\u2014 pick node \u2014';
+                select.appendChild(blank);
+                const walk = (n) => {
+                    if (n.id !== id && (!spec.ofType || n.type === spec.ofType)) {
+                        const o = document.createElement('option');
+                        o.value = n.id;
+                        o.textContent = `${n.id} (${n.type})`;
+                        select.appendChild(o);
+                    }
+                    n.children.forEach(walk);
+                };
+                walk(handle.tree());
+                select.value = value === undefined ? '' : String(value);
+                select.addEventListener('change', () => commit(select.value === '' ? undefined : select.value));
+                return [select];
+            }
+            if (spec.kind === 'enum') {
+                const select = document.createElement('select');
+                for (const opt of spec.options ?? []) {
+                    const o = document.createElement('option');
+                    o.value = opt;
+                    o.textContent = opt;
+                    select.appendChild(o);
                 }
+                select.value = value === undefined ? '' : String(value);
+                select.addEventListener('change', () => commit(select.value));
+                return [select];
+            }
+            if (spec.kind === 'boolean') {
+                const input = document.createElement('input');
+                input.type = 'checkbox';
+                input.checked = value === true;
+                input.addEventListener('change', () => commit(input.checked));
+                return [input];
+            }
+            if (spec.kind === 'color') {
+                const color = document.createElement('input');
+                color.type = 'color';
+                color.value = normalizeHex(value);
+                const text = document.createElement('input');
+                text.type = 'text';
+                text.value = value === undefined ? '' : String(value);
+                color.addEventListener('input', () => {
+                    text.value = color.value;
+                    commit(color.value);
+                });
+                text.addEventListener('change', () => commit(text.value));
+                return [color, text];
+            }
+            if (spec.kind === 'json') {
+                const area = document.createElement('textarea');
+                area.className = 'e8si-json';
+                area.value = value === undefined ? '' : JSON.stringify(value, null, 1);
+                area.addEventListener('change', () => {
+                    const raw = area.value.trim();
+                    if (raw === '')
+                        return commit(undefined);
+                    try {
+                        commit(JSON.parse(raw));
+                        area.style.borderColor = '';
+                    }
+                    catch {
+                        area.style.borderColor = '#ff4d8d';
+                    }
+                });
+                return [area];
+            }
+            const input = document.createElement('input');
+            input.type = spec.kind === 'number' ? 'number' : 'text';
+            if (spec.step !== undefined)
+                input.step = String(spec.step);
+            if (spec.min !== undefined)
+                input.min = String(spec.min);
+            if (spec.max !== undefined)
+                input.max = String(spec.max);
+            input.value = value === undefined ? '' : String(value);
+            input.addEventListener('change', () => {
+                if (input.value === '')
+                    return commit(undefined);
+                const raw = spec.kind === 'number' ? Number(input.value) : input.value;
+                if (spec.kind === 'number' && !Number.isFinite(raw))
+                    return;
+                commit(raw);
+            });
+            return [input];
+        }
+        /** Fallback for props the schema doesn't describe (plugin extras, hand-written keys). */
+        function renderInferred(key, value) {
+            const kind = propControlKind(value);
+            if (kind === 'json') {
+                const wrap = field(key);
                 inspHost.appendChild(wrap);
+                const area = document.createElement('textarea');
+                area.className = 'e8si-json';
+                area.value = JSON.stringify(value, null, 1);
+                const apply = document.createElement('button');
+                apply.className = 'e8si-apply';
+                apply.textContent = `apply ${key}`;
+                apply.addEventListener('click', () => {
+                    try {
+                        patchAndRefresh({ op: 'set-props', id, props: { [key]: JSON.parse(area.value) } });
+                    }
+                    catch {
+                        apply.textContent = `apply ${key} — invalid JSON`;
+                    }
+                });
+                inspHost.append(area, apply);
+                return;
             }
+            const wrap = field(key);
+            const control = buildControl({ kind: kind === 'color' ? 'color' : kind }, value, (v) => patchAndRefresh({ op: 'set-props', id, props: { [key]: v } }));
+            wrap.append(...control);
+            inspHost.appendChild(wrap);
         }
     };
+    function normalizeHex(value) {
+        const s = typeof value === 'string' ? value : '';
+        return /^#[0-9a-f]{6}/i.test(s) ? s.slice(0, 7) : '#000000';
+    }
     const select = (id) => {
         selectedId = id;
         renderTree();
@@ -860,7 +1061,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;
@@ -872,18 +1076,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: {} };
@@ -904,6 +1103,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,
@@ -917,6 +1119,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);
@@ -932,10 +1139,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);
@@ -978,6 +1195,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));
@@ -1026,88 +1261,222 @@ function mountIdeBridge(opts) {
     const post = (msg) => window.parent?.postMessage(msg, origin);
     const emit = (event, payload) => post({ type: EVT, event, payload });
     const pushSnapshot = () => emit('snapshot', snapshot());
-    // Current authoring mode — the view the canvas shows AND the override edits target.
-    let editMode = null;
     const snapshot = () => ({
         docId: handle.doc().id,
         doc: handle.doc(),
         tree: handle.tree(),
         palette: handle.palette(),
+        // Per-kind props schemas: the editor lives in another origin and cannot reach the
+        // registry, so the authoring contract travels with the snapshot.
+        schemas: handle.schemas(),
         sceneFile: opts.sceneFile,
-        modes: handle.doc().modes ?? [],
-        mode: editMode,
         selectedId,
     });
+    // Undo bookkeeping. Every applied patch reports the patch that undoes it; the editor
+    // keeps the stack. A gizmo drag emits a patch per pointer frame, so while a gesture is in
+    // flight we keep only the FIRST inverse — undoing a drag must rewind the whole gesture,
+    // not one mouse-move.
+    let gesture = null;
+    const recordEdit = (result) => {
+        if (result.ok !== true || !result.inverse)
+            return;
+        if (gesture) {
+            gesture.inverse ??= result.inverse;
+            return;
+        }
+        emit('edit', { inverse: result.inverse });
+    };
     // Transform gizmo (resize/rotate/move on canvas) — owns the selection visuals too, so
     // no game writes selection code. Its patches round-trip a fresh snapshot to the IDE.
     const gizmo = createTransformGizmo({
         handle,
         app,
         getOrientation: opts.getOrientation,
-        getMode: () => editMode,
         designPerPixel: opts.designPerPixel,
         applyPatch: (patch) => {
-            handle.patch(patch);
+            recordEdit(handle.patch(patch));
             pushSnapshot();
         },
+        onGestureStart: () => {
+            gesture = {};
+            // Pixi dispatches to the gizmo's own graphics before our canvas listener runs; this
+            // stops a handle press from also re-picking underneath the gizmo.
+            gizmoBusy = true;
+            setTimeout(() => {
+                gizmoBusy = false;
+            }, 0);
+        },
+        onGestureEnd: () => {
+            const pending = gesture?.inverse;
+            gesture = null;
+            if (pending)
+                emit('edit', { inverse: pending });
+        },
+        // A press inside the selection box that never became a drag is a click, not a move:
+        // forward it so overlapping siblings and deeper children stay reachable.
+        onBodyClick: (x, y, alt) => pickAt(x, y, alt),
     });
     const select = (id) => {
         selectedId = id;
         gizmo.attach(id);
         emit('selected', { id });
     };
-    // Click any node on the canvas → select it (bubbles the id up to the IDE).
-    const wireHitAreas = () => {
-        const walk = (node) => {
-            if (node.id !== handle.doc().root.id) {
-                const view = handle.node(node.id);
-                if (view) {
-                    view.eventMode = 'static';
-                    view.cursor = 'pointer';
-                    const lb = view.getLocalBounds();
-                    view.hitArea = new Rectangle(lb.x, lb.y, lb.width, lb.height);
-                    view.removeAllListeners('pointerdown');
-                    view.on('pointerdown', (e) => {
-                        e.stopPropagation();
-                        select(node.id);
-                    });
-                }
+    /**
+     * Canvas picking. Every node used to carry its own `hitArea` + a stopPropagation
+     * pointerdown, which meant (a) the click rect went stale the moment anything resized,
+     * and (b) you landed on whatever node happened to be deepest with no way to go up or
+     * down. Picking is now computed at click time from live bounds, and yields the whole
+     * ancestor chain under the cursor so the user can drill.
+     */
+    const hitChain = (globalX, globalY) => {
+        const rootId = handle.doc().root.id;
+        let best = [];
+        const walk = (node, ancestors) => {
+            const view = handle.node(node.id);
+            if (!view || !view.visible || view.alpha === 0)
+                return;
+            const b = view.getBounds();
+            const inside = globalX >= b.x && globalX <= b.x + b.width && globalY >= b.y && globalY <= b.y + b.height;
+            const chain = inside && node.id !== rootId ? [...ancestors, node.id] : ancestors;
+            // Document order IS draw order (parents before children, siblings in order), so the
+            // LAST hit is the one drawn on top. Preferring the deepest instead would make a node
+            // added on top of the reels lose to the grid underneath it.
+            if (inside && chain.length > 0)
+                best = chain;
+            for (const child of node.children ?? [])
+                walk(child, chain);
+        };
+        walk(handle.doc().root, []);
+        return best; // outermost → innermost
+    };
+    /** Where the last pick happened, so clicking the same spot again drills one level in. */
+    let lastPick = null;
+    const pickAt = (globalX, globalY, deepest = false) => {
+        const chain = hitChain(globalX, globalY);
+        if (chain.length === 0) {
+            lastPick = null;
+            select(null);
+            return;
+        }
+        const sameSpot = lastPick !== null &&
+            Math.abs(lastPick.x - globalX) < 5 &&
+            Math.abs(lastPick.y - globalY) < 5 &&
+            lastPick.chain.join() === chain.join();
+        const index = deepest
+            ? chain.length - 1
+            : sameSpot
+                ? Math.min(lastPick.index + 1, chain.length - 1)
+                : 0;
+        lastPick = { x: globalX, y: globalY, chain, index };
+        select(chain[index]);
+    };
+    /** Select the parent of the current selection (Esc on the canvas, or the IDE's key). */
+    const selectParent = () => {
+        if (!selectedId)
+            return;
+        const rootId = handle.doc().root.id;
+        const findParent = (node, parent) => {
+            if (node.id === selectedId)
+                return parent;
+            for (const c of node.children ?? []) {
+                const hit = findParent(c, node);
+                if (hit)
+                    return hit;
             }
-            node.children?.forEach(walk);
+            return null;
         };
-        walk(handle.doc().root);
+        const parent = findParent(handle.doc().root, null);
+        if (parent && parent.id !== rootId) {
+            // Keep drilling consistent: stepping out moves the cursor back up the same chain.
+            if (lastPick)
+                lastPick.index = Math.max(0, lastPick.chain.indexOf(parent.id));
+            select(parent.id);
+        }
+        else {
+            lastPick = null;
+            select(null);
+        }
     };
-    app.stage.eventMode = 'static';
-    app.stage.hitArea = app.screen;
-    app.stage.on('pointerdown', () => select(null));
-    wireHitAreas();
+    // Picking listens on the CANVAS ELEMENT rather than the Pixi stage: a stage-level
+    // `pointerdown` is only delivered when the stage itself wins the hit test, which depends
+    // on event modes set elsewhere in the host — node-level handlers fired while the stage's
+    // did not. The DOM event always arrives, and converting it is one rectangle of maths.
+    const canvasEl = (app.canvas ?? app.view);
+    /** True while the gizmo is handling this press (its own handles/body take priority). */
+    let gizmoBusy = false;
+    const onCanvasDown = (e) => {
+        if (gizmoBusy)
+            return;
+        const rect = canvasEl.getBoundingClientRect();
+        if (rect.width === 0 || rect.height === 0)
+            return;
+        // CSS pixels → renderer screen units (the space Pixi bounds are reported in).
+        const x = ((e.clientX - rect.left) / rect.width) * app.screen.width;
+        const y = ((e.clientY - rect.top) / rect.height) * app.screen.height;
+        pickAt(x, y, e.altKey);
+    };
+    canvasEl.addEventListener('pointerdown', onCanvasDown);
     const afterStructural = () => {
         opts.relayout?.();
-        wireHitAreas();
     };
     // ── RPC ───────────────────────────────────────────────────────────────────────
     const methods = {
         snapshot: () => snapshot(),
         patch: (params) => {
             const patch = params;
-            handle.patch(patch);
-            if (patch.op === 'add-node' || patch.op === 'remove-node' || patch.op === 'move-node' || patch.op === 'duplicate-node') {
-                afterStructural();
-            }
-            return snapshot();
+            // A rejected patch used to warn into the game's console and still answer "ok" —
+            // throw so the editor learns why nothing changed.
+            const result = handle.patch(patch);
+            if (result && result.ok === false)
+                throw new Error(result.error);
+            // Geometry may have moved (a swapped texture resizes a sprite just as a layout edit
+            // does); picking reads live bounds, so only the host relayout hook is needed.
+            afterStructural();
+            // Broadcast too: patches can arrive from outside the editor (an agent driving the
+            // bridge directly), and those used to leave the editor mirroring a stale doc.
+            pushSnapshot();
+            // The inverse rides back with the response rather than as an event, so the caller
+            // records exactly the edits it made — no double-recording, no message ordering race.
+            return { ...snapshot(), inverse: result.ok === true ? result.inverse : undefined };
+        },
+        /** The aliases `props.src` may hold — authoritative, unlike the public/assets file scan. */
+        assetAliases: () => ({ aliases: opts.assetAliases?.() ?? null }),
+        /**
+         * Run a gizmo handle drag programmatically — the same path the mouse takes (down, move,
+         * up), so tests and agents exercise gesture coalescing rather than a single patch.
+         */
+        /** Arrow-key move of the selection, in screen px (one undo step per call). */
+        nudge: (params) => {
+            const p = params;
+            gizmo.nudge(p.dx, p.dy);
+            return { selectedId };
+        },
+        gizmoDrag: (params) => {
+            const p = params;
+            gizmo.drag(p.handle, p.from, p.to);
+            return { ok: true };
         },
         select: (params) => {
-            select(params.id);
+            const id = params.id;
+            // A selection made in the tree restarts the drill cursor for the next canvas click.
+            lastPick = null;
+            select(id);
             return { selectedId };
         },
-        // Switch the authoring mode: drives the runtime `mode` var (so visibleWhen + mode
-        // overlays render the mode's view) AND becomes the target of subsequent edits.
-        setMode: (params) => {
-            const mode = params.mode;
-            editMode = mode && mode !== 'base' ? mode : null;
-            handle.setVar('mode', editMode ?? 'base');
-            pushSnapshot();
-            return { mode: editMode };
+        /** Step out one level (Esc) — the counterpart to click-again-to-drill-in. */
+        selectParent: () => {
+            selectParent();
+            return { selectedId };
+        },
+        /**
+         * Pick at a canvas point exactly as a click does — same drill-in cursor. Exposed so
+         * tests and agents can select without synthesising pointer events (headless renderers
+         * do not deliver them), and so the chain is inspectable.
+         */
+        pick: (params) => {
+            const p = params;
+            pickAt(p.x, p.y, p.deepest === true);
+            return { selectedId, chain: hitChain(p.x, p.y) };
         },
         save: async (params) => {
             const file = params?.file ?? opts.sceneFile;
@@ -1158,7 +1527,9 @@ function mountIdeBridge(opts) {
                 file: f.file,
                 events: Object.keys(f.doc.on ?? {}),
                 cues: Object.keys(f.doc.cues ?? {}),
-                stepKinds: f.stepKinds ?? [],
+                // Prefer what the runner actually accepts, with each kind's authoring schema; the
+                // editor is cross-origin and cannot reach the registry itself.
+                stepKinds: f.runner.stepKinds?.() ?? (f.stepKinds ?? []).map((kind) => ({ kind })),
                 ctx: f.ctx ?? [],
             };
         },
@@ -1206,12 +1577,54 @@ function mountIdeBridge(opts) {
             requireFlow().runner.skip();
             return { ok: true };
         },
+        // ── stage surface (multi-scene graph) — present only if opts.stage was given ─────
+        stageMeta: () => {
+            const s = opts.stage;
+            if (!s)
+                return { enabled: false };
+            return { enabled: true, manifest: s.manifest, activeKey: s.activeKey, file: s.file, sceneParam: s.sceneParam ?? 'scene' };
+        },
+        stageSetManifest: (params) => {
+            requireStage().manifest = params;
+            return { ok: true };
+        },
+        stageSave: async () => {
+            const s = requireStage();
+            if (!s.file)
+                throw new Error('no stage file configured');
+            const res = await fetch('/__ide/write', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ file: s.file, content: s.manifest }),
+            });
+            if (!res.ok)
+                throw new Error(await res.text());
+            return { saved: s.file };
+        },
+        // Create a scene doc file (blank or a copy) so a new/duplicated scene has a real doc.
+        stageCreateScene: async (params) => {
+            const { file, from } = params;
+            const content = from ?? { version: 1, id: file, design: handle.doc().design, root: { id: 'root', type: 'container', children: [] } };
+            const res = await fetch('/__ide/write', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ file, content }),
+            });
+            if (!res.ok)
+                throw new Error(await res.text());
+            return { file };
+        },
     };
     const requireFlow = () => {
         if (!opts.flow)
             throw new Error('this game exposed no flow surface');
         return opts.flow;
     };
+    const requireStage = () => {
+        if (!opts.stage)
+            throw new Error('this game exposed no stage surface');
+        return opts.stage;
+    };
     /** Topmost sprite-like node (props.src) whose laid-out bounds contain the point. */
     const topSpriteAt = (x, y) => {
         let best = null;
@@ -1260,13 +1673,14 @@ function mountIdeBridge(opts) {
     };
     window.addEventListener('message', onMessage);
     // Announce readiness (the IDE may mount before or after the game boots).
-    emit('ready', { docId: handle.doc().id, hasFlow: !!opts.flow });
+    emit('ready', { docId: handle.doc().id, hasFlow: !!opts.flow, hasStage: !!opts.stage });
     return {
         refresh: pushSnapshot,
         select,
         gizmo,
         destroy() {
             window.removeEventListener('message', onMessage);
+            canvasEl.removeEventListener('pointerdown', onCanvasDown);
             gizmo.destroy();
         },
     };