@waica/engine 0.5.0 → 0.6.1

package/README.md

@@ -0,0 +1,85 @@
+# `@waica/engine`
+
+Waica's public engine core: entities and components, the game loop, scene and prefab loading, state machines, input, collisions, sprites, camera, stats, and UI.
+
+```ts
+import { Component, Game, loadScene } from '@waica/engine'
+```
+
+## Component lifecycle
+
+Waica keeps the lifecycle boundaries distinct:
+
+1. `Entity.add()` mounts a component and calls its `onReady` immediately. This remains component insertion order so setup behavior does not silently move.
+2. During each simulated frame, entities keep their existing entity order. When an entity's turn begins, `Game` snapshots and resolves that entity's component `onUpdate` schedule, then dispatches only that schedule.
+3. Physical `onContact` hooks run from `DynamicBody` while it updates. Hitbox `onCollide` hooks run after all entity component updates. Their existing component dispatch order is unchanged.
+4. `Game.onUpdate` callbacks run after component updates, collisions, and camera work; input end-of-frame handling follows them.
+5. `Entity.destroy()` calls `onDestroy` in component insertion order.
+
+Only classes whose prototype chain implements `onUpdate` participate in the update schedule. Passive components remain available to their siblings but receive no update position.
+
+## Declaring update constraints
+
+An updateable component can declare the sibling writes it must observe with inherited static `updateAfter` metadata:
+
+```ts
+import { Component, StateMachine } from '@waica/engine'
+
+export class DamageFlash extends Component {
+  static override componentName = 'DamageFlash'
+  static override updateAfter: readonly string[] = ['StateMachine']
+
+  override onUpdate(dt: number): void {
+    const state = this.entity.get(StateMachine)?.current
+    // This update observes StateMachine's state for the same frame.
+    void state
+    void dt
+  }
+}
+```
+
+The relation is conditional on co-presence. `DamageFlash` does not require a `StateMachine`; when that target is registered but absent from this entity, no edge and no issue are created. A subclass inherits `updateAfter` when it declares nothing and replaces the inherited list when it declares its own list.
+
+Constraints always win over the tie-break. Whenever several components are ready simultaneously, Waica compares their case-sensitive `componentName` values in ascending Unicode code-unit order. It never uses locale collation, prefab order, scene order, or editor card grouping. Repeated names in one `updateAfter` list describe one edge.
+
+## Invalid schedules fail closed
+
+Component identity must be unique within an entity, and both sides of a present constraint must implement `onUpdate`. Waica rejects duplicate component names, unknown targets, passive declarers or present passive targets, self-edges, and multi-component cycles.
+
+At runtime an invalid entity runs no partial update schedule and does not fall back to authored order. Other entities continue updating. The engine logs one diagnostic containing the entity and causes, then logs again only if that entity's composition changes.
+
+Tools can inspect a composition without constructing components:
+
+```ts
+import { resolveComponentUpdateSchedule, type ComponentClass } from '@waica/engine'
+
+const registry: Record<string, ComponentClass> = { DamageFlash, StateMachine }
+const result = resolveComponentUpdateSchedule(
+  ['DamageFlash', 'StateMachine'],
+  registry,
+)
+
+if (result.ok) {
+  console.log(result.order) // ['StateMachine', 'DamageFlash']
+} else {
+  console.error(result.issues)
+}
+```
+
+The resolver is pure. Pass the effective component-name list and the complete class registry, including project-owned classes. A valid result contains `order` and no issues; an invalid result contains typed, actionable issues and no executable order.
+
+## Runtime inspection
+
+The engine owns Runtime Bridge protocol 1, but it is dormant during ordinary execution: there is no string-named global, network endpoint or per-frame bridge work. An MCP-owned browser context can install the symbol-keyed ephemeral activation hook before navigation. In that context `Game.start()` registers the fully constructed Game at a paused frame-zero baseline; `Game.dispose()` or page unload unregisters it.
+
+Runtime Snapshots automatically inspect public own component fields and setter-backed accessors while excluding `_` fields, `entity`, `game` and functions. A component can replace automatic discovery with the optional public contract:
+
+```ts
+class PathFinder extends Component {
+  inspectState(): unknown {
+    return { target: this.target, remaining: this.path.length }
+  }
+}
+```
+
+The return value still passes through the bounded safe projector; it is not serialized with arbitrary `toJSON()`. The package root exports the Runtime Snapshot, projection marker, metadata, control and activation types plus `RUNTIME_BRIDGE_PROTOCOL_VERSION` and `RUNTIME_PROJECTION_LIMITS`.

package/dist/component-update-schedule.d.ts

