@aura3d/engine 1.4.5 → 1.5.1

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

@@ -1,8 +1,18 @@
 import { PhysicsDebugDraw, PhysicsStepper, PhysicsWorld, ScenePhysicsBridge, Shape as PhysicsShapeFactory } from "../../physics/index.js";
 import { createExternalParityEnvironmentLighting, Geometry, IndexBuffer, PBRMaterial, ProductionRuntimeRenderer, VertexBuffer, VertexFormat } from "../../rendering/index.js";
-import { DirectionalLight } from "../../scene/index.js";
+import { DirectionalLight, PointLight, SpotLight } from "../../scene/index.js";
 import { createTypedGLBActor } from "../production-runtime/TypedGLBActor.js";
 import { AURA_NORMALIZED_MODEL_MAX_DIMENSION, boundsFromAsset, boundsHeight, boundsMaxDimension, boundsSize } from "./SceneGroundingUtils.js";
+import { createWorldLabelLayer } from "./WorldLabelRenderer.js";
+export * from "./SpatialAnchoring.js";
+export * from "./FocusSelection.js";
+export * from "./WorldLabelRenderer.js";
+export * from "./VehicleChassis.js";
+export * from "./VehicleDriverAi.js";
+export * from "./PlatformerMotion.js";
+export * from "./CombatFrameData.js";
+export * from "./SceneQueries.js";
+export * from "./ApplicationKits.js";
 export * from "./FrameEncoder.js";
 export * from "./BrowserFrameCaptureAdapter.js";
 export * from "./MediaRecorderFrameEncoder.js";
@@ -35,6 +45,9 @@ export * from "./CloudRenderAdapter.js";
 export * from "./BatchEpisodeRenderer.js";
 export * from "./AnimationAssetManifest.js";
 export * from "./SceneGroundingUtils.js";
+export * from "./SubjectFramingUtils.js";
+export * from "./LayeredSceneComposition.js";
+export * from "./TouchControlBinding.js";
 export * from "./AssetLibraryBrowser.js";
 export * from "./DialogueAlignment.js";
 export * from "./PerformancePoseEditor.js";
@@ -98,6 +111,9 @@ export * from "./AnimationPerformance.js";
 export * from "./AnimationRenderQueue.js";
 export * from "./AnimationAssetManifest.js";
 export * from "./SceneGroundingUtils.js";
