partforge 0.133.3 → 0.135.0

package/src/framework/export/layout.js

@@ -0,0 +1,92 @@
+// The kit's sheet layout: one stock group's pieces packed onto sheets of one stock size.
+// Deterministic first-fit decreasing-height SHELVES over each piece's bounding box of ALL
+// its layers, kerf included — a stray engrave or score mark must never land on a
+// neighbour — turned 0° or 90°, `margin` in from every sheet edge and `spacing` apart,
+// so no two pieces share a cut line. v1 packs rectangles only: no nesting into holes,
+// grain ignored; the README says so (design spec D.5).
+//
+// Coordinates are the sheet frame: mm, y up, origin at the sheet's corner. A placement's
+// `at` is where the (turned) drawing's bounds.min lands (contract §5.6).
+import { fmtMm } from "../sheet/constants.js";
+import { KIT_OPTIONS_ERROR } from "./formats.js";
+
+const EPS = 1e-9;
+const sizeOf = ({ min, max }) => [max[0] - min[0], max[1] - min[1]];
+const byKey = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+// Throws when `margin` leaves a stock sheet with no inside at all — the options' fault,
+// for either destination, not a "stock too small" quoting a negative size, nor a service
+// kit with every piece oversized. `label` is the group's `${material} ${fmtMm(t)} mm`.
+// The options allow a 50 mm margin and a 10 mm stock side, which together can trigger
+// this. Exported so buildBundle can check every stock group right after resolveStock —
+// before any piece is drawn (spec D.3: a bad option must not wait behind a build) —
+// rather than only once a group finally reaches layoutGroup below, which calls this too
+// so a caller that skips the early check (or a future one) still gets it.
+export function marginFitsStock(stock, margin, label) {
+  const [W, H] = stock;
+  const innerW = W - 2 * margin, innerH = H - 2 * margin;
+  if (innerW <= EPS || innerH <= EPS)
+    throw new Error(`${KIT_OPTIONS_ERROR} a ${fmtMm(W)} × ${fmtMm(H)} mm sheet has no room inside a ${fmtMm(margin)} mm margin on every side (${label}) — lower margin or use larger stock`);
+  return [innerW, innerH];
+}
+
+// `pieces`: [{ key, label, drawing, qty }] — `key` names the piece in `oversized` and
+// breaks sort ties; `label` is what an error quotes. The `label` argument is the group's
+// `${material} ${fmtMm(t)} mm`; `group` is accepted and not needed here. `strict` (own
+// laser): a piece that fits the sheet in neither orientation is an options error;
+// otherwise (a cutting service, whose sheets are reference only) its key is listed in
+// `oversized` and it is left out. The sheets-per-group cap belongs to the caller — this
+// only packs.
+export function layoutGroup({ label, pieces, stock, margin, spacing, strict }) {
+  const [W, H] = stock;
+  const [innerW, innerH] = marginFitsStock(stock, margin, label);
+  const items = [];
+  const oversized = [];
+  for (const pc of pieces) {
+    const [w, h] = sizeOf(pc.drawing.bounds);
+    const fits = [];
+    if (w <= innerW + EPS && h <= innerH + EPS) fits.push({ rotated: false, w, h });
+    if (h <= innerW + EPS && w <= innerH + EPS) fits.push({ rotated: true, w: h, h: w });
+    if (fits.length === 0) {
+      if (strict)
+        throw new Error(`${KIT_OPTIONS_ERROR} stock too small — "${pc.label}" is ${w.toFixed(1)} × ${h.toFixed(1)} mm; a ${fmtMm(W)} × ${fmtMm(H)} mm sheet leaves ${fmtMm(innerW)} × ${fmtMm(innerH)} after its ${fmtMm(margin)} mm margin (${label})`);
+      oversized.push(pc.key);
+      continue;
+    }
+    // The orientation with the smaller height packs shelves tighter; 0° wins a tie.
+    const pick = fits.length === 2 && fits[1].h < fits[0].h - EPS ? fits[1] : fits[0];
+    for (let i = 0; i < pc.qty; i++) items.push({ key: pc.key, drawing: pc.drawing, ...pick });
+  }
+  items.sort((a, b) => b.h - a.h || b.w - a.w || byKey(a.key, b.key));
+
+  // Each sheet: shelves bottom-up ({ y, h, x: used width, n: pieces }), `top` = the last
+  // shelf's upper edge, `area` = placed bounding-box area.
+  const sheets = [];
+  const place = (sh, shelf, it) => {
+    const x = shelf.n ? shelf.x + spacing : 0;
+    sh.placements.push({ drawing: it.drawing, at: [margin + x, margin + shelf.y], rotated: it.rotated });
+    shelf.x = x + it.w; shelf.n++; sh.area += it.w * it.h;
+  };
+  for (const it of items) {
+    // 1. the first shelf, on any sheet, with room left along it
+    const onShelf = (() => {
+      for (const sh of sheets) for (const shelf of sh.shelves) {
+        const x = shelf.n ? shelf.x + spacing : 0;
+        if (x + it.w <= innerW + EPS && it.h <= shelf.h + EPS) return [sh, shelf];
+      }
+      return null;
+    })();
+    if (onShelf) { place(onShelf[0], onShelf[1], it); continue; }
+    // 2. a new shelf on the first sheet with height left; 3. else a new sheet
+    let sh = sheets.find((s) => s.top + spacing + it.h <= innerH + EPS);
+    if (!sh) { sh = { placements: [], shelves: [], top: -spacing, area: 0 }; sheets.push(sh); }
+    const shelf = { y: sh.top + spacing, h: it.h, x: 0, n: 0 };
+    sh.shelves.push(shelf);
+    sh.top = shelf.y + it.h;
+    place(sh, shelf, it);
+  }
+  return {
+    sheets: sheets.map((sh) => ({ placements: sh.placements, used: (100 * sh.area) / (W * H) })),
+    oversized,
+  };
+}

