cozyclay 3.1.0 → 3.1.1

package/dist/cozyclay-package.json

@@ -1 +1 @@
-{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"3.1.0\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"a82f58c8669edb7800fcdb79939b1cfc242616a17675fdf278927d7f4f5d016e\"}","signature":"EmIwI46B/uZyNSY0QYgaR43ElVC4MFt2ROKPMaDioTSwJytnF2kwqj3qWkaJIPvqeVR4sN5qglBO6Ya+mOprCQ=="}
+{"payload":"{\"distribution\":\"npm\",\"package\":\"cozyclay\",\"version\":\"3.1.1\",\"repository\":\"NomaDamas/CozyClay\",\"content_sha256\":\"65554e5162b89f817b066016390471333bfcabcee80e0ae0ee46939bdc759599\"}","signature":"M4R6haq7YzLWxDPcdy5h4zI/w7nVEBubTszIj4UzgWEKB4XZgZYtrjsQJmjt2rF3IooyCKnvMlzNiYB/arAGDg=="}

package/dist/workflow/index.html

@@ -8,13 +8,13 @@
     <meta name="theme-color" content="#101116" />
     <meta name="description" content="CozyClay visual workflow builder" />
     <title>CozyClay Workflow</title>
-    <script type="module" crossorigin src="/assets/workflow-B8Dhzexj.js"></script>
+    <script type="module" crossorigin src="/assets/workflow-zQM-EKW1.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-hePW80VL.js">
     <link rel="modulepreload" crossorigin href="/assets/modulepreload-polyfill-P2Xu9kJm.js">
-    <link rel="modulepreload" crossorigin href="/assets/task-board-BKaM7d-9.js">
+    <link rel="modulepreload" crossorigin href="/assets/task-board-ErQvfoaz.js">
     <link rel="modulepreload" crossorigin href="/assets/fflate.module-KbGj5-H6.js">
-    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-CQzEdsqu.js">
-    <link rel="stylesheet" crossorigin href="/assets/scene-asset-sync-COGOlF5T.css">
+    <link rel="modulepreload" crossorigin href="/assets/scene-asset-sync-Cgdtr1Yw.js">
+    <link rel="stylesheet" crossorigin href="/assets/scene-asset-sync-CBx7XRti.css">
     <link rel="stylesheet" crossorigin href="/assets/workflow-DRdwoDBT.css">
   </head>
   <body>

package/mcp/tool-handlers.mjs

