partforge 0.115.0 → 0.116.0

package/docs/AUTHORING-PARTS.md

@@ -3650,6 +3650,16 @@ 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)).
+  **Spheres are the exception on both tiers:** a sphere spends the segment count
+  squared (6,728 triangles at 116, whatever its radius), so `k.sphere` is sized by chord
+  tolerance — 0.02 mm at preview, never fewer than 24 segments (288 triangles) and never
+  more than 116, so only spheres under about 60 mm radius get coarser and none get
+  finer. That is what keeps a body studded with a few hundred rivet spheres inside a
+  phone's memory ([preview-build-too-heavy-for-phones](ERROR-PATTERNS.md#preview-build-too-heavy-for-phones)).
+  Spheres 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 of them is a
+  boolean operand. 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). 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,15 @@ 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 —
+with one exception: `sphere`, whose triangle count is quadratic in the segment count
+(8·(n/4)²), is sized by chord tolerance on BOTH tiers (`sphereSegs` 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 a part carrying a few
+hundred of them was a 2.7 GB preview build that phones could not survive; at the
+floor it is 288. Circles in extrusions, revolves 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.116.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,75 @@
 // 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 one exception is `sphere`, which has its 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);
+}
+
+// Spheres are the one primitive whose triangle count is QUADRATIC in the segment
+// count — Manifold.sphere(r, n) subdivides an octahedron n/4 times per edge, 8·(n/4)²
+// triangles — so the per-circle budget above, spent on a sphere, is spent squared:
+// at the flat preview 116 every sphere is 6,728 triangles whatever its radius, and a
+// 0.75 mm rivet sphere carries a chord error of 0.0003 mm, a hundredth of a screen
+// pixel at any zoom. A part carrying ~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 — with the rivets at 12 triangles each the same body was 4 s and 500 MB.
+//
+// So spheres are sized by chord tolerance on BOTH tiers, like print circles are:
+//
+// - preview holds SPHERE_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 SPHERE_FLOOR segments (24 — ~15° facets, so a tiny ball never reads as
+//   a polygon under close zoom, and 288 triangles instead of 6,728) and capped at the
+//   old flat count (nothing gets FINER than before; a sphere of 60 mm radius 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.
+//
+// Circles in extrusions, revolves, cylinders and 2-D outlines 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. A sphere has no sharp edges of its own and roundAll
+// sizes its own balls (roundAllSegs), so this rule touches nothing tuned to 116.
+export const SPHERE_SAGITTA_TOL = { preview: 0.02, print: SAGITTA_TOL.print }; // mm
+export const SPHERE_FLOOR = 24;                                                  // segments
+
+// Segments for a sphere of radius `r` at `quality`: the fewest that keep the chord
+// sagitta under the tier's sphere tolerance, clamped as described above. An unknown
+// tier facets as preview; a degenerate radius takes the floor and never throws.
+export function sphereSegs(r, quality) {
+  const tier = Object.hasOwn(SPHERE_SAGITTA_TOL, quality ?? "") ? quality : "preview";
+  const floor = tier === "preview" ? SPHERE_FLOOR : sphereSegs(r, "preview");
+  return segsForSagitta(r, SPHERE_SAGITTA_TOL[tier], floor, SEGS[tier]);
 }

package/src/framework/geometry/manifold-backend.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, sphereSegs } from "./circle-segs.js";
 import { checkBooleanResult } from "./boolean-gate.js";
 import { KernelCapabilityError } from "./errors.js";
 import { heightfieldMesh, hashGridData } from "./heightfield.js";
@@ -659,7 +659,10 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
         const solid = T(loftMesh(wasm, roundedBoxRings(size, round, segsAt(Math.max(round.side, round.top, round.bottom)))));
         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 its own per-radius 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, sphereSegs(r, quality))), h("sphere", r, sphereSegs(r, quality))),
     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));

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) {