package/src/framework/export/placement.js

@@ -0,0 +1,14 @@
+// Shared by the kit's SVG and DXF writers: one Drawing's frame → the sheet frame for one
+// placement. IMPORT-FREE, like formats.js — svg.js and dxf.js are each a "paper-free leaf
+// (arc-math.js only)" on their own, and this tiny third leaf is what lets them share the
+// placement math without either reaching into the other or into drawing.js (which reaches
+// paper).
+
+// Translate so the drawing's bounds.min lands on `at`, after an optional 90° CCW turn (a
+// proper rotation: arcs keep their sense).
+export function placer({ drawing, at, rotated }) {
+  const { min, max } = drawing.bounds;
+  if (!rotated) return ([x, y]) => [x - min[0] + at[0], y - min[1] + at[1]];
+  // (x, y) → (−y, x); the turned bounds' min corner is (−max.y, min.x)
+  return ([x, y]) => [max[1] - y + at[0], x - min[0] + at[1]];
+}

package/src/framework/export/readme.js

@@ -0,0 +1,103 @@
+// The kit's two plain-text files: README.txt, read by a person standing at the laser,
+// and parts.csv, opened in a spreadsheet (spec D.9). Pure string building over a model
+// that export/bundle.js assembles, so both are testable without a kernel.
+//
+// Neither carries a timestamp — the same forge and options always write the same bytes
+// — and neither is Markdown: every label is an author string, and plain text is the one
+// format in which nothing an author writes renders as anything.
+import { fmtMm } from "../sheet/constants.js";
+
+export const README_HEADINGS = Object.freeze([
+  "BEFORE YOU CUT", "SHEETS", "PIECES", "PRINTED PARTS", "CLEARANCES (design fit, not kerf)",
+  "SETTINGS", "CHECKS", "OVERSIZED PIECES", "RENAMED FILES", "LIMITS",
+]);
+export const CSV_HEADER = "file,kind,labels,material,thickness_mm,width_mm,height_mm,quantity";
+
+const SVG_LEGEND = "Colours: engrave = filled black #000000, score = blue #0000FF, cut = red #FF0000 (inner cuts come before outer cuts).";
+const DXF_LEGEND = "DXF layers: CUT (colour 1), SCORE (colour 5), ENGRAVE (colour 7) — set ENGRAVE to fill; R12 has no hatch.";
+const LIMITS_LINE = "Layout packs bounding boxes only: no nesting into holes, and grain direction is ignored.";
+
+// C0 controls, DEL and C1 controls out of an author string, so a label can never ring a
+// bell, move a cursor or smuggle a line break into a table row — and the Unicode line
+// and paragraph separators (U+2028/U+2029, a line break in many editors) and the bidi
+// embeddings, overrides and isolates (U+202A–U+202E, U+2066–U+2069), which reorder the
+// text around them, for the same reason.
+export const cleanLabel = (s) => String(s).replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g, "");
+
+// One RFC 4180 cell. A cell starting with = + - or @ is a formula to Excel, Numbers and
+// Sheets, so it gets a leading ' first — before quoting, so no quote can be closed
+// around it.
+export function csvCell(v) {
+  let s = v == null ? "" : String(v);
+  if (/^[=+\-@]/.test(s)) s = `'${s}`;
+  return /[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+
+const clip = (s, n = 200) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+
+// A parameter value the way one README line can hold it: numbers and booleans as
+// written, strings JSON-quoted (so "" and " " stay visible), bytes by size, anything
+// else as clipped JSON.
+function settingValue(v) {
+  if (v === null || v === undefined || typeof v === "number" || typeof v === "boolean") return String(v);
+  if (typeof v === "string") return JSON.stringify(clip(cleanLabel(v)));
+  if (v instanceof ArrayBuffer || ArrayBuffer.isView(v)) return `<${v.byteLength} bytes>`;
+  try { return clip(JSON.stringify(v) ?? String(v)); } catch { return "<unprintable>"; }
+}
+
+const table = (header, rows) => (rows.length ? [header.join(" | "), ...rows.map((r) => r.join(" | "))] : []);
+const mm2 = ([w, h]) => `${w.toFixed(2)} × ${h.toFixed(2)} mm`;
+const labelsOf = (labels) => labels.map(cleanLabel).join(", ");
+
+export function renderReadme(m) {
+  const k = m.kerf;
+  const kerfed = k > 0;
+  // A cutting service gets each piece's score and engrave lines in a separate
+  // -marks.dxf, which neither table lists — so the files are named here, or a service
+  // order built from the cut files alone silently leaves the marks off.
+  const marksFiles = m.pieces.map((pc) => pc.marksFile).filter(Boolean);
+  const body = {
+    "BEFORE YOU CUT": [
+      ...m.stockNotes.map((g) =>
+        `This kit assumes ${g.thickness.toFixed(2)} mm ${cleanLabel(g.material)} — if yours differs, change "${cleanLabel(g.control ?? "the sheet thickness setting")}" and re-download.`),
+      kerfed
+        ? `Kerf: ${k.toFixed(2)} mm applied to the cut lines only. Set kerf in ONE place — these download options, or your laser software / cutting service — never both.`
+        : "Kerf: none applied — your laser software or cutting service must compensate.",
+      ...(kerfed ? [] : ["To have the files adjusted instead, download again with a kerf set, and turn compensation off in your laser software or service."]),
+      "Scale check — measure one cut piece against its line:",
+      ...m.scale.map((s) => `${cleanLabel(s.label)}: nominal ${s.nominal[0].toFixed(2)} × ${s.nominal[1].toFixed(2)} mm; this file draws ${
+        kerfed ? `${s.drawn[0].toFixed(2)} × ${s.drawn[1].toFixed(2)} with ${k.toFixed(2)} mm kerf` : "the same (no kerf applied)"}`),
+      m.cutFormat === "dxf" ? DXF_LEGEND : SVG_LEGEND,
+      ...(marksFiles.length ? [`Score and engrave marks are in their own files, not in the cut files — send them with the cut files if you want the marks made: ${marksFiles.join(", ")}.`] : []),
+      // A service kit whose every piece is oversized writes no sheets/ at all.
+      ...(m.destination === "service" && m.sheets.length ? ["The sheets in sheets/ are for reference only — a cutting service lays out the pieces itself."] : []),
+      "Test-cut one joint first.",
+    ],
+    SHEETS: table(["file", "material", "thickness", "size", "pieces", "used"], m.sheets.map((s) => [
+      s.file, cleanLabel(s.material), `${s.thickness.toFixed(2)} mm`, `${fmtMm(s.size[0])} × ${fmtMm(s.size[1])} mm`,
+      String(s.pieces), `${Math.round(s.used)}%`])),
+    PIECES: table(["file", "labels", "material", "thickness", "size", "quantity"], m.pieces.map((pc) => [
+      pc.file, labelsOf(pc.labels), cleanLabel(pc.material), `${pc.thickness.toFixed(2)} mm`, mm2(pc.size), String(pc.quantity)])),
+    "PRINTED PARTS": table(["file", "labels", "quantity"], m.printed.map((pp) => [pp.file, labelsOf(pp.labels), String(pp.quantity)])),
+    "CLEARANCES (design fit, not kerf)": m.clearances.map((c) =>
+      `${cleanLabel(c.label)}: ${settingValue(c.value)}${c.unit ? ` ${cleanLabel(c.unit)}` : ""}`),
+    SETTINGS: m.settings.map((s) => `${cleanLabel(s.key)} = ${settingValue(s.value)}`),
+    CHECKS: m.checks.length ? m.checks.map(cleanLabel) : ["none"],
+    "OVERSIZED PIECES": m.destination === "service" ? m.oversized.map(cleanLabel) : [],
+    "RENAMED FILES": m.renamed.map(cleanLabel),
+    LIMITS: [LIMITS_LINE],
+  };
+  const out = [`${cleanLabel(m.title)} — cut & print kit`, ""];
+  for (const heading of README_HEADINGS) {
+    if (body[heading].length) out.push(heading, ...body[heading], "");
+  }
+  return out.join("\n");
+}
+
+export function renderPartsCsv(rows) {
+  const line = (cells) => `${cells.map(csvCell).join(",")}\r\n`;
+  return `${CSV_HEADER}\r\n${rows.map((r) => line([
+    r.file, r.kind, r.labels.map(cleanLabel).join("; "), cleanLabel(r.material ?? ""),
+    r.thickness == null ? "" : r.thickness.toFixed(2), r.width.toFixed(2), r.height.toFixed(2), String(r.quantity),
+  ])).join("")}`;
+}

package/src/framework/export/svg.js

@@ -0,0 +1,97 @@
+// The kit's SVG writer: a SheetDoc (placed Drawings on one sheet) → one SVG string,
+// built by hand — paper.js cannot export SVG in a worker (there is no DOM to serialize
+// through), and this module stays a paper-free leaf (arc-math.js only).
+//
+// Written for laser software, which reads styling far more literally than a browser:
+//   - Size is physical: width/height in mm, viewBox in mm, so 1 user unit = 1 mm.
+//   - y is flipped IN THE COORDINATES (svgY = H − y): the Drawing is y-up, SVG is y-down,
+//     and a transform on the root is exactly the kind of inherited state a laser importer
+//     may drop. The flip reverses every arc's sense, hence the sweep flag below.
+//   - Every <path> carries its whole style. Nothing on the root or a group: inherited
+//     style is where importers disagree. Cut and score paths carry fill="none" — an
+//     unfilled SVG path defaults to BLACK FILL, which Glowforge reads as an engrave.
+//   - Colours are LightBurn's convention (SVG_COLORS); groups are written in cut order.
+//   - The only text is the escaped <title>. Escaping is hygiene, not the security
+//     boundary: a hostile part shares the worker with this writer and can post its own
+//     bytes — the host's download allowlist is the boundary (design spec E.1).
+import { arcCenterAndSweep } from "../geometry/arc-math.js";
+import { placer } from "./placement.js";
+
+export const SVG_COLORS = Object.freeze({ engrave: "#000000", score: "#0000FF", "cut-inner": "#FF0000", "cut-outer": "#FF0000" });
+export const SVG_STROKE_MM = 0.025;   // a hairline: laser software cuts it as a vector
+// The group order is the cut order — the same list as drawing.js's LAYER_ORDER, which
+// this leaf cannot import (drawing.js reaches paper); test/kit-svg.test.js pins them equal.
+const ORDER = Object.keys(SVG_COLORS);
+
+const num = (x) => { const v = Number(x.toFixed(4)); return String(v === 0 ? 0 : v); };   // -0 → "0"
+const escapeXml = (s) => String(s)
+  .replace(/[\u0000-\u001f\u007f]/g, "")
+  .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+  .replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+
+// Every IR arc is written as ceil(|dA| / 90°) equal pieces about the IR's own centre.
+// An `A` command carries no centre: a reader rebuilds it from the radius and the two
+// ends (SVG 1.1 F.6.5), at sqrt(r² − (chord/2)²) from the chord — and at 180° that
+// root is of a number near zero, so the 4-decimal rounding of r and both ends moves the
+// centre by ~sqrt(2·r·1e-4): a quarter of a millimetre-scale error on an ordinary hole,
+// and exactly what the refit makes (a faceted circle comes back as two 180° arcs). At
+// 90° or less the rebuild is well conditioned and lands within ~1e-4 mm. The pieces'
+// inner ends come from the centre and angle, never from a rounded neighbour; the last
+// one is the IR's own `to`.
+const QUARTER = Math.PI / 2;
+function arcCommands(from, s, P) {
+  const g = arcCenterAndSweep(from, s.via, s.to);   // drawing frame: the turn keeps dA's sign
+  if (!g) return ` L${P(s.to)}`;                     // collinear "arc": a straight line
+  const n = Math.max(1, Math.ceil(Math.abs(g.dA) / QUARTER - 1e-9));
+  const a0 = Math.atan2(from[1] - g.center[1], from[0] - g.center[0]);
+  const step = g.dA / n;
+  let d = "";
+  for (let i = 1; i <= n; i++) {
+    const t = a0 + step * i;
+    const to = i === n ? s.to : [g.center[0] + g.r * Math.cos(t), g.center[1] + g.r * Math.sin(t)];
+    d += ` A${num(g.r)} ${num(g.r)} 0 ${Math.abs(step) > Math.PI ? 1 : 0} ${step > 0 ? 0 : 1} ${P(to)}`;
+  }
+  return d;
+}
+
+function pathData(path, place, H) {
+  const P = (p) => { const [x, y] = place(p); return `${num(x)} ${num(H - y)}`; };
+  let d = `M${P(path.start)}`;
+  let from = path.start;
+  for (const s of path.segments) {
+    if (s.c1) d += ` C${P(s.c1)} ${P(s.c2)} ${P(s.to)}`;
+    else if (s.via) d += arcCommands(from, s, P);
+    else d += ` L${P(s.to)}`;
+    from = s.to;
+  }
+  return path.closed ? `${d} Z` : d;
+}
+
+export function renderSvg(doc) {
+  const [W, H] = doc.size;
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="${num(W)}mm" height="${num(H)}mm" viewBox="0 0 ${num(W)} ${num(H)}">`,
+    `<title>${escapeXml(doc.title)}</title>`,
+  ];
+  for (const id of ORDER) {
+    const paths = [];
+    for (const placement of doc.placements) {
+      const layer = placement.drawing.layers.find((l) => l.id === id);
+      if (!layer || layer.paths.length === 0) continue;
+      const place = placer(placement);
+      if (id === "engrave") {
+        // one filled path per piece: all its engrave rings, even-odd, so a glyph's
+        // counter stays open whatever the rings' winding
+        const d = layer.paths.map((p) => pathData(p, place, H)).join(" ");
+        paths.push(`<path d="${d}" fill="${SVG_COLORS.engrave}" fill-rule="evenodd" stroke="none"/>`);
+      } else {
+        for (const p of layer.paths)
+          paths.push(`<path d="${pathData(p, place, H)}" fill="none" stroke="${SVG_COLORS[id]}" stroke-width="${SVG_STROKE_MM}"/>`);
+      }
+    }
+    if (paths.length) lines.push(`<g id="${id}">`, ...paths, "</g>");
+  }
+  lines.push("</svg>");
+  return `${lines.join("\n")}\n`;
+}

package/src/framework/export-controller.js

@@ -39,13 +39,18 @@ export function createExportController({ send, currentView, title, defaultBacken
   // other's Promise.
   let nextWarmId = 1;
 
-  function exportParts({ parts, format, quality = "print", onProgress } = {}) {
+  // `options` are the cut & print kit's download options (format "bundle"). They ride
+  // the message for any format when given — the worker's other export branches never
+  // read them — and are left off entirely when not, so every other export's message is
+  // exactly what it always was.
+  function exportParts({ parts, format, quality = "print", onProgress, options } = {}) {
     const jobId = `export-${controller}-${nextId++}`;
     const type = `export-${format}`;
     const backend = backendForFormat(format, defaultBackend);
     return new Promise((resolve, reject) => {
       pending.set(jobId, { resolve, reject, onProgress });
-      send({ type, jobId, parts, view: currentView(), params: currentParams(), name: title(), quality }, backend);
+      send({ type, jobId, parts, view: currentView(), params: currentParams(), name: title(), quality,
+        ...(options !== undefined ? { options } : {}) }, backend);
     });
   }
 

package/src/framework/export-rows.js

@@ -0,0 +1,34 @@
+// The two lists an embedder's export UI is drawn from — the exportable sub-parts and
+// the formats — behind the mount handle's listExportableParts()/listExportFormats().
+//
+// Main-thread only: mount.js imports it. Deliberately NOT part of export-select.js,
+// which jobs.js imports at worker boot — export/formats.js must stay out of the
+// worker's eager closure (test/worker-layering.test.js).
+import { exportablePartNames, partLabel } from "./export-select.js";
+import { resolveDerived } from "./derive.js";
+import { sheetMeta } from "./sheet/constants.js";
+import { EXPORT_FORMATS } from "./export/formats.js";
+
+// A row for every exportable, enabled sub-part, in definition order. A sheet part's row
+// adds `sheet: { process, material, thickness, group }`, evaluated here at the live
+// params the way enabled() already is, so a host can tag it ("Sheet · …") and name its
+// stock group before asking for a kit. The key is OMITTED, never null, when it cannot
+// be evaluated — not a sheet, a material or thickness that throws, or a derive() that
+// throws (nothing about any part's stock is trustworthy then). The kit recomputes its
+// groups in the worker regardless, so a missing tag costs a label, never a wrong file.
+export function exportableRows(part, params) {
+  const p = { ...part.defaults, ...params };
+  let d = null;
+  let derived = true;
+  try { d = resolveDerived(part, p); } catch { derived = false; }
+  return exportablePartNames(part, params).map((name) => {
+    const row = { name, label: partLabel(part, name) };
+    const s = derived ? sheetMeta(part.parts[name], p, d) : null;
+    if (s) row.sheet = { process: s.process, material: s.material, thickness: s.thickness, group: s.group };
+    return row;
+  });
+}
+
+// What exportParts can write in this version, as fresh copies — a host that annotates
+// or sorts its list can never edit the table every later call reads.
+export const exportFormatList = () => EXPORT_FORMATS.map((f) => ({ ...f }));

package/src/framework/jobs.js

@@ -31,6 +31,12 @@ const loadInspect = () => Promise.all([
   import("./oracle/verify.js"),
 ]);
 
+// The cut & print kit loads the same way, on the first export-bundle job: its writers,
+// layout and README (export/*) and the process exporters behind them are dead weight to
+// a session that never downloads a kit. test/worker-layering.test.js keeps every one of
+// them out of worker boot, and test/kit-layering.test.js keeps the kit off ./oracle/*.
+const loadBundle = () => import("./export/bundle.js");
+
 // HOST JOBS — the extension seam. A host registers its own job types with
 // `runWorker(part, { jobs: { <type>: handler } })`, threaded here as `opts.jobs`, and
 // a message whose type matches no built-in below is handed to that handler with the
@@ -47,6 +53,8 @@ const loadInspect = () => Promise.all([
 //   { type:"generate", subparts, view, params } → { type:"meshes", meshes, ms }
 //   { type:"export-stl", view, params }         → { type:"download-parts", ext, mime, parts }
 //   { type:"export-step", view, params }        → { type:"download", data, filename, mime }
+//   { type:"export-bundle", view, params, parts, options }
+//                                               → { type:"download", data, filename, mime }  (the cut & print kit, a ZIP)
 // A generate also accepts `opts.isStale` — a caller-supplied predicate checked at each
 // sub-part boundary — and answers { type:"superseded" } instead of `meshes` when it
 // stops early (a build that ended without meshes, not an error; see KERNEL-CONTRACT.md).
@@ -455,6 +463,14 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       onProgress("writing 3MF file");
       const data = meshTo3MF(meshes);
       post({ type: "download", data, filename: `${fileBase}.3mf`, mime: "model/3mf", jobId: msg.jobId }, [bufferOf(data)]);
+    } else if (msg.type === "export-bundle") {
+      // The cut & print kit: sheet parts drawn flat from their 2-D declaration and laid
+      // out on the user's stock, printed parts as STL/3MF, a README — one ZIP. Every
+      // download-option problem throws a "cut kit options:" error, posted verbatim by the
+      // catch below like any other failed job.
+      const { buildBundle } = await loadBundle();
+      const { data, filename } = await buildBundle({ kernel, part, msg, p, d, posed, label, exportName, names: selected(), onProgress, fileBase });
+      post({ type: "download", data, filename, mime: "application/zip", jobId: msg.jobId }, [bufferOf(data)]);
     } else if (msg.type === "warm-kernel") {
       // Deliberately empty. worker.js awaits kernelFor() before calling handle(),
       // so REACHING this branch is the whole result: the backend this job was

package/src/framework/lint/rules-materials.js

@@ -1,12 +1,13 @@
 // src/framework/lint/rules-materials.js
 // Appearance findings. All WARNINGS by design: a misspelled material must never
 // block geometry, and the viewer already falls back (resolve.js). Pure — imports
-// only the three-free materials data (test/lint-purity.test.js).
+// only three-free materials and sheet data (test/lint-purity.test.js).
 import { warn } from "./finding.js";
 import { PRESETS } from "../materials/presets.js";
 import { ENVIRONMENTS } from "../materials/environments.js";
 import { resolveMaterial, resolveEnvironmentId, OVERRIDE_RANGES } from "../materials/resolve.js";
 import { suggest } from "../geometry/op-options.js";
+import { sheetStockLook } from "../materials/sheet-look.js";
 
 const listedPresets = () => Object.keys(PRESETS);
 const subParts = (part) => Object.entries(part?.parts ?? {}).filter(([, sp]) => sp && typeof sp === "object");
@@ -18,9 +19,15 @@ export const MATERIAL_RULES = [
     id: "unknown-material",
     run: ({ part }) => issuesOf(part, "unknown-material").map(({ name, value }) => {
       const near = typeof value === "string" ? suggest(value, listedPresets()) : null;
+      // A laser sheet falls back to its stock's look, not to PLA (materials/sheet-look.js) —
+      // read from a string label only: a label written as a function takes the default look.
+      const sp = part.parts[name];
+      const stock = sheetStockLook(sp);
+      const why = typeof sp.sheet?.material === "string" ? ", from its stock label" : ": its stock label is a function";
+      const fallback = stock ? `in realistic mode \`${stock}\`${why}` : "a PLA print in realistic mode";
       return warn("unknown-material",
         `sub-part "${name}" names material ${JSON.stringify(value)}, which is not in the library`,
-        `${near ? `Did you mean "${near}"? ` : ""}The viewer draws it as if it named no material instead (a PLA print in realistic mode). Known materials: ${listedPresets().join(", ")}.`,
+        `${near ? `Did you mean "${near}"? ` : ""}The viewer draws it as if it named no material instead (${fallback}). Known materials: ${listedPresets().join(", ")}.`,
         `parts.${name}.display.material`);
     }),
   },

