reze-engine 0.42.3 → 0.50.0

package/dist/engine.d.ts

@@ -3,6 +3,9 @@ import { Model } from "./model";
 import { RezePhysics } from "./physics";
 import type { WindOptions } from "./physics/world";
 import { type AssetReader } from "./asset-reader";
+import { type ParamKey } from "./param-track";
+import { type HdrImage } from "./hdr";
+import { type LyricLine, type LyricRect } from "./shaders/lyrics-api";
 import { type CompileOptions, type StyleSlot } from "./graph/compile";
 import type { AlphaMode, RenderClass } from "./graph/render-class";
 import type { ApplyStyleGroupResult, ApplyStyleGroupsResult, StyleGroup } from "./graph/style-group";
@@ -26,18 +29,35 @@ type GroupInstall = {
      *  an unchanged group. */
     signature: string;
 };
-export type RaycastCallback = (modelName: string, material: string | null, bone: string | null, screenX: number, screenY: number) => void;
+type RaycastCallback = (modelName: string, material: string | null, bone: string | null, screenX: number, screenY: number) => void;
 /** Select a folder (webkitdirectory) and pass FileList or File[]; pmxFile picks which .pmx when several exist. */
 export type LoadModelFromFilesOptions = {
     files: FileList | File[];
     pmxFile?: File;
 };
