cozyclay 3.1.0 → 3.1.2

package/src/material-look.js

@@ -0,0 +1,189 @@
+/**
+ * Material presets as three.js materials (the table is material-presets.js),
+ * one factory for sculpt parts and plain primitives. `lookMaterial(look)`
+ * mints a material per call, which the caller owns and disposes; its detail
+ * comes from pattern textures (material-textures.js) generated once per
+ * pattern on first draw and shared by every material that uses it, so no one
+ * owner may free them (material.dispose() leaves uniforms alone).
+ *
+ * Mapping is triplanar in the mesh's own frame, measured in metres (the
+ * frame's scale is divided back out): the pattern rides with a moving prop,
+ * keeps its size on a stretched cube and never reads a geometry's UVs, which
+ * on a blob's remapped UV sphere would pinch at the poles. A directional
+ * pattern (grain, thatch, brick courses) runs along the axis the vertex
+ * shader picks from the part's size and its tilt in the world. The shader
+ * text is the same for every preset (only uniforms differ), so all of them
+ * share one compiled program per material class.
+ *
+ * Reflections: the studio stage look has no scene environment, and a metal
+ * there would reflect black. While the scene has none, the reflective presets
+ * take a RoomEnvironment prefiltered once per renderer; on a stage with an
+ * environment they reflect that one, at its intensity, like everything else.
+ */
+
+import * as THREE from "three";
+import { RoomEnvironment } from "three/examples/jsm/environments/RoomEnvironment.js";
+import { FINISH_ROUGHNESS, MATERIAL_LOOKS, lookTint } from "./material-presets.js";
+import { PATTERN_SIZE, patternPixels } from "./material-textures.js";
+
+const VERTEX_HEAD = `
+uniform vec3 lookExtent;
+uniform float lookTile;
+uniform float lookGrain;
+varying vec3 vLookPos;
+varying vec3 vLookNormal;`;
+
+// lookGrain: 0 the part's own y, 1 its longest side, 2 its most upright side
+// (a slab's thickness never counts). A downward axis is flipped so a thatch
+// course's lower edge stays at the bottom.
+const VERTEX_BODY = `
+mat3 lookFrame = mat3( modelMatrix );
+#ifdef USE_INSTANCING
+	lookFrame = lookFrame * mat3( instanceMatrix );
+#endif
+vec3 lookSize = max( vec3( length( lookFrame[ 0 ] ), length( lookFrame[ 1 ] ), length( lookFrame[ 2 ] ) ), vec3( 1e-6 ) );
+vec3 lookExt = lookExtent * lookSize;
+vec3 lookUp = vec3( lookFrame[ 0 ].y, lookFrame[ 1 ].y, lookFrame[ 2 ].y ) / lookSize;
+int lookAxis = 1;
+if ( lookGrain > 1.5 ) {
+	vec3 score = abs( lookUp );
+	float thin = min( lookExt.x, min( lookExt.y, lookExt.z ) );
+	float mid = lookExt.x + lookExt.y + lookExt.z - thin - max( lookExt.x, max( lookExt.y, lookExt.z ) );
+	if ( thin < 0.35 * mid ) score -= 2.0 * vec3( equal( lookExt, vec3( thin ) ) );
+	lookAxis = score.x >= score.y && score.x >= score.z ? 0 : ( score.y >= score.z ? 1 : 2 );
+} else if ( lookGrain > 0.5 ) {
+	lookAxis = lookExt.x >= lookExt.y && lookExt.x >= lookExt.z ? 0 : ( lookExt.y >= lookExt.z ? 1 : 2 );
+}
+vec3 lookP = transformed * lookSize / lookTile;
+vec3 lookN = objectNormal / lookSize;
+if ( lookAxis == 0 ) { lookP = lookP.yxz; lookN = lookN.yxz; }
+else if ( lookAxis == 2 ) { lookP = lookP.xzy; lookN = lookN.xzy; }
+if ( lookGrain > 1.5 && lookUp[ lookAxis ] < 0.0 ) { lookP.y = - lookP.y; lookN.y = - lookN.y; }
+vLookPos = lookP;
+vLookNormal = lookN;`;
+
+// Bump is Mikkelsen's surface gradient with unnormalized screen derivatives,
+// so `lookAmount.y` is a real relief depth in metres at any distance.
+const FRAGMENT_HEAD = `
+uniform sampler2D lookMap;
+uniform vec4 lookAmount;
+uniform vec3 lookMask;
+varying vec3 vLookPos;
+varying vec3 vLookNormal;
+vec4 lookTriplanar( vec3 q, vec3 w ) {
+	return texture2D( lookMap, q.zy ) * w.x + texture2D( lookMap, q.xz ) * w.y + texture2D( lookMap, q.xy ) * w.z;
+}
+vec3 lookPerturb( vec3 pos, vec3 n, vec2 dH, float face ) {
+	vec3 sx = dFdx( pos ), sy = dFdy( pos );
+	vec3 r1 = cross( sy, n ), r2 = cross( n, sx );
+	float det = dot( sx, r1 ) * face;
+	if ( abs( det ) < 1e-14 ) return n;
+	return normalize( abs( det ) * n - sign( det ) * ( dH.x * r1 + dH.y * r2 ) );
+}`;
+
+const FRAGMENT_COLOR = `
+vec3 lookW = pow( abs( normalize( vLookNormal ) ), vec3( 4.0 ) );
+lookW /= lookW.x + lookW.y + lookW.z;
+vec4 lookTex = lookTriplanar( vLookPos, lookW );
+vec2 lookDH = lookAmount.y * ( vec2( lookTriplanar( vLookPos + dFdx( vLookPos ), lookW ).g, lookTriplanar( vLookPos + dFdy( vLookPos ), lookW ).g ) - lookTex.g );
+diffuseColor.rgb *= max( 0.0, 1.0 + ( lookTex.r - 0.5 ) * 2.0 * lookAmount.x );
+diffuseColor.rgb = mix( diffuseColor.rgb, lookMask, lookTex.a * lookAmount.w );`;
+
+const FRAGMENT_ROUGHNESS = "\nroughnessFactor = clamp( roughnessFactor + ( lookTex.b - 0.5 ) * 2.0 * lookAmount.z, 0.03, 1.0 );";
+const FRAGMENT_NORMAL = "\nnormal = lookPerturb( - vViewPosition, normal, lookDH, faceDirection );";
+
+const after = (marker, code) => (source) => source.replace(marker, `${marker}${code}`);
+const patchVertex = [after("#include <common>", VERTEX_HEAD), after("#include <begin_vertex>", VERTEX_BODY)];
+const patchFragment = [after("#include <common>", FRAGMENT_HEAD), after("#include <color_fragment>", FRAGMENT_COLOR),
+	after("#include <roughnessmap_fragment>", FRAGMENT_ROUGHNESS), after("#include <normal_fragment_maps>", FRAGMENT_NORMAL)];
+const GRAIN = { up: 0, long: 1, hang: 2 };
+
+const patternTextures = new Map();
+/** The shared tile for a pattern, made on first use. Never disposed: every
+ * material of the preset, now and later, samples the same one. */
+function patternTexture(pattern) {
+	let texture = patternTextures.get(pattern);
+	if (!texture) {
+		texture = new THREE.DataTexture(patternPixels(pattern), PATTERN_SIZE, PATTERN_SIZE);
+		texture.wrapS = texture.wrapT = THREE.RepeatWrapping;
+		texture.magFilter = THREE.LinearFilter;
+		texture.minFilter = THREE.LinearMipmapLinearFilter;
+		texture.generateMipmaps = true;
+		texture.anisotropy = 8;
+		texture.needsUpdate = true;
+		patternTextures.set(pattern, texture);
+	}
+	return texture;
+}
+
+/** Hooks the pattern into a material. The texture is fetched at compile time,
+ * which only a renderer does, so Node never generates one. */
+function addPattern(material, preset, size) {
+	const uniforms = {
+		lookMap: { value: null },
+		lookTile: { value: preset.tile },
+		lookExtent: { value: new THREE.Vector3(...size) },
+		lookGrain: { value: GRAIN[preset.grain ?? "up"] },
+		lookAmount: { value: new THREE.Vector4(preset.contrast ?? 0, preset.bump ?? 0, preset.roughVar ?? 0, preset.mask ? 0.9 : 0) },
+		lookMask: { value: new THREE.Color(preset.mask ?? "#000000") },
+	};
+	material.onBeforeCompile = (shader) => {
+		uniforms.lookMap.value ??= patternTexture(preset.pattern);
+		Object.assign(shader.uniforms, uniforms);
+		shader.vertexShader = patchVertex.reduce((source, patch) => patch(source), shader.vertexShader);
+		shader.fragmentShader = patchFragment.reduce((source, patch) => patch(source), shader.fragmentShader);
+	};
+	material.customProgramCacheKey = () => "cozyclay-look-1";
+}
+
+const studioMaps = new WeakMap();
+/** A neutral room to reflect, prefiltered once per renderer and kept. */
+function studioReflections(renderer) {
+	let map = studioMaps.get(renderer);
+	if (!map) {
+		const generator = new THREE.PMREMGenerator(renderer), room = new RoomEnvironment();
+		map = generator.fromScene(room, 0.04).texture;
+		room.dispose();
+		generator.dispose();
+		studioMaps.set(renderer, map);
+	}
+	return map;
+}
+
+/** Runs before each draw: the room while the scene has no environment, the
+ * scene's own (envMap null) once it has one. three swaps the program itself. */
+function reflectWhenBare(intensity) {
+	return function onBeforeRender(renderer, scene) {
+		const own = scene?.environment ? null : studioReflections(renderer);
+		if (this.envMap === own) return;
+		this.envMap = own;
+		this.envMapIntensity = intensity;
+	};
+}
+
+const WHITE = new THREE.Color("#ffffff");
+
+/**
+ * A material for `look` = { material, finish, color, size, side }: the preset
+ * name (unknown or absent is clay), the finish, the authored colour, the
+ * surface's extent in its mesh frame (metres; sizes the glass thickness and
+ * steers the grain) and an optional side. `extra` is set last (polygon offset).
+ */
+export function lookMaterial(look, extra = null) {
+	const name = Object.hasOwn(MATERIAL_LOOKS, look.material ?? "") ? look.material : "clay";
+	const preset = MATERIAL_LOOKS[name], size = look.size ?? [1, 1, 1];
+	const roughness = FINISH_ROUGHNESS[look.finish] ?? preset.roughness;
+	const color = new THREE.Color(lookTint(look.color, name));
+	const params = { color, roughness, metalness: preset.metalness ?? 0, ...(look.side === undefined ? {} : { side: look.side }), ...extra };
+	let material;
+	if (preset.physical) {
+		const physical = { ...preset.physical };
+		if (physical.transmission) physical.thickness = Math.min(0.5, Math.max(0.002, Math.min(...size) / 2));
+		if (physical.sheen) physical.sheenColor = color.clone().lerp(WHITE, 0.25);
+		if (physical.clearcoat && look.finish) Object.assign(physical, { clearcoat: look.finish === "matte" ? 0 : 1, clearcoatRoughness: roughness / 2 });
+		material = new THREE.MeshPhysicalMaterial({ ...params, ...physical });
+	} else material = new THREE.MeshStandardMaterial(params);
+	if (preset.pattern) addPattern(material, preset, size);
+	if (preset.env) material.onBeforeRender = reflectWhenBare(preset.env);
+	return material;
+}

