reze-engine 0.13.4 → 0.14.0

package/dist/engine.js

@@ -1,5 +1,5 @@
 import { Camera } from "./camera";
-import { Mat4, Vec3 } from "./math";
+import { Mat4, Quat, Vec3 } from "./math";
 import { PmxLoader } from "./pmx-loader";
 import { Physics } from "./physics";
 import { createFetchAssetReader, createFileMapAssetReader, deriveBasePathFromPmxPath, fileListToMap, findFirstPmxFileInList, joinAssetPath, normalizeAssetPath, } from "./asset-reader";
@@ -17,6 +17,8 @@ import { LTC_MAG_LUT_SIZE, LTC_MAG_LUT_DATA } from "./shaders/ltc_mag_lut";
 import { SHADOW_DEPTH_SHADER_WGSL } from "./shaders/passes/shadow";
 import { GROUND_SHADOW_SHADER_WGSL } from "./shaders/passes/ground";
 import { OUTLINE_SHADER_WGSL } from "./shaders/passes/outline";
+import { SELECTION_MASK_SHADER_WGSL, SELECTION_EDGE_SHADER_WGSL } from "./shaders/passes/selection";
+import { GIZMO_SHADER_WGSL } from "./shaders/passes/gizmo";
 import { BLOOM_BLIT_SHADER_WGSL, BLOOM_DOWNSAMPLE_SHADER_WGSL, BLOOM_UPSAMPLE_SHADER_WGSL, } from "./shaders/passes/bloom";
 import { COMPOSITE_SHADER_WGSL } from "./shaders/passes/composite";
 import { PICK_SHADER_WGSL } from "./shaders/passes/pick";
@@ -65,6 +67,16 @@ export class Engine {
         this.lightData = new Float32Array(64);
         this.lightCount = 0;
         this.resizeObserver = null;
+        this.selectedMaterial = null;
+        // ─── Transform gizmo ───────────────────────────────────────────────
+        this.selectedBone = null;
+        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
+        // to the drag handler. All vectors/quats stored are in world / local frames as
+        // indicated; we snapshot "initial" values on drag start so the drag is driven
+        // by mouse-delta relative to the click point (not cumulative frame-to-frame).
+        this.gizmoDrag = null;
         // HDR intermediate format. rg11b10ufloat when the adapter exposes the
         // `rg11b10ufloat-renderable` feature (Chrome + Safari on Apple Silicon both
         // do), else fall back to rgba16float.
@@ -154,6 +166,173 @@ export class Engine {
                 this.lastTouchTime = currentTime;
             }
         };