-export type WorldOptions = {
+type WorldOptions = {
     /** Linear scene-referred color of the World Background (Blender: World > Surface > Color). */
     color?: Vec3;
     /** Multiplier on world color (Blender: World > Surface > Strength). */
     strength?: number;
 };
+/**
+ * One note in a score: when it sounds, for how long, at what pitch, how hard.
+ *
+ * Seconds and MIDI pitch (60 = middle C) rather than ticks and a tempo map — a
+ * score is consumed against the scene clock, so anything the engine stores in
+ * musical time would have to be resolved to seconds before every read.
+ */
+export interface MidiNote {
+    /** Seconds from the start of the piece. */
+    start: number;
+    /** Seconds the note sounds for. */
+    duration: number;
+    /** MIDI pitch, 0–127. */
+    pitch: number;
+    /** How hard it was struck, 0–1. Defaults to 1. */
+    velocity?: number;
+}
 export type ModelTransform = {
     position: Vec3;
     rotation: Quat;
@@ -45,7 +65,7 @@ export type ModelTransform = {
     scale: number;
     visible: boolean;
 };
-export type SunOptions = {
+type SunOptions = {
     /** Linear color of the sun lamp (Blender: Light > Color). */
     color?: Vec3;
     /** Lamp power in Blender units (Blender: Light > Strength). */
@@ -61,9 +81,19 @@ export type EffectParamValue = number | {
     y: number;
     z: number;
 };
+/** A vector by shape rather than by class — Vec3 satisfies it, and so does a
+ *  JSON object out of a scene document or a literal typed into a console. */
+export type XYZ = {
+    x: number;
+    y: number;
+    z: number;
+};
 export type EffectResult = {
     ok: boolean;
-    /** Compile/validation errors, line:col relative to the USER's WGSL. */
+    /** Compile/validation errors, line:col relative to the USER's WGSL. Also
+     *  carries non-fatal warnings on an effect that DID install — a directive
+     *  that parsed but will never fire, an anchor the scene had no slot for. So
+     *  a non-empty list is not a failure; `ok` is. */
     diagnostics: string[];
     /** Which mounts the WGSL declared — `fn background` / `fn foreground`. Both
      *  false only on a failed compile, since defining neither IS the failure. */
@@ -72,7 +102,7 @@ export type EffectResult = {
         foreground: boolean;
     };
 };
-export type CameraOptions = {
+type CameraOptions = {
     /** Orbit distance from target. */
     distance?: number;
     /** World-space orbit center. */
@@ -193,23 +223,6 @@ export type EngineOptions = {
     /** See {@link GizmoDragCallback}. */
     onGizmoDrag?: GizmoDragCallback;
 };
-export declare const DEFAULT_ENGINE_OPTIONS: {
-    world: {
-        color: Vec3;
-        strength: number;
-    };
-    sun: {
-        color: Vec3;
-        strength: number;
-        direction: Vec3;
-    };
-    camera: {
-        distance: number;
-        target: Vec3;
-        fov: number;
-    };
-    onRaycast: undefined;
-};
 export interface EngineStats {
     fps: number;
     frameTime: number;
@@ -238,6 +251,75 @@ interface DrawCall {
     outline?: {
         bindGroup: GPUBindGroup;
     };
+    /** MODEL-SPACE AABB over this material's index range, computed at load:
+     *  [minX, minY, minZ, maxX, maxY, maxZ]. Usable for culling only while the
+     *  owning model is rigid (see ModelInstance.rigid) — animation moves vertices
+     *  out of it, which is why a skinned model culls per model instead. */
+    bounds: Float32Array;
+    /** Slot in the cull metadata and indirect-argument buffers. Reassigned every
+     *  time the flat draw list is rebuilt (model added/removed, draws re-sorted).
+     *  -1 until the list is built. */
+    cullIndex: number;
+}
+/** What getCullDiagnostics() reports: the GPU's answer, an independent CPU
+ *  answer over the same source data, and every draw where they disagree. */
+export interface CullDiagnostics {
+    drawCount: number;
+    modelCount: number;
+    /** Draws the GPU compute left with instanceCount = 1. */
+    cameraVisibleGpu: number;
+    shadowVisibleGpu: number;
+    /** The same test run on the CPU from the same bounds and frusta. */
+    cameraVisibleCpu: number;
+    shadowVisibleCpu: number;
+    /** How each model was bounded this frame — the split that decides whether a
+     *  stage culls per material or per model. */
+    rigidModels: number;
+    skinnedModels: number;
+    mismatches: {
+        model: string;
+        material: string;
+        pass: "camera" | "shadow";
+        gpu: boolean;
+        cpu: boolean;
+    }[];
+    /** What each model was actually tested against. Without this a report saying
+     *  "everything visible" is unreadable — you cannot tell a working cull looking
+     *  at geometry that genuinely fills the screen from a cull that never rejects
+     *  anything. The radius against the camera distance answers it directly. */
+    models: {
+        name: string;
+        rigid: boolean;
+        visible: boolean;
+        draws: number;
+        /** How many of this model's draws survived the camera frustum. */
+        cameraVisible: number;
+        /** How many survived the light frustum AND carry the PMX cast-shadow flag.
+         *  Split from `casters` so a zero here is readable: no casters at all means
+         *  the author turned shadows off, while casters with zero survivors means
+         *  the light-frustum test rejected them. */
+        shadowVisible: number;
+        /** Draws with the PMX cast-shadow flag set (bit 0x04), before any culling. */
+        casters: number;
+        /** Sphere path only: the world centre and radius tested against. Null for a
+         *  rigid model, whose draws each carry their own box instead. */
+        sphere: [number, number, number, number] | null;
+    }[];
+    /** Where the camera was, so the numbers above can be read against it. */
+    camera: {
+        eye: [number, number, number];
+        target: [number, number, number];
+    };
+    /** Times the draw list has been rebuilt since the engine started. It should
+     *  climb only when scene STRUCTURE changes — a model loaded, a style group
+     *  applied — and then stop. A number that keeps rising while nothing but the
+     *  animation is moving means something is dirtying the list every frame, which
+     *  is the failure mode that makes render bundles cost more than they save. */
+    rebuilds: number;
+    /** Times the render bundles have been re-recorded. Held to the same standard
+     *  as `rebuilds`, and for the sharper reason: a bundle exists to be replayed,
+     *  so one re-recorded every frame is strictly worse than not having it. */
+    bundleRecords: number;
 }
 interface PickDrawCall {
     count: number;
@@ -246,6 +328,10 @@ interface PickDrawCall {
 }
 interface ModelInstance {
     name: string;
+    /** This model's id in the id attachment — 1-based, so 0 stays "nothing".
+     *  The pick pass has always minted it; the cast carries it now too, so an
+     *  effect can compare what it reads out of the id buffer against a subject. */
+    objectId: number;
     model: Model;
     basePath: string;
     assetReader: AssetReader;
@@ -258,7 +344,7 @@ interface ModelInstance {
     skinMatrixBuffer: GPUBuffer;
     drawCalls: DrawCall[];
     shadowDrawCalls: DrawCall[];
-    shadowBindGroup: GPUBindGroup;
+    shadowBindGroups: GPUBindGroup[];
     mainPerInstanceBindGroup: GPUBindGroup;
     pickPerInstanceBindGroup: GPUBindGroup;
     pickDrawCalls: PickDrawCall[];
@@ -283,6 +369,24 @@ interface ModelInstance {
     styleGroups: Map<string, GroupInstall>;
     materialToGroup: Map<string, string>;
     styleGroupGen: Map<string, number>;
+    /** Slot in the per-model cull buffer, assigned when the draw list is rebuilt. */
+    cullModelIndex: number;
+    /** Every bone shares one skin matrix (within tolerance) and no vertex morph can
+     *  move a vertex out of its material's box — so the model is a rigid transform
+     *  of its bind pose and its per-material AABBs are live. True for a stage, and
+     *  for any character still in bind pose. Re-evaluated only on the frames the
+     *  skin matrices are re-uploaded, which is never for an idle stage. */
+    rigid: boolean;
+    /** The shared skin matrix, when rigid: model space → world, INCLUDING the
+     *  scene placement (setModelTransform bakes the root into skinning). */
+    rigidXform: Float32Array;
+    /** Bound on how far skinning can carry a vertex from the bone that drives it:
+     *  max over vertices of max over influencing joints of |v − bindPos(joint)|,
+     *  plus the largest single vertex-morph displacement. An AABB over the model's
+     *  POSED bone positions grown by this contains every skinned vertex, because a
+     *  skinned position is a convex combination of rigid images of v, each within
+     *  that distance of its bone's posed position. */
+    skinMargin: number;
 }
 /**
  * One material a type-8 morph can reach, with the uniform block as it loaded.
@@ -339,6 +443,10 @@ export declare class Engine {
     private zeroStyleBuffer;
     private mainPipelineLayout;
     private sceneTargets;
+    /** The scene pass's attachment formats, settled at init once the device has
+     *  said which HDR format it will blend. Every scene-pass pipeline asks
+     *  scene-contract for its targets against these. */
+    private get sceneFormats();
     private fullVertexBufferLayouts;
     private defaultToonRampTexture;
     private groundShadowPipeline;
@@ -381,6 +489,16 @@ export declare class Engine {
     private hdrResolveTexture;
     private static readonly MULTISAMPLE_COUNT;
     private hdrFormat;
+    /** Main-pass depth. Float when the adapter offers depth32float-stencil8, which
+     *  is also what makes reversed-Z worth switching on. */
+    private depthFormat;
+    /** Near maps to 1 and far to 0. Set once at init and never toggled — every
+     *  pipeline's compare function and both depth clears are chosen from it. */
+    private reversedZ;
+    /** The compare a "draw what is in front" pipeline wants, either way round. */
+    private get depthAhead();
+    /** The value a cleared depth buffer holds: the FAR plane, whichever end that is. */
+    private get depthClear();
     /** Stencil value stamped by eye draws so hair can stencil-test against it and
      *  alpha-blend a second pass over eye silhouette pixels (see-through-hair effect). */
     private static readonly STENCIL_EYE_VALUE;
@@ -393,15 +511,229 @@ export declare class Engine {
      *        cleared / edge-faded regions like before).
      *  rg8unorm at 4× MSAA is 8 bytes/texel — still fits Apple TBDR tile memory comfortably. */
     private static readonly BLOOM_MASK_FORMAT;
+    /**
+     * The master switch for the id attachment. OFF — and off having been proven
+     * to work, not off because it was never finished.
+     *
+     * ON, because there is finally something that reads it: rzObjectAt and
+     * rzMaterialAt in the field module let an effect mask itself to one character
+     * or one material. It was switched off in the meantime rather than left
+     * running — rg16uint at the pass's sample count is around 33MB at 1080p,
+     * cleared and stored every frame, and paying that for a buffer nobody read
+     * would have handed back the same order of bandwidth the empty field-pass
+     * clears had just saved.
+     *
+     * Verified through setIdDebug against a real scene: flat colour per material
+     * with hard edges (so nothing interpolates or resolves them), the floor on
+     * its reserved id, black exactly where nothing drew. Turning it back off is
+     * this line, and the accessors then answer 0 rather than failing to compile.
+     */
+    private static readonly MRT_IDS;
+    /** The id attachment. Multisampled with the pass and NEVER resolved: an
+     *  averaged id belongs to nothing, so consumers textureLoad sample 0. */
+    private idTexture;
+    private idView;
+    /** The id buffer drawn to the screen — see setIdDebug. */
+    private idDebugPipeline;
+    private idDebugBindGroupLayout;
+    private idDebugBindGroup;
+    private idDebug;
     private multisampleMaskTexture;
     private maskResolveTexture;
     private maskResolveView;
+    /**
+     * The installed effect's particle system, or null when it declared none.
+     *
+     * A fixed pool: the count is chosen at install and the slots recycle, so there
+     * is no allocation and no spawn-rate bookkeeping in the hot path. Dead slots
+     * cost a degenerate quad the rasteriser rejects, which is cheaper than the
+     * prefix sum and readback a compacted draw list would need every frame.
+     */
+    /** Ceiling for `// @particles`. Past this an author is asking for a stall. */
+    private static readonly MAX_PARTICLES;
+    private particleFrame;
+    /**
+     * The installed effect's persistent grid, or null when it declared none.
+     *
+     * Two textures, not one, and read/write alternate between them every frame:
+     * a shader cannot coherently read and write the same texture, so this is not
+     * an optimisation but the only correct shape. `parity` says which one holds
+     * the CURRENT grid — the one everything else samples.
+     */
+    private simSampler;
+    private simFallbackView;
+    /** 1×1 transparent stand-in, for every layer binding with nothing behind it. */
+    private trailFallbackView;
+    /**
+     * The field layer: user background/foreground mounts, ONE TARGET PAIR PER
+     * RESOLUTION. Index 0 is full, index 1 is half — coarsest last, so the
+     * composite reads them full-over-half.
+     *
+     * `@fullres` used to be a property of the shared targets: one effect
+     * declaring it promoted the pass for every effect installed, so a starfield
+     * that upsamples perfectly paid four times the pixels because a keyboard
+     * beside it needed crisp edges. Measured, that was the largest avoidable cost
+     * in the frame — Footprints went from about 1.2ms to 4.5ms purely by being
+     * dragged along.
+     *
+     * The price is that a resolution boundary is now a LAYER boundary. Within a
+     * pair, effects blend in document order; across pairs the full-res layer
+     * composites over the half-res one whatever the document said. Invisible for
+     * the additive glows this is nearly always used for, and stated because it is
+     * the one thing document order stopped deciding.
+     */
+    private static readonly FIELD_SCALES;
+    /** Reused for the per-frame field-clock upload — one 16-byte write per
+     *  drawing effect, and allocating a fresh array for each would be garbage
+     *  every frame. */
+    private fieldClockScratch;
+    /** Material parameters driven by the scene clock — see setStyleParamTrack. */
+    private paramTracks;
+    private fieldBgTextures;
+    private fieldBgViews;
+    private fieldFgTextures;
+    private fieldFgViews;
+    /** One per scale: the field shader reconstructs the full-res pixel it stands
+     *  in for, so each pass needs its own (w, h, fullW, fullH). */
+    private fieldUniformBuffers;
+    private fieldFullW;
+    private fieldFullH;
+    private fieldBindGroupLayout;
+    private fieldPipelineLayout;
+    /**
+     * The audio analysis buffer every effect module binds: header
+     * [frames, bands, secondsPerFrame, audioTime], then [level, band0..bandN-1]
+     * per frame. Precomputed by the host for the whole track — never a live
+     * analyser, which would render silence during an export. Falls back to four
+     * zeroes (frames = 0) so layouts always bind.
+     */
+    private audioBuffer;
+    private audioFallbackBuffer;
+    private midiBuffer;
+    private midiFallbackBuffer;
+    /** Fixed-size (LYRICS_FLOATS): setLyrics is a write, never a reallocation,
+     *  so lyric data arriving after any effect reaches it with no re-binding. */
+    private lyricsBuffer;
+    /** The rasterised lines, for rzLyricText. Sized to the track that arrives —
+     *  a 1×1 placeholder until one does, so a scene with no lyrics pays nothing
+     *  and a song's text is stored at the resolution it is drawn at. */
+    private lyricsTexture;
+    private lyricsTextureView;
+    /** The notes as installed, kept CPU-side because the per-pitch key map is
+     *  rebuilt from them every time the clock moves. */
+    private midiNotes;
+    /** Header + key map, re-uploaded per clock write. */
+    private midiLiveScratch;
+    private midiRelease;
+    private audioTimeScratch;
     private renderPassDescriptor;
     private compositePassDescriptor;
     private compositePipelineIdentity;
     private compositePipelineGamma;
     private morphComputePipeline;
     private morphComputeBindGroupLayout;
+    /** Null once the pipeline has failed to compile — the pass then does nothing
+     *  rather than invalidating every command buffer it touches. */
+    private cullPipeline;
+    private cullBindGroupLayout;
+    private cullBindGroup;
+    /** Every material draw in the scene, flat, in the order the passes walk them.
+     *  A draw's position here IS its slot in every cull buffer. */
+    private cullDraws;
+    private cullModels;
+    /** Structure changed — model added or removed, draws re-sorted. NOT set by
+     *  animation, physics or camera movement, which is the whole point. */
+    private cullListDirty;
+    private cullMetaBuffer;
+    private cullModelBuffer;
+    private cullHiddenBuffer;
+    private cullHidden;
+    private cullArgs;
+    /** Draws and models the current buffers can hold. A rebuild that fits inside
+     *  these rewrites contents and allocates nothing. */
+    private cullCapacity;
+    private cullModelCapacity;
+    /** How many times the draw list has been rebuilt — a bundle-era regression
+     *  guard, reported by getCullDiagnostics. Steady-state it must not climb. */
+    private cullRebuilds;
+    private opaqueBundle;
+    private transparentBundle;
+    private shadowBundles;
+    /** Set by scene STRUCTURE only. Every frame of animation, every physics step
+     *  and every camera move must leave this alone — re-recording constantly is
+     *  worse than having no bundles at all. */
+    private bundlesDirty;
+    /** Companion to cullRebuilds: how many times the bundles have been recorded.
+     *  Steady-state it must not climb. */
+    private bundleRecords;
+    /** Every pass worth watching across a refactor. The query set, the resolve
+     *  buffer and the readback are all sized from this, so adding one here is the
+     *  whole change.
+     *
+     *  `field` earns its place now that a scene runs SEVERAL field effects at
+     *  once: it is one pass with N draws, its resolution is a property of the
+     *  shared targets rather than of any one effect — so a single `@fullres`
+     *  effect quadruples the pixel count for all of them — and it is the pass the
+     *  field restructure moves. Restructuring it while it was the only untimed
+     *  pass in the frame would have meant reasoning about the cost instead of
+     *  reading it. */
+    private static readonly TIMED_PASSES;
+    private timestampQuerySet;
+    private timestampResolve;
+    private timestampRead;
+    /** A map is in flight; the readback buffer cannot be written while it is. */
+    private timestampBusy;
+    private gpuPassMs;
+    private cullCameraArgs;
+    private cullShadowArgs;
+    private cullMirrorArgs;
+    private static readonly REFLECTION_PLANE_Y;
+    private mirrorCameraData;
+    private mirrorCameraBuffer;
+    private mirrorVPData;
+    private mirrorVPBuffer;
+    private mirrorPerFrameBindGroup;
+    private mirrorColorMsTexture;
+    private mirrorColorTexture;
+    private mirrorColorView;
+    private mirrorMipCount;
+    private mirrorMipViews;
+    private mirrorBlurBindGroups;
+    private groundMirrorBlur;
+    private mirrorMaskMsTexture;
+    private mirrorIdMsTexture;
+    private mirrorDepthTexture;
+    private mirrorDepthReadView;
+    private mirrorPassDescriptor;
+    private mirrorOpaqueBundle;
+    private mirrorTransparentBundle;
+    /** setGroundMirror lands in step 7D; the debug dial is what exercises C. */
+    private groundMirror;
+    private reflectionDebug;
+    private reflectionDebugPipeline;
+    private reflectionDebugBindGroupLayout;
+    private reflectionDebugBindGroup;
+    private get reflectionActive();
+    private cullFrustaBuffer;
+    private cullFrustaBytes;
+    private cullFrustaF32;
+    private cullFrustaU32;
+    /** CPU-side mirrors of what was uploaded, so the reference test reads exactly
+     *  the same numbers the compute did. */
+    private cullMetaBytes;
+    private cullMetaF32;
+    private cullMetaU32;
+    private cullModelData;
+    private cullModelFlags;
+    /** Per draw: bit0 = passes the camera frustum, bit1 = passes the light frustum
+     *  and casts. Filled by the CPU reference; only computed when something asks. */
+    private cullReference;
+    private cullReferenceFrame;
+    private cullEnabled;
+    private cullFrame;
+    private cullScratchVp;
+    private cullReadback;
+    private cullReadbackInFlight;
     private compositeBindGroupLayout;
     private compositeBindGroup;
     private depthOfField;
@@ -416,15 +748,50 @@ export declare class Engine {
     private backgroundColor;
     private backdropEquirectTexture;
     private backdropEquirectView;
+    private backdropEquirectHDR;
+    private backdropStrength;
+    /** The installed HDRI's folded irradiance SH (27 floats), or null. */
+    private worldSH;
     private fallbackEquirectTexture;
     private fallbackEquirectView;
-    private effect;
+    /**
+     * The scene's effects, in document order — the order they layer in.
+     *
+     * An array from here down even while setEffect installs exactly one, because
+     * the plural is the whole point of this step and a singleton that has to be
+     * "generalised later" is a singleton that shapes every call site against it.
+     */
+    private effects;
+    /** The first installed effect, for the many places that legitimately want
+     *  "is anything installed" or the singleton API's one effect. */
+    private get effect();
     /** The cast, as the effect API sees it. Written per frame while an effect is
      *  installed, and only up to what that effect actually declared. */
     private castBuffer;
+    /** The positional lights, as data — see shaders/lights.ts for the layout.
+     *  Allocated once at full size and zero-filled, so "no lights" is a count of
+     *  zero rather than an absent binding. */
+    private lightsBuffer;
+    private lightsData;
+    /** Just the header, for rewriting the total without touching a record. */
+    private lightHeader;
+    /** How many of the slots belong to the DOCUMENT. Effects get what follows. */
+    private docLightCount;
     private castData;
     /** Last frame's anchor world positions, for velocity. Keyed model id → slot. */
     private anchorPrev;
+    /**
+     * The SCENE's bones: which ones are recorded into the cast buffer, and which
+     * address each one holds. Built at install from every effect's requests, so
+     * the buffer is written once per bone however many effects read it.
+     *
+     * Everything that touches the cast buffer iterates THIS rather than any one
+     * effect's declarations — that is the whole change, and it is what makes N
+     * effects a loop instead of a rewrite. With one effect installed the table is
+     * exactly that effect's anchors in declaration order, which is why this lands
+     * with no visible difference.
+     */
+    private anchorTable;
     private castLastMs;
     /** Recent path per trailed anchor, keyed "model\0slot". Newest first, so the
      *  shader's index 0 is now — written by unshifting rather than by tracking a
@@ -446,7 +813,6 @@ export declare class Engine {
     /** time=0 origin for the active effect — reset each setEffect. */
     /** Scene-clock reading when the current effect was installed. The effect's
      *  `time` is measured from here — see where it is written. */
-    private effectEpochScene;
     private compositeBloomView;
     private bloomSampler;
     private bloomBlitUniformBuffer;
@@ -473,16 +839,16 @@ export declare class Engine {
     private groundVertexBuffer?;
     private groundIndexBuffer?;
     private hasGround;
-    private shadowMapTexture;
-    private shadowMapDepthView;
+    private shadowMapTextures;
+    private shadowMapDepthViews;
     private brdfLutTexture;
     private brdfLutView;
     private filmicLutTexture;
     private filmicLutView;
     private static readonly FILMIC_LUT_WIDTH;
-    private static readonly SHADOW_MAP_SIZE;
     private shadowDepthPipeline;
     private shadowLightVPBuffer;
+    private shadowCascadeVPBuffers;
     private shadowLightVPMatrix;
     private groundShadowBindGroup?;
     private shadowComparisonSampler;
@@ -563,7 +929,118 @@ export declare class Engine {
     /** Debug/diagnostic: skip every inverted-hull outline draw. */
     private outlineEnabled;
     setOutlineEnabled(on: boolean): void;
+    /**
+     * Draw the id attachment instead of the scene.
+     *
+     * The only way to SEE whether ids are right: with no consumer, a correct id
+     * buffer and a wrong one render the same frame. See id-debug.ts for what
+     * correct looks like and what each failure looks like instead.
+     *
+     * Returns false when there is nothing to show — ids compiled out, or a device
+     * that cannot multisample the format — rather than turning on and drawing
+     * black, which would read as "the ids are all zero".
+     */
+    setIdDebug(on: boolean): boolean;
+    /** True when the id attachment exists on this device. */
+    hasObjectIds(): boolean;
+    /** The pass that draws it, built lazily so a scene that never asks for the
+     *  debug view never compiles it. */
+    private ensureIdDebugPipeline;
+    private renderIdDebugPass;
+    /**
+     * Show the floor mirror's target instead of the finished frame — the
+     * instrument that makes the reflection pass checkable before the ground
+     * consumes it. Dev surface, like setIdDebug beside it.
+     */
+    setReflectionDebug(on: boolean): void;
+    /**
+     * What is lighting the world seat right now — the dev-console answer to
+     * "did the HDRI actually arrive". Flat mode reports the same colour for
+     * every direction, which is what flat means.
+     */
+    getWorldLighting(): {
+        source: "hdri" | "flat";
+        strength: number;
+        up: [number, number, number];
+        down: [number, number, number];
+    };
+    /**
+     * Switch the floor mirror without rebuilding the ground — the adjust-tier
+     * sibling of addGround's own options. False when there is no ground.
+     *
+     * ON OR OFF, deliberately not a strength: the reflection is an independent
+     * LAYER beneath the floor surface, and how much of it shows is the ground's
+     * own opacity covering it. Blur 0 is a polished mirror; 1 samples the
+     * softest level, scaled by how far the reflected geometry sits behind the
+     * surface.
+     */
+    setGroundMirror(on: boolean, blur?: number): boolean;
+    private ensureReflectionDebugPipeline;
+    private renderReflectionDebugPass;
+    /** Refold the live camera with the reflection — a copy and a handful of
+     *  sign flips; cheap enough to run every frame a mirror is on. */
+    private updateMirrorCamera;
+    /**
+     * The scene, mirrored about the floor, into the half-res reflection target.
+     *
+     * Models only: no ground (the mirror IS the ground), no particles, trails or
+     * field effects — the classic MMD stage-floor reflection is the cast, and
+     * each of those layers would need its own mirrored variant to join. Runs
+     * between emitLights (materials read the lights buffer) and the scene pass
+     * (whose ground will sample the resolve).
+     *
+     * KNOWN LIMIT, deliberate: geometry BELOW the floor plane would reflect up
+     * into the target — there is no oblique clip. MMD stages rarely have any;
+     * the clip is the follow-up if one shows.
+     */
+    private renderMirrorPass;
+    /**
+     * Fill the mirror's mip levels — the bloom pyramid's own 13-tap downsample,
+     * one pass per level. Only when the blur dial is up: at zero the ground
+     * samples level 0 exactly and the chain would be work nobody reads.
+     */
+    private renderMirrorBlurChain;
+    /**
+     * Can this device multisample the id format at the pass's sample count?
+     *
+     * Asked by creating one and catching the validation error, because there is
+     * no capability flag for it — WebGPU guarantees multisampling for renderable
+     * colour formats but implementations have differed on uint targets, and the
+     * cost of finding out the hard way is a device-lost on someone's machine and
+     * a black canvas.
+     *
+     * The scope is popped in a finally: leaving an error scope pushed swallows
+     * the NEXT error in this device, wherever it happens, and that error would
+     * then be attributed to nothing.
+     */
+    private probeMultisampledIds;
     private rebuildCompositeBindGroup;
+    /**
+     * Does any installed effect draw into field pair `layer`?
+     *
+     * Shared with renderFieldPass deliberately. The pass skips a pair nothing
+     * draws into, so the composite must read the 1x1 fallback for that pair
+     * rather than a target no one cleared. Two spellings of "empty" is two
+     * spellings that eventually disagree, and the frame it disagreed on would
+     * show last frame's effect after the effect was removed.
+     *
+     * It is only ever asked at bind-group build time, and setEffects rebuilds the
+     * bind group after assigning this.effects — which is exactly the moment a
+     * pair can change between empty and not.
+     */
+    private fieldPairUsed;
+    /** One half of one field pair, as the composite should read it. */
+    private fieldLayerView;
+    private createFieldTargets;
+    /**
+     * ONE PER GRID PARITY.
+     *
+     * The grid alternates which texture holds the current grid, so the field pass
+     * needs a bind group for each — built once here rather than rebuilt every
+     * frame, which is what a single group would force and is pure waste for a
+     * change that only ever toggles between two known states.
+     */
+    private rebuildFieldBindGroup;
     /**
      * Set a 360° backdrop from an equirectangular (2:1) image — a PhotoDome-style
      * skybox at infinity, sampled per-pixel by view direction so it follows the
@@ -571,7 +1048,10 @@ export declare class Engine {
      * affects lighting, bloom, or tonemapping. Pass null to remove (the background
      * color, or transparency, takes over again).
      */
-    setBackdropEquirect(source: ImageBitmap | HTMLImageElement | HTMLCanvasElement | null): void;
+    setBackdropEquirect(source: ImageBitmap | HTMLImageElement | HTMLCanvasElement | HdrImage | null, options?: {
+        /** World strength for an HDR source, Blender's dial. Default 1. */
+        strength?: number;
+    }): void;
     private makeCompositePipeline;
     /**
      * Install the scene's WGSL effect (shadertoy-style), rendered per-pixel in the
@@ -608,7 +1088,118 @@ export declare class Engine {
      * is KEPT and diagnostics are returned with line numbers relative to the
      * user's WGSL. Pass null to remove the effect.
      */
+    private compileEffect;
+    /**
+     * Compile an effect's particle stages and allocate its pool.
+     *
+     * Two modules, not one: the compute and render stages bind the same buffer
+     * with different access (read_write vs read), and a single module would have
+     * to pick one. Compiling them separately also means an author's helper names
+     * live in their own compilation unit, which is what lets two effects both
+     * define `hash21` without meeting.
+     */
+    /**
+     * Install a LIST of effects, in document order — the order they layer in.
+     *
+     * Each is compiled independently and a failure is contained: it is reported in
+     * its own slot of the returned array and left out of the scene, while the rest
+     * install. That is the style-group discipline, and it matters more here — with
+     * four effects on screen, "one bad shader blanks the scene" is the first bug
+     * report anyone would file.
+     *
+     * The bones are allocated ONCE for the whole list: two effects naming the same
+     * wrist share one address and one recorded path, and the cap is eight distinct
+     * bones across the scene rather than per file.
+     *
+     * Null or empty clears everything.
+     */
+    setEffects(list: {
+        wgsl: string;
+        params?: Record<string, EffectParamValue>;
+    }[] | null): Promise<EffectResult[]>;
+    /**
+     * Install ONE effect — the singleton API, kept because most scenes are one
+     * effect and every existing caller uses it. A one-element setEffects.
+     */
     setEffect(wgsl: string | null, params?: Record<string, EffectParamValue>): Promise<EffectResult>;
+    private buildParticles;
+    /**
+     * Step the pool, before the scene pass.
+     *
+     * Outside the render pass because a compute dispatch cannot be encoded inside
+     * one — and it has to precede the draw that reads the same buffer, or the
+     * quads render last frame's positions.
+     */
+    /**
+     * Compile an effect's lightEmit stage and give it a bind group.
+     *
+     * Its own layout rather than a shared one: this is the only place the lights
+     * buffer is WRITABLE, and every other binding of it is read-only. Keeping the
+     * writable view here means a material pipeline cannot accidentally acquire
+     * one.
+     */
+    private buildLightEmit;
+    /**
+     * Hand every emitting effect its slot range, and write the total.
+     *
+     * Document lights sit FIRST, at slot 0, and effects follow in document order.
+     * That ordering is the stable one: a scene's own lamps are the thing a person
+     * placed and can see in a list, so they should not move because an effect was
+     * installed ahead of them.
+     *
+     * Called whenever either producer changes. The base lands in each effect's
+     * uniform, so nothing recompiles.
+     */
+    private allocateLightSlots;
+    /** Run every effect's lightEmit, before the pass that reads the result. */
+    private emitLights;
+    private stepParticles;
+    /** Draw the pool. Inside the scene pass, so it is depth-tested and pre-bloom. */
+    private renderParticles;
+    /**
+     * Compile an effect's ribbon stage.
+     *
+     * One instance per (slot, subject, segment), so a scene with several dancers
+     * and several declared bones is still one draw and nothing is computed per
+     * frame on the CPU.
+     */
+    private buildTrails;
+    private releaseTrails;
+    /**
+     * Ribbons, drawn INSIDE the scene pass — as geometry, in HDR, before bloom.
+     *
+     * They used to own a colour target and be pasted over the finished frame
+     * after tone mapping, which is exactly why they could not bloom: nothing
+     * composited post-tonemap can. Here they are lit like anything else in the
+     * scene, depth-tested against the body they circle, and their emission
+     * reaches the bloom prefilter through the aux mask they now write.
+     *
+     * Takes the pass rather than opening one: that IS the change.
+     */
+    private drawTrails;
+    /** The user's field mounts, drawn at half resolution for the composite to
+     *  upsample. Runs the whole quad — uniform control flow, so effects may use
+     *  derivatives freely, which the old inline path had to forbid. */
+    private renderFieldPass;
+    /** The trail bind group holds the depth view, which a resize recreates. */
+    private rebindTrails;
+    private releaseParticles;
+    /**
+     * Compile and allocate the effect's persistent grid.
+     *
+     * The textures are created ZEROED, which is the contract a kernel is written
+     * against: rzGridFrame() is 0 on the first step and every value it reads is
+     * zero, so seeding is just "if frame is 0, return the initial state".
+     */
+    private buildSim;
+    private releaseGrid;
+    /**
+     * Step the grid, before anything reads it.
+     *
+     * Outside the render pass, like the particle step and for the same reason —
+     * and before the field pass, or an effect samples a grid one frame stale.
+     */
+    private stepSim;
     /** Which mounts the installed effect declared. Both false when none is set. */
     getEffectMounts(): {
         background: boolean;
@@ -684,6 +1275,67 @@ export declare class Engine {
      *  loaded. A timeline cannot draw a lane to scale without it, and the camera's
      *  length is its own: it does not have to match any model's clip. */
     getCameraVmdDuration(): number;
+    /**
+     * Install a track's precomputed analysis for the rzAudio* effect functions:
+     * `data` is frames × (2 + bands) floats — loudness, bass onset, then the band
+     * magnitudes, all 0..1 — sampled by the clock given to setAudioTime. Null
+     * clears back to silence.
+     *
+     * Precomputed for the WHOLE track, never fed live from an analyser: an export
+     * steps the engine frame by frame rather than playing in real time, so live
+     * analysis would render silence into the exported video.
+     */
+    setAudioData(data: Float32Array | null, bandsPerFrame: number, secondsPerFrame: number): void;
+    /**
+     * Install a score — note events — for the rzNote* and rzKey* effect functions.
+     * Null clears it.
+     *
+     * The sibling of setAudioData, and deliberately a SEPARATE interface rather
+     * than something derived from it: a spectrum cannot give back a discrete pitch
+     * and onset, and that discreteness is the whole substance of a falling note.
+     * A scene can hold both and read them together.
+     *
+     * `release` is how long a key keeps glowing after its note ends, in seconds.
+     * It belongs here rather than in the effect because the key map it feeds is
+     * computed on the CPU — see writeMidiClock.
+     */
+    /**
+     * Install the track's lyric lines for the rzLyric* effect functions — the
+     * timing of the words on the scene clock, and optionally the words
+     * themselves: `atlas.source` is a canvas/bitmap of rasterised lines (the
+     * host draws them — Canvas2D handles every script the platform does) with
+     * `atlas.rects` saying where each line sits, in 0..1 [u0, vTop, u1, vBottom].
+     * Null clears. A plain buffer write plus at most a texture copy: buffer and
+     * atlas are both fixed-size, so nothing re-binds whenever lyrics arrive.
+     */
+    setLyrics(lines: LyricLine[] | null, atlas?: {
+        source: GPUCopyExternalImageSource;
+        width: number;
+        height: number;
+        rects: LyricRect[];
+    }): void;
+    setMidiNotes(notes: MidiNote[] | null, release?: number): void;
+    /**
+     * Move the score's clock, and rebuild the per-pitch key map from it.
+     *
+     * The map is why this is more than a header write. Falling notes index the
+     * note list directly, but a keyboard glow asks the opposite question per
+     * pixel — is anything sounding at THIS pitch — and answering that in the
+     * shader would be a scan of the whole score per fragment. One O(notes) pass
+     * here, once a frame, turns it into a single lookup.
+     *
+     * The pass is a full scan rather than a cursor because scrubbing exists: a
+     * cursor is only correct while time moves forward, and a timeline drag is
+     * exactly when a wrong answer is most visible. Ten thousand notes is ten
+     * thousand comparisons, which is nothing beside the pose pass.
+     */
+    setMidiTime(seconds: number, playing?: boolean): void;
+    /**
+     * Where the track is NOW, in seconds — written by whoever owns playback: the
+     * editor's audio clock, the viewer's, or the export loop with its exact
+     * per-frame time. A 4-byte header write, cheap enough for every frame.
+     */
+    setAudioTime(seconds: number, playing?: boolean): void;
     /** Every camera keyframe's frame index — what a timeline draws as its cuts.
      *  Empty when no camera VMD is loaded. */
     getCameraVmdKeyframes(): number[];
@@ -739,7 +1391,39 @@ export declare class Engine {
         noiseStrength?: number;
         /** Whole-ground opacity, 0–1 (multiplies the radial edge fade). Default 1. */
         opacity?: number;
+        /** Floor mirror, on or off — NOT a strength: the reflection is its own
+         *  layer, and how much of it shows is the surface's own `opacity`
+         *  covering it. Off (default) never renders the reflection pass at all. */
+        mirror?: boolean;
+        /** Mirror softness, 0–1: 0 a polished mirror, 1 the softest blur level,
+         *  scaled by how far the reflected geometry sits behind the surface. */
+        mirrorBlur?: number;
     }): void;
+    /**
+     * The scene's positional lights — an ADDITIVE layer over the sun, which stays
+     * the key light and keeps the toon ramp to itself.
+     *
+     * Colour and intensity are multiplied here rather than stored apart: every
+     * read is the product, and two numbers that are only ever multiplied are two
+     * numbers that can disagree.
+     *
+     * Past MAX_LIGHTS the extras are DROPPED, not wrapped: the lights that fit
+     * keep the meaning the caller gave them, which is the same rule the anchor
+     * table follows. Passing none (or an empty list) turns the layer off and the
+     * scene renders exactly as it did before lights existed.
+     */
+    setLights(
+    /** Structural {x,y,z} rather than the Vec3 class, the same choice effect
+     *  params make: a scene document's JSON passes straight in, and so does a
+     *  literal typed into a console. Vec3 satisfies it either way. */
+    lights: {
+        position: XYZ;
+        color: XYZ;
+        intensity?: number;
+        radius?: number;
+    }[] | null): void;
+    /** How many positional lights the scene is carrying. */
+    getLightCount(): number;
     private updateLightBuffer;
     getStats(): EngineStats;
     runRenderLoop(callback?: () => void): void;
@@ -852,10 +1536,170 @@ export declare class Engine {
     private updateInstances;
     private updateVertexBuffer;
     private dispatchMorphCompute;
+    private static readonly CULL_META_BYTES;
+    private static readonly CULL_MODEL_FLOATS;
+    private static readonly CULL_ARG_WORDS;
+    private static readonly CULL_DRAW_CASTS_SHADOW;
+    private static readonly CULL_MODEL_VISIBLE;
+    private static readonly CULL_MODEL_RIGID;
+    /**
+     * Flatten the scene's material draws into the order every cull buffer is
+     * indexed by, and upload everything that only changes with STRUCTURE: the
+     * per-draw metadata and the constant words of the indirect arguments.
+     *
+     * Runs on model add/remove and on any re-sort of a model's draws (a style
+     * group assignment re-ranks them). Animation, physics and camera movement all
+     * leave it alone — that is the same invalidation set the render bundles will
+     * want, tested here first where being wrong is cheap.
+     */
+    private rebuildCullList;
+    /**
+     * Per-draw hidden state, uploaded only when it actually changes.
+     *
+     * The two sets behind it are cheap to read but the buffer is not worth
+     * rewriting every frame: applyMaterialMorphs rebuilds morphHiddenMaterials on
+     * every frame of any character carrying a face VMD, and almost every one of
+     * those rebuilds produces the same answer. So compare, then upload.
+     */
+    private writeCullHidden;
+    private releaseCullBuffers;
+    /**
+     * One record per model: the rigid transform its per-material boxes live under,
+     * or the world sphere that bounds it in any pose. Written every frame, because
+     * this is the part animation moves — a few hundred bytes per model.
+     */
+    private writeCullModels;
+    /**
+     * The world sphere for a skinned model: an AABB over its POSED bone positions,
+     * grown by the model's skin margin, then carried through the scene placement.
+     *
+     * Bone positions come from the pose that already ran this frame, so a jump, a
+     * run across the stage or a physics-driven skirt are all inside it by
+     * construction — none of which a bind-pose box would have contained. See
+     * ModelInstance.skinMargin for why growing by that one number is a bound and
+     * not an estimate.
+     */
+    private writeCullSphere;
+    /**
+     * The camera's six frustum planes then the sun's, normalized, as inward
+     * half-spaces (`dot(n, p) + d >= 0` is inside).
+     *
+     * Extracted from the combined view-projection rather than rebuilt from the
+     * camera's own parameters, so a VMD-driven shot, an orbit and the shadow
+     * volume's ortho box all go through one code path and none of them can
+     * disagree with what the vertex shader actually projects.
+     *
+     * Culling shadow casters to the light's frustum looks like it should lose
+     * casters that stand outside the volume and throw shade into it. It cannot:
+     * the cull tests the OUTERMOST cascade's box, each cascade's rasterizer clips
+     * to its own box, and every inner box lies inside the outer one (the
+     * containment invariant in shadow-cascades.ts) — so anything rejected here
+     * was contributing to no cascade at all.
+     */
+    private writeCullFrusta;
+    /**
+     * Cull every material draw against the camera and the sun, writing
+     * `instanceCount` into two indirect-argument buffers.
+     *
+     * Nothing draws from those buffers yet. This increment stands the pass up and
+     * leaves the draw path issuing direct draws, so the bounds and the frusta can
+     * be checked against a scene that is definitely rendering correctly — see
+     * getCullDiagnostics and setCullApply.
+     */
+    /**
+     * Record the three bundles: the shadow pass, the opaque phase and the
+     * transparent phase.
+     *
+     * The insight this rests on is that a character's DRAW COMMANDS are stable
+     * frame to frame — same pipeline, same bind groups, same index ranges, with
+     * only the contents of the skin-matrix buffer changing. So bundles apply to
+     * the cast, not merely to scenery, and what invalidates one is scene
+     * STRUCTURE. Animation, physics, camera movement, material morphs, a hidden
+     * material and a hidden model all leave a bundle valid — the first three
+     * because they touch buffers and not commands, the last two because their
+     * switches live in the cull compute rather than in this encode loop.
+     *
+     * The ground and the particles are deliberately not in a bundle: the ground is
+     * one draw that sits BETWEEN the two phases, and the particle count comes from
+     * the CPU. Both are cheaper to leave direct than to invalidate around.
+     */
+    private recordBundles;
+    /** The two query slots for a pass, or undefined where the device has no
+     *  timestamps — which every pass descriptor accepts as "do not measure". */
+    private stamps;
+    /**
+     * Resolve this frame's timings and start a readback, at most one in flight.
+     *
+     * Deliberately not awaited anywhere in the frame: a timing that costs a stall
+     * to collect would change the thing it is measuring. The numbers are therefore
+     * a frame or two old, which is exactly right for what they are for — watching
+     * a pass get more expensive across a refactor, not attributing one frame.
+     */
+    private resolveTimestamps;
+    /**
+     * Milliseconds on the GPU per pass, or null where the device cannot measure.
+     *
+     * The regression guard for the draw-path work: these are the numbers that say
+     * whether restructuring cost anything, which is the claim being made — not
+     * whether it made the scene faster, which was never the goal.
+     */
+    getGpuTimings(): Record<string, number> | null;
+    private dispatchCull;
+    /**
+     * The same test the compute runs, on the CPU, from the same uploaded numbers.
+     *
+     * Deliberately a second implementation rather than a shared one: two
+     * independent readings of the same data is what makes agreement evidence. It
+     * reads the mirrors written by writeCullModels/writeCullFrusta, so it answers
+     * for the frame that was last dispatched, and caches per frame because both
+     * the debug draw gate and the diagnostics want it.
+     */
+    private cullReferencePass;
+    /**
+     * Issue one material draw, indirect when the cull owns it.
+     *
+     * The outline and the over-eyes pass share their material's slot rather than
+     * getting their own: same index range, same bounds, so the same decision. That
+     * also means an outline can never survive a material that was culled, which is
+     * the only relationship between them that is ever correct.
+     *
+     * Falls back to a direct draw for anything outside the cull list — the ground,
+     * and any draw whose slot has not been assigned yet.
+     */
+    private issueDraw;
+    /**
+     * Turn frustum culling off without turning the pass off.
+     *
+     * The compute keeps running and keeps reporting; it just writes "visible" for
+     * every draw. That is the A/B a missing-geometry report needs — if it is still
+     * missing with culling off, the cull was not what removed it — and it costs
+     * one uniform word rather than a rebuild.
+     */
+    setCullEnabled(on: boolean): void;
+    /**
+     * Read the GPU's culling decisions back and diff them against the CPU
+     * reference over the same frame's uploaded data.
+     *
+     * A clean report means the compute, its buffer layouts and the plane
+     * extraction all agree with a second implementation. It does NOT prove the
+     * bounds contain the geometry — that is what setCullApply(true) and looking at
+     * the scene is for.
+     */
+    getCullDiagnostics(): Promise<CullDiagnostics>;
+    /** The GPU half of getCullDiagnostics: copy both argument buffers back and
+     *  diff them against the reference. */
+    private readCullArgs;
     private setupModelInstance;
     private createGpuMorph;
     private createGroundGeometry;
     private createShadowGroundResources;
+    /**
+     * (Re)build the ground's bind group. Its own method because the RESIZE path
+     * needs it too: the reflection resolve is recreated at every canvas size,
+     * and a bind group holding the old view would sample a destroyed texture on
+     * the first resized frame with a mirror on.
+     */
+    private buildGroundBindGroup;
     /** Whether the shadow map needs clearing — see the shadow pass in `render`.
      *
      *  Starts true so the very first frame runs the pass even with an empty scene. The
@@ -889,6 +1733,14 @@ export declare class Engine {
      */
     private applyMaterialMorphs;
     private createUniformBuffer;
+    /** Whether a material is switched on — the user's own toggle, or a material
+     *  morph having driven its alpha to zero.
+     *
+     *  The material passes no longer consult this: their draws are indirect, and
+     *  the cull compute zeroes the instance count of anything hidden, which is
+     *  what lets a render bundle survive a face VMD rewriting the morph-hidden set
+     *  sixty times a second. It remains the answer for the passes that draw
+     *  directly, where there is no argument buffer to zero. */
     private shouldRenderDrawCall;
     private createTextureFromLogicalPath;
     private generateMipmaps;
@@ -950,6 +1802,31 @@ export declare class Engine {
     /** Clear all style groups on a model — every material returns to the hand-shader path. */
     resetStyleGroups(modelName: string): void;
     /** Instant adjust-tier write: set one exposed slider on a group's applied graph. */
+    /**
+     * Drive a material parameter from the SCENE CLOCK.
+     *
+     * The channel this writes into already existed — setStyleParam below puts a
+     * value straight into the style uniform. What a track adds is WHEN: the value
+     * is a pure function of scene time, so a scene describes a dissolve once and
+     * playback, a re-open and an offline export stepped at another rate all
+     * produce the same frames.
+     *
+     * Addressed BY NAME (model, group, param), not by id. Worth stating because
+     * the id attachment landed alongside this and the two look related: ids
+     * answer "which object is this PIXEL", which is a screen-space question, and
+     * a track answers "what is this parameter NOW". Nothing here needs MRT.
+     *
+     * Null or empty clears the track and leaves the parameter wherever it was —
+     * removing an animation is not the same as resetting a value, and guessing
+     * which the caller meant would be worse than either.
+     */
+    setStyleParamTrack(modelName: string, groupId: string, paramId: string, keys: ParamKey[] | null): boolean;
+    /** Forget what a group's tracks last wrote, so the next frame writes it again.
+     *  Called whenever something else has written that uniform underneath them. */
+    private invalidateParamTracks;
+    /** Every track, at the current scene clock. Called once per frame, before the
+     *  pass that reads the uniforms it writes. */
+    private evaluateParamTracks;
     setStyleParam(modelName: string, groupId: string, paramId: string, value: number | [number, number, number]): boolean;
     private currentClaims;
     private compileAndInstallGroup;
@@ -980,6 +1857,14 @@ export declare class Engine {
      * right after the material itself, like MMD's per-mesh outline stage.
      */
     private setModelDrawState;
+    /**
+     * Which eye the scene is being drawn FOR — the main camera or the floor
+     * mirror. Threaded explicitly through the phase draws rather than read off
+     * the engine, because both sets of bundles are recorded in one call and
+     * ambient state at record time is how a mirror bundle ends up baked with the
+     * main camera's bind group.
+     */
+    private sceneView;
     private renderModelOpaquePhase;
     private renderModelTransparentPhase;
     /** Depth-only re-draw of transparent-bucket materials (see depth-prepass.ts).
@@ -1019,6 +1904,16 @@ export declare class Engine {
      * export record the same path at the same spacing. A frame that covers several
      * intervals emits several samples rather than one, or a fast hand would tear.
      */
+    /**
+     * Forget every recorded path, because the slots have been re-dealt.
+     *
+     * Called on every effect swap. The rings are keyed by (model, slot) and a slot
+     * is an ADDRESS, so re-allocating the table can leave a left wrist's recorded
+     * history sitting at the address a right wrist now occupies — a ribbon drawn
+     * confidently along a path that belongs to another bone. Refilling from live
+     * samples costs about two seconds of trail and cannot be wrong.
+     */
+    private clearTrailHistory;
     private writeTrail;
     private updateSkinMatrices;
     private updateStats;