partforge 0.122.0 → 0.123.0

package/docs/KERNEL-CONTRACT.md

@@ -406,6 +406,16 @@ are present:
 - `normals` — per-vertex shading normals. Smooth within one surface, hard
   across boolean-cut seams. OCCT ships analytic B-rep normals; Manifold ships
   the policy-aware crease pass (`src/framework/geometry/creased-normals.js`).
+  Fillet bands are analytic on both backends: each Manifold fillet tool registers
+  its rolling-ball spine (`src/framework/geometry/blend-surfaces.js` — a line,
+  circle, point or planar path), and the crease pass shades any smooth group the
+  band takes part in with that exact normal, so a band meets the faces it is
+  tangent to with matching normals (within 0.1° of the true surface on a
+  filleted box — `test/mesh-fillet-normals.test.js`, with its OCCT twin in
+  `test/occt-shading.test.js`). The spine follows the band through later
+  booleans, poses and `label()`. Planar-path bands (rims of extrusions) shade
+  the smooth curve their polyline samples; at a line-to-arc junction in that
+  polyline the normal is off by up to half an arc segment, as before.
 - `edges` — flat feature-edge segment pairs (6 floats per segment). An EMPTY
   array means "this solid has no feature edges"; it is not "unknown". OCCT
   ships true B-rep edges with tangent edges (fillet blends, seam lines)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.122.0",
+  "version": "0.123.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/geometry/blend-surfaces.js

