partforge 0.132.1 → 0.133.1

package/bin/cli.js

@@ -9,6 +9,7 @@ import { pathToFileURL } from "node:url";
 import { resolve, dirname, basename } from "node:path";
 import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
 import { detectBackend } from "../src/framework/backend-select.js";
+import { SHEET_DOC_ID, fmtMm } from "../src/framework/sheet/constants.js";
 import { fontsFor } from "../src/framework/fonts.js";
 import { imagesFor } from "../src/framework/images.js";
 import { isNoImageSource } from "../src/framework/image-source.js";
@@ -31,6 +32,10 @@ const die = (msg) => { console.error(msg); process.exit(1); };
 
 const USAGE = "usage: partforge <lint|measure|render|pick-serve|pick|ingest> …";
 
+// Where a finding's `pattern` points: an ERROR-PATTERNS.md entry — or, for a sheet-part
+// finding, the authoring guide's "Sheet parts" section, which rides the same field.
+const patternRef = (pattern) => (pattern === SHEET_DOC_ID ? 'AUTHORING-PARTS.md "Sheet parts"' : `ERROR-PATTERNS.md#${pattern}`);
+
 // Crash contract (issue #27): with --json, a thrown error becomes structured
 // stdout JSON; either way the message is matched against ERROR-PATTERNS.md and
 // the pattern's fix is surfaced. Exit 1 always. NOTE on stdout purity: in --json
@@ -505,6 +510,11 @@ function printMeasure(r) {
     console.log(`  ${s.name}  bbox ${s.bbox.map((n) => n.toFixed(1)).join("×")}  ` +
       `vol ${(s.volume / 1000).toFixed(2)}cm³  area ${(s.surfaceArea / 100).toFixed(1)}cm²  ` +
       `tris ${s.triangleCount}  ${wt}  ${holes}`);
+    // A sheet part's stock and flat size — what the cut file will be.
+    if (s.sheet) {
+      console.log(`    sheet  ${s.sheet.material ?? "?"} ${s.sheet.thickness == null ? "?" : fmtMm(s.sheet.thickness)} mm, ` +
+        `flat ${s.sheet.flat.map((n) => n.toFixed(1)).join(" × ")} mm, ${s.sheet.pieces} piece${s.sheet.pieces === 1 ? "" : "s"}`);
+    }
   }
   const a = r.aggregate;
   console.log(`  ── view  bbox ${a.bbox.map((n) => n.toFixed(1)).join("×")}  vol ${(a.volume / 1000).toFixed(2)}cm³  tris ${a.triangleCount}`);
