partforge 0.28.0 → 0.32.0

package/README.md

@@ -128,6 +128,20 @@ so **the rail must be a direct child of the positioned `.pf-shell`** unless
 the host also supplies `elements.shell` to point at the real containing block
 (e.g. when a wrapper div sits between them, as is common in a React layout).
 
+`runtime.setParams(partial)` edits parameters programmatically — the entry point
+for animating a part from host code:
+
+```js
+runtime.setParams({ openAngle: 45 });   // merges into the live params, syncs the panel
+```
+
+The partial is merged into the current params and the control panel updates to
+match. Keys the part doesn't define are silently ignored. When every changed
+parameter only moves geometry (a rotation or translation in `place()`), the
+viewer re-poses the meshes it already has — instantly, with no worker rebuild;
+`onBuild` does not fire for those pose-only edits. Anything that changes the
+geometry itself rebuilds as usual.
+
 `onPick` arms click-to-select permanently: `label` is the feature label (falling
 back to the sub-part label/name) for compact UI, `prompt` is the LLM-ready
 sentence, `token` the compact form, `selection` the raw object. When `onPick` is

package/docs/AUTHORING-PARTS.md

@@ -337,6 +337,15 @@ their hash folds every shape-affecting argument (each `loft` ring's points/`z`/`
 profile's segment specs from `roundedProfile`, and the tessellation from `twist`), so
 changing any of them is a fresh cache node while an identical rebuild is a hit.
 
+This holds on **both backends** — and on OCCT, `translate`/`rotate` are additionally
+*pose-lazy*: the backend re-poses the cached solid's cached tessellation instead of
+re-running any B-rep work. A parameter that only feeds a final placement rotation (a
+lid's open angle, an exploded-view offset) therefore re-drags in ~0 ms even on the
+slow exact kernel — keep such transforms as the last ops in `build` (or in `place`)
+rather than baking them into the geometry earlier. In the app, such pose-only edits
+skip the worker entirely — the viewer re-poses the cached mesh — so they stay smooth
+even at animation rates (see `runtime.setParams`).
+
 ---
 
 ## Parameters: the control-panel schema
@@ -1210,6 +1219,63 @@ entirely on OCCT, its fillets are exact in the STEP **and** present in the print
 > `partforge measure` reports `watertight`/`holes` as `n/a` for OCCT parts (Manifold-only
 > topology); `render` works on both.
 
+### Cost: fillet/chamfer scale with edge count — and order matters
+
+OCCT fillet/chamfer cost is **per selected edge**, on top of the OCCT boolean tax the
+routing already imposes on the rest of the part. Two habits keep it tolerable:
+
+- **Fillet/chamfer as early as possible, on the simplest solid.** A fillet on a bare
+  primitive is ~15× cheaper than the same fillet after a dozen boolean cuts have
+  multiplied the face count — and because the solid cache keys each op by its input's
+  content hash, an early fillet is a cache **hit** when a downstream parameter changes,
+  while a fillet-last build re-pays the whole op on every slider step of every parameter.
+- **Never point a rim selector at a many-point extruded profile.** `edges: {inPlane}` on
+  a gear-like extrusion selects *every* polygon edge (hundreds); one chamfer call then
+  costs seconds — and if the distance doesn't fit the tooth lands, the failure-rescue
+  bisection re-runs it ~8× (`ERROR-PATTERNS.md#chamfer-rescue-bisection`). Use the loft
+  bevel below instead.
+
+### Beveling profile rims: extrude's bevel option
+
+For an **extruded profile** (gear, star, bracket outline — any `k.extrude` of a polygon),
+a top/bottom rim bevel doesn't need `chamfer` at all — it's built into `extrude`:
+
+```js
+k.extrude({ profile: prof, h: 5, bevel: 0.6 });                 // 45° bevel, both rims
+k.extrude({ profile: prof, h: 5, bevel: { top: 0.6 } });        // one rim only
+```
+
+Same 45° bevel a rim `chamfer` would cut, but it desugars into extrude + loft +
+intersect at the shared kernel front, so the part **stays on the fast Manifold
+backend** (no CAD-only op for the probe to find) and costs one boolean regardless of
+profile point count. Measured on a 24-tooth involute gear: ~0.1 s on Manifold vs
+~40 s for the equivalent OCCT `chamfer` (576-edge rim × the rescue bisection).
+
+Every profile form works: point arrays, arc profiles, `{outer, holes}` regions
+(hole rims flare outward — the opening is larger at the face, as a chamfer would
+cut it), and `Shape2D` (multi-region shapes bevel each region and union). One
+fidelity caveat: curved profiles are **materialized to point rings** first — the
+loft envelope needs matched points — so a beveled extrusion is faceted at the
+sampling LOD even in STEP export. Arc contours sample at a fixed LOD identically
+on both backends; a `Shape2D` materializes at its own backend's LOD. If you need
+arc-exact STEP walls, that's the one case native `chamfer` still buys you (at
+its OCCT cost).
+
+Rules (throws otherwise — `ERROR-PATTERNS.md#extrude-bevel-invalid`): no
+`twist`/`scaleTop`, and `bottom + top < h` — clamp from your height parameter, e.g.
+`bevel: Math.min(p.chamfer, p.thickness / 2 - 0.2)`. A bevel that would pinch a
+narrow feature shut (a gear's tooth land) is deterministically reduced to the
+largest offset the rim can take, with a console warning
+(`ERROR-PATTERNS.md#extrude-bevel-reduced`).
+
+Under the hood it insets the profile with `offsetPolygon(prof, -c, { corners:
+"sharp" })` and intersects with a loft envelope extended past both faces (so the
+envelope's own end caps never coincide with the extrusion's faces — coincident caps
+leave sliver-triangle shading artifacts). The same construction works by hand when
+you need a variant the option doesn't cover. This bevels a **whole rim**; for
+selective edges on a solid that's already OCCT-routed, plain `chamfer` with a tight
+selector is still the right tool.
+
 ---
 
 ## Conventions & gotchas

package/docs/ERROR-PATTERNS.md

@@ -47,7 +47,7 @@ test parses every one; keep prose like this as plain paragraphs):
 - **Cause:** replicad transforms and booleans (`translate`/`rotate`/`mirror`/`cut`/…) consume their operand — the input solid is deleted and a new one returned.
 - **Fix:** Never reuse a solid after transforming it; take a `.clone()` first when you need the original again. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API" (the `s.clone()` row).
 
-The framework itself rebuilds each sub-part fresh per job and applies `place` once, which avoids the problem — follow the same pattern in your own code.
+The framework itself rebuilds each sub-part fresh per job and applies `place` once, which avoids the problem — follow the same pattern in your own code. (Since the OCCT solid cache landed, the in-repo backend clones internally before every consuming replicad call, so wrapped `Solid`s effectively have value semantics and this crash should no longer reproduce through the kernel API — but the portable rule stands: per KERNEL-CONTRACT.md a backend MAY consume, so a part must still not rely on reuse.)
 
 ## probe-routed-to-occt
 
@@ -55,6 +55,34 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 - **Cause:** The geometry-free probe runs `build` against a recording proxy (dummy query values), and a `fillet`/`chamfer`/`shell` call it reaches — including a branch the real build wouldn't take, since queries return dummies — routes the whole part to OCCT.
 - **Fix:** Remove the CAD-only call the probe reaches unnecessarily, or force the backend with `meta.backend: "manifold"` (or `"occt"`). See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Fillet & chamfer (automatic OCCT backend)".
 
+## fillet-chamfer-many-edges-slow
+
+- **Symptom:** A part that fillets or chamfers the rim of an extruded profile (a gear, a star, any many-point polygon) takes many seconds — even tens of seconds — per build, with no error anywhere.
+- **Cause:** OCCT fillet/chamfer cost scales with the number of selected edges, and an `inPlane` rim selector on a many-point extruded profile selects every polygon edge (hundreds for a gear), so one op call costs seconds — and re-runs on every parameter change.
+- **Fix:** Use `extrude`'s `bevel` option instead of `chamfer` — same geometry, stays on the fast Manifold backend. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Beveling profile rims: extrude's bevel option".
+
+## chamfer-rescue-bisection
+
+- **Symptom:** `partforge: chamfer` warning saying the distance `over-ran the geometry — reduced to` a smaller one (or `has no valid distance`), with an attempt count and elapsed seconds, alongside slow builds.
+- **Cause:** The requested chamfer distance doesn't fit the geometry (it over-runs an adjacent face or a short edge), so the failure-rescue bisection in `occt-repair.js` re-runs the full chamfer up to 7 more times to find the largest valid distance — multiplying an already-expensive op by ~8× on every build, since the result is only cached per exact input hash.
+- **Fix:** Lower the chamfer parameter to at most the printed valid distance (the rescue then never fires), clamp it in `build` from the geometry that limits it, or — for extruded profile rims — switch to `extrude`'s `bevel` option, which finds its own limit in pure JS. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Beveling profile rims: extrude's bevel option".
+
+Variant literals under this entry: `partforge: chamfer <d> over-ran the geometry — reduced to <d'> (largest valid; <n> attempts, <t>s — see ERROR-PATTERNS.md#chamfer-rescue-bisection)`, `partforge: chamfer <d> has no valid distance for this geometry — feature skipped (<n> attempts, <t>s — see ERROR-PATTERNS.md#chamfer-rescue-bisection)`.
+
+## extrude-bevel-invalid
+
+- **Symptom:** `extrude: bevel must fit the height (bottom + top < h)` or `extrude: bevel cannot combine with twist or scaleTop` thrown from a build.
+- **Cause:** `extrude`'s `bevel` option desugars into offset-loft envelopes, which need an untwisted straight extrusion and room for both bevels inside the height.
+- **Fix:** Clamp the bevel from the height parameter (e.g. `Math.min(c, h / 2 - 0.2)`) and drop `twist`/`scaleTop`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Beveling profile rims: extrude's bevel option".
+
+Variant literals under this entry: `extrude: unknown bevel option`, `extrude: bevel must be a number or { bottom?, top? }`, `extrude: bevel distances must be finite numbers >= 0`.
+
+## extrude-bevel-reduced
+
+- **Symptom:** `partforge: extrude bevel` warning saying the requested distance `exceeds what the profile can take — reduced to` a smaller one (or `has no valid offset for this profile — rim left square`; `hole` in place of `profile` when a hole's flare is the limit).
+- **Cause:** Offsetting the rim by the bevel distance would pinch a narrow feature (a tooth land, a thin bar, a thin web beside a hole) shut, so the bevel deterministically backs off to the largest offset the outline can take — the same geometric limit OCCT's chamfer hits, resolved in pure JS instead of kernel re-runs.
+- **Fix:** Usually nothing — the reduced bevel is the correct maximum for the geometry. To silence it, clamp the bevel parameter below the printed value or widen the narrow feature.
+
 ## boolean-not-watertight
 
 - **Symptom:** `NOT watertight ✗` from `partforge measure` (non-zero exit) after adding a boolean cut or union.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.28.0",
+  "version": "0.32.0",
   "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/controls.js

@@ -218,6 +218,7 @@ export function buildControls(root, parameters, params, onDirty) {
   const info = createInfoPopover();
   const controls = []; // { key, el } per control element
   const sections = []; // { el, keys:Set } per rendered section
+  const syncFns = []; // { key, sync } for every widget that can re-read params
   for (const sec of parameters) {
     if (!sectionRenders(sec)) continue;
     const section = el("div", "section");
@@ -225,7 +226,11 @@ export function buildControls(root, parameters, params, onDirty) {
     attachInfo(title, sec.description, info);
     section.append(title);
     const keys = new Set();
-    const register = (key, node) => { controls.push({ key, el: node }); keys.add(key); };
+    const register = (key, node, sync) => {
+      controls.push({ key, el: node });
+      keys.add(key);
+      if (sync) syncFns.push({ key, sync });
+    };
     if (sec.features) buildFeatureSection(section, sec, params, onDirty, register, info);
     else buildPresetSection(section, sec, params, onDirty, register, info);
     root.append(section);
@@ -233,6 +238,12 @@ export function buildControls(root, parameters, params, onDirty) {
   }
   return {
     applyRelevance: (relevant) => applyRelevance(relevant, controls, sections),
+    // Re-read params into the widgets — all of them, or just `keys`. The
+    // programmatic twin of a user edit (setParams); never fires onDirty.
+    syncValues: (keys) => {
+      const only = keys && new Set(keys);
+      for (const { key, sync } of syncFns) if (!only || only.has(key)) sync();
+    },
     dispose: () => { info.dispose(); root.replaceChildren(); },
   };
 }
@@ -263,7 +274,7 @@ function buildPresetSection(section, sec, params, onDirty, register, info) {
     attachInfo(lbl, t.description, info);
     row.append(box, lbl);
     box.addEventListener("change", () => { params[t.key] = box.checked ? (t.on ?? 1) : 0; onDirty?.(); });
-    register(t.key, row);
+    register(t.key, row, () => { box.checked = params[t.key] > 0; });
     section.append(row);
   }
 
@@ -274,8 +285,11 @@ function buildPresetSection(section, sec, params, onDirty, register, info) {
     for (const def of advanced) {
       const s = makeParameterControl(def, params, () => { if (preset) preset.value = "Custom"; onDirty?.(); }, info);
       adv.append(s.wrap);
-      syncs[def.key] = s.sync;
-      register(def.key, s.wrap);
+      syncs[def.key] = s.sync; // raw: preset APPLICATION must not mark itself Custom
+      // A programmatic edit diverges from the preset exactly as a user edit does,
+      // so the picker falls back to Custom — leaving a stale preset name selected
+      // would also make it unre-appliable (no change event for the current option).
+      register(def.key, s.wrap, () => { s.sync(); if (preset) preset.value = "Custom"; });
     }
     section.append(toggle, adv);
   }
@@ -306,7 +320,12 @@ function buildFeatureSection(section, sec, params, onDirty, register, info) {
     const featLabel = el("span", "", feat.label);
     attachInfo(featLabel, feat.description, info);
     checkRow.append(box, featLabel);
-    register(feat.key, checkRow);
+    // `group` is created just below — the sync only ever runs after this
+    // function returns, so the closure is safely bound by then.
+    register(feat.key, checkRow, () => {
+      box.checked = params[feat.key] > 0;
+      group.classList.toggle("hidden", !box.checked);
+    });
 
     const group = el("div", "feat-group");
     const syncs = [];
@@ -314,7 +333,7 @@ function buildFeatureSection(section, sec, params, onDirty, register, info) {
       const s = makeParameterControl(def, params, onDirty, info);
       group.append(s.wrap);
       syncs.push(s.sync);
-      register(def.key, s.wrap);
+      register(def.key, s.wrap, s.sync);
     }
     group.classList.toggle("hidden", !box.checked);
 

package/src/framework/debug-overlay.js

@@ -43,13 +43,21 @@ export function createDebugOverlay({ initialCachingOn = true, onToggle } = {}) {
 
   cb.addEventListener("change", () => onToggle?.(cb.checked));
 
+  // What's currently on screen. update() MERGES over it, so a caller reporting one
+  // figure doesn't blank the others: a pose-only edit ran no build and no L2 ops,
+  // and would otherwise wipe the last build's timing back to "—" on its way to
+  // showing a posed count.
+  const shown = { ms: null, hits: 0, misses: 0, skipped: 0, rebuilt: 0, posed: 0 };
+
   return {
-    update({ ms, hits = 0, misses = 0, skipped = 0, rebuilt = 0 } = {}) {
+    update(counts = {}) {
+      Object.assign(shown, counts);
+      const { ms, hits, misses, skipped, rebuilt, posed } = shown;
       const l2 = cb.checked ? `${hits} hit / ${misses} miss` : "off";
       readout.textContent =
         `build: ${ms != null ? Math.round(ms) + " ms" : "—"}\n` +
         `L2 ops: ${l2}\n` +
-        `L1 parts: ${skipped} skipped / ${rebuilt} rebuilt`;
+        `L1 parts: ${skipped} skipped / ${rebuilt} rebuilt / ${posed} posed`;
     },
     detach: () => box.remove(),
   };

package/src/framework/download.js

@@ -2,9 +2,16 @@ import { zipSync } from "fflate";
 
 // Browser file-download helpers. Pure DOM/Blob utilities with no app state — the
 // worker produces the bytes; these just hand them to the browser as a download.
+//
+// `sink` is an optional escape hatch for embedders that cannot download from
+// their own document — e.g. partforge running inside a null-origin sandboxed
+// iframe, where a blob: URL is blob:null and browsers such as WebKit refuse to
+// load it. When `sink` is supplied it receives the FINAL bytes and no DOM work
+// happens here; the embedder saves them from a context that can.
 
-// Trigger a download of one binary blob under `filename`.
-export function triggerDownload(data, filename, mime) {
+// Trigger a download of one binary blob under `filename` (or hand it to `sink`).
+export function triggerDownload(data, filename, mime, sink) {
+  if (typeof sink === "function") { sink({ data, filename, mime }); return; }
   const url = URL.createObjectURL(new Blob([data], { type: mime }));
   const a = document.createElement("a");
   a.href = url;
@@ -14,10 +21,11 @@ export function triggerDownload(data, filename, mime) {
 }
 
 // Download a set of built parts: a single part downloads directly; multiple parts
-// are bundled into one flat, store-only (level 0) zip named `zipName`.
-export function downloadParts({ parts, ext, mime }, zipName) {
-  if (parts.length === 1) return triggerDownload(parts[0].data, `${parts[0].name}.${ext}`, mime);
+// are bundled into one flat, store-only (level 0) zip named `zipName`. `sink`, if
+// given, is forwarded to triggerDownload so it receives the final bytes.
+export function downloadParts({ parts, ext, mime }, zipName, sink) {
+  if (parts.length === 1) return triggerDownload(parts[0].data, `${parts[0].name}.${ext}`, mime, sink);
   const entries = {};
   for (const p of parts) entries[`${p.name}.${ext}`] = new Uint8Array(p.data);
-  triggerDownload(zipSync(entries, { level: 0 }), zipName, "application/zip");
+  triggerDownload(zipSync(entries, { level: 0 }), zipName, "application/zip", sink);
 }

package/src/framework/geometry/kernel-front.js

@@ -25,6 +25,7 @@ const opentype = typeof opentypeNamespace.parse === "function"
 import { KernelCapabilityError } from "./errors.js";
 import { isPlainOptions, KERNEL_OP_SPECS } from "./op-options.js";
 import { textGlyphs } from "./text2d.js";
+import { beveledExtrude } from "./rim-bevel.js";
 import { DEFAULT_FONT_BYTES } from "./fonts/default-font.js";
 import { convexHull, hullPoints } from "./hull.js";
 
@@ -45,6 +46,16 @@ export function finishKernel(k) {
     };
   }
 
+  // extrude({ bevel }) desugars here — before the spec-wrapped op ever sees it —
+  // into extrude + loft + intersect (rim-bevel.js), so both backends share one
+  // implementation and the probe records no CAD-only op. beveledExtrude calls
+  // back into the wrapped k.extrude/k.loft, so caching and validation apply.
+  const specExtrude = k.extrude;
+  k.extrude = (...a) =>
+    a.length === 1 && isPlainOptions(a[0]) && a[0].bevel !== undefined
+      ? beveledExtrude(k, a[0])
+      : specExtrude(...a);
+
   k.toSTEP ??= () => { throw new KernelCapabilityError("toSTEP requires the OCCT backend"); };
   k.shape2d ??= () => { throw new KernelCapabilityError("shape2d requires the Manifold backend"); };
 

package/src/framework/geometry/kernel.js

@@ -99,7 +99,7 @@ export const OCCT_ONLY_OPS = ["fillet", "chamfer", "shell"];
  * @property {(o:{r?:number,d?:number}) => Solid} sphere   sphere centred at the origin; {r|d}; bare sphere(r) stays valid
  * @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}) => Solid} extrude   polygon-with-holes region from z=0; legacy (profile,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:{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

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

@@ -8,6 +8,7 @@ import { addSugar } from "./solid-sugar.js";
 import { addShape2dSugar } from "./shape2d-sugar.js";
 import { assembleRegions } from "./shape2d-regions.js";
 import { finishKernel } from "./kernel-front.js";
+import { meshToStl } from "./mesh-stl.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
@@ -363,21 +364,14 @@ function creasedNormals(g, sharpCos, featureLabels) {
 }
 
 function stlFromMesh(g) {
-  const tris = g.triVerts, vp = g.vertProperties, np = g.numProp, n = tris.length / 3;
-  const ab = new ArrayBuffer(84 + n * 50); const dv = new DataView(ab); dv.setUint32(80, n, true);
-  let o = 84; const P = (i) => [vp[i*np], vp[i*np+1], vp[i*np+2]];
-  for (let i = 0; i < n; i++) {
-    const a = P(tris[i*3]), b = P(tris[i*3+1]), c = P(tris[i*3+2]);
-    // Per-facet flat normal from the winding (Manifold is CCW → outward). Slicers
-    // recompute this, but viewers that light from the stored normal (macOS
-    // Preview/Quick Look) render the mesh unlit if it's left as zero.
-    const ux = b[0]-a[0], uy = b[1]-a[1], uz = b[2]-a[2];
-    const vx = c[0]-a[0], vy = c[1]-a[1], vz = c[2]-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;
-    dv.setFloat32(o, nx/L, true); dv.setFloat32(o+4, ny/L, true); dv.setFloat32(o+8, nz/L, true); o += 12;
-    for (const p of [a, b, c]) for (const x of p) { dv.setFloat32(o, x, true); o += 4; }
-    dv.setUint16(o, 0, true); o += 2;
+  const vp = g.vertProperties, np = g.numProp;
+  const nVert = (vp.length / np) | 0;
+  let positions;
+  if (np === 3) {
+    positions = vp; // already x,y,z per vertex
+  } else {
+    positions = new Float32Array(nVert * 3);
+    for (let i = 0; i < nVert; i++) { positions[i*3] = vp[i*np]; positions[i*3+1] = vp[i*np+1]; positions[i*3+2] = vp[i*np+2]; }
   }
-  return ab;
+  return meshToStl(positions, g.triVerts);
 }

package/src/framework/geometry/mesh-stl.js

@@ -0,0 +1,27 @@
+// Pure-JS binary STL writer, shared by both geometry backends. Takes a flat
+// vertex-position array (x,y,z per vertex) and triangle indices, and returns a
+// binary STL ArrayBuffer. STL is a triangle-mesh format, so this is the one and
+// only STL path — OCCT and Manifold both feed it a mesh. It deliberately does
+// NOT touch Blobs: the sandbox worker on Safari cannot read a Blob, so every
+// export must hand back a raw ArrayBuffer.
+export function meshToStl(positions, indices) {
+  const n = (indices.length / 3) | 0;
+  const ab = new ArrayBuffer(84 + n * 50);
+  const dv = new DataView(ab);
+  dv.setUint32(80, n, true); // triangle count (80-byte header left zero)
+  let o = 84;
+  const P = (i) => [positions[i * 3], positions[i * 3 + 1], positions[i * 3 + 2]];
+  for (let i = 0; i < n; i++) {
+    const a = P(indices[i * 3]), b = P(indices[i * 3 + 1]), c = P(indices[i * 3 + 2]);
+    // Per-facet flat normal from the winding. Slicers recompute this, but some
+    // viewers (macOS Preview/Quick Look) render unlit if it's left zero.
+    const ux = b[0] - a[0], uy = b[1] - a[1], uz = b[2] - a[2];
+    const vx = c[0] - a[0], vy = c[1] - a[1], vz = c[2] - 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;
+    dv.setFloat32(o, nx / L, true); dv.setFloat32(o + 4, ny / L, true); dv.setFloat32(o + 8, nz / L, true); o += 12;
+    for (const p of [a, b, c]) for (const x of p) { dv.setFloat32(o, x, true); o += 4; }
+    dv.setUint16(o, 0, true); o += 2;
+  }
+  return ab;
+}