partforge 0.133.3 → 0.135.0

package/docs/AUTHORING-PARTS.md

@@ -334,9 +334,10 @@ meta: { title: "…", units: "mm", environment: "studio" },
 - `material` — a preset id from the table below. Without one (or with one the
   library does not know) the sub-part keeps the CAD view's look — its `color`,
   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, export colours and
+  (`pla-print`'s finish and layer lines) in that same colour — except a laser
+  `sheetPart`, which shows its stock instead (below). 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, 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
@@ -349,6 +350,23 @@ meta: { title: "…", units: "mm", environment: "studio" },
 - **One material per sub-part.** Something that needs two finishes (a knurled
   grip in rubber on an aluminium body) is two sub-parts.
 
+**Sheet parts default to their stock.** A laser `sheetPart` that names no material (or
+one the library does not know) is not drawn as a PLA print: realistic mode shows it as the
+sheet its stock label names — the first row with a stem that starts a word of the label,
+ignoring case (so `Plexiglas`, `Acrylite` and `poly-carbonate` match; `perplexing` does not):
+
+| A word of the stock label starts with | Realistic look |
+| --- | --- |
+| `acryl`, `perspex`, `plexi`, `pmma`, `methacryl`, `polycarb`, `lexan`, `makrolon`, `lucite` | `clear-acrylic` |
+| anything else — plywood, birch, basswood, poplar, MDF, hardboard — or no readable label | `plywood` |
+
+Stock that is neither wood nor acrylic — felt, leather, card, cork — takes the `plywood`
+look too, charred edges and all. A `color` tints the look, as it tints any preset (a
+stained plywood, a coloured acrylic); the CAD view still shows the `color` itself. Only a
+string label is read: a stock written as a `(p, d)` function counts as unreadable. Name
+`display.material` to choose the look yourself — for such stock, or any other. Like the
+PLA look, this is realistic-only and never makes a part declare a material.
+
 **Where it shows.** The CAD view (with feature lines) shows each material's
 colour, flattened so dark materials stay readable. **Realistic** mode — the
 viewer's toggle — shows the full material under environment lighting, with a
@@ -365,6 +383,15 @@ displayed. If the lines run the wrong way, fix the export pose with `place()`
 fixed to the sub-part, so they never slide when the camera or an animation
 moves.
 
+**Laser-cut wood.** In realistic mode a laser `sheetPart` in a wood — `plywood`, `oak` or
+`walnut`, named or its stock's default (so a plywood sheet that names no material burns too)
+— shows what the laser did: its cut edges are charred, darker on thicker stock (on
+`plywood` the plies show through), and its engraving and score lines are scorched, while its
+faces stay wood. There is nothing to set, and it is still one material: the char follows
+from the sheet and the wood it is drawn in. It needs the sheet's own frame, so a sheet part
+with a custom `build` or its own `place` shows plain wood. The CAD view and every export are
+unchanged.
+
 **`textureScale` is millimetres, and what it measures depends on the preset's
 pattern** — so a value copied from one preset family is wrong on another (0.2
 on oak shrinks the grain to a 0.2 mm tile, i.e. invisible noise):
@@ -373,7 +400,7 @@ on oak shrinks the grain to a 0.2 mm tile, i.e. invisible noise):
 | --- | --- | --- | --- |
 | layer lines | `pla-print`, `petg-print` | layer height | 0.2 |
 | SLS grain | `nylon-sls` | grain size | 0.15 |
-| wood | `oak`, `walnut` | size of one texture tile (the grain repeats every this many mm) | 250 (`oak`), 400 (`walnut`) |
+| wood | `oak`, `walnut`, `plywood` | size of one texture tile (the grain repeats every this many mm) | 250 (`oak`), 400 (`walnut`), 150 (`plywood`) |
 | carbon weave | `carbon-fiber` | size of one texture tile | 48 |
 
 Presets without a pattern ignore it.
@@ -409,6 +436,7 @@ the viewer's blue-grey.
 | `rubber` | Rubber | yes | Matte elastomer: gaskets, feet, grips; tint with `color`. |
 | `oak` | Oak | — | Light oak with open grain. |
 | `walnut` | Walnut | — | Dark oiled walnut. |
+| `plywood` | Birch plywood | — | Birch plywood sheet: a pale, fine-grained face; its plies show on laser-cut edges. |
 | `carbon-fiber` | Carbon fibre | — | 2x2 twill carbon fibre under clear coat. |
 
 **Environments** (`meta.environment`, default `studio`; viewers can switch):
@@ -1808,8 +1836,8 @@ 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).
+pose. `build` is supplied — passing one throws, as do `kerf`, `outline`/`cut` and
+`quantity`; each error names the fix.
 
 ### Cut, score and engrave
 