+        this.handleGizmoMouseDown = (e) => {
+            if (!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();
+            const boneMat = worldMats[this.selectedBone.boneIndex];
+            if (!boneMat)
+                return;
+            const bonePos = boneMat.getPosition();
+            const boneWorldRot = boneMat.toQuat().normalize();
+            const rect = this.canvas.getBoundingClientRect();
+            const px = e.clientX - rect.left;
+            const py = e.clientY - rect.top;
+            const ray = this.buildMouseRay(px, py);
+            if (!ray)
+                return;
+            const gizmoSize = Engine.GIZMO_WORLD_SIZE;
+            // Bounding-sphere check: if the mouse ray passes inside an imaginary sphere
+            // around the gizmo, ALWAYS consume the event — so the user never accidentally
+            // orbits the camera while trying to click near a handle. Outside the sphere,
+            // let the camera handler take over as normal.
+            const sphereR = gizmoSize * Engine.GIZMO_AXIS_LENGTH * 1.05;
+            const f = ray.origin.subtract(bonePos);
+            const fd = f.dot(ray.dir);
+            const rayInsideSphere = fd * fd - (f.dot(f) - sphereR * sphereR) >= 0;
+            if (!rayInsideSphere)
+                return;
+            // We're inside the gizmo's claim area — the event is ours regardless of hit.
+            e.stopImmediatePropagation();
+            e.preventDefault();
+            // Pick threshold stays pixel-based — clicking should feel the same at any zoom.
+            const camPos = this.camera.getPosition();
+            const dist = Math.max(0.01, bonePos.subtract(camPos).length());
+            const worldPerPixel = (dist * Math.tan(this.camera.fov * 0.5) * 2) / Math.max(1, this.canvas.clientHeight);
+            const worldThreshold = Engine.GIZMO_PICK_THRESHOLD_PX * worldPerPixel;
+            // World-rotated local axes (where the visible gizmo arms actually point).
+            const worldAxes = [
+                this.rotateVec3ByQuat(new Vec3(1, 0, 0), boneWorldRot),
+                this.rotateVec3ByQuat(new Vec3(0, 1, 0), boneWorldRot),
+                this.rotateVec3ByQuat(new Vec3(0, 0, 1), boneWorldRot),
+            ];
+            const hit = this.hitTestGizmo(ray, bonePos, gizmoSize, worldThreshold, worldAxes);
+            if (!hit)
+                return; // Inside sphere but didn't hit a handle — event consumed, no drag.
+            this.camera.setInputLocked(true);
+            const parentIdx = inst.model.getSkeleton().bones[this.selectedBone.boneIndex].parentIndex;
+            const parentWorldRot = parentIdx >= 0 && parentIdx < worldMats.length ? worldMats[parentIdx].toQuat().normalize() : Quat.identity();
+            const parentWorldRotInv = parentWorldRot.clone().conjugate();
+            const worldAxis = worldAxes[hit.axis];
+            // In-plane basis for the ring: u/v are the OTHER two world-rotated axes.
+            //   X ring (normal X) → (u=Y, v=Z); Y ring → (u=Z, v=X); Z ring → (u=X, v=Y)
+            const basisU = hit.axis === 0 ? worldAxes[1] : hit.axis === 1 ? worldAxes[2] : worldAxes[0];
+            const basisV = hit.axis === 0 ? worldAxes[2] : hit.axis === 1 ? worldAxes[0] : worldAxes[1];
+            let initialAngle = 0;
+            let initialAxisParam = 0;
+            if (hit.kind === "ring") {
+                const p = this.rayPlane(ray.origin, ray.dir, bonePos, worldAxis);
+                if (p)
+                    initialAngle = this.angleInRingPlane(p, bonePos, basisU, basisV);
+            }
+            else {
+                initialAxisParam = this.closestParamOnAxisLine(bonePos, worldAxis, ray.origin, ray.dir);
+            }
+            const initialLocalRot = inst.model.getBoneLocalRotation(this.selectedBone.boneIndex).clone();
+            const initTrans = inst.model.getBoneLocalTranslation(this.selectedBone.boneIndex);
+            const initialLocalTrans = new Vec3(initTrans.x, initTrans.y, initTrans.z);
+            this.gizmoDrag = {
+                kind: hit.kind,
+                axis: hit.axis,
+                bonePos,
+                worldAxis,
+                basisU,
+                basisV,
+                initialLocalRot,
+                initialLocalTrans,
+                parentWorldRot,
+                parentWorldRotInv,
+                initialAngle,
+                initialAxisParam,
+            };
+            if (this.onGizmoDrag) {
+                this.onGizmoDrag({
+                    modelName: this.selectedBone.modelName,
+                    boneName: this.selectedBone.boneName,
+                    boneIndex: this.selectedBone.boneIndex,
+                    kind: hit.kind === "ring" ? "rotate" : "translate",
+                    localRotation: initialLocalRot.clone(),
+                    localTranslation: new Vec3(initialLocalTrans.x, initialLocalTrans.y, initialLocalTrans.z),
+                    phase: "start",
+                });
+            }
+        };
+        this.handleGizmoMouseMove = (e) => {
+            const drag = this.gizmoDrag;
+            if (!drag || !this.selectedBone || !this.camera)
+                return;
+            const inst = this.modelInstances.get(this.selectedBone.modelName);
+            if (!inst)
+                return;
+            const rect = this.canvas.getBoundingClientRect();
+            const px = e.clientX - rect.left;
+            const py = e.clientY - rect.top;
+            const ray = this.buildMouseRay(px, py);
+            if (!ray)
+                return;
+            // Compute the target local rotation / translation. The engine never writes
+            // to the skeleton itself — we hand the result to the host callback and let
+            // it decide (runtime write, tween, clip keyframe edit, …).
+            let nextRot = drag.initialLocalRot;
+            let nextTrans = drag.initialLocalTrans;
+            if (drag.kind === "ring") {
+                const p = this.rayPlane(ray.origin, ray.dir, drag.bonePos, drag.worldAxis);
+                if (!p)
+                    return;
+                const currentAngle = this.angleInRingPlane(p, drag.bonePos, drag.basisU, drag.basisV);
+                const deltaAngle = currentAngle - drag.initialAngle;
+                const qWorld = Quat.fromAxisAngle(drag.worldAxis, deltaAngle);
+                // L_new = P_inv · Q_world · P · L_initial
+                const lNew = drag.parentWorldRotInv
+                    .multiply(qWorld)
+                    .multiply(drag.parentWorldRot)
+                    .multiply(drag.initialLocalRot);
+                lNew.normalize();
+                nextRot = lNew;
+            }
+            else {
+                const tNow = this.closestParamOnAxisLine(drag.bonePos, drag.worldAxis, ray.origin, ray.dir);
+                const deltaParam = tNow - drag.initialAxisParam;
+                const worldDelta = drag.worldAxis.scale(deltaParam);
+                const localDelta = this.rotateVec3ByQuat(worldDelta, drag.parentWorldRotInv);
+                nextTrans = new Vec3(drag.initialLocalTrans.x + localDelta.x, drag.initialLocalTrans.y + localDelta.y, drag.initialLocalTrans.z + localDelta.z);
+            }
+            this.onGizmoDrag?.({
+                modelName: this.selectedBone.modelName,
+                boneName: this.selectedBone.boneName,
+                boneIndex: this.selectedBone.boneIndex,
+                kind: drag.kind === "ring" ? "rotate" : "translate",
+                localRotation: nextRot,
+                localTranslation: nextTrans,
+            });
+        };
+        this.handleGizmoMouseUp = () => {
+            const drag = this.gizmoDrag;
+            if (!drag)
+                return;
+            if (this.onGizmoDrag && this.selectedBone) {
+                const inst = this.modelInstances.get(this.selectedBone.modelName);
+                if (inst) {
+                    const finalRot = inst.model.getBoneLocalRotation(this.selectedBone.boneIndex).clone();
+                    const t = inst.model.getBoneLocalTranslation(this.selectedBone.boneIndex);
+                    const finalTrans = new Vec3(t.x, t.y, t.z);
+                    this.onGizmoDrag({
+                        modelName: this.selectedBone.modelName,
+                        boneName: this.selectedBone.boneName,
+                        boneIndex: this.selectedBone.boneIndex,
+                        kind: drag.kind === "ring" ? "rotate" : "translate",
+                        localRotation: finalRot,
+                        localTranslation: finalTrans,
+                        phase: "end",
+                    });
+                }
+            }
+            this.gizmoDrag = null;
+            this.camera?.setInputLocked(false);
+        };
         this.canvas = canvas;
         const d = DEFAULT_ENGINE_OPTIONS;
         this.world = {
@@ -171,6 +350,7 @@ export class Engine {
             fov: options?.camera?.fov ?? d.camera.fov,
         };
         this.onRaycast = options?.onRaycast;
+        this.onGizmoDrag = options?.onGizmoDrag;
         this.physicsOptions = options?.physicsOptions ?? d.physicsOptions;
         this.bloomSettings = Engine.mergeBloomDefaults(options?.bloom);
         this.viewTransform = Engine.mergeViewTransformDefaults(options?.view);
@@ -866,6 +1046,79 @@ export class Engine {
                 stencilWriteMask: 0,
             },
         });
