partforge 0.122.0 → 0.124.0

package/src/framework/geometry/mesh-fillet.js

@@ -86,6 +86,21 @@ const rotVec = (p, k, th) => { // Rodrigues rotation about unit axis k
   return add(add(scl(p, c), scl(cross(k, p), s)), scl(k, dot(k, p) * (1 - c)));
 };
 
+// Analytic shading. Each fillet tool's blend wall is a canal surface about a known
+// spine (blend-surfaces.js); tell the kernel, which registers it against the tool's
+// surface id so toMesh can emit the exact rolling-ball normals instead of facet
+// averages. `surf` is in the tool's CURRENT (posed, world) frame. A kernel without
+// the hook (or a chamfer, whose flat/conical walls facet-shade exactly already) just
+// gets the tool back.
+const markBlend = (k, tool, surf) => (k._markBlendSurface ? k._markBlendSurface(tool, surf) : tool);
+// The ball centre's offset from the edge point, given the two unit flank normals —
+// profile2D's C, in any dimension (2-D profile coordinates or 3-D world vectors).
+const ballOffset = (n1, n2, r, convex) => {
+  const c = clamp1(n1.reduce((acc, x, i) => acc + x * n2[i], 0));
+  const f = (convex ? 1 : -1) * (-r / (1 + c));
+  return n1.map((x, i) => f * (x + n2[i]));
+};
+
 // ---------------------------------------------------------------------------
 // Sharp-edge extraction: weld vertices, keep edges whose two incident triangles
 // meet at a dihedral sharper than sharpDeg, tag convexity and flank normals.
@@ -663,7 +678,8 @@ function prismTool(k, chain, magnitude, mode, segs, pSegs = segs) {
     { shading: "smooth" },
   );
   if (axis) tool = tool.rotateAbout({ axis, deg: (theta * 180) / Math.PI });
-  return tool.translate(a);
+  tool = tool.translate(a);
+  return mode === "fillet" ? markBlend(k, tool, { kind: "line", p: add(a, ballOffset(n1, n2, magnitude, convex)), d: e }) : tool;
 }
 
 // `segs` is the KERNEL quality — it sizes the flank-facet guards (sag/ext) and the
@@ -756,7 +772,11 @@ function revolveTool(k, chain, magnitude, mode, segs, pSegs = segs, flankAt = ()
   const dephase = closed ? Math.PI / flankSegs : 0;
   const twist = Math.atan2(dot(w, cross(xImage, startDir)), dot(xImage, startDir)) + dephase;
   if (Math.abs(twist) > 1e-9) tool = tool.rotateAbout({ axis: w, deg: (twist * 180) / Math.PI });
-  return tool.translate(O);
+  tool = tool.translate(O);
+  if (mode !== "fillet") return tool;
+  // spine: the ball centre's circle — profile C = [R, 0] + offset in (ρ, w)
+  const C = ballOffset(n1, n2, magnitude, convex);
+  return markBlend(k, tool, { kind: "circle", c: add(O, scl(w, C[1])), a: w, R: R + C[0] });
 }
 
 // ---------------------------------------------------------------------------
@@ -895,6 +915,32 @@ function weldChainPoints(pts, wallNs, closed) {
   return { pts: outP, wallNs: outW };
 }
 