@@ -556,7 +566,7 @@ function printVerify(v) {
       if (ch.note) console.log(`        note: ${ch.note}`);
       if (ch.status === "fail" || ch.status === "warn") {
         if (ch.location) console.log(`        at [${ch.location.map((n) => n.toFixed(1)).join(", ")}]`);
-        if (ch.hint) console.log(`        hint: ${ch.hint}${ch.pattern ? ` (ERROR-PATTERNS.md#${ch.pattern})` : ""}`);
+        if (ch.hint) console.log(`        hint: ${ch.hint}${ch.pattern ? ` (${patternRef(ch.pattern)})` : ""}`);
       }
     }
   }
@@ -589,7 +599,7 @@ function printLint(r) {
     const at = f.file ? `  ${f.file}:${f.line ?? "?"}` : "";
     console.log(`  ${icon} ${f.rule}${f.path ? `  ${f.path}` : ""}${at}`);
     console.log(`      ${f.message}`);
-    console.log(`      hint: ${f.hint}${f.pattern ? ` (ERROR-PATTERNS.md#${f.pattern})` : ""}`);
+    console.log(`      hint: ${f.hint}${f.pattern ? ` (${patternRef(f.pattern)})` : ""}`);
   }
   const e = r.errors.length, w = r.warnings.length, n = (r.notes ?? []).length;
   console.log(`  result: ${e ? `${e} error(s)` : "no errors"}${w ? `, ${w} warning(s)` : ""}${n ? `, ${n} note(s)` : ""}`);

package/docs/AUTHORING-PARTS.md

@@ -319,7 +319,7 @@ and asks for the existing positional view argument
 ## Materials and appearance
 
 A sub-part's `display` block says how it LOOKS. Appearance never changes
-geometry, exports (other than 3MF colour, below), `measure` or `verify`, and a
+geometry, exports (other than export colours, below), `measure` or `verify`, and a
 mistake in it never fails a build — lint warns and the viewer falls back.
 
 ```js
@@ -336,7 +336,7 @@ meta: { title: "…", units: "mm", environment: "studio" },
   else the viewer's blue-grey — and **realistic mode shows it as a PLA print**
   (`pla-print`'s finish and layer lines) in that same colour. So an untouched
   part looks printed in realistic mode; name a material when it is made some
-  other way. The PLA look is realistic-only: the CAD view, 3MF colours and
+  other way. The PLA look is realistic-only: the CAD view, export colours and
   `declaresMaterials` are unaffected, and a part that names no material is not
   treated as declaring one.
 - `color` — the base colour (`0xRRGGBB`). With a preset it is the TINT. Presets
@@ -378,9 +378,11 @@ on oak shrinks the grain to a 0.2 mm tile, i.e. invisible noise):
 
 Presets without a pattern ignore it.
 
-**3MF export** carries each sub-part's colour (its `color`, else its preset's
-colour), so a multi-colour print opens in a slicer already split and coloured.
-A part with no `color` or `material` exports exactly as before.
+**3MF and STEP export** carry each sub-part's colour (its `color`, else its
+preset's colour), so a multi-colour print opens in a slicer already split and
+coloured, and each STEP body opens in a CAD tool in its own colour. A part with
+no `color` or `material` exports a 3MF exactly as before; its STEP bodies take
+the viewer's blue-grey.
 
 | Preset | Name | Tintable | Use |
 | --- | --- | --- | --- |
@@ -1518,6 +1520,9 @@ returned `circlePolygon`'s points; it takes no `segs`.) For a round SOLID use `k
 and **use `k.torus({ rMajor, rMinor })` for a torus** — the primitive keeps real TORUS faces
 in STEP.
 
+**Laser-cut flat stock** (plywood, acrylic, MDF panels) is built differently — with
+`sheetPart()` and the joinery helpers; see [Sheet parts](#sheet-parts).
+
 **Patterns** (return `Solid[]` — feed to `k.union(...)` for features or `s.cutAll(...)` for holes):
 `linearPattern(solid, count, [dx,dy,dz])`, `circularPattern(solid, count, { center, axis, angle, rotateCopies })`.
 
@@ -1769,6 +1774,280 @@ 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).
 
+## Sheet parts
+
+Laser-cut parts from flat stock — plywood, MDF, acrylic — for a laser cutter
+(LightBurn, xTool, Glowforge) or a cutting service (SendCutSend): flat-pack boxes,
+finger/box joints, tab and slot, T-slot screw joints, engraving and scoring. Build each
+piece cut from a sheet with `sheetPart()` from `partforge/geometry`; the cut & print
+kit turns them into SVG or DXF cut files, and kerf is chosen there, at download.
+
+### When a sub-part is a sheet part
+
+When it is cut out of one flat sheet: a 2-D outline with holes, marks on its face, the
+stock as its third dimension. A 3 mm plate you **print** is not one, nor is anything
+with pockets, steps or fillets. Mixing is normal — plywood panels, printed hinges.
+
+### sheetPart
+
+```js
+import { sheetPart, sheetHole } from "partforge/geometry";
+
+plate: sheetPart({
+  label: "Plate", views: ["main"], display: { material: "clear-acrylic" },
+  material: "clear acrylic",                  // stock label: groups pieces in the kit
+  thickness: (p) => p.t,                      // the MEASURED thickness, from a control
+  profile: (k, p) => k.shape2d([[0, 0], [p.w, 0], [p.w, p.h], [0, p.h]])
+    .cut(sheetHole({ d: 5, at: [8, 8] })),    // the cut layer
+  pose: (p) => ({ face: "-Y", up: "+Z", at: [-p.w / 2, 0, 0] }),
+}),
+```
+
+It returns an ordinary sub-part: `build`, `place` and a plain-data `sheet`. A field
+needing the kernel is `(k, p, d) => …`; a plain value is a literal or `(p, d) => …`.
+`material`, `thickness` and `profile` are required; `score`, `engrave`, `pose`,
+`process` (default `"laser"`) are optional; `label`, `views`, `display`, `export`,
+`enabled`, `exportable`, `reference` pass through; your own `place` runs after the
+pose. `build` is supplied — passing one throws, as do `kerf`, `outline`/`cut` (use
+`profile`) and `quantity` (the kit counts identical pieces).
+
+### Cut, score and engrave
+
+- **`profile`** is the CUT layer — outline plus holes, seen from the laser face, one
+  piece. Round holes: `sheetHole({ d, at })` or `circleProfile(r, at)` — exact, not the
+  48-gon `circlePolygon`.
+- **`score`** returns an array: an entry of exactly two `[x, y]` points is a LINE;
+  anything else is a shape whose boundaries are scored (`[[0, 0], [10, 0],
+  [10, 10]]` is a triangle). `null` entries are skipped.
+- **`engrave`** returns filled regions — `k.text2d(…)`, `k.vector2d(…)`, a Shape2D —
+  or `null`. No raster engraving.
+
+The preview pockets engraving and scores a groove 0.2 mm deep, so marks show in
+renders; the cut files carry vectors. Empty marks are dropped. Keep these functions
+chainable — no branching on `isEmpty()`/`area()`/`boundingBox()` — so pose-only
+sliders stay fast.
+
+### Thickness, clearance and kerf
+
+Three numbers, never mixed. **Thickness** is what you *measured* ("3 mm" plywood is
+often 2.7–3.3): bind it to a control, `thickness: (p) => p.t`; it is the extrusion and
+every joint's depth. **Clearance** is a finished joint's total play, on its own control
+(`fit`, 0–0.4 mm): fingers split it between the panels, slots take all of it. **Kerf**,
+what the beam burns away, never appears in the part: it is asked at download and
+applied once to the cut lines. Joinery refuses a `kerf` option; add no kerf control.
+
+### Placing panels: pose and worldToSheet
+
+A sheet part is drawn in its own frame: drawing in XY, material over z ∈ [0, t], laser
+face at z = t. `pose: { face, up, at }` places it — `face` is the laser face's outward
+normal, `up` the drawing's +y (axis words `"+X"`, `"-Y"`, …, at right angles), `at`
+where drawing `[0, 0]` lands; the material runs back along −`face`. Drawing +x is
+`up × face`, so an engraving is never mirrored. The pose holds for display AND export:
+STEP/3MF/STL come out assembled. No pose: flat at the origin. A box's front panel,
+laser face out: `{ face: "-Y", up: "+Z", at: [-W / 2, -D / 2, 0] }`.
+
+`worldToSheet(pose, [x, y, z])` → `[u, v]`: where a world point lands on the drawing —
+cut a slot where a printed tongue really is. `sheetToWorld(pose, [u, v], depth)` goes
+back.
+
+### Joinery helpers
+
+Pure and kernel-free — call them in `derive()`. They draw NOMINAL material.
+
+| Helper | Returns |
+|---|---|
+| `fingers({ thickness, clearance = 0.1, finger = 2t, side = "outer" })` | outer fingers protrude, inner ones notch |
+| `tabs({ thickness, count = 2, width = 3t })` | tongues protruding `thickness` |
+| `tSlots({ thickness, screw = "M3", screwLength = 12, at = [0.5], clearance = 0.2 })` | shank slot + nut trap (`JOINERY_SCREWS`) |
+| `sheetPanel({ width, height, edges: { bottom, right, top, left } })` | `{ outline, size }` |
+| `matchingSlots(joint, { line, clearance })` | holes the OTHER panel needs |
+| `fingerBox({ width, depth, height, thickness, clearance, finger })` | `{ bottom, front, back, left, right }` → `{ outline, size, pose }` |
+
+`sheetPanel`'s nominal edges are the box `[0, W] × [0, H]`; protrusions lie outside
+(`size` includes them). Edges run CCW — bottom, right, top, left — and positions are
+measured from an edge's start. Finger counts are odd, cells ≥ 2t, and every corner has
+one owner. `thickness` is the mating sheet's. `matchingSlots`' `line` is the tabbed
+panel's mid-plane in the slotted panel's frame, from the tabbed edge's start.
+
+```js
+derive: (p) => ({ box: fingerBox({ width: p.w, depth: p.d, height: p.h, thickness: p.t, clearance: p.fit }) }),
+front: sheetPart({ ...PLY, profile: (k, p, d) => d.box.front.outline, pose: (p, d) => d.box.front.pose }),
+```
+
+### Printed parts that key into sheets
+
+`printedTab({ size: [w, h], thickness, clearance = 0.3 })` gives a slot and its printed
+tongue from one spec: `slot` is `(w + c) × (h + c)`, centred (all the play); `tongue`
+is `[w, h, thickness]` for `k.box({ size: tongue })`. Build the printed part in its
+PRINT pose, `place` it for display, and cut the slot where the tongue lands:
+`k.shape2d(tab.slot).translate(worldToSheet(panelPose, tongueCentre))`.
+
+### What lint and verify check
+
+**Lint** (no kernel; judged at the part's defaults). Every finding carries
+`pattern: "sheet-parts"`:
+
+| Rule | Tier | Fires when |
+|---|---|---|
+| `sheet-invalid` | error | a hand-written `sheet` declaration is malformed |
+| `sheet-thickness-invalid` | error | `thickness(p, d)` is not a finite number above 0, or throws |
+| `sheet-pose-invalid` | error | a pose uses a non-axis word, or `up` is not perpendicular to `face` |
+| `sheet-thickness-literal` | warning | thickness is a fixed number, not the measured-value control |
+| `sheet-kerf-control` | warning | a control's key or label says kerf |
+| `sheet-custom-build` | warning | `build` replaced the one `sheetPart` generated |
+| `verify-process-sheets-only` | warning | `verify.process` is set but every exportable part is a sheet part |
+| `laser-thickness-range` | warning | a laser sheet is thinner than 0.5 mm or thicker than 12 mm |
+
+**Verify** runs the laser checks on every sheet part. They are
+*volunteered* warnings: none counts toward `declared`/`evaluated`, so none makes
+`verify.ok` true on its own. Declare one in `expect` to make it count:
+
+| Metric | Reads | Checked at |
+|---|---|---|
+| `sheetBridge` | narrowest web or finger, mm | `>=` half the thickness, at least 0.5 mm |
+| `sheetGap` | narrowest hole, slot or notch, mm | the same floor |
+| `sheetMarks` | engrave/score regions outside the cut | `0` |
+| `sheetPieces` | regions in the profile | `1` |
+| `sheetSolidMatch` | a custom build's volume vs. profile area × thickness, % | `<=2` (custom builds only) |
+
+Widths come from shrinking and regrowing the cut outline with sharp corners,
+bisected to 0.05 mm; nothing narrower than twice the floor reads as that ceiling,
+with a note. A finding's `location` is its spot in the assembly at mid-thickness
+(none when the pose cannot be traced). The 2-D checks share a 1.5 s budget per
+measurement: past it, or when a profile is plainly too complex for it, a sheet
+gets one `sheetChecks` warning instead, and a declared sheet check comes back
+unevaluated. In a forge mixing sheet and printed
+parts, the profile's bed fits each **printed** part in its print (export) pose, not
+the assembled view, and `minWall` and the overhang check skip sheet parts.
+
+### Limits
+
+- One thickness per joint: fingers, tabs and T-slots join panels cut from the
+  same sheet.
+- Poses are rigid and axis-aligned: `face` and `up` are the six axis words. A
+  panel at an angle is an author `place` after the pose, or a printed part.
+- No bends, folds, living hinges or grain direction: `folds`, `bends` and
+  `grain` are reserved keys and throw.
+- Cut and score are vector lines; engraving is filled regions. There is no raster
+  image engraving.
+- The laser checks are warnings. Sharp-corner shrinking can over-report at acute
+  tips, and a web within 0.05 mm of the floor can read as passing.
+
+### Worked example: laser-box.js
+
+`src/parts/laser-box.js`, verbatim:
+
+```js
+// Finger-jointed plywood box: five laser-cut panels from fingerBox, a laser-cut lid,
+// and two print-in-place hinges whose tongues key into slots in the back panel and
+// the lid; an engraved label and a score line on the front. A hinge prints flat and
+// flat is 90° open, so the box is shown with its lid standing up.
+import { sheetPart, fingerBox, printedTab, worldToSheet } from "partforge/geometry";
+
+// Hinge in its PRINT pose: leaves flat on the bed, knuckle axis along X at y = 0,
+// z = R, tongues up (+Z). Fixed leaf (y < 0) → back panel; lid leaf (y > 0) → lid.
+const HINGE = { width: 24, leaf: 18, leafT: 3, R: 3, gap: 0.4, pinR: 1.2, lift: 0.25,
+  tongue: [8, 3], tongueX: 6, tongueY: 11 };
+
+// ONE spec for a tongue and its slot; the slot carries the clearance.
+const tab = (p) => printedTab({ size: HINGE.tongue, thickness: p.t, clearance: p.printFit });
+
+function hinge(k, p, d) {
+  const { width: w, leaf, leafT, R, gap, pinR, tongueX } = HINGE, { tongueY } = d;
+  const seg = (w - 2 * gap) / 3;                                  // three knuckles, `gap` apart
+  const x0 = -w / 2, x1 = x0 + seg, x2 = x1 + gap, x3 = x2 + seg, x4 = x3 + gap, x5 = w / 2;
+  const box = (min, max) => k.box({ min, max });
+  const barrel = (a, b, r = R) => k.cylinder({ r, h: b - a }).along("+X").at([a, 0, R]);
+  const tongues = (y) => [-tongueX, tongueX].map((x) => k.box({ size: tab(p).tongue }).at([x, y, leafT]));
+  const fixed = k.union([
+    box([x0, -leaf, 0], [x5, -(R + gap), leafT]),
+    box([x0, -(R + gap), 0], [x1, 0, leafT]), box([x4, -(R + gap), 0], [x5, 0, leafT]),
+    barrel(x0, x1), barrel(x4, x5), barrel(x0, x5, pinR),         // outer knuckles + pin
+    ...tongues(-tongueY),
+  ]).label("Fixed leaf");
+  const moving = k.union([
+    box([x0, R + gap, 0], [x5, leaf, leafT]), box([x2, 0, 0], [x3, R + gap, leafT]),
+    barrel(x2, x3), ...tongues(tongueY),
+  ]).cut(barrel(x2 - 1, x3 + 1, pinR + gap)).label("Lid leaf");  // running clearance on the pin
+  return k.union([fixed, moving]);
+}
+
+// Display: flat hinge against the back panel's outside face, knuckles above the wall.
+// Export: the print pose, untouched — both hinges export the same solid.
+const hingePlace = (i) => (s, { purpose, p, d }) => (purpose === "export" ? s
+  : s.rotateX(90).at([d.hingeX[i], p.depth / 2 + HINGE.leafT, d.axisZ]));
+
+// Tongue slots for both hinges, cut where the tongues really land (world → sheet).
+const hingeSlots = (k, p, d, pose, z) => d.hingeX.flatMap((hx) =>
+  [hx - HINGE.tongueX, hx + HINGE.tongueX].map((x) =>
+    k.shape2d(tab(p).slot).translate(worldToSheet(pose, [x, p.depth / 2, z]))));
+
+const PLY = { views: ["box"], display: { material: "oak" }, material: "birch plywood", thickness: (p) => p.t };
+const panel = (name, label, extra = {}) => sheetPart({
+  ...PLY, label,
+  profile: (k, p, d) => d.box[name].outline,       // drawn as seen from outside
+  pose: (p, d) => d.box[name].pose,                // fingerBox knows where it goes
+  ...extra,
+});
+
+export default {
+  meta: { title: "Plywood box with printed hinges", units: "mm" },
+  parameters: [
+    { id: "box", title: "Box", description: "Outside size, lid excluded.", controls: [
+      { key: "width", label: "Width", unit: "mm", min: 100, max: 400, step: 1, description: "Outside width." },
+      { key: "depth", label: "Depth", unit: "mm", min: 80, max: 300, step: 1, description: "Hinges on the back." },
+      { key: "height", label: "Height", unit: "mm", min: 50, max: 200, step: 1, description: "Wall height." },
+      { key: "label", type: "text", label: "Label", description: "Engraved on the front; empty for none." },
+    ] },
+    { id: "stock", title: "Stock & fit", description: "Measure your sheet. Kerf is chosen when you download the kit.", controls: [
+      { key: "t", label: "Sheet thickness", unit: "mm", min: 2, max: 6.5, step: 0.05, description: "MEASURED — '3 mm' ply is often 2.7–3.3." },
+      { key: "fit", label: "Finger clearance", unit: "mm", min: 0, max: 0.4, step: 0.02, description: "Total play per finger joint." },
+      { key: "printFit", label: "Hinge tab clearance", unit: "mm", min: 0, max: 0.8, step: 0.05, description: "Slot minus printed tongue." },
+    ] },
+  ],
+  defaults: { width: 160, depth: 110, height: 80, label: "TOOLS", t: 3, fit: 0.1, printFit: 0.3 },
+  derive: (p) => {
+    const rise = Math.max(0, p.t - HINGE.R);                     // thick stock: the shut lid clears the walls
+    const axisZ = p.height + HINGE.lift + HINGE.R + rise;        // knuckle axis, above the back wall
+    const lidZ = axisZ + HINGE.lift + HINGE.R;                   // hinge edge of the open lid
+    return {
+      box: fingerBox({ width: p.width, depth: p.depth, height: p.height, thickness: p.t, clearance: p.fit }),
+      hingeX: [-(p.width / 2 - 25), p.width / 2 - 25],
+      axisZ,
+      tongueY: HINGE.tongueY + rise,                             // slots stay put
+      // Open 90°: laser face to the back, the drawing's front edge (v = 0) on top.
+      lidPose: { face: "+Y", up: "-Z", at: [-p.width / 2, p.depth / 2, lidZ + p.depth] },
+    };
+  },
+  parts: {
+    bottom: panel("bottom", "Bottom"),
+    left: panel("left", "Left"),
+    right: panel("right", "Right"),
+    front: panel("front", "Front", {                              // u across, v up
+      engrave: (k, p) => (p.label?.trim() ? k.text2d(p.label, { size: 14 }).translate([p.width / 2, p.height * 0.55]) : null),
+      score: (k, p) => [[[12, p.height * 0.35], [p.width - 12, p.height * 0.35]]],   // a two-point line
+    }),
+    back: panel("back", "Back", {
+      profile: (k, p, d) => k.shape2d(d.box.back.outline)
+        .cutAll(hingeSlots(k, p, d, d.box.back.pose, d.axisZ - d.tongueY)),
+    }),
+    lid: sheetPart({
+      ...PLY, label: "Lid",
+      profile: (k, p, d) => k.shape2d([[0, 0], [p.width, 0], [p.width, p.depth], [0, p.depth]])
+        .cutAll(hingeSlots(k, p, d, d.lidPose, d.axisZ + d.tongueY)),
+      pose: (p, d) => d.lidPose,
+    }),
+    hingeL: { label: "Hinge (left)", views: ["box"], display: { material: "pla-print" },
+      export: { name: "hinge" }, build: hinge, place: hingePlace(0) },
+    hingeR: { label: "Hinge (right)", views: ["box"], display: { material: "pla-print" },
+      build: hinge, place: hingePlace(1) },    // identical solid: the kit prints "hinge" ×2
+  },
+  views: { box: { label: "Box" } },
+  // `process` = the PRINTED parts' profile; sheet parts get the laser checks instead.
+  verify: { process: "fdm-pla", expect: { _view: { overlaps: 0 } } },
+};
+```
+
 ## Convex hull
 
 `k.hull([a, b, …])` wraps its inputs (Shape2Ds, curve contours, or point lists) in a
@@ -3452,6 +3731,14 @@ rules judge the argument values the probe resolves under the part's default para
 same basis `import-unknown-name` uses; a call that only goes wrong for
 non-default params still fails correctly at build time.
 
+**Sheet parts** — `sheet-invalid`, `sheet-thickness-invalid`, `sheet-pose-invalid`
+(errors); `sheet-thickness-literal`, `sheet-kerf-control`, `sheet-custom-build`,
+`verify-process-sheets-only`, `laser-thickness-range` (warnings). Each carries
+`pattern: "sheet-parts"` and is described under "Sheet parts" → "What lint and
+verify check". `no-buildable-parts` points a sub-part with a `sheet` but no `build`
+at `sheetPart()`, and `verify-unknown-process` answers `process: "laser"` the same
+way.
+
 A rule that itself throws yields an `internal-rule-error` **warning** and the run
 continues: `lintPart` never throws and never blocks a part because of a linter bug.
 
@@ -3463,7 +3750,8 @@ carries:
 
 - `hint` — one self-contained corrective sentence (always present),
 - `pattern` — a stable [ERROR-PATTERNS.md](ERROR-PATTERNS.md) entry ID when one
-  applies (follow it with `ERROR-PATTERNS.md#<id>`),
+  applies (follow it with `ERROR-PATTERNS.md#<id>`); on a sheet-part check it is
+  `sheet-parts`, this guide's "Sheet parts" section, instead,
 - `note` — an optional caveat about *how* the value was measured, or a companion
   reading, attached whatever the verdict. `minWall` sets one when the reading came
   from a sample rather than every triangle (see below); `overhangArea` sets one
@@ -3517,6 +3805,14 @@ pair: `{ a, b, distance, at }`, distance 0 = touching or overlapping) and
 **absent** rather than empty when it did not run — an empty table means "measured,
 and these pairs have no distance", which a declared `clearance` gate fails on.
 
+A sheet sub-part (`sheetPart()`) also carries `sheet` — its 2-D facts:
+`material`, `thickness`, `flat` (the cut layer's size), `area`, `pieces`, the
+bisected `bridge`/`gap` widths with their `bridgeCapped`/`gapCapped` flags,
+`marksOutside`, `evaluated` (false when the 2-D budget ran out) and `at` (each
+finding's spot in the assembly) — and `sheet: null` on every other sub-part. In a
+view that holds one, each printed sub-part also carries `printBbox`, its size in
+the print (export) pose.
+
 ### Quick checks
 
 An editor may ask for a **quick** check, which skips both ray-casting passes — min
@@ -3698,6 +3994,15 @@ the two apart. A single answerable expectation — or a process profile, which b
 the bed-fit gate — is enough for a verdict. Treat `null` as "not verified", never as
 a pass.
 
+**Forges with sheet parts.** When a view holds a `sheetPart()` sub-part, the
+profile's bed fits each printed sub-part in its print (export) pose — the check
+carries the note "measured in the print (export) pose" — instead of the assembled
+view, and `minWall` and `overhangArea` skip the sheet parts. The laser checks
+(`sheetBridge`, `sheetGap`, `sheetMarks`, `sheetPieces`, `sheetSolidMatch`) run on
+every sheet part as volunteered warnings that never make `ok` true on their own;
+see "Sheet parts" → "What lint and verify check". A view with no sheet part is
+verified exactly as before.
+
 **Per-case expectations.** Checks run across defaults **and every preset**, so a
 static `expect` breaks the moment a preset legitimately changes an asserted fact —
 a "cup" preset that turns the drainage hole off flips the genus from 1 to 0.

package/docs/KERNEL-CONTRACT.md

@@ -296,7 +296,7 @@ above. All ops return a `Solid`.
 | `vector2d(name, {shape?, width\|height\|fit, align?, valign?})` | A declared vector document → `Shape2D`. `name` = a declared name in the part's `vectors` field (`partforge-vector` JSON — authored by hand or ingested from an `.svg`; never raw `.svg`). With no `shape`, the document's own composition: every `"add"` shape unioned minus every `"subtract"` shape; `shape` selects one named shape's geometry whatever its role. Sizing follows the document's required `units`: `"artwork"` requires exactly one of `width`/`height`/`fit` in millimetres, `"mm"` places as authored (scale 1, no translate) and accepts a size option optionally; more than one is refused. Uniform scale in every case (`fit` = larger extent); `align`/`valign` position it, same as `text2d`, defaulting to centre/middle for `"artwork"` and to no translate for `"mm"`. **The composed call derives ONE transform from every region in the document**, `"add"` and `"subtract"` alike, so a size or align option cannot scale the subtracts relative to the adds; a `shape` call is measured against that shape alone. **Primitive contours (`circle`/`rect`/`polygon`) expand to ordinary path contours at the format boundary, in `vector-format.js`, so this op's kernel-facing contract is unchanged by them** — nothing below the loader learns primitives exist. Conformance: **both backends** (it lowers to `shape2d` + `union`, exactly like `text2d`). Parity: **identical across backends by construction** — the regions are curve-native (arcs/cubics), so there is no sampling step for the two backends to diverge over. |
 | `hull(inputs[])` | Convex hull of all inputs (each a `Shape2D`, a curve contour, or an `[[x,y],…]` point list) → a convex `Shape2D`. Backend-agnostic: a pure-JS monotone-chain hull over the inputs' sampled points (curved inputs tessellated at a fixed LOD), lifted via `shape2d` (see the parity note below). Throws on an empty input array or a degenerate (collinear/point-count < 3) hull. |
 | `hullChain(inputs[])` | Swept hull over an ordered sequence of ≥2 inputs (same input forms as `hull`): the union of `hull([inᵢ, inᵢ₊₁])` for each consecutive pair — e.g. a tapered link connecting a row of circles. Throws with fewer than 2 inputs. |
-| `toSTEP(named[])` | `[{name, solid}]` → `Promise<ArrayBuffer>` of a STEP assembly. B-rep class only. |
+| `toSTEP(named[])` | `[{name, solid, color?}]` → `Promise<ArrayBuffer>` of a STEP assembly. B-rep class only. `color` (`0xRRGGBB`, optional) is the body's surface colour, written as that exact sRGB value; a body without one (or with an unusable one) is written in the viewer's no-material blue-grey (`0x9fb4cc`), never a kernel default. The framework passes each sub-part's display colour — the one its 3MF object gets. Additive: `CONTRACT_VERSION` stays 4, the `import` precedent. |
 | `import(name)` | Previously-registered imported geometry (STEP/STL/3MF, declared in the part's `imports` field) as an ordinary `Solid`. Required on both in-repo backends (Manifold accepts mesh formats, OCCT accepts STEP); a format the routed backend can't use throws lazily, at this call, not at registration. Fed by an underscore-prefixed side-channel, not part authors — see [Conformance classes](#conformance-classes). Additive: not in `OCCT_ONLY_OPS`; needed no `CONTRACT_VERSION` bump of its own (v3 came from the mesh fillet/chamfer change, not this op). |
 
 `hull`/`hullChain` parity: point-list and curve-contour inputs hull bit-identically
@@ -600,7 +600,17 @@ backend-independently on the contour IR — no backend `CrossSection` or `Drawin
 ever involved. Lines and arcs offset exactly (arcs stay arcs); cubics are
 approximated to ≤ 1e-3 mm deviation. `corners: "round"` inserts exact arc joins,
 `"chamfer"` a true 45°-bisecting bevel chord at every corner angle, `"sharp"` miters
-with limit 2 (falling back to the bevel chord past the limit). Self-intersecting raw
+with limit 2 (falling back to the bevel chord past the limit) — where an arc meets the
+corner it extends along its own circle, not its end tangent (OCCT's intersection join,
+`BRepOffsetAPI_MakeOffset` with `GeomAbs_Intersection`: measured within 2e-3 mm of it on
+D shapes, pies, ring sectors, lenses and notches, `test/offset-oracle-occt.test.js`), so a
+sharp inset grown back by the same amount returns an arc-and-line corner to the winding
+resolver's precision (5e-3 mm), not exactly. The arc is extended up to 90° and the join
+takes the meeting point nearest the corner within 2·|delta|; where the extended pieces
+never meet there — an inner arc that collapses or curls away, as a 3..5 mm ring sector's
+does grown by 2 — the tangent miter applies, then the bevel, and the result matches
+neither OCCT join. A line meeting a line or a cubic is mitred along its end tangent, as
+before. Self-intersecting raw
 results are resolved through the shared planar boolean engine (paper.js), which may
 return arcs as cubic approximations — identical to boolean-op output. `segs` is
 accepted and ignored (there is no backend LOD to tune). Both backends produce
@@ -616,7 +626,7 @@ backwards for the holes (see the migration note below).
 | Op | Contract |
 |---|---|
 | `union(other)` / `cut(other)` / `cutAll(others[])` / `intersect(other)` | 2-D boolean ops; `other` may be a `Shape2D` or a raw profile (lifted via `shape2d` first). Curve-exact and backend-identical (paper.js). |
-| `offset(delta, {corners?, segs?})` | Grows (`delta>0`) or insets (`delta<0`) by `delta` mm; `corners` = `round` (default) / `chamfer` / `sharp`. Runs backend-independently on the contour IR — lines/arcs offset exactly, cubics approximate to ≤ 1e-3 mm; `chamfer` is a true 45°-bisecting bevel at every corner angle, `sharp` miters with limit 2. Backend-identical by construction, like every other Shape2D op. Holes offset material-wise (`-delta` where the outer gets `delta`). `segs` is accepted and ignored. Empty in → empty out (short-circuits before the engine). Throws if the offset collapses the shape. |
+| `offset(delta, {corners?, segs?})` | Grows (`delta>0`) or insets (`delta<0`) by `delta` mm; `corners` = `round` (default) / `chamfer` / `sharp`. Runs backend-independently on the contour IR — lines/arcs offset exactly, cubics approximate to ≤ 1e-3 mm; `chamfer` is a true 45°-bisecting bevel at every corner angle, `sharp` miters with limit 2 (an arc at the corner extends along its circle — OCCT's intersection join, to the resolver's 5e-3 mm, the tangent miter where the extensions never meet). Backend-identical by construction, like every other Shape2D op. Holes offset material-wise (`-delta` where the outer gets `delta`). `segs` is accepted and ignored. Empty in → empty out (short-circuits before the engine). Throws if the offset collapses the shape. |
 | `area()` | Net area (Σ\|outers\| − Σ\|holes\|), mm². Curve-exact. |
 | `boundingBox()` | `{min, max}` — axis-aligned 2-D bounds, curve-exact (no `center`/`size`, unlike `Solid.boundingBox`). |
 | `toRegions()` | Materialize into `{outer, holes}[]` point-ring region arrays (`assembleRegions`), tessellating curves at the backend's LOD; a boolean result may be several disjoint regions. |
@@ -700,19 +710,30 @@ The currently parked limitations are narrower:
 - **Round erosion with several holes reaching the eroded outer can keep too much material.**
   The characterized 30×20 plate with three rectangular holes at −2 returns about 324.75
   instead of the 258.18 oracle truth under round corners; chamfer and sharp are exact.
-- **Fully eroded holes under sharp and chamfer can leave a remnant.** The source-inradius
-  gate is intentionally limited to round joins, whose structuring element is a Euclidean
-  disk. A 1×1 hole at +2 closes correctly under round, while the sharp/chamfer variants
-  remain parked rather than applying the wrong geometric criterion.
+- **Fully eroded holes under chamfer can leave a remnant.** The source-inradius gate
+  (a hole survives a positive offset only if it holds a disk of radius delta) runs for
+  round joins, whose structuring element is that disk, and for sharp ones whose every
+  join on the hole takes the miter, which then erodes the hole at least as deeply — the
+  miter reaches past the arc at the hole's reflex corners. Without it a sharp dilation
+  left the inverted ring as a phantom hole once delta passed twice the hole's half-width.
+  A sharp hole with a spike of material under 60° is NOT gated: there the miter would
+  pass the limit, the join falls back to the bevel, and the bevel chord adds less than the
+  arc, so a real pocket survives that the disk would fill — a 12-ray star hole (rays 5,
+  spikes to 1.2) keeps 0.9–1.9 mm² at +1.3…+2, and the Minkowski oracle agrees. Such a
+  hole takes the ordinary path, which can still leave a phantom if it fully erodes.
+  Chamfer's bevel removes less than the arc at every reflex corner, so the disk rule is
+  the wrong criterion there: a 1×1 hole at +2 closes under round and sharp, and the
+  chamfer variant remains parked (four fuzz seeds at +2 are pinned exactly).
 - **Erosion can emit sub-0.001 mm² rings.** Five exact seeded cases are pinned in
   `test/offset-fuzz.test.js`. They are not automatically deleted: unlike positive
   dilation, erosion has no source-membership invariant that distinguishes a false island
   from a genuine surviving crumb.
 
-The fuzz oracle sweep covers 150 seeded shapes × 6 deltas × 3 styles and currently reports
-no region-count, hole-count, or area disagreements outside those explicit
-characterizations. Do not widen tolerances or add an area-based sliver filter when a new
-case appears; add its deterministic fixture and establish the source-domain truth first.
+The fuzz oracle sweep covers 150 seeded shapes × 7 deltas (five inward; outward, 1 and 2)
+× 3 styles and currently reports no region-count, hole-count, or area disagreements outside
+those explicit characterizations. Do not widen tolerances or add an area-based sliver
+filter when a new case appears; add its deterministic fixture and establish the
+source-domain truth first.
 ## The 2-D helper library
 
 `partforge/geometry` ships pure-JS helpers of several kinds. The **contour builders**
@@ -736,6 +757,15 @@ the helpers come along unmodified. (`test/kernel-contract.test.js` asserts every
 - `pathProfile` — fluent builder for a curve-native path contour (`lineTo` /
   `arcTo` / `cubicTo` / `close`); cubic segments become exact B-rep on OCCT and
   facet at mesh LOD on Manifold.
+- **Sheet parts** — `sheetPart` wraps a laser-cut piece into an ordinary sub-part
+  (a generated `build` and `place` plus a plain-data `sheet` declaration); the
+  joinery helpers `fingers`, `tabs`, `tSlots`, `sheetPanel`, `matchingSlots`,
+  `fingerBox`, `printedTab`, `sheetHole` and the `JOINERY_SCREWS` table are pure
+  functions returning plain data in this contract's input format; `sheetToWorld` /
+  `worldToSheet` convert between a posed sheet's drawing and world coordinates. The
+  generated build calls only ops from the tables above (`shape2d`, `extrude`,
+  `offset`, `cut`, `cutAll`, `translate`, `rotate`), so a sheet part is portable by
+  construction too. None of these is a kernel op.
 
 **Profile validation on the way in** (0.112). `prism`, `extrude`, `revolve`, `sweep`,
 `loft` (per ring) and `shape2d` (including boolean operands) run `validateProfile` on a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.132.1",
+  "version": "0.133.1",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",