@aura3d/engine 2.0.3 → 3.0.0

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

@@ -1,4 +1,6 @@
-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 { 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 DayNightSkyOptions, type EnvironmentLightingOptions, type WaterSurfaceBoat, type WaterSurfacePreset, type WeatherType, type RenderDeviceDiagnostics, type RendererPostprocessExecutionMode } from "../../rendering/index.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,8 +19,23 @@ 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";
+/**
+ * Deliberate public surface for the shared arcade vehicle core. The racing kit
+ * owns the certified circuit path; exporting the bare motion helper lets routes
+ * such as showcase-courier-rush prove a different driving personality on their
+ * own topology without touching kit internals. Pinned by unit test.
+ */
+export { createGameArcadeVehicle, type GameArcadeVehicle, type GameArcadeVehicleInput, type GameArcadeVehicleOptions, type GameArcadeVehicleState } from "./GameRuntime.js";
 export * from "./PlatformerMotion.js";
 export * from "./CombatFrameData.js";
 export * from "./SceneQueries.js";
@@ -30,8 +47,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";
@@ -63,6 +87,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";
@@ -109,6 +134,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";
@@ -143,6 +170,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;
@@ -157,6 +194,10 @@ export interface AuraAssetMetadata {
     readonly materials?: readonly string[];
     readonly animations?: readonly string[];
     readonly textures?: readonly string[];
+    /** Manifest-relative source path retained by the generated asset map. */
+    readonly sourcePath?: string;
+    /** Published `/aura-assets/` output path retained by the generated asset map. */
+    readonly outputPath?: string;
     readonly boundsMetadata?: {
         readonly min?: readonly number[];
         readonly max?: readonly number[];
@@ -218,14 +259,46 @@ 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;
+    /**
+     * 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;
+    };
+    /** 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;
+    };
 }
 export interface AuraEditableMaterialParameters {
     readonly kind: "aura-material-parameters";
@@ -277,7 +350,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;
@@ -315,6 +388,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;
@@ -470,6 +551,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;
@@ -480,6 +579,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";
@@ -507,7 +608,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;
@@ -516,8 +617,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";
@@ -536,6 +643,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;
@@ -549,6 +692,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";
@@ -589,10 +746,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 {
@@ -648,6 +824,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";
@@ -667,6 +849,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. */
@@ -683,6 +866,24 @@ export interface AuraRendererDiagnosticReport {
         readonly shadowRenderTargetsAllocated: number;
         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;
@@ -710,6 +911,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: {
@@ -723,17 +926,61 @@ export interface AuraRendererDiagnosticReport {
         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;
@@ -883,12 +1130,53 @@ export declare const instances: {
         readonly transforms: readonly AuraTransformSpec[];
         readonly colors?: readonly AuraColor[];
     }) => AuraNodeBuilder<AuraPrimitiveNode>;
+    readonly custom: (spec: AuraCustomGeometrySpec, options: Omit<AuraPrimitiveOptions, "geometry"> & {
+        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;
@@ -964,6 +1252,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>;
@@ -1037,6 +1337,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"> & {
@@ -1093,6 +1399,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;
@@ -1111,13 +1426,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` is recorded but withheld (no history binding
+     * at root) with an explicit diagnostic 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 (muse3jsparity-PRD A3): recorded but withheld (no
+     * velocity binding at root) with an explicit diagnostic 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;
@@ -1208,6 +1665,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;
@@ -1219,6 +1686,103 @@ 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;
+        /**
+         * 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, "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;
@@ -2390,6 +2954,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";
@@ -2536,6 +3102,13 @@ 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 footPlantingConfigured?: boolean | undefined;
     readonly diagnostics: readonly AuraRuntimeNodeImportedAssetDiagnostic[];
 }
 export interface AuraRuntimeNodeImportedAssetDiagnostic {
@@ -2561,6 +3134,13 @@ 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 footPlantingConfigured?: boolean | undefined;
     readonly requiredClips?: readonly string[] | undefined;
     readonly requiredBones?: readonly string[] | undefined;
     readonly requiredMorphTargets?: readonly string[] | undefined;
@@ -2682,6 +3262,10 @@ 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;
@@ -2752,6 +3336,135 @@ 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;
+    /** 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[];
+}
+/**
+ * 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 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.
+ */
+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 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): 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: {
@@ -2773,5 +3486,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