partforge 0.163.0 → 0.164.0

package/bin/cli.js

@@ -559,14 +559,17 @@ function printVerify(v) {
   for (const c of v.cases) {
     console.log(`  ${c.name}`);
     for (const ch of c.checks) {
-      const icon = ch.status === "pass" ? "✓" : ch.status === "fail" ? "✗" : ch.status === "warn" ? "⚠" : "·";
-      console.log(`    ${icon} ${ch.subpart ?? "_view"} ${ch.metric} ${ch.expr}  (${ch.message})`);
+      // A cost has a price (supports, a brim), so it gets `$`, not a warning sign.
+      const icon = ch.status === "pass" ? "✓" : ch.status === "fail" ? "✗" : ch.status === "warn" ? "⚠"
+        : ch.status === "cost" ? "$" : "·";
+      console.log(`    ${icon} ${ch.subpart ?? "_view"} ${ch.metric} ${ch.expr}  (${ch.message})${ch.accepted ? " (accepted)" : ""}`);
       // A measurement caveat prints whatever the verdict — "passed, but sampled"
       // is precisely the line a reader must not miss.
       if (ch.note) console.log(`        note: ${ch.note}`);
-      if (ch.status === "fail" || ch.status === "warn") {
+      if (ch.status === "fail" || ch.status === "warn" || ch.status === "cost") {
         if (ch.location) console.log(`        at [${ch.location.map((n) => n.toFixed(1)).join(", ")}]`);
-        if (ch.hint) console.log(`        hint: ${ch.hint}${ch.pattern ? ` (${patternRef(ch.pattern)})` : ""}`);
+        // An accepted cost's remedy is moot: the user already chose to pay it.
+        if (ch.hint && !ch.accepted) console.log(`        hint: ${ch.hint}${ch.pattern ? ` (${patternRef(ch.pattern)})` : ""}`);
       }
     }
   }
@@ -584,7 +587,8 @@ function printVerify(v) {
     : v.unevaluated?.length ? `verdict withheld (${v.unevaluated.length} check(s) not evaluated)`
     : v.declared ? "nothing verified (every declared check skipped)"
     : "nothing verified (no expectations declared)";
-  console.log(`  result: ${verdict}${w ? `, ${w} warning(s)` : ""}`);
+  const c = v.costs?.length ?? 0;
+  console.log(`  result: ${verdict}${w ? `, ${w} warning(s)` : ""}${c ? `, ${c} cost(s)` : ""}`);
 }
 
 function printLint(r) {

package/docs/AUTHORING-PARTS.md

@@ -1919,6 +1919,128 @@ that tessellates nothing, unlike `toRegions()`), `fillet(r, opts?)`, `chamfer(di
 opts?)`, `simplify(tolerance)`, `corners()`, `contains([x,y])`, `isEmpty()` (no
 regions left — see the vanishing-features rule above).
 
+## Printed parts
+
+3D-printed parts: FDM (filament) and resin. Everything that is not a sheet
+part is printed, but a part says so on purpose by declaring its print process in
+`verify.process`; that one key arms the process's print checks below from the first
+build (all of them under FDM; bed fit and min wall under `resin`). Name
+the process the user will print with, never one written by habit: it is the declaration
+the checks, the fits and the advice all read.
+
+### Declaring the process
+
+`process` is a profile id — `fdm-pla`, `fdm-petg` (the `fdm` process) or `resin` (the
+`resin` process) — or an inline object whose `base` names one and whose other keys
+override it: `{ base: "fdm-pla", bed: [256, 256, 256] }` for a bigger printer,
+`{ base: "fdm-pla", fits: { … } }` for a calibrated one (`fits` replaces the whole
+table). The profile numbers are in the `verify` section's table below. `accept` lists
+the costs the user has chosen to pay:
+
+```js
+verify: {
+  process: "fdm-pla",
+  accept: ["supports"],        // the user chose supports for the organic body
+  expect: { body: { holes: 1 }, _view: { overlaps: 0 } },
+}
+```
+
+### Gates, costs and advisories
+
+Every print check is in exactly one tier, decided by what the reading means:
+
+| tier | checks | effect on `verify.ok` |
+| --- | --- | --- |
+| **gate** — a defect in any orientation | bed fit (`bbox` within `bed`), bed contact (`bedContactPct` ≥ 50) | fails it |
+| **cost** — a design choice with a price | overhang (`overhangArea`, id `supports`), footprint (`footprintPct` ≥ 10, id `footprint`) | never |
+| **advisory** — a reading that may not matter | min wall (`minWall`), `wall` | never; a warning |
+
+A **gate** is fixed before the work is done: the piece cannot be printed this way
+whatever the user wants. A **cost** is a fact with a number and a location — mm² of
+overhang on a named piece and where it sits, or the share of a piece's silhouette on
+the bed that actually touches it — listed in `verify().costs` (never in `warnings`) with `status: "cost"`. It
+does not block a part still being shaped; it informs. Say each cost to the user once,
+in one sentence naming the piece, the number and the alternative ("the arm overhangs
+by 840 mm² and prints on supports; splitting it at the elbow avoids them"), and record
+the answer in `accept`. An **advisory** is read, and acted on only when
+it is real (a thin wall the user will hold, not a sliver at a facet seam).
+
+**Accepting a cost is not switching it off.** An accepted cost is still measured and
+still listed in `costs`, with `accepted: true`, so the number stays visible; it is
+simply no longer something to raise. Switching a measurement off is the inline
+profile form, `{ base: "fdm-pla", overhang: null }` (or `footprint: null`,
+`bedContact: null`), and is for a part where the reading is meaningless, not unwelcome.
+A threshold the user named ("under 500 mm² of supports") is an `expect`:
+`overhangArea: "<=500"` — still a cost, reported in `costs` and never failing `ok`;
+the user's own limit keeps its meaning, so it is never marked accepted, whatever
+`accept` says (`accept` covers only the process's default check). Lint refuses an `accept` entry the process does not define
+(`verify-unknown-accept`): `fdm` defines `supports` and `footprint`; `resin` prints on
+supports and defines none.
+
+**What arms what.** Under `fdm-pla`/`fdm-petg` the profile alone arms every check in
+the table except `wall`, which runs only where a sub-part declares a band; overhang fires past 1 mm². `resin` arms bed fit and min wall only. `orientation: "print"` declares that `build()`
+is the print pose (Z up, bed at the lowest Z); it arms nothing under a named profile,
+and with no profile at all it arms bed contact alone. An expectation you write yourself
+(`overhangArea`, `bedContactPct`, `footprintPct`) arms its own measurement under any
+profile or none; an `overhangArea` one is measured against 45° when the profile names no
+angle.
+
+### Orientation first
+
+Decide each piece's print pose before its geometry. Put its largest flat face on the
+bed; when a piece has none, split it at its widest flat section so each half has one,
+and join the halves with pins or a dovetail. `build()` IS that pose — every check and
+every export reads the piece as built — and `views.assembly` poses it into place; a
+`print` view lays the pieces out on the bed beside each other (see "The
+`PartDefinition` contract"). A piece that reads well in the assembly and prints on its
+side is the most common source of both costs.
+
+### What costs supports and what does not
+
+Overhangs past the profile's angle (45° from vertical on FDM) cost supports, and so
+do bridges longer than `bridge` (10 mm) and any cavity that opens downward — a socket
+under a ball, a pocket on the underside. The check counts every flat underside, a short
+bridge and the ceiling of a horizontal bore included, since a mesh cannot tell a bridge
+from a ceiling: a bridge within `bridge` prints without support, so tell the user that
+rather than redesign it. Faces within 45° of
+vertical do not cost supports: a chamfer under a ledge instead of a square step, a
+teardrop bore (a round hole with a 45° peak on top) instead of a round one. Faces on
+the bed or within 1 mm of it are never counted, so a bottom-edge chamfer, or a small fillet, is
+free.
+
+**Ball joints on FDM** are a split socket (two halves that clamp the ball and screw or
+pin together) or a pinned clevis, not a socket snapped over a sphere: the snap's inside
+is a downward cavity that prints on supports nobody can reach. Build the snap only when
+the user wants it and has accepted the supports.
+
+### Small features and scale
+
+A feature thinner than the profile's `minWall` (1.2 mm PLA, 1.5 mm PETG, 0.6 mm
+resin) prints as noise or not at all. A part with a scale parameter is checked at both
+ends of it: add a preset at the smallest and the largest scale and name them in
+`verify.cases`, so the small end's pins and walls are measured rather than described
+in the control's label ("below 150 mm the pins get thin").
+
+### Fits
+
+Size a mating feature from the profile's fit class — `press`, `push`, `slip`,
+`moving`, `printInPlace` — copied into `derive()` with a comment naming it
+(`// slip fit: fdm-pla 0.25`), and a horizontal bore enlarged by `holeUndersize`. A
+snap is a contact; its fit is `push` or `slip`. The numbers, and how a diametral fit
+becomes a `clearance` expectation, are in the `verify` section below.
+
+### First layer
+
+The first layer squashes wider than drawn (elephant's foot): give a bottom edge that
+must mate or measure true a small 45° chamfer (about 0.4 mm). Keep the underside flat
+and lowest: a knuckle, pin or boss that dips below it lifts the flat face off the bed
+and fails bed contact ([piece-hovers-above-bed](ERROR-PATTERNS.md#piece-hovers-above-bed))
+— size a print-in-place knuckle tangent to the bed and give it a block down to
+z = 0. A piece resting on a point, a line or a curve is reported as a footprint cost
+([piece-stands-on-nothing](ERROR-PATTERNS.md#piece-stands-on-nothing)): lay it on a
+flat face, add a pad, or record the user's brim with `accept: ["footprint"]`. Never
+emboss text on the underside; deboss it, or put it on a side or the top.
+
 ## Sheet parts
 
 Laser-cut parts from flat stock — plywood, MDF, acrylic — for a laser cutter
@@ -4008,7 +4130,7 @@ runtime a throwing probe only degrades quietly to `{ error }`.
 
 **Verify block** — `verify-unknown-metric`, `verify-unknown-subpart`,
 `verify-bad-expr`, `verify-bad-pair-check`, `verify-unknown-process`,
-`verify-unknown-orientation`,
+`verify-unknown-orientation`, `verify-unknown-accept`,
 `verify-expect-throws` (all errors). Note `_view` also accepts the pair-wise
 `contacts` / `clearance` / `held` keys, which are not scalar view metrics; they are
 validated by `verify-bad-pair-check`, matching `verify.js`'s own handling.
@@ -4173,7 +4295,8 @@ carries:
   from a sample rather than every triangle (see below); `overhangArea` sets one
   naming the steepest unsupported face's angle,
 - `location` — `[x, y, z]` in mm where the metric has one: `minWall` (thinnest
-  sample point), `overhangArea` (the largest unsupported face's centroid) and
+  sample point), `overhangArea` (the largest unsupported face's centroid),
+  `footprintPct` (the piece's lowest point; absent when its export-pose reading failed) and
   `overlaps` (the center of the first offending intersection's
   *bounding box* — a nearby indicator, not an exact point: when a pair overlaps in
   more than one place the bbox center can fall in the empty space between regions)
@@ -4188,7 +4311,8 @@ exists, e.g. the OCCT backend or min-wall measurement turned off, matching
 per triangle, which is unbounded work on a dense mesh, so past a sample budget
 it casts from a spread, deterministic subset instead — `minWallSampled` (boolean)
 and `minWallSamples` (`{ sampled, total }` or `null`) say whether that happened.
-A part that opted into the overhang check (see the `verify` block) also carries
+A part checked for overhang (a profile carrying `overhang`, or an `overhangArea`
+expectation — see the `verify` block) also carries
 `overhangArea` (mm² of unsupported downward-facing surface, `null` when not
 checked or on an `exportable: false` sub-part), `overhangAngle` (the steepest such
 face, degrees from vertical) and `overhangAt` (that face's centroid); the report's
@@ -4198,7 +4322,13 @@ A part checked for bed contact (an FDM profile, see the `verify` block) carries
 when not checked or on an `exportable: false` sub-part), `bedContactArea` and
 `bedHoverArea` (mm² touching and hovering), `bedHoverGap` (how far above the bed the
 largest hovering face sits, `null` when nothing hovers) and `bedHoverAt` (its
-centroid); the report's `measuredBedContact` says whether the pass ran.
+centroid); the report's `measuredBedContact` says whether the pass ran. The same
+pass reads `footprintPct` (the share of the piece's silhouette on the bed that actually
+touches it, in percent; `null` when not measured or the silhouette is empty) and
+`footprintAt`
+(the piece's lowest point; `null` when its export-pose reading failed), stamped by
+`measuredFootprint`; a profile carrying
+`footprint`, or a `footprintPct` expectation, arms the pass too.
 A sub-part that declares `wall` (see the `verify` section below) also carries
 `wall` — `{ value, location, band, members }` or `null`: the declared band's
 worst member, located, with the band it was measured against and how many rays
@@ -4302,10 +4432,11 @@ A part can declare how it should be checked, co-located with its schema, so
 
 ```js
 verify: {
-  process: "fdm-pla",            // a DFM profile: fdm-pla | fdm-petg | resin, or an
-                                  // inline { base, bed:[x,y,z], minWall, overhang, bedContact, fits, holeUndersize, bridge } object
-  orientation: "print",          // optional; ONLY with this is overhang checked — it says the
-                                  // part is laid out for its bed (Z up, bed at the lowest Z)
+  process: "fdm-pla",            // a DFM profile: fdm-pla | fdm-petg | resin, or an inline
+                                  // { base, bed:[x,y,z], minWall, overhang, bedContact, footprint, fits, holeUndersize, bridge } object
+  accept: ["supports"],          // optional; the costs the user chose to pay (fdm: supports, footprint)
+  orientation: "print",          // optional; declares build() is the print pose (Z up, bed at
+                                  // the lowest Z) — with no profile it arms bed contact
   cases: ["defaults", "M3"],     // optional; default = defaults + every preset
   expect: {                      // design intent, by sub-part name (+ "_view")
     spacer: { holes: 1, bbox: "<=[60,60,60]", volume: "0.4..0.6cm3" },
@@ -4318,28 +4449,38 @@ verify: {
 ```
 
 **What the profile gives you:** a hard **bed-fit** gate (the view bbox must fit `bed`),
-a **min-wall** warning, and — only for a part that also declares
-`orientation: "print"` — an **overhang** warning: `overhangArea` is the mm² of
+a **min-wall** warning, and on the FDM profiles a **bed-contact** gate and two
+**costs** — overhang and footprint (below). A cost is never a failure: it is a design
+choice with a price, reported in `verify().costs` with its number, location and hint
+and `status: "cost"`, and `ok` ignores it. See "Printed parts" for the tiers and how
+to raise a cost with the user.
+
+**Overhang — a COST, armed by the process.** `overhangArea` is the mm² of
 downward-facing surface steeper than the profile's `overhang` angle (45° from vertical
 on the FDM profiles; resin carries none, since it prints on supports), measured per
 sub-part in its print (export) pose — not as the view shows it — with the bed at that
-pose's own lowest Z, and warned past 1 mm²; the reported location is where the face sits
-in the view. The
-opt-in is deliberate: a profile says what a process can print, the orientation key
-says this part is laid out for it, and a part still being shaped, or one bound for a
-different process, should not be nagged about its underside. Writing your own
+pose's own lowest Z; it is a cost past 1 mm², with cost id `supports`, and the
+reported location is where the face sits in the view. A profile carrying `overhang`
+arms it from the first build; `orientation` takes no part. Writing your own
 `overhangArea` expectation is the other way in — it arms the measurement by itself,
-against the profile's angle or 45° when the profile names none, so a declared
-expectation is never answered "unavailable". Two bands next to the bed are never
+against the profile's angle or 45° when the profile names none, and is also how a
+user's limit is spelled (`overhangArea: "<=500"`). Two bands next to the bed are never
 counted: the footprint itself, and faces whose centroid sits within 1 mm of the bed
 (the lower curl of a bottom-edge fillet or chamfer, which prints fine). A bridge (a
 flat underside spanning two supports) and the ceiling of a horizontal bore are
-reported as overhangs — the mesh alone cannot tell a bridge from a ceiling — which
-is why this is a warning and never a gate. Two more limits, stated: it is judged in
-the DISPLAY pose, so a sub-part whose `assembly` pose stands it differently from how it prints (a lid that prints
-flat beside its base) is measured as displayed, and `exportable: false` sub-parts
-are skipped. Switch it off under an FDM profile with an inline
-`{ base: "fdm-pla", overhang: null }`.
+reported as overhangs — the mesh alone cannot tell a bridge from a ceiling — so read
+the location before proposing a redesign. When a sub-part's `place()` cannot be
+trusted as a rigid pose (it queries its solid), the reading falls back to the DISPLAY
+pose, so such a piece is measured as the view shows it. `exportable: false` sub-parts
+are skipped.
+
+**`accept` records the user's choice.** `accept: ["supports"]` says the user chose to
+print with supports: the overhang is still measured and still listed in `costs`, with
+`accepted: true`, and is no longer something to raise. That is a different thing from
+switching the measurement off, which is the inline `{ base: "fdm-pla", overhang: null }`
+(and `footprint: null`) for a part where the reading means nothing. `accept` holds cost
+ids, not metric names — `fdm` defines `supports` and `footprint`, `resin` none — and
+lint refuses any other entry (`verify-unknown-accept`).
 
 **Bed contact — a GATE, armed by the FDM profile alone.** Every exporter and slicer
 lays a printed piece on its lowest point. When that point is something small — a
@@ -4362,10 +4503,9 @@ its note says how far up it sits and how much area hovers versus touches. The fi
 almost always to trim the piece flat at the bed plane — cut away everything below
 z = 0 in its print pose — or to raise or shorten the lower feature so the flat face
 is the lowest; size a print-in-place knuckle so its cylinder is tangent to the bed
-(diameter = 2 × its centre height) and give it a support block down to z = 0. Unlike
-overhang, no orientation key is needed: an overhang is a design choice a part still
-being shaped may not have made, but a hovering underside is a defect in whatever
-orientation the piece exports. Resin prints on supports, so `resin` never checks it
+(diameter = 2 × its centre height) and give it a support block down to z = 0. It is a
+gate where overhang is a cost: an overhang is a design choice that prints on supports,
+but a hovering underside is a defect in whatever orientation the piece exports. Resin prints on supports, so `resin` never checks it
 unless you ask: your own `bedContactPct` expectation arms it under any profile, and
 `orientation: "print"` arms it on a part with no profile at all (both against 50%). A
 named profile otherwise decides alone. A recess meant to clear the
@@ -4375,6 +4515,23 @@ default stands, and a part that means it declares a lower `bedContactPct` (or
 `{ base: "fdm-pla", bedContact: null }` to switch it off). `exportable: false`
 sub-parts are not judged.
 
+**Footprint — a COST, armed by the FDM profile.** Bed contact passes a piece that
+stands on a point, a line or a curve, since nothing flat hovers; the first layer still
+has almost nothing to grip, and the piece tips or pulls loose unless it prints with a
+brim or a raft. `footprintPct` is the share of the piece's silhouette on the bed (its
+outline seen from below, in the same print pose) that actually touches it, read by bed
+contact's pass, in percent: a plate reads 100, and so do a tube on its rim, a frame of
+thin bars, spread pins and a bar laid diagonally, since each stands on all of its
+outline; a rod on a rounded tip reads about 0, a cylinder on its side a few percent
+(the facets along its lowest line), under the floor, and a wide piece balanced on a
+narrow foot reads low too. It is a cost below the profile's `footprint` (10%), with cost id
+`footprint`, located at the piece's lowest point
+([piece-stands-on-nothing](ERROR-PATTERNS.md#piece-stands-on-nothing)). Lay the piece on
+a flat face or add a pad; when the user chooses the brim, `accept: ["footprint"]`
+records it. Your own `footprintPct` expectation arms it under any profile; `orientation`
+does not, and `{ base: "fdm-pla", footprint: null }` switches it off. `exportable: false`
+sub-parts are not judged.
+
 **What the profile tells you.** Three more fields carry the numbers a mating
 feature needs. Nothing checks them; they are the one place the value is spelled,
 so `derive()` copies it with a comment naming the fit (`// slip fit: fdm-pla 0.25`).
@@ -4399,7 +4556,7 @@ an inline `{ base: "fdm-pla", fits: { … } }` replaces the whole table.
 **What `expect` gives you:** per-sub-part
 assertions on the facts `measure` already reports — `holes` (through-bores / genus),
 `volume`, `surfaceArea`, `triangleCount`, `bbox`, `watertight`, `minWall`,
-`overhangArea`, `bedContactPct`, `wall` (a range — see below), `bounds` (the axis-aligned corner
+`overhangArea`, `bedContactPct`, `footprintPct`, `wall` (a range — see below), `bounds` (the axis-aligned corner
 positions, written in the same `{ min, max }` shape `measure` reports them — where
 the geometry sits, vs `bbox` which is only its size) and `centerOfMass` (`[x,y,z]`, the volume-weighted
 centroid; `null` for a degenerate/zero-volume sub-part); and `_view` assertions `bbox`,
@@ -4442,12 +4599,14 @@ verify: { expect: {
 } }
 ```
 
-**Gates vs. warnings:** exact facts are **gates** (a failure sets a non-zero exit code);
-`minWall` is computed (a ray/shot wall-thickness measurement) and reported as a
-**warning** — it flags walls below the profile's minimum but never fails the build —
-and so is `overhangArea` (see above). `bedContactPct` is a **gate** even though the
-profile arms it (see above). `holes`/`watertight` are Manifold-only, so those
-assertions **skip** on OCCT parts rather than fail.
+**Gates, costs and warnings:** exact facts are **gates** (a failure sets a non-zero
+exit code and `ok: false`), and so is `bedContactPct`, even though the profile arms it.
+`overhangArea` and `footprintPct` under a process are **costs**: listed in `costs`, never
+failing, `accepted` once `accept` names them — but an `overhangArea` or `footprintPct`
+you write in `expect` is still a cost, not a gate. `minWall` is computed (a ray/shot
+wall-thickness measurement) and reported as a **warning** — it flags walls below the
+profile's minimum but never fails the build. `holes`/`watertight` are Manifold-only, so
+those assertions **skip** on OCCT parts rather than fail.
 
 **A wall that must stay one thickness: `wall`.** `minWall` answers "is anything too
 thin"; `wall` answers "does this wall stay what I declared" — the question a bend, a
@@ -4553,8 +4712,8 @@ mass. A reference ghost (`exportable: false`) is left out entirely: it neither
 counts nor holds, since it is never printed (lint refuses one named as the base).
 A named base that is `enabled()`-off
 in a case skips that case; a name that exists nowhere throws, like a `contacts`
-pair. It is an expectation, never a default, for the overhang reason: a part
-still being shaped should not be nagged. Topological only — a part balanced on a
+pair. It is an expectation, never a default: a part still being shaped should not
+fail for pieces it has not joined yet. Topological only — a part balanced on a
 point passes — and the same OCCT caveat applies: a sub-part fully inside another
 reads as not touching there. A view with fewer than two printed sub-parts passes with nothing to hold. A pin or axle running in a clearance bore, or a print-in-place piece, touches nothing in the model and reads as floating: `held` is for assemblies whose pieces seat on each other, so leave it off when a piece is captured with running clearance (`fits.moving`, `fits.printInPlace`) and declare that pair's `clearance` instead. A quick lap answers it `unevaluated`.
 

package/docs/ERROR-PATTERNS.md

@@ -210,6 +210,12 @@ Variant literals under this entry: `extrude: unknown bevel option`, `extrude: be
 - **Cause:** Something smaller than the piece's flat underside sits lower than it in the print pose — a horizontal knuckle or pin whose cylinder dips below the plate, a boss, or lettering embossed on the bottom — so exporters and slicers rest the piece on that feature and the flat face prints in mid-air.
 - **Fix:** Trim the piece flat at the bed plane (cut everything below z = 0 in its print pose), or raise or shorten the lower feature so the flat face is the lowest; size a print-in-place knuckle so its cylinder is tangent to the bed and give it a support block down to z = 0. A recess meant to clear the bed declares a lower `bedContactPct`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Self-verification (the `verify` block)".
 
+## piece-stands-on-nothing
+
+- **Symptom:** A `footprintPct` cost from `verify` (in `verify.costs`, e.g. `0.42 not >= 10`) on a piece whose print pose rests on a point, a line or a curl — a sphere-tipped rod standing on its end, a cylinder lying on its side — while `bedContactPct` passes.
+- **Cause:** The lowest point of the piece is not a flat face, so almost none of its silhouette on the bed actually touches it (a cylinder on its side reads a few percent, under the floor): the first layer has almost nothing to bond to, and the piece tips or pulls loose unless it prints with a brim, a raft, or in a different orientation.
+- **Fix:** Lay the piece on its flat face in its print pose, add a flat foot or pad at its lowest point, or print it with a brim. When the user chose the brim, `verify.accept: ["footprint"]` records it and the cost reads accepted. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Printed parts".
+
 ## expect-static-across-presets
 
 - **Symptom:** A `verify` exact gate (`holes`, `volume`, …) fails on SOME presets only — e.g. `✗ planter holes 1  (0 != 1)` on two cases while defaults pass — and the preview looks right for every preset.
@@ -877,6 +883,12 @@ between the Manifold preview and the OCCT STEP export.
 - **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.
 
+## kernel-internal-error
+
+- **Symptom:** `the geometry kernel raised an internal error it could not describe` — from a build or a STEP import, naming the operation when known (`during STEP import of "frame" (17.1 MB)`) and, when the kernel's own heap could say, the C++ exception type (`C++ exception StdFail_NotDone`, `Standard_ConstructionError`, `std::bad_alloc`, …) and the heap size. Before partforge 0.163.1 the same failure was a bare number (`{"ok":false,"error":"154591824"}`), different on every attempt.
+- **Cause:** The OCCT kernel is a WASM build compiled without C++ exception catching, so an exception nothing inside it catches — the STEP reader's transfer refusing an entity, a construction with a zero-length direction, an allocation the heap could not grow for — reaches JavaScript as the exception's ADDRESS. The number is not a code and means nothing across runs. partforge now names the operation and reads the exception's type off the heap, but it cannot read OCCT's own message for it.
+- **Fix:** Act on the type. `std::bad_alloc` or `Standard_OutOfMemory` (the message then says "probably too large for the in-browser kernel") is memory: a STEP import needs roughly six times its file size of kernel heap (measured on OCCT-written files: 17 MB → 100 MiB, 42 MB → 248 MiB), so a file that exhausts the 2 GB wasm32 ceiling is hundreds of megabytes, or the browser refused to grow the heap — simplify the imported model or split it. Any other type on an import is the file itself: re-export it from the CAD tool as AP214/AP242 solids (no assembly-only or surface-only exports) and try the smaller file; the same type from a build is that operation refusing its input (a `Standard_ConstructionError` is usually a zero-length direction or a degenerate profile). Retrying the identical build fails the same way — it is not transient.
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.163.0",
+  "version": "0.164.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/occt-backend.js

@@ -27,6 +27,7 @@ import { makeProfileWarner } from "./profile-warnings.js";
 import { createOcctRepair } from "./occt-repair.js";
 import { occtRoundAll } from "./occt-roundall.js";
 import { classifyFaceGroups } from "./feature-attribution.js";
+import { emscriptenThrowEvidence, labelImportFailure } from "../kernel-error.js";
 import { resolveLoftRings, loftRingsKey } from "./loft-rings.js";
 import { resolveSweepStations } from "./sweep.js";
 import { normalizeProfile } from "./profile.js";
@@ -199,6 +200,7 @@ export function createOcctKernel(replicad) {
   // registers pre-build via `_registerImport` (kernel-lifetime, untracked by the
   // solid cache: imports are the framework's own memo, keyed by name+digest).
   const imports = new Map();
+  const throwEvidence = (value) => emscriptenThrowEvidence(replicad.getOC?.(), value);
   // name -> { digest, width, height, data } — depth-map grids the framework
   // registers pre-build via `_registerImage` (ensureImages). Kernel-lifetime like
   // `imports` above, and plain data rather than OCCT objects, so there is nothing
@@ -815,11 +817,22 @@ export function createOcctKernel(replicad) {
       const prev = imports.get(name);
       if (!prev?.error && prev?.digest === digest) return; // error entries are always upgradable
       if (error) { imports.set(name, { error, digest }); return; }
-      imports.set(name, { shape: await importSTEP(new Blob([step])), digest });
+      // A STEP the reader refuses, or an OCCT exception out of its transfer,
+      // leaves here labelled with the import's name and size. The latter
+      // reaches JavaScript as a bare number from this exception-less build
+      // (kernel-error.js), and the heap is read for its C++ type BEFORE
+      // anything else runs on the kernel.
+      let shape;
+      try { shape = await importSTEP(new Blob([step])); }
+      catch (e) { throw labelImportFailure({ name, bytes: step?.byteLength, error: e, evidence: throwEvidence(e) }); }
+      imports.set(name, { shape, digest });
     },
     // Registration memo: undefined for an error entry, so a later registration with
     // the same digest can upgrade it rather than being treated as a no-op repeat.
     _importDigest: (name) => { const e = imports.get(name); return e?.error ? undefined : e?.digest; },
+    // What the kernel's heap can say about a value OCCT threw (kernel-error.js):
+    // the job loop asks this when a build throws something that is not an Error.
+    _throwEvidence: throwEvidence,
     // Depth-map grids, registered pre-build by the framework via `_registerImage`
     // (ensureImages). Unlike imports there is no per-format error entry: every
     // backend can consume a normalized grid, so registration never fails.

package/src/framework/jobs.js

@@ -10,6 +10,7 @@ import { fontsFor, resolveFonts, forgetFontSource } from "./fonts.js";
 import { normalizeOpentype, parseFont } from "./geometry/opentype-interop.js";
 import { imageControlAllows, imageSourceAllowed, isNoImageSource } from "./image-source.js";
 import { imagesFor, ensureImages } from "./images.js";
+import { describeKernelThrow } from "./kernel-error.js";
 import { ensureImports, resolveImports } from "./imports.js";
 import { safeName } from "./safe-name.js";
 import { vectorControlAllows, vectorSourceAllowed, isNoVectorSource } from "./vector-source.js";
@@ -651,7 +652,12 @@ export async function handle(kernel, part, msg, post, opts = {}) {
     } else if (opts.jobs && Object.hasOwn(opts.jobs, msg.type)) {
       await opts.jobs[msg.type](kernel, part, msg, post, { isStale: opts.isStale });
     }
-  } catch (err) {
+  } catch (thrown) {
+    // A kernel compiled without exception catching throws a bare NUMBER for an
+    // uncaught C++ exception; describeKernelThrow turns that into a readable
+    // Error (with the C++ type when the kernel's heap can say) and returns a
+    // real Error untouched, `code` included.
+    const err = describeKernelThrow(thrown, { evidence: kernel._throwEvidence?.(thrown) });
     // `subparts` (generate jobs only) tells the reroute policy which sub-parts the
     // failed job covered, so only those latch to OCCT — not the whole part.
     if (err?.code === "NEEDS_IMPORT_MESH") post({ type: "needs-import-mesh", jobId: msg.jobId, subparts: msg.subparts });

package/src/framework/kernel-error.js

@@ -0,0 +1,161 @@
+// What to say when the geometry kernel throws something that is not an Error.
+//
+// replicad-opencascadejs's `replicad_single` build (the OCCT kernel worker.js
+// loads) is compiled WITHOUT C++ exception catching. An exception OCCT throws
+// that nothing inside the WASM catches — a Standard_Failure out of the STEP
+// reader, a std::bad_alloc when the heap cannot grow — leaves the module through
+// Emscripten's `___cxa_throw`, whose last line is `throw ptr`: JavaScript
+// receives the exception's ADDRESS, a bare number such as 154591824, different
+// on every run. Stringified as-is, that number was the whole error message a
+// part author (and partforge-cloud's agent, which read it as the part's fault
+// and retried blindly — cloud feedback #208) got for a failed build.
+//
+// This module is the ONE place such a value becomes a readable Error, used by
+// both the job loop's error post (jobs.js, worker.js) and the STEP import path
+// (occt-backend.js). It never invents a cause: the message says the kernel
+// raised an internal error it could not describe, names the operation when the
+// caller knows it, and adds only what the kernel's own heap can prove —
+// `emscriptenThrowEvidence` reads the thrown exception's C++ type name off the
+// heap through the Itanium ABI layout Emscripten's `ExceptionInfo` uses, and
+// says "too large for the in-browser kernel" only when that type IS an
+// out-of-memory type, or the heap has reached the wasm32 ceiling. Anything the
+// read cannot validate is dropped rather than guessed.
+
+// A thrown value the caller cannot read: a number (the Emscripten case above), or
+// an object with no non-empty string message (a bare WebAssembly.Exception, a
+// plain object). A real Error — anything with a message — is never opaque.
+export function isOpaqueThrow(err) {
+  if (typeof err === "number") return true;
+  if (err == null) return true;
+  if (typeof err === "string") return err.trim() === "";
+  return !(typeof err.message === "string" && err.message.trim() !== "");
+}
+
+// Emscripten's ExceptionInfo (replicad-opencascadejs 0.23): the thrown pointer
+// is the exception OBJECT; a 24-byte header sits before it, with the
+// std::type_info pointer at header + 4. A std::type_info (libc++abi, wasm32)
+// is { vtable*, const char* __type_name }, so the mangled class name is the
+// C string at *(typeInfo + 4). test/kernel-error-occt.test.js holds this
+// layout against the installed glue: a replicad-opencascadejs bump that moves
+// it fails there, and until it is re-pinned the read simply yields no type
+// name (a wrong read almost never parses as a mangled name — see below).
+const EXCEPTION_HEADER_BYTES = 24;
+const TYPE_OFFSET_IN_HEADER = 4;
+const NAME_OFFSET_IN_TYPE_INFO = 4;
+const MAX_MANGLED_NAME = 128;
+
+// getHeapMax() in the replicad_single glue: the wasm32 build's memory ceiling.
+export const WASM32_HEAP_CEILING_BYTES = 2 ** 31;
+// At or past this share of the ceiling, a throw with no readable type is still
+// called out of memory: nothing else grows a heap to the top of its range.
+const HEAP_CEILING_SHARE = 0.9;
+
+// C++ exception types that mean the kernel could not get memory.
+const OUT_OF_MEMORY_TYPES = new Set(["std::bad_alloc", "std::bad_array_new_length", "Standard_OutOfMemory"]);
+
+// Itanium-mangled class name → readable, for the shapes exception types take:
+// `St9bad_alloc` (std::bad_alloc), `16Standard_Failure`, `N3foo3BarE`
+// (foo::Bar). Every length prefix must match its identifier exactly and the
+// string must be consumed whole, which is what makes a misread (a pointer that
+// landed on arbitrary heap bytes) come back null instead of as a "type".
+export function demangleClassName(mangled) {
+  if (typeof mangled !== "string" || !/^[A-Za-z0-9_]{1,128}$/.test(mangled)) return null;
+  let i = 0;
+  const nested = mangled[0] === "N";
+  if (nested) i++;
+  const parts = [];
+  if (mangled.startsWith("St", i)) { parts.push("std"); i += 2; }
+  while (i < mangled.length && /[0-9]/.test(mangled[i])) {
+    let j = i;
+    while (j < mangled.length && /[0-9]/.test(mangled[j])) j++;
+    const len = Number(mangled.slice(i, j));
+    if (len < 1 || j + len > mangled.length) return null;
+    const ident = mangled.slice(j, j + len);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(ident)) return null;
+    parts.push(ident);
+    i = j + len;
+  }
+  if (nested ? mangled.slice(i) !== "E" : i !== mangled.length) return null;
+  if (parts.length === 0 || (parts.length === 1 && parts[0] === "std")) return null;
+  return parts.join("::");
+}
+
+function readCString(u8, ptr, cap) {
+  if (!Number.isInteger(ptr) || ptr <= 0 || ptr >= u8.length) return null;
+  let s = "";
+  for (let i = 0; i < cap && ptr + i < u8.length; i++) {
+    const c = u8[ptr + i];
+    if (c === 0) return s;
+    s += String.fromCharCode(c);
+  }
+  return null; // ran past the cap or the heap without a terminator
+}
+
+// What the kernel's heap can say about a thrown value: `{ heapBytes, typeName? }`.
+// `module` is the Emscripten module object (what `opencascade()` resolved to,
+// `replicad.getOC()`); the HEAP views are re-read from it on every call because
+// the glue replaces them whenever the memory grows. Returns `{}` for a module
+// without heap views, and never throws.
+export function emscriptenThrowEvidence(module, value) {
+  const evidence = {};
+  const u8 = module?.HEAPU8;
+  const u32 = module?.HEAPU32;
+  if (!(u8 instanceof Uint8Array) || !(u32 instanceof Uint32Array)) return evidence;
+  evidence.heapBytes = u8.length;
+  if (!Number.isInteger(value) || value <= EXCEPTION_HEADER_BYTES || value >= u8.length) return evidence;
+  const typeInfo = u32[(value - EXCEPTION_HEADER_BYTES + TYPE_OFFSET_IN_HEADER) >> 2];
+  if (!(typeInfo > 0 && typeInfo + NAME_OFFSET_IN_TYPE_INFO + 4 <= u8.length)) return evidence;
+  const namePtr = u32[(typeInfo + NAME_OFFSET_IN_TYPE_INFO) >> 2];
+  const typeName = demangleClassName(readCString(u8, namePtr, MAX_MANGLED_NAME));
+  if (typeName) evidence.typeName = typeName;
+  return evidence;
+}
+
+export function formatBytes(n) {
+  if (!Number.isFinite(n) || n < 0) return "unknown size";
+  if (n < 1e6) return `${Math.max(1, Math.round(n / 1e3))} KB`;
+  return `${(n / 1e6).toFixed(1)} MB`;
+}
+
+const describeRaw = (err) => {
+  if (typeof err === "number") return `the kernel reported only an exception address, ${err}`;
+  const ctor = err?.constructor?.name;
+  return `the kernel reported only an opaque ${ctor && ctor !== "Object" ? ctor : "value"}`;
+};
+
+// Turn a thrown value into an Error. A real Error (anything with a message) is
+// returned AS IS — same object, nothing rewritten — so a caller can branch on
+// its `code` exactly as before. `operation` names what was running ("STEP
+// import of "frame" (17.1 MB)"); `subject` is what the memory clause blames
+// ("the file" for an import, "the part" otherwise); `evidence` is
+// `emscriptenThrowEvidence`'s answer, or nothing.
+export function describeKernelThrow(err, { operation, subject = "the part", evidence = {} } = {}) {
+  if (!isOpaqueThrow(err)) return err;
+  const { typeName, heapBytes } = evidence ?? {};
+  let message = "the geometry kernel raised an internal error it could not describe";
+  if (operation) message += ` during ${operation}`;
+  const detail = [];
+  if (typeName) detail.push(`C++ exception ${typeName}`);
+  if (Number.isFinite(heapBytes)) detail.push(`kernel heap ${formatBytes(heapBytes)}`);
+  message += detail.length ? ` (${detail.join(", ")})` : ` (${describeRaw(err)})`;
+  const outOfMemory = typeName
+    ? OUT_OF_MEMORY_TYPES.has(typeName)
+    : Number.isFinite(heapBytes) && heapBytes >= WASM32_HEAP_CEILING_BYTES * HEAP_CEILING_SHARE;
+  if (outOfMemory) {
+    message += ` — the kernel ran out of memory, so ${subject} is probably too large for the in-browser kernel; retrying without reducing it will fail the same way`;
+  }
+  const out = new Error(message, { cause: err });
+  if (typeName) out.kernelExceptionType = typeName;
+  return out;
+}
+
+// The STEP import path's wrapper: whatever `importSTEP` threw, labelled with the
+// import's name and size. An opaque throw takes `describeKernelThrow` with the
+// import as its operation; a real Error (replicad's "Failed to load STEP file",
+// its "This shape has not type, it is null" for a file the reader parsed but
+// could not transfer) keeps its text behind the same label, `cause` attached.
+export function labelImportFailure({ name, bytes, error, evidence }) {
+  const operation = `STEP import of "${name}" (${formatBytes(bytes)})`;
+  if (isOpaqueThrow(error)) return describeKernelThrow(error, { operation, subject: "the file", evidence });
+  return new Error(`${operation} failed: ${error.message}`, { cause: error });
+}