reze-engine 0.18.1 → 0.19.0

package/dist/engine.js

@@ -26,6 +26,15 @@ import { COMPOSITE_SHADER_WGSL } from "./shaders/passes/composite";
 import { PICK_SHADER_WGSL } from "./shaders/passes/pick";
 import { MIPMAP_BLIT_SHADER_WGSL } from "./shaders/passes/mipmap";
 import { compileGraph } from "./graph/compile";
+import { DEFAULT_GRAPH } from "./graph/presets/default";
+import { FACE_GRAPH } from "./graph/presets/face";
+import { HAIR_GRAPH } from "./graph/presets/hair";
+import { BODY_GRAPH } from "./graph/presets/body";
+import { EYE_GRAPH } from "./graph/presets/eye";
+import { STOCKINGS_GRAPH } from "./graph/presets/stockings";
+import { METAL_GRAPH } from "./graph/presets/metal";
+import { CLOTH_SMOOTH_GRAPH } from "./graph/presets/cloth_smooth";
+import { CLOTH_ROUGH_GRAPH } from "./graph/presets/cloth_rough";
 // Substring hints mapping common PMX material names (JP/CN/EN) to presets,
 // tried when a material isn't in the model's explicit MaterialPresetMap.
 // Ordered: more specific families first (靴下 must hit stockings before 靴
@@ -87,6 +96,21 @@ function resolvePreset(materialName, map) {
     }
     return "mmd_classic";
 }
+// Default-group recipe per preset label: the shipped graph + its natural pass-integration
+// (renderClass, alphaMode). This is the auto-default-groups mapping (docs §8) — the same
+// label→integration knowledge the old fixed slots encoded, now producing editable groups.
+// mmd_classic has no entry — those materials stay ungrouped (hand-shader path).
+const PRESET_GROUP_INFO = {
+    default: { graph: DEFAULT_GRAPH, renderClass: "auto", alphaMode: "opaque" },
+    face: { graph: FACE_GRAPH, renderClass: "auto", alphaMode: "opaque" },
+    hair: { graph: HAIR_GRAPH, renderClass: "hair", alphaMode: "opaque" },
+    body: { graph: BODY_GRAPH, renderClass: "auto", alphaMode: "opaque" },
+    eye: { graph: EYE_GRAPH, renderClass: "eye", alphaMode: "opaque" },
+    stockings: { graph: STOCKINGS_GRAPH, renderClass: "auto", alphaMode: "hashed" },
+    metal: { graph: METAL_GRAPH, renderClass: "auto", alphaMode: "opaque" },
+    cloth_smooth: { graph: CLOTH_SMOOTH_GRAPH, renderClass: "auto", alphaMode: "opaque" },
+    cloth_rough: { graph: CLOTH_ROUGH_GRAPH, renderClass: "auto", alphaMode: "opaque" },
+};
 // Map a WGSL compile-error line back to the graph node whose `let` produced it —
 // the compiler tags every generated line with a trailing `// @node:<id>` marker.
 function nodeIdForWgslLine(wgsl, lineNum) {
@@ -133,16 +157,6 @@ export class Engine {
         this.lightCount = 0;
         this.resizeObserver = null;
         this.resizePending = false;
-        // ── Style graph runtime (graph/ compiler output applied to preset slots) ──
-        // Per-slot 256 B StyleUniforms buffers (group(2) binding(4)). Created eagerly so
-        // material bind groups can reference them at model-load time regardless of whether
-        // a graph is ever applied; mmd_classic materials bind the shared zero buffer.
-        this.styleBuffers = new Map();
-        // Applied graphs: slot → swapped pipeline(s) + the slider→UBO map for setStyleParam.
-        this.styleOverrides = new Map();
-        // Per-slot generation counter — an async compile that finishes after a newer
-        // applyStyleGraph/resetStyleSlot call on the same slot is discarded (stale guard).
-        this.styleGenerations = new Map();
         this.selectedMaterial = null;
         // ─── Transform gizmo ───────────────────────────────────────────────
         this.selectedBone = null;
@@ -940,30 +954,13 @@ export class Engine {
                 { binding: 4, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
             ],
         });
-        // Per-slot style buffers + shared zero buffer (mmd_classic / never-styled slots).
+        // Shared zero StyleUniforms buffer — bound by every ungrouped material; grouped
+        // materials rebind binding(4) to their group's own buffer (per model, per group).
         this.zeroStyleBuffer = this.device.createBuffer({
             label: "style uniforms (zero)",
             size: 256,
             usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
         });
-        const ALL_PRESETS = [
-            "default",
-            "face",
-            "hair",
-            "body",
-            "eye",
-            "stockings",
-            "metal",
-            "cloth_smooth",
-            "cloth_rough",
-        ];
-        for (const preset of ALL_PRESETS) {
-            this.styleBuffers.set(preset, this.device.createBuffer({
-                label: `style uniforms (${preset})`,
-                size: 256,
-                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
-            }));
-        }
         const mainPipelineLayout = this.device.createPipelineLayout({
             label: "main pipeline layout",
             bindGroupLayouts: [
@@ -2143,6 +2140,7 @@ export class Engine {
             bindGroup: this.groundShadowBindGroup,
             materialName: "Ground",
             preset: "cloth_rough",
+            groupId: null,
         };
     }
     updateLightBuffer() {
@@ -2189,12 +2187,14 @@ export class Engine {
             this.resizeObserver.disconnect();
             this.resizeObserver = null;
         }
-        // Style graph runtime: per-slot uniform buffers + swapped pipelines (pipelines
-        // are GC'd; buffers need explicit destroy).
-        this.styleOverrides.clear();
-        for (const buf of this.styleBuffers.values())
-            buf.destroy();
-        this.styleBuffers.clear();
+        // Style group runtime: per-group uniform buffers (pipelines are GC'd; buffers need
+        // explicit destroy). Per-model group buffers are torn down in removeModel; the shared
+        // zero buffer is engine-owned.
+        this.forEachInstance((inst) => {
+            for (const install of inst.styleGroups.values())
+                install.uniformBuffer.destroy();
+            inst.styleGroups.clear();
+        });
         this.zeroStyleBuffer?.destroy();
     }
     async loadModel(nameOrPath, pathOrOptions) {
@@ -2246,6 +2246,9 @@ export class Engine {
         for (const buf of inst.gpuBuffers) {
             buf.destroy();
         }
+        // Per-group StyleUniforms buffers aren't in gpuBuffers (allocated post-load).
+        for (const install of inst.styleGroups.values())
+            install.uniformBuffer.destroy();
         this.modelInstances.delete(name);
     }
     getModelNames() {
@@ -2291,18 +2294,15 @@ export class Engine {
         if (!inst)
             return;
         inst.materialPresets = presets;
-        for (const dc of inst.drawCalls) {
-            const preset = resolvePreset(dc.materialName, presets);
-            if (preset === dc.preset)
-                continue;
-            dc.preset = preset;
-            // Rebind so binding(4) follows the new slot's style buffer.
-            if (dc.baseBindGroupEntries)
-                dc.bindGroup = this.createMaterialBindGroup(`material: ${dc.materialName}`, dc.baseBindGroupEntries, preset);
-        }
-    }
-    createMaterialBindGroup(label, baseEntries, preset) {
-        const styleBuffer = preset === "mmd_classic" ? this.zeroStyleBuffer : this.styleBuffers.get(preset);
+        // Only updates the ungrouped fallback preset; grouped materials render via their
+        // group regardless. binding(4) is unaffected (ungrouped always binds the zero
+        // buffer; grouped bindings are owned by applyStyleGroups).
+        for (const dc of inst.drawCalls)
+            dc.preset = resolvePreset(dc.materialName, presets);
+    }
+    // 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).
+    createMaterialBindGroup(label, baseEntries, styleBuffer) {
         return this.device.createBindGroup({
             label,
             layout: this.mainPerMaterialBindGroupLayout,
@@ -2517,6 +2517,9 @@ export class Engine {
             physics,
             vertexBufferNeedsUpdate: false,
             gpuMorph,
+            styleGroups: new Map(),
+            materialToGroup: new Map(),
+            styleGroupGen: new Map(),
         };
         await this.setupMaterialsForInstance(inst);
         this.modelInstances.set(name, inst);
@@ -2757,7 +2760,8 @@ export class Engine {
                 { binding: 2, resource: (toonTexture ?? this.fallbackMaterialTexture).createView() },
                 { binding: 3, resource: (sphereTexture ?? this.fallbackMaterialTexture).createView() },
             ];
-            const bindGroup = this.createMaterialBindGroup(`${prefix}material: ${mat.name}`, baseBindGroupEntries, preset);
+            // Ungrouped at load — binding(4) = zero buffer. applyStyleGroups rebinds grouped ones.
+            const bindGroup = this.createMaterialBindGroup(`${prefix}material: ${mat.name}`, baseBindGroupEntries, this.zeroStyleBuffer);
             const type = isTransparent ? "transparent" : "opaque";
             inst.drawCalls.push({
                 type,
@@ -2766,6 +2770,7 @@ export class Engine {
                 bindGroup,
                 materialName: mat.name,
                 preset,
+                groupId: null,
                 baseBindGroupEntries,
             });
             if ((mat.edgeFlag & 0x10) !== 0 && mat.edgeSize > 0) {
@@ -2794,6 +2799,7 @@ export class Engine {
                     bindGroup: outlineBindGroup,
                     materialName: mat.name,
                     preset,
+                    groupId: null,
                 });
             }
             if (this.onRaycast) {
@@ -2809,30 +2815,14 @@ export class Engine {
             }
             currentIndexOffset += indexCount;
         }
-        // Sort so the opaque bucket is emitted in the order the stencil-based
-        // see-through-hair effect requires: {non-hair, non-eye} → {eye} → {hair}.
-        // Eye writes stencil=EYE_VALUE; hair's pipeline stencil-tests "not equal" so
-        // it skips eye pixels; a follow-up hairOverEyes pass (see renderOneModel)
-        // re-fills those skipped pixels alpha-blended. Array.sort is stable in
-        // ES2019+, so within a bucket the PMX material order is preserved.
-        const typeOrder = {
-            opaque: 0,
-            "opaque-outline": 1,
-            transparent: 2,
-            "transparent-outline": 3,
-            ground: 4,
-        };
-        const presetRank = (p) => (p === "hair" ? 2 : p === "eye" ? 1 : 0);
-        inst.drawCalls.sort((a, b) => {
-            const ta = typeOrder[a.type] - typeOrder[b.type];
-            if (ta !== 0)
-                return ta;
-            return presetRank(a.preset) - presetRank(b.preset);
-        });
-        for (const d of inst.drawCalls) {
-            if (d.type === "opaque")
-                inst.shadowDrawCalls.push(d);
-        }
+        // Sort so the opaque bucket is emitted in the order the stencil-based see-through-hair
+        // effect requires: {non-hair, non-eye} → {eye} → {hair}. Eye writes stencil=EYE_VALUE;
+        // hair stencil-tests "not equal" and skips eye pixels; the follow-up hairOverEyes pass
+        // re-fills them alpha-blended. sortDrawCalls also (re)builds shadowDrawCalls. All draws
+        // are ungrouped at setup, so the rank comes from the preset; applyStyleGroups re-sorts
+        // by render-class when groups are assigned. Array.sort is stable → PMX order preserved
+        // within a bucket.
+        this.sortDrawCalls(inst);
     }
     createMaterialUniformBuffer(label, mat, sphereMode, headBoneIndex) {
         // Matches the WGSL MaterialUniforms struct in common.ts — 64 bytes
@@ -3401,35 +3391,192 @@ export class Engine {
                 sp.drawIndexed(draw.count, 1, draw.firstIndex, 0, 0);
         }
     }
-    // ─── Style graph API ──────────────────────────────────────────────
-    // Two-tier edit model: applyStyleGraph = topology tier (async compile + pipeline
-    // swap, previous look keeps rendering until the new pipeline is ready or on any
-    // error); setStyleParam = adjust tier (uniform write, instant, no pipeline touch).
+    // ─── Style group API ──────────────────────────────────────────────
+    // Two-tier edits: applyStyleGroups/upsert = topology (async compile + pipeline swap,
+    // fallback-on-error, per-group stale guard); setStyleParam = adjust (instant uniform
+    // write). Overlay-first: grouped materials render via their group's compiled graph;
+    // ungrouped ones keep the hand-written preset path. See docs/style-groups-spec.md.
+    /** Read a model's current style groups (including auto-created defaults) for editor
+     *  round-trip. The host owns group state; this is bootstrap/read, not a second store. */
+    getStyleGroups(modelName) {
+        const inst = this.modelInstances.get(modelName);
+        if (!inst)
+            return [];
+        return [...inst.styleGroups.values()].map((g) => g.group);
+    }
+    /**
+     * Create default style groups from the model's material→preset resolution
+     * (`setMaterialPresets` map first, then name hints), so a freshly loaded model comes up
+     * editably grouped with zero interaction. Materials resolving to `mmd_classic` (no map
+     * entry, no hint) stay ungrouped. The returned promise resolves after grouping AND the
+     * async graph compiles, so `getStyleGroups` is populated the moment it resolves. Opt-in:
+     * call it explicitly (typically after `setMaterialPresets`); a bare load stays ungrouped
+     * / byte-identical to before.
+     */
+    async autoStyleGroups(modelName) {
+        const inst = this.modelInstances.get(modelName);
+        if (!inst)
+            return { ok: false, groups: [], unknownMaterials: [], conflicts: [] };
+        const buckets = new Map();
+        for (const dc of inst.drawCalls) {
+            if (!dc.baseBindGroupEntries)
+                continue; // material draw calls only (skip outlines)
+            const preset = resolvePreset(dc.materialName, inst.materialPresets);
+            if (preset === "mmd_classic")
+                continue; // unmatched → ungrouped
+            const arr = buckets.get(preset) ?? [];
+            if (!arr.includes(dc.materialName))
+                arr.push(dc.materialName);
+            buckets.set(preset, arr);
+        }
+        const groups = [];
+        for (const [preset, materials] of buckets) {
+            const info = PRESET_GROUP_INFO[preset];
+            if (!info)
+                continue;
+            groups.push({
+                id: preset,
+                label: info.graph.name,
+                materials,
+                graph: info.graph,
+                renderClass: info.renderClass,
+                alphaMode: info.alphaMode,
+            });
+        }
+        return this.applyStyleGroups(modelName, groups);
+    }
     /**
-     * Compile a style graph and swap it onto its preset slot. Fallback-on-error: the
-     * slot's current pipeline keeps rendering unless compilation fully succeeds.
-     * Slider defaults are written to the slot's StyleUniforms buffer on success.
+     * Replace a model's full style-group set. Unchanged groups (same graph + renderClass +
+     * alphaMode) keep their pipeline; new/changed ones compile and swap; removed ones are
+     * torn down and their materials revert to the ungrouped hand-shader path. A group whose
+     * compile fails is not installed and its materials stay ungrouped (fallback-on-error).
      */
-    async applyStyleGraph(graph, opts) {
-        const result = compileGraph(graph, opts);
+    async applyStyleGroups(modelName, groups) {
+        const inst = this.modelInstances.get(modelName);
+        if (!inst)
+            return { ok: false, groups: [], unknownMaterials: [], conflicts: [] };
+        // Whole-set validation: material claims (last group in array order wins), unknowns.
+        const modelMaterials = new Set(inst.drawCalls.map((d) => d.materialName));
+        const claimed = new Map();
+        const conflicts = new Set();
+        const unknownMaterials = new Set();
+        for (const g of groups) {
+            for (const m of g.materials) {
+                if (!modelMaterials.has(m))
+                    unknownMaterials.add(m);
+                if (claimed.has(m))
+                    conflicts.add(m);
+                claimed.set(m, g.id);
+            }
+        }
+        // Tear down installs no longer present.
+        const nextIds = new Set(groups.map((g) => g.id));
+        for (const [id, install] of inst.styleGroups) {
+            if (!nextIds.has(id)) {
+                inst.styleGroupGen.set(id, (inst.styleGroupGen.get(id) ?? 0) + 1);
+                install.uniformBuffer.destroy();
+                inst.styleGroups.delete(id);
+            }
+        }
+        const groupResults = [];
+        for (const g of groups) {
+            const r = await this.compileAndInstallGroup(inst, g);
+            groupResults.push({ groupId: g.id, diagnostics: r.diagnostics, ok: r.ok });
+        }
+        this.assignDrawCallGroups(inst, claimed);
+        return {
+            ok: groupResults.every((r) => r.ok),
+            groups: groupResults,
+            unknownMaterials: [...unknownMaterials],
+            conflicts: [...conflicts],
+        };
+    }
+    /** Add or replace a single style group by id. `opts` may carry a `previewNode` for the
+     *  editor's node-output preview workflow. */
+    async upsertStyleGroup(modelName, group, opts) {
+        const inst = this.modelInstances.get(modelName);
+        if (!inst)
+            return { ok: false, diagnostics: [{ severity: "error", message: `unknown model "${modelName}"` }], slotMap: [] };
+        const r = await this.compileAndInstallGroup(inst, group, opts);
+        this.assignDrawCallGroups(inst, this.currentClaims(inst));
+        return r;
+    }
+    /** Remove a style group; its materials revert to the ungrouped hand-shader path. */
+    removeStyleGroup(modelName, groupId) {
+        const inst = this.modelInstances.get(modelName);
+        const install = inst?.styleGroups.get(groupId);
+        if (!inst || !install)
+            return;
+        inst.styleGroupGen.set(groupId, (inst.styleGroupGen.get(groupId) ?? 0) + 1); // discard in-flight compile
+        install.uniformBuffer.destroy();
+        inst.styleGroups.delete(groupId);
+        this.assignDrawCallGroups(inst, this.currentClaims(inst));
+    }
+    /** Clear all style groups on a model — every material returns to the hand-shader path. */
+    resetStyleGroups(modelName) {
+        const inst = this.modelInstances.get(modelName);
+        if (!inst)
+            return;
+        for (const [id, install] of inst.styleGroups) {
+            inst.styleGroupGen.set(id, (inst.styleGroupGen.get(id) ?? 0) + 1);
+            install.uniformBuffer.destroy();
+        }
+        inst.styleGroups.clear();
+        this.assignDrawCallGroups(inst, new Map());
+    }
+    /** Instant adjust-tier write: set one exposed slider on a group's applied graph. */
+    setStyleParam(modelName, groupId, paramId, value) {
+        const install = this.modelInstances.get(modelName)?.styleGroups.get(groupId);
+        const styleSlot = install?.slotMap.find((s) => s.id === paramId);
+        if (!install || !styleSlot)
+            return false;
+        if (styleSlot.kind === "float") {
+            if (typeof value !== "number")
+                return false;
+            const offset = styleSlot.vec4Index * 16 + ["x", "y", "z", "w"].indexOf(styleSlot.component) * 4;
+            this.device.queue.writeBuffer(install.uniformBuffer, offset, new Float32Array([value]));
+        }
+        else {
+            if (typeof value === "number")
+                return false;
+            this.device.queue.writeBuffer(install.uniformBuffer, styleSlot.vec4Index * 16, new Float32Array(value));
+        }
+        return true;
+    }
+    // Materials claimed by the model's currently-installed groups (for upsert/remove paths;
+    // applyStyleGroups derives claims from its input array instead).
+    currentClaims(inst) {
+        const claimed = new Map();
+        for (const install of inst.styleGroups.values())
+            for (const m of install.group.materials)
+                claimed.set(m, install.group.id);
+        return claimed;
+    }
+    // Compile a group's graph → WGSL → pipeline(s), install keyed by group id. Reuses the
+    // install (pipeline + uniform buffer) when the graph/integration is byte-unchanged.
+    async compileAndInstallGroup(inst, group, opts) {
+        const renderClass = group.renderClass ?? "auto";
+        const alphaMode = group.alphaMode ?? "opaque";
+        const signature = JSON.stringify({ g: group.graph, rc: renderClass, am: alphaMode, o: opts?.previewNode ?? null });
+        const existing = inst.styleGroups.get(group.id);
+        if (existing && existing.signature === signature) {
+            existing.group = group; // refresh def (label/materials) without recompiling
+            return { ok: true, diagnostics: [], slotMap: existing.slotMap };
+        }
+        const result = compileGraph(group.graph, { ...opts, renderClass, alphaMode });
         if (!result.ok)
             return { ok: false, diagnostics: result.diagnostics, slotMap: result.slotMap };
-        const slot = graph.slot;
-        const generation = (this.styleGenerations.get(slot) ?? 0) + 1;
-        this.styleGenerations.set(slot, generation);
+        const generation = (inst.styleGroupGen.get(group.id) ?? 0) + 1;
+        inst.styleGroupGen.set(group.id, generation);
         this.device.pushErrorScope("validation");
-        const module = this.device.createShaderModule({ label: `style graph: ${graph.name} (${slot})`, code: result.wgsl });
+        const module = this.device.createShaderModule({ label: `style group: ${group.id} (${renderClass})`, code: result.wgsl });
         const info = await module.getCompilationInfo();
         const scopeError = await this.device.popErrorScope();
         const diagnostics = [...result.diagnostics];
         for (const msg of info.messages) {
             if (msg.type !== "error")
                 continue;
-            diagnostics.push({
-                severity: "error",
-                nodeId: nodeIdForWgslLine(result.wgsl, msg.lineNum),
-                message: `WGSL: ${msg.message}`,
-            });
+            diagnostics.push({ severity: "error", nodeId: nodeIdForWgslLine(result.wgsl, msg.lineNum), message: `WGSL: ${msg.message}` });
         }
         if (diagnostics.some((d) => d.severity === "error") || scopeError) {
             if (scopeError && !diagnostics.some((d) => d.severity === "error"))
@@ -3439,52 +3586,61 @@ export class Engine {
         let pipeline;
         let overEyesPipeline;
         try {
-            pipeline = await this.createSlotPipeline(slot, module, false);
-            if (slot === "hair")
-                overEyesPipeline = await this.createSlotPipeline(slot, module, true);
+            pipeline = await this.createRenderClassPipeline(renderClass, module, false);
+            if (renderClass === "hair")
+                overEyesPipeline = await this.createRenderClassPipeline(renderClass, module, true);
         }
         catch (e) {
             diagnostics.push({ severity: "error", message: `pipeline creation failed: ${e.message}` });
             return { ok: false, diagnostics, slotMap: result.slotMap };
         }
-        // A newer apply/reset on this slot finished (or started) while we compiled.
-        if (this.styleGenerations.get(slot) !== generation) {
+        // Stale guard: a newer compile/remove for this id happened while we awaited.
+        if (inst.styleGroupGen.get(group.id) !== generation) {
             diagnostics.push({ severity: "warning", message: "superseded by a newer edit — result discarded" });
             return { ok: false, diagnostics, slotMap: result.slotMap };
         }
-        this.styleOverrides.set(slot, { pipeline, overEyesPipeline, slotMap: result.slotMap });
-        this.writeStyleDefaults(slot, graph, result.slotMap);
+        const uniformBuffer = existing?.uniformBuffer ??
+            this.device.createBuffer({
+                label: `style uniforms: ${group.id}`,
+                size: 256,
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            });
+        inst.styleGroups.set(group.id, {
+            group,
+            renderClass,
+            alphaMode,
+            pipeline,
+            overEyesPipeline,
+            uniformBuffer,
+            slotMap: result.slotMap,
+            signature,
+        });
+        this.writeGroupDefaults(uniformBuffer, group, result.slotMap);
         return { ok: true, diagnostics, slotMap: result.slotMap };
     }
-    /** Instant adjust-tier write: set one exposed slider on the slot's applied graph. */
-    setStyleParam(slot, paramId, value) {
-        const override = this.styleOverrides.get(slot);
-        const styleSlot = override?.slotMap.find((s) => s.id === paramId);
-        const buffer = this.styleBuffers.get(slot);
-        if (!styleSlot || !buffer)
-            return false;
-        if (styleSlot.kind === "float") {
-            if (typeof value !== "number")
-                return false;
-            const offset = styleSlot.vec4Index * 16 + ["x", "y", "z", "w"].indexOf(styleSlot.component) * 4;
-            this.device.queue.writeBuffer(buffer, offset, new Float32Array([value]));
-        }
-        else {
-            if (typeof value === "number")
-                return false;
-            this.device.queue.writeBuffer(buffer, styleSlot.vec4Index * 16, new Float32Array(value));
+    // Rebind each material draw call to its (successfully-installed) group's uniform buffer,
+    // or the zero buffer when ungrouped, then re-sort by render-class draw order.
+    assignDrawCallGroups(inst, claimed) {
+        inst.materialToGroup.clear();
+        for (const dc of inst.drawCalls) {
+            if (!dc.baseBindGroupEntries)
+                continue; // outlines/ground are never grouped
+            const wantId = claimed.get(dc.materialName);
+            const install = wantId ? inst.styleGroups.get(wantId) : undefined;
+            const groupId = install ? wantId : null;
+            if (groupId)
+                inst.materialToGroup.set(dc.materialName, groupId);
+            if (dc.groupId === groupId)
+                continue;
+            dc.groupId = groupId;
+            dc.bindGroup = this.createMaterialBindGroup(`material: ${dc.materialName}`, dc.baseBindGroupEntries, install ? install.uniformBuffer : this.zeroStyleBuffer);
         }
-        return true;
+        this.sortDrawCalls(inst);
     }
-    /** Remove an applied style graph — the slot returns to its built-in preset shader. */
-    resetStyleSlot(slot) {
-        this.styleGenerations.set(slot, (this.styleGenerations.get(slot) ?? 0) + 1);
-        this.styleOverrides.delete(slot);
-    }
-    writeStyleDefaults(slot, graph, slotMap) {
+    writeGroupDefaults(buffer, group, slotMap) {
         const data = new Float32Array(64); // 16 vec4f
         for (const styleSlot of slotMap) {
-            const param = graph.params?.find((p) => p.id === styleSlot.id);
+            const param = group.graph.params?.find((p) => p.id === styleSlot.id);
             if (!param)
                 continue;
             const base = styleSlot.vec4Index * 4;
@@ -3495,19 +3651,38 @@ export class Engine {
                 data.set(param.default.slice(0, 3), base);
             }
         }
-        this.device.queue.writeBuffer(this.styleBuffers.get(slot), 0, data);
+        this.device.queue.writeBuffer(buffer, 0, data);
+    }
+    // Draw-order rank within a bucket: eye stamps before hair reads. A grouped call ranks by
+    // its group's render-class; an ungrouped call by its preset (the hand-shader path).
+    drawCallRank(inst, dc) {
+        const rc = dc.groupId ? (inst.styleGroups.get(dc.groupId)?.renderClass ?? "auto") : undefined;
+        if (rc)
+            return rc === "hair" ? 2 : rc === "eye" ? 1 : 0;
+        return dc.preset === "hair" ? 2 : dc.preset === "eye" ? 1 : 0;
+    }
+    sortDrawCalls(inst) {
+        const typeOrder = {
+            opaque: 0,
+            "opaque-outline": 1,
+            transparent: 2,
+            "transparent-outline": 3,
+            ground: 4,
+        };
+        inst.drawCalls.sort((a, b) => typeOrder[a.type] - typeOrder[b.type] || this.drawCallRank(inst, a) - this.drawCallRank(inst, b));
+        inst.shadowDrawCalls = inst.drawCalls.filter((d) => d.type === "opaque");
     }
     /**
-     * Slot pipeline states mirror createPipelines exactly — a compiled graph swaps the
-     * fragment shading of a slot, never its pass integration (stencil interplay, depth
-     * bias, cull mode stay slot-owned; see docs/graph-compiler-spec.md §6).
+     * Render-class pipeline state. A group's compiled graph swaps the fragment shading; the
+     * render-class owns pass integration (stencil interplay, depth bias, cull). auto = plain;
+     * eye = stamp + front cull + bias; hair = stencil-test (+ the over-eyes variant).
      */
-    createSlotPipeline(slot, module, overEyes) {
+    createRenderClassPipeline(renderClass, module, overEyes) {
         const base = {
-            label: `style ${slot}${overEyes ? " (over eyes)" : ""}`,
+            label: `style ${renderClass}${overEyes ? " (over eyes)" : ""}`,
             layout: this.mainPipelineLayout,
             vertex: { module, buffers: this.fullVertexBufferLayouts },
-            primitive: { cullMode: (slot === "eye" ? "front" : "none") },
+            primitive: { cullMode: (renderClass === "eye" ? "front" : "none") },
             multisample: { count: Engine.MULTISAMPLE_COUNT },
         };
         const plainDepth = {
@@ -3517,7 +3692,7 @@ export class Engine {
         };
         let depthStencil = plainDepth;
         let constants;
-        if (slot === "hair" && !overEyes) {
+        if (renderClass === "hair" && !overEyes) {
             depthStencil = {
                 ...plainDepth,
                 stencilFront: { compare: "not-equal", failOp: "keep", depthFailOp: "keep", passOp: "keep" },
@@ -3526,7 +3701,7 @@ export class Engine {
                 stencilWriteMask: 0,
             };
         }
-        else if (slot === "hair" && overEyes) {
+        else if (renderClass === "hair" && overEyes) {
             constants = { IS_OVER_EYES: 1 };
             depthStencil = {
                 format: "depth24plus-stencil8",
@@ -3538,7 +3713,7 @@ export class Engine {
                 stencilWriteMask: 0,
             };
         }
-        else if (slot === "eye") {
+        else if (renderClass === "eye") {
             depthStencil = {
                 ...plainDepth,
                 depthBias: -0.00005,
@@ -3556,12 +3731,17 @@ export class Engine {
             depthStencil,
         });
     }
+    // Pipeline for a material draw call: its group's compiled pipeline when grouped, else
+    // the built-in preset (hand-shader) pipeline.
+    pipelineForDrawCall(inst, dc) {
+        if (dc.groupId) {
+            const install = inst.styleGroups.get(dc.groupId);
+            if (install)
+                return install.pipeline;
+        }
+        return this.pipelineForPreset(dc.preset);
+    }
     pipelineForPreset(preset) {
-        // Applied style graph wins over the built-in preset shader (mmd_classic is never
-        // in the override map — it's not a stylable slot).
-        const override = this.styleOverrides.get(preset);
-        if (override)
-            return override.pipeline;
         if (preset === "face")
             return this.facePipeline;
         if (preset === "hair")
@@ -3599,7 +3779,7 @@ export class Engine {
                 pass.setBindGroup(1, inst.mainPerInstanceBindGroup);
                 bound = true;
             }
-            const pipeline = this.pipelineForPreset(draw.preset);
+            const pipeline = this.pipelineForDrawCall(inst, draw);
             if (pipeline !== currentPipeline) {
                 pass.setPipeline(pipeline);
                 currentPipeline = pipeline;
@@ -3650,26 +3830,41 @@ export class Engine {
         this.drawOutlines(pass, inst, "transparent-outline");
     }
     /**
-     * Second hair pass for the see-through-hair effect. Re-draws every hair opaque
-     * draw using `hairOverEyesPipeline` — which stencil-matches `EYE_VALUE` and runs
-     * the hair shader with `IS_OVER_EYES=true` so alpha is scaled to 25%. depthWriteEnabled
-     * is off, so the eye's depth stays authoritative for anything drawn after.
+     * Second hair pass for the see-through-hair effect. Re-draws every hair-class opaque
+     * draw with its over-eyes pipeline — stencil-matched to `EYE_VALUE`, `IS_OVER_EYES=true`
+     * (25% alpha), depth-write off. Covers both grouped hair-class draws (their compiled
+     * over-eyes pipeline) and ungrouped hair-preset draws (the hand `hairOverEyesPipeline`).
      */
     drawHairOverEyes(pass, inst) {
         let bound = false;
+        let currentPipeline = null;
         for (const draw of inst.drawCalls) {
-            if (draw.type !== "opaque" || draw.preset !== "hair" || !this.shouldRenderDrawCall(inst, draw))
+            if (draw.type !== "opaque" || !this.shouldRenderDrawCall(inst, draw))
+                continue;
+            const overEyes = this.overEyesPipelineFor(inst, draw);
+            if (!overEyes)
                 continue;
             if (!bound) {
-                pass.setPipeline(this.styleOverrides.get("hair")?.overEyesPipeline ?? this.hairOverEyesPipeline);
                 pass.setBindGroup(0, this.perFrameBindGroup);
                 pass.setBindGroup(1, inst.mainPerInstanceBindGroup);
                 bound = true;
             }
+            if (overEyes !== currentPipeline) {
+                pass.setPipeline(overEyes);
+                currentPipeline = overEyes;
+            }
             pass.setBindGroup(2, draw.bindGroup);
             pass.drawIndexed(draw.count, 1, draw.firstIndex, 0, 0);
         }
     }
+    // The over-eyes pipeline for a hair draw call, or null if it isn't hair-class.
+    overEyesPipelineFor(inst, dc) {
+        if (dc.groupId) {
+            const install = inst.styleGroups.get(dc.groupId);
+            return install?.renderClass === "hair" ? (install.overEyesPipeline ?? null) : null;
+        }
+        return dc.preset === "hair" ? this.hairOverEyesPipeline : null;
+    }
     updateCameraUniforms() {
         const viewMatrix = this.camera.getViewMatrix();
         const projectionMatrix = this.camera.getProjectionMatrix();