partforge 0.67.4 → 0.69.0

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

@@ -54,6 +54,33 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   const unionRaw = (ms) => (ms.length === 1 ? ms[0] : T(Manifold.union(ms)));
 
   const cache = createSolidCache();
+  // Feature-skip warnings (the OCCT backend's safeOp policy, adopted here): a
+  // fillet/chamfer whose mesh machinery is defeated by the geometry returns its
+  // INPUT solid unchanged and records one message here instead of failing the
+  // whole build. jobs.js drains this per sub-part (takeBuildWarnings) and ships
+  // it out on the meshes message, so a caller — the cloud agent above all — is
+  // TOLD the feature was skipped rather than left believing it landed.
+  const buildWarnings = [];
+  // cache key -> warning message for ops that skipped. The identity result is
+  // deliberately NOT cached (a later build should re-attempt the feature after
+  // upstream geometry changes — same key means same failure, so re-warning is
+  // cheap), but a repeated call in the SAME session must still re-emit the
+  // warning: without this map, a no-op re-apply would rebuild from warm caches
+  // upstream, hit the recorded skip nowhere, silently re-fail and re-warn — fine
+  // — but a memoized wrapper above us could also swallow the retry. Keeping the
+  // message per key makes "skipped before, skipped again" deterministic and free.
+  const skippedOps = new Map();
+  // The one recorder. Shared, backend-neutral degrades (the extrude rim bevel in
+  // rim-bevel.js, roundedBox's rim clamp in op-options.js, Shape2D's corner-op
+  // clamps in contour-ops.js) reach it through the kernel's `_recordWarning`, so
+  // every degrade in the build lands in one drainable list rather than only in
+  // the console.
+  const recordWarning = (msg) => { buildWarnings.push(msg); console.warn(`partforge: ${msg}`); };
+  const skipFeature = (key, op, magnitude, err) => {
+    const msg = `${op} ${magnitude} failed (${String(err?.message || err).slice(0, 200)}) — feature skipped, edges left sharp`;
+    skippedOps.set(key, msg);
+    recordWarning(msg);
+  };
   const featureLabels = new Map(); // originalID -> label string (grows per label(); tiny)
   const oidPolicies = new Map();   // originalID -> shading policy (grows per faceted/hinted loft; tiny)
   // name -> { m, digest, hash } | { error, digest } — imported geometry the framework
@@ -80,6 +107,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     segs,
     extrude: (o) => kernel.extrude(o),
     revolve: (o) => kernel.revolve(o),
+    recordWarning,
   });
   // Lazy CrossSection materialization, memoized through the solid cache by content
   // hash + LOD: the same shape extruded twice (or extruded and revolved) tessellates
@@ -237,8 +265,13 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
         let base = T(Manifold.extrude(cur, height));
         if (z0 !== 0) base = T(base.translate([0, 0, z0]));
         const wrapped = wrap(base, h("roundAllPrismBase", mHash, r, quality));
-        // selector-free: every sharp edge of the mitered prism gets its radius here
-        const filleted = wrapped.fillet(r);
+        // selector-free: every sharp edge of the mitered prism gets its radius here.
+        // The THROWING form deliberately: this path's answer to a failed fillet is
+        // the `catch` below, which returns null and hands the job to the reference
+        // Minkowski roundAll. The degrading public fillet would instead hand back
+        // the un-rounded prism, and this function would emit it as a successful
+        // roundAll — silently wrong geometry instead of a correct slow result.
+        const filleted = wrapped._filletRaw(r);
         // Decouple from the fillet cache's pin: cached() will pin the object this
         // returns under the roundAll hash, and one WASM object must never sit
         // under two cache entries (double-dispose on eviction). The decouple is
@@ -273,22 +306,66 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     }
   };
 
