reze-engine 0.54.16 → 0.55.0

package/src/engine.ts

@@ -56,6 +56,28 @@ 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,
+  type BoneOverlayOptions,
+  type JointOverlayOptions,
+  type OverlayGeometry,
+  type OverlayPrimitive,
+  type OverlayShape,
+  type RigidbodyOverlayOptions,
+} from "./overlay"
 import {
   BLOOM_BLIT_SHADER_WGSL,
   BLOOM_DOWNSAMPLE_SHADER_WGSL,
@@ -772,6 +794,15 @@ interface ModelInstance {
   materialMorphTargets: MaterialMorphTarget[] | null
   /** The same targets by PMX material index, so a named offset is one lookup. */
   materialMorphByIndex: Map<number, MaterialMorphTarget> | null
+  /** The mesh's unique edges as a line-list index buffer, built on first use.
+   *  Deduplicated: an interior edge belongs to two triangles, so drawing the
+   *  triangle list's edges directly would draw most of the mesh twice.
+   *
+   *  Keyed by the material the edges were cut from, "" for the whole mesh. A
+   *  material is a consecutive index run, so scoping is a slice of the same
+   *  build — and both stay cached, because narrowing to one material and
+   *  widening back out is the loop somebody auditing a model is in. */
+  wireEdges: Map<string, { buffer: GPUBuffer; count: number; bindGroup: GPUBindGroup } | null>
   physics: RezePhysics | null
   vertexBufferNeedsUpdate: boolean
   gpuMorph: GpuMorph | null
@@ -1493,8 +1524,73 @@ export class Engine {
   private selectionEdgePassDescriptor!: GPURenderPassDescriptor
   private selectionSampler!: GPUSampler
 
+  // ─── Editor overlays (bones, rigidbodies, joints) ──────────────────
+  // One instanced pass over unit wireframes. Static layers are whatever the
+  // host handed setOverlay; the three live ones are rebuilt from the model
+  // every frame, because a posed skeleton has moved by the next one.
+  private overlayVertexBuffer!: GPUBuffer
+  private overlayInstanceBuffer: GPUBuffer | null = null
+  private overlayInstanceCapacity = 0
+  private overlayPipeline!: GPURenderPipeline
+  private overlaySolidPipeline!: GPURenderPipeline
+  private overlayBindGroup!: GPUBindGroup
+  private overlayGeometry!: OverlayGeometry
+  private overlayPassDescriptor!: GPURenderPassDescriptor
+  private overlayDepthTexture: GPUTexture | null = null
+  private overlayMsaaTexture: GPUTexture | null = null
+  private overlayResolveTexture: GPUTexture | null = null
+  private overlayUniformBuffer!: GPUBuffer
+  private overlayUniformData = new Float32Array(4)
+  private overlayCompositePipeline!: GPURenderPipeline
+  private overlayCompositeLayout!: GPUBindGroupLayout
+  private overlayCompositeBindGroup: GPUBindGroup | null = null
+  private overlayCompositePassDescriptor!: GPURenderPassDescriptor
+  private overlayTargetSize: [number, number] = [0, 0]
+  /** 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. */
+  private static readonly OVERLAY_SAMPLE_COUNT = 4
+  /** Dash period in device pixels — dashes are geometry, so this is only the
+   *  reference the dashedLine shape is cut against. */
+  private static readonly OVERLAY_DASH_PERIOD_PX = 8.0
+  private overlayLayers = new Map<string, OverlayPrimitive[]>()
+  private overlayBones: { modelName: string; options: BoneOverlayOptions } | null = null
+  private overlayBodies: { modelName: string; options: RigidbodyOverlayOptions } | null = null
+  private overlayJoints: { modelName: string; options: JointOverlayOptions } | null = null
+  private overlayVertices: { modelName: string; xray: boolean; material: string | null } | null = null
+  private wireframePipeline!: GPURenderPipeline
+  private wireframeDepthPipeline!: GPURenderPipeline
+  private wireframeUniformBuffer!: GPUBuffer
+  private wireframeBindGroup!: GPUBindGroup
+  /** The seam pass draws in the same frame at a different stroke and alpha, and
+   *  every queue write lands before the command buffer runs — writing the one
+   *  buffer twice would give both draws the second value. */
+  private wireframeSeamUniformBuffer!: GPUBuffer
+  private wireframeSeamBindGroup!: GPUBindGroup
+  /** Same reason: the hovered material draws its own stroke, self-occluding, in
+   *  the same frame as the base mesh and the seams. */
+  private wireframeHoverUniformBuffer!: GPUBuffer
+  private wireframeHoverBindGroup!: GPUBindGroup
+  private wireframeSkinLayout!: GPUBindGroupLayout
+  private wireframeColorData = new Float32Array(8)
+  /** Rebuilt every frame into these, grouped by shape so each shape is one draw. */
+  private overlayByShape = new Map<OverlayShape, OverlayPrimitive[]>()
+  private overlayScratch: OverlayPrimitive[] = []
+  private bonePickScratch: Float32Array = new Float32Array(0)
+  private overlayInstanceData = new Float32Array(0)
+
   // ─── Transform gizmo ───────────────────────────────────────────────
   private selectedBone: { modelName: string; boneName: string; boneIndex: number } | null = 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. */
+  private hoverMaterial: { modelName: string; materialName: string } | null = 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. */
+  private gizmoEnabled = true
   private gizmoVertexBuffer!: GPUBuffer
   private gizmoTransformBuffer!: GPUBuffer
   private gizmoPipeline!: GPURenderPipeline
@@ -1872,6 +1968,7 @@ export class Engine {
     "field",
     "bloom",
     "composite",
+    "overlay",
   ] as const
   private timestampQuerySet: GPUQuerySet | null = null
   private timestampResolve: GPUBuffer | null = null
@@ -5062,15 +5159,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}`,
-    )
   }
 
   // One-shot bake of EEVEE's combined BRDF LUT — DFG (bsdf_lut_frag.glsl) packed
@@ -6122,6 +6210,9 @@ export class Engine {
     // ─── 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
@@ -7094,6 +7185,330 @@ 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.
+  private 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" as GPUVertexFormat }, // pos
+              { shaderLocation: 1, offset: 3 * 4, format: "float32x3" as GPUVertexFormat }, // dir
+              { shaderLocation: 2, offset: 6 * 4, format: "float32x2" as GPUVertexFormat }, // caps
+              { shaderLocation: 3, offset: 8 * 4, format: "float32" as GPUVertexFormat }, // side
+              { shaderLocation: 4, offset: 9 * 4, format: "float32" as GPUVertexFormat }, // t
+              { shaderLocation: 5, offset: 10 * 4, format: "float32" as GPUVertexFormat }, // mode
+            ],
+          },
+          {
+            arrayStride: OVERLAY_INSTANCE_FLOATS * 4,
+            stepMode: "instance",
+            attributes: [
+              { shaderLocation: 6, offset: 0, format: "float32x4" as GPUVertexFormat }, // rotation
+              { shaderLocation: 7, offset: 4 * 4, format: "float32x4" as GPUVertexFormat }, // position + extent
+              { shaderLocation: 8, offset: 8 * 4, format: "float32x4" as GPUVertexFormat }, // scale + thickness
+              { shaderLocation: 9, offset: 12 * 4, format: "float32x4" as GPUVertexFormat }, // 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 },
+    } satisfies GPURenderPipelineDescriptor
+    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 as unknown as GPUTextureView, 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" as GPUVertexFormat }] },
+          { arrayStride: 4 * 2, attributes: [{ shaderLocation: 1, offset: 0, format: "uint16x4" as GPUVertexFormat }] },
+          { arrayStride: 4, attributes: [{ shaderLocation: 2, offset: 0, format: "unorm8x4" as GPUVertexFormat }] },
+        ],
+      },
+      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 as unknown as GPUTextureView,
+          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 as unknown as GPUTextureView,
+        depthClearValue: this.depthClear,
+        depthLoadOp: "clear",
+        depthStoreOp: "discard",
+      },
+    }
+  }
+
   // Step 4: Create camera and uniform buffer
   private setupCamera() {
     this.cameraUniformBuffer = this.device.createBuffer({
@@ -7667,6 +8082,13 @@ export class Engine {
      *  scaled by how far the reflected geometry sits behind the surface. */
     mirrorBlur?: number
   }): void {
+    // 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,
@@ -7767,7 +8189,14 @@ export class Engine {
     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. */
   private updateLightBuffer() {
+    if (!this.device || !this.lightUniformBuffer) return
     this.device.queue.writeBuffer(this.lightUniformBuffer, 0, this.lightData)
   }
 
@@ -7817,6 +8246,19 @@ export class Engine {
       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)
@@ -8278,6 +8720,18 @@ export class Engine {
     this.selectedMaterial = modelName && materialName ? { modelName, materialName } : null
   }
 
+  /** Show the transform gizmo on the selected bone. On by default. */
+  setGizmoEnabled(on: boolean): void {
+    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: string | null, materialName: string | null): void {
+    this.hoverMaterial = modelName && materialName ? { modelName, materialName } : null
+  }
+
   setSelectedBone(modelName: string | null, boneName: string | null): void {
     if (!modelName || !boneName) {
       this.selectedBone = null
@@ -8292,6 +8746,246 @@ export class Engine {
     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: string, primitives: OverlayPrimitive[]): void {
+    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?: string): void {
+    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: number,
+    y: number,
+    options: { radiusPx?: number; modelName?: string } = {},
+  ): { modelName: string; boneName: string; boneIndex: number } | null {
+    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: { modelName: string; boneName: string; boneIndex: number } | null = 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
+  }
+
+  /** Skinned positions for picking, grown on demand. One click's worth of work
+   *  reused across clicks — a model's vertex count does not change. */
+  private materialPickScratch: Float32Array | null = null
+
+  /**
+   * 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: number,
+    y: number,
+    options: { modelName?: string } = {},
+  ): { modelName: string; materialName: string; materialIndex: number } | null {
+    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: { modelName: string; materialName: string; materialIndex: number } | null = 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: string | null, options: BoneOverlayOptions = {}): void {
+    this.overlayBones = modelName ? { modelName, options } : null
+  }
+
+  /** Draw every rigidbody of `modelName` where the simulation has it, rebuilt
+   *  each frame. Null off. */
+  setRigidbodyOverlay(modelName: string | null, options: RigidbodyOverlayOptions = {}): void {
+    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: string | null, options: JointOverlayOptions = {}): void {
+    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: string | null,
+    options: { xray?: boolean; material?: string | null } = {},
+  ): void {
+    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
@@ -8387,8 +9081,23 @@ export class Engine {
     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: boolean): void {
+    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(): boolean {
@@ -9498,7 +10207,9 @@ 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,
@@ -9511,7 +10222,7 @@ export class Engine {
     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,
@@ -9614,6 +10325,7 @@ export class Engine {
       jointsBuffer,
       weightsBuffer,
       skinMatrixBuffer,
+      wireEdges: new Map(),
       drawCalls: [],
       shadowDrawCalls: [],
       shadowBindGroups,
@@ -10630,6 +11342,425 @@ export class Engine {
     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. */
+  private materialIndexRange(inst: ModelInstance, material: string | null): [number, number] | null {
+    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
+  }
+
+  /** A cache key no material can collide with — a PMX name is never empty and
+   *  never contains a NUL. */
+  private static readonly SEAM_KEY = "\u0000seams"
+
+  /**
+   * @param material one material's own edges, or null for the whole mesh
+   * @param seams    every material's OUTLINE instead — the borders between them
+   */
+  private ensureEdgeBuffer(inst: ModelInstance, material: string | null, seams = false): boolean {
+    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: number[] = []
+
+    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<number, number>()
+      const seen = new Set<number>()
+      let offset = 0
+      for (const m of inst.model.getMaterials()) {
+        const end = offset + m.vertexCount
+        used.clear()
+        const bump = (a: number, b: number) => {
+          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<number>()
+      const add = (a: number, b: number) => {
+        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
+  }
+
+  private renderWireframe(pass: GPURenderPassEncoder): void {
+    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. */
+  private boneOverlayOptions(modelName: string): BoneOverlayOptions {
+    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
+  }
+  private boneOptionsScratch: BoneOverlayOptions = {}
+
+  private overlayActive(): boolean {
+    return (
+      this.overlayLayers.size > 0 ||
+      this.overlayBones !== null ||
+      this.overlayBodies !== null ||
+      this.overlayJoints !== null ||
+      this.overlayVertices !== null
+    )
+  }
+
+  private overlayModel(name: string): ModelInstance | null {
+    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: "bones" | "rigidbodies" | "joints"): OverlayPrimitive[] {
+    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.
+  private ensureOverlayTargets(width: number, height: number): void {
+    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 as GPURenderPassColorAttachment[])[0]
+    colorAtt.view = this.overlayMsaaTexture.createView()
+    colorAtt.resolveTarget = this.overlayResolveTexture.createView()
+    const depthAtt = this.overlayPassDescriptor.depthStencilAttachment as GPURenderPassDepthStencilAttachment
+    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() }],
+    })
+  }
+
+  private ensureOverlayInstanceCapacity(count: number): void {
+    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.
+  private renderOverlayPass(encoder: GPUCommandEncoder, swapchainView: GPUTextureView): void {
+    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: readonly OverlayPrimitive[]) => {
+      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: { shape: OverlayShape; first: number; count: number }[] = []
+    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 as GPURenderPassColorAttachment[])[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
@@ -10844,7 +11975,7 @@ export class Engine {
   }
 
   private handleGizmoMouseDown = (e: MouseEvent) => {
-    if (!this.selectedBone || !this.camera || !this.device || e.button !== 0) return
+    if (!this.gizmoEnabled || !this.selectedBone || !this.camera || !this.device || e.button !== 0) return
     const inst = this.modelInstances.get(this.selectedBone.modelName)
     if (!inst) return
     const worldMats = inst.model.getWorldMatrices()
@@ -11489,7 +12620,10 @@ export class Engine {
     this.renderIdDebugPass(encoder, swapchainView)
 
     if (this.selectedMaterial && hasModels) this.renderSelectionPasses(encoder, swapchainView)
-    if (this.selectedBone && hasModels) this.renderGizmoPass(encoder, swapchainView)
+    // 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) this.renderPickPass(encoder)