+// The spine of a planar sweep tool, as a "path" blend surface (blend-surfaces.js).
+// The sweep transports the profile about the face normal, so the wall keeps its
+// face-normal component and its in-plane part turns with the path; the seed segment
+// (the one sweepSeedFrame is built ⟂ to: the first, or the closing one of a loop)
+// fixes which side that is. Vertex directions bisect their two segments' sides.
+function planarSpine(path, closed, faceN, wallN, magnitude, convex) {
+  const n = path.length, nSeg = closed ? n : n - 1;
+  const tan = (i) => norm(sub(path[(i + 1) % n], path[i]));
+  const tSeed = tan(closed ? n - 1 : 0);
+  const wallP = norm(sub(wallN, scl(tSeed, dot(wallN, tSeed))));
+  const cf = dot(wallP, faceN);
+  const wIn = sub(wallP, scl(faceN, cf));
+  const side = dot(wIn, cross(faceN, tSeed)) >= 0 ? 1 : -1;
+  const segSide = [];
+  for (let i = 0; i < nSeg; i++) segSide.push(scl(norm(cross(faceN, tan(i))), side));
+  const dirs = path.map((_, i) => {
+    const a = closed ? segSide[(i - 1 + nSeg) % nSeg] : segSide[Math.max(0, i - 1)];
+    const b = closed ? segSide[i % nSeg] : segSide[Math.min(nSeg - 1, i)];
+    const m = norm(add(a, b));
+    return len(m) > 0 ? m : a;
+  });
+  // ballOffset(faceN, wall) = K·(faceN + wall) with wall = cf·faceN + |wIn|·dir
+  const K = (convex ? 1 : -1) * (-magnitude / (1 + clamp1(cf)));
+  return { kind: "path", pts: path, closed, dirs, f: faceN, kf: K * (1 + cf), kd: K * len(wIn) };
+}
+
 function planarTool(k, chain, magnitude, mode, segs, pSegs = segs, endTins = null, flankAt = () => segs) {
   const { points, closed, convex, faceN } = chain;
   let { wallNs } = chain;
@@ -1036,7 +1082,8 @@ function planarTool(k, chain, magnitude, mode, segs, pSegs = segs, endTins = nul
       return [q[0] / l, q[1] / l];
     };
     const poly = profile2D({ P: [0, 0], n1: p2(faceN), n2: p2(wallN), magnitude, mode, convex, segs: pSegs });
-    return k.sweep(poly, path3D, { closed: isClosed });
+    const tool = k.sweep(poly, path3D, { closed: isClosed });
+    return mode === "fillet" ? markBlend(k, tool, planarSpine(path3D, isClosed, faceN, wallN, magnitude, convex)) : tool;
   };
 
   // Sweep one open stretch; when the sweep refuses a VERTEX fold the pre-split
@@ -1333,7 +1380,9 @@ function reflexPivotTool(k, { vertex, f, u0, span }, magnitude, mode, segs, pSeg
   const xImage = axis ? rotVec([1, 0, 0], axis, theta) : [1, 0, 0];
   const twist = Math.atan2(dot(f, cross(xImage, startDir)), dot(xImage, startDir));
   if (Math.abs(twist) > 1e-9) tool = tool.rotateAbout({ axis: f, deg: (twist * 180) / Math.PI });
-  return tool.translate(vertex);
+  tool = tool.translate(vertex);
+  // spine: the ball centre swings on a circle of radius r, r below the face
+  return mode === "fillet" ? markBlend(k, tool, { kind: "circle", c: sub(vertex, scl(f, r)), a: f, R: r }) : tool;
 }
 
 function chainEndInfo(ch, end) {
@@ -1546,7 +1595,8 @@ function cornerPatches(k, selected, r, segs, flankAt = () => segs) {
     const twist = Math.atan2(dot(e1, cross(xImage, e2)), dot(xImage, e2));
     if (Math.abs(twist) > 1e-9) block = block.rotateAbout({ axis: e1, deg: (twist * 180) / Math.PI });
     block = block.translate(V);
-    patches.push(block.cut(k.sphere({ r }).at(add(C, scl(inward, bury)))));
+    const centre = add(C, scl(inward, bury));
+    patches.push(block.cut(markBlend(k, k.sphere({ r }).at(centre), { kind: "point", c: centre })));
   }
   return patches;
 }

package/src/framework/materials/assets/SOURCES.md

@@ -68,7 +68,7 @@ the sliced primary and gain-map buffers now start with SOI (`FF D8`) and end wit
 | `pattern-walnut-rough.jpg` | Poly Haven "Dark Wood" (roughness; API key `Rough`) | https://polyhaven.com/a/dark_wood — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/dark_wood/dark_wood_rough_1k.jpg | 2026-09-24 | 1K JPG, grayscale data -> `node scripts/bake-environments.mjs --texture dark_wood_rough_1k.jpg pattern-walnut-rough.jpg --gray` (source is neutral grey; channel means unchanged). |
 | `ground-maple-color.jpg` | Poly Haven "Oak Veneer 01" (colour; API key `Diffuse`) | https://polyhaven.com/a/oak_veneer_01 — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/oak_veneer_01/oak_veneer_01_diff_1k.jpg | 2026-09-24 | Workshop floor, "unfinished maple": `node scripts/bake-environments.mjs --texture oak_veneer_01_diff_1k.jpg ground-maple-color.jpg --modulate 1.5,0.7 --quality 85` (lightened 1.5x, saturation 0.7). |
 | `ground-maple-normal.jpg` | Poly Haven "Oak Veneer 01" (OpenGL normal map; API key `nor_gl`) | https://polyhaven.com/a/oak_veneer_01 — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/oak_veneer_01/oak_veneer_01_nor_gl_1k.jpg | 2026-09-24 | Workshop floor relief: `node scripts/bake-environments.mjs --texture oak_veneer_01_nor_gl_1k.jpg ground-maple-normal.jpg --data --quality 92`. A separate file from `pattern-oak-normal.jpg` so the floor and the oak material never share (and dispose) one texture. |
