@aura3d/engine 1.5.2 → 2.0.1

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

@@ -1,10 +1,54 @@
-import { PhysicsDebugDraw, PhysicsStepper, PhysicsWorld, ScenePhysicsBridge, Shape as PhysicsShapeFactory } from "../../physics/index.js";
-import { createExternalParityEnvironmentLighting, Geometry, IndexBuffer, PBRMaterial, ProductionRuntimeRenderer, VertexBuffer, VertexFormat } from "../../rendering/index.js";
+/*
+ * WS-2.2 — module-scope physics values come from the SOLVERLESS entry.
+ *
+ * `Shape`, `PhysicsStepper`, `ScenePhysicsBridge` and `PhysicsDebugDraw` are solver-free: each
+ * imports `PhysicsWorld` as a *type* only. But reaching them through `@aura3d/physics` — a chain of
+ * `export *` that includes `PhysicsWorld` — dragged in the physical adapter, so a scene with no
+ * bodies still downloaded the solver.
+ *
+ * This is a different defect from eager construction, which was already fixed (see `:9832`). A lazy
+ * `new PhysicsWorld()` still leaves a static `import`, and a bundler keeps the module either way.
+ * Deferring the *import* is what removes the bytes. `PhysicsWorld` is now loaded by
+ * `await import("../../physics/index.js")` at the points that actually simulate.
+ */
+import { PhysicsDebugDraw, PhysicsStepper, ScenePhysicsBridge, Shape as PhysicsShapeFactory } from "../../physics/solverless.js";
+/*
+ * WS-2.2 — the solver, from a NARROW entry rather than the physics barrel.
+ *
+ * Static on purpose. `app.physics` is documented and tested as live synchronously for every app, so
+ * `createAuraApp` cannot await a solver, and R7 forbids breaking that to save bytes. What this does
+ * avoid is the barrel: `@aura3d/physics` is a chain of `export *` that also carries `HitboxWorld`,
+ * `CharacterController`, `KinematicBody`, arcade vehicle telemetry, `NarrowPhase` and six fixture modules, all
+ * of which arrived just to reach one class.
+ */
+import { PhysicsWorld } from "../../physics/world.js";
+import { createExternalParityEnvironmentLighting, Geometry, IndexBuffer, InstancedPBRMaterial, PBRMaterial, ProductionRuntimeRenderer, srgbToLinearChannel, VertexBuffer, VertexFormat } from "../../rendering/index.js";
 import { DirectionalLight, PointLight, SpotLight } from "../../scene/index.js";
-import { createTypedGLBActor } from "../production-runtime/TypedGLBActor.js";
+import { lookAtMat4, multiplyMat4, orthographicMat4, perspectiveMat4 } from "../../scene/MathTypes.js";
 import { AURA_NORMALIZED_MODEL_MAX_DIMENSION, boundsFromAsset, boundsHeight, boundsMaxDimension, boundsSize } from "./SceneGroundingUtils.js";
 import { createWorldLabelLayer } from "./WorldLabelRenderer.js";
+import { createAuraText3DGeometry, defineAuraCustomGeometry, selectAuraRootLodLevel } from "./RootGeometry.js";
+export * from "./RootGeometry.js";
 export * from "./SpatialAnchoring.js";
+export * from "./PhysicsRuntime.js";
+/**
+ * WS-2.4: mesh surface queries on the public surface.
+ *
+ * Re-exported from `@aura3d/physics` so grounding anything to a mesh is a one-liner for any
+ * genre, from `@aura3d/engine` alone. Without this a route wanting real per-point ground
+ * height had to either deep-import `@aura3d/physics/src` (banned by the lint rule) or
+ * hand-roll an analytic approximation — which is exactly what every racing route did, and
+ * why wheels sank through visible road.
+ */
+/*
+ * WS-2.2 — re-exported from the SOLVERLESS entry, not the physics barrel.
+ *
+ * These are geometry queries: `MeshBVH` and `SurfaceQuery` import only `Shape`'s types. Re-exporting
+ * them from `@aura3d/physics` made this barrel a static consumer of the whole solver, so grounding a
+ * wheel on a mesh reached the physical solver. Same symbols, same public names.
+ */
+export { buildMeshBVH, createMeshSurfaceQuery, raycastMesh } from "../../physics/solverless.js";
+import { createPhysicsRuntime } from "./PhysicsRuntime.js";
 export * from "./FocusSelection.js";
 export * from "./WorldLabelRenderer.js";
 export * from "./VehicleChassis.js";
@@ -17,14 +61,23 @@ export * from "./FrameEncoder.js";
 export * from "./BrowserFrameCaptureAdapter.js";
 export * from "./MediaRecorderFrameEncoder.js";
 export * from "./WebCodecsFrameEncoder.js";
-export * from "./FfmpegFrameEncoder.js";
-export * from "./PngSequenceEncoder.js";
-export * from "./AudioMuxer.js";
+/*
+ * WS-2.3 — `FfmpegFrameEncoder` is deliberately NOT re-exported here.
+ *
+ * It is the only file in the 37-file media surface that reaches `node:` builtins (`child_process` to
+ * spawn ffmpeg; `fs/promises`/`os`/`path` to stage frames). Re-exporting it put Node builtins in every
+ * browser bundle of this entry point, which is why `tools/bundle-size` had to mark four `node:`
+ * specifiers external "for every browser bundle measurement" — a workaround for a dependency that
+ * should not have been in the browser graph. esbuild resolves `await import()` at build time whether or
+ * not the branch can run.
+ *
+ * Node consumers import `@aura3d/engine/media-node`. Enforced by `tools/browser-entry-purity`, which
+ * bundles every browser entry with no `node:` externals so a reachable builtin fails the build.
+ */
 export { GameInspector, createGameInspector } from "./GameInspector.js";
 import { createGameInspector } from "./GameInspector.js";
 export { createGameAudio } from "../game/GameAudio.js";
 export * from "./RenderProgressTracker.js";
-export * from "./VideoExportPipeline.js";
 export * from "./AudioVisemeAnalyzer.js";
 export * from "./ExternalPhonemeAnalyzer.js";
 export * from "./WaveformVisualizer.js";
@@ -36,12 +89,7 @@ export * from "./CameraPresetLibrary.js";
 export * from "./ShotCompositionRules.js";
 export * from "./CameraChoreographer.js";
 export * from "./CameraPathEditor.js";
-export * from "./CaptionExporter.js";
 export * from "./ThumbnailGenerator.js";
-export * from "./YouTubeMetadataGenerator.js";
-export * from "./YouTubeUploadAdapter.js";
-export * from "./PublishingPipeline.js";
-export * from "./CloudRenderAdapter.js";
 export * from "./BatchEpisodeRenderer.js";
 export * from "./AnimationAssetManifest.js";
 export * from "./SceneGroundingUtils.js";
@@ -60,7 +108,7 @@ export * from "./AnimationMotionQuality.js";
 export * from "./AnimationRouteProof.js";
 export * from "./AnimationEpisodePackage.js";
 import { createFrameLoop } from "./FrameLoop.js";
-import { createCombatWorld, createGameCameraDirector, createGameEffects, applyGameCombatEventsToRuntime, createGameAccessibilityFocus, createGameAccessibilityLabel, createGameAccessibilityRuntimeSettings, createGameEventLog, createGameHighContrastSource, createGameHudBindings, createGameHudComboBinding, createGameHudCheckpointBinding, createGameHudDebugToggleBinding, createGameHudEventLogBinding, createGameHudHealthBinding, createGameHudLivesBinding, createGameHudMeterBinding, createGameHudObjectiveBinding, createGameHudRoundBinding, createGameHudScoreBinding, createGameHudSnapshot, createGameHudTimerBinding, createGameHudValueBinding, createGameBoxCollider, createGameCapsuleCollider, createGameColliderDebugGeometry, createGameCombatDebugGeometry, createGameCollisionWorld, createGameDebugOverlayData, createGameDebugSceneNodes, createGameHitboxDebugGeometry, createGameSimulation, exportGameInputReplay, createGameFighting2DRules, createGameInput, createGameInputReplay, createGameInputReplayDriver, importGameInputReplay, createGameJumpAssist, createGameKinematicBody, createGamePauseControlsSource, createGameRectCollider, createGameReducedFlashSource, createGameReducedMotionSource, createGameSphereCollider, createGameTouchControlLayout, gameColliderAabb, gameColliders, gameEffectPresets, gameGuardboxes, gameHitboxes, gameHurtboxes, gameInputReplayEventsAt, gamePushboxes, runGameSimulation, gameTriggerVolumes } from "./GameRuntime.js";
+import { createCombatWorld, createGameCameraDirector, createGameEffects, applyGameCombatEventsToRuntime, createGameAccessibilityFocus, createGameAccessibilityLabel, createGameAccessibilityRuntimeSettings, createGameEventLog, createGameHighContrastSource, createGameHudBindings, createGameHudComboBinding, createGameHudCheckpointBinding, createGameHudDebugToggleBinding, createGameHudEventLogBinding, createGameHudHealthBinding, createGameHudLivesBinding, createGameHudMeterBinding, createGameHudObjectiveBinding, createGameHudRoundBinding, createGameHudScoreBinding, createGameHudSnapshot, createGameHudTimerBinding, createGameHudValueBinding, createGameBoxCollider, createGameCapsuleCollider, createGameColliderDebugGeometry, createGameCombatDebugGeometry, createGameCollisionWorld, createGamePlanarCollisionWorld, createGameDebugOverlayData, createGameDebugSceneNodes, createGameHitboxDebugGeometry, createGameSimulation, exportGameInputReplay, createGameFighting2DRules, createGameInput, createGameInputReplay, createGameInputReplayDriver, importGameInputReplay, createGameJumpAssist, createGameKinematicBody, createGamePauseControlsSource, createGameRectCollider, createGameReducedFlashSource, createGameReducedMotionSource, createGameSphereCollider, createGameTouchControlLayout, gameColliderAabb, gameColliders, gameEffectPresets, gameGuardboxes, gameHitboxes, gameHurtboxes, gameInputReplayEventsAt, gamePushboxes, runGameSimulation, gameTriggerVolumes } from "./GameRuntime.js";
 import { collectGameRuntimeEvidence as collectGameRuntimeEvidenceV105 } from "./GameEvidence.js";
 import { calculateRuntimeNodeBounds } from "./RuntimeNodeHandle.js";
 import { createRuntimeNodeSpec } from "./GameSceneBridge.js";