-  const wrap = (m, hash) => addSugar({
+  // `self` names the wrapper being built so the degrading public fillet/chamfer
+  // can delegate to their throwing `_`-prefixed twins above without re-deriving
+  // the cache key or the capability checks. Declared as a binding the closures
+  // capture: every reference runs after addSugar has returned.
+  const wrap = (m, hash) => {
+    const self = addSugar({
     _m: m,
     _hash: hash,
     cut: (t) => cached(h("cut", hash, t._hash), () => T(m.subtract(t._m))),
-    fillet: (r, selector) => {
+    // THROWING forms. These are the composition primitives — internal callers
+    // that have their own recovery (prismRoundAllFast, which answers a failed
+    // fillet by falling back to the reference Minkowski roundAll) must use
+    // these, never the degrading public ops below: a skip there would emit an
+    // UN-rounded prism as a successful roundAll, which is silently wrong
+    // geometry rather than a reported missing feature.
+    _filletRaw: (r, selector) => {
       if (typeof selector === "function") throw new KernelCapabilityError("fillet: function selectors need the OCCT backend");
       if (r === 0) return wrap(m, hash); // contract: zero magnitude is the identity
       return cached(h("fillet", hash, r, selector ?? null, segs), () =>
         meshCadOp("fillet", m, () => meshFillet(kernel, wrap(m, hash), { r, edges: selector, segs })));
     },
-    chamfer: (d, selector) => {
+    _chamferRaw: (d, selector) => {
       if (typeof selector === "function") throw new KernelCapabilityError("chamfer: function selectors need the OCCT backend");
       if (d === 0) return wrap(m, hash);
       return cached(h("chamfer", hash, d, selector ?? null, segs), () =>
         meshCadOp("chamfer", m, () => meshChamfer(kernel, wrap(m, hash), { d, edges: selector, segs })));
     },
+
+    // The AUTHOR-FACING ops degrade on failure instead of failing the build (the
+    // OCCT backend's safeOp policy — see occt-repair.js): a defeated op returns
+    // the INPUT solid and records a feature-skip warning. Only NEEDS_OCCT
+    // capability errors still propagate — they are the split-backend reroute
+    // signal, not a geometry failure, and swallowing one would strand the
+    // sub-part on the wrong backend. The skip result is not cached: same key →
+    // same failure → same cheap re-warn, while an upstream geometry change mints
+    // a new key and genuinely re-attempts the feature.
+    fillet: (r, selector) => {
+      const key = h("fillet", hash, r, selector ?? null, segs);
+      const skipped = skippedOps.get(key);
+      if (skipped !== undefined) { buildWarnings.push(skipped); return wrap(m, hash); }
+      try {
+        return self._filletRaw(r, selector);
+      } catch (e) {
+        if (e?.code === "NEEDS_OCCT") throw e;
+        skipFeature(key, "fillet", r, e);
+        return wrap(m, hash);
+      }
+    },
+    chamfer: (d, selector) => {
+      const key = h("chamfer", hash, d, selector ?? null, segs);
+      const skipped = skippedOps.get(key);
+      if (skipped !== undefined) { buildWarnings.push(skipped); return wrap(m, hash); }
+      try {
+        return self._chamferRaw(d, selector);
+      } catch (e) {
+        if (e?.code === "NEEDS_OCCT") throw e;
+        skipFeature(key, "chamfer", d, e);
+        return wrap(m, hash);
+      }
+    },
     roundAll: (r) => {
       if (r === 0) return wrap(m, hash); // contract: zero magnitude is the identity
       // `quality` in the key is redundant but harmless — the cache lives on a
@@ -433,7 +510,9 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     toMesh: () => meshOut(m, false),
     toSTL: () => Promise.resolve(meshOut(m, true)),
     toIndexedMesh: () => indexedMeshOut(m),
-  });
+    });
+    return self;
+  };
 
   const kernel = finishKernel({
     cylinder: (rb, rt, h2, { center = false } = {}) =>
@@ -571,6 +650,13 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     sweepCache: () => cache.sweep(),
     cacheStats: () => cache.stats(),
     resetCacheStats: () => cache.resetStats(),
+    // Drain the feature-skip warnings recorded since the last drain (see
+    // buildWarnings above). jobs.js calls this per sub-part so a warning is
+    // attributed to the sub-part whose build recorded it.
+    takeBuildWarnings: () => buildWarnings.splice(0),
+    // Internal (underscore = not the contract surface): the recorder shared,
+    // backend-neutral helpers report their own degrades through.
+    _recordWarning: recordWarning,
     // Free every WASM object created since the last cleanup EXCEPT solids the cache
     // still pins (they must survive for the next build to resume from them).
     cleanup: () => { for (const o of tracked) if (!cache.isPinned(o)) o.delete?.(); tracked.length = 0; },

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

@@ -39,9 +39,15 @@ export function createOcctKernel(replicad) {
   const { makeCylinder, makeBox, makeCircle, makeHelix, assembleWire, genericSweep,
           loft, draw, exportSTEP, importSTEP, measureVolume, makeSphere, makeLine, Plane } = replicad;
 
+  // Feature-skip warnings: everything occt-repair (and roundAll) skips or rescues
+  // is recorded here as well as console.warned, and jobs.js drains it per
+  // sub-part (takeBuildWarnings) onto the meshes message — same channel as the
+  // Manifold backend's fillet/chamfer degradation.
+  const buildWarnings = [];
+  const recordWarning = (msg) => { buildWarnings.push(msg); console.warn(`partforge: ${msg}`); };
   // Fillet/chamfer/shell failure recovery (skip-on-failure, chamfer binary search) —
   // see occt-repair.js for the policies and why they differ per op.
-  const { validChamfer, safeOp } = createOcctRepair(measureVolume);
+  const { validChamfer, safeOp } = createOcctRepair(measureVolume, recordWarning);
 
   // name -> { shape, digest } | { error, digest } — imported geometry the framework
   // registers pre-build via `_registerImport` (kernel-lifetime, untracked by the
@@ -234,7 +240,7 @@ export function createOcctKernel(replicad) {
         return cached(key, () => {
           const a = mat();
           if (r === 0) return wrap(a._s.clone(), cloneLabels(a._labels), key);
-          return wrap(occtRoundAll(replicad, a._s, r), cloneLabels(a._labels), key);
+          return wrap(occtRoundAll(replicad, a._s, r, recordWarning), cloneLabels(a._labels), key);
         });
       },
       shell: (thickness, openFaces) => {
@@ -367,6 +373,7 @@ export function createOcctKernel(replicad) {
     segs: SHAPE2D_SEGS,
     extrude: (o) => kernel.extrude(o),
     revolve: (o) => kernel.revolve(o),
+    recordWarning,
   });
   // Lazy Drawing materialization for the kernel ops that need one. drawingFromRegions
   // draws a FRESH Drawing on every call, so callers never need to .clone() the result
@@ -524,6 +531,12 @@ export function createOcctKernel(replicad) {
     sweepCache: () => cache.sweep(),
     cacheStats: () => cache.stats(),
     resetCacheStats: () => cache.resetStats(),
+    // Drain the feature-skip warnings recorded since the last drain — the
+    // Manifold backend's channel, mirrored (see occt-repair.js for the sources).
+    takeBuildWarnings: () => buildWarnings.splice(0),
+    // Internal: the recorder shared, backend-neutral helpers report through
+    // (rim-bevel, roundedBox's clamp, Shape2D corner-op clamps).
+    _recordWarning: recordWarning,
   });
   return kernel;
 }

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

@@ -33,7 +33,11 @@ export const isClosedSolid = (shape) => {
   return true;
 };
 
-export function createOcctRepair(measureVolume) {
+// `warn` receives every feature-skip / rescue message. The default keeps the
+// historical console.warn; the OCCT backend injects a recorder that ALSO feeds
+// the kernel's takeBuildWarnings channel, so a skipped feature reaches the
+// build result (and, in the cloud app, the agent) instead of only the console.
+export function createOcctRepair(measureVolume, warn = (msg) => console.warn(`partforge: ${msg}`)) {
   // The true maximum chamfer for an edge depends on local angles and adjacent features,
   // which is hard to predict analytically (and OCCT exposes no max-radius query). So
   // VALIDATE the result instead of guessing: try the requested distance, and if it makes
@@ -65,8 +69,8 @@ export function createOcctRepair(measureVolume) {
     // multiplies an already-expensive op by ~8x, so make the cost loud enough to
     // act on (lower the distance, or bevel profile rims with a loft instead).
     const cost = `${attempts} attempts, ${((performance.now() - t0) / 1000).toFixed(1)}s — see ERROR-PATTERNS.md#chamfer-rescue-bisection`;
-    if (best) { console.warn(`partforge: chamfer ${distance} over-ran the geometry — reduced to ${bestD.toFixed(2)} (largest valid; ${cost})`); return best; }
-    console.warn(`partforge: chamfer ${distance} has no valid distance for this geometry — feature skipped (${cost})`);
+    if (best) { warn(`chamfer ${distance} over-ran the geometry — reduced to ${bestD.toFixed(2)} (largest valid; ${cost})`); return best; }
+    warn(`chamfer ${distance} has no valid distance for this geometry — feature skipped (${cost})`);
     return shape.clone();                                    // nothing valid — skip the chamfer
   };
 
@@ -90,10 +94,10 @@ export function createOcctRepair(measureVolume) {
       const resultVolume = measureVolume(result);
       if (resultVolume > 0 && (!isValid || isValid(resultVolume, beforeVolume))) { backup.delete?.(); return result; }
       result.delete?.();
-      if (resultVolume > 0) console.warn(`partforge: ${label} produced invalid geometry — feature skipped`);
-      else console.warn(`partforge: ${label} produced an empty solid — feature skipped (radius out of range?)`);
+      if (resultVolume > 0) warn(`${label} produced invalid geometry — feature skipped`);
+      else warn(`${label} produced an empty solid — feature skipped (radius out of range?)`);
     } catch (e) {
-      console.warn(`partforge: ${label} failed (${e?.message || e}) — feature skipped`);
+      warn(`${label} failed (${e?.message || e}) — feature skipped`);
     }
     return backup;
   };

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

@@ -31,7 +31,7 @@ const VARIANTS = [
   { join: "int", inter: true },
 ];
 
-export function occtRoundAll(replicad, shape, r) {
+export function occtRoundAll(replicad, shape, r, warn = (msg) => console.warn(`partforge: ${msg}`)) {
   if (!Number.isFinite(r) || r <= 0) throw new Error("roundAll: r must be a finite number > 0 (r = 0 is handled as the identity by the caller)");
   const oc = replicad.getOC();
   const tryOffset = (topo, offset, v) => {
@@ -60,7 +60,7 @@ export function occtRoundAll(replicad, shape, r) {
     vol = replicad.measureVolume(shape);
   } catch (e) {
     // Can't gate what can't be measured — skip rather than run the cascade blind.
-    console.warn(`partforge: roundall-skipped: the input solid's volume could not be measured (${e?.message || e}); returning the un-rounded solid`);
+    warn(`roundall-skipped: the input solid's volume could not be measured (${e?.message || e}); returning the un-rounded solid`);
     return shape.clone(); // if the clone throws too, the caller's shape is unusable — let it propagate
   }
   let cur = shape;
@@ -85,7 +85,7 @@ export function occtRoundAll(replicad, shape, r) {
     }
     if (cur !== shape) cur.delete?.(); // superseded intermediate; never the caller's shape
     if (!next) {
-      console.warn(`partforge: roundall-skipped: offset step ${off} produced no valid solid — r=${r} is likely at/above the smallest feature size; returning the un-rounded solid`);
+      warn(`roundall-skipped: offset step ${off} produced no valid solid — r=${r} is likely at/above the smallest feature size; returning the un-rounded solid`);
       return shape.clone();
     }
     cur = next;

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

@@ -150,7 +150,7 @@ const checkRoundRadius = (op, name, v, max, maxDesc) => {
   if (v > max + 1e-9) throw new Error(`${op}: ${name} (${v}) must be ≤ ${maxDesc}`);
 };
 
-export function roundedBoxArgs(o) {
+export function roundedBoxArgs(o, record) {
   checkKeys("roundedBox", o, ["size", "center", "round"]);
   const size = req("roundedBox", o, "size");
   if (!Array.isArray(size) || size.length !== 3 || !size.every((v) => Number.isFinite(v) && v > 0))
@@ -174,6 +174,11 @@ export function roundedBoxArgs(o) {
         // message (and a distinct Set entry) on every rebuild, defeating the dedupe.
         const dedupeKey = `roundedBox.${key}|${round.side}`;
         const msg = `roundedBox: round.${key} ${round[key]} clamped to round.side ${round.side} (side must be 0 or ≥ rim radii; use side: 0 for a rim-only round-over)`;
+        // The console dedupe stays (a slider sweep would otherwise spam it), but
+        // the RECORDER is fed every time: warnings are drained per build, so
+        // deduping them across builds would silently drop the clamp from the
+        // second and every later build that still clamps.
+        record?.(msg);
         if (!warnedClamps.has(dedupeKey)) { warnedClamps.add(dedupeKey); console.warn(msg); }
         round[key] = round.side;
       }

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

@@ -67,7 +67,7 @@ const ccw = (r) => {
 // loop is deterministic, preserving build purity. `corners: "sharp"` keeps the
 // offset 1:1 with the input points — loft stitching requires every ring to
 // share the profile's exact point count (a mismatch is treated as a failed try).
-const fit = (ring, delta, what) => {
+const fit = (ring, delta, what, record) => {
   const requested = Math.abs(delta), sign = Math.sign(delta);
   let c = requested;
   for (;;) {
@@ -75,13 +75,13 @@ const fit = (ring, delta, what) => {
       const off = offsetPolygon(ring, sign * c, { corners: "sharp" });
       if (off.length === ring.length) {
         if (c < requested)
-          console.warn(`partforge: extrude bevel ${requested} exceeds what the ${what} can take — reduced to ${c.toFixed(2)}`);
+          record(`extrude bevel ${requested} exceeds what the ${what} can take — reduced to ${c.toFixed(2)}`);
         return { ring: off, c };
       }
     } catch { /* offset collapsed or self-intersected — try smaller */ }
     c *= 0.85;
     if (c < 0.05) {
-      console.warn(`partforge: extrude bevel ${requested} has no valid offset for this ${what} — rim left square`);
+      record(`extrude bevel ${requested} has no valid offset for this ${what} — rim left square`);
       return null;
     }
   }
@@ -96,12 +96,12 @@ const outerRings = (outer, h, b, t) => {
   return rings;
 };
 
-const bevelRegion = (k, region, h, bottom, top) => {
+const bevelRegion = (k, region, h, bottom, top, record) => {
   const outer = ccw(region.outer);
   const holes = (region.holes ?? []).map(ccw);
   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;
+  const b = bottom > 0 ? fit(outer, -bottom, "profile", record) : null;
+  const t = top > 0 ? fit(outer, -top, "profile", record) : null;
   // 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-
@@ -112,11 +112,11 @@ const bevelRegion = (k, region, h, bottom, top) => {
   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;
+    const hb = bottom > 0 ? fit(hole, bottom, "hole", record) : 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;
+    const ht = top > 0 ? fit(hole, top, "hole", record) : 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" }));
@@ -124,7 +124,14 @@ const bevelRegion = (k, region, h, bottom, top) => {
   return cutters.length ? s.cutAll(cutters) : s;
 };
 
-export function beveledExtrude(k, { profile, h, twist, scaleTop, bevel }) {
+// `record` reports the two ways a rim bevel degrades — reduced to what the ring
+// can take, or skipped entirely with the rim left square. Both used to reach only
+// console.warn, which meant a build could come back ok:true with a bevel the part
+// asked for and never got, invisible to the caller (and to the cloud agent). The
+// kernel supplies its own recorder; the default keeps the historical console.warn
+// for a direct call with no kernel recorder behind it.
+export function beveledExtrude(k, { profile, h, twist, scaleTop, bevel },
+                               record = k?._recordWarning ?? ((m) => console.warn(`partforge: ${m}`))) {
   if (twist !== undefined || scaleTop !== undefined)
     throw new Error("extrude: bevel cannot combine with twist or scaleTop");
   const { bottom, top } = resolveBevel(bevel, h);
@@ -135,5 +142,5 @@ export function beveledExtrude(k, { profile, h, twist, scaleTop, bevel }) {
     ? profile.toRegions()
     : [tessellateProfile(profile, BEVEL_SEGS)];
   if (regions.length === 0) throw new Error("extrude: bevel profile produced no regions");
-  return regions.map((r) => bevelRegion(k, r, h, bottom, top)).reduce((a, x) => a.union(x));
+  return regions.map((r) => bevelRegion(k, r, h, bottom, top, record)).reduce((a, x) => a.union(x));
 }

package/src/framework/geometry/shape2d.js

@@ -45,7 +45,11 @@ const checkProfile = (x) => {
   }
 };
 
-export function makeShape2dFactory({ segs, extrude, revolve }) {
+// `recordWarning` is the kernel's build-warning recorder (see manifold-backend /
+// occt-backend). Corner ops CLAMP a magnitude the geometry cannot take rather
+// than throwing, and a clamp that only reached the console would leave a caller
+// believing it got the radius it asked for.
+export function makeShape2dFactory({ segs, extrude, revolve, recordWarning }) {
   // Lift any accepted profile form into stored regions: a live Shape2D is deep-copied out
   // via its own toContours() (value semantics — never alias another shape's storage);
   // anything else goes through liftProfile + per-ring winding normalization.
@@ -86,8 +90,8 @@ export function makeShape2dFactory({ segs, extrude, revolve }) {
       rotate:    (deg, center) => viaOps((r) => rotateProfile(r, deg, center)),
       scale:     (f, center) => viaOps((r) => scaleProfile(r, f, center)),
       mirror:    (axis) => viaOps((r) => mirrorProfile(r, axis)),
-      fillet:    (r, opts) => viaOps((rg) => filletProfile(rg, r, opts)),
-      chamfer:   (d, opts) => viaOps((rg) => chamferProfile(rg, d, opts)),
+      fillet:    (r, opts) => viaOps((rg) => filletProfile(rg, r, opts, recordWarning)),
+      chamfer:   (d, opts) => viaOps((rg) => chamferProfile(rg, d, opts, recordWarning)),
       simplify:  (tol) => viaOps((r) => simplifyProfile(r, tol)),
       corners:   () => profileCorners(regions),
       contains:  (p) => profileContains(regions, p),

package/src/framework/jobs.js

@@ -130,6 +130,13 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       const t0 = Date.now();
       const useCache = msg.cache !== false; // ?debug toggle can disable caching (cache:false)
       const meshes = [];
+      // Feature-skip warnings (a fillet/chamfer the geometry defeated — see the
+      // backends' takeBuildWarnings): drained per sub-part below so each message
+      // names the sub-part whose build recorded it, and drained-and-discarded here
+      // first so a previous job's stragglers (an oracle build, an export) cannot be
+      // misattributed to this build's first sub-part.
+      kernel.takeBuildWarnings?.();
+      const warnings = [];
       kernel.resetCacheStats?.(); // count hits/misses for just this job
       for (const [i, name] of msg.subparts.entries()) {
         if (useCache) kernel.beginSubPart?.(name); // open the per-sub-part cache round
@@ -137,6 +144,7 @@ export async function handle(kernel, part, msg, post, opts = {}) {
           const m = posed(name, "display").toMesh({ quality: "preview" });
           meshes.push({ name, positions: m.positions, normals: m.normals, indices: m.indices, triangles: m.triangles, edges: m.edges, featureIds: m.featureIds, features: m.features });
         } finally {
+          for (const message of kernel.takeBuildWarnings?.() ?? []) warnings.push({ part: name, message });
           if (useCache) kernel.endSubPart?.(); // always close the bracket — a throw mid-build must not strand pinned solids
           kernel.cleanup?.();                  // free this round's transients (cached/pinned solids survive)
         }
@@ -152,7 +160,8 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       }
       const transfer = meshes.flatMap((m) =>
         [m.positions.buffer, m.normals?.buffer, m.indices?.buffer, m.edges?.buffer, m.featureIds?.buffer].filter(Boolean));
-      post({ type: "meshes", meshes, ms: Date.now() - t0, cache: kernel.cacheStats?.() }, transfer);
+      post({ type: "meshes", meshes, ms: Date.now() - t0, cache: kernel.cacheStats?.(),
+             ...(warnings.length ? { warnings } : {}) }, transfer);
     } else if (msg.type === "capture-generate") {
       // A private, job-correlated one-shot channel for captureView — builds a
       // (possibly non-active) view's meshes off the regen loop, so it can never
@@ -161,19 +170,23 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       // isStale/superseded polling — there's nothing to supersede a one-shot.
       const useCache = msg.cache !== false;
       const meshes = [];
+      kernel.takeBuildWarnings?.(); // discard a previous job's stragglers (same as generate)
+      const warnings = [];
       for (const name of msg.subparts) {
         if (useCache) kernel.beginSubPart?.(name);
         try {
           const m = posed(name, "display").toMesh({ quality: "preview" });
           meshes.push({ name, positions: m.positions, normals: m.normals, indices: m.indices, triangles: m.triangles, edges: m.edges, featureIds: m.featureIds, features: m.features });
         } finally {
+          for (const message of kernel.takeBuildWarnings?.() ?? []) warnings.push({ part: name, message });
           if (useCache) kernel.endSubPart?.();
           kernel.cleanup?.();
         }
       }
       const captureTransfer = meshes.flatMap((m) =>
         [m.positions.buffer, m.normals?.buffer, m.indices?.buffer, m.edges?.buffer, m.featureIds?.buffer].filter(Boolean));
-      post({ type: "capture-meshes", jobId: msg.jobId, meshes }, captureTransfer);
+      post({ type: "capture-meshes", jobId: msg.jobId, meshes,
+             ...(warnings.length ? { warnings } : {}) }, captureTransfer);
     } else if (msg.type === "export-stl") {
       const names = selected();
       if (names.length === 0) throw new Error("no exportable parts selected");

package/src/framework/mount.js

@@ -28,6 +28,8 @@ import { attachAnimationControls } from "./animation-controls.js";
 import { resolveDefaultView } from "./default-view.js";
 import { createMeasureMode } from "./measure/measure-mode.js";
 import { attachMeasureControls } from "./measure/measure-controls.js";
+import { createAnnotateMode } from "./annotate/annotate-mode.js";
+import { attachAnnotateControls } from "./annotate/annotate-controls.js";
 
 // The mount handle, factored out so its shape is unit-testable without booting
 // the full mount() pipeline (WASM + workers + DOM).
@@ -37,6 +39,14 @@ const NOOP_TOOLTIP_BINDING = { sync: () => {}, hide: () => {}, detach: () => {}
 // Same no-op-default stance as attachTooltips/setHostPane below, for a
 // makeHandle caller (or a direct test) that doesn't wire measure mode.
 const NOOP_MEASURE = { isEnabled: () => false, setEnabled: () => {}, clearPins: () => {}, pinCount: () => 0 };
+// Same stance as NOOP_MEASURE: the handle's annotate surface exists whether or
+// not this mount wired the mode (it wires only when the host passes
+// onAnnotationSend — without a sink, Send would have nowhere to go).
+const NOOP_ANNOTATE = {
+  isEnabled: () => false, setEnabled: () => {}, undo: () => {}, clear: () => {},
+  strokeCount: () => 0, send: () => false,
+  onInkChange: () => () => {}, onModeChange: () => () => {},
+};
 // The STEP-on-Manifold import crossover's broken-state message (a second
 // needs-import-mesh after the mesh is already primed — see the "needs-import-mesh"
 // case below). One shared string so the status line, onBuild, and the ready
@@ -49,7 +59,7 @@ const IMPORT_MESH_BROKEN_MESSAGE = "STEP import tessellation failed to satisfy t
 // carries the worker's own error text. See the correlated "error" case below.
 const importTessellateFailedMessage = (workerMessage) => `STEP import tessellation failed — ${workerMessage}`;
 
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView, attachTooltips, measure }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView, attachTooltips, measure, annotate }) {
   return {
     ready, dispose, setParams,
     // Part-declared animation playback (spec 2026-08-02): animations are
@@ -91,6 +101,11 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     // button. Dimensions render in the scene, so a dimensioned capture is just
     // captureCurrent() taken while the mode is on.
     measure: measure ?? NOOP_MEASURE,
+    // Annotation-mode API (spec 2026-08-18): { isEnabled, setEnabled, clear,
+    // strokeCount, send, onModeChange } — an embedder drives the mode without
+    // the built-in pencil button. send() delivers to onAnnotationSend and
+    // returns false when there is no ink or the capture failed.
+    annotate: annotate ?? NOOP_ANNOTATE,
   };
 }
 
@@ -182,6 +197,12 @@ function createCleanupStack() {
 //   const off = runtime.onContextLost(() => …);  // WebGL context loss, i.e. the GPU or the
 //                                 // OS gave up — surface it rather than showing a dead
 //                                 // canvas. Returns an unsubscribe.
+//   runtime.annotate: { isEnabled, setEnabled, undo, clear, strokeCount, send, onInkChange,
+//                       onModeChange } — drive annotation mode without the built-in button;
+//                                 // no-op when onAnnotationSend was not supplied. Both
+//                                 // subscribes return an unsubscribe; onInkChange fires on
+//                                 // every stroke/undo/clear, which is what a host driving its
+//                                 // own Send button gates that button on (strokeCount() > 0).
 //   runtime.dispose();     // full teardown
 // onBuild fires per completed build, so it does NOT fire for a pose-only edit —
 // those are repaired in the viewer and produce no build at all.
@@ -194,10 +215,27 @@ function createCleanupStack() {
 //                                         // is a snapshot copy. Never fired by setParams or
 //                                         // animation playback — hosts call setParams from their
 //                                         // own undo/reset, and firing here would loop.
+// onAnnotationSend(payload)              // receive user annotations (freehand ink over the frozen
+//                                         // view). Supplying this reveals the #annotate viewbar
+//                                         // button; omitting it hides the button entirely.
+//                                         // payload.images carries two data URLs (the ink drawing
+//                                         // and the rendered model), each bounded to a 2048px long
+//                                         // edge — a stage bigger than that exports scaled down
+//                                         // rather than at its own hi-DPI size. Still hundreds of
+//                                         // KB of base64 apiece, so a host should not assume this
+//                                         // payload is small, only that it is bounded.
+// annotateSend: "viewbar" | "host"       // who owns the Send affordance. "viewbar" (default) puts
+//                                         // Send beside Undo/Clear in the annotate actions row.
+//                                         // "host" drops it and leaves Undo/Clear: the host draws
+//                                         // its own send control — e.g. a composer that pairs the
+//                                         // sketch with a typed message — and calls
+//                                         // runtime.annotate.send() itself. Ignored without
+//                                         // onAnnotationSend (there is no button to place).
 // Every `elements` entry defaults to the legacy global-ID lookup (below), resolved
 // exactly once here — submodules take element refs and never query the document.
 // `container`/`controls` remain as deprecated aliases for elements.viewer/.controls.
-export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload, onViewChange, onParamsCommit,
+export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload, onViewChange, onParamsCommit, onAnnotationSend,
+                              annotateSend = "viewbar",
                               container: legacyContainer, controls: legacyControls } = {}) {
   // --- element resolution (the only getElementById calls in the framework, save the ?pickserver client's optional #viewbar lookup) ----
   const byId = (id) => document.getElementById(id);
@@ -228,6 +266,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       theme: elements.chrome?.theme ?? byId("theme"),
       cutaway: elements.chrome?.cutaway ?? byId("cutaway"),
       measure: elements.chrome?.measure ?? byId("measure"),
+      annotate: elements.chrome?.annotate ?? byId("annotate"),
       railToggle: elements.chrome?.railToggle ?? byId("rail-toggle"),
     },
   };
@@ -349,6 +388,30 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       getParamsVersion: () => loop.version(),
     });
     cleanup.defer(() => measureMode.detach());
+    // Annotation mode (spec 2026-08-18): freehand ink over the frozen view,
+    // delivered to the host via onAnnotationSend. Wired only when the host
+    // passes the sink; the chrome hides the button otherwise (mode = null).
+    let annotateMode = null;
+    if (onAnnotationSend) {
+      annotateMode = createAnnotateMode(viewer, {
+        stage: els.viewer,
+        getContext: () => ({ view: view(), params }),
+        onSend: onAnnotationSend,
+      });
+      cleanup.defer(() => annotateMode.detach());
+      // Annotate and measure both claim canvas pointer input — mutually
+      // exclusive, whichever turns on turns the other off.
+      cleanup.defer(annotateMode.onModeChange(() => {
+        if (annotateMode.isEnabled()) measureMode.setEnabled(false);
+      }));
+      cleanup.defer(measureMode.onModeChange(() => {
+        if (measureMode.isEnabled()) annotateMode.setEnabled(false);
+      }));
+    }
+    const annotateChrome = attachAnnotateControls(viewer, annotateMode, {
+      annotate: els.chrome.annotate,
+    }, { tooltip, escapeScope: els.viewer, send: annotateSend });
+    cleanup.defer(() => annotateChrome.detach());
     // escapeScope: cutaway's Flip/Reset buttons are canvas SIBLINGS inside
     // #viewbar, not descendants of the canvas — attaching Escape to
     // viewer.domElement alone would leave a guarded Escape from those buttons
@@ -360,13 +423,15 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     cleanup.defer(() => measureChrome.detach());
     const cutawayChrome = attachCutawayControls(viewer, {
       cutaway: els.chrome.cutaway,
-    }, { tooltip, escapeGuard: () => measureMode.isEnabled() });
+    }, { tooltip, escapeGuard: () => measureMode.isEnabled() || (annotateMode?.isEnabled() ?? false) });
     cleanup.defer(() => cutawayChrome.detach());
-    // Suppress the always-on hover tooltip while measure mode is active — its
-    // own feature highlight + dims take over the pointer.
-    const offMeasureHover = measureMode.onModeChange(() =>
-      hover.setSuppressed(measureMode.isEnabled()));
-    cleanup.defer(offMeasureHover);
+    // Suppress the always-on hover tooltip while measure OR annotate mode is
+    // active — measure's highlight + dims take the pointer; annotate's overlay
+    // canvas takes it entirely.
+    const syncHoverSuppression = () =>
+      hover.setSuppressed(measureMode.isEnabled() || (annotateMode?.isEnabled() ?? false));
+    cleanup.defer(measureMode.onModeChange(syncHoverSuppression));
+    if (annotateMode) cleanup.defer(annotateMode.onModeChange(syncHoverSuppression));
 
     // Current selection context for the pickers: the active view + live params +
     // derived values. Shared by every pick mode below.
@@ -392,7 +457,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
         // resync on mode changes. The ?pick/?pickserver harnesses below are
         // deliberately not guarded — one is armed by an explicit dev toggle,
         // the other per agent request.
-        suppressed: () => measureMode.isEnabled(),
+        suppressed: () => measureMode.isEnabled() || (annotateMode?.isEnabled() ?? false),
         onPick: (selection) => onPick({
           selection,
           label: selection.feature?.label ?? part.parts[selection.subPart]?.label ?? selection.subPart,
@@ -869,6 +934,16 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
         clearPins: measureMode.clearPins,
         pinCount: measureMode.pinCount,
       },
+      annotate: annotateMode ? {
+        isEnabled: annotateMode.isEnabled,
+        setEnabled: annotateMode.setEnabled,
+        undo: annotateMode.undo,
+        clear: annotateMode.clear,
+        strokeCount: annotateMode.strokeCount,
+        send: annotateMode.send,
+        onInkChange: annotateMode.onInkChange,
+        onModeChange: annotateMode.onModeChange,
+      } : null,
     });
   } catch (error) {
     try {