-| `ground-pei.jpg` | None — procedural | n/a | n/a | Gold-brown fine-grain speckle, no external source. First attempt tinted ambientCG "Plastic 010"'s colour map (near-uniform, stdev < 1/channel — visibly flat, no grain, when actually viewed) gold-brown; that colour map carries no usable grain at all (its roughness map does, which is why `ground-pei-rough.jpg` below is still Plastic010's roughness). Checked ambientCG alternatives (Metal049A — also flat; Granite006A — real speckle but reads as rock, not powder-coat) and found nothing closer. Generated in-baker instead, same procedural precedent as `pattern-carbon.jpg`: per-pixel triangular-distributed noise around a `196,154,82` gold-brown base (asymmetric per channel so flecks warm rather than grey), then a 0.5px blur to turn single-pixel noise into soft grains -> `node scripts/bake-environments.mjs --speckle ground-pei.jpg --tint 196,154,82`. |
+| `ground-pei.jpg` | None — procedural | n/a | n/a | Gold-brown fine-grain speckle, no external source. First attempt tinted ambientCG "Plastic 010"'s colour map (near-uniform, stdev < 1/channel — visibly flat, no grain, when actually viewed) gold-brown; that colour map carries no usable grain at all (its roughness map does, which is why `ground-pei-rough.jpg` below is still Plastic010's roughness). Checked ambientCG alternatives (Metal049A — also flat; Granite006A — real speckle but reads as rock, not powder-coat) and found nothing closer. Generated in-baker instead, same procedural precedent as `pattern-carbon.jpg`: per-pixel triangular-distributed noise around a `168,134,82` bronze-gold base (asymmetric per channel so flecks warm rather than grey), then a 0.5px blur to turn single-pixel noise into soft grains -> `node scripts/bake-environments.mjs --speckle ground-pei.jpg --tint 168,134,82`. (Re-baked 2026-09-24 from `196,154,82`: darker and less saturated, closer to a Bambu textured-PEI plate's muted bronze-gold.) |
 | `ground-pei-rough.jpg` | ambientCG "Plastic 010" (Roughness) | https://ambientcg.com/a/Plastic010 | 2026-09-24 | 1K JPG, grayscale -> `node scripts/bake-environments.mjs --texture Plastic010_1K-JPG_Roughness.jpg ground-pei-rough.jpg --gray` |
 | `ground-concrete.jpg` | ambientCG "Concrete 047 A" (Color) | https://ambientcg.com/a/Concrete047A | 2026-09-24 | 2K JPG -> `node scripts/bake-environments.mjs --texture Concrete047A_2K-JPG_Color.jpg ground-concrete.jpg --size 1024 --modulate 1.35,0 --flatten 0.7 --quality 82` (grey, brightened to the old map's mean so the concrete material preset keeps its tone; `--flatten 0.7` is 30% less grain contrast). Replaced ambientCG "Concrete 034", whose colour map was nearly flat (stdev ~5/255) and read as blur up close; 047 A's exposed aggregate keeps fine grain. |
 | `ground-concrete-rough.jpg` | ambientCG "Concrete 047 A" (Roughness) | https://ambientcg.com/a/Concrete047A | 2026-09-24 | 2K JPG, grayscale -> `node scripts/bake-environments.mjs --texture Concrete047A_2K-JPG_Roughness.jpg ground-concrete-rough.jpg --gray --size 1024` |

package/src/framework/materials/environment.js

@@ -94,21 +94,32 @@ export async function loadEnvironmentRig(renderer, requestedId, { loadHdr, loadT
   if (env.ground.bed) {
     const material = groundMaterial(tex, rough, normal, { ...env.ground, bed: true });
     const bed = createPrintBed({ pei: material, tileMm: env.ground.tileMm ?? env.ground.sizeMm, createCanvas });
-    // An enclosure's LED bar: one hard overhead light, riding with the bed so
-    // it always falls on the part from the same place.
+    // An enclosure's LED bar: one hard overhead light, aimed at the bed's own
+    // origin. The LIGHT itself is deliberately not a child of bed.object:
+    // updateForCamera hides that whole group from below, and a hidden parent
+    // stops three from rendering its children too — the light would go dark
+    // exactly when the part needs it lit from underneath. It rides in
+    // `lights` instead and is repositioned by hand wherever the bed moves.
+    // The target CAN stay a child (matrixWorld updates regardless of
+    // visibility), which is what lets it keep tracking the bed for free.
     let keyLight = null;
     if (env.keyLight) {
       keyLight = new THREE.DirectionalLight(0xffffff, env.keyLight.intensity);
-      keyLight.position.set(...env.keyLight.direction);
-      bed.object.add(keyLight, keyLight.target);
+      bed.object.add(keyLight.target);
     }
     return {
       id, exposure: env.exposure, envMap, background, backgroundBlurriness, backgroundIntensity,
       rotationY: ((env.rotationDeg ?? 0) * Math.PI) / 180,
       ground: bed.object,
+      lights: keyLight ? [keyLight] : [],
       shadow,
+      updateForCamera(camera) { bed.updateForCamera(camera); },
       setGround({ y, centerX = 0, centerZ = 0, radius, footprintMm = radius }) {
         bed.place({ y, centerX, centerZ, footprintMm });
+        if (keyLight) {
+          const p = bed.object.position; // the fixed offset off the bed's origin
+          keyLight.position.set(p.x + env.keyLight.direction[0], p.y + env.keyLight.direction[1], p.z + env.keyLight.direction[2]);
+        }
         shadow.group.position.set(centerX, y, centerZ);
         // The shadow plane never hangs past the plate's edge into thin air.
         const s = Math.min(Math.max(radius * 3, 20), bed.sizeMm);
@@ -147,6 +158,7 @@ export async function loadEnvironmentRig(renderer, requestedId, { loadHdr, loadT
     backgroundIntensity,
     rotationY: ((env.rotationDeg ?? 0) * Math.PI) / 180,
     ground,
+    lights: [],
     shadow,
     setGround,
     dispose() {

package/src/framework/materials/patterns.js

@@ -45,10 +45,22 @@ uniform sampler2D pfNormalMap;
 uniform sampler2D pfRoughMap;
 uniform float pfRoughMean;
 uniform float pfNormalStrength;
+uniform vec3 pfGrainSwap;
 varying vec3 vPfNmX;
 varying vec3 vPfNmY;
 varying vec3 vPfNmZ;
 vec3 pfTriplanarWeights(vec3 n) { vec3 w = pow(abs(n), vec3(4.0)); return w / (w.x + w.y + w.z); }
+// One grain direction on every face: each projection's UV pair is transposed
+// where pfGrainSwap says so (grainSwaps below), so the texture's grain lands on
+// the sub-part's grain axis. A transpose is a mirror, not a rotation, which is
+// what keeps the normal map exact: its slopes just swap axes (t.yx), no signs.
+vec2 pfGrainUv(vec2 ab, float s) { return mix(ab, ab.yx, s); }
+vec3 pfTriplanarWood(sampler2D map, vec3 p, vec3 n) {
+  vec3 w = pfTriplanarWeights(n);
+  return texture2D(map, pfGrainUv(p.yz, pfGrainSwap.x) / pfPatternScale).rgb * w.x
+       + texture2D(map, pfGrainUv(p.xz, pfGrainSwap.y) / pfPatternScale).rgb * w.y
+       + texture2D(map, pfGrainUv(p.xy, pfGrainSwap.z) / pfPatternScale).rgb * w.z;
+}
 // Triplanar tangent-space normal map, whiteout-blended (Golus, "Normal Mapping
 // for a Triplanar Shader"). Each projection's map is read as a height field over
 // the two object axes its UVs run along, so its tangent normal (x, y) is a slope
@@ -59,10 +71,13 @@ vec3 pfTriplanarWeights(vec3 n) { vec3 w = pow(abs(n), vec3(4.0)); return w / (w
 // Poly Haven "nor_gl" convention. Returns an OBJECT-space unit normal.
 vec3 pfTriplanarNormal(vec3 p, vec3 n, float scale) {
   vec3 w = pfTriplanarWeights(n);
-  vec3 tx = texture2D(pfNormalMap, p.yz / scale).xyz * 2.0 - 1.0;
-  vec3 ty = texture2D(pfNormalMap, p.xz / scale).xyz * 2.0 - 1.0;
-  vec3 tz = texture2D(pfNormalMap, p.xy / scale).xyz * 2.0 - 1.0;
-  tx.xy *= pfNormalStrength; ty.xy *= pfNormalStrength; tz.xy *= pfNormalStrength;
+  vec3 tx = texture2D(pfNormalMap, pfGrainUv(p.yz, pfGrainSwap.x) / scale).xyz * 2.0 - 1.0;
+  vec3 ty = texture2D(pfNormalMap, pfGrainUv(p.xz, pfGrainSwap.y) / scale).xyz * 2.0 - 1.0;
+  vec3 tz = texture2D(pfNormalMap, pfGrainUv(p.xy, pfGrainSwap.z) / scale).xyz * 2.0 - 1.0;
+  // a transposed sample's slopes run along the swapped axes
+  tx.xy = pfGrainUv(tx.xy, pfGrainSwap.x) * pfNormalStrength;
+  ty.xy = pfGrainUv(ty.xy, pfGrainSwap.y) * pfNormalStrength;
+  tz.xy = pfGrainUv(tz.xy, pfGrainSwap.z) * pfNormalStrength;
   tx = vec3(tx.xy + n.yz, abs(tx.z) * n.x);   // uv = (y, z), face axis x
   ty = vec3(ty.xy + n.xz, abs(ty.z) * n.y);   // uv = (x, z), face axis y
   tz = vec3(tz.xy + n.xy, abs(tz.z) * n.z);   // uv = (x, y), face axis z
@@ -102,11 +117,12 @@ const FRAG_BODY = {
   // author tinted it, physical.js — and the roughness map varies roughnessFactor
   // around the preset's value (divided by the map's own mean, so the preset sets
   // the average). Mipmaps (and RepeatWrapping) do the far-distance filtering.
+  // All three maps follow the grain axis (pfTriplanarWood / setGrainAxis).
   wood: `
   {
     vec3 pfN = normalize(vPfObjNormal);
-    diffuseColor.rgb *= pfTriplanar(pfPatternMap, vPfObjPos, pfN, pfPatternScale);
-    float r = pfTriplanar(pfRoughMap, vPfObjPos, pfN, pfPatternScale).g;
+    diffuseColor.rgb *= pfTriplanarWood(pfPatternMap, vPfObjPos, pfN);
+    float r = pfTriplanarWood(pfRoughMap, vPfObjPos, pfN).g;
     roughnessFactor = clamp(roughnessFactor * r / pfRoughMean, 0.02, 1.0);
   }`,
   // Carbon samples a luminance MASK (raw, not sRGB-decoded: physical.js) and
@@ -164,7 +180,40 @@ const FRAG_NORMAL = {
   }`,
 };
 
-export function applyPattern(material, { kind, scale = 1, printFrame, texture, normalMap, roughnessMap, roughnessMean = 0.5, normalScale = 1 } = {}) {
+// Wood grain: real wood has ONE grain direction, the board's long axis, but a
+// triplanar projection with fixed UVs (X-faces (y, z), Y-faces (x, z), Z-faces
+// (x, y)) lands the texture's grain on a different object axis per face — on a
+// block, adjacent faces showed grain at right angles. So each sub-part gets a
+// grain axis (its longest object-space bounding-box axis, X on a tie) and every
+// projection whose face CONTAINS that axis is transposed where needed so the
+// texture's grain runs along it. Faces across the axis are end grain; there is
+// no end-grain texture, so they keep the default sample.
+//
+// `grain` is which texture axis a scan's figure runs along ("u" horizontal, "v"
+// vertical in the image), declared per texture set in presets.js.
+const PLANE_AXES = [[1, 2], [0, 2], [0, 1]]; // each projection's (u, v) object axes
+export function grainAxisFor(box) {
+  if (!box || box.isEmpty?.()) return 0;
+  const s = [box.max.x - box.min.x, box.max.y - box.min.y, box.max.z - box.min.z];
+  const eps = Math.max(...s) * 1e-6;
+  let axis = 0;
+  for (let i = 1; i < 3; i++) if (s[i] > s[axis] + eps) axis = i;
+  return axis;
+}
+export function grainSwaps(axis, grain = "u") {
+  const want = grain === "v" ? 1 : 0;
+  return PLANE_AXES.map(([u], face) => (face === axis ? 0 : (axis === u ? 0 : 1) !== want ? 1 : 0));
+}
+// Point a wood material (and every clone sharing its uniforms) at a grain axis.
+// A no-op on any other material.
+export function setGrainAxis(material, axis) {
+  const u = material?.userData?.patternUniforms?.pfGrainSwap;
+  if (!u) return;
+  material.userData.pfGrainAxis = axis;
+  u.value.fromArray(grainSwaps(axis, material.userData.pfGrain));
+}
+
+export function applyPattern(material, { kind, scale = 1, printFrame, texture, normalMap, roughnessMap, roughnessMean = 0.5, normalScale = 1, grain = "u" } = {}) {
   if (!kind || !FRAG_BODY[kind]) return material;
   const wood = kind === "wood";
   const uniforms = {
@@ -176,9 +225,11 @@ export function applyPattern(material, { kind, scale = 1, printFrame, texture, n
       pfRoughMap: { value: roughnessMap ?? null },
       pfRoughMean: { value: roughnessMean },
       pfNormalStrength: { value: normalScale },
+      pfGrainSwap: { value: new THREE.Vector3() },
     } : {}),
   };
   material.userData.patternUniforms = uniforms;
+  if (wood) { material.userData.pfGrain = grain; setGrainAxis(material, 0); }
   material.onBeforeCompile = (shader) => {
     Object.assign(shader.uniforms, uniforms);
     shader.vertexShader = shader.vertexShader
@@ -193,3 +244,51 @@ export function applyPattern(material, { kind, scale = 1, printFrame, texture, n
   material.needsUpdate = true;
   return material;
 }
+
+// Brush frame for anisotropic (brushed) metal, chosen PER PIXEL. three follows the
+// tangent frame `tbn`; built from per-vertex data it interpolates across each
+// triangle, so wherever the brush direction has to turn (it must, somewhere, on
+// any closed part) the turn followed the triangulation — a jagged staircase across
+// a fillet corner's small facets. Here the box-projection rule (brush along object
+// X, or along Y where X dominates the normal) runs on the interpolated object
+// normal in the fragment, so the turn lands on the smooth |nx| = max(|ny|,|nz|)
+// contour instead. The frame is rebuilt from the final shading `normal`, just
+// before <lights_physical_fragment> reads it. Composes with a pattern's own
+// injection (applied first) rather than replacing it.
+const BRUSH_VERT_DECL = "varying vec3 vPfBrushN;\nvarying vec3 vPfBrushNmX;\nvarying vec3 vPfBrushNmY;\nvarying vec3 vPfBrushNmZ;\n";
+const BRUSH_VERT_BODY = "vPfBrushN = normal;\nvPfBrushNmX = normalMatrix[0];\nvPfBrushNmY = normalMatrix[1];\nvPfBrushNmZ = normalMatrix[2];\n";
+const BRUSH_FRAG_DECL = "varying vec3 vPfBrushN;\nvarying vec3 vPfBrushNmX;\nvarying vec3 vPfBrushNmY;\nvarying vec3 vPfBrushNmZ;\n";
+const BRUSH_FRAG_BODY = `
+  #ifdef USE_ANISOTROPY
+  {
+    vec3 pfN = normalize(vPfBrushN);
+    vec3 pfA = abs(pfN);
+    vec3 pfAxis = (pfA.x > pfA.y && pfA.x > pfA.z) ? vec3(0.0, 1.0, 0.0) : vec3(1.0, 0.0, 0.0);
+    vec3 pfT = mat3(vPfBrushNmX, vPfBrushNmY, vPfBrushNmZ) * (pfAxis - pfN * dot(pfAxis, pfN));
+    pfT = pfT - normal * dot(normal, pfT);
+    if (dot(pfT, pfT) > 1e-12) {
+      pfT = normalize(pfT);
+      tbn[0] = pfT;
+      tbn[1] = cross(normal, pfT);
+    }
+  }
+  #endif
+`;
+
+export function applyBrushFrame(material) {
+  const prev = material.onBeforeCompile;
+  const prevKey = material.customProgramCacheKey;
+  material.onBeforeCompile = (shader, renderer) => {
+    prev?.call(material, shader, renderer);
+    shader.vertexShader = shader.vertexShader
+      .replace("#include <common>", `#include <common>\n${BRUSH_VERT_DECL}`)
+      .replace("#include <begin_vertex>", `#include <begin_vertex>\n${BRUSH_VERT_BODY}`);
+    shader.fragmentShader = shader.fragmentShader
+      .replace("#include <common>", `#include <common>\n${BRUSH_FRAG_DECL}`)
+      .replace("#include <lights_physical_fragment>", `${BRUSH_FRAG_BODY}\n#include <lights_physical_fragment>`);
+  };
+  const base = prevKey && prevKey !== THREE.Material.prototype.customProgramCacheKey ? prevKey.call(material) : "";
+  material.customProgramCacheKey = () => `${base}|pf-brush`;
+  material.needsUpdate = true;
+  return material;
+}

package/src/framework/materials/physical.js

@@ -5,7 +5,7 @@
 // disagree about which preset a sub-part is.
 import * as THREE from "three";
 import { cadAppearance, resolveMaterial } from "./resolve.js";
-import { applyPattern } from "./patterns.js";
+import { applyBrushFrame, applyPattern } from "./patterns.js";
 import { PATTERN_TEXTURES } from "./assets.js";
 
 const APPEARANCE_KEYS = ["color", "opacity", "material", "roughness", "metalness", "clearcoat", "clearcoatRoughness", "anisotropy", "textureScale"];
@@ -24,7 +24,13 @@ export function buildCadMaterial(display, base) {
 
 // Realistic-mode material. `loadTexture(fileName)` is injected (the viewer owns
 // a caching TextureLoader), so this stays unit-testable without a network.
-export function buildPhysicalMaterial(display, { printFrame, loadTexture } = {}) {
+export function buildPhysicalMaterial(display, opts = {}) {
+  const m = buildPhysical(display, opts);
+  // brushed metal picks its brush direction per pixel (patterns.js applyBrushFrame)
+  return m.userData.pfAnisotropic ? applyBrushFrame(m) : m;
+}
+
+function buildPhysical(display, { printFrame, loadTexture } = {}) {
   const { params, tinted } = resolveMaterial(display);
   const set = params.textures;
   // A textured preset's colour map carries its own colour; the preset `color` is
@@ -66,6 +72,7 @@ export function buildPhysicalMaterial(display, { printFrame, loadTexture } = {})
       roughnessMap: load(set.roughness, THREE.NoColorSpace),
       roughnessMean: set.roughnessMean,
       normalScale: set.normalScale,
+      grain: set.grain,
     });
     return m;
   }

package/src/framework/materials/presets.js

@@ -77,13 +77,16 @@ export const PRESETS = {
   // `roughnessMean` is the roughness map's mean, so the preset `roughness` (or an
   // override) sets the AVERAGE roughness and the map only varies it. `normalScale`
   // strengthens the normal map: these scans' tangent normals barely leave +Z (a
-  // ~1% tilt), which reads as flat under an environment map.
+  // ~1% tilt), which reads as flat under an environment map. `grain` is the
+  // texture axis the scan's figure runs along — oak's runs up the image ("v"),
+  // walnut's across it ("u") — so patterns.js can lay it along each sub-part's
+  // long axis.
   oak: P("oak", "Oak", "natural", "Light oak with open grain.",
     { color: 0xa17e57, metalness: 0, roughness: 0.65, pattern: "wood", textureScale: 250,
-      textures: { color: "pattern-oak-color.jpg", normal: "pattern-oak-normal.jpg", roughness: "pattern-oak-rough.jpg", roughnessMean: 0.53, normalScale: 2.5 } }),
+      textures: { color: "pattern-oak-color.jpg", normal: "pattern-oak-normal.jpg", roughness: "pattern-oak-rough.jpg", roughnessMean: 0.53, normalScale: 2.5, grain: "v" } }),
   walnut: P("walnut", "Walnut", "natural", "Dark oiled walnut.",
     { color: 0x5d2a18, metalness: 0, roughness: 0.5, clearcoat: 0.3, clearcoatRoughness: 0.4, pattern: "wood", textureScale: 400,
-      textures: { color: "pattern-walnut-color.jpg", normal: "pattern-walnut-normal.jpg", roughness: "pattern-walnut-rough.jpg", roughnessMean: 0.628, normalScale: 3 } }),
+      textures: { color: "pattern-walnut-color.jpg", normal: "pattern-walnut-normal.jpg", roughness: "pattern-walnut-rough.jpg", roughnessMean: 0.628, normalScale: 3, grain: "u" } }),
   "carbon-fiber": P("carbon-fiber", "Carbon fibre", "natural", "2x2 twill carbon fibre under clear coat.",
     { color: 0x1b1c1e, metalness: 0.2, roughness: 0.35, clearcoat: 1, clearcoatRoughness: 0.05, pattern: "carbon", textureScale: 48 }),
 };

package/src/framework/materials/print-bed.js

@@ -154,6 +154,14 @@ export function createPrintBed({ pei, tileMm, createCanvas }) {
     ink.scale.set(size, 1, size);
   }
 
+  // Below this, the whole plate hides — like the other environments' single-
+  // sided ground discs, which cull away once the camera passes their back
+  // face. The epsilon keeps a camera sitting exactly at plate height from
+  // flickering the bed in and out as float error nudges it either side.
+  const HIDE_EPSILON_MM = 0.05;
+  const _camWorld = new THREE.Vector3();
+  const _topWorld = new THREE.Vector3();
+
   return {
     object: group,
     get sizeMm() { return size; },
@@ -161,6 +169,15 @@ export function createPrintBed({ pei, tileMm, createCanvas }) {
       setSize(bedSizeFor(footprintMm));
       group.position.set(centerX, y - 0.01, centerZ);
     },
+    // Called once per render, with the camera actually doing the rendering
+    // (the live camera, or an offscreen capture's) — never a cached "current
+    // view" — so a canonical "from below" render also sees the part rather
+    // than the plate's underside.
+    updateForCamera(camera) {
+      camera.getWorldPosition(_camWorld);
+      group.getWorldPosition(_topWorld); // local y = 0 is the plate's top surface
+      group.visible = _camWorld.y >= _topWorld.y - HIDE_EPSILON_MM;
+    },
     dispose() {
       plate.geometry.dispose(); ink.geometry.dispose();
       edge.dispose(); inkMat.dispose(); inkTex?.dispose();

package/src/framework/materials/uv.js

@@ -1,23 +1,42 @@
-// Box-projected UVs, added only for realistic mode. three's anisotropy (brushed
-// metal) builds its tangent frame from UV derivatives, and CAD meshes carry no
-// UVs. Projection is in OBJECT space along each vertex normal's dominant axis, so
-// it rides with the sub-part and never swims. Seams on curved surfaces are
-// acceptable: nothing samples a texture through these UVs — triplanar patterns
-// (patterns.js) ignore them.
+// Box-projected UVs and brush tangents, added only for realistic mode. three's
+// anisotropy (brushed metal) needs a tangent frame, and CAD meshes carry neither
+// UVs nor tangents. Projection is in OBJECT space along each vertex normal's
+// dominant axis, so it rides with the sub-part and never swims. Nothing samples a
+// texture through these UVs — triplanar patterns (patterns.js) ignore them.
+//
+// The TANGENT attribute is what the brush actually follows. Without one, three
+// derives the frame per pixel from screen-space UV derivatives, which is constant
+// across each triangle: on a fillet or a corner every facet read as its own flat
+// brushed patch, and a triangle whose corners picked different projection axes
+// got a garbage frame outright. The per-vertex tangent is the projection's u-axis
+// (world X, or Y where X dominates the normal) flattened into the tangent plane, so
+// it interpolates smoothly with the (analytic) vertex normals. It turns 90° only
+// across the one facet row where the dominant axis changes, and never through
+// zero — the two candidate axes are orthogonal.
 import * as THREE from "three";
 
 export function ensureBoxUVs(geometry, scaleMm = 20) {
-  if (geometry.userData.boxUVs && geometry.attributes.uv) return geometry;
+  if (geometry.userData.boxUVs && geometry.attributes.uv && geometry.attributes.tangent) return geometry;
   const pos = geometry.attributes.position, nrm = geometry.attributes.normal;
   const uv = new Float32Array(pos.count * 2);
+  const tangent = new Float32Array(pos.count * 4);
   for (let i = 0; i < pos.count; i++) {
     const x = pos.getX(i), y = pos.getY(i), z = pos.getZ(i);
-    const ax = Math.abs(nrm ? nrm.getX(i) : 0), ay = Math.abs(nrm ? nrm.getY(i) : 0), az = Math.abs(nrm ? nrm.getZ(i) : 1);
+    const nx = nrm ? nrm.getX(i) : 0, ny = nrm ? nrm.getY(i) : 0, nz = nrm ? nrm.getZ(i) : 1;
+    const ax = Math.abs(nx), ay = Math.abs(ny), az = Math.abs(nz);
     let u, v;
     if (az >= ax && az >= ay) { u = x; v = y; } else if (ay >= ax) { u = x; v = z; } else { u = y; v = z; }
     uv[i * 2] = u / scaleMm; uv[i * 2 + 1] = v / scaleMm;
+    // u-axis minus its normal component; |that| ≥ √½ because the axis is never the
+    // dominant one, so the normalize is always well-conditioned
+    const uxAxis = !(ax > ay && ax > az);
+    const d = uxAxis ? nx : ny;
+    let tx = (uxAxis ? 1 : 0) - d * nx, ty = (uxAxis ? 0 : 1) - d * ny, tz = -d * nz;
+    const L = Math.hypot(tx, ty, tz) || 1;
+    tangent[i * 4] = tx / L; tangent[i * 4 + 1] = ty / L; tangent[i * 4 + 2] = tz / L; tangent[i * 4 + 3] = 1;
   }
   geometry.setAttribute("uv", new THREE.BufferAttribute(uv, 2));
+  geometry.setAttribute("tangent", new THREE.BufferAttribute(tangent, 4));
   geometry.userData.boxUVs = true;
   return geometry;
 }