partforge 0.45.0 → 0.46.2

package/docs/AUTHORING-PARTS.md

@@ -234,7 +234,7 @@ future contract v2 — but are not shown here; see `docs/KERNEL-CONTRACT.md`
 | `k.box({ size, center? })` · `k.box({ min, max })` | `{size:[x,y,z]}` = centered X/Y, base at z=0 (`center:true` also centers Z); `{min,max}` = explicit `[x,y,z]` corners |
 | `k.prism({ points, h, twist?, scaleTop? })` | extrude a 2-D polygon (or an **arc profile** from `roundedProfile`) from z=0; optional `twist` (degrees over the height) and `scaleTop` (uniform top taper: 1 straight, <1 taper in, 0 → point/cone) |
 | `k.extrude({ profile, h, twist?, scaleTop? })` | extrude a **polygon-with-holes** region from z=0 in one op — `profile` is `{ outer, holes? }` where each contour is a points array **or an arc profile** (`roundedProfile`, for true STEP fillets), or a bare points array / arc profile for outer-only; same `twist`/`scaleTop` as `prism` (both backends) |
-| `k.loft({ rings, ruled?, closed? })` | stack polygon cross-sections into a solid — ruled walls between consecutive rings, capped ends (both backends; `closed:true` capless loops are Manifold-only). `ruled:false` (smooth C2 blend) is honoured only by OCCT/STEP export; the Manifold preview always shows faceted straight walls |
+| `k.loft({ rings, ruled?, closed?, shading? })` | stack polygon cross-sections into a solid — ruled walls between consecutive rings, capped ends (both backends; `closed:true` capless loops are Manifold-only). `ruled:false` (smooth C2 blend) is honoured only by OCCT/STEP export; the Manifold preview always shows faceted straight walls. `shading?: "smooth" \| "faceted"` overrides facet/smooth shading inference (default: <32-side rings shade as flat facets, drawing no same-surface lines at all — not even their own cap rims — though cut seams against other solids still draw; ≥32 sides shade smooth) |
 | `k.sweep({ profile, path, cornerRadius?, closed?, ruled?, smooth? })` | sweep a fixed 2-D profile along a 3-D polyline path — sharp mitered corners (or `cornerRadius` fillets), capped ends (both backends). `closed:true` capless loops and `smooth:true` (OCCT-native swept B-rep, STEP-exact / preview-faceted) are backend-specific, like loft's `closed`/`ruled:false`. `closed:true` loops must be **planar** — RMF frame-transport holonomy can seam-twist a non-planar closed loop where the last station rejoins the first, so only planar closed loops are supported/tested |
 | `k.sphere({ r\|d })` | sphere centred at the origin; bare `k.sphere(r)` also stays valid |
 | `k.roundedBox({ size, center?, round })` | box with rounded edges — `round` = number (all edges) or `{ side?, top?, bottom? }` (vertical edges / rims); stays on Manifold (no OCCT routing, unlike `fillet`); `side` must be 0 or ≥ the rim radii (between clamps with a warning); with `side > 0`, `top + bottom` must be strictly `< h` |