package/src/material-presets.js

@@ -0,0 +1,78 @@
+/**
+ * Material presets: named surface looks for sculpt parts (`material`, `finish`)
+ * and plain primitives (`object.material`, `object.finish`). Pure data and the
+ * record rules, no three.js, so the recipe reader, the scene record and Node
+ * tests share one list; material-look.js turns an entry into a material.
+ *
+ * A record keeps only the names. `color` stays the base tint ("#c24a3b" with
+ * wood is red-painted wood), and a colour left at the blockout grey takes the
+ * preset's own (brick with no colour draws brick red). `finish` replaces the
+ * preset's roughness: chrome is metal + gloss, frosted glass is glass + matte.
+ * Clay with no finish is exactly the look every prop wore before presets.
+ *
+ * An entry (every field optional): roughness, metalness, color (its natural
+ * tint), physical (MeshPhysicalMaterial fields), env (reflection strength on
+ * a stage with no environment of its own), and a pattern with its tile in
+ * metres, the axis its grain runs along (up: the part's own y; long: its
+ * longest side; hang: its most upright side, skipping a slab's thickness),
+ * albedo contrast, bump depth in metres, roughness variation and a mask
+ * colour (brick mortar).
+ */
+
+import { GREY_BOX } from "./object-colors.js";
+
+export const MATERIAL_LOOKS = Object.freeze({
+	clay: { roughness: 0.82 },
+	wood: { roughness: 0.68, color: "#9a6b3f", pattern: "wood", tile: 0.5, grain: "long", contrast: 0.32, bump: 0.0015, roughVar: 0.1 },
+	straw: { roughness: 0.88, color: "#c8a85c", pattern: "straw", tile: 0.6, grain: "hang", contrast: 0.5, bump: 0.02, roughVar: 0.08 },
+	stone: { roughness: 0.9, color: "#8d8a83", pattern: "stone", tile: 1, contrast: 0.32, bump: 0.008, roughVar: 0.1 },
+	brick: { roughness: 0.88, color: "#a5503a", pattern: "brick", tile: 0.5, grain: "hang", contrast: 0.22, bump: 0.008, roughVar: 0.08, mask: "#b9b3a8" },
+	concrete: { roughness: 0.92, color: "#a7a49d", pattern: "concrete", tile: 1.2, contrast: 0.2, bump: 0.0015, roughVar: 0.08 },
+	metal: { roughness: 0.32, metalness: 1, color: "#c9ccd1", env: 1, pattern: "brushed", tile: 0.4, contrast: 0.06, bump: 0.0001, roughVar: 0.12 },
+	glass: { roughness: 0.04, color: "#f2f7f7", env: 1, physical: { transmission: 1, ior: 1.5 } },
+	ceramic: { roughness: 0.35, color: "#efece4", env: 0.45, physical: { clearcoat: 1, clearcoatRoughness: 0.06 } },
+	plastic: { roughness: 0.3, env: 0.35 },
+	rubber: { roughness: 0.92, color: "#2d2d2f", pattern: "stipple", tile: 0.15, contrast: 0.08, bump: 0.0003, roughVar: 0.06 },
+	fabric: { roughness: 0.95, pattern: "weave", tile: 0.12, contrast: 0.22, bump: 0.0008, roughVar: 0.05, physical: { sheen: 1, sheenRoughness: 0.6 } },
+	paper: { roughness: 0.88, color: "#ebe6da", pattern: "paper", tile: 0.25, contrast: 0.08, bump: 0.0002 },
+	foliage: { roughness: 0.62, color: "#4f7d34", pattern: "leaves", tile: 0.6, contrast: 0.45, bump: 0.015, roughVar: 0.15, physical: { sheen: 0.8, sheenRoughness: 0.45 } },
+});
+
+export const MATERIAL_PRESETS = Object.freeze(Object.keys(MATERIAL_LOOKS));
+/** What a finish sets the roughness to, whatever the preset's own. */
+export const FINISH_ROUGHNESS = Object.freeze({ matte: 0.85, satin: 0.45, gloss: 0.12 });
+export const MATERIAL_FINISHES = Object.freeze(Object.keys(FINISH_ROUGHNESS));
+
+/** The colour a surface draws in: the authored one, or the preset's own while
+ * the authored one is still the blockout grey. */
+export function lookTint(color, preset) {
+	const own = MATERIAL_LOOKS[preset]?.color;
+	return own && (!color || color.toLowerCase() === GREY_BOX) ? own : color ?? GREY_BOX;
+}
+
+/** The record renderers that draw a preset (props.jsx Primitive). */
+const LOOK_RENDERERS = new Set(["cube", "sphere", "capsule", "cylinder", "cone", "plane"]);
+const LOOK_KEYS = [["material", MATERIAL_PRESETS], ["finish", MATERIAL_FINISHES]];
+
+/** The patch keys object.update reads for the look, on the renderers that draw one. */
+export const objectMaterialKeys = (renderer) => (LOOK_RENDERERS.has(renderer) ? LOOK_KEYS.map(([key]) => key) : []);
+
+/** The material/finish a normalized record keeps: known names on a primitive,
+ * nothing otherwise, so records written before presets come back unchanged. */
+export function objectMaterialFields(record, renderer) {
+	if (!LOOK_RENDERERS.has(renderer)) return {};
+	return Object.fromEntries(LOOK_KEYS.filter(([key, names]) => names.includes(record?.[key])).map(([key]) => [key, record[key]]));
+}
+
+/** The material/finish part of an object.update patch: a known name sets it,
+ * null removes it (back to the preset default), anything else is ignored. */
+export function objectMaterialPatch(object, patch) {
+	if (!LOOK_RENDERERS.has(object?.renderer)) return {};
+	const update = {};
+	for (const [key, names] of LOOK_KEYS) {
+		const value = patch?.[key];
+		if (value === undefined || (value !== null && !names.includes(value))) continue;
+		if ((value ?? undefined) !== object[key]) update[key] = value;
+	}
+	return update;
+}