@@ -0,0 +1,39 @@
+import type { ComponentClass } from './component.js';
+export type InvalidUpdateConstraintReason = 'unknown-target' | 'passive-declarer' | 'passive-target' | 'self-edge' | 'unregistered-component';
+export interface DuplicateComponentUpdateIssue {
+    readonly code: 'duplicate-component';
+    readonly componentNames: readonly string[];
+    readonly componentName: string;
+    readonly count: number;
+    readonly cause: string;
+}
+export interface InvalidComponentUpdateConstraintIssue {
+    readonly code: 'invalid-update-constraint';
+    readonly componentNames: readonly string[];
+    readonly declarer: string;
+    readonly target?: string;
+    readonly reason: InvalidUpdateConstraintReason;
+    readonly cause: string;
+}
+export interface ComponentUpdateCycleIssue {
+    readonly code: 'component-update-cycle';
+    readonly componentNames: readonly string[];
+    readonly cause: string;
+}
+export type ComponentUpdateScheduleIssue = DuplicateComponentUpdateIssue | InvalidComponentUpdateConstraintIssue | ComponentUpdateCycleIssue;
+export interface ValidComponentUpdateSchedule {
+    readonly ok: true;
+    readonly order: readonly string[];
+    readonly issues: readonly [];
+}
+export interface InvalidComponentUpdateSchedule {
+    readonly ok: false;
+    readonly issues: readonly ComponentUpdateScheduleIssue[];
+}
+export type ComponentUpdateScheduleResult = ValidComponentUpdateSchedule | InvalidComponentUpdateSchedule;
+export type ComponentUpdateRegistry = Readonly<Record<string, ComponentClass | undefined>>;
+/**
+ * Resolves one entity's deterministic component update schedule without
+ * constructing components or mutating either input.
+ */
+export declare function resolveComponentUpdateSchedule(componentNames: readonly string[], registry: ComponentUpdateRegistry): ComponentUpdateScheduleResult;

package/dist/component-update-schedule.js

@@ -0,0 +1,157 @@
+function codeUnitCompare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function registeredClass(registry, componentName) {
+    return Object.hasOwn(registry, componentName) ? registry[componentName] : undefined;
+}
+function updates(Class) {
+    return typeof Class?.prototype.onUpdate === 'function';
+}
+function updateCycles(nodes, outgoing) {
+    let nextIndex = 0;
+    const indices = new Map();
+    const lowLinks = new Map();
+    const stack = [];
+    const onStack = new Set();
+    const cycles = [];
+    const visit = (node) => {
+        const index = nextIndex++;
+        indices.set(node, index);
+        lowLinks.set(node, index);
+        stack.push(node);
+        onStack.add(node);
+        for (const dependent of [...(outgoing.get(node) ?? [])].sort(codeUnitCompare)) {
+            if (!indices.has(dependent)) {
+                visit(dependent);
+                lowLinks.set(node, Math.min(lowLinks.get(node), lowLinks.get(dependent)));
+            }
+            else if (onStack.has(dependent)) {
+                lowLinks.set(node, Math.min(lowLinks.get(node), indices.get(dependent)));
+            }
+        }
+        if (lowLinks.get(node) !== indices.get(node))
+            return;
+        const group = [];
+        while (stack.length > 0) {
+            const member = stack.pop();
+            onStack.delete(member);
+            group.push(member);
+            if (member === node)
+                break;
+        }
+        if (group.length > 1)
+            cycles.push(group.sort(codeUnitCompare));
+    };
+    for (const node of nodes) {
+        if (!indices.has(node))
+            visit(node);
+    }
+    return cycles.sort((left, right) => codeUnitCompare(left[0], right[0]));
+}
+/**
+ * Resolves one entity's deterministic component update schedule without
+ * constructing components or mutating either input.
+ */
+export function resolveComponentUpdateSchedule(componentNames, registry) {
+    const present = new Set(componentNames);
+    const nodes = [...present]
+        .filter((name) => updates(registeredClass(registry, name)))
+        .sort(codeUnitCompare);
+    const outgoing = new Map(nodes.map((name) => [name, new Set()]));
+    const indegree = new Map(nodes.map((name) => [name, 0]));
+    const issues = [];
+    const counts = new Map();
+    for (const name of componentNames)
+        counts.set(name, (counts.get(name) ?? 0) + 1);
+    for (const [componentName, count] of [...counts].sort(([left], [right]) => codeUnitCompare(left, right))) {
+        if (count < 2)
+            continue;
+        issues.push({
+            code: 'duplicate-component',
+            componentName,
+            componentNames: [componentName],
+            count,
+            cause: `Component "${componentName}" appears ${count} times on the same entity; component identity must be unique.`,
+        });
+    }
+    for (const declarer of [...present].sort(codeUnitCompare)) {
+        const Class = registeredClass(registry, declarer);
+        if (Class?.updateAfter !== undefined && !updates(Class)) {
+            issues.push({
+                code: 'invalid-update-constraint',
+                reason: 'passive-declarer',
+                declarer,
+                componentNames: [declarer],
+                cause: `Passive component "${declarer}" declares updateAfter but does not implement onUpdate.`,
+            });
+        }
+    }
+    for (const declarer of nodes) {
+        const Class = registeredClass(registry, declarer);
+        for (const target of new Set(Class?.updateAfter ?? [])) {
+            if (!present.has(target)) {
+                if (!registeredClass(registry, target)) {
+                    issues.push({
+                        code: 'invalid-update-constraint',
+                        reason: 'unknown-target',
+                        declarer,
+                        target,
+                        componentNames: [declarer, target],
+                        cause: `Component "${declarer}" declares updateAfter target "${target}", which is neither present nor registered.`,
+                    });
+                }
+                continue;
+            }
+            if (target === declarer) {
+                issues.push({
+                    code: 'invalid-update-constraint',
+                    reason: 'self-edge',
+                    declarer,
+                    target,
+                    componentNames: [declarer],
+                    cause: `Component "${declarer}" cannot declare itself in updateAfter.`,
+                });
+                continue;
+            }
+            if (!outgoing.has(target)) {
+                issues.push({
+                    code: 'invalid-update-constraint',
+                    reason: 'passive-target',
+                    declarer,
+                    target,
+                    componentNames: [declarer, target],
+                    cause: `Component "${declarer}" declares updateAfter target "${target}", but "${target}" does not implement onUpdate.`,
+                });
+                continue;
+            }
+            const readers = outgoing.get(target);
+            if (readers.has(declarer))
+                continue;
+            readers.add(declarer);
+            indegree.set(declarer, (indegree.get(declarer) ?? 0) + 1);
+        }
+    }
+    for (const componentNames of updateCycles(nodes, outgoing)) {
+        issues.push({
+            code: 'component-update-cycle',
+            componentNames,
+            cause: `Component update cycle among ${componentNames.map((name) => `"${name}"`).join(', ')}.`,
+        });
+    }
+    if (issues.length > 0)
+        return { ok: false, issues };
+    const ready = nodes.filter((name) => indegree.get(name) === 0);
+    const order = [];
+    while (ready.length > 0) {
+        ready.sort(codeUnitCompare);
+        const next = ready.shift();
+        order.push(next);
+        for (const dependent of [...(outgoing.get(next) ?? [])].sort(codeUnitCompare)) {
+            const remaining = (indegree.get(dependent) ?? 0) - 1;
+            indegree.set(dependent, remaining);
+            if (remaining === 0)
+                ready.push(dependent);
+        }
+    }
+    return { ok: true, order, issues: [] };
+}