package/src/framework/materials/assets/SOURCES.md

@@ -66,6 +66,9 @@ the sliced primary and gain-map buffers now start with SOI (`FF D8`) and end wit
 | `pattern-walnut-color.jpg` | Poly Haven "Dark Wood" (colour; API key `Diffuse`) | https://polyhaven.com/a/dark_wood — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/dark_wood/dark_wood_diff_1k.jpg | 2026-09-24 | 1K JPG, sRGB colour -> `node scripts/bake-environments.mjs --texture dark_wood_diff_1k.jpg pattern-walnut-color.jpg` (q82). Scanned tile 2000 mm (`api.polyhaven.com/info/dark_wood` dimensions). |
 | `pattern-walnut-normal.jpg` | Poly Haven "Dark Wood" (OpenGL normal map; API key `nor_gl`) | https://polyhaven.com/a/dark_wood — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/dark_wood/dark_wood_nor_gl_1k.jpg | 2026-09-24 | 1K JPG, OpenGL (+Y up) tangent normals, kept as data -> `node scripts/bake-environments.mjs --texture dark_wood_nor_gl_1k.jpg pattern-walnut-normal.jpg --data --quality 95` (4:4:4 chroma, no grayscale/tint; q95 because the map is nearly flat and the viewer amplifies it, so q90's 8x8 blocks showed). |
 | `pattern-walnut-rough.jpg` | Poly Haven "Dark Wood" (roughness; API key `Rough`) | https://polyhaven.com/a/dark_wood — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/dark_wood/dark_wood_rough_1k.jpg | 2026-09-24 | 1K JPG, grayscale data -> `node scripts/bake-environments.mjs --texture dark_wood_rough_1k.jpg pattern-walnut-rough.jpg --gray` (source is neutral grey; channel means unchanged). |
