reze-engine 0.54.15 → 0.55.0

package/dist/engine.js

@@ -32,6 +32,9 @@ import { outlineShaderWgsl, RZ_OUTLINE_DISSOLVE_OFFSET } from "./shaders/passes/
 import { transparentDepthPrepassWgsl } from "./shaders/passes/depth-prepass";
 import { SELECTION_MASK_SHADER_WGSL, SELECTION_EDGE_SHADER_WGSL } from "./shaders/passes/selection";
 import { GIZMO_SHADER_WGSL } from "./shaders/passes/gizmo";
+import { OVERLAY_SHADER_WGSL, OVERLAY_COMPOSITE_SHADER_WGSL } from "./shaders/passes/overlay";
+import { WIREFRAME_SHADER_WGSL } from "./shaders/passes/wireframe";
+import { boneOverlay, boneMarkerPositions, buildOverlayShapes, jointOverlay, rigidbodyOverlay, writeOverlayInstance, OVERLAY_INSTANCE_FLOATS, OVERLAY_VERTEX_FLOATS, OVERLAY_SHAPES, OVERLAY_SOLID_SHAPES, DEFAULT_VERTEX_COLOR, OVERLAY_STYLE, } from "./overlay";
 import { BLOOM_BLIT_SHADER_WGSL, BLOOM_DOWNSAMPLE_SHADER_WGSL, BLOOM_UPSAMPLE_SHADER_WGSL, } from "./shaders/passes/bloom";
 import { AGX_LUT_GZ, AGX_LUT_SIZE } from "./shaders/agx-lut";
 import { buildCompositeShader, EFFECT_SCENE_API, buildFieldShader, EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLES, } from "./shaders/passes/composite";
