@aura3d/engine 1.4.4 → 1.5.0

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

@@ -1,6 +1,6 @@
 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";
 export * from "./FrameEncoder.js";
@@ -35,6 +35,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 +101,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 +1741,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 +4341,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])
@@ -7131,38 +7152,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 +7169,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 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`
+    };
 }
-function createProductionRuntimeShadowOptions() {
-    return PRODUCTION_RUNTIME_SHADOWS;
+/**
+ * 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 +7327,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 +7478,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 +7491,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 +7504,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 +7647,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 +7665,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,7 +7693,7 @@ 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;
@@ -7331,7 +7710,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 +7719,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 +7741,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 +7944,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);
@@ -8858,7 +9306,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 +9996,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 +10042,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) {