+| `pattern-plywood-color.jpg` | Poly Haven `plywood` (colour; API key `Diffuse`) | https://polyhaven.com/a/plywood — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/plywood/plywood_diff_1k.jpg | 2026-09-30 | 1K JPG, sRGB colour -> `node scripts/bake-environments.mjs --texture plywood_diff_1k.jpg pattern-plywood-color.jpg --modulate 1.85,0.9 --flatten 0.55 --quality 85` (lightened 1.85x and saturation 0.9 from the scan's mid brown to a pale birch; grain contrast 0.55, since lightening doubles it). One continuous veneer, fine even grain running across the image (`grain: "u"`). Chosen 2026-09-30 from five approved CC0 candidates: ambientCG Wood090A, Wood090B, Wood091A and Wood091B (https://ambientcg.com/a/<id>) are edge-glued strip panels with visible parallel joints, not a veneer face; Wood087/088/089 (checked earlier the same day) show plywood edges. |
+| `pattern-plywood-normal.jpg` | Poly Haven `plywood` (OpenGL normal map; API key `nor_gl`) | https://polyhaven.com/a/plywood — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/plywood/plywood_nor_gl_1k.jpg | 2026-09-30 | 1K JPG, OpenGL (+Y up) tangent normals, kept as data -> `node scripts/bake-environments.mjs --texture plywood_nor_gl_1k.jpg pattern-plywood-normal.jpg --data --quality 95` (4:4:4 chroma, no grayscale/tint). The map leans slightly (mean red 118/255, a ~4° tilt along the grain) as the source does; kept as authored. |
+| `pattern-plywood-rough.jpg` | Poly Haven `plywood` (roughness; API key `Rough`) | https://polyhaven.com/a/plywood — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/plywood/plywood_rough_1k.jpg | 2026-09-30 | 1K JPG, grayscale data -> `node scripts/bake-environments.mjs --texture plywood_rough_1k.jpg pattern-plywood-rough.jpg --gray` (mean 191/255 = 0.749, the preset's `roughnessMean`). |
 | `ground-maple-color.jpg` | Poly Haven "Oak Veneer 01" (colour; API key `Diffuse`) | https://polyhaven.com/a/oak_veneer_01 — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/oak_veneer_01/oak_veneer_01_diff_1k.jpg | 2026-09-24 | Workshop floor, "unfinished maple": `node scripts/bake-environments.mjs --texture oak_veneer_01_diff_1k.jpg ground-maple-color.jpg --modulate 1.5,0.7 --quality 85` (lightened 1.5x, saturation 0.7). |
 | `ground-maple-normal.jpg` | Poly Haven "Oak Veneer 01" (OpenGL normal map; API key `nor_gl`) | https://polyhaven.com/a/oak_veneer_01 — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/oak_veneer_01/oak_veneer_01_nor_gl_1k.jpg | 2026-09-24 | Workshop floor relief: `node scripts/bake-environments.mjs --texture oak_veneer_01_nor_gl_1k.jpg ground-maple-normal.jpg --data --quality 92`. A separate file from `pattern-oak-normal.jpg` so the floor and the oak material never share (and dispose) one texture. |
 | `ground-pei.jpg` | None — procedural | n/a | n/a | Gold-brown fine-grain speckle, no external source. First attempt tinted ambientCG "Plastic 010"'s colour map (near-uniform, stdev < 1/channel — visibly flat, no grain, when actually viewed) gold-brown; that colour map carries no usable grain at all (its roughness map does, which is why `ground-pei-rough.jpg` below is still Plastic010's roughness). Checked ambientCG alternatives (Metal049A — also flat; Granite006A — real speckle but reads as rock, not powder-coat) and found nothing closer. Generated in-baker instead, same procedural precedent as `pattern-carbon.jpg`: per-pixel triangular-distributed noise around a `168,134,82` bronze-gold base (asymmetric per channel so flecks warm rather than grey), then a 0.5px blur to turn single-pixel noise into soft grains -> `node scripts/bake-environments.mjs --speckle ground-pei.jpg --tint 168,134,82`. (Re-baked 2026-09-24 from `196,154,82`: darker and less saturated, closer to a Bambu textured-PEI plate's muted bronze-gold.) |
@@ -76,9 +79,11 @@ the sliced primary and gain-map buffers now start with SOI (`FF D8`) and end wit
 | `pattern-carbon.jpg` | None — procedural | n/a | n/a | ambientCG has no CC0 carbon-fiber weave (searched "carbon"; only unrelated fabric hits). Generated in-baker: a 256x256 2x2 twill tile (32 threads/tile, alternating dark/light grey diagonal bands) -> `node scripts/bake-environments.mjs --carbon pattern-carbon.jpg`. No external source/licence to record. |
 
 ambientCG publishes every asset under CC0 (https://ambientcg.com/, "CC0 Public Domain
-license", checked 2026-09-24). The wood sets (`pattern-oak-*`, `pattern-walnut-*`,
-`ground-maple-*`) are Poly Haven textures, CC0 like its HDRIs above
-(https://polyhaven.com/license, checked 2026-09-24); the exact 1K JPG URLs came
+license", checked 2026-09-24; https://ambientcg.com/license, "Creative Commons CC0 1.0
+Universal License", checked again 2026-09-30 for the plywood candidates). The wood sets
+(`pattern-oak-*`, `pattern-walnut-*`, `pattern-plywood-*`, `ground-maple-*`) are Poly Haven
+textures, CC0 like its HDRIs above (https://polyhaven.com/license, checked 2026-09-24, and
+again 2026-09-30 for `plywood`); the exact 1K JPG URLs came
 from `https://api.polyhaven.com/files/<slug>` (keys `Diffuse`, `nor_gl`, `Rough`).
 The presets tile them smaller than the scanned size — see the comment on `oak` in
 `presets.js` and on `workshop` in `environments.js`.
@@ -86,5 +91,6 @@ The presets tile them smaller than the scanned size — see the comment on `oak`
 ## Budgets
 
 Environments stay under 1.5 MB (largest: `env-workshop.jpg` at ~398 KB); ground/pattern
-textures stay under 400 KB (largest: `pattern-oak-rough.jpg` at ~218 KB). All committed
+textures stay under 400 KB (largest: `ground-concrete-normal.jpg` at ~380 KB; the largest
+pattern map is `pattern-plywood-normal.jpg` at ~337 KB). All committed
 outputs are well inside both ceilings — see `test/framework/materials-assets.test.js`.

package/src/framework/materials/assets.js

@@ -25,6 +25,9 @@ const URLS = {
   "pattern-walnut-color.jpg": new URL("./assets/pattern-walnut-color.jpg", import.meta.url).href,
   "pattern-walnut-normal.jpg": new URL("./assets/pattern-walnut-normal.jpg", import.meta.url).href,
   "pattern-walnut-rough.jpg": new URL("./assets/pattern-walnut-rough.jpg", import.meta.url).href,
+  "pattern-plywood-color.jpg": new URL("./assets/pattern-plywood-color.jpg", import.meta.url).href,
+  "pattern-plywood-normal.jpg": new URL("./assets/pattern-plywood-normal.jpg", import.meta.url).href,
+  "pattern-plywood-rough.jpg": new URL("./assets/pattern-plywood-rough.jpg", import.meta.url).href,
   "pattern-carbon.jpg": new URL("./assets/pattern-carbon.jpg", import.meta.url).href,
 };
 

package/src/framework/materials/patterns.js

@@ -5,7 +5,10 @@
 // they move with the sub-part under animation and never slide when the camera
 // moves. Layer lines additionally map object space through `pfPrintFrame`
 // (print-frame.js: display→export), so they run the way the part will print.
+// A laser-cut wood sheet's burn (applyBurn) composes over the wood pass in the sheet's
+// canonical frame (sheet-look.js).
 import * as THREE from "three";
+import { BURN, srgbToLinear } from "./sheet-look.js";
 
 const VERT_DECL = "varying vec3 vPfObjPos;\nvarying vec3 vPfObjNormal;\nvarying vec3 vPfPrintUpView;\nuniform mat4 pfPrintFrame;\n";
 // Wood's triplanar normal map builds its normal in OBJECT space; the fragment
@@ -354,3 +357,103 @@ export function applyBrushFrame(material) {
   material.needsUpdate = true;
   return material;
 }
+
+// --- laser burns ------------------------------------------------------------------
+// A laser-cut sheet in a wood shows what the laser did to it (sheet-look.js decides which
+// sub-parts, and mount hands the viewer each one's canonical frame): cut walls charred,
+// engrave and score floors scorched, faces untouched. Composes over the wood pass the way
+// applyBrushFrame does, injecting at three points in three's meshphysical order:
+//   (a) colour + roughness, before <normal_fragment_begin>: after wood's body (injected
+//       after <roughnessmap_fragment>) and <metalnessmap_fragment>. A second replace of
+//       <roughnessmap_fragment> would land IN FRONT of wood's body, so it is not reused.
+//       pfBurnWall / pfBurnFloor are declared at main() scope, like pfLayer, for (b), (c).
+//   (b) the normal, before <emissivemap_fragment>: after wood's normal map and the
+//       clearcoat normals. Char flattens the wood's relief: the wood normal fades toward
+//       the geometric one (nonPerturbedNormal, set by <normal_fragment_begin>), keeping
+//       BURN.relief of it.
+//   (c) clearcoat, after <lights_physical_fragment>, which assigns material.clearcoat:
+//       walnut's lacquer comes off the char.
+// Every snippet sits between `// pf-burn {` and `// } pf-burn` lines: that is how the tests
+// prove a burning program is the plain wood program plus these and nothing else. The
+// vertex stage is untouched — the pass reads the varyings every pattern already has. With
+// pfSheetT = 0 (no frame delivered yet) it draws plain wood. No noise term: an unfiltered
+// striation would shimmer at part scale (the layer-lines lesson above).
+const glf = (x) => (Number.isInteger(x) ? x.toFixed(1) : String(x));
+const CHARCOAL = srgbToLinear(BURN.charcoal);
+const burnBlock = (glsl) => `// pf-burn {\n${glsl}\n// } pf-burn`;
+
+const BURN_FRAG_DECL = burnBlock(`uniform mat4 pfSheetFrame;
+uniform float pfSheetT;
+uniform float pfPlies;
+uniform vec3 pfFaceAvg;
+// 1 on a cross ply (an odd one), 0 on a face-grain ply: the square wave box-filtered over
+// the pixel (its integral, differenced across fwidth), so plies too thin to draw average
+// out instead of shimmering.
+float pfCrossPlyI(float x) { return floor(x * 0.5) + max(0.0, fract(x * 0.5) * 2.0 - 1.0); }
+float pfCrossPly(float x) {
+  float w = max(fwidth(x), 1e-4);
+  return (pfCrossPlyI(x + 0.5 * w) - pfCrossPlyI(x - 0.5 * w)) / w;
+}`);
+
+const BURN_FRAG_BODY = burnBlock(`float pfBurnWall = 0.0;
+float pfBurnFloor = 0.0;
+if (pfSheetT > 0.0) {
+  vec3 pfC = (pfSheetFrame * vec4(vPfObjPos, 1.0)).xyz;
+  vec3 pfCn = normalize(mat3(pfSheetFrame) * vPfObjNormal);
+  pfBurnWall = 1.0 - smoothstep(${glf(BURN.wallNz[0])}, ${glf(BURN.wallNz[1])}, abs(pfCn.z));
+  pfBurnFloor = step(0.5, pfCn.z) * step(pfC.z, pfSheetT - ${glf(BURN.floorDepth)});
+  float pfK = mix(${glf(BURN.kThin)}, ${glf(BURN.kThick)}, clamp((pfSheetT - ${glf(BURN.tThin)}) / ${glf(BURN.tThick - BURN.tThin)}, 0.0, 1.0));
+  float pfZ = clamp(pfC.z / pfSheetT, 0.0, 1.0);
+  vec3 pfFace = diffuse * pfFaceAvg;
+  // Per channel, not the vector scaled by one luminance ratio (sheet-look.js's burnAlbedo,
+  // this shader's twin, explains why): a channel where charOfDark·face is already below raw
+  // charcoal chars toward ITS OWN darker value, so no channel can come out lighter than it
+  // went in.
+  vec3 pfChar = min(vec3(${CHARCOAL.map((c) => c.toFixed(6)).join(", ")}), ${glf(BURN.charOfDark)} * pfFace);
+  vec3 pfEdge = mix(pfFace, pfChar, min(1.0, pfK + ${glf(BURN.exit)} * (1.0 - pfZ)));
+  if (pfPlies > 0.0) pfEdge *= mix(1.0, ${glf(BURN.crossPly)}, pfCrossPly(pfZ * pfPlies));
+  vec3 pfMark = mix(pfFace, pfChar, pfK - ${glf(BURN.engraveLess)});
+  // The grain survives the char (sheet-look.js's burnTexel is the twin): pfEdge and pfMark
+  // are what the face AVERAGE chars to, and each texel keeps its ratio to that average,
+  // blended in by BURN.grain. At 1, a pure multiply, the average chars exactly as above and
+  // no texel comes out lighter than it went in.
+  vec3 pfGrain = mix(vec3(1.0), diffuseColor.rgb / max(pfFace, vec3(1e-4)), ${glf(BURN.grain)});
+  pfEdge *= pfGrain;
+  pfMark *= pfGrain;
+  diffuseColor.rgb = mix(diffuseColor.rgb, pfEdge, pfBurnWall);
+  diffuseColor.rgb = mix(diffuseColor.rgb, pfMark, pfBurnFloor);
+  roughnessFactor = mix(roughnessFactor, ${glf(BURN.roughness)}, max(pfBurnWall, pfBurnFloor));
+}`);
+
+const BURN_FRAG_NORMAL = burnBlock(`normal = normalize(mix(normal, nonPerturbedNormal, max(pfBurnWall, pfBurnFloor) * ${glf(1 - BURN.relief)}));`);
+
+const BURN_FRAG_CLEARCOAT = burnBlock(`#ifdef USE_CLEARCOAT
+material.clearcoat *= 1.0 - max(pfBurnWall, pfBurnFloor);
+#endif`);
+
+// `faceAvg` is the preset's own colour (0xRRGGBB) — its texture's average, never the tint:
+// the tint arrives as `diffuse`, so the shader's face colour is diffuse · pfFaceAvg.
+export function applyBurn(material, { faceAvg }) {
+  const uniforms = material.userData.patternUniforms;
+  if (!uniforms?.pfGrainSwap) return material; // wood only: the burn draws over the wood pass
+  Object.assign(uniforms, {
+    pfSheetFrame: { value: new THREE.Matrix4() },
+    pfSheetT: { value: 0 },
+    pfPlies: { value: 0 },
+    pfFaceAvg: { value: new THREE.Color(faceAvg) },
+  });
+  const prev = material.onBeforeCompile;
+  const prevKey = material.customProgramCacheKey;
+  material.onBeforeCompile = (shader, renderer) => {
+    prev?.call(material, shader, renderer); // applyPattern's hook copies `uniforms` — burn uniforms included
+    shader.fragmentShader = shader.fragmentShader
+      .replace("#include <common>", `#include <common>\n${BURN_FRAG_DECL}`)
+      .replace("#include <normal_fragment_begin>", `${BURN_FRAG_BODY}\n#include <normal_fragment_begin>`)
+      .replace("#include <emissivemap_fragment>", `${BURN_FRAG_NORMAL}\n#include <emissivemap_fragment>`)
+      .replace("#include <lights_physical_fragment>", `#include <lights_physical_fragment>\n${BURN_FRAG_CLEARCOAT}`);
+  };
+  const base = prevKey && prevKey !== THREE.Material.prototype.customProgramCacheKey ? prevKey.call(material) : "";
+  material.customProgramCacheKey = () => `${base}|pf-burn`;
+  material.needsUpdate = true;
+  return material;
+}