@waica/engine 0.10.0 → 0.12.0

package/dist/archetype.d.ts

@@ -22,6 +22,13 @@ export interface ArchetypeManifest {
     id: string;
     label: string;
     scene: SceneJson;
+    /**
+     * Additional demo scenes beyond `scene` (its name is always "main"),
+     * keyed by name — the isometric archetype's second demo scene (CA-13).
+     * `start:blank` never emits these; `start:demo` emits one file per entry
+     * alongside `scene`.
+     */
+    extraScenes?: Readonly<Record<string, SceneJson>>;
     blankScene: SceneJson;
     registry: SceneRegistry;
     palette: EntityTemplate[];

package/dist/component.d.ts

@@ -69,6 +69,11 @@ export declare abstract class Component {
     onCollide?(other: Entity): void;
     /** Runs when this entity's DynamicBody physically contacts a Solid. */
     onContact?(contact: SolidContact): void;
+    /**
+     * Runs when this entity wins the nearest-Interactable scan and the
+     * initiator interacts with it (a keypress or a click-to-move NPC order).
+     */
+    onInteract?(initiator: Entity): void;
     /** Runs when the entity is destroyed or the component removed. */
     onDestroy?(): void;
 }

package/dist/game.d.ts

@@ -4,7 +4,8 @@ import type { Component } from './component.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
 import { Input, type InputBindings } from './input.js';
-import { type SceneRegistry, type SceneRenderJson } from './scene.js';
+import { Pointer } from './pointer.js';
+import { type SceneJson, type SceneRegistry, type SceneRenderJson } from './scene.js';
 import { Stats, type StatValue } from './stats.js';
 import { GameUi } from './ui.js';
 /** Fixed game resolution: the view keeps this aspect, letterboxed. */
@@ -31,6 +32,11 @@ export interface SpawnPrefabOptions {
     name?: string;
     position?: [number, number];
 }
+/** The Project's scenes by name (a file's stem), plus the registry shared by all of them. */
+export interface SceneCatalog {
+    scenes: Record<string, SceneJson>;
+    registry: SceneRegistry;
+}
 /** Persisted overrides: entity → componentName → prop → value. */
 export type ParamOverrides = Record<string, Record<string, Record<string, number | boolean | string>>>;
 /**
@@ -41,6 +47,7 @@ export declare class Game {
     readonly scene: THREE.Scene<THREE.Object3DEventMap>;
     readonly camera: THREE.OrthographicCamera;
     readonly input: Input;
+    readonly pointer: Pointer;
     readonly entities: Entity[];
     readonly events: Emitter;
     readonly stats: Stats;
@@ -59,12 +66,22 @@ export declare class Game {
     private readonly updateFns;
     private readonly invalidUpdateCompositions;
     private readonly resolution;
+    /** The constructor's viewHeight — unloadScene() restores it. */
+    private readonly baseViewHeight;
     private viewHeight;
     private sceneCamera;
     private renderSort;
     private sceneProjection;
     private lastTime;
     private runtimeBridge;
+    /** Host-registered scenes by name, resolved by loadSceneByName. Session-scoped. */
+    private sceneCatalog;
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    private liveSceneName;
+    /** True for the whole extent of a runFrame() call, incl. its tail. */
+    private insideFrame;
+    /** A loadSceneByName() enqueued while insideFrame; applied at the next runFrame's start. */
+    private pendingSceneLoad;
     constructor(options: GameOptions);
     /** Creates a live entity in the scene. */
     spawn(name: string): Entity;
@@ -72,6 +89,35 @@ export declare class Game {
     spawnPrefab(prefab: string, options?: SpawnPrefabOptions): Entity | null;
     /** Finds an entity by name. */
     find(name: string): Entity | undefined;
+    /**
+     * Destroys the live scene — every entity (Entity.destroy(), so onDestroy
+     * cascades and GPU resources release) and its scene-scoped UI — and
+     * leaves the Game as newly constructed: no registry, no scene camera, no
+     * render sort or projection, viewHeight back to the constructor's.
+     * Session-scoped state (stats, paramOverrides, subscriptions, the scene
+     * catalog) is untouched. See ADR 0011. Public: the seam `loadScene` calls
+     * to replace a scene, and how a host leaves the Game with none loaded.
+     */
+    unloadScene(): void;
+    /** Registers the Project's scenes by name, resolved by loadSceneByName. */
+    registerSceneCatalog(catalog: SceneCatalog): void;
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    get sceneName(): string | null;
+    /** Names registered via registerSceneCatalog, in registration order. */
+    get availableScenes(): string[];
+    /**
+     * Resolves `name` through the registered catalog and loads it, replacing
+     * the live scene. An unknown name warns and leaves the live scene
+     * untouched. Triggered mid-frame (e.g. from a SceneTransition's
+     * onCollide/onInteract) the swap is deferred to the very start of the
+     * next runFrame — dispatchCollisions finishes its double loop over the
+     * outgoing scene, and the incoming scene's entities are present only
+     * from the next frame. Called from outside a frame (boot, or the Runtime
+     * Bridge's `scene` control operation) it applies synchronously and wins
+     * over anything queued earlier this frame. A second mid-frame request
+     * loses to the first and says so. Returns whether the load took effect.
+     */
+    loadSceneByName(name: string): boolean;
     /** Loads persisted parameter overrides (waica.params.json). */
     loadParams(url: string): Promise<void>;
     /** Applies persisted overrides to a freshly added component. */
@@ -102,6 +148,7 @@ export declare class Game {
     private resumeRuntime;
     private tick;
     private runFrame;
+    private flushPendingSceneLoad;
     private unregisterRuntimeBridge;
     /** Under y-sort, re-derives every participant's z from layer band + entity Y. */
     private applyYSort;

package/dist/game.js

@@ -6,11 +6,12 @@ import { Hitbox } from './components/hitbox.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
 import { Input } from './input.js';
+import { Pointer } from './pointer.js';
 import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
 import { RuntimeInspector } from './runtime-inspection.js';
 import { projectIsometric } from './projection.js';
 import { isYSortParticipant, ySortZ } from './render-sort.js';
-import { registryEntry, spawnFromJson } from './scene.js';
+import { loadScene, registryEntry, spawnFromJson, } from './scene.js';
 import { Stats } from './stats.js';
 import { GameUi } from './ui.js';
 /**
@@ -21,6 +22,7 @@ export class Game {
     scene = new THREE.Scene();
     camera;
     input;
+    pointer;
     entities = [];
     events = new Emitter();
     stats;
@@ -40,14 +42,25 @@ export class Game {
     updateFns = new Set();
     invalidUpdateCompositions = new WeakMap();
     resolution;
+    /** The constructor's viewHeight — unloadScene() restores it. */
+    baseViewHeight;
     viewHeight;
     sceneCamera = null;
     renderSort = null;
     sceneProjection = null;
     lastTime = 0;
     runtimeBridge = null;
+    /** Host-registered scenes by name, resolved by loadSceneByName. Session-scoped. */
+    sceneCatalog = null;
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    liveSceneName = null;
+    /** True for the whole extent of a runFrame() call, incl. its tail. */
+    insideFrame = false;
+    /** A loadSceneByName() enqueued while insideFrame; applied at the next runFrame's start. */
+    pendingSceneLoad = null;
     constructor(options) {
         const { canvas, background = 0x1a1a2e, viewHeight = 10 } = options;
+        this.baseViewHeight = viewHeight;
         this.viewHeight = viewHeight;
         this.resolution = options.resolution ?? null;
         this.input = new Input(options.bindings);
@@ -58,6 +71,12 @@ export class Game {
         this.scene.background = new THREE.Color(background);
         this.camera = new THREE.OrthographicCamera();
         this.camera.position.z = 10;
+        this.pointer = new Pointer(canvas, {
+            camera: this.camera,
+            resolution: this.resolution,
+            projection: () => this.sceneProjection,
+            entities: this.entities,
+        });
         this.resize();
         this.resizeObserver = new ResizeObserver(() => this.resize());
         this.resizeObserver.observe(canvas);
@@ -89,6 +108,84 @@ export class Game {
     find(name) {
         return this.entities.find((e) => e.name === name);
     }
+    /**
+     * Destroys the live scene — every entity (Entity.destroy(), so onDestroy
+     * cascades and GPU resources release) and its scene-scoped UI — and
+     * leaves the Game as newly constructed: no registry, no scene camera, no
+     * render sort or projection, viewHeight back to the constructor's.
+     * Session-scoped state (stats, paramOverrides, subscriptions, the scene
+     * catalog) is untouched. See ADR 0011. Public: the seam `loadScene` calls
+     * to replace a scene, and how a host leaves the Game with none loaded.
+     */
+    unloadScene() {
+        this.ui.unloadScene();
+        // An explicit unload means "no scene": a swap queued earlier this frame
+        // would otherwise flush next frame and resurrect one.
+        this.pendingSceneLoad = null;
+        // Entity.destroy() splices itself out of `this.entities` in place — the
+        // Pointer holds that array by reference, so it must never be reassigned.
+        for (const entity of [...this.entities])
+            entity.destroy();
+        this.registry = null;
+        this.renderSort = null;
+        this.sceneProjection = null;
+        this.sceneCamera = null;
+        this.liveSceneName = null;
+        this.setViewHeight(this.baseViewHeight);
+    }
+    /** Registers the Project's scenes by name, resolved by loadSceneByName. */
+    registerSceneCatalog(catalog) {
+        this.sceneCatalog = catalog;
+    }
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    get sceneName() {
+        return this.liveSceneName;
+    }
+    /** Names registered via registerSceneCatalog, in registration order. */
+    get availableScenes() {
+        return this.sceneCatalog ? Object.keys(this.sceneCatalog.scenes) : [];
+    }
+    /**
+     * Resolves `name` through the registered catalog and loads it, replacing
+     * the live scene. An unknown name warns and leaves the live scene
+     * untouched. Triggered mid-frame (e.g. from a SceneTransition's
+     * onCollide/onInteract) the swap is deferred to the very start of the
+     * next runFrame — dispatchCollisions finishes its double loop over the
+     * outgoing scene, and the incoming scene's entities are present only
+     * from the next frame. Called from outside a frame (boot, or the Runtime
+     * Bridge's `scene` control operation) it applies synchronously and wins
+     * over anything queued earlier this frame. A second mid-frame request
+     * loses to the first and says so. Returns whether the load took effect.
+     */
+    loadSceneByName(name) {
+        const catalog = this.sceneCatalog;
+        const json = catalog ? registryEntry(catalog.scenes, name) : undefined;
+        if (!catalog || !json) {
+            console.warn(`[waica] unknown scene: "${name}"`);
+            return false;
+        }
+        const apply = () => {
+            loadScene(this, json, catalog.registry);
+            this.liveSceneName = name;
+        };
+        if (!this.insideFrame) {
+            // Authoritative: dropping the queue is the point. A swap a transition
+            // enqueued earlier would otherwise flush on the next frame and silently
+            // undo this load, reporting success for a scene the caller never got.
+            this.pendingSceneLoad = null;
+            apply();
+            return true;
+        }
+        if (this.pendingSceneLoad) {
+            // Two transitions resolving in the same collision dispatch: the one the
+            // simulation reached first wins, and the loser is told. Last-write-wins
+            // would drop the player in the other door's destination with no signal.
+            console.warn(`[waica] a scene swap is already queued this frame; ignoring "${name}"`);
+            return false;
+        }
+        this.pendingSceneLoad = apply;
+        return true;
+    }
     /** Loads persisted parameter overrides (waica.params.json). */
     async loadParams(url) {
         try {
@@ -162,6 +259,11 @@ export class Game {
                     availableActions: () => this.input.availableActions(),
                     heldActions: () => this.input.heldActions(),
                     inspect: (metadata, filters) => inspector.snapshot(metadata, filters),
+                    click: (x, y) => {
+                        this.pointer.injectClick(x, y);
+                    },
+                    loadScene: (name) => this.loadSceneByName(name),
+                    availableScenes: () => this.availableScenes,
                 });
                 activation.register(this.runtimeBridge);
                 window.addEventListener('pagehide', this.unregisterRuntimeBridge);
@@ -197,6 +299,7 @@ export class Game {
         this.stop();
         this.unregisterRuntimeBridge();
         this.input.dispose();
+        this.pointer.dispose();
         this.resizeObserver.disconnect();
         this.ui.dispose();
         for (const entity of [...this.entities])
@@ -218,23 +321,40 @@ export class Game {
         this.runFrame(dt);
     }
     runFrame(dt) {
-        if (this.simulate) {
-            for (const entity of [...this.entities]) {
-                const schedule = this.componentUpdateSchedule(entity);
-                if (!schedule)
-                    continue;
-                for (const component of schedule)
-                    component.onUpdate?.(dt);
+        this.insideFrame = true;
+        try {
+            // Flushes a scene swap enqueued mid-frame last time (CA-7): applied
+            // before this frame's own simulation, so the incoming scene's
+            // entities are present only from this next frame onward.
+            this.flushPendingSceneLoad();
+            if (this.simulate) {
+                for (const entity of [...this.entities]) {
+                    const schedule = this.componentUpdateSchedule(entity);
+                    if (!schedule)
+                        continue;
+                    for (const component of schedule)
+                        component.onUpdate?.(dt);
+                }
+                this.dispatchCollisions();
+                this.updateSceneCamera(dt);
             }
-            this.dispatchCollisions();
-            this.updateSceneCamera(dt);
+            // The UI must react to the pause itself (hide until resumed).
+            this.ui.setActive(this.simulate);
+            for (const fn of this.updateFns)
+                fn(dt);
+            this.input.endFrame();
+            this.renderSurface();
         }
-        // The UI must react to the pause itself (hide until resumed).
-        this.ui.setActive(this.simulate);
-        for (const fn of this.updateFns)
-            fn(dt);
-        this.input.endFrame();
-        this.renderSurface();
+        finally {
+            this.insideFrame = false;
+        }
+    }
+    flushPendingSceneLoad() {
+        const pending = this.pendingSceneLoad;
+        if (!pending)
+            return;
+        this.pendingSceneLoad = null;
+        pending();
     }
     unregisterRuntimeBridge = () => {
         window.removeEventListener('pagehide', this.unregisterRuntimeBridge);

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Game } from './game.js';
-export type { GameOptions, GameResolution, SpawnPrefabOptions, UpdateFn, ParamOverrides, } from './game.js';
+export type { GameOptions, GameResolution, SceneCatalog, SpawnPrefabOptions, UpdateFn, ParamOverrides, } from './game.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export type { AnimationFacingProvider, DirectionalAnimation, DirectionalFallback, ResolvedDirectionalClip, } from './animation/directional.js';
 export { isYSortParticipant, ySortZ } from './render-sort.js';
@@ -20,7 +20,9 @@ export { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 export type { ComponentUpdateCycleIssue, ComponentUpdateRegistry, ComponentUpdateScheduleIssue, ComponentUpdateScheduleResult, DuplicateComponentUpdateIssue, InvalidComponentUpdateConstraintIssue, InvalidComponentUpdateSchedule, InvalidUpdateConstraintReason, ValidComponentUpdateSchedule, } from './component-update-schedule.js';
 export { Input, DEFAULT_BINDINGS } from './input.js';
 export type { ActionName, InjectedActionOperation, InputBindings } from './input.js';
-export { RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
+export { Pointer } from './pointer.js';
+export type { PointerCamera, PointerDeps, PointerPick, PointerResolution } from './pointer.js';
+export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export type { RuntimeBridge, RuntimeBridgeActivation, RuntimeControlRequest, RuntimeControlResult, RuntimeMetadata, RuntimeMode, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
 export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotFilters, RuntimeTransformSnapshot, } from './runtime-inspection.js';

package/dist/index.js

@@ -10,7 +10,8 @@ export { authoringDefaults } from './authoring-defaults.js';
 export { collectModuleComponents, mergeRegistryComponents } from './component-registry.js';
 export { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 export { Input, DEFAULT_BINDINGS } from './input.js';
-export { RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
+export { Pointer } from './pointer.js';
+export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
 export { Stats } from './stats.js';
 export { GameUi } from './ui.js';

package/dist/pointer.d.ts

@@ -0,0 +1,71 @@
+import type { Entity } from './entity.js';
+import { type ProjectedPoint } from './projection.js';
+/** Fixed-resolution letterbox target; a duck-typed subset of GameResolution. */
+export interface PointerResolution {
+    width: number;
+    height: number;
+}
+/** The orthographic camera state a Pointer needs; a duck-typed THREE.OrthographicCamera. */
+export interface PointerCamera {
+    position: {
+        x: number;
+        y: number;
+    };
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+export interface PointerDeps {
+    camera: PointerCamera;
+    /** Fixed resolution (letterbox target), or null to fill the canvas. */
+    resolution: PointerResolution | null;
+    /** The scene's active render projection, read live. */
+    projection: () => 'isometric' | null;
+    /** Live entity list — read at pick time, so later spawns are visible. */
+    entities: readonly Entity[];
+}
+/** One resolved click: the logical-space point, plus the entity picked there (if any). */
+export interface PointerPick {
+    readonly point: ProjectedPoint;
+    readonly entity: Entity | null;
+}
+/**
+ * Engine-owned pointer primitive (ADR-0010): the only place a click/tap on
+ * the game canvas is read. Converts a real `pointerdown` into a logical-space
+ * point (camera, letterbox, isometric unprojection) plus the entity picked
+ * there — resolved against declared sprite bounds (width/height/offset/anchor
+ * at the entity's projected position), y-sort breaking ties front-most wins —
+ * and queues it as one pending click for a consumer (ClickToMove) to drain.
+ * The Runtime Bridge injects a click through the same resolution, in logical
+ * coordinates, via injectClick.
+ */
+export declare class Pointer {
+    private readonly canvas;
+    private readonly deps;
+    private pending;
+    constructor(canvas: HTMLCanvasElement, deps: PointerDeps);
+    dispose(): void;
+    /**
+     * Consumes and clears the pending click, if any. A consumer (the grid
+     * player role's update) drains this once per simulated frame, so a click
+     * queued while paused takes effect on the next stepped frame.
+     */
+    takePending(): PointerPick | null;
+    /**
+     * Programmatic click injection (Runtime Bridge CA-10), in logical
+     * coordinates — resolved through the exact same picking a real click uses.
+     */
+    injectClick(x: number, y: number): PointerPick;
+    private handlePointerDown;
+    private letterboxRect;
+    private toRenderPoint;
+    private resolveRenderPoint;
+    /**
+     * The entity whose projected sprite bounds contain the render-space point,
+     * front-most under y-sort winning ties (ADR-0010, CA-1). Ignores current
+     * animation frame and mirroring: picking is scoped to the declared
+     * width/height/offset/anchor box, not the momentary displayed frame.
+     */
+    private pickEntity;
+}

package/dist/pointer.js

@@ -0,0 +1,162 @@
+import { projectIsometric, unprojectIsometric } from './projection.js';
+import { ySortZ } from './render-sort.js';
+import { AnimatedSprite } from './components/animated-sprite.js';
+import { Sprite } from './components/sprite.js';
+import { spritePlacement } from './sprite-placement.js';
+function spriteBoxOf(component) {
+    if (!(component instanceof Sprite) && !(component instanceof AnimatedSprite))
+        return null;
+    return {
+        width: component.width,
+        height: component.height,
+        offsetX: component.offsetX,
+        offsetY: component.offsetY,
+        anchorX: component.anchorX,
+        anchorY: component.anchorY,
+        layer: component.layer,
+    };
+}
+/**
+ * Engine-owned pointer primitive (ADR-0010): the only place a click/tap on
+ * the game canvas is read. Converts a real `pointerdown` into a logical-space
+ * point (camera, letterbox, isometric unprojection) plus the entity picked
+ * there — resolved against declared sprite bounds (width/height/offset/anchor
+ * at the entity's projected position), y-sort breaking ties front-most wins —
+ * and queues it as one pending click for a consumer (ClickToMove) to drain.
+ * The Runtime Bridge injects a click through the same resolution, in logical
+ * coordinates, via injectClick.
+ */
+export class Pointer {
+    canvas;
+    deps;
+    pending = null;
+    constructor(canvas, deps) {
+        this.canvas = canvas;
+        this.deps = deps;
+        this.canvas.addEventListener('pointerdown', this.handlePointerDown);
+    }
+    dispose() {
+        this.canvas.removeEventListener('pointerdown', this.handlePointerDown);
+        this.pending = null;
+    }
+    /**
+     * Consumes and clears the pending click, if any. A consumer (the grid
+     * player role's update) drains this once per simulated frame, so a click
+     * queued while paused takes effect on the next stepped frame.
+     */
+    takePending() {
+        const pick = this.pending;
+        this.pending = null;
+        return pick;
+    }
+    /**
+     * Programmatic click injection (Runtime Bridge CA-10), in logical
+     * coordinates — resolved through the exact same picking a real click uses.
+     */
+    injectClick(x, y) {
+        const renderPoint = this.toRenderPoint(x, y);
+        const pick = this.resolveRenderPoint(renderPoint.x, renderPoint.y);
+        this.pending = pick;
+        return pick;
+    }
+    handlePointerDown = (event) => {
+        // Primary button only; a touch tap reports the same button (ADR-0010).
+        if (event.button !== 0)
+            return;
+        const w = this.canvas.clientWidth;
+        const h = this.canvas.clientHeight;
+        if (w <= 0 || h <= 0)
+            return;
+        const { vx, vy, vw, vh } = this.letterboxRect(w, h);
+        if (vw <= 0 || vh <= 0)
+            return;
+        const rect = this.canvas.getBoundingClientRect();
+        const px = event.clientX - rect.left;
+        const py = event.clientY - rect.top;
+        const nx = (px - vx) / vw;
+        const ny = (py - vy) / vh;
+        // Outside the visible viewport (a letterbox bar): not a click on the world.
+        if (nx < 0 || nx > 1 || ny < 0 || ny > 1)
+            return;
+        const camera = this.deps.camera;
+        const renderX = camera.position.x + camera.left + nx * (camera.right - camera.left);
+        const renderY = camera.position.y + camera.top - ny * (camera.top - camera.bottom);
+        this.pending = this.resolveRenderPoint(renderX, renderY);
+    };
+    letterboxRect(w, h) {
+        const resolution = this.deps.resolution;
+        if (!resolution)
+            return { vx: 0, vy: 0, vw: w, vh: h };
+        const aspect = resolution.width / resolution.height;
+        const vw = Math.min(w, h * aspect);
+        const vh = vw / aspect;
+        return { vx: (w - vw) / 2, vy: (h - vh) / 2, vw, vh };
+    }
+    toRenderPoint(logicalX, logicalY) {
+        return this.deps.projection() === 'isometric'
+            ? projectIsometric(logicalX, logicalY)
+            : { x: logicalX, y: logicalY };
+    }
+    resolveRenderPoint(renderX, renderY) {
+        const point = this.deps.projection() === 'isometric'
+            ? unprojectIsometric(renderX, renderY)
+            : { x: renderX, y: renderY };
+        return { point, entity: this.pickEntity(renderX, renderY) };
+    }
+    /**
+     * The entity whose projected sprite bounds contain the render-space point,
+     * front-most under y-sort winning ties (ADR-0010, CA-1). Ignores current
+     * animation frame and mirroring: picking is scoped to the declared
+     * width/height/offset/anchor box, not the momentary displayed frame.
+     */
+    pickEntity(renderX, renderY) {
+        const hits = [];
+        for (const entity of this.deps.entities) {
+            if (!entity.alive)
+                continue;
+            for (const component of entity.components) {
+                const box = spriteBoxOf(component);
+                if (!box)
+                    continue;
+                const anchor = this.deps.projection() === 'isometric'
+                    ? projectIsometric(entity.position.x, entity.position.y)
+                    : { x: entity.position.x, y: entity.position.y };
+                const placement = spritePlacement({
+                    width: box.width,
+                    height: box.height,
+                    offsetX: box.offsetX,
+                    offsetY: box.offsetY,
+                    anchorX: box.anchorX,
+                    anchorY: box.anchorY,
+                    flipX: false,
+                    frameScaleX: 1,
+                    frameScaleY: 1,
+                });
+                const halfW = Math.abs(placement.scaleX) / 2;
+                const halfH = Math.abs(placement.scaleY) / 2;
+                const centerX = anchor.x + placement.x;
+                const centerY = anchor.y + placement.y;
+                if (renderX >= centerX - halfW &&
+                    renderX <= centerX + halfW &&
+                    renderY >= centerY - halfH &&
+                    renderY <= centerY + halfH) {
+                    // Matches Game.applyYSort's key exactly: the entity's node
+                    // position, which for an isometric scene is the projected Y (the
+                    // same `anchor.y` just used to place this box), not the logical one.
+                    hits.push({ entity, layer: box.layer, y: anchor.y });
+                    break;
+                }
+            }
+        }
+        if (hits.length === 0)
+            return null;
+        if (hits.length === 1)
+            return hits[0].entity;
+        const z = ySortZ(hits.map((h) => ({ layer: h.layer, y: h.y })));
+        let bestIndex = 0;
+        for (let i = 1; i < hits.length; i += 1)
+            if (z[i] > z[bestIndex])
+                bestIndex = i;
+        return hits[bestIndex].entity;
+    }
+}

package/dist/runtime-bridge.d.ts

@@ -2,12 +2,23 @@ import type { RuntimeSnapshot, RuntimeSnapshotFilters } from './runtime-inspecti
 export declare const RUNTIME_BRIDGE_PROTOCOL_VERSION: 1;
 export declare const RUNTIME_BRIDGE_SYMBOL: unique symbol;
 export type RuntimeMode = 'paused' | 'real-time';
+/**
+ * Operations this build's control() actually implements, beyond the
+ * baseline protocol 1 set (press/hold/release/pause/resume/step) every
+ * bridge has always supported. Additive metadata, not a protocol bump: a
+ * pre-CA-10 engine simply lacks this field, which is exactly what callers
+ * gating on capabilities check for (review finding #4) — protocol 1 alone
+ * doesn't distinguish an engine that silently no-ops an unknown operation
+ * from one that runs it.
+ */
+export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene'];
 export interface RuntimeMetadata {
     bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     engineVersion: string;
     mode: RuntimeMode;
     frame: number;
     simulationTime: number;
+    capabilities: readonly string[];
 }
 export type RuntimeControlRequest = {
     operation: 'press' | 'hold' | 'release';
@@ -18,6 +29,13 @@ export type RuntimeControlRequest = {
     operation: 'step';
     dt?: number;
     frames?: number;
+} | {
+    operation: 'click';
+    x: number;
+    y: number;
+} | {
+    operation: 'scene';
+    scene: string;
 };
 export interface RuntimeControlResult extends RuntimeMetadata {
     heldActions: string[];
@@ -25,8 +43,9 @@ export interface RuntimeControlResult extends RuntimeMetadata {
 export declare class RuntimeBridgeOperationError extends Error {
     readonly code: 'runtime-invalid-state' | 'runtime-operation-failed';
     readonly availableActions?: string[] | undefined;
+    readonly availableScenes?: string[] | undefined;
     readonly stage: 'control';
-    constructor(code: 'runtime-invalid-state' | 'runtime-operation-failed', message: string, availableActions?: string[] | undefined);
+    constructor(code: 'runtime-invalid-state' | 'runtime-operation-failed', message: string, availableActions?: string[] | undefined, availableScenes?: string[] | undefined);
 }
 /** Engine-owned capability registered only in an MCP-activated page. */
 export interface RuntimeBridge {
@@ -50,6 +69,10 @@ export interface RuntimeBridgeHost {
     availableActions(): string[];
     heldActions(): string[];
     inspect(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
+    click(x: number, y: number): void;
+    /** Resolves `name` through the registered catalog and loads it. */
+    loadScene(name: string): boolean;
+    availableScenes(): string[];
 }
 export declare class EngineRuntimeBridge implements RuntimeBridge {
     readonly surface: HTMLCanvasElement;

package/dist/runtime-bridge.js

@@ -1,14 +1,26 @@
 import enginePackage from '../package.json' with { type: 'json' };
 export const RUNTIME_BRIDGE_PROTOCOL_VERSION = 1;
 export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
+/**
+ * Operations this build's control() actually implements, beyond the
+ * baseline protocol 1 set (press/hold/release/pause/resume/step) every
+ * bridge has always supported. Additive metadata, not a protocol bump: a
+ * pre-CA-10 engine simply lacks this field, which is exactly what callers
+ * gating on capabilities check for (review finding #4) — protocol 1 alone
+ * doesn't distinguish an engine that silently no-ops an unknown operation
+ * from one that runs it.
+ */
+export const RUNTIME_BRIDGE_CAPABILITIES = ['click', 'scene'];
 export class RuntimeBridgeOperationError extends Error {
     code;
     availableActions;
+    availableScenes;
     stage = 'control';
-    constructor(code, message, availableActions) {
+    constructor(code, message, availableActions, availableScenes) {
         super(message);
         this.code = code;
         this.availableActions = availableActions;
+        this.availableScenes = availableScenes;
         this.name = 'RuntimeBridgeOperationError';
     }
 }
@@ -45,6 +57,7 @@ export class EngineRuntimeBridge {
             mode: this.mode,
             frame: this.frame,
             simulationTime: this.simulationTime,
+            capabilities: RUNTIME_BRIDGE_CAPABILITIES,
         };
     }
     inspect(filters = {}) {
@@ -88,6 +101,24 @@ export class EngineRuntimeBridge {
                     this.advance(dt);
                 break;
             }
+            case 'click': {
+                if (!Number.isFinite(request.x) || !Number.isFinite(request.y)) {
+                    throw new RuntimeBridgeOperationError('runtime-operation-failed', 'x and y must be finite numbers.');
+                }
+                this.host.click(request.x, request.y);
+                break;
+            }
+            case 'scene': {
+                if (!this.host.loadScene(request.scene)) {
+                    const available = this.host.availableScenes();
+                    throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unknown scene "${request.scene}". Available scenes: ${available.join(', ') || '(none)'}.`, undefined, available);
+                }
+                break;
+            }
+            default: {
+                const unsupported = request;
+                throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unsupported runtime control operation "${unsupported.operation}".`);
+            }
         }
         return { ...this.metadata(), heldActions: this.host.heldActions() };
     }

package/dist/runtime-inspection.d.ts

@@ -50,6 +50,8 @@ export interface RuntimeEntitySnapshot {
 }
 export interface RuntimeSnapshot extends RuntimeMetadata {
     stats: Record<string, StatValue>;
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    scene: string | null;
     entities: RuntimeEntitySnapshot[];
     projectionIssues: ProjectionIssue[];
 }

package/dist/runtime-inspection.js

@@ -234,6 +234,7 @@ export class RuntimeInspector {
         return this.capSnapshot({
             ...metadata,
             stats: Object.fromEntries([...this.game.stats.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
+            scene: this.game.sceneName,
             entities,
             projectionIssues,
         });

package/dist/scene.d.ts

@@ -88,5 +88,9 @@ export declare function resolveProps(props: Record<string, unknown> | undefined,
 export declare function resolveEntityComponents(entity: SceneEntityJson, prefabs?: Record<string, PrefabJson>): SceneComponentJson[];
 /** Instantiates a scene entity into the game. */
 export declare function spawnFromJson(game: Game, json: SceneEntityJson, registry: SceneRegistry): Entity;
-/** Loads a full scene into the game. */
+/**
+ * Loads a full scene into the game, replacing whatever scene is already
+ * live (Game.unloadScene() first) — see ADR 0011. A Game shows one scene
+ * at a time.
+ */
 export declare function loadScene(game: Game, scene: SceneJson, registry: SceneRegistry): void;

package/dist/scene.js

@@ -79,8 +79,14 @@ export function spawnFromJson(game, json, registry) {
     }
     return entity;
 }
-/** Loads a full scene into the game. */
+/**
+ * Loads a full scene into the game, replacing whatever scene is already
+ * live (Game.unloadScene() first) — see ADR 0011. A Game shows one scene
+ * at a time.
+ */
 export function loadScene(game, scene, registry) {
+    if (game.registry)
+        game.unloadScene();
     game.registry = registry;
     game.setSceneRender(scene.render);
     for (const entityJson of scene.entities)
@@ -89,6 +95,7 @@ export function loadScene(game, scene, registry) {
     game.setSceneCamera(scene.camera);
     if (registry.ui)
         game.ui.defineAll(registry.ui);
+    // Scene-scoped: Game.unloadScene() unmounts these along with the entities.
     for (const name of scene.ui ?? [])
-        game.ui.show(name);
+        game.ui.show(name, { scope: 'scene' });
 }

package/dist/ui.d.ts

@@ -27,7 +27,7 @@ export declare class GameUi {
     defineAll(pieces: Record<string, string>): void;
     /** Piece names available to show (defined via the registry or define()). */
     names(): string[];
-    show(name: string): void;
+    show(name: string, options?: ShowOptions): void;
     hide(name: string): void;
     toggle(name: string): void;
     isVisible(name: string): boolean;
@@ -41,7 +41,18 @@ export declare class GameUi {
     setActive(active: boolean): void;
     /** Unmounts every piece and removes the overlay (Game.dispose). */
     dispose(): void;
+    /**
+     * Unmounts every scene-scoped piece: the ones `loadScene` showed from the
+     * outgoing scene's `ui` list, plus any shown with `{ scope: 'scene' }`.
+     * A piece the host showed with no scope is untouched. The definition
+     * catalog (sources) always survives — Game.unloadScene.
+     */
+    unloadScene(): void;
     private mount;
     private mountOverlay;
     private sync;
 }
+export interface ShowOptions {
+    /** 'scene': unmounted by Game.unloadScene() along with the rest of the scene. */
+    scope?: 'scene';
+}

package/dist/ui.js

@@ -35,10 +35,19 @@ export class GameUi {
     names() {
         return [...this.sources.keys()];
     }
-    show(name) {
+    show(name, options = {}) {
+        const mounted = this.pieces.has(name);
         const piece = this.mount(name);
-        if (piece)
+        if (piece) {
             piece.visible = true;
+            // Scope belongs to whoever mounts the piece, and a later show never
+            // changes it. Otherwise a scene whose `ui` list happens to name a piece
+            // the host already mounted would quietly take ownership of it and
+            // destroy it on the next unload — a session-scoped HUD dying with a
+            // map it merely shares a name with.
+            if (!mounted)
+                piece.scope = options.scope;
+        }
         this.sync();
     }
     hide(name) {
@@ -81,6 +90,23 @@ export class GameUi {
         this.overlay?.remove();
         this.overlay = undefined;
     }
+    /**
+     * Unmounts every scene-scoped piece: the ones `loadScene` showed from the
+     * outgoing scene's `ui` list, plus any shown with `{ scope: 'scene' }`.
+     * A piece the host showed with no scope is untouched. The definition
+     * catalog (sources) always survives — Game.unloadScene.
+     */
+    unloadScene() {
+        for (const [name, piece] of this.pieces) {
+            if (piece.scope !== 'scene')
+                continue;
+            for (const off of piece.unsubs)
+                off();
+            piece.shell.remove();
+            this.pieces.delete(name);
+        }
+        this.sync();
+    }
     mount(name) {
         const existing = this.pieces.get(name);
         if (existing)
@@ -100,7 +126,13 @@ export class GameUi {
         root.style.display = 'contents';
         root.innerHTML = html;
         shadow.append(root);
-        const piece = { shell, root, visible: false, unsubs: bindStats(root, this.stats) };
+        const piece = {
+            shell,
+            root,
+            visible: false,
+            scope: undefined,
+            unsubs: bindStats(root, this.stats),
+        };
         this.mountOverlay().append(shell);
         this.pieces.set(name, piece);
         return piece;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",