npm - partforge - Versions diffs - 0.35.0 → 0.36.1 - Mend

partforge 0.35.0 → 0.36.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/docs/AUTHORING-PARTS.md +18 -0
package/docs/KERNEL-CONTRACT.md +1 -1
package/package.json +1 -1
package/src/framework/export-controller.js +54 -0
package/src/framework/export-select.js +15 -0
package/src/framework/geometry/occt-backend.js +10 -4
package/src/framework/geometry/threemf.js +50 -3
package/src/framework/jobs.js +25 -11
package/src/framework/mount.js +34 -5

package/docs/AUTHORING-PARTS.md CHANGED Viewed

@@ -705,6 +705,24 @@ Copy `demo.html` and change the title, the panel heading, and the `<script src>`
 workers are spawned from your one worker entry (`name` = `"manifold"` for preview/STL/3MF,
 `"occt"` for STEP — handled for you).
+**Headless export (the mount handle).** The `#download*` buttons above are the built-in,
+view-bound export UI. An embedder that wants its own export UI (e.g. a "pick which parts,
+pick a format" modal) can skip those buttons and drive export off the handle `mount()`
+returns instead:
+- `runtime.listExportableParts() → [{ name, label }]` — every exportable sub-part
+  (excludes any `exportable: false` part, respects each part's `enabled(params)`),
+  **independent of the active view**. Use it to populate an export checklist.
+- `runtime.exportParts({ parts, format, quality?, onProgress }) → Promise<void>` — build
+  the given `parts` (sub-part names) in `format` (`"stl" | "step" | "3mf"`), streaming
+  phase strings to `onProgress(phase)`. Resolves once the file is written (handed to your
+  `onDownload` sink, or downloaded directly if you don't supply one); rejects on
+  build/export failure or an empty selection. Placement uses the current
+  view. STEP is routed to OCCT automatically.
+Pass `onDownload({ data, filename, mime })` to `mount()` to receive the exported bytes
+yourself (e.g. to download from a different origin) instead of partforge's own DOM download.
 **The markup convention (`demo.html` is the canonical copy-me page):** `<body>` carries
 `class="pf-shell"`, the flex row that lays the viewer column next to the rail. `#app`
 (`class="pf-stage"`) *is* that viewer column, and now contains the floating chrome

package/docs/KERNEL-CONTRACT.md CHANGED Viewed

@@ -222,7 +222,7 @@ Normative signatures: `kernel.js`'s `@typedef Solid`.
 | `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. |
 | `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()` | `{positions, indices}` indexed mesh (3MF path). |
+| `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. |
 `quality` (`"preview"` | `"print"`) is **advisory**: it trades tessellation density for

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.35.0",
+  "version": "0.36.1",
   "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/export-controller.js ADDED Viewed

@@ -0,0 +1,54 @@
+// src/framework/export-controller.js
+// Owns the jobId correlation for headless exportParts(): matches worker
+// replies (progress/download/error) back to the Promise that started them.
+// Pure — no DOM, no worker; `send` and the sink are injected.
+import { triggerDownload, downloadParts } from "./download.js";
+export function createExportController({ send, currentView, title, defaultBackend = () => "manifold", currentParams = () => ({}) }) {
+  const pending = new Map(); // jobId -> { resolve, reject, onProgress }
+  let nextId = 1;
+  function exportParts({ parts, format, quality = "print", onProgress } = {}) {
+    const jobId = nextId++;
+    const type = `export-${format}`;
+    const backend = format === "step" ? "occt" : defaultBackend();
+    return new Promise((resolve, reject) => {
+      pending.set(jobId, { resolve, reject, onProgress });
+      send({ type, jobId, parts, view: currentView(), params: currentParams(), name: title(), quality }, backend);
+    });
+  }
+  // Returns true iff this message belonged to a pending export (so the caller
+  // can skip legacy handling). `sink` is partforge's onDownload.
+  function handleMessage(m, sink) {
+    const entry = m && m.jobId != null ? pending.get(m.jobId) : undefined;
+    if (!entry) return false;
+    if (m.type === "progress") { entry.onProgress?.(m.phase); return true; }
+    if (m.type === "download") {
+      pending.delete(m.jobId);
+      triggerDownload(m.data, m.filename, m.mime, sink);
+      entry.resolve();
+      return true;
+    }
+    if (m.type === "download-parts") {
+      pending.delete(m.jobId);
+      const zipName = `${title() ?? "parts"}.zip`.toLowerCase().replace(/\s+/g, "-");
+      downloadParts(m, zipName, sink);
+      entry.resolve();
+      return true;
+    }
+    if (m.type === "error") { pending.delete(m.jobId); entry.reject(new Error(m.message)); return true; }
+    if (m.type === "needs-occt") { pending.delete(m.jobId); entry.reject(new Error("needs OCCT backend")); return true; }
+    return false;
+  }
+  // Reject every in-flight export and clear the map — for teardown / worker
+  // death, where worker replies will never arrive to settle these Promises.
+  function dispose(reason) {
+    const err = new Error(reason ?? "export cancelled");
+    for (const entry of pending.values()) entry.reject(err);
+    pending.clear();
+  }
+  return { exportParts, handleMessage, dispose };
+}

package/src/framework/export-select.js ADDED Viewed

@@ -0,0 +1,15 @@
+// Pure selection helpers for headless export. No kernel, no DOM.
+export function partLabel(part, name) {
+  return part.parts[name]?.label ?? name;
+}
+// The union of sub-parts eligible for export, independent of the active view:
+// exportable (not exportable:false) AND enabled under the current params.
+export function exportablePartNames(part, params) {
+  return Object.keys(part.parts).filter((name) => {
+    const sp = part.parts[name];
+    if (sp.exportable === false) return false;
+    return sp.enabled ? !!sp.enabled(params) : true;
+  });
+}

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

@@ -34,7 +34,7 @@ const MESH = { preview: { tolerance: 0.1, angularTolerance: 0.5 }, print: { tole
 export function createOcctKernel(replicad) {
   const { makeCylinder, makeBox, makeCircle, makeHelix, assembleWire, genericSweep,
-          makeCompound, loft, draw, exportSTEP, measureVolume, makeSphere, makeLine, Plane } = replicad;
+          loft, draw, exportSTEP, measureVolume, makeSphere, makeLine, Plane } = replicad;
   // Fillet/chamfer/shell failure recovery (skip-on-failure, chamfer binary search) —
   // see occt-repair.js for the policies and why they differ per op.
@@ -127,8 +127,12 @@ export function createOcctKernel(replicad) {
         const key = h("cutAll", hash, tools.map((t) => t._hash));
         return cached(key, () => {
           const a = mat(), bs = tools.map((t) => t._mat());
+          if (bs.length === 0) return wrap(a._s.clone(), cloneLabels(a._labels), key);
+          const fusedTools = bs
+            .slice(1)
+            .reduce((acc, b) => acc.fuse(b._s.clone()), bs[0]._s.clone());
           return wrap(
-            a._s.clone().cut(makeCompound(bs.map((b) => b._s.clone()))),
+            a._s.clone().cut(fusedTools),
             [...cloneLabels(a._labels), ...bs.flatMap((b) => cloneLabels(b._labels))],
             key,
           );
@@ -210,8 +214,10 @@ export function createOcctKernel(replicad) {
         });
       },
       volume: () => measureVolume(mat()._s),
-      toIndexedMesh: () => {
-        const base = baseMesh("preview");
+      // Same default as toSTL: an export is an export, so a .3mf must not ship a
+      // coarser tessellation than the .stl of the same solid would.
+      toIndexedMesh: ({ quality = "print" } = {}) => {
+        const base = baseMesh(quality);
         return { positions: posedPositions(base), indices: Uint32Array.from(base.indices) };
       },
     });

package/src/framework/geometry/threemf.js CHANGED Viewed

@@ -19,6 +19,54 @@ const RELS =
 const xmlEsc = (s) => String(s).replace(/[<>&"]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", '"': "&quot;" }[c]));
 const r = (x) => +x.toFixed(4); // 0.1 µm precision — finer than any printer, much smaller XML
+// Weld coincident vertices and drop triangles that collapse to zero area.
+//
+// This is what keeps a .3mf manifold, and it has no STL equivalent: STL is vertex
+// soup, so a consumer re-stitches triangles by POSITION and never sees how the
+// mesh was indexed. 3MF reads topology from the indices instead, so two triangles
+// that meet along an edge must literally cite the same two vertex ids — otherwise
+// each counts the shared edge as its own boundary and slicers report the solid as
+// non-manifold. The OCCT backend triangulates every B-rep face independently and
+// concatenates the results, so it hands us one copy of each seam vertex PER
+// adjacent face; welding here is what closes that mesh. (Manifold's own output is
+// already welded, so for that backend this is a no-op beyond the copy.)
+//
+// Welding uses `r` — exactly the precision the file is written at — so any two
+// vertices that would print identical coordinates always collapse to one id. A
+// looser tolerance would move geometry; a tighter one would leave split vertices
+// sitting at coordinates the file cannot tell apart.
+function weld(positions, indices) {
+  const idOf = new Map(); // "x,y,z" → canonical vertex id
+  const coord = []; // canonical id → rounded x,y,z (flat)
+  const canon = new Uint32Array(positions.length / 3);
+  for (let i = 0, v = 0; i < positions.length; i += 3, v++) {
+    const x = r(positions[i]), y = r(positions[i + 1]), z = r(positions[i + 2]);
+    const key = `${x},${y},${z}`;
+    let id = idOf.get(key);
+    if (id === undefined) { id = coord.length / 3; idOf.set(key, id); coord.push(x, y, z); }
+    canon[v] = id;
+  }
+  // Emit vertices in order of first use by a surviving triangle, so a vertex left
+  // behind by a dropped degenerate never ships as an unreferenced <vertex>.
+  const emitted = new Map(); // canonical id → written vertex index
+  const verts = [], tris = [];
+  const emit = (id) => {
+    let at = emitted.get(id);
+    if (at === undefined) {
+      at = verts.length / 3;
+      emitted.set(id, at);
+      verts.push(coord[id * 3], coord[id * 3 + 1], coord[id * 3 + 2]);
+    }
+    return at;
+  };
+  for (let k = 0; k < indices.length; k += 3) {
+    const a = canon[indices[k]], b = canon[indices[k + 1]], c = canon[indices[k + 2]];
+    if (a === b || b === c || a === c) continue; // zero area at print precision — carries no surface
+    tris.push(emit(a), emit(b), emit(c));
+  }
+  return { verts, tris };
+}
 // parts: [{ name, positions: Float32Array (x,y,z per vertex), indices: Uint32Array (3 per triangle) }]
 // → ArrayBuffer of the .3mf zip (millimetre units; one <object> + <build> item per part).
 export function meshTo3MF(parts) {
@@ -29,10 +77,9 @@ export function meshTo3MF(parts) {
   ];
   parts.forEach((p, i) => {
     out.push(`<object id="${i + 1}" type="model" name="${xmlEsc(p.name)}"><mesh><vertices>`);
-    const v = p.positions;
-    for (let k = 0; k < v.length; k += 3) out.push(`<vertex x="${r(v[k])}" y="${r(v[k + 1])}" z="${r(v[k + 2])}"/>`);
+    const { verts: v, tris: t } = weld(p.positions, p.indices);
+    for (let k = 0; k < v.length; k += 3) out.push(`<vertex x="${v[k]}" y="${v[k + 1]}" z="${v[k + 2]}"/>`);
     out.push("</vertices><triangles>");
-    const t = p.indices;
     for (let k = 0; k < t.length; k += 3) out.push(`<triangle v1="${t[k]}" v2="${t[k + 1]}" v3="${t[k + 2]}"/>`);
     out.push("</triangles></mesh></object>");
   });

package/src/framework/jobs.js CHANGED Viewed

@@ -1,4 +1,5 @@
 import { meshTo3MF } from "./geometry/threemf.js";
+import { exportablePartNames } from "./export-select.js";
 import { resolveDerived } from "./derive.js";
 import { resolveFonts } from "./fonts.js";
 import { measure } from "../testing/measure.js";
@@ -58,7 +59,7 @@ const bufferOf = (data) => (ArrayBuffer.isView(data) ? data.buffer : data);
 export async function handle(kernel, part, msg, post, opts = {}) {
   const isStale = opts.isStale ?? (() => false);
-  const onProgress = (phase) => post({ type: "progress", phase });
+  const onProgress = (phase) => post({ type: "progress", phase, jobId: msg.jobId });
   const label = (name) => part.parts[name].label ?? name;
   const exportName = (name) => part.parts[name].export?.name ?? name;
@@ -76,6 +77,12 @@ export async function handle(kernel, part, msg, post, opts = {}) {
     const { p, d } = resolveParams(part, msg.params);
     // 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 });
+    // Explicit selection (headless exportParts) overrides view-derived selection.
+    const selected = () =>
+      msg.parts
+        ? exportablePartNames(part, p).filter((name) => msg.parts.includes(name))
+        : exportSubParts(part, msg.view, p);
+    const fileBase = msg.name ?? msg.view; // STEP/3MF single-file name base
     if (msg.type === "generate") {
       const t0 = Date.now();
@@ -105,29 +112,36 @@ export async function handle(kernel, part, msg, post, opts = {}) {
         [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 names = selected();
+      if (names.length === 0) throw new Error("no exportable parts selected");
       const out = [];
-      for (const name of exportSubParts(part, msg.view, p)) {
+      for (const name of names) {
         onProgress(`building ${label(name)}`);
-        out.push({ name: exportName(name), data: await posed(name, "export", onProgress).toSTL({ quality: "print" }) });
+        out.push({ name: exportName(name), data: await posed(name, "export", onProgress).toSTL({ quality: msg.quality ?? "print" }) });
       }
-      post({ type: "download-parts", ext: "stl", mime: "model/stl", parts: out }, out.map((p) => bufferOf(p.data)));
+      post({ type: "download-parts", ext: "stl", mime: "model/stl", parts: out, jobId: msg.jobId },
+           out.map((pp) => bufferOf(pp.data)));
     } else if (msg.type === "export-step") {
-      const solids = exportSubParts(part, msg.view, p).map((name) => {
+      const names = selected();
+      if (names.length === 0) throw new Error("no exportable parts selected");
+      const solids = names.map((name) => {
         onProgress(`building ${label(name)}`);
         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" }, [bufferOf(data)]);
+      post({ type: "download", data, filename: `${fileBase}.step`, mime: "application/step", jobId: msg.jobId }, [bufferOf(data)]);
     } else if (msg.type === "export-3mf") {
-      const meshes = exportSubParts(part, msg.view, p).map((name) => {
+      const names = selected();
+      if (names.length === 0) throw new Error("no exportable parts selected");
+      const meshes = names.map((name) => {
         onProgress(`building ${label(name)}`);
-        const { positions, indices } = posed(name, "export", onProgress).toIndexedMesh();
+        const { positions, indices } = posed(name, "export", onProgress).toIndexedMesh({ quality: msg.quality ?? "print" });
         return { name: exportName(name), positions, indices };
       });
       onProgress("writing 3MF file");
       const data = meshTo3MF(meshes);
-      post({ type: "download", data, filename: `${msg.view}.3mf`, mime: "model/3mf" }, [bufferOf(data)]);
+      post({ type: "download", data, filename: `${fileBase}.3mf`, mime: "model/3mf", jobId: msg.jobId }, [bufferOf(data)]);
     } else if (msg.type === "inspect") {
       // Full geometric oracle for the current view: solid facts (volume/genus/
       // watertight), mesh facts, overlaps, and gap distances, plus the part's
@@ -142,8 +156,8 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       post({ type: "report", ...report });
     }
   } catch (err) {
-    if (err?.code === "NEEDS_OCCT") post({ type: "needs-occt" });
-    else post({ type: "error", message: String(err?.message || err) });
+    if (err?.code === "NEEDS_OCCT") post({ type: "needs-occt", jobId: msg.jobId });
+    else post({ type: "error", message: String(err?.message || err), jobId: msg.jobId });
   } finally {
     kernel.cleanup?.();
   }

package/src/framework/mount.js CHANGED Viewed

@@ -20,11 +20,18 @@ import { createStatusUi } from "./status-ui.js";
 import { createViewTabs } from "./view-tabs.js";
 import { attachPickToggle, attachHoverLabels, attachPicker, formatSelection } from "./selection/index.js";
 import { createPickRequestClient } from "./pick-request/index.js";
+import { exportablePartNames, partLabel } from "./export-select.js";
+import { createExportController } from "./export-controller.js";
 // The mount handle, factored out so its shape is unit-testable without booting
 // the full mount() pipeline (WASM + workers + DOM).
-export function makeHandle({ ready, dispose, viewer, setParams }) {
-  return { ready, dispose, setParams, captureViews: (viewNames) => viewer.captureCanonicalViews(viewNames) };
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts }) {
+  return {
+    ready, dispose, setParams,
+    captureViews: (viewNames) => viewer.captureCanonicalViews(viewNames),
+    listExportableParts,
+    exportParts,
+  };
 }
 function createCleanupStack() {
@@ -56,10 +63,16 @@ function createCleanupStack() {
 // mesh-validity cache, and the geometry workers. The app supplies `createWorker(name)`
 // so Vite can bundle the worker (see geometry-service.js).
 //
-// Embedding contract (0.12.0):
-//   const runtime = mount(part, { createWorker, elements, onBuild, onPick });
+// Embedding contract (0.36.0):
+//   const runtime = mount(part, { createWorker, elements, onBuild, onPick, onDownload });
 //   await runtime.ready;   // first successful build of the default view
 //   runtime.setParams({ openAngle: 45 }); // programmatic edit; pose-only changes apply instantly
+//   runtime.listExportableParts();        // [{ name, label }] — every exportable sub-part,
+//                                         // independent of the active view (for an embedder-drawn export UI)
+//   await runtime.exportParts({ parts: ["base"], format: "stl", onProgress });
+//                                         // headless export of a chosen subset; resolves when the file is
+//                                         // written (handed to your onDownload sink, or downloaded directly
+//                                         // if you don't supply one), rejects on failure
 //   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.
@@ -279,6 +292,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // --- shared message handler ------------------------------------------------
     function onWorkerMessage({ data }) {
+      // Headless exportParts() correlation: consume its own replies first.
+      if (exportCtl.handleMessage(data, onDownload)) return;
       switch (data.type) {
         case "ready":
           loop.ready(); // auto-build the default view (keeps the busy spinner up)
@@ -338,6 +353,15 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     const service = createGeometryService({ createWorker, onMessage: onWorkerMessage });
     cleanup.defer(() => service.terminate());
+    const exportCtl = createExportController({
+      send: (msg, backend) => service.send(msg, backend),
+      currentView: () => view(),
+      title: () => part.meta?.title ?? "parts",
+      defaultBackend: () => backendFor(),
+      currentParams: () => params,
+    });
+    cleanup.defer(() => exportCtl.dispose("viewer disposed"));
     const panel = buildControls(els.controls, part.parameters, params, onParamChange);
     cleanup.defer(() => panel.dispose());
     const updateRelevance = () => panel.applyRelevance(relevantParamKeys(part, view(), params));
@@ -417,7 +441,12 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       cleanup.dispose();
     }
-    return makeHandle({ ready, dispose, viewer, setParams });
+    return makeHandle({
+      ready, dispose, viewer, setParams,
+      listExportableParts: () =>
+        exportablePartNames(part, params).map((name) => ({ name, label: partLabel(part, name) })),
+      exportParts: (opts) => exportCtl.exportParts(opts),
+    });
   } catch (error) {
     try {
       cleanup.dispose();