@@ -1898,7 +1926,7 @@ PRINT pose, `place` it for display, and cut the slot where the tongue lands:
 | `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
+**Verify** runs the laser checks on every sheet part, as
 *volunteered* warnings: none counts toward `declared`/`evaluated`, so none makes
 `verify.ok` true on its own. Declare one in `expect` to make it count:
 
@@ -1920,16 +1948,21 @@ 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.
 
+### The kit
+
+A host downloads sheet parts as one ZIP, the **cut & print kit** (`format: "bundle"`): `README.txt`, `parts.csv`, laid-out `sheets/`, one `parts/` file per distinct piece (plus a `-marks.dxf` for a cutting service) and `print/` for printed parts. Identical pieces merge into one `-xN` file named from `export: { name }`, else the key. Destination (`"own-laser"` or `"service"`), kerf and stock size are chosen at download, so draw nominal and bind `thickness` to the measured control. A choice the kit cannot honour fails with `cut kit options:`.
+
 ### 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.
+- Poses are rigid and axis-aligned: `face` and `up` are the six axis words. An
+  angled panel is an author `place` after the pose (realistic mode then shows
+  no laser burns), 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.
+- Cut and score are vector lines; engraving is filled regions, never a raster
+  image.
 - 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.
 
@@ -1982,7 +2015,7 @@ 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 PLY = { views: ["box"], display: { material: "plywood" }, 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
@@ -2995,15 +3028,41 @@ view-bound export UI. An embedder that wants its own export UI (e.g. a "pick whi
 pick a format" modal) can skip those buttons and drive export off the handle `mount()`
 returns instead:
 
-- `runtime.listExportableParts() → [{ name, label }]` — every exportable sub-part
+- `runtime.listExportableParts() → [{ name, label, sheet? }]` — every exportable sub-part
   (excludes any `exportable: false` part, respects each part's `enabled(params)`),
-  **independent of the active view**. Use it to populate an export checklist.
-- `runtime.exportParts({ parts, format, quality?, onProgress }) → Promise<void>` — build
-  the given `parts` (sub-part names) in `format` (`"stl" | "step" | "3mf"`), streaming
+  **independent of the active view**. Use it to populate an export checklist. A sheet
+  part's row also carries `sheet: { process, material, thickness, group }`, evaluated at
+  the current params (omitted when that throws) — enough to tag it in the list and to
+  name its stock group in the kit's `stock` option.
+- `runtime.listExportFormats() → [{ id, label, ext, mime, needsSheet }]` — the formats
+  `exportParts` writes in this version, as fresh copies of `EXPORT_FORMATS`. `needsSheet`
+  marks the one that needs a sheet part checked: `"bundle"`, the cut & print kit.
+- `runtime.exportParts({ parts, format, quality?, onProgress, options? }) → Promise<void>` — build
+  the given `parts` (sub-part names) in `format` (`"stl" | "step" | "3mf" | "bundle"`), streaming
   phase strings to `onProgress(phase)`. Resolves once the file is written (handed to your
   `onDownload` sink, or downloaded directly if you don't supply one); rejects on
   build/export failure or an empty selection. Placement uses the current
-  view. STEP is routed to OCCT automatically.
+  view. STEP is routed to OCCT automatically. Only `"bundle"` reads `options`.
+- **The cut & print kit** (`format: "bundle"`) writes one `<title>-kit.zip`: `README.txt`
+  (the thickness each material assumes, the kerf applied, a scale check per piece, the
+  colour or DXF-layer legend, every 2-D check that warned), `parts.csv`,
+  `sheets/<material>-<t>mm/sheet-<i>-of-<n>.svg` (the pieces laid out on the user's
+  stock), `parts/<name>[-xN].svg` (one per distinct piece; identical pieces merge) and
+  `print/<name>[-xN].stl` or `.3mf` (the printed parts, in their export pose). With
+  `destination: "service"` each piece is a cut-only `.dxf` plus a `-marks.dxf` for its
+  score and engrave lines, and the DXF sheets are for reference. Every `options` key is
+  optional: `destination` (`"own-laser"`, the default, or `"service"`), `kerf` (0–0.5 mm,
+  applied to the cut lines only), `stock: [{ group, size: [w, h] }]` (a row's
+  `sheet.group`; a `"*"` entry sizes every group that has no entry of its own; 300 × 300
+  mm when `stock` is omitted), `margin` (5 mm),
+  `spacing` (3 mm), `printFormat` (`"stl"` or `"3mf"`) and `sets` (1–20). The main entry
+  exports `EXPORT_FORMATS`, `KIT_DEFAULTS`, `validateKitOptions` and `KIT_OPTIONS_ERROR`
+  for a host that draws its own options screen. An option the kit cannot honour — an
+  unknown key, a kerf that closes a slot, a piece bigger than an own laser's sheet, a
+  margin that leaves no room on the sheet, a stock entry naming no group, more than 200
+  pieces or 50 sheets of one material —
+  rejects with a message starting `cut kit options:`: the user's setting to change, not
+  the part's code.
 - `runtime.warmExportKernel() → Promise<boolean>` — pay OCCT's cold boot *before* an
   export needs it. Because STEP is pinned to OCCT and OCCT's ~11 MB WASM loads on its
   first job, a part whose preview ran on Manifold pays that whole boot inside its first
@@ -3147,7 +3206,8 @@ addition to) the generated view style button above:
   revert too.
 - `runtime.declaresMaterials` — `true` when any sub-part names a
   `display.material`. A part with none still supports realistic mode (every
-  sub-part renders as a PLA print in its CAD colour), so use this to decide
+  sub-part renders as a PLA print in its CAD colour, a laser sheet part as its
+  stock — "Sheet parts default to their stock"), so use this to decide
   whether to surface your own realistic control at all, not whether it works.
   Feature lines are not a preference: they draw whenever `runtime.renderMode`
   reads `"cad"` and never while it reads `"realistic"` — there is no switch
@@ -3635,7 +3695,8 @@ trust handling.
 
 **Appearance** (all warnings) — `unknown-material` (a `display.material` the
 library does not know; the viewer draws it as if it named none — a PLA print
-in realistic mode), `unknown-environment`
+in realistic mode, or for a laser sheet part its stock's look, per "Sheet parts
+default to their stock"), `unknown-environment`
 (`meta.environment` not known; realistic mode uses `studio`),
 `material-key-unknown` (a `display` key that is not colour, opacity, material
 or one of the six overrides; ignored), `material-override-clamped` (an override

package/docs/KERNEL-CONTRACT.md

@@ -852,7 +852,7 @@ maps that protocol onto `setPart` itself.
   readiness exactly as it would on a freshly spawned worker.
 
 **Epoch guard.** Generates supersede each other; exports (`export-stl`/`export-step`/
-`export-3mf`), `inspect`, and `lint` are **never** epoch-guarded — cancelling a user's
+`export-3mf`/`export-bundle`), `inspect`, and `lint` are **never** epoch-guarded — cancelling a user's
 export because an edit landed would be wrong. A generate that is stale by the time the
 job pump reaches it is skipped and never builds at all. A generate already running
 re-checks staleness at each sub-part boundary and, if it has been superseded, stops

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.133.3",
+  "version": "0.135.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/app-materials.js

@@ -12,7 +12,9 @@ import { mount } from "./framework/index.js";
 // open /materials.html. Not part of the production build — check materials.html
 // by eye after any preset or shader change (see AGENTS.md "Architecture").
 // Dev-only: the handle is stashed on window so scripts/check-app.mjs can drive
-// the embedding contract (runtime.captureCurrent) the way an embedder would.
+// the embedding contract (runtime.captureCurrent) the way an embedder would, and
+// scripts/capture-contact-sheet.mjs can switch views and environments and call
+// runtime.renderViews — removing it breaks both.
 window.__pfRuntime = mount(materialSwatchesPart, {
   createWorker: (name) =>
     new Worker(new URL("./materials-worker.js", import.meta.url), { type: "module", name }),

package/src/framework/export/bundle.js

@@ -0,0 +1,413 @@
+// The cut & print kit (spec D): one ZIP per forge — every checked sheet part drawn flat
+// and laid out on the user's stock, every checked printed part as STL or 3MF, a README
+// and a parts list.
+//
+// jobs.js loads this module LAZILY, on the first export-bundle job (`loadBundle`), never
+// at worker boot (test/worker-layering.test.js). And nothing here may reach ./oracle/*
+// (test/kit-layering.test.js mocks every oracle module to throw): the mesh oracle has
+// OOM-killed iOS Safari, and the kit needs none of it — a sheet is drawn from its 2-D
+// declaration and checked by its own process's facts()/checks().
+import { zipSync, strToU8 } from "fflate";
+import { safeName } from "../safe-name.js";
+import { meshTo3MF } from "../geometry/threemf.js";
+import { h } from "../geometry/solid-hash.js";
+import { printColor } from "../materials/resolve.js";
+import {
+  isSheetPart, sheetMeta, fmtMm, SHEET_CHECK_BUDGET_MS, SHEET_CHECKS_NOTICE, SHEET_READ_ERROR_HINT,
+} from "../sheet/constants.js";
+import { resolveSheet } from "../sheet/resolve.js";
+import { processById, SHEET_METRICS } from "../process/registry.js";
+import { loadExporter } from "../process/exporters.js";
+import { validateKitOptions, resolveStock, KIT_OPTIONS_ERROR, KIT_LIMITS } from "./formats.js";
+import { canonicalDrawingKey } from "./drawing.js";
+import { renderSvg } from "./svg.js";
+import { renderDxf } from "./dxf.js";
+import { layoutGroup, marginFitsStock } from "./layout.js";
+import { renderReadme, renderPartsCsv, cleanLabel } from "./readme.js";
+
+// Every entry name the kit may write (spec D.10). test/kit-bundle.test.js pins every
+// kit it builds against it, and buildBundle asserts it again before zipping.
+export const KIT_ENTRY_RE = /^(README\.txt|parts\.csv|sheets\/[a-z0-9][a-z0-9._-]*\/sheet-\d+-of-\d+\.(svg|dxf)|parts\/[a-z0-9][a-z0-9._-]*(-x\d+)?(-marks)?\.(svg|dxf)|print\/[a-z0-9][a-z0-9._-]*(-x\d+)?\.(stl|3mf))$/;
+
+// A path segment from an author string. safeName already lowercases, collapses runs and
+// refuses a leading dot or dash; folding every run of dots on top means no entry name
+// can ever carry "..". safeName keeps a leading underscore, which KIT_ENTRY_RE (copied
+// verbatim by the cloud) refuses, so it comes off here too — a sub-part keyed `_left`
+// is `left`, never a kit that fails at its last step — and a name that was nothing but
+// separators falls back to "part".
+export const kitName = (s) => safeName(s, "part").replace(/\.{2,}/g, ".").replace(/^[._-]+/, "") || "part";
+
+// The first of base, base-2, base-3, … whose files are all free, claimed in `taken`.
+// `filesOf(name)` lists every path a name produces — a piece's cut file and its -marks
+// file — so a name is free only when all of them are, and "front" ×2 can never land on
+// the file of a piece literally named "front-x2". Called in definition order, so a
+// forge always gets the same names.
+export function uniqueName(base, taken, filesOf = (name) => [name]) {
+  let name = base;
+  for (let i = 2; filesOf(name).some((f) => taken.has(f)); i++) name = `${base}-${i}`;
+  for (const f of filesOf(name)) taken.add(f);
+  return name;
+}
+
+// Merge equal items, first-seen order kept. `hashOf` only NOMINATES candidates — the kit
+// hashes with solid-hash.js's 32-bit FNV, which can collide — and `same(a, b)` confirms.
+// Returns [{ item, members }], `item` being the first member.
+export function dedupe(items, hashOf, same) {
+  const groups = [];
+  const byHash = new Map();
+  for (const item of items) {
+    const key = hashOf(item);
+    const candidates = byHash.get(key) ?? [];
+    const hit = candidates.find((g) => same(g.item, item));
+    if (hit) { hit.members.push(item); continue; }
+    const group = { item, members: [item] };
+    candidates.push(group);
+    byHash.set(key, candidates);
+    groups.push(group);
+  }
+  return groups;
+}
+
+// verify's wording for the three expression forms a process's checks() emits — ">=N",
+// "<=N" and a bare number (equality) — restated from oracle/assert-dsl.js, because the
+// kit must never load ./oracle/*. test/kit-bundle-helpers.test.js holds the two equal.
+// Any other form throws: it needs a line here, not a silent pass.
+const EPS = 1e-6;
+export function checkMessage(expr, actual) {
+  const m = /^(>=|<=)?\s*([-+]?[0-9]*\.?[0-9]+)$/.exec(String(expr).trim());
+  if (!m) throw new Error(`cut kit: unsupported sheet check "${expr}"`);
+  const value = Number(m[2]);
+  if (m[1] === ">=") {
+    const pass = actual >= value - EPS;
+    return { pass, message: `${actual} ${pass ? ">=" : "not >="} ${value}` };
+  }
+  if (m[1] === "<=") {
+    const pass = actual <= value + EPS;
+    return { pass, message: `${actual} ${pass ? "<=" : "not <="} ${value}` };
+  }
+  const pass = Math.abs(actual - value) <= EPS + EPS * Math.abs(value);
+  return { pass, message: `${actual} ${pass ? "==" : "!="} ${value}` };
+}
+
+// SHEET_CHECKS_NOTICE.message ("2-D sheet checks not evaluated (time budget)") is
+// oracle/verify.js's own wording for the same state, imported from sheet/constants.js —
+// the one place it lives, since the kit must never load ./oracle/*. The kit appends its
+// own reason to the shared prefix rather than restating the whole line.
+const NOT_EVALUATED = `${SHEET_CHECKS_NOTICE.message} — the kit ran out of time checking this piece for narrow webs, narrow gaps and stray marks; look it over before cutting`;
+
+// The README's CHECKS lines for one piece: every volunteered check its process runs
+// that fails, as `${label}: ${message} — ${hint}` with the metric's own hint. A metric
+// with no reading (budget-gated and not evaluated, or a custom build's volume match,
+// which needs a solid the kit never builds) is skipped; an unevaluated piece gets one
+// line saying so instead. A metric the geometry engine refused to read (readErrors) gets
+// its own line, worded like verify's: `not measured — <reason>`, with SHEET_READ_ERROR_HINT
+// (sheet/constants.js, imported above — the kit must never load ./oracle/* itself, so it
+// reads the one shared text rather than a copy) — never the metric's own hint, which
+// describes a value that was never taken.
+export function sheetWarnings(label, facts) {
+  const desc = facts ? processById(facts.process) : null;
+  if (!desc) return [];
+  const out = [];
+  for (const [metric, expr] of Object.entries(desc.checks(facts))) {
+    const reg = SHEET_METRICS[metric];
+    const actual = reg?.extract({ sheet: facts });
+    if (actual === null || actual === undefined) {
+      const why = reg?.readError?.({ sheet: facts });
+      if (why) out.push(`${label}: not measured — ${why} — ${SHEET_READ_ERROR_HINT}`);
+      continue;
+    }
+    const { pass, message } = checkMessage(expr, actual);
+    if (!pass) out.push(`${label}: ${message} — ${reg.hint}`);
+  }
+  if (facts.evaluated === false) out.push(`${label}: ${NOT_EVALUATED}`);
+  return out;
+}
+
+// ─── buildBundle ────────────────────────────────────────────────────────────
+
+// cl:src/sandbox/protocol.js clips a progress phase at 120 characters; the kit keeps
+// its own phases under that, so a long label is cut here, once, with an ellipsis.
+const PHASE_MAX = 120;
+const clipPhase = (s) => (s.length > PHASE_MAX ? `${s.slice(0, PHASE_MAX - 1)}…` : s);
+const sizeOf = (b) => [b.max[0] - b.min[0], b.max[1] - b.min[1]];
+const near = (a, b) => Math.abs(a - b) <= 1e-6 * Math.max(1, Math.abs(a), Math.abs(b));
+// The words of a control's key or label: camelCase, snake_case, digits and spaces all
+// split, lowercased — "fingerClearance" → finger, clearance.
+const wordsOf = (s) => String(s ?? "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([a-zA-Z])([0-9])/g, "$1 $2")
+  .toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+// Controls the README lists as design fit rather than kerf (spec D.9): a WORD of the key
+// or label is clearance, fit or play — so "Finger clearance", "tab_play" and "pressFit"
+// are listed, and "display", "outfit" and "profit" are not.
+const CLEARANCE_WORDS = new Set(["clearance", "clearances", "fit", "play"]);
+const isClearance = (c) => [...wordsOf(c.key), ...wordsOf(c.label)].some((w) => CLEARANCE_WORDS.has(w));
+const ALL_LAYERS = ["cut", "score", "engrave"];
+
+// Every control that owns a parameter key, whatever the section shape: authored
+// `controls` (groups nest), and the legacy `advanced`, `toggles`, `features` and a
+// feature's own `sliders`. Groups and presets own no key.
+function collectControls(parameters) {
+  const out = [];
+  const visit = (list) => {
+    for (const c of Array.isArray(list) ? list : []) {
+      if (!c || typeof c !== "object") continue;
+      if (typeof c.key === "string" && c.type !== "group" && c.type !== "preset") out.push(c);
+      visit(c.controls);
+      visit(c.sliders);
+    }
+  };
+  for (const sec of Array.isArray(parameters) ? parameters : []) {
+    visit(sec?.controls); visit(sec?.advanced); visit(sec?.toggles); visit(sec?.features);
+  }
+  return out;
+}
+
+// The control that sets a sheet part's thickness, so the README can name the setting to
+// change when the user's sheet measures differently. Of the controls the thickness
+// function reads, the one whose value IS the thickness it returned (a
+// `p.material === "acrylic" ? p.acrylicT : p.plyT` reads Material first, and Material
+// is not the thickness); failing a single such control, the one read whose key or label
+// says "thick"; else null — the generic wording, never a guess. Null too for a literal
+// thickness or one that reads no control.
+function thicknessControlLabel(controls, sp, p, d) {
+  const t = sp.sheet.thickness;
+  if (typeof t !== "function") return null;
+  const reads = new Set();
+  const spy = new Proxy(p, { get: (target, key) => { if (typeof key === "string") reads.add(key); return target[key]; } });
+  let value;
+  try { value = t(spy, d); } catch { return null; }
+  const read = controls.filter((x) => reads.has(x.key));
+  const holds = read.filter((x) => typeof p[x.key] === "number" && Math.abs(p[x.key] - value) <= 1e-9);
+  const pool = holds.length > 1 ? holds : read;
+  const named = pool.filter((x) => [...wordsOf(x.key), ...wordsOf(x.label)].some((w) => w.startsWith("thick")));
+  const c = holds.length === 1 ? holds[0] : named.length === 1 ? named[0] : null;
+  return c ? String(c.label ?? c.key) : null;
+}
+
+// A sheet part's stock group, or the part's own named error: sheetMeta answers null
+// when material or thickness cannot be evaluated, and resolveSheet is what knows how to
+// say why.
+function sheetMetaOrThrow(kernel, sp, p, d, name) {
+  const meta = sheetMeta(sp, p, d);
+  if (meta) return meta;
+  resolveSheet(kernel, sp, p, d);
+  throw new Error(`sheet part "${name}": its material or thickness could not be evaluated`);
+}
+
+// One export-bundle job's kit. `names` is the job's selected() — exportable, enabled, in
+// definition order — and `posed`/`label`/`exportName` are jobs.js's own, so a kit's
+// printed parts are built exactly the way the STL and 3MF exports build them.
+export async function buildBundle({ kernel, part, msg, p, d, posed, label, exportName, names, onProgress, fileBase }) {
+  // Options first, before anything is built: a bad option is the user's to fix and must
+  // not wait behind a build (spec D.3). An absent options object means every default.
+  const o = validateKitOptions(msg.options ?? {});
+  const service = o.destination === "service";
+  const cutExt = service ? "dxf" : "svg";
+  const say = (phase) => onProgress(clipPhase(phase));
+  const nameOf = (name) => cleanLabel(label(name));
+  if (names.length === 0) throw new Error("no exportable parts selected");
+  const sheetNames = names.filter((name) => isSheetPart(part.parts[name]));
+  const printNames = names.filter((name) => !isSheetPart(part.parts[name]));
+  if (sheetNames.length === 0) {
+    throw new Error(`${KIT_OPTIONS_ERROR} none of the checked parts is a sheet part — check a sheet part or export STL/3MF instead`);
+  }
+  // The cut-piece count is sheet sub-parts × sets — exactly what the merged pieces sum
+  // to — so it is checked before the builds it would otherwise waste. The remedy named
+  // is one that can work: past the cap at a single set, only fewer parts will do.
+  const cutCount = sheetNames.length * o.sets;
+  if (cutCount > KIT_LIMITS.pieces) {
+    const remedy = sheetNames.length > KIT_LIMITS.pieces ? "check fewer sheet parts" : "lower sets";
+    throw new Error(`${KIT_OPTIONS_ERROR} the kit has ${cutCount} pieces — at most ${KIT_LIMITS.pieces}; ${remedy}`);
+  }
+
+  // Stock groups from each part's material and thickness alone, so a stock entry that
+  // names no group in the kit fails before any drawing is made.
+  const groups = new Map();
+  const groupOf = new Map();
+  for (const name of sheetNames) {
+    const meta = sheetMetaOrThrow(kernel, part.parts[name], p, d, nameOf(name));
+    if (!groups.has(meta.group)) {
+      const material = cleanLabel(meta.material);
+      groups.set(meta.group, { group: meta.group, material, thickness: meta.thickness,
+        label: `${material} ${fmtMm(meta.thickness)} mm`, first: name });
+    }
+    groupOf.set(name, meta.group);
+  }
+  const stockFor = resolveStock(o.stock, [...groups.values()].map((g) => ({ group: g.group, label: g.label })));
+  // A margin that leaves a group's stock with no inside at all is known right here —
+  // check it before any piece is drawn (spec D.3), not only once layoutGroup reaches
+  // that group after every sheet part has been built.
+  for (const g of groups.values()) marginFitsStock(stockFor.get(g.group), o.margin, g.label);
+
+  // Draw every sheet part flat, from its 2-D declaration, with its 2-D facts under ONE
+  // budget for the whole kit.
+  const deadline = Date.now() + SHEET_CHECK_BUDGET_MS;
+  const drawn = [];
+  for (const name of sheetNames) {
+    say(`building ${nameOf(name)}`);
+    const s = resolveSheet(kernel, part.parts[name], p, d);
+    const desc = processById(s.process);
+    if (!desc) throw new Error(`sheet part "${nameOf(name)}": unknown process "${s.process}"`);
+    const facts = desc.facts(s, { deadline });
+    const exporter = await loadExporter(s.process);
+    const drawing = exporter.drawing(s, o, kernel, { label: nameOf(name), facts });
+    drawn.push({ name, label: nameOf(name), fileKey: exportName(name), group: groupOf.get(name),
+      drawing, facts, key: canonicalDrawingKey(drawing) });
+  }
+
+  // Identical pieces become one file ×N (spec D.4): the hash nominates; the canonical
+  // drawing and the stock group confirm.
+  const pieces = dedupe(drawn, (x) => h(x.key), (a, b) => a.key === b.key && a.group === b.group)
+    .map(({ item, members }) => ({
+      ...item, labels: members.map((m) => m.label), qty: members.length * o.sets,
+      hasMarks: item.drawing.layers.some((l) => l.id === "score" || l.id === "engrave"),
+    }));
+
+  // Names, in definition order. A name that was taken moves to name-2; the README's
+  // RENAMED FILES says which file it was and who held the name (spec D.10). A piece
+  // claims its bare name as well as its files (the `parts/<name>/` key, which no file
+  // path can equal): `-x<n>` is a QUANTITY, so a second, different piece with the
+  // same name must be name-2 — never name.svg beside name-x2.svg, which reads as one
+  // piece at two quantities.
+  const taken = new Set();
+  const owners = new Map();
+  const renamed = [];
+  const claim = (base, filesOf, labels) => {
+    const name = uniqueName(base, taken, filesOf);
+    const file = filesOf(name)[0];
+    if (name !== base) {
+      const holder = filesOf(base).map((f) => owners.get(f)).find(Boolean);
+      renamed.push(`${file}: ${labels.join(", ")}${holder ? ` (renamed: ${holder.file} is ${holder.labels.join(", ")})` : ""}`);
+    }
+    for (const f of filesOf(name)) owners.set(f, { file, labels });
+    return name;
+  };
+  for (const pc of pieces) {
+    const sx = pc.qty > 1 ? `-x${pc.qty}` : "";
+    const marks = service && pc.hasMarks;
+    const name = claim(kitName(pc.fileKey),
+      (n) => [`parts/${n}${sx}.${cutExt}`, ...(marks ? [`parts/${n}${sx}-marks.dxf`] : []), `parts/${n}/`], pc.labels);
+    pc.file = `parts/${name}${sx}.${cutExt}`;
+    pc.marksFile = marks ? `parts/${name}${sx}-marks.dxf` : null;
+  }
+
+  // Lay out each stock group. An own laser needs every piece to fit (layoutGroup
+  // throws "stock too small"); for a cutting service the sheets are reference only, so
+  // an oversized piece is listed in the README instead (spec D.5).
+  const sheets = [];
+  const oversized = [];
+  for (const g of groups.values()) {
+    const inGroup = pieces.filter((pc) => pc.group === g.group);
+    const count = inGroup.reduce((n, pc) => n + pc.qty, 0);
+    say(`laying out ${g.material} ${fmtMm(g.thickness)} mm (${count} pieces)`);
+    const stock = stockFor.get(g.group);
+    const laid = layoutGroup({
+      group: g.group, label: g.label, stock, margin: o.margin, spacing: o.spacing, strict: !service,
+      pieces: inGroup.map((pc) => ({ key: pc.file, label: pc.labels[0], drawing: pc.drawing, qty: pc.qty })),
+    });
+    if (laid.sheets.length > KIT_LIMITS.sheetsPerGroup) {
+      throw new Error(`${KIT_OPTIONS_ERROR} ${g.material} ${fmtMm(g.thickness)} mm needs ${laid.sheets.length} sheets — at most ${KIT_LIMITS.sheetsPerGroup} per material; use larger stock or fewer sets`);
+    }
+    const dir = claim(kitName(`${g.material}-${fmtMm(g.thickness)}mm`), (n) => [`sheets/${n}/`], [g.label]);
+    laid.sheets.forEach((sh, i) => sheets.push({
+      file: `sheets/${dir}/sheet-${i + 1}-of-${laid.sheets.length}.${cutExt}`,
+      group: g, stock, placements: sh.placements, used: sh.used, index: i + 1, count: laid.sheets.length,
+    }));
+    for (const key of laid.oversized) {
+      const pc = inGroup.find((x) => x.file === key);
+      const [w, ht] = sizeOf(pc.drawing.bounds);
+      oversized.push(`${pc.labels.join(", ")}: ${w.toFixed(1)} × ${ht.toFixed(1)} mm does not fit a ${fmtMm(stock[0])} × ${fmtMm(stock[1])} mm sheet after its ${fmtMm(o.margin)} mm margin (${g.label}) — cut it from ${pc.file}`);
+    }
+  }
+
+  // Printed parts, posed for export exactly as the STL/3MF exports pose them. Identical
+  // prints merge: the solid hash nominates; volume, bounding box, triangle count and
+  // print colour confirm (spec D.4).
+  const quality = msg.quality ?? "print";
+  const builtPrints = [];
+  for (const name of printNames) {
+    say(`building ${nameOf(name)}`);
+    const solid = posed(name, "export", onProgress);
+    const box = solid.boundingBox();
+    const display = part.parts[name]?.display;
+    const pp = {
+      name, label: nameOf(name), fileKey: exportName(name), hash: String(solid._hash ?? ""),
+      size: [0, 1, 2].map((i) => box.max[i] - box.min[i]), volume: solid.volume(),
+      color: printColor(display), material: typeof display?.material === "string" ? display.material : "",
+    };
+    if (o.printFormat === "stl") {
+      pp.bytes = new Uint8Array(await solid.toSTL({ quality }));
+      pp.triangles = new DataView(pp.bytes.buffer, pp.bytes.byteOffset, pp.bytes.byteLength).getUint32(80, true);
+    } else {
+      const { positions, indices } = solid.toIndexedMesh({ quality });
+      pp.mesh = { positions, indices };
+      pp.triangles = indices.length / 3;
+    }
+    builtPrints.push(pp);
+  }
+  const prints = dedupe(builtPrints, (x) => x.hash, (a, b) => a.triangles === b.triangles && a.color === b.color
+      && near(a.volume, b.volume) && a.size.every((x, i) => near(x, b.size[i])))
+    .map(({ item, members }) => ({ ...item, labels: members.map((m) => m.label), qty: members.length * o.sets }));
+  for (const pp of prints) {
+    const sx = pp.qty > 1 ? `-x${pp.qty}` : "";
+    const filesOf = (n) => [`print/${n}${sx}.${o.printFormat}`, `print/${n}/`];
+    pp.file = filesOf(claim(kitName(pp.fileKey), filesOf, pp.labels))[0];
+    if (!pp.bytes) pp.bytes = new Uint8Array(meshTo3MF([{ name: pp.fileKey, ...pp.mesh, color: pp.color }]));
+  }
+
+  // The files (spec D.8): own laser — an SVG per sheet and per piece; service — a
+  // cut-only DXF per piece, a -marks.dxf where it has marks, and reference DXF sheets.
+  say("writing cut files");
+  const title = cleanLabel(part.meta?.title ?? fileBase);
+  const files = [];
+  const put = (file, text) => files.push({ file, data: strToU8(text) });
+  for (const sh of sheets) {
+    const doc = { title: `${title} — ${sh.group.label} — sheet ${sh.index} of ${sh.count}`, size: sh.stock, placements: sh.placements };
+    put(sh.file, service ? renderDxf(doc, { include: ALL_LAYERS }) : renderSvg(doc));
+  }
+  for (const pc of pieces) {
+    const doc = { title: pc.labels.join(", "), size: sizeOf(pc.drawing.bounds),
+      placements: [{ drawing: pc.drawing, at: [0, 0], rotated: false }] };
+    if (!service) { put(pc.file, renderSvg(doc)); continue; }
+    put(pc.file, renderDxf(doc, { include: ["cut"] }));
+    if (pc.marksFile) put(pc.marksFile, renderDxf(doc, { include: ["score", "engrave"] }));
+  }
+  for (const pp of prints) files.push({ file: pp.file, data: pp.bytes });
+
+  const controls = collectControls(part.parameters);
+  const readme = renderReadme({
+    title, destination: o.destination, cutFormat: o.cutFormat, kerf: o.kerf,
+    stockNotes: [...groups.values()].map((g) => ({ material: g.material, thickness: g.thickness,
+      control: thicknessControlLabel(controls, part.parts[g.first], p, d) })),
+    scale: pieces.map((pc) => ({ label: pc.labels.join(", "), nominal: pc.drawing.nominal, drawn: sizeOf(pc.drawing.bounds) })),
+    sheets: sheets.map((sh) => ({ file: sh.file, material: sh.group.material, thickness: sh.group.thickness,
+      size: sh.stock, pieces: sh.placements.length, used: sh.used })),
+    pieces: pieces.map((pc) => ({ file: pc.file, marksFile: pc.marksFile, labels: pc.labels, material: groups.get(pc.group).material,
+      thickness: groups.get(pc.group).thickness, size: pc.drawing.nominal, quantity: pc.qty })),
+    printed: prints.map((pp) => ({ file: pp.file, labels: pp.labels, quantity: pp.qty })),
+    clearances: controls.filter(isClearance)
+      .map((c) => ({ label: c.label ?? c.key, value: p[c.key], unit: c.unit ?? "" })),
+    settings: Object.keys(p).map((key) => ({ key, value: p[key] })),
+    checks: pieces.flatMap((pc) => sheetWarnings(pc.labels.join(", "), pc.facts)),
+    oversized, renamed,
+  });
+  const csv = renderPartsCsv([
+    ...pieces.map((pc) => ({ file: pc.file, kind: "sheet", labels: pc.labels, material: groups.get(pc.group).material,
+      thickness: groups.get(pc.group).thickness, width: pc.drawing.nominal[0], height: pc.drawing.nominal[1], quantity: pc.qty })),
+    ...prints.map((pp) => ({ file: pp.file, kind: "print", labels: pp.labels, material: pp.material, thickness: null,
+      width: pp.size[0], height: pp.size[1], quantity: pp.qty })),
+  ]);
+
+  // Every planned file must land under its own name: a path two files shared would
+  // silently overwrite one of them, so the count is asserted, and every name is held to
+  // the entry pattern once more on the way in.
+  const planned = [{ file: "README.txt", data: strToU8(readme) }, { file: "parts.csv", data: strToU8(csv) }, ...files];
+  const entries = {};
+  for (const { file, data } of planned) {
+    if (!KIT_ENTRY_RE.test(file) || file.includes("..")) throw new Error(`cut kit: bad entry name ${JSON.stringify(file)}`);
+    entries[file] = data;
+  }
+  const built = Object.keys(entries).length;
+  if (built !== planned.length) throw new Error(`cut kit: planned ${planned.length} files but built ${built}`);
+  say("zipping kit");
+  return { data: zipSync(entries, { level: 6 }), filename: `${fileBase}-kit.zip` };
+}