@energy8platform/game-engine 0.33.6 → 0.33.8

package/dist/scene.d.ts

@@ -1,4 +1,5 @@
-import { Container, Texture } from 'pixi.js';
+import { Container, Filter, Texture, Application } from 'pixi.js';
+import { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
 
 type Orientation = 'landscape' | 'portrait';
 interface SceneDoc {
@@ -31,6 +32,8 @@ interface SceneNode {
     states?: 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). */
+    filters?: FilterSpec[];
     /**
      * Tiny condition over runtime vars, e.g. `"mode === 'free_spins'"`. Supported form:
      * `<var> <op> <literal>` with `=== !== >= <= > <`. Anything richer belongs in flow/code.
@@ -41,6 +44,11 @@ interface SceneNode {
     /** Order = z-order. */
     children?: SceneNode[];
 }
+/** A filter instance: kind + kind-specific params (validated by the contribution). */
+interface FilterSpec {
+    kind: string;
+    [param: string]: unknown;
+}
 /** Partial node applied on top of the base for an orientation or a named state. */
 interface NodeOverride {
     layout?: LayoutRule;
@@ -57,6 +65,13 @@ interface LayoutCommon {
     };
     /** Static rotation in radians (choreographed rotation belongs to flow/animation). */
     rotation?: number;
+    /**
+     * `'viewport'` resolves this rule against the LIVE viewport even when the node lives
+     * inside a nested coordinate space — the engine converts the result into the space's
+     * coordinates. The paper-duel logo idiom: screen-pinned, but rendered at a diorama
+     * z-depth.
+     */
+    space?: 'viewport';
 }
 /** Fixed design-space coordinates. */
 interface AbsoluteLayout extends LayoutCommon {
@@ -153,6 +168,28 @@ type ScenePatch = {
     op: 'set-var';
     name: string;
     value: unknown;
+}
+/** Insert `node` under `parent` at `index` (default: append). Ids must be unused. */
+ | {
+    op: 'add-node';
+    parent: string;
+    node: SceneNode;
+    index?: number;
+} | {
+    op: 'remove-node';
+    id: string;
+}
+/** Reparent/reorder `id` under `parent` at `index` (same parent = pure reorder). */
+ | {
+    op: 'move-node';
+    id: string;
+    parent: string;
+    index?: number;
+}
+/** Deep-copy `id` (all descendant ids suffixed to stay unique) as its next sibling. */
+ | {
+    op: 'duplicate-node';
+    id: string;
 };
 /** Outliner row — the tree the inspector and the agent both read. */
 interface OutlineNode {
@@ -252,6 +289,23 @@ interface SymbolView extends Container {
 /** Game-supplied factory: build the view for a symbol id (sprite / layered sprites / Spine / composite). */
 type SymbolResolver = (symbolId: string) => SymbolView | null;
 
+interface IScene {
+    /** Root display container for this scene */
+    readonly container: Container;
+    /** @internal GameApplication reference — set by SceneManager */
+    __engineApp?: any;
+    /** Called when the scene is entered */
+    onEnter?(data?: unknown): Promise<void> | void;
+    /** Called when the scene is exited */
+    onExit?(): Promise<void> | void;
+    /** Called every frame */
+    onUpdate?(dt: number): void;
+    /** Called when viewport resizes */
+    onResize?(width: number, height: number): void;
+    /** Called when the scene is destroyed */
+    onDestroy?(): void;
+}
+
 interface NodeCreateContext {
     registry: SceneRegistry;
     /** Resolve a texture alias (defaults to Pixi `Texture.from`; tests/labs inject). */
@@ -274,12 +328,22 @@ interface NodeInstance {
     };
     destroy?(): void;
 }
+/** Skeleton a palette/agent uses to spawn a fresh node of this kind (id is assigned by the caller). */
+interface NodeDefaults {
+    /** Human label for the palette button (defaults to the kind). */
+    label?: string;
+    name?: string;
+    props?: Record<string, unknown>;
+    layout?: SceneNode['layout'];
+}
 interface NodeTypeContribution {
     kind: string;
     /** JSON-Schema-ish description of `props` — validation, inspector autogen, agent docs. */
     schema?: Record<string, unknown>;
     /** 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). */
+    defaults?: NodeDefaults;
     create(node: SceneNode, ctx: NodeCreateContext): NodeInstance;
 }
 /** Reusable game component (meters, HUDs) addressed as `{type:'prefab', props:{prefab:'name'}}`. */
@@ -287,22 +351,47 @@ interface PrefabContribution {
     name: string;
     schema?: Record<string, unknown>;
     agentDoc?: string;
+    /** Palette skeleton (props merged onto `{prefab:name}`, plus a starter layout). */
+    defaults?: NodeDefaults;
     create(props: Record<string, unknown>, ctx: NodeCreateContext): NodeInstance;
 }
+/** A filter kind: `{kind:'blur', strength: 3}` in a node's `filters` resolves through this. */
+interface FilterKindContribution {
+    kind: string;
+    schema?: Record<string, unknown>;
+    agentDoc?: string;
+    create(spec: FilterSpec): Filter;
+}
 interface ScenePlugin {
     id: string;
     nodeTypes?: NodeTypeContribution[];
     prefabs?: PrefabContribution[];
+    filterKinds?: FilterKindContribution[];
+}
+/** One palette entry — a spawnable node kind or prefab, with its skeleton. */
+interface PaletteEntry {
+    kind: string;
+    label: string;
+    /** 'prefab' entries spawn `{type:'prefab', props:{prefab:kind}}`; others spawn `{type:kind}`. */
+    isPrefab: boolean;
+    agentDoc?: string;
+    defaults: NodeDefaults;
 }
 interface SceneRegistry {
     nodeType(kind: string): NodeTypeContribution | undefined;
     prefab(name: string): PrefabContribution | undefined;
+    filterKind(kind: string): FilterKindContribution | undefined;
     kinds(): string[];
     prefabNames(): string[];
+    filterKindNames(): string[];
+    /** Spawnable palette: node kinds with `defaults` + all registered prefabs. */
+    palette(): PaletteEntry[];
 }
 /** Merge built-ins with plugin contributions; later plugins may override earlier kinds. */
-declare function createSceneRegistry(plugins?: ScenePlugin[], builtins?: NodeTypeContribution[]): SceneRegistry;
+declare function createSceneRegistry(plugins?: ScenePlugin[], builtins?: NodeTypeContribution[], builtinFilters?: FilterKindContribution[]): SceneRegistry;
 
+/** Core filter kinds; heavier looks (bloom etc.) arrive as plugins carrying their deps. */
+declare const BUILTIN_FILTER_KINDS: FilterKindContribution[];
 declare const BUILTIN_NODE_TYPES: NodeTypeContribution[];
 
 interface SceneValidationError {
@@ -336,9 +425,524 @@ interface SceneHandle {
     patch(patch: ScenePatch): void;
     /** 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[];
+    /**
+     * Re-apply every node's doc-effective props, wiping transient presentation writes
+     * (flow tweens/count-ups). "Settle = the doc" — scrub replays call this first.
+     */
+    resetProps(): void;
     destroy(): void;
 }
 declare function createSceneFromDoc(doc: SceneDoc, opts?: CreateSceneOptions): SceneHandle;
 
-export { BUILTIN_NODE_TYPES, createSceneFromDoc, createSceneRegistry, dependencyOf, edgePoint, effectiveNode, evalVisibleWhen, orientationOf, placementBounds, resolveLayoutRule, validateSceneDoc };
-export type { AbsoluteLayout, CoverLayout, CreateSceneOptions, FrameFractionLayout, GridCellLayout, LayoutContext, LayoutResolution, LayoutRule, NodeCreateContext, NodeInstance, NodeOverride, NodeTypeContribution, Orientation, OutlineNode, PinEdge, PinLayout, Placement, PrefabContribution, Rect, SceneDoc, SceneHandle, SceneNode, ScenePatch, ScenePlugin, SceneRegistry, SceneValidationError, Size, ViewportFractionLayout };
+interface InnerFracs {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+type InnerEdge = 'left' | 'right' | 'top' | 'bottom';
+/** Pure edge-drag math: `frac` is the pointer position normalized to the frame rect axis. */
+declare function dragInnerEdge(inner: InnerFracs, edge: InnerEdge, frac: number): InnerFracs;
+interface InnerCalibratorOptions {
+    handle: SceneHandle;
+    /** The node whose props.inner is being calibrated (reelFrame or any inner-declaring node). */
+    nodeId: string;
+    /** Patch route (host may add logging/saving); defaults to handle.patch. */
+    applyPatch?: (patch: ScenePatch) => void;
+    onChange?: (inner: InnerFracs) => void;
+}
+interface InnerCalibrator {
+    /** Add to the stage ABOVE the scene view (canvas coordinates). */
+    view: Container;
+    /** Redraw from current bounds/props (call after resize or external patches). */
+    refresh(): void;
+    destroy(): void;
+}
+declare function createInnerCalibrator(opts: InnerCalibratorOptions): InnerCalibrator;
+
+/** Which size lever a rule exposes — decides how a resize drag is interpreted. */
+declare function sizeLever(rule: LayoutRule): 'wh-frac' | 'wh-box' | 'scale' | 'none';
+/**
+ * Multiply a rule's size lever by (factorX, factorY). Corners pass equal factors (uniform);
+ * edges pass 1 on the untouched axis. Uniform levers (`scale`) use factorX.
+ */
+declare function resizeRule(rule: LayoutRule, factorX: number, factorY: number): LayoutRule;
+declare function setRuleRotation(rule: LayoutRule, radians: number): LayoutRule;
+/** Nudge a rule's final pixel offset by a screen delta already converted to design units. */
+declare function nudgeRule(rule: LayoutRule, dxDesign: number, dyDesign: number): LayoutRule;
+type HandleId = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'rotate' | 'body';
+interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Screen position of each handle for a bounding box. */
+declare function handlePoint(box: Box, id: Exclude<HandleId, 'body'>): {
+    x: number;
+    y: number;
+};
+/**
+ * Resize factors from dragging a handle, using the OPPOSITE edge/corner as the fixed
+ * reference — the intuitive "grab a corner, drag out, it grows" feel.
+ */
+declare function resizeFactors(startBox: Box, handle: HandleId, pointer: {
+    x: number;
+    y: number;
+}): {
+    factorX: number;
+    factorY: number;
+};
+
+interface TransformGizmoOptions {
+    handle: SceneHandle;
+    app: Application;
+    applyPatch?: (patch: ScenePatch) => void;
+    getOrientation?: () => Orientation;
+    /** Override screen→design conversion for move drags. Default: the node's parent world scale. */
+    designPerPixel?: (nodeId: string) => number;
+}
+interface TransformGizmo {
+    attach(nodeId: string | null): void;
+    refresh(): void;
+    /** Run a full handle drag programmatically (keyboard/agent/tests). Screen coords. */
+    drag(handle: HandleId, from: {
+        x: number;
+        y: number;
+    }, to: {
+        x: number;
+        y: number;
+    }): void;
+    destroy(): void;
+}
+declare function createTransformGizmo(opts: TransformGizmoOptions): TransformGizmo;
+
+/**
+ * Base class for all scenes.
+ * Provides a root PixiJS Container and lifecycle hooks.
+ *
+ * @example
+ * ```ts
+ * class MenuScene extends Scene {
+ *   async onEnter() {
+ *     const bg = Sprite.from('menu-bg');
+ *     this.container.addChild(bg);
+ *   }
+ *
+ *   onUpdate(dt: number) {
+ *     // per-frame logic
+ *   }
+ *
+ *   onResize(width: number, height: number) {
+ *     // reposition UI
+ *   }
+ * }
+ * ```
+ */
+declare abstract class Scene implements IScene {
+    readonly container: Container;
+    constructor();
+    /** Called when this scene becomes active. Override in subclass. */
+    onEnter?(data?: unknown): Promise<void> | void;
+    /** Called when this scene is deactivated. Override in subclass. */
+    onExit?(): Promise<void> | void;
+    /** Called every frame with delta time (in seconds). Override in subclass. */
+    onUpdate?(dt: number): void;
+    /** Called when the viewport resizes. Override in subclass. */
+    onResize?(width: number, height: number): void;
+    /** Cleanup — called when the scene is permanently removed. */
+    onDestroy?(): void;
+}
+
+/** Everything a scene needs to render one segment. The host builds it per segment. */
+interface RenderContext {
+    /** Bet for this round (major units). Stable for the whole round. */
+    bet: number;
+    /** Trigger action in the game's own vocabulary ('spin' | 'ante' | 'buy_bonus' | …). */
+    action: string;
+    /** Stake bet-mode of the round ('BASE' | 'ANTE' | 'BONUS' | …). */
+    mode: string;
+    /** Currency-aware money formatter. */
+    formatAmount(value: number): string;
+    /** LIVE turbo level (0 = off, 1..3 = escalating speed). Read at access. */
+    readonly turbo: number;
+    /** Only meaningful in `onEnterMode`: true when RETURNING to a suspended parent bonus after a
+     *  nested sub-bonus finished (e.g. back to free spins after an adventure), false on a fresh
+     *  entry. Lets a scene restore vs rebuild. Undefined outside `onEnterMode`. */
+    resumed?: boolean;
+    /** Aborted when the player skips this segment (double-tap). The scene's async pacing can race or
+     *  cancel on it; on abort the scene must collapse to the segment's final visual state. */
+    signal: AbortSignal;
+}
+/** Playback-only audio handle. Volume/mute are shell settings → host, never the scene. */
+interface SceneAudio {
+    play(alias: string, opts?: {
+        volume?: number;
+        loop?: boolean;
+        speed?: number;
+    }): void;
+    playMusic(alias: string, fadeMs?: number): void;
+    stopMusic(): void;
+    duck(factor: number): void;
+    unduck(): void;
+}
+interface OverlayShowOptions {
+    /** Draw the overlay content into `container` (sized to the canvas). */
+    build(container: Container, size: {
+        width: number;
+        height: number;
+    }): void;
+    /** Re-layout the same `container` when the canvas resizes while the overlay is open.
+     *  Receives the content container from `build` and the new size. Optional — omit for
+     *  overlays that self-center or don't care about resize. */
+    onResize?(container: Container, size: {
+        width: number;
+        height: number;
+    }): void;
+    /** Auto-close after N ms (combine with closeOn — whichever fires first). */
+    autoCloseMs?: number;
+    /** Dismiss on a single tap. Default 'tap'. Set false to require an explicit close(). */
+    closeOn?: 'tap' | false;
+    /** Optional host-drawn backdrop alpha (0..1). Default: none (game draws its own). */
+    dim?: number;
+}
+/** Single host-owned layer above scene + shell. Eats pointer events so shell controls are
+ *  unreachable while open. */
+interface SceneOverlay {
+    /** Resolves when the overlay closes. Rejects if one is already open. */
+    show(opts: OverlayShowOptions): Promise<void>;
+    close(): void;
+}
+interface SceneShell {
+    /** Live insets (px). `bottom` = the shell bar height; read inside onResize. */
+    readonly safeArea: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+interface AutoplaySceneState {
+    running: boolean;
+    remaining: number;
+}
+/** Stable capabilities injected once via onCreate. */
+interface SceneApi {
+    audio: SceneAudio;
+    overlay: SceneOverlay;
+    shell: SceneShell;
+    formatAmount(value: number): string;
+    readonly bet: number;
+    readonly mode: string;
+    readonly turbo: number;
+}
+/** The contract a slot scene implements. The HOST owns the play→present→ack→drain loop and the
+ *  shell; the scene only renders + reacts. The core spin-lifecycle hooks are REQUIRED (implement
+ *  them — empty bodies are fine where a game has nothing to do); the incidental reactions below
+ *  stay optional. */
+interface SlotSceneController<T extends SlotSpinResultBase = SlotSpinResultBase> {
+    /** Injected ONCE before the first round — capabilities, subscriptions, one-time setup. */
+    onCreate(api: SceneApi): void;
+    /** Fires once per round when the player presses spin (before the network result). */
+    onSpinStart(): void;
+    /** Render ONE segment (a spin or one free spin). Await your own pacing. */
+    onSpin(result: T, ctx: RenderContext): Promise<void>;
+    /** Fires when a bonus LEVEL begins. With nested bonuses this fires once per level (free spins,
+     *  then adventure, …) — check `ctx.mode` for which. `ctx.resumed` is true when returning to a
+     *  suspended parent after a nested sub-bonus finished, so a scene can restore instead of rebuild.
+     *  A single-bonus round fires it exactly once (as before). */
+    onEnterMode(result: T, ctx: RenderContext): Promise<void>;
+    /** Fires when a bonus LEVEL ends — popping a nested sub-bonus back to its parent, or unwinding
+     *  the last level back to BASE. `ctx.mode` is the level being left. Fires once per level. */
+    onExitMode(result: T, ctx: RenderContext): Promise<void>;
+    /** Fires once per round after the full drain (controls unlocked). */
+    onSpinEnd(result: T, ctx: RenderContext): void;
+    /** Shell events (may fire while idle) — optional. */
+    onBetChanged?(bet: number): void;
+    onTurboChanged?(level: number): void;
+    onAutoplayChanged?(state: AutoplaySceneState): void;
+    /** Double-tap skip during an active onSpin (gated by the skipGesture setting). */
+    onSkip?(): void;
+    /** Tab focus lost / regained. */
+    onPause?(): void;
+    onResume?(): void;
+}
+
+interface FlowDoc {
+    version: 1;
+    id: string;
+    /** Sound cue registry: alias → definition. Steps refer to cues, never to files. */
+    cues?: Record<string, CueDef>;
+    /** Event name (host lifecycle: spinStart/reelStop/result/enterMode/…) → steps. */
+    on: Record<string, Step[]>;
+}
+interface CueDef {
+    /** One source alias, or several — with `rotate` the runner cycles them (anti-repetition). */
+    src: string | string[];
+    channel?: 'music' | 'sfx';
+    loop?: boolean;
+    rotate?: boolean;
+    /** ± random playback-rate jitter (0.06 = ±6%). */
+    jitter?: number;
+    volume?: 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 {
+    do: 'tween';
+    node: string;
+    /** Target numeric view properties (alpha, x, y, scale, rotation, …). */
+    to: Record<string, number>;
+    ms: number;
+    ease?: string;
+}
+interface SoundStep {
+    do: 'sound';
+    cue: string;
+    action?: 'play' | 'stop';
+}
+interface SetStateStep {
+    do: 'setState';
+    node: string;
+    state: string | null;
+}
+interface SetVarStep {
+    do: 'setVar';
+    name: string;
+    value: unknown;
+}
+/** Transient prop write on the live instance (presentation) — does NOT touch the doc. */
+interface SetPropsStep {
+    do: 'setProps';
+    node: string;
+    props: Record<string, unknown>;
+}
+interface CountUpStep {
+    do: 'countUp';
+    node: string;
+    /** Instance prop receiving the formatted value (default 'value' — badge prefabs). */
+    prop?: string;
+    from?: number | string;
+    /** Number or a '$path' reference into the fire() ctx (e.g. '$win'). */
+    to: number | string;
+    ms?: number;
+    format?: 'int' | 'space';
+}
+interface WaitStep {
+    do: 'wait';
+    ms?: number;
+    until?: 'tap';
+}
+interface IfStep {
+    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 {
+    do: 'parallel';
+    /** Independent tracks, awaited together. */
+    steps: Step[][];
+}
+interface SeqStep {
+    do: 'seq';
+    steps: Step[];
+}
+/**
+ * Iterate a ctx collection — THE dynamic fan-out every studied game needs (staggered jar
+ * flights, per-cell transmutes, cascade histories). Nested steps see the current element
+ * as `$<as>` (default `$item`) and its index as `$<as>Index`.
+ */
+interface ForEachStep {
+    do: 'forEach';
+    /** '$path' into the ctx (or an inline array). */
+    items: string | unknown[];
+    as?: string;
+    mode?: 'sequential' | 'parallel';
+    /** Per-item delay: parallel start stagger / sequential inter-item gap (turbo-scaled). */
+    staggerMs?: number;
+    steps: Step[];
+}
+/** Escape hatch: a named code choreography registered on the runner. */
+interface CodeStep {
+    do: 'code';
+    ref: string;
+    args?: Record<string, unknown>;
+}
+interface PluginStep {
+    do: string;
+    [key: string]: unknown;
+}
+interface TraceEntry {
+    /** ms since fire() (real time, unscaled). */
+    t: number;
+    do: string;
+    node?: string;
+    info?: string;
+}
+interface FlowTrace {
+    event: string;
+    turbo: number;
+    skipped: boolean;
+    /** Set on scrub replays: the run executed instantly and halted after this entry index. */
+    haltedAtEntry?: number;
+    durationMs: number;
+    entries: TraceEntry[];
+}
+
+/** What the audio adapter receives — cue already resolved (rotation/jitter applied). */
+interface ResolvedCue {
+    cue: string;
+    src: string;
+    channel: 'music' | 'sfx';
+    loop: boolean;
+    rate: number;
+    volume: number;
+}
+interface FlowAudioAdapter {
+    play(cue: ResolvedCue): void;
+    stop(cueName: string): void;
+}
+interface CreateFlowRunnerOptions {
+    scene: SceneHandle;
+    audio?: FlowAudioAdapter;
+    plugins?: FlowPlugin[];
+    /** Named code choreographies for `{do:'code', ref}` escape hatches. */
+    code?: Record<string, (rt: FlowRuntime, args: Record<string, unknown>) => Promise<void> | void>;
+    /** Live trace feed (the log/timeline view); the full trace is also returned by fire(). */
+    onTrace?: (event: string, entry: TraceEntry) => void;
+    log?: (msg: string) => void;
+}
+interface FireOptions {
+    /** Scrub replay: run instantly (no waits, anims jump, audio muted) and halt after entry N. */
+    replay?: {
+        untilEntry?: number;
+    };
+}
+interface FlowRunner {
+    fire(event: string, ctx?: Record<string, unknown>, opts?: FireOptions): Promise<FlowTrace>;
+    /** Scrub: re-fire `event` with its LAST ctx, instantly, halting after trace entry N. */
+    replay(event: string, untilEntry: number): Promise<FlowTrace>;
+    /** Complete every active run in zero time (settle). */
+    skip(): void;
+    /** 1 = normal; 2 = twice as fast. Applies to waits, tweens, count-ups. */
+    setTurbo(factor: number): void;
+    /** Host reports a user tap (releases `wait until:'tap'`). */
+    tap(): void;
+    events(): string[];
+    destroy(): void;
+}
+/** Per-run runtime handed to step executors (core and plugin alike). */
+interface FlowRuntime {
+    scene: SceneHandle;
+    ctx: Record<string, unknown>;
+    audio: FlowAudioAdapter;
+    /** Turbo-scaled, skip-aware sleep. */
+    wait(ms: number): Promise<void>;
+    waitTap(): Promise<void>;
+    /** Execute a nested step list (if/parallel/seq bodies). */
+    run(steps: Step[]): Promise<void>;
+    /** True once skip() hit this run — executors should jump straight to end states. */
+    readonly skipped: boolean;
+    /** True for scrub replays — like skipped (jump to end states), plus audio stays muted. */
+    readonly instant: boolean;
+    readonly turbo: number;
+    /** Resolve '$path' references against ctx; other values pass through. */
+    resolve(value: unknown): unknown;
+    /** Evaluate an if-condition against ctx. */
+    when(expr: string): boolean;
+    /** A runtime whose ctx is overlaid with extra values (forEach exposes `$item` this way). */
+    child(ctxPatch: Record<string, unknown>): FlowRuntime;
+    trace(entry: Omit<TraceEntry, 't'>): void;
+    /** The node's live view (tween targets). */
+    view(id: string): Container | undefined;
+    log(msg: string): void;
+    codeRef(ref: string): ((rt: FlowRuntime, args: Record<string, unknown>) => Promise<void> | void) | undefined;
+    playCue(name: string, action: 'play' | 'stop'): void;
+}
+
+interface FlowStepContribution {
+    kind: string;
+    schema?: Record<string, unknown>;
+    /** 3–10 lines for the agent: when to use the step, patterns, anti-patterns. */
+    agentDoc?: string;
+    run(step: Step, rt: FlowRuntime): Promise<void> | void;
+}
+interface FlowPlugin {
+    id: string;
+    steps?: FlowStepContribution[];
+}
+
+/** The multi-scene graph as data: which docs exist and how the player moves between them. */
+interface StageDoc {
+    version: 1;
+    scenes: Array<{
+        key: string;
+        scene: SceneDoc;
+        flow?: FlowDoc;
+        /** Host skips this scene on replay launches (intro idiom). */
+        skipOnReplay?: boolean;
+        /** A tap anywhere advances to this scene key (intro → game). */
+        advanceOnTap?: string;
+    }>;
+}
+/** Build the createSlotGame `scenes` list from a StageDoc — every entry a DocScene. */
+declare function buildDocScenes<T extends SlotSpinResultBase = SlotSpinResultBase>(stage: StageDoc, shared: Omit<DocSceneOptions<T>, 'scene' | 'flow' | 'advanceOnTap'>): Array<{
+    key: string;
+    scene: DocScene<T>;
+    skipOnReplay?: boolean;
+}>;
+interface DocSceneOptions<T extends SlotSpinResultBase = SlotSpinResultBase> {
+    scene: SceneDoc;
+    flow?: FlowDoc;
+    /** A tap anywhere advances to this scene key (uses the host-injected goto). */
+    advanceOnTap?: string;
+    plugins?: ScenePlugin[];
+    flowPlugins?: FlowPlugin[];
+    code?: CreateFlowRunnerOptions['code'];
+    resolveSymbol?: SymbolResolver;
+    texture?: (alias: string) => Texture;
+    vars?: Record<string, unknown>;
+    /**
+     * Build the flow ctx for result-bearing events. Default: the result object spread +
+     * `{ win: totalWin, mode, action, bet }`. Games with richer normalized data override.
+     */
+    resultCtx?: (result: T, ctx: RenderContext) => Record<string, unknown>;
+    /** Map the shell turbo level (0..3) to a flow time factor. Default 1 + level. */
+    turboFactor?: (level: number) => number;
+    onTrace?: CreateFlowRunnerOptions['onTrace'];
+    log?: (msg: string) => void;
+}
+declare class DocScene<T extends SlotSpinResultBase = SlotSpinResultBase> extends Scene implements SlotSceneController<T> {
+    private opts;
+    private api;
+    private handle_;
+    private runner_;
+    private chain;
+    private lastSize;
+    private log;
+    constructor(opts: DocSceneOptions<T>);
+    /** The live scene handle (inspector/agent attachment). Null before onEnter. */
+    get scene(): SceneHandle | null;
+    get flow(): FlowRunner | null;
+    onEnter(data?: unknown): void;
+    onResize(width: number, height: number): void;
+    onDestroy(): void;
+    private fire;
+    private ctxOf;
+    onCreate(api: SceneApi): void;
+    onSpinStart(): void;
+    onSpin(result: T, ctx: RenderContext): Promise<void>;
+    onEnterMode(result: T, ctx: RenderContext): Promise<void>;
+    onExitMode(result: T, ctx: RenderContext): Promise<void>;
+    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 };