@convai/embody 1.0.1-beta.0 → 1.1.0-beta.0

package/dist/render/surfaces.js

@@ -0,0 +1,1020 @@
+/**
+ * Surface shading for skin and hair — how the body takes whatever light the
+ * app puts it in.
+ *
+ * Lighting is the app's. What embody owns is that the materials respond to
+ * it the way skin and hair do, under a portrait key, noon sun, a neon club or
+ * an overcast sky alike. The convai-mha-1 exports ship neither: the face is a
+ * plain standard material (metalness map and all) whose light/shadow edge cuts
+ * straight from lit to black, and the hair is roughness 1, IOR 1.1 chalk drawn
+ * as a depthless blended shell over hard-cut cards.
+ *
+ * What changes, and on which renderer:
+ *
+ *   EVERY RENDERER (material properties three's WebGL and WebGPU renderers
+ *   both honour):
+ *   · skin → MeshPhysicalMaterial: skin's IOR (1.4) and specular, no metal,
+ *     and a faint warm sheen at grazing angles where light scatters out;
+ *   · hair cards and lashes → alpha-to-coverage in the opaque pass: they write
+ *     depth (so they sort and take shadows) and MSAA softens their edges; the
+ *     export's blended hair layer stays blended, after the cards, as the soft
+ *     edge; hair gets a broad, soft keratin sheen in its own colour;
+ *   · the scalp under the hair is shaded as skin in the hair's shade (vertex
+ *     colours), so partings and the gaps between cards don't show bare skin;
+ *   · every texture is sampled anisotropically.
+ *
+ *   WEBGL ONLY (a shader patch WebGPU ignores, leaving the above):
+ *   · light wraps past the terminator as a warm band, as it does through skin
+ *     (Green, "Real-time approximations to subsurface scattering", GPU Gems 1
+ *     ch.16), so the edge is soft instead of clay;
+ *   · thin tissue (ears, nostril wings) glows when lit from behind
+ *     (Barré-Brisebois & Bouchard, GDC 2011);
+ *   · a fine pore normal over the face's own normal map — the published face
+ *     textures are 1024², too coarse to hold pores under a hard key.
+ *
+ * Values are the ones the coffee-shop studio arrived at by comparing renders
+ * against Unreal MetaHuman references under moving light.
+ */
+import * as THREE from 'three';
+import { isEye } from './faceMaterials.js';
+/**
+ * The skin response on a male record, where the app sets nothing. The
+ * published male heads have the same albedo lightness as the light female
+ * ones (face luma 0.023-0.026 against 0.031, measured at the mesh), so this
+ * is a look, not a measurement: tighter and less pink, with more pore, after
+ * a look-dev review (2026-11-07) of a male head that read waxy and warm beside
+ * a female head from the same pipeline. Smaller than it sounds: roughness 0.45
+ * went plastic in the same review.
+ */
+const MALE_SKIN = {
+    roughness: 0.48,
+    sheen: 0.04,
+    sheenColor: [0.75, 0.52, 0.46],
+    specular: 0.5,
+    // Pores at 0.3: 0.42 overshot the reference's micro-contrast (0.046
+    // against 0.039), 0.2 read smooth.
+    detail: 0.3,
+    // Less light carried past the terminator: the nose, cheek and jaw hold
+    // their form (contrast 0.24 -> 0.27 measured; the reference sits far
+    // higher under its own harder key).
+    wrap: 0.42,
+    subsurface: 0.28,
+    translucency: 0.18,
+    shadowFloor: [0.1, 0.065, 0.055],
+    tint: [0.965, 1, 1.03],
+};
+const SHADOW_FLOOR = [0.12, 0.07, 0.055];
+/**
+ * The lash alpha multiplier a male record is capped to: the texture's own
+ * alpha, no multiplier. At 1.6 the lashes were still the darkest line on a
+ * male face whose brows and stubble are faint, and read as the feature.
+ */
+export const LASH_MALE = 1;
+const TEXTURE_KEYS = [
+    'map', 'normalMap', 'roughnessMap', 'metalnessMap', 'aoMap', 'emissiveMap', 'alphaMap',
+    'specularColorMap', 'specularIntensityMap', 'sheenColorMap', 'clearcoatNormalMap',
+];
+const SKIN_MATERIAL = /^(base)?head|skin|^body/i;
+const HAIR_MESH = /hair|groom|beard|mustache|moustache|brow|fuzz/i;
+const HAIR_MATERIAL = /hair|blind|blend|clip|brow|beard|mustache|fuzz|lash/i;
+/** Base name without the exporter's `.001` suffix. */
+const baseName = (name) => name.replace(/\.\d+$/, '');
+const isHairLike = (mesh, mat) => {
+    const alpha = mat.transparent || mat.alphaTest > 0;
+    return alpha && (HAIR_MESH.test(mesh.name) || HAIR_MATERIAL.test(baseName(mat.name)));
+};
+const isSkin = (mat) => SKIN_MATERIAL.test(baseName(mat.name)) && 'roughness' in mat && !(mat.transparent || mat.alphaTest > 0);
+/** Mean linear colour of a texture's opaque texels, or null if unreadable. */
+export function meanTextureColor(tex) {
+    const img = tex?.image;
+    if (!img)
+        return null;
+    let data = img.data;
+    if (!data && typeof document !== 'undefined' && img.width && img.height) {
+        const canvas = document.createElement('canvas');
+        canvas.width = canvas.height = 32;
+        const g = canvas.getContext('2d');
+        if (!g)
+            return null;
+        g.drawImage(img, 0, 0, 32, 32);
+        data = g.getImageData(0, 0, 32, 32).data;
+    }
+    if (!data)
+        return null;
+    let r = 0, gr = 0, b = 0, n = 0;
+    for (let i = 0; i + 3 < data.length; i += 4) {
+        if (data[i + 3] < 128)
+            continue;
+        r += data[i];
+        gr += data[i + 1];
+        b += data[i + 2];
+        n++;
+    }
+    if (!n)
+        return null;
+    const c = new THREE.Color(r / n / 255, gr / n / 255, b / n / 255);
+    return tex.colorSpace === THREE.SRGBColorSpace ? c.convertSRGBToLinear() : c;
+}
+/**
+ * Mean linear colour of a texture where a mesh actually uses it: sampled at
+ * every third vertex's UV. A head atlas is mostly empty or not skin (mouth,
+ * ears, unused space), so its own mean said nothing about the face (luma
+ * 0.013 measured against 0.026 sampled at the mesh). Null if unreadable.
+ */
+export function meanSkinColor(mesh, tex) {
+    const img = tex?.image;
+    const uv = mesh.geometry.attributes.uv;
+    if (!img || !uv || !img.width || !img.height)
+        return null;
+    let data = img.data;
+    let w = img.width, h = img.height;
+    if (!data && typeof document !== 'undefined') {
+        const canvas = document.createElement('canvas');
+        canvas.width = canvas.height = 256;
+        const g = canvas.getContext('2d');
+        if (!g)
+            return null;
+        g.drawImage(img, 0, 0, 256, 256);
+        data = g.getImageData(0, 0, 256, 256).data;
+        w = h = 256;
+    }
+    if (!data)
+        return null;
+    const wrap = (x) => x - Math.floor(x);
+    let r = 0, gr = 0, b = 0, n = 0;
+    for (let i = 0; i < uv.count; i += 3) {
+        const u = wrap(uv.getX(i)), v = wrap(uv.getY(i));
+        const x = Math.min(w - 1, Math.floor(u * w));
+        const y = Math.min(h - 1, Math.floor((tex.flipY ? 1 - v : v) * h));
+        const p = (y * w + x) * 4;
+        if (data[p + 3] < 128)
+            continue;
+        r += data[p];
+        gr += data[p + 1];
+        b += data[p + 2];
+        n++;
+    }
+    if (!n)
+        return null;
+    const c = new THREE.Color(r / n / 255, gr / n / 255, b / n / 255);
+    return tex.colorSpace === THREE.SRGBColorSpace ? c.convertSRGBToLinear() : c;
+}
+/**
+ * Lashes (and the eye-occlusion film) only get the soft edge. Given hair's
+ * specular they caught a top light or the sun and read white.
+ */
+const isLash = (mesh, mat) => /lash/i.test(mesh.name) || /lash/i.test(baseName(mat.name));
+function tuneHair(mesh, mat, lash) {
+    const m = mat;
+    // Every card layer as coverage in the opaque pass: it writes depth, sorts,
+    // takes shadows, and MSAA smooths what passes the cut. 0.35 keeps the
+    // strands' fine ends (fuller hair); the cards' faint dark-edged texels
+    // stay out. (The export's blended twin of the same cards is hidden by
+    // applySurfaces: it drew the same hair twice.)
+    m.transparent = false;
+    m.depthWrite = true;
+    m.alphaHash = false;
+    m.alphaToCoverage = true;
+    m.alphaTest = Math.max(m.alphaTest, lash ? 0.2 : 0.35);
+    // Some exports ship hair with opacity above 1, an alpha multiplier for
+    // their own blended draw (3.4 on one short male cut, 1 on the long cuts).
+    // Drawn as coverage it turns every strand texel past ~0.3 solid: a flat
+    // cap with no strand ends. Coverage already follows alpha and restores
+    // fullness on the small mips, so the multiplier is dropped. Lashes keep
+    // theirs: at 3.5 they read as full lashes, at 1 as a few hairs.
+    if (!lash && m.opacity > 1)
+        m.opacity = 1;
+    if (lash) {
+        fadeHairSpecular(m);
+        m.needsUpdate = true;
+        return;
+    }
+    // Hair highlights are faint and coloured by the hair, and fade out at the
+    // silhouette (the coffee-shop studio's, matched to Unreal references). A
+    // white specular at 0.25 read silvery at grazing angles and greyed dark
+    // hair; at 0.55 roughness with full white specular it streaked as wet.
+    // The export's roughness map is dropped: hair maps are authored for engine
+    // hair shaders and mean something else on a physical material.
+    const albedo = meanTextureColor(m.map) ?? m.color.clone();
+    const tint = albedo.clone().multiplyScalar(1 / Math.max(albedo.r, albedo.g, albedo.b, 1e-3));
+    // Lighter hair shows more of the uncoloured primary highlight (the R lobe
+    // of a strand reflects the light's colour; the coloured lobes come from
+    // inside the strand and dominate dark hair). Dark hair keeps the fully
+    // tinted, faint highlight that was matched to the studio films; from
+    // mid-brown up a share of white comes in, or a light cut read flat.
+    const luma = 0.2126 * albedo.r + 0.7152 * albedo.g + 0.0722 * albedo.b;
+    const white = THREE.MathUtils.clamp((luma - 0.12) / 0.5, 0, 0.6);
+    if ('roughness' in m) {
+        m.roughnessMap = null;
+        m.roughness = 0.55 - 0.08 * white;
+        m.metalness = 0;
+        m.envMapIntensity = 0.35;
+    }
+    if (m.isMeshPhysicalMaterial) {
+        m.ior = 1.55;
+        m.specularIntensity = 0.055 + 0.1 * white;
+        m.specularColor = tint.clone().lerp(new THREE.Color(1, 1, 1), white);
+        m.sheen = 0.08;
+        m.sheenRoughness = 0.45;
+        m.sheenColor = albedo;
+    }
+    if ('roughness' in m)
+        fadeHairSpecular(m);
+    m.needsUpdate = true;
+}
+/** three's physical lighting setup, with hair specular faded at the silhouette. */
+export function patchHairSpecular(fs) {
+    if (!fs.includes('#include <lights_physical_fragment>'))
+        return fs;
+    return fs.replace('#include <lights_physical_fragment>', `#include <lights_physical_fragment>
+	{
+		// Cards are double-sided: either face toward the eye.
+		float embodyFacing = smoothstep( 0.05, 0.45, abs( dot( normal, normalize( vViewPosition ) ) ) );
+		material.specularColor *= embodyFacing;
+		material.specularF90 *= embodyFacing;
+	}`);
+}
+/**
+ * Coverage that follows the strand's own alpha. three's WebGL
+ * alpha-to-coverage applies the cut as a step (every texel fully in or
+ * out), so a fringe read as sparse separate strings with skin between them;
+ * coverage proportional to alpha (as WebGPU's is, and as the studio films
+ * were rendered) draws faint strand texels faintly and the hair reads full
+ * and soft, with alpha scaled back up on the smaller mips. Only
+ * near-empty texels are discarded.
+ */
+export function patchHairCoverage(fs) {
+    if (!fs.includes('#include <alphatest_fragment>'))
+        return fs;
+    return fs.replace('#include <alphatest_fragment>', `#ifdef USE_MAP
+	{
+		// Smaller mips average each strand's alpha with the gaps around it,
+		// so at a distance strands thin and vanish (forehead showing through
+		// a fringe). Scale alpha back up with the mip level sampled.
+		vec2 embodyPx = vMapUv * vec2( textureSize( map, 0 ) );
+		vec2 embodyDx = dFdx( embodyPx ), embodyDy = dFdy( embodyPx );
+		float embodyLod = max( 0.0, 0.5 * log2( max( dot( embodyDx, embodyDx ), dot( embodyDy, embodyDy ) ) ) );
+		diffuseColor.a = clamp( diffuseColor.a * ( 1.0 + embodyLod * 0.6 ), 0.0, 1.0 );
+	}
+	#endif
+	if ( diffuseColor.a < 0.02 ) discard;`);
+}
+/** Whether the renderer draws with multisampling, which alpha-to-coverage needs. */
+const multisampled = (renderer) => {
+    try {
+        return !!renderer?.getContext?.().getContextAttributes()?.antialias;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * WebGL: hair specular fades to nothing at the silhouette, and coverage
+ * follows alpha where the canvas is multisampled (without MSAA, coverage is
+ * ignored and the cards would draw solid: three's own cut is kept).
+ * Chains onto any hook.
+ */
+function fadeHairSpecular(m) {
+    if (m.userData.embodyHairSpecular)
+        return;
+    m.userData.embodyHairSpecular = true;
+    const before = m.onBeforeCompile;
+    const key = m.customProgramCacheKey.bind(m);
+    m.onBeforeCompile = (shader, renderer) => {
+        before.call(m, shader, renderer);
+        shader.fragmentShader = patchHairSpecular(shader.fragmentShader);
+        if (m.alphaToCoverage && multisampled(renderer))
+            shader.fragmentShader = patchHairCoverage(shader.fragmentShader);
+    };
+    m.customProgramCacheKey = () => `${key()}|embody-hair-spec${m.alphaToCoverage ? '-a2c' : ''}`;
+}
+/** Eyes, lashes, the mouth, and the films over the eyes. */
+const isFacePart = (mesh, mat) => isEye(baseName(mat.name)) || /teeth|tongue|occlusion|tearline|tear_line|cornea|lash/i.test(`${mesh.name} ${mat.name}`);
+/** Casts nothing, whatever the app sets castShadow to. */
+function noShadow(mesh) {
+    const mat = [mesh.material].flat()[0];
+    cutShadow(mesh, mat, NO_SHADOW);
+}
+/** Hair and other see-through texels below this coverage cast no shadow. */
+const SHADOW_CUT = 0.5;
+/** Past 1: every fragment is discarded, so the surface casts nothing. */
+const NO_SHADOW = 1.01;
+/**
+ * Hair, and every other see-through surface, casts shadow only where it is
+ * dense. Without this the skin under it was covered in dark marks:
+ *
+ *  · three's shadow pass copies the drawn material's `alphaTest` onto the
+ *    depth material every frame, custom or not, and the blended hair layer,
+ *    brows and face overlays draw at 0 to keep their soft edge; so they cast
+ *    their whole cards, as solid quads (measured on a Character Creator head:
+ *    a hard blob over half the face and the collar). The cut is set again in
+ *    `onBeforeShadow`, which three calls after that copy.
+ *  · cut at the drawing threshold, every faint wisp threw a long hard line
+ *    across the face under a key light.
+ *
+ * A see-through surface with no texture alpha (an eye-occlusion or tear-line
+ * film) casts nothing. Each mesh gets its own depth materials, so the cut does
+ * not recompile three's shared one. Point lights use the distance material.
+ */
+function cutShadow(mesh, mat, force) {
+    const map = mat.map ?? null;
+    const alphaMap = mat.alphaMap ?? null;
+    const cut = force ?? (map || alphaMap ? SHADOW_CUT : NO_SHADOW);
+    mesh.customDepthMaterial = new THREE.MeshDepthMaterial({ depthPacking: THREE.RGBADepthPacking, map, alphaMap, alphaTest: cut });
+    mesh.customDistanceMaterial = new THREE.MeshDistanceMaterial({ map, alphaMap, alphaTest: cut });
+    const before = mesh.onBeforeShadow;
+    mesh.onBeforeShadow = function (renderer, object, camera, shadowCamera, geometry, depthMaterial, group) {
+        before.call(this, renderer, object, camera, shadowCamera, geometry, depthMaterial, group);
+        if (depthMaterial === mesh.customDepthMaterial || depthMaterial === mesh.customDistanceMaterial)
+            depthMaterial.alphaTest = cut;
+    };
+    mesh.userData.embodyShadowCut = cut;
+}
+/** A physical copy of a standard skin material; textures are shared, not cloned. */
+function toPhysicalSkin(src) {
+    const m = new THREE.MeshPhysicalMaterial();
+    THREE.MeshStandardMaterial.prototype.copy.call(m, src);
+    return m;
+}
+/**
+ * Skin's response, on any physical skin (converted or shipped physical):
+ * dielectric at skin's IOR, a moderate specular, a faint warm sheen at
+ * grazing angles. Without a roughness map, 0.52: at a distance the pore
+ * detail mips flat, and glossier read as plastic; the pores roughen it
+ * further where they are (see the skin shader).
+ */
+function skinResponse(m, t = {}) {
+    m.metalness = 0;
+    m.metalnessMap = null;
+    m.ior = 1.4;
+    m.specularIntensity = t.specular ?? 0.6;
+    m.sheen = t.sheen ?? 0.06;
+    m.sheenRoughness = 0.55;
+    m.sheenColor = new THREE.Color(...(t.sheenColor ?? [0.9, 0.38, 0.28]));
+    if (!m.roughnessMap)
+        m.roughness = t.roughness ?? 0.52;
+    if (t.tint)
+        m.color.multiply(new THREE.Color(...t.tint));
+}
+let detailTexture = null;
+/**
+ * Seamless pore and fine-crease detail as a tangent-space normal map,
+ * deterministic (seeded) so every load is identical. Shared by every
+ * character: it is never stored on a material, so `dispose()` does not free
+ * it out from under another body.
+ */
+export function poreDetailTexture() {
+    if (detailTexture)
+        return detailTexture;
+    const size = 512;
+    let seed = 0x2f6b4e1;
+    const rand = () => ((seed = (seed * 1664525 + 1013904223) >>> 0) / 4294967296);
+    const lattice = (n) => {
+        const v = new Float32Array(n * n);
+        for (let i = 0; i < v.length; i++)
+            v[i] = rand();
+        return v;
+    };
+    // Two octaves of wrapping value noise: fine texture over creases.
+    const octaves = [[lattice(96), 96, 0.55], [lattice(32), 32, 0.3]];
+    const h = new Float32Array(size * size);
+    for (const [lat, n, amp] of octaves) {
+        for (let y = 0; y < size; y++)
+            for (let x = 0; x < size; x++) {
+                const fx = (x / size) * n, fy = (y / size) * n;
+                const x0 = Math.floor(fx), y0 = Math.floor(fy);
+                const tx = fx - x0, ty = fy - y0;
+                const sx = tx * tx * (3 - 2 * tx), sy = ty * ty * (3 - 2 * ty);
+                const at = (i, j) => lat[((j + n) % n) * n + ((i + n) % n)];
+                const top = at(x0, y0) + (at(x0 + 1, y0) - at(x0, y0)) * sx;
+                const bot = at(x0, y0 + 1) + (at(x0 + 1, y0 + 1) - at(x0, y0 + 1)) * sx;
+                h[y * size + x] += (top + (bot - top) * sy) * amp;
+            }
+    }
+    // Pores: small soft pits on 1.2% of texels, wrapped at the edges. Noise
+    // alone read as sand; pits are what reads as skin.
+    const pores = Math.round(size * size * 0.012);
+    for (let p = 0; p < pores; p++) {
+        const cx = rand() * size, cy = rand() * size, r = 0.8 + rand() * 1.4;
+        for (let dy = -3; dy <= 3; dy++)
+            for (let dx = -3; dx <= 3; dx++) {
+                const d = Math.hypot(dx, dy) / r;
+                if (d > 1.6)
+                    continue;
+                const x = (Math.round(cx + dx) + size) % size;
+                const y = (Math.round(cy + dy) + size) % size;
+                h[y * size + x] -= 0.45 * Math.exp(-d * d * 1.6);
+            }
+    }
+    const data = new Uint8Array(size * size * 4);
+    const H = (x, y) => h[((y + size) % size) * size + ((x + size) % size)];
+    for (let y = 0; y < size; y++)
+        for (let x = 0; x < size; x++) {
+            const nx = (H(x - 1, y) - H(x + 1, y)) * 2.2;
+            const ny = (H(x, y - 1) - H(x, y + 1)) * 2.2;
+            const l = Math.hypot(nx, ny, 1);
+            const o = (y * size + x) * 4;
+            data[o] = Math.round(((nx / l) * 0.5 + 0.5) * 255);
+            data[o + 1] = Math.round(((ny / l) * 0.5 + 0.5) * 255);
+            data[o + 2] = Math.round(((1 / l) * 0.5 + 0.5) * 255);
+            data[o + 3] = 255;
+        }
+    const tex = new THREE.DataTexture(data, size, size, THREE.RGBAFormat);
+    tex.wrapS = tex.wrapT = THREE.RepeatWrapping;
+    tex.magFilter = THREE.LinearFilter;
+    tex.minFilter = THREE.LinearMipmapLinearFilter;
+    tex.generateMipmaps = true;
+    tex.colorSpace = THREE.NoColorSpace;
+    tex.needsUpdate = true;
+    return (detailTexture = tex);
+}
+/** The anchors the WebGL patch hooks; absent in a shader it does not know. */
+const LIGHTS_ANCHOR = '#include <lights_physical_pars_fragment>';
+const NORMAL_ANCHOR = 'mapN.xy *= normalScale;';
+const SHADOW_PARS_ANCHOR = '#include <shadowmap_pars_fragment>';
+const LIGHTS_BEGIN_ANCHOR = '#include <lights_fragment_begin>';
+/** A shadowed light in three's lights_fragment_begin: `directLight.color *= ( … ) ? <shadow> : 1.0;`. */
+const SHADOWED = /directLight\.color \*= (\( directLight\.visible && receiveShadow \) \? [^;]+ : 1\.0);/g;
+/**
+ * How skin receives shadow (WebGL): a hair or collar shadow on skin read as
+ * a dark mark rather than shade. Two things a real face does that three's
+ * receiver does not:
+ *  · the edge is soft: light scatters a few millimetres under the skin, so
+ *    a shadow never ends on a texel staircase. The skin filters its shadow
+ *    over 16 samples, at least `embodyShadowSoft` texels wide, with PCF and
+ *    with BASIC (three's own: 5 samples at the light's radius with PCF, which
+ *    widened went grainy without temporal AA, and one hard sample with
+ *    BASIC, which r182 also gives apps asking for PCFSoftShadowMap);
+ *  · it is not grey: skin in shade glows faintly red from light carried in
+ *    from the lit side, so a shadow keeps `embodyShadowFloor` of the light,
+ *    warm, and never goes to the dull brown that read as dirt.
+ * VSM keeps three's filter (already soft) and takes only the floor.
+ */
+const SHADOW_RECEIVER = `
+uniform vec3 embodyShadowFloor;
+uniform float embodyShadowSoft;
+vec3 embodyShadowLight( float shadow ) {
+	return mix( embodyShadowFloor, vec3( 1.0 ), shadow );
+}
+float embodyIgn( vec2 p ) {
+	return fract( 52.9829189 * fract( dot( p, vec2( 0.06711056, 0.00583715 ) ) ) );
+}
+vec2 embodyDisk( int k, int n, float phi ) {
+	float r = sqrt( ( float( k ) + 0.5 ) / float( n ) );
+	float theta = float( k ) * 2.399963229728653 + phi;
+	return vec2( cos( theta ), sin( theta ) ) * r;
+}
+#if defined( USE_SHADOWMAP ) && defined( SHADOWMAP_TYPE_PCF )
+float embodySkinShadow( sampler2DShadow shadowMap, vec2 shadowMapSize, float shadowIntensity, float shadowBias, float shadowRadius, vec4 shadowCoord ) {
+	float shadow = 1.0;
+	shadowCoord.xyz /= shadowCoord.w;
+	shadowCoord.z += shadowBias;
+	bool inFrustum = shadowCoord.x >= 0.0 && shadowCoord.x <= 1.0 && shadowCoord.y >= 0.0 && shadowCoord.y <= 1.0;
+	if ( inFrustum && shadowCoord.z <= 1.0 ) {
+		float radius = max( shadowRadius, embodyShadowSoft ) / shadowMapSize.x;
+		float phi = embodyIgn( gl_FragCoord.xy ) * 6.28318530718;
+		shadow = 0.0;
+		for ( int k = 0; k < 16; k ++ ) {
+			shadow += texture( shadowMap, vec3( shadowCoord.xy + embodyDisk( k, 16, phi ) * radius, shadowCoord.z ) );
+		}
+		shadow /= 16.0;
+	}
+	return mix( 1.0, shadow, shadowIntensity );
+}
+#elif defined( USE_SHADOWMAP ) && ! defined( SHADOWMAP_TYPE_VSM )
+// BASIC: one hard comparison per pixel in three. Also what an app asking for
+// PCFSoftShadowMap gets in r182: it warns and sets the type on its local light
+// list, not the renderer, so programs see no PCF define. Same filter, compared
+// by hand.
+float embodySkinShadow( sampler2D shadowMap, vec2 shadowMapSize, float shadowIntensity, float shadowBias, float shadowRadius, vec4 shadowCoord ) {
+	float shadow = 1.0;
+	shadowCoord.xyz /= shadowCoord.w;
+	shadowCoord.z += shadowBias;
+	bool inFrustum = shadowCoord.x >= 0.0 && shadowCoord.x <= 1.0 && shadowCoord.y >= 0.0 && shadowCoord.y <= 1.0;
+	if ( inFrustum && shadowCoord.z <= 1.0 ) {
+		float radius = max( shadowRadius, embodyShadowSoft ) / shadowMapSize.x;
+		float phi = embodyIgn( gl_FragCoord.xy ) * 6.28318530718;
+		shadow = 0.0;
+		for ( int k = 0; k < 16; k ++ ) {
+			float depth = texture2D( shadowMap, shadowCoord.xy + embodyDisk( k, 16, phi ) * radius ).r;
+			#ifdef USE_REVERSED_DEPTH_BUFFER
+			shadow += step( depth, shadowCoord.z );
+			#else
+			shadow += step( shadowCoord.z, depth );
+			#endif
+		}
+		shadow /= 16.0;
+	}
+	return mix( 1.0, shadow, shadowIntensity );
+}
+#else
+#define embodySkinShadow getShadow
+#endif
+`;
+/**
+ * Farthest skin looks up its shadow off the surface, metres. A light's
+ * `normalBias` is set for its scene; at 2 cm (common for rooms) the lookup
+ * on a neck passed the collar 1 cm away, and the collar's shadow broke into
+ * faceted stripes along the neck's triangles. Skin clamps it to face scale.
+ */
+const SKIN_MAX_NORMAL_BIAS = 0.004;
+/** three's shadowmap_vertex, with the normal offset clamped to face scale. */
+export function skinShadowVertex(chunk) {
+    return chunk.replace(/(\w+LightShadows\[ i \])\.shadowNormalBias/g, `min( $1.shadowNormalBias, ${SKIN_MAX_NORMAL_BIAS.toFixed(3)} )`);
+}
+/**
+ * A lit fragment shader receiving shadow as described above. Unchanged when
+ * it has no lights (or is already patched).
+ */
+export function patchShadowReceiver(fragmentShader) {
+    if (!fragmentShader.includes(SHADOW_PARS_ANCHOR) || !fragmentShader.includes(LIGHTS_BEGIN_ANCHOR))
+        return fragmentShader;
+    return fragmentShader
+        .replace(SHADOW_PARS_ANCHOR, `${SHADOW_PARS_ANCHOR}\n${SHADOW_RECEIVER}`)
+        .replace(LIGHTS_BEGIN_ANCHOR, skinLightsBegin(THREE.ShaderChunk.lights_fragment_begin));
+}
+/**
+ * Every other lit surface on the character (clothing, hair, eyes) receives
+ * shadow the same way, soft and at face scale, with no warm floor: a collar
+ * on a shirt stair-stepped exactly as it did on the neck. Chains onto any
+ * shader hook the material already has.
+ */
+function installShadowReceiver(m) {
+    if (m.userData.embodyShadow)
+        return;
+    const uniforms = { embodyShadowFloor: { value: new THREE.Color(0, 0, 0) }, embodyShadowSoft: { value: 3 } };
+    m.userData.embodyShadow = uniforms;
+    const before = m.onBeforeCompile;
+    const key = m.customProgramCacheKey.bind(m);
+    m.onBeforeCompile = (shader, renderer) => {
+        before.call(m, shader, renderer);
+        Object.assign(shader.uniforms, uniforms);
+        shader.fragmentShader = patchShadowReceiver(shader.fragmentShader);
+        if (shader.vertexShader)
+            shader.vertexShader = shader.vertexShader.replace('#include <shadowmap_vertex>', skinShadowVertex(THREE.ShaderChunk.shadowmap_vertex));
+    };
+    m.customProgramCacheKey = () => `${key()}|embody-shadow`;
+}
+/** three's lights_fragment_begin, with skin's shadow receiver. */
+export function skinLightsBegin(chunk) {
+    return chunk
+        .replace(/\bgetShadow\(/g, 'embodySkinShadow(')
+        .replace(SHADOWED, 'directLight.color *= embodyShadowLight( $1 );');
+}
+/**
+ * Patch three's WebGL physical fragment shader for skin. Exported for the
+ * test, which runs it on three's real shader source. A shader without the
+ * anchors (a future three, a custom material) is returned unchanged.
+ */
+export function patchSkinShader(fragmentShader, withDetail) {
+    if (!fragmentShader.includes(LIGHTS_ANCHOR))
+        return fragmentShader;
+    let s = fragmentShader.replace(LIGHTS_ANCHOR, `${LIGHTS_ANCHOR}
+uniform float embodyWrap;
+uniform float embodySubsurface;
+uniform float embodyTranslucency;
+void RE_Direct_EmbodySkin( const in IncidentLight directLight, const in vec3 geometryPosition, const in vec3 geometryNormal, const in vec3 geometryViewDir, const in vec3 geometryClearcoatNormal, const in PhysicalMaterial material, inout ReflectedLight reflectedLight ) {
+	RE_Direct_Physical( directLight, geometryPosition, geometryNormal, geometryViewDir, geometryClearcoatNormal, material, reflectedLight );
+	float nl = dot( geometryNormal, directLight.direction );
+	// Only the band past the terminator is added; the lit side is Lambert's.
+	float band = saturate( ( nl + embodyWrap ) / ( 1.0 + embodyWrap ) ) - saturate( nl );
+	reflectedLight.directDiffuse += band * directLight.color * material.diffuseColor * vec3( 0.5, 0.4, 0.36 ) * embodySubsurface;
+	vec3 through = normalize( directLight.direction + geometryNormal * 0.25 );
+	float back = pow( saturate( dot( geometryViewDir, - through ) ), 3.0 ) * embodyTranslucency;
+	reflectedLight.directDiffuse += back * directLight.color * material.diffuseColor * vec3( 0.75, 0.3, 0.2 );
+}
+#undef RE_Direct
+#define RE_Direct RE_Direct_EmbodySkin`);
+    s = patchShadowReceiver(s);
+    // Scalp under hair (shadeScalp's vertex colour, 1 bare to 0.3 under hair):
+    // matte and without specular, which caught the light pink through the
+    // hair even once darkened.
+    if (s.includes('#include <roughnessmap_fragment>') && s.includes('#include <lights_physical_fragment>')) {
+        s = s.replace('#include <roughnessmap_fragment>', `#include <roughnessmap_fragment>
+	#if defined( USE_COLOR ) || defined( USE_COLOR_ALPHA )
+	float embodyUnderHair = clamp( ( 1.0 - vColor.r ) / 0.7, 0.0, 1.0 );
+	roughnessFactor = mix( roughnessFactor, 0.85, embodyUnderHair );
+	#endif`);
+        s = s.replace('#include <lights_physical_fragment>', `#include <lights_physical_fragment>
+	#if defined( USE_COLOR ) || defined( USE_COLOR_ALPHA )
+	material.specularColor *= 1.0 - 0.8 * embodyUnderHair;
+	material.specularF90 *= 1.0 - 0.8 * embodyUnderHair;
+	#endif`);
+    }
+    if (withDetail && s.includes(NORMAL_ANCHOR)) {
+        s = s.replace('void main() {', 'uniform sampler2D embodyDetailMap;\nuniform float embodyDetail;\nuniform float embodyDetailTile;\nvoid main() {');
+        s = s.replace('#include <roughnessmap_fragment>', `#include <roughnessmap_fragment>
+	// Specular breaks up with the pores: pits and creases are rougher.
+	roughnessFactor = clamp( roughnessFactor + ( 1.0 - texture2D( embodyDetailMap, vNormalMapUv * embodyDetailTile ).z ) * 0.6, 0.0, 1.0 );`);
+        s = s.replace(NORMAL_ANCHOR, `${NORMAL_ANCHOR}
+	vec3 embodyPore = texture2D( embodyDetailMap, vNormalMapUv * embodyDetailTile ).xyz * 2.0 - 1.0;
+	mapN = normalize( vec3( mapN.xy + embodyPore.xy * embodyDetail, mapN.z * embodyPore.z ) );`);
+    }
+    return s;
+}
+function installSkinShader(m, tuning) {
+    const detail = tuning.detail ?? 0.16;
+    const withDetail = detail > 0 && !!m.normalMap;
+    const uniforms = {
+        embodyWrap: { value: tuning.wrap ?? 0.65 },
+        embodySubsurface: { value: tuning.subsurface ?? 0.45 },
+        embodyTranslucency: { value: tuning.translucency ?? 0.3 },
+        embodyDetailMap: { value: withDetail ? poreDetailTexture() : null },
+        embodyDetail: { value: detail },
+        embodyDetailTile: { value: tuning.detailTile ?? 30 },
+        embodyShadowFloor: { value: new THREE.Color(...(tuning.shadowFloor ?? SHADOW_FLOOR)) },
+        embodyShadowSoft: { value: tuning.shadowSoftness ?? 3 },
+    };
+    m.userData.embodySkin = uniforms;
+    m.onBeforeCompile = (shader) => {
+        Object.assign(shader.uniforms, uniforms);
+        shader.fragmentShader = patchSkinShader(shader.fragmentShader, withDetail);
+        if (shader.vertexShader)
+            shader.vertexShader = shader.vertexShader.replace('#include <shadowmap_vertex>', skinShadowVertex(THREE.ShaderChunk.shadowmap_vertex));
+    };
+    m.customProgramCacheKey = () => `embody-skin-${withDetail ? 1 : 0}`;
+}
+/**
+ * Darken the head's vertices that sit under hair: within `near` of a hair
+ * vertex lying over them (within 60° of the skin's outward normal), above
+ * the eyes. Hair beside the skin does not count: at the hairline the fringe
+ * lies along the forehead, and counting it tinted a hard brown strip below
+ * the hairline (the published heads have ~2.6k vertices, so a tinted row
+ * reads as a band). The shade also scales with how much hair is over the
+ * vertex, so it fades out through the thinning hairline. Reads skinned positions in WORLD space, so call it
+ * after the body is scaled to metres and before anything animates it.
+ */
+export function shadeScalp(root, opts = {}) {
+    const near = opts.near ?? 0.01;
+    const far = opts.far ?? 0.025;
+    let head = null;
+    let eyes = null;
+    const hair = [];
+    root.updateMatrixWorld(true);
+    root.traverse((o) => {
+        const mesh = o;
+        if (!mesh.isMesh || !mesh.visible)
+            return;
+        const mat = (Array.isArray(mesh.material) ? mesh.material[0] : mesh.material);
+        if (!head && mesh.isSkinnedMesh && isSkin(mat) && /head/i.test(baseName(mat.name)))
+            head = mesh;
+        else if (!eyes && mesh.isSkinnedMesh && /^eyes?$/i.test(baseName(mat.name)))
+            eyes = mesh;
+        else if (isHairLike(mesh, mat) && HAIR_MESH.test(mesh.name) && !/brow|lash/i.test(mesh.name))
+            hair.push(mesh);
+    });
+    if (!head || !hair.length)
+        return 0;
+    const headMesh = head;
+    const v = new THREE.Vector3();
+    const world = (m, i) => m.isSkinnedMesh
+        ? m.getVertexPosition(i, v).applyMatrix4(m.matrixWorld)
+        : v.fromBufferAttribute(m.geometry.attributes.position, i).applyMatrix4(m.matrixWorld);
+    // Hair vertices hashed into `far`-sized cells: every hair vertex within
+    // `far` of a point lies in its cell or one of the 26 around it.
+    const grid = new Map();
+    const cellOf = (x, y, z) => ((Math.floor(x / far) + 512) * 1024 + (Math.floor(y / far) + 512)) * 1024 + (Math.floor(z / far) + 512);
+    for (const m of hair) {
+        const count = m.geometry.attributes.position.count;
+        for (let i = 0; i < count; i += 3) {
+            const p = world(m, i);
+            const k = cellOf(p.x, p.y, p.z);
+            let cell = grid.get(k);
+            if (!cell)
+                grid.set(k, (cell = []));
+            cell.push(p.x, p.y, p.z);
+        }
+    }
+    // Scalp only: hair hanging beside the cheeks must not shade the face. The
+    // eyes' height marks the face; without eyes, everything near hair counts.
+    let eyeY = -Infinity;
+    if (eyes) {
+        const e = eyes;
+        const count = e.geometry.attributes.position.count;
+        let sum = 0;
+        for (let i = 0; i < count; i++)
+            sum += world(e, i).y;
+        eyeY = sum / count;
+    }
+    const count = headMesh.geometry.attributes.position.count;
+    const pos = new Float32Array(count * 3);
+    for (let i = 0; i < count; i++)
+        world(headMesh, i).toArray(pos, i * 3);
+    const normals = posedNormals(headMesh.geometry, pos);
+    const colors = new Float32Array(count * 3).fill(1);
+    // Scalp seen through hair takes the hair's colour, as a real one does (a
+    // fixed skin-grey left a parting reading bald under dark hair). Darker
+    // than the hair's mean, never brighter than the old skin shade.
+    const hairMap = hair.map((m) => [m.material].flat()[0]).find((m) => m.map);
+    const hairColor = meanTextureColor(hairMap?.map)?.multiply(hairMap.color) ?? null;
+    const tint = hairColor ? new THREE.Color(Math.min(0.3, hairColor.r * 0.8), Math.min(0.28, hairColor.g * 0.8), Math.min(0.27, hairColor.b * 0.8)) : new THREE.Color(0.3, 0.28, 0.27);
+    const p = new THREE.Vector3();
+    const n = new THREE.Vector3();
+    const near_ = new Float32Array(count).fill(Infinity);
+    const over_ = new Float32Array(count);
+    for (let i = 0; i < count; i++) {
+        p.fromArray(pos, i * 3);
+        if (p.y < eyeY + 0.03)
+            continue;
+        n.fromArray(normals, i * 3);
+        const facing = n.lengthSq() > 0;
+        let best = Infinity;
+        let anyBest = Infinity;
+        let over = 0;
+        for (let dx = -1; dx <= 1; dx++)
+            for (let dy = -1; dy <= 1; dy++)
+                for (let dz = -1; dz <= 1; dz++) {
+                    const cell = grid.get(cellOf(p.x + dx * far, p.y + dy * far, p.z + dz * far));
+                    if (!cell)
+                        continue;
+                    for (let j = 0; j < cell.length; j += 3) {
+                        const x = cell[j] - p.x, y = cell[j + 1] - p.y, z = cell[j + 2] - p.z;
+                        const d = x * x + y * y + z * z;
+                        if (d > far * far)
+                            continue;
+                        if (d < anyBest)
+                            anyBest = d;
+                        // Over the skin, not beside it: cos(angle to the normal) ≥ 0.5.
+                        const out = x * n.x + y * n.y + z * n.z;
+                        if (facing && (out <= 0 || out * out < 0.25 * d))
+                            continue;
+                        over++;
+                        if (d < best)
+                            best = d;
+                    }
+                }
+        // Hair lying over the skin counts on the forehead (where the fringe lies
+        // along it); on the scalp any hair near counts (at a parting it lies
+        // beside the skin, not over it, and the parting showed bare pink).
+        const forward = THREE.MathUtils.smoothstep(n.z, 0.35, 0.75);
+        near_[i] = Math.sqrt(forward > 0.5 ? best : anyBest);
+        over_[i] = over;
+    }
+    // How much hair is over a vertex, against this body's own full head of hair
+    // (the 90th percentile; point counts depend on how the hair is tessellated).
+    // The thinning fringe at the hairline fades out: on CineFemale-type heads it
+    // has 0–20 sampled points over it against 20–160 on the scalp.
+    const counts = Array.from(over_).filter((c) => c > 0).sort((a, b) => a - b);
+    const full = counts.length ? counts[Math.floor(counts.length * 0.9)] : 0;
+    let shaded = 0;
+    for (let i = 0; i < count; i++) {
+        if (near_[i] === Infinity)
+            continue;
+        p.fromArray(pos, i * 3);
+        const aboveFace = eyeY === -Infinity ? 1 : THREE.MathUtils.smoothstep(p.y, eyeY + 0.03, eyeY + 0.05);
+        // Only at the forehead hairline (skin facing forward): there the fringe
+        // thins out over the skin. Scalp facing up (the crown, a parting) keeps
+        // the full shade however few strands cover it, or it showed bare pink.
+        // Forward-facing skin (a forehead, however high the hairline: no fixed
+        // height holds across heads) counts hair over it, not beside it.
+        const forward = THREE.MathUtils.smoothstep(normals[i * 3 + 2], 0.35, 0.75);
+        const dense = 1 - forward * (1 - THREE.MathUtils.smoothstep(over_[i], DENSE_FROM * full, DENSE_FULL * full));
+        const w = (1 - THREE.MathUtils.smoothstep(near_[i], near, far)) * aboveFace * dense;
+        if (w <= 0)
+            continue;
+        shaded++;
+        // Scalp facing up takes the hair's colour; a forehead under hair only
+        // darkens, keeping its own hue (hair-tinted, bare forehead under a quiff
+        // read as a grey patch).
+        const grey = Math.max(0.45, (tint.r + tint.g + tint.b) / 3);
+        const r = tint.r + (grey - tint.r) * forward, g = tint.g + (grey - tint.g) * forward, b = tint.b + (grey - tint.b) * forward;
+        colors[i * 3] = 1 + (r - 1) * w;
+        colors[i * 3 + 1] = 1 + (g - 1) * w;
+        colors[i * 3 + 2] = 1 + (b - 1) * w;
+    }
+    if (!shaded)
+        return 0;
+    headMesh.geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+    for (const m of [headMesh.material].flat()) {
+        m.vertexColors = true;
+        m.needsUpdate = true;
+    }
+    return shaded;
+}
+/** Hair over a scalp vertex, as a share of a full head's, where its shade starts and is full. */
+const DENSE_FROM = 0.08;
+const DENSE_FULL = 0.4;
+/**
+ * Depth in the hair: strands near the scalp sit under the ones above them and
+ * get less light, so a real head of hair is darker at the roots and inside
+ * than on its outer shell. Card hair carries none of that unless its texture
+ * bakes it in (the long cuts do, a short light cut did not and read as a flat
+ * cap). Each hair vertex is darkened by how close it lies to the head,
+ * against this hair's own thickness (its 90th-percentile distance from the
+ * head), as a vertex colour that multiplies the diffuse: roots to ~45% on
+ * light hair, less on dark hair, where the texture already carries the depth
+ * and the same darkening would have read as a different cut. Reads skinned
+ * positions in WORLD space: call it after the body is scaled to metres and
+ * before anything animates it. Returns the number of hair vertices shaded.
+ */
+export function shadeHairDepth(root) {
+    let head = null;
+    const hair = [];
+    root.updateMatrixWorld(true);
+    root.traverse((o) => {
+        const mesh = o;
+        if (!mesh.isMesh || !mesh.visible)
+            return;
+        const mat = (Array.isArray(mesh.material) ? mesh.material[0] : mesh.material);
+        if (!head && mesh.isSkinnedMesh && isSkin(mat) && /head/i.test(baseName(mat.name)))
+            head = mesh;
+        else if (isHairLike(mesh, mat) && HAIR_MESH.test(mesh.name) && !/brow|lash/i.test(mesh.name))
+            hair.push(mesh);
+    });
+    if (!head || !hair.length)
+        return 0;
+    const headMesh = head;
+    const v = new THREE.Vector3();
+    const world = (m, i) => m.isSkinnedMesh
+        ? m.getVertexPosition(i, v).applyMatrix4(m.matrixWorld)
+        : v.fromBufferAttribute(m.geometry.attributes.position, i).applyMatrix4(m.matrixWorld);
+    // Head vertices hashed into cells of `reach`: the nearest head vertex to
+    // a hair vertex within `reach` lies in its cell or one of the 26 around it.
+    const reach = 0.06;
+    const grid = new Map();
+    const cellOf = (x, y, z) => ((Math.floor(x / reach) + 512) * 1024 + (Math.floor(y / reach) + 512)) * 1024 + (Math.floor(z / reach) + 512);
+    const headCount = headMesh.geometry.attributes.position.count;
+    for (let i = 0; i < headCount; i++) {
+        const p = world(headMesh, i);
+        const k = cellOf(p.x, p.y, p.z);
+        let cell = grid.get(k);
+        if (!cell)
+            grid.set(k, (cell = []));
+        cell.push(p.x, p.y, p.z);
+    }
+    const nearest = (p) => {
+        let best = reach * reach;
+        for (let dx = -1; dx <= 1; dx++)
+            for (let dy = -1; dy <= 1; dy++)
+                for (let dz = -1; dz <= 1; dz++) {
+                    const cell = grid.get(cellOf(p.x + dx * reach, p.y + dy * reach, p.z + dz * reach));
+                    if (!cell)
+                        continue;
+                    for (let j = 0; j < cell.length; j += 3) {
+                        const x = cell[j] - p.x, y = cell[j + 1] - p.y, z = cell[j + 2] - p.z;
+                        const d = x * x + y * y + z * z;
+                        if (d < best)
+                            best = d;
+                    }
+                }
+        return Math.sqrt(best);
+    };
+    let shaded = 0;
+    const p = new THREE.Vector3();
+    for (const m of hair) {
+        const count = m.geometry.attributes.position.count;
+        const depth = new Float32Array(count);
+        for (let i = 0; i < count; i++)
+            depth[i] = nearest(world(m, i).clone());
+        const sorted = Array.from(depth).sort((a, b) => a - b);
+        const thick = sorted[Math.floor(sorted.length * 0.9)] ?? 0;
+        if (!(thick > 0.004))
+            continue; // a cap painted on the scalp has no depth to shade
+        const mat = [m.material].flat()[0];
+        const albedo = meanTextureColor(mat.map) ?? mat.color.clone();
+        const luma = 0.2126 * albedo.r + 0.7152 * albedo.g + 0.0722 * albedo.b;
+        // How dark the roots go: light hair 55%, dark hair 25% (its texture
+        // already carries the depth).
+        const strength = 0.25 + 0.3 * THREE.MathUtils.clamp((luma - 0.08) / 0.4, 0, 1);
+        const colors = new Float32Array(count * 3);
+        for (let i = 0; i < count; i++) {
+            const w = 1 - THREE.MathUtils.smoothstep(depth[i], 0, thick);
+            const c = 1 - strength * w * w;
+            colors[i * 3] = colors[i * 3 + 1] = colors[i * 3 + 2] = c;
+        }
+        m.geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+        for (const x of [m.material].flat()) {
+            x.vertexColors = true;
+            x.needsUpdate = true;
+        }
+        shaded += count;
+    }
+    return shaded;
+}
+/** Area-weighted vertex normals of `geometry` at the positions `pos`. */
+function posedNormals(geometry, pos) {
+    const out = new Float32Array(pos.length);
+    const index = geometry.index;
+    const tris = index ? index.count : pos.length / 3;
+    const a = new THREE.Vector3(), b = new THREE.Vector3(), c = new THREE.Vector3();
+    for (let t = 0; t + 2 < tris; t += 3) {
+        const i = index ? index.getX(t) : t, j = index ? index.getX(t + 1) : t + 1, k = index ? index.getX(t + 2) : t + 2;
+        a.fromArray(pos, i * 3);
+        b.fromArray(pos, j * 3).sub(a);
+        c.fromArray(pos, k * 3).sub(a);
+        b.cross(c);
+        for (const v of [i, j, k]) {
+            out[v * 3] += b.x;
+            out[v * 3 + 1] += b.y;
+            out[v * 3 + 2] += b.z;
+        }
+    }
+    for (let v = 0; v < out.length; v += 3) {
+        const l = Math.hypot(out[v], out[v + 1], out[v + 2]);
+        if (l > 0) {
+            out[v] /= l;
+            out[v + 1] /= l;
+            out[v + 2] /= l;
+        }
+    }
+    return out;
+}
+/**
+ * Upgrade skin and hair materials in place (skin materials are replaced on
+ * their meshes; the originals are disposed, their textures kept). Run once
+ * after load. `shadeScalp` is separate because it needs the body in metres.
+ */
+export function applySurfaces(root, tuning = {}) {
+    const report = { skin: 0, hair: 0, textures: 0, scalp: 0 };
+    const anisotropy = tuning.anisotropy ?? 16;
+    const lashCap = tuning.lashOpacity ?? (/^male$/i.test(tuning.gender ?? '') ? LASH_MALE : undefined);
+    const male = /^male$/i.test(tuning.gender ?? '');
+    const skinTuning = tuning.skin === false ? null : { ...(male ? MALE_SKIN : {}), ...(tuning.skin === true || !tuning.skin ? {} : tuning.skin) };
+    const replaced = new Map();
+    const tunedHair = new Set();
+    const textures = new Set();
+    // The export ships hair twice, a blended layer and an alpha-tested copy of
+    // the same cards: drawn as coverage they look the same, and the second
+    // copy halved the frame rate. A blended hair mesh with such a twin is
+    // hidden; one without keeps drawing (as coverage).
+    const hairCounts = new Set();
+    root.traverse((o) => {
+        const m = o;
+        if (m.isMesh && m.visible && [m.material].flat().some((x) => isHairLike(m, x) && !x.transparent))
+            hairCounts.add(m.geometry.attributes.position?.count ?? -1);
+    });
+    root.traverse((o) => {
+        const mesh = o;
+        if (!mesh.isMesh)
+            return;
+        const list = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        if (tuning.hair !== false && list.every((x) => isHairLike(mesh, x) && x.transparent) && hairCounts.has(mesh.geometry.attributes.position?.count ?? -2)) {
+            mesh.visible = false;
+            return;
+        }
+        // The small face parts: no shadows (lashes, eyes, the socket film and the
+        // mouth threw jagged slivers across the face), and never culled (their
+        // bounding spheres are the bind pose's, and in close-ups the eyes and
+        // mouth blinked out while on screen).
+        if (list.some((x) => isFacePart(mesh, x))) {
+            noShadow(mesh);
+            mesh.frustumCulled = false;
+        }
+        // A lit surface needs normals; geometry exported for an unlit material
+        // often has none, and lit it renders black.
+        const g = mesh.geometry;
+        if (g.attributes.position && !g.attributes.normal && list.some((m) => m.isMeshStandardMaterial))
+            g.computeVertexNormals();
+        const next = list.map((mat) => {
+            for (const k of TEXTURE_KEYS) {
+                const t = mat[k];
+                if (t && !textures.has(t)) {
+                    textures.add(t);
+                    t.anisotropy = Math.max(t.anisotropy, anisotropy);
+                    t.needsUpdate = true;
+                }
+            }
+            if (tuning.hair !== false && isHairLike(mesh, mat)) {
+                if (!tunedHair.has(mat)) {
+                    tunedHair.add(mat);
+                    tuneHair(mesh, mat, isLash(mesh, mat));
+                    if (isLash(mesh, mat) && lashCap !== undefined && mat.opacity > lashCap)
+                        mat.opacity = lashCap;
+                    report.hair++;
+                }
+                if (!mesh.customDepthMaterial)
+                    cutShadow(mesh, mat);
+                if (mat.isMeshStandardMaterial)
+                    installShadowReceiver(mat);
+                return mat;
+            }
+            if (skinTuning && isSkin(mat)) {
+                const done = replaced.get(mat);
+                if (done)
+                    return done;
+                const std = mat;
+                const skin = std.isMeshPhysicalMaterial ? std : toPhysicalSkin(std);
+                if (skin !== mat)
+                    skin.name = mat.name;
+                skinResponse(skin, skinTuning);
+                installSkinShader(skin, skinTuning);
+                replaced.set(mat, skin);
+                report.skin++;
+                return skin;
+            }
+            // Any other see-through surface (eye-occlusion and tear-line films,
+            // lace, visors): the same cut, or no shadow without texture alpha.
+            if (mat.transparent && !mesh.customDepthMaterial)
+                cutShadow(mesh, mat);
+            if (mat.isMeshStandardMaterial)
+                installShadowReceiver(mat);
+            return mat;
+        });
+        mesh.material = Array.isArray(mesh.material) ? next : next[0];
+    });
+    for (const [old, now] of replaced)
+        if (old !== now)
+            old.dispose();
+    report.textures = textures.size;
+    return report;
+}