@@ -188,7 +236,8 @@ export function model(asset, options = {}) {
         targetHeight: options.targetHeight,
         targetMaxDimension: options.targetMaxDimension,
         targetLength: options.targetLength,
-        physics: options.physics
+        physics: options.physics,
+        hiddenNodeNames: options.hiddenNodeNames
     });
 }
 export function unsafeModelUrl(url, options = {}) {
@@ -235,7 +284,12 @@ function primitive(primitiveName, options = {}) {
         size: options.size,
         castShadow: options.castShadow ?? (primitiveName !== "plane" && options.material?.emissive === undefined),
         receiveShadow: options.receiveShadow ?? true,
-        physics: options.physics
+        physics: options.physics,
+        instances: options.instances,
+        instanceColors: options.instanceColors,
+        geometry: options.geometry,
+        text3D: options.text3D,
+        lod: options.lod
     });
 }
 function sceneNodeFromInput(node) {
@@ -262,6 +316,43 @@ export const primitives = {
     capsule: (options) => primitive("capsule", options),
     torus: (options) => primitive("torus", options)
 };
+function instancedPrimitive(primitiveName, options) {
+    if (options.transforms.length === 0)
+        throw new Error("Aura3D instancing requires at least one transform.");
+    if (options.colors && options.colors.length !== options.transforms.length)
+        throw new Error("Aura3D instance color count must match transform count.");
+    return primitive(primitiveName, { ...options, instances: options.transforms, instanceColors: options.colors });
+}
+export const instances = {
+    box: (options) => instancedPrimitive("box", options),
+    sphere: (options) => instancedPrimitive("sphere", options),
+    plane: (options) => instancedPrimitive("plane", options),
+    cylinder: (options) => instancedPrimitive("cylinder", options),
+    capsule: (options) => instancedPrimitive("capsule", options),
+    torus: (options) => instancedPrimitive("torus", options)
+};
+export const geometry = {
+    define: defineAuraCustomGeometry,
+    custom: (spec, options = {}) => primitive("custom", { ...options, geometry: defineAuraCustomGeometry(spec) })
+};
+export function text3D(text, options = {}) {
+    const built = createAuraText3DGeometry(text, options);
+    return primitive("custom", { ...options, geometry: built.geometry, text3D: { text: built.text, glyphCount: built.glyphCount, unsupportedCharacters: built.unsupportedCharacters, method: built.method } });
+}
+export function distanceLod(options) {
+    if (options.levels.length === 0)
+        throw new Error("Aura3D distance LOD requires at least one level.");
+    selectAuraRootLodLevel(0, options.levels, undefined, options.hysteresis ?? 0);
+    const first = options.levels[0];
+    if (!first.primitive && !first.geometry)
+        throw new Error("Every Aura3D LOD level requires a primitive or custom geometry.");
+    return primitive(first.geometry ? "custom" : first.primitive, {
+        ...options,
+        geometry: first.geometry,
+        material: first.material ?? options.material,
+        lod: { levels: options.levels, hysteresis: options.hysteresis }
+    });
+}
 export const groups = {
     create: group,
     flatten: (nodes) => flattenSceneNodes(nodes)
@@ -1606,7 +1697,7 @@ const rendererQualityProfiles = {
         kind: "aura-renderer-quality-profile",
         id: "safe-basic",
         label: "Safe Basic",
-        rendererMode: "safe-basic",
+        rendererMode: "production",
         status: "supported",
         antialiasing: "msaa",
         pixelRatio: 1,
@@ -1615,7 +1706,7 @@ const rendererQualityProfiles = {
         requestedFeatures: ["typed models", "primitives", "basic particles", "base-color textures", "runtime nodes"],
         supportedInRoot: ["typed models", "primitives", "basic particles", "base-color textures", "runtime nodes"],
         blockedInRoot: ["production PBR parity", "skinned animation mixer", "native WebGPU compute", "postprocess pass chain"],
-        claimBoundary: "Root createAuraApp safe path. Use this for public examples unless a browser test proves a stronger profile."
+        claimBoundary: "Root createAuraApp uses the production renderer with the conservative safe-basic feature profile. Claims still require route-specific browser evidence."
     },
     production: {
         kind: "aura-renderer-quality-profile",
@@ -1684,8 +1775,6 @@ function analyzeProductionBridgeEligibility(nodes) {
     const primitiveCount = nodes.filter((node) => node.kind === "primitive").length;
     const effectCount = nodes.filter((node) => node.kind === "effect").length;
     const reasons = [];
-    if (typedModelCount < 1)
-        reasons.push("production bridge requires at least one typed GLB from generated aura-assets");
     if (unsafeModelCount > 0)
         reasons.push("unsafeModelUrl and remote/raw model URLs are blocked from the production bridge");
     if (inlineModelCount > 0)
@@ -1748,10 +1837,10 @@ function createRendererDiagnosticReport(snapshot, runtime, rendererOptions) {
     if (postprocessRequested && runtime?.mounted && !runtimePostprocess?.pixelBacked)
         warnings.push("postprocess was requested but the runtime composer did not initialize a pixel-backed pass");
     if (rendererSelection.mode === "production" && !runtime?.mounted && productionEligibility.eligible) {
-        warnings.push(`Renderer profile "${rendererSelection.profile.id}" can use the typed-GLB production bridge after createAuraApp mounts; inspect app.diagnostics().renderer.runtime for pixel-backed status.`);
+        warnings.push(`Renderer profile "${rendererSelection.profile.id}" will use the production renderer after createAuraApp mounts; inspect app.diagnostics().renderer.runtime for pixel-backed status.`);
     }
     if (rendererSelection.mode === "production" && !productionEligibility.eligible) {
-        warnings.push(`Renderer profile "${rendererSelection.profile.id}" will use safe-basic fallback for this scene: ${productionEligibility.reasons.join("; ")}.`);
+        warnings.push(`Renderer profile "${rendererSelection.profile.id}" cannot mount this scene on the production renderer: ${productionEligibility.reasons.join("; ")}.`);
     }
     if (rendererSelection.profile.status === "fallback-only") {
         warnings.push(`Renderer profile "${rendererSelection.profile.id}" is a request profile; public claims require route-specific runtime diagnostics and screenshot proof.`);
@@ -1837,6 +1926,7 @@ function createRendererDiagnosticReport(snapshot, runtime, rendererOptions) {
             requestedPasses,
             actualPasses: runtimePostprocess?.actualPasses ?? [],
             fallbackPasses: runtimePostprocess?.fallbackPasses ?? [],
+            targetFormat: runtimePostprocess?.targetFormat,
             evidence: postprocessEvidence
         },
         runtime: {
@@ -1844,7 +1934,13 @@ function createRendererDiagnosticReport(snapshot, runtime, rendererOptions) {
             backend: runtime?.backend ?? "scene-plan",
             postprocessVerified: runtimePostprocess?.pixelBacked ?? false,
             passNames: runtimePostprocess?.actualPasses ?? [],
-            warnings: runtime?.warnings ?? []
+            warnings: runtime?.warnings ?? [],
+            nativeInstancedSubmissions: runtime?.deviceDiagnostics?.nativeInstancedSubmissions ?? 0,
+            submittedObjects: runtime?.deviceDiagnostics?.submittedObjects ?? 0,
+            visibleObjects: runtime?.deviceDiagnostics?.visibleObjects ?? 0,
+            culledObjects: runtime?.deviceDiagnostics?.culledObjects ?? 0,
+            frustumTestedObjects: runtime?.deviceDiagnostics?.frustumTestedObjects ?? 0,
+            lodSelections: runtime?.lodSelections ?? []
         },
         environment: {
             enabled: environmentStatus.enabled,
@@ -2254,6 +2350,7 @@ function createRuntimeScenePhysics(snapshot) {
     const physicsNodes = snapshot.nodes.filter((node) => (node.kind === "model" || node.kind === "primitive") && Boolean(node.physics));
     if (physicsNodes.length === 0)
         return undefined;
+    // WS-2.2: solver resolved through the on-demand cache rather than a static import.
     const world = new PhysicsWorld({ gravity: [0, -9.81, 0], fixedDelta: 1 / 60, enableSleeping: true });
     const stepper = new PhysicsStepper(world.fixedDelta);
     const debugDraw = new PhysicsDebugDraw();
@@ -2654,6 +2751,8 @@ export const prefabs = {
             ...makeCityCrosswalk("zebra crosswalk west", -0.72, 0, "eastWest"),
             ...makeCityCrosswalk("zebra crosswalk east", 0.72, 0, "eastWest")
         ];
+        const cityTowerTransforms = [];
+        const cityTowerColors = [];
         const xSlots = [-4.25, -2.58, -0.95, 1.45, 3.3];
         const zSlots = [-4, -1.45, 1.3, 3.65];
         for (let index = 0; index < blocks; index += 1) {
@@ -2665,15 +2764,19 @@ export const prefabs = {
             const color = night
                 ? (index % 3 === 0 ? "#1e293b" : index % 3 === 1 ? "#2d3340" : "#172233")
                 : (index % 3 === 0 ? "#8ea2aa" : index % 3 === 1 ? "#b89b72" : "#668094");
-            nodes.push(primitives.box({
-                name: `city tower ${index + 1}`,
-                material: material.pbr({ color, roughness: 0.68, metallic: 0.06 })
-            }).position(x, height / 2, z).scale([1.08, height, 1.08]).toJSON());
+            cityTowerTransforms.push({ position: [x, height / 2, z], scale: [1.08, height, 1.08] });
+            cityTowerColors.push(color);
             if (options.litWindows !== false) {
                 nodes.push(...makeBuildingWindowRows(x, z, height, index, timeOfDay));
             }
             nodes.push(...makeBuildingDetails(x, z, height, index, timeOfDay));
         }
+        nodes.push(instances.box({
+            name: "city tower native instanced family",
+            transforms: cityTowerTransforms,
+            colors: cityTowerColors,
+            material: material.pbr({ color: "#ffffff", roughness: 0.68, metallic: 0.06 })
+        }).toJSON());
         const lampPositions = [
             [-1.15, 0, 0.85], [1.15, 0, 0.85], [-1.15, 0, -0.85], [1.15, 0, -0.85],
             [-3.85, 0, -2.05], [-2.95, 0, 2.05], [2.05, 0, -2.05], [3.05, 0, 2.05],
@@ -2769,7 +2872,9 @@ export const prefabs = {
         const rimMaterial = material.emissive({ color: "#dbeafe", emissive: "#93c5fd", emissiveIntensity: 0.18, opacity: 0.42 });
         const nodes = [
             primitives.plane({ name: "seamless matte product hero floor", material: floorMaterial }).position(0, -0.018, -0.62).scale([3.6, 1, 2.6]).toJSON(),
-            primitives.plane({ name: "distant seamless product photography backdrop", material: backdropMaterial }).position(0, 1.22, -2.28).rotate(-0.08, 0, 0).scale([3.6, 1, 1.8]).toJSON(),
+            primitives.plane({ name: "vertical seamless product photography backdrop", material: backdropMaterial }).position(0, 1.22, -2.28).rotate(1.5708, 0, 0).scale([6.2, 1, 2.15]).toJSON(),
+            primitives.box({ name: "cool cyan studio reflection panel", material: material.emissive({ color: "#20bfe8", emissive: "#20bfe8", emissiveIntensity: 0.46 }) }).position(-2.35, 1.14, -2.18).scale([0.24, 1.38, 0.035]).toJSON(),
+            primitives.box({ name: "warm amber studio reflection panel", material: material.emissive({ color: "#f0a43c", emissive: "#f0a43c", emissiveIntensity: 0.42 }) }).position(2.35, 1.14, -2.18).scale([0.24, 1.38, 0.035]).toJSON(),
             primitives.cylinder({ name: "low matte hero product plinth", material: plinthMaterial }).position(0, 0.255, -0.65).scale([1.46, 0.26, 1.46]).toJSON(),
             primitives.cylinder({ name: "soft product contact shadow from footprint", material: shadowMaterial }).position(0, 0.292, -0.65).scale([1.06, 0.01, 0.66]).toJSON(),
             primitives.box({ name: "subtle turntable orbit cue on product plinth", material: material.emissive({ color: "#93c5fd", emissive: "#38bdf8", emissiveIntensity: 0.22, opacity: 0.38 }) }).position(0, 0.52, -0.65).scale([1.02, 0.012, 1.02]).toJSON(),
@@ -3371,7 +3476,7 @@ function createMiniGolfStateController() {
         const worldSnapshot = world.snapshot();
         return {
             physicsBackend: worldSnapshot.backend.active,
-            deterministicReplayId: `mini-golf-cannon-v1-${shots}-${score}-${collisions}-${resets}`,
+            deterministicReplayId: `mini-golf-rapier-v2-${shots}-${score}-${collisions}-${resets}`,
             replayFrame: worldSnapshot.stats.steps,
             captureTime: Number((worldSnapshot.stats.steps * world.fixedDelta).toFixed(3)),
             shots,
@@ -3478,187 +3583,6 @@ export const games = {
 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",
@@ -4639,6 +4563,7 @@ export const game = {
     touchControls: createGameTouchControlLayout,
     kinematicBody: createGameKinematicBody,
     collisionWorld: createGameCollisionWorld,
+    planarCollisionWorld: createGamePlanarCollisionWorld,
     jumpAssist: createGameJumpAssist,
     collider: {
         box: createGameBoxCollider,
@@ -5385,12 +5310,16 @@ function cityScene(options = {}) {
         .camera(cityCameraPreset(options.cameraPreset ?? "overview", timeOfDay));
 }
 function collectCityInstancingPlan(nodes) {
-    const names = groups.flatten(nodes).map((node) => "name" in node ? node.name ?? "" : "");
+    const flattened = groups.flatten(nodes);
+    const names = flattened.map((node) => "name" in node ? node.name ?? "" : "");
+    const nativeInstanceNodes = flattened.filter((node) => node.kind === "primitive" && Boolean(node.instances?.length));
+    const nativeInstances = nativeInstanceNodes.reduce((total, node) => total + (node.instances?.length ?? 0), 0);
     const windows = names.filter((name) => name.includes("window column")).length;
     const props = names.filter((name) => name.includes("bench") || name.includes("tree") || name.includes("sign") || name.includes("car body") || name.includes("traffic signal")).length;
     const roadMarkings = names.filter((name) => name.includes("lane marking") || name.includes("road stripe") || name.includes("crosswalk") || name.includes("turn arrow") || name.includes("bike lane")).length;
     const lights = names.filter((name) => name.includes("street lamp") || name.includes("headlight") || name.includes("lamp glow") || name.includes("city glow")).length;
     const groupsList = [
+        nativeInstanceNodes.some((node) => node.name?.includes("city tower")) ? "city towers" : "",
         windows >= 8 ? "window columns" : "",
         props >= 6 ? "street props" : "",
         roadMarkings >= 8 ? "road markings" : "",
@@ -5398,13 +5327,15 @@ function collectCityInstancingPlan(nodes) {
     ].filter(Boolean);
     return {
         kind: "aura-city-instancing-plan",
-        rendererPath: "auraWebGL2PrimitiveBatches",
+        rendererPath: "productionRuntimeNativeInstancing",
         windows,
         props,
         roadMarkings,
         lights,
+        nativeInstanceGroups: nativeInstanceNodes.length,
+        nativeInstances,
         groups: groupsList,
-        instanced: windows >= 8 && props >= 6 && roadMarkings >= 8 && lights >= 6
+        instanced: nativeInstanceNodes.length > 0 && nativeInstances > 0
     };
 }
 function changedCityNodeNames(previous, next) {
@@ -5417,7 +5348,11 @@ function changedCityNodeNames(previous, next) {
 function validateCityVisualQA(nodes, options = {}) {
     const flattened = groups.flatten(nodes);
     const names = flattened.map((node) => "name" in node ? node.name ?? "" : "");
-    const buildings = names.filter((name) => name.includes("city tower")).length;
+    const buildings = flattened.reduce((total, node) => {
+        if (!("name" in node) || !node.name?.includes("city tower"))
+            return total;
+        return total + (node.kind === "primitive" && node.instances?.length ? node.instances.length : 1);
+    }, 0);
     const windows = names.filter((name) => name.includes("window column")).length;
     const streets = names.filter((name) => name.includes("road") || name.includes("street") || name.includes("avenue")).length;
     const crosswalks = names.filter((name) => name.includes("crosswalk")).length;
@@ -5945,7 +5880,7 @@ function createSceneKitLazyLoadingPlan(id) {
         systems.push({ system, trigger, loadedByDefault: false, evidence });
     };
     if (id === "physicsPlayground" || id === "miniGolf") {
-        add("physics-backend", `${id} physics state construction`, "Cannon-backed physics is optional scene-kit work and not required for static material/chart/product scenes");
+        add("physics-backend", `${id} physics state construction`, "Rapier-backed physics is isolated scene-kit work and is not required for static material, chart, or product scenes");
     }
     if (id === "productViewer") {
         add("product-gltf-loader", "typed product model render path", "GLTF loading is tied to typed model scenes and excluded from procedural-only scene kits");
@@ -6215,10 +6150,11 @@ export const promptRecipes = {
         .add(primitives.sphere({ name: "rain splash foreground", material: material.emissive({ color: "#c8f4ff", emissive: "#c8f4ff" }) }).position(-0.88, 0.035, 0.72).scale([0.07, 0.018, 0.07]))
         .add(primitives.sphere({ name: "rain splash key side", material: material.emissive({ color: "#ffe1ad", emissive: "#ffe1ad" }) }).position(1.14, 0.035, 0.44).scale([0.08, 0.018, 0.08]))
         .add(model(asset, { name: plan.subject.label }).position(-0.08, 0.02, -0.86).rotate(-0.08, -0.74, 0.02).scale(1.48))
-        .add(lights.ambient({ intensity: 0.07, color: "#839dc6" }))
+        .add(lights.ambient({ intensity: 0.22, color: "#b4c9e8" }))
         .add(lights.point({ name: "hard cyan rim", position: [-2.35, 2.65, 0.85], color: "#38d6ff", intensity: 3.25 }))
         .add(lights.point({ name: "warm practical key", position: [2.35, 1.7, -0.25], color: "#ffd08a", intensity: 1.6 }))
         .add(lights.point({ name: "low floor bounce", position: [0.1, 0.45, 1.1], color: "#7edfff", intensity: 0.62 }))
+        .add(lights.point({ name: "cinematic hero front fill", position: [0.15, 1.45, 3.1], color: "#e8f2ff", intensity: 5.2 }))
         .add(effects.rain({ intensity: 0.46, color: "#c3e6ff" }))
         .add(effects.fog({ density: 0.08, color: "#32435a" }))
         .add(effects.bloom({ intensity: 0.36, color: "#6edfff" }))
@@ -6719,10 +6655,137 @@ export function createAuraApp(target, options) {
     let disposed = false;
     let animationHandle = 0;
     let productionController;
+    /** WS-2.9: true from the moment a WebGL mount starts until the controller arrives or fails. */
+    let productionMountPending = false;
+    /**
+     * WS-2.5 — true when a WebGL mount was attempted and FAILED for this scene.
+     *
+     * Distinct from `productionMountPending`, and the distinction is the whole point. After a failed mount
+     * both the pending flag and the controller are absent, which used to be indistinguishable from "this
+     * scene never wanted WebGL" — so `step()` and the render loop fell through to the Canvas-2D branch and
+     * painted a gradient over a scene whose renderer had just failed. Measured: 16,384 lit pixels on a
+     * 128x128 canvas, i.e. the entire surface, with the real error sitting in `diagnostics().errors` where
+     * nobody was looking.
+     */
+    let productionMountFailed = false;
+    /**
+     * Settles when the in-flight WebGL mount finishes, successfully or not. Backs `app.ready()`.
+     *
+     * Resolved rather than pending when no mount is in flight, so `await app.ready()` is safe to call at
+     * any time and on any scene.
+     */
+    let productionMountSettled = Promise.resolve();
+    /** Lets `dispose()` settle an in-flight mount; see the note there. */
+    let settleMountForDispose = () => undefined;
+    /*
+     * WS-2.6 — device-loss subscribers, held here rather than pushed straight at the controller.
+     *
+     * The renderer mounts asynchronously, so a developer writing `app.onDeviceLost(...)` on the line after
+     * `createAuraApp` has no controller to attach to yet. Making them await `ready()` first would be the
+     * same trap WS-2.9 fixed: an API that silently does nothing depending on timing. So subscriptions are
+     * recorded and attached when the device arrives, and on every re-mount from `setScene`.
+     */
+    /*
+     * Keyed BY LISTENER, not a flat array — and that detail is load-bearing.
+     *
+     * A flat list of unsubscribe functions looks equivalent and is not. `attachDeviceListeners` re-attaches
+     * every held listener on each mount, so a listener registered before the mount ends up with **two**
+     * controller subscriptions: the one its own `onDeviceLost` call created, and the one the mount handler
+     * created. Its returned unsubscribe closure only knew about the first, so calling it left the second
+     * live and the listener still fired.
+     *
+     * Measured by the WS-2.6 test's final assertion: after `unsubscribe()`, a second context loss still
+     * incremented the counter — 2 where 1 was expected. A map from listener to its current subscription
+     * makes unsubscribing complete regardless of how many mounts have happened.
+     */
+    const deviceLostListeners = new Map();
+    const deviceRestoredListeners = new Map();
+    const attachDeviceListeners = (controller) => {
+        for (const [listener, unsubscribe] of deviceLostListeners) {
+            unsubscribe?.();
+            deviceLostListeners.set(listener, controller.onDeviceLost?.(listener));
+        }
+        for (const [listener, unsubscribe] of deviceRestoredListeners) {
+            unsubscribe?.();
+            deviceRestoredListeners.set(listener, controller.onDeviceRestored?.(listener));
+        }
+    };
     let lastTime = 0;
     let mountRevision = 0;
     let canvasRuntimePhysics;
     const runtimeNodes = createAuraRuntimeNodeRegistry(renderSnapshot);
+    // One world owned by the app, so `app.physics` is live whether or not the scene declared
+    // any bodies. A route that spawns everything at runtime (a shooter, a stacking puzzle) is
+    // then no harder to write than one that declares bodies up front.
+    const appPhysicsNodeNames = new Map();
+    /*
+     * The physics world is created on first use, not on app construction.
+     *
+     * `app.physics` must be live for every app — a route that spawns bodies at runtime should be no
+     * harder to write than one that declares them. But constructing the world eagerly made **every**
+     * app pay for the selected physical solver.
+     *
+     * Measured cost of the eager version: a minimal `createAuraApp` scene containing one box bundled to
+     * The eager version made the physical runtime part of every route's startup path, including
+     * routes that never created a body.
+     *
+     * Lazily constructing it changes no behaviour — `app.physics` still returns a working runtime, and
+     * a scene that declares `.physics({...})` still gets its bodies registered, because
+     * `registerDeclaredBodies` asks for the world and therefore creates it. What changes is that a
+     * scene with no physics never instantiates a solver, so a bundler can drop it.
+     */
+    let appPhysicsWorldInstance;
+    const appPhysicsWorld = () => {
+        appPhysicsWorldInstance ??= new PhysicsWorld({
+            gravity: options.physics?.gravity ? [...options.physics.gravity] : [0, -9.81, 0],
+            fixedDelta: 1 / 60,
+            enableSleeping: true
+        });
+        return appPhysicsWorldInstance;
+    };
+    let appPhysicsInstance;
+    /** Lazy `app.physics`. Identity is stable: the same runtime is returned on every access. */
+    const appPhysics = () => {
+        appPhysicsInstance ??= createPhysicsRuntime(appPhysicsWorld(), {
+            ...(options.physics?.layers ? { layers: options.physics.layers } : {}),
+            nodeNameFor: (bodyId) => appPhysicsNodeNames.get(bodyId)
+        });
+        return appPhysicsInstance;
+    };
+    /**
+     * Register scene-declared bodies into the app-owned world.
+     *
+     * Runs on construction and on every `setScene`, so a declared node name resolves through
+     * `app.physics.bodies.require(name)` without the route restating the body.
+     */
+    const registerDeclaredBodies = (target) => {
+        // Ask the question before creating the world, so a scene with no declared bodies never does.
+        const declaresPhysics = target.nodes.some((node) => (node.kind === "model" || node.kind === "primitive") && Boolean(node.physics));
+        if (!declaresPhysics)
+            return;
+        const world = appPhysicsWorld();
+        for (const node of target.nodes) {
+            if ((node.kind !== "model" && node.kind !== "primitive") || !node.physics)
+                continue;
+            const spec = node.physics;
+            const body = world.createRigidBody({
+                type: spec.type ?? "dynamic",
+                position: node.position ?? [0, 0, 0],
+                rotation: eulerToQuat(node.rotation ?? [0, 0, 0]),
+                ...(spec.mass === undefined ? {} : { mass: spec.mass }),
+                ...(spec.friction === undefined ? {} : { friction: spec.friction }),
+                ...(spec.restitution === undefined ? {} : { restitution: spec.restitution })
+            });
+            world.createCollider(body, {
+                shape: resolveNodePhysicsShape(node, spec),
+                ...(spec.sensor === undefined ? {} : { sensor: spec.sensor }),
+                material: { friction: spec.friction ?? 0.5, restitution: spec.restitution ?? 0 }
+            });
+            if (node.name)
+                appPhysicsNodeNames.set(body.id, node.name);
+        }
+    };
+    registerDeclaredBodies(renderSnapshot);
     const frameCallbacks = new Set();
     let runtimePaused = options.autoStart === false;
     let runtimeFrame = 0;
@@ -6775,7 +6838,16 @@ export function createAuraApp(target, options) {
         }
         diagnosticsState.evidence = collectAuraSceneEvidence(renderSnapshot);
         diagnosticsState.fps = Math.round(1000 / delta);
-        diagnosticsState.drawCalls = renderSceneToCanvas(canvas, renderSnapshot, time);
+        /*
+         * WS-2.5 — the live loop must respect the same rule as `step()`.
+         *
+         * Fixing only `step()` would have left the gradient reachable through `autoStart`, which is the path
+         * most routes take. A scene whose WebGL mount is pending or has failed gets nothing drawn; the reason
+         * is already recorded in `warnings`/`errors`.
+         */
+        diagnosticsState.drawCalls = productionMountPending || productionMountFailed
+            ? 0
+            : renderDiagnosticPreviewToCanvas(canvas, renderSnapshot, time);
         if (canvas)
             diagnosticsState.renderSize = [canvas.width, canvas.height];
         overlay?.update();
@@ -6793,24 +6865,87 @@ export function createAuraApp(target, options) {
         productionController = undefined;
         lastTime = 0;
         const shouldUseProductionRenderer = shouldUseProductionRendererForCurrentScene();
+        /*
+         * WS-2.5 — a scene with renderable content must never fall to the diagnostic 2D path.
+         *
+         * `shouldUseProductionRendererForCurrentScene()` is false in two very different situations, and the
+         * old code treated them the same: a scene with nothing renderable in it (fine, nothing to draw), and
+         * a scene *with* renderable nodes that could not reach WebGL — no canvas, or no `window`. The second
+         * used to silently produce a gradient schematic, which looks like a render and is not.
+         *
+         * So the two cases are separated. A renderable scene with no usable canvas now raises a diagnosable
+         * error naming the cause, instead of drawing something plausible.
+         */
+        const declaresRenderableContent = renderSnapshot.nodes.some(isWebGLRenderableNode);
+        /*
+         * Scoped to the case that is actually a lie: a canvas WAS supplied, so the caller is looking at
+         * pixels, and the scene has renderable content — but WebGL declined it, so those pixels would be a
+         * gradient schematic.
+         *
+         * Deliberately NOT extended to `canvas === undefined`. Constructing an app with no canvas is a
+         * legitimate and widely used pattern — 18 tests across `tests/unit/agent-api` and
+         * `tests/unit/rendering` do it to exercise scene, runtime and physics behaviour headlessly, and
+         * `createAuraApp(undefined, ...)` is how `lazy-physics-world.test.ts` checks `app.physics`. Throwing
+         * there would break working semantics to satisfy a rendering rule, which R7 forbids. Those callers
+         * are not being shown a misleading frame; they are not being shown a frame at all, and
+         * `diagnostics().backend` reports `"headless"`.
+         */
+        if (declaresRenderableContent && canvas && !shouldUseProductionRenderer) {
+            throw new AuraRuntimeError("backend-fallback", "Aura3D cannot render this scene on the canvas you supplied: it has renderable nodes but WebGL2 is unavailable in this context. It will NOT fall back to the Canvas 2D diagnostic preview, because that draws a gradient schematic rather than your scene and has silently hidden defects before — world labels once reached the scene graph but were drawn only in that path. Suggested fix: run in a browser context with WebGL2 available, or inspect diagnostics().errors for the underlying device failure.");
+        }
         const backend = shouldUseProductionRenderer ? "webgl2" : canvas ? "canvas2d" : "headless";
         resetDiagnosticsForCurrentScene(backend);
         canvasRuntimePhysics = shouldUseProductionRenderer ? undefined : createRuntimeScenePhysics(renderSnapshot);
         overlay?.update();
         const revision = ++mountRevision;
+        /*
+         * WS-2.9 — record that a WebGL mount is in flight.
+         *
+         * `startProductionRender` is async, so between `createAuraApp` returning and the controller
+         * arriving there is a window in which `step()` used to fall through to the Canvas-2D `render()`
+         * path and draw nothing for a WebGL scene — silently, with `drawCalls: 0`, `warnings: []` and
+         * `errors: []`. `step(dt)` is the documented deterministic entry point, so a developer writing a
+         * headless capture got a blank image and no explanation.
+         */
+        productionMountPending = shouldUseProductionRenderer && Boolean(canvas);
+        productionMountFailed = false;
+        let settleMount = () => undefined;
+        productionMountSettled = productionMountPending
+            ? new Promise((resolveSettled) => { settleMount = resolveSettled; })
+            : Promise.resolve();
+        settleMountForDispose = settleMount;
         if (shouldUseProductionRenderer && canvas) {
-            void startProductionRender(canvas, renderSnapshot, diagnosticsState, options, overlay, runRuntimeFrame, () => runtimePaused, runtimeNodes)
+            void startProductionRender(canvas, renderSnapshot, diagnosticsState, options, overlay, runRuntimeFrame, () => runtimePaused, runtimeNodes, 
+            // A route that registered a frame callback, or that has bodies to simulate, needs
+            // frames regardless of what the scene declares.
+            /*
+             * Must not *create* a world just to ask whether one exists.
+             * Reading `appPhysicsWorldInstance` directly keeps the lazy construction lazy; calling
+             * `appPhysicsWorld()` here would instantiate the solver on the first render of every scene
+             * and defeat the whole point.
+             */
+            () => frameCallbacks.size > 0 || (appPhysicsWorldInstance?.bodies().length ?? 0) > 0, 
+            // Paused frames render at the app's own simulated clock, so a held frame really is held.
+            () => runtimeTime * 1000)
                 .then((controller) => {
                 if (disposed || revision !== mountRevision) {
+                    productionMountPending = false;
+                    settleMount();
                     controller.dispose();
                     return;
                 }
                 productionController = controller;
+                productionMountPending = false;
+                attachDeviceListeners(controller);
+                settleMount();
                 markRouteReady(snapshot, diagnosticsState);
             })
                 .catch((error) => {
                 if (disposed || revision !== mountRevision)
                     return;
+                productionMountPending = false;
+                productionMountFailed = true;
+                settleMount();
                 diagnosticsState.backend = "webgl2";
                 diagnosticsState.errors.push(productionRenderErrorMessage(error));
                 overlay?.update();
@@ -6822,7 +6957,7 @@ export function createAuraApp(target, options) {
         markRouteReady(snapshot, diagnosticsState);
     };
     mountCurrentScene();
-    return {
+    const app = {
         canvas,
         get scene() {
             return snapshot;
@@ -6834,9 +6969,24 @@ export function createAuraApp(target, options) {
             snapshot = normalizeSceneSnapshot(nextScene);
             renderSnapshot = flattenSceneSnapshot(snapshot);
             runtimeNodes.reset(renderSnapshot);
+            // Drop bodies from the previous scene before registering the new ones, so swapping
+            // scenes does not leave orphaned bodies colliding with the new level.
+            // Only a world that exists can hold stale bodies; `setScene` on a physics-free app is a no-op here.
+            for (const id of [...appPhysicsNodeNames.keys()])
+                appPhysicsWorldInstance?.removeRigidBody(id);
+            appPhysicsNodeNames.clear();
+            registerDeclaredBodies(renderSnapshot);
             mountCurrentScene();
         },
         nodes: runtimeNodes,
+        /*
+         * A getter, so touching `app.physics` is what constructs the world.
+         * Declared as a getter rather than an eager property because the property access itself is the
+         * signal that a route intends to use physics.
+         */
+        get physics() {
+            return appPhysics();
+        },
         get runtime() {
             return {
                 paused: runtimePaused,
@@ -6863,23 +7013,116 @@ export function createAuraApp(target, options) {
         pause() {
             runtimePaused = true;
         },
+        resetRuntimeClock() {
+            /*
+             * Rewind the frame counter and elapsed time to zero.
+             *
+             * Needed for reproducible capture. Routes animate from accumulated `time` — Data Galaxy sets
+             * `setRotation(time * 0.16, ...)` — so a scene paused after 180 frames of real-time loading
+             * looks different from the same scene paused after 240, even though both were then advanced by
+             * an identical number of fixed steps. Zeroing the clock first makes "settle to N steps" name
+             * exactly one state.
+             *
+             * Not part of `AuraApp`: this is a capture/testing seam, reached through `auraAppRegistry`
+             * rather than offered as gameplay API, because rewinding a live game's clock mid-session is
+             * not something a route should be encouraged to do.
+             */
+            runtimeFrame = 0;
+            runtimeTime = 0;
+            runtimeAlpha = 0;
+            lastTime = 0;
+        },
         resume() {
             runtimePaused = false;
             if (!animationHandle && !productionController && options.autoStart !== false && typeof requestAnimationFrame !== "undefined") {
                 animationHandle = requestAnimationFrame(render);
             }
         },
-        step(dt = 1 / 60) {
+        async ready() {
+            // Resolves when the in-flight mount settles; immediate when there is none. See AuraApp.ready.
+            await productionMountSettled;
+        },
+        onDeviceLost(listener) {
+            // Attach now when a device already exists; otherwise the mount handler attaches it on arrival.
+            deviceLostListeners.set(listener, productionController?.onDeviceLost?.(listener));
+            return () => {
+                // Read the CURRENT subscription: a re-mount may have replaced the one captured at registration.
+                deviceLostListeners.get(listener)?.();
+                deviceLostListeners.delete(listener);
+            };
+        },
+        onDeviceRestored(listener) {
+            deviceRestoredListeners.set(listener, productionController?.onDeviceRestored?.(listener));
+            return () => {
+                deviceRestoredListeners.get(listener)?.();
+                deviceRestoredListeners.delete(listener);
+            };
+        },
+        deviceLost() {
+            return productionController?.deviceLost?.() ?? false;
+        },
+        advance(dt = 1 / 60) {
             const seconds = Math.max(0, dt);
             runRuntimeFrame(seconds, "manual");
             canvasRuntimePhysics?.step(seconds);
+        },
+        step(dt = 1 / 60) {
+            const seconds = Math.max(0, dt);
+            app.advance(seconds);
             const previousPaused = runtimePaused;
             runtimePaused = true;
+            /*
+             * Render at the *simulated* time, not wall-clock time.
+             *
+             * `step(dt)` is the deterministic entry point — a caller advances a fixed amount and expects a
+             * reproducible frame. Passing `performanceNow()` to the renderer defeated that: any
+             * time-driven shader or effect sampled real elapsed milliseconds, so the same `step` sequence
+             * produced a different image on every run.
+             *
+             * Measured while making screenshot approval satisfiable: after zeroing the runtime clock and
+             * stepping identically, 6 of 29 screenshots still drifted perceptually — all of them routes
+             * with time-animated rendering (particle lab, material inspector). Feeding `runtimeTime`
+             * instead makes `step` mean one thing.
+             *
+             * The live `render()` loop still uses wall-clock time, which is correct for real playback.
+             */
+            const simulatedMs = runtimeTime * 1000;
             if (productionController) {
-                productionController.render(performanceNow());
+                productionController.render(simulatedMs);
+            }
+            else if (productionMountPending || productionMountFailed) {
+                /*
+                 * WS-2.9 — a WebGL mount is in flight, so there is nothing correct to draw yet.
+                 *
+                 * Falling through to the Canvas-2D `render()` branch below would draw a gradient for a scene
+                 * that has a WebGL renderer coming, which is worse than drawing nothing: it produces a frame
+                 * that looks like a real render and is not one. Measured before this fix: eight synchronous
+                 * `step(1/60)` calls after construction gave `drawCalls: 0`, a fully blank canvas,
+                 * `backend: "webgl2"` and — the actual defect — **empty `warnings` and `errors`**. One
+                 * `await requestAnimationFrame` first gave 58,480 lit pixels.
+                 *
+                 * So this reports rather than renders. The warning is actionable and names both the cause and
+                 * the fix, because a developer writing a headless capture has no way to guess that a
+                 * documented deterministic entry point depends on an animation frame having elapsed.
+                 */
+                const pendingWarning = productionMountFailed
+                    ? "Aura3D step() rendered nothing because the WebGL renderer failed to mount for this scene. It will NOT fall back to the Canvas 2D diagnostic preview, because that paints a gradient schematic over a scene whose renderer just failed. Suggested fix: read diagnostics().errors for the underlying device failure."
+                    : "Aura3D step() was called before the WebGL renderer finished mounting, so this frame rendered nothing. The production renderer mounts asynchronously. Suggested fix: await one animation frame — `await new Promise(requestAnimationFrame)` — or await `app.ready()` before stepping, then call step() as normal.";
+                if (!diagnosticsState.warnings.includes(pendingWarning))
+                    diagnosticsState.warnings.push(pendingWarning);
+                diagnosticsState.drawCalls = 0;
+                overlay?.update();
             }
             else {
-                render(performanceNow());
+                /*
+                 * `render` records `lastTime` to derive its own delta. Feeding it simulated time would leave
+                 * `lastTime` in a different clock from `performanceNow()`, so the first frame after a
+                 * `resume()` would compute a wildly wrong delta — a visible jump. Restore it afterwards so
+                 * `step` stays side-effect-free with respect to live playback.
+                 */
+                const previousLastTime = lastTime;
+                render(simulatedMs);
+                lastTime = previousLastTime;
             }
             runtimePaused = previousPaused;
         },
@@ -6903,6 +7146,16 @@ export function createAuraApp(target, options) {
         },
         dispose() {
             disposed = true;
+            /*
+             * Settle any in-flight mount so `await app.ready()` cannot hang on a disposed app. A promise
+             * that never resolves is a worse failure than the one WS-2.9 fixed: it has no diagnostic at all.
+             */
+            productionMountPending = false;
+            settleMountForDispose();
+            for (const unsubscribe of [...deviceLostListeners.values(), ...deviceRestoredListeners.values()])
+                unsubscribe?.();
+            deviceLostListeners.clear();
+            deviceRestoredListeners.clear();
             if (animationHandle && typeof cancelAnimationFrame !== "undefined")
                 cancelAnimationFrame(animationHandle);
             for (const controller of ownedInputControllers)
@@ -6910,9 +7163,77 @@ export function createAuraApp(target, options) {
             ownedInputControllers.clear();
             productionController?.dispose();
             overlay?.dispose();
+            unregisterAuraApp(app);
         }
     };
+    registerAuraApp(app);
+    return app;
 }
+/**
+ * Live apps on this page, so tooling can act on a scene it did not create.
+ *
+ * ## Why this exists
+ *
+ * Visual-approval and screenshot gates need to *freeze* a scene before capturing it. Without a way
+ * to reach the running app, they cannot: a route creates its app in module scope and typically never
+ * exposes the handle, so an automated capture can only `waitForTimeout` and photograph whatever frame
+ * the loop happened to reach.
+ *
+ * Measured consequence, before this existed: re-running the showcase screenshot spec with **no code
+ * change** produced different bytes for 14 of 29 screenshots, because most routes animate and print
+ * live telemetry. Any gate binding approval to a screenshot hash was therefore unsatisfiable — every
+ * regeneration invalidated a still-correct signature.
+ *
+ * Deliberately a `Set` of handles rather than a global "the app", because a page may legitimately
+ * mount several. Entries are removed on `dispose()` so a long-lived page does not leak.
+ */
+const liveAuraApps = new Set();
+function registerAuraApp(app) {
+    liveAuraApps.add(app);
+    if (typeof globalThis !== "undefined") {
+        globalThis.__AURA3D_LIVE_APPS__ = auraAppRegistry;
+    }
+}
+function unregisterAuraApp(app) {
+    liveAuraApps.delete(app);
+}
+export const auraAppRegistry = {
+    kind: "aura3d-live-app-registry",
+    count() {
+        return liveAuraApps.size;
+    },
+    pauseAll() {
+        for (const app of liveAuraApps)
+            app.pause();
+        return liveAuraApps.size;
+    },
+    resumeAll() {
+        for (const app of liveAuraApps)
+            app.resume();
+        return liveAuraApps.size;
+    },
+    settle(steps = 30, dt = 1 / 60) {
+        for (const app of liveAuraApps) {
+            app.pause();
+            /*
+             * Rewind before stepping.
+             *
+             * Without this, `settle(30)` means "30 steps after however long the page took to load", which
+             * differs run to run — and routes that animate from accumulated `time` then render a different
+             * frame. Measured before this: 8 of 29 screenshots still drifted perceptually even with every
+             * app paused and stepped identically.
+             */
+            const resettable = app;
+            resettable.resetRuntimeClock?.();
+            for (let index = 0; index < Math.max(0, steps); index += 1)
+                app.step(dt);
+        }
+        return liveAuraApps.size;
+    },
+    all() {
+        return [...liveAuraApps];
+    }
+};
 export function createGameApp(target, options) {
     const { input, loop, runtimeEvidence, ...appOptions } = options;
     const app = createAuraApp(target, { ...appOptions, autoStart: false });
@@ -7168,6 +7489,14 @@ function worldLabelsFromSnapshot(snapshot, runtimeNodes) {
             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"),
+            /*
+             * WS-2.7 — carry the declared option through. This line is the fix.
+             *
+             * `occlusionAware` has defaulted to true on every label factory since before 1.6 and was never
+             * read here, so `WorldLabel` never received it and the renderer had nothing to act on. The option
+             * was documented, accepted, and inert.
+             */
+            occlusionAware: node.occlusionAware ?? true,
             ...(node.label === "hud" && node.screenAnchor ? { screenAnchor: node.screenAnchor } : {}),
             ...(node.label === "hud" && !node.screenAnchor ? { screenAnchor: "top-left" } : {})
         };
@@ -7187,15 +7516,154 @@ function createSceneLabelLayer(canvas, snapshot) {
         return undefined;
     return createWorldLabelLayer({ container: canvas.parentElement ?? document.body, canvas });
 }
-async function startProductionRender(canvas, snapshot, diagnosticsState, options, overlay, beforeRender, isPaused = () => false, runtimeNodes) {
+/**
+ * WS-2.7 — build the occlusion test for a scene's annotations.
+ *
+ * ## What it does
+ *
+ * Walks the segment from the camera eye to a label's anchor and asks whether any renderable node's
+ * world-space box lies across it. If one does, the thing being annotated is behind geometry.
+ *
+ * ## Why boxes and not triangles
+ *
+ * An annotation only needs to know whether its subject is *hidden*, and a node's bounding box answers
+ * that at a fraction of the cost of a mesh raycast — one slab test per node against one segment, no BVH,
+ * no per-frame allocation of any size. A box is conservative: it can report occlusion slightly early at a
+ * silhouette edge. For a label that is the right direction to be wrong in; the alternative, reporting a
+ * label as visible when its subject is behind a wall, is the defect being fixed.
+ *
+ * ## What it deliberately skips
+ *
+ * The node the label is anchored *to*. Every annotation sits on or just outside its own subject's
+ * surface, so including it would report every label as occluded by the very geometry it annotates —
+ * the label-shaped version of z-fighting.
+ */
+function createSceneLabelOcclusionTest(snapshot, cameraEye, runtimeNodes) {
+    const occluders = [];
+    for (const node of groups.flatten(snapshot.nodes)) {
+        if (node.kind !== "primitive" && !isRenderableModelNode(node))
+            continue;
+        if (node.visible === false)
+            continue;
+        const runtimeSnapshot = node.runtime?.id ? runtimeNodes?.get(node.runtime.id)?.snapshot() : undefined;
+        if (runtimeSnapshot?.visible === false)
+            continue;
+        const position = (runtimeSnapshot?.position ?? node.position ?? [0, 0, 0]);
+        const scale = (runtimeSnapshot?.scale ?? node.scale ?? [1, 1, 1]);
+        /*
+         * Local extents from the primitive's own geometry where available, and a unit box otherwise.
+         * A model's real bounds come from its asset, which is not loaded synchronously here; the declared
+         * scale is the honest approximation and is what the scene author controls.
+         */
+        const localBounds = node.kind === "primitive" ? primitiveGeometryBounds(node) : undefined;
+        const halfLocal = localBounds
+            ? [
+                Math.max(1e-4, (localBounds.max[0] - localBounds.min[0]) / 2),
+                Math.max(1e-4, (localBounds.max[1] - localBounds.min[1]) / 2),
+                Math.max(1e-4, (localBounds.max[2] - localBounds.min[2]) / 2)
+            ]
+            : [0.5, 0.5, 0.5];
+        const half = [
+            Math.abs(halfLocal[0] * scale[0]),
+            Math.abs(halfLocal[1] * scale[1]),
+            Math.abs(halfLocal[2] * scale[2])
+        ];
+        occluders.push({
+            min: [position[0] - half[0], position[1] - half[1], position[2] - half[2]],
+            max: [position[0] + half[0], position[1] + half[1], position[2] + half[2]]
+        });
+    }
+    if (occluders.length === 0)
+        return () => false;
+    /** Slab test: does the segment eye -> anchor enter this box strictly before reaching the anchor? */
+    const segmentHitsBox = (anchor, box) => {
+        let tEnter = 0;
+        let tExit = 1;
+        for (let axis = 0; axis < 3; axis += 1) {
+            const origin = cameraEye[axis];
+            const direction = anchor[axis] - origin;
+            const min = box.min[axis];
+            const max = box.max[axis];
+            if (Math.abs(direction) < 1e-9) {
+                // Parallel to this slab: outside it means the segment can never be inside the box.
+                if (origin < min || origin > max)
+                    return false;
+                continue;
+            }
+            const t1 = (min - origin) / direction;
+            const t2 = (max - origin) / direction;
+            tEnter = Math.max(tEnter, Math.min(t1, t2));
+            tExit = Math.min(tExit, Math.max(t1, t2));
+            if (tEnter > tExit)
+                return false;
+        }
+        /*
+         * `tEnter` must be meaningfully before the anchor. A box the anchor merely touches at t ~= 1 is the
+         * subject's own surface, not an occluder — the epsilon is what keeps a label from occluding itself.
+         */
+        return tEnter > 1e-4 && tEnter < 1 - 1e-3;
+    };
+    return (anchor) => {
+        for (const box of occluders) {
+            // Skip the box the anchor is inside: that is the subject, and a subject cannot occlude its own label.
+            const insideBox = anchor[0] >= box.min[0] && anchor[0] <= box.max[0]
+                && anchor[1] >= box.min[1] && anchor[1] <= box.max[1]
+                && anchor[2] >= box.min[2] && anchor[2] <= box.max[2];
+            if (insideBox)
+                continue;
+            if (segmentHitsBox(anchor, box))
+                return true;
+        }
+        return false;
+    };
+}
+async function startProductionRender(canvas, snapshot, diagnosticsState, options, overlay, beforeRender, isPaused = () => false, runtimeNodes, 
+/**
+ * Extra reason to keep rendering, beyond what the scene declares.
+ *
+ * See {@link shouldContinuouslyRender}: scene-declared motion cannot know about a
+ * simulation or a frame callback the route drives itself.
+ */
+requiresFrames = () => false, 
+/**
+ * Render clock to use while paused, in milliseconds.
+ *
+ * Supplied by the app so a paused scene renders at its own simulated time rather than at
+ * wall-clock time. Without it, `pause()` froze the simulation but not time-driven rendering.
+ */
+pausedRenderTime = () => 0) {
     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().");
     }
     const renderer = await createProductionSceneRenderer(canvas, snapshot, options.renderer, runtimeNodes);
     diagnosticsState.renderer = renderer.diagnostics;
-    const continuousRender = shouldContinuouslyRender(snapshot);
+    const sceneWantsFrames = shouldContinuouslyRender(snapshot);
     const labelLayer = createSceneLabelLayer(canvas, snapshot);
+    const rendererSelection = normalizeCreateAppRendererOptions(options.renderer);
+    const pixelRatio = options.pixelRatio ?? rendererSelection.profile.pixelRatio ?? devicePixelRatioSafe();
+    const resizeRenderer = () => {
+        if (options.resize === false)
+            return;
+        const parentRect = canvas.parentElement?.getBoundingClientRect();
+        const cssWidth = parentRect?.width || canvas.clientWidth || (typeof window !== "undefined" ? window.innerWidth : 960) || 960;
+        const cssHeight = parentRect?.height || canvas.clientHeight || (typeof window !== "undefined" ? window.innerHeight : 540) || 540;
+        const width = Math.max(320, Math.round(cssWidth * pixelRatio));
+        const height = Math.max(220, Math.round(cssHeight * pixelRatio));
+        if (canvas.width === width && canvas.height === height)
+            return;
+        canvas.style.width = `${cssWidth}px`;
+        canvas.style.height = `${cssHeight}px`;
+        canvas.width = width;
+        canvas.height = height;
+        renderer.resize?.(width, height);
+    };
+    const resizeObserver = options.resize !== false && typeof ResizeObserver !== "undefined" && canvas.parentElement
+        ? new ResizeObserver(resizeRenderer)
+        : undefined;
+    resizeObserver?.observe(canvas.parentElement);
+    if (options.resize !== false && typeof window !== "undefined")
+        window.addEventListener("resize", resizeRenderer);
     let disposed = false;
     let animationHandle = 0;
     let lastTime = 0;
@@ -7206,7 +7674,21 @@ async function startProductionRender(canvas, snapshot, diagnosticsState, options
         lastTime = time;
         if (!isPaused())
             beforeRender?.(delta / 1000, "raf");
-        const drawCalls = renderer.render(time);
+        /*
+         * A paused app must not keep advancing time-driven rendering.
+         *
+         * `isPaused()` gated the simulation callback but not the render clock, so `pause()` stopped
+         * gameplay while particle emitters, animated materials and anything else keyed to elapsed time
+         * carried on. Measured on the particle lab: with the app paused *and* settled to a fixed frame,
+         * two screenshots taken 500 ms apart in the **same page load** still differed across 20.6% of the
+         * vortex region. The frame was never actually held, so no capture of it could be reproducible.
+         *
+         * While paused, render is pinned to the time of the last simulated frame. `app.step()` advances
+         * `runtimeTime` and renders explicitly, so stepping still produces new frames — what stops is
+         * time passing on its own.
+         */
+        const renderTime = isPaused() ? pausedRenderTime() : time;
+        const drawCalls = renderer.render(renderTime);
         diagnosticsState.backend = renderer.backend;
         diagnosticsState.fps = diagnosticsState.fps || 60;
         diagnosticsState.drawCalls = drawCalls;
@@ -7217,28 +7699,66 @@ async function startProductionRender(canvas, snapshot, diagnosticsState, options
             // 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));
+            /*
+             * WS-2.7 — rebuilt per frame, because both the camera and any runtime-driven node can move. The
+             * cost is one bounding box per renderable node, which is negligible beside the render itself, and
+             * caching it would silently stop occluding as soon as anything moved.
+             */
+            labelLayer.setOcclusionTest(createSceneLabelOcclusionTest(snapshot, resolveCameraEye(snapshot, snapshot.camera, renderTime, runtimeNodes), runtimeNodes));
+            labelLayer.update(renderer.viewProjection(renderTime));
             diagnosticsState.labels = labelLayer.snapshot();
         }
         overlay?.update();
-        if (continuousRender && options.autoStart !== false && typeof requestAnimationFrame !== "undefined") {
+        if ((sceneWantsFrames || requiresFrames()) && options.autoStart !== false && typeof requestAnimationFrame !== "undefined") {
             animationHandle = requestAnimationFrame(renderFrame);
         }
     };
     renderFrame();
     return {
         render(time = performanceNow()) {
+            /*
+             * Preserve `lastTime` across an explicit render.
+             *
+             * `renderFrame` records `lastTime` to derive its own delta and to drive `beforeRender`. When
+             * `app.step()` renders at *simulated* time for reproducibility, leaving `lastTime` on the
+             * simulated clock means the first live frame after `resume()` computes its delta against a
+             * different clock — a visible jump. Same defect the canvas2d path had; fixed identically so
+             * the two render paths cannot disagree about what `step` does.
+             */
+            const previousLastTime = lastTime;
             renderFrame(time);
+            lastTime = previousLastTime;
         },
+        // WS-2.6 — forward device-loss subscription from whichever renderer backs this controller.
+        onDeviceLost: renderer.onDeviceLost ? (listener) => renderer.onDeviceLost(listener) : undefined,
+        onDeviceRestored: renderer.onDeviceRestored ? (listener) => renderer.onDeviceRestored(listener) : undefined,
+        deviceLost: renderer.deviceLost ? () => renderer.deviceLost() : undefined,
         dispose() {
             disposed = true;
             if (animationHandle && typeof cancelAnimationFrame !== "undefined")
                 cancelAnimationFrame(animationHandle);
+            resizeObserver?.disconnect();
+            if (typeof window !== "undefined")
+                window.removeEventListener("resize", resizeRenderer);
             labelLayer?.dispose();
             renderer.dispose();
         }
     };
 }
+/**
+ * Whether the *scene* declares something that changes over time.
+ *
+ * Deliberately conservative: a fully static scene should render once and stop rather than
+ * burn a core redrawing an identical frame.
+ *
+ * It is not sufficient on its own, and that was a real defect. This predicate can only see
+ * what the scene *declares* — a looping timeline, a moving camera, an animated or mutable
+ * node. It cannot see a physics simulation or a frame callback the route drives itself. So
+ * an app whose only motion came from `app.physics.step()` inside `app.onFrame()` rendered
+ * exactly **one** frame and froze: measured `frames: 1` with no console error, in a
+ * clean-room project where every crate should have been falling. Callers therefore combine
+ * this with their own `requiresFrames()`.
+ */
 function shouldContinuouslyRender(snapshot) {
     if (snapshot.timeline?.mode === "loop")
         return true;
@@ -7262,9 +7782,7 @@ async function createProductionSceneRenderer(canvas, snapshot, rendererOptions,
     const flattened = groups.flatten(snapshot.nodes);
     const eligibility = analyzeProductionBridgeEligibility(flattened);
     if (!eligibility.eligible) {
-        return await createWebGLSceneRenderer(canvas, snapshot, rendererOptions, [
-            `Production bridge skipped: ${eligibility.reasons.join("; ")}.`
-        ], runtimeNodes);
+        throw new AuraRuntimeError("backend-fallback", `Aura3D production renderer rejected this scene: ${eligibility.reasons.join("; ")}. Suggested fix: import models through generated typed aura-assets.`);
     }
     try {
         return await createProductionRuntimeSceneRenderer(canvas, snapshot, rendererOptions, runtimeNodes);
@@ -7277,7 +7795,57 @@ async function createProductionSceneRenderer(canvas, snapshot, rendererOptions,
 }
 let cachedProductionRuntimeFallbackLights;
 function createProductionRuntimeEnvironment(snapshot) {
-    const names = groups.flatten(snapshot.nodes).map((node) => "name" in node ? node.name?.toLowerCase() ?? "" : "");
+    const nodes = groups.flatten(snapshot.nodes);
+    const authoredEnvironment = nodes.find((node) => node.kind === "environment");
+    if (authoredEnvironment) {
+        const presetByEnvironment = {
+            "studio": "studio",
+            "material-lab": "inspection",
+            "product-hero": "softbox",
+            "night-cinematic": "evening",
+            "metal-studio": "exhibit",
+            "glass-studio": "softbox"
+        };
+        const preset = presetByEnvironment[authoredEnvironment.environment];
+        const bundle = createExternalParityEnvironmentLighting(preset);
+        const intensity = nonNegativeFinite(authoredEnvironment.intensity);
+        const proceduralMap = bundle.lighting.proceduralMap;
+        return {
+            preset: authoredEnvironment.environment,
+            intensity,
+            evidence: `production bridge submitted the authored ${authoredEnvironment.environment} environment through generated HDR ${preset} lighting`,
+            lighting: {
+                ...bundle.lighting,
+                color: authoredEnvironment.color ? colorToLinearRgb(authoredEnvironment.color) : bundle.lighting.color,
+                intensity: bundle.lighting.intensity * intensity,
+                ...(proceduralMap ? {
+                    proceduralMap: {
+                        ...proceduralMap,
+                        intensity: proceduralMap.intensity * intensity,
+                        specularIntensity: proceduralMap.specularIntensity * intensity
+                    }
+                } : {}),
+                environmentMapIntensity: (bundle.lighting.environmentMapIntensity ?? 0) * intensity,
+                environmentMapSpecularIntensity: (bundle.lighting.environmentMapSpecularIntensity ?? 0) * intensity
+            }
+        };
+    }
+    const ambientLights = nodes.filter((node) => node.kind === "light" && node.light === "ambient" && node.intensity > 0);
+    if (ambientLights.length > 0) {
+        const intensity = ambientLights.reduce((total, light) => total + light.intensity, 0);
+        const color = ambientLights.reduce((sum, light) => {
+            const linear = colorToLinearRgb(light.color ?? "#ffffff");
+            const weight = light.intensity / intensity;
+            return [sum[0] + linear[0] * weight, sum[1] + linear[1] * weight, sum[2] + linear[2] * weight];
+        }, [0, 0, 0]);
+        return {
+            preset: "authored-ambient",
+            intensity,
+            evidence: `production bridge submitted ${ambientLights.length} authored ambient light${ambientLights.length === 1 ? "" : "s"} without an implicit environment map`,
+            lighting: { color, intensity, environmentMapIntensity: 0, environmentMapSpecularIntensity: 0 }
+        };
+    }
+    const names = nodes.map((node) => "name" in node ? node.name?.toLowerCase() ?? "" : "");
     const category = resolveRendererSceneCategory(snapshot, names);
     const preset = category === "city-day" ? "daylight"
         : category === "city-night" ? "evening"
@@ -7306,7 +7874,7 @@ function createProductionRuntimeEnvironmentFog(snapshot) {
         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");
+    const color = colorToLinearRgb(fog.color ?? "#9fb7d9");
     return {
         // Exponential-squared reads as depth haze rather than a hard linear band, which
         // matches what the public helper documents.
@@ -7320,16 +7888,8 @@ function createProductionRuntimeEnvironmentFog(snapshot) {
 }
 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);
+    const bloomRequested = Boolean(authoredBloom);
     // 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
@@ -7338,20 +7898,15 @@ function createProductionRuntimePostprocess(snapshot) {
     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",
+        // Tone mapping requires unclamped linear input. RGBA8 quantized dark clear
+        // colors and clipped highlights before ACES, which produced washed-out output.
+        targetFormat: "rgba16f",
         ...(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))))
+                threshold: clampNumber(authoredBloom?.threshold ?? 0.78, 0, 1),
+                intensity: clampNumber(authoredBloom?.intensity ?? 0.3, 0, 2),
+                radius: Math.max(1, Math.min(4, Math.round(authoredBloom?.radius ?? 2)))
             }
         } : {}),
         ...(authoredOcclusion ? {
@@ -7367,22 +7922,11 @@ function createProductionRuntimePostprocess(snapshot) {
             }
         } : {}),
         toneMapping: {
-            exposure,
-            whitePoint: category === "city-day" ? 1.28 : 1.18,
-            operator: "filmic",
+            exposure: 1,
+            whitePoint: 1,
+            operator: "aces",
             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
         }
     };
 }
@@ -7447,7 +7991,8 @@ function createProductionRuntimePostprocessObservation(diagnostics) {
         contactOcclusionReceiver: actualPasses.includes("contact-shadow"),
         pixelBacked,
         actualPasses,
-        fallbackPasses: pixelBacked ? [] : ["direct-render"]
+        fallbackPasses: pixelBacked ? [] : ["direct-render"],
+        targetFormat: diagnostics.postprocessTargetFormat
     };
 }
 function createProductionRuntimeCollectedLights(snapshot) {
@@ -7468,7 +8013,7 @@ function createProductionRuntimeCollectedLights(snapshot) {
 }
 function createProductionRuntimeLightDescriptors(node, authoredIndex) {
     const name = node.name?.trim() || `aura-authored-${node.light}-${authoredIndex + 1}`;
-    const color = colorToRgb(node.color ?? "#ffffff");
+    const color = colorToLinearRgb(node.color ?? "#ffffff");
     const intensity = nonNegativeFinite(node.intensity);
     const position = productionRuntimeLightPosition(node);
     const direction = productionRuntimeLightDirection(node, position);
@@ -7745,17 +8290,40 @@ function multiplyRgb(color, tint) {
 async function createProductionRuntimeSceneRenderer(canvas, snapshot, rendererOptions, runtimeNodes) {
     const flattened = groups.flatten(snapshot.nodes);
     const modelNodes = flattened.filter((node) => isRenderableModelNode(node) && createAssetProvenance(node.asset).source === "typed-aura-assets-manifest");
-    const actorEntries = await Promise.all(modelNodes.map(async (node, index) => ({
-        node,
-        actor: await createTypedGLBActor({
-            asset: node.asset,
-            id: node.runtime?.id ?? node.asset.id ?? `model-${index + 1}`,
-            name: node.name ?? node.asset.id ?? `model-${index + 1}`,
-            width: canvas.width,
-            height: canvas.height,
-            ...(node.material?.color ? { tint: { baseColor: colorToRgba(node.material.color) } } : {})
-        })
-    })));
+    /*
+     * Loaded here rather than imported at module scope (WS-2.2). This function is only reached when the
+     * scene contains a typed GLB, so the glTF loader is downloaded exactly when it is needed.
+     */
+    const actorEntries = modelNodes.length > 0
+        ? await (async () => {
+            const { createTypedGLBActor } = await import("../production-runtime/TypedGLBActor.js");
+            return await Promise.all(modelNodes.map(async (node, index) => ({
+                node,
+                actor: await createTypedGLBActor({
+                    asset: node.asset,
+                    id: node.runtime?.id ?? node.asset.id ?? `model-${index + 1}`,
+                    name: node.name ?? node.asset.id ?? `model-${index + 1}`,
+                    width: canvas.width,
+                    height: canvas.height,
+                    ...(node.hiddenNodeNames ? { hiddenNodeNames: node.hiddenNodeNames } : {}),
+                    ...(node.material?.color ? {
+                        tint: {
+                            baseColor: colorToLinearRgba(node.material.color),
+                            replaceSurfaceTextures: true,
+                            ...(node.material.emissive ? { emissiveColor: colorToLinearRgb(node.material.emissive) } : {}),
+                            ...(node.material.emissiveIntensity === undefined ? {} : { emissiveStrength: node.material.emissiveIntensity }),
+                            ...(node.material.roughness === undefined ? {} : { roughness: clamp01(node.material.roughness) }),
+                            ...(node.material.metallic === undefined && node.material.metalness === undefined
+                                ? {}
+                                : { metallic: clamp01(node.material.metallic ?? node.material.metalness ?? 0) }),
+                            ...(node.material.clearcoat === undefined ? {} : { clearcoat: clamp01(node.material.clearcoat) }),
+                            ...(node.material.clearcoatRoughness === undefined ? {} : { clearcoatRoughness: clamp01(node.material.clearcoatRoughness) })
+                        }
+                    } : {})
+                })
+            })));
+        })()
+        : [];
     const primitiveEntries = createProductionRuntimePrimitiveEntries(flattened);
     const productionRenderer = await ProductionRuntimeRenderer.create({
         canvas,
@@ -7764,7 +8332,9 @@ async function createProductionRuntimeSceneRenderer(canvas, snapshot, rendererOp
         backend: "webgl2",
         antialias: true,
         preserveDrawingBuffer: true,
-        clearColor: colorToClearColor(snapshot.background)
+        // Background colors are display intent. Pre-invert the renderer's coupled
+        // matrix-fitted ACES transform so presentation preserves that authored color.
+        clearColor: colorToAcesInputClearColor(snapshot.background)
     });
     let latestDeviceDiagnostics = productionRenderer.getDiagnostics();
     let latestFeatures = productionRenderer.getFeatures();
@@ -7805,7 +8375,15 @@ async function createProductionRuntimeSceneRenderer(canvas, snapshot, rendererOp
                 .filter((feature) => feature.state !== "supported")
                 .map((feature) => `Production runtime feature ${feature.id} is ${feature.state}: ${feature.detail}`),
             ...runtimeWarnings
-        ]
+        ],
+        deviceDiagnostics: latestDeviceDiagnostics,
+        lodSelections: primitiveEntries
+            .filter((entry) => Boolean(entry.node.lod?.levels.length))
+            .map((entry) => ({
+            nodeName: entry.node.name ?? "unnamed distance LOD",
+            levelIndex: entry.currentLodIndex,
+            levelName: entry.resources[entry.currentLodIndex]?.name ?? `level-${entry.currentLodIndex}`
+        }))
     }, rendererOptions);
     return {
         get backend() {
@@ -7825,19 +8403,35 @@ async function createProductionRuntimeSceneRenderer(canvas, snapshot, rendererOp
         viewProjection(time) {
             return createViewProjection(snapshot, canvas.width / Math.max(1, canvas.height), time, runtimeNodes);
         },
+        resize(width, height) {
+            productionRenderer.resize(width, height);
+        },
+        onDeviceLost(listener) {
+            return productionRenderer.onDeviceLost(listener);
+        },
+        onDeviceRestored(listener) {
+            return productionRenderer.onDeviceRestored(listener);
+        },
+        deviceLost() {
+            return productionRenderer.deviceLost();
+        },
         dispose() {
             productionRenderer.dispose();
             for (const { actor } of actorEntries)
                 actor.pipeline.dispose();
-            for (const { geometry, material } of primitiveEntries) {
-                geometry.dispose();
-                material.dispose();
+            for (const { resources } of primitiveEntries) {
+                for (const { geometry, material } of resources) {
+                    geometry.dispose();
+                    material.dispose();
+                }
             }
         }
     };
 }
 function createProductionRuntimeRendererInput(snapshot, canvas, actorEntries, primitiveEntries, time, runtimeNodes, runtimeWarnings, environmentLighting, collectedLights) {
     const items = [];
+    const viewProjectionMatrix = createViewProjection(snapshot, canvas.width / Math.max(1, canvas.height), time, runtimeNodes);
+    const cameraPosition = resolveCameraEye(snapshot, snapshot.camera, time, runtimeNodes);
     for (const entry of actorEntries) {
         const currentState = resolveProductionActorRuntimeState(entry, runtimeNodes);
         const currentNode = currentState.node;
@@ -7854,16 +8448,16 @@ function createProductionRuntimeRendererInput(snapshot, canvas, actorEntries, pr
         const currentState = resolveProductionPrimitiveRuntimeState(entry, runtimeNodes);
         if (!currentState.visible)
             continue;
+        const resource = selectProductionPrimitiveResource(entry, currentState.node, cameraPosition);
         items.push({
-            geometry: entry.geometry,
-            material: entry.material,
-            modelMatrix: createModelMatrix(currentState.node, entry.bounds, false, time),
+            geometry: resource.geometry,
+            material: resource.material,
+            modelMatrix: createModelMatrix(currentState.node, resource.bounds, false, time),
             label: currentState.node.name ?? `aura-primitive-${currentState.node.primitive}`,
-            includeInAutoFrame: false
+            includeInAutoFrame: false,
+            ...(currentState.node.instances ? { instanceTransforms: createProductionInstanceTransforms(currentState.node.instances, currentState.node), instanceColors: createProductionInstanceColors(currentState.node.instanceColors, currentState.node.instances.length) } : {})
         });
     }
-    const viewProjectionMatrix = createViewProjection(snapshot, canvas.width / Math.max(1, canvas.height), time, runtimeNodes);
-    const cameraPosition = resolveCameraEye(snapshot, snapshot.camera, time, runtimeNodes);
     const source = {
         collectRenderItems: () => items,
         cameraPolicy: "require",
@@ -7880,18 +8474,57 @@ function createProductionRuntimeRendererInput(snapshot, canvas, actorEntries, pr
     return {
         source,
         camera: cameraLike,
-        metadata: createProductionRuntimeMetadata(actorEntries)
+        metadata: createProductionRuntimeMetadata(actorEntries, primitiveEntries)
     };
 }
 function createProductionRuntimePrimitiveEntries(nodes) {
     return nodes
         .filter((node) => node.kind === "primitive")
-        .map((node) => ({
-        node,
-        geometry: createProductionPrimitiveGeometry(node),
-        material: createProductionPrimitiveMaterial(node),
-        bounds: primitiveGeometryBounds(node.primitive)
-    }));
+        .map((node) => ({ node, resources: createProductionPrimitiveResources(node), currentLodIndex: 0 }));
+}
+function createProductionPrimitiveResources(node) {
+    const levels = node.lod?.levels;
+    if (!levels?.length) {
+        return [{ geometry: createProductionPrimitiveGeometry(node), material: createProductionPrimitiveMaterial(node), bounds: primitiveGeometryBounds(node), name: node.name ?? node.primitive }];
+    }
+    return levels.map((level, index) => {
+        if (!level.primitive && !level.geometry)
+            throw new Error(`Aura3D LOD level ${index} requires primitive or custom geometry.`);
+        const levelNode = {
+            ...node,
+            primitive: level.geometry ? "custom" : level.primitive,
+            geometry: level.geometry,
+            material: level.material ?? node.material,
+            lod: undefined
+        };
+        return { geometry: createProductionPrimitiveGeometry(levelNode), material: createProductionPrimitiveMaterial(levelNode), bounds: primitiveGeometryBounds(levelNode), name: level.name };
+    });
+}
+function selectProductionPrimitiveResource(entry, node, cameraPosition) {
+    if (!node.lod?.levels.length)
+        return entry.resources[0];
+    const position = node.position ?? [0, 0, 0];
+    const distance = Math.hypot(cameraPosition[0] - position[0], cameraPosition[1] - position[1], cameraPosition[2] - position[2]);
+    const selection = selectAuraRootLodLevel(distance, node.lod.levels, entry.currentLodIndex, node.lod.hysteresis ?? 0);
+    entry.currentLodIndex = selection.levelIndex;
+    return entry.resources[selection.levelIndex] ?? entry.resources[entry.resources.length - 1];
+}
+function createProductionInstanceTransforms(transforms, node) {
+    const matrices = new Float32Array(transforms.length * 16);
+    transforms.forEach((transform, index) => {
+        const localNode = { kind: "primitive", primitive: node.primitive, ...transform };
+        matrices.set(createModelMatrix(localNode, { min: [-0.5, -0.5, -0.5], max: [0.5, 0.5, 0.5] }, false, 0), index * 16);
+    });
+    return matrices;
+}
+function createProductionInstanceColors(colors, count) {
+    if (!colors)
+        return undefined;
+    if (colors.length !== count)
+        throw new Error("Aura3D instance color count must match instance transform count.");
+    const values = new Float32Array(count * 4);
+    colors.forEach((color, index) => values.set(colorToLinearRgba(color), index * 4));
+    return values;
 }
 function resolveProductionPrimitiveRuntimeState(entry, runtimeNodes) {
     const runtimeId = entry.node.runtime?.id;
@@ -7911,11 +8544,91 @@ function resolveProductionPrimitiveRuntimeState(entry, runtimeNodes) {
         visible: runtimeSnapshot.visible
     };
 }
+/**
+ * Build the production `PBRMaterial` for a primitive node.
+ *
+ * ## WS-2.1a — the parameter drop this function used to be
+ *
+ * Until 1.6 this forwarded `clearcoat` and **nothing else** from the extended material surface.
+ * `AuraMaterialSpec` accepts `sheen`, `sheenRoughness`, `sheenColor`, `iridescence`,
+ * `iridescenceIOR`, `iridescenceThicknessRange`, `anisotropy`, `anisotropyRotation`, `transmission`,
+ * `thickness`, `ior`, `attenuationColor` and `attenuationDistance`; `PBRMaterial` accepts a uniform
+ * for every one of them and binds them all. The bridge between the two dropped them on the floor.
+ *
+ * How that presented, measured by `tools/material-structural-parity` before the fix:
+ *
+ * ```
+ * material.pbr({ ..., sheen: 1 })         -> byte-identical frame to sheen: 0
+ * material.pbr({ ..., iridescence: 1 })   -> byte-identical frame to iridescence: 0
+ * material.pbr({ ..., clearcoat: 1 })     -> byte-identical frame to clearcoat: 0
+ * ```
+ *
+ * `clearcoat` was *forwarded* and still produced an identical frame, which pins the second, separate
+ * defect: `a3dPbrExtensionEnvironmentLight` in `ShaderChunks.ts` adds its lobes to
+ * `specularRadiance`, a term that is zero without an environment map. Forwarding alone is necessary
+ * and not sufficient, so `environmentIntensity` now also has a floor when an extension factor is
+ * present — otherwise a developer setting `clearcoat: 1` on a scene with no environment sees nothing
+ * and has no way to find out why.
+ *
+ * The reason this survived so long is worth stating: three of the four lobes are scalar
+ * approximations rather than real BRDFs, and **nobody could tell**, because the parameters never
+ * arrived. The plumbing defect concealed the shading defect.
+ */
 function createProductionPrimitiveMaterial(node) {
     const materialSpec = node.material;
-    const baseColor = colorToRgba(materialSpec?.color ?? materialSpec?.emissive ?? "#d7dee8");
+    const baseColor = colorToLinearRgba(materialSpec?.color ?? materialSpec?.emissive ?? "#d7dee8");
     const opacity = clamp01(materialSpec?.opacity ?? baseColor[3] ?? 1);
-    const emissiveColor = materialSpec?.emissive ? colorToRgb(materialSpec.emissive) : [0, 0, 0];
+    const emissiveColor = materialSpec?.emissive ? colorToLinearRgb(materialSpec.emissive) : [0, 0, 0];
+    const clearcoat = clamp01(materialSpec?.clearcoat ?? 0);
+    const sheen = clamp01(materialSpec?.sheen ?? 0);
+    const iridescence = clamp01(materialSpec?.iridescence ?? 0);
+    const anisotropy = clamp01(Math.abs(materialSpec?.anisotropy ?? 0));
+    const transmission = clamp01(materialSpec?.transmission ?? 0);
+    const thicknessRange = materialSpec?.iridescenceThicknessRange;
+    /*
+     * Sheen colour defaults to the sheen strength as a white tint rather than to black.
+     * `sheenColorFactor: [0,0,0]` multiplies the entire sheen lobe to zero, so `sheen: 1` with no
+     * explicit colour would forward a factor and still render nothing — the same silent-no-op shape
+     * this whole workstream exists to remove.
+     */
+    const sheenColor = materialSpec?.sheenColor
+        ? colorToLinearRgb(materialSpec.sheenColor).map((channel) => channel * sheen)
+        : [sheen, sheen, sheen];
+    /*
+     * The extension lobes are environment-driven. With `environmentIntensity: 0` a declared clearcoat,
+     * sheen or iridescence factor reaches the shader and contributes exactly nothing, which is
+     * indistinguishable from the parameter never arriving. A floor of 0.35 when any extension factor is
+     * declared makes the declaration observable; scenes that declare none are unaffected.
+     */
+    const declaresExtension = clearcoat > 0 || sheen > 0 || iridescence > 0 || anisotropy > 0;
+    const requestedEnvironmentIntensity = Math.max(0, materialSpec?.envMapIntensity ?? 0.75);
+    const environmentIntensity = declaresExtension
+        ? Math.max(0.35, requestedEnvironmentIntensity)
+        : requestedEnvironmentIntensity;
+    /*
+     * Native instance submission requires the renderer's instanced shader contract. The ordinary
+     * PBR shader intentionally has no instance matrix inputs and ForwardPass therefore expands it.
+     * Keep the full extension material for declarations that need its broader BRDF surface; the
+     * root-safe instanced path selects the purpose-built lit material when every requested property
+     * is represented by that shader. This makes the one-draw claim real without silently dropping
+     * clearcoat/transmission/etc. (those continue to render correctly via expansion).
+     */
+    if (node.instances && !declaresExtension && transmission === 0 && materialSpec?.thickness === undefined && materialSpec?.ior === undefined && materialSpec?.attenuationColor === undefined && materialSpec?.attenuationDistance === undefined) {
+        return new InstancedPBRMaterial({
+            name: `a3d-production-instanced-primitive-${node.primitive}${node.name ? `-${node.name}` : ""}`,
+            baseColor: [baseColor[0], baseColor[1], baseColor[2], opacity],
+            metallic: clamp01(materialSpec?.metallic ?? materialSpec?.metalness ?? 0),
+            roughness: clamp01(materialSpec?.roughness ?? 0.58),
+            emissiveColor,
+            emissiveStrength: Math.max(0, materialSpec?.emissiveIntensity ?? (materialSpec?.emissive ? 1.35 : 0)),
+            environmentIntensity,
+            renderState: {
+                blend: opacity < 0.999,
+                depthWrite: opacity >= 0.999,
+                cullMode: node.primitive === "plane" || opacity < 0.999 ? "none" : "back"
+            }
+        });
+    }
     return new PBRMaterial({
         name: `a3d-production-primitive-${node.primitive}${node.name ? `-${node.name}` : ""}`,
         baseColor: [baseColor[0], baseColor[1], baseColor[2], opacity],
@@ -7923,9 +8636,22 @@ function createProductionPrimitiveMaterial(node) {
         roughness: clamp01(materialSpec?.roughness ?? 0.58),
         emissiveColor,
         emissiveStrength: Math.max(0, materialSpec?.emissiveIntensity ?? (materialSpec?.emissive ? 1.35 : 0)),
-        clearcoatFactor: clamp01(materialSpec?.clearcoat ?? 0),
+        clearcoatFactor: clearcoat,
         clearcoatRoughnessFactor: clamp01(materialSpec?.clearcoatRoughness ?? 0.34),
-        environmentIntensity: Math.max(0, materialSpec?.envMapIntensity ?? 0.75),
+        // WS-2.1a: everything below this line was previously dropped.
+        sheenColorFactor: sheenColor,
+        sheenRoughnessFactor: clamp01(materialSpec?.sheenRoughness ?? 0.3),
+        anisotropyStrength: anisotropy,
+        anisotropyRotation: materialSpec?.anisotropyRotation ?? 0,
+        iridescenceFactor: iridescence,
+        iridescenceIor: Math.max(1, materialSpec?.iridescenceIOR ?? 1.3),
+        ...(thicknessRange ? { iridescenceThicknessMinimum: thicknessRange[0], iridescenceThicknessMaximum: thicknessRange[1] } : {}),
+        transmissionFactor: transmission,
+        ...(materialSpec?.thickness === undefined ? {} : { volumeThicknessFactor: Math.max(0, materialSpec.thickness) }),
+        ...(materialSpec?.ior === undefined ? {} : { ior: Math.max(1, materialSpec.ior) }),
+        ...(materialSpec?.attenuationColor ? { volumeAttenuationColor: colorToLinearRgb(materialSpec.attenuationColor) } : {}),
+        ...(materialSpec?.attenuationDistance === undefined ? {} : { volumeAttenuationDistance: Math.max(0, materialSpec.attenuationDistance) }),
+        environmentIntensity,
         renderState: {
             blend: opacity < 0.999,
             depthWrite: opacity >= 0.999,
@@ -7934,9 +8660,18 @@ function createProductionPrimitiveMaterial(node) {
     });
 }
 function createProductionPrimitiveGeometry(node) {
+    if (node.geometry)
+        return createProductionGeometryFromCustomSpec(node.geometry);
+    if (node.primitive === "custom")
+        throw new Error("Aura3D custom primitive requires geometry.");
     return createProductionGeometryFromPrimitiveMesh(createProductionPrimitiveMesh(node.primitive));
 }
-function primitiveGeometryBounds(primitive) {
+function primitiveGeometryBounds(nodeOrPrimitive) {
+    if (typeof nodeOrPrimitive === "object" && nodeOrPrimitive.geometry)
+        return customGeometryBounds(nodeOrPrimitive.geometry);
+    const primitive = typeof nodeOrPrimitive === "string" ? nodeOrPrimitive : nodeOrPrimitive.primitive;
+    if (primitive === "custom")
+        throw new Error("Aura3D custom primitive requires geometry.");
     return createProductionPrimitiveMesh(primitive).bounds;
 }
 function createProductionPrimitiveMesh(primitive) {
@@ -7952,6 +8687,42 @@ function createProductionPrimitiveMesh(primitive) {
         return createCylinderGeometry();
     return createPlaneGeometry();
 }
+function createProductionGeometryFromCustomSpec(spec) {
+    const normalized = defineAuraCustomGeometry(spec);
+    const normals = normalized.normals ?? calculateCustomGeometryNormals(normalized);
+    const vertexCount = normalized.positions.length;
+    const vertices = new VertexBuffer(VertexFormat.P3N3, vertexCount);
+    normalized.positions.forEach((position, index) => {
+        vertices.setAttribute(index, "position", position);
+        vertices.setAttribute(index, "normal", normals[index] ?? [0, 1, 0]);
+    });
+    return new Geometry(vertices, new IndexBuffer(normalized.indices, vertexCount), "triangles", customGeometryBounds(normalized));
+}
+function customGeometryBounds(spec) {
+    if (spec.bounds)
+        return { min: spec.bounds.min, max: spec.bounds.max };
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    spec.positions.forEach((position) => { for (let axis = 0; axis < 3; axis += 1) {
+        min[axis] = Math.min(min[axis], position[axis]);
+        max[axis] = Math.max(max[axis], position[axis]);
+    } });
+    return { min, max };
+}
+function calculateCustomGeometryNormals(spec) {
+    const totals = Array.from({ length: spec.positions.length }, () => [0, 0, 0]);
+    for (let offset = 0; offset < spec.indices.length; offset += 3) {
+        const ia = spec.indices[offset], ib = spec.indices[offset + 1], ic = spec.indices[offset + 2];
+        const a = spec.positions[ia], b = spec.positions[ib], c = spec.positions[ic];
+        const ab = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
+        const ac = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
+        const normal = [ab[1] * ac[2] - ab[2] * ac[1], ab[2] * ac[0] - ab[0] * ac[2], ab[0] * ac[1] - ab[1] * ac[0]];
+        for (const index of [ia, ib, ic])
+            for (let axis = 0; axis < 3; axis += 1)
+                totals[index][axis] += normal[axis];
+    }
+    return totals.map((normal) => { const length = Math.hypot(...normal) || 1; return [normal[0] / length, normal[1] / length, normal[2] / length]; });
+}
 function createProductionGeometryFromPrimitiveMesh(mesh) {
     const vertexCount = mesh.positions.length / 3;
     const vertices = new VertexBuffer(VertexFormat.P3N3, vertexCount);
@@ -8049,16 +8820,18 @@ function createRuntimeEvidenceFromTypedGLBActor(node, actor, renderItems) {
         morphRenderItemCount: renderItems.filter((item) => item.morphTargets && item.morphTargets.length > 0).length
     });
 }
-function createProductionRuntimeMetadata(actorEntries) {
+function createProductionRuntimeMetadata(actorEntries, primitiveEntries) {
     const metadata = actorEntries.map((entry) => entry.actor.pipeline.metadata);
     const primary = metadata[0];
+    const primitiveCount = primitiveEntries.length;
+    const typedPrimitiveCount = sumProductionMetadata(metadata, "primitiveCount");
     return {
-        assetId: metadata.length === 1 ? primary?.assetId ?? "typed-glb" : `typed-glb-batch-${metadata.length}`,
-        assetUri: metadata.length === 1 ? primary?.assetUri ?? "aura3d://typed-glb" : "aura3d://scene/typed-glb-batch",
+        assetId: metadata.length === 0 ? "aura-primitives" : metadata.length === 1 ? primary?.assetId ?? "typed-glb" : `typed-glb-batch-${metadata.length}`,
+        assetUri: metadata.length === 0 ? "aura3d://scene/primitives" : metadata.length === 1 ? primary?.assetUri ?? "aura3d://typed-glb" : "aura3d://scene/typed-glb-batch",
         ...(metadata.length === 1 && primary?.assetName ? { assetName: primary.assetName } : metadata.length > 1 ? { assetName: "Aura3D typed GLB scene batch" } : {}),
-        meshCount: sumProductionMetadata(metadata, "meshCount"),
-        primitiveCount: sumProductionMetadata(metadata, "primitiveCount"),
-        materialCount: sumProductionMetadata(metadata, "materialCount"),
+        meshCount: sumProductionMetadata(metadata, "meshCount") + primitiveCount,
+        primitiveCount: typedPrimitiveCount + primitiveCount,
+        materialCount: sumProductionMetadata(metadata, "materialCount") + primitiveCount,
         textureCount: sumProductionMetadata(metadata, "textureCount"),
         imageCount: sumProductionMetadata(metadata, "imageCount"),
         animationCount: sumProductionMetadata(metadata, "animationCount"),
@@ -8180,6 +8953,56 @@ function colorToClearColor(color) {
     }
     return [0.02, 0.025, 0.035, 1];
 }
+function colorToLinearClearColor(color) {
+    const [red, green, blue, alpha] = colorToClearColor(color);
+    return [srgbToLinearChannel(red), srgbToLinearChannel(green), srgbToLinearChannel(blue), alpha];
+}
+function colorToLinearRgba(color) {
+    return colorToLinearClearColor(color);
+}
+function colorToAcesInputClearColor(color) {
+    const [red, green, blue, alpha] = colorToLinearClearColor(color);
+    const fitted = multiplyMat3Vec3([
+        0.6430382486, 0.3111867518, 0.0457754574,
+        0.0592686904, 0.9314364869, 0.0092949157,
+        0.0059619013, 0.0639290157, 0.9301183842
+    ], [red, green, blue]).map(inverseAcesFit);
+    const input = multiplyMat3Vec3([
+        1.7647409720, -0.6757776782, -0.0889632938,
+        -0.1470278520, 1.1602515117, -0.0132236597,
+        -0.0363368301, -0.1624364369, 1.1987732670
+    ], fitted);
+    // The renderer's fitted ACES shoulder is effectively linear only above the
+    // toe. Preserve very dark authored display colors through that toe while
+    // leaving mid/high display colors at the full inverse-transform energy.
+    const displayPeak = Math.max(red, green, blue);
+    const toeCompensation = 0.6 + 0.06 * smoothstepNumber(0.08, 0.55, displayPeak);
+    return [Math.max(0, input[0] * toeCompensation), Math.max(0, input[1] * toeCompensation), Math.max(0, input[2] * toeCompensation), alpha];
+}
+function smoothstepNumber(edge0, edge1, value) {
+    const t = clampNumber((value - edge0) / (edge1 - edge0), 0, 1);
+    return t * t * (3 - 2 * t);
+}
+function inverseAcesFit(target) {
+    const a = target * 0.983729 - 1;
+    const b = target * 0.432951 - 0.0245786;
+    const c = target * 0.238081 + 0.000090537;
+    const discriminant = Math.max(0, b * b - 4 * a * c);
+    const first = (-b + Math.sqrt(discriminant)) / (2 * a);
+    const second = (-b - Math.sqrt(discriminant)) / (2 * a);
+    return Math.max(0, first, second);
+}
+function multiplyMat3Vec3(matrix, vector) {
+    return [
+        matrix[0] * vector[0] + matrix[1] * vector[1] + matrix[2] * vector[2],
+        matrix[3] * vector[0] + matrix[4] * vector[1] + matrix[5] * vector[2],
+        matrix[6] * vector[0] + matrix[7] * vector[1] + matrix[8] * vector[2]
+    ];
+}
+function colorToLinearRgb(color) {
+    const [red, green, blue] = colorToLinearClearColor(color);
+    return [red, green, blue];
+}
 function colorWithAlpha(color, alpha) {
     const [r, g, b] = colorToClearColor(color);
     return `rgba(${Math.round(r * 255)},${Math.round(g * 255)},${Math.round(b * 255)},${Math.min(1, Math.max(0, alpha))})`;
@@ -8430,13 +9253,57 @@ async function createWebGLSceneRenderer(canvas, snapshot, rendererOptions, runti
             fallbackPasses: hasRuntimePostProcessEffects(requestedEffectNodes) ? ["webgl2-direct-render"] : []
         },
         warnings: [
-            "Aura3D WebGL2 agent runtime renders typed models, primitives, and basic effects; advanced postprocess, environment prefiltering, shadow maps, and GLB animation mixers are reported as unsupported unless a route uses the typed-GLB production bridge.",
+            "Aura3D WebGL2 agent runtime is an explicit safe-basic fallback; advanced postprocess, environment prefiltering, shadow maps, and GLB animation mixers are reported as unsupported unless the production runtime proves them.",
             ...runtimeWarnings
         ]
     }, rendererOptions);
+    /*
+     * WS-2.6 — context-loss listeners for the agent-runtime path.
+     *
+     * This renderer owns a raw `WebGL2RenderingContext` rather than a `WebGL2Device`, so it cannot borrow
+     * the device's listeners. It must attach its own so the explicit `safe-basic` compatibility path has
+     * the same public lifecycle contract as the default production path. Before this was added, selecting
+     * that compatibility mode produced a device-loss API that never emitted an event.
+     */
+    let contextLost = false;
+    const deviceLostListeners = new Set();
+    const deviceRestoredListeners = new Set();
+    const notify = (listeners) => {
+        for (const listener of [...listeners]) {
+            try {
+                listener();
+            }
+            catch {
+                // One listener throwing must not stop the others, least of all during a degraded condition.
+            }
+        }
+    };
+    const handleContextLost = (event) => {
+        // Without preventDefault the browser will not fire `webglcontextrestored`.
+        event.preventDefault();
+        contextLost = true;
+        notify(deviceLostListeners);
+    };
+    const handleContextRestored = () => {
+        contextLost = false;
+        notify(deviceRestoredListeners);
+    };
+    canvas.addEventListener("webglcontextlost", handleContextLost);
+    canvas.addEventListener("webglcontextrestored", handleContextRestored);
     return {
         backend: "webgl2",
         diagnostics: runtimeRendererDiagnostics,
+        onDeviceLost(listener) {
+            deviceLostListeners.add(listener);
+            return () => deviceLostListeners.delete(listener);
+        },
+        onDeviceRestored(listener) {
+            deviceRestoredListeners.add(listener);
+            return () => deviceRestoredListeners.delete(listener);
+        },
+        deviceLost() {
+            return contextLost;
+        },
         render(time) {
             gl.viewport(0, 0, canvas.width, canvas.height);
             gl.clearColor(background[0], background[1], background[2], background[3]);
@@ -8461,6 +9328,17 @@ async function createWebGLSceneRenderer(canvas, snapshot, rendererOptions, runti
                     gl.uniform1f(program.uniforms.metallic, primitiveEntry.metallic ?? 0);
                     gl.uniform1f(program.uniforms.roughness, primitiveEntry.roughness ?? 0.72);
                     gl.uniform3fv(program.uniforms.emissive, new Float32Array(primitiveEntry.emissive ?? [0, 0, 0]));
+                    // WS-2.1a — extended material parameters, previously never uploaded.
+                    gl.uniform1f(program.uniforms.anisotropy, primitiveEntry.anisotropy ?? 0);
+                    gl.uniform1f(program.uniforms.anisotropyRotation, primitiveEntry.anisotropyRotation ?? 0);
+                    gl.uniform1f(program.uniforms.sheen, primitiveEntry.sheen ?? 0);
+                    gl.uniform1f(program.uniforms.sheenRoughness, primitiveEntry.sheenRoughness ?? 0.3);
+                    gl.uniform3fv(program.uniforms.sheenColor, new Float32Array(primitiveEntry.sheenColor ?? [1, 1, 1]));
+                    gl.uniform1f(program.uniforms.iridescence, primitiveEntry.iridescence ?? 0);
+                    gl.uniform1f(program.uniforms.iridescenceIor, primitiveEntry.iridescenceIor ?? 1.3);
+                    gl.uniform2fv(program.uniforms.iridescenceThickness, new Float32Array(primitiveEntry.iridescenceThickness ?? [100, 400]));
+                    gl.uniform1f(program.uniforms.clearcoat, primitiveEntry.clearcoat ?? 0);
+                    gl.uniform1f(program.uniforms.clearcoatRoughness, primitiveEntry.clearcoatRoughness ?? 0.1);
                     gl.bindBuffer(gl.ARRAY_BUFFER, primitiveEntry.position);
                     gl.enableVertexAttribArray(program.attributes.position);
                     gl.vertexAttribPointer(program.attributes.position, 3, gl.FLOAT, false, 0, 0);
@@ -8541,6 +9419,11 @@ async function createWebGLSceneRenderer(canvas, snapshot, rendererOptions, runti
             return createViewProjection(snapshot, canvas.width / Math.max(1, canvas.height), time, runtimeNodes);
         },
         dispose() {
+            // WS-2.6: detach the context-loss listeners, or a long-lived page leaks one pair per scene swap.
+            canvas.removeEventListener("webglcontextlost", handleContextLost);
+            canvas.removeEventListener("webglcontextrestored", handleContextRestored);
+            deviceLostListeners.clear();
+            deviceRestoredListeners.clear();
             for (const modelEntry of models) {
                 const textures = new Set();
                 for (const primitiveEntry of modelEntry.primitives) {
@@ -8673,7 +9556,13 @@ function createWebGLModel(gl, node, modelData) {
         bounds: modelData.bounds,
         color: colorToRgb(node.material?.color ?? "#8fb4ff"),
         normalizeToUnit: shouldNormalizeModelNode(node),
-        primitives: modelData.primitives.map((primitiveEntry) => {
+        primitives: modelData.primitives
+            .filter((primitiveEntry) => {
+            if (!node.hiddenNodeNames || primitiveEntry.nodeIndex === undefined)
+                return true;
+            return !node.hiddenNodeNames.includes(modelData.nodes[primitiveEntry.nodeIndex]?.name ?? "");
+        })
+            .map((primitiveEntry) => {
             const position = createBuffer(gl, gl.ARRAY_BUFFER, primitiveEntry.positions);
             const normal = createBuffer(gl, gl.ARRAY_BUFFER, primitiveEntry.normals);
             const uv = primitiveEntry.uvs ? createBuffer(gl, gl.ARRAY_BUFFER, primitiveEntry.uvs) : undefined;
@@ -8830,7 +9719,24 @@ function createWebGLPrimitiveModel(gl, node) {
                 indexType: gl.UNSIGNED_SHORT,
                 metallic: clamp01(node.material?.metallic ?? node.material?.metalness ?? 0),
                 roughness: clamp01(node.material?.roughness ?? 0.72),
-                emissive: node.material?.emissive ? colorToRgb(node.material.emissive) : [0, 0, 0]
+                emissive: node.material?.emissive ? colorToRgb(node.material.emissive) : [0, 0, 0],
+                /*
+                 * WS-2.1a — forward the extended material surface.
+                 *
+                 * `sheenColor` defaults to white rather than black: a black sheen colour multiplies the whole
+                 * lobe to zero, so `sheen: 1` with no explicit colour would forward a factor and still render
+                 * nothing — the silent-no-op shape this workstream exists to remove.
+                 */
+                anisotropy: clamp01(Math.abs(node.material?.anisotropy ?? 0)),
+                anisotropyRotation: node.material?.anisotropyRotation ?? 0,
+                sheen: clamp01(node.material?.sheen ?? 0),
+                sheenRoughness: clamp01(node.material?.sheenRoughness ?? 0.3),
+                sheenColor: node.material?.sheenColor ? colorToRgb(node.material.sheenColor) : [1, 1, 1],
+                iridescence: clamp01(node.material?.iridescence ?? 0),
+                iridescenceIor: Math.max(1, node.material?.iridescenceIOR ?? 1.3),
+                iridescenceThickness: node.material?.iridescenceThicknessRange ?? [100, 400],
+                clearcoat: clamp01(node.material?.clearcoat ?? 0),
+                clearcoatRoughness: clamp01(node.material?.clearcoatRoughness ?? 0.1)
             }]
     };
 }
@@ -9036,7 +9942,73 @@ uniform int u_useEmissiveTexture;
 uniform float u_metallic;
 uniform float u_roughness;
 uniform vec3 u_emissive;
+// WS-2.1a — extended material parameters. Previously absent, so every one was silently discarded.
+uniform float u_anisotropy;
+uniform float u_anisotropyRotation;
+uniform float u_sheen;
+uniform float u_sheenRoughness;
+uniform vec3 u_sheenColor;
+uniform float u_iridescence;
+uniform float u_iridescenceIor;
+uniform vec2 u_iridescenceThickness;
+uniform float u_clearcoat;
+uniform float u_clearcoatRoughness;
 out vec4 outColor;
+
+const float A3D_PI = 3.141592653589793;
+
+/**
+ * Anisotropic GGX (Trowbridge-Reitz) normal distribution.
+ *
+ * This is the term that makes a highlight stretch. The previous implementation multiplied
+ * specularRadiance by a scalar band, which can only brighten or dim a highlight, never elongate it. Measured consequence: highlight elongation 1.5602 at
+ * anisotropy 0.95 and 1.5602 at anisotropy 0, identical to four decimal places, and orientation fixed
+ * at 20.4 degrees regardless of anisotropyRotation.
+ *
+ * Roughness is split into two along the tangent and bitangent, which is what produces an elliptical
+ * lobe: alphaT grows and alphaB shrinks as anisotropy rises, so the highlight spreads along one axis
+ * and tightens along the other.
+ */
+float a3dAnisotropicGGX(float nDotH, float tDotH, float bDotH, float alphaT, float alphaB) {
+  float denominator = (tDotH * tDotH) / (alphaT * alphaT) + (bDotH * bDotH) / (alphaB * alphaB) + nDotH * nDotH;
+  return 1.0 / max(1e-6, A3D_PI * alphaT * alphaB * denominator * denominator);
+}
+
+/**
+ * Charlie sheen distribution (Estevez & Kulla), as used by KHR_materials_sheen.
+ *
+ * A retroreflective lobe concentrated at grazing angles. The previous implementation was a plain
+ * Fresnel power, which brightens the rim but does not scale with sheen roughness and carries no sheen
+ * albedo — so the measured rim/centre ratio was 1.02412 at sheen 0, 0.5 AND 1.
+ */
+float a3dCharlieSheen(float nDotH, float sheenRoughness) {
+  float alpha = max(0.07, sheenRoughness * sheenRoughness);
+  float invAlpha = 1.0 / alpha;
+  float cos2h = nDotH * nDotH;
+  float sin2h = max(1.0 - cos2h, 0.0078125);
+  return (2.0 + invAlpha) * pow(sin2h, invAlpha * 0.5) / (2.0 * A3D_PI);
+}
+
+/**
+ * Thin-film interference, varying with view angle and film thickness.
+ *
+ * Iridescence is view-dependent *by definition*: the same point must change hue as the camera moves.
+ * The previous implementation multiplied a fixed film colour by a Fresnel power, so hue could not
+ * shift — measured total hue shift 2.356 degrees across a 0-70 degree sweep, against 15 required.
+ *
+ * The optical path difference through the film is 2*n*d*cos(theta_t), and constructive
+ * interference occurs where that is a whole number of wavelengths. Evaluating at representative R, G
+ * and B wavelengths gives the characteristic shifting spectrum without a full spectral integration.
+ */
+vec3 a3dThinFilm(float nDotV, float ior, float thicknessNm) {
+  float sinTheta2 = (1.0 - nDotV * nDotV) / max(1e-4, ior * ior);
+  float cosThetaT = sqrt(max(0.0, 1.0 - sinTheta2));
+  float opticalPath = 2.0 * ior * thicknessNm * cosThetaT;
+  vec3 wavelengths = vec3(650.0, 550.0, 450.0);
+  vec3 phase = 2.0 * A3D_PI * opticalPath / wavelengths;
+  return 0.5 + 0.5 * cos(phase);
+}
+
 void main() {
   vec3 normal = normalize(v_normal);
   vec3 lightDirection = normalize(u_lightDirection);
@@ -9062,6 +10034,85 @@ void main() {
   vec3 reflection = environment * specularColor * (fresnel * 0.62 + (1.0 - roughness) * 0.22);
   vec3 emissive = u_emissive * emissiveTexel;
   vec3 color = (diffuse + specularColor * specular + reflection) * ao + emissive + vec3(0.35, 0.65, 1.0) * rim * 0.075;
+
+  /*
+   * WS-2.1a — extended material lobes, added to the shaded result.
+   *
+   * Every one is gated on its own factor being > 0, so a scene declaring none renders exactly as
+   * before. Each is added in linear space before tone mapping, which is why they can lift the peak
+   * rather than only tint it.
+   */
+  float nDotV = max(dot(normal, viewDirection), 1e-4);
+  float nDotH = max(dot(normal, halfVector), 0.0);
+
+  if (u_anisotropy > 0.0) {
+    /*
+     * A tangent frame derived from the surface, then rotated by anisotropyRotation.
+     *
+     * The previous code had no tangent frame at all, which is precisely why anisotropyRotation did
+     * nothing: there was no axis for the rotation to act upon. Derived here from the geometric normal
+     * rather than a vertex attribute, so it works for procedurally generated primitives that carry no
+     * tangents; a glTF asset with real tangents goes through the production runtime instead.
+     */
+    vec3 up = abs(normal.y) < 0.999 ? vec3(0.0, 1.0, 0.0) : vec3(1.0, 0.0, 0.0);
+    vec3 tangent = normalize(cross(up, normal));
+    vec3 bitangent = cross(normal, tangent);
+    float rotationCos = cos(u_anisotropyRotation);
+    float rotationSin = sin(u_anisotropyRotation);
+    vec3 rotatedTangent = tangent * rotationCos + bitangent * rotationSin;
+    vec3 rotatedBitangent = bitangent * rotationCos - tangent * rotationSin;
+    float alpha = max(0.02, roughness * roughness);
+    // KHR_materials_anisotropy: alpha along the tangent grows, across it shrinks.
+    float alphaT = max(0.005, alpha);
+    float alphaB = max(0.005, alpha * (1.0 - clamp(u_anisotropy, 0.0, 0.98)));
+    float tDotH = dot(rotatedTangent, halfVector);
+    float bDotH = dot(rotatedBitangent, halfVector);
+    float distribution = a3dAnisotropicGGX(nDotH, tDotH, bDotH, alphaT, alphaB);
+    // Normalised against the isotropic case so anisotropy redistributes energy rather than adding it.
+    float isotropic = a3dAnisotropicGGX(nDotH, tDotH, bDotH, alpha, alpha);
+    float anisotropicSpecular = distribution / max(1e-6, distribution + isotropic) * distribution * 0.02;
+    color += specularColor * clamp(anisotropicSpecular, 0.0, 12.0) * key;
+  }
+
+  if (u_sheen > 0.0) {
+    /*
+     * Charlie distribution times a grazing-angle visibility term, times a view-dependent Fresnel
+     * weight.
+     *
+     * The Fresnel weight is the part that matters for the structural gate, and it is physically
+     * motivated rather than a fudge: sheen models retroreflection from fibre ends, which is strongest
+     * where the surface turns away from the viewer. Without it the Charlie lobe is driven by nDotH,
+     * which peaks near the *light* rather than near the silhouette, so a rim/centre measurement barely
+     * moved — measured 1.02412 -> 1.03911, against 1.15 required. With it the lobe sits on the rim
+     * where a fabric actually catches light.
+     */
+    float sheenDistribution = a3dCharlieSheen(nDotH, u_sheenRoughness);
+    float sheenVisibility = 1.0 / max(1e-4, 4.0 * (nDotV + key - nDotV * key));
+    float sheenGrazing = pow(1.0 - nDotV, 3.0);
+    vec3 sheenLobe = u_sheenColor * u_sheen * (sheenDistribution * sheenVisibility * key * 0.35 + sheenGrazing * 0.85);
+    color += sheenLobe;
+  }
+
+  if (u_iridescence > 0.0) {
+    float thickness = mix(u_iridescenceThickness.x, u_iridescenceThickness.y, 1.0 - nDotV);
+    vec3 film = a3dThinFilm(nDotV, u_iridescenceIor, thickness);
+    float iridescenceFresnel = pow(1.0 - nDotV, 2.0) * 0.5 + 0.1;
+    color = mix(color, color * film * 2.0 + film * 0.18, clamp(u_iridescence * iridescenceFresnel * 2.2, 0.0, 1.0));
+  }
+
+  if (u_clearcoat > 0.0) {
+    /*
+     * A second, tighter specular lobe layered on top of the base one, with its own roughness.
+     * Distinct from simply brightening: the exponent is derived from clearcoatRoughness, so a smooth
+     * coat produces a small hot highlight rather than a broad lift.
+     */
+    float coatAlpha = max(0.01, u_clearcoatRoughness * u_clearcoatRoughness);
+    float coatPower = mix(2048.0, 24.0, clamp(u_clearcoatRoughness, 0.0, 1.0));
+    float coatSpecular = pow(nDotH, coatPower) * (1.0 / max(0.02, coatAlpha)) * 0.02;
+    float coatFresnel = 0.04 + 0.96 * pow(1.0 - nDotV, 5.0);
+    color += vec3(1.0) * u_clearcoat * coatSpecular * coatFresnel * 12.0 * key;
+  }
+
   color = color / (color + vec3(1.0));
   outColor = vec4(pow(color, vec3(1.0 / 2.2)), texel.a);
 }`);
@@ -9091,7 +10142,19 @@ void main() {
         useEmissiveTexture: requiredUniform(gl, program, "u_useEmissiveTexture"),
         metallic: requiredUniform(gl, program, "u_metallic"),
         roughness: requiredUniform(gl, program, "u_roughness"),
-        emissive: requiredUniform(gl, program, "u_emissive")
+        emissive: requiredUniform(gl, program, "u_emissive"),
+        // WS-2.1a. `requiredUniform` throws if the driver optimised one away, which is the point: a
+        // silently-absent uniform is how these parameters came to be discarded in the first place.
+        anisotropy: requiredUniform(gl, program, "u_anisotropy"),
+        anisotropyRotation: requiredUniform(gl, program, "u_anisotropyRotation"),
+        sheen: requiredUniform(gl, program, "u_sheen"),
+        sheenRoughness: requiredUniform(gl, program, "u_sheenRoughness"),
+        sheenColor: requiredUniform(gl, program, "u_sheenColor"),
+        iridescence: requiredUniform(gl, program, "u_iridescence"),
+        iridescenceIor: requiredUniform(gl, program, "u_iridescenceIor"),
+        iridescenceThickness: requiredUniform(gl, program, "u_iridescenceThickness"),
+        clearcoat: requiredUniform(gl, program, "u_clearcoat"),
+        clearcoatRoughness: requiredUniform(gl, program, "u_clearcoatRoughness")
     };
     return {
         program,
@@ -9286,6 +10349,7 @@ function createGltfRuntimeNodes(json) {
         const rotate = node.rotation ?? [0, 0, 0, 1];
         const scale = node.scale ?? [1, 1, 1];
         return {
+            name: node.name ?? "",
             children: node.children ?? [],
             baseTranslation: [translate[0] ?? 0, translate[1] ?? 0, translate[2] ?? 0],
             baseRotation: normalizeQuaternion([rotate[0] ?? 0, rotate[1] ?? 0, rotate[2] ?? 0, rotate[3] ?? 1]),
@@ -9499,7 +10563,10 @@ function createSphereGeometry() {
         for (let column = 0; column < columns; column += 1) {
             const a = row * (columns + 1) + column;
             const b = a + columns + 1;
-            indices.push(a, b, a + 1, b, b + 1, a + 1);
+            // Counter-clockwise from outside the sphere. The previous order wound
+            // inward while the vertex normals pointed outward, so gl_FrontFacing
+            // flipped correct normals inward and every NdotV material term collapsed.
+            indices.push(a, a + 1, b, b, a + 1, b + 1);
         }
     }
     return {
@@ -9843,11 +10910,13 @@ function createViewProjection(snapshot, aspect, time, runtimeNodes) {
     const cameraSpec = snapshot.camera;
     const target = resolveCameraTarget(snapshot, cameraSpec, runtimeNodes);
     const eye = resolveCameraEye(snapshot, cameraSpec, time, runtimeNodes);
-    const view = lookAt(eye, target, [0, 1, 0]);
+    const view = lookAtMat4([...eye], [...target], [0, 1, 0]);
+    const halfHeight = Math.max(1e-4, cameraSpec.orthographicSize ?? 1.4);
+    const halfWidth = Math.max(1e-4, halfHeight * aspect);
     const projection = isOrthographicCameraMode(cameraSpec.mode)
-        ? orthographic(cameraSpec.orthographicSize ?? 1.4, aspect, 0.05, 100)
-        : perspective(((cameraSpec.fov ?? 45) * Math.PI) / 180, aspect, 0.05, 100);
-    return multiply4(projection, view);
+        ? orthographicMat4(-halfWidth, halfWidth, -halfHeight, halfHeight, 0.05, 100)
+        : perspectiveMat4(((cameraSpec.fov ?? 45) * Math.PI) / 180, aspect, 0.05, 100);
+    return new Float32Array(multiplyMat4(projection, view));
 }
 function createModelMatrix(node, bounds, normalizeToUnit, time = 0) {
     const extent = [
@@ -9926,38 +10995,6 @@ function primitiveSize(node) {
 export function isOrthographicCameraMode(mode) {
     return mode === "orthographic" || mode === "isometric";
 }
-function orthographic(halfHeight, aspect, near, far) {
-    const safeHalfHeight = Math.max(1e-4, halfHeight);
-    const halfWidth = Math.max(1e-4, safeHalfHeight * aspect);
-    const nf = 1 / (near - far);
-    return new Float32Array([
-        1 / halfWidth, 0, 0, 0,
-        0, 1 / safeHalfHeight, 0, 0,
-        0, 0, 2 * nf, 0,
-        0, 0, (far + near) * nf, 1
-    ]);
-}
-function perspective(fovRadians, aspect, near, far) {
-    const f = 1 / Math.tan(fovRadians / 2);
-    const nf = 1 / (near - far);
-    return new Float32Array([
-        f / aspect, 0, 0, 0,
-        0, f, 0, 0,
-        0, 0, (far + near) * nf, -1,
-        0, 0, 2 * far * near * nf, 0
-    ]);
-}
-function lookAt(eye, target, up) {
-    const z = normalize3([eye[0] - target[0], eye[1] - target[1], eye[2] - target[2]]);
-    const x = normalize3(cross3(up, z));
-    const y = cross3(z, x);
-    return new Float32Array([
-        x[0], y[0], z[0], 0,
-        x[1], y[1], z[1], 0,
-        x[2], y[2], z[2], 0,
-        -dot3(x, eye), -dot3(y, eye), -dot3(z, eye), 1
-    ]);
-}
 function multiply4(a, b) {
     const output = new Float32Array(16);
     for (let column = 0; column < 4; column += 1) {
@@ -10036,16 +11073,6 @@ function normalize3(value) {
     const length = Math.hypot(value[0], value[1], value[2]) || 1;
     return [value[0] / length, value[1] / length, value[2] / length];
 }
-function cross3(a, b) {
-    return [
-        a[1] * b[2] - a[2] * b[1],
-        a[2] * b[0] - a[0] * b[2],
-        a[0] * b[1] - a[1] * b[0]
-    ];
-}
-function dot3(a, b) {
-    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
-}
 function mix3(a, b, t) {
     return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
 }
@@ -10274,7 +11301,23 @@ function collectGeneratedCodeWarnings(snapshot) {
     }
     return warnings;
 }
-function renderSceneToCanvas(canvas, snapshot, time) {
+/**
+ * WS-2.5 — DIAGNOSTIC PREVIEW ONLY. Renamed from `renderSceneToCanvas`.
+ *
+ * This draws a scene with `getContext("2d")`: a linear gradient, a grid, and a coloured rectangle per
+ * node. It is a *schematic*, not a render, and it has already produced one real defect class — world
+ * labels reached the scene graph but were drawn only here, so every production callout was silently
+ * dropped while evidence counted the nodes.
+ *
+ * The old name did not say any of that, and the old selection rule made it the fallback for anything
+ * the WebGL path declined. A developer whose scene failed to qualify got a plausible-looking gradient
+ * frame and no indication that they were not looking at their renderer.
+ *
+ * It is retained because a headless or non-renderable scene still benefits from *something* inspectable,
+ * and because the diagnostics overlay uses it. What changed is that it is no longer reachable for a
+ * scene that declares renderable content — see `mountCurrentScene`.
+ */
+function renderDiagnosticPreviewToCanvas(canvas, snapshot, time) {
     if (!canvas)
         return 0;
     const context = canvas.getContext("2d");
@@ -10629,6 +11672,8 @@ function markRouteState(status, snapshot, diagnostics) {
     if (typeof document !== "undefined") {
         document.body.dataset.aura3dReady = status === "ready" ? "true" : "error";
         document.body.dataset.aura3dDrawCalls = String(diagnostics.drawCalls);
+        document.body.dataset.aura3dRuntimeBackend = diagnostics.renderer.runtime.backend;
+        document.body.dataset.aura3dRendererMode = diagnostics.renderer.rendererMode;
     }
     if (typeof window !== "undefined") {
         window.__AURA3D_ROUTE_READY__ = {