@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/docs/texture-lab.md

@@ -0,0 +1,135 @@
+# Texture Lab and texgen
+
+Texture Lab (`/texture-lab/`) generates **seamless procedural PBR textures
+for anything** — stone, ground, wood, metal, fabric, ceramics, creatures,
+liquids, sci-fi panels, stylized prints — entirely on the CPU, deterministic
+per seed, with zero image assets. The generator ships as the
+`@call-me-sensei/toonlab/texgen` cluster so you can bake the same maps in
+your own app or in Node.
+
+## The lab
+
+- **Gallery** — 60+ built-in material presets across ten categories, each
+  thumbnail baked live by the real generator. Your saved textures appear in
+  *Your library*.
+- **Pattern stage** — the base generator (25 tileable patterns: fbm, ridged,
+  billow, turbulence, worley/voronoi variants, cracks, caustics, speckle,
+  bricks, tiles, hex, checker, grid, stripes, chevron, weave, basket weave,
+  scales, dots, marble, wood grain, …) plus two blendable detail layers.
+  Sliders irrelevant to the selected pattern hide automatically.
+- **Color stage** — a five-stop height ramp (set *Band smoothness* to 0 for
+  hard cel bands), painterly hue/value jitter (optionally per pattern cell —
+  per-brick tint shifts), cavity darkening and ridge sheen for the
+  hand-painted read, and a final grade (hue/saturation/brightness/contrast/
+  gamma).
+- **Overlays stage** — one-knob **wear macros** (*Damage* carves seeded
+  scratches and chips and roughens them; *Dirt* pools grime into crevices)
+  plus two masked colored overlays for moss, rust, grime, snow, patina,
+  stains. *Crevice bias* pools an overlay into recesses (+1) or caps ridges
+  (−1); each overlay can also shift roughness, height, and metalness (rust
+  strips metal).
+- **Surface stage** — relief depth, derived normal strength, baked AO,
+  roughness base + height-correlated contrast, metalness, and an optional
+  emissive source (crevices / peaks / band / overlay) for lava, circuits,
+  force fields.
+- **Preview** — lit 3D meshes (sphere, cube, cylinder, torus, knot, plane)
+  with live displacement, or a flat 2D sheet with a per-map view
+  (albedo/height/normal/roughness/metalness/AO/emissive) and 1–4× tiling to
+  eyeball the seams. `R` re-rolls the seed; keys 1–5 switch stages;
+  backtick opens the all-controls drawer.
+
+## Image base (bring your own image)
+
+“Use an image as the base” (Pattern stage, or *From an image* in the
+gallery) turns **a picture of one surface into a tiling toon material** —
+a wall photo, a bark close-up, a fabric scan, a crop from concept art.
+There is **no AI in this path**: it converts, it does not interpret, so a
+whole scene or screenshot just becomes repeating wallpaper (the lab warns
+when an upload looks like a scene — crop the material you want first;
+scene → material-list breakdown is the planned pro tool). Mechanically:
+the bitmap is seamless-ized (torus blend), relief is derived from
+band-split luminance (*Relief detail* / *Relief base*), and an optional
+*Cel bands* control quantizes it toward the toon look. The image replaces
+only the **base layer** — detail layers, wear, overlays (moss a
+photographed wall!), glow, cavity/sheen, and the color grade all still
+apply, and every map derives as usual. The base pattern and height-ramp
+controls disable with a hint while an image is active. Images are stored
+in the browser only; share URLs strip them (Recipe JSON keeps them).
+Library callers: `imageToTextureMaps(imagePixels, { params, settings,
+size })` — decoding stays outside so texgen remains headless.
+
+## AI assist (bring your own key)
+
+The **AI** stage maps plain language — *“old leather jacket”*, *“mossy
+castle bricks”*, *“molten lava with glowing cracks”* — onto generator
+parameters:
+
+- **Built-in (no key)** — a deterministic offline mapper scores your words
+  against the preset library and applies wear/color modifiers (old, wet,
+  mossy, rusty, cracked, glowing, chunky, fine, color words…).
+- **Gemini / OpenAI (your key)** — the lab sends a compact schema catalog
+  (generated from the live field schema, ~3k tokens) plus your description
+  to the model you name, and expects a small JSON recipe back: a base
+  preset, a 2–5 color palette, and a parameter patch. Cheap “mini” tiers
+  are plenty: the defaults are `gemini-2.5-flash-lite` and `gpt-5-mini`,
+  and the model id field is free text so any model you have access to
+  works. Every returned value is validated and clamped against the schema
+  before it touches your document.
+
+Keys are stored in this browser's `localStorage` only and are sent solely
+to `generativelanguage.googleapis.com` / `api.openai.com` — there is no
+ToonLab server in the path. *Refine current* mode patches the texture you
+are editing instead of starting fresh.
+
+## Export
+
+The Export dialog bakes at 256–2048 px (independent of the preview) and
+downloads:
+
+- individual PNGs per map,
+- one ZIP with the selected maps plus `recipe.json` (re-importable) and
+  `material.json` (usage hints),
+- the recipe JSON on its own, or a **share URL** with the whole recipe
+  inlined (`?textureRecipe=`).
+
+Maps: `albedo` + `emissive` are sRGB; `normal` (OpenGL +Y), `roughness`,
+`metalness`, `ao`, `height`, and the glTF-style `orm` pack
+(R=occlusion, G=roughness, B=metalness) are linear. Everything tiles
+seamlessly — noise wraps its lattice periodically rather than blending
+mirrored copies.
+
+## Library usage
+
+```js
+import {
+  createTextureSettings,
+  evaluateTextureMaps,
+  syncTextureMapTextures,
+  findTexturePreset,
+} from '@call-me-sensei/toonlab/texgen';
+
+const settings = createTextureSettings(findTexturePreset('rusted-iron').settings);
+const maps = await evaluateTextureMaps(settings, { size: 512 });
+
+const { textures } = syncTextureMapTextures(maps); // THREE.DataTexture set
+const material = new THREE.MeshStandardMaterial({
+  aoMap: textures.ao,
+  map: textures.albedo,          // SRGBColorSpace, RepeatWrapping — pre-tagged
+  metalnessMap: textures.metalness,
+  metalness: 1,
+  normalMap: textures.normal,
+  roughnessMap: textures.roughness,
+  roughness: 1,
+});
+```
+
+`evaluateTextureMaps` is async and chunked (pass `onProgress` /
+`shouldCancel`), headless-safe (no DOM), and deterministic: the same
+settings always produce byte-identical maps. To map language to settings
+yourself, use `keywordTextureRecipe(prompt)` (offline) or
+`buildTextureAiPrompt` + `parseTextureAiResponse` +
+`compileTextureAiRecipe` around any LLM call.
+
+Settings documents are versioned (`kind: "toonlab.textureRecipe"`,
+`version: 1`) and validated/clamped by `createTextureSettings` — unknown
+keys are ignored, colors accept hex strings or `[r, g, b]` triplets.