+export * from "./SubjectFramingUtils.js";
+export * from "./LayeredSceneComposition.js";
+export * from "./TouchControlBinding.js";
 export * from "./AssetLibraryBrowser.js";
 const auraAssetRefBrand = Symbol("AuraAssetRef");
 export function defineAuraAssets(definitions) {
@@ -1735,7 +1751,17 @@ function createRendererDiagnosticReport(snapshot, runtime, rendererOptions) {
             antiBlowout: bloom?.antiBlowout ?? true
         },
         shadows: {
-            enabled: true,
+            // Never a source-authored `true`. When the runtime is mounted this is the
+            // device-observed shadow-map state; when it is not mounted the scene has
+            // only requested shadows and nothing has been proven yet.
+            enabled: runtime?.mounted ? Boolean(runtime.shadow?.mapSampled) : false,
+            requested: runtime?.shadow?.requested ?? false,
+            mapRendered: runtime?.shadow?.mapRendered ?? false,
+            mapSampled: runtime?.shadow?.mapSampled ?? false,
+            mapSize: runtime?.shadow?.mapSize,
+            label: runtime?.shadow?.label,
+            nativeShadowMapBindings: runtime?.shadow?.nativeShadowMapBindings ?? 0,
+            shadowRenderTargetsAllocated: runtime?.shadow?.shadowRenderTargetsAllocated ?? 0,
             contactShadows,
             mapType: "pcf-soft"
         },
@@ -4325,7 +4351,12 @@ export function createGamePlatformerPresentationSurfaceNodes(options) {
         const point = options.sceneBinding.toScenePoint(checkpoint, 0.02);
         nodes.push(primitives.box({
             name: `scene-bound platformer checkpoint ${checkpoint.id}`,
-            material: material.emissive({ color: "#d7f9ff", emissive: "#a6f4ff", emissiveIntensity: 0.48, roughness: 0.4 })
+            material: material.emissive({
+                color: options.checkpointColor ?? "#d7f9ff",
+                emissive: options.checkpointColor ?? "#a6f4ff",
+                emissiveIntensity: 0.48,
+                roughness: 0.4
+            })
         })
             .position(point[0], point[1], point[2] + (isGameLevel ? 0.29 : 0.19))
             .scale([0.026, 0.22, 0.034])
@@ -7052,6 +7083,66 @@ function isRenderableModelNode(node) {
 function isWebGLRenderableNode(node) {
     return isRenderableModelNode(node) || node.kind === "primitive";
 }
+/**
+ * Translate scene label nodes into world-anchored labels for the label layer.
+ *
+ * `labels.callout(...)` and friends previously reached the scene snapshot and were
+ * counted by evidence but drawn only by the canvas2d fallback. Every route with a
+ * typed GLB takes the production WebGL2 path, so every production callout was
+ * silently dropped. This is the bridge that makes the public label API real in the
+ * path public routes actually use.
+ */
+function worldLabelsFromSnapshot(snapshot, runtimeNodes) {
+    const labelNodes = groups.flatten(snapshot.nodes).filter((node) => node.kind === "label");
+    return labelNodes.map((node, index) => {
+        const runtimeId = node.runtime?.id;
+        const runtimeSnapshot = runtimeId ? runtimeNodes?.get(runtimeId)?.snapshot() : undefined;
+        if (runtimeSnapshot?.visible === false) {
+            return {
+                id: node.name ?? `${node.label}-${index + 1}`,
+                text: node.text,
+                anchor: [0, 0, 0],
+                offscreenPolicy: "hide"
+            };
+        }
+        const position = (runtimeSnapshot?.position ?? node.position ?? labelDefaultPosition(node));
+        const anchor = node.anchorWorldPosition ?? position;
+        // Screen offset is derived from the gap between the label box and its anchor,
+        // projected as a vertical nudge. A label that requests no separate anchor sits
+        // directly on its own position.
+        const separated = node.anchorWorldPosition !== undefined;
+        return {
+            id: node.name ?? `${node.label}-${index + 1}`,
+            text: node.text,
+            anchor: [position[0], position[1], position[2]],
+            leaderAnchor: [anchor[0], anchor[1], anchor[2]],
+            screenOffset: separated ? [0, 0] : [0, -26],
+            color: typeof node.color === "string" ? node.color : undefined,
+            background: typeof node.background === "string" ? node.background : undefined,
+            // `size` is authored in world units for scene labels; map it onto a legible
+            // pixel range rather than using it directly as a font size.
+            fontSize: Math.max(11, Math.min(26, Math.round((node.size ?? 0.34) * 46))),
+            leader: node.leader === true,
+            offscreenPolicy: node.offscreenPolicy ?? (node.label === "hud" ? "draw" : "clamp"),
+            ...(node.label === "hud" && node.screenAnchor ? { screenAnchor: node.screenAnchor } : {}),
+            ...(node.label === "hud" && !node.screenAnchor ? { screenAnchor: "top-left" } : {})
+        };
+    });
+}
+/**
+ * Mount the world-label layer for a canvas, if the scene has any label nodes.
+ *
+ * Returns `undefined` in headless or label-free scenes so nothing is created that
+ * would then need disposing.
+ */
+function createSceneLabelLayer(canvas, snapshot) {
+    if (!canvas || typeof document === "undefined")
+        return undefined;
+    const hasLabels = groups.flatten(snapshot.nodes).some((node) => node.kind === "label");
+    if (!hasLabels)
+        return undefined;
+    return createWorldLabelLayer({ container: canvas.parentElement ?? document.body, canvas });
+}
 async function startProductionRender(canvas, snapshot, diagnosticsState, options, overlay, beforeRender, isPaused = () => false, runtimeNodes) {
     const renderableNode = snapshot.nodes.find(isWebGLRenderableNode);
     if (!renderableNode) {
@@ -7060,6 +7151,7 @@ async function startProductionRender(canvas, snapshot, diagnosticsState, options
     const renderer = await createProductionSceneRenderer(canvas, snapshot, options.renderer, runtimeNodes);
     diagnosticsState.renderer = renderer.diagnostics;
     const continuousRender = shouldContinuouslyRender(snapshot);
+    const labelLayer = createSceneLabelLayer(canvas, snapshot);
     let disposed = false;
     let animationHandle = 0;
     let lastTime = 0;
@@ -7077,6 +7169,13 @@ async function startProductionRender(canvas, snapshot, diagnosticsState, options
         diagnosticsState.renderSize = [canvas.width, canvas.height];
         diagnosticsState.evidence = collectAuraSceneEvidence(snapshot);
         diagnosticsState.renderer = renderer.diagnostics;
+        if (labelLayer) {
+            // Reproject every frame against the renderer's own camera so labels track
+            // their anchors while the camera moves.
+            labelLayer.setLabels(worldLabelsFromSnapshot(snapshot, runtimeNodes));
+            labelLayer.update(renderer.viewProjection(time));
+            diagnosticsState.labels = labelLayer.snapshot();
+        }
         overlay?.update();
         if (continuousRender && options.autoStart !== false && typeof requestAnimationFrame !== "undefined") {
             animationHandle = requestAnimationFrame(renderFrame);
@@ -7091,6 +7190,7 @@ async function startProductionRender(canvas, snapshot, diagnosticsState, options
             disposed = true;
             if (animationHandle && typeof cancelAnimationFrame !== "undefined")
                 cancelAnimationFrame(animationHandle);
+            labelLayer?.dispose();
             renderer.dispose();
         }
     };
@@ -7131,38 +7231,7 @@ async function createProductionSceneRenderer(canvas, snapshot, rendererOptions,
         ], runtimeNodes);
     }
 }
-const PRODUCTION_RUNTIME_POSTPROCESS = {
-    targetFormat: "rgba8",
-    toneMapping: {
-        exposure: 1.14,
-        whitePoint: 1.18,
-        operator: "filmic",
-        inputColorSpace: "linear",
-        outputColorSpace: "srgb"
-    },
-    colorGrade: {
-        contrast: 1.1,
-        saturation: 1.06,
-        vibrance: 0.12,
-        vignette: 0.08,
-        sharpening: 0.24
-    },
-    fxaa: {
-        edgeThreshold: 0.08,
-        subpixelBlend: 0.55
-    }
-};
-const PRODUCTION_RUNTIME_SHADOWS = {
-    enabled: true,
-    size: 1024,
-    bias: 0.0014,
-    strength: 0.28,
-    pcfRadius: 1.2,
-    pcfSamples: 9,
-    filter: "pcf",
-    label: "aura3d-root-production-shadow-map"
-};
-let cachedProductionRuntimeLights;
+let cachedProductionRuntimeFallbackLights;
 function createProductionRuntimeEnvironment(snapshot) {
     const names = groups.flatten(snapshot.nodes).map((node) => "name" in node ? node.name?.toLowerCase() ?? "" : "");
     const category = resolveRendererSceneCategory(snapshot, names);
@@ -7179,11 +7248,149 @@ function createProductionRuntimeEnvironment(snapshot) {
         lighting: bundle.lighting
     };
 }
-function createProductionRuntimePostprocess() {
-    return PRODUCTION_RUNTIME_POSTPROCESS;
+/**
+ * Translates a public `effects.fog(...)` node into renderer forward-pass fog.
+ *
+ * Without this the root bridge never set `environmentFog`, so `effects.fog()` was
+ * accepted by the scene builder, reported as `fog.enabled` in diagnostics, and
+ * changed exactly zero pixels through `createAuraApp`. Returning `false` when no
+ * fog node is authored keeps the unfogged path unchanged.
+ */
+function createProductionRuntimeEnvironmentFog(snapshot) {
+    const fog = groups.flatten(snapshot.nodes).find((node) => node.kind === "effect" && node.effect === "fog");
+    if (!fog)
+        return false;
+    const density = clampNumber(fog.density ?? 0.12, 0, 1);
+    const intensity = clampNumber(fog.intensity ?? 0.5, 0, 1);
+    const color = colorToRgb(fog.color ?? "#9fb7d9");
+    return {
+        // Exponential-squared reads as depth haze rather than a hard linear band, which
+        // matches what the public helper documents.
+        mode: "exponential-squared",
+        color: [color[0], color[1], color[2]],
+        near: 1,
+        far: 60,
+        density,
+        maxOpacity: clampNumber(0.25 + intensity * 0.55, 0, 0.92)
+    };
 }
-function createProductionRuntimeShadowOptions() {
-    return PRODUCTION_RUNTIME_SHADOWS;
+function createProductionRuntimePostprocess(snapshot) {
+    const nodes = groups.flatten(snapshot.nodes);
+    const names = nodes.map((node) => "name" in node ? node.name?.toLowerCase() ?? "" : "");
+    const category = resolveRendererSceneCategory(snapshot, names);
+    const authoredBloom = nodes.find((node) => node.kind === "effect" && node.effect === "bloom");
+    const emissiveSubjects = nodes.filter((node) => {
+        if (!("material" in node) || !node.material)
+            return false;
+        return Boolean(node.material.emissive) && (node.material.emissiveIntensity ?? 1) > 0;
+    }).length;
+    const darkScene = ["neon", "city-night", "space", "game"].includes(category);
+    const bloomRequested = Boolean(authoredBloom) || (darkScene && emissiveSubjects > 0);
+    // Root previously advertised `ssao` in `requestedPasses` whenever a scene added
+    // effects.ambientOcclusion() or effects.contactOcclusion(), but never submitted
+    // an `ssao` option to the renderer. The advertised pass could therefore never
+    // run, and `ambientOcclusionPass` was permanently false. Submit the real option
+    // so the request and the rendered pass agree.
+    const authoredAmbientOcclusion = nodes.find((node) => node.kind === "effect" && node.effect === "ambient-occlusion");
+    const authoredContactOcclusion = nodes.find((node) => node.kind === "effect" && node.effect === "contact-occlusion");
+    const authoredOcclusion = authoredAmbientOcclusion ?? authoredContactOcclusion;
+    const exposure = category === "city-day" ? 1.02
+        : category === "material" || category === "product" ? 1.08
+            : category === "space" ? 1.18
+                : 1.12;
+    const saturation = category === "material" || category === "product" ? 1.01
+        : category === "city-day" ? 1.04
+            : 1.1;
+    return {
+        targetFormat: "rgba8",
+        ...(bloomRequested ? {
+            bloom: {
+                threshold: clampNumber(authoredBloom?.threshold ?? (darkScene ? 0.68 : 0.78), 0, 1),
+                intensity: clampNumber(authoredBloom?.intensity ?? Math.min(0.5, 0.24 + emissiveSubjects * 0.035), 0, 2),
+                radius: Math.max(1, Math.min(4, Math.round(authoredBloom?.radius ?? (category === "space" ? 3 : 2))))
+            }
+        } : {}),
+        ...(authoredOcclusion ? {
+            ssao: {
+                // The renderer's SSAO radius is an integer sample-kernel size in pixels
+                // (1-8), while the public effect `radius` is a world-space extent whose
+                // default is 0.42. Passing the authored value straight through threw
+                // "SSAO radius must be an integer in [1, 8]" and left the route with zero
+                // draw calls, so it is mapped onto the kernel range instead.
+                radius: Math.max(1, Math.min(8, Math.round((authoredOcclusion.radius ?? 0.42) * 8))),
+                intensity: clampNumber(authoredOcclusion.intensity ?? 0.32, 0, 1),
+                bias: 0.025
+            }
+        } : {}),
+        toneMapping: {
+            exposure,
+            whitePoint: category === "city-day" ? 1.28 : 1.18,
+            operator: "filmic",
+            inputColorSpace: "linear",
+            outputColorSpace: "srgb"
+        },
+        colorGrade: {
+            contrast: category === "material" || category === "product" ? 1.06 : 1.1,
+            saturation,
+            vibrance: darkScene ? 0.14 : 0.06,
+            vignette: category === "game" || category === "neon" ? 0.1 : 0.04,
+            sharpening: category === "material" || category === "product" ? 0.28 : 0.2
+        },
+        fxaa: {
+            edgeThreshold: category === "game" ? 0.07 : 0.09,
+            subpixelBlend: category === "material" || category === "product" ? 0.48 : 0.58
+        }
+    };
+}
+function createProductionRuntimeShadowOptions(snapshot, collectedLights) {
+    const nodes = groups.flatten(snapshot.nodes);
+    const names = nodes.map((node) => "name" in node ? node.name?.toLowerCase() ?? "" : "");
+    const category = resolveRendererSceneCategory(snapshot, names);
+    const sceneRadius = nodes.reduce((radius, node) => {
+        const position = "position" in node && Array.isArray(node.position)
+            ? node.position
+            : [0, 0, 0];
+        const nodeScale = "scale" in node ? node.scale : undefined;
+        const scale = typeof nodeScale === "number"
+            ? Math.abs(nodeScale)
+            : Array.isArray(nodeScale) ? Math.max(...nodeScale.map(Math.abs)) : 1;
+        return Math.max(radius, Math.hypot(...position) + scale);
+    }, 1);
+    const shadowCaster = collectedLights.find((light) => light.castsShadow);
+    const size = sceneRadius > 30 ? 4096 : sceneRadius > 10 ? 2048 : 1024;
+    const texelWorldSize = (sceneRadius * 2) / size;
+    return {
+        enabled: Boolean(shadowCaster),
+        size,
+        bias: clampNumber(texelWorldSize * 0.55, 0.00035, 0.004),
+        strength: category === "city-day" ? 0.38
+            : category === "material" || category === "product" ? 0.24
+                : 0.32,
+        pcfRadius: size >= 2048 ? 1.5 : 1.2,
+        pcfSamples: size >= 2048 ? 16 : 9,
+        filter: "pcf",
+        label: `aura3d-root-production-${category}-${size}px-shadow-map`
+    };
+}
+/**
+ * Device-observed shadow state. `requested` comes from the submitted shadow
+ * options, but `mapRendered`/`mapSampled` come only from what the device
+ * actually did: a shadow depth target has to exist and a shader has to bind and
+ * sample it. This is what stops the root report from publishing an unconditional
+ * `shadows.enabled: true`.
+ */
+function createProductionRuntimeShadowObservation(shadowOptions, diagnostics) {
+    const nativeShadowMapBindings = diagnostics.nativeShadowMapBindings ?? 0;
+    const mapRendered = Boolean(shadowOptions.enabled) && (diagnostics.shadowRenderTargetsAllocated ?? 0) > 0;
+    return {
+        requested: Boolean(shadowOptions.enabled),
+        mapRendered,
+        mapSampled: mapRendered && nativeShadowMapBindings > 0,
+        mapSize: shadowOptions.size,
+        label: shadowOptions.label,
+        nativeShadowMapBindings,
+        shadowRenderTargetsAllocated: diagnostics.shadowRenderTargetsAllocated ?? 0
+    };
 }
 function createProductionRuntimePostprocessObservation(diagnostics) {
     const actualPasses = diagnostics.postprocessPassNames ?? [];
@@ -7199,22 +7406,150 @@ function createProductionRuntimePostprocessObservation(diagnostics) {
         fallbackPasses: pixelBacked ? [] : ["direct-render"]
     };
 }
-function createProductionRuntimeCollectedLights() {
-    if (cachedProductionRuntimeLights)
-        return cachedProductionRuntimeLights;
-    const key = new DirectionalLight("aura3d-root-production-key-shadow");
-    const fill = new DirectionalLight("aura3d-root-production-fill");
-    const rim = new DirectionalLight("aura3d-root-production-rim");
-    key.castsShadow = true;
-    key.color = [1, 0.94, 0.82];
-    key.intensity = 2.6;
-    fill.color = [0.52, 0.64, 0.9];
-    fill.intensity = 0.64;
-    rim.color = [0.88, 0.94, 1];
-    rim.intensity = 0.88;
-    cachedProductionRuntimeLights = [
+function createProductionRuntimeCollectedLights(snapshot) {
+    const authoredLights = groups.flatten(snapshot.nodes).filter((node) => node.kind === "light");
+    const descriptors = authoredLights.flatMap((node, index) => createProductionRuntimeLightDescriptors(node, index));
+    if (descriptors.length === 0)
+        return createProductionRuntimeFallbackLights();
+    const shadowCasterIndex = descriptors.reduce((selected, descriptor, index) => {
+        if (selected < 0)
+            return index;
+        const current = descriptors[selected];
+        if (descriptor.shadowPriority !== current.shadowPriority) {
+            return descriptor.shadowPriority > current.shadowPriority ? index : selected;
+        }
+        return descriptor.intensity > current.intensity ? index : selected;
+    }, -1);
+    return descriptors.map((descriptor, index) => createProductionRuntimeCollectedLight(descriptor, index === shadowCasterIndex));
+}
+function createProductionRuntimeLightDescriptors(node, authoredIndex) {
+    const name = node.name?.trim() || `aura-authored-${node.light}-${authoredIndex + 1}`;
+    const color = colorToRgb(node.color ?? "#ffffff");
+    const intensity = nonNegativeFinite(node.intensity);
+    const position = productionRuntimeLightPosition(node);
+    const direction = productionRuntimeLightDirection(node, position);
+    if (node.light === "ambient") {
+        // CollectedLight intentionally represents direct lights only. Ambient light remains
+        // environment-lighting intent and does not masquerade as a directional light.
+        return [];
+    }
+    if (node.light === "directional") {
+        return [{
+                kind: "directional",
+                name,
+                color,
+                intensity,
+                position,
+                direction,
+                range: 0,
+                spotAngle: 0,
+                penumbra: 0,
+                shadowPriority: 3,
+                authoredLight: node.light
+            }];
+    }
+    if (node.light === "point") {
+        return [{
+                kind: "point",
+                name,
+                color,
+                intensity,
+                position,
+                direction,
+                range: 10 * productionRuntimeLightMaxScale(node.scale),
+                spotAngle: 0,
+                penumbra: 0,
+                shadowPriority: 1,
+                authoredLight: node.light
+            }];
+    }
+    if (node.light === "studio") {
+        return createProductionRuntimeStudioLightDescriptors(node, name, color, intensity, position);
+    }
+    const width = positiveFinite(node.width, node.light === "softbox" ? 2.4 : 2.2)
+        * productionRuntimeLightAxisScale(node.scale, 0);
+    const height = positiveFinite(node.height, node.light === "softbox" ? 1.6 : 1.2)
+        * productionRuntimeLightAxisScale(node.scale, 1);
+    const target = node.lookAt ?? [0, 0.75, 0];
+    const targetDistance = Math.max(0.001, distance3(position, target));
+    const halfDiagonal = Math.hypot(width, height) / 2;
+    return [{
+            kind: "spot",
+            name: `${name}-${node.light}-spot-proxy`,
+            color,
+            intensity,
+            position,
+            direction,
+            range: Math.max(1, targetDistance + halfDiagonal * 2),
+            spotAngle: clampNumber(Math.atan2(halfDiagonal, targetDistance), 0.08, Math.PI / 2 - 0.01),
+            penumbra: node.light === "softbox" ? 0.78 : 0.42,
+            shadowPriority: 2,
+            authoredLight: node.light,
+            authoredWidth: width,
+            authoredHeight: height
+        }];
+}
+function createProductionRuntimeStudioLightDescriptors(node, name, color, intensity, position) {
+    const target = node.lookAt ?? [0, 0.75, 0];
+    const fillPosition = [
+        position[0] === 0 ? 3.2 : -position[0],
+        Math.max(1, position[1] * 0.72),
+        position[2] * 0.58
+    ];
+    const rimPosition = [
+        position[0] * 0.2,
+        Math.max(1, position[1] * 0.88),
+        position[2] === 0 ? -3.6 : -Math.abs(position[2])
+    ];
+    return [
         {
             kind: "directional",
+            name: `${name}-key`,
+            color,
+            intensity,
+            position,
+            direction: productionRuntimeLightDirection(node, position),
+            range: 0,
+            spotAngle: 0,
+            penumbra: 0,
+            shadowPriority: 3,
+            authoredLight: node.light
+        },
+        {
+            kind: "directional",
+            name: `${name}-fill`,
+            color: multiplyRgb(color, [0.62, 0.72, 1]),
+            intensity: intensity * 0.32,
+            position: fillPosition,
+            direction: normalizedDirection(fillPosition, target),
+            range: 0,
+            spotAngle: 0,
+            penumbra: 0,
+            shadowPriority: 0,
+            authoredLight: node.light
+        },
+        {
+            kind: "directional",
+            name: `${name}-rim`,
+            color: multiplyRgb(color, [0.84, 0.92, 1]),
+            intensity: intensity * 0.54,
+            position: rimPosition,
+            direction: normalizedDirection(rimPosition, target),
+            range: 0,
+            spotAngle: 0,
+            penumbra: 0,
+            shadowPriority: 0,
+            authoredLight: node.light
+        }
+    ];
+}
+function createProductionRuntimeFallbackLights() {
+    if (cachedProductionRuntimeFallbackLights)
+        return cachedProductionRuntimeFallbackLights;
+    const descriptors = [
+        {
+            kind: "directional",
+            name: "aura3d-root-production-fallback-key-shadow",
             color: [1, 0.94, 0.82],
             intensity: 2.6,
             position: [0, 0, 0],
@@ -7222,12 +7557,12 @@ function createProductionRuntimeCollectedLights() {
             range: 0,
             spotAngle: 0,
             penumbra: 0,
-            castsShadow: true,
-            layerMask: 0xffffffff,
-            source: key
+            shadowPriority: 3,
+            authoredLight: "fallback"
         },
         {
             kind: "directional",
+            name: "aura3d-root-production-fallback-fill",
             color: [0.52, 0.64, 0.9],
             intensity: 0.64,
             position: [0, 0, 0],
@@ -7235,12 +7570,12 @@ function createProductionRuntimeCollectedLights() {
             range: 0,
             spotAngle: 0,
             penumbra: 0,
-            castsShadow: false,
-            layerMask: 0xffffffff,
-            source: fill
+            shadowPriority: 0,
+            authoredLight: "fallback"
         },
         {
             kind: "directional",
+            name: "aura3d-root-production-fallback-rim",
             color: [0.88, 0.94, 1],
             intensity: 0.88,
             position: [0, 0, 0],
@@ -7248,12 +7583,120 @@ function createProductionRuntimeCollectedLights() {
             range: 0,
             spotAngle: 0,
             penumbra: 0,
-            castsShadow: false,
-            layerMask: 0xffffffff,
-            source: rim
+            shadowPriority: 0,
+            authoredLight: "fallback"
         }
     ];
-    return cachedProductionRuntimeLights;
+    cachedProductionRuntimeFallbackLights = descriptors.map((descriptor, index) => createProductionRuntimeCollectedLight(descriptor, index === 0));
+    return cachedProductionRuntimeFallbackLights;
+}
+function createProductionRuntimeCollectedLight(descriptor, castsShadow) {
+    const source = descriptor.kind === "directional"
+        ? new DirectionalLight(descriptor.name)
+        : descriptor.kind === "point"
+            ? new PointLight(descriptor.name)
+            : new SpotLight(descriptor.name);
+    source.color = [...descriptor.color];
+    source.intensity = descriptor.intensity;
+    source.castsShadow = castsShadow;
+    source.layerMask = 0xffffffff;
+    source.userData.aura3dAuthoredLight = descriptor.authoredLight;
+    if (descriptor.authoredWidth !== undefined)
+        source.userData.aura3dAuthoredWidth = descriptor.authoredWidth;
+    if (descriptor.authoredHeight !== undefined)
+        source.userData.aura3dAuthoredHeight = descriptor.authoredHeight;
+    source.transform.setPosition(...descriptor.position);
+    if (source instanceof PointLight || source instanceof SpotLight) {
+        source.range = Math.max(0.001, descriptor.range);
+    }
+    if (source instanceof SpotLight) {
+        source.angle = clampNumber(descriptor.spotAngle, 0.001, Math.PI / 2 - 0.001);
+        source.penumbra = clampNumber(descriptor.penumbra, 0, 1);
+    }
+    if (!(source instanceof PointLight)) {
+        const rotation = quaternionFromForwardDirection(descriptor.direction);
+        source.transform.setRotation(...rotation);
+    }
+    source.updateWorldTransform(true);
+    return {
+        kind: descriptor.kind,
+        color: descriptor.color,
+        intensity: descriptor.intensity,
+        position: descriptor.position,
+        direction: normalize3(descriptor.direction),
+        range: descriptor.range,
+        spotAngle: descriptor.spotAngle,
+        penumbra: descriptor.penumbra,
+        castsShadow,
+        layerMask: 0xffffffff,
+        source
+    };
+}
+function productionRuntimeLightPosition(node) {
+    const fallback = node.light === "directional" ? [3, 4, 3]
+        : node.light === "point" ? [2, 2.5, 1.5]
+            : node.light === "studio" ? [0, 3, 4]
+                : node.light === "softbox" ? [-2.2, 2.4, 2.2]
+                    : node.light === "rect" ? [0, 2.6, 1.8]
+                        : [0, 0, 0];
+    const position = node.position ?? fallback;
+    return position.map((component, index) => Number.isFinite(component) ? component : fallback[index]);
+}
+function productionRuntimeLightDirection(node, position) {
+    if (node.lookAt) {
+        const direction = normalizedDirection(position, node.lookAt);
+        if (length3(direction) > 0)
+            return direction;
+    }
+    if (node.rotation) {
+        const matrix = rotationXYZ(node.rotation);
+        return normalize3([-matrix[8], -matrix[9], -matrix[10]]);
+    }
+    if (length3(position) > 0.000001)
+        return normalize3([-position[0], -position[1], -position[2]]);
+    return [0, -1, 0];
+}
+function quaternionFromForwardDirection(direction) {
+    const target = normalize3(direction);
+    const dot = clampNumber(-target[2], -1, 1);
+    if (dot > 0.999999)
+        return [0, 0, 0, 1];
+    if (dot < -0.999999)
+        return [0, 1, 0, 0];
+    const quaternion = [target[1], -target[0], 0, 1 + dot];
+    const length = Math.hypot(...quaternion) || 1;
+    return [
+        quaternion[0] / length,
+        quaternion[1] / length,
+        quaternion[2] / length,
+        quaternion[3] / length
+    ];
+}
+function normalizedDirection(from, to) {
+    const direction = [to[0] - from[0], to[1] - from[1], to[2] - from[2]];
+    return length3(direction) > 0.000001 ? normalize3(direction) : [0, -1, 0];
+}
+function length3(value) {
+    return Math.hypot(value[0], value[1], value[2]);
+}
+function productionRuntimeLightMaxScale(scale) {
+    return Math.max(productionRuntimeLightAxisScale(scale, 0), productionRuntimeLightAxisScale(scale, 1), productionRuntimeLightAxisScale(scale, 2));
+}
+function productionRuntimeLightAxisScale(scale, axis) {
+    const value = typeof scale === "number" ? scale : scale?.[axis] ?? 1;
+    return positiveFinite(Math.abs(value), 1);
+}
+function nonNegativeFinite(value) {
+    return Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+function positiveFinite(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function clampNumber(value, min, max) {
+    return Math.max(min, Math.min(max, Number.isFinite(value) ? value : min));
+}
+function multiplyRgb(color, tint) {
+    return [color[0] * tint[0], color[1] * tint[1], color[2] * tint[2]];
 }
 async function createProductionRuntimeSceneRenderer(canvas, snapshot, rendererOptions, runtimeNodes) {
     const flattened = groups.flatten(snapshot.nodes);
@@ -7283,10 +7726,16 @@ async function createProductionRuntimeSceneRenderer(canvas, snapshot, rendererOp
     let latestFeatures = productionRenderer.getFeatures();
     const runtimeWarnings = new Set();
     const productionEnvironment = createProductionRuntimeEnvironment(snapshot);
+    const productionRuntimeLights = createProductionRuntimeCollectedLights(snapshot);
+    const authoredLightNodes = flattened.filter((node) => node.kind === "light");
+    const authoredDirectLightNodes = authoredLightNodes.filter((node) => node.light !== "ambient");
+    const authoredAmbientLightCount = authoredLightNodes.length - authoredDirectLightNodes.length;
+    const authoredAreaProxyCount = authoredDirectLightNodes.filter((node) => node.light === "rect" || node.light === "softbox").length;
     const buildDiagnostics = () => createRendererDiagnosticReport(snapshot, {
         mounted: true,
         backend: "production-runtime",
         postprocess: createProductionRuntimePostprocessObservation(latestDeviceDiagnostics),
+        shadow: createProductionRuntimeShadowObservation(createProductionRuntimeShadowOptions(snapshot, productionRuntimeLights), latestDeviceDiagnostics),
         environment: {
             enabled: true,
             preset: productionEnvironment.preset,
@@ -7295,6 +7744,15 @@ async function createProductionRuntimeSceneRenderer(canvas, snapshot, rendererOp
         },
         warnings: [
             `Production runtime bridge active with ${actorEntries.length} typed GLB actor${actorEntries.length === 1 ? "" : "s"} and ${primitiveEntries.length} Aura primitive${primitiveEntries.length === 1 ? "" : "s"} on ${productionRenderer.backend}.`,
+            ...(authoredDirectLightNodes.length === 0
+                ? ["Production runtime direct-light fallback active: the scene has no authored directional, point, studio, rect, or softbox light."]
+                : [`Production runtime derived ${productionRuntimeLights.length} collected direct light${productionRuntimeLights.length === 1 ? "" : "s"} from ${authoredDirectLightNodes.length} authored scene light${authoredDirectLightNodes.length === 1 ? "" : "s"}.`]),
+            ...(authoredAmbientLightCount > 0
+                ? [`${authoredAmbientLightCount} authored ambient light${authoredAmbientLightCount === 1 ? "" : "s"} remain environment-lighting intent and are not mislabeled as direct CollectedLight entries.`]
+                : []),
+            ...(authoredAreaProxyCount > 0
+                ? [`${authoredAreaProxyCount} authored rect/softbox light${authoredAreaProxyCount === 1 ? "" : "s"} use bounded spot-light proxies whose cone and range derive from authored width and height; this does not claim physical area-light shading.`]
+                : []),
             ...(flattened.some((node) => node.kind === "effect")
                 ? ["Effect nodes are requested in the scene graph; production bridge diagnostics report them, but unsupported postprocess/effect passes remain non-pixel-backed until the runtime feature reports support."]
                 : []),
@@ -7314,12 +7772,15 @@ async function createProductionRuntimeSceneRenderer(canvas, snapshot, rendererOp
         },
         render(time) {
             runtimeWarnings.clear();
-            const input = createProductionRuntimeRendererInput(snapshot, canvas, actorEntries, primitiveEntries, time, runtimeNodes, runtimeWarnings, productionEnvironment.lighting);
+            const input = createProductionRuntimeRendererInput(snapshot, canvas, actorEntries, primitiveEntries, time, runtimeNodes, runtimeWarnings, productionEnvironment.lighting, productionRuntimeLights);
             const result = productionRenderer.renderInteractiveFrame(input);
             latestDeviceDiagnostics = result.diagnostics;
             latestFeatures = result.features;
             return latestDeviceDiagnostics.drawCalls;
         },
+        viewProjection(time) {
+            return createViewProjection(snapshot, canvas.width / Math.max(1, canvas.height), time, runtimeNodes);
+        },
         dispose() {
             productionRenderer.dispose();
             for (const { actor } of actorEntries)
@@ -7331,7 +7792,7 @@ async function createProductionRuntimeSceneRenderer(canvas, snapshot, rendererOp
         }
     };
 }
-function createProductionRuntimeRendererInput(snapshot, canvas, actorEntries, primitiveEntries, time, runtimeNodes, runtimeWarnings, environmentLighting) {
+function createProductionRuntimeRendererInput(snapshot, canvas, actorEntries, primitiveEntries, time, runtimeNodes, runtimeWarnings, environmentLighting, collectedLights) {
     const items = [];
     for (const entry of actorEntries) {
         const currentState = resolveProductionActorRuntimeState(entry, runtimeNodes);
@@ -7340,7 +7801,7 @@ function createProductionRuntimeRendererInput(snapshot, canvas, actorEntries, pr
             continue;
         applyProductionActorAnimation(entry, currentNode, currentState.animationBinding, time, runtimeWarnings);
         applyProductionActorMorphTargets(entry, currentState.morphTargets, runtimeWarnings);
-        const modelMatrix = [...createModelMatrix(currentNode, boundsFromAuraAsset(currentNode.asset), shouldNormalizeModelNode(currentNode), time)];
+        const modelMatrix = [...createModelMatrix(currentNode, productionActorModelBounds(currentNode.asset, entry.actor), shouldNormalizeModelNode(currentNode), time)];
         const actorItems = entry.actor.collectRenderItems({ modelMatrix });
         items.push(...actorItems);
         attachProductionActorEvidence(currentNode, entry.actor, actorItems, runtimeNodes);
@@ -7362,12 +7823,13 @@ function createProductionRuntimeRendererInput(snapshot, canvas, actorEntries, pr
     const source = {
         collectRenderItems: () => items,
         cameraPolicy: "require",
-        staticBatching: false,
-        frustumCulling: false,
-        collectedLights: createProductionRuntimeCollectedLights(),
+        staticBatching: true,
+        frustumCulling: true,
+        collectedLights,
         environmentLighting,
-        postprocess: createProductionRuntimePostprocess(),
-        shadow: createProductionRuntimeShadowOptions(),
+        postprocess: createProductionRuntimePostprocess(snapshot),
+        shadow: createProductionRuntimeShadowOptions(snapshot, collectedLights),
+        environmentFog: createProductionRuntimeEnvironmentFog(snapshot),
         cameraPosition
     };
     const cameraLike = { viewProjectionMatrix };
@@ -7564,6 +8026,74 @@ function createProductionRuntimeMetadata(actorEntries) {
 function sumProductionMetadata(metadata, key) {
     return metadata.reduce((total, item) => total + item[key], 0);
 }
+/**
+ * Bounds used to size a typed model in the production bridge.
+ *
+ * Order matters and is deliberate:
+ *
+ * 1. The actor's actually-loaded GLB bounds. These are what the geometry really
+ *    occupies, so the bridge stays correct even if a manifest is stale or was written
+ *    by an older CLI. Preferring metadata here once caused whole levels to disappear:
+ *    a world recorded with an ~8x-too-small X extent was sized far too large and
+ *    frustum-culled out of frame.
+ * 2. Manifest `boundsMetadata` min/max, when loaded bounds are unavailable.
+ * 3. The flat `bounds` size triple, only if neither is available. This assumes a
+ *    min-Y-at-zero box that the mesh may not match, so it is a last resort.
+ *
+ * `camera.frameAsset` is synchronous and can only read manifest metadata, so framing
+ * and rendering agree only while the manifest matches the geometry. Both are correct
+ * as of the scene-space bounds fix and manifest regeneration;
+ * `auraProductionBoundsProbes()` records any per-asset disagreement at runtime so a
+ * future divergence is observable rather than silent.
+ */
+function productionActorModelBounds(asset, actor) {
+    const loaded = typedGLBActorLoadedBounds(actor);
+    const metadataBounds = asset.metadata?.boundsMetadata;
+    const metadataMin = vec3FromReadonly(metadataBounds?.min);
+    const metadataMax = vec3FromReadonly(metadataBounds?.max);
+    if (loaded) {
+        if (metadataMin && metadataMax) {
+            productionBoundsProbes.set(asset.id, {
+                assetId: asset.id,
+                metadata: { min: metadataMin, max: metadataMax },
+                loaded: { min: [...loaded.min], max: [...loaded.max] }
+            });
+        }
+        return loaded;
+    }
+    if (metadataMin && metadataMax)
+        return { min: metadataMin, max: metadataMax };
+    return boundsFromAuraAsset(asset);
+}
+const productionBoundsProbes = new Map();
+/**
+ * Diagnostic: manifest `boundsMetadata` versus the bounds actually computed from the
+ * loaded GLB, per typed asset routed through the production bridge.
+ *
+ * The bridge sizes models from loaded bounds because those are what the geometry
+ * really occupies. This accessor exists so a disagreement with manifest metadata —
+ * which `camera.frameAsset` must use, being synchronous — is observable instead of
+ * silently producing mismatched framing.
+ */
+export function auraProductionBoundsProbes() {
+    return [...productionBoundsProbes.values()];
+}
+/**
+ * Real bounds of the loaded GLB scene, as computed from its geometry. Returns
+ * undefined when the actor cannot supply them, so callers fall back to manifest
+ * metadata rather than silently using a zeroed box.
+ */
+function typedGLBActorLoadedBounds(actor) {
+    const bounds = actor.pipeline?.resources?.bounds;
+    const min = vec3FromReadonly(bounds?.min);
+    const max = vec3FromReadonly(bounds?.max);
+    if (!min || !max)
+        return undefined;
+    // A degenerate box would produce a divide-by-near-zero fit scale.
+    if (max[0] - min[0] <= 0 && max[1] - min[1] <= 0 && max[2] - min[2] <= 0)
+        return undefined;
+    return { min, max };
+}
 function boundsFromAuraAsset(asset) {
     const metadataBounds = asset.metadata?.boundsMetadata;
     const metadataMin = vec3FromReadonly(metadataBounds?.min);
@@ -7963,6 +8493,9 @@ async function createWebGLSceneRenderer(canvas, snapshot, rendererOptions, runti
             }
             return drawCalls;
         },
+        viewProjection(time) {
+            return createViewProjection(snapshot, canvas.width / Math.max(1, canvas.height), time, runtimeNodes);
+        },
         dispose() {
             for (const modelEntry of models) {
                 const textures = new Set();
@@ -8858,7 +9391,13 @@ function createPlaneGeometry() {
             0, 1, 0,
             0, 1, 0
         ]),
-        indices: new Uint16Array([0, 1, 2, 0, 2, 3]),
+        // Counter-clockwise when viewed from +Y, so the triangle winding agrees with
+        // the [0, 1, 0] vertex normals. The previous [0, 1, 2, 0, 2, 3] order wound
+        // the opposite way: its geometric normal was [0, -1, 0], so `gl_FrontFacing`
+        // was false for a camera above the plane and the two-sided shader flipped the
+        // up-normal downward. The plane then faced away from every overhead light and
+        // received no direct lighting or visible cast shadows.
+        indices: new Uint16Array([0, 2, 1, 0, 3, 2]),
         bounds: { min: [-0.5, 0, -0.5], max: [0.5, 0, 0.5] }
     };
 }
@@ -9542,6 +10081,23 @@ function appendCanvas(target) {
     target.append(canvas);
     return canvas;
 }
+/**
+ * `resize: false` means "do not take over sizing", not "render at the HTML
+ * default backing store". A canvas element always reports `width === 300` and
+ * `height === 150` until something assigns them, so a truthiness check on those
+ * properties can never tell an author-chosen size from the spec default. Only an
+ * explicit `width`/`height` attribute, or a backing store that was already
+ * assigned to something other than the default pair, counts as author intent.
+ */
+function hasAuthoredBackingStore(canvas) {
+    if (canvas.dataset.aura3dCanvas === "true")
+        return false;
+    if (canvas.hasAttribute("width") || canvas.hasAttribute("height"))
+        return true;
+    return canvas.width !== DEFAULT_CANVAS_BACKING_WIDTH || canvas.height !== DEFAULT_CANVAS_BACKING_HEIGHT;
+}
+const DEFAULT_CANVAS_BACKING_WIDTH = 300;
+const DEFAULT_CANVAS_BACKING_HEIGHT = 150;
 function applyDefaultCanvasMountLayout(target) {
     if (typeof window === "undefined")
         return;
@@ -9571,8 +10127,9 @@ function configureCanvas(canvas, pixelRatio, resize) {
     canvas.style.height = `${cssHeight}px`;
     const width = Math.max(320, Math.round(cssWidth * pixelRatio));
     const height = Math.max(220, Math.round(cssHeight * pixelRatio));
-    canvas.width = resize ? width : canvas.width || width;
-    canvas.height = resize ? height : canvas.height || height;
+    const keepAuthoredSize = !resize && hasAuthoredBackingStore(canvas);
+    canvas.width = keepAuthoredSize ? canvas.width : width;
+    canvas.height = keepAuthoredSize ? canvas.height : height;
 }
 function validateSceneAssets(snapshot, assets) {
     for (const node of snapshot.nodes) {
@@ -9638,7 +10195,8 @@ function snapshotDiagnostics(value) {
         evidence: value.evidence,
         renderer: value.renderer,
         warnings: [...value.warnings],
-        errors: [...value.errors]
+        errors: [...value.errors],
+        ...(value.labels ? { labels: value.labels } : {})
     };
 }
 function collectGeneratedCodeWarnings(snapshot) {