partforge 0.6.1 → 0.8.0

package/src/framework/geometry/solid-sugar.js

@@ -1,9 +1,16 @@
 // src/framework/geometry/solid-sugar.js
-// Self-describing build-step vocabulary, defined ONCE over both geometry backends.
-// Every Solid a backend's wrap() returns is passed through addSugar(), which attaches
-// readable transform/placement methods composed purely from the solid's existing
-// rotate()/translate() primitives — so the sugar is geometry-identical to the
-// hand-written primitive calls, on Manifold and OCCT alike.
+// The backend-shared Solid front, defined ONCE over both geometry backends. Every
+// Solid a backend's wrap() returns is passed through addSugar(), which:
+//   - attaches the readable transform/placement vocabulary (rotateX/along/at/…),
+//     composed purely from the solid's own rotate()/translate() primitives, so the
+//     sugar is geometry-identical on Manifold and OCCT alike;
+//   - validates arguments the backends would otherwise each check (scale factor);
+//   - derives boundingBox center/size from the backend's raw {min,max};
+//   - stubs any OCCT-only op the backend lacks with a KernelCapabilityError, so
+//     the needs-occt reroute works without hand-written per-backend stubs.
+import { KernelCapabilityError } from "./errors.js";
+import { OCCT_ONLY_OPS } from "./kernel.js";
+
 const ORIGIN = [0, 0, 0];
 const AXIS = { X: [1, 0, 0], Y: [0, 1, 0], Z: [0, 0, 1] };
 
@@ -31,5 +38,25 @@ const SUGAR = {
 };
 
 export function addSugar(s) {
+  const rawScale = s.scale;
+  s.scale = (factor, center = ORIGIN) => {
+    if (!(factor > 0)) throw new Error("scale: factor must be > 0");
+    return rawScale(factor, center);
+  };
+
+  const rawBoundingBox = s.boundingBox;
+  s.boundingBox = () => {
+    const { min, max } = rawBoundingBox();
+    return {
+      min, max,
+      center: [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2],
+      size: [max[0] - min[0], max[1] - min[1], max[2] - min[2]],
+    };
+  };
+
+  for (const op of OCCT_ONLY_OPS) {
+    s[op] ??= () => { throw new KernelCapabilityError(`${op} requires the OCCT backend`); };
+  }
+
   return Object.assign(s, SUGAR);
 }

package/src/framework/geometry/sweep.js