+        // ─── Selection overlay (screen-space edge-detect on a per-material mask) ───
+        // Reuses outline camera + main skinMats bind group layouts. No group 2 (no per-mat uniform).
+        const selectionMaskPipelineLayout = this.device.createPipelineLayout({
+            label: "selection mask pipeline layout",
+            bindGroupLayouts: [this.outlinePerFrameBindGroupLayout, this.mainPerInstanceBindGroupLayout],
+        });
+        const selectionMaskShaderModule = this.device.createShaderModule({
+            label: "selection mask shader",
+            code: SELECTION_MASK_SHADER_WGSL,
+        });
+        this.selectionMaskPipeline = this.device.createRenderPipeline({
+            label: "selection mask pipeline",
+            layout: selectionMaskPipelineLayout,
+            vertex: { module: selectionMaskShaderModule, entryPoint: "vs", buffers: outlineVertexBuffers },
+            fragment: {
+                module: selectionMaskShaderModule,
+                entryPoint: "fs",
+                targets: [{ format: "r8unorm" }],
+            },
+            primitive: { cullMode: "none" },
+            // Single-sample, no depth (depth-always via not attaching a depth buffer at all).
+            multisample: { count: 1 },
+        });
+        this.selectionEdgeBindGroupLayout = this.device.createBindGroupLayout({
+            label: "selection edge bind group layout",
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+                { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
+                { binding: 2, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+            ],
+        });
+        const selectionEdgePipelineLayout = this.device.createPipelineLayout({
+            label: "selection edge pipeline layout",
+            bindGroupLayouts: [this.selectionEdgeBindGroupLayout],
+        });
+        const selectionEdgeShaderModule = this.device.createShaderModule({
+            label: "selection edge shader",
+            code: SELECTION_EDGE_SHADER_WGSL,
+        });
+        this.selectionEdgePipeline = this.device.createRenderPipeline({
+            label: "selection edge pipeline",
+            layout: selectionEdgePipelineLayout,
+            vertex: { module: selectionEdgeShaderModule, entryPoint: "vs" },
+            fragment: {
+                module: selectionEdgeShaderModule,
+                entryPoint: "fs",
+                targets: [
+                    {
+                        format: this.presentationFormat,
+                        blend: {
+                            color: { srcFactor: "src-alpha", 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.selectionSampler = this.device.createSampler({
+            label: "selection sampler",
+            magFilter: "linear",
+            minFilter: "linear",
+        });
+        this.selectionEdgeUniformBuffer = this.device.createBuffer({
+            label: "selection edge uniforms",
+            size: 16,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        // thickness (pixels), + 3 floats padding
+        this.device.queue.writeBuffer(this.selectionEdgeUniformBuffer, 0, new Float32Array([5.0, 0, 0, 0]));
+        // ─── Transform gizmo (3 axes + 3 rings) ─────────────────────────
+        this.setupGizmo();
         // ─── 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
@@ -1061,6 +1314,13 @@ export class Engine {
             this.canvas.addEventListener("dblclick", this.handleCanvasDoubleClick);
             this.canvas.addEventListener("touchend", this.handleCanvasTouch);
         }
+        // Gizmo drag. mousedown registered in capture phase so we can consume the
+        // event via stopImmediatePropagation before the camera's mousedown handler
+        // runs (both listen on the canvas). move/up on window so drag tracks even
+        // if the cursor leaves the canvas.
+        this.canvas.addEventListener("mousedown", this.handleGizmoMouseDown, { capture: true });
+        window.addEventListener("mousemove", this.handleGizmoMouseMove);
+        window.addEventListener("mouseup", this.handleGizmoMouseUp);
     }
     handleResize() {
         const displayWidth = this.canvas.clientWidth;
@@ -1181,6 +1441,45 @@ export class Engine {
                     },
                 ],
             };
+            // Selection mask: single-channel canvas-res texture. Depth-always (no depth attachment).
+            this.selectionMaskTexture = this.device.createTexture({
+                label: "selection mask",
+                size: [width, height],
+                format: "r8unorm",
+                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+            });
+            this.selectionMaskView = this.selectionMaskTexture.createView();
+            this.selectionMaskPassDescriptor = {
+                label: "selection mask pass",
+                colorAttachments: [
+                    {
+                        view: this.selectionMaskView,
+                        clearValue: { r: 0, g: 0, b: 0, a: 0 },
+                        loadOp: "clear",
+                        storeOp: "store",
+                    },
+                ],
+            };
+            this.selectionEdgeBindGroup = this.device.createBindGroup({
+                label: "selection edge bind group",
+                layout: this.selectionEdgeBindGroupLayout,
+                entries: [
+                    { binding: 0, resource: this.selectionMaskView },
+                    { binding: 1, resource: this.selectionSampler },
+                    { binding: 2, resource: { buffer: this.selectionEdgeUniformBuffer } },
+                ],
+            });
+            // Edge pass draws on top of the composite output — load-store on swapchain.
+            this.selectionEdgePassDescriptor = {
+                label: "selection edge pass",
+                colorAttachments: [
+                    {
+                        view: undefined,
+                        loadOp: "load",
+                        storeOp: "store",
+                    },
+                ],
+            };
             this.writeBloomUniforms();
             if (this.compositeBindGroupLayout && this.bloomBlitBindGroupLayout) {
                 // Blit: reads HDR resolve texture (full-res), writes bloomDown mip 0.
@@ -1254,6 +1553,162 @@ export class Engine {
             }
         }
     }
+    // Builds the gizmo pipeline, its shared transform bind group, 3 per-color bind
+    // groups (R/G/B), and the packed triangle-list vertex buffer. Each original
+    // line segment is expanded to 6 verts (2 triangles) carrying (pos, dir, side)
+    // so the VS can extrude to a uniform pixel-width ribbon.
+    setupGizmo() {
+        const SEG = Engine.GIZMO_RING_SEGMENTS;
+        const R = Engine.GIZMO_RING_RADIUS;
+        const ringVerts = SEG * 6;
+        this.gizmoDraws = [
+            { first: 0, count: 6, color: 0 }, // X axis
+            { first: 6, count: 6, color: 1 }, // Y axis
+            { first: 12, count: 6, color: 2 }, // Z axis
+            { first: 18, count: ringVerts, color: 0 }, // X ring (YZ plane)
+            { first: 18 + ringVerts, count: ringVerts, color: 1 }, // Y ring (XZ plane)
+            { first: 18 + 2 * ringVerts, count: ringVerts, color: 2 }, // Z ring (XY plane)
+        ];
+        const verts = [];
+        // Per-vertex layout: pos(3), segDir(3), side(1), axisT(1) = 8 floats.
+        // axisT encodes "parameter along the axis" for axis verts (0 at center, 1
+        // at tip). Ring verts use -1 as a "not an axis" flag the FS uses to skip
+        // the dash + fade treatment.
+        const pushSeg = (p0, p1, t0, t1) => {
+            const d = [p1[0] - p0[0], p1[1] - p0[1], p1[2] - p0[2]];
+            const dn = [-d[0], -d[1], -d[2]];
+            verts.push(p0[0], p0[1], p0[2], d[0], d[1], d[2], -1, t0);
+            verts.push(p0[0], p0[1], p0[2], d[0], d[1], d[2], 1, t0);
+            verts.push(p1[0], p1[1], p1[2], dn[0], dn[1], dn[2], -1, t1);
+            verts.push(p0[0], p0[1], p0[2], d[0], d[1], d[2], 1, t0);
+            verts.push(p1[0], p1[1], p1[2], dn[0], dn[1], dn[2], 1, t1);
+            verts.push(p1[0], p1[1], p1[2], dn[0], dn[1], dn[2], -1, t1);
+        };
+        // Axes (open). t = 0 at center → 1 at tip. FS dashes + dims the inside-ring part.
+        const L = Engine.GIZMO_AXIS_LENGTH;
+        pushSeg([0, 0, 0], [L, 0, 0], 0, 1);
+        pushSeg([0, 0, 0], [0, L, 0], 0, 1);
+        pushSeg([0, 0, 0], [0, 0, L], 0, 1);
+        // Rings (closed). t = -1 signals "not an axis".
+        for (let plane = 0; plane < 3; plane++) {
+            for (let i = 0; i < SEG; i++) {
+                const t0 = (i / SEG) * Math.PI * 2;
+                const t1 = ((i + 1) / SEG) * Math.PI * 2;
+                const c0 = Math.cos(t0) * R, s0 = Math.sin(t0) * R;
+                const c1 = Math.cos(t1) * R, s1 = Math.sin(t1) * R;
+                if (plane === 0)
+                    pushSeg([0, c0, s0], [0, c1, s1], -1, -1);
+                else if (plane === 1)
+                    pushSeg([s0, 0, c0], [s1, 0, c1], -1, -1);
+                else
+                    pushSeg([c0, s0, 0], [c1, s1, 0], -1, -1);
+            }
+        }
+        const geom = new Float32Array(verts);
+        this.gizmoVertexBuffer = this.device.createBuffer({
+            label: "gizmo vertex buffer",
+            size: geom.byteLength,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        this.device.queue.writeBuffer(this.gizmoVertexBuffer, 0, geom);
+        // Shared transform+viewport+thickness uniform. Rewritten per frame.
+        this.gizmoTransformBuffer = this.device.createBuffer({
+            label: "gizmo transform",
+            size: 80, // mat4 (64) + vec2 viewport (8) + thickness f32 (4) + pad (4)
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        const bg0Layout = this.device.createBindGroupLayout({
+            label: "gizmo group 0 layout (camera + transform)",
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } },
+                { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: "uniform" } },
+            ],
+        });
+        const bg1Layout = this.device.createBindGroupLayout({
+            label: "gizmo group 1 layout (color)",
+            entries: [{ binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } }],
+        });
+        const pipelineLayout = this.device.createPipelineLayout({
+            label: "gizmo pipeline layout",
+            bindGroupLayouts: [bg0Layout, bg1Layout],
+        });
+        const shader = this.device.createShaderModule({ label: "gizmo shader", code: GIZMO_SHADER_WGSL });
+        this.gizmoPipeline = this.device.createRenderPipeline({
+            label: "gizmo pipeline",
+            layout: pipelineLayout,
+            vertex: {
+                module: shader,
+                entryPoint: "vs",
+                buffers: [
+                    {
+                        arrayStride: 8 * 4, // pos(3) + segDir(3) + side(1) + axisT(1) = 8 floats
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: "float32x3" }, // position
+                            { shaderLocation: 1, offset: 3 * 4, format: "float32x3" }, // segDir
+                            { shaderLocation: 2, offset: 6 * 4, format: "float32" }, // side
+                            { shaderLocation: 3, offset: 7 * 4, format: "float32" }, // axisT
+                        ],
+                    },
+                ],
+            },
+            fragment: {
+                module: shader,
+                entryPoint: "fs",
+                targets: [
+                    {
+                        format: this.presentationFormat,
+                        blend: {
+                            color: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha", operation: "add" },
+                            alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+                        },
+                    },
+                ],
+            },
+            primitive: { topology: "triangle-list", cullMode: "none" },
+            multisample: { count: 1 },
+        });
+        this.gizmoBindGroup0 = this.device.createBindGroup({
+            label: "gizmo bind group 0",
+            layout: bg0Layout,
+            entries: [
+                { binding: 0, resource: { buffer: this.cameraUniformBuffer } },
+                { binding: 1, resource: { buffer: this.gizmoTransformBuffer } },
+            ],
+        });
+        // Vivid game-UI palette. FS applies an edge-to-center alpha falloff so these
+        // full-saturation colors stay readable without feeling flat. Pipeline writes
+        // straight to the LDR swapchain (no tonemap), so values > 1 clamp.
+        const colors = [
+            new Float32Array([1.0, 0.24, 0.38, 1.0]), // X: warm red, slight pink
+            new Float32Array([0.35, 0.95, 0.52, 1.0]), // Y: emerald
+            new Float32Array([0.33, 0.62, 1.0, 1.0]), // Z: azure
+        ];
+        this.gizmoColorBindGroups = [];
+        for (let i = 0; i < 3; i++) {
+            const buf = this.device.createBuffer({
+                label: `gizmo color ${i}`,
+                size: 16,
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            });
+            this.device.queue.writeBuffer(buf, 0, colors[i]);
+            this.gizmoColorBindGroups.push(this.device.createBindGroup({
+                label: `gizmo color bg ${i}`,
+                layout: bg1Layout,
+                entries: [{ binding: 0, resource: { buffer: buf } }],
+            }));
+        }
+        // Gizmo pass — depth-less, loads the swapchain so it composites on top.
+        this.gizmoPassDescriptor = {
+            label: "gizmo pass",
+            colorAttachments: [
+                {
+                    view: undefined,
+                    loadOp: "load",
+                    storeOp: "store",
+                },
+            ],
+        };
+    }
     // Step 4: Create camera and uniform buffer
     setupCamera() {
         this.cameraUniformBuffer = this.device.createBuffer({
@@ -1445,6 +1900,10 @@ export class Engine {
             this.canvas.removeEventListener("dblclick", this.handleCanvasDoubleClick);
             this.canvas.removeEventListener("touchend", this.handleCanvasTouch);
         }
+        // Remove gizmo drag listeners
+        this.canvas.removeEventListener("mousedown", this.handleGizmoMouseDown, { capture: true });
+        window.removeEventListener("mousemove", this.handleGizmoMouseMove);
+        window.removeEventListener("mouseup", this.handleGizmoMouseUp);
         if (this.resizeObserver) {
             this.resizeObserver.disconnect();
             this.resizeObserver = null;
@@ -1523,6 +1982,22 @@ export class Engine {
             }
         }
     }
+    setSelectedMaterial(modelName, materialName) {
+        this.selectedMaterial = modelName && materialName ? { modelName, materialName } : null;
+    }
+    setSelectedBone(modelName, boneName) {
+        if (!modelName || !boneName) {
+            this.selectedBone = null;
+            return;
+        }
+        const inst = this.modelInstances.get(modelName);
+        if (!inst) {
+            this.selectedBone = null;
+            return;
+        }
+        const boneIndex = inst.model.getSkeleton().bones.findIndex((b) => b.name === boneName);
+        this.selectedBone = boneIndex >= 0 ? { modelName, boneName, boneIndex } : null;
+    }
     setMaterialPresets(modelName, presets) {
         const inst = this.modelInstances.get(modelName);
         if (!inst)
@@ -1797,7 +2272,7 @@ export class Engine {
         const eye = new Vec3(target.x - dir.x * 72, target.y - dir.y * 72, target.z - dir.z * 72);
         const up = Math.abs(dir.y) > 0.99 ? new Vec3(0, 0, -1) : new Vec3(0, 1, 0);
         const view = Mat4.lookAt(eye, target, up);
-        const proj = Mat4.orthographicLh(-72, 72, -72, 72, 1, 140);
+        const proj = Mat4.orthographicLh(-32, 32, -32, 32, 1, 140);
         const vp = proj.multiply(view);
         this.shadowLightVPMatrix.set(vp.values);
         this.device.queue.writeBuffer(this.shadowLightVPBuffer, 0, this.shadowLightVPMatrix);
@@ -2033,12 +2508,239 @@ export class Engine {
     }
     performRaycast(screenX, screenY) {
         if (!this.onRaycast || this.modelInstances.size === 0) {
-            this.onRaycast?.("", null, screenX, screenY);
+            this.onRaycast?.("", null, null, screenX, screenY);
             return;
         }
         const dpr = window.devicePixelRatio || 1;
         this.pendingPick = { x: Math.floor(screenX * dpr), y: Math.floor(screenY * dpr) };
     }
+    renderSelectionPasses(encoder, swapchainView) {
+        if (!this.selectedMaterial || !this.selectionEdgeBindGroup)
+            return;
+        const inst = this.modelInstances.get(this.selectedMaterial.modelName);
+        if (!inst)
+            return;
+        const target = this.selectedMaterial.materialName;
+        const draw = inst.drawCalls.find((d) => (d.type === "opaque" || d.type === "transparent") && d.materialName === target);
+        if (!draw || !this.shouldRenderDrawCall(inst, draw))
+            return;
+        // Mask pass: fill the selected material's projected footprint with 1.0. Depth-always
+        // (no depth attachment) so the outline traces complete boundaries even when the
+        // material is partially occluded — matches Blender selection-through behaviour.
+        const mpass = encoder.beginRenderPass(this.selectionMaskPassDescriptor);
+        mpass.setPipeline(this.selectionMaskPipeline);
+        mpass.setBindGroup(0, this.outlinePerFrameBindGroup);
+        mpass.setBindGroup(1, inst.mainPerInstanceBindGroup);
+        mpass.setVertexBuffer(0, inst.vertexBuffer);
+        mpass.setVertexBuffer(1, inst.jointsBuffer);
+        mpass.setVertexBuffer(2, inst.weightsBuffer);
+        mpass.setIndexBuffer(inst.indexBuffer, "uint32");
+        mpass.drawIndexed(draw.count, 1, draw.firstIndex, 0, 0);
+        mpass.end();
+        // Edge pass: screen-space edge detect on the mask, alpha-blended over swapchain.
+        const edgeAttachment = this.selectionEdgePassDescriptor.colorAttachments[0];
+        edgeAttachment.view = swapchainView;
+        const epass = encoder.beginRenderPass(this.selectionEdgePassDescriptor);
+        epass.setPipeline(this.selectionEdgePipeline);
+        epass.setBindGroup(0, this.selectionEdgeBindGroup);
+        epass.draw(3);
+        epass.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
+    // rotates around that bone's natural axis.
+    renderGizmoPass(encoder, swapchainView) {
+        if (!this.selectedBone || !this.camera)
+            return;
+        const inst = this.modelInstances.get(this.selectedBone.modelName);
+        if (!inst)
+            return;
+        const worldMats = inst.model.getWorldMatrices();
+        if (this.selectedBone.boneIndex >= worldMats.length)
+            return;
+        const boneMat = worldMats[this.selectedBone.boneIndex];
+        const bonePos = boneMat.getPosition();
+        const q = boneMat.toQuat().normalize(); // world rotation
+        const s = Engine.GIZMO_WORLD_SIZE;
+        // Column-major mat4: rotation columns × scale, then translation in col 3.
+        const xx = q.x * q.x, yy = q.y * q.y, zz = q.z * q.z;
+        const xy = q.x * q.y, xz = q.x * q.z, yz = q.y * q.z;
+        const wx = q.w * q.x, wy = q.w * q.y, wz = q.w * q.z;
+        const u = new Float32Array(20);
+        u[0] = s * (1 - 2 * (yy + zz));
+        u[1] = s * 2 * (xy + wz);
+        u[2] = s * 2 * (xz - wy);
+        u[3] = 0;
+        u[4] = s * 2 * (xy - wz);
+        u[5] = s * (1 - 2 * (xx + zz));
+        u[6] = s * 2 * (yz + wx);
+        u[7] = 0;
+        u[8] = s * 2 * (xz + wy);
+        u[9] = s * 2 * (yz - wx);
+        u[10] = s * (1 - 2 * (xx + yy));
+        u[11] = 0;
+        u[12] = bonePos.x;
+        u[13] = bonePos.y;
+        u[14] = bonePos.z;
+        u[15] = 1;
+        u[16] = this.canvas.width;
+        u[17] = this.canvas.height;
+        u[18] = Engine.GIZMO_THICKNESS_PX;
+        u[19] = 0;
+        this.device.queue.writeBuffer(this.gizmoTransformBuffer, 0, u);
+        const att = this.gizmoPassDescriptor.colorAttachments[0];
+        att.view = swapchainView;
+        const pass = encoder.beginRenderPass(this.gizmoPassDescriptor);
+        pass.setPipeline(this.gizmoPipeline);
+        pass.setBindGroup(0, this.gizmoBindGroup0);
+        pass.setVertexBuffer(0, this.gizmoVertexBuffer);
+        for (const d of this.gizmoDraws) {
+            pass.setBindGroup(1, this.gizmoColorBindGroups[d.color]);
+            pass.draw(d.count, 1, d.first, 0);
+        }
+        pass.end();
+    }
+    // ──────────────────────────────────────────────────────────────────
+    // Gizmo drag — hit test + input handlers + rotation/translation math
+    // ──────────────────────────────────────────────────────────────────
+    rotateVec3ByQuat(v, q) {
+        // Standard rodrigues-via-quat formulation. Cheaper than q * v * q_conj.
+        const tx = 2 * (q.y * v.z - q.z * v.y);
+        const ty = 2 * (q.z * v.x - q.x * v.z);
+        const tz = 2 * (q.x * v.y - q.y * v.x);
+        return new Vec3(v.x + q.w * tx + (q.y * tz - q.z * ty), v.y + q.w * ty + (q.z * tx - q.x * tz), v.z + q.w * tz + (q.x * ty - q.y * tx));
+    }
+    unproject(invVP, ndcX, ndcY, ndcZ) {
+        const m = invVP.values;
+        const x = m[0] * ndcX + m[4] * ndcY + m[8] * ndcZ + m[12];
+        const y = m[1] * ndcX + m[5] * ndcY + m[9] * ndcZ + m[13];
+        const z = m[2] * ndcX + m[6] * ndcY + m[10] * ndcZ + m[14];
+        const w = m[3] * ndcX + m[7] * ndcY + m[11] * ndcZ + m[15];
+        if (Math.abs(w) < 1e-9)
+            return null;
+        return new Vec3(x / w, y / w, z / w);
+    }
+    // World-space ray from camera through a canvas pixel. Uses WebGPU's NDC z ∈ [0,1].
+    buildMouseRay(px, py) {
+        if (!this.camera)
+            return null;
+        const width = this.canvas.clientWidth;
+        const height = this.canvas.clientHeight;
+        if (width <= 0 || height <= 0)
+            return null;
+        const ndcX = (px / width) * 2 - 1;
+        const ndcY = -((py / height) * 2 - 1);
+        const view = this.camera.getViewMatrix();
+        const proj = this.camera.getProjectionMatrix();
+        const invVP = proj.multiply(view).inverse();
+        const near = this.unproject(invVP, ndcX, ndcY, 0);
+        const far = this.unproject(invVP, ndcX, ndcY, 1);
+        if (!near || !far)
+            return null;
+        return { origin: near, dir: far.subtract(near).normalize() };
+    }
+    // Finds the closest gizmo handle to the mouse ray, within `worldThreshold`.
+    // `worldAxes[i]` is the i-th local axis rotated into world by bone world rotation.
+    hitTestGizmo(ray, bonePos, gizmoSize, worldThreshold, worldAxes) {
+        let bestKind = null;
+        let bestAxis = 0;
+        let bestDist = worldThreshold;
+        // Axes only hit on their OUTER portion (past the ring radius). Inside the
+        // ring the axis line passes through the plane of the perpendicular ring
+        // (e.g. X-axis passes through the interior of the Y ring), so including the
+        // full axis produced ring-vs-axis ties and constant misclicks. Axis extends
+        // to AXIS_LENGTH, so the hit zone is roughly half the visible axis length —
+        // easy to grab while leaving the ring's interior unambiguous.
+        const axisHitStart = gizmoSize * (Engine.GIZMO_RING_RADIUS + 0.05);
+        const axisHitEnd = gizmoSize * Engine.GIZMO_AXIS_LENGTH;
+        for (let i = 0; i < 3; i++) {
+            const segA = bonePos.add(worldAxes[i].scale(axisHitStart));
+            const segB = bonePos.add(worldAxes[i].scale(axisHitEnd));
+            const d = this.distSegmentRay(segA, segB, ray.origin, ray.dir);
+            if (d < bestDist) {
+                bestDist = d;
+                bestKind = "axis";
+                bestAxis = i;
+            }
+        }
+        const ringR = gizmoSize * Engine.GIZMO_RING_RADIUS;
+        for (let i = 0; i < 3; i++) {
+            const n = worldAxes[i];
+            const denom = ray.dir.dot(n);
+            if (Math.abs(denom) < 1e-6)
+                continue;
+            const t = bonePos.subtract(ray.origin).dot(n) / denom;
+            if (t < 0)
+                continue;
+            const hit = ray.origin.add(ray.dir.scale(t));
+            const rel = hit.subtract(bonePos);
+            const radial = rel.subtract(n.scale(rel.dot(n)));
+            const radius = radial.length();
+            const d = Math.abs(radius - ringR);
+            if (d < bestDist) {
+                bestDist = d;
+                bestKind = "ring";
+                bestAxis = i;
+            }
+        }
+        return bestKind ? { kind: bestKind, axis: bestAxis } : null;
+    }
+    // Shortest distance between segment [A, B] and ray (origin, dir-unit).
+    distSegmentRay(A, B, rayO, rayD) {
+        const u = B.subtract(A); // segment direction (not normalized)
+        const w = A.subtract(rayO);
+        const a = u.dot(u);
+        const b = u.dot(rayD);
+        const d = u.dot(w);
+        const e = rayD.dot(w);
+        const denom = a - b * b; // since |rayD|=1
+        let sc, tc;
+        if (Math.abs(denom) < 1e-9) {
+            sc = 0;
+            tc = e;
+        }
+        else {
+            sc = (b * e - d) / denom;
+            tc = (a * e - b * d) / denom;
+        }
+        sc = Math.max(0, Math.min(1, sc));
+        if (tc < 0)
+            tc = 0;
+        const ps = new Vec3(A.x + sc * u.x, A.y + sc * u.y, A.z + sc * u.z);
+        const pr = new Vec3(rayO.x + tc * rayD.x, rayO.y + tc * rayD.y, rayO.z + tc * rayD.z);
+        return ps.subtract(pr).length();
+    }
+    // Line-line closest point: returns the parameter t on line (A, dir) where the
+    // closest approach to the ray is. Used by axis-translation drag so frame N
+    // reads a signed delta vs the mouse-down snapshot.
+    closestParamOnAxisLine(A, dir, rayO, rayD) {
+        const w = A.subtract(rayO);
+        const b = dir.dot(rayD);
+        const d = dir.dot(w);
+        const e = rayD.dot(w);
+        const denom = 1 - b * b; // |dir|=|rayD|=1
+        if (Math.abs(denom) < 1e-9)
+            return -d; // lines parallel
+        return (b * e - d) / denom;
+    }
+    // Ray-vs-plane (point bonePos, normal n). Returns the hit point or null.
+    rayPlane(rayO, rayD, bonePos, n) {
+        const denom = rayD.dot(n);
+        if (Math.abs(denom) < 1e-6)
+            return null;
+        const t = bonePos.subtract(rayO).dot(n) / denom;
+        if (t < 0)
+            return null;
+        return rayO.add(rayD.scale(t));
+    }
+    // 2D angle of `hit` around `bonePos` in a plane spanned by (u, v). Basis vectors
+    // are snapshotted at drag start so the angle frame is stable even if the bone
+    // (and gizmo visual) rotates during the drag.
+    angleInRingPlane(hit, bonePos, u, v) {
+        const rel = hit.subtract(bonePos);
+        return Math.atan2(rel.dot(v), rel.dot(u));
+    }
     renderPickPass(encoder) {
         if (!this.pendingPick || !this.pickTexture || !this.pickDepthTexture)
             return;
@@ -2084,9 +2786,10 @@ export class Engine {
         const data = new Uint8Array(this.pickReadbackBuffer.getMappedRange());
         const modelId = data[0];
         const materialId = data[1];
+        const boneId = data[2];
         this.pickReadbackBuffer.unmap();
         if (modelId === 0) {
-            this.onRaycast("", null, screenX, screenY);
+            this.onRaycast("", null, null, screenX, screenY);
             return;
         }
         // Find model by 1-based index
@@ -2099,11 +2802,12 @@ export class Engine {
             }
             idx++;
         }
-        // Find material by 1-based index (skipping zero-vertex materials)
         let hitMaterial = null;
+        let hitBone = null;
         if (hitModel) {
             const inst = this.modelInstances.get(hitModel);
             if (inst) {
+                // Find material by 1-based index (skipping zero-vertex materials)
                 const materials = inst.model.getMaterials();
                 let matIdx = 0;
                 for (const mat of materials) {
@@ -2115,9 +2819,13 @@ export class Engine {
                         break;
                     }
                 }
+                // Bone index is 0-based (matches joints0 attribute values fed to pick shader).
+                const bones = inst.model.getSkeleton().bones;
+                if (boneId < bones.length)
+                    hitBone = bones[boneId].name;
             }
         }
-        this.onRaycast(hitModel, hitMaterial, screenX, screenY);
+        this.onRaycast(hitModel, hitMaterial, hitBone, screenX, screenY);
     }
     render() {
         if (!this.multisampleTexture || !this.camera || !this.device)
@@ -2201,14 +2909,19 @@ export class Engine {
             }
         }
         // Composite: HDR + bloom → Filmic tonemap → swapchain.
+        const swapchainView = this.context.getCurrentTexture().createView();
         const compositeAttachment = this.compositePassDescriptor.colorAttachments[0];
-        compositeAttachment.view = this.context.getCurrentTexture().createView();
+        compositeAttachment.view = swapchainView;
         const cpass = encoder.beginRenderPass(this.compositePassDescriptor);
         const compositePipeline = this.viewTransform.gamma === 1.0 ? this.compositePipelineIdentity : this.compositePipelineGamma;
         cpass.setPipeline(compositePipeline);
         cpass.setBindGroup(0, this.compositeBindGroup);
         cpass.draw(3);
         cpass.end();
+        if (this.selectedMaterial && hasModels)
+            this.renderSelectionPasses(encoder, swapchainView);
+        if (this.selectedBone && hasModels)
+            this.renderGizmoPass(encoder, swapchainView);
         const pick = this.pendingPick;
         if (pick && hasModels)
             this.renderPickPass(encoder);
@@ -2379,6 +3092,14 @@ export class Engine {
     }
 }
 Engine.instance = null;
+Engine.GIZMO_RING_SEGMENTS = 96;
+Engine.GIZMO_RING_RADIUS = 0.8;
+// Axis visible length (relative to gizmo size). Extends past ring radius so
+// the "arrow stub" sticking out of the ring is a comfortable click target.
+Engine.GIZMO_AXIS_LENGTH = 1.25;
+Engine.GIZMO_WORLD_SIZE = 1.5;
+Engine.GIZMO_THICKNESS_PX = 15.0;
+Engine.GIZMO_PICK_THRESHOLD_PX = 17.0;
 Engine.MULTISAMPLE_COUNT = 4;
 /** Stencil value stamped by eye draws so hair can stencil-test against it and
  *  alpha-blend a second pass over eye silhouette pixels (see-through-hair effect). */
@@ -2392,5 +3113,5 @@ Engine.STENCIL_EYE_VALUE = 1;
  *        cleared / edge-faded regions like before).
  *  rg8unorm at 4× MSAA is 8 bytes/texel — still fits Apple TBDR tile memory comfortably. */
 Engine.BLOOM_MASK_FORMAT = "rg8unorm";
-Engine.BLOOM_MAX_LEVELS = 7;
+Engine.BLOOM_MAX_LEVELS = 5;
 Engine.SHADOW_MAP_SIZE = 2048;