reze-engine 0.18.0 → 0.19.0

package/src/graph/compile.ts

@@ -8,6 +8,7 @@ import type { Diagnostic, ExposedParam, GraphNode, SocketValue, StyleGraph } fro
 import { NODE_REGISTRY, canConvert, convert, fmtValue, literalFits } from "./registry"
 import type { NodeSpec, SockT } from "./registry"
 import { assembleModule } from "./slots"
+import type { AlphaMode, RenderClass } from "./render-class"
 
 export type CompileOptions = {
   /** Fold exposed params to their defaults as consts (no StyleUniforms binding).
@@ -16,6 +17,11 @@ export type CompileOptions = {
   /** Override the graph output with any node's socket — Blender's node-preview
    *  (Ctrl+Shift+Click viewer) workflow for the editor. */
   previewNode?: { node: string; socket: string }
+  /** Pass-integration class the fs() shell is assembled for (stencil/cull/gate). The
+   *  graph is pure shading; the group supplies this. Default "auto". */
+  renderClass?: RenderClass
+  /** Alpha-handling axis, orthogonal to renderClass. Default "opaque". */
+  alphaMode?: AlphaMode
 }
 
 /** UBO slot for one exposed param: write `value` at style.p[vec4Index] (+ component). */
@@ -337,6 +343,6 @@ export function compileGraph(graph: StyleGraph, opts: CompileOptions = {}): Comp
   lines.push(`  let final_color = ${outputExpr(out, "color")}; // @node:${out.node}`)
 
   const fsBody = lines.join("\n")
-  const wgsl = assembleModule(graph.slot, fsBody, usesStyle.current)
+  const wgsl = assembleModule(opts.renderClass ?? "auto", opts.alphaMode ?? "opaque", fsBody, usesStyle.current)
   return { ok: true, wgsl, fsBody, slotMap, diagnostics, prunedNodes }
 }

package/src/graph/presets/body.ts