@@ -0,0 +1,256 @@
+// Analytic blend-surface descriptors — the exact normal field of a mesh fillet band.
+//
+// A mesh fillet (mesh-fillet.js) is a boolean against tool solids whose curved wall
+// IS the rolling-ball surface. Facet-averaged vertex normals on that wall are only
+// approximately right: one-sided at the band's tangent boundary (half a facet off
+// the face it is tangent to — ~1-2° at preview density), biased by the boolean's
+// uneven fans, and on a coarse corner sphere several degrees off the edge cylinders
+// it meets. Every blend surface is a canal surface — the envelope of a ball rolling
+// along a SPINE — so its exact normal at any point is the direction from the nearest
+// spine point, and the spine is known when the tool is built. A descriptor records
+// that spine:
+//
+//   { kind: "line",   p, d }        straight edge → cylinder (prism tools)
+//   { kind: "circle", c, a, R }     arc edge → torus (revolve / pivot tools); R may
+//                                   be 0 (a sphere about c)
+//   { kind: "point",  c }           sphere (corner patches)
+//   { kind: "path", pts, closed, dirs, f, kf, kd }
+//                                   planar polyline edge (planar sweep tools): pts is
+//                                   the swept path, f its face normal, dirs[i] the
+//                                   in-plane wall-side direction at vertex i, and the
+//                                   ball centre sits at kf·f + kd·dir off the edge
+//
+// A path's polyline usually STANDS FOR a smooth curve (a circle's rim, an outline's
+// rounded corner): its per-segment cylinders would shade faceted around the curve,
+// while the facet average this replaces blurred those joints smooth. So the path
+// normal is Phong-style: the in-plane direction is interpolated between the vertex
+// directions (each the bisector of its two segments), giving the normal of the
+// smooth canal surface the polyline samples — exact on a straight stretch, and on
+// a sampled curve exact at the samples and continuous between them.
+//
+// The normal is sign-free here (a spine direction); the caller orients it against
+// the facet, which also makes one descriptor serve cutters and fillers alike.
+//
+// Descriptors are registered per Manifold originalID in the tool's ORIGINAL frame
+// (the inverse of the run's runTransform at registration), and evaluated per output
+// run through that run's transform — so they follow every later translate, rotate,
+// boolean and re-stamp that carries runTransform along (Manifold does, verified).
+// Pure module: no DOM, no node:, no three.
+
+const EPS = 1e-12;
+
+// --- 3x4 column-major affine helpers (Manifold's runTransform layout) -------------
+export function affineAt(rt, run) {
+  const o = run * 12;
+  return [rt[o], rt[o + 1], rt[o + 2], rt[o + 3], rt[o + 4], rt[o + 5],
+    rt[o + 6], rt[o + 7], rt[o + 8], rt[o + 9], rt[o + 10], rt[o + 11]];
+}
+export const IDENTITY = Object.freeze([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]);
+const applyPt = (M, p) => [
+  M[0] * p[0] + M[3] * p[1] + M[6] * p[2] + M[9],
+  M[1] * p[0] + M[4] * p[1] + M[7] * p[2] + M[10],
+  M[2] * p[0] + M[5] * p[1] + M[8] * p[2] + M[11],
+];
+const applyDir = (M, d) => [
+  M[0] * d[0] + M[3] * d[1] + M[6] * d[2],
+  M[1] * d[0] + M[4] * d[1] + M[7] * d[2],
+  M[2] * d[0] + M[5] * d[1] + M[8] * d[2],
+];
+// Inverse of an affine; null when singular.
+export function invertAffine(M) {
+  const [a, b, c, d, e, f, g, h, i] = M; // columns (a,b,c) (d,e,f) (g,h,i)
+  const A = e * i - f * h, B = f * g - d * i, C = d * h - e * g;
+  const det = a * A + b * B + c * C;
+  if (!(Math.abs(det) > EPS)) return null;
+  const s = 1 / det;
+  // rows of the inverse = cofactor columns; stored column-major
+  const L = [
+    A * s, (c * h - b * i) * s, (b * f - c * e) * s,
+    B * s, (a * i - c * g) * s, (c * d - a * f) * s,
+    C * s, (b * g - a * h) * s, (a * e - b * d) * s,
+  ];
+  const t = applyDir([...L, 0, 0, 0], [M[9], M[10], M[11]]);
+  return [...L, -t[0], -t[1], -t[2]];
+}
+
+const norm = (v) => {
+  const l = Math.hypot(v[0], v[1], v[2]);
+  return l > EPS ? [v[0] / l, v[1] / l, v[2] / l] : null;
+};
+
+// Map a descriptor through an affine (used with the INVERSE run transform at
+// registration: world → original frame). Exact for rigid maps, which is what the
+// tools are posed with; radii scale by the map's mean axis stretch.
+export function mapSurface(desc, M) {
+  switch (desc.kind) {
+    case "line": return { kind: "line", p: applyPt(M, desc.p), d: norm(applyDir(M, desc.d)) ?? desc.d };
+    case "point": return { kind: "point", c: applyPt(M, desc.c) };
+    case "circle": {
+      const s = Math.cbrt(Math.abs(
+        M[0] * (M[4] * M[8] - M[5] * M[7]) - M[3] * (M[1] * M[8] - M[2] * M[7]) + M[6] * (M[1] * M[5] - M[2] * M[4])));
+      return { kind: "circle", c: applyPt(M, desc.c), a: norm(applyDir(M, desc.a)) ?? desc.a, R: desc.R * s };
+    }
+    case "path": {
+      const s = Math.cbrt(Math.abs(
+        M[0] * (M[4] * M[8] - M[5] * M[7]) - M[3] * (M[1] * M[8] - M[2] * M[7]) + M[6] * (M[1] * M[5] - M[2] * M[4])));
+      return { kind: "path", closed: desc.closed, pts: desc.pts.map((p) => applyPt(M, p)),
+        dirs: desc.dirs.map((d) => norm(applyDir(M, d)) ?? d), f: norm(applyDir(M, desc.f)) ?? desc.f,
+        kf: desc.kf * s, kd: desc.kd * s };
+    }
+    default: throw new Error(`blend surface: unknown kind ${desc.kind}`);
+  }
+}
+
+// Nearest spine point to x, in the descriptor's own frame.
+function spinePoint(desc, x) {
+  switch (desc.kind) {
+    case "point": return desc.c;
+    case "line": {
+      const { p, d } = desc;
+      const t = (x[0] - p[0]) * d[0] + (x[1] - p[1]) * d[1] + (x[2] - p[2]) * d[2];
+      return [p[0] + t * d[0], p[1] + t * d[1], p[2] + t * d[2]];
+    }
+    case "circle": {
+      const { c, a, R } = desc;
+      const q = [x[0] - c[0], x[1] - c[1], x[2] - c[2]];
+      const t = q[0] * a[0] + q[1] * a[1] + q[2] * a[2];
+      const rad = norm([q[0] - t * a[0], q[1] - t * a[1], q[2] - t * a[2]]);
+      if (!rad) return R > 0 ? null : c; // on the axis: the normal is undefined unless the spine is a point
+      return [c[0] + R * rad[0], c[1] + R * rad[1], c[2] + R * rad[2]];
+    }
+    default: return null;
+  }
+}
+
+// Path normal (see the header): nearest edge segment i at parameter t, the in-plane
+// direction lerped between its vertex directions, the ball centre offset along it,
+// and the normal rebuilt from x's height above the centre (along f) and its signed
+// in-plane distance across the segment.
+function pathNormal(desc, x) {
+  const { pts, dirs, f, kf, kd } = desc;
+  const n = pts.length;
+  const { bi, bt } = nearestSegment(desc, x);
+  if (bi < 0) return null;
+  const p = pts[bi], q = pts[(bi + 1) % n], d0 = dirs[bi], d1 = dirs[(bi + 1) % n];
+  const dir = norm([d0[0] + (d1[0] - d0[0]) * bt, d0[1] + (d1[1] - d0[1]) * bt, d0[2] + (d1[2] - d0[2]) * bt]);
+  if (!dir) return null;
+  const e = [p[0] + (q[0] - p[0]) * bt, p[1] + (q[1] - p[1]) * bt, p[2] + (q[2] - p[2]) * bt];
+  const c = [e[0] + kf * f[0] + kd * dir[0], e[1] + kf * f[1] + kd * dir[1], e[2] + kf * f[2] + kd * dir[2]];
+  const v = [x[0] - c[0], x[1] - c[1], x[2] - c[2]];
+  const h = v[0] * f[0] + v[1] * f[1] + v[2] * f[2];
+  // signed in-plane distance across the SEGMENT (the local surface's own measure)
+  const segN = norm([q[0] - p[0], q[1] - p[1], q[2] - p[2]]);
+  const perp = segN ? norm([f[1] * segN[2] - f[2] * segN[1], f[2] * segN[0] - f[0] * segN[2], f[0] * segN[1] - f[1] * segN[0]]) : null;
+  if (!perp) return null;
+  const sgn = perp[0] * dir[0] + perp[1] * dir[1] + perp[2] * dir[2] >= 0 ? 1 : -1;
+  const w = sgn * (v[0] * perp[0] + v[1] * perp[1] + v[2] * perp[2]);
+  return norm([h * f[0] + w * dir[0], h * f[1] + w * dir[1], h * f[2] + w * dir[2]]);
+}
+
+// Nearest path segment to x (index + clamped parameter). A text rim's path runs to
+// hundreds of segments and every band vertex asks, so the segments are bucketed
+// once per descriptor into a uniform grid (lazily, off the enumerable fields) and
+// the query widens ring by ring only until no unvisited cell can hold a closer one.
+// squared distance from x to segment pq; the clamped parameter lands in segT
+let segT = 0;
+function segDist2(p, q, x) {
+  const dx = q[0] - p[0], dy = q[1] - p[1], dz = q[2] - p[2];
+  const dd = dx * dx + dy * dy + dz * dz;
+  let t = dd > EPS ? ((x[0] - p[0]) * dx + (x[1] - p[1]) * dy + (x[2] - p[2]) * dz) / dd : 0;
+  t = t < 0 ? 0 : t > 1 ? 1 : t;
+  segT = t;
+  return (x[0] - p[0] - t * dx) ** 2 + (x[1] - p[1] - t * dy) ** 2 + (x[2] - p[2] - t * dz) ** 2;
+}
+const GRID_MIN_SEGS = 16;
+function segmentGrid(desc) {
+  let g = desc[GRID];
+  if (g) return g;
+  const { pts, closed } = desc, n = pts.length, nSeg = closed ? n : n - 1;
+  let total = 0;
+  for (let i = 0; i < nSeg; i++) { const p = pts[i], q = pts[(i + 1) % n]; total += Math.hypot(q[0] - p[0], q[1] - p[1], q[2] - p[2]); }
+  const h = Math.max(total / Math.max(1, nSeg), Math.abs(desc.kf) + Math.abs(desc.kd), 1e-6);
+  const cells = new Map();
+  // numeric hashed cell keys: a collision only adds candidates, each distance-checked
+  const key = (a, b, c) => (Math.imul(a, 73856093) ^ Math.imul(b, 19349663) ^ Math.imul(c, 83492791)) | 0;
+  for (let i = 0; i < nSeg; i++) {
+    const p = pts[i], q = pts[(i + 1) % n];
+    const lo = [0, 1, 2].map((a) => Math.floor(Math.min(p[a], q[a]) / h));
+    const hi = [0, 1, 2].map((a) => Math.floor(Math.max(p[a], q[a]) / h));
+    for (let a = lo[0]; a <= hi[0]; a++) for (let b = lo[1]; b <= hi[1]; b++) for (let c = lo[2]; c <= hi[2]; c++) {
+      const k = key(a, b, c);
+      const list = cells.get(k);
+      if (list) list.push(i); else cells.set(k, [i]);
+    }
+  }
+  g = { h, cells, key, nSeg, stamp: new Uint32Array(nSeg), epoch: 0 };
+  Object.defineProperty(desc, GRID, { value: g, enumerable: false });
+  return g;
+}
+const GRID = Symbol("segmentGrid");
+function nearestSegment(desc, x) {
+  const { pts, closed } = desc, n = pts.length, nSeg = closed ? n : n - 1;
+  let bi = -1, bt = 0, bestD = Infinity;
+  if (nSeg < GRID_MIN_SEGS) {
+    for (let i = 0; i < nSeg; i++) {
+      const D = segDist2(pts[i], pts[(i + 1) % n], x);
+      if (D < bestD) { bestD = D; bi = i; bt = segT; }
+    }
+    return { bi, bt };
+  }
+  const g = segmentGrid(desc), { h, cells, key, stamp } = g;
+  const epoch = ++g.epoch;
+  const c0 = Math.floor(x[0] / h), c1 = Math.floor(x[1] / h), c2 = Math.floor(x[2] / h);
+  for (let ring = 0; ; ring++) {
+    // every cell at Chebyshev distance `ring`; its points lie ≥ (ring-1)·h away
+    if (bi >= 0 && (ring - 1) * h > Math.sqrt(bestD)) break;
+    let any = false;
+    for (let a = -ring; a <= ring; a++) for (let b = -ring; b <= ring; b++) for (let c = -ring; c <= ring; c++) {
+      if (Math.max(Math.abs(a), Math.abs(b), Math.abs(c)) !== ring) continue;
+      const list = cells.get(key(c0 + a, c1 + b, c2 + c));
+      if (!list) continue;
+      any = true;
+      for (const i of list) {
+        if (stamp[i] === epoch) continue;
+        stamp[i] = epoch;
+        const D = segDist2(pts[i], pts[(i + 1) % n], x);
+        if (D < bestD) { bestD = D; bi = i; bt = segT; }
+      }
+    }
+    // h ≥ the ball-centre offset, so a band point finds its segment within a ring or
+    // two; a point this far from the path is not on the band — scan and be done
+    if (!any && bi < 0 && ring >= 3) {
+      for (let i = 0; i < nSeg; i++) {
+        const D = segDist2(pts[i], pts[(i + 1) % n], x);
+        if (D < bestD) { bestD = D; bi = i; bt = segT; }
+      }
+      break;
+    }
+  }
+  return { bi, bt };
+}
+
+// Unit spine→point direction at x in the descriptor's frame, or null where undefined.
+export function surfaceNormal(desc, x) {
+  if (desc.kind === "path") return pathNormal(desc, x);
+  const s = spinePoint(desc, x);
+  return s ? norm([x[0] - s[0], x[1] - s[1], x[2] - s[2]]) : null;
+}
+
+// Per-run evaluator for creased-normals: world-frame analytic normal at world point
+// x for a run whose original-frame descriptor is `desc` and whose runTransform is M.
+// Normals map by the inverse-transpose of M's linear part, so this stays exact under
+// any affine a part applies after the fillet (mirrors, non-uniform scales).
+export function runEvaluator(desc, M) {
+  const inv = invertAffine(M);
+  if (!inv) return null;
+  return (x) => {
+    const n0 = surfaceNormal(desc, applyPt(inv, x));
+    if (!n0) return null;
+    // (M^-1)^T n0: the inverse's COLUMNS dotted with n0
+    return norm([
+      inv[0] * n0[0] + inv[1] * n0[1] + inv[2] * n0[2],
+      inv[3] * n0[0] + inv[4] * n0[1] + inv[5] * n0[2],
+      inv[6] * n0[0] + inv[7] * n0[1] + inv[8] * n0[2],
+    ]);
+  };
+}