@@ -0,0 +1,151 @@
+// Backend-shared sweep support. resolveSweepStations() walks a 3-D polyline path with a
+// rotation-minimizing frame (parallel transport, specialised to piecewise-linear paths:
+// the frame only ever rotates ACROSS a vertex, by the minimal rotation carrying the
+// incoming tangent onto the outgoing one) and places the 2-D profile at a fixed, shared
+// set of 3-D cross-section stations. BOTH backends build from that SAME station list —
+// Manifold hand-meshes it (sweepMesh below, the loft/helix-tube recipe via mesh-build.js),
+// OCCT lofts the same rings ruled (occt-backend.js). So the elbow shape agrees BY
+// CONSTRUCTION, not by tolerance — the same parity mechanism loft's resolveRings uses.
+//
+// Corners: cornerRadius==0 → a SHARP MITER (one station per vertex, in the bisecting
+// plane, stretched by 1/cos(turn/2) so straight walls meet flush). cornerRadius>0 →
+// a tangent circular ARC FAN (setback clamped like filletPolygon). Fold conditions
+// (profile too wide for a bend; 180° reversal) throw up front — the volume+bbox oracle
+// would ship a fold silently otherwise.
+import { sideQuads, fanCap, manifoldFromMesh, reverseWinding } from "./mesh-build.js";
+
+const EPS = 1e-9;
+const Z = [0, 0, 1], X = [1, 0, 0];
+// Corner-arc station density, in degrees of turn per station. A shared CONSTANT (not a
+// backend/quality value) so both backends subdivide a cornerRadius arc identically →
+// identical stations → parity by construction.
+const ARC_STEP_DEG = 12;
+
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+const scl = (a, s) => [a[0] * s, a[1] * s, a[2] * s];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+const vlen = (a) => Math.hypot(a[0], a[1], a[2]);
+const norm = (a) => { const m = vlen(a) || 1; return [a[0] / m, a[1] / m, a[2] / m]; };
+// Rotate vector v about unit axis k by angle ang (Rodrigues) — same math as
+// manifold-backend.js axisAngleMat4, applied to a vector.
+const rodrigues = (v, k, ang) => {
+  const c = Math.cos(ang), s = Math.sin(ang), kd = dot(k, v), kv = cross(k, v);
+  return [
+    v[0] * c + kv[0] * s + k[0] * kd * (1 - c),
+    v[1] * c + kv[1] * s + k[1] * kd * (1 - c),
+    v[2] * c + kv[2] * s + k[2] * kd * (1 - c),
+  ];
+};
+
+// Place the 2-D profile into 3-D at `center` using frame axes (N=profile-x, B=profile-y).
+const placeRing = (profile2D, center, N, B) =>
+  profile2D.map(([x, y]) => add(center, add(scl(N, x), scl(B, y))));
+
+export function resolveSweepStations(profile2D, path3D, { closed = false, cornerRadius = 0 } = {}) {
+  if (!Array.isArray(profile2D) || profile2D.length < 3)
+    throw new Error("sweep: profile2D must be an array of ≥3 [x,y] points");
+  if (!Array.isArray(path3D) || path3D.length < 2)
+    throw new Error("sweep: path3D must be an array of ≥2 [x,y,z] points");
+  for (let i = 0; i < path3D.length; i++) {
+    const p = path3D[i];
+    if (!Array.isArray(p) || p.length < 3 || !Number.isFinite(p[0]) || !Number.isFinite(p[1]) || !Number.isFinite(p[2]))
+      throw new Error(`sweep: path3D[${i}] must be a finite [x,y,z]`);
+  }
+  const P = path3D, m = P.length;
+  const segCount = closed ? m : m - 1;
+  const dir = [], segLen = [];
+  for (let k = 0; k < segCount; k++) {
+    const d = sub(P[(k + 1) % m], P[k]), l = vlen(d);
+    if (l < EPS) throw new Error(`sweep: path segment ${k} has zero length (coincident points ${k} and ${(k + 1) % m})`);
+    dir.push(scl(d, 1 / l)); segLen.push(l);
+  }
+  // profile half-width = the farthest a profile vertex reaches from its own origin
+  let maxReach = 0;
+  for (const [x, y] of profile2D) maxReach = Math.max(maxReach, Math.hypot(x, y));
+
+  // Seed the frame ⟂ the tangent coming INTO the first processed station (reference-vector
+  // method; the ref pick avoids N collapsing when the path starts along Z).
+  const seedT = closed ? dir[segCount - 1] : dir[0];
+  const ref = Math.abs(dot(seedT, Z)) < 0.9 ? Z : X;
+  let N = norm(sub(ref, scl(seedT, dot(ref, seedT))));
+  let B = cross(seedT, N);
+
+  const stations = [];
+
+  // Emit station(s) for an interior vertex and advance (N,B) from ⟂tIn to ⟂tOut.
+  const corner = (center, tIn, tOut, vtx, lenIn, lenOut) => {
+    const axisRaw = cross(tIn, tOut), s = vlen(axisRaw);
+    const cdot = Math.max(-1, Math.min(1, dot(tIn, tOut)));
+    if (cdot < -1 + 1e-6)
+      throw new Error(`sweep: 180° reversal at vertex ${vtx} is ambiguous — insert an intermediate point or use cornerRadius`);
+    if (s < EPS) { stations.push(placeRing(profile2D, center, N, B)); return; } // collinear: no turn, frame unchanged
+    const axis = scl(axisRaw, 1 / s);
+    const theta = Math.atan2(s, cdot);                    // exterior turn angle
+    if (cornerRadius > 0) {
+      if (cornerRadius < maxReach)
+        throw new Error(`sweep: cornerRadius ${cornerRadius} < profile half-width ${maxReach.toFixed(3)} at vertex ${vtx} — the inner wall would fold; increase cornerRadius`);
+      const t = cornerRadius * Math.tan(theta / 2);       // tangent setback along each leg (= r/tan(interiorHalf))
+      const tmax = Math.min(lenIn, lenOut) / 2;
+      if (t > tmax)
+        throw new Error(`sweep: cornerRadius too large for the bend at vertex ${vtx} (setback ${t.toFixed(3)} > half the shorter segment ${tmax.toFixed(3)}) — reduce cornerRadius or lengthen the segment`);
+      const a = sub(center, scl(tIn, t));                 // arc start on the incoming leg
+      const arcCenter = add(center, scl(norm(sub(tOut, tIn)), cornerRadius / Math.cos(theta / 2)));
+      const va = sub(a, arcCenter);
+      const steps = Math.max(2, Math.ceil(((theta * 180) / Math.PI) / ARC_STEP_DEG));
+      for (let i = 0; i <= steps; i++) {                  // smooth arc: rotate frame with the tangent, no miter tilt
+        const ang = (theta * i) / steps;
+        stations.push(placeRing(profile2D, add(arcCenter, rodrigues(va, axis, ang)),
+          rodrigues(N, axis, ang), rodrigues(B, axis, ang)));
+      }
+    } else {                                              // sharp miter: one station in the bisecting plane
+      if (maxReach * Math.tan(theta / 2) > 0.5 * Math.min(lenIn, lenOut))
+        throw new Error(`sweep: profile too wide for the bend at vertex ${vtx} (turn too sharp / segment too short) — increase cornerRadius or lengthen the segment`);
+      const Nh = rodrigues(N, axis, theta / 2), Bh = rodrigues(B, axis, theta / 2);
+      const mDir = rodrigues(tIn, axis, theta / 2);       // ring-plane normal (average travel dir)
+      const u = norm(cross(axis, mDir));                  // in-plane bend direction (stretch axis)
+      const cosh = Math.cos(theta / 2);
+      stations.push(profile2D.map(([x, y]) => {
+        const p = add(scl(Nh, x), scl(Bh, y));            // profile point in the miter plane (spanned by u, axis)
+        return add(center, add(scl(axis, dot(p, axis)), scl(u, dot(p, u) / cosh))); // stretch the u component
+      }));
+    }
+    N = rodrigues(N, axis, theta); B = rodrigues(B, axis, theta); // advance frame to ⟂ tOut
+  };
+
+  if (closed) {
+    for (let k = 0; k < m; k++)
+      corner(P[k], dir[(k - 1 + m) % m], dir[k], k, segLen[(k - 1 + m) % m], segLen[k]);
+  } else {
+    stations.push(placeRing(profile2D, P[0], N, B));      // start cap ring ⟂ dir[0]
+    for (let k = 1; k <= m - 2; k++) corner(P[k], dir[k - 1], dir[k], k, segLen[k - 1], segLen[k]);
+    stations.push(placeRing(profile2D, P[m - 1], N, B));  // end cap ring ⟂ dir[last]
+  }
+  return { stations, closed };
+}
+
+const centroid = (ring) => {
+  let cx = 0, cy = 0, cz = 0;
+  for (const [x, y, z] of ring) { cx += x; cy += y; cz += z; }
+  return [cx / ring.length, cy / ring.length, cz / ring.length];
+};
+
+// Manifold path: stack the resolved stations, stitch side quads, and (unless closed) fan a
+// cap over each end from its 3-D centroid. Winding self-heals via loft's signed-volume
+// check so the sweep is winding/direction-agnostic. Returns a raw Manifold (caller T()s).
+export function sweepMesh(wasm, profile2D, path3D, opts = {}) {
+  const { stations, closed } = resolveSweepStations(profile2D, path3D, opts);
+  const N = profile2D.length;
+  const V = [];
+  for (const ring of stations) for (const [x, y, z] of ring) V.push(x, y, z);
+  const Tr = [];
+  sideQuads(Tr, stations.length, N, closed);
+  if (!closed) {
+    fanCap(V, Tr, 0, N, centroid(stations[0]), true);                          // start cap faces backward
+    fanCap(V, Tr, (stations.length - 1) * N, N, centroid(stations[stations.length - 1]), false); // end faces forward
+  }
+  let out = manifoldFromMesh(wasm, V, Tr);
+  if (out.volume() < 0) { out.delete?.(); reverseWinding(Tr); out = manifoldFromMesh(wasm, V, Tr); }
+  return out;
+}

