@aura3d/engine 1.0.3 → 1.0.5

package/dist/engine/agent-api/index.js

@@ -1,5 +1,42 @@
 import { PhysicsDebugDraw, PhysicsStepper, PhysicsWorld, ScenePhysicsBridge, Shape as PhysicsShapeFactory } from "../../physics/index.js";
+import { createFrameLoop } from "./FrameLoop.js";
+import { createCombatWorld, createGameCameraDirector, createGameEffects, applyGameCombatEventsToRuntime, createGameAccessibilityFocus, createGameAccessibilityLabel, createGameAccessibilityRuntimeSettings, createGameHighContrastSource, createGameHudBindings, createGameHudComboBinding, createGameHudDebugToggleBinding, createGameHudHealthBinding, createGameHudMeterBinding, createGameHudRoundBinding, createGameHudSnapshot, createGameHudTimerBinding, createGameBoxCollider, createGameCapsuleCollider, createGameColliderDebugGeometry, createGameCombatDebugGeometry, createGameDebugOverlayData, createGameDebugSceneNodes, createGameHitboxDebugGeometry, createGameFighting2DRules, createGameInput, createGameInputReplay, createGameInputReplayDriver, createGameJumpAssist, createGameKinematicBody, createGamePauseControlsSource, createGameRectCollider, createGameReducedFlashSource, createGameReducedMotionSource, createGameSphereCollider, createGameTouchControlLayout, gameColliderAabb, gameColliders, gameEffectPresets, gameGuardboxes, gameHitboxes, gameHurtboxes, gameInputReplayEventsAt, gamePushboxes, gameTriggerVolumes } from "./GameRuntime.js";
+import { collectGameRuntimeEvidence as collectGameRuntimeEvidenceV105 } from "./GameEvidence.js";
+import { calculateRuntimeNodeBounds } from "./RuntimeNodeHandle.js";
+import { createRuntimeNodeSpec } from "./GameSceneBridge.js";
+import { createFightingGameKit, fighting as fightingGameKit } from "./game-kits/fighting.js";
+import { createPromptAnimationEpisodePlan, createPromptAnimationStoryBible, definePromptAnimationStoryboard } from "./PromptAnimationContract.js";
+import { applyShotPlaybackFrame, createShotPlaybackPlan, createShotTimeline, installShotPlayback, sampleShotPlaybackPlan } from "./ShotTimeline.js";
+import { captionCueAtTime, createCaptionTimingProof, deriveCaptionTrackFromDialogue } from "./DialoguePerformance.js";
+import { createAuraVoiceVisemeTrack, createGlbBlendshapeVisemeCue, createPrimitiveMouthVisemeCues, sampleVisemeTrack } from "./VisemeController.js";
+import { createAuraVoiceBridgePackage, createAuraVoiceDubRerenderProof, createAuraVoiceRerenderPlan, sampleAuraVoiceBridgeAtTime } from "./AuraVoiceBridge.js";
+import { createCartoonDirectorPlan } from "./CartoonDirector.js";
+import { createCartoonPerformance } from "./CartoonPerformance.js";
+import { createCartoonRenderOutputPackageMetadata, createCartoonRenderQueue } from "./CartoonRenderQueue.js";
+import { collectPromptAnimationEvidence } from "./PromptAnimationEvidence.js";
 export { Engine } from "../../core/index.js";