package/src/material-textures.js

@@ -0,0 +1,157 @@
+/**
+ * Procedural surface detail for the material presets: one small seamless tile
+ * per pattern, from integer hashes, so every machine draws the same pixels.
+ * Pure arithmetic, no three.js and no DOM; material-look.js wraps the bytes in
+ * a DataTexture the first time a preset is drawn, and never in Node.
+ *
+ * Channels, each 0..255: R albedo detail (128 is the authored colour), G
+ * height (0..255 spans the preset's bump depth), B roughness offset (128 is
+ * none), A where a second colour shows (brick mortar). Each pattern is drawn
+ * in tile coordinates u (across) and v (along the grain, or up), both 0..1;
+ * R and B are re-centred on their mean afterwards, so a preset never shifts
+ * the colour the author picked.
+ */
+
+export const PATTERN_SIZE = 256;
+
+function hash(x, y, seed) {
+	let h = Math.imul(x, 0x27d4eb2d) ^ Math.imul(y, 0x165667b1) ^ Math.imul(seed, 0x9e3779b1);
+	h = Math.imul(h ^ (h >>> 15), 0x85ebca6b);
+	h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
+	return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+const wrap = (i, n) => ((i % n) + n) % n;
+const smooth = (t) => t * t * (3 - 2 * t);
+const step = (a, b, x) => smooth(Math.min(1, Math.max(0, (x - a) / (b - a))));
+
+/** Value noise on a px by py lattice over the tile, seamless at its edges. */
+function noise(u, v, px, py, seed) {
+	const x = u * px, y = v * py, ix = Math.floor(x), iy = Math.floor(y);
+	const fx = smooth(x - ix), fy = smooth(y - iy);
+	const x0 = wrap(ix, px), x1 = wrap(ix + 1, px), y0 = wrap(iy, py), y1 = wrap(iy + 1, py);
+	const a = hash(x0, y0, seed), b = hash(x1, y0, seed), c = hash(x0, y1, seed), d = hash(x1, y1, seed);
+	return a + (b - a) * fx + (c - a) * fy + (a - b - c + d) * fx * fy;
+}
+
+function fbm(u, v, px, py, octaves, seed) {
+	let sum = 0, amp = 0.5, total = 0;
+	for (let o = 0; o < octaves; o += 1) {
+		sum += amp * noise(u, v, px << o, py << o, seed + o);
+		total += amp;
+		amp /= 2;
+	}
+	return sum / total;
+}
+
+/** Worley cells on an n by n jittered grid, seamless: the nearest and second
+ * nearest feature distances (tile units) and the nearest cell's hash. */
+function cells(u, v, n, seed) {
+	const x = u * n, y = v * n, ix = Math.floor(x), iy = Math.floor(y);
+	let f1 = 9, f2 = 9, id = 0;
+	for (let dy = -1; dy <= 1; dy += 1) {
+		for (let dx = -1; dx <= 1; dx += 1) {
+			const cx = ix + dx, cy = iy + dy, wx = wrap(cx, n), wy = wrap(cy, n);
+			const d = Math.hypot(cx + hash(wx, wy, seed) - x, cy + hash(wx, wy, seed + 1) - y) / n;
+			if (d < f1) {
+				f2 = f1;
+				f1 = d;
+				id = hash(wx, wy, seed + 2);
+			} else if (d < f2) f2 = d;
+		}
+	}
+	return { f1, f2, id };
+}
+
+/** Each pattern: (u, v) to [albedo, height, roughness, mask]. */
+const PATTERNS = {
+	// Ten rings across the tile, wandering along it, over fine fibres.
+	wood(u, v) {
+		const late = (0.5 + 0.5 * Math.sin(2 * Math.PI * (u * 10 + fbm(u, v, 2, 1, 3, 11) * 2.2))) ** 6;
+		const fibre = noise(u, v, 128, 4, 12), fleck = fbm(u, v, 16, 2, 2, 13);
+		return [0.5 - 0.45 * late + 0.25 * fibre + 0.2 * fleck, 0.6 * fibre - 0.5 * late, 0.5 + 0.4 * late - 0.2 * fibre, 0];
+	},
+	// Four overlapping courses of strands; each course is thickest at its ragged
+	// lower edge and shaded just under the edge of the course above.
+	straw(u, v) {
+		const strand = 0.6 * noise(u, v, 192, 3, 21) + 0.4 * noise(u, v, 96, 2, 22);
+		const course = v * 4 + 0.12 * noise(u, v, 48, 1, 23), cv = course - Math.floor(course);
+		const shade = step(0.55, 1, cv);
+		return [0.5 * strand - 0.45 * shade + 0.1 * fbm(u, v, 6, 2, 2, 24), 0.7 * (1 - cv) + 0.3 * strand, 0.5 + 0.2 * shade, 0];
+	},
+	// Weathered fieldstone: lumpy noise, stones of their own tone, dark joints.
+	stone(u, v) {
+		const lump = fbm(u, v, 4, 4, 5, 31), cell = cells(u, v, 5, 32), grain = noise(u, v, 128, 128, 33);
+		const edge = cell.f2 - cell.f1, crack = 1 - step(0, 0.012, edge);
+		return [0.35 * lump + 0.25 * cell.id + 0.12 * grain - 0.35 * crack, 0.5 * lump + 0.35 * step(0, 0.08, edge) + 0.1 * grain, 0.25 * lump + 0.15 * crack, 0];
+	},
+	// Running bond: six 83 mm courses of two 250 mm bricks on the 0.5 m tile,
+	// 10 mm recessed mortar joints (the mask), each brick its own tone.
+	brick(u, v) {
+		const row = Math.floor(v * 6), cv = v * 6 - row;
+		const across = u * 2 + (row % 2 ? 0.5 : 0), col = Math.floor(across), cu = across - col;
+		const gap = Math.min(Math.min(cu, 1 - cu) / 2, Math.min(cv, 1 - cv) / 6), joint = 0.01;
+		const grit = noise(u, v, 96, 96, 42), mortar = 1 - step(joint * 0.6, joint, gap);
+		return [0.35 * hash(wrap(col, 2), row, 41) + 0.15 * grit + 0.15 * fbm(u, v, 8, 8, 3, 43), 0.85 * step(joint * 0.6, joint * 2.2, gap) + 0.15 * grit, 0.1 * grit + 0.15 * mortar, mortar];
+	},
+	// Cast concrete: soft mottling, fine grit, scattered air pits.
+	concrete(u, v) {
+		const mottle = fbm(u, v, 3, 3, 5, 51), grit = noise(u, v, 160, 160, 52), pit = step(0.86, 0.95, noise(u, v, 48, 48, 53));
+		return [0.3 * mottle + 0.1 * grit - 0.25 * pit, 0.4 * mottle + 0.25 * grit - 0.6 * pit, 0.2 * mottle, 0];
+	},
+	// Brushed metal: fine lines across the tile and faint smudges in the sheen.
+	brushed(u, v) {
+		const brush = 0.6 * noise(u, v, 3, 220, 61) + 0.4 * noise(u, v, 2, 110, 62), smudge = fbm(u, v, 3, 3, 4, 63);
+		return [0.15 * brush + 0.1 * smudge, brush, 0.35 * brush + 0.4 * smudge, 0];
+	},
+	stipple(u, v) {
+		const fine = noise(u, v, 128, 128, 71), wear = fbm(u, v, 6, 6, 3, 72);
+		return [0.2 * wear + 0.1 * fine, fine, 0.3 * wear, 0];
+	},
+	// Plain weave: 32 threads each way, over and under, each thread its own tone.
+	weave(u, v) {
+		const x = u * 32, y = v * 32, i = Math.floor(x), j = Math.floor(y);
+		const across = Math.sin(Math.PI * (x - i)), along = Math.sin(Math.PI * (y - j)), warp = (i + j) % 2 === 0;
+		const height = warp ? across * (0.75 + 0.25 * along) : along * (0.75 + 0.25 * across);
+		return [0.3 * height + 0.2 * (warp ? hash(i, 0, 81) : hash(0, j, 82)) + 0.1 * noise(u, v, 256, 256, 83), height, -0.2 * height, 0];
+	},
+	paper(u, v) {
+		const pulp = fbm(u, v, 8, 8, 4, 91), fibre = noise(u, v, 64, 8, 92) * noise(u, v, 8, 64, 93);
+		return [0.12 * pulp + 0.1 * fibre, pulp + 0.5 * fibre, 0.1 * pulp, 0];
+	},
+	// Two layers of leaf cells; the leaf nearer its own centre lies on top, and
+	// where neither covers the surface a dark gap shows through.
+	leaves(u, v) {
+		const big = cells(u, v, 6, 101), small = cells(u, v, 9, 104);
+		const domeBig = Math.max(0, 1 - big.f1 * 6 * 1.6), domeSmall = 0.9 * Math.max(0, 1 - small.f1 * 9 * 1.6);
+		const top = domeBig >= domeSmall ? big : small, dome = Math.max(domeBig, domeSmall), gap = 1 - step(0, 0.15, dome);
+		return [0.45 * top.id + 0.2 * dome - 0.5 * gap + 0.05 * noise(u, v, 64, 64, 107), dome, 0.3 * top.id + 0.3 * gap, 0];
+	},
+};
+
+export const PATTERN_NAMES = Object.freeze(Object.keys(PATTERNS));
+
+/** The RGBA bytes of one pattern's tile, PATTERN_SIZE square, row 0 at v = 0. */
+export function patternPixels(name) {
+	const draw = PATTERNS[name];
+	if (!draw) throw new Error(`unknown material pattern "${name}"`);
+	const count = PATTERN_SIZE * PATTERN_SIZE, raw = new Float32Array(count * 4);
+	for (let y = 0; y < PATTERN_SIZE; y += 1) {
+		for (let x = 0; x < PATTERN_SIZE; x += 1) raw.set(draw((x + 0.5) / PATTERN_SIZE, (y + 0.5) / PATTERN_SIZE), (y * PATTERN_SIZE + x) * 4);
+	}
+	let albedo = 0, rough = 0, low = Infinity, high = -Infinity;
+	for (let i = 0; i < count; i += 1) {
+		albedo += raw[i * 4] / count;
+		rough += raw[i * 4 + 2] / count;
+		low = Math.min(low, raw[i * 4 + 1]);
+		high = Math.max(high, raw[i * 4 + 1]);
+	}
+	const span = high - low || 1, byte = (value) => Math.round(255 * Math.min(1, Math.max(0, value)));
+	const out = new Uint8Array(count * 4);
+	for (let i = 0; i < count; i += 1) {
+		out[i * 4] = byte(raw[i * 4] - albedo + 0.5);
+		out[i * 4 + 1] = byte((raw[i * 4 + 1] - low) / span);
+		out[i * 4 + 2] = byte(raw[i * 4 + 2] - rough + 0.5);
+		out[i * 4 + 3] = byte(raw[i * 4 + 3]);
+	}
+	return out;
+}

package/src/motion3/compile-job.js

@@ -3,11 +3,13 @@
 // name, the motion scene (scene.js motionScene of the editor's objects: oriented boxes; shapes.js reads a sphere or a cylinder round from them), the spec as sent, and
 // what to do with it (probes, checks, lenient, repair, bake). The answer is plain data and typed arrays
 // only (the compiler's out holds closures), so it crosses a worker boundary: QA, observations, the stored
-// spec, and the baked take when asked.
+// spec, and the baked take when asked. The hint patches QA offers are compiled first (hint-check.js).
 // A refusal is an Error with a code (INVALID_ARGUMENT, MOTION_SPEC_INVALID turned into it), which the
 // client turns back into the Studio's protocol error.
 import { compileSpec, liftRequest } from "./pipeline.js";
+import { prepareSpec } from "./correct.js";
 import { repairSpec } from "./repair.js";
+import { checkHints } from "./hint-check.js";
 import { bakeTake } from "./take.js";
 import { skeletonFor } from "./rigs/index.js";
 import { keptPeople } from "./people.js";
@@ -49,7 +51,17 @@ export function runCompileJob({ model, scene, spec: asked, probes: sentProbes, c
 		const r = asArgument(() => compileSpec(sent, { sk, scene }, { ...opts, probes }));
 		return { ...r, stored: r.spec === sent ? spec : r.spec };
 	};
-	const t0 = performance.now(), fixed = repair ? repairSpec(asked, repair, once) : { spec: asked, result: once(asked) };
+	// repair patches address the stored spec, so a repair starts from it corrected (correct.js), and says what was
+	const corrected = [], start = repair && !lenient ? prepareSpec(asked, { sk, scene }, corrected) : asked;
+	// every compile's QA by its spec, so a hint patch repair already tried is not compiled again (hint-check.js)
+	const seen = new Map(), measured = s => { const r = once(s); seen.set(JSON.stringify(s), r.qa); return r; };
+	const t0 = performance.now(), fixed = repair ? repairSpec(start, repair, measured) : { spec: asked, result: measured(asked) };
+	// a hint's patch is offered only when its compile helped (hint-check.js), and only by a compile that repairs: repair has
+	// compiled most of the patches already (seen), where a plain compile paid two more compiles for them (bench replay: first
+	// compile 1.6 -> 5.2 s median) and the agent applied an offered patch as sent once in the 60 bench runs (374 direct
+	// compiles, 319 with repair; a plain compile is mostly a variant in a sweep); a plain compile keeps the hint's words only
+	if (repair) checkHints(fixed.spec, fixed.result.qa, s => seen.get(JSON.stringify(s)) ?? measured(s).qa);
+	else for (const g of fixed.result.qa?.groups ?? []) delete g.patch;
 	// ms.repair: the whole repair's wall time, so a sweep that repairs every variant shows what it costs
 	const r = fixed.result, label = fixed.spec?.label ?? null, ms = fixed.repair ? { ...r.ms, repair: Math.round(performance.now() - t0) } : r.ms;
 	const take = bake ? bakeTake(sk, r.out, { position: bake.position, yaw: bake.yaw }, { spec: r.stored, prompt: ("prompt" in bake ? bake.prompt : label) ?? "" }) : undefined;
@@ -57,7 +69,7 @@ export function runCompileJob({ model, scene, spec: asked, probes: sentProbes, c
 	const people = take && keptPeople(scene, [r.expanded, r.stored]);
 	if (people) take.people = people;
 	return { stored: r.stored, qa: r.qa, observations: r.observations, used: r.used, fixed: r.fixed, search: r.search, timeline: r.timeline,
-		...(r.probes ? { probes: r.probes } : {}), ...(r.notes ? { notes: r.notes } : {}), ms, frameCount: r.out.frameCount, label,
+		...(r.probes ? { probes: r.probes } : {}), ...(r.notes || corrected.length ? { notes: [...corrected, ...(r.notes ?? [])] } : {}), ms, frameCount: r.out.frameCount, label,
 		...(fixed.repair ? { repair: fixed.repair } : {}), ...(take ? { take } : {}) };
 }
 

package/src/motion3/compiler/channels.js

@@ -12,7 +12,11 @@
 // flow is gone by the time the arm is a quarter of the way onto it: an arm's swing and bend by its
 // own armw, the spine (which carries the shoulders) and the head (the hands work near it) by the
 // larger of the two; a reach or a held prop lands as keyed. A hold (two equal keys in a row) stays
-// exactly flat either way.
+// exactly flat either way. Overlap (overlap.js) breaks each change along the chains on top of that: the
+// lower spine, the chest (chest_*: the top spine bone's share, baked beside spine_*), the head, the upper
+// arm, the forearm and the wrist each take a later delay, one side of the body trails the other, and the
+// arm's swing and bend overshoot and settle where they stop.
+import { overlapDelay, sideTrail, settleBump, ikGap, contactGap, OVERLAP_SLOPE } from "./overlap.js";
 
 function pchipSlopes(x, y) {
 	const n = y.length, m = new Array(n).fill(0);
@@ -37,18 +41,24 @@ function pchipEval(x, y, m, q) {
 	return (2 * t3 - 3 * t2 + 1) * y[i] + (t3 - 2 * t2 + t) * h * m[i] + (-2 * t3 + 3 * t2) * y[i + 1] + (t3 - t2) * h * m[i + 1];
 }
 
-const FLOW_SMOOTH = /^(spine|head)_(yaw|pitch|roll)$|^(aswing|abend)_[lr]$/;
+const FLOW_SMOOTH = /^(spine|chest|head)_(yaw|pitch|roll)$|^(aswing|abend)_[lr]$/;
 const FLOW_LAG = { spine: 0, head: 2, arms: 3 };
+const ARM = /^(hand|armw|elbow|aswing|abend|wflex|wtwist)_[lr]$/; // one side's arm: trails as one (overlap.js sideTrail)
 const OVER_FRAC = 0.15, OVER_MAX = 6; // a smooth segment's overshoot: at most this share of its change, and degrees
-const ikSides = ch => (/^(spine|head)_/.test(ch) ? ["l", "r"] : /^(aswing|abend)_([lr])$/.test(ch) ? [ch.slice(-1)] : []);
-const lagFamily = ch => (/^spine_/.test(ch) ? "spine" : /^head_/.test(ch) ? "head" : /^(aswing|abend)_[lr]$/.test(ch) ? "arms" : null);
+const ikSides = ch => (/^(spine|chest|head)_/.test(ch) ? ["l", "r"] : /^(aswing|abend|wflex|wtwist)_([lr])$/.test(ch) ? [ch.slice(-1)] : []);
+const lagFamily = ch => (/^(spine|chest)_/.test(ch) ? "spine" : /^head_/.test(ch) ? "head" : /^(aswing|abend)_[lr]$/.test(ch) ? "arms" : null);
 
-/** spec.flow -> { smooth, lag: { spine, head, arms } }: undefined is the default, false turns both off. */
-export function flowOptions(flow) {
-	if (flow === false) return { smooth: false, lag: { spine: 0, head: 0, arms: 0 } };
+/**
+ * spec.flow -> { smooth, lag: { spine, head, arms }, overlap, seed, hands }: undefined is the default, false turns all off.
+ * overlap: true (1) | false (0) | a scale of its delays and settle (overlap.js); seed (the spec's label) picks which side trails;
+ * hands: the frames each hand works on something (overlap.js handBusy), where a free IK hand's trail stops.
+ */
+export function flowOptions(flow, seed = "", hands = { l: [], r: [] }) {
+	if (flow === false) return { smooth: false, lag: { spine: 0, head: 0, arms: 0 }, overlap: 0, seed, hands };
 	const f = flow ?? {}, lag = f.lag === false ? 0 : f.lag;
 	const each = typeof lag === "number" ? { spine: lag, head: lag, arms: lag } : { ...FLOW_LAG, ...(lag ?? {}) };
-	return { smooth: f.smooth !== false, lag: each };
+	const overlap = f.overlap === false ? 0 : typeof f.overlap === "number" ? f.overlap : 1;
+	return { smooth: f.smooth !== false, lag: each, overlap, seed, hands };
 }
 
 /** Catmull-Rom slopes, flat at a hold and at the ends, each segment's overshoot bounded. */
@@ -78,11 +88,47 @@ export function bakeChannels(keys, frameCount, flow = flowOptions()) {
 	for (const key of [...keys].sort((a, b) => a.f - b.f)) {
 		for (const [ch, value] of Object.entries(key.set ?? {})) {
 			if (!byChannel.has(ch)) byChannel.set(ch, []);
-			byChannel.get(ch).push({ f: key.f, value, step: key.step?.includes(ch) });
+			byChannel.get(ch).push({ f: key.f, value, step: key.step?.includes(ch), src: key.src });
 		}
 	}
+	// the top spine bone's share breaks after the two below it (pose.js), so it is baked as its own channel
+	const overlap = flow.overlap ?? 0, entries = [...byChannel];
+	if (overlap > 0) for (const [ch, list] of byChannel) if (/^spine_/.test(ch)) entries.push([ch.replace("spine", "chest"), list]);
+	// an arm's IK weights first: a link's own delay runs out before an arm goes onto its IK and comes back after it
+	// leaves (overlap.js), so the fade below never snaps a delayed move onto its keyed frames. Before them where each
+	// hand touches: its anchor and fit weights (never delayed) and its carries and hand goals (flow.hands); a side's
+	// trail stops short of those
+	const pre = new Map(), near = new Map(), touch = {}, trails = {};
+	if (overlap > 0) {
+		for (const [ch, list] of entries) if (/^w_.+_[lr]$/.test(ch)) pre.set(ch, bakeOne(ch, list));
+		for (const k of ["l", "r"]) touch[k] = contactGap(flow.hands?.[k] ?? [], [...pre].filter(([ch]) => ch.endsWith(`_${k}`)).map(([, b]) => b.frames), frameCount);
+		// the whole arm of a side trails as one (overlap.js sideTrail), its FK swing with its IK weight, so a blend between
+		// them never sets a late weight over an on-time swing
+		for (const k of ["l", "r"]) trails[k] = sideTrail([...byChannel].filter(([ch]) => ARM.test(ch) && ch.endsWith(`_${k}`)).map(([ch, list]) => Object.assign([...list], { weight: /^armw_/.test(ch) })), k, overlap, flow.seed ?? "", touch[k]);
+		for (const [ch, list] of entries) if (/^armw_[lr]$/.test(ch)) pre.set(ch, bakeOne(ch, list));
+	}
+	const gapOf = ch => {
+		const sides = ikSides(ch).filter(k => pre.has(`armw_${k}`)), key = sides.join("");
+		if (!sides.length) return null;
+		if (!near.has(key)) near.set(key, ikGap(sides.map(k => pre.get(`armw_${k}`).frames), frameCount));
+		return near.get(key);
+	};
 	const out = {}, plain = {};
-	for (const [ch, list] of byChannel) {
+	for (const [ch, list] of entries) {
+		const baked = pre.get(ch) ?? bakeOne(ch, list, gapOf(ch));
+		out[ch] = baked.frames;
+		if (baked.plain) plain[ch] = baked.plain;
+	}
+	// flow fades out as the arm goes onto its IK (the spine with either arm)
+	for (const [ch, keyed] of Object.entries(plain)) {
+		const ws = ikSides(ch).map(k => out[`armw_${k}`]).filter(Boolean);
+		if (!ws.length) continue;
+		out[ch] = out[ch].map((v, f) => { const w = Math.min(1, 4 * Math.max(0, ...ws.map(a => a[f]))); return v + (keyed[f] - v) * w * (2 - w); });
+	}
+	return out;
+
+	/** One channel's frames (and, for a flowing body channel, its keyed frames: plain); gap: frames to the nearest IK frame. */
+	function bakeOne(ch, list, gap = null) {
 		// later keys at the same frame win
 		const pts = [...new Map(list.map(k => [k.f, k])).values()];
 		const shape = shapeOf(pts[0].value);
@@ -91,15 +137,24 @@ export function bakeChannels(keys, frameCount, flow = flowOptions()) {
 			: shape === "vec" ? Array.from({ length: comps }, (_, i) => pts.map(p => p.value[i]))
 				: [...new Set(pts.flatMap(p => Object.keys(p.value)))].map(name => ({ name, y: pts.map(p => p.value[name] ?? 0) }));
 		const x = pts.map(p => p.f), smooth = flow.smooth && FLOW_SMOOTH.test(ch), lag = flow.lag[lagFamily(ch)] ?? 0;
-		// the trail eases out over the last 2 * lag frames, so the take ends on the last value
-		const at = f => (lag > 0 ? f - lag * Math.min(1, (frameCount - 1 - f) / (2 * lag)) : f);
+		const delay = shape === "num" ? overlapDelay(ch, pts, overlap, flow.seed ?? "", gap) : null;
+		const trail = ARM.test(ch) ? trails[ch.slice(-1)] : null, most = lag + (delay?.max ?? 0);
+		const delayAt = f => (delay ? Math.min(delay.at(f), gap ? OVERLAP_SLOPE * gap[Math.round(f)] : Infinity) : 0);
+		const end = (f, d) => Math.min(1, (frameCount - 1 - f) / (2 * d));
+		// the trail eases out over the last 2 * (its most) frames, so the take ends on the last value (the side's trail over
+		// its own: a short ease there would quicken the arm's last move); the side's trail rides the keyed curve too (plain),
+		// which an arm on its IK goes back to
+		const keyedAt = f => (trail ? f - trail.at(f) * end(f, trail.max) : f);
+		const at = f => keyedAt(f) - (most > 0 ? (lag + delayAt(f)) * end(f, most) : 0);
+		// a settle near an arm's IK would be cut by the fade below: none within its span and a few frames
+		const clear = (a, b) => { if (!gap) return true; for (let f = Math.max(0, Math.floor(a)); f <= Math.min(frameCount - 1, Math.ceil(b + most)); f++) if (gap[f] < 2) return false; return true; };
 		const evalSeries = (y, flowing = true) => {
-			const m = smooth && flowing ? smoothSlopes(x, y) : pchipSlopes(x, y);
+			const m = smooth && flowing ? smoothSlopes(x, y) : pchipSlopes(x, y), bump = flowing && shape === "num" ? settleBump(ch, pts, y, overlap, frameCount - 1, clear) : null;
 			return q => {
-				const f = flowing ? at(q) : q;
+				const f = flowing ? at(q) : keyedAt(q);
 				// a step key holds the previous value right up to its frame
 				for (let i = 1; i < pts.length; i++) if (pts[i].step && f >= x[i - 1] && f < x[i]) return y[i - 1];
-				return pchipEval(x, y, m, f);
+				return pchipEval(x, y, m, f) + (bump ? bump(f) : 0);
 			};
 		};
 		const frames = new Array(frameCount);
@@ -109,16 +164,11 @@ export function bakeChannels(keys, frameCount, flow = flowOptions()) {
 			const es = series.map(({ name, y }) => [name, evalSeries(y)]);
 			for (let f = 0; f < frameCount; f++) frames[f] = Object.fromEntries(es.map(([n, e]) => [n, e(f)]));
 		}
-		out[ch] = frames;
-		if (shape === "num" && (smooth || lag > 0) && ikSides(ch).length) { const e = evalSeries(series[0], false); plain[ch] = Array.from({ length: frameCount }, (_, f) => e(f)); }
-	}
-	// flow fades out as the arm goes onto its IK (the spine with either arm)
-	for (const [ch, keyed] of Object.entries(plain)) {
-		const ws = ikSides(ch).map(k => out[`armw_${k}`]).filter(Boolean);
-		if (!ws.length) continue;
-		out[ch] = out[ch].map((v, f) => { const w = Math.min(1, 4 * Math.max(0, ...ws.map(a => a[f]))); return v + (keyed[f] - v) * w * (2 - w); });
+		if (!(shape === "num" && (smooth || most > 0) && ikSides(ch).length)) return { frames };
+		// an arm's own channels keep the side's trail on its IK too (plain), only the links' own delays and settle fade
+		const e = evalSeries(series[0], false);
+		return { frames, plain: Array.from({ length: frameCount }, (_, f) => e(f)) };
 	}
-	return out;
 }
 
 /** Frame f's channel dict. */

package/src/motion3/compiler/compile.js

@@ -26,6 +26,7 @@ import { pose, SIDES } from "./pose.js";
 import { graspAnchor } from "./socket-grip.js";
 import { gripHand } from "./grip.js";
 import { bakeChannels, channelsAt, flowOptions } from "./channels.js";
+import { handBusy } from "./overlap.js";
 import { idleLayer, withIdle, busyHands } from "./idle.js";
 import { resolveAnchor, measureProps, armReach } from "./anchors.js";
 import { expandGenerators } from "./walk.js";
@@ -208,7 +209,7 @@ export function compileMotion(spec, { sk, scene }, opts = {}) {
 	const engine = {
 		rebake(keys) {
 			out.keys = keys;
-			out.baked = bakeChannels(keys, frameCount, flowOptions(spec.flow));
+			out.baked = bakeChannels(keys, frameCount, flowOptions(spec.flow, spec.label ?? "", handBusy(spec)));
 			ctx.socketTurns = new Map();
 			ctx.graspPlans = new Map();
 			steadyHead(out.baked, keys, frameCount);

package/src/motion3/compiler/idle.js

@@ -109,5 +109,7 @@ export function withIdle(c, layer, f) {
 	if (!d) return c;
 	const out = { ...c };
 	for (const [ch, v] of Object.entries(d)) out[ch] = Array.isArray(v) ? (Array.isArray(c[ch]) ? c[ch].map((x, i) => x + v[i]) : c[ch]) : (Number(c[ch]) || 0) + v;
+	// the top spine bone's own share (chest_*, channels.js overlap) breathes and sways with the rest of the spine
+	for (const ch of ["chest_pitch", "chest_roll"]) if (c[ch] !== undefined && d[ch.replace("chest", "spine")] !== undefined) out[ch] = c[ch] + d[ch.replace("chest", "spine")];
 	return out;
 }