package/src/framework/geometry/creased-normals.js

@@ -8,12 +8,30 @@
 // near-tangent), and a surface's own sharp edges stay crisp too. Each original
 // surface may carry a shading policy (shading-policy.js); surfaces without one
 // use SMOOTH, which reproduces the pre-policy behavior exactly.
+//
+// Analytic blend normals: a surface id with a registered blend-surface descriptor
+// (`surfaces`, blend-surfaces.js — mesh fillet bands) shades with the EXACT normal of
+// its rolling-ball surface instead of a facet average. Wherever such a surface takes
+// part in a vertex's smooth group, the group's normal is the average of the analytic
+// normals alone: at a band's tangent boundary that is the neighbouring face's own
+// normal (the surfaces meet with zero angle), so the face side of the seam, the band
+// side, and any band vertex riding a face edge as a T-junction all agree.
 import { SMOOTH, COPLANAR_ANGLE, MIN_EDGE, MIN_FACE, cosDeg } from "./shading-policy.js";
+import { affineAt, IDENTITY, runEvaluator } from "./blend-surfaces.js";
 
 const COPLANAR_COS = cosDeg(COPLANAR_ANGLE);
 const MIN_EDGE2 = MIN_EDGE * MIN_EDGE;
+// A descriptor's normal is trusted on a triangle only while it stays within this of
+// the facet: a blend facet spans at most 30° of arc (blendSegs' floor of 12), so its
+// normal is ≤15° from any of its vertices' — anything further is a tool face that is
+// NOT the blend wall (a filler's flush end cap, a cutter's closing wall).
+const ANALYTIC_COS = cosDeg(25);
+// Shading-adjacency weld radius (mm): far below anything visible, above the boolean's
+// nanometre seam splits (see the weld below).
+const SHADE_WELD = 5e-5;
+const SHADE_CELL = 1e-3; // its hash-grid cell
 
