@energy8platform/game-engine 0.34.2 → 0.35.0

package/dist/scene.d.ts

@@ -6,13 +6,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 {
@@ -32,13 +36,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). */
@@ -158,21 +155,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;
@@ -204,6 +206,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;
@@ -215,6 +233,91 @@ interface OutlineNode {
     children: OutlineNode[];
 }
 
+/** A node in an extending doc may delete an inherited node instead of overriding it. */
+declare const REMOVE_MARKER = "$remove";
+interface ExtendOptions {
+    /** Resolve a parent reference (a path, an id — whatever the host uses) to its doc. */
+    load: (ref: string) => SceneDoc | undefined;
+    /** Guards against a cycle; also the practical depth limit for a chain of modes. */
+    maxDepth?: number;
+}
+/**
+ * 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.
+ */
+declare function resolveExtends(doc: SceneDoc, opts: ExtendOptions): SceneDoc;
+/**
+ * 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.
+ */
+declare function diffDocs(from: SceneDoc, to: SceneDoc): ScenePatch[];
+
+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>;
+/** Shared field definitions, so every kind describes `alpha` the same way. */
+declare const ALPHA_FIELD: FieldSchema;
+/** Fractions of a texture (0..1), used for both `region` (crop) and `inner` (frame hollow). */
+declare const fracBoxFields: (doc: string) => FieldSchema;
+/**
+ * Flatten a schema into dot-path rows, pairing each with the value currently in `props`
+ * (`undefined` when unset). Nested `object` fields expand to `parent.child`, matching how
+ * layout rules are already flattened for the inspector.
+ */
+interface SchemaFieldRow {
+    /** Dot-path into props ('src', 'sheet.alias'). */
+    path: string;
+    label: string;
+    schema: FieldSchema;
+    /** Current value, or `undefined` when the prop is not set. */
+    value: unknown;
+    /** True when the value comes from the schema default rather than the doc. */
+    unset: boolean;
+}
+declare function schemaFieldRows(schema: PropsSchema | undefined, props: Record<string, unknown>): SchemaFieldRow[];
+/** Props present on the node that the schema doesn't describe (plugin extras, hand-written). */
+declare function extraPropKeys(schema: PropsSchema | undefined, props: Record<string, unknown>): string[];
+
 interface Rect {
     x: number;
     y: number;
@@ -263,7 +366,7 @@ type LayoutResolution = {
 };
 declare function orientationOf(width: number, height: number, portraitFactor?: number): Orientation;
 /** Base node + orientation override + active state override (state wins), for one frame. */
-declare function effectiveNode(node: SceneNode, orientation: Orientation, state: string | null, mode?: string | null): {
+declare function effectiveNode(node: SceneNode, orientation: Orientation, state: string | null): {
     layout?: LayoutRule;
     props: Record<string, unknown>;
     visible: boolean;
@@ -351,8 +454,8 @@ interface NodeDefaults {
 }
 interface NodeTypeContribution {
     kind: string;
-    /** JSON-Schema-ish description of `props` — validation, inspector autogen, agent docs. */
-    schema?: Record<string, unknown>;
+    /** Authorable `props` — drives the inspector's controls, validation and the agent's docs. */
+    schema?: PropsSchema;
     /** 3–10 lines for the agent: when to use this kind, patterns, anti-patterns. */
     agentDoc?: string;
     /** Palette skeleton — omit to hide the kind from the add-menu (e.g. `prefab` dispatch). */
@@ -362,7 +465,7 @@ interface NodeTypeContribution {
 /** Reusable game component (meters, HUDs) addressed as `{type:'prefab', props:{prefab:'name'}}`. */
 interface PrefabContribution {
     name: string;
-    schema?: Record<string, unknown>;
+    schema?: PropsSchema;
     agentDoc?: string;
     /** Palette skeleton (props merged onto `{prefab:name}`, plus a starter layout). */
     defaults?: NodeDefaults;
@@ -371,7 +474,7 @@ interface PrefabContribution {
 /** A filter kind: `{kind:'blur', strength: 3}` in a node's `filters` resolves through this. */
 interface FilterKindContribution {
     kind: string;
-    schema?: Record<string, unknown>;
+    schema?: PropsSchema;
     agentDoc?: string;
     create(spec: FilterSpec): Filter;
 }
@@ -435,11 +538,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.
@@ -514,15 +623,26 @@ interface TransformGizmoOptions {
     app: Application;
     applyPatch?: (patch: ScenePatch) => void;
     getOrientation?: () => Orientation;
-    /** Current authoring mode; when set and not 'base', edits target that mode's override. */
-    getMode?: () => string | null;
     /** Override screen→design conversion for move drags. Default: the node's parent world scale. */
     designPerPixel?: (nodeId: string) => number;
+    /**
+     * Gesture boundaries. A drag emits a patch per pointer frame, so undo needs to know that
+     * the whole gesture is ONE edit — otherwise ⌘Z rewinds a drag one mouse-move at a time.
+     */
+    onGestureStart?: () => void;
+    onGestureEnd?: () => void;
+    /**
+     * A press inside the selection box that never moved. The body covers the whole selected
+     * node so it can be dragged, which also made it swallow every click there — overlapping
+     * siblings and deeper children became unreachable once anything was selected. The host
+     * re-picks at this point instead.
+     */
+    onBodyClick?: (globalX: number, globalY: number, altKey: boolean) => void;
 }
 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;
@@ -530,6 +650,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;
 }
 declare function createTransformGizmo(opts: TransformGizmoOptions): TransformGizmo;
@@ -748,9 +873,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, …). */
@@ -758,28 +901,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). */
@@ -790,24 +933,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[];
 }
@@ -816,7 +959,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[];
@@ -827,12 +970,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;
 }
@@ -840,6 +984,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;
 }
@@ -893,6 +1043,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;
 }
 /** Per-run runtime handed to step executors (core and plugin alike). */
