@aura3d/engine 2.0.4 → 3.0.1

package/dist/engine/agent-api/index.d.ts

@@ -1,4 +1,9 @@
-import type { Collider, ColliderDescriptor, CollisionEvent, Constraint, ConstraintDescriptor, Contact, DebugLine, PhysicsBackendSelection, PhysicsShape, PhysicsSnapshot, PhysicsWorldDescriptor, RaycastHit, RaycastOptions, RigidBody, RigidBodyDescriptor, RigidBodyType, ScenePhysicsNode, SphereCastHit } from "../../physics/index.js";
+import { type AuraPerformanceQuality } from "./RootRuntimeSupport.js";
+export type { AuraPerformanceQuality } from "./RootRuntimeSupport.js";
+import type { Collider, ColliderDescriptor, CollisionEvent, Constraint, ConstraintDescriptor, Contact, DebugLine, PhysicsBackendSelection, PhysicsContinuousCollisionDescriptor, PhysicsShape, PhysicsSnapshot, PhysicsWorldDescriptor, RaycastHit, RaycastOptions, RigidBody, RigidBodyDescriptor, RigidBodyType, ScenePhysicsNode, SphereCastHit } from "../../physics/index.js";
+import { type SdfTextOcclusionPolicy, type SdfTextStyle, sampleOceanFixture, Geometry, InstancedPBRMaterial, PBRMaterial, TexturedPBRMaterial, type CollectedLight, type DayNightSkyOptions, type EnvironmentLightingOptions, type WaterSurfaceBoat, type WaterSurfacePreset, type WeatherType, type RenderDeviceDiagnostics, type RendererPostprocessExecutionMode } from "../../rendering/index.js";
+import type { TypedGLBActorEvidence } from "../production-runtime/TypedGLBActor.js";
+import { type LabelTelemetry, type TextBucketSummary } from "./LabelTelemetry.js";
 import { type ProjectedLabel } from "./WorldLabelRenderer.js";
 import { defineAuraCustomGeometry, type AuraCustomGeometrySpec, type AuraText3DGeometry, type AuraText3DOptions } from "./RootGeometry.js";
 export * from "./RootGeometry.js";