+export { asAuraAppHandle, isAuraAppHandle } from "./AuraAppHandle.js";
+export { FrameLoop, createFrameLoop } from "./FrameLoop.js";
+export { createCombatWorld, createGameCameraDirector, createGameEffects, applyGameCombatEventsToRuntime, createGameAccessibilityFocus, createGameAccessibilityLabel, createGameAccessibilityRuntimeSettings, createGameHighContrastSource, createGameHudBindings, createGameHudComboBinding, createGameHudDebugToggleBinding, createGameHudHealthBinding, createGameHudMeterBinding, createGameHudRoundBinding, createGameHudSnapshot, createGameHudTimerBinding, createGameBoxCollider, createGameCapsuleCollider, createGameColliderDebugGeometry, createGameCombatDebugGeometry, createGameDebugOverlayData, createGameDebugSceneNodes, createGameHitboxDebugGeometry, createGameInput, createGameInputReplay, createGameInputReplayDriver, createGameJumpAssist, createGameKinematicBody, createGamePauseControlsSource, createGameRectCollider, createGameReducedFlashSource, createGameReducedMotionSource, createGameSphereCollider, createGameTouchControlLayout, gameColliderAabb, gameColliders, gameInputReplayEventsAt, createGameLoopPlan } from "./GameRuntime.js";
+export { collectGameSceneRuntimeNodes, createGameSceneBridge, createRuntimeNodeSpec } from "./GameSceneBridge.js";
+export { calculateRuntimeNodeBounds, createRuntimeNodeEffectAttachment, runtimeNodeHasTag } from "./RuntimeNodeHandle.js";
+export { createFightingGameKit, fighting, fighterRuntimeNode } from "./game-kits/fighting.js";
+export { gameKits } from "./game-kits/index.js";
+export * from "./GameAssetValidation.js";
+export * from "./CharacterAssembly.js";
+export * from "./AssetEvidence.js";
+export * from "./AnimationController.js";
+export { gameAssetValidation, quaterniusGameReadyFighterValidationContract, validateQuaterniusGameReadyFighterAsset } from "./GameAssetValidation.js";
+export { createAnimationController } from "./AnimationController.js";
+export * from "./PromptAnimationContract.js";
+export * from "./AuraVoiceBridge.js";
+export * from "./ShotTimeline.js";
+export * from "./DialoguePerformance.js";
+export * from "./VisemeController.js";
+export * from "./PromptAnimationEvidence.js";
+export * from "./CartoonDirector.js";
+export * from "./CartoonPerformance.js";
+export * from "./CartoonRenderQueue.js";
 const auraAssetRefBrand = Symbol("AuraAssetRef");
 export function defineAuraAssets(definitions) {
     const refs = {};
@@ -45,6 +82,9 @@ export class AuraNodeBuilder {
     physics(spec) {
         return this.with({ physics: spec });
     }
+    runtime(spec) {
+        return this.with({ runtime: { mutable: true, ...spec } });
+    }
     toJSON() {
         return this.value;
     }
@@ -2876,6 +2916,8 @@ export const games = {
     miniGolfCourse: () => prefabs.miniGolfCourse(),
     createMiniGolfState: () => createMiniGolfStateController(),
     miniGolfPointerShot: miniGolfPointerShotFromDrag,
+    fighting: fightingGameKit,
+    createFightingGameKit,
     miniGolfScene: () => scene()
         .background("#12321d")
         .addMany(prefabs.miniGolfHole())
@@ -2883,6 +2925,321 @@ export const games = {
         .camera(camera.follow({ targetNode: "white physics golf ball", distance: 4.2 }))
         .timeline(timeline.loop({ seconds: 8 }))
 };
+export function collectGameRuntimeEvidence(app, options = {}) {
+    return collectGameRuntimeEvidenceV105(app, options);
+}
+function createGameInputController(options) {
+    const actions = options.actions;
+    const axes = options.axes ?? {};
+    const bufferMs = options.bufferMs ?? 120;
+    const activeBindings = new Set();
+    const activeActionOverrides = new Set();
+    const previousHeld = new Map();
+    const currentHeld = new Map();
+    const pressedEdges = new Set();
+    const releasedEdges = new Set();
+    const lastPressedAt = new Map();
+    const replayEvents = [];
+    let frame = 0;
+    let time = 0;
+    let latestSnapshot = {
+        kind: "aura-game-input-snapshot",
+        frame,
+        time,
+        activeBindings: [],
+        actions: {}
+    };
+    const resolveHeld = (action) => {
+        if (activeActionOverrides.has(action))
+            return true;
+        const bindings = actions[action] ?? [];
+        return bindings.some((binding) => activeBindings.has(binding));
+    };
+    const record = (type, binding) => {
+        replayEvents.push({ frame, time, type, binding });
+    };
+    const pressBinding = (binding, shouldRecord = true) => {
+        activeBindings.add(binding);
+        if (actions[binding])
+            activeActionOverrides.add(binding);
+        if (shouldRecord)
+            record("press", binding);
+    };
+    const releaseBinding = (binding, shouldRecord = true) => {
+        activeBindings.delete(binding);
+        activeActionOverrides.delete(binding);
+        if (shouldRecord)
+            record("release", binding);
+    };
+    const toSnapshot = () => {
+        const actionStates = {};
+        const nowMs = time * 1000;
+        for (const action of Object.keys(actions)) {
+            const held = currentHeld.get(action) ?? false;
+            actionStates[action] = {
+                pressed: pressedEdges.has(action),
+                held,
+                released: releasedEdges.has(action),
+                buffered: pressedEdges.has(action) || nowMs - (lastPressedAt.get(action) ?? Number.NEGATIVE_INFINITY) <= bufferMs,
+                value: held ? 1 : 0
+            };
+        }
+        return {
+            kind: "aura-game-input-snapshot",
+            frame,
+            time,
+            activeBindings: [...activeBindings].sort(),
+            actions: actionStates
+        };
+    };
+    const update = (dt = 1 / 60) => {
+        frame += 1;
+        time += Math.max(0, dt);
+        pressedEdges.clear();
+        releasedEdges.clear();
+        for (const action of Object.keys(actions)) {
+            const held = resolveHeld(action);
+            const wasHeld = previousHeld.get(action) ?? false;
+            currentHeld.set(action, held);
+            if (held && !wasHeld) {
+                pressedEdges.add(action);
+                lastPressedAt.set(action, time * 1000);
+            }
+            if (!held && wasHeld)
+                releasedEdges.add(action);
+            previousHeld.set(action, held);
+        }
+        latestSnapshot = toSnapshot();
+        return latestSnapshot;
+    };
+    const target = options.target ?? (typeof window !== "undefined" ? window : undefined);
+    const onKeyDown = (event) => {
+        const keyboard = event;
+        if (keyboard.repeat)
+            return;
+        if (keyboard.code)
+            pressBinding(keyboard.code);
+        if (keyboard.key && keyboard.key !== keyboard.code)
+            pressBinding(keyboard.key);
+    };
+    const onKeyUp = (event) => {
+        const keyboard = event;
+        if (keyboard.code)
+            releaseBinding(keyboard.code);
+        if (keyboard.key && keyboard.key !== keyboard.code)
+            releaseBinding(keyboard.key);
+    };
+    if (options.autoListen !== false && target?.addEventListener) {
+        target.addEventListener("keydown", onKeyDown);
+        target.addEventListener("keyup", onKeyUp);
+    }
+    return {
+        kind: "aura-game-input-plan",
+        actions,
+        axes,
+        bufferMs,
+        update,
+        snapshot() {
+            return latestSnapshot;
+        },
+        pressed(action) {
+            return pressedEdges.has(action);
+        },
+        held(action) {
+            return currentHeld.get(action) ?? resolveHeld(action);
+        },
+        released(action) {
+            return releasedEdges.has(action);
+        },
+        buffered(action, windowMs = bufferMs) {
+            return pressedEdges.has(action) || time * 1000 - (lastPressedAt.get(action) ?? Number.NEGATIVE_INFINITY) <= windowMs;
+        },
+        axis(name, negativeAction, positiveAction) {
+            const binding = axes[name];
+            const negative = negativeAction ?? binding?.negative;
+            const positive = positiveAction ?? binding?.positive;
+            if (!negative && !positive)
+                return this.held(name) ? 1 : 0;
+            return (positive && this.held(positive) ? 1 : 0) - (negative && this.held(negative) ? 1 : 0);
+        },
+        press(binding) {
+            pressBinding(binding);
+        },
+        release(binding) {
+            releaseBinding(binding);
+        },
+        setAction(action, held) {
+            if (held) {
+                activeActionOverrides.add(action);
+                record("press", action);
+            }
+            else {
+                activeActionOverrides.delete(action);
+                record("release", action);
+            }
+        },
+        recorded() {
+            return [...replayEvents];
+        },
+        replay(events) {
+            activeBindings.clear();
+            activeActionOverrides.clear();
+            for (const event of events) {
+                if (event.type === "press")
+                    pressBinding(event.binding, false);
+                else
+                    releaseBinding(event.binding, false);
+            }
+            return update(0);
+        },
+        clearReplay() {
+            replayEvents.length = 0;
+        },
+        dispose() {
+            if (target?.removeEventListener) {
+                target.removeEventListener("keydown", onKeyDown);
+                target.removeEventListener("keyup", onKeyUp);
+            }
+            activeBindings.clear();
+            activeActionOverrides.clear();
+            previousHeld.clear();
+            currentHeld.clear();
+            pressedEdges.clear();
+            releasedEdges.clear();
+        }
+    };
+}
+export function createAuraGameRules(options = {}) {
+    return {
+        kind: "aura-game-rules",
+        gravity: options.gravity ?? 24,
+        roundSeconds: options.roundSeconds ?? 90,
+        maxHealth: options.maxHealth ?? 100,
+        maxGuard: options.maxGuard ?? 100,
+        maxMeter: options.maxMeter ?? 100,
+        stageBounds: options.stageBounds ?? {
+            minX: -4.5,
+            maxX: 4.5
+        }
+    };
+}
+export const gameRules = Object.assign(createAuraGameRules, {
+    fighting2D: createGameFighting2DRules
+});
+export function createAuraGameRuntime(options = {}) {
+    return {
+        kind: "aura-game-runtime",
+        loop: {
+            kind: "aura-game-loop-plan",
+            fixedDt: options.loop?.fixedDt ?? 1 / 60,
+            maxSubSteps: options.loop?.maxSubSteps ?? 5,
+            timeScale: options.loop?.timeScale ?? 1
+        },
+        rules: createAuraGameRules(options.rules),
+        input: options.input ? createGameInput(options.input) : undefined,
+        combat: createCombatWorld(),
+        camera: createGameCameraDirector({
+            stageBounds: {
+                minX: options.rules?.stageBounds?.minX ?? -4.5,
+                maxX: options.rules?.stageBounds?.maxX ?? 4.5
+            }
+        }),
+        effects: createGameEffects({ poolSize: options.effectPoolSize }),
+        bodies: []
+    };
+}
+export const game = {
+    createRuntime: createAuraGameRuntime,
+    rules: gameRules,
+    loop: (options = {}) => ({
+        kind: "aura-game-loop-plan",
+        fixedDt: options.fixedDt ?? 1 / 60,
+        maxSubSteps: options.maxSubSteps ?? 5,
+        timeScale: options.timeScale ?? 1
+    }),
+    frameLoop: createFrameLoop,
+    runtimeNode: createRuntimeNodeSpec,
+    input: createGameInput,
+    inputReplay: createGameInputReplay,
+    inputReplayDriver: createGameInputReplayDriver,
+    inputReplayEventsAt: gameInputReplayEventsAt,
+    touchControls: createGameTouchControlLayout,
+    kinematicBody: createGameKinematicBody,
+    jumpAssist: createGameJumpAssist,
+    collider: {
+        box: createGameBoxCollider,
+        sphere: createGameSphereCollider,
+        capsule: createGameCapsuleCollider,
+        rect: createGameRectCollider,
+        aabb: gameColliderAabb,
+        factories: gameColliders
+    },
+    hitbox: gameHitboxes,
+    hurtbox: gameHurtboxes,
+    guardbox: gameGuardboxes,
+    pushbox: gamePushboxes,
+    trigger: gameTriggerVolumes,
+    combatWorld: createCombatWorld,
+    combatEvents: applyGameCombatEventsToRuntime,
+    cameraDirector: createGameCameraDirector,
+    effects: createGameEffects,
+    effectPresets: gameEffectPresets,
+    debug: {
+        colliders: createGameColliderDebugGeometry,
+        hitboxes: createGameHitboxDebugGeometry,
+        combat: createGameCombatDebugGeometry,
+        overlay: createGameDebugOverlayData,
+        sceneNodes: createGameDebugSceneNodes
+    },
+    hud: {
+        health: createGameHudHealthBinding,
+        meter: createGameHudMeterBinding,
+        timer: createGameHudTimerBinding,
+        combo: createGameHudComboBinding,
+        round: createGameHudRoundBinding,
+        debugToggle: createGameHudDebugToggleBinding,
+        bindings: createGameHudBindings,
+        snapshot: createGameHudSnapshot
+    },
+    accessibility: {
+        label: createGameAccessibilityLabel,
+        focus: createGameAccessibilityFocus,
+        reducedMotion: createGameReducedMotionSource,
+        reducedFlash: createGameReducedFlashSource,
+        highContrast: createGameHighContrastSource,
+        pauseControls: createGamePauseControlsSource,
+        settings: createGameAccessibilityRuntimeSettings
+    },
+    fighting: createFightingGameKit,
+    evidence: collectGameRuntimeEvidence
+};
+export const cartoon = {
+    episodePlan: createPromptAnimationEpisodePlan,
+    storyBible: createPromptAnimationStoryBible,
+    storyboard: definePromptAnimationStoryboard,
+    shotTimeline: createShotTimeline,
+    shotPlaybackPlan: createShotPlaybackPlan,
+    sampleShotPlaybackPlan,
+    applyShotPlaybackFrame,
+    installShotPlayback,
+    captionsFromDialogue: deriveCaptionTrackFromDialogue,
+    captionCueAtTime,
+    captionTimingProof: createCaptionTimingProof,
+    visemeTrack: createAuraVoiceVisemeTrack,
+    primitiveMouthVisemes: createPrimitiveMouthVisemeCues,
+    glbBlendshapeViseme: createGlbBlendshapeVisemeCue,
+    sampleVisemeTrack,
+    auraVoiceBridgePackage: createAuraVoiceBridgePackage,
+    sampleAuraVoiceBridgeAtTime,
+    auraVoiceRerenderPlan: createAuraVoiceRerenderPlan,
+    auraVoiceDubRerenderProof: createAuraVoiceDubRerenderProof,
+    director: createCartoonDirectorPlan,
+    performance: createCartoonPerformance,
+    renderQueue: createCartoonRenderQueue,
+    renderOutputPackage: createCartoonRenderOutputPackageMetadata,
+    evidence: collectPromptAnimationEvidence
+};
+export const animationStudio = cartoon;
 function collectParticleBudgetDiagnostics(nodes) {
     const flattened = groups.flatten(nodes);
     const particleEffects = flattened.filter((node) => node.kind === "effect" && node.effect === "particles");
@@ -3500,6 +3857,7 @@ export const character = {
     lowPolyHumanoid: (options = {}) => createLowPolyHumanoid(options),
     authoredHumanoid: (options = {}) => createAuthoredLowPolyHumanoid(options),
     primitiveHumanoid: (options = {}) => createHierarchicalPrimitiveHumanoid(options),
+    performance: createCartoonPerformance,
     importedRigRuntime: async (options) => {
         markAuraLazySystemRequested("character-rig", "character.importedRigRuntime");
         const started = performanceNow();
@@ -4278,17 +4636,46 @@ export const sceneKits = {
     humanoidWalk: (options = {}) => makeSceneKit("humanoidWalk", options),
     productViewer: (asset, options = {}) => makeSceneKit("productViewer", { ...options, asset })
 };
+export function promptSubjectIsResolved(s) {
+    return "asset" in s;
+}
+export async function resolvePromptPlanSubject(plan, resolver) {
+    if (promptSubjectIsResolved(plan.subject)) {
+        return plan;
+    }
+    const intent = plan.subject;
+    const result = await resolver.resolve({ text: intent.intent, constraints: intent.constraints });
+    if (!result) {
+        throw new Error(`No auto-pullable asset matched the prompt-plan intent "${intent.intent}". ` +
+            "Refine the intent or constraints (maxTriangles/license/animated), or provide a concrete typed asset " +
+            "(e.g. a file via `assets add` / a typed asset ref) before compiling.");
+    }
+    const resolvedSubject = {
+        asset: result.asset,
+        ...(intent.label !== undefined ? { label: intent.label } : {})
+    };
+    return { ...plan, subject: resolvedSubject };
+}
 export function definePromptPlan(plan) {
     return plan;
 }
+function requireResolvedPromptSubject(plan) {
+    if (!promptSubjectIsResolved(plan.subject)) {
+        throw new Error(`Cannot compile a prompt plan whose subject is still an unresolved intent ("${plan.subject.intent}"). ` +
+            "Resolve the prompt-plan subject first via resolvePromptPlanSubject(...) or the CLI `assets search`; " +
+            "compile needs a concrete typed asset.");
+    }
+    return plan.subject;
+}
 export function compilePromptPlan(plan) {
-    const sceneBuilder = promptRecipes[plan.sceneType](plan.subject.asset, plan);
+    const subject = requireResolvedPromptSubject(plan);
+    const sceneBuilder = promptRecipes[plan.sceneType](subject.asset, plan);
     return {
         scene: sceneBuilder,
         report: {
             schema: "aura3d-prompt-plan-report/1.0",
             sceneType: plan.sceneType,
-            subjectAssetId: plan.subject.asset.id,
+            subjectAssetId: subject.asset.id,
             recipe: plan.sceneType,
             cameraPreset: plan.camera?.preset ?? defaultCameraPreset(plan.sceneType),
             lightingPreset: plan.lighting?.preset ?? defaultLightingPreset(plan.sceneType),
@@ -4485,6 +4872,10 @@ function repairHintsForPromptPlan(plan) {
 function promptPlanWarnings(plan) {
     const warnings = [];
     const acceptanceCriteria = plan.acceptanceCriteria.map((item) => item.trim()).filter(Boolean);
+    if (!promptSubjectIsResolved(plan.subject)) {
+        warnings.push(`PromptPlan subject is still an unresolved intent ("${plan.subject.intent}"); resolve it via resolvePromptPlanSubject(...) ` +
+            "or the CLI `assets search` to a concrete typed asset before compiling.");
+    }
     if (!plan.subject.label?.trim()) {
         warnings.push("PromptPlan subject is missing a human-readable label; add one so reports and diagnostics describe the visible subject.");
     }
@@ -4522,6 +4913,217 @@ export class AuraRuntimeError extends Error {
         this.code = code;
     }
 }
+function createAuraRuntimeNodeRegistry(snapshot) {
+    let handles = new Map();
+    const registry = {
+        get(id) {
+            return handles.get(id);
+        },
+        require(id) {
+            const handle = handles.get(id);
+            if (!handle) {
+                throw new AuraRuntimeError("missing-asset", `Aura3D runtime node "${id}" was not found. Suggested fix: add .runtime({ id: "${id}" }) to the model, primitive, group, or label you want to mutate.`);
+            }
+            return handle;
+        },
+        has(id) {
+            return handles.has(id);
+        },
+        ids() {
+            return [...handles.keys()];
+        },
+        all() {
+            return [...handles.values()];
+        },
+        reset(nextSnapshot) {
+            handles = collectRuntimeNodeHandles(nextSnapshot);
+        }
+    };
+    registry.reset(snapshot);
+    return registry;
+}
+function collectRuntimeNodeHandles(snapshot) {
+    const next = new Map();
+    for (const node of snapshot.nodes) {
+        const runtime = "runtime" in node ? node.runtime : undefined;
+        if (!runtime?.id)
+            continue;
+        next.set(runtime.id, createRuntimeNodeHandle(node, runtime));
+    }
+    return next;
+}
+function createRuntimeNodeHandle(node, runtime) {
+    const tags = runtime.tags ?? [];
+    const attachedEffects = [];
+    const morphTargetWeights = new Map();
+    let animationBinding;
+    let animationPose;
+    let animationPoseBinding;
+    const getVisible = () => node.kind === "model" ? node.visible !== false : node.visible !== false;
+    const getBounds = () => calculateRuntimeNodeBounds({
+        position: node.position,
+        scale: node.scale,
+        size: "size" in node ? node.size : undefined
+    });
+    return {
+        id: runtime.id,
+        kind: node.kind,
+        name: "name" in node ? node.name : undefined,
+        tags,
+        get position() {
+            return node.position ?? [0, 0, 0];
+        },
+        set position(next) {
+            node.position = next;
+        },
+        get rotation() {
+            return node.rotation ?? [0, 0, 0];
+        },
+        set rotation(next) {
+            node.rotation = next;
+        },
+        get scale() {
+            return node.scale ?? 1;
+        },
+        set scale(next) {
+            node.scale = next;
+        },
+        get visible() {
+            return getVisible();
+        },
+        set visible(next) {
+            node.visible = next;
+        },
+        setPosition(x, y, z) {
+            node.position = [x, y, z];
+            return this;
+        },
+        translate(x, y, z) {
+            const current = node.position ?? [0, 0, 0];
+            node.position = [current[0] + x, current[1] + y, current[2] + z];
+            return this;
+        },
+        setRotation(x, y, z) {
+            node.rotation = [x, y, z];
+            return this;
+        },
+        setScale(scale) {
+            node.scale = scale;
+            return this;
+        },
+        setVisible(visible) {
+            node.visible = visible;
+            return this;
+        },
+        setMaterial(nextMaterial) {
+            node.material = nextMaterial;
+            return this;
+        },
+        play(clip, options = {}) {
+            node.animation = { ...options, clip };
+            return this;
+        },
+        setAnimation(animation) {
+            node.animation = animation;
+            return this;
+        },
+        setAnimationBinding(binding) {
+            animationBinding = binding;
+            return this;
+        },
+        setAnimationPose(pose, metadata) {
+            animationPose = pose ? cloneRuntimeAnimationPose(pose) : undefined;
+            animationPoseBinding = pose ? metadata : undefined;
+            if (pose?.morphTargets) {
+                for (const [name, weight] of Object.entries(pose.morphTargets)) {
+                    const normalizedName = name.trim();
+                    if (normalizedName) {
+                        morphTargetWeights.set(normalizedName, sanitizeRuntimeMorphWeight(weight));
+                    }
+                }
+            }
+            return this;
+        },
+        animationPose() {
+            return animationPose ? cloneRuntimeAnimationPose(animationPose) : undefined;
+        },
+        setMorphTarget(name, weight) {
+            const normalizedName = name.trim();
+            if (!normalizedName) {
+                throw new AuraRuntimeError("missing-asset", "Aura3D morph target name is required.");
+            }
+            morphTargetWeights.set(normalizedName, sanitizeRuntimeMorphWeight(weight));
+            return this;
+        },
+        setMorphTargets(weights) {
+            morphTargetWeights.clear();
+            for (const [name, weight] of Object.entries(weights)) {
+                const normalizedName = name.trim();
+                if (normalizedName) {
+                    morphTargetWeights.set(normalizedName, sanitizeRuntimeMorphWeight(weight));
+                }
+            }
+            return this;
+        },
+        morphTargets() {
+            return Object.fromEntries(morphTargetWeights.entries());
+        },
+        bounds() {
+            return getBounds();
+        },
+        attachEffect(effect) {
+            attachedEffects.push(effect);
+            return this;
+        },
+        effects() {
+            return [...attachedEffects];
+        },
+        snapshot() {
+            return {
+                id: runtime.id,
+                kind: node.kind,
+                name: "name" in node ? node.name : undefined,
+                tags,
+                position: node.position ?? [0, 0, 0],
+                rotation: node.rotation ?? [0, 0, 0],
+                scale: node.scale ?? 1,
+                visible: getVisible(),
+                animation: node.animation,
+                animationBinding,
+                animationPose: animationPose ? cloneRuntimeAnimationPose(animationPose) : undefined,
+                animationPoseBinding,
+                morphTargets: Object.fromEntries(morphTargetWeights.entries()),
+                bounds: getBounds(),
+                effects: [...attachedEffects]
+            };
+        }
+    };
+}
+function cloneRuntimeAnimationPose(pose) {
+    return {
+        bones: Object.fromEntries(Object.entries(pose.bones ?? {}).map(([bone, transform]) => [
+            bone,
+            {
+                position: transform.position ? { ...transform.position } : undefined,
+                rotation: transform.rotation ? { ...transform.rotation } : undefined,
+                scale: transform.scale ? { ...transform.scale } : undefined
+            }
+        ])),
+        morphTargets: pose.morphTargets ? { ...pose.morphTargets } : undefined,
+        rootMotion: pose.rootMotion
+            ? {
+                translation: pose.rootMotion.translation ? { ...pose.rootMotion.translation } : undefined,
+                rotation: pose.rootMotion.rotation ? { ...pose.rootMotion.rotation } : undefined
+            }
+            : undefined,
+        metadata: pose.metadata ? { ...pose.metadata } : undefined
+    };
+}
+function sanitizeRuntimeMorphWeight(weight) {
+    if (!Number.isFinite(weight))
+        return 0;
+    return Math.max(0, Math.min(1, weight));
+}
 export function createAuraApp(target, options) {
     let snapshot = normalizeSceneSnapshot(options.scene);
     let renderSnapshot = flattenSceneSnapshot(snapshot);
@@ -4537,6 +5139,32 @@ export function createAuraApp(target, options) {
     let lastTime = 0;
     let mountRevision = 0;
     let canvasRuntimePhysics;
+    const runtimeNodes = createAuraRuntimeNodeRegistry(renderSnapshot);
+    const frameCallbacks = new Set();
+    let runtimePaused = options.autoStart === false;
+    let runtimeFrame = 0;
+    let runtimeTime = 0;
+    const runtimeFixedDt = 1 / 60;
+    let runtimeAlpha = 0;
+    const ownedInputControllers = new Set();
+    const runRuntimeFrame = (dt, source) => {
+        runtimeFrame += 1;
+        runtimeTime += dt;
+        runtimeAlpha = runtimeFixedDt > 0 ? Math.max(0, Math.min(1, (dt % runtimeFixedDt) / runtimeFixedDt)) : 0;
+        const frame = {
+            dt,
+            fixedDt: runtimeFixedDt,
+            time: runtimeTime,
+            frame: runtimeFrame,
+            alpha: runtimeAlpha,
+            paused: runtimePaused,
+            source,
+            substep: 1,
+            substeps: 1
+        };
+        for (const callback of [...frameCallbacks])
+            callback(frame);
+    };
     const shouldUseProductionRendererForCurrentScene = () => Boolean(canvas && renderSnapshot.nodes.some(isWebGLRenderableNode) && typeof window !== "undefined");
     const resetDiagnosticsForCurrentScene = (backend) => {
         const fresh = createInitialDiagnostics(renderSnapshot);
@@ -4557,7 +5185,11 @@ export function createAuraApp(target, options) {
             return;
         const delta = lastTime > 0 ? Math.max(1, time - lastTime) : 16.67;
         lastTime = time;
-        canvasRuntimePhysics?.step(delta / 1000);
+        const dt = delta / 1000;
+        if (!runtimePaused) {
+            runRuntimeFrame(dt, "raf");
+            canvasRuntimePhysics?.step(dt);
+        }
         diagnosticsState.evidence = collectAuraSceneEvidence(renderSnapshot);
         diagnosticsState.fps = Math.round(1000 / delta);
         diagnosticsState.drawCalls = renderSceneToCanvas(canvas, renderSnapshot, time);
@@ -4584,7 +5216,7 @@ export function createAuraApp(target, options) {
         overlay?.update();
         const revision = ++mountRevision;
         if (shouldUseProductionRenderer && canvas) {
-            void startProductionRender(canvas, renderSnapshot, diagnosticsState, options, overlay)
+            void startProductionRender(canvas, renderSnapshot, diagnosticsState, options, overlay, runRuntimeFrame, () => runtimePaused)
                 .then((controller) => {
                 if (disposed || revision !== mountRevision) {
                     controller.dispose();
@@ -4618,11 +5250,71 @@ export function createAuraApp(target, options) {
         setScene(nextScene) {
             snapshot = normalizeSceneSnapshot(nextScene);
             renderSnapshot = flattenSceneSnapshot(snapshot);
+            runtimeNodes.reset(renderSnapshot);
             mountCurrentScene();
         },
+        nodes: runtimeNodes,
+        get runtime() {
+            return {
+                paused: runtimePaused,
+                frame: runtimeFrame,
+                time: runtimeTime,
+                fixedDt: runtimeFixedDt,
+                alpha: runtimeAlpha
+            };
+        },
+        onFrame(callback) {
+            frameCallbacks.add(callback);
+            return () => {
+                frameCallbacks.delete(callback);
+            };
+        },
+        offFrame(callback) {
+            frameCallbacks.delete(callback);
+        },
+        input(inputOptions) {
+            const controller = createGameInput(inputOptions);
+            ownedInputControllers.add(controller);
+            return controller;
+        },
+        pause() {
+            runtimePaused = true;
+        },
+        resume() {
+            runtimePaused = false;
+            if (!animationHandle && !productionController && options.autoStart !== false && typeof requestAnimationFrame !== "undefined") {
+                animationHandle = requestAnimationFrame(render);
+            }
+        },
+        step(dt = 1 / 60) {
+            const seconds = Math.max(0, dt);
+            runRuntimeFrame(seconds, "manual");
+            canvasRuntimePhysics?.step(seconds);
+            const previousPaused = runtimePaused;
+            runtimePaused = true;
+            if (productionController) {
+                productionController.render(performanceNow());
+            }
+            else {
+                render(performanceNow());
+            }
+            runtimePaused = previousPaused;
+        },
         diagnostics() {
             return snapshotDiagnostics(diagnosticsState);
         },
+        evidence(evidenceOptions = {}) {
+            return collectGameRuntimeEvidenceV105({
+                runtime: {
+                    paused: runtimePaused,
+                    frame: runtimeFrame,
+                    time: runtimeTime,
+                    fixedDt: runtimeFixedDt,
+                    alpha: runtimeAlpha
+                },
+                nodes: runtimeNodes
+            }, evidenceOptions);
+        },
         screenshot() {
             return captureAuraScreenshot(canvas);
         },
@@ -4630,6 +5322,9 @@ export function createAuraApp(target, options) {
             disposed = true;
             if (animationHandle && typeof cancelAnimationFrame !== "undefined")
                 cancelAnimationFrame(animationHandle);
+            for (const controller of ownedInputControllers)
+                controller.dispose();
+            ownedInputControllers.clear();
             productionController?.dispose();
             overlay?.dispose();
         }
@@ -4653,6 +5348,10 @@ export function collectAuraSceneEvidence(sceneValue) {
     const assetProvenance = snapshot.nodes
         .filter((node) => node.kind === "model")
         .map((node) => createAssetProvenance(node.asset));
+    const runtimeNodeIds = snapshot.nodes
+        .map((node) => "runtime" in node ? node.runtime?.id : undefined)
+        .filter((id) => Boolean(id));
+    const expectsGameRuntime = runtimeNodeIds.length > 0 || interactionNodes.some((node) => node.mode === "keyboard" || node.mode === "drag-vector" || node.mode === "click-impulse");
     return {
         physics: {
             worldAttached: Boolean(snapshot.physics),
@@ -4690,6 +5389,31 @@ export function collectAuraSceneEvidence(sceneValue) {
             collisionAvoidance: labelNodes.filter((node) => node.collisionAvoidance === true).length
         },
         performance: createPerformanceEvidence(snapshot),
+        gameRuntime: collectGameRuntimeEvidenceV105({
+            runtime: {
+                frame: 0,
+                time: 0,
+                paused: true
+            },
+            nodes: {
+                ids: () => runtimeNodeIds
+            }
+        }, {
+            animation: {
+                controllers: animatedNodes.length,
+                activeClips: clips,
+                eventCount: 0
+            },
+            assets: {
+                typedAssets: assetProvenance.filter((asset) => asset.source === "typed-aura-assets-manifest").length,
+                missingAssets: []
+            },
+            source: {
+                mode: "scene-source",
+                expectsGame: expectsGameRuntime,
+                label: "collectAuraSceneEvidence"
+            }
+        }),
         rendering: createRendererDiagnosticReport(snapshot),
         assets: assetProvenance
     };
@@ -4810,7 +5534,7 @@ function isRenderableModelNode(node) {
 function isWebGLRenderableNode(node) {
     return isRenderableModelNode(node) || node.kind === "primitive";
 }
-async function startProductionRender(canvas, snapshot, diagnosticsState, options, overlay) {
+async function startProductionRender(canvas, snapshot, diagnosticsState, options, overlay, beforeRender, isPaused = () => false) {
     const renderableNode = snapshot.nodes.find(isWebGLRenderableNode);
     if (!renderableNode) {
         throw new AuraRuntimeError("missing-asset", "Aura3D production rendering requires at least one typed model asset or primitive. Suggested fix: add model(assets.product), primitives.box(), primitives.sphere(), primitives.cylinder(), or primitives.plane().");
@@ -4820,9 +5544,14 @@ async function startProductionRender(canvas, snapshot, diagnosticsState, options
     const continuousRender = shouldContinuouslyRender(snapshot);
     let disposed = false;
     let animationHandle = 0;
+    let lastTime = 0;
     const renderFrame = (time = performanceNow()) => {
         if (disposed)
             return;
+        const delta = lastTime > 0 ? Math.max(1, time - lastTime) : 16.67;
+        lastTime = time;
+        if (!isPaused())
+            beforeRender?.(delta / 1000, "raf");
         const drawCalls = renderer.render(time);
         diagnosticsState.backend = "webgl2";
         diagnosticsState.fps = diagnosticsState.fps || 60;
@@ -4837,6 +5566,9 @@ async function startProductionRender(canvas, snapshot, diagnosticsState, options
     };
     renderFrame();
     return {
+        render(time = performanceNow()) {
+            renderFrame(time);
+        },
         dispose() {
             disposed = true;
             if (animationHandle && typeof cancelAnimationFrame !== "undefined")
@@ -4851,6 +5583,8 @@ function shouldContinuouslyRender(snapshot) {
     if (snapshot.camera.mode === "dolly" || snapshot.camera.mode === "follow" || snapshot.camera.mode === "path" || snapshot.camera.mode === "flythrough")
         return true;
     return snapshot.nodes.some((node) => {
+        if ("runtime" in node && node.runtime?.mutable !== false)
+            return true;
         if ((node.kind === "model" || node.kind === "primitive") && node.animation)
             return true;
         if (node.kind !== "effect")
@@ -6179,7 +6913,7 @@ function normalizeSceneSnapshot(value) {
 }
 function resolveCanvas(target) {
     if (!target) {
-        throw new AuraRuntimeError("missing-canvas", "Aura3D could not mount because the app target was null or undefined. Suggested fix: pass a selector like createAuraApp(\"#app\", ...) or check document.querySelector before mounting.");
+        return undefined;
     }
     if (typeof target === "string") {
         if (typeof document === "undefined") {