@@ -1155,10 +1155,10 @@ export const createToolHandlers = ({ projectRootPromise } = {}) => {
 				title: "Sculpt a clay prop from a recipe of soft parts",
 				description:
 					"Unlike place_object, import_mesh and compare_sculpt, sculpt_object builds or changes a clay prop from a recipe of parts you write, typically after reading a reference image. It needs no file and no catalogue entry. " +
-					"recipe = { version: 1, parts: [{ id, shape, size: [x, y, z], position?, rotation?, color?, parent?, mirror?, roundness?, taper?, border? }] }. " +
+					"recipe = { version: 1, parts: [{ id, shape, size: [x, y, z], position?, rotation?, color?, parent?, mirror?, ...shape fields, material?, finish?, detail?, gradient?, op? }] }. " +
 					"Units are metres and degrees. The floor is y = 0, front is +z, and the subject's own left is +x. size is the full extent; position is the part's centre, in its parent part's frame when parent is set. " +
 					"shape: blob (soft superellipsoid: roundness 0 is an ellipsoid, 1 is a rounded box; taper narrows the top when positive and the bottom when negative), box (roundness bevels the edges), " +
-					"cylinder (taper 1 is a cone), torus (size [outer, outer, tube]), frame (a rectangular ring in x/y with a border width, for glasses rims, windows and picture frames). " +
+					"cylinder (taper 1 is a cone), torus (size [outer, outer, tube]), frame (a rectangular ring in x/y with a border width, for glasses rims, windows and picture frames), " + "lathe { profile: [[r 0..1 of half-width, y 0..1 of height], ...] bottom to top, smooth? } for turned objects (pot, vase, bottle, bowl, lampshade, mushroom), " + "tube { path: [[x, y, z] each -0.5..0.5 of size], thickness (m, diameter), taper?, closed? } for ropes, vines, cables, handles, branches and bike frames, " + "extrude { outline: [[x, y] -0.5..0.5 of size], holes?, roundness? } for flat cut shapes pushed through size z (sign, leaf, gable, gear, star), " + "loft { sections: [{ y 0..1, points: [[x, z]...] } or { y, w, d, x?, z?, roundness? }] bottom to top (first y 0, last y 1), smooth? } for cross-sections that change (hull, car body, shoe, loaf; lay it down with rotation [-90,0,0]), " + "convex { points: [[x, y, z]...] or seed + facetCount?, facets? } for rocks, boulders, gems and crystals, " + "scatter { item: blade|tuft|flower|leaf|pebble|twig, count <= 4000, spread: ground|shell, seed? } for thousands of small items as ONE part (grass, flower beds, gravel; shell covers a crown or bush it is parented to; 12000 items per recipe). " + "Any part also takes material clay|wood|straw|stone|brick|concrete|metal|glass|ceramic|plastic|rubber|fabric|paper|foliage (real texture and shine; color tints it; never fake glass with opacity or thatch with stripes) and finish matte|satin|gloss; detail { amount 0..1, scale?, seed? } for a lumpy surface (clouds, bushes, rocks, hay, bread), gradient { color, axis? y|x|z, from?, to? } to blend into a second colour (sky-lit clouds, fruit, sunset walls), " + "and op: subtract|intersect, which makes the part an undrawn cutter of its parent (windows, doors, arches; hollow a lathe with a smaller lathe of the same profile; cut deeper than the wall; mirror cuts both sides). " +
 					"mirror: true adds a copy reflected across x = 0 of the parent frame, with its children; author the subject's left (+x) side once. color is #rrggbb. At most 48 parts after mirrors. " +
 					"To fix a sculpt, pass its id with edits instead of a whole recipe: [{ set: partId, ...fields }, { add: part }, { remove: partId }] (parent: null and mirror: false clear; remove takes the part's children). " +
 					"capture: true also returns the editor's frame (connected editor only), so one call is one round. " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cozyclay",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Open source previs software in the browser: block a scene, pose characters, author camera moves and cuts, then take the same shots to an AI video model.",
   "scripts": {
     "dev": "node tools/dev-full.mjs --host 127.0.0.1 --port 5180",
@@ -82,6 +82,8 @@
     "react-icons": "^5.7.0",
     "reactflow": "^11.11.4",
     "three": "^0.185.1",
+    "three-bvh-csg": "^0.0.18",
+    "three-mesh-bvh": "^0.9.16",
     "vite": "^8.2.0"
   },
   "bin": {

package/src/App.jsx

@@ -137,7 +137,7 @@ import {
 	pathMetrics,
 	strokeToPathPoints,
 } from "./object-path.js";
-import { carriedPointAt, sceneObjectsAt } from "./object-travel.js"; import { objectTracksOf } from "./motion3/object-tracks.js"; import { ViewGhosts } from "./view-ghosts.jsx"; import { DraftGhost } from "./draft-ghost.jsx";
+import { carriedPointAt, sceneObjectsAt } from "./object-travel.js"; import { objectTracksOf } from "./motion3/object-tracks.js"; import { ViewGhosts } from "./view-ghosts.jsx"; import { DraftGhost } from "./draft-ghost.jsx"; import { SculptSketch } from "./sculpt-sketch.jsx";
 import { routeOwnerFor } from "./route-owner.js";
 import {
 	analyticsActive,
@@ -4791,7 +4791,7 @@ export default function App() {
 									/>
 								</ObjectCarrier>
 							))}
-							<ViewGhosts rig={rigs[activeChar.id]} take={motion} frame={tlFrame} objects={sceneObjects} propTake={{ frameCount: tlFrameCount, fps: tlFps, objectTracks }} /><DraftGhost rigs={rigs} objects={sceneObjects} />
+							<ViewGhosts rig={rigs[activeChar.id]} take={motion} frame={tlFrame} objects={sceneObjects} propTake={{ frameCount: tlFrameCount, fps: tlFps, objectTracks }} /><DraftGhost rigs={rigs} objects={sceneObjects} /><SculptSketch objects={sceneObjects} />
 
 							{/* Selection marker: XYZ tripod + ring on the picked cast
 							    member; the X/Z arrows drag it across the deck. */}

package/src/commands/elements.js

@@ -111,9 +111,10 @@ export function elementPatchArgs(kind, args) {
   });
   return collection ? ops.length === 1 ? ops[0] : { ops } : ops.reduce((patch, op) => mergeElementSet(patch, op.set), {});
 }