@@ -926,7 +1086,8 @@ interface FlowRuntime {
 
 interface FlowStepContribution {
     kind: string;
-    schema?: Record<string, unknown>;
+    /** Authorable fields — drives the editor's controls and documents the step for an agent. */
+    schema?: PropsSchema;
     /** 3–10 lines for the agent: when to use the step, patterns, anti-patterns. */
     agentDoc?: string;
     run(step: Step, rt: FlowRuntime): Promise<void> | void;
@@ -943,6 +1104,13 @@ interface StageDoc {
         key: string;
         scene: SceneDoc;
         flow?: FlowDoc;
+        /**
+         * The game mode this scene is the view for (`free_spins`, `bonus`, …). Such a scene is
+         * NOT a separate host scene: it is folded into the scene it extends and applied as a
+         * diff when the mode starts, so the board is not rebuilt. Omit for real screens (intro,
+         * an adventure map) — those stay their own host scene.
+         */
+        mode?: string;
         /** Host skips this scene on replay launches (intro idiom). */
         skipOnReplay?: boolean;
         /** A tap anywhere advances to this scene key (intro → game). */
@@ -957,6 +1125,14 @@ declare function buildDocScenes<T extends SlotSpinResultBase = SlotSpinResultBas
 }>;
 interface DocSceneOptions<T extends SlotSpinResultBase = SlotSpinResultBase> {
     scene: SceneDoc;
+    /**
+     * A scene doc per game mode (`free_spins`, `bonus`, …) — each authored as its own file,
+     * usually `extends`-ing this one so it carries only its delta. Entering a mode applies
+     * the DIFF to the live scene: shared nodes are never touched, so the reel system, its
+     * symbols and any running animation survive the transition. (No game in the surveyed set
+     * rebuilds its board on mode entry, and rebuilding mid-spin would be visible.)
+     */
+    modeScenes?: Record<string, SceneDoc>;
     flow?: FlowDoc;
     /** A tap anywhere advances to this scene key (uses the host-injected goto). */
     advanceOnTap?: string;
@@ -995,14 +1171,25 @@ declare class DocScene<T extends SlotSpinResultBase = SlotSpinResultBase> extend
     private ctxOf;
     onCreate(api: SceneApi): void;
     onSpinStart(): void;
+    /** The resolved doc currently on screen, so a mode switch diffs from the right baseline. */
+    private activeDoc_;
+    private activeDocId_;
     onSpin(result: T, ctx: RenderContext): Promise<void>;
     onEnterMode(result: T, ctx: RenderContext): Promise<void>;
     onExitMode(result: T, ctx: RenderContext): Promise<void>;
+    /**
+     * 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.
+     */
+    private applySceneFor;
+    /** Fold a doc's `extends` chain, looking parents up among the scenes this game declared. */
+    private resolveDoc;
     onSpinEnd(result: T, ctx: RenderContext): void;
     onSkip(): void;
     onTurboChanged(level: number): void;
 }
 declare function createDocScene<T extends SlotSpinResultBase = SlotSpinResultBase>(opts: DocSceneOptions<T>): DocScene<T>;
 
-export { BUILTIN_FILTER_KINDS, BUILTIN_NODE_TYPES, DocScene, buildDocScenes, createDocScene, createInnerCalibrator, createSceneFromDoc, createSceneRegistry, createTransformGizmo, dependencyOf, dragInnerEdge, edgePoint, effectiveNode, evalVisibleWhen, handlePoint, nudgeRule, orientationOf, placementBounds, resizeFactors, resizeRule, resolveLayoutRule, setRuleRotation, sizeLever, validateSceneDoc };
-export type { AbsoluteLayout, Box, CoverLayout, CreateSceneOptions, DocSceneOptions, FilterKindContribution, FilterSpec, FrameFractionLayout, GridCellLayout, HandleId, InnerCalibrator, InnerCalibratorOptions, InnerEdge, InnerFracs, LayoutContext, LayoutResolution, LayoutRule, NodeCreateContext, NodeDefaults, NodeInstance, NodeOverride, NodeTypeContribution, Orientation, OutlineNode, PaletteEntry, PinEdge, PinLayout, Placement, PrefabContribution, Rect, SceneDoc, SceneHandle, SceneNode, ScenePatch, ScenePlugin, SceneRegistry, SceneValidationError, Size, StageDoc, TransformGizmo, TransformGizmoOptions, ViewportFractionLayout };
+export { ALPHA_FIELD, BUILTIN_FILTER_KINDS, BUILTIN_NODE_TYPES, DocScene, REMOVE_MARKER, buildDocScenes, createDocScene, createInnerCalibrator, createSceneFromDoc, createSceneRegistry, createTransformGizmo, dependencyOf, diffDocs, dragInnerEdge, edgePoint, effectiveNode, evalVisibleWhen, extraPropKeys, fracBoxFields, handlePoint, nudgeRule, orientationOf, placementBounds, resizeFactors, resizeRule, resolveExtends, resolveLayoutRule, schemaFieldRows, setRuleRotation, sizeLever, validateSceneDoc };
+export type { AbsoluteLayout, Box, CoverLayout, CreateSceneOptions, DocSceneOptions, ExtendOptions, FieldKind, FieldSchema, FilterKindContribution, FilterSpec, FrameFractionLayout, GridCellLayout, HandleId, InnerCalibrator, InnerCalibratorOptions, InnerEdge, InnerFracs, LayoutContext, LayoutResolution, LayoutRule, NodeCreateContext, NodeDefaults, NodeInstance, NodeOverride, NodeTypeContribution, Orientation, OutlineNode, PaletteEntry, PatchResult, PinEdge, PinLayout, Placement, PrefabContribution, PropsSchema, Rect, SceneDoc, SceneHandle, SceneNode, ScenePatch, ScenePlugin, SceneRegistry, SceneValidationError, SchemaFieldRow, Size, StageDoc, TransformGizmo, TransformGizmoOptions, ViewportFractionLayout };