package/docs/toon-shading.md

@@ -0,0 +1,183 @@
+# Toon character shading
+
+Modern anime character shading for any Three.js character. One call
+converts a loaded model's materials into the toon shader; everything else is
+settings.
+
+The implementation is TSL/NodeMaterial-only after the WebGPU cutover. It runs
+on native WebGPU by default and on the TSL WebGL2 fallback with
+`?renderer=webgl`; the old GLSL material path has been removed.
+
+```js
+import { applyToonShader, createToonSettings } from '@call-me-sensei/toonlab/toon';
+
+applyToonShader(characterRoot, {
+  settings: createToonSettings({
+    preset: 'default',
+    skinTone: { skinShadowBrightness: 0.94 },
+    rimLight: { hairIntensity: 0.2 },
+  }),
+});
+```
+
+(Inside this repo the labs import from `../../src/toon/...`.)
+
+`applyToonShader(root, options)` traverses the model, classifies material
+roles, converts materials in place, and adds the inverted-hull outline pass.
+Settings groups can also be passed directly as options
+(`applyToonShader(root, { rimLight: {...} })`). To re-tune an already
+converted model at runtime, use
+`applyToonSettingsToMaterial(target, settings)` — it applies uniform-safe
+edits without reconversion (this is what the debug panel calls).
+
+## Settings groups
+
+`createToonSettings(options)` merges your overrides over a preset over the
+defaults, and returns the full nested settings object. There are 23 groups
+(`TOON_SETTING_GROUPS`), each with its own module under `src/toon/settings/`:
+
+| Group | What it controls |
+|---|---|
+| `baseTexture` | Preserves source texture, source material color, and saturation policy before toon lighting. |
+| `materialRoles` | Classifies materials as skin, face, hair, eyes, costume, metal, transparent overlays, and outline. |
+| `alpha` | Cutout, blend, opacity, eye overlay sorting, and transparent decoration behavior. |
+| `skinTone` | Keeps skin and face shadows warm, readable, and separate from costume/hair shadows. |
+| `faceLighting` | Overrides face-area cel response so noses, cheeks, and eyes do not receive harsh body shadows. |
+| `celShade` | The primary directional cel band threshold, softness, and light-ignore amount. |
+| `shadowColor` | Tints and reshapes lit-to-shadow transitions and fully shadowed regions. |
+| `sceneShadow` | How renderer shadow maps darken character materials. |
+| `selfShadow` | Character-local self shadow (dedicated shadow pass or scene-proxy source). |
+| `averageShadow` | Averaged shadow visibility for softer role-specific shadow damping. |
+| `indirectLight` | Mixes ambient, hemisphere, and environment light into toon shading. |
+| `localLights` | Point and spot light response without overpowering cel bands. |
+| `rimLight` | View-dependent edge light; classic fresnel or screen-space depth-texture mode. |
+| `contactShadow` | Thin screen-space contact shadows (hair-on-face, arm-on-torso) from the depth prepass. |
+| `specular` | Role-aware stylized highlights and optional source specular masks. |
+| `hairHighlight` | Hair-specific highlight bands, optional anisotropic strand response, and source masks. |
+| `eyeHighlight` | Role-aware eye/catchlight boosts and optional source masks. |
+| `materialMaps` | Routes source normal, AO, emissive, MatCap, ramp, detail, roughness, metalness, and specular-color maps. |
+| `outline` | The inverted-hull outline pass, including role-specific widths and colors. |
+| `glitter` | Procedural view-dependent sparkles for costumes/accessories. Off by default. |
+| `sticker` | Blends a decal/overlay texture into the albedo before lighting. Off by default. |
+| `perspectiveRemoval` | Flattens perspective around the tracked head for anime-portrait closeups. Off by default. |
+| `fur` | Opt-in shell fur for matched materials (collars, trims, animal parts). Off by default. |
+
+Every field (298 of them) is listed with type, default, and range in the
+generated [settings reference](settings-reference.md). The same schema
+(`TOON_SETTING_FIELD_SCHEMA`) drives the [debug panel](debug-panel.md), so
+each field is also a live slider in the Character Shader Lab.
+
+## Material roles
+
+Materials are classified into roles before conversion — `default`,
+`costume`, `skin`, `face`, `hair`, `eye`, `iris`, `pupil`, `sclera`,
+`eyeHighlight`, `catchlight`, `blush`, `transparentOverlay`, `metal`,
+`outline`. Roles decide which settings apply where (skin shadow tint, hair
+highlights, outline widths, alpha behavior).
+
+The default classifier is heuristic (names, textures, PMX conventions).
+Override it without touching shader code:
+
+```js
+applyToonShader(characterRoot, {
+  materialRoles: {
+    byName: { Face: 'face', Hair: 'hair' },
+    byUuid: { [material.uuid]: 'skin' },
+    patterns: [{ pattern: /eye.*highlight/i, role: 'eyeHighlight' }],
+  },
+});
+```
+
+A source material can also declare `material.userData.toonRole`. Inspect the
+resolved roles with `?toonDebug=role`, or programmatically via
+`document.body.dataset.materialRoleSummary` in the labs.
+
+## Presets and preset documents
+
+Presets are named partial settings registered in a registry. Built-ins:
+`default`, `call_me_sensei`, `showcase` (`TOON_PRESET_IDS`,
+`getToonPresetOptions()`).
+
+```js
+import {
+  registerToonPreset,
+  serializeToonPreset,
+  parseToonPresetDocument,
+} from '@call-me-sensei/toonlab/toon';
+
+// Register in code:
+registerToonPreset('zzz_soft', {
+  label: 'ZZZ Soft',
+  description: 'Flatter urban anime lighting.',
+  settings: { hairHighlight: { mode: 'anisotropic' } },
+});
+
+// Share as a versioned JSON document (same shape the Character Shader Lab exports):
+const json = serializeToonPreset('warm_skin_test', {
+  label: 'Warm Skin Test',
+  settings: { skinTone: { skinShadowBrightness: 0.94 } },
+});
+
+// Load one back, with validation:
+const result = parseToonPresetDocument(json);
+if (result.ok) registerToonPreset(result.value.id, result.value, { overwrite: true });
+```
+
+Documents carry `{ type: 'toonlab/toon-preset', version, id,
+label, description, settings }` and are validated field-by-field against the
+schema (`validateToonPresetDocument`). Scalars, booleans, enums, colors, and
+vectors serialize; runtime texture objects (mask maps) are intentionally
+ignored by JSON validation — wire those in code. Related APIs:
+`createToonPresetDocument`, `registerSerializedToonPreset`,
+`sanitizeToonPresetSettings`, `getToonPresetDefinition`.
+
+## Render passes
+
+`applyToonShader` alone produces a complete material.
+`createCharacterRenderPasses` adds the per-frame passes that unlock the
+screen-space and shadow-map features:
+
+```js
+import { createCharacterRenderPasses } from '@call-me-sensei/toonlab/toon';
+
+const passes = createCharacterRenderPasses({ renderer, scene, camera });
+passes.registerCharacterRoot(modelRoot); // after applyToonShader
+
+// in the render loop, before rendering:
+passes.update();
+```
+
+The passes:
+
+1. **Scene depth prepass** — feeds the depth-texture rim light mode and
+   contact shadows.
+2. **Character-only orthographic shadow map** — real self shadow
+   (`selfShadow` group; direction follows the main light or a
+   camera-relative art-directed angle).
+3. **Head bone tracking** — head-space face shading
+   (`faceLighting.headSpaceMode: 'headBone'`).
+4. **Average shadow measurement** — per-character uniform scene shadow.
+5. **Character mask** — character-aware bloom in the
+   [post pipeline](post-processing.md).
+
+Every pass is auto-gated: it only renders when at least one registered
+material actually consumes its output, so leaving the passes running with
+the features disabled costs almost nothing.
+
+## Debug views
+
+`?toonDebug=<mode>` in the labs, or `setToonDebugOutput(root, mode)` in
+code, renders one shader term in isolation:
+
+```text
+sourceAlbedo | albedo | band | shadow | selfShadow | directVisibility |
+contactShadow | rim | depthRim | specular | hairHighlight | eyeHighlight |
+normalMap | aoMap | emissiveMap | matcap | ramp | detailMap | roughnessMap |
+metalnessMap | shadowColor | lit | role | alpha
+```
+
+Typical tuning loop: `?toonDebug=band` while adjusting `celShade`,
+`?toonDebug=shadowColor` for `shadowColor`, `?toonDebug=rim` for `rimLight`,
+`?toonDebug=role` when a model misclassifies. The full mode map is
+`TOON_DEBUG_OUTPUT_MODES` (aliases included); debug branches compile out
+when off.

