partforge 0.121.1 → 0.123.0

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/geometry/threemf.js

@@ -1,6 +1,7 @@
 // Minimal 3MF writer. 3MF is an OPC package (a zip) holding an XML model; it's a
 // mesh format like STL but supports units and multiple named objects in one file,
 // so a multi-part view exports as a single .3mf. Built from indexed meshes.
+// Each object may carry an optional colour (0xRRGGBB).
 import { zipSync, strToU8 } from "fflate";
 
 const CONTENT_TYPES =
@@ -67,16 +68,44 @@ function weld(positions, indices) {
   return { verts, tris };
 }
 
-// parts: [{ name, positions: Float32Array (x,y,z per vertex), indices: Uint32Array (3 per triangle) }]
-// → ArrayBuffer of the .3mf zip (millimetre units; one <object> + <build> item per part).
+// Default for an uncoloured object in an export where some other object IS
+// coloured: the viewer's own default look (presets.js "default"). Written as a
+// literal so this module keeps its fflate-only import closure.
+const DEFAULT_DISPLAY_COLOR = 0x9fb4cc;
+// Base-material group id: outside the object id range (objects are 1..n).
+const BASE_MATERIALS_ID = 1000;
+const hexColor = (c) => `#${c.toString(16).padStart(6, "0").toUpperCase()}FF`;
+
+// parts: [{ name, positions, indices, color? }] → ArrayBuffer of the .3mf zip.
+// `color` (0xRRGGBB) is optional per part. When NO part carries one, the model is
+// byte-for-byte what it was before colour support — no <basematerials>, no pid.
+// When any does, every object points (pid/pindex) into one core-spec
+// <basematerials> group, one <base> per distinct colour, so a slicer opens the
+// file pre-split into coloured objects.
 export function meshTo3MF(parts) {
+  const colored = parts.some((p) => p.color != null);
+  const palette = [];
+  const pindexOf = (c) => {
+    const color = c ?? DEFAULT_DISPLAY_COLOR;
+    let i = palette.indexOf(color);
+    if (i < 0) { i = palette.length; palette.push(color); }
+    return i;
+  };
+  const pindex = colored ? parts.map((p) => pindexOf(p.color)) : [];
+
   const out = [
     '<?xml version="1.0" encoding="UTF-8"?>',
     '<model unit="millimeter" xml:lang="en-US" xmlns="http://schemas.microsoft.com/3dmanufacturing/core/2015/02">',
     "<resources>",
   ];
+  if (colored) {
+    out.push(`<basematerials id="${BASE_MATERIALS_ID}">`);
+    palette.forEach((c, i) => out.push(`<base name="color-${i + 1}" displaycolor="${hexColor(c)}"/>`));
+    out.push("</basematerials>");
+  }
   parts.forEach((p, i) => {
-    out.push(`<object id="${i + 1}" type="model" name="${xmlEsc(p.name)}"><mesh><vertices>`);
+    const mat = colored ? ` pid="${BASE_MATERIALS_ID}" pindex="${pindex[i]}"` : "";
+    out.push(`<object id="${i + 1}" type="model" name="${xmlEsc(p.name)}"${mat}><mesh><vertices>`);
     const { verts: v, tris: t } = weld(p.positions, p.indices);
     for (let k = 0; k < v.length; k += 3) out.push(`<vertex x="${v[k]}" y="${v[k + 1]}" z="${v[k + 2]}"/>`);
     out.push("</vertices><triangles>");

package/src/framework/jobs.js

@@ -3,6 +3,7 @@
 // the oracle and the collision check can share it without importing this async,
 // kernel-bound module back.
 import { meshTo3MF } from "./geometry/threemf.js";
+import { printColor } from "./materials/resolve.js";
 import { exportablePartNames } from "./export-select.js";
 import { fontControlAllows, fontSourceAllowed, isNoFontSource } from "./font-source.js";
 import { fontsFor, resolveFonts } from "./fonts.js";
@@ -449,7 +450,7 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       const meshes = names.map((name) => {
         onProgress(`building ${label(name)}`);
         const { positions, indices } = posed(name, "export", onProgress).toIndexedMesh({ quality: msg.quality ?? "print" });
-        return { name: exportName(name), positions, indices };
+        return { name: exportName(name), positions, indices, color: printColor(part.parts[name]?.display) };
       });
       onProgress("writing 3MF file");
       const data = meshTo3MF(meshes);

package/src/framework/lint/index.js

@@ -20,8 +20,9 @@ import { FONT_RULES } from "./rules-fonts.js";
 import { IMAGE_RULES } from "./rules-images.js";
 import { SOURCE_RULES } from "./rules-source.js";
 import { VECTOR_RULES } from "./rules-vector.js";
+import { MATERIAL_RULES } from "./rules-materials.js";
 
-export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES, ...IMPORT_RULES, ...FONT_RULES, ...IMAGE_RULES, ...SOURCE_RULES, ...VECTOR_RULES];
+export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES, ...IMPORT_RULES, ...FONT_RULES, ...IMAGE_RULES, ...SOURCE_RULES, ...VECTOR_RULES, ...MATERIAL_RULES];
 
 // A usable sources input, or null. Deliberately forgiving: lintPart's callers
 // include hosted paths handing over user/LLM-authored trees, so a malformed

package/src/framework/lint/rules-materials.js

@@ -0,0 +1,56 @@
+// src/framework/lint/rules-materials.js
+// Appearance findings. All WARNINGS by design: a misspelled material must never
+// block geometry, and the viewer already falls back (resolve.js). Pure — imports
+// only the three-free materials data (test/lint-purity.test.js).
+import { warn } from "./finding.js";
+import { PRESETS, DEFAULT_PRESET_ID } from "../materials/presets.js";
+import { ENVIRONMENTS } from "../materials/environments.js";
+import { resolveMaterial, resolveEnvironmentId, OVERRIDE_RANGES } from "../materials/resolve.js";
+import { suggest } from "../geometry/op-options.js";
+
+const listedPresets = () => Object.keys(PRESETS).filter((id) => id !== DEFAULT_PRESET_ID);
+const subParts = (part) => Object.entries(part?.parts ?? {}).filter(([, sp]) => sp && typeof sp === "object");
+const issuesOf = (part, kind) => subParts(part).flatMap(([name, sp]) =>
+  resolveMaterial(sp.display).issues.filter((i) => i.kind === kind).map((i) => ({ name, ...i })));
+
+export const MATERIAL_RULES = [
+  {
+    id: "unknown-material",
+    run: ({ part }) => issuesOf(part, "unknown-material").map(({ name, value }) => {
+      const near = typeof value === "string" ? suggest(value, listedPresets()) : null;
+      return warn("unknown-material",
+        `sub-part "${name}" names material ${JSON.stringify(value)}, which is not in the library`,
+        `${near ? `Did you mean "${near}"? ` : ""}The viewer shows the default look instead. Known materials: ${listedPresets().join(", ")}.`,
+        `parts.${name}.display.material`);
+    }),
+  },
+  {
+    id: "unknown-environment",
+    run: ({ part }) => {
+      const env = part?.meta?.environment;
+      if (resolveEnvironmentId(env).known) return [];
+      return [warn("unknown-environment",
+        `meta.environment ${JSON.stringify(env)} is not a known environment`,
+        `Realistic mode uses "studio" instead. Known environments: ${Object.keys(ENVIRONMENTS).join(", ")}.`,
+        "meta.environment")];
+    },
+  },
+  {
+    id: "material-key-unknown",
+    run: ({ part }) => issuesOf(part, "material-key-unknown").map(({ name, key }) =>
+      warn("material-key-unknown",
+        `sub-part "${name}" display has unknown key "${key}"`,
+        `It is ignored. display accepts color, opacity, material and the overrides ${Object.keys(OVERRIDE_RANGES).join(", ")}; transmission, IOR, sheen and iridescence come only from a preset.`,
+        `parts.${name}.display.${key}`)),
+  },
+  {
+    id: "material-override-clamped",
+    run: ({ part }) => issuesOf(part, "material-override-clamped").map(({ name, key, value, clampedTo }) => {
+      const [lo, hi] = OVERRIDE_RANGES[key];
+      return warn("material-override-clamped",
+        `sub-part "${name}" display.${key} = ${JSON.stringify(value)} is outside ${lo}..${hi}; using ${clampedTo}`,
+        `Give ${key} a number from ${lo} to ${hi}.`,
+        `parts.${name}.display.${key}`);
+    }),
+  },
+];