package/src/framework/geometry-service.js

@@ -9,10 +9,8 @@ export function createGeometryService({ createWorker, onMessage }) {
   const workers = { manifold: createWorker("manifold"), occt: createWorker("occt") };
   workers.manifold.onmessage = onMessage;
   workers.occt.onmessage = onMessage;
-  return {
-    generate: (msg, backend = "manifold") => workers[backend].postMessage(msg),
-    exportStl: (msg, backend = "manifold") => workers[backend].postMessage(msg),
-    export3mf: (msg, backend = "manifold") => workers[backend].postMessage(msg),
-    exportStep: (msg) => workers.occt.postMessage(msg), // STEP is always OCCT
-  };
+  // Post a job to the chosen backend's worker. The message's own `type` says what to
+  // do (generate / export-stl / export-3mf / export-step); `backend` picks the worker
+  // — manifold for preview/STL/3MF, occt for STEP (the caller passes "occt" for that).
+  return { send: (msg, backend = "manifold") => workers[backend].postMessage(msg) };
 }

package/src/framework/jobs.js

@@ -19,25 +19,44 @@ export function exportSubParts(part, view, params) {
   return viewSubParts(part, view, params).filter((name) => part.parts[name].exportable !== false);
 }
 
-// Handle one geometry job, posting results/progress via `post`. Backend-agnostic
-// and part-agnostic: every part specific comes through `part`.
+// Resolve a part's effective params + derived values for a build: the user's params
+// layered over the part defaults, and derive() run once over the result.
+export function resolveParams(part, params) {
+  const p = { ...part.defaults, ...params };
+  const d = part.derive ? part.derive(p) : {};
+  return { p, d };
+}
+
+// Build one sub-part and apply its optional place() for the given purpose/view.
+// `p`/`d` come from resolveParams(). This is the SINGLE definition of "a posed
+// sub-part solid" — the worker, the collision check, and the test harness all call
+// it, so display/export poses can never drift between the app and its tests.
+export function buildPosed(kernel, part, name, { purpose, view, p, d, onProgress } = {}) {
+  const sp = part.parts[name];
+  const solid = sp.build(kernel, p, d, onProgress);
+  return sp.place ? sp.place(solid, { view, purpose, p, d }) : solid;
+}
+
+// Handle one geometry job, posting results/progress via `post(msg, transfer?)`.
+// Backend-agnostic and part-agnostic: every part specific comes through `part`.
 //   { type:"generate", subparts, view, params } → { type:"meshes", meshes, ms }
 //   { type:"export-stl", view, params }         → { type:"download-parts", ext, mime, parts }
 //   { type:"export-step", view, params }        → { type:"download", data, filename, mime }
