@call-me-sensei/toonlab 0.5.0 → 0.5.1

package/NPM-LIBRARY.md

@@ -1,7 +1,7 @@
 # ToonLab npm library guide
 
 This guide is included in `@call-me-sensei/toonlab`. It is the package-first
-reference for version 0.5.0 and does not require access to the source
+reference for version 0.5.1 and does not require access to the source
 repository.
 
 ## Install
@@ -143,7 +143,7 @@ surface detail, not displacement that replaces a geometric high-to-low bake.
 
 ## Load Nature Reference Rocks
 
-Version 0.5.0 understands both the original `rock-0001`–`rock-0480`
+Version 0.5.1 understands both the original `rock-0001`–`rock-0480`
 identities and the Nature Reference Rocks catalog. Acquiring an asset
 directly returns its realistic PBR GLB. The one-call placement path additionally
 loads that asset's reviewed geology maps and `call_me_sensei` material settings
@@ -229,7 +229,7 @@ it uses the disk workspace passed through `--workspace`; no account is needed.
       "command": "npx",
       "args": [
         "-y",
-        "--package=@call-me-sensei/toonlab@0.5.0",
+        "--package=@call-me-sensei/toonlab@0.5.1",
         "toonlab-mcp",
         "--workspace",
         "/absolute/path/to/your-game/.toonlab"

package/README.md

@@ -19,7 +19,7 @@ Use ToonLab as a focused runtime library (`@call-me-sensei/toonlab` on npm), as
 an asset/preset authoring workspace, or as an asset-discovery service—not as a
 one-shot world generator.
 
-## Versioned expectation: 0.5.0
+## Versioned expectation: 0.5.1
 
 For a correctly constructed and semantically labeled scene, one strict Call Me
 Sensei bundle application is expected to establish the supported visual

package/agents/PROMPTS.md

@@ -1,7 +1,7 @@
 # ToonLab agent prompts
 
 These prompts are included with the npm package. They use only the supported
-0.5.0 runtime, agent skills, and MCP workflows.
+0.5.1 runtime, agent skills, and MCP workflows.
 
 ## New playable game
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@call-me-sensei/toonlab",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Anime-style game toolkit for Three.js with cel shading, vegetation, rocks, water, sky, clouds, procedural textures, and portable Lab artifacts",
   "license": "MIT",
   "author": "Hyperbond Studio PTE. LTD. (Call Me Sensei)",

package/src/shaders-tsl/character/characterMaterial.js

@@ -561,7 +561,9 @@ function vertexBlend(u, features) {
 
 // View-space displacement of the hull: outward along the (baked smooth)
 // geometry normal by the role's width, corrected to a constant on-screen
-// width, and pushed back along the view ray on faces.
+// width, and pushed back along the view ray by the role's depth push (faces:
+// faceDepthPush by face weight), so inner edges of layered parts fail the
+// depth test against the surface behind them and only silhouettes ink.
 function outlineViewOffset(u, features) {
   return (positionViewBase) => {
     const blend = vertexBlend(u, features);
@@ -586,7 +588,7 @@ function outlineViewOffset(u, features) {
     }
     width = min(width, u.outlineMaxWidth);
     const away = select(orthographic, vec3(0, 0, -1), normalize(positionViewBase));
-    return normalView.mul(width).add(away.mul(u.outlineFaceDepthPush.mul(faceWeight)));
+    return normalView.mul(width).add(away.mul(blend('outlineDepthPush').add(u.outlineFaceDepthPush.mul(faceWeight))));
   };
 }
 

package/src/toon/autoRoles.js

@@ -19,7 +19,15 @@ import { rasterizeTriangle, readTexturePixels, sampleTexturePixel } from './text
 //   2. The model's own skin tone, sampled from the cheek/chin band of the
 //      front of the head — a region that is skin on essentially every
 //      character. The band must itself look like skin (skinEvidence.js), so a
-//      helmet visor or a robot face is not taken as one.
+//      helmet visor or a robot face is not taken as one; glasses or a lock of
+//      hair across the band may outnumber the skin in it, so a band that is
+//      mostly skin-coloured texels by a clear share still counts. Brown,
+//      auburn and blond hair is skin-coloured by hue too, and hair framing a
+//      chibi face fills much of the band: when the band's skin-coloured texels
+//      form two clearly different lightness groups and the crown's lightness
+//      matches the darker one, that group is hair and the lighter one is the
+//      skin, and from then on only texels on the skin's side of the lightness
+//      boundary count as skin-toned. Hair as light as the skin is not split.
 //   3. Face = the front face zone of the head. Below the brow line everything
 //      is face (eyes, brows and mouth belong to it); above it only texels in
 //      the model's skin tone (so bangs over the forehead are not face).
@@ -27,7 +35,8 @@ import { rasterizeTriangle, readTexturePixels, sampleTexturePixel } from './text
 //      = body texels in the face's skin tone.
 //
 // The result is a normalized Uint8 vec4 `toonRoleWeights` (R skin, G face,
-// B hair) per vertex, consumed by the toon shader, and an estimated head frame
+// B hair; a partition — they sum to at most 1, the rest is the material's own
+// role) per vertex, consumed by the toon shader, and an estimated head frame
 // on the root for face lighting on unrigged models. When the head is low-poly
 // (a face of a few large polygons, where per-vertex weights smear the
 // face/hair boundary across whole triangles), the same classification is also
@@ -62,6 +71,19 @@ function colorSignature(rgba, target = [0, 0, 0]) {
   return target;
 }
 
+// Oklab lightness (0 black – 1 white) of an sRGB texel. Perceptual, unlike the
+// down-weighted log-luminance above: it is what separates skin from hair of
+// the same warm hue.
+function oklabLightness(rgba) {
+  const r = srgbToLinear(rgba[0]);
+  const g = srgbToLinear(rgba[1]);
+  const b = srgbToLinear(rgba[2]);
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  return 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+}
+
 function signatureDistance(a, b) {
   const dr = a[0] - b[0];
   const dg = a[1] - b[1];
@@ -85,6 +107,79 @@ function collectTargets(root, isEligible) {
   return targets;
 }
 
+// Texture (or material) colour at a vertex, 0-255 RGBA into `target`.
+function sampleVertexColor(mesh, i, target) {
+  const material = Array.isArray(mesh.material) ? mesh.material[0] : mesh.material;
+  const texture = material?.map;
+  const uv = mesh.geometry.attributes.uv;
+  const pixels = texture ? readTexturePixels(texture, { maxSize: 1024 }) : null;
+  if (!pixels || !uv) {
+    const color = material?.color ?? new THREE.Color(1, 1, 1);
+    target[0] = color.r * 255; target[1] = color.g * 255; target[2] = color.b * 255; target[3] = 255;
+    return target;
+  }
+  return sampleTexturePixel(pixels, texture, uv.getX(i), uv.getY(i), target);
+}
+
+function updateMapMatrices(meshes) {
+  for (const mesh of meshes) {
+    const material = Array.isArray(mesh.material) ? mesh.material[0] : mesh.material;
+    if (material?.map?.matrixAutoUpdate) material.map.updateMatrix();
+  }
+}
+
+// Rest-pose facing. Every classification here works in the character frame
+// (facing +Z), which a model states with `root.userData.toonForward`; without
+// it +Z is assumed. A rig whose rest pose faces elsewhere while its animations
+// turn it forward (the Sensei Run chibis face -X at rest) was analysed from
+// the side of the head: the face put on one cheek and the hair over the eyes.
+// The face is where the head's bright skin-coloured surface points: measured
+// on five chibis (2026-10-13), its mean horizontal normal is 0.21-0.41 long
+// and within 9 degrees of an axis; brown hair (skin-coloured by hue) is
+// excluded by lightness. Rigged models only (the head comes from the skin
+// weights); bald or masked heads give no clear direction and keep +Z. Light
+// warm hair is not excluded (Yuxi's ash-grey hair, 2026-10-16, pointed it at
+// -Z), so inferAutoRoleWeights consults it only after the +Z analysis fails.
+const FORWARD_MIN_SAMPLES = 64;
+const FORWARD_MIN_STRENGTH = 0.12;
+const FORWARD_SKIN_MIN_LIGHTNESS = 0.6;
+
+function estimateRestForward(root, targets, headBones) {
+  if (headBones.size === 0) return null;
+  updateMapMatrices(targets);
+  const rootInverse = new THREE.Matrix4().copy(root.matrixWorld).invert();
+  const normal = new THREE.Vector3();
+  const texel = [0, 0, 0, 255];
+  let sumX = 0;
+  let sumZ = 0;
+  let count = 0;
+  for (const mesh of targets) {
+    const headness = skinnedHeadness(mesh, headBones);
+    const normals = mesh.geometry.attributes.normal;
+    if (!headness || !normals) continue;
+    const normalMatrix = new THREE.Matrix3().getNormalMatrix(new THREE.Matrix4().multiplyMatrices(rootInverse, mesh.matrixWorld));
+    const stride = Math.max(1, Math.floor(normals.count / 20000));
+    for (let i = 0; i < normals.count; i += stride) {
+      if (headness[i] < 0.9) continue;
+      sampleVertexColor(mesh, i, texel);
+      if (!isSkinLikeColor(texel[0] / 255, texel[1] / 255, texel[2] / 255)) continue;
+      if (oklabLightness(texel) < FORWARD_SKIN_MIN_LIGHTNESS) continue;
+      normal.fromBufferAttribute(normals, i).applyMatrix3(normalMatrix).normalize();
+      sumX += normal.x;
+      sumZ += normal.z;
+      count += 1;
+    }
+  }
+  if (count < FORWARD_MIN_SAMPLES) return null;
+  const x = sumX / count;
+  const z = sumZ / count;
+  const strength = Math.hypot(x, z);
+  if (strength < FORWARD_MIN_STRENGTH) return null;
+  // Rigs are authored axis-aligned: the nearest horizontal axis.
+  const forward = Math.abs(x) > Math.abs(z) ? [Math.sign(x), 0, 0] : [0, 0, Math.sign(z)];
+  return { forward, samples: count, strength };
+}
+
 function headBoneSet(headBone) {
   const bones = new Set();
   headBone?.traverse((node) => {
@@ -136,7 +231,23 @@ const FOOTPRINT_PERCENTILE = 0.8;
 // least this share of it (large painted features — a chibi nose and lips —
 // take the rest).
 const REFERENCE_MIN_SKIN_FRACTION = 0.3;
+// When the band's median colour is not skin (glasses frames and lenses, or a
+// lock of hair, cover much of it), a larger share of skin-coloured texels is
+// required instead (Keisuke, glasses: 42 %; Akika, hair over the cheeks: 38 %).
+const REFERENCE_MIN_SKIN_FRACTION_MIXED = 0.35;
 const SATURATED_REFERENCE_CHROMA = 0.2;
+// Skin-coloured hair in the cheek band: its skin-coloured texels split into
+// two lightness groups (1-D two-means on Oklab lightness) at least this far
+// apart, the smaller holding at least SKIN_SPLIT_MIN_SHARE of them. Measured
+// on six chibis with brown hair (2026-10-13): group centres skin 0.72–0.84,
+// hair 0.32–0.46 (black hair is not skin-coloured and never splits). The
+// boundary is softened by SKIN_SPLIT_SOFTNESS either side.
+const SKIN_SPLIT_MIN_GAP = 0.2;
+const SKIN_SPLIT_MIN_SHARE = 0.1;
+const SKIN_SPLIT_SOFTNESS = 0.04;
+// Crown: head texels this far above the head's centre (fraction of its height
+// radius) give the hair's lightness.
+const CROWN_Y = 0.7;
 
 function extendHeadAboveNeck(meshes, headBone, rootInverse) {
   const neckBone = headBone?.parent?.isBone ? headBone.parent : null;
@@ -170,6 +281,48 @@ function percentileOf(sorted, fraction) {
   return sorted[Math.min(sorted.length - 1, Math.max(0, Math.round((sorted.length - 1) * fraction)))];
 }
 
+// Two lightness groups among the band's skin-coloured texels — skin and darker
+// hair of the same warm hue — or null when they form one group. The darker
+// group is the hair only when the crown's median lightness is nearer to it.
+// Hair as light as the skin or lighter (ash, silver, platinum) is never split
+// off: its crown matches the lighter group, which is then the skin itself
+// (Yuxi, 2026-10-16: crown and cheeks both about 0.8, the darker group her
+// lips and lashes), so such models keep the unsplit skin reference. (A bald
+// head with a brown beard would be read the wrong way round; name its face
+// material to skip automatic roles.)
+function splitSkinFromHair(lightness, crownLightness) {
+  if (lightness.length < 32 || crownLightness.length < 16) return null;
+  const sorted = [...lightness].sort((a, b) => a - b);
+  let low = percentileOf(sorted, 0.2);
+  let high = percentileOf(sorted, 0.8);
+  let lowCount = 0;
+  for (let iteration = 0; iteration < 16; iteration += 1) {
+    const boundary = (low + high) / 2;
+    let lowSum = 0;
+    let highSum = 0;
+    lowCount = 0;
+    for (const value of sorted) {
+      if (value < boundary) {
+        lowSum += value;
+        lowCount += 1;
+      } else {
+        highSum += value;
+      }
+    }
+    if (lowCount === 0 || lowCount === sorted.length) return null;
+    low = lowSum / lowCount;
+    high = highSum / (sorted.length - lowCount);
+  }
+  const smallerShare = Math.min(lowCount, sorted.length - lowCount) / sorted.length;
+  if (high - low < SKIN_SPLIT_MIN_GAP || smallerShare < SKIN_SPLIT_MIN_SHARE) return null;
+  const crown = median(crownLightness);
+  if (Math.abs(crown - low) > Math.abs(crown - high)) return null;
+  const boundary = (low + high) / 2;
+  // 1 on the skin's (lighter) side of the boundary.
+  const weight = (value) => smoothstep(boundary - SKIN_SPLIT_SOFTNESS, boundary + SKIN_SPLIT_SOFTNESS, value);
+  return { boundary, groups: [low, high], hair: 'darker', isSkinSide: (value) => weight(value) >= 0.5, weight };
+}
+
 // Centre and radii (root space, x/y) of the visible face: head vertices that
 // face forward, sit on the front half of the head and match the skin tone.
 function measureFaceFrame(meshes, headnessAt, isSkinToned, center, radiusX) {
@@ -320,11 +473,24 @@ function findNeckHeight(slices, minY, sliceHeight) {
   return minY + (neck + 0.5) * sliceHeight;
 }
 
+// Analysis failures that mean "no skin where the face should be", after which
+// an undeclared rest-pose facing is estimated and the analysis retried.
+const RETRY_WITH_INFERRED_FORWARD = new Set(['no-skin-reference', 'reference-not-skin']);
+
 /**
  * Infers per-vertex role weights for the eligible meshes under `root`.
  * `isEligible(material)` selects materials whose roles are unknown.
  * Returns a report; `applied` is false (with a `reason`) when evidence is
  * insufficient, in which case nothing is modified.
+ *
+ * The analysis runs in the declared character frame (`root.userData.toonForward`,
+ * +Z when none is declared). Only when a model declares nothing and its +Z
+ * analysis finds no skin in the cheek band is its rest-pose facing estimated
+ * (estimateRestForward) and the analysis retried from that side. The estimate
+ * is a fallback, never an override: light warm hair (ash, silver, blond) is
+ * skin-coloured by hue and can outweigh the face in it. The inferred axis is
+ * kept, and written to the root so later bakes and head tracking agree, only
+ * when the retry succeeds.
  */
 export function inferAutoRoleWeights(root, {
   headBone = null,
@@ -335,10 +501,33 @@ export function inferAutoRoleWeights(root, {
   if (targets.length === 0) return { applied: false, reason: 'no-eligible-meshes' };
 
   root.updateMatrixWorld(true);
+  const headBones = headBoneSet(headBone);
+  const analyse = (forwardInferred) => analyseRoles(root, targets, headBone, headBones, skinTolerance, forwardInferred);
+  const result = analyse(null);
+  if (result.applied || !RETRY_WITH_INFERRED_FORWARD.has(result.reason)) return result;
+  if (Array.isArray(root.userData?.toonForward)) return result;
+
+  const estimate = estimateRestForward(root, targets, headBones);
+  if (!estimate || estimate.forward[2] === 1) return result;
+  const previousForward = root.userData.toonForward;
+  root.userData.toonForward = estimate.forward;
+  const retried = analyse(estimate);
+  if (retried.applied) return retried;
+  if (previousForward === undefined) delete root.userData.toonForward;
+  else root.userData.toonForward = previousForward;
+  return result;
+}
+
+/**
+ * One analysis in the root's current character frame. Returns before
+ * modifying anything when the evidence is insufficient.
+ * @param {THREE.Mesh[]} targets
+ * @param {{ forward: number[], samples: number, strength: number } | null} forwardInferred
+ */
+function analyseRoles(root, targets, headBone, headBones, skinTolerance, forwardInferred) {
   // The character frame (facing +Z), not the root's raw frame: a VRM 0.x
   // root is turned 180° by its importer.
   const rootInverse = characterFrameInverse(root);
-  const headBones = headBoneSet(headBone);
 
   // Gather every eligible vertex in root space once.
   const meshes = targets.map((mesh) => {
@@ -422,34 +611,22 @@ export function inferAutoRoleWeights(root, {
   const radiusY = Math.max((headBox.max.y - headBox.min.y) / 2, 1e-4);
 
   // Skin reference from the cheek/chin band on the front of the head.
-  const sampleColor = (mesh, i, target) => {
-    const material = Array.isArray(mesh.material) ? mesh.material[0] : mesh.material;
-    const texture = material?.map;
-    const uv = mesh.geometry.attributes.uv;
-    const pixels = texture ? readTexturePixels(texture, { maxSize: 1024 }) : null;
-    if (!pixels || !uv) {
-      const color = material?.color ?? new THREE.Color(1, 1, 1);
-      target[0] = color.r * 255; target[1] = color.g * 255; target[2] = color.b * 255; target[3] = 255;
-      return target;
-    }
-    return sampleTexturePixel(pixels, texture, uv.getX(i), uv.getY(i), target);
-  };
-  for (const { mesh } of meshes) {
-    const material = Array.isArray(mesh.material) ? mesh.material[0] : mesh.material;
-    if (material?.map?.matrixAutoUpdate) material.map.updateMatrix();
-  }
+  const sampleColor = sampleVertexColor;
+  updateMapMatrices(targets);
 
   const texel = [0, 0, 0, 255];
   const signature = [0, 0, 0];
-  const reference = [[], [], []];
-  let referenceSkinLike = 0;
+  // Skin-coloured band texels: signature and Oklab lightness each.
+  const bandSkin = [];
   const referenceRgb = [[], [], []];
+  const crownLightness = [];
   for (const entry of meshes) {
     const stride = Math.max(1, Math.floor(entry.points.length / 3 / 20000));
     for (let i = 0; i < entry.points.length / 3; i += stride) {
       if (headnessAt(entry, i) < 0.9) continue;
       const x = (entry.points[i * 3] - center.x) / radiusX;
       const y = (entry.points[i * 3 + 1] - center.y) / radiusY;
+      if (y > CROWN_Y) crownLightness.push(oklabLightness(sampleColor(entry.mesh, i, texel)));
       const facing = entry.normals[i * 3 + 2];
       if (facing < 0.55 || Math.abs(x) > 0.45 || y > -0.1 || y < -0.65) continue;
       colorSignature(sampleColor(entry.mesh, i, texel), signature);
@@ -458,20 +635,22 @@ export function inferAutoRoleWeights(root, {
       // a big red nose, dark lips and eyes in this zone otherwise pulled it
       // off the skin, leaving the forehead and outer cheeks part hair.
       if (!isSkinLikeColor(texel[0] / 255, texel[1] / 255, texel[2] / 255)) continue;
-      referenceSkinLike += 1;
-      reference[0].push(signature[0]);
-      reference[1].push(signature[1]);
-      reference[2].push(signature[2]);
+      bandSkin.push({ signature: [signature[0], signature[1], signature[2]], lightness: oklabLightness(texel) });
     }
   }
   const sampled = referenceRgb[0].length;
   if (sampled < 16) return { applied: false, reason: 'no-skin-reference' };
   const medianRgb = referenceRgb.map(median);
   const medianIsSkin = isSkinLikeColor(medianRgb[0] / 255, medianRgb[1] / 255, medianRgb[2] / 255);
-  if (!medianIsSkin || reference[0].length < 16 || referenceSkinLike < sampled * REFERENCE_MIN_SKIN_FRACTION) {
-    return { applied: false, medianRgb, reason: 'reference-not-skin', referenceSkinFraction: referenceSkinLike / sampled };
+  const minSkinFraction = medianIsSkin ? REFERENCE_MIN_SKIN_FRACTION : REFERENCE_MIN_SKIN_FRACTION_MIXED;
+  if (bandSkin.length < 16 || bandSkin.length < sampled * minSkinFraction) {
+    return { applied: false, medianRgb, reason: 'reference-not-skin', referenceSkinFraction: bandSkin.length / sampled };
   }
-  const skinReference = reference.map(median);
+  const skinSplit = splitSkinFromHair(bandSkin.map((sample) => sample.lightness), crownLightness);
+  const skinSamples = skinSplit ? bandSkin.filter((sample) => skinSplit.isSkinSide(sample.lightness)) : bandSkin;
+  const skinReference = [0, 1, 2].map((k) => median(skinSamples.map((sample) => sample.signature[k])));
+  // 1 on the skin's side of a lightness split (always 1 without one).
+  const skinSideAt = (rgba) => (skinSplit ? skinSplit.weight(oklabLightness(rgba)) : 1);
   // Linear chromaticity spreads saturated colours apart: painted shading on an
   // orange-brown skin moves further in it than on pale skin. The tolerance
   // grows with the reference's own distance from neutral (pale and typical
@@ -485,7 +664,7 @@ export function inferAutoRoleWeights(root, {
   // so the scalp of a bald head is not all face.
   const faceFrame = measureFaceFrame(meshes, headnessAt, (entry, i) => {
     colorSignature(sampleColor(entry.mesh, i, texel), signature);
-    return signatureDistance(signature, skinReference) <= tolerance;
+    return signatureDistance(signature, skinReference) <= tolerance && skinSideAt(texel) >= 0.5;
   }, center, radiusX);
   // The upper half fades out over the forehead rather than at a hard edge:
   // face shading follows the face map (light azimuth only) and the scalp
@@ -507,7 +686,7 @@ export function inferAutoRoleWeights(root, {
   const roles = [0, 0, 0];
   const classify = (px, py, pz, facing, headness, rgba) => {
     colorSignature(rgba, signature);
-    const skinLike = 1 - smoothstep(tolerance * 0.6, tolerance, signatureDistance(signature, skinReference));
+    const skinLike = (1 - smoothstep(tolerance * 0.6, tolerance, signatureDistance(signature, skinReference))) * skinSideAt(rgba);
     const z = pz - center.z;
     // On the front of the face either by normal or by position: recessed eye
     // sockets, nose sides and lips face sideways, but sit well in front of the
@@ -515,10 +694,14 @@ export function inferAutoRoleWeights(root, {
     const front = Math.max(smoothstep(0.05, 0.35, facing), smoothstep(0.35, 0.6, z / radiusX));
     const frontZone = headness * ovalAt(px, py) * front * (z > -0.1 * radiusX ? 1 : 0);
     const face = frontZone * Math.max(lowerFaceAt(py), skinLike);
-    // Skin includes the face: a skin-coloured texel is fully skin however
-    // much of it is face. (A max() of the two left a part-face cheek only
-    // part skin, the remainder shaded as cloth.)
-    roles[0] = face + (1 - face) * skinLike;
+    // The weights partition the surface: the shader blends each role's full
+    // parameters by its weight and gives the material's own role the
+    // remainder (characterMaterial.js createBlend). Skin is the skin-coloured
+    // share that is not face, so a skin-coloured cheek is fully face plus skin
+    // with no cloth remainder, and a face texel is not also counted as skin
+    // (that summed the skin and face terminators, tones and outline widths,
+    // washing faces out).
+    roles[0] = (1 - face) * skinLike;
     roles[1] = face;
     roles[2] = headness * (1 - face) * (1 - skinLike);
     return roles;
@@ -581,9 +764,13 @@ export function inferAutoRoleWeights(root, {
     headVertexCount: headCount,
     meshes: meshes.length,
     faceFrame,
+    forwardInferred,
+    head: { center: center.toArray(), radiusX, radiusY },
     maskedMeshes,
     method: rigged ? 'skin-weights' : 'silhouette',
+    referenceSkinFraction: bandSkin.length / sampled,
     skinReference,
+    skinSplit: skinSplit ? { boundary: skinSplit.boundary, groups: skinSplit.groups, hair: skinSplit.hair } : null,
     skinTolerance: tolerance,
   };
 }

package/src/toon/characterParameters.js

@@ -42,6 +42,7 @@ export const ROLE_PARAMETER_NAMES = Object.freeze([
   'specularThreshold',
   'specularSoftness',
   'outlineWidth',
+  'outlineDepthPush',
   'ink',
   'inkSaturation',
   'outlineLightingMix',
@@ -101,6 +102,8 @@ function roleParameters(settings, role, { hasSpecularMask = false, paintedEyeHig
     outlineMaxBrightness: Math.max(lighting.min, lighting.max),
     outlineMinBrightness: lighting.min,
     outlineWidth: outline.enabled ? outline.width[role] : 0,
+    // Faces (and eyes) use faceDepthPush, applied by face weight in the hull shader.
+    outlineDepthPush: inkRole === 'face' ? 0 : outline.depthPush[inkRole] ?? 0,
     rimIntensity: rim.enabled ? rim.intensity[rimRole] : 0,
     rimSilhouette: role === 'hair' ? rim.silhouette.hair : role === 'eye' ? 0 : rim.silhouette.body,
     sceneShadowStrength: sceneShadow,

package/src/toon/settings/outlineSettings.js

@@ -56,6 +56,15 @@ export const OUTLINE_FIELDS = Object.freeze({
     metal: lightingRole(0.2, 'metal'),
   }),
   faceDepthPush: numberField(0.02, 0, 0.2, 'Push face hull lines back in depth (metres) so they show only on the silhouette, not across nose and eyelids.'),
+  // The same push for the other roles. Layered parts (a jacket over a shirt, sleeves, separate hair locks) each
+  // carry their own hull, so without it every inner edge inks a full-width line across the body; pushed back,
+  // a part's hull only shows where the part stands clear of what is behind it (its silhouette).
+  depthPush: Object.freeze({
+    cloth: numberField(0, 0, 0.2, 'Push cloth hull lines back in depth (metres): inner edges of layered clothing stop inking across the body; silhouettes stay.'),
+    hair: numberField(0, 0, 0.2, 'Push hair hull lines back in depth (metres): edges of overlapping locks stop inking; the hair silhouette stays.'),
+    skin: numberField(0, 0, 0.2, 'Push body-skin hull lines back in depth (metres).'),
+    metal: numberField(0, 0, 0.2, 'Push metal hull lines back in depth (metres).'),
+  }),
   honourSourceOff: booleanField(true, 'Respect a source material\'s "no outline" (MMD edge flag off).'),
   widthMap: textureField('Per-texel width multiplier (also `userData.toonOutlineWidthMap`, MToon outline width texture).'),
   widthMapChannel: selectField(0, [0, 1, 2, 3], 'Width map channel.', { numeric: true, optionLabels: { 0: 'Red', 1: 'Green', 2: 'Blue', 3: 'Alpha' } }),

package/src/toon/toonMaterialAdapter.js

@@ -1168,12 +1168,17 @@ function runAutoRoles(root, toonSettings, materialRoleOverrides, modelFacts, rep
     report.add('warn', 'no-face-role', 'No material is recognised as a face and automatic roles are off; the face is shaded with the body terminator.');
     return null;
   }
+  const declaredForward = Array.isArray(root.userData?.toonForward);
   const result = inferAutoRoleWeights(root, {
     headBone: findHeadBone(root),
     isEligible: (mat) => !(mat?.isMToonMaterial && mat.isOutline) &&
       AUTO_ROLE_ELIGIBLE.has(classifyMaterialRole(mat, materialRoleOverrides).role),
     skinTolerance: toonSettings.autoRoles.skinTolerance,
   });
+  if (!declaredForward && Array.isArray(root.userData?.toonForward)) {
+    const forward = root.userData.toonForward;
+    report.add('warn', 'rest-forward-inferred', `The model declares no forward and its +Z analysis found no skin in the cheek band; its rest pose faces [${forward.join(', ')}] (inferred from the face) and that was written to root.userData.toonForward. Declare it on the model to make this explicit.`, { forward });
+  }
   if (result.applied) {
     report.add('info', 'auto-roles-applied', `No material is named as a face; inferred face, skin and hair per vertex (${result.method}).`, result);
   } else {

package/src/version.js

@@ -1,3 +1,3 @@
 // Single runtime source of truth for package consumers and ToonLab Pro/MCP.
 // Keep this value synchronized with package.json during release preparation.
-export const TOONLAB_VERSION = '0.5.0';
+export const TOONLAB_VERSION = '0.5.1';

package/types/toon/autoRoles.d.ts

@@ -3,25 +3,21 @@
  * `isEligible(material)` selects materials whose roles are unknown.
  * Returns a report; `applied` is false (with a `reason`) when evidence is
  * insufficient, in which case nothing is modified.
+ *
+ * The analysis runs in the declared character frame (`root.userData.toonForward`,
+ * +Z when none is declared). Only when a model declares nothing and its +Z
+ * analysis finds no skin in the cheek band is its rest-pose facing estimated
+ * (estimateRestForward) and the analysis retried from that side. The estimate
+ * is a fallback, never an override: light warm hair (ash, silver, blond) is
+ * skin-coloured by hue and can outweigh the face in it. The inferred axis is
+ * kept, and written to the root so later bakes and head tracking agree, only
+ * when the retry succeeds.
  */
 export function inferAutoRoleWeights(root: any, { headBone, isEligible, skinTolerance, }?: {
     headBone?: any;
     isEligible?: () => boolean;
     skinTolerance?: number;
 }): {
-    applied: boolean;
-    reason: string;
-    medianRgb?: undefined;
-    referenceSkinFraction?: undefined;
-    counts?: undefined;
-    headVertexCount?: undefined;
-    meshes?: undefined;
-    faceFrame?: undefined;
-    maskedMeshes?: undefined;
-    method?: undefined;
-    skinReference?: undefined;
-    skinTolerance?: undefined;
-} | {
     applied: boolean;
     medianRgb: any[];
     reason: string;
@@ -30,9 +26,12 @@ export function inferAutoRoleWeights(root: any, { headBone, isEligible, skinTole
     headVertexCount?: undefined;
     meshes?: undefined;
     faceFrame?: undefined;
+    forwardInferred?: undefined;
+    head?: undefined;
     maskedMeshes?: undefined;
     method?: undefined;
     skinReference?: undefined;
+    skinSplit?: undefined;
     skinTolerance?: undefined;
 } | {
     applied: boolean;
@@ -49,12 +48,31 @@ export function inferAutoRoleWeights(root: any, { headBone, isEligible, skinTole
         x: number;
         y: number;
     };
+    forwardInferred: {
+        forward: number[];
+        samples: number;
+        strength: number;
+    };
+    head: {
+        center: THREE.Vector3Tuple;
+        radiusX: number;
+        radiusY: number;
+    };
     maskedMeshes: number;
     method: string;
+    referenceSkinFraction: number;
     skinReference: any[];
+    skinSplit: {
+        boundary: number;
+        groups: any[];
+        hair: string;
+    };
     skinTolerance: number;
     reason?: undefined;
     medianRgb?: undefined;
-    referenceSkinFraction?: undefined;
+} | {
+    applied: boolean;
+    reason: string;
 };
 export const AUTO_ROLE_ATTRIBUTE: "toonRoleWeights";
+import * as THREE from 'three';

package/types/toon/settings/outlineSettings.d.ts

@@ -62,6 +62,12 @@ export const OUTLINE_FIELDS: Readonly<{
         }>;
     }>;
     faceDepthPush: import("./fieldSchema.js").SettingField;
+    depthPush: Readonly<{
+        cloth: import("./fieldSchema.js").SettingField;
+        hair: import("./fieldSchema.js").SettingField;
+        skin: import("./fieldSchema.js").SettingField;
+        metal: import("./fieldSchema.js").SettingField;
+    }>;
     honourSourceOff: import("./fieldSchema.js").SettingField;
     widthMap: import("./fieldSchema.js").SettingField;
     widthMapChannel: import("./fieldSchema.js").SettingField;

package/types/toon/toonMaterialAdapter.d.ts

@@ -18,32 +18,6 @@ export function findPrimarySkinnedMesh(root: any): any;
  */
 export function applyToonShader(root: any, options?: {}): {
     autoRoles: {
-        applied: boolean;
-        reason: string;
-        medianRgb?: undefined;
-        referenceSkinFraction?: undefined;
-        counts?: undefined;
-        headVertexCount?: undefined;
-        meshes?: undefined;
-        faceFrame?: undefined;
-        maskedMeshes?: undefined;
-        method?: undefined;
-        skinReference?: undefined;
-        skinTolerance?: undefined;
-    } | {
-        applied: boolean;
-        medianRgb: any[];
-        reason: string;
-        referenceSkinFraction: number;
-        counts?: undefined;
-        headVertexCount?: undefined;
-        meshes?: undefined;
-        faceFrame?: undefined;
-        maskedMeshes?: undefined;
-        method?: undefined;
-        skinReference?: undefined;
-        skinTolerance?: undefined;
-    } | {
         applied: boolean;
         counts: {
             face: number;
@@ -58,13 +32,31 @@ export function applyToonShader(root: any, options?: {}): {
             x: number;
             y: number;
         };
+        forwardInferred: {
+            forward: number[];
+            samples: number;
+            strength: number;
+        };
+        head: {
+            center: THREE.Vector3Tuple;
+            radiusX: number;
+            radiusY: number;
+        };
         maskedMeshes: number;
         method: string;
+        referenceSkinFraction: number;
         skinReference: any[];
+        skinSplit: {
+            boundary: number;
+            groups: any[];
+            hair: string;
+        };
         skinTolerance: number;
         reason?: undefined;
         medianRgb?: undefined;
-        referenceSkinFraction?: undefined;
+    } | {
+        applied: boolean;
+        reason: string;
     };
     convertedMeshCount: number;
     debugOutputMode: {
@@ -114,6 +106,7 @@ export const TOON_DEBUG_OUTPUT_MODES: Readonly<{
 }>;
 /** Debug view name → label. */
 export const TOON_DEBUG_OUTPUT_LABELS: any;
+import * as THREE from 'three';
 export { alphaTestForMaterial, createAlphaSettings, DEFAULT_ALPHA_SETTINGS, resolveAlphaForMaterial, sourceOpacity, usesAlphaBlend, usesAlphaCutout } from "./settings/alphaSettings.js";
 export { BASE_TEXTURE_MATERIAL_COLOR_MODES, BASE_TEXTURE_SATURATION_MODES, createBaseTextureSettings, DEFAULT_BASE_TEXTURE_SETTINGS } from "./settings/baseTextureSettings.js";
 export { createFurSettings, DEFAULT_FUR_SETTINGS, materialUsesFur } from "./settings/furSettings.js";

package/types/version.d.ts

@@ -1 +1 @@
-export const TOONLAB_VERSION: "0.5.0";
+export const TOONLAB_VERSION: "0.5.1";