package/dist/component.d.ts

@@ -23,6 +23,8 @@ export interface ComponentClass<T extends Component = Component> {
     displayName?: string;
     /** Which properties the inspector exposes, with their ranges. */
     params?: Record<string, ParamSpec>;
+    /** Sibling component updates that must complete before this one when present. */
+    updateAfter?: readonly string[];
     /**
      * Instance fields holding runtime state rather than authorable defaults.
      * Excluded from authoringDefaults(); a subclass that does not redeclare
@@ -51,9 +53,12 @@ export declare abstract class Component {
     static componentName: string;
     static displayName?: string;
     static params?: Record<string, ParamSpec>;
+    static updateAfter?: readonly string[];
     static transient?: readonly string[];
     entity: Entity;
     game: Game;
+    /** Replaces automatic runtime-state discovery for Runtime Snapshots. */
+    inspectState?(): unknown;
     /** Runs once the component is mounted on its entity. */
     onReady?(): void;
     /** Runs once per frame. */

package/dist/component.js

@@ -6,6 +6,7 @@ export class Component {
     static componentName = 'Component';
     static displayName;
     static params;
+    static updateAfter;
     static transient;
     entity;
     game;

package/dist/components/animated-sprite.d.ts

@@ -12,6 +12,7 @@ import { type SheetCell, type SheetDef } from '../animation/sheet.js';
  */
 export declare class AnimatedSprite extends Component {
     static componentName: string;
+    static updateAfter: readonly string[];
     static params: {
         offsetX: {
             label: string;

package/dist/components/animated-sprite.js

@@ -14,6 +14,7 @@ const loader = new THREE.TextureLoader();
  */
 export class AnimatedSprite extends Component {
     static componentName = 'AnimatedSprite';
+    static updateAfter = ['StateMachine'];
     static params = {
         offsetX: { label: 'x offset' },
         offsetY: { label: 'y offset' },

package/dist/game.d.ts

@@ -57,10 +57,12 @@ export declare class Game {
     private readonly renderer;
     private readonly resizeObserver;
     private readonly updateFns;
+    private readonly invalidUpdateCompositions;
     private readonly resolution;
     private viewHeight;
     private sceneCamera;
     private lastTime;
+    private runtimeBridge;
     constructor(options: GameOptions);
     /** Creates a live entity in the scene. */
     spawn(name: string): Entity;
@@ -88,7 +90,12 @@ export declare class Game {
     setViewHeight(value: number): void;
     /** Shuts the game down completely (loop, input, GPU). */
     dispose(): void;
+    private resumeRuntime;
     private tick;
+    private runFrame;
+    private unregisterRuntimeBridge;
+    private renderSurface;
+    private componentUpdateSchedule;
     private updateSceneCamera;
     private dispatchCollisions;
     private resize;

package/dist/game.js

@@ -1,10 +1,13 @@
 import * as THREE from 'three';
 import { collisionOverlap } from './collision-shape.js';
 import { resolveSceneCamera, stepSceneCamera } from './camera.js';
+import { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 import { Hitbox } from './components/hitbox.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
 import { Input } from './input.js';
+import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
+import { RuntimeInspector } from './runtime-inspection.js';
 import { registryEntry, spawnFromJson } from './scene.js';
 import { Stats } from './stats.js';
 import { GameUi } from './ui.js';
@@ -33,10 +36,12 @@ export class Game {
     renderer;
     resizeObserver;
     updateFns = new Set();
+    invalidUpdateCompositions = new WeakMap();
     resolution;
     viewHeight;
     sceneCamera = null;
     lastTime = 0;
+    runtimeBridge = null;
     constructor(options) {
         const { canvas, background = 0x1a1a2e, viewHeight = 10 } = options;
         this.viewHeight = viewHeight;
@@ -124,6 +129,25 @@ export class Game {
         this.setViewHeight(this.sceneCamera.zoom);
     }
     start() {
+        const activation = activeRuntimeBridgeHook();
+        if (activation) {
+            if (!this.runtimeBridge) {
+                const inspector = new RuntimeInspector(this);
+                this.runtimeBridge = new EngineRuntimeBridge(this.renderer.domElement, activation, {
+                    step: (dt) => this.runFrame(dt),
+                    resume: (frame) => this.resumeRuntime(frame),
+                    pause: () => this.stop(),
+                    injectAction: (action, operation) => this.input.injectAction(action, operation),
+                    availableActions: () => this.input.availableActions(),
+                    heldActions: () => this.input.heldActions(),
+                    inspect: (metadata, filters) => inspector.snapshot(metadata, filters),
+                });
+                activation.register(this.runtimeBridge);
+                window.addEventListener('pagehide', this.unregisterRuntimeBridge);
+            }
+            this.renderSurface();
+            return;
+        }
         this.renderer.setAnimationLoop((time) => this.tick(time));
     }
     stop() {
@@ -146,6 +170,7 @@ export class Game {
     /** Shuts the game down completely (loop, input, GPU). */
     dispose() {
         this.stop();
+        this.unregisterRuntimeBridge();
         this.input.dispose();
         this.resizeObserver.disconnect();
         this.ui.dispose();
@@ -153,13 +178,27 @@ export class Game {
             entity.destroy();
         this.renderer.dispose();
     }
+    resumeRuntime(frame) {
+        let previousTime = null;
+        this.renderer.setAnimationLoop((time) => {
+            const dt = previousTime === null ? 0 : Math.min((time - previousTime) / 1000, 0.1);
+            previousTime = time;
+            frame(dt);
+        });
+    }
     tick(time) {
         // Clamp dt: switching tabs or pausing doesn't fast-forward the simulation.
         const dt = Math.min((time - this.lastTime) / 1000, 0.1);
         this.lastTime = time;
+        this.runFrame(dt);
+    }
+    runFrame(dt) {
         if (this.simulate) {
             for (const entity of [...this.entities]) {
-                for (const component of [...entity.components])
+                const schedule = this.componentUpdateSchedule(entity);
+                if (!schedule)
+                    continue;
+                for (const component of schedule)
                     component.onUpdate?.(dt);
             }
             this.dispatchCollisions();
@@ -170,6 +209,15 @@ export class Game {
         for (const fn of this.updateFns)
             fn(dt);
         this.input.endFrame();
+        this.renderSurface();
+    }
+    unregisterRuntimeBridge = () => {
+        window.removeEventListener('pagehide', this.unregisterRuntimeBridge);
+        this.runtimeBridge?.unregister();
+        this.runtimeBridge = null;
+    };
+    renderSurface() {
+        this.ui.setActive(this.simulate);
         if (this.resolution) {
             // Letterbox bars: clear the whole canvas, then render inside the scissor.
             this.renderer.setScissorTest(false);
@@ -179,6 +227,36 @@ export class Game {
         }
         this.renderer.render(this.scene, this.camera);
     }
+    componentUpdateSchedule(entity) {
+        const components = [...entity.components];
+        const registry = {
+            ...(this.registry?.components ?? {}),
+        };
+        const byName = new Map();
+        const names = [];
+        const signatureParts = [];
+        for (const component of components) {
+            const Class = component.constructor;
+            const name = Class.componentName;
+            registry[name] = Class;
+            names.push(name);
+            byName.set(name, component);
+            signatureParts.push(`${name}:${typeof Class.prototype.onUpdate === 'function' ? 'updates' : 'passive'}:` +
+                [...new Set(Class.updateAfter ?? [])].sort().join(','));
+        }
+        const result = resolveComponentUpdateSchedule(names, registry);
+        if (!result.ok) {
+            const signature = signatureParts.sort().join('|');
+            if (this.invalidUpdateCompositions.get(entity) !== signature) {
+                this.invalidUpdateCompositions.set(entity, signature);
+                console.error(`[waica] invalid component update schedule for "${entity.name}": ` +
+                    result.issues.map((issue) => issue.cause).join(' '));
+            }
+            return null;
+        }
+        this.invalidUpdateCompositions.delete(entity);
+        return result.order.map((name) => byName.get(name));
+    }
     updateSceneCamera(dt) {
         const cam = this.sceneCamera;
         if (!cam)

package/dist/index.d.ts

@@ -8,8 +8,14 @@ export { authoringDefaults } from './authoring-defaults.js';
 export type { ComponentClass, ContactNormal, ParamSpec, SolidContact, } from './component.js';
 export { collectModuleComponents, mergeRegistryComponents } from './component-registry.js';
 export type { ComponentModule } from './component-registry.js';
+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, InputBindings } 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 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';
 export type { ArchetypeArt, ArchetypeManifest, BrowserArchetypeManifest, EntityTemplate, } from './archetype.js';
 export { Stats } from './stats.js';
 export type { StatValue } from './stats.js';

package/dist/index.js

@@ -4,7 +4,10 @@ export { Entity } from './entity.js';
 export { Component } from './component.js';
 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 { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
 export { Stats } from './stats.js';
 export { GameUi } from './ui.js';
 export { Sprite } from './components/sprite.js';

package/dist/input.d.ts

@@ -1,4 +1,5 @@
 export type ActionName = string;
+export type InjectedActionOperation = 'press' | 'hold' | 'release';
 /** Action → KeyboardEvent.code list. */
 export type InputBindings = Record<string, string[]>;
 /** Neutral engine baseline; archetypes own their action vocabulary. */
@@ -11,6 +12,9 @@ export declare class Input {
     private readonly bindings;
     private readonly down;
     private readonly justDown;
+    private readonly injectedDown;
+    private readonly injectedJustDown;
+    private readonly injectedPresses;
     private readonly used;
     /** Installs exactly the action map supplied by the active archetype/project. */
     constructor(bindings?: Readonly<InputBindings>);
@@ -18,6 +22,12 @@ export declare class Input {
     held(action: ActionName): boolean;
     /** Was the action pressed exactly this frame? */
     justPressed(action: ActionName): boolean;
+    /** Installed semantic action names in deterministic order. */
+    availableActions(): ActionName[];
+    /** Currently held semantic action names in deterministic order. */
+    heldActions(): ActionName[];
+    /** Injects an action by semantic name; false means the action is not installed. */
+    injectAction(action: ActionName, operation: InjectedActionOperation): boolean;
     /** -1..1 axis from two actions (left/right by default). */
     axis(negative?: ActionName, positive?: ActionName): number;
     /**

package/dist/input.js

@@ -8,6 +8,9 @@ export class Input {
     bindings = new Map();
     down = new Set();
     justDown = new Set();
+    injectedDown = new Set();
+    injectedJustDown = new Set();
+    injectedPresses = new Set();
     used = new Set();
     /** Installs exactly the action map supplied by the active archetype/project. */
     constructor(bindings = DEFAULT_BINDINGS) {
@@ -21,11 +24,39 @@ export class Input {
     }
     /** Is the action held this frame? */
     held(action) {
-        return this.isActive(action, this.down);
+        return this.injectedDown.has(action) || this.isActive(action, this.down);
     }
     /** Was the action pressed exactly this frame? */
     justPressed(action) {
-        return this.isActive(action, this.justDown);
+        return this.injectedJustDown.has(action) || this.isActive(action, this.justDown);
+    }
+    /** Installed semantic action names in deterministic order. */
+    availableActions() {
+        return [...this.bindings.keys()].sort();
+    }
+    /** Currently held semantic action names in deterministic order. */
+    heldActions() {
+        return this.availableActions().filter((action) => this.held(action));
+    }
+    /** Injects an action by semantic name; false means the action is not installed. */
+    injectAction(action, operation) {
+        if (!this.bindings.has(action))
+            return false;
+        if (operation === 'release') {
+            this.injectedDown.delete(action);
+            this.injectedPresses.delete(action);
+            return true;
+        }
+        if (this.held(action)) {
+            if (operation === 'hold')
+                this.injectedPresses.delete(action);
+            return true;
+        }
+        this.injectedDown.add(action);
+        this.injectedJustDown.add(action);
+        if (operation === 'press')
+            this.injectedPresses.add(action);
+        return true;
     }
     /** -1..1 axis from two actions (left/right by default). */
     axis(negative = 'left', positive = 'right') {
@@ -47,9 +78,16 @@ export class Input {
     /** Called by the Game at the end of each frame. */
     endFrame() {
         this.justDown.clear();
+        this.injectedJustDown.clear();
+        for (const action of this.injectedPresses)
+            this.injectedDown.delete(action);
+        this.injectedPresses.clear();
         this.used.clear();
     }
     dispose() {
+        this.injectedDown.clear();
+        this.injectedJustDown.clear();
+        this.injectedPresses.clear();
         window.removeEventListener('keydown', this.onKeyDown);
         window.removeEventListener('keyup', this.onKeyUp);
         window.removeEventListener('blur', this.releaseAll);

package/dist/runtime-bridge.d.ts

@@ -0,0 +1,69 @@
+import type { RuntimeSnapshot, RuntimeSnapshotFilters } from './runtime-inspection.js';
+export declare const RUNTIME_BRIDGE_PROTOCOL_VERSION: 1;
+export declare const RUNTIME_BRIDGE_SYMBOL: unique symbol;
+export type RuntimeMode = 'paused' | 'real-time';
+export interface RuntimeMetadata {
+    bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
+    engineVersion: string;
+    mode: RuntimeMode;
+    frame: number;
+    simulationTime: number;
+}
+export type RuntimeControlRequest = {
+    operation: 'press' | 'hold' | 'release';
+    action: string;
+} | {
+    operation: 'pause' | 'resume';
+} | {
+    operation: 'step';
+    dt?: number;
+    frames?: number;
+};
+export interface RuntimeControlResult extends RuntimeMetadata {
+    heldActions: string[];
+}
+export declare class RuntimeBridgeOperationError extends Error {
+    readonly code: 'runtime-invalid-state' | 'runtime-operation-failed';
+    readonly availableActions?: string[] | undefined;
+    readonly stage: 'control';
+    constructor(code: 'runtime-invalid-state' | 'runtime-operation-failed', message: string, availableActions?: string[] | undefined);
+}
+/** Engine-owned capability registered only in an MCP-activated page. */
+export interface RuntimeBridge {
+    readonly surface: HTMLCanvasElement;
+    metadata(): RuntimeMetadata;
+    inspect(filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
+    control(request: RuntimeControlRequest): RuntimeControlResult;
+}
+/** Ephemeral pre-page hook installed by the owner of a browser context. */
+export interface RuntimeBridgeActivation {
+    readonly protocolVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
+    register(bridge: RuntimeBridge): void;
+    unregister(bridge: RuntimeBridge): void;
+}
+export declare function activeRuntimeBridgeHook(): RuntimeBridgeActivation | null;
+export interface RuntimeBridgeHost {
+    step(dt: number): void;
+    resume(frame: (dt: number) => void): void;
+    pause(): void;
+    injectAction(action: string, operation: 'press' | 'hold' | 'release'): boolean;
+    availableActions(): string[];
+    heldActions(): string[];
+    inspect(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
+}
+export declare class EngineRuntimeBridge implements RuntimeBridge {
+    readonly surface: HTMLCanvasElement;
+    private readonly activation;
+    private readonly host;
+    readonly engineVersion: string;
+    private registered;
+    private mode;
+    private frame;
+    private simulationTime;
+    constructor(surface: HTMLCanvasElement, activation: RuntimeBridgeActivation, host: RuntimeBridgeHost);
+    metadata(): RuntimeMetadata;
+    inspect(filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
+    control(request: RuntimeControlRequest): RuntimeControlResult;
+    private advance;
+    unregister(): void;
+}

package/dist/runtime-bridge.js

@@ -0,0 +1,105 @@
+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');
+export class RuntimeBridgeOperationError extends Error {
+    code;
+    availableActions;
+    stage = 'control';
+    constructor(code, message, availableActions) {
+        super(message);
+        this.code = code;
+        this.availableActions = availableActions;
+        this.name = 'RuntimeBridgeOperationError';
+    }
+}
+export function activeRuntimeBridgeHook() {
+    const candidate = globalThis[RUNTIME_BRIDGE_SYMBOL];
+    if (!candidate || typeof candidate !== 'object')
+        return null;
+    const hook = candidate;
+    if (hook.protocolVersion !== RUNTIME_BRIDGE_PROTOCOL_VERSION ||
+        typeof hook.register !== 'function' ||
+        typeof hook.unregister !== 'function') {
+        return null;
+    }
+    return hook;
+}
+export class EngineRuntimeBridge {
+    surface;
+    activation;
+    host;
+    engineVersion = enginePackage.version;
+    registered = true;
+    mode = 'paused';
+    frame = 0;
+    simulationTime = 0;
+    constructor(surface, activation, host) {
+        this.surface = surface;
+        this.activation = activation;
+        this.host = host;
+    }
+    metadata() {
+        return {
+            bridgeVersion: RUNTIME_BRIDGE_PROTOCOL_VERSION,
+            engineVersion: this.engineVersion,
+            mode: this.mode,
+            frame: this.frame,
+            simulationTime: this.simulationTime,
+        };
+    }
+    inspect(filters = {}) {
+        return this.host.inspect(this.metadata(), filters);
+    }
+    control(request) {
+        switch (request.operation) {
+            case 'pause':
+                if (this.mode === 'real-time') {
+                    this.host.pause();
+                    this.mode = 'paused';
+                }
+                break;
+            case 'resume':
+                if (this.mode === 'paused') {
+                    this.mode = 'real-time';
+                    this.host.resume((dt) => this.advance(dt));
+                }
+                break;
+            case 'press':
+            case 'hold':
+            case 'release':
+                if (!this.host.injectAction(request.action, request.operation)) {
+                    const available = this.host.availableActions();
+                    throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unknown action "${request.action}". Available actions: ${available.join(', ') || '(none)'}.`, available);
+                }
+                break;
+            case 'step': {
+                if (this.mode !== 'paused') {
+                    throw new RuntimeBridgeOperationError('runtime-invalid-state', 'step is only available while the Runtime Bridge is paused.');
+                }
+                const dt = request.dt ?? 1 / 60;
+                const frames = request.frames ?? 1;
+                if (!Number.isFinite(dt) || dt <= 0 || dt > 0.1) {
+                    throw new RuntimeBridgeOperationError('runtime-operation-failed', 'dt must be finite and greater than 0 and at most 0.1.');
+                }
+                if (!Number.isInteger(frames) || frames < 1 || frames > 600) {
+                    throw new RuntimeBridgeOperationError('runtime-operation-failed', 'frames must be an integer from 1 through 600.');
+                }
+                for (let index = 0; index < frames; index += 1)
+                    this.advance(dt);
+                break;
+            }
+        }
+        return { ...this.metadata(), heldActions: this.host.heldActions() };
+    }
+    advance(dt) {
+        this.host.step(dt);
+        this.frame += 1;
+        this.simulationTime += dt;
+    }
+    unregister() {
+        if (!this.registered)
+            return;
+        this.registered = false;
+        this.activation.unregister(this);
+    }
+}

package/dist/runtime-inspection.d.ts

@@ -0,0 +1,71 @@
+import type { Game } from './game.js';
+import type { RuntimeMetadata } from './runtime-bridge.js';
+import type { StatValue } from './stats.js';
+export type ProjectionMarkerKind = 'cycle' | 'unsupported' | 'error' | 'truncated';
+export interface ProjectionMarker {
+    $waica: ProjectionMarkerKind | 'date' | 'bigint' | 'map' | 'set';
+    [key: string]: unknown;
+}
+export type ProjectedValue = null | boolean | number | string | ProjectionMarker | ProjectedValue[] | {
+    [key: string]: ProjectedValue;
+};
+export interface ProjectionIssue {
+    path: string;
+    marker: ProjectionMarkerKind;
+    omitted?: number;
+}
+export interface RuntimeSnapshotFilters {
+    entity_ids?: string[];
+    entity_names?: string[];
+    component_types?: string[];
+}
+export interface RuntimeTransformSnapshot {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+        order: string;
+    };
+    scale: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+export interface RuntimeComponentSnapshot {
+    type: string;
+    index: number;
+    state: ProjectedValue;
+}
+export interface RuntimeEntitySnapshot {
+    id: string;
+    name: string;
+    transform: RuntimeTransformSnapshot;
+    components: RuntimeComponentSnapshot[];
+}
+export interface RuntimeSnapshot extends RuntimeMetadata {
+    stats: Record<string, StatValue>;
+    entities: RuntimeEntitySnapshot[];
+    projectionIssues: ProjectionIssue[];
+}
+export declare const RUNTIME_PROJECTION_LIMITS: {
+    readonly depth: 5;
+    readonly entries: 100;
+    readonly stringBytes: number;
+    readonly componentBytes: number;
+    readonly snapshotBytes: number;
+};
+export declare class RuntimeInspector {
+    private readonly game;
+    private readonly ids;
+    private nextId;
+    constructor(game: Game);
+    snapshot(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
+    private capSnapshot;
+    private idFor;
+}

package/dist/runtime-inspection.js

@@ -0,0 +1,279 @@
+export const RUNTIME_PROJECTION_LIMITS = {
+    depth: 5,
+    entries: 100,
+    stringBytes: 4 * 1024,
+    componentBytes: 64 * 1024,
+    snapshotBytes: 1024 * 1024,
+};
+function marker(context, path, kind, detail = {}) {
+    context.issues.push({ path, marker: kind });
+    return { $waica: kind, ...detail };
+}
+function isPlainRecord(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+const textEncoder = new TextEncoder();
+function utf8Bytes(value) {
+    return textEncoder.encode(value).byteLength;
+}
+function stringPreview(value, byteLimit) {
+    let low = 0;
+    let high = value.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (utf8Bytes(value.slice(0, middle)) <= byteLimit)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    const preview = value.slice(0, low);
+    const last = preview.charCodeAt(preview.length - 1);
+    return last >= 0xd800 && last <= 0xdbff ? preview.slice(0, -1) : preview;
+}
+function projectValue(value, path, context, depth = 0) {
+    if (depth > RUNTIME_PROJECTION_LIMITS.depth) {
+        return marker(context, path, 'truncated', {
+            reason: 'depth',
+            maxDepth: RUNTIME_PROJECTION_LIMITS.depth,
+        });
+    }
+    if (value === null || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        const bytes = utf8Bytes(value);
+        if (bytes <= RUNTIME_PROJECTION_LIMITS.stringBytes)
+            return value;
+        return marker(context, path, 'truncated', {
+            reason: 'string',
+            preview: stringPreview(value, RUNTIME_PROJECTION_LIMITS.stringBytes),
+            originalLength: value.length,
+            originalBytes: bytes,
+        });
+    }
+    if (typeof value === 'bigint')
+        return { $waica: 'bigint', value: value.toString() };
+    if (typeof value === 'number') {
+        return Number.isFinite(value)
+            ? value
+            : marker(context, path, 'unsupported', { type: 'non-finite-number' });
+    }
+    if (typeof value !== 'object') {
+        return marker(context, path, 'unsupported', { type: typeof value });
+    }
+    const previousPath = context.seen.get(value);
+    if (previousPath)
+        return marker(context, path, 'cycle', { path: previousPath });
+    context.seen.set(value, path);
+    if (value instanceof Date) {
+        return Number.isFinite(value.getTime())
+            ? { $waica: 'date', value: value.toISOString() }
+            : marker(context, path, 'error', { message: 'Invalid Date' });
+    }
+    if (Array.isArray(value)) {
+        const entries = value.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
+            .map((entry, index) => projectValue(entry, `${path}[${index}]`, context, depth + 1));
+        const omitted = value.length - entries.length;
+        if (omitted > 0) {
+            entries.push(marker(context, path, 'truncated', { reason: 'entries', omitted }));
+        }
+        return entries;
+    }
+    if (value instanceof Map) {
+        const sourceEntries = [...value.entries()];
+        const entries = sourceEntries.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
+            .map(([key, entry], index) => [
+            projectValue(key, `${path}.entries[${index}].key`, context, depth + 1),
+            projectValue(entry, `${path}.entries[${index}].value`, context, depth + 1),
+        ]);
+        const omitted = sourceEntries.length - entries.length;
+        return {
+            $waica: 'map',
+            entries,
+            ...(omitted > 0
+                ? { truncated: marker(context, path, 'truncated', { reason: 'entries', omitted }) }
+                : {}),
+        };
+    }
+    if (value instanceof Set) {
+        const sourceValues = [...value];
+        const values = sourceValues.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
+            .map((entry, index) => projectValue(entry, `${path}.values[${index}]`, context, depth + 1));
+        const omitted = sourceValues.length - values.length;
+        return {
+            $waica: 'set',
+            values,
+            ...(omitted > 0
+                ? { truncated: marker(context, path, 'truncated', { reason: 'entries', omitted }) }
+                : {}),
+        };
+    }
+    if (isPlainRecord(value)) {
+        const keys = Object.keys(value).sort();
+        const projected = Object.fromEntries(keys.slice(0, RUNTIME_PROJECTION_LIMITS.entries)
+            .map((key) => [
+            key,
+            projectValue(value[key], `${path}.${key}`, context, depth + 1),
+        ]));
+        const omitted = keys.length - Object.keys(projected).length;
+        if (omitted === 0)
+            return projected;
+        return marker(context, path, 'truncated', {
+            reason: 'entries',
+            omitted,
+            value: projected,
+        });
+    }
+    return marker(context, path, 'unsupported', {
+        type: value.constructor?.name ?? 'object',
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function componentState(component, path, context) {
+    if (typeof component.inspectState === 'function') {
+        try {
+            return projectValue(component.inspectState(), path, context);
+        }
+        catch (error) {
+            return marker(context, path, 'error', { message: errorMessage(error) });
+        }
+    }
+    const keys = new Set(Object.keys(component));
+    for (let prototype = Object.getPrototypeOf(component); prototype && prototype !== Object.prototype; prototype = Object.getPrototypeOf(prototype)) {
+        for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(prototype))) {
+            if (typeof descriptor.set === 'function')
+                keys.add(key);
+        }
+    }
+    const state = {};
+    for (const key of [...keys].sort()) {
+        if (key === 'entity' || key === 'game' || key.startsWith('_'))
+            continue;
+        const valuePath = `${path}.${key}`;
+        try {
+            const value = component[key];
+            if (typeof value === 'function')
+                continue;
+            state[key] = projectValue(value, valuePath, context, 1);
+        }
+        catch (error) {
+            state[key] = marker(context, valuePath, 'error', { message: errorMessage(error) });
+        }
+    }
+    return state;
+}
+function boundedComponentState(component, path, context) {
+    const state = componentState(component, path, context);
+    const originalBytes = utf8Bytes(JSON.stringify(state));
+    if (originalBytes <= RUNTIME_PROJECTION_LIMITS.componentBytes)
+        return state;
+    return marker(context, path, 'truncated', {
+        reason: 'component-size',
+        limit: RUNTIME_PROJECTION_LIMITS.componentBytes,
+        originalBytes,
+        path,
+    });
+}
+export class RuntimeInspector {
+    game;
+    ids = new WeakMap();
+    nextId = 1;
+    constructor(game) {
+        this.game = game;
+    }
+    snapshot(metadata, filters = {}) {
+        const projectionIssues = [];
+        const idFilter = filters.entity_ids ? new Set(filters.entity_ids) : null;
+        const nameFilter = filters.entity_names ? new Set(filters.entity_names) : null;
+        const componentFilter = filters.component_types ? new Set(filters.component_types) : null;
+        const live = this.game.entities.map((entity) => ({ entity, id: this.idFor(entity) }));
+        const entities = live.flatMap(({ entity, id }) => {
+            if (idFilter && !idFilter.has(id))
+                return [];
+            if (nameFilter && !nameFilter.has(entity.name))
+                return [];
+            const components = entity.components.flatMap((component, index) => {
+                const Class = component.constructor;
+                if (componentFilter && !componentFilter.has(Class.componentName))
+                    return [];
+                const context = { issues: projectionIssues, seen: new Map() };
+                return [{
+                        type: Class.componentName,
+                        index,
+                        state: boundedComponentState(component, `entities[${id}].components[${index}].state`, context),
+                    }];
+            });
+            if (componentFilter && components.length === 0)
+                return [];
+            return [{
+                    id,
+                    name: entity.name,
+                    transform: {
+                        position: {
+                            x: entity.position.x,
+                            y: entity.position.y,
+                            z: entity.position.z,
+                        },
+                        rotation: {
+                            x: entity.node.rotation.x,
+                            y: entity.node.rotation.y,
+                            z: entity.node.rotation.z,
+                            order: entity.node.rotation.order,
+                        },
+                        scale: {
+                            x: entity.scale.x,
+                            y: entity.scale.y,
+                            z: entity.scale.z,
+                        },
+                    },
+                    components,
+                }];
+        });
+        return this.capSnapshot({
+            ...metadata,
+            stats: Object.fromEntries([...this.game.stats.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
+            entities,
+            projectionIssues,
+        });
+    }
+    capSnapshot(snapshot) {
+        if (utf8Bytes(JSON.stringify(snapshot)) <= RUNTIME_PROJECTION_LIMITS.snapshotBytes) {
+            return snapshot;
+        }
+        const retained = [...snapshot.entities];
+        const removedIds = new Set();
+        while (retained.length > 0) {
+            const removed = retained.pop();
+            if (removed)
+                removedIds.add(removed.id);
+            const omitted = snapshot.entities.length - retained.length;
+            const projectionIssues = snapshot.projectionIssues
+                .filter((issue) => [...removedIds].every((id) => !issue.path.startsWith(`entities[${id}]`)))
+                .concat({ path: `entities[${retained.length}]`, marker: 'truncated', omitted });
+            const candidate = { ...snapshot, entities: retained, projectionIssues };
+            if (utf8Bytes(JSON.stringify(candidate)) <= RUNTIME_PROJECTION_LIMITS.snapshotBytes) {
+                return candidate;
+            }
+        }
+        return {
+            ...snapshot,
+            entities: [],
+            projectionIssues: [{
+                    path: 'entities[0]',
+                    marker: 'truncated',
+                    omitted: snapshot.entities.length,
+                }],
+        };
+    }
+    idFor(entity) {
+        const existing = this.ids.get(entity);
+        if (existing)
+            return existing;
+        const id = `entity-${this.nextId}`;
+        this.nextId += 1;
+        this.ids.set(entity, id);
+        return id;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",
@@ -10,7 +10,8 @@
     "directory": "packages/engine"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "exports": {
     ".": {