+// Each result branch declares its own transferables (the big binary buffers,
+// zero-copy across the worker boundary) right where the buffers are created —
+// so a new job type can't silently regress to structured-cloning its payload.
 // Progress is posted as { type:"progress", phase }. Export builds thread the
 // progress callback into build() so a part's own per-feature progress surfaces;
 // preview generates stay quiet (no callback) to avoid flicker during slider drags.
+const bufferOf = (data) => (ArrayBuffer.isView(data) ? data.buffer : data);
+
 export async function handle(kernel, part, msg, post) {
   const onProgress = (phase) => post({ type: "progress", phase });
-  const p = { ...part.defaults, ...msg.params };
-  const d = part.derive ? part.derive(p) : {};
+  const { p, d } = resolveParams(part, msg.params);
   const label = (name) => part.parts[name].label ?? name;
   const exportName = (name) => part.parts[name].export?.name ?? name;
-  const buildPosed = (name, purpose, view, prog) => {
-    const sp = part.parts[name];
-    const solid = sp.build(kernel, p, d, prog);
-    return sp.place ? sp.place(solid, { view, purpose, p, d }) : solid;
-  };
+  // Local shorthand over the shared helper: kernel/part/view/p/d are fixed per job.
+  const posed = (name, purpose, prog) => buildPosed(kernel, part, name, { purpose, view: msg.view, p, d, onProgress: prog });
 
   try {
     if (msg.type === "generate") {
@@ -48,37 +67,40 @@ export async function handle(kernel, part, msg, post) {
       for (const name of msg.subparts) {
         if (useCache) kernel.beginSubPart?.(name); // open the per-sub-part cache round
         try {
-          const m = buildPosed(name, "display", msg.view).toMesh({ quality: "preview" });
-          meshes.push({ name, positions: m.positions, normals: m.normals, indices: m.indices, triangles: m.triangles, edges: m.edges });
+          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 {
           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)
         }
       }
-      post({ type: "meshes", meshes, ms: Date.now() - t0, cache: kernel.cacheStats?.() });
+      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);
     } else if (msg.type === "export-stl") {
       const out = [];
       for (const name of exportSubParts(part, msg.view, p)) {
         onProgress(`building ${label(name)}`);
-        out.push({ name: exportName(name), data: await buildPosed(name, "export", msg.view, onProgress).toSTL({ quality: "print" }) });
+        out.push({ name: exportName(name), data: await posed(name, "export", onProgress).toSTL({ quality: "print" }) });
       }
-      post({ type: "download-parts", ext: "stl", mime: "model/stl", parts: out });
+      post({ type: "download-parts", ext: "stl", mime: "model/stl", parts: out }, out.map((p) => bufferOf(p.data)));
     } else if (msg.type === "export-step") {
       const solids = exportSubParts(part, msg.view, p).map((name) => {
         onProgress(`building ${label(name)}`);
-        return { name: exportName(name), solid: buildPosed(name, "export", msg.view, onProgress) };
+        return { name: exportName(name), solid: posed(name, "export", onProgress) };
       });
       onProgress("writing STEP file");
       const data = await kernel.toSTEP(solids);
-      post({ type: "download", data, filename: `${msg.view}.step`, mime: "application/step" });
+      post({ type: "download", data, filename: `${msg.view}.step`, mime: "application/step" }, [bufferOf(data)]);
     } else if (msg.type === "export-3mf") {
       const meshes = exportSubParts(part, msg.view, p).map((name) => {
         onProgress(`building ${label(name)}`);
-        const { positions, indices } = buildPosed(name, "export", msg.view, onProgress).toIndexedMesh();
+        const { positions, indices } = posed(name, "export", onProgress).toIndexedMesh();
         return { name: exportName(name), positions, indices };
       });
       onProgress("writing 3MF file");
-      post({ type: "download", data: meshTo3MF(meshes), filename: `${msg.view}.3mf`, mime: "model/3mf" });
+      const data = meshTo3MF(meshes);
+      post({ type: "download", data, filename: `${msg.view}.3mf`, mime: "model/3mf" }, [bufferOf(data)]);
     }
   } catch (err) {
     if (err?.code === "NEEDS_OCCT") post({ type: "needs-occt" });

package/src/framework/mesh-cache.js

@@ -0,0 +1,41 @@
+import { subPartReadKeys, relevanceHash, RELEVANT_ALL } from "./param-deps.js";
+
+// Tracks whether each sub-part's cached display mesh is still valid for the current
+// params ("Layer 1" of the cache — skipping regeneration of sub-parts whose inputs
+// didn't change). A sub-part's mesh is stamped with a relevance hash over just the
+// params that sub-part reads; it's current while that hash is unchanged and the mesh
+// is still in the viewer.
+//
+// The view/paramsVersion/caching state lives in mount and changes over time, so it's
+// passed as getters. `params` is a stable object mutated in place, so it's passed by
+// reference.
+export function createMeshCache(part, viewer, { params, getView, getParamsVersion, isCaching }) {
+  const cacheHash = {}; // name -> relevance hash the cached mesh was built at
+
+  // Memoize the per-sub-part read-key map per (paramsVersion, view): subPartReadKeys
+  // runs probe builds, so we compute it once per change, not per sub-part.
+  let readsKey = null, readsMap = null;
+  const readsFor = () => {
+    const key = `${getParamsVersion()}|${getView()}`;
+    if (readsKey !== key) { readsKey = key; readsMap = subPartReadKeys(part, getView(), params); }
+    return readsMap;
+  };
+
+  // The relevance hash for one sub-part at the current params (RELEVANT_ALL → hash
+  // over ALL params, so any edit invalidates it — the safe fallback).
+  const hashFor = (name) => {
+    if (!isCaching()) return `v${getParamsVersion()}`; // caching off: any edit invalidates every sub-part
+    const reads = readsFor();
+    const keys = reads === RELEVANT_ALL ? Object.keys(params) : [...(reads.get(name) ?? Object.keys(params))];
+    return relevanceHash(keys, params);
+  };
+
+  return {
+    // A cached sub-part is current only if its relevance hash is unchanged.
+    isCurrent: (name) => viewer.hasSubMesh(name) && cacheHash[name] === hashFor(name),
+    // Stamp a freshly built mesh with the hash it was built at.
+    record: (name) => { cacheHash[name] = hashFor(name); },
+    // Drop a sub-part's stamp so it rebuilds next generate.
+    forget: (name) => { delete cacheHash[name]; },
+  };
+}