@@ -398,6 +398,10 @@ if (p.drain > 0) s = s.cut(k.cylinder({ r: d.drainR, h: p.floor + 4 }).at([0, 0,
   a cutting tool's label lands on the faces it leaves behind (the hole's wall).
 - Label **after** shaping compound tools (e.g. after an `intersect` clip) and
   either before or after transforms — labels ride through `at`/`rotate`/etc.
+  Labeling a compound collapses it to ONE shading surface — the majority
+  policy of its registered surfaces (by triangle count) applies to the whole
+  solid, so a faceted policy also suppresses line-drawing on the compound's
+  internal seams.
 - **Same label merges; distinct siblings need distinct names.** The same label on
   several solids merges into one feature — label a ring of four bolt holes
   `"Mounting holes"` and they hover/highlight as one. Conversely, when two similar
@@ -1411,6 +1415,13 @@ everything else (so sweep-heavy parts, e.g. helical grooves, stay fast). Force i
 `meta.backend: "occt" | "manifold"` if you ever need to. Because an OCCT part is built
 entirely on OCCT, its fillets are exact in the STEP **and** present in the printed STL.
 
+**Shading intent.** The kernel decides what shades smooth and where edge lines
+draw — spheres, cylinders and fillets are smooth by construction; boolean cut
+seams always shade hard and draw a line; a loft's facets shade flat when its
+rings have fewer than 32 sides (`shading: "smooth"|"faceted"` on `k.loft`
+overrides the inference either way). If your part previews smooth but would
+print faceted — or the reverse — set the hint rather than changing facet counts.
+
 > Trade-off: OCCT is much slower on heavy swept geometry (helical grooves), so don't reach for
 > `fillet`/`chamfer` on a sweep-heavy part — design those edges in, or keep the part on Manifold.
 

package/docs/ERROR-PATTERNS.md

@@ -318,6 +318,25 @@ Variant literals under this entry: `offsetPolygon: delta must be a finite number
 - **Cause:** A track drives a param that feeds real geometry (or a build the pose probe can't trust — a query op or function selector), so every frame is a worker rebuild instead of a pose repair.
 - **Fix:** Run `npx partforge lint <part>` — the `animation-track-rebuilds` note names the track. Restructure so the param only feeds rigid placement (`place()` or a trailing translate/rotate in `build`), or accept best-effort playback if geometry morphing is the intent. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Animations".
 
+## phantom-edges-on-curved-surface
+
+- **Symptom:** edge lines or hard-shaded patches appear scattered on a smooth
+  curved surface (a sphere, fillet, or blend) in the viewer or in `render` PNGs.
+- **Cause:** the mesh reached the viewer without kernel `normals`/`edges`, so a
+  consumer fell back to dihedral-angle guessing on coarse preview tessellation.
+- **Fix:** the backend's `toMesh` must return analytic normals and filtered
+  feature edges ([KERNEL-CONTRACT.md](KERNEL-CONTRACT.md) "Shading intent") —
+  fix the backend or payload plumbing; do not tune viewer angle thresholds.
+
+## faceted-loft-previews-smooth
+
+- **Symptom:** an intentionally faceted loft (low-side-count rings) previews
+  smooth-shaded, but exports/prints show flat facets.
+- **Cause:** the loft's shading policy resolved to smooth — a `shading:
+  "smooth"` hint, `ruled: false`, or rings with 32+ sides.
+- **Fix:** pass `shading: "faceted"` to `k.loft` (or drop the smooth-implying
+  option) per [AUTHORING-PARTS.md](AUTHORING-PARTS.md) shading-intent note.
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/docs/KERNEL-CONTRACT.md

@@ -258,7 +258,7 @@ Normative signatures: `kernel.js`'s `@typedef Solid`.
 | `boundingBox()` | `{min, max, center, size}`; `center`/`size` are derived by `addSugar` from the backend's `{min, max}`. |
 | `volume()` | Solid volume in mm³. |
 | `genus()` / `isEmpty()` | Optional (`SOLID_OPTIONAL_OPS`): mesh-topology queries — through-hole count / no-geometry test. The mesh backend provides them; OCCT has no cheap equivalent. |
-| `toMesh({quality?})` | Render mesh: `{positions, normals, indices?, triangles, edges?, featureIds?, features?}`. `indices` optional (a backend may emit soup or indexed); `normals` may be empty (`length 0`) to delegate creasing to the viewer; `edges` (feature-line segments) and the feature fields are optional metadata. |
+| `toMesh({quality?})` | Render mesh: `{positions, normals, indices?, triangles, edges?, featureIds?, features?}`. `indices` optional (a backend may emit soup or indexed); `normals` and `edges` are authoritative shading intent from both backends — see [Shading intent](#shading-intent-tomesh-normals-and-edges) below; `featureIds`/`features` are optional metadata. |
 | `toSTL({quality?})` | `Promise<ArrayBuffer>`, binary STL, outward CCW winding. Stored facet normals may be zero — slicers recompute them (the mesh backend happens to write them). |
 | `toIndexedMesh({quality?})` | `{positions, indices}` indexed mesh (3MF path); defaults to `"print"` like `toSTL`. Coincident vertices need NOT be welded — the 3MF writer welds, because that format reads topology from the indices rather than re-stitching soup by position the way an STL consumer does. |
 | `fillet(r)` · `fillet({r, edges?})` / `chamfer(d)` · `chamfer({d, edges?})` / `shell({t, open})` | B-rep class (core throws `KernelCapabilityError`). Scalar `fillet(3)`/`chamfer(1)` acts on all edges; the options form adds an `edges` selector. `shell` hollows inward, keeping outer dimensions; `open` (face selector) is required. |
@@ -267,6 +267,39 @@ Normative signatures: `kernel.js`'s `@typedef Solid`.
 speed and a backend may bake it at kernel creation (Manifold does). A part must never
 depend on triangle counts, segment counts, or normals being present.
 
+### Shading intent (toMesh normals and edges)
+
+`toMesh` output is the authoritative statement of how a solid SHADES and which
+edges are FEATURE edges — consumers (viewer, CLI renderer) must draw what they
+are given and must not re-derive either from dihedral angles when the fields
+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`).
+- `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)
+  filtered out; Manifold ships policy-gated sharp/seam segments.
+
+`loft` accepts `shading?: "smooth" | "faceted"` to override facet-vs-smooth
+inference: by default, rings with fewer than 32 sides shade as intentional flat
+facets with no same-surface edge lines, while rings with 32+ sides (and
+`ruled: false` lofts) shade smooth. `shading: "smooth"` forces smooth shading;
+`shading: "faceted"` forces facets; any other non-nullish value throws.
+Thresholds live in `src/framework/geometry/shading-policy.js`.
+
+Known limitation: the OCCT backend ignores `shading` — a loft forced to OCCT
+via `meta.backend` draws its facet corner edges as B-rep feature lines. The
+hint is honored on the Manifold path, which is where lofts preview by default.
+
+`label()`ing a compound solid (one spanning more than one original surface)
+collapses it to a single shading surface that inherits the majority policy of
+its registered constituent surfaces, weighted by triangle count. A constituent
+with no registered policy of its own (e.g. a plain boolean tool) still votes,
+as SMOOTH — the policy it actually renders with — and an exact tie resolves to
+the no-lines (faceted) policy.
+
 **Selectors** (`fillet`/`chamfer` `edges` selector, `shell` `open` face selector) are
 declarative objects, criteria AND-combined:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.45.0",
+  "version": "0.46.2",
   "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/brep-edges.js

@@ -0,0 +1,124 @@
+// Filter replicad meshEdges() down to genuinely sharp feature edges using the
+// analytic per-vertex normals from mesh(). A B-rep edge whose adjacent faces
+// meet tangentially (fillet blend boundaries, closed-surface seam lines) is
+// not a visual feature — drop it, so a sphere or fillet never draws phantom
+// lines. Plain arrays in, plain arrays out; no OCCT required (unit-testable).
+//
+// Format facts this relies on (replicad):
+// - mesh() vertices are concatenated per face: boundary points are duplicated,
+//   one copy per adjacent face, each carrying that face's analytic normal, and
+//   edge polyline nodes reuse the exact face-triangulation coordinates — so an
+//   exact-position key connects an edge point to every adjacent face normal.
+// - mesh() also returns `triangles` (flat vertex-index list) and `faceGroups`
+//   ({start,count,faceId} spans into `triangles`, in index units) — every
+//   vertex index belongs to exactly one face, so this gives a vertex→faceId map.
+// - meshEdges().lines is already flat segment PAIRS ((p0,p1),(p1,p2),…);
+//   edgeGroups {start,count} span one B-rep edge, in points (count = 2·segs).
+import { TANGENT_ANGLE, MIN_EDGE, cosDeg } from "./shading-policy.js";
+
+const TANGENT_COS = cosDeg(TANGENT_ANGLE);
+const MIN_EDGE2 = MIN_EDGE * MIN_EDGE;
+
+export function filterBrepEdges(mesh, meshEdges) {
+  const { vertices, normals, triangles = [], faceGroups = [] } = mesh;
+  const { lines, edgeGroups } = meshEdges;
+
+  // vertex index → owning face's id (-1 if unknown/not supplied).
+  const vface = new Int32Array(vertices.length / 3).fill(-1);
+  for (const fg of faceGroups)
+    for (let i = fg.start; i < fg.start + fg.count; i++) vface[triangles[i]] = fg.faceId;
+
+  // exact-position key → [nx, ny, nz, faceId] for every face copy of that vertex
+  const byPos = new Map();
+  for (let i = 0; i + 2 < vertices.length; i += 3) {
+    const key = `${vertices[i]},${vertices[i + 1]},${vertices[i + 2]}`;
+    let arr = byPos.get(key);
+    if (!arr) byPos.set(key, arr = []);
+    arr.push([normals[i], normals[i + 1], normals[i + 2], vface[i / 3]]);
+  }
+
+  // Any pair of entries in `ns` whose normals disagree past TANGENT_COS makes the sample sharp.
+  const disagrees = (ns) => {
+    for (let a = 0; a < ns.length; a++)
+      for (let b = a + 1; b < ns.length; b++) {
+        const dot = ns[a][0] * ns[b][0] + ns[a][1] * ns[b][1] + ns[a][2] * ns[b][2];
+        if (dot < TANGENT_COS) return true;
+      }
+    return false;
+  };
+  const normalsAt = (g, p) => {
+    const o = (g.start + p) * 3;
+    return byPos.get(`${lines[o]},${lines[o + 1]},${lines[o + 2]}`);
+  };
+
+  const out = [];
+  for (const g of edgeGroups) {
+    if (g.count < 2) continue;
+    // Sharp iff a sample sees two adjacent-face normals disagreeing past
+    // TANGENT_COS. A point with fewer than two known normals is inconclusive;
+    // an edge with no conclusive point is KEPT: a spurious line is visible and
+    // debuggable, a missing feature edge is not.
+    let sharp = false, conclusive = false;
+    if (g.count > 2) {
+      // Interior points are free of corner contamination — group ENDPOINTS are
+      // corners that also touch a third face, so skip them here.
+      for (let p = 1; p <= g.count - 2 && !sharp; p++) {
+        const ns = normalsAt(g, p);
+        if (!ns || ns.length < 2) continue;
+        conclusive = true;
+        if (disagrees(ns)) sharp = true;
+      }
+    } else {
+      // No interior points exist — BOTH samples are corners, each possibly
+      // touching its OWN unrelated third face (e.g. a fillet seam's top rim
+      // touches the top cap, its bottom rim touches the bottom cap). Matching
+      // normals BY DIRECTION across the two corners (near-parallel) is unsound:
+      // a non-developable adjacent face's normal can legitimately swing along
+      // the edge, so it fails to "match itself" between corners, while an
+      // unrelated coplanar fragment touching only one corner can spuriously
+      // match — silently reading a genuinely sharp edge as tangent (fail-
+      // invisible, which this module must never do). Key persistence on FACE
+      // IDENTITY instead: the edge's two true adjacent faces are whichever
+      // faceIds are actually present at BOTH corners, independent of how much
+      // their normal varies between the two samples.
+      //
+      // A closed surface's seam ruling (cylinder/cone/bore) has the SAME
+      // faceId on both sides of the seam, so a corner can carry two copies of
+      // one persisting id rather than two distinct ids. Count persistence as a
+      // MULTISET intersection (tally occurrences per corner, sum the min per
+      // shared id) so that case still reaches persisting >= 2, instead of a
+      // Set intersection whose size tops out at 1 for a single repeated id.
+      // This assumes every adjacent face contributes a vertex copy at each
+      // corner it touches (replicad guarantees this); if that ever didn't
+      // hold, a corner could show persistence only against itself and this
+      // could drop a genuinely sharp edge.
+      const n0 = normalsAt(g, 0), n1 = normalsAt(g, 1);
+      if (n0 && n1) {
+        const count0 = new Map();
+        for (const e of n0) if (e[3] !== -1) count0.set(e[3], (count0.get(e[3]) || 0) + 1);
+        const count1 = new Map();
+        for (const e of n1) if (e[3] !== -1) count1.set(e[3], (count1.get(e[3]) || 0) + 1);
+        const sharedIds = new Set();
+        let persisting = 0;
+        for (const [id, c0] of count0) {
+          const c1 = count1.get(id);
+          if (c1) { persisting += Math.min(c0, c1); sharedIds.add(id); }
+        }
+        if (persisting >= 2) {
+          conclusive = true;
+          const atSharedFaces = (ns) => ns.filter((e) => sharedIds.has(e[3]));
+          sharp = disagrees(atSharedFaces(n0)) || disagrees(atSharedFaces(n1));
+        } // else: fewer than 2 confirmed persisting face copies — inconclusive, KEPT
+      } // else: one or both corners have no evidence at all — inconclusive, KEPT (fail-open)
+    }
+    if (conclusive && !sharp) continue; // tangent edge — not a visual feature
+
+    for (let p = 0; p + 1 < g.count; p += 2) { // lines is segment pairs — step 2 points
+      const a = (g.start + p) * 3, b = (g.start + p + 1) * 3;
+      const dx = lines[a] - lines[b], dy = lines[a + 1] - lines[b + 1], dz = lines[a + 2] - lines[b + 2];
+      if (dx * dx + dy * dy + dz * dz < MIN_EDGE2) continue; // degenerate sliver / pole edge
+      out.push(lines[a], lines[a + 1], lines[a + 2], lines[b], lines[b + 1], lines[b + 2]);
+    }
+  }
+  return Float32Array.from(out);
+}

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

@@ -0,0 +1,131 @@
+// Policy-aware crease pass for Manifold meshes — moved out of the backend so it
+// is unit-testable on plain arrays without booting WASM. Builds a non-indexed
+// mesh with normals that are smooth within a single original surface but HARD
+// across boolean-cut seams. Manifold's runOriginalID tells us which input solid
+// each triangle came from; we average a corner's face normals only over
+// incident triangles of the SAME original surface that also meet within that
+// surface's policy creaseAngle — so cut seams stay crisp at any angle (even
+// 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.
+import { SMOOTH, COPLANAR_ANGLE, MIN_EDGE, cosDeg } from "./shading-policy.js";
+
+const COPLANAR_COS = cosDeg(COPLANAR_ANGLE);
+const MIN_EDGE2 = MIN_EDGE * MIN_EDGE;
+
+export function creasedNormals(g, { policies = null, featureLabels = null } = {}) {
+  const np = g.numProp, vp = g.vertProperties, tris = g.triVerts;
+  const nTri = (tris.length / 3) | 0, nVert = (vp.length / np) | 0;
+
+  // per-OID policy lookup with a cached cosine per OID
+  const polFor = (oid) => (policies && policies.get(oid)) || SMOOTH;
+  const cosCache = new Map();
+  const cosFor = (oid) => {
+    let c = cosCache.get(oid);
+    if (c === undefined) { c = cosDeg(polFor(oid).creaseAngle); cosCache.set(oid, c); }
+    return c;
+  };
+
+  // unify any coincident vertices Manifold kept separate, for adjacency
+  const remap = new Uint32Array(nVert);
+  for (let i = 0; i < nVert; i++) remap[i] = i;
+  const mf = g.mergeFromVert, mt = g.mergeToVert;
+  if (mf && mt) for (let i = 0; i < mf.length; i++) remap[mf[i]] = mt[i];
+
+  // per-triangle original-surface id, from the run table
+  const triOID = new Uint32Array(nTri);
+  const ri = g.runIndex, roid = g.runOriginalID;
+  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-triangle face normals
+  const fn = new Float32Array(nTri * 3);
+  for (let t = 0; t < nTri; t++) {
+    const a = tris[t * 3] * np, b = tris[t * 3 + 1] * np, c = tris[t * 3 + 2] * np;
+    const ux = vp[b] - vp[a], uy = vp[b + 1] - vp[a + 1], uz = vp[b + 2] - vp[a + 2];
+    const vx = vp[c] - vp[a], vy = vp[c + 1] - vp[a + 1], vz = vp[c + 2] - vp[a + 2];
+    const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx;
+    const L = Math.hypot(nx, ny, nz) || 1;
+    fn[t * 3] = nx / L; fn[t * 3 + 1] = ny / L; fn[t * 3 + 2] = nz / L;
+  }
+
+  // canonical vertex → incident triangles
+  const incident = new Map();
+  for (let t = 0; t < nTri; t++)
+    for (let k = 0; k < 3; k++) {
+      const cv = remap[tris[t * 3 + k]];
+      const arr = incident.get(cv);
+      if (arr) arr.push(t); else incident.set(cv, [t]);
+    }
+
+  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
+    for (let k = 0; k < 3; k++) {
+      const v = tris[t * 3 + k];
+      let nx = 0, ny = 0, nz = 0;
+      for (const t2 of incident.get(remap[v])) {
+        if (triOID[t2] !== oid) continue; // different cut surface → hard
+        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];
+      }
+      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];
+      normals[o] = nx / L; normals[o + 1] = ny / L; normals[o + 2] = nz / L;
+    }
+  }
+
+  // Feature edge segments for CAD-style edge lines: draw a line where the
+  // surface actually BENDS. Same-surface edges draw per the surface's policy
+  // (sharper than creaseAngle, and only if the policy wants same-surface lines
+  // at all — intentional facets shade flat with no wireframe). Cut seams
+  // (different original surface) draw when they bend more than COPLANAR_ANGLE;
+  // coplanar seams get no line, and curved-surface facets are skipped.
+  const edges = [];
+  const seenEdge = new Map(); // edge key → first incident triangle
+  for (let t = 0; t < nTri; t++)
+    for (let e = 0; e < 3; e++) {
+      const i = remap[tris[t * 3 + e]], j = remap[tris[t * 3 + ((e + 1) % 3)]];
+      if (i === j) continue;
+      const key = i < j ? i * nVert + j : j * nVert + i;
+      const prev = seenEdge.get(key);
+      if (prev === undefined) { seenEdge.set(key, t); continue; }
+      seenEdge.delete(key);
+      const dot = fn[prev * 3] * fn[t * 3] + fn[prev * 3 + 1] * fn[t * 3 + 1] + fn[prev * 3 + 2] * fn[t * 3 + 2];
+      // policy-gated same-surface lines; seam rule unchanged
+      const hard = triOID[prev] === triOID[t]
+        ? polFor(triOID[t]).sameSurfaceLines && dot < cosFor(triOID[t])
+        : dot < COPLANAR_COS;
+      if (hard) {
+        const ai = i * np, bj = j * np;
+        const dx = vp[ai] - vp[bj], dy = vp[ai + 1] - vp[bj + 1], dz = vp[ai + 2] - vp[bj + 2];
+        if (dx * dx + dy * dy + dz * dz >= MIN_EDGE2) // skip degenerate sliver segments (noise)
+          edges.push(vp[ai], vp[ai + 1], vp[ai + 2], vp[bj], vp[bj + 1], vp[bj + 2]);
+      }
+    }
+
+  // Per-triangle feature attribution: map each triangle's original-surface id
+  // through the label registry. Same label string → same feature entry, so a
+  // pattern of solids labeled alike reads as one feature.
+  let featureIds = null, features = null;
+  if (featureLabels?.size) {
+    const indexOf = new Map(); // label string -> 1-based feature index
+    features = [];
+    featureIds = new Uint16Array(nTri);
+    for (let t = 0; t < nTri; t++) {
+      const label = featureLabels.get(triOID[t]);
+      if (label === undefined) continue;
+      let fi = indexOf.get(label);
+      if (fi === undefined) { features.push(label); fi = features.length; indexOf.set(label, fi); }
+      featureIds[t] = fi;
+    }
+    if (features.length === 0) { featureIds = features = null; } // labels exist in the kernel, none in THIS mesh
+  }
+
+  const out = { positions, normals, triangles: nTri, edges: Float32Array.from(edges) }; // mesh non-indexed
+  if (featureIds) { out.featureIds = featureIds; out.features = features; }
+  return out;
+}

package/src/framework/geometry/kernel.js

@@ -76,7 +76,7 @@ export const OCCT_ONLY_OPS = ["fillet", "chamfer", "shell"];
  * @property {(factor:number, center?:number[]) => Solid} scale   uniform scale about center (default origin)
  * @property {() => number} volume                   solid volume in mm³ (both backends; used by collision/overlap tests)
  * @property {(opts?: {quality?: "preview"|"print"}) => {positions:Float32Array, normals:Float32Array, indices?:Uint32Array, triangles:number, edges?:Float32Array}} toMesh
- *           `edges` = feature-edge line segments (Manifold); quality is advisory — the Manifold kernel bakes it at creation
+ *           `normals`/`edges` are authoritative shading intent from both backends — see docs/KERNEL-CONTRACT.md "Shading intent"; quality is advisory — the Manifold kernel bakes it at creation
  * @property {(opts?: {quality?: "preview"|"print"}) => Promise<ArrayBuffer>} toSTL
  * @property {() => {positions:Float32Array, indices:Uint32Array}} toIndexedMesh   indexed mesh, for 3MF
  * @property {(r:number|{r:number,edges?:object}) => Solid} fillet    round edges (OCCT only); fillet(3) or fillet({r,edges}); legacy (r,selector) accepted until v2
@@ -106,7 +106,7 @@ export const OCCT_ONLY_OPS = ["fillet", "chamfer", "shell"];
  * @property {(o:{size?:number[],center?:boolean,min?:number[],max?:number[]}) => Solid} box   {size} = centered X/Y, base z=0 ({center:true} centers Z too) or {min,max}; legacy (min,max) accepted until v2
  * @property {(o:{points:number[][],h:number,twist?:number,scaleTop?:number}) => Solid} prism   extrude polygon from z=0; legacy (points,h,opts) accepted until v2
  * @property {(o:{profile:number[][]|{outer:number[][],holes?:number[][][]},h:number,twist?:number,scaleTop?:number,bevel?:number|{bottom?:number,top?:number}}) => Solid} extrude   polygon-with-holes region from z=0; bevel = 45° rim bevel (any profile form incl. Shape2D, materialized to point rings; no twist/scaleTop); legacy (profile,h,opts) accepted until v2
- * @property {(o:{rings:{polygon?:number[][],sides?:number,radius?:number,z:number,rotate?:number,scale?:number|number[]}[],ruled?:boolean,closed?:boolean}) => Solid} loft   stack polygon cross-sections; legacy (rings,opts) accepted until v2
+ * @property {(o:{rings:{polygon?:number[][],sides?:number,radius?:number,z:number,rotate?:number,scale?:number|number[]}[],ruled?:boolean,closed?:boolean,shading?:"smooth"|"faceted"}) => Solid} loft   stack polygon cross-sections; shading overrides facet-vs-smooth shading inference; legacy (rings,opts) accepted until v2
  * @property {(o:{profile:number[][],path:number[][],closed?:boolean,cornerRadius?:number,ruled?:boolean,smooth?:boolean}) => Solid} sweep   sweep a 2-D profile along a 3-D polyline; legacy (profile,path,opts) accepted until v2
  * @property {(o:{profile:number[][],degrees?:number}) => Solid} revolve   revolve a lathe profile [[r,z],…] around Z; legacy (points,opts) accepted until v2
  * @property {(o:{pathR:number,profileR:number,pitch:number,turns:number,z0:number,lefthand:boolean}) => Solid} helixSweptTube

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

@@ -10,15 +10,14 @@ import { addShape2dSugar } from "./shape2d-sugar.js";
 import { assembleRegions } from "./shape2d-regions.js";
 import { finishKernel } from "./kernel-front.js";
 import { meshToStl } from "./mesh-stl.js";
+import { creasedNormals } from "./creased-normals.js";
+import { loftShadingPolicy, SMOOTH } from "./shading-policy.js";
 
 const PLANE_NORMAL = { XY: [0, 0, 1], XZ: [0, 1, 0], YZ: [1, 0, 0] };
 // 'preview' = interactive view (fast); 'print' = STL export (high-res, used only
 // by the export path — Manifold meshing is cheap, so we tessellate generously).
 const SEGS = { preview: 116, print: 480 };       // circular segments
 const TUBE = { preview: { stationsPerTurn: 38, ringSegs: 24 }, print: { stationsPerTurn: 160, ringSegs: 40 } };
-const SHARP_ANGLE = 35; // deg — same-surface edges sharper than this shade hard (cut seams are always hard)
-const COPLANAR_COS = Math.cos((5 * Math.PI) / 180); // edge lines: skip cut seams that bend less than 5° (coplanar)
-const MIN_EDGE2 = 0.01 * 0.01; // edge lines: drop sub-0.01mm segments (degenerate boolean slivers, not real features)
 
 // true axis-angle rotation as a column-major 4x4 (manifold Mat4), translation 0
 function axisAngleMat4(axis, deg) {
@@ -46,6 +45,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
 
   const cache = createSolidCache();
   const featureLabels = new Map(); // originalID -> label string (grows per label(); tiny)
+  const oidPolicies = new Map();   // originalID -> shading policy (grows per faceted/hinted loft; tiny)
   // Boundary ops route through cache.lookup; on a miss `make` runs the WASM op,
   // tracks the result, and returns the triple the cache needs to pin/dispose it.
   const cached = (hash, computeM) => cache.lookup(hash, () => {
@@ -114,7 +114,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, Math.cos((SHARP_ANGLE * Math.PI) / 180), featureLabels);
+    const r = asStl ? stlFromMesh(g) : creasedNormals(g, { policies: oidPolicies, featureLabels });
     g.delete?.();
     return r;
   }
@@ -153,10 +153,56 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     label: (name) => {
       const lh = h("label", hash, name);
       return cache.lookup(lh, () => {
+        const prevId = typeof m.originalID === "function" ? m.originalID() : -1;
         const o = T(m.asOriginal());
         const id = o.originalID();
         featureLabels.set(id, name);
-        return { value: wrap(o, lh), pin: o, dispose: () => { featureLabels.delete(id); o.delete?.(); } };
+        // labeling re-stamps the originalID — carry the surface's shading policy along.
+        // A boolean upstream of this label() (e.g. a faceted loft().intersect(tool),
+        // as the vase does to hollow itself) leaves the solid spanning more than one
+        // original surface, so originalID() reports -1 ("mixed") rather than a single
+        // id — the direct lookup below misses even though the loft's policy is right
+        // there. Fall back to the mesh's own run table and recover it via a
+        // triangle-count-weighted majority vote across all surfaces feeding this
+        // mesh (a plain tool like a box has no registered policy of its own, but
+        // still votes SMOOTH — see below).
+        let inherited = prevId !== -1 ? oidPolicies.get(prevId) : undefined;
+        // Skip the mesh scan entirely when no surface anywhere has a registered
+        // policy (e.g. planter's labeled prism compound) — getMesh() forces a
+        // full mesh materialization and parts with no lofts must not pay for it.
+        if (inherited === undefined && prevId === -1 && oidPolicies.size > 0) {
+          const g = m.getMesh();
+          // Triangle-count-weighted majority: walk the run table with runIndex
+          // (each run r spans triangles ri[r]/3..ri[r+1]/3 — same arithmetic
+          // creased-normals.js uses) and tally triangle counts per registered
+          // policy, keyed by VALUE (creaseAngle/sameSurfaceLines), not object
+          // reference — a majority-by-object-identity check would silently
+          // break if policies were ever constructed per-op instead of shared
+          // singletons. A run whose original surface has NO registered policy
+          // (a plain boolean tool, e.g. a box) still gets a vote: at render
+          // time an unregistered surface shades SMOOTH (buildGeometry's
+          // default), so counting it as an abstention would let the vote
+          // disagree with what's actually drawn — it contributes its triangle
+          // weight to SMOOTH instead. The policy spanning the most triangles
+          // wins; an exact tie favors the FACETED-like policy
+          // (sameSurfaceLines: false) — deterministic, and biased toward
+          // honest-print rendering over silently smoothing facets away.
+          const ri = g.runIndex, roid = g.runOriginalID;
+          const weightByKey = new Map();  // policy key -> triangle count
+          let bestWeight = -1, bestPol;
+          for (let r = 0; r < roid.length; r++) {
+            const pol = oidPolicies.get(roid[r]) ?? SMOOTH;
+            const key = `${pol.creaseAngle}/${pol.sameSurfaceLines}`;
+            const weight = (weightByKey.get(key) || 0) + (ri[r + 1] / 3 - ri[r] / 3);
+            weightByKey.set(key, weight);
+            const better = weight > bestWeight || (weight === bestWeight && !pol.sameSurfaceLines && bestPol?.sameSurfaceLines);
+            if (better) { bestWeight = weight; bestPol = pol; }
+          }
+          g.delete?.();
+          inherited = bestPol;
+        }
+        if (inherited !== undefined) oidPolicies.set(id, inherited);
+        return { value: wrap(o, lh), pin: o, dispose: () => { featureLabels.delete(id); oidPolicies.delete(id); o.delete?.(); } };
       });
     },
     boundingBox: () => {
@@ -240,8 +286,21 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
       });
     },
     // Ring loft: hand-meshed via the shared ring-mesh helpers (helix-tube recipe).
-    // Cached atomically; the hash folds every ring's points/z/rotate/scale and the opts.
-    loft: (rings, opts = {}) => cached(h("loft", rings, opts), () => T(loftMesh(wasm, rings, opts))),
+    // Cached atomically; the hash folds every ring's points/z/rotate/scale and the
+    // opts (including `shading`, so toggling the hint is a fresh cache node).
+    // asOriginal() stamps a stable originalID; the shading policy (inferred from
+    // the rings, or forced by `shading`) registers under it for the crease pass
+    // and lives exactly as long as the cache pins the solid.
+    loft: (rings, opts = {}) => {
+      const key = h("loft", rings, opts);
+      return cache.lookup(key, () => {
+        const raw = T(loftMesh(wasm, rings, opts));
+        const m = T(raw.asOriginal());
+        const id = m.originalID();
+        oidPolicies.set(id, loftShadingPolicy(rings, opts));
+        return { value: wrap(m, key), pin: m, dispose: () => { oidPolicies.delete(id); m.delete?.(); } };
+      });
+    },
     // Sweep a fixed 2-D profile along a 3-D polyline: hand-meshed from the shared station
     // list (sweep.js), so it agrees with OCCT's ruled loft of the same stations by
     // construction. Cached atomically; the hash folds profile pts, path pts, and opts
@@ -253,7 +312,12 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
         return cached(h("revolve", pts._hash, degrees, segs), () => T(pts._cs.revolve(segs, degrees)));
       return cached(h("revolve", pts, degrees, segs), () => T(Manifold.revolve([pts], segs, degrees)));
     },
-    union: (solids) => cached(h("union", solids.map((s) => s._hash)), () => unionRaw(solids.map((s) => s._m))),
+    // A one-solid union is an identity — no new WASM / cache entry (avoids double-free):
+    // unionRaw's reduce returns the operand's own Manifold untouched, so caching it
+    // would pin one WASM object under two entries and eviction would dispose it twice.
+    union: (solids) => solids.length === 1
+      ? solids[0]
+      : cached(h("union", solids.map((s) => s._hash)), () => unionRaw(solids.map((s) => s._m))),
     shape2d,
     beginSubPart: (name) => cache.begin(name),
     endSubPart: () => cache.end(),
@@ -267,114 +331,6 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   return kernel;
 }
 
-// Build a non-indexed mesh with normals that are smooth within a single original
-// surface but HARD across boolean-cut seams. Manifold's runOriginalID tells us
-// which input solid each triangle came from; we average a corner's face normals
-// only over incident triangles of the SAME original surface that also meet within
-// `sharpCos` — so cut seams stay crisp at any angle (even near-tangent), and a
-// surface's own sharp edges (e.g. a face meeting a side) stay crisp too.
-function creasedNormals(g, sharpCos, featureLabels) {
-  const np = g.numProp, vp = g.vertProperties, tris = g.triVerts;
-  const nTri = (tris.length / 3) | 0, nVert = (vp.length / np) | 0;
-
-  // unify any coincident vertices Manifold kept separate, for adjacency
-  const remap = new Uint32Array(nVert);
-  for (let i = 0; i < nVert; i++) remap[i] = i;
-  const mf = g.mergeFromVert, mt = g.mergeToVert;
-  if (mf && mt) for (let i = 0; i < mf.length; i++) remap[mf[i]] = mt[i];
-
-  // per-triangle original-surface id, from the run table
-  const triOID = new Uint32Array(nTri);
-  const ri = g.runIndex, roid = g.runOriginalID;
-  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-triangle face normals
-  const fn = new Float32Array(nTri * 3);
-  for (let t = 0; t < nTri; t++) {
-    const a = tris[t * 3] * np, b = tris[t * 3 + 1] * np, c = tris[t * 3 + 2] * np;
-    const ux = vp[b] - vp[a], uy = vp[b + 1] - vp[a + 1], uz = vp[b + 2] - vp[a + 2];
-    const vx = vp[c] - vp[a], vy = vp[c + 1] - vp[a + 1], vz = vp[c + 2] - vp[a + 2];
-    const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx;
-    const L = Math.hypot(nx, ny, nz) || 1;
-    fn[t * 3] = nx / L; fn[t * 3 + 1] = ny / L; fn[t * 3 + 2] = nz / L;
-  }
-
-  // canonical vertex → incident triangles
-  const incident = new Map();
-  for (let t = 0; t < nTri; t++)
-    for (let k = 0; k < 3; k++) {
-      const cv = remap[tris[t * 3 + k]];
-      const arr = incident.get(cv);
-      if (arr) arr.push(t); else incident.set(cv, [t]);
-    }
-
-  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];
-    for (let k = 0; k < 3; k++) {
-      const v = tris[t * 3 + k];
-      let nx = 0, ny = 0, nz = 0;
-      for (const t2 of incident.get(remap[v])) {
-        if (triOID[t2] !== oid) continue; // different cut surface → hard
-        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];
-      }
-      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];
-      normals[o] = nx / L; normals[o + 1] = ny / L; normals[o + 2] = nz / L;
-    }
-  }
-
-  // Feature edge segments for CAD-style edge lines: draw a line where the surface
-  // actually BENDS — a sharp same-surface edge (dihedral past sharpCos), or a cut
-  // seam (different original surface) that bends more than COPLANAR_COS. Coplanar
-  // faces — even across a cut seam — get no line, and curved-surface facets are skipped.
-  const edges = [];
-  const seenEdge = new Map(); // edge key → first incident triangle
-  for (let t = 0; t < nTri; t++)
-    for (let e = 0; e < 3; e++) {
-      const i = remap[tris[t * 3 + e]], j = remap[tris[t * 3 + ((e + 1) % 3)]];
-      if (i === j) continue;
-      const key = i < j ? i * nVert + j : j * nVert + i;
-      const prev = seenEdge.get(key);
-      if (prev === undefined) { seenEdge.set(key, t); continue; }
-      seenEdge.delete(key);
-      const dot = fn[prev * 3] * fn[t * 3] + fn[prev * 3 + 1] * fn[t * 3 + 1] + fn[prev * 3 + 2] * fn[t * 3 + 2];
-      const hard = dot < sharpCos || (triOID[prev] !== triOID[t] && dot < COPLANAR_COS);
-      if (hard) {
-        const ai = i * np, bj = j * np;
-        const dx = vp[ai] - vp[bj], dy = vp[ai + 1] - vp[bj + 1], dz = vp[ai + 2] - vp[bj + 2];
-        if (dx * dx + dy * dy + dz * dz >= MIN_EDGE2) // skip degenerate sliver segments (noise)
-          edges.push(vp[ai], vp[ai + 1], vp[ai + 2], vp[bj], vp[bj + 1], vp[bj + 2]);
-      }
-    }
-
-  // Per-triangle feature attribution: map each triangle's original-surface id
-  // through the label registry. Same label string → same feature entry, so a
-  // pattern of solids labeled alike reads as one feature.
-  let featureIds = null, features = null;
-  if (featureLabels?.size) {
-    const indexOf = new Map(); // label string -> 1-based feature index
-    features = [];
-    featureIds = new Uint16Array(nTri);
-    for (let t = 0; t < nTri; t++) {
-      const label = featureLabels.get(triOID[t]);
-      if (label === undefined) continue;
-      let fi = indexOf.get(label);
-      if (fi === undefined) { features.push(label); fi = features.length; indexOf.set(label, fi); }
-      featureIds[t] = fi;
-    }
-    if (features.length === 0) { featureIds = features = null; } // labels exist in the kernel, none in THIS mesh
-  }
-
-  const out = { positions, normals, triangles: nTri, edges: Float32Array.from(edges) }; // mesh non-indexed
-  if (featureIds) { out.featureIds = featureIds; out.features = features; }
-  return out;
-}
-
 function stlFromMesh(g) {
   const vp = g.vertProperties, np = g.numProp;
   const nVert = (vp.length / np) | 0;

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

@@ -29,9 +29,10 @@ import { normalizeProfile } from "./profile.js";
 import { roundedRectContour } from "./rounded-solids.js";
 import { h } from "./solid-hash.js";
 import { createSolidCache } from "./solid-cache.js";
-import { composePose, transformPositions } from "./pose.js";
+import { composePose, transformPositions, rotateNormals } from "./pose.js";
+import { filterBrepEdges } from "./brep-edges.js";
 import { meshToStl } from "./mesh-stl.js";
-const MESH = { preview: { tolerance: 0.1, angularTolerance: 0.5 }, print: { tolerance: 0.01, angularTolerance: 0.1 } };
+const MESH = { preview: { tolerance: 0.1, angularTolerance: 0.25 }, print: { tolerance: 0.01, angularTolerance: 0.1 } };
 
 export function createOcctKernel(replicad) {
   const { makeCylinder, makeBox, makeCircle, makeHelix, assembleWire, genericSweep,
@@ -87,6 +88,8 @@ export function createOcctKernel(replicad) {
       const m = shape.mesh(MESH[quality]);
       const out = {
         positions: Float32Array.from(m.vertices),
+        normals: Float32Array.from(m.normals),   // analytic per-face-vertex normals — smooth by construction
+        edges: filterBrepEdges(m, shape.meshEdges(MESH[quality])), // true B-rep edges, tangent-filtered
         indices: Uint32Array.from(m.triangles),
         triangles: m.triangles.length / 3,
       };
@@ -106,6 +109,16 @@ export function createOcctKernel(replicad) {
       if (pose.length) transformPositions(positions, composePose(pose));
       return positions;
     };
+    const posedNormals = (base) => {
+      const normals = Float32Array.from(base.normals);
+      if (pose.length) rotateNormals(normals, composePose(pose)); // rotation only — normals are directions
+      return normals;
+    };
+    const posedEdges = (base) => {
+      const edges = Float32Array.from(base.edges);
+      if (pose.length) transformPositions(edges, composePose(pose)); // segment endpoints pose like positions
+      return edges;
+    };
 
     const self = addSugar({
       _s: shape,
@@ -179,7 +192,8 @@ export function createOcctKernel(replicad) {
         const base = baseMesh(quality);
         const out = {
           positions: posedPositions(base),
-          normals: new Float32Array(0), // let the main thread crease (matches prior look)
+          normals: posedNormals(base), // analytic — the viewer must NOT re-crease these
+          edges: posedEdges(base),     // empty array = "no feature edges", not "unknown"
           indices: Uint32Array.from(base.indices),
           triangles: base.triangles,
         };

package/src/framework/geometry/op-options.js

@@ -116,8 +116,8 @@ export function revolveArgs(o) {
 }
 
 export function loftArgs(o) {
-  checkKeys("loft", o, ["rings", "ruled", "closed"]);
-  return [req("loft", o, "rings"), ...tail(o, ["ruled", "closed"])];
+  checkKeys("loft", o, ["rings", "ruled", "closed", "shading"]);
+  return [req("loft", o, "rings"), ...tail(o, ["ruled", "closed", "shading"])];
 }
 
 export function sweepArgs(o) {

package/src/framework/geometry/pose.js

@@ -77,3 +77,16 @@ export const poseDelta = (newSteps, oldSteps) => {
   const inv = invertRigid(composePose(oldSteps));
   return mulMat4(target, inv);
 };
+
+// Apply ONLY the rotation block of a rigid mat4 to interleaved xyz normals, in
+// place. composePose matrices are rigid (orthonormal 3x3 block), so normals
+// transform by the same block — no inverse-transpose — and stay unit length.
+// Translation columns are deliberately ignored: normals are directions.
+export function rotateNormals(normals, m) {
+  for (let i = 0; i < normals.length; i += 3) {
+    const x = normals[i], y = normals[i + 1], z = normals[i + 2];
+    normals[i] = m[0] * x + m[4] * y + m[8] * z;
+    normals[i + 1] = m[1] * x + m[5] * y + m[9] * z;
+    normals[i + 2] = m[2] * x + m[6] * y + m[10] * z;
+  }
+}

package/src/framework/geometry/rim-bevel.js

@@ -102,17 +102,24 @@ const bevelRegion = (k, region, h, bottom, top) => {
   let s = k.extrude({ profile: holes.length ? { outer, holes } : outer, h });
   const b = bottom > 0 ? fit(outer, -bottom, "profile") : null;
   const t = top > 0 ? fit(outer, -top, "profile") : null;
-  if (b || t) s = s.intersect(k.loft({ rings: outerRings(outer, h, b, t) }));
+  // shading: "smooth" on all three internal lofts — a bevel band inherits the
+  // profile's own shading intent (sharp corners at the bevel's start/end
+  // rings, as a real chamfer would look), not the loft op's own facet-vs-
+  // smooth ring-count inference. Left to infer, a <32-point profile (any
+  // ordinary polygon) registers FACETED, which drops the bevel band's own
+  // corner crease lines and, via label()'s majority vote, can strip ALL
+  // edge lines from a labeled beveled solid.
+  if (b || t) s = s.intersect(k.loft({ rings: outerRings(outer, h, b, t), shading: "smooth" }));
   const cutters = [];
   for (const hole of holes) {
     const hb = bottom > 0 ? fit(hole, bottom, "hole") : null;
     if (hb) cutters.push(k.loft({ rings: [
       { polygon: hb.ring, z: -1 }, { polygon: hb.ring, z: 0 }, { polygon: hole, z: hb.c },
-    ] }));
+    ], shading: "smooth" }));
     const ht = top > 0 ? fit(hole, top, "hole") : null;
     if (ht) cutters.push(k.loft({ rings: [
       { polygon: hole, z: h - ht.c }, { polygon: ht.ring, z: h }, { polygon: ht.ring, z: h + 1 },
-    ] }));
+    ], shading: "smooth" }));
   }
   return cutters.length ? s.cutAll(cutters) : s;
 };

package/src/framework/geometry/shading-policy.js

@@ -0,0 +1,36 @@
+// Shading-intent policies — the single home for every edge/shading threshold.
+// A policy says how one original surface (a Manifold originalID) wants its
+// SAME-surface edges treated by creased-normals.js:
+//   creaseAngle       deg — same-surface edges bending more than this shade hard
+//   sameSurfaceLines  whether same-surface edges past creaseAngle also draw lines
+// Cross-surface (boolean cut seam) behavior is not policy: seams always shade
+// hard, and draw a line when bent more than COPLANAR_ANGLE.
+
+export const SMOOTH = Object.freeze({ creaseAngle: 35, sameSurfaceLines: true });
+export const FACETED = Object.freeze({ creaseAngle: 10, sameSurfaceLines: false });
+
+export const COPLANAR_ANGLE = 5;  // deg — cut seams bending less than this are coplanar: no line
+export const TANGENT_ANGLE = 5;   // deg — B-rep edges whose faces agree within this are tangent: no line
+export const MIN_EDGE = 0.01;     // mm — drop shorter segments (degenerate slivers, pole edges)
+
+// Loft rings with at least this many sides read as an approximation of a smooth
+// surface (e.g. a 64-gon "circle"), not as 64 intentional facets.
+export const SMOOTH_SIDES_MIN = 32;
+
+export const cosDeg = (deg) => Math.cos((deg * Math.PI) / 180);
+
+// Loft shading inference. An explicit `shading` hint wins; `ruled:false` asks
+// OCCT for a smoothly blended surface, so the Manifold preview of the same part
+// must shade smooth too; otherwise low-side-count rings are intentional facets.
+export function loftShadingPolicy(rings, { shading, ruled } = {}) {
+  if (shading === "smooth") return SMOOTH;
+  if (shading === "faceted") return FACETED;
+  if (shading != null) throw new Error('loft: shading must be "smooth" | "faceted"');
+  if (ruled === false) return SMOOTH;
+  let maxSides = 0;
+  if (Array.isArray(rings)) for (const r of rings) {
+    const n = Array.isArray(r?.polygon) ? r.polygon.length : (Number.isFinite(r?.sides) ? r.sides : 0);
+    if (n > maxSides) maxSides = n;
+  }
+  return maxSides >= SMOOTH_SIDES_MIN ? SMOOTH : FACETED;
+}

package/src/framework/viewer.js

@@ -166,7 +166,7 @@ export function createViewer(container, part) {
   }
 
   // CAD-style feature edge lines (anti-aliased "fat" lines), one per sub-part.
-  const EDGE_ANGLE = 35; // deg — OCCT fallback threshold (Manifold supplies seam-aware edges)
+  const EDGE_ANGLE = 35; // deg — last-ditch threshold for payloads with no kernel edge data
   const lineMaterial = new LineMaterial({ color: THEME.dark.line, linewidth: 1.0 }); // ~10% lighter, 1 px
   lineMaterial.resolution.set(1, 1); // real size set by resize() below
   const subLines = Object.fromEntries(
@@ -246,10 +246,10 @@ export function createViewer(container, part) {
   controls.addEventListener("start", onControlsStart);
   function onCameraStart(cb) { cameraStartListeners.add(cb); return () => cameraStartListeners.delete(cb); }
 
-  // Smooth shading within CREASE_ANGLE of a shared edge, hard edge past it — so the
-  // round body and helical groove read smooth while bore rims, drum faces, and
-  // groove walls stay crisp. Lower = more hard edges; raise toward Math.PI/3 for
-  // softer. (Worker normals are ignored; we recompute per the crease threshold.)
+  // Fallback creasing for payloads with no kernel normals. Both backends now
+  // ship authoritative normals (Manifold: policy-aware crease pass; OCCT:
+  // analytic B-rep normals), so this path is last-ditch only — it must not be
+  // "improved" in lieu of fixing a backend that stopped sending normals.
   const CREASE_ANGLE = Math.PI / 6; // 30°
 
   // --- geometry builder -----------------------------------------------------
@@ -262,20 +262,23 @@ export function createViewer(container, part) {
     const triCount = triangles ?? (indices ? indices.length : positions.length / 3) / 3;
     let out;
     if (normals?.length) {
-      // kernel-computed normals (Manifold) — smooth within a surface, hard at cut seams
+      // kernel-computed normals (both backends) — smooth within a surface, hard at cut seams
       geo.setAttribute("normal", new THREE.BufferAttribute(normals, 3));
       geo.computeBoundingBox();
       out = geo;
     } else {
-      // fallback (no kernel normals, e.g. OCCT): crease from the triangle soup
+      // fallback (payload with no kernel normals — no current backend does this): crease from the triangle soup
       out = toCreasedNormals(geo, CREASE_ANGLE);
       out.computeBoundingBox();
     }
     out.userData.triangles = triCount;
     if (featureIds) { out.userData.featureIds = featureIds; out.userData.features = features; }
-    // feature edge lines: Manifold supplies seam-aware segments; else derive by angle
+    // feature edge lines: kernel-supplied segments are authoritative — an EMPTY
+    // array means "this solid has no feature edges" (e.g. a lone sphere), so
+    // draw none rather than falling back. Only a payload with NO edge data at
+    // all (edges === undefined; no current backend does this) derives by angle.
     const lg = new LineSegmentsGeometry();
-    if (edges?.length) lg.setPositions(edges);
+    if (edges) lg.setPositions(edges); // edges is already a well-formed (possibly zero-length) Float32Array
     else lg.fromEdgesGeometry(new THREE.EdgesGeometry(out, EDGE_ANGLE));
     out.userData.edges = lg;
     return out;

package/src/testing/render.js

@@ -86,8 +86,8 @@ export async function renderViews(kernel, part, view = Object.keys(part.views)[0
 
     for (const m of meshes) {
       const P = m.positions, N = m.normals, ind = m.indices;
-      // Manifold meshes are a non-indexed soup (3 consecutive verts/triangle) with
-      // per-vertex normals; OCCT meshes are indexed and carry no normals.
+      // Manifold meshes are a non-indexed soup (3 consecutive verts/triangle);
+      // OCCT meshes are indexed. Both carry per-vertex normals.
       const triCount = ind?.length ? ind.length / 3 : P.length / 9;
       for (let t = 0; t < triCount; t++) {
         const ai = ind?.length ? ind[t * 3] * 3 : t * 9;

package/types/kernel.d.ts

@@ -267,6 +267,8 @@ export interface LoftOptions {
   ruled?: boolean;
   /** Capless loop — Manifold only. */
   closed?: boolean;
+  /** Overrides the facet-vs-smooth shading inference. */
+  shading?: "smooth" | "faceted";
 }
 
 export interface SweepOptions {