-// Unasked, an optional structured value (a glow, a light) is listed only where
-// the item has one, so every plain object's receipt stays as short as before.
-const listed = (element, item, paths) => paths ? paths.includes(element.path) : element.type !== 'object' || readElement(item, element.path) != null;
+// Unasked, an optional structured value (a glow, a light) or a `sparse` field (a
+// surface preset) is listed only where the item has one, so every plain
+// object's receipt stays as short as before.
+const listed = (element, item, paths) => paths ? paths.includes(element.path) : (element.type !== 'object' && !element.sparse) || readElement(item, element.path) != null;
 export function elementReadback(kind, item, paths, document) {
   return patchElements(projectionKind(kind)).filter(element => listed(element, item, paths)).map(element => {
     const path = element.path;

package/src/commands/objects.js

@@ -28,7 +28,7 @@ const semantic = [
 	// A clay prop from a recipe of soft parts (docs/sculpt-from-image.md). With `id` it re-sculpts that
 	// sculpt in place (one undo); without, it creates one. The recipe is checked by sculpt-recipe.js.
 	{ ...mutation('object.sculpt', 'Sculpt a clay prop from a recipe', input({ recipe: { type: 'object', properties: {}, additionalProperties: true }, edits: { type: 'array', minItems: 1, maxItems: 48, items: { type: 'object', properties: {}, additionalProperties: true } }, id, name: { type: 'string', maxLength: 240 }, placement, parent: id }, [])),
-		description: 'Create a sculpt (or re-sculpt one by id) from a recipe, or patch a sculpt by id with edits [{ set: partId, ...fields } | { add: part } | { remove: partId }]. Recipe { version: 1, parts: [{ id, shape: blob|box|cylinder|torus|frame, size: [x,y,z] m, position, rotation (deg), color, parent, mirror, roundness, taper, border }] }. Floor is y=0, front +z, the subject\'s left +x; mirror reflects across x=0.' },
+		description: 'Create a sculpt (or re-sculpt one by id) from a recipe, or patch a sculpt by id with edits [{ set: partId, ...fields } | { add: part } | { remove: partId }]. Recipe { version: 1, parts: [{ id, shape, size: [x,y,z] m, position, rotation (deg), color, parent, mirror, ...shape fields, material, finish, detail, gradient, op }] }. Shapes: blob {roundness, taper} soft forms; box {roundness}; cylinder {taper}; torus; frame {border} rims; lathe {profile [[r 0..1, y 0..1]...], smooth} turned objects (pot, vase, bottle, bowl, lampshade); tube {path [[x,y,z] each -0.5..0.5 of size], thickness m, taper, closed} ropes, vines, cables, handles, bike frames; extrude {outline [[x,y] -0.5..0.5], holes, roundness} flat cut shapes (sign, leaf, gable, star); loft {sections [{ y 0..1, points [[x,z]] } | { y, w, d, x?, z?, roundness? }], smooth} cross-sections that change (hull, car body, shoe, loaf); convex {points | seed, facetCount, facets} rocks, boulders, gems; scatter {item blade|tuft|flower|leaf|pebble|twig, count <= 4000, spread ground|shell, seed} thousands of small items as ONE part (grass, flower beds, gravel, leaf crowns). Any part: material clay|wood|straw|stone|brick|concrete|metal|glass|ceramic|plastic|rubber|fabric|paper|foliage (real texture and shine; color tints it; never fake glass with opacity or thatch with stripes) and finish matte|satin|gloss; detail {amount 0..1, scale, seed} lumpy surface (clouds, bushes, rocks, hay); gradient {color, axis, from, to} two-tone blend; op subtract|intersect turns the part into a cutter of its parent (windows, doors, arches; hollow a lathe with a smaller lathe of the same profile). Floor is y=0, front +z, the subject\'s left +x; mirror reflects across x=0.' },
 	mutation('object.remove', 'Remove objects', input({ ids })),
 	mutation('object.rename', 'Rename object', input({ id, name: { type: 'string', maxLength: 240 } })),
 	mutation('object.group', 'Group objects', input({ parent: id, children: ids })),

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/object-look.js

@@ -16,6 +16,7 @@
  */
 
 import { normalizeObjectColor } from "./object-colors.js";
+import { objectMaterialFields, objectMaterialPatch } from "./material-presets.js";
 
 export const LIGHT_KIND = "light";
 
@@ -94,8 +95,8 @@ export function normalizeObjectGlow(value) {
 }
 
 /** The light/glow fields a normalized record carries. A light renderer always
- * has a light; any record keeps a glow only when it has one, so records written
- * before glow existed come back byte-for-byte unchanged. */
+ * has a light; any record keeps a glow (and a primitive its surface preset)
+ * only when it has one, so records written before come back unchanged. */
 export function objectLookFields(record, entry) {
 	const out = {};
 	if ((entry.renderer ?? entry.kind) === LIGHT_KIND) out.light = normalizeObjectLight(record.light, record.light?.type ?? entry.light?.type);
@@ -103,12 +104,14 @@ export function objectLookFields(record, entry) {
 	if (glow) out.glow = glow;
 	// A kit part a take switches on (a muzzle flash and its light) stays hidden without one (object-travel.js trackShown).
 	if (record.showOnlyInTake === true) out.showOnlyInTake = true;
-	return out;
+	// A primitive's surface preset (material-presets.js).
+	return Object.assign(out, objectMaterialFields(record, entry.renderer ?? entry.kind));
 }
 
 /** The light/glow part of an object.update patch: each field merges over the
  * record's own and is repaired; `glow: null` removes the glow. Only changes are
- * returned. A light on a record that is not a light is ignored. */
+ * returned. A light on a record that is not a light is ignored. A primitive's
+ * material and finish ride along (material-presets.js). */
 export function objectLookPatch(object, patch) {
 	const update = {};
 	if (patch?.light && typeof patch.light === "object" && object.renderer === LIGHT_KIND) {
@@ -119,7 +122,7 @@ export function objectLookPatch(object, patch) {
 		const next = patch.glow === null ? null : normalizeObjectGlow({ ...(object.glow ?? {}), ...patch.glow });
 		if (JSON.stringify(next) !== JSON.stringify(object.glow ?? null)) update.glow = next;
 	}
-	return update;
+	return Object.assign(update, objectMaterialPatch(object, patch));
 }
 
 /** 32-bit FNV-1a of the record id: the flicker's seed. */
@@ -196,3 +199,4 @@ export function withShadowCapWarnings(result, objects) {
 }
 // A record's grasp sockets ride the same normalize and patch paths (object-grasp.js).
 export { objectGraspFields, objectGraspPatch } from "./object-grasp.js";
+export { objectMaterialKeys } from "./material-presets.js";

package/src/primitive-look.js

@@ -0,0 +1,38 @@
+/**
+ * A primitive's surface preset (object.material / object.finish) as the
+ * material props.jsx hangs on its mesh, and the polygon offset every prop
+ * material takes for its depth rank.
+ */
+
+import { useEffect, useMemo } from "react";
+import { lookMaterial } from "./material-look.js";
+
+// Parts of an assembly can share a plane with an earlier part (hood top and
+// grille top). The depth test can't order them and the winner flips as the
+// camera moves, so a ranked part is pulled toward the camera by `rank` steps
+// (negative = nearer). Rank 0 gets nothing: those materials stay untouched.
+export function depthRankProps(rank) {
+	return rank > 0 ? { polygonOffset: true, polygonOffsetFactor: -rank, polygonOffsetUnits: -rank } : null;
+}
+
+/** Each primitive's extent in its mesh frame at scale 1 (props.jsx builds
+ * them); the rest are unit sized. The shader multiplies the record's scale in. */
+const PRIMITIVE_SIZE = { capsule: [0.7, 1.4, 0.7], plane: [2, 2, 0.01] };
+
+/**
+ * The preset material for a primitive record, or null when the record keeps
+ * the plain clay look (no material and no finish) or auto-colour paints it
+ * flat: the caller then draws exactly what it drew before presets. Rebuilt
+ * when the look, the colour or the rank changes; the program and the pattern
+ * textures are shared, so a rebuild is cheap.
+ */
+export function usePrimitiveLook(object, kind, side, depthRank) {
+	const { material, finish, color, autoColor } = object;
+	const active = !autoColor && Boolean(material || finish);
+	const look = useMemo(
+		() => (active ? lookMaterial({ material, finish, color, side, size: PRIMITIVE_SIZE[kind] }, depthRankProps(depthRank)) : null),
+		[active, material, finish, color, side, kind, depthRank],
+	);
+	useEffect(() => () => look?.dispose(), [look]);
+	return look;
+}