partforge 0.115.0 → 0.117.0

package/docs/AUTHORING-PARTS.md

@@ -3650,6 +3650,24 @@ symptom first** — it maps error text → cause → fix. The invariants, one li
   is a part that exports: the old flat 480 turned a 0.75 mm rivet into 115,200 triangles
   and a body with a few hundred of them into an out-of-memory trap at export
   ([export-kernel-out-of-memory](ERROR-PATTERNS.md#export-kernel-out-of-memory)).
+  **Doubly-curved surfaces are the exception on both tiers:** a sphere, a lathe's
+  profile arcs (`torus`, `roundedCylinder`, a `revolve` of your own rounded `Shape2D`)
+  and a `roundedBox`'s corners all spend the segment count squared (6,728 triangles
+  for any sphere at 116; 27,000 for a tiny O-ring), so they are sized by chord
+  tolerance — 0.02 mm at preview, never fewer than 24 segments per circle (a rivet
+  sphere is 288 triangles, an O-ring ~6,000) and never more than the flat count, so
+  only features under about 60 mm radius get coarser and none get finer. That is what
+  keeps a body studded with a few hundred rivets inside a phone's memory
+  ([preview-build-too-heavy-for-phones](ERROR-PATTERNS.md#preview-build-too-heavy-for-phones)).
+  Two consequences to know: a lathe's sweep still runs at the flat count, so a small
+  rounded cylinder is cheaper as `roundedCylinder` than as a revolve you densify by
+  hand; and a tolerance-sized surface measures slightly smaller than the exact one
+  (about 0.8% on a 3 mm rounded feature), so give a `verify` volume gate on small
+  rounded parts that much slack. Spheres and rounded features are still the costliest
+  way to add small detail — a domed rivet is 288 triangles where a short cylinder is
+  232 and a box is 12, and every one is a boolean operand — so prefer instancing one
+  union of a row over a chain of per-feature booleans, and drop counts the print
+  cannot show.
 - **Display placement is view-independent**; only `place(..., { purpose: "export" })` may
   depend on `view` ([view-dependent-display-place](ERROR-PATTERNS.md#view-dependent-display-place)).
 - **Keep geometry backend-agnostic** (kernel calls only); only STEP requires OCCT

package/docs/ERROR-PATTERNS.md

@@ -829,6 +829,12 @@ between the Manifold preview and the OCCT STEP export.
 - **Cause:** The mesh kernel's WASM heap ran out while building the print-quality mesh, and a WASM trap leaves that kernel instance corrupt — every later call into it fails until the worker is replaced or the page reloaded. Before partforge 0.115 the print tier meshed every circle at a flat 480 segments whatever its radius, so a part with a few hundred small spheres or cylinders (a 0.75 mm rivet was 115,200 triangles — 176 of them are 20 M before a single boolean) exhausted a 4 GB heap on its first export while its whole unioned preview was a few hundred thousand triangles. Since 0.115 print sizes circles by a 0.01 mm chord tolerance, floored at the preview count, so a part that previews normally exports at roughly the preview's cost; a part that still traps is genuinely too heavy for the browser at ANY quality — usually thousands of repeated small features, or a boolean chain whose intermediates dwarf the result.
 - **Fix:** Reload the page (or let the host replace the kernel worker) before retrying anything — the trapped instance cannot recover. Then reduce what the export has to hold at once: build repeated detail as one union of instances rather than a chain of per-feature booleans, drop feature counts that exceed what the print can show (a 0.75 mm sphere prints as a dot), or pass `segs` to `revolve` where a coarser sweep is acceptable ([Preview vs print quality](AUTHORING-PARTS.md#conventions--gotchas)). Do NOT strip visible detail from the part to dodge a pre-0.115 trap — update partforge instead; the geometry was never the problem.
 
+## preview-build-too-heavy-for-phones
+
+- **Symptom:** A part that previews on a desktop crashes, reloads, or shows a blank viewer on phones — iOS Safari's "This webpage was reloaded because a problem occurred", a viewer that never finishes its first build, or (in partforge-cloud) a `sandbox_timeout` from a phone user agent — with no error text at all, because the browser killed the page rather than the build throwing.
+- **Cause:** Peak WASM memory during the preview build exceeded what the phone allows a page (roughly 1–1.5 GB on iOS; a desktop tolerates several GB). The usual shape is hundreds of repeated small features unioned into one body: before partforge 0.116 every sphere was 6,728 triangles regardless of radius (the flat 116-segment preview count, squared), so a body with ~250 rivet spheres carried 1.7 M triangles of rivets into its booleans — measured 10 s and a 2.7 GB peak on a desktop for a 400k-triangle sub-part, against 4 s and 500 MB with the rivets as 12-triangle boxes. A boolean chain whose intermediates dwarf the result (a full-body skin intersected per groove) is the other shape.
+- **Fix:** Update partforge (0.116 sizes spheres by chord tolerance: that body builds in ~550 MB and 120k triangles unchanged; 0.117 extends the rule to lathe profile arcs — `torus`, `roundedCylinder`, revolved rounded profiles — and `roundedBox` corners, the other two shapes that spend the count squared). Then keep the preview build's peak down the same ways the export needs: build repeated detail as one union of instances rather than a chain of per-feature booleans, cut grooves from a thin local skin rather than the whole envelope, and drop feature counts the print cannot show ([Preview vs print quality](AUTHORING-PARTS.md#conventions--gotchas)). `partforge measure` reports triangle counts per sub-part; a single preview sub-part past ~200k triangles, or a whole view past ~400k, is the range where phones start to fail.
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/docs/KERNEL-CONTRACT.md

@@ -380,7 +380,21 @@ backends both define `print` as a **chord tolerance of 0.01 mm** (OCCT's linear
 deflection; Manifold's per-circle segment rule in `geometry/circle-segs.js`, floored at
 the preview's 116 segments so print is never coarser than preview and capped at 480), so
 a small feature costs the export exactly what its preview cost — the property that makes
-"if it previews, it exports" hold. Preview is a flat 116 on Manifold, a visual choice.
+"if it previews, it exports" hold. Preview is a flat 116 on Manifold, a visual choice —
+except for the DOUBLY-CURVED family, whose triangle count is quadratic in the segment
+count: `sphere` (8·(n/4)² triangles), a lathe's profile arcs (`revolve` of a
+`Shape2D`, so `torus`, `roundedCylinder` and any hand-drawn rounded profile — every
+arc sample becomes a full ring of the sweep) and a `roundedBox`'s corners (sphere
+octants). Those are sized by chord tolerance on BOTH tiers (`doubleCurvatureSegs` in
+`geometry/circle-segs.js`: 0.02 mm at preview, floored at 24 segments and capped at
+the flat 116; 0.01 mm at print, floored at the preview count, capped at 480). At the
+flat count a 0.75 mm rivet sphere was 6,728 triangles and an O-ring of that tube
+radius 27,376, and a part carrying a few hundred rivets was a 2.7 GB preview build
+that phones could not survive; at the floor they are 288 and ~6,000. A tolerance-sized
+surface reads slightly smaller than the exact one (about 2π²/(3n²): 0.8% on a 3 mm
+tube at 28 segments), which `measure` reports faithfully. A lathe's SWEEP, and
+circles in extrusions, cylinders and outlines, keep the flat count, which the mesh
+fillet's arc gate and the roundAll fast path are tuned to.
 
 ### Shading intent (toMesh normals and edges)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.115.0",
+  "version": "0.117.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/geometry/circle-segs.js

@@ -35,22 +35,92 @@
 // helix tube's station/ring counts (TUBE in manifold-backend.js) and mesh-fillet's
 // blend bands keep their own sizing; loft rings keep LOFT_SEGS.
 //
+// The exceptions are the doubly-curved surfaces — sphere, a lathe's profile arcs, a
+// rounded box's corners — which have their own rule at the bottom of this file.
+//
 // Pure, dependency-free: profile.js's samplers take a `(r) => n` function in place of
 // a count, and this is what the backend hands them.
 
 export const SEGS = { preview: 116, print: 480 };       // full-circle segments (flat / cap)
 export const SAGITTA_TOL = { print: 0.01 };             // mm — max chord sagitta per tier
 
+// THE formula, shared by every tolerance-sized circle in the mesh backend: the fewest
+// full-circle segments that keep the chord sagitta r·(1 − cos(π/n)) under `tol`,
+// clamped to [floor, cap]. acos(1 − tol/r) is the half-angle of a chord with sagitta
+// tol; π over it is the full-circle count. r = Infinity gives acos(1) = 0 → Infinity →
+// the cap. A degenerate radius (0, negative, NaN, undefined) or one no larger than the
+// tolerance takes the floor and never throws. The callers differ only in POLICY — which
+// tolerance, which clamps — and that is all they should ever add: `circleSegs` and
+// `sphereSegs` below, mesh-fillet's blendSegs and mesh-roundall's roundAllSegs.
+export function segsForSagitta(r, tol, floor, cap) {
+  if (!(r > tol)) return floor;
+  return Math.min(cap, Math.max(floor, Math.ceil(Math.PI / Math.acos(1 - tol / r))));
+}
+
 // Segments per full circle for a circle of radius `r` at `quality`. A tier with no
-// tolerance (preview, or an unknown tier) is flat. A degenerate radius (0, negative,
-// NaN, undefined) takes the floor: it facets like the preview and never throws.
+// tolerance (preview, or an unknown tier) is flat; print is sized by tolerance, floored
+// at the preview count and capped at its own.
 export function circleSegs(r, quality) {
   const cap = SEGS[quality] ?? SEGS.preview;
   const tol = SAGITTA_TOL[quality];
   if (tol === undefined) return cap;
-  const floor = SEGS.preview;
-  if (!(r > tol)) return floor;
-  // acos(1 − tol/r) is the half-angle of a chord with sagitta tol; π over it is the
-  // full-circle count. r = Infinity gives acos(1) = 0 → Infinity → the cap.
-  return Math.min(cap, Math.max(floor, Math.ceil(Math.PI / Math.acos(1 - tol / r))));
+  return segsForSagitta(r, tol, SEGS.preview, cap);
+}
+
+// DOUBLE CURVATURE — the family whose triangle count is QUADRATIC in the segment
+// count, so the per-circle budget above, spent on one of them, is spent squared:
+//
+// - `sphere`: Manifold.sphere(r, n) subdivides an octahedron n/4 times per edge,
+//   8·(n/4)² triangles. At the flat preview 116 every sphere was 6,728 triangles
+//   whatever its radius; a 0.75 mm rivet carried a chord error of 0.0003 mm, a
+//   hundredth of a screen pixel at any zoom. A part with ~250 such rivets (the
+//   steampunk-spider feedback, "not loading on phones") unioned 1.7 M triangles of
+//   rivets into a 100k body: 10 s and a 2.7 GB peak on a desktop, which iOS Safari's
+//   content process does not survive — at 12 triangles each the same body was 4 s
+//   and 500 MB.
+// - a lathe's PROFILE ARCS (`revolve` of a Shape2D — `torus`, `roundedCylinder`, a
+//   hand-drawn rounded profile): every arc sample becomes a full ring of the sweep,
+//   so an O-ring of 0.75 mm tube radius was 27,376 triangles. The sweep itself stays
+//   on the circle rule (its rim is what the fillet machinery reads).
+// - a `roundedBox`'s corners: sphere octants, sampled per quarter arc AND per rim
+//   station, so a 3 mm rounded cube was 4,092 triangles (roundedBoxArcSamples in
+//   rounded-solids.js turns this count into that sample budget).
+//
+// All three are sized by chord tolerance on BOTH tiers, like print circles are:
+//
+// - preview holds DOUBLE_CURVATURE_SAGITTA_TOL.preview (0.02 mm — an absolute chord
+//   error is what screen pixels measure, so one tolerance reads equally smooth at
+//   every radius and every zoom; 0.02 mm is a fifth of a pixel at a typical
+//   100 mm-part zoom), floored at DOUBLE_CURVATURE_FLOOR segments (24 — ~15° facets,
+//   so a tiny ball never reads as a polygon under close zoom; a rivet sphere is 288
+//   triangles instead of 6,728) and capped at the old flat count (nothing gets FINER
+//   than before; a radius of 60 mm and up keeps exactly the density it always had).
+// - print holds the print tier's 0.01 mm, floored at the preview count for the same
+//   radius (never coarser than the preview the user approved — the same property the
+//   circle rule keeps) and capped at 480.
+//
+// A tolerance-sized surface reads a little SMALLER than the exact one — an inscribed
+// polygon's area deficit is about 2π²/(3n²), so 0.8% on a 3 mm tube at 28 segments
+// — and `measure` reports what the mesh holds. Gates on small rounded features should
+// carry that slack; print-scale features are unaffected at the cap.
+//
+// Circles in extrusions, cylinders, 2-D outlines and a lathe's SWEEP stay on the flat
+// preview count on purpose: their cost is linear in the count, and the mesh fillet's
+// arc gate, the roundAll prism fast path and the shading policies are all tuned to
+// that density — a spike that made EVERY preview circle tolerance-based (0.05 mm,
+// floor 24) turned bore-rim fillets from revolve tools into planar sweeps and drew 26
+// feature lines across a roundAll band that had none. None of the three surfaces
+// above has a sharp edge of its own, and roundAll sizes its own balls (roundAllSegs),
+// so this rule touches nothing tuned to 116.
+export const DOUBLE_CURVATURE_SAGITTA_TOL = { preview: 0.02, print: SAGITTA_TOL.print }; // mm
+export const DOUBLE_CURVATURE_FLOOR = 24;                                                  // segments
+
+// Segments per full circle for a doubly-curved feature of radius `r` at `quality`: the
+// fewest that keep the chord sagitta under the tier's tolerance, clamped as described
+// above. An unknown tier facets as preview; a degenerate radius takes the floor and
+// never throws.
+export function doubleCurvatureSegs(r, quality) {
+  const tier = Object.hasOwn(DOUBLE_CURVATURE_SAGITTA_TOL, quality ?? "") ? quality : "preview";
+  const floor = tier === "preview" ? DOUBLE_CURVATURE_FLOOR : doubleCurvatureSegs(r, "preview");
+  return segsForSagitta(r, DOUBLE_CURVATURE_SAGITTA_TOL[tier], floor, SEGS[tier]);
 }

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

@@ -2,7 +2,7 @@ import { helixTube } from "./helix-tube.js";
 import { loftMesh } from "./loft.js";
 import { resolveLoftRings, loftRingsKey } from "./loft-rings.js";
 import { sweepMesh } from "./sweep.js";
-import { roundedBoxRings } from "./rounded-solids.js";
+import { roundedBoxRings, roundedBoxArcSamples } from "./rounded-solids.js";
 import { tessellateContour, tessellateProfile } from "./profile.js";
 import { h } from "./solid-hash.js";
 import { ensureOutward, openEdgeCount } from "./mesh-repair.js";
@@ -19,7 +19,7 @@ import { creasedNormals } from "./creased-normals.js";
 import { loftShadingPolicy, SMOOTH, BLEND } from "./shading-policy.js";
 import { meshFillet, meshChamfer, UnsupportedEdgeError } from "./mesh-fillet.js";
 import { meshRoundAll, prismSection, roundAllSegs } from "./mesh-roundall.js";
-import { SEGS, circleSegs } from "./circle-segs.js";
+import { SEGS, circleSegs, doubleCurvatureSegs } from "./circle-segs.js";
 import { checkBooleanResult } from "./boolean-gate.js";
 import { KernelCapabilityError } from "./errors.js";
 import { heightfieldMesh, hashGridData } from "./heightfield.js";
@@ -51,6 +51,9 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   // Per-radius count for every site that facets a circle it knows the radius of; the
   // samplers behind prism/extrude/Shape2D take it as a function (profile.js).
   const segsAt = (r) => circleSegs(r, quality);
+  // The doubly-curved family's own per-radius count (sphere, a lathe's profile arcs,
+  // a rounded box's corners) — circle-segs.js explains why they are sized apart.
+  const dcAt = (r) => doubleCurvatureSegs(r, quality);
 
   // Manifold/CrossSection are WASM objects with no garbage collection — every
   // primitive and boolean op allocates a new one. Track them all and free them
@@ -187,6 +190,14 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     const cs = T(CrossSection.ofPolygons(regionPolys(shape._regions, segsAt), "EvenOdd"));
     return { value: cs, pin: cs, dispose: () => cs.delete?.() };
   });
+  // The same shape as a LATHE profile: its arcs sampled at the double-curvature count
+  // (every sample becomes a full ring of the sweep — the quadratic cost circle-segs.js
+  // describes), memoized apart from the extrude-facing tessellation above under its
+  // own key. Keyed on the tier, not a count: the count varies per arc radius.
+  const csForLathe = (shape) => cache.lookup(h("cs2d-lathe", shape._hash, quality), () => {
+    const cs = T(CrossSection.ofPolygons(regionPolys(shape._regions, dcAt), "EvenOdd"));
+    return { value: cs, pin: cs, dispose: () => cs.delete?.() };
+  });
 
   // Copy the mesh out into JS-owned arrays (so it survives cleanup) and free the
   // transient mesh handle.
@@ -653,13 +664,17 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     // spec). Reuses loftMesh's stitch/cap/winding machinery. Atomic cache
     // node hashed from its own args, like boredCylinder.
     roundedBox: ({ size, center, round }) => cached(
-      h("roundedBox", size, center, round.side, round.top, round.bottom, segsAt(Math.max(round.side, round.top, round.bottom))),
+      h("roundedBox", size, center, round.side, round.top, round.bottom, roundedBoxArcSamples(segsAt(Math.max(round.side, round.top, round.bottom)), dcAt(Math.max(round.side, round.top, round.bottom)))),
       () => {
         // One count serves every corner and rim arc, so it is sized for the largest.
-        const solid = T(loftMesh(wasm, roundedBoxRings(size, round, segsAt(Math.max(round.side, round.top, round.bottom)))));
+        const rMax = Math.max(round.side, round.top, round.bottom);
+        const solid = T(loftMesh(wasm, roundedBoxRings(size, round, segsAt(rMax), roundedBoxArcSamples(segsAt(rMax), dcAt(rMax)))));
         return center ? T(solid.translate([0, 0, -size[2] / 2])) : solid;
       }),
-    sphere: (r) => wrap(T(Manifold.sphere(r, segsAt(r))), h("sphere", r, segsAt(r))),
+    // Sized by the double-curvature rule (circle-segs.js: a sphere spends the per-circle
+    // count squared), on both tiers — the hash carries the count, so a sphere built at
+    // one tier never masquerades as the other's in the cache.
+    sphere: (r) => wrap(T(Manifold.sphere(r, dcAt(r))), h("sphere", r, dcAt(r))),
     box: (min, max) => {
       const cube = T(Manifold.cube([max[0] - min[0], max[1] - min[1], max[2] - min[2]]));
       return wrap(T(cube.translate(min)), h("box", min, max));
@@ -779,8 +794,8 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
       if (pts && pts._shape2d) {
         // Keyed on the override, not the resolved density, so a cache hit never
         // materializes the CrossSection just to measure its bounds.
-        return cached(h("revolve", pts._hash, degrees, segsOverride ?? null), () => {
-          const cs = csFor(pts);
+        return cached(h("revolve", pts._hash, degrees, segsOverride ?? null, quality), () => {
+          const cs = csForLathe(pts); // profile arcs at the double-curvature count; the sweep below stays on the circle rule
           const b = cs.bounds();
           return T(cs.revolve(densityFor(Math.max(Math.abs(b.min[0]), Math.abs(b.max[0]))), degrees));
         });

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

@@ -43,6 +43,7 @@
 // `dir` only ever matches straight chains, like replicad's inDirection.
 // Pure module: no DOM, no node:, no three — safe anywhere in the worker graph.
 import { sweepSeedFrame } from "./sweep.js";
+import { segsForSagitta } from "./circle-segs.js";
 
 const TOL = 1e-4;            // selector / coplanarity tolerance (mm)
 const WELD = 1e6;            // vertex weld quantization (1/WELD mm grid)
@@ -64,8 +65,7 @@ export class UnsupportedEdgeError extends Error {
 // angle (≤30°) under the viewer's 35° same-surface crease threshold.
 const BLEND_SAG = 1e-3; // mm — max chord sagitta of a blend cross-section
 function blendSegs(segs, r) {
-  const s = Math.min(BLEND_SAG, 0.02 * r);
-  return Math.min(segs, Math.max(12, Math.ceil(Math.PI / Math.acos(1 - s / r))));
+  return segsForSagitta(r, Math.min(BLEND_SAG, 0.02 * r), 12, segs);
 }
 // One derivation for a synthetic corner arc's angular density, shared by revolveTool
 // (which sweeps at it) and cornerHornTool (whose apothem bound below depends on it) —

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

@@ -28,13 +28,14 @@
 // is sized from the erosion ball (2r), the larger of the two, so the coarser of
 // the two facetings still meets the tier's sagitta tolerance.
 
+import { segsForSagitta } from "./circle-segs.js";
+
 // Sphere tessellation from the facet sagitta r·(1 − cos(π/segs)): pick the
-// fewest segments that keep it under the quality tier's tolerance.
+// fewest segments that keep it under the quality tier's tolerance — its own
+// tolerance table and 12..64 window, on the shared formula.
 const SAGITTA_TOL = { preview: 0.05, print: 0.01 }; // mm
 export function roundAllSegs(r, quality) {
-  const tol = SAGITTA_TOL[quality] ?? SAGITTA_TOL.preview;
-  if (!(r > tol)) return 12;
-  return Math.min(64, Math.max(12, Math.ceil(Math.PI / Math.acos(1 - tol / r))));
+  return segsForSagitta(r, SAGITTA_TOL[quality] ?? SAGITTA_TOL.preview, 12, 64);
 }
 
 export function meshRoundAll(wasm, m, r, quality) {

package/src/framework/geometry/rounded-solids.js

@@ -34,13 +34,25 @@ export function roundedRectRing(hw, hd, rc, A) {
   return pts;
 }
 
+// Quarter-arc sample count for a rounded box's corners (and z-stations per rim
+// zone): the corners are sphere octants, so they take the double-curvature count
+// for the corner radius, a quarter of it per 90° arc — the facet angle the sphere
+// floor itself has (24 → 6 → 15°). Capped at what the flat circle count used to
+// give (ceil(circle/8): 15 at preview, up to 49 at a metre-scale print), so no
+// rounded box gets finer than before and a large one keeps exactly its old
+// density. Floor 2: the builder's own minimum for a valid ring.
+export function roundedBoxArcSamples(circleSegs, doubleCurvatureSegs) {
+  return Math.max(2, Math.min(Math.ceil(circleSegs / 8), Math.ceil(doubleCurvatureSegs / 4)));
+}
+
 // Ring stack for the Manifold roundedBox: ascending-z loft ring specs
 // [{ polygon, z }]. A (arc samples per corner AND z-stations per rim zone) is
-// derived from the kernel's segs so the z-sampling matches the in-plane LOD.
-// Consecutive duplicate stations (top + bottom = h) are deduped so the loft
-// never sees a zero-height band.
-export function roundedBoxRings([w, d, h], { side, top, bottom }, segs) {
-  const A = Math.max(2, Math.ceil(segs / 8));
+// derived from the kernel's segs — or passed outright as `arcSamples` (the
+// backend hands in roundedBoxArcSamples) — so the z-sampling matches the
+// in-plane LOD. Consecutive duplicate stations (top + bottom = h) are deduped
+// so the loft never sees a zero-height band.
+export function roundedBoxRings([w, d, h], { side, top, bottom }, segs, arcSamples = Math.max(2, Math.ceil(segs / 8))) {
+  const A = arcSamples;
   const st = [];
   const push = (z, delta) => {
     const last = st[st.length - 1];