package/docs/tsl-conventions.md

@@ -0,0 +1,167 @@
+# TSL Porting Conventions (three r185+)
+
+House rules for porting the GLSL shader library to TSL/NodeMaterial during
+the WebGPU migration. Everything here was
+verified against `three@0.185.1` on both node backends — the WGSL
+builder (WebGPU) and the GLSL builder (`forceWebGL: true`). Re-validate the
+"r185 quirk" items on any version bump.
+
+## File layout
+
+- `src/shaders-tsl/` is the canonical shader library: one module per material
+  (`sky.js`, `anime.js`, …), one module per reusable chunk under
+  `src/shaders-tsl/chunks/` (`water-common.js`, `character-lighting.js`, …).
+  The retired raw GLSL tree (`src/shaders/`) and `shaderSource.js` registry
+  were removed in Phase 11.
+- Leaf helpers that map nodes→nodes are `Fn()` exports. Helpers with
+  compile-time-constant parameters (loop counts, feature flags) are plain JS
+  functions that unroll at graph-build time.
+- Chunks that need material uniforms export a factory
+  (`createXxxChunk({ u, tex, v, flags })`) returning the chunk's functions;
+  the shader module assembles them. `u` = uniform nodes under GLSL names,
+  `tex` = texture nodes, `v` = varyings, `flags` = compile-time booleans.
+
+## The `.uniforms` compatibility surface
+
+TSL material factories attach `material.uniforms` — a map of UniformNodes
+(and TextureNodes) keyed by the **exact GLSL uniform names**. UniformNode and
+TextureNode both expose `.value`, so every existing write-through
+(`mat.uniforms.celShadeMidPoint.value = x`, HUD panels, characterRenderPasses
+`setUniform`) works identically on both backends. Do not rename uniforms in
+a port.
+
+## Feature gating
+
+- Former GLSL `#ifdef USE_X` sampler-presence gates are now JS
+  `if (flags.hasX)` graph-build gates. Absent maps never enter the graph, so
+  no texture/bind slots are wasted. Keep these gates: both native WebGPU (with
+  default requested limits) and the forced WebGL2 fallback currently have a
+  16-sampled-texture ceiling.
+- GLSL `uniform bool useX` runtime toggles → keep as uniform-driven
+  `If()`/`select()`, exactly like the GLSL branch.
+- Debug views are always compiled into TSL materials when available; the
+  selector is a pure uniform write.
+
+## r185 gotchas (each cost real debugging time)
+
+1. **`matN()` scalar constructors are three.js ROW-major** (`Matrix2`
+   constructor docs), the transpose of GLSL's column-major `matN()`.
+   Transpose the scalar order when porting, or write the multiply
+   component-wise. Constructors from column *vectors* (`mat4(v0,v1,v2,v3)`)
+   match GLSL. Symptom: fbm/rotation patterns differ subtly.
+2. **`select()` operands must be pure expressions.** A branch that creates a
+   var (`.toVar()`) or calls an `Fn()` crashes the GLSL builder with
+   `Cannot read properties of undefined (reading 'addToStack')` — the
+   ConditionalNode type-resolution fallback builds the operand subtree in a
+   detached (stack-less) flow. Referencing vars created *outside* the select
+   is fine. Hoist calls into `If()`-assigned vars instead.
+3. **Deep nested `select()` chains** (the 24-entry debug table) hit the same
+   fallback. Use masked arithmetic sums
+   (`Σ value.mul(select(cond, 1, 0))`) for big tables, and never leave a
+   ConditionalNode as the `fragmentNode` root (wrap with `mix()` or `vec4()`).
+4. **All mutating node code needs an active stack** — build vertex work
+   inside one `Fn()` assigned to `vertexNode`, declare varyings up front
+   (`varying(vec3(), 'vName')`) and `.assign()` them inside; the declarative
+   `varying(Fn(...)())` form breaks the GLSL builder.
+5. **Depth-texture sampling types differently per builder** (WGSL: `float`,
+   GLSL: `vec4` snippet under a `float` node type → compile error). Passes
+   that feed shaders write linear window depth into **float COLOR targets**
+   instead; `[0,1]` window depth is numerically identical on both coordinate
+   systems (perspective *and* orthographic), so `perspectiveDepthToViewZ`
+   works unchanged.
+6. **Render targets are written top-down on BOTH node backends.** Manual
+   shadow/projective sampling (matrix-composed uv) needs a y-flip that the
+   classic pipeline didn't; WebGPU additionally has clip z in [0,1] (the GLSL
+   `*0.5+0.5` contract needs a `z' = 2z − 1` pre-stretch). Compose both into
+   the CPU-side matrix (see characterRenderPasses `shadowClipAdjust*`).
+   three's own `screenUV` node already handles orientation — prefer it over
+   `gl_FragCoord`-style math.
+7. **SkinningNode stores bone matrices in a uniform buffer** —
+   `GL_MAX_UNIFORM_BLOCK_SIZE` (16KB ≈ 256 bones) breaks MMD-scale skeletons
+   on the WebGL2 backend. `withToonStorageSkinning()`
+   (chunks/character-skinning.js) reroutes skinned meshes to a
+   `storage(...).setPBO(true)` bone buffer (emitted as a DataTexture +
+   texelFetch on GLSL). Note: the GLSL builder **replaces the attribute
+   array** with a padded copy at PBO setup — per-frame updates must copy
+   `skeleton.boneMatrices` into `attribute.array` and flag
+   `attribute.pbo.needsUpdate`.
+8. **Guard uniform-dependent divisions.** GLSL branches skipped
+   `direction.xz / (up + 0.28)` below the horizon; a masked straight-line
+   port produces NaN·0 = NaN. Keep the `If()` structure (uniform conditions
+   are fine in WGSL uniformity analysis) or clamp the divisor.
+9. **RT-fed textures sample at `.level(0)`** — no mips exist and WGSL forbids
+   implicit-derivative sampling in non-uniform control flow.
+10. **`MeshDepthMaterial` (and other non-node classics) don't auto-convert**
+    on the node renderer (`NodeBuilder: Material "MeshDepthMaterial" is not
+    compatible`). Standard lit materials do. Pass materials are node-built.
+11. **`renderer.capabilities` doesn't exist on WebGPURenderer** — use
+    `renderer.getMaxAnisotropy()` etc. with optional chaining at seams shared
+    by both renderers.
+12. **KTX2 `detectSupport(renderer)` needs an initialized backend** — gate
+    loader configuration (and anything else probing capabilities) on
+    `await renderer.init()` / `whenRendererReady()`.
+13. **`UniformArrayNode.value` is the packed GPU buffer** (null until first
+    setup); the authoring array is `.array`. Expose array uniforms on the
+    `.uniforms` surface as `{ value: node.array, node }` wrappers so
+    `uniforms.uWavesA.value[i].set()` write-throughs keep working (water).
+14. **Depth-as-color passes get fogged by `NodeMaterial.setupOutput`** in
+    fogged scenes — distant depth blends toward the fog color. Null
+    `scene.fog` for the pass render and force `fog: false` on the variant
+    materials (water depth pass; the environment sun-shadow pass has the
+    same latent hazard in any future fogged scene).
+15. **The node renderer force-rebuilds a camera's projection on
+    `coordinateSystem` mismatch** (and on its first reversed-depth pass) —
+    copy `camera.coordinateSystem` onto any manual virtual/pass camera or a
+    hand-mutated projection matrix (oblique clip) gets wiped on first render
+    (planar reflection, water reflection).
+16. **`geometry.setDrawRange` doesn't limit instanced draws** on the node
+    renderer — set `geometry.instanceCount` instead (rain intensity).
+17. **Shared uniform NODES must be adopted at graph build time** — swapping
+    entries in a material's `.uniforms` map after build changes nothing (the
+    map is a compatibility view, not the graph). Rebuild the material (or
+    build it with the shared nodes from the start) when wiring cross-material
+    shared uniforms (`attachWaveUniforms`).
+18. **The classic pipeline's baked `colorspace_fragment` is per-render-target**
+    — `linearToOutputTexel` compiles against the BOUND target's
+    `texture.colorSpace`, so an offscreen NoColorSpace target holds LINEAR
+    color on classic despite the include. When porting a pass that reads such
+    a target, do NOT add a compensating transfer (post composite: a drafted
+    OETF-at-read washed the frame +191/255). The single encode happens at the
+    canvas draw on both pipelines.
+
+## Scene lights
+
+Custom lighting models that need raw light data (main-light direction, toon
+banding per light, shadow mask separate from color) don't fit the node
+LightingModel shape. `chunks/character-scene-lights.js` mirrors the scene's
+lights into shared uniforms once per frame (from `Object3D.onBeforeRender`,
+which both renderers call) replicating three's WebGLLights view-space
+conventions and attenuation math. Materials share the module-level uniform
+nodes, so one sync updates every toon material.
+
+## Renderer/backends
+
+- `?renderer=` flag: absent / `webgpu` = native WebGPU; `webgl` = TSL through
+  `WebGPURenderer({ forceWebGL: true })`; `webgpu-forced-gl` = compatibility
+  alias for `webgl`.
+  `labs/shared/rendererKind.js` resolves it; `labs/shared/rendererFactory.js`
+  creates the renderer (sync create, async `init()` gate via
+  `whenRendererReady`), sets the `src/core/shaderBackend.js` marker, and
+  reports `document.body.dataset.rendererKind` / `.rendererBackend`
+  (`webgpu` | `webgl2-fallback` — capture scripts assert this).
+- Material factories in `src/` are TSL-first. Some helpers still branch on
+  `isTslBackend()` for shared WebGPU/forced-WebGL2 code, but the classic
+  `WebGLRenderer`/GLSL material path is gone.
+- Headless WebGPU (Playwright): launch with
+  `--enable-unsafe-webgpu --enable-gpu` → hardware Metal adapter on macOS.
+  Captures: `TOON_BASELINE_RENDERER=webgpu|webgl|webgpu-forced-gl
+  TOON_BASELINE_SCOPE=ganyu npm run baseline:capture` (backend mismatch fails
+  the capture).
+
+## Verification
+
+WebGL headless captures are byte-deterministic (noise floor zero) — any
+classic-path diff is a real regression. TSL-vs-WebGL diffs bottom out at
+fp-level noise around toon band/fbm thresholds (mean ≈ 1/1020 per pixel);
+structural differences always traced to a real porting bug, so do not accept
+"looks close" while a debug view disagrees.