@@ -673,8 +676,37 @@ export class Engine {
         this.resizeObserver = null;
         this.resizePending = false;
         this.selectedMaterial = null;
+        this.overlayInstanceBuffer = null;
+        this.overlayInstanceCapacity = 0;
+        this.overlayDepthTexture = null;
+        this.overlayMsaaTexture = null;
+        this.overlayResolveTexture = null;
+        this.overlayUniformData = new Float32Array(4);
+        this.overlayCompositeBindGroup = null;
+        this.overlayTargetSize = [0, 0];
+        this.overlayLayers = new Map();
+        this.overlayBones = null;
+        this.overlayBodies = null;
+        this.overlayJoints = null;
+        this.overlayVertices = null;
+        this.wireframeColorData = new Float32Array(8);
+        /** Rebuilt every frame into these, grouped by shape so each shape is one draw. */
+        this.overlayByShape = new Map();
+        this.overlayScratch = [];
+        this.bonePickScratch = new Float32Array(0);
+        this.overlayInstanceData = new Float32Array(0);
         // ─── Transform gizmo ───────────────────────────────────────────────
         this.selectedBone = null;
+        /** The material a pointer is currently over, or null. Cheap and separate from
+         *  setVertexOverlay on purpose — the same split setSelectedBone takes from
+         *  setBoneOverlay — because this is written every frame the pointer moves and
+         *  the overlay's own option object is not something to reconstruct that often. */
+        this.hoverMaterial = null;
+        /** The transform gizmo follows setSelectedBone, which is also what selects a
+         *  bone to INSPECT. A model editor selects bones constantly and poses them
+         *  rarely, so the two need separating: off leaves selection working and takes
+         *  the handles away. */
+        this.gizmoEnabled = true;
         this.gizmoColorBindGroups = [];
         // Drag state — set on mousedown if the pointer is over a gizmo handle; cleared
         // on mouseup. While non-null, the camera is locked and mousemove/up are routed
@@ -1037,6 +1069,9 @@ export class Engine {
          *  Set by the cascade loop, which skips a cascade that is unwanted and already
          *  cleared rather than re-clearing it every frame. */
         this.shadowCascadeCleared = [];
+        /** Skinned positions for picking, grown on demand. One click's worth of work
+         *  reused across clicks — a model's vertex count does not change. */
+        this.materialPickScratch = null;
         // CPU frame-time breakdown (EMA-smoothed into getStats): where a frame's
         // milliseconds actually go — animation/IK/blending vs physics vs everything
         // else on the render thread. The first question of any perf report.
@@ -1098,8 +1133,9 @@ export class Engine {
                 this.lastTouchTime = currentTime;
             }
         };
+        this.boneOptionsScratch = {};
         this.handleGizmoMouseDown = (e) => {
-            if (!this.selectedBone || !this.camera || !this.device || e.button !== 0)
+            if (!this.gizmoEnabled || !this.selectedBone || !this.camera || !this.device || e.button !== 0)
                 return;
             const inst = this.modelInstances.get(this.selectedBone.modelName);
             if (!inst)
@@ -2060,10 +2096,11 @@ export class Engine {
      * change that only ever toggles between two known states.
      */
     rebuildFieldBindGroup() {
-        if (!this.device || !this.depthReadView || this.fieldUniformBuffers.length === 0)
+        if (!this.device || !this.depthReadView || !this.compositeBloomView || this.fieldUniformBuffers.length === 0)
             return;
-        // Captured, so the null guard above survives into the closure.
+        // Captured, so the null guards above survive into the closure.
         const depth = this.depthReadView;
+        const bloom = this.compositeBloomView;
         const build = (owner, grid) => this.device.createBindGroup({
             label: "field layer bind group",
             layout: this.fieldBindGroupLayout,
@@ -2084,6 +2121,13 @@ export class Engine {
                 { binding: 17, resource: grid },
                 { binding: 18, resource: this.simSampler },
                 { binding: 26, resource: this.castDistView ?? this.castDistFallbackView },
+                { binding: 27, resource: this.hdrResolveTexture.createView() },
+                { binding: 28, resource: this.simSampler },
+                { binding: 2, resource: this.bloomSampler },
+                { binding: 5, resource: this.filmicLutView },
+                { binding: 10, resource: (this.agxLutTexture ?? this.agxFallbackTexture).createView({ dimension: "3d" }) },
+                { binding: 1, resource: bloom },
+                { binding: 4, resource: this.maskResolveView },
             ],
         });
         // Per effect: the params buffer and the grid are both its own, so two
@@ -3859,6 +3903,14 @@ export class Engine {
         const proj = this.camera.getProjectionMatrix().values;
         u[8] = proj[10];
         u[9] = proj[14];
+        // THE FAR PLANE ITSELF, written rather than left to be re-derived. An effect
+        // that resamples has to know whether the scene was drawn at a given pixel,
+        // and "nothing was drawn" reads back as exactly this distance. Recovering it
+        // from the pair above means inverting a cleared depth, which is a sign trap
+        // that differs by projection convention and fails silently — as an effect
+        // that draws nothing at all, or one that paints the sky. The camera knows
+        // the number; this hands it over.
+        u[10] = this.camera.far;
         this.device.queue.writeBuffer(this.dofUniformBuffer, 0, u);
     }
     setBloomOptions(patch) {
@@ -4020,13 +4072,6 @@ export class Engine {
         this.createPipelines();
         this.setupResize();
         Engine.instance = this;
-        // One line, at init, naming the three answers that differ between two
-        // browsers on the same machine. Not a debug flag and not a readout — it is
-        // the identity of the renderer that was actually built, and on a device that
-        // cannot be attached to a debugger it is the only way to know which of the
-        // three paths is running. Every graphics application prints this.
-        const r = this.gpuReport();
-        console.info(`[reze] hdr=${r.hdrFormat} depth=${r.depthFormat} reversedZ=${r.reversedZ} ids=${r.ids} msaa=${r.sampleCount}`);
     }
     /**
      * Bake the ground's frost noise once — the same fbm the shader used to run
@@ -4362,6 +4407,23 @@ export class Engine {
                 // compiled, and a 1x1 stands in when the flood is not running, so an
                 // author never has to guard the name.
                 { binding: 26, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "2d" } },
+                // The finished scene, and a sampler of its own — see scene-tap.ts for
+                // why it may not borrow the one at 18.
+                { binding: 27, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+                { binding: 28, visibility: GPUShaderStage.FRAGMENT, sampler: {} },
+                // THE VIEW TRANSFORM'S OWN RESOURCES. viewTransform() lives in the
+                // header both this module and the composite share, but its lookups did
+                // not: an effect calling it compiled and then failed at pipeline
+                // creation with "binding doesn't exist", naming a binding no effect
+                // author ever wrote. Sharing the code meant sharing these.
+                { binding: 2, visibility: GPUShaderStage.FRAGMENT, sampler: {} },
+                { binding: 5, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+                { binding: 10, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float", viewDimension: "3d" } },
+                // And the scene's COVERAGE and bloom, without which the tap cannot
+                // reconstruct a pixel: the HDR target is premultiplied, so colour alone
+                // reads a half-transparent ground as a dark opaque one.
+                { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+                { binding: 4, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
             ],
         });
         this.fieldPipelineLayout = this.device.createPipelineLayout({
@@ -4979,6 +5041,8 @@ export class Engine {
         this.device.queue.writeBuffer(this.selectionEdgeUniformBuffer, 0, new Float32Array([5.0, 0, 0, 0]));
         // ─── Transform gizmo (3 axes + 3 rings) ─────────────────────────
         this.setupGizmo();
+        // ─── Editor overlays (instanced wireframe primitives) ────────────
+        this.setupOverlay();
         // ─── Bloom (EEVEE 3.6 pyramid): blit(Karis prefilter) → 13-tap downsamples → 9-tap tent upsamples ───
         // Mirrors source/blender/draw/engines/eevee/shaders/effect_bloom_frag.glsl.
         // Firefly suppression lives in the blit (Karis luminance-weighted 4-tap average). A single-pass
@@ -5884,6 +5948,322 @@ export class Engine {
             ],
         };
     }
+    // Builds the overlay pipeline and the one vertex buffer holding every unit
+    // wireframe. The instance buffer is grown on demand in renderOverlayPass — a
+    // scene with no overlays on never allocates one.
+    setupOverlay() {
+        this.overlayGeometry = buildOverlayShapes();
+        const verts = this.overlayGeometry.vertices;
+        this.overlayVertexBuffer = this.device.createBuffer({
+            label: "overlay vertex buffer",
+            size: verts.byteLength,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        this.device.queue.writeBuffer(this.overlayVertexBuffer, 0, verts);
+        this.overlayUniformBuffer = this.device.createBuffer({
+            label: "overlay uniforms",
+            size: 16, // vec2 viewport + dash period + pad
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        const bgLayout = this.device.createBindGroupLayout({
+            label: "overlay group 0 layout (camera + overlay)",
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } },
+                { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } },
+            ],
+        });
+        const shader = this.device.createShaderModule({ label: "overlay shader", code: OVERLAY_SHADER_WGSL });
+        const overlayPipelineDescriptor = {
+            label: "overlay pipeline",
+            layout: this.device.createPipelineLayout({
+                label: "overlay pipeline layout",
+                bindGroupLayouts: [bgLayout],
+            }),
+            vertex: {
+                module: shader,
+                entryPoint: "vs",
+                buffers: [
+                    {
+                        arrayStride: OVERLAY_VERTEX_FLOATS * 4,
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: "float32x3" }, // pos
+                            { shaderLocation: 1, offset: 3 * 4, format: "float32x3" }, // dir
+                            { shaderLocation: 2, offset: 6 * 4, format: "float32x2" }, // caps
+                            { shaderLocation: 3, offset: 8 * 4, format: "float32" }, // side
+                            { shaderLocation: 4, offset: 9 * 4, format: "float32" }, // t
+                            { shaderLocation: 5, offset: 10 * 4, format: "float32" }, // mode
+                        ],
+                    },
+                    {
+                        arrayStride: OVERLAY_INSTANCE_FLOATS * 4,
+                        stepMode: "instance",
+                        attributes: [
+                            { shaderLocation: 6, offset: 0, format: "float32x4" }, // rotation
+                            { shaderLocation: 7, offset: 4 * 4, format: "float32x4" }, // position + extent
+                            { shaderLocation: 8, offset: 8 * 4, format: "float32x4" }, // scale + thickness
+                            { shaderLocation: 9, offset: 12 * 4, format: "float32x4" }, // color
+                        ],
+                    },
+                ],
+            },
+            fragment: {
+                module: shader,
+                entryPoint: "fs",
+                targets: [
+                    {
+                        format: this.presentationFormat,
+                        // Premultiplied: the FS already scaled rgb by alpha. See the shader.
+                        blend: {
+                            color: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+                            alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+                        },
+                    },
+                ],
+            },
+            primitive: { topology: "triangle-list", cullMode: "none" },
+            // The rig ignores depth entirely. It shares this pass's buffer with the
+            // wireframe's mesh prepass, and that prepass exists to hide the far side
+            // of the BODY — not to hide the skeleton inside it. An editor wants the
+            // rig in front of the mesh, which is what "always" says. The cost is that
+            // the rig no longer sorts against itself; for line work a few pixels wide,
+            // draw order reads the same.
+            depthStencil: {
+                format: "depth24plus",
+                depthWriteEnabled: false,
+                depthCompare: "always",
+            },
+            multisample: { count: Engine.OVERLAY_SAMPLE_COUNT },
+        };
+        this.overlayPipeline = this.device.createRenderPipeline(overlayPipelineDescriptor);
+        // The solid volumes: the same shader and layout, with no depth write and no
+        // culling. A translucent body must not hide the rig behind it, and you have
+        // to see its far wall for it to read as a volume rather than a silhouette.
+        this.overlaySolidPipeline = this.device.createRenderPipeline({
+            ...overlayPipelineDescriptor,
+            label: "overlay solid pipeline",
+            primitive: { topology: "triangle-list", cullMode: "none" },
+            depthStencil: { format: "depth24plus", depthWriteEnabled: false, depthCompare: "always" },
+        });
+        const compositeShader = this.device.createShaderModule({
+            label: "overlay composite shader",
+            code: OVERLAY_COMPOSITE_SHADER_WGSL,
+        });
+        this.overlayCompositeLayout = this.device.createBindGroupLayout({
+            label: "overlay composite layout",
+            entries: [{ binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } }],
+        });
+        this.overlayCompositePipeline = this.device.createRenderPipeline({
+            label: "overlay composite pipeline",
+            layout: this.device.createPipelineLayout({
+                label: "overlay composite pipeline layout",
+                bindGroupLayouts: [this.overlayCompositeLayout],
+            }),
+            vertex: { module: compositeShader, entryPoint: "vs" },
+            fragment: {
+                module: compositeShader,
+                entryPoint: "fs",
+                targets: [
+                    {
+                        format: this.presentationFormat,
+                        blend: {
+                            color: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+                            alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+                        },
+                    },
+                ],
+            },
+            primitive: { topology: "triangle-list" },
+            multisample: { count: 1 },
+        });
+        this.overlayCompositePassDescriptor = {
+            label: "overlay composite pass",
+            colorAttachments: [
+                { view: undefined, loadOp: "load", storeOp: "store" },
+            ],
+        };
+        this.overlayBindGroup = this.device.createBindGroup({
+            label: "overlay bind group",
+            layout: bgLayout,
+            entries: [
+                { binding: 0, resource: { buffer: this.cameraUniformBuffer } },
+                { binding: 1, resource: { buffer: this.overlayUniformBuffer } },
+            ],
+        });
+        // The mesh wireframe: the same line-list target, its own pipeline, because it
+        // draws the model's OWN vertex buffer through the model's OWN skin matrices.
+        // That is the whole reason it exists rather than emitting lines from the
+        // loader's positions — those are bind pose, and a wireframe built from them
+        // sits perfectly on a T-posed model and slides off every animated one.
+        this.wireframeUniformBuffer = this.device.createBuffer({
+            label: "wireframe color",
+            size: 32, // vec4 colour + vec2 viewport + thickness + pad
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.wireframeSeamUniformBuffer = this.device.createBuffer({
+            label: "wireframe color (material borders)",
+            size: 32,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.wireframeHoverUniformBuffer = this.device.createBuffer({
+            label: "wireframe color (hovered material)",
+            size: 32,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        const wireBg0 = this.device.createBindGroupLayout({
+            label: "wireframe group 0 layout (camera + wire)",
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } },
+                // Both stages: the FS takes the colour, the VS takes the viewport and
+                // the stroke width it extrudes each edge quad to.
+                {
+                    binding: 1,
+                    visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+                    buffer: { type: "uniform" },
+                },
+            ],
+        });
+        // Spelled out rather than mapped over a range: tests/bindings.test.mjs reads
+        // these statically to check every bind group covers its layout, and a loop
+        // hides the bindings from it.
+        this.wireframeSkinLayout = this.device.createBindGroupLayout({
+            label: "wireframe group 1 layout (mesh + skin)",
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+                { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+                { binding: 2, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+                { binding: 3, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+                { binding: 4, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
+            ],
+        });
+        const wireShader = this.device.createShaderModule({ label: "wireframe shader", code: WIREFRAME_SHADER_WGSL });
+        this.wireframePipeline = this.device.createRenderPipeline({
+            label: "wireframe pipeline",
+            layout: this.device.createPipelineLayout({
+                label: "wireframe pipeline layout",
+                bindGroupLayouts: [wireBg0, this.wireframeSkinLayout],
+            }),
+            // No vertex stream: an edge quad's corners come from two different model
+            // vertices, so the mesh is read through storage instead.
+            vertex: { module: wireShader, entryPoint: "vs" },
+            fragment: {
+                module: wireShader,
+                entryPoint: "fs",
+                targets: [
+                    {
+                        format: this.presentationFormat,
+                        blend: {
+                            color: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+                            alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+                        },
+                    },
+                ],
+            },
+            primitive: { topology: "triangle-list", cullMode: "none" },
+            // Depth-TESTED but not written: the mesh is a haze the rig reads against,
+            // so a bone behind a triangle must not be punched out by it.
+            depthStencil: { format: "depth24plus", depthWriteEnabled: false, depthCompare: this.depthAhead },
+            multisample: { count: Engine.OVERLAY_SAMPLE_COUNT },
+        });
+        // The mesh's own depth, so the wireframe can be occluded by the body it
+        // belongs to. Occluded is the default everywhere — Blender's edit mode, Maya,
+        // three's and Babylon's wireframe materials all depth-test, and X-ray is a
+        // toggle beside them. Seeing both walls of a 30k-triangle body at once is
+        // moire, not information.
+        //
+        // It writes depth and nothing else — but it still DECLARES the colour
+        // target, at writeMask 0. A pipeline's attachment state has to match its
+        // pass's, and a pass with a colour attachment will not take a pipeline that
+        // has none. Same trick the scene's own depth prepass uses.
+        //
+        // Its own pass rather than the scene's, because the scene's depth is
+        // multisampled and discarded before the composite.
+        this.wireframeDepthPipeline = this.device.createRenderPipeline({
+            label: "wireframe depth prepass pipeline",
+            layout: this.device.createPipelineLayout({
+                label: "wireframe depth prepass layout",
+                bindGroupLayouts: [wireBg0, this.wireframeSkinLayout],
+            }),
+            vertex: {
+                module: wireShader,
+                entryPoint: "vsDepth",
+                buffers: [
+                    { arrayStride: 8 * 4, attributes: [{ shaderLocation: 0, offset: 0, format: "float32x3" }] },
+                    { arrayStride: 4 * 2, attributes: [{ shaderLocation: 1, offset: 0, format: "uint16x4" }] },
+                    { arrayStride: 4, attributes: [{ shaderLocation: 2, offset: 0, format: "unorm8x4" }] },
+                ],
+            },
+            fragment: {
+                module: wireShader,
+                entryPoint: "fs",
+                targets: [{ format: this.presentationFormat, writeMask: 0 }],
+            },
+            primitive: { topology: "triangle-list", cullMode: "none" },
+            depthStencil: {
+                format: "depth24plus",
+                depthWriteEnabled: true,
+                depthCompare: this.depthAhead,
+                // The wireframe lies exactly ON the surface this writes, so every edge
+                // ties with its own triangles and loses wherever rounding goes the wrong
+                // way — lines that break up and shift as the camera turns. Push the
+                // solid mesh back so the edges win their own ties. The slope term is
+                // what handles a surface seen at a grazing angle, where a pixel spans
+                // far more depth than a constant bias can cover.
+                //
+                // SIGNED BY CONVENTION, as the outline hulls are: bias adds to the depth
+                // VALUE, and reversed-Z inverts what a larger value means.
+                depthBias: this.reversedZ ? -64 : 64,
+                depthBiasSlopeScale: this.reversedZ ? -2 : 2,
+                depthBiasClamp: 0,
+            },
+            multisample: { count: Engine.OVERLAY_SAMPLE_COUNT },
+        });
+        this.wireframeBindGroup = this.device.createBindGroup({
+            label: "wireframe bind group",
+            layout: wireBg0,
+            entries: [
+                { binding: 0, resource: { buffer: this.cameraUniformBuffer } },
+                { binding: 1, resource: { buffer: this.wireframeUniformBuffer } },
+            ],
+        });
+        this.wireframeSeamBindGroup = this.device.createBindGroup({
+            label: "wireframe bind group (material borders)",
+            layout: wireBg0,
+            entries: [
+                { binding: 0, resource: { buffer: this.cameraUniformBuffer } },
+                { binding: 1, resource: { buffer: this.wireframeSeamUniformBuffer } },
+            ],
+        });
+        this.wireframeHoverBindGroup = this.device.createBindGroup({
+            label: "wireframe bind group (hovered material)",
+            layout: wireBg0,
+            entries: [
+                { binding: 0, resource: { buffer: this.cameraUniformBuffer } },
+                { binding: 1, resource: { buffer: this.wireframeHoverUniformBuffer } },
+            ],
+        });
+        this.overlayPassDescriptor = {
+            label: "overlay pass",
+            timestampWrites: this.stamps("overlay"),
+            colorAttachments: [
+                {
+                    view: undefined,
+                    resolveTarget: undefined,
+                    // Transparent, because this layer is composited over the frame rather
+                    // than drawn into it. storeOp discard keeps the 4 samples in tile
+                    // memory on a TBDR part — only the resolve reaches RAM.
+                    clearValue: { r: 0, g: 0, b: 0, a: 0 },
+                    loadOp: "clear",
+                    storeOp: "discard",
+                },
+            ],
+            depthStencilAttachment: {
+                view: undefined,
+                depthClearValue: this.depthClear,
+                depthLoadOp: "clear",
+                depthStoreOp: "discard",
+            },
+        };
+    }
     // Step 4: Create camera and uniform buffer
     setupCamera() {
         this.cameraUniformBuffer = this.device.createBuffer({
@@ -6028,6 +6408,20 @@ export class Engine {
      * analysis would render silence into the exported video.
      */
     setAudioData(data, bandsPerFrame, secondsPerFrame) {
+        // NOT YET, OR NEVER AGAIN. `device` is definite-assignment: it is undefined
+        // until init() resolves and after dispose(), and TypeScript cannot see
+        // either state. This setter is reached from an ASYNC callback — the audio
+        // analysis, the score fetch, the lyric rasteriser all land whenever they
+        // land — so on a hot reload the in-flight promise of the outgoing engine
+        // resolves against the incoming one, which is holding a ref but has not
+        // finished init. It threw "Cannot read properties of undefined (reading
+        // 'createBuffer')" from a line whose only crime was being fast.
+        //
+        // Dropped rather than queued: every caller here re-pushes on the effect
+        // that owns the asset, and that effect re-runs on the very reload that
+        // caused this.
+        if (!this.device)
+            return;
         if (this.audioBuffer !== this.audioFallbackBuffer)
             this.audioBuffer.destroy();
         if (!data || data.length === 0) {
@@ -6074,6 +6468,20 @@ export class Engine {
      * atlas are both fixed-size, so nothing re-binds whenever lyrics arrive.
      */
     setLyrics(lines, atlas) {
+        // NOT YET, OR NEVER AGAIN. `device` is definite-assignment: it is undefined
+        // until init() resolves and after dispose(), and TypeScript cannot see
+        // either state. This setter is reached from an ASYNC callback — the audio
+        // analysis, the score fetch, the lyric rasteriser all land whenever they
+        // land — so on a hot reload the in-flight promise of the outgoing engine
+        // resolves against the incoming one, which is holding a ref but has not
+        // finished init. It threw "Cannot read properties of undefined (reading
+        // 'createBuffer')" from a line whose only crime was being fast.
+        //
+        // Dropped rather than queued: every caller here re-pushes on the effect
+        // that owns the asset, and that effect re-runs on the very reload that
+        // caused this.
+        if (!this.device)
+            return;
         this.device.queue.writeBuffer(this.lyricsBuffer, 0, packLyrics(lines ?? [], atlas?.rects));
         if (!atlas)
             return;
@@ -6101,6 +6509,20 @@ export class Engine {
         this.device.queue.copyExternalImageToTexture({ source: atlas.source }, { texture: this.lyricsTexture, premultipliedAlpha: true }, [w, h]);
     }
     setMidiNotes(notes, release = 0.35) {
+        // NOT YET, OR NEVER AGAIN. `device` is definite-assignment: it is undefined
+        // until init() resolves and after dispose(), and TypeScript cannot see
+        // either state. This setter is reached from an ASYNC callback — the audio
+        // analysis, the score fetch, the lyric rasteriser all land whenever they
+        // land — so on a hot reload the in-flight promise of the outgoing engine
+        // resolves against the incoming one, which is holding a ref but has not
+        // finished init. It threw "Cannot read properties of undefined (reading
+        // 'createBuffer')" from a line whose only crime was being fast.
+        //
+        // Dropped rather than queued: every caller here re-pushes on the effect
+        // that owns the asset, and that effect re-runs on the very reload that
+        // caused this.
+        if (!this.device)
+            return;
         if (this.midiBuffer !== this.midiFallbackBuffer)
             this.midiBuffer.destroy();
         this.midiRelease = Math.max(0, release);
@@ -6377,6 +6799,14 @@ export class Engine {
         return this.sun;
     }
     addGround(options) {
+        // NOT YET, OR NEVER AGAIN — same race setAudioData documents. This call is
+        // deferred a frame by useSceneSync's own rAF batching, and a hot reload
+        // that swaps in a new (uninitialized) engine between the schedule and the
+        // callback lands this on a `device` that has not been assigned yet. The
+        // effect that scheduled it re-fires once the new engine is ready, so
+        // dropping this one loses nothing.
+        if (!this.device)
+            return;
         const opts = {
             width: 160,
             height: 160,
@@ -6467,7 +6897,15 @@ export class Engine {
     getLightCount() {
         return this.lightHeader[0];
     }
+    /** Guarded, unlike most private writers here, because its callers are not:
+     *  setWorld/setSun are public and can be called before init() finishes
+     *  assigning `device` — a scene-settings effect firing on mount races the
+     *  engine's own async setup. The state write still lands immediately either
+     *  way; only the GPU upload defers, and setupLighting's own writeWorld/
+     *  writeSun calls during init pick up whatever was already set. */
     updateLightBuffer() {
+        if (!this.device || !this.lightUniformBuffer)
+            return;
         this.device.queue.writeBuffer(this.lightUniformBuffer, 0, this.lightData);
     }
     getStats() {
@@ -6511,6 +6949,19 @@ export class Engine {
             this.canvas.removeEventListener("dblclick", this.handleCanvasDoubleClick);
             this.canvas.removeEventListener("touchend", this.handleCanvasTouch);
         }
+        this.overlayDepthTexture?.destroy();
+        this.overlayDepthTexture = null;
+        this.overlayMsaaTexture?.destroy();
+        this.overlayMsaaTexture = null;
+        this.overlayResolveTexture?.destroy();
+        this.overlayResolveTexture = null;
+        this.overlayInstanceBuffer?.destroy();
+        this.overlayInstanceBuffer = null;
+        for (const inst of this.modelInstances.values()) {
+            for (const edges of inst.wireEdges.values())
+                edges?.buffer.destroy();
+            inst.wireEdges.clear();
+        }
         // Remove gizmo drag listeners
         this.canvas.removeEventListener("mousedown", this.handleGizmoMouseDown, { capture: true });
         window.removeEventListener("mousemove", this.handleGizmoMouseMove);
@@ -6906,6 +7357,16 @@ export class Engine {
     setSelectedMaterial(modelName, materialName) {
         this.selectedMaterial = modelName && materialName ? { modelName, materialName } : null;
     }
+    /** Show the transform gizmo on the selected bone. On by default. */
+    setGizmoEnabled(on) {
+        this.gizmoEnabled = on;
+    }
+    /** A pointer-driven preview of a pick, not a pick itself — see pickMaterial
+     *  for the click that actually selects one. Cheap: a field write, nothing
+     *  rebuilt, safe to call every frame the pointer is over the canvas. */
+    setHoveredMaterial(modelName, materialName) {
+        this.hoverMaterial = modelName && materialName ? { modelName, materialName } : null;
+    }
     setSelectedBone(modelName, boneName) {
         if (!modelName || !boneName) {
             this.selectedBone = null;
@@ -6919,6 +7380,235 @@ export class Engine {
         const boneIndex = inst.model.getSkeleton().bones.findIndex((b) => b.name === boneName);
         this.selectedBone = boneIndex >= 0 ? { modelName, boneName, boneIndex } : null;
     }
+    // ─── Editor overlays ───────────────────────────────────────────────
+    //
+    // Two ways in. setOverlay takes a list and draws exactly that list, so a host
+    // can paste one in, hand one to a test, or print one back out. The three live
+    // layers name a model instead and are rebuilt from its pose every frame,
+    // which is the only way a skeleton overlay can be right on an animated model.
+    /**
+     * Replace one named layer of overlay primitives. World space, drawn as given
+     * until it is replaced. An empty list removes the layer.
+     */
+    setOverlay(layer, primitives) {
+        if (primitives.length === 0)
+            this.overlayLayers.delete(layer);
+        else
+            this.overlayLayers.set(layer, primitives);
+    }
+    /** Drop one named layer, or every one. Live layers keep drawing. */
+    clearOverlay(layer) {
+        if (layer === undefined)
+            this.overlayLayers.clear();
+        else
+            this.overlayLayers.delete(layer);
+    }
+    /**
+     * The bone whose marker is nearest a point on the canvas, or null.
+     *
+     * On the CPU, and exact. A few hundred bones with known world positions is a
+     * loop, not a render pass — and having the answer synchronously is what makes
+     * cycling through overlapping bones possible at all. Only VERTICES justify GPU
+     * picking, at tens of thousands.
+     *
+     * `x`/`y` are CSS pixels relative to the canvas, which is what a MouseEvent
+     * gives once getBoundingClientRect is subtracted.
+     *
+     * It projects boneMarkerPositions, the same points the overlay draws markers
+     * at, so the hit box cannot drift away from the circle you are aiming at.
+     */
+    pickBone(x, y, options = {}) {
+        if (!this.camera)
+            return null;
+        const width = this.canvas.clientWidth;
+        const height = this.canvas.clientHeight;
+        if (width <= 0 || height <= 0)
+            return null;
+        const vp = this.camera.getProjectionMatrix().multiply(this.camera.getViewMatrix()).values;
+        let best = null;
+        let bestDist = options.radiusPx ?? 14;
+        let bestDepth = Infinity;
+        for (const inst of this.modelInstances.values()) {
+            if (options.modelName !== undefined && inst.name !== options.modelName)
+                continue;
+            if (inst.isStage || inst.isPlane)
+                continue;
+            const bones = inst.model.getSkeleton().bones;
+            this.bonePickScratch = boneMarkerPositions(inst.model, this.bonePickScratch);
+            const pos = this.bonePickScratch;
+            for (let i = 0; i < bones.length; i++) {
+                const px = pos[i * 3];
+                const py = pos[i * 3 + 1];
+                const pz = pos[i * 3 + 2];
+                const cw = vp[3] * px + vp[7] * py + vp[11] * pz + vp[15];
+                if (cw <= 1e-6)
+                    continue; // behind the camera
+                const cx = vp[0] * px + vp[4] * py + vp[8] * pz + vp[12];
+                const cy = vp[1] * px + vp[5] * py + vp[9] * pz + vp[13];
+                const sx = ((cx / cw) * 0.5 + 0.5) * width;
+                const sy = (1 - ((cy / cw) * 0.5 + 0.5)) * height;
+                const d = Math.hypot(sx - x, sy - y);
+                if (d > bestDist)
+                    continue;
+                // Within a couple of pixels the two are the same click, and MMD stacks
+                // control bones on one point — so the nearer bone takes it.
+                if (d < bestDist - 2 || cw < bestDepth) {
+                    best = { modelName: inst.name, boneName: bones[i].name, boneIndex: i };
+                    bestDist = d;
+                    bestDepth = cw;
+                }
+            }
+        }
+        return best;
+    }
+    /**
+     * The material under a point on the canvas, or null for a miss.
+     *
+     * On the CPU, like pickBone, and for the same reason: a click (or a hover) is
+     * rare and an answer you have synchronously is worth more than one that
+     * arrives a frame later. Tens of thousands of triangles is a loop that costs
+     * a few milliseconds ONCE, against a GPU id pass that costs an attachment and
+     * a readback every frame whether anyone is pointing at the model or not.
+     *
+     * Skinned on the CPU with getSkinMatrices — the same matrices the vertex
+     * shader uses — so the pick lands on the POSED mesh. Bind-pose geometry would
+     * be right on a T-posed model and wrong on every animated one, which is
+     * exactly when someone is clicking around a costume.
+     *
+     * Morph offsets are NOT applied: they move a face, never move it into another
+     * material, and reading them back per click would cost more than the pick.
+     *
+     * `x`/`y` are CSS pixels relative to the canvas, as pickBone takes them.
+     */
+    pickMaterial(x, y, options = {}) {
+        if (!this.camera)
+            return null;
+        const width = this.canvas.clientWidth;
+        const height = this.canvas.clientHeight;
+        if (width <= 0 || height <= 0)
+            return null;
+        const vp = this.camera.getProjectionMatrix().multiply(this.camera.getViewMatrix()).values;
+        let best = null;
+        let bestDepth = Infinity;
+        for (const inst of this.modelInstances.values()) {
+            if (options.modelName !== undefined && inst.name !== options.modelName)
+                continue;
+            if (inst.isStage || inst.isPlane)
+                continue;
+            const model = inst.model;
+            const { positions } = model.getGeometry();
+            const count = positions.length / 3;
+            const { joints, weights } = model.getSkinning();
+            const skin = model.getSkinMatrices();
+            // Project every vertex ONCE into screen x, y and clip w. The triangle
+            // loop then reads three of these rather than re-skinning shared vertices
+            // — a closed mesh uses each vertex about six times.
+            if (!this.materialPickScratch || this.materialPickScratch.length !== count * 3) {
+                this.materialPickScratch = new Float32Array(count * 3);
+            }
+            const proj = this.materialPickScratch;
+            for (let v = 0; v < count; v++) {
+                const bx = positions[v * 3];
+                const by = positions[v * 3 + 1];
+                const bz = positions[v * 3 + 2];
+                let px = 0;
+                let py = 0;
+                let pz = 0;
+                for (let k = 0; k < 4; k++) {
+                    const w = weights[v * 4 + k] / 255;
+                    if (w === 0)
+                        continue;
+                    const m = joints[v * 4 + k] * 16;
+                    px += w * (skin[m] * bx + skin[m + 4] * by + skin[m + 8] * bz + skin[m + 12]);
+                    py += w * (skin[m + 1] * bx + skin[m + 5] * by + skin[m + 9] * bz + skin[m + 13]);
+                    pz += w * (skin[m + 2] * bx + skin[m + 6] * by + skin[m + 10] * bz + skin[m + 14]);
+                }
+                const cw = vp[3] * px + vp[7] * py + vp[11] * pz + vp[15];
+                proj[v * 3 + 2] = cw;
+                if (cw <= 1e-6)
+                    continue;
+                const cx = vp[0] * px + vp[4] * py + vp[8] * pz + vp[12];
+                const cy = vp[1] * px + vp[5] * py + vp[9] * pz + vp[13];
+                proj[v * 3] = ((cx / cw) * 0.5 + 0.5) * width;
+                proj[v * 3 + 1] = (1 - ((cy / cw) * 0.5 + 0.5)) * height;
+            }
+            // Point-in-triangle in SCREEN space, nearest w wins. The same projection
+            // pickBone uses, so the two agree about where things are, and it needs no
+            // inverse view-projection to build a ray from.
+            const indices = model.getIndices();
+            const materials = model.getMaterials();
+            let m = 0;
+            let matEnd = materials.length > 0 ? materials[0].vertexCount : indices.length;
+            for (let i = 0; i + 2 < indices.length; i += 3) {
+                while (i >= matEnd && m + 1 < materials.length) {
+                    m++;
+                    matEnd += materials[m].vertexCount;
+                }
+                const a = indices[i] * 3;
+                const b = indices[i + 1] * 3;
+                const c = indices[i + 2] * 3;
+                if (proj[a + 2] <= 1e-6 || proj[b + 2] <= 1e-6 || proj[c + 2] <= 1e-6)
+                    continue;
+                const ax = proj[a];
+                const ay = proj[a + 1];
+                const bx = proj[b];
+                const by = proj[b + 1];
+                const cx2 = proj[c];
+                const cy2 = proj[c + 1];
+                // Barycentric sign test, both windings: PMX faces are one winding but a
+                // double-sided material is legitimately seen from behind.
+                const d1 = (x - bx) * (ay - by) - (ax - bx) * (y - by);
+                const d2 = (x - cx2) * (by - cy2) - (bx - cx2) * (y - cy2);
+                const d3 = (x - ax) * (cy2 - ay) - (cx2 - ax) * (y - ay);
+                const neg = d1 < 0 || d2 < 0 || d3 < 0;
+                const pos = d1 > 0 || d2 > 0 || d3 > 0;
+                if (neg && pos)
+                    continue;
+                const depth = (proj[a + 2] + proj[b + 2] + proj[c + 2]) / 3;
+                if (depth >= bestDepth)
+                    continue;
+                bestDepth = depth;
+                best = { modelName: inst.name, materialName: materials[m].name, materialIndex: m };
+            }
+        }
+        return best;
+    }
+    /** Draw an octahedron per bone of `modelName`, rebuilt each frame. Null off. */
+    setBoneOverlay(modelName, options = {}) {
+        this.overlayBones = modelName ? { modelName, options } : null;
+    }
+    /** Draw every rigidbody of `modelName` where the simulation has it, rebuilt
+     *  each frame. Null off. */
+    setRigidbodyOverlay(modelName, options = {}) {
+        this.overlayBodies = modelName ? { modelName, options } : null;
+    }
+    /** Draw a cross per joint of `modelName` plus dashed lines to the bodies it
+     *  holds together, rebuilt each frame. Null off. */
+    setJointOverlay(modelName, options = {}) {
+        this.overlayJoints = modelName ? { modelName, options } : null;
+    }
+    /**
+     * Draw `modelName`'s mesh as a wireframe — its vertices and its topology.
+     *
+     * Skinned on the GPU from the model's own vertex buffer and skin matrices, so
+     * it sits on the POSED mesh. The loader's CPU-side positions are bind pose: a
+     * wireframe built from those looks right on a T-posed model and slides off
+     * every animated one, which is exactly the state a user is in while looking at
+     * weights.
+     *
+     * The edge list is deduplicated and built once, on the first frame this is on.
+     *
+     * `material` narrows the wireframe to one material's faces. The mesh still
+     * writes depth in full, so the material reads as part of the body rather than
+     * as a shell floating in front of it — which is the point of scoping it: you
+     * are asking where this material's faces ARE, and an answer that ignores the
+     * torso in front of them is not one.
+     */
+    setVertexOverlay(modelName, options = {}) {
+        this.overlayVertices = modelName
+            ? { modelName, xray: options.xray ?? false, material: options.material ?? null }
+            : null;
+    }
     // Build a material's bind group with binding(4) pointing at a given StyleUniforms buffer
     // (the group's buffer when grouped, or the shared zero buffer when ungrouped).
     /** A group's uniform buffer and its maps have the same lifetime — freeing one
@@ -7005,8 +7695,26 @@ export class Engine {
     getIKEnabled() {
         return this.ikEnabled;
     }
+    /**
+     * Run the solver, or stop it.
+     *
+     * Turning it OFF snaps every body back onto its bone. Merely halting the step
+     * leaves hair and skirts hanging wherever the simulation happened to be — a
+     * pose nothing in the document describes, which is the opposite of what "off"
+     * is asked for: you switch physics off to see what the RIG does, and a frozen
+     * mid-swing is still the solver's answer, just a stale one.
+     */
     setPhysicsEnabled(enabled) {
+        if (this.physicsEnabled === enabled)
+            return;
         this.physicsEnabled = enabled;
+        if (enabled)
+            return;
+        for (const inst of this.modelInstances.values()) {
+            if (!inst.physics)
+                continue;
+            inst.physics.reset(inst.model.getWorldMatrices());
+        }
     }
     getPhysicsEnabled() {
         return this.physicsEnabled;
@@ -8049,13 +8757,15 @@ export class Engine {
         const jointsBuffer = this.device.createBuffer({
             label: `${name}: joints buffer`,
             size: skinning.joints.byteLength,
-            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+            // STORAGE so the wireframe overlay can skin from it: its quads read two
+            // different model vertices per corner, which no vertex stream can supply.
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST | GPUBufferUsage.STORAGE,
         });
         this.device.queue.writeBuffer(jointsBuffer, 0, skinning.joints.buffer, skinning.joints.byteOffset, skinning.joints.byteLength);
         const weightsBuffer = this.device.createBuffer({
             label: `${name}: weights buffer`,
             size: skinning.weights.byteLength,
-            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST | GPUBufferUsage.STORAGE,
         });
         this.device.queue.writeBuffer(weightsBuffer, 0, skinning.weights.buffer, skinning.weights.byteOffset, skinning.weights.byteLength);
         const skinMatrixBuffer = this.device.createBuffer({
@@ -8142,6 +8852,7 @@ export class Engine {
             jointsBuffer,
             weightsBuffer,
             skinMatrixBuffer,
+            wireEdges: new Map(),
             drawCalls: [],
             shadowDrawCalls: [],
             shadowBindGroups,
@@ -9012,6 +9723,407 @@ export class Engine {
         epass.draw(3);
         epass.end();
     }
+    // Unique edges of the mesh, as a line-list index buffer. Each interior edge is
+    // shared by two triangles, so deduplicating halves both the buffer and the
+    // draw. Built once per model, on the first frame its wireframe is asked for.
+    /** The index run `material` owns, or the whole list when it is null. Materials
+     *  are consecutive runs in declaration order, so the offset is a prefix sum —
+     *  the same walk the draw list does. Returns null for a name the model does
+     *  not have, which is what a stale selection looks like after a reload. */
+    materialIndexRange(inst, material) {
+        const indices = inst.model.getIndices();
+        if (!material)
+            return [0, indices.length];
+        let offset = 0;
+        for (const m of inst.model.getMaterials()) {
+            if (m.name === material)
+                return [offset, offset + m.vertexCount];
+            offset += m.vertexCount;
+        }
+        return null;
+    }
+    /**
+     * @param material one material's own edges, or null for the whole mesh
+     * @param seams    every material's OUTLINE instead — the borders between them
+     */
+    ensureEdgeBuffer(inst, material, seams = false) {
+        const key = material ?? (seams ? Engine.SEAM_KEY : "");
+        if (inst.wireEdges.has(key))
+            return inst.wireEdges.get(key) !== null;
+        const indices = inst.model.getIndices();
+        const vertexCount = inst.model.getGeometry().positions.length / 3;
+        const edges = [];
+        if (seams && !material) {
+            // Inside one material's run an interior edge belongs to two triangles and
+            // a border edge to one, so counting uses within the run and keeping the
+            // singles gives exactly that material's outline.
+            //
+            // Per run, never over the whole mesh: an edge two materials share is
+            // interior to the model and a border to both, and only the per-run count
+            // can tell those two cases apart.
+            const used = new Map();
+            const seen = new Set();
+            let offset = 0;
+            for (const m of inst.model.getMaterials()) {
+                const end = offset + m.vertexCount;
+                used.clear();
+                const bump = (a, b) => {
+                    const k = (a < b ? a : b) * vertexCount + (a < b ? b : a);
+                    used.set(k, (used.get(k) ?? 0) + 1);
+                };
+                for (let i = offset; i + 2 < end; i += 3) {
+                    bump(indices[i], indices[i + 1]);
+                    bump(indices[i + 1], indices[i + 2]);
+                    bump(indices[i + 2], indices[i]);
+                }
+                for (const [k, count] of used) {
+                    if (count !== 1 || seen.has(k))
+                        continue;
+                    seen.add(k);
+                    edges.push(Math.floor(k / vertexCount), k % vertexCount);
+                }
+                offset = end;
+            }
+        }
+        else {
+            const range = this.materialIndexRange(inst, material);
+            if (!range)
+                return false;
+            const [start, end] = range;
+            const seen = new Set();
+            const add = (a, b) => {
+                const lo = a < b ? a : b;
+                const hi = a < b ? b : a;
+                const k = lo * vertexCount + hi;
+                if (seen.has(k))
+                    return;
+                seen.add(k);
+                edges.push(lo, hi);
+            };
+            for (let i = start; i + 2 < end; i += 3) {
+                add(indices[i], indices[i + 1]);
+                add(indices[i + 1], indices[i + 2]);
+                add(indices[i + 2], indices[i]);
+            }
+        }
+        if (edges.length === 0) {
+            inst.wireEdges.set(key, null);
+            return false;
+        }
+        const data = new Uint32Array(edges);
+        const buffer = this.device.createBuffer({
+            label: `wireframe edges ${inst.name}${material ? ` / ${material}` : seams ? " / seams" : ""}`,
+            size: data.byteLength,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        this.device.queue.writeBuffer(buffer, 0, data);
+        const bindGroup = this.device.createBindGroup({
+            label: `wireframe mesh ${inst.name}${material ? ` / ${material}` : seams ? " / seams" : ""}`,
+            layout: this.wireframeSkinLayout,
+            entries: [
+                { binding: 0, resource: { buffer: inst.skinMatrixBuffer } },
+                { binding: 1, resource: { buffer: inst.vertexBuffer } },
+                { binding: 2, resource: { buffer: inst.jointsBuffer } },
+                { binding: 3, resource: { buffer: inst.weightsBuffer } },
+                { binding: 4, resource: { buffer } },
+            ],
+        });
+        inst.wireEdges.set(key, { buffer, count: edges.length, bindGroup });
+        return true;
+    }
+    renderWireframe(pass) {
+        if (!this.overlayVertices)
+            return;
+        const inst = this.overlayModel(this.overlayVertices.modelName);
+        const { material, xray } = this.overlayVertices;
+        if (!inst || !this.ensureEdgeBuffer(inst, material))
+            return;
+        const edges = inst.wireEdges.get(material ?? "");
+        if (!edges)
+            return;
+        // The whole mesh gets its material BORDERS drawn over it — that is what
+        // makes the view read as every material at once rather than as one body of
+        // undifferentiated lines. A single material asked for by name is already
+        // one material, so it needs no borders to separate it from anything.
+        const seams = material === null && this.ensureEdgeBuffer(inst, null, true)
+            ? (inst.wireEdges.get(Engine.SEAM_KEY) ?? null)
+            : null;
+        // A pointer over a material previews EXACTLY what clicking it would pick —
+        // the same self-occluding reveal, layered over the section-wide view rather
+        // than replacing it, so the rest of the mesh stays legible while one
+        // material calls attention to itself. Meaningless once something IS
+        // picked, since only the picked material draws at all then.
+        const hm = this.hoverMaterial;
+        const hoverName = material === null && hm?.modelName === inst.name ? hm.materialName : null;
+        const hoverRange = hoverName ? this.materialIndexRange(inst, hoverName) : null;
+        const hover = hoverRange && this.ensureEdgeBuffer(inst, hoverName) ? inst.wireEdges.get(hoverName) : null;
+        this.wireframeColorData.set(DEFAULT_VERTEX_COLOR);
+        this.wireframeColorData[4] = this.canvas.width;
+        this.wireframeColorData[5] = this.canvas.height;
+        this.wireframeColorData[6] = OVERLAY_STYLE.meshStrokePx;
+        // The triangulation steps back only when there is something drawn over it
+        // to step back FROM.
+        if (seams)
+            this.wireframeColorData[3] = DEFAULT_VERTEX_COLOR[3] * OVERLAY_STYLE.meshAlpha;
+        this.device.queue.writeBuffer(this.wireframeUniformBuffer, 0, this.wireframeColorData);
+        if (seams) {
+            this.wireframeColorData[3] = DEFAULT_VERTEX_COLOR[3];
+            this.wireframeColorData[6] = OVERLAY_STYLE.seamStrokePx;
+            this.device.queue.writeBuffer(this.wireframeSeamUniformBuffer, 0, this.wireframeColorData);
+        }
+        if (hover) {
+            this.wireframeColorData[6] = OVERLAY_STYLE.hoverStrokePx;
+            this.device.queue.writeBuffer(this.wireframeHoverUniformBuffer, 0, this.wireframeColorData);
+        }
+        // Both bind groups, before the FIRST draw call below, regardless of which
+        // branch runs first — the depth prepass reads the camera from group 0 and
+        // the skin matrices from group 1 same as the edge pass does, and every
+        // draw in this function needs both set to SOMETHING before it runs. Each
+        // block below is free to swap either one out for its own draws.
+        pass.setBindGroup(0, this.wireframeBindGroup);
+        pass.setBindGroup(1, edges.bindGroup);
+        const bindMesh = () => {
+            pass.setPipeline(this.wireframeDepthPipeline);
+            pass.setVertexBuffer(0, inst.vertexBuffer);
+            pass.setVertexBuffer(1, inst.jointsBuffer);
+            pass.setVertexBuffer(2, inst.weightsBuffer);
+            pass.setIndexBuffer(inst.indexBuffer, "uint32");
+        };
+        // The hover preview writes and draws against its OWN depth first, while the
+        // shared depth buffer is still empty — the same trick a pick uses, run
+        // before the base mesh below gets a chance to occlude it. The base mesh's
+        // depth write further down repeats the SAME geometry for these faces
+        // (identical z), so it neither disturbs this nor needs to skip them.
+        if (hover && hoverRange && !xray) {
+            bindMesh();
+            pass.drawIndexed(hoverRange[1] - hoverRange[0], 1, hoverRange[0]);
+            pass.setBindGroup(0, this.wireframeHoverBindGroup);
+            pass.setBindGroup(1, hover.bindGroup);
+            pass.setPipeline(this.wireframePipeline);
+            pass.draw(6, hover.count / 2);
+            pass.setBindGroup(0, this.wireframeBindGroup);
+            pass.setBindGroup(1, edges.bindGroup);
+        }
+        // What writes depth is what is allowed to hide the wireframe, and that
+        // differs between the two views.
+        //
+        // The whole mesh, so the far wall of a 30k-triangle body does not draw on
+        // top of the near one — occluded is the default everywhere, Blender's edit
+        // mode and Maya included, and seeing both walls at once is moire rather than
+        // information.
+        //
+        // A PICKED material writes only its OWN faces. The question a pick asks is
+        // where this material is, and half of it is usually under a coat; letting
+        // the coat hide it does not answer that. Its own depth still goes in, so its
+        // back faces stay hidden and it reads as an object instead of a haze —
+        // which is the difference between this and turning x-ray on.
+        const range = material !== null ? this.materialIndexRange(inst, material) : null;
+        if (!xray) {
+            bindMesh();
+            if (range)
+                pass.drawIndexed(range[1] - range[0], 1, range[0]);
+            else
+                pass.drawIndexed(inst.model.getIndices().length);
+        }
+        // Six vertices an edge, instanced.
+        pass.setPipeline(this.wireframePipeline);
+        pass.draw(6, edges.count / 2);
+        if (seams) {
+            pass.setBindGroup(0, this.wireframeSeamBindGroup);
+            pass.setBindGroup(1, seams.bindGroup);
+            pass.draw(6, seams.count / 2);
+        }
+    }
+    /** The bone overlay's options with `selected` filled in from setSelectedBone,
+     *  so clicking a bone highlights it without the host mirroring the state. An
+     *  explicit `selected` in the options still wins. */
+    boneOverlayOptions(modelName) {
+        const options = this.overlayBones?.options ?? {};
+        if (options.selected !== undefined)
+            return options;
+        const chosen = this.selectedBone?.modelName === modelName ? this.selectedBone.boneName : null;
+        this.boneOptionsScratch.selected = chosen;
+        this.boneOptionsScratch.include = options.include;
+        return this.boneOptionsScratch;
+    }
+    overlayActive() {
+        return (this.overlayLayers.size > 0 ||
+            this.overlayBones !== null ||
+            this.overlayBodies !== null ||
+            this.overlayJoints !== null ||
+            this.overlayVertices !== null);
+    }
+    overlayModel(name) {
+        return this.modelInstances.get(name) ?? null;
+    }
+    /** The primitives a live layer would draw right now. Same list the pass uses,
+     *  so a host can show it as data, diff it, or hit-test it on the CPU. */
+    getOverlayPrimitives(layer) {
+        if (layer === "bones") {
+            const inst = this.overlayBones ? this.overlayModel(this.overlayBones.modelName) : null;
+            return inst ? boneOverlay(inst.model, this.boneOverlayOptions(inst.name)) : [];
+        }
+        if (layer === "rigidbodies") {
+            const inst = this.overlayBodies ? this.overlayModel(this.overlayBodies.modelName) : null;
+            return inst ? rigidbodyOverlay(inst.model, inst.physics, this.overlayBodies.options) : [];
+        }
+        const inst = this.overlayJoints ? this.overlayModel(this.overlayJoints.modelName) : null;
+        return inst ? jointOverlay(inst.model, inst.physics, this.overlayJoints.options) : [];
+    }
+    // The overlay's own layer: a 4x multisampled colour target, its resolve, and a
+    // matching depth. All three are allocated the first frame an overlay is
+    // actually on, so a scene that never shows one never pays for any of it.
+    ensureOverlayTargets(width, height) {
+        if (this.overlayResolveTexture && this.overlayTargetSize[0] === width && this.overlayTargetSize[1] === height) {
+            return;
+        }
+        const samples = Engine.OVERLAY_SAMPLE_COUNT;
+        this.overlayDepthTexture?.destroy();
+        this.overlayMsaaTexture?.destroy();
+        this.overlayResolveTexture?.destroy();
+        this.overlayMsaaTexture = this.device.createTexture({
+            label: "overlay msaa",
+            size: [width, height],
+            sampleCount: samples,
+            format: this.presentationFormat,
+            usage: GPUTextureUsage.RENDER_ATTACHMENT,
+        });
+        this.overlayResolveTexture = this.device.createTexture({
+            label: "overlay resolve",
+            size: [width, height],
+            format: this.presentationFormat,
+            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+        });
+        this.overlayDepthTexture = this.device.createTexture({
+            label: "overlay depth",
+            size: [width, height],
+            sampleCount: samples,
+            format: "depth24plus",
+            usage: GPUTextureUsage.RENDER_ATTACHMENT,
+        });
+        this.overlayTargetSize = [width, height];
+        const colorAtt = this.overlayPassDescriptor.colorAttachments[0];
+        colorAtt.view = this.overlayMsaaTexture.createView();
+        colorAtt.resolveTarget = this.overlayResolveTexture.createView();
+        const depthAtt = this.overlayPassDescriptor.depthStencilAttachment;
+        depthAtt.view = this.overlayDepthTexture.createView();
+        this.overlayCompositeBindGroup = this.device.createBindGroup({
+            label: "overlay composite bind group",
+            layout: this.overlayCompositeLayout,
+            entries: [{ binding: 0, resource: this.overlayResolveTexture.createView() }],
+        });
+    }
+    ensureOverlayInstanceCapacity(count) {
+        if (this.overlayInstanceBuffer && this.overlayInstanceCapacity >= count)
+            return;
+        // Grow in powers of two so a skirt gaining bodies one at a time does not
+        // reallocate once per body.
+        let capacity = Math.max(64, this.overlayInstanceCapacity || 64);
+        while (capacity < count)
+            capacity *= 2;
+        this.overlayInstanceBuffer?.destroy();
+        this.overlayInstanceBuffer = this.device.createBuffer({
+            label: "overlay instance buffer",
+            size: capacity * OVERLAY_INSTANCE_FLOATS * 4,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        this.overlayInstanceCapacity = capacity;
+        this.overlayInstanceData = new Float32Array(capacity * OVERLAY_INSTANCE_FLOATS);
+    }
+    // Collects every layer, groups it by shape so each shape is one instanced
+    // draw, and runs them into the swapchain over the finished frame.
+    renderOverlayPass(encoder, swapchainView) {
+        if (!this.camera)
+            return;
+        const byShape = this.overlayByShape;
+        for (const shape of OVERLAY_SHAPES) {
+            const list = byShape.get(shape);
+            if (list)
+                list.length = 0;
+        }
+        let total = 0;
+        const collect = (primitives) => {
+            for (const primitive of primitives) {
+                let list = byShape.get(primitive.shape);
+                if (!list) {
+                    list = [];
+                    byShape.set(primitive.shape, list);
+                }
+                list.push(primitive);
+                total++;
+            }
+        };
+        for (const layer of this.overlayLayers.values())
+            collect(layer);
+        if (this.overlayBones) {
+            const inst = this.overlayModel(this.overlayBones.modelName);
+            if (inst)
+                collect(boneOverlay(inst.model, this.boneOverlayOptions(inst.name)));
+        }
+        if (this.overlayBodies) {
+            const inst = this.overlayModel(this.overlayBodies.modelName);
+            if (inst)
+                collect(rigidbodyOverlay(inst.model, inst.physics, this.overlayBodies.options));
+        }
+        if (this.overlayJoints) {
+            const inst = this.overlayModel(this.overlayJoints.modelName);
+            if (inst)
+                collect(jointOverlay(inst.model, inst.physics, this.overlayJoints.options));
+        }
+        if (total === 0 && !this.overlayVertices)
+            return;
+        this.ensureOverlayInstanceCapacity(total);
+        const data = this.overlayInstanceData;
+        const draws = [];
+        let written = 0;
+        for (const shape of OVERLAY_SHAPES) {
+            const list = byShape.get(shape);
+            if (!list || list.length === 0)
+                continue;
+            draws.push({ shape, first: written, count: list.length });
+            for (const primitive of list) {
+                writeOverlayInstance(primitive, data, written * OVERLAY_INSTANCE_FLOATS);
+                written++;
+            }
+        }
+        this.device.queue.writeBuffer(this.overlayInstanceBuffer, 0, data.buffer, data.byteOffset, written * OVERLAY_INSTANCE_FLOATS * 4);
+        const width = this.canvas.width;
+        const height = this.canvas.height;
+        this.ensureOverlayTargets(width, height);
+        this.overlayUniformData[0] = width;
+        this.overlayUniformData[1] = height;
+        this.overlayUniformData[2] = Engine.OVERLAY_DASH_PERIOD_PX;
+        this.device.queue.writeBuffer(this.overlayUniformBuffer, 0, this.overlayUniformData);
+        const pass = encoder.beginRenderPass(this.overlayPassDescriptor);
+        // Under everything: the mesh is the haze the rig is read against.
+        this.renderWireframe(pass);
+        pass.setBindGroup(0, this.overlayBindGroup);
+        pass.setVertexBuffer(0, this.overlayVertexBuffer);
+        pass.setVertexBuffer(1, this.overlayInstanceBuffer);
+        // Volumes first and without depth writes, then the line work over them.
+        for (const solid of [true, false]) {
+            let bound = false;
+            for (const draw of draws) {
+                if (OVERLAY_SOLID_SHAPES.has(draw.shape) !== solid)
+                    continue;
+                if (!bound) {
+                    pass.setPipeline(solid ? this.overlaySolidPipeline : this.overlayPipeline);
+                    bound = true;
+                }
+                const range = this.overlayGeometry.ranges[draw.shape];
+                pass.draw(range.count, draw.count, range.first, draw.first);
+            }
+        }
+        pass.end();
+        // The resolved layer over the finished frame, premultiplied.
+        const compositeAtt = this.overlayCompositePassDescriptor.colorAttachments[0];
+        compositeAtt.view = swapchainView;
+        const composite = encoder.beginRenderPass(this.overlayCompositePassDescriptor);
+        composite.setPipeline(this.overlayCompositePipeline);
+        composite.setBindGroup(0, this.overlayCompositeBindGroup);
+        composite.draw(3);
+        composite.end();
+    }
     // Writes gizmo transform = T(bonePos) · R(boneWorldRot) · S(GIZMO_WORLD_SIZE),
     // then runs 6 triangle-list draws (3 axes + 3 rings). Local-axes mode: rotation
     // aligns rings with the bone's current world orientation, so clicking a ring
@@ -9659,7 +10771,11 @@ export class Engine {
         this.renderIdDebugPass(encoder, swapchainView);
         if (this.selectedMaterial && hasModels)
             this.renderSelectionPasses(encoder, swapchainView);
-        if (this.selectedBone && hasModels)
+        // Under the gizmo: the handles you drag stay on top of the rig you are
+        // reading them against.
+        if (this.overlayActive())
+            this.renderOverlayPass(encoder, swapchainView);
+        if (this.gizmoEnabled && this.selectedBone && hasModels)
             this.renderGizmoPass(encoder, swapchainView);
         const pick = this.pendingPick;
         if (pick && hasModels)
@@ -10945,6 +12061,13 @@ export class Engine {
     }
 }
 Engine.instance = null;
+/** The overlay renders multisampled into its own layer; the scene's own depth
+ *  is discarded before the composite (see the depthRead note in render), so it
+ *  could not have shared either that or the single-sample swapchain. */
+Engine.OVERLAY_SAMPLE_COUNT = 4;
+/** Dash period in device pixels — dashes are geometry, so this is only the
+ *  reference the dashedLine shape is cut against. */
+Engine.OVERLAY_DASH_PERIOD_PX = 8.0;
 Engine.GIZMO_RING_SEGMENTS = 96;
 Engine.GIZMO_RING_RADIUS = 0.8;
 // Axis visible length (relative to gizmo size). Extends past ring radius so
@@ -11100,6 +12223,7 @@ Engine.TIMED_PASSES = [
     "field",
     "bloom",
     "composite",
+    "overlay",
 ];
 // ── The floor mirror (step 7C) ──
 // Half-res scene-contract attachments a mirrored draw renders into, plus the
@@ -11124,3 +12248,6 @@ Engine.CULL_ARG_WORDS = 5;
 Engine.CULL_DRAW_CASTS_SHADOW = 1;
 Engine.CULL_MODEL_VISIBLE = 1;
 Engine.CULL_MODEL_RIGID = 2;
+/** A cache key no material can collide with — a PMX name is never empty and
+ *  never contains a NUL. */
+Engine.SEAM_KEY = "\u0000seams";