@@ -17,6 +22,14 @@ export { buildMeshBVH, createMeshSurfaceQuery, raycastMesh, type MeshBVH, type M
 import { type AuraCollisionLayers, type AuraPhysicsRuntime } from "./PhysicsRuntime.js";
 export * from "./FocusSelection.js";
 export * from "./WorldLabelRenderer.js";
+export * from "./GameCameraRigs.js";
+export * from "./GameFeel.js";
+export * from "./LabelTelemetry.js";
+export * from "./NavigationCrowds.js";
+export * from "./FootPlanting.js";
+export * from "./Decals.js";
+export * from "./Scatter.js";
+export * from "./AssetDecoders.js";
 export * from "./VehicleChassis.js";
 export * from "./VehicleDriverAi.js";
 /**
@@ -37,8 +50,15 @@ export * from "./WebCodecsFrameEncoder.js";
 export { GameInspector, createGameInspector } from "./GameInspector.js";
 export type { GameInspectorRuntimeInput, GameInspectorSnapshot } from "./GameInspector.js";
 import { createGameInspector } from "./GameInspector.js";
+import { type WrinkleMapHook } from "../../rendering/index.js";
 export { createGameAudio } from "../game/GameAudio.js";
 export type { GameAudio, GameAudioBusDefinition, GameAudioBusId, GameAudioContextLike, GameAudioCueDefinition, GameAudioCueEvent, GameAudioEvidence, GameAudioOptions } from "../game/GameAudio.js";
+export type { GameAudioBusLevel, GameAudioDuckingOptions, GameAudioFootPlant, GameAudioFootstepOptions, GameAudioPlayingNode, GameAudioPositionalOptions, GameAudioVec3 } from "../game/GameAudio.js";
+export { PositionalEmitter, FootstepPlayer, createGameMixer, attachFocusPolicy, computeDistanceAttenuation, computeDopplerShift, resolveOcclusion } from "../../audio/index.js";
+export { ComboDetector, createTouchLayoutPreset, probeHaptics, playHaptic } from "../../input/index.js";
+export { attachVisualScriptingGraph, createVisualScriptingGraph, listVisualScriptingNodeCatalog } from "../../scripting/index.js";
+export { createRootEditorSurface } from "../../editor-runtime/index.js";
+import { attachVisualScriptingGraph as attachVisualScriptingGraphFn, createVisualScriptingGraph as createVisualScriptingGraphFn, listVisualScriptingNodeCatalog as listVisualScriptingNodeCatalogFn } from "../../scripting/index.js";
 export * from "./RenderProgressTracker.js";
 export * from "./AudioVisemeAnalyzer.js";
 export * from "./ExternalPhonemeAnalyzer.js";
@@ -70,6 +90,7 @@ export * from "./AnimationMotionQuality.js";
 export * from "./AnimationRouteProof.js";
 export * from "./AnimationEpisodePackage.js";
 import type { GLTFSceneAnimationRuntime, GLTFSceneAnimationRuntimeOptions } from "../../assets/browser-index.js";
+import { type TextureStreamingResidency } from "../../assets/browser-index.js";
 import type { AnimationPose } from "../../animation/index.js";
 import type { GameHudBindingKind, GameRuntimeSubsystemOwnership } from "./GameRuntime.js";
 import { createFrameLoop } from "./FrameLoop.js";
@@ -108,7 +129,7 @@ export { createGameAppRuntime, type GameAppRuntime, type GameAppRuntimeEvidence,
 export { FrameLoop, createFrameLoop, type FrameLoopCallback, type FrameLoopFrame, type FrameLoopOptions, type FrameLoopSnapshot, type FrameLoopSource } from "./FrameLoop.js";
 export { createCombatWorld, createGameCameraDirector, createGameEffects, applyGameCombatEventsToRuntime, createGameAccessibilityFocus, createGameAccessibilityLabel, createGameAccessibilityRuntimeSettings, createGameHighContrastSource, createGameHudBindings, createGameHudComboBinding, createGameHudDebugToggleBinding, createGameHudHealthBinding, createGameHudMeterBinding, createGameHudRoundBinding, createGameHudSnapshot, createGameHudTimerBinding, createGameBoxCollider, createGameCapsuleCollider, createGameColliderDebugGeometry, createGameCombatDebugGeometry, createGameDebugOverlayData, createGameDebugSceneNodes, createGameHitboxDebugGeometry, createGameSimulation, createGameInput, createGameInputReplay, createGameInputReplayDriver, createGameJumpAssist, createGameKinematicBody, createGamePauseControlsSource, createGameRectCollider, createGameReducedFlashSource, createGameReducedMotionSource, createGameSphereCollider, createGameTouchControlLayout, gameColliderAabb, gameColliders, gameInputReplayEventsAt, createGameLoopPlan, runGameSimulation, type GameAccessibilityFocusOptions, type GameAccessibilityLabelOptions, type GameAccessibilityPauseControlsOptions, type GameAccessibilityPreferenceOptions, type GameAccessibilityRuntimeSettings, type GameAccessibilityRuntimeSettingsOptions, type GameAccessibilitySource, type GameAccessibilitySourceKind, type GameAabb, type GameBounds3, type GameCameraDirector, type GameCameraDirectorOptions, type GameCameraSnapshot, type GameCameraTarget, type GameCollisionAddBodyOptions, type GameCollisionBodyHandle, type GameCollisionBodyOptions, type GameCollisionBodySnapshot, type GameCollisionBox, type GameCollisionContact, type GameCollisionEvent, type GameCollisionParticipant, type GameCollisionQueryFilter, type GameCollisionSweepHit, type GameCollisionSweepOptions, type GameCollisionWorld, type GameCollisionWorldSnapshot, type GameCombatActorOptions, type GameCombatActorSnapshot, type GameCombatActiveAttackSnapshot, type GameCombatEvent, type GameCombatEventRuntimeBridgeOptions, type GameCombatEventRuntimeBridgeResult, type GameCombatEventType, type GameCombatMove, type GameCombatWorld, type GameCombatWorldSnapshot, type GameBoxCollider, type GameBoxColliderOptions, type GameCapsuleCollider, type GameCapsuleColliderOptions, type GameCollider, type GameColliderAxis, type GameColliderBase, type GameColliderDimension, type GameColliderFactoryOptions, type GameColliderKind, type GameColliderPlane, type GameDebugGeometryNode, type GameDebugGeometryOptions, type GameDebugGeometryPrimitive, type GameDebugOverlayData, type GameDebugOverlayMetric, type GameDebugOverlayOptions, type GameDebugOverlaySection, type GameDebugSceneNode, type GameDebugSceneNodeOptions, type GameDebugScenePrimitive, type GameEffectInstance, type GameEffectAttachment, type GameEffectKind, type GameEffectOptions, type GameEffectsController, type GameEffectsSnapshot, type GameEventInput, type GameEventLog, type GameEventLogOptions, type GameEventLogSnapshot, type GameEventRecord, type GameEventSeverity, type GameHudActorBindingOptions, type GameHudBinding, type GameHudBindingKind, type GameHudComboBindingOptions, type GameHudDebugToggleBindingOptions, type GameHudEventLogBindingOptions, type GameHudObjectiveBindingOptions, type GameHudResolvedValue, type GameHudRoundBindingOptions, type GameHudScoreBindingOptions, type GameHudSourceKind, type GameHudSnapshot, type GameHudSnapshotItem, type GameHudSnapshotOptions, type GameHudTimerBindingOptions, type GameHudValueBindingOptions, type GameHudValueFormat, type GameInputActionState, type GameInputAxisSettings, type GameInputAxisBinding, type GameInputController, type GameInputOptions, type GameInputReplayDriver, type GameInputReplayDriverSnapshot, type GameInputReplayEvent, type GameInputReplayOptions, type GameInputReplayPlan, type GameInputSnapshot, type GameJumpAssistController, type GameJumpAssistOptions, type GameJumpAssistSnapshot, type GameJumpAssistUpdate, type GameKinematicBody, type GameKinematicBodyOptions, type GameKinematicBodySnapshot, type GameLoopPlan, type GamePointerSnapshot, type GameRectCollider, type GameRectColliderOptions, type GameRuntimeSubsystemId, type GameRuntimeSubsystemOwnership, type GameSimulation, type GameSimulationFrame, type GameSimulationOptions, type GameSimulationResult, type GameSimulationStepContext, type GameSimulationStepResult, type GameSphereCollider, type GameSphereColliderOptions, type GameSubsystemOwner, type GameTouchControlAnchor, type GameTouchControlKind, type GameTouchControlLayout, type GameTouchControlLayoutOptions, type GameTouchControlRegion, type GameTouchControlRequest, type GameVec3, type GamepadSnapshot } from "./GameRuntime.js";
 export { collectGameSceneRuntimeNodes, createGameSceneBridge, createRuntimeNodeSpec, type GameSceneBridge, type GameSceneBridgeApp, type GameSceneBridgeBodyLike, type GameSceneBridgeEvidence, type GameSceneBridgeNodeHandle, type GameSceneRuntimeNode } from "./GameSceneBridge.js";
-export { calculateRuntimeNodeBounds, createRuntimeNodeEffectAttachment, runtimeNodeHasTag, type AuraRuntimeNodeAnimationPoseBindingMetadata, type AuraRuntimeNodeAnimationBindingMetadata, type AuraRuntimeNodeBounds, type AuraRuntimeNodeEffectAttachment, type AuraRuntimeNodeEffectKind, type RuntimeNodeAnimationSpecLike, type RuntimeNodeBoundsInput, type RuntimeNodeHandleLike, type RuntimeNodeMorphTargetWeights, type RuntimeNodeVec3 } from "./RuntimeNodeHandle.js";
+export { calculateRuntimeNodeBounds, createRuntimeNodeEffectAttachment, runtimeNodeHasTag, type AuraRuntimeNodeAnimationPoseBindingMetadata, type AuraRootMotionBinding, type AuraRuntimeNodeAnimationBindingMetadata, type AuraRuntimeNodeBounds, type AuraRuntimeNodeEffectAttachment, type AuraRuntimeNodeEffectKind, type RuntimeNodeAnimationSpecLike, type RuntimeNodeBoundsInput, type RuntimeNodeHandleLike, type RuntimeNodeMorphTargetWeights, type RuntimeNodeVec3 } from "./RuntimeNodeHandle.js";
 export { createFightingGameKit, fighting, fighterRuntimeNode, type FightingActorState, type FightingControls, type FightingGameKit, type FightingGameKitOptions, type FightingGameSnapshot, type FightingStageOptions } from "./game-kits/fighting.js";
 export { gameKits } from "./game-kits/index.js";
 export type { GameRuntimeEvidence, GameRuntimeEvidenceApp, GameRuntimeEvidenceOptions, GameRuntimeSourceEvidence } from "./GameEvidence.js";
@@ -116,6 +137,8 @@ export * from "./GameAssetValidation.js";
 export * from "./CharacterAssembly.js";
 export * from "./AssetEvidence.js";
 export * from "./AnimationController.js";
+export * from "./AnimationMixerBuilders.js";
+export * from "./AnimationDebugOverlay.js";
 export { gameAssetValidation, quaterniusGameReadyFighterValidationContract, validateQuaterniusGameReadyFighterAsset } from "./GameAssetValidation.js";
 export { createAnimationController } from "./AnimationController.js";
 export * from "./PromptAnimationContract.js";
@@ -150,6 +173,16 @@ export interface AuraProceduralTextureSpec {
     readonly colorB?: AuraColor;
 }
 export type AuraMaterialTextureInput = AuraAssetRef<"texture"> | AuraProceduralTextureSpec;
+/**
+ * Per-map UV transform for the C1 textured-PBR slots (muse3jsparity-PRD C1).
+ * Offset/scale apply in UV units, rotation in radians, matching the native
+ * per-slot `*TextureTransform` uniforms.
+ */
+export interface AuraTextureTransform {
+    readonly offset?: readonly [number, number];
+    readonly scale?: readonly [number, number];
+    readonly rotation?: number;
+}
 export interface AuraAssetDefinition {
     readonly type: AuraAssetType;
     readonly format: string;
@@ -229,14 +262,72 @@ export interface AuraMaterialSpec {
     readonly iridescenceThicknessRange?: readonly [number, number];
     readonly anisotropy?: number;
     readonly anisotropyRotation?: number;
+    /**
+     * Desired texture sampler anisotropy (muse3jsparity-PRD C3). Defaults to 8;
+     * the request snaps to a device step and the renderer clamps to the device
+     * maximum at upload time, so low-capability devices fold down safely.
+     */
+    readonly textureAnisotropy?: number;
     readonly attenuationColor?: AuraColor;
     readonly attenuationDistance?: number;
+    /** P3 physical-extension bounded warnings, stamped by `material.physical` (muse3jsparity-PRD): surfaced by capability diagnostics, never silent. */
+    readonly physicalWarnings?: readonly string[];
     readonly envMapIntensity?: number;
     readonly normal?: AuraMaterialTextureInput;
     readonly normalScale?: number;
     readonly roughnessMap?: AuraMaterialTextureInput;
     readonly metalnessMap?: AuraMaterialTextureInput;
     readonly texture?: AuraAssetRef<"texture">;
+    /** Occlusion (AO/lightmap) slot: scalar is the strength 0..1, asset ref is the occlusion map. */
+    readonly occlusionMap?: AuraMaterialTextureInput;
+    readonly occlusionStrength?: number;
+    /** Emissive map slot: multiplied by `emissive` (default white when only the map is set) × `emissiveIntensity`. */
+    readonly emissiveMap?: AuraMaterialTextureInput;
+    /** glTF extension maps: data channels are linear; sheen color is sRGB. */
+    readonly clearcoatMap?: AuraAssetRef<"texture">;
+    readonly clearcoatRoughnessMap?: AuraAssetRef<"texture">;
+    readonly clearcoatNormalMap?: AuraAssetRef<"texture">;
+    readonly clearcoatNormalScale?: number;
+    readonly sheenColorMap?: AuraAssetRef<"texture">;
+    readonly sheenRoughnessMap?: AuraAssetRef<"texture">;
+    readonly iridescenceMap?: AuraAssetRef<"texture">;
+    readonly iridescenceThicknessMap?: AuraAssetRef<"texture">;
+    readonly anisotropyMap?: AuraAssetRef<"texture">;
+    /**
+     * Per-slot UV set selection for the native texCoord selector (muse3jsparity-PRD C1).
+     * 0 samples the authored unwrap, 1 the procedural 2x tiling unwrap.
+     */
+    readonly texCoords?: {
+        readonly baseColor?: 0 | 1;
+        readonly normal?: 0 | 1;
+        readonly metallicRoughness?: 0 | 1;
+        readonly occlusion?: 0 | 1;
+        readonly emissive?: 0 | 1;
+        readonly clearcoat?: 0 | 1;
+        readonly clearcoatRoughness?: 0 | 1;
+        readonly clearcoatNormal?: 0 | 1;
+        readonly sheenColor?: 0 | 1;
+        readonly sheenRoughness?: 0 | 1;
+        readonly iridescence?: 0 | 1;
+        readonly iridescenceThickness?: 0 | 1;
+        readonly anisotropy?: 0 | 1;
+    };
+    /** Per-slot UV transforms, passed through to the native per-slot transform uniforms. */
+    readonly texTransforms?: {
+        readonly baseColor?: AuraTextureTransform;
+        readonly normal?: AuraTextureTransform;
+        readonly metallicRoughness?: AuraTextureTransform;
+        readonly occlusion?: AuraTextureTransform;
+        readonly emissive?: AuraTextureTransform;
+        readonly clearcoat?: AuraTextureTransform;
+        readonly clearcoatRoughness?: AuraTextureTransform;
+        readonly clearcoatNormal?: AuraTextureTransform;
+        readonly sheenColor?: AuraTextureTransform;
+        readonly sheenRoughness?: AuraTextureTransform;
+        readonly iridescence?: AuraTextureTransform;
+        readonly iridescenceThickness?: AuraTextureTransform;
+        readonly anisotropy?: AuraTextureTransform;
+    };
 }
 export interface AuraEditableMaterialParameters {
     readonly kind: "aura-material-parameters";
@@ -288,7 +379,7 @@ export interface AuraMaterialVisualQAResult {
     readonly minimumMaterialDistance: number;
     readonly problems: readonly string[];
 }
-export type AuraMaterialCapabilityFeatureId = "base-color" | "base-color-texture" | "metallic-roughness" | "normal-map" | "emissive" | "alpha" | "double-sided" | "clearcoat" | "sheen" | "transmission" | "variants" | "hdr-ibl" | "shadow-maps";
+export type AuraMaterialCapabilityFeatureId = "base-color" | "base-color-texture" | "metallic-roughness" | "normal-map" | "occlusion-map" | "emissive" | "alpha" | "double-sided" | "clearcoat" | "sheen" | "transmission" | "variants" | "hdr-ibl" | "shadow-maps";
 export type AuraMaterialCapabilitySupport = "supported" | "partial" | "metadata-only" | "unsupported" | "internal";
 export interface AuraMaterialCapabilityFeature {
     readonly id: AuraMaterialCapabilityFeatureId;
@@ -326,6 +417,14 @@ export interface AuraModelOptions extends AuraTransformSpec {
     readonly physics?: AuraNodePhysicsSpec;
     /** Exact glTF node names to suppress when composing a typed model into a route. */
     readonly hiddenNodeNames?: readonly string[];
+    /**
+     * Wrinkle-detail hook (E1 face-rig demo): per-frame the engine resolves
+     * `resolveWrinkleMapStrength(liveMorphWeights, wrinkle)` and uploads it as
+     * `u_wrinkleStrength` on shaders that declare it (skinned-lit family), modulating
+     * procedural normal detail. No authored wrinkle texture required; strength 0 renders
+     * exactly as without the hook. `textureUniform` is accepted but currently unused.
+     */
+    readonly wrinkle?: WrinkleMapHook;
 }
 export interface AuraPrimitiveOptions extends AuraTransformSpec {
     readonly name?: string;
@@ -481,6 +580,24 @@ export interface AuraModelNode extends AuraTransformSpec {
     readonly castShadow: boolean;
     readonly receiveShadow: boolean;
     readonly visible: boolean;
+    /** P2 model instancing (muse3jsparity-PRD): per-instance transforms consumed at mount exactly like primitive nodes. */
+    readonly instances?: readonly AuraTransformSpec[];
+    readonly instanceColors?: readonly AuraColor[];
+    readonly instanceLod?: {
+        readonly levels: readonly {
+            readonly maxDistance: number;
+        }[];
+        readonly hysteresis?: number;
+    };
+    /** P2 culling telemetry stamped by `instances.model`: centroid + bounding radius over instance positions. */
+    readonly instanceCulling?: {
+        readonly instanceCount: number;
+        readonly centroid: AuraVec3;
+        readonly boundingRadius: number;
+        readonly cullable: true;
+    };
+    /** P2 D1 fallback diagnostic stamped by `instances.model` when the material is not instancing-aware. */
+    readonly instancedModelWarning?: string;
     readonly role?: AuraModelRole;
     readonly scaleMode?: AuraModelScaleMode;
     readonly targetHeight?: number;
@@ -491,6 +608,8 @@ export interface AuraModelNode extends AuraTransformSpec {
     readonly physics?: AuraNodePhysicsSpec;
     readonly hiddenNodeNames?: readonly string[];
     readonly runtime?: AuraRuntimeNodeSpec;
+    /** Wrinkle-detail hook; see `AuraModelOptions.wrinkle`. */
+    readonly wrinkle?: WrinkleMapHook;
 }
 export interface AuraPrimitiveNode extends AuraTransformSpec {
     readonly kind: "primitive";
@@ -518,7 +637,7 @@ export interface AuraGroupNode extends AuraTransformSpec {
     readonly character?: AuraCharacterRigSpec;
     readonly runtime?: AuraRuntimeNodeSpec;
 }
-export type AuraLightType = "ambient" | "directional" | "point" | "studio" | "rect" | "softbox";
+export type AuraLightType = "ambient" | "directional" | "point" | "studio" | "rect" | "softbox" | "spot";
 export interface AuraLightNode extends AuraTransformSpec {
     readonly kind: "light";
     readonly light: AuraLightType;
@@ -527,8 +646,14 @@ export interface AuraLightNode extends AuraTransformSpec {
     readonly intensity: number;
     readonly width?: number;
     readonly height?: number;
+    readonly target?: AuraVec3;
+    readonly angle?: number;
+    readonly penumbra?: number;
+    readonly distance?: number;
+    readonly decay?: number;
+    readonly shadow?: boolean;
 }
-export type AuraEffectType = "fog" | "bloom" | "rain" | "particles" | "ambient-occlusion" | "contact-occlusion";
+export type AuraEffectType = "fog" | "bloom" | "rain" | "particles" | "ambient-occlusion" | "contact-occlusion" | "color-grade" | "anti-alias" | "outline" | "screen-space-reflections" | "depth-of-field" | "motion-blur" | "volumetric-fog" | "snow" | "flipbook-sprite" | "light-beam";
 export type AuraParticleMaterialMode = "additive-glow" | "soft-alpha" | "spark" | "smoke" | "splash" | "dust" | "star";
 export interface AuraEffectNode extends AuraTransformSpec {
     readonly kind: "effect";
@@ -547,6 +672,42 @@ export interface AuraEffectNode extends AuraTransformSpec {
     readonly threshold?: number;
     readonly antiBlowout?: boolean;
     readonly maxIntensity?: number;
+    /** Native bloom path (muse3jsparity-PRD A1): performance keeps the legacy single-scale ping-pong; balanced/cinematic use the mip pyramid. */
+    readonly quality?: "performance" | "balanced" | "cinematic";
+    /** HDR bright-extract knee width in [0, 0.5]; 0 keeps the hard threshold step. */
+    readonly softKnee?: number;
+    /** LDR composite highlight shoulder in [0, 1]; 0 keeps the legacy clamp. */
+    readonly shoulder?: number;
+    /** Color-grade exposure multiplier (muse3jsparity-PRD A3). */
+    readonly exposure?: number;
+    /** Color-grade contrast around mid-grey (muse3jsparity-PRD A3). */
+    readonly contrast?: number;
+    /** Color-grade saturation multiplier (muse3jsparity-PRD A3). */
+    readonly saturation?: number;
+    /** Recorded color-grade shadow lift: no native grade target yet, warned when set. */
+    readonly shadows?: number;
+    /** Recorded color-grade highlight gain: no native grade target yet, warned when set. */
+    readonly highlights?: number;
+    /** Reserved color-grade LUT asset id: recorded on the node, not yet sampled by the native grade. */
+    readonly lut?: string;
+    /** Anti-alias mode (muse3jsparity-PRD A3): fxaa executes natively; taa/off never submit a pass. */
+    readonly mode?: "fxaa" | "taa" | "off";
+    /** Outline width in pixels, 1-6 (muse3jsparity-PRD A3). */
+    readonly width?: number;
+    /** Depth-of-field focus as a linear-distance fraction, 0 = near, 1 = far (muse3jsparity-PRD A3). */
+    readonly focus?: number;
+    /** Depth-of-field blur-band width derived control in [0, 1] (muse3jsparity-PRD A3). */
+    readonly aperture?: number;
+    /** Depth-of-field maximum blur radius in pixels (muse3jsparity-PRD A3). */
+    readonly maxBlur?: number;
+    /** Volumetric-fog quality (muse3jsparity-PRD A5): "off" keeps forward exp2 fog only, never submits the inscatter pass. */
+    readonly volumetricQuality?: "off" | "balanced" | "quality" | "ultra";
+    /** Volumetric-fog radial anchor override in UV (muse3jsparity-PRD A5); defaults to the upper third. */
+    readonly lightPosition?: readonly [number, number];
+    /** Volumetric height falloff (muse3jsparity-PRD A5); 0 disables the height gate. */
+    readonly heightFalloff?: number;
+    /** Volumetric height reference in world units (muse3jsparity-PRD A5). */
+    readonly heightReference?: number;
     readonly emissionRate?: number;
     readonly gravity?: number;
     readonly groundCollision?: boolean;
@@ -560,6 +721,20 @@ export interface AuraEffectNode extends AuraTransformSpec {
     readonly noise?: number;
     readonly splashes?: boolean;
     readonly mist?: boolean;
+    /** Flipbook sprite sheet columns (muse3jsparity-PRD D4); validated fail-loud by resolveFlipbookUv. */
+    readonly spriteColumns?: number;
+    /** Flipbook sprite sheet rows (muse3jsparity-PRD D4). */
+    readonly spriteRows?: number;
+    /** Flipbook playback rate in frames per second (muse3jsparity-PRD D4). */
+    readonly frameRate?: number;
+    /** Light-beam start point in world units (muse3jsparity-PRD D4). */
+    readonly from?: AuraVec3;
+    /** Light-beam end point in world units (muse3jsparity-PRD D4). */
+    readonly to?: AuraVec3;
+    /** Light-beam width in world units (muse3jsparity-PRD D4). */
+    readonly widthWorld?: number;
+    /** Light-beam quad-strip segment count (muse3jsparity-PRD D4). */
+    readonly segmentCount?: number;
 }
 export interface AuraParticleBudgetDiagnostics {
     readonly kind: "aura-particle-budget";
@@ -600,10 +775,29 @@ export interface AuraLabelNode extends AuraTransformSpec {
 }
 export interface AuraEnvironmentNode {
     readonly kind: "environment";
-    readonly environment: "studio" | "material-lab" | "product-hero" | "night-cinematic" | "metal-studio" | "glass-studio";
+    readonly environment: "studio" | "material-lab" | "product-hero" | "night-cinematic" | "metal-studio" | "glass-studio" | "hdri";
     readonly name?: string;
     readonly intensity: number;
     readonly color?: AuraColor;
+    /**
+     * B3 root HDRI input (muse3jsparity-PRD). Only meaningful with
+     * `environment: "hdri"`: a Radiance `.hdr` asset ref resolved post-mount
+     * through the HDR→cubemap→GGX→BRDF-LUT chain. Scalar/procedural first
+     * frames stay honest; `iblPixelBacked` reports the swap.
+     */
+    readonly texture?: AuraAssetRef<"texture">;
+    /**
+     * B3 second probe slot (muse3jsparity-PRD). Optional reflection `.hdr`:
+     * the diffuse/illumination term keeps sampling `texture` (roughest mip)
+     * while the specular term samples `reflectionTexture` (sharper mips).
+     * Absent, both terms sample `texture` (single probe).
+     */
+    readonly reflectionTexture?: AuraAssetRef<"texture">;
+    /**
+     * M3 HDRI rotation (muse3jsparity-PRD) in radians. Forwards into the
+     * production HDR chain (`environmentMapRotation`); 0 keeps B3 behavior.
+     */
+    readonly rotation?: number;
 }
 export type AuraSceneCategory = "product" | "material" | "neon" | "city-night" | "city-day" | "space" | "physics" | "chart" | "game";
 export interface AuraRendererColorManagementPreset {
@@ -659,6 +853,12 @@ export interface AuraCreateAppRendererOptions {
     readonly mode?: AuraRendererMode;
     readonly fallback?: AuraRendererFallbackMode;
     readonly qualityProfile?: AuraRendererQualityProfileId;
+    /**
+     * M2 texture streaming budget in bytes (muse3jsparity-PRD). Funds the
+     * distance-prioritized mip residency; the unfunded tail surfaces as
+     * over-budget telemetry instead of silent thrash. Default 256 MiB.
+     */
+    readonly textureBudgetBytes?: number;
 }
 export interface AuraRendererDiagnosticReport {
     readonly kind: "aura-renderer-diagnostics";
@@ -678,6 +878,7 @@ export interface AuraRendererDiagnosticReport {
         readonly threshold: number;
         readonly radius: number;
         readonly antiBlowout: boolean;
+        readonly quality?: "performance" | "balanced" | "cinematic";
     };
     readonly shadows: {
         /** True only when a mounted runtime actually sampled a shadow map. */
@@ -692,8 +893,28 @@ export interface AuraRendererDiagnosticReport {
         readonly label?: string;
         readonly nativeShadowMapBindings: number;
         readonly shadowRenderTargetsAllocated: number;
+        /** Submitted cascade matrices/point atlas state; null before a real shadow frame. */
+        readonly observed: Readonly<Record<string, unknown>> | null;
         readonly contactShadows: number;
         readonly mapType: "pcf-soft";
+        /**
+         * N1 authored spot shadow state (muse3jsparity-PRD). `requested` is the
+         * author intent (`lights.spot({ shadow: true })` winning the caster
+         * slot); `spotPixelBacked` additionally requires the device-observed
+         * map signals — never declared from intent alone.
+         */
+        readonly spot?: {
+            readonly requested: boolean;
+            readonly casterIsSpot: boolean;
+            readonly casterName?: string;
+            readonly angle?: number;
+            readonly penumbra?: number;
+            readonly range?: number;
+            readonly atlasResolution?: number;
+            readonly atlasReason?: string;
+            readonly spotPixelBacked: boolean;
+            readonly reason: string;
+        };
     };
     readonly occlusion: {
         readonly enabled: boolean;
@@ -721,6 +942,8 @@ export interface AuraRendererDiagnosticReport {
         readonly fallbackPasses: readonly string[];
         /** Device-observed render-target format used by the mounted composer. */
         readonly targetFormat?: "rgba8" | "rgba16f" | "rgba32f";
+        /** Device-observed postprocess execution path (muse3jsparity-PRD A1). */
+        readonly executionMode: RendererPostprocessExecutionMode | "unknown";
         readonly evidence: string;
     };
     readonly runtime: {
@@ -730,21 +953,67 @@ export interface AuraRendererDiagnosticReport {
         readonly passNames: readonly string[];
         readonly warnings: readonly string[];
         readonly nativeInstancedSubmissions: number;
+        readonly nativeTemporalPasses?: number;
+        readonly nativeTemporalBindings?: number;
         readonly submittedObjects: number;
         readonly visibleObjects: number;
         readonly culledObjects: number;
         readonly frustumTestedObjects: number;
+        /** Most recent native bloom execution observed on the device (muse3jsparity-PRD A1); null until a native bloom pass runs. */
+        readonly bloom: RenderDeviceDiagnostics["bloom"];
+        /** C3 sampler anisotropy telemetry: uploads issued and device maximum (1 when unsupported). */
+        readonly samplerAnisotropyUploads?: number;
+        readonly maxTextureAnisotropy?: number;
         readonly lodSelections: readonly {
             readonly nodeName: string;
             readonly levelIndex: number;
             readonly levelName: string;
         }[];
+        /** C1 per-material textured diagnostics; pixelBacked only after the post-mount upgrade swaps materials. */
+        readonly texturedMaterials: readonly {
+            readonly nodeName: string;
+            readonly levelName: string;
+            readonly status: "none" | "pending" | "textured" | "fallback";
+            readonly slots: readonly string[];
+            readonly pixelBacked: boolean;
+            readonly warnings: readonly string[];
+        }[];
     };
     readonly environment: {
         readonly enabled: boolean;
         readonly preset?: AuraEnvironmentNode["environment"];
         readonly intensity?: number;
         readonly evidence: string;
+        /** B3: true only after the HDRI chain swaps the live lighting object. */
+        readonly iblPixelBacked: boolean;
+        readonly hdriStatus: "none" | "pending" | "ready" | "fallback";
+        readonly dualProbe?: boolean;
+    };
+    /**
+     * G1 SDF world-text state (muse3jsparity-PRD). `textPixelBacked` is true
+     * only when the atlas-derived label texture uploaded AND SDF quads were
+     * submitted this frame — layout alone never backs pixels.
+     */
+    readonly text: {
+        readonly sdfTexts: number;
+        readonly textPixelBacked: boolean;
+        readonly quadCount: number;
+        readonly lastOpacity: number;
+        readonly reason: string;
+    };
+    /**
+     * M2 texture streaming residency (muse3jsparity-PRD). Funded from the
+     * post-upgrade texture table against `textureBudgetBytes`; the unfunded
+     * tail reports over-budget bytes instead of thrashing silently.
+     */
+    readonly textures: {
+        readonly budgetBytes: number;
+        readonly usedBytes: number;
+        readonly requestedBytes: number;
+        readonly overBudget: boolean;
+        readonly overBudgetBytes: number;
+        readonly residentEntries: number;
+        readonly evictedEntries: readonly string[];
     };
     readonly antialiasing: AuraRendererQualityPreset["antialiasing"];
     readonly screenshotQuality: AuraRendererQualityPreset;
@@ -898,12 +1167,49 @@ export declare const instances: {
         readonly transforms: readonly AuraTransformSpec[];
         readonly colors?: readonly AuraColor[];
     }) => AuraNodeBuilder<AuraPrimitiveNode>;
+    /**
+     * P2 instanced GLB models (muse3jsparity-PRD): one draw class for repeated
+     * static models. Skinned actors fall back with a D1 warning at mount (E1
+     * owns rigs); explicitly unaware materials warn at build.
+     */
+    readonly model: <TAsset extends AuraAssetRef<"model">>(asset: TAsset, options: AuraModelOptions & {
+        readonly transforms: readonly AuraTransformSpec[];
+        readonly colors?: readonly AuraColor[];
+        readonly lod?: {
+            readonly levels: readonly {
+                readonly maxDistance: number;
+            }[];
+            readonly hysteresis?: number;
+        };
+        readonly instancingAware?: boolean;
+        readonly maxInstancesPerDraw?: number;
+    }) => AuraNodeBuilder<AuraModelNode>;
+};
+export declare const visualScripting: {
+    readonly graph: typeof createVisualScriptingGraphFn;
+    readonly attach: typeof attachVisualScriptingGraphFn;
+    readonly catalog: typeof listVisualScriptingNodeCatalogFn;
+};
+export declare const editor: {
+    readonly undo: (context?: import("../../editor-runtime/index.js").CommandContext) => Promise<void>;
+    readonly redo: (context?: import("../../editor-runtime/index.js").CommandContext) => Promise<void>;
+    readonly gizmo: (kind: import("../../editor-runtime/index.js").RootEditorGizmoKind, target?: import("../../editor-runtime/index.js").TransformTarget) => import("../../editor-runtime/index.js").RootEditorGizmoHandle;
+    readonly playMode: {
+        readonly enter: () => void;
+        readonly exit: (restore?: boolean) => void;
+    };
+    readonly outliner: (root: import("../../editor-runtime/index.js").AnimationSceneNode) => readonly import("../../editor-runtime/index.js").SceneOutlinerItem[];
+    readonly capabilityLabel: "editor";
 };
 export declare const geometry: {
     readonly define: typeof defineAuraCustomGeometry;
     readonly custom: (spec: AuraCustomGeometrySpec, options?: Omit<AuraPrimitiveOptions, "geometry">) => AuraNodeBuilder<AuraPrimitiveNode>;
 };
-export declare function text3D(text: string, options?: AuraText3DOptions & Omit<AuraPrimitiveOptions, "geometry" | "text3D">): AuraNodeBuilder<AuraPrimitiveNode>;
+export declare function text3D(text: string, options?: AuraText3DOptions & Omit<AuraPrimitiveOptions, "geometry" | "text3D"> & {
+    readonly backend?: "extruded-mesh" | "sdf";
+    readonly sdfStyle?: SdfTextStyle;
+    readonly sdfOcclusion?: SdfTextOcclusionPolicy;
+}): AuraNodeBuilder<AuraPrimitiveNode>;
 export declare function distanceLod(options: Omit<AuraPrimitiveOptions, "lod" | "geometry"> & {
     readonly levels: readonly AuraRootLodLevelSpec[];
     readonly hysteresis?: number;
@@ -972,6 +1278,7 @@ export declare const lights: {
         readonly position?: AuraVec3;
         readonly intensity?: number;
         readonly color?: AuraColor;
+        readonly shadow?: boolean;
     }) => AuraNodeBuilder<AuraLightNode>;
     readonly point: (options?: {
         readonly name?: string;
@@ -979,6 +1286,18 @@ export declare const lights: {
         readonly intensity?: number;
         readonly color?: AuraColor;
     }) => AuraNodeBuilder<AuraLightNode>;
+    readonly spot: (options?: {
+        readonly name?: string;
+        readonly position?: AuraVec3;
+        readonly target?: AuraVec3;
+        readonly angle?: number;
+        readonly penumbra?: number;
+        readonly distance?: number;
+        readonly decay?: number;
+        readonly intensity?: number;
+        readonly color?: AuraColor;
+        readonly shadow?: boolean;
+    }) => AuraNodeBuilder<AuraLightNode>;
     readonly studio: (options?: {
         readonly intensity?: number;
     }) => AuraNodeBuilder<AuraLightNode>;
@@ -1014,6 +1333,10 @@ export interface AuraCameraSpec {
     readonly targetOffset?: AuraVec3;
     readonly offsetMode?: "scene" | "target-yaw";
     readonly fov?: number;
+    /** Positive near clipping distance in world units; defaults to 0.05. */
+    readonly near?: number;
+    /** Far clipping distance in world units, greater than near; defaults to 100. */
+    readonly far?: number;
     readonly distance?: number;
     readonly from?: AuraVec3;
     readonly to?: AuraVec3;
@@ -1052,6 +1375,12 @@ export interface AuraCameraFrameAssetOptions {
     readonly minDistance?: number;
 }
 export declare const camera: {
+    readonly shoulder: typeof import("./GameCameraRigs.js").createShoulderCamera;
+    readonly collisionAwareOrbit: typeof import("./GameCameraRigs.js").createCollisionAwareOrbit;
+    readonly shake: typeof import("./GameCameraRigs.js").createTraumaShake;
+    readonly punchIn: typeof import("./GameCameraRigs.js").createPunchIn;
+    readonly followRig: typeof import("./GameCameraRigs.js").createFollowRig;
+    readonly gameRig: typeof import("./GameCameraRigs.js").createGameCameraRig;
     readonly perspective: (options?: Omit<AuraCameraSpec, "mode">) => AuraCameraSpec;
     readonly orbit: (options?: Omit<AuraCameraSpec, "mode">) => AuraCameraSpec;
     readonly dolly: (options: Omit<AuraCameraSpec, "mode"> & {
@@ -1108,6 +1437,15 @@ export declare const camera: {
     readonly miniGolf: () => AuraCameraSpec;
     readonly neon: () => AuraCameraSpec;
 };
+export declare const gameFeel: {
+    readonly create: typeof import("./GameFeel.js").createGameFeel;
+    readonly hitStopDefaults: {
+        readonly light: 0.045;
+        readonly heavy: 0.07;
+        readonly special: 0.1;
+        readonly default: 0.06;
+    };
+};
 export interface AuraTimelineSpec {
     readonly mode: "loop" | "once";
     readonly seconds?: number;
@@ -1126,13 +1464,155 @@ export declare const effects: {
     readonly bloom: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
     readonly cinematicBloom: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
     readonly neonBloom: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * A5 volumetric fog (muse3jsparity-PRD): builds a DISTINCT "volumetric-fog"
+     * node (never plain fog) that submits the depth-aware inscatter pass plus
+     * forward GPU height-fog terms. quality "off" keeps forward exp2 fog only.
+     */
     readonly volumetricFog: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
     readonly depthFog: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
     readonly ambientOcclusion: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
     readonly contactOcclusion: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Root color-grade node (muse3jsparity-PRD A3). contrast/saturation execute
+     * natively; exposure/shadows/highlights/lut are recorded on the node and
+     * warned (no native grade target yet — never silently accepted).
+     */
+    readonly colorGrade: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Root anti-alias node (muse3jsparity-PRD A3). `fxaa` executes natively;
+     * `off` submits nothing; `taa` uses renderer-owned velocity/history for opaque
+     * rigid triangles. Unsupported deforming/transparent geometry emits a named warning.
+     */
+    readonly antiAlias: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Root outline node (muse3jsparity-PRD A3): native outline pass, width in
+     * pixels clamped to the device range 1-6 by the bridge.
+     */
+    readonly outline: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Root screen-space reflections node (muse3jsparity-PRD A3): submits the
+     * native SSR pass against renderer-owned depth where available.
+     */
+    readonly screenSpaceReflections: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Root depth-of-field node (muse3jsparity-PRD A3). focus is a
+     * linear-distance fraction (0 = near plane, 1 = far plane); aperture widens
+     * the focus transition band (game-tuned control, not a physical f-stop).
+     */
+    readonly depthOfField: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Root motion-blur node: renderer-owned GPU velocity for opaque rigid geometry.
+     * Unsupported deforming/transparent/instanced geometry emits a named warning.
+     */
+    readonly motionBlur: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
     readonly rain: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    readonly snow: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Flipbook explosion/muzzle-flash sprite sheet (muse3jsparity-PRD D4):
+     * recorded with validated sheet geometry, but withheld — root has no
+     * native sprite-sheet sampler yet, so no pass is submitted.
+     */
+    readonly flipbook: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Additive thick light beam / fence strip (muse3jsparity-PRD D4): recorded
+     * with a validated quad-strip descriptor, but withheld — root has no native
+     * beam target yet, so no pass is submitted.
+     */
+    readonly beam: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
     readonly particles: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
 };
+/**
+ * D3 atmosphere builders (PRD D3 boxes 1-2). ADDITIVE root surface over the
+ * pure descriptors in `@aura3d/rendering` (`DayNightSky.ts`,
+ * `AtmosphereWetness.ts`, `Weather.ts`).
+ *
+ * Every builder below composes pre-existing node kinds only (primitive,
+ * light, effect); no existing builder is modified. Precipitation pixels in
+ * the default production path come from weather-state-driven primitive
+ * streaks/flakes, because the production bridge does not pixel-back `rain`,
+ * `snow`, or `particles` effect passes (they render only in the safe-basic
+ * fallback and the Canvas2D diagnostic path). The matching effect node is
+ * still declared so diagnostics report the request.
+ */
+export declare const sky: {
+    /** Time-of-day sky: background key, sun/moon discs, stars, 2D-noise clouds, key light. */
+    readonly dayNight: (options?: DayNightSkyOptions & {
+        readonly starLimit?: number;
+        readonly cloudLimit?: number;
+    }) => {
+        readonly nodes: readonly AuraSceneNode[];
+        readonly background: string;
+        readonly dayFactor: number;
+        readonly visibleStarCount: number;
+    };
+};
+export declare const weather: {
+    /** Rain/snow declaration + weather-state-driven primitive streaks/flakes for production-path pixels. */
+    readonly precipitation: (options: {
+        readonly type: WeatherType;
+        readonly seed?: number;
+        readonly streakLimit?: number;
+        readonly elapsedSeconds?: number;
+    }) => {
+        readonly nodes: readonly AuraSceneNode[];
+        readonly dropCount: number;
+        readonly wetness: number;
+    };
+    /** Ground slab with wetness darkening + puddle discs mapped from WeatherPuddlePatch. */
+    readonly wetGround: (options?: {
+        readonly type?: WeatherType;
+        readonly dryColor?: string;
+        readonly dryRoughness?: number;
+        readonly seed?: number;
+        readonly size?: number;
+    }) => {
+        readonly nodes: readonly AuraSceneNode[];
+        readonly wetness: number;
+        readonly albedoColor: string;
+        readonly roughness: number;
+        readonly puddleCount: number;
+    };
+    /** Lightning-flash light hook: intensity is 0 unless type is thunderstorm. */
+    readonly lightning: (options?: {
+        readonly type: WeatherType;
+        readonly elapsedSeconds?: number;
+        readonly seed?: number;
+    }) => {
+        readonly nodes: readonly AuraSceneNode[];
+        readonly intensity: number;
+    };
+};
+/**
+ * D3 water surface builder (PRD D3 box 3). ADDITIVE root surface over
+ * `createWaterSurface` in `@aura3d/rendering`.
+ *
+ * Rendered material = layered opaque depth-tinted bands (bounded refraction
+ * look) + fresnel-baked sky tint + white shore-foam discs mapped from
+ * `OceanFoamPatch` + boat + fading wake trail. Buoyancy queries stay on the
+ * fixture (`sampleOceanFixture().buoyancy`); this builder creates no planar
+ * reflection/refraction targets (B4 dependency, see
+ * WATER_SURFACE_PLANAR_DEPENDENCY).
+ */
+export declare const water: {
+    readonly surface: (options?: {
+        readonly preset?: WaterSurfacePreset;
+        readonly seed?: number;
+        readonly boat?: WaterSurfaceBoat;
+        readonly withBoatHull?: boolean;
+    }) => {
+        readonly nodes: readonly AuraSceneNode[];
+        readonly bandCount: number;
+        readonly foamCount: number;
+        readonly wakeActive: boolean;
+        readonly wakeSegmentCount: number;
+    };
+    /** Fixture-side buoyancy telemetry passthrough (no physics implemented here). */
+    readonly buoyancy: (options?: {
+        readonly preset?: WaterSurfacePreset;
+        readonly seed?: number;
+    }) => ReturnType<typeof sampleOceanFixture>["buoyancy"];
+};
 export declare const interactions: {
     readonly orbit: (options?: {
         readonly target?: string;
@@ -1223,6 +1703,16 @@ export declare const environments: {
     readonly glassStudio: (options?: AuraEnvironmentOptions) => AuraNodeBuilder<AuraEnvironmentNode>;
     readonly presets: () => readonly AuraEnvironmentMapPreset[];
     readonly forMaterial: (materialClass: "metal" | "glass" | "product" | "studio") => AuraNodeBuilder<AuraEnvironmentNode>;
+    /**
+     * B3 root HDRI environment (muse3jsparity-PRD). The `.hdr` asset resolves
+     * post-mount: first frames render the honest studio procedural fallback,
+     * then the HDR→cubemap→GGX-prefilter→BRDF-LUT chain swaps in and
+     * `iblPixelBacked` flips true in diagnostics. Fetch/parse failures keep the
+     * fallback and warn — never a black scene, never a silent swap.
+     */
+    readonly hdri: (options: AuraEnvironmentOptions & {
+        texture: AuraAssetRef<"texture">;
+    }) => AuraNodeBuilder<AuraEnvironmentNode>;
 };
 export declare const renderer: {
     readonly colorManagementPreset: () => AuraRendererColorManagementPreset;
@@ -1234,6 +1724,104 @@ export declare const renderer: {
     readonly screenshotQuality: () => AuraRendererQualityPreset;
     readonly diagnostics: (sceneValue: AuraSceneBuilder | AuraSceneSnapshot, options?: AuraCreateAppRendererOptions) => AuraRendererDiagnosticReport;
 };
+interface AuraRendererRuntimeObservation {
+    readonly mounted: boolean;
+    readonly backend: "scene-plan" | "webgl2-agent-runtime" | "production-runtime";
+    readonly postprocess: {
+        readonly renderPass: boolean;
+        readonly outputPass: boolean;
+        readonly bloomPass: boolean;
+        readonly ambientOcclusionPass: boolean;
+        readonly contactOcclusionReceiver: boolean;
+        readonly pixelBacked: boolean;
+        readonly actualPasses: readonly string[];
+        readonly fallbackPasses: readonly string[];
+        readonly targetFormat?: "rgba8" | "rgba16f" | "rgba32f";
+        /** Device-observed postprocess execution path (muse3jsparity-PRD A1). */
+        readonly executionMode: RendererPostprocessExecutionMode | "unknown";
+    };
+    readonly environment?: {
+        readonly enabled: boolean;
+        readonly preset?: AuraEnvironmentNode["environment"] | string;
+        readonly intensity?: number;
+        readonly evidence: string;
+        /** B3: true only after the HDRI chain swaps the live lighting object. */
+        readonly iblPixelBacked?: boolean;
+        readonly hdriStatus?: "none" | "pending" | "ready" | "fallback";
+        readonly dualProbe?: boolean;
+        readonly hdriRotation?: number;
+    };
+    /**
+     * Device-observed shadow-map activity. This exists because the root report
+     * previously published `shadows.enabled: true` unconditionally, which is a
+     * source-authored boolean rather than evidence that any shadow map was
+     * rendered or sampled.
+     */
+    readonly shadow?: {
+        readonly requested: boolean;
+        readonly mapRendered: boolean;
+        readonly mapSampled: boolean;
+        readonly mapSize?: number;
+        readonly label?: string;
+        readonly nativeShadowMapBindings?: number;
+        readonly shadowRenderTargetsAllocated?: number;
+        readonly observed?: Readonly<Record<string, unknown>> | null;
+        /**
+         * N1 authored spot shadow state (muse3jsparity-PRD). `spotPixelBacked`
+         * requires the device-observed map signals on a spot caster.
+         */
+        readonly spot?: {
+            readonly requested: boolean;
+            readonly casterIsSpot: boolean;
+            readonly casterName?: string;
+            readonly angle?: number;
+            readonly penumbra?: number;
+            readonly range?: number;
+            readonly atlasResolution?: number;
+            readonly atlasReason?: string;
+            readonly spotPixelBacked: boolean;
+            readonly reason: string;
+        };
+    };
+    /** G1 SDF text observation, computed from the mounted primitive entries. */
+    readonly text?: {
+        readonly sdfTexts: number;
+        readonly textPixelBacked: boolean;
+        readonly quadCount: number;
+        readonly lastOpacity: number;
+        readonly reason: string;
+    };
+    /** M2 streaming residency, funded from the post-upgrade texture table. */
+    readonly textures?: {
+        readonly budgetBytes: number;
+        readonly usedBytes: number;
+        readonly requestedBytes: number;
+        readonly overBudget: boolean;
+        readonly overBudgetBytes: number;
+        readonly residentEntries: number;
+        readonly evictedEntries: readonly string[];
+    };
+    readonly warnings?: readonly string[];
+    readonly deviceDiagnostics?: Pick<RenderDeviceDiagnostics, "nativeTemporalPasses" | "nativeTemporalBindings" | "nativeInstancedSubmissions" | "submittedObjects" | "visibleObjects" | "culledObjects" | "frustumTestedObjects" | "bloom" | "samplerAnisotropyUploads" | "maxTextureAnisotropy">;
+    readonly lodSelections?: readonly {
+        readonly nodeName: string;
+        readonly levelIndex: number;
+        readonly levelName: string;
+    }[];
+    /**
+     * C1 per-material textured diagnostics. pixelBacked is true only after the
+     * post-mount upgrade swaps in the TexturedPBRMaterial (scalar first frames
+     * report false, never a premature true).
+     */
+    readonly texturedMaterials?: readonly {
+        readonly nodeName: string;
+        readonly levelName: string;
+        readonly status: "none" | "pending" | "textured" | "fallback";
+        readonly slots: readonly string[];
+        readonly pixelBacked: boolean;
+        readonly warnings: readonly string[];
+    }[];
+}
 export interface AuraSceneSnapshot {
     readonly schema: "aura3d-scene-snapshot/1.0";
     readonly background: AuraColor;
@@ -2405,6 +2993,8 @@ export interface AuraDiagnostics {
      * while evidence counted the nodes, so the counted-node signal is not enough.
      */
     readonly labels?: readonly ProjectedLabel[];
+    readonly labelTelemetry?: LabelTelemetry;
+    readonly textBuckets?: TextBucketSummary;
 }
 export interface AuraAssetProvenance {
     readonly source: "typed-aura-assets-manifest" | "unsafe-url" | "inline-definition";
@@ -2551,6 +3141,21 @@ export interface AuraRuntimeNodeImportedAssetEvidence {
     readonly renderItemCount: number;
     readonly skinnedRenderItemCount: number;
     readonly morphRenderItemCount: number;
+    readonly lastMaterialTracksApplied?: number | undefined;
+    readonly lastLightTracksApplied?: number | undefined;
+    readonly lastFootPlantingGroundedFeet?: number | undefined;
+    readonly lastFootPlantingTargetError?: number | undefined;
+    readonly lastFootPlantingHipOffset?: number | undefined;
+    readonly lastFootPlantingMissingLegs?: readonly string[] | undefined;
+    readonly lastFootPlantingDeformation?: TypedGLBActorEvidence["lastFootPlantingDeformation"];
+    readonly lastFootPlantingSurfaces?: TypedGLBActorEvidence["lastFootPlantingSurfaces"];
+    readonly lastFootPlantingFeet?: readonly {
+        readonly side: "left" | "right";
+        readonly worldPosition: readonly [number, number, number];
+        readonly contactError: number;
+        readonly locked: boolean;
+    }[] | undefined;
+    readonly footPlantingConfigured?: boolean | undefined;
     readonly diagnostics: readonly AuraRuntimeNodeImportedAssetDiagnostic[];
 }
 export interface AuraRuntimeNodeImportedAssetDiagnostic {
@@ -2576,6 +3181,21 @@ export interface AuraRuntimeNodeImportedAssetEvidenceInput {
     readonly renderItemCount?: number | undefined;
     readonly skinnedRenderItemCount?: number | undefined;
     readonly morphRenderItemCount?: number | undefined;
+    readonly lastMaterialTracksApplied?: number | undefined;
+    readonly lastLightTracksApplied?: number | undefined;
+    readonly lastFootPlantingGroundedFeet?: number | undefined;
+    readonly lastFootPlantingTargetError?: number | undefined;
+    readonly lastFootPlantingHipOffset?: number | undefined;
+    readonly lastFootPlantingMissingLegs?: readonly string[] | undefined;
+    readonly lastFootPlantingDeformation?: TypedGLBActorEvidence["lastFootPlantingDeformation"];
+    readonly lastFootPlantingSurfaces?: TypedGLBActorEvidence["lastFootPlantingSurfaces"];
+    readonly lastFootPlantingFeet?: readonly {
+        readonly side: "left" | "right";
+        readonly worldPosition: readonly [number, number, number];
+        readonly contactError: number;
+        readonly locked: boolean;
+    }[] | undefined;
+    readonly footPlantingConfigured?: boolean | undefined;
     readonly requiredClips?: readonly string[] | undefined;
     readonly requiredBones?: readonly string[] | undefined;
     readonly requiredMorphTargets?: readonly string[] | undefined;
@@ -2614,6 +3234,8 @@ export interface AuraApp {
      */
     readonly physics: AuraPhysicsRuntime;
     setScene(scene: AuraSceneBuilder | AuraSceneSnapshot): void;
+    /** Apply native renderer quality between completed frames; rejects unsupported particle owners. */
+    setPerformanceQuality(settings: AuraPerformanceQuality): void;
     onFrame(callback: AuraFrameCallback): () => void;
     offFrame(callback: AuraFrameCallback): void;
     input(options: GameInputOptions): ReturnType<typeof createGameInput>;
@@ -2676,12 +3298,18 @@ export interface AuraApp {
      */
     advance(dt?: number): void;
     step(dt?: number): void;
+    /** Submit a native asynchronous production frame. Rejects unavailable or disposed renderers. */
+    stepAsync(dt?: number): Promise<void>;
+    /** Wait for pending submissions and release renderer resources. */
+    disposeAsync(): Promise<void>;
     diagnostics(): AuraDiagnostics;
     evidence(options?: GameRuntimeEvidenceOptions): ReturnType<typeof collectGameRuntimeEvidenceV105>;
     screenshot(): AuraScreenshot;
     dispose(): void;
 }
 export interface AuraCreateAppOptions {
+    /** Native asynchronous presentation for the automatic loop; synchronous remains the default. */
+    readonly frameMode?: "sync" | "async";
     readonly scene: AuraSceneBuilder | AuraSceneSnapshot;
     /**
      * Configuration for {@link AuraApp.physics}.
@@ -2697,10 +3325,20 @@ export interface AuraCreateAppOptions {
         readonly layers?: AuraCollisionLayers | undefined;
         /** World gravity. Defaults to `[0, -9.81, 0]`; top-down games usually want zero. */
         readonly gravity?: readonly [number, number, number] | undefined;
+        /** Repeatability seed provenance (H1): recorded on the world, fail-loud unless a finite integer. */
+        readonly seed?: number | undefined;
+        /** Continuous-collision selection (H1): without this the app world never enables CCD. */
+        readonly continuousCollision?: PhysicsContinuousCollisionDescriptor | undefined;
     };
     readonly diagnostics?: boolean | AuraDiagnosticsOptions;
     readonly renderer?: AuraCreateAppRendererOptions;
     readonly pixelRatio?: number;
+    /**
+     * Native renderer quality applied before the first production frame. Use this
+     * when a known device/capture budget must constrain the initial render; later
+     * changes use {@link AuraApp.setPerformanceQuality} between completed frames.
+     */
+    readonly performanceQuality?: AuraPerformanceQuality;
     readonly autoStart?: boolean;
     readonly resize?: boolean;
 }
@@ -2767,6 +3405,161 @@ export declare const performance: {
 };
 export declare function captureAuraScreenshot(target?: HTMLCanvasElement): AuraScreenshot;
 export declare function createAuraAssetLoadError(asset: AuraAssetRef<"model">, reason: string): AuraRuntimeError;
+interface ProductionRuntimePrimitiveEntry {
+    readonly node: AuraPrimitiveNode;
+    readonly resources: readonly ProductionRuntimePrimitiveResource[];
+    currentLodIndex: number;
+}
+interface ProductionRuntimePrimitiveResource {
+    readonly geometry: Geometry;
+    readonly material: PBRMaterial | InstancedPBRMaterial;
+    readonly bounds: GltfBounds;
+    readonly name: string;
+    /** Source material spec (for the C1 textured upgrade); undefined when the node carries none. */
+    readonly materialSpec: AuraMaterialSpec | undefined;
+    /** Effective primitive node (LOD level node when applicable) for scalar re-derivation on upgrade. */
+    readonly sourceNode: AuraPrimitiveNode;
+    /**
+     * C1 textured upgrade slot. The sync factory always installs a scalar
+     * material first; the post-mount upgrade swaps in a TexturedPBRMaterial
+     * once authored texture refs resolve. Reads prefer this slot.
+     */
+    texturedMaterial: TexturedPBRMaterial | null;
+    /** Owns decoded bitmap and texture resources created by asynchronous upgrade. */
+    textureDisposer?: () => void;
+    /** C1 upgrade lifecycle: none (no texture inputs) → pending → textured | fallback. */
+    textureStatus: "none" | "pending" | "textured" | "fallback";
+    /** Native texture slots bound by the upgrade (subset of baseColor/normal/metallicRoughness). */
+    textureSlots: readonly string[];
+    /** Per-resource texture warnings (procedural inputs, fetch failures, skips). */
+    textureWarnings: string[];
+    /**
+     * G1 SDF text state. Non-null only when the SDF sampler mounted this
+     * resource as atlas-derived quads (textPixelBacked diagnostics source).
+     */
+    sdfText: {
+        readonly quadCount: number;
+        readonly imageBytes: number;
+        readonly lodFadeNear?: number;
+        readonly lodFadeFar?: number;
+        readonly occlusionPolicy: SdfTextOcclusionPolicy;
+        /** Last per-frame opacity written to the quad material (LOD x occlusion). */
+        lastOpacity: number;
+        /** Last per-frame visibility (occlusion hide policy skips submission). */
+        lastVisible: boolean;
+        /** True when quads were submitted on the last frame (pixel-backing leg). */
+        lastSubmitted: boolean;
+    } | null;
+    /**
+     * M2 streaming table: resident texture bytes on this resource (base +
+     * full mip-chain estimate) feeding the distance-prioritized residency.
+     */
+    textureBytes: number;
+    /** Coarse-to-fine mip-level bytes for the residency funding walk. */
+    textureMipBytes: readonly number[];
+}
+export declare function resolveNativeBloomRadius(authoredRadius: number | undefined): number;
+/**
+ * Shadow bias is compared in normalized light-depth space. Directional maps use
+ * an orthographic projection, so their existing scene-radius/texel heuristic is
+ * world-linear. A spot map is perspective: applying that world-space value at
+ * the far end of its cone erased legitimate caster/receiver separation (Aura
+ * Clash measured 0.00147 normalized depth versus the old 0.004 constant bias),
+ * and the default slope term could erase the remainder on a vertical receiver.
+ * Keep the established directional/point policy intact and use a bounded
+ * fraction of one normalized spot-map texel for both perspective terms.
+ */
+export declare function resolveProductionRuntimeShadowTuning(kind: CollectedLight["kind"] | undefined, size: number, sceneRadius: number): {
+    readonly bias: number;
+    readonly slopeBias?: number;
+};
+/**
+ * N1 caster selection (pure, unit-tested): an explicit `shadow: true`
+ * request wins the single caster slot over unrequested lights; ties and
+ * all-unrequested scenes keep the legacy priority-then-intensity order.
+ */
+export declare function resolveProductionShadowCasterIndex(descriptors: readonly {
+    readonly shadowPriority: number;
+    readonly shadowRequested: boolean;
+    readonly shadowDisabled?: boolean;
+    readonly intensity: number;
+}[]): number;
+/**
+ * C1 texture intent classification (pure, unit-tested). Asset refs resolve to
+ * fetchable urls; procedural inputs have no rasterizer and are reported so
+ * the caller can warn instead of silently dropping them.
+ */
+declare const ROOT_EXTENSION_TEXTURE_SLOTS: readonly ["clearcoat", "clearcoatRoughness", "clearcoatNormal", "sheenColor", "sheenRoughness", "iridescence", "iridescenceThickness", "anisotropy"];
+type RootExtensionTextureSlot = typeof ROOT_EXTENSION_TEXTURE_SLOTS[number];
+export declare function createProductionPrimitiveTextureIntent(materialSpec: AuraMaterialSpec | undefined): {
+    readonly baseColorUrl?: string;
+    readonly normalUrl?: string;
+    readonly roughnessUrl?: string;
+    readonly metalnessUrl?: string;
+    readonly occlusionUrl?: string;
+    readonly emissiveUrl?: string;
+    readonly extensionMaps?: Readonly<Partial<Record<RootExtensionTextureSlot, {
+        readonly url: string;
+        readonly colorSpace: "srgb" | "linear";
+        readonly texCoord: 0 | 1;
+        readonly transform?: AuraTextureTransform;
+    }>>>;
+    readonly proceduralInputs: readonly string[];
+};
+/**
+ * C1 post-mount textured upgrade (muse3jsparity-PRD). Runs fire-and-forget
+ * after mount: scalar first frames stay fast and honest, and every outcome —
+ * textured, fallback, or skipped — is recorded on the resource with warnings.
+ * Procedural inputs have no rasterizer: recorded + warned, never faked.
+ */
+export declare function upgradeProductionPrimitiveTextures(entries: readonly ProductionRuntimePrimitiveEntry[], warn: (message: string) => void, maxTextureSize?: number): Promise<void>;
+/**
+ * B3 post-mount HDRI upgrade (muse3jsparity-PRD). Fetches a Radiance `.hdr`
+ * asset, runs the HDR→cubemap→GGX-prefilter→BRDF-LUT chain, and returns the
+ * live lighting object plus its disposal. Throws on fetch/parse failure so
+ * the caller keeps the honest procedural fallback and warns.
+ */
+export declare function upgradeProductionEnvironmentHdri(url: string, intensity: number, reflectionUrl?: string, rotation?: number): Promise<{
+    readonly lighting: EnvironmentLightingOptions;
+    readonly dispose: () => void;
+    readonly maxLinearValue: number;
+    readonly specularMipCount: number;
+    readonly dualProbe: boolean;
+}>;
+export declare function compositeMetallicRoughnessPixels(rough: Uint8Array | undefined, metal: Uint8Array | undefined, pixelCount: number, roughnessScalar: number, metalnessScalar: number): Uint8Array;
+/**
+ * M2 mip-chain byte estimate (pure, unit-tested): full chain from the base
+ * level, coarse-to-fine, RGBA8. Matches the GPU residency the bridge funds.
+ */
+export declare function mipChainBytesCoarseToFine(width: number, height: number): readonly number[];
+/** M2 streaming budget normalization (pure, unit-tested): default 256 MiB, fail-closed. */
+export declare function normalizeTextureBudgetBytes(value: number | undefined): number;
+export interface TextureStreamingTableEntry {
+    readonly id: string;
+    readonly mipBytesCoarseToFine: readonly number[];
+    readonly distanceMeters: number;
+}
+/**
+ * M2 streaming residency from the post-upgrade texture table (pure,
+ * unit-tested): distance-prioritized mip funding against the budget with
+ * over-budget telemetry for the unfunded tail.
+ */
+export declare function describeTextureStreamingResidency(table: readonly TextureStreamingTableEntry[], budgetBytes: number): TextureStreamingResidency;
+/**
+ * N1 spot shadow observation (pure, unit-tested): cone + atlas tier from the
+ * authored spot, pixel-backing gated on the device-observed map signals with
+ * the spot as caster. No signal, no claim.
+ */
+export declare function describeProductionSpotShadow(input: {
+    readonly requested: boolean;
+    readonly casterIsSpot: boolean;
+    readonly casterName?: string;
+    readonly angle?: number;
+    readonly penumbra?: number;
+    readonly range?: number;
+    readonly mapRendered: boolean;
+    readonly mapSampled: boolean;
+}): NonNullable<AuraRendererRuntimeObservation["shadow"]>["spot"];
 interface ProductionBoundsProbe {
     readonly assetId: string;
     readonly metadata: {
@@ -2788,5 +3581,9 @@ interface ProductionBoundsProbe {
  * silently producing mismatched framing.
  */
 export declare function auraProductionBoundsProbes(): readonly ProductionBoundsProbe[];
+interface GltfBounds {
+    readonly min: AuraVec3;
+    readonly max: AuraVec3;
+}
 export declare function isOrthographicCameraMode(mode: AuraCameraMode): boolean;
 //# sourceMappingURL=index.d.ts.map