-export function creasedNormals(g, { policies = null, featureLabels = null } = {}) {
+export function creasedNormals(g, { policies = null, featureLabels = null, surfaces = null } = {}) {
   const np = g.numProp, vp = g.vertProperties, tris = g.triVerts;
   const nTri = (tris.length / 3) | 0, nVert = (vp.length / np) | 0;
 
@@ -38,6 +56,43 @@ export function creasedNormals(g, { policies = null, featureLabels = null } = {}
   for (let r = 0; r < roid.length; r++)
     for (let t = ri[r] / 3; t < ri[r + 1] / 3; t++) triOID[t] = roid[r];
 
+  // per-run analytic evaluators (only runs whose surface id has a descriptor), and
+  // each triangle's run — evaluated lazily, memoized per (run, vertex)
+  let triRun = null, runEval = null;
+  if (surfaces?.size) {
+    const rt = g.runTransform;
+    runEval = new Array(roid.length).fill(null);
+    let any = false;
+    for (let r = 0; r < roid.length; r++) {
+      const desc = surfaces.get(roid[r]);
+      if (!desc) continue;
+      runEval[r] = runEvaluator(desc, rt && rt.length >= (r + 1) * 12 ? affineAt(rt, r) : IDENTITY);
+      any ||= !!runEval[r];
+    }
+    if (any) {
+      triRun = new Uint32Array(nTri);
+      for (let r = 0; r < roid.length; r++)
+        for (let t = ri[r] / 3; t < ri[r + 1] / 3; t++) triRun[t] = r;
+    } else runEval = null;
+  }
+  const analyticMemo = new Map();
+  // analytic normal of triangle t at vertex v, oriented with the facet — or null
+  const analyticAt = (t, v) => {
+    const r = triRun[t], ev = runEval[r];
+    if (!ev) return null;
+    const key = r * nVert + v;
+    let n = analyticMemo.get(key);
+    if (n === undefined) {
+      const o = v * np;
+      n = ev([vp[o], vp[o + 1], vp[o + 2]]);
+      analyticMemo.set(key, n);
+    }
+    if (!n) return null;
+    const d = n[0] * fn[t * 3] + n[1] * fn[t * 3 + 1] + n[2] * fn[t * 3 + 2];
+    if (Math.abs(d) < ANALYTIC_COS) return null;
+    return d < 0 ? [-n[0], -n[1], -n[2]] : n;
+  };
+
   // per-triangle face normals, plus each triangle's minimum height (2·area /
   // longest edge) — the "thinness" the feature-edge pass gates on below
   const fn = new Float32Array(nTri * 3);
@@ -69,14 +124,40 @@ export function creasedNormals(g, { policies = null, featureLabels = null } = {}
   // pass below deliberately keeps `remap` (Manifold's own topology): welding
   // its edge keys would make pairing at collapsed seams order-dependent and
   // could pair a boundary ring's edges away.
+  //
+  // The join is within SHADE_WELD, not float-exact: a seam where a fillet band meets
+  // a curved flank comes out of the boolean as two or three vertex columns a few
+  // NANOmetres apart (measured 0.5-4 nm on a cylinder rim fillet), so an exact key
+  // left the flank's rim vertices shading on their own facet while the band beside
+  // them shaded smooth — a ~1.5° lighting step along every rim, which mirror-like
+  // materials show as a seam.
   const weld = Uint32Array.from(remap);
   {
-    const byPos = new Map();
+    // cells SHADE_CELL wide (≫ SHADE_WELD), so a vertex probes a neighbor cell only
+    // on the axes where it sits within SHADE_WELD of the cell wall — one lookup for
+    // almost every vertex. Numeric hashed keys; a collision only adds candidates,
+    // and every candidate is distance-checked.
+    const inv = 1 / SHADE_CELL, edge = SHADE_WELD / SHADE_CELL, tol2 = SHADE_WELD * SHADE_WELD;
+    const cells = new Map();
+    const hash = (x, y, z) => (Math.imul(x, 73856093) ^ Math.imul(y, 19349663) ^ Math.imul(z, 83492791)) | 0;
+    const offs = (f) => (f < edge ? [0, -1] : f > 1 - edge ? [0, 1] : [0]);
     for (let i = 0; i < nVert; i++) {
-      const o = i * np;
-      const key = `${vp[o]}|${vp[o + 1]}|${vp[o + 2]}`;
-      const first = byPos.get(key);
-      if (first === undefined) byPos.set(key, weld[i]); else weld[i] = first;
+      const o = i * np, x = vp[o], y = vp[o + 1], z = vp[o + 2];
+      const fx = x * inv, fy = y * inv, fz = z * inv;
+      const cx = Math.floor(fx), cy = Math.floor(fy), cz = Math.floor(fz);
+      let hit = -1;
+      search: for (const dx of offs(fx - cx)) for (const dy of offs(fy - cy)) for (const dz of offs(fz - cz)) {
+        const reps = cells.get(hash(cx + dx, cy + dy, cz + dz));
+        if (!reps) continue;
+        for (const j of reps) {
+          const q = j * np;
+          if ((vp[q] - x) ** 2 + (vp[q + 1] - y) ** 2 + (vp[q + 2] - z) ** 2 <= tol2) { hit = j; break search; }
+        }
+      }
+      if (hit >= 0) { weld[i] = weld[hit]; continue; }
+      const key = hash(cx, cy, cz);
+      const reps = cells.get(key);
+      if (reps) reps.push(i); else cells.set(key, [i]);
     }
   }
 
@@ -89,14 +170,42 @@ export function creasedNormals(g, { policies = null, featureLabels = null } = {}
       if (arr) arr.push(t); else incident.set(cv, [t]);
     }
 
+  // Micro-ledges. Where two independently tessellated blend surfaces meet — a
+  // corner sphere octant against its edge cylinders, buried a hair on purpose (see
+  // mesh-fillet's cornerPatches) — the boolean leaves a step a few µm tall whose
+  // triangles face 90° off the band. Sub-visible as geometry, but shaded with their
+  // own facet they draw a bright/dark hairline around every fillet corner on a
+  // mirror material. A triangle thinner than MIN_FACE cannot show a crease of its
+  // own (the line pass drops it for the same reason), so one that touches a blend
+  // takes the band's analytic normal at each corner, crease and surface filters
+  // notwithstanding.
+  const ledgeNormal = (v) => {
+    let ax = 0, ay = 0, az = 0, any = false;
+    for (const t2 of incident.get(weld[v])) {
+      if (thin[t2] < MIN_FACE) continue;
+      const an = analyticAt(t2, weld[v]);
+      if (an) { ax += an[0]; ay += an[1]; az += an[2]; any = true; }
+    }
+    const L = Math.hypot(ax, ay, az);
+    return any && L > 1e-9 ? [ax / L, ay / L, az / L] : null;
+  };
+
   const positions = new Float32Array(nTri * 9);
   const normals = new Float32Array(nTri * 9);
   for (let t = 0; t < nTri; t++) {
     const fx = fn[t * 3], fy = fn[t * 3 + 1], fz = fn[t * 3 + 2], oid = triOID[t];
     const sharpCos = cosFor(oid); // per-surface crease threshold
+    const ledge = runEval && thin[t] < MIN_FACE;
     for (let k = 0; k < 3; k++) {
       const v = tris[t * 3 + k];
-      let nx = 0, ny = 0, nz = 0;
+      const ln = ledge ? ledgeNormal(v) : null;
+      if (ln) {
+        const o = (t * 3 + k) * 3, vv = v * np;
+        positions[o] = vp[vv]; positions[o + 1] = vp[vv + 1]; positions[o + 2] = vp[vv + 2];
+        normals[o] = ln[0]; normals[o + 1] = ln[1]; normals[o + 2] = ln[2];
+        continue;
+      }
+      let nx = 0, ny = 0, nz = 0, ax = 0, ay = 0, az = 0, analytic = false;
       for (const t2 of incident.get(weld[v])) {
         // different cut surface → hard, EXCEPT when a blend surface (boundaryLines)
         // is involved on either side. Blend↔blend: one band is many tool surfaces
@@ -112,7 +221,12 @@ export function creasedNormals(g, { policies = null, featureLabels = null } = {}
           !(polFor(triOID[t2]).boundaryLines || polFor(oid).boundaryLines)) continue;
         if (fn[t2 * 3] * fx + fn[t2 * 3 + 1] * fy + fn[t2 * 3 + 2] * fz < sharpCos) continue; // sharp same-surface edge → hard
         nx += fn[t2 * 3]; ny += fn[t2 * 3 + 1]; nz += fn[t2 * 3 + 2];
+        if (runEval) {
+          const an = analyticAt(t2, weld[v]);
+          if (an) { ax += an[0]; ay += an[1]; az += an[2]; analytic = true; }
+        }
       }
+      if (analytic && Math.hypot(ax, ay, az) > 1e-9) { nx = ax; ny = ay; nz = az; }
       const L = Math.hypot(nx, ny, nz) || 1;
       const o = (t * 3 + k) * 3, vv = v * np;
       positions[o] = vp[vv]; positions[o + 1] = vp[vv + 1]; positions[o + 2] = vp[vv + 2];

package/src/framework/geometry/manifold-backend.js

@@ -18,6 +18,7 @@ import { meshToStl } from "./mesh-stl.js";
 import { creasedNormals } from "./creased-normals.js";
 import { loftShadingPolicy, SMOOTH, BLEND } from "./shading-policy.js";
 import { meshFillet, meshChamfer, UnsupportedEdgeError } from "./mesh-fillet.js";
+import { affineAt, invertAffine, mapSurface } from "./blend-surfaces.js";
 import { meshRoundAll, prismSection, roundAllSegs } from "./mesh-roundall.js";
 import { SEGS, circleSegs, doubleCurvatureSegs } from "./circle-segs.js";
 import { checkBooleanResult } from "./boolean-gate.js";
@@ -137,6 +138,11 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   };
   const featureLabels = new Map(); // originalID -> label string (grows per label(); tiny)
   const oidPolicies = new Map();   // originalID -> shading policy (grows per faceted/hinted loft; tiny)
+  // originalID -> analytic blend-surface descriptor in that original's own frame
+  // (blend-surfaces.js; registered by mesh-fillet's tools through _markBlendSurface).
+  // Keyed on geometry, not on use: a cached tool reused elsewhere IS that surface, so
+  // the entry is true wherever the id shows up. Grows per fillet tool, like oidPolicies.
+  const blendSurfaces = new Map();
   // name -> { m, digest, hash } | { error, digest } — imported geometry the framework
   // registers pre-build (ensureImports, Task 8). Kernel-lifetime, NOT tracked/T()'d:
   // these masters must survive cleanup() and be read again on every subsequent build.
@@ -216,7 +222,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   // transient mesh handle.
   function meshOut(m, asStl) {
     const g = m.getMesh();
-    const r = asStl ? stlFromMesh(g) : creasedNormals(g, { policies: oidPolicies, featureLabels });
+    const r = asStl ? stlFromMesh(g) : creasedNormals(g, { policies: oidPolicies, featureLabels, surfaces: blendSurfaces });
     g.delete?.();
     return r;
   }
@@ -282,6 +288,23 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   // mesh-fillet-perf.test.js. Shading is unchanged (BLEND shades like SMOOTH), and
   // label() on a blend result already handles a mixed-original mesh (the majority
   // vote below).
+  // Fresh ids for a blend-aware re-stamp (label(), the roundAll decouple): ONE base id
+  // for every non-blend run, and one fresh id PER blend surface — each keeps its BLEND
+  // policy and its analytic descriptor (runTransform rides through the MeshGL
+  // round-trip, so the descriptor's original frame stays valid). Folding the band
+  // into a single blend id, as this used to, lost every descriptor with it: a labeled
+  // fillet shaded with facet normals again.
+  const reserveBlendRestamp = (oids) => {
+    const blends = [...oids].filter((oid) => !!oidPolicies.get(oid)?.boundaryLines);
+    const baseId = Manifold.reserveIDs(1 + blends.length);
+    const blendIdFor = new Map(blends.map((oid, i) => [oid, baseId + 1 + i]));
+    for (const [oid, id2] of blendIdFor) {
+      oidPolicies.set(id2, BLEND);
+      const surf = blendSurfaces.get(oid);
+      if (surf) blendSurfaces.set(id2, surf);
+    }
+    return { baseId, blendIdFor, blendIds: [...blendIdFor.values()] };
+  };
   const runOids = (mm) => { const g = mm.getMesh(); const s = new Set(g.runOriginalID); g.delete?.(); return s; };
   const meshCadOp = (op, baseM, run) => {
     try {
@@ -373,16 +396,16 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
         // folded blend and base into one fresh surface, erasing the distinction
         // the band-boundary lines need — a roundAll'd prism rendered with no
         // feature lines at all, unlike the identical geometry from fillet().
-        // Re-stamp as two reserved ids instead (base stays unregistered → SMOOTH,
-        // the extruded section has no policy of its own) so the result draws
-        // exactly the lines the fillet drew.
+        // Re-stamp onto fresh reserved ids instead — one base id (unregistered →
+        // SMOOTH, the extruded section has no policy of its own) and one per blend
+        // surface (reserveBlendRestamp) — so the result draws exactly the lines, and
+        // shades with exactly the normals, the fillet did.
         const g0 = filleted._m.getMesh();
         try {
           const isBlend = (oid) => !!oidPolicies.get(oid)?.boundaryLines;
           if (![...new Set(g0.runOriginalID)].some(isBlend)) return T(filleted._m.asOriginal());
-          const baseId = Manifold.reserveIDs(2), blendId = baseId + 1;
-          g0.runOriginalID = Uint32Array.from(g0.runOriginalID, (o) => (isBlend(o) ? blendId : baseId));
-          oidPolicies.set(blendId, BLEND);
+          const { baseId, blendIdFor } = reserveBlendRestamp(new Set(g0.runOriginalID));
+          g0.runOriginalID = Uint32Array.from(g0.runOriginalID, (o) => (isBlend(o) ? blendIdFor.get(o) : baseId));
           // The constructor re-welds, and that can pinch a latent sliver off a
           // component as fresh femto-debris (the same rebirth dropDebris's own
           // compose() loop guards against) — sweep the reconstruction too.
@@ -507,8 +530,10 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
         // Blend-aware re-stamp. If this mesh carries blend surfaces (the boundaryLines
         // policy), one asOriginal() would fold band and base into a single surface and
         // erase the band-boundary overlay on exactly the solids parts label — every
-        // real part labels its top-level solids. Re-stamp as TWO reserved ids instead,
-        // base and blend: the label covers both (same string → one feature entry), the
+        // real part labels its top-level solids. Re-stamp onto fresh reserved ids
+        // instead, one base id and one per blend surface (reserveBlendRestamp, which
+        // also carries each band's analytic normals): the label covers all of them
+        // (same string → one feature entry), the
         // distinction survives labeling and every later boolean, and reserved ids are
         // fresh so cached-solid reuse under another label cannot collide — the same
         // guarantee asOriginal() gives the plain path below.
@@ -544,7 +569,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
           } };
         }
         if ([...oids0].some(isBlend)) {
-          const baseId = Manifold.reserveIDs(2), blendId = baseId + 1;
+          const { baseId, blendIdFor, blendIds } = reserveBlendRestamp(oids0);
           // base-group policy: the same triangle-weighted majority vote as the plain
           // path, but over the NON-blend runs only — blend runs would elect BLEND for
           // the base group and flag BOTH sides of every boundary seam, which is
@@ -561,16 +586,15 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
             const better = weight > bestWeight || (weight === bestWeight && !pol.sameSurfaceLines && basePol?.sameSurfaceLines);
             if (better) { bestWeight = weight; basePol = pol; }
           }
-          g0.runOriginalID = Uint32Array.from(roid, (o2) => (isBlend(o2) ? blendId : baseId));
+          g0.runOriginalID = Uint32Array.from(roid, (o2) => (isBlend(o2) ? blendIdFor.get(o2) : baseId));
           const o = T(new Manifold(g0));
           g0.delete?.();
           featureLabels.set(baseId, name);
-          featureLabels.set(blendId, name);
-          oidPolicies.set(blendId, BLEND);
+          for (const id2 of blendIds) featureLabels.set(id2, name);
           if (basePol !== undefined) oidPolicies.set(baseId, basePol);
           return { value: wrap(o, lh), pin: o, dispose: () => {
-            featureLabels.delete(baseId); featureLabels.delete(blendId);
-            oidPolicies.delete(baseId); oidPolicies.delete(blendId);
+            featureLabels.delete(baseId); oidPolicies.delete(baseId);
+            for (const id2 of blendIds) { featureLabels.delete(id2); oidPolicies.delete(id2); blendSurfaces.delete(id2); }
             o.delete?.();
           } };
         }
@@ -839,6 +863,23 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     // is total; errors are lazy"). Re-registering the same name+digest is a no-op
     // EXCEPT an error entry is always upgradable (the post-crossover retry depends
     // on this — see `_importDigest`).
+    // Side-channel for mesh-fillet (underscore = off-contract): `surf` describes the
+    // tool's blend wall in its current frame. Stored per surface id in the id's
+    // ORIGINAL frame (inverse runTransform), so any later pose or boolean — which
+    // carry runTransform along — still evaluates it exactly.
+    _markBlendSurface: (tool, surf) => {
+      const g = tool._m.getMesh();
+      try {
+        const roid = g.runOriginalID, rt = g.runTransform;
+        for (let r = 0; r < roid.length; r++) {
+          const inv = invertAffine(affineAt(rt, r));
+          if (inv) blendSurfaces.set(roid[r], mapSurface(surf, inv));
+        }
+      } finally {
+        g.delete?.();
+      }
+      return tool;
+    },
     _registerImport: ({ name, digest, positions, indices, error }) => {
       const prev = imports.get(name);
       if (!prev?.error && prev?.digest === digest) return; // error entries are always upgradable

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/patterns.js

@@ -193,3 +193,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

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;
 }