@@ -8,7 +8,7 @@ import type { StyleGraph } from "../schema"
 export const BODY_GRAPH: StyleGraph = {
   version: 1,
   name: "Body",
-  slot: "body",
+  tags: ["body"],
   nodes: [
     { id: "tex", type: "texture" },
     { id: "geo", type: "geometry" },

package/src/graph/presets/cloth_rough.ts

@@ -8,7 +8,7 @@ import type { StyleGraph } from "../schema"
 export const CLOTH_ROUGH_GRAPH: StyleGraph = {
   version: 1,
   name: "Rough Cloth",
-  slot: "cloth_rough",
+  tags: ["cloth_rough"],
   nodes: [
     { id: "tex", type: "texture" },
     { id: "geo", type: "geometry" },

package/src/graph/presets/cloth_smooth.ts

@@ -8,7 +8,7 @@ import type { StyleGraph } from "../schema"
 export const CLOTH_SMOOTH_GRAPH: StyleGraph = {
   version: 1,
   name: "Smooth Cloth",
-  slot: "cloth_smooth",
+  tags: ["cloth_smooth"],
   nodes: [
     { id: "tex", type: "texture" },
     { id: "geo", type: "geometry" },

package/src/graph/presets/default.ts

@@ -9,7 +9,7 @@ import type { StyleGraph } from "../schema"
 export const DEFAULT_GRAPH: StyleGraph = {
   version: 1,
   name: "Principled BSDF",
-  slot: "default",
+  tags: ["default"],
   nodes: [
     { id: "tex", type: "texture" },
     {

package/src/graph/presets/eye.ts

@@ -0,0 +1,33 @@
+// Eye as a StyleGraph — port of shaders/materials/eye.ts. The published preset
+// author's instruction: "keep eyes in the default nodegraph, add emission 1.5".
+// So it's the default Principled BSDF plus an Emission of the diffuse texture at
+// 1.5× (Blender's Principled Emission socket, decomposed as a separate Emission +
+// Add Shader — the emission feeds bloom pre-tonemap).
+//
+// The rear-view gate and the see-through stencil stamp are slot-owned (built-in eye
+// behavior, see EYE_TEMPLATE in slots.ts + createSlotPipeline) — not in this graph.
+
+import type { StyleGraph } from "../schema"
+
+export const EYE_GRAPH: StyleGraph = {
+  version: 1,
+  name: "Eye",
+  tags: ["eye"],
+  nodes: [
+    { id: "tex", type: "texture" },
+    {
+      id: "principled",
+      type: "principled",
+      inputs: { metallic: 0.0, specular: 0.5, roughness: 0.5, spec_clamp: 1e30, sheen: 0.0, sheen_tint: 0.0 },
+    },
+    { id: "emission", type: "emission", inputs: { strength: 1.5 } },
+    { id: "add", type: "add_shader" },
+  ],
+  links: [
+    { from: { node: "tex", socket: "color" }, to: { node: "principled", socket: "base" } },
+    { from: { node: "tex", socket: "color" }, to: { node: "emission", socket: "color" } },
+    { from: { node: "principled", socket: "color" }, to: { node: "add", socket: "a" } },
+    { from: { node: "emission", socket: "color" }, to: { node: "add", socket: "b" } },
+  ],
+  output: { node: "add", socket: "color" },
+}

package/src/graph/presets/face.ts

@@ -0,0 +1,136 @@
+// M_Face as a StyleGraph — port of shaders/materials/face.ts (仿深空之眼 "M_Face").
+// Toon + warm rim + dual fresnel rim + BT.601 bright-tex gate, mixed 50/50 against a
+// Principled BSDF with noise bump. Structurally close to body, but: the toon uses the
+// edge-AA ramp, hue tints are 0.46 (full hue_sat, not the 0.5 _id specialization),
+// rim2 is the hair-style fresnel×layer_weight_fresnel rim, and there's an extra
+// near-white texture gate that emits (freckle/highlight paint). Plain material — no
+// built-in slot effect, so it uses the default prelude/epilogue.
+
+import type { StyleGraph } from "../schema"
+
+export const FACE_GRAPH: StyleGraph = {
+  version: 1,
+  name: "Face",
+  tags: ["face"],
+  nodes: [
+    { id: "tex", type: "texture" },
+    { id: "geo", type: "geometry" },
+
+    // ── toon shading ──
+    { id: "str", type: "shader_to_rgb_diffuse" },
+    { id: "toon", type: "ramp_constant_aa", inputs: { edge: 0.2966 } },
+    { id: "shadow_tint", type: "hue_sat", inputs: { hue: 0.46000000834465027, saturation: 2.0, value: 0.3499999940395355, fac: 1.0 } },
+    { id: "lit_tint", type: "hue_sat", inputs: { hue: 0.46000000834465027, saturation: 1.600000023841858, value: 1.5, fac: 1.0 } },
+    { id: "toon_color", type: "mix/blend" },
+    { id: "bc", type: "bright_contrast", inputs: { bright: 0.1, contrast: 0.2 } },
+    { id: "emission3", type: "emission", inputs: { strength: 2.5 } },
+
+    // ── warm rim (toon*0.5+0.5 → cardinal ramp) ──
+    { id: "warm_mul", type: "math/multiply", inputs: { b: 0.5 } },
+    { id: "warm_add", type: "math/add", inputs: { b: 0.5 } },
+    { id: "warm_clamp", type: "math/clamp01" },
+    {
+      id: "warm_ramp",
+      type: "ramp_cardinal",
+      inputs: {
+        pos0: 0.2409,
+        color0: [0.2426, 0.068, 0.0588, 1.0],
+        pos1: 0.4663,
+        color1: [0.6677, 0.5024, 0.5126, 1.0],
+      },
+    },
+    { id: "warm_emit", type: "emission", inputs: { strength: 0.30000001192092896 } },
+
+    // ── rim1: fresnel × facing ──
+    { id: "rim1_fres", type: "fresnel", inputs: { ior: 2.0 } },
+    { id: "rim1_lw", type: "layer_weight/facing", inputs: { blend: 0.24 } },
+    { id: "rim1_str", type: "math/multiply" },
+    { id: "rim1", type: "emission", inputs: { color: [0.984157919883728, 0.6110184788703918, 0.5736401677131653] } },
+
+    // ── rim2: fresnel × fresnel-layer-weight, powered (hair-style) ──
+    { id: "rim2_fres", type: "fresnel", inputs: { ior: 1.45 } },
+    { id: "rim2_lw", type: "layer_weight/fresnel", inputs: { blend: 0.61 } },
+    { id: "rim2_raw", type: "math/multiply" },
+    { id: "rim2_pow", type: "math/power", inputs: { b: 0.6300000548362732 } },
+    { id: "rim2_mix", type: "mix_shader", inputs: { b: [1.0, 0.4684903025627136, 0.3698573112487793] } },
+
+    // ── near-white texture gate emission ──
+    { id: "gate", type: "math/greater_than", inputs: { b: 0.9300000071525574 } },
+    { id: "gate_scale", type: "math/multiply", inputs: { b: 3.0 } },
+
+    // ── npr stack (rim1 + rim2 + bright_emit + warm) ──
+    { id: "npr_add1", type: "add_shader" },
+    { id: "npr_add2", type: "add_shader" },
+    { id: "npr_stack", type: "add_shader" },
+
+    // ── principled with noise bump ──
+    { id: "map", type: "mapping", inputs: { scl: [1.0, 1.0, 1.5] } },
+    { id: "noise", type: "tex_noise", inputs: { scale: 1.0 } },
+    { id: "noise_ramp", type: "ramp_linear", inputs: { pos0: 0.0, pos1: 1.0 } },
+    { id: "bump", type: "bump", inputs: { strength: 0.324644535779953 } },
+    { id: "principled_base", type: "mix/blend", inputs: { b: [0.6832, 0.1947, 0.1373] } },
+    { id: "p_emit", type: "emission", inputs: { strength: 0.2 } },
+    {
+      id: "principled",
+      type: "principled",
+      inputs: { metallic: 0.0, specular: 0.5, roughness: 0.3, spec_clamp: 10.0, sheen: 0.0, sheen_tint: 0.0 },
+    },
+    { id: "p_sum", type: "add_shader" },
+
+    { id: "mix_shader_001", type: "mix_shader", inputs: { fac: 0.5 } },
+  ],
+  links: [
+    // toon
+    { from: { node: "str", socket: "value" }, to: { node: "toon", socket: "fac" } },
+    { from: { node: "tex", socket: "color" }, to: { node: "shadow_tint", socket: "color" } },
+    { from: { node: "tex", socket: "color" }, to: { node: "lit_tint", socket: "color" } },
+    { from: { node: "toon", socket: "fac_out" }, to: { node: "toon_color", socket: "fac" } },
+    { from: { node: "shadow_tint", socket: "color" }, to: { node: "toon_color", socket: "a" } },
+    { from: { node: "lit_tint", socket: "color" }, to: { node: "toon_color", socket: "b" } },
+    { from: { node: "toon_color", socket: "color" }, to: { node: "bc", socket: "color" } },
+    { from: { node: "bc", socket: "color" }, to: { node: "emission3", socket: "color" } },
+    // warm rim
+    { from: { node: "toon", socket: "fac_out" }, to: { node: "warm_mul", socket: "a" } },
+    { from: { node: "warm_mul", socket: "value" }, to: { node: "warm_add", socket: "a" } },
+    { from: { node: "warm_add", socket: "value" }, to: { node: "warm_clamp", socket: "a" } },
+    { from: { node: "warm_clamp", socket: "value" }, to: { node: "warm_ramp", socket: "fac" } },
+    { from: { node: "warm_ramp", socket: "color" }, to: { node: "warm_emit", socket: "color" } },
+    // rim1
+    { from: { node: "rim1_fres", socket: "value" }, to: { node: "rim1_str", socket: "a" } },
+    { from: { node: "rim1_lw", socket: "value" }, to: { node: "rim1_str", socket: "b" } },
+    { from: { node: "rim1_str", socket: "value" }, to: { node: "rim1", socket: "strength" } },
+    // rim2
+    { from: { node: "rim2_fres", socket: "value" }, to: { node: "rim2_raw", socket: "a" } },
+    { from: { node: "rim2_lw", socket: "value" }, to: { node: "rim2_raw", socket: "b" } },
+    { from: { node: "rim2_raw", socket: "value" }, to: { node: "rim2_pow", socket: "a" } },
+    { from: { node: "emission3", socket: "color" }, to: { node: "rim2_mix", socket: "a" } },
+    { from: { node: "rim2_pow", socket: "value" }, to: { node: "rim2_mix", socket: "fac" } },
+    // gate
+    { from: { node: "tex", socket: "color" }, to: { node: "gate", socket: "a" } },
+    { from: { node: "gate", socket: "value" }, to: { node: "gate_scale", socket: "a" } },
+    // npr stack
+    { from: { node: "rim1", socket: "color" }, to: { node: "npr_add1", socket: "a" } },
+    { from: { node: "rim2_mix", socket: "color" }, to: { node: "npr_add1", socket: "b" } },
+    { from: { node: "npr_add1", socket: "color" }, to: { node: "npr_add2", socket: "a" } },
+    { from: { node: "gate_scale", socket: "value" }, to: { node: "npr_add2", socket: "b" } },
+    { from: { node: "npr_add2", socket: "color" }, to: { node: "npr_stack", socket: "a" } },
+    { from: { node: "warm_emit", socket: "color" }, to: { node: "npr_stack", socket: "b" } },
+    // principled + noise bump
+    { from: { node: "geo", socket: "rest_pos" }, to: { node: "map", socket: "vector" } },
+    { from: { node: "map", socket: "vector" }, to: { node: "noise", socket: "vector" } },
+    { from: { node: "noise", socket: "value" }, to: { node: "noise_ramp", socket: "fac" } },
+    { from: { node: "noise_ramp", socket: "fac_out" }, to: { node: "bump", socket: "height" } },
+    { from: { node: "geo", socket: "normal" }, to: { node: "bump", socket: "normal" } },
+    { from: { node: "noise_ramp", socket: "fac_out" }, to: { node: "principled_base", socket: "fac" } },
+    { from: { node: "bc", socket: "color" }, to: { node: "principled_base", socket: "a" } },
+    { from: { node: "bc", socket: "color" }, to: { node: "p_emit", socket: "color" } },
+    { from: { node: "principled_base", socket: "color" }, to: { node: "principled", socket: "base" } },
+    { from: { node: "bump", socket: "vector" }, to: { node: "principled", socket: "normal" } },
+    { from: { node: "principled", socket: "color" }, to: { node: "p_sum", socket: "a" } },
+    { from: { node: "p_emit", socket: "color" }, to: { node: "p_sum", socket: "b" } },
+    // final mix
+    { from: { node: "npr_stack", socket: "color" }, to: { node: "mix_shader_001", socket: "a" } },
+    { from: { node: "p_sum", socket: "color" }, to: { node: "mix_shader_001", socket: "b" } },
+  ],
+  output: { node: "mix_shader_001", socket: "color" },
+}

package/src/graph/presets/hair.ts

@@ -15,7 +15,7 @@ import type { StyleGraph } from "../schema"
 export const HAIR_GRAPH: StyleGraph = {
   version: 1,
   name: "Hair",
-  slot: "hair",
+  tags: ["hair"],
   nodes: [
     { id: "tex", type: "texture" },
     { id: "geo", type: "geometry" },

package/src/graph/presets/metal.ts

@@ -9,7 +9,7 @@ import type { StyleGraph } from "../schema"
 export const METAL_GRAPH: StyleGraph = {
   version: 1,
   name: "Metal",
-  slot: "metal",
+  tags: ["metal"],
   nodes: [
     { id: "tex", type: "texture" },
     { id: "geo", type: "geometry" },

package/src/graph/presets/stockings.ts

@@ -11,7 +11,7 @@ import type { StyleGraph } from "../schema"
 export const STOCKINGS_GRAPH: StyleGraph = {
   version: 1,
   name: "Stockings",
-  slot: "stockings",
+  tags: ["stockings"],
   nodes: [
     { id: "tex", type: "texture" },
     { id: "geo", type: "geometry" },

package/src/graph/render-class.ts

@@ -0,0 +1,33 @@
+// Render-class + alpha-mode: the small, closed, engine-owned vocabularies that carry
+// pass integration for a style group. A group's node graph is pure shading; these select
+// how the engine wires that shading into the passes. Not user-extensible — this is where
+// rendering correctness lives (stencil, cull, draw order, alpha test). See
+// docs/style-groups-spec.md §5.
+
+/** Pass-integration class. Selects stencil/cull/draw-order behavior. */
+export type RenderClass = "auto" | "eye" | "hair"
+
+/** Alpha-handling axis, orthogonal to RenderClass. "hashed" = Wyman & McGuire object-space
+ *  hashed alpha test (stockings); "opaque" = the standard near-zero threshold discard. */
+export type AlphaMode = "opaque" | "hashed"
+
+/** Descriptive manifest for hosts (reze-design) so the render-class picker is data-driven
+ *  instead of hardcoding strings. The effect implementations stay engine-side; this only
+ *  describes them. `pairsWith` = the effect needs a counterpart class present to show. */
+export type RenderClassInfo = {
+  id: RenderClass
+  label: string
+  description: string
+  pairsWith?: RenderClass
+}
+
+export const RENDER_CLASSES: readonly RenderClassInfo[] = [
+  { id: "auto", label: "Standard", description: "Opaque or transparent, derived from material alpha." },
+  { id: "eye", label: "Eye", description: "Stamps the see-through stencil; visible through hair.", pairsWith: "hair" },
+  {
+    id: "hair",
+    label: "Hair",
+    description: "Reads the eye stencil so eyes show through the silhouette.",
+    pairsWith: "eye",
+  },
+]

package/src/graph/schema.ts

@@ -3,8 +3,6 @@
 // time (Blender Normal Z → engine Y), the compiler never sees Blender conventions.
 // See docs/graph-compiler-spec.md.
 
-import type { MaterialPreset } from "../engine"
-
 export type SocketValue = number | [number, number, number] | [number, number, number, number]
 
 export type GraphNode = {
@@ -39,15 +37,15 @@ export type ExposedParam = {
 export type StyleGraph = {
   version: 1
   name: string
-  /** Which preset slot this style targets. The slot owns pass integration (stencil
-   *  variants like hair-over-eyes, alpha semantics, draw order) — always on,
-   *  graph-invisible. The graph only restyles the slot's shading. */
-  slot: MaterialPreset
   nodes: GraphNode[]
   links: GraphLink[]
   /** Must resolve to a color (vec3f) or float (auto-splatted) socket. */
   output: { node: string; socket: string }
   params?: ExposedParam[]
+  /** Soft, host-only hints for library filtering and smart default-group / render-class
+   *  matching (e.g. ["hair"]). Ignored by the compiler; round-tripped. A graph is pure
+   *  shading — pass integration lives on the style group's renderClass, not here. */
+  tags?: string[]
 }
 
 export type Diagnostic = {

package/src/graph/slots.ts

@@ -1,52 +1,24 @@
-// Per-slot WGSL templates. The graph computes only `final_color`; everything the slot
-// owns — texture sample, MMD alpha semantics, discard, lighting context, FSOut/mask
-// writes, and built-in pass effects like hair's over-eyes stencil variant — lives here,
-// always on, graph-invisible. Mirrors the hand-written material shaders line-for-line.
+// fs() shell assembly. The graph computes only `final_color`; everything around it —
+// texture sample, alpha discard, lighting context, built-in gates, and the FSOut/mask
+// write — is composed here from two orthogonal, engine-owned axes:
+//   RenderClass ("auto" | "eye" | "hair")  — stencil/cull/draw-order + eye rear-gate +
+//                                             hair over-eyes alpha. See render-class.ts.
+//   AlphaMode   ("opaque" | "hashed")       — standard threshold discard vs Wyman hashed.
+// A style group supplies both; this file turns them into the WGSL shell around fsBody.
+// See docs/style-groups-spec.md §5, §7.
 
 import { NODES_WGSL } from "../shaders/materials/nodes"
 import { COMMON_MATERIAL_PRELUDE_WGSL } from "../shaders/materials/common"
-import type { MaterialPreset } from "../engine"
+import type { AlphaMode, RenderClass } from "./render-class"
 
-export type SlotTemplate = {
-  /** Module-scope declarations (pipeline-override constants, helper fns). */
-  decls: string
-  /** Optional replacement for the standard fs() prelude (custom alpha semantics). */
-  prelude?: string
-  /** Tail of fs(): consumes `final_color` + template locals, writes FSOut. */
-  epilogue: string
-}
+// ── Module-scope declarations ──
+// hair: the over-eyes pipeline-override constant (a second pipeline is compiled with
+// IS_OVER_EYES=1). hashed: the Wyman & McGuire object-space hashed-alpha helpers.
+const HAIR_OVER_EYES_DECL = `override IS_OVER_EYES: bool = false;
 
-const DEFAULT_EPILOGUE = `  var out: FSOut;
-  out.color = vec4f(final_color, alpha);
-  out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
-  return out;
 `
 
-const DEFAULT_TEMPLATE: SlotTemplate = { decls: "", epilogue: DEFAULT_EPILOGUE }
-
-// Hair's built-in over-eyes effect (see hair.ts): the engine compiles two pipeline
-// variants from the same module — normal opaque hair, and a stencil-matched re-draw
-// at 25% alpha so eyes read through the silhouette. Always on for the hair slot.
-const HAIR_TEMPLATE: SlotTemplate = {
-  decls: `override IS_OVER_EYES: bool = false;
-
-`,
-  epilogue: `  var outAlpha = alpha;
-  if (IS_OVER_EYES) { outAlpha = alpha * 0.25; }
-
-  var out: FSOut;
-  out.color = vec4f(final_color, outAlpha);
-  out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
-  return out;
-`,
-}
-
-// Stockings' built-in alpha behavior (see stockings.ts): Wyman & McGuire hashed
-// alpha testing on bind-pose restPos replaces the standard threshold discard —
-// sort-independent through self-overlap, dither pinned to the fabric. The graph
-// only computes final_color; the hash gate and the alpha=1 output are slot-owned.
-const STOCKINGS_TEMPLATE: SlotTemplate = {
-  decls: `fn _hash3d_wm(a: vec3f) -> f32 {
+const HASHED_ALPHA_DECLS = `fn _hash3d_wm(a: vec3f) -> f32 {
   return _hash33(a).x * 0.5 + 0.5;
 }
 fn hashed_alpha_threshold(co: vec3f) -> f32 {
@@ -71,56 +43,48 @@ fn hashed_alpha_threshold(co: vec3f) -> f32 {
   return clamp(threshold, 1e-6, 1.0);
 }
 
-`,
-  prelude: `@fragment fn fs(input: VertexOutput) -> FSOut {
-  let tex_s = textureSample(diffuseTexture, diffuseSampler, input.uv);
-  // Hashed alpha test (EEVEE "Hashed" blend) instead of the standard threshold.
-  let alpha = material.alpha * tex_s.a;
-  if (alpha < hashed_alpha_threshold(input.restPos)) { discard; }
-
-  let n = safe_normal(input.normal);
-  let v = normalize(camera.viewPos - input.worldPos);
-  let l = -light.lights[0].direction.xyz;
-  let sun = light.lights[0].color.xyz * light.lights[0].color.w;
-  let amb = light.ambientColor.xyz;
-  let shadow = sampleShadow(input.worldPos, n);
-  let tex_color = tex_s.rgb;
-
-`,
-  epilogue: `  var out: FSOut;
-  out.color = vec4f(final_color, 1.0);
-  out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
-  return out;
-`,
-}
-
-export const SLOT_TEMPLATES: Partial<Record<MaterialPreset, SlotTemplate>> = {
-  hair: HAIR_TEMPLATE,
-  stockings: STOCKINGS_TEMPLATE,
-}
+`
 
-export function slotTemplate(slot: MaterialPreset): SlotTemplate {
-  return SLOT_TEMPLATES[slot] ?? DEFAULT_TEMPLATE
-}
+// Eye's built-in rear-view gate (open-shell PMX heads don't occlude the eye from behind,
+// so gate by camera-vs-face hemisphere via the 頭 bone; discard drops color + depth +
+// the stencil stamp together). Injected between the view vectors and the lighting setup.
+const EYE_REAR_GATE = `
+  if (material.headBoneIndex >= 0.0) {
+    let hm = skinMats[u32(material.headBoneIndex)];
+    let faceDir = -normalize(hm[2].xyz);
+    if (dot(faceDir, v) < -0.15) { discard; }
+  }
+`
 
-// Adjust-tier uniforms — fixed 16-vec4f block (256 B) so the single shared material
-// bind group layout serves every graph; non-graph presets bind a zero buffer.
+// ── Adjust-tier uniforms — fixed 16-vec4f block (256 B) shared by the single material
+// bind group layout; non-graph draws bind a zero buffer. ──
 export const STYLE_UNIFORMS_WGSL = `struct StyleUniforms { p: array<vec4f, 16> };
 @group(2) @binding(4) var<uniform> style: StyleUniforms;
 
 `
 
-// fs() prelude — identical to the hand-written materials so template locals keep the
-// exact names the registry's context nodes and emit functions reference.
-const FS_PRELUDE = `@fragment fn fs(input: VertexOutput) -> FSOut {
+function decls(renderClass: RenderClass, alphaMode: AlphaMode): string {
+  return (alphaMode === "hashed" ? HASHED_ALPHA_DECLS : "") + (renderClass === "hair" ? HAIR_OVER_EYES_DECL : "")
+}
+
+// fs() header up to and including the graph body's context locals. Composed so the
+// hand-written material shaders' local names (tex_color, n, v, l, sun, amb, shadow) are
+// preserved exactly — the registry's context nodes and emit functions reference them.
+function prelude(renderClass: RenderClass, alphaMode: AlphaMode): string {
+  const discard =
+    alphaMode === "hashed"
+      ? "  if (alpha < hashed_alpha_threshold(input.restPos)) { discard; }"
+      : "  if (alpha < 0.001) { discard; }"
+  const gate = renderClass === "eye" ? EYE_REAR_GATE : ""
+  return `@fragment fn fs(input: VertexOutput) -> FSOut {
   let tex_s = textureSample(diffuseTexture, diffuseSampler, input.uv);
-  // MMD alpha semantics: material alpha × texture alpha (hair/lace textures cut
-  // their shapes in the alpha channel).
+  // MMD alpha semantics: material alpha × texture alpha.
   let alpha = material.alpha * tex_s.a;
-  if (alpha < 0.001) { discard; }
+${discard}
 
   let n = safe_normal(input.normal);
   let v = normalize(camera.viewPos - input.worldPos);
+${gate}
   let l = -light.lights[0].direction.xyz;
   let sun = light.lights[0].color.xyz * light.lights[0].color.w;
   let amb = light.ambientColor.xyz;
@@ -128,18 +92,50 @@ const FS_PRELUDE = `@fragment fn fs(input: VertexOutput) -> FSOut {
   let tex_color = tex_s.rgb;
 
 `
+}
+
+// Tail of fs(): consumes `final_color` + locals, writes FSOut. hashed forces output
+// alpha to 1 (the discard already did the cutout); hair scales alpha for the over-eyes
+// pass when IS_OVER_EYES is compiled true.
+function epilogue(renderClass: RenderClass, alphaMode: AlphaMode): string {
+  const alphaBase = alphaMode === "hashed" ? "1.0" : "alpha"
+  if (renderClass === "hair") {
+    return `  var outAlpha = ${alphaBase};
+  if (IS_OVER_EYES) { outAlpha = ${alphaBase} * 0.25; }
+
+  var out: FSOut;
+  out.color = vec4f(final_color, outAlpha);
+  out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
+  return out;
+`
+  }
+  return `  var out: FSOut;
+  out.color = vec4f(final_color, ${alphaBase});
+  out.mask = vec4f(1.0, 1.0, 0.0, out.color.a);
+  return out;
+`
+}
 
-export function assembleModule(slot: MaterialPreset, fsBody: string, includeStyleUniforms: boolean): string {
-  const tmpl = slotTemplate(slot)
+/**
+ * Assemble a full WGSL module: shared node library + bindings/skinning prelude, optional
+ * StyleUniforms, render-class/alpha-mode declarations, the composed fs() shell, and the
+ * graph's node body.
+ */
+export function assembleModule(
+  renderClass: RenderClass,
+  alphaMode: AlphaMode,
+  fsBody: string,
+  includeStyleUniforms: boolean,
+): string {
   return (
     NODES_WGSL +
     COMMON_MATERIAL_PRELUDE_WGSL +
     (includeStyleUniforms ? STYLE_UNIFORMS_WGSL : "") +
-    tmpl.decls +
-    (tmpl.prelude ?? FS_PRELUDE) +
+    decls(renderClass, alphaMode) +
+    prelude(renderClass, alphaMode) +
     fsBody +
     "\n" +
-    tmpl.epilogue +
+    epilogue(renderClass, alphaMode) +
     "}\n"
   )
 }

package/src/graph/style-group.ts

@@ -0,0 +1,39 @@
+// Style groups — the user-facing unit of material styling. A group binds a set of
+// materials to a node graph (pure shading) plus the engine-owned pass-integration axes
+// (renderClass + alphaMode). Each material belongs to at most one group; grouped
+// materials render via the group's compiled-graph pipeline, ungrouped ones fall back to
+// the hand-written preset path. See docs/style-groups-spec.md.
+
+import type { Diagnostic, StyleGraph } from "./schema"
+import type { AlphaMode, RenderClass } from "./render-class"
+import type { StyleSlot } from "./compile"
+
+export type StyleGroup = {
+  /** Stable, unique within a model; /^[a-z0-9_-]+$/. The engine keys installs by this. */
+  id: string
+  /** Human display name ("Skirt", "Visor"); host-owned, round-tripped, never interpreted
+   *  by the engine. Defaults to `id`. */
+  label?: string
+  /** Material names in this group; each material is in AT MOST one group. */
+  materials: string[]
+  /** Pure shading (StyleGraph has no `slot` — integration lives here on the group). */
+  graph: StyleGraph
+  /** Pass-integration class: stencil/cull/draw-order. Default "auto". */
+  renderClass?: RenderClass
+  /** Alpha-handling axis, orthogonal to renderClass. Default "opaque". */
+  alphaMode?: AlphaMode
+}
+
+export type GroupDiagnostic = { groupId: string; diagnostics: Diagnostic[]; ok: boolean }
+
+export type ApplyStyleGroupsResult = {
+  /** Every group compiled + swapped. */
+  ok: boolean
+  groups: GroupDiagnostic[]
+  /** Names in a group that no model material matches (warning). */
+  unknownMaterials: string[]
+  /** Materials claimed by >1 group; the last group in array order wins (logged). */
+  conflicts: string[]
+}
+
+export type ApplyStyleGroupResult = { ok: boolean; diagnostics: Diagnostic[]; slotMap: StyleSlot[] }

package/src/index.ts

@@ -10,7 +10,6 @@ export {
   type MaterialPreset,
   type ResolvedMaterialPreset,
   type MaterialPresetMap,
-  type ApplyStyleResult,
   type GizmoDragEvent,
   type GizmoDragCallback,
   type GizmoDragKind,
@@ -33,6 +32,13 @@ export type {
   Diagnostic,
 } from "./graph/schema"
 export { NODE_REGISTRY, type NodeSpec, type SockT } from "./graph/registry"
+export { RENDER_CLASSES, type RenderClass, type AlphaMode, type RenderClassInfo } from "./graph/render-class"
+export type {
+  StyleGroup,
+  GroupDiagnostic,
+  ApplyStyleGroupsResult,
+  ApplyStyleGroupResult,
+} from "./graph/style-group"
 export { HAIR_GRAPH } from "./graph/presets/hair"
 export { DEFAULT_GRAPH } from "./graph/presets/default"
 export { CLOTH_SMOOTH_GRAPH } from "./graph/presets/cloth_smooth"
@@ -40,6 +46,8 @@ export { CLOTH_ROUGH_GRAPH } from "./graph/presets/cloth_rough"
 export { METAL_GRAPH } from "./graph/presets/metal"
 export { BODY_GRAPH } from "./graph/presets/body"
 export { STOCKINGS_GRAPH } from "./graph/presets/stockings"
+export { EYE_GRAPH } from "./graph/presets/eye"
+export { FACE_GRAPH } from "./graph/presets/face"
 export { Model } from "./model"
 export { Vec3, Quat, Mat4 } from "./math"
 export type {