@energy8platform/game-engine 0.34.2 → 0.35.0

package/dist/scene-devtools.d.ts

@@ -5,13 +5,17 @@ interface SceneDoc {
     version: 1;
     /** Stable document id (usually the game id). */
     id: string;
+    /**
+     * Another scene this one builds on. The resolved doc is base ⊕ this, merged by node id,
+     * so a per-mode scene carries only its delta instead of a copy of the whole board.
+     * Resolved by `resolveExtends` before the doc reaches the engine.
+     */
+    extends?: string;
     /** Design space the layout rules are authored in (viewport arrives in these units). */
     design: {
         width: number;
         height: number;
     };
-    /** Authoring modes the scene has views for (e.g. ['base','free_spins']); base is implicit. */
-    modes?: string[];
     root: SceneNode;
 }
 interface SceneNode {
@@ -31,13 +35,6 @@ interface SceneNode {
      * frame's `anticipation` / `bonus` looks. A state is an override, not a new node.
      */
     states?: Record<string, NodeOverride>;
-    /**
-     * Per-GAME-MODE override, applied automatically when the runtime `mode` var matches
-     * (base / free_spins / …). This is why base and free_spins are ONE scene, not two: a
-     * node re-poses per mode instead of being duplicated into a separate scene. Layered
-     * after orientation, before the active state.
-     */
-    modes?: Record<string, NodeOverride>;
     /** Id of another node in this doc used as this node's mask. */
     mask?: string;
     /** Filters applied to the node's view; kinds resolve through the registry (core: blur). */
@@ -157,21 +154,26 @@ interface PinLayout extends LayoutCommon {
 }
 type PinEdge = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
 type LayoutRule = AbsoluteLayout | ViewportFractionLayout | CoverLayout | FrameFractionLayout | GridCellLayout | PinLayout;
-type ScenePatch = 
-/** `mode` targets that mode's override (node.modes[mode].props); else base props. */
-{
+type ScenePatch = {
     op: 'set-props';
     id: string;
     props: Record<string, unknown>;
-    mode?: string;
 }
-/** Targets, in precedence: `mode` (node.modes[mode]) → `orientation` (responsive) → base. */
+/**
+ * Targets `orientation` (responsive) when given, else the base rule. `layout: null` clears
+ * that slot — which is how undo removes an override the edit created.
+ */
  | {
     op: 'set-layout';
     id: string;
-    layout: LayoutRule;
+    layout: LayoutRule | null;
     orientation?: Orientation;
-    mode?: string;
+}
+/** Rename the outliner label. `name` is presentation only — addressing is always by id. */
+ | {
+    op: 'set-name';
+    id: string;
+    name: string | undefined;
 } | {
     op: 'set-state';
     id: string;
@@ -203,6 +205,22 @@ type ScenePatch =
     op: 'duplicate-node';
     id: string;
 };
+/**
+ * Outcome of applying a patch. Rejections used to be console-only warnings inside the
+ * game, so an editor (or agent) saw "ok" for a patch that never applied — the reason now
+ * travels back to the caller.
+ */
+type PatchResult = {
+    ok: true;
+    /**
+     * The patch that undoes this one. Applying it restores the pre-patch state exactly,
+     * which is what the editor's undo stack replays. Absent only when the op had no effect.
+     */
+    inverse?: ScenePatch;
+} | {
+    ok: false;
+    error: string;
+};
 /** Outliner row — the tree the inspector and the agent both read. */
 interface OutlineNode {
     id: string;
@@ -214,6 +232,46 @@ interface OutlineNode {
     children: OutlineNode[];
 }
 
+type FieldKind = 'number' | 'text' | 'boolean' | 'color'
+/** One of `options`. */
+ | 'enum'
+/** A texture/audio alias from the game's asset manifest — the editor offers a picker. */
+ | 'asset'
+/** The id of another node in this doc — the editor offers the node list. */
+ | 'nodeRef'
+/** Nested record described by `fields`. */
+ | 'object'
+/** Anything else: edited as raw JSON. */
+ | 'json';
+interface FieldSchema {
+    kind: FieldKind;
+    /** Human label (defaults to the key). */
+    label?: string;
+    /** What the field does — inspector tooltip AND the agent's documentation. */
+    doc?: string;
+    /**
+     * Value the runtime uses when the field is absent. The inspector shows it as the
+     * effective value so "not set" never looks like "zero".
+     */
+    default?: unknown;
+    /** `enum`: the allowed values. */
+    options?: readonly string[];
+    /** `number`: bounds and input step. */
+    min?: number;
+    max?: number;
+    step?: number;
+    /** `asset`: which kind of media this field accepts (filters the picker). */
+    accept?: 'image' | 'audio' | 'spritesheet';
+    /** `nodeRef`: restrict the picker to nodes of this type (e.g. `reelFrame`). */
+    ofType?: string;
+    /** `object`: the nested fields. */
+    fields?: PropsSchema;
+    /** Lower sorts first in the inspector; unordered fields follow, alphabetically. */
+    order?: number;
+}
+/** A node type's (or prefab's) authorable props, keyed by prop name. */
+type PropsSchema = Record<string, FieldSchema>;
+
 interface Size {
     width: number;
     height: number;
@@ -260,11 +318,17 @@ interface SceneHandle {
     layout(width: number, height: number): void;
     setVar(name: string, value: unknown): void;
     setState(id: string, state: string | null): void;
-    patch(patch: ScenePatch): void;
+    /** Apply an edit. Returns `{ok:false, error}` when the patch was rejected. */
+    patch(patch: ScenePatch): PatchResult;
     /** The live doc (mutated by patches) — serialize this to persist the scene. */
     doc(): SceneDoc;
     /** Spawnable palette (node kinds with defaults + prefabs) — feeds the editor add-menu. */
     palette(): PaletteEntry[];
+    /**
+     * Props schemas by node kind (prefabs keyed `prefab:<name>`) — what the inspector renders
+     * its controls from, and what an agent reads as the authoring contract.
+     */
+    schemas(): Record<string, PropsSchema>;
     /**
      * Re-apply every node's doc-effective props, wiping transient presentation writes
      * (flow tweens/count-ups). "Settle = the doc" — scrub replays call this first.
@@ -273,6 +337,12 @@ interface SceneHandle {
     destroy(): void;
 }
 
+/** One entry of the game's asset manifest, as offered by the asset picker. */
+interface InspectorAsset {
+    alias: string;
+    path: string;
+    kind?: 'image' | 'audio' | string;
+}
 interface SceneInspectorOptions {
     handle: SceneHandle;
     container: HTMLElement;
@@ -286,6 +356,13 @@ interface SceneInspectorOptions {
     onCalibrate?: (id: string) => void;
     /** Hide the built-in outliner (a host — e.g. the standalone IDE — provides its own). */
     showTree?: boolean;
+    /**
+     * The game's assets, for `kind:'asset'` fields. Without it those fields stay a text box —
+     * which is exactly the dead end a fresh sprite used to hit.
+     */
+    assets?: () => InspectorAsset[];
+    /** Map an asset path to a previewable URL (the IDE prefixes the game's origin). */
+    assetUrl?: (path: string) => string;
 }
 interface SceneInspector {
     select(id: string | null): void;
@@ -302,8 +379,8 @@ interface LayoutFieldSpec {
     /** Dot-path inside the rule ('x', 'pxNudge.x', 'anchor.0', 'offset.1'). */
     path: string;
     label: string;
-    kind: 'number' | 'text' | 'readonly';
-    value: number | string;
+    kind: 'number' | 'text' | 'boolean' | 'readonly';
+    value: number | string | boolean;
     /** Input step — fractions and anchors get fine steps, px fields get 1. */
     step?: number;
 }
@@ -330,9 +407,27 @@ interface CueDef {
     jitter?: number;
     volume?: number;
 }
+/**
+ * Fields every step carries regardless of kind.
+ *
+ * `id` exists because steps used to be addressed purely by position — three different
+ * positional schemes across the codebase — so any insert or delete invalidated every
+ * sibling's path, and a trace entry could not say WHICH step it came from. It lives on the
+ * step rather than in a document-level map on purpose: the editor→game doc push copies only
+ * `on` and `cues`, so a new top-level key would be silently dropped and never saved.
+ */
+interface StepCommon {
+    /** Stable identity. Assigned by `ensureStepIds` when a hand-written doc omits it. */
+    id?: string;
+    /** Editor-only: where the node sits on the flow canvas. Absent → auto-laid-out. */
+    ui?: {
+        x: number;
+        y: number;
+    };
+}
 /** Core step vocabulary; plugins contribute additional `do` kinds through the registry. */
 type Step = TweenStep | SoundStep | SetStateStep | SetVarStep | SetPropsStep | CountUpStep | WaitStep | IfStep | ParallelStep | SeqStep | ForEachStep | CodeStep | PluginStep;
-interface TweenStep {
+interface TweenStep extends StepCommon {
     do: 'tween';
     node: string;
     /** Target numeric view properties (alpha, x, y, scale, rotation, …). */
@@ -340,28 +435,28 @@ interface TweenStep {
     ms: number;
     ease?: string;
 }
-interface SoundStep {
+interface SoundStep extends StepCommon {
     do: 'sound';
     cue: string;
     action?: 'play' | 'stop';
 }
-interface SetStateStep {
+interface SetStateStep extends StepCommon {
     do: 'setState';
     node: string;
     state: string | null;
 }
-interface SetVarStep {
+interface SetVarStep extends StepCommon {
     do: 'setVar';
     name: string;
     value: unknown;
 }
 /** Transient prop write on the live instance (presentation) — does NOT touch the doc. */
-interface SetPropsStep {
+interface SetPropsStep extends StepCommon {
     do: 'setProps';
     node: string;
     props: Record<string, unknown>;
 }
-interface CountUpStep {
+interface CountUpStep extends StepCommon {
     do: 'countUp';
     node: string;
     /** Instance prop receiving the formatted value (default 'value' — badge prefabs). */
@@ -372,24 +467,24 @@ interface CountUpStep {
     ms?: number;
     format?: 'int' | 'space';
 }
-interface WaitStep {
+interface WaitStep extends StepCommon {
     do: 'wait';
     ms?: number;
     until?: 'tap';
 }
-interface IfStep {
+interface IfStep extends StepCommon {
     do: 'if';
     /** Micro-expression over the fire() ctx: `win >= 100`, `mode === 'fs'`, or a bare truthy name. */
     when: string;
     then: Step[];
     else?: Step[];
 }
-interface ParallelStep {
+interface ParallelStep extends StepCommon {
     do: 'parallel';
     /** Independent tracks, awaited together. */
     steps: Step[][];
 }
-interface SeqStep {
+interface SeqStep extends StepCommon {
     do: 'seq';
     steps: Step[];
 }
@@ -398,7 +493,7 @@ interface SeqStep {
  * flights, per-cell transmutes, cascade histories). Nested steps see the current element
  * as `$<as>` (default `$item`) and its index as `$<as>Index`.
  */
-interface ForEachStep {
+interface ForEachStep extends StepCommon {
     do: 'forEach';
     /** '$path' into the ctx (or an inline array). */
     items: string | unknown[];
@@ -409,12 +504,13 @@ interface ForEachStep {
     steps: Step[];
 }
 /** Escape hatch: a named code choreography registered on the runner. */
-interface CodeStep {
+interface CodeStep extends StepCommon {
     do: 'code';
     ref: string;
     args?: Record<string, unknown>;
 }
-interface PluginStep {
+/** A plugin-contributed kind: open shape, but it still carries the common fields. */
+interface PluginStep extends StepCommon {
     do: string;
     [key: string]: unknown;
 }
@@ -422,6 +518,12 @@ interface TraceEntry {
     /** ms since fire() (real time, unscaled). */
     t: number;
     do: string;
+    /**
+     * Which step produced this entry. Without it the trace only says a `tween` ran — two
+     * identical tweens are indistinguishable — so a canvas cannot highlight what is running
+     * and a scrub cannot point at a step.
+     */
+    stepId?: string;
     node?: string;
     info?: string;
 }
@@ -452,6 +554,16 @@ interface FlowRunner {
     /** Host reports a user tap (releases `wait until:'tap'`). */
     tap(): void;
     events(): string[];
+    /**
+     * The step kinds this runner accepts, with their authoring metadata. The editor lives in
+     * another origin and cannot reach the registry, so the contract travels through here —
+     * before this, field lists were hardcoded in the editor (twice, and already drifting).
+     */
+    stepKinds(): Array<{
+        kind: string;
+        schema?: PropsSchema;
+        agentDoc?: string;
+    }>;
     destroy(): void;
 }
 
@@ -486,7 +598,7 @@ type HandleId = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'rotate' | '
 interface TransformGizmo {
     attach(nodeId: string | null): void;
     refresh(): void;
-    /** Run a full handle drag programmatically (keyboard/agent/tests). Screen coords. */
+    /** Run a full handle drag programmatically (agent/tests). Screen coords. */
     drag(handle: HandleId, from: {
         x: number;
         y: number;
@@ -494,6 +606,11 @@ interface TransformGizmo {
         x: number;
         y: number;
     }): void;
+    /**
+     * Move the selection by a discrete amount (arrow keys). Deliberately NOT a synthetic drag:
+     * a drag ignores travel below the click/drag threshold, which would swallow a 1px nudge.
+     */
+    nudge(dxScreen: number, dyScreen: number): void;
     destroy(): void;
 }
 
@@ -512,12 +629,38 @@ interface IdeFlowSurface {
     /** Writable path for the flow doc (idePlugin allowlist), e.g. 'src/scene/flow.json'. */
     file?: string;
     /** Step kinds available (built-ins + plugins) for the add-step menu. */
+    /** @deprecated the runner reports its own kinds WITH schemas — kept for older hosts. */
     stepKinds?: string[];
     /** ctx fields for the `$`/`when` pickers — ideally derived from the game's result schema. */
     ctx?: CtxField[];
     /** Build a ctx to fire an event with when the console has no real result (spike/dev). */
     sampleCtx?: (event: string) => Record<string, unknown>;
 }
+/** One scene in the stage graph (file-referenced; the host swaps scenes by navigation). */
+interface StageSceneRef {
+    key: string;
+    title?: string;
+    /** Scene doc file (idePlugin-writable), e.g. 'src/scene/scene.json'. */
+    file: string;
+    /** Transition into this scene, as data on the edge (host animates it at runtime). */
+    transition?: 'none' | 'fade' | 'slide-left' | 'slide-right';
+    /** Skipped on replay launches (intro idiom). */
+    skipOnReplay?: boolean;
+}
+/** The multi-scene graph the IDE Scenes panel lists and edits — data, not a live scene. */
+interface StageManifest {
+    scenes: StageSceneRef[];
+}
+/** A game's stage surface: the manifest, which scene this page shows, and how to navigate. */
+interface IdeStageSurface {
+    manifest: StageManifest;
+    /** Which scene key THIS page is currently rendering. */
+    activeKey: string;
+    /** Writable path for the manifest (idePlugin allowlist), e.g. 'src/scene/stage.json'. */
+    file?: string;
+    /** Query param the page reads to pick a scene (default 'scene' → ?scene=<key>). */
+    sceneParam?: string;
+}
 interface IdeBridgeOptions {
     handle: SceneHandle;
     /** Pixi app — the bridge draws the selection outline on its stage and drives it on the ticker. */
@@ -532,6 +675,16 @@ interface IdeBridgeOptions {
     designPerPixel?: () => number;
     /** Optional flow-IR surface — enables the IDE's Flow tab + spin console. */
     flow?: IdeFlowSurface;
+    /** Optional multi-scene stage — enables the IDE's Scenes panel. */
+    stage?: IdeStageSurface;
+    /**
+     * The game's texture aliases as `alias -> public path`. THIS is what `props.src` holds.
+     * Scanning public/assets only yields file names, and for most games those are not the
+     * aliases the game registered (paper-duel loads `back.webp` as `th_back`), so a picker
+     * built from the file scan alone would write aliases the game cannot resolve. Pass the
+     * game's own manifest and the editor offers exactly the values that will work.
+     */
+    assetAliases?: () => Record<string, string>;
     targetOrigin?: string;
 }
 interface IdeBridge {
@@ -545,4 +698,4 @@ interface IdeBridge {
 declare function mountIdeBridge(opts: IdeBridgeOptions): IdeBridge;
 
 export { createFlowEditor, createFlowTimeline, createSceneInspector, layoutFieldSpecs, mountIdeBridge, propControlKind, setRulePath };
-export type { CtxField, FlowEditor, FlowEditorOptions, FlowTimeline, FlowTimelineOptions, IdeBridge, IdeBridgeOptions, IdeFlowSurface, LayoutFieldSpec, PropControlKind, SceneInspector, SceneInspectorOptions };
+export type { CtxField, FlowEditor, FlowEditorOptions, FlowTimeline, FlowTimelineOptions, IdeBridge, IdeBridgeOptions, IdeFlowSurface, IdeStageSurface, LayoutFieldSpec, PropControlKind, SceneInspector, SceneInspectorOptions, StageManifest, StageSceneRef };