partforge 0.132.0 → 0.133.0

package/src/framework/sheet/pose.js

@@ -0,0 +1,114 @@
+// Sheet frames and poses — pure math, no kernel, no paper (lint and the oracle read it).
+//
+// A sheet part is authored in its CANONICAL frame: the profile in XY, the solid
+// extruded over z ∈ [0, t], the laser face at z = t. A SheetPose { face, up, at } says
+// where that piece sits in the assembly:
+//   face  the laser face's outward normal, as an axis word ("+X", "-Y", …)
+//   up    the drawing's +y, an axis word perpendicular to face
+//   at    where drawing [0, 0] lands (on the laser face); the material extends along −face
+// The drawing's +x maps to X = up × face, so R = [X | Y | F] (columns) is always a
+// proper rotation (det +1) and an engraving can never come out mirrored. A canonical
+// point [u, v, z] lands at  at + u·X + v·Y + (z − t)·F.
+import { AXIS_WORDS } from "./constants.js";
+
+// A sheet part with no pose: no transform at all — the canonical solid stays put.
+export const FLAT_POSE = null;
+
+const AXIS_VEC = {
+  "+X": [1, 0, 0], "-X": [-1, 0, 0],
+  "+Y": [0, 1, 0], "-Y": [0, -1, 0],
+  "+Z": [0, 0, 1], "-Z": [0, 0, -1],
+};
+const WORDS = AXIS_WORDS.join(", ");
+const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+const finiteN = (v, n) => Array.isArray(v) && v.length === n && v.every((c) => typeof c === "number" && Number.isFinite(c));
+// `+ 0` folds a -0 component to 0, so frames and steps serialize cleanly.
+const cross = (a, b) => [a[1] * b[2] - a[2] * b[1] + 0, a[2] * b[0] - a[0] * b[2] + 0, a[0] * b[1] - a[1] * b[0] + 0];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+
+// null when `pose` is a valid SheetPose, else the reason (callers add their prefix).
+export function validatePose(pose) {
+  if (!isPlainObject(pose)) return "pose must be a { face, up, at } object";
+  if (!AXIS_WORDS.includes(pose.face)) return `face must be one of ${WORDS}, got ${JSON.stringify(pose.face)}`;
+  if (!AXIS_WORDS.includes(pose.up)) return `up must be one of ${WORDS}, got ${JSON.stringify(pose.up)}`;
+  if (pose.up[1] === pose.face[1]) return `up (${pose.up}) must be perpendicular to face (${pose.face})`;
+  if (!finiteN(pose.at, 3)) return `at must be a finite [x, y, z], got ${JSON.stringify(pose.at)}`;
+  return null;
+}
+
+function checkPose(pose, prefix) {
+  const reason = validatePose(pose);
+  if (reason) throw new Error(`${prefix}: ${reason}`);
+}
+
+// The pose's world frame: X = up × face (drawing +x), Y = up (drawing +y), F = face.
+export function poseFrame(pose) {
+  checkPose(pose, "sheet pose");
+  const F = [...AXIS_VEC[pose.face]], Y = [...AXIS_VEC[pose.up]];
+  return { X: cross(Y, F), Y, F, at: [...pose.at] };
+}
+
+// Axis-angle of R = [X | Y | F], or null for the identity. R is a signed permutation
+// matrix, so the angle is 90°, 120° or 180°; the axis is scaled so its largest
+// component is ±1 (the backends normalize it), which keeps basis rotations exact.
+function axisAngle(X, Y, F) {
+  // R[i][j] = component i of column j
+  const R = [[X[0], Y[0], F[0]], [X[1], Y[1], F[1]], [X[2], Y[2], F[2]]];
+  const trace = R[0][0] + R[1][1] + R[2][2];
+  if (trace > 2.5) return null; // identity (trace 3)
+  const cos = Math.max(-1, Math.min(1, (trace - 1) / 2));
+  const deg = Math.round((Math.acos(cos) * 180) / Math.PI * 1e9) / 1e9;
+  let axis;
+  if (trace < -0.5) {
+    // 180°: R + I = 2·a·aᵀ — take the column with the largest diagonal entry
+    const i = [0, 1, 2].reduce((best, k) => (R[k][k] > R[best][best] ? k : best), 0);
+    axis = [0, 1, 2].map((r) => R[r][i] + (r === i ? 1 : 0));
+  } else {
+    axis = [R[2][1] - R[1][2], R[0][2] - R[2][0], R[1][0] - R[0][1]];
+  }
+  const m = Math.max(...axis.map(Math.abs));
+  return { deg, axis: axis.map((c) => c / m + 0) };
+}
+
+// The rigid steps that carry the canonical solid (z ∈ [0, t]) to the pose:
+// translate [0, 0, −t] (laser face to z = 0), rotate by R about the origin (omitted
+// when R = I), translate `at`. Exactly the step vocabulary the pose probe records
+// (pose-probe-core.js), so a posed sheet part stays probe-trusted.
+export function poseSteps(pose, t) {
+  const { X, Y, F, at } = poseFrame(pose);
+  const steps = [{ t: "translate", v: [0, 0, -t] }];
+  const rot = axisAngle(X, Y, F);
+  if (rot) steps.push({ t: "rotate", deg: rot.deg, center: [0, 0, 0], axis: rot.axis });
+  steps.push({ t: "translate", v: at });
+  return steps;
+}
+
+// The flat pose (FLAT_POSE, null) is the canonical frame itself — the same placement as
+// { face: "+Z", up: "+Y", at: [0, 0, t] } — which a pose function may return for some
+// params. The converters take it: worldToSheet needs nothing more, sheetToWorld needs
+// the sheet's thickness, since the laser face then sits at z = t.
+const flatFrame = (t) => ({ face: "+Z", up: "+Y", at: [0, 0, t] });
+
+// Drawing [u, v] (on the laser face, `depth` mm into the material) → world [x, y, z].
+// `thickness` is read only for the flat pose.
+export function sheetToWorld(pose, uv, depth = 0, thickness) {
+  if (pose === FLAT_POSE && !(typeof thickness === "number" && Number.isFinite(thickness) && thickness > 0)) {
+    throw new Error("sheetToWorld: a flat (null) pose needs the sheet's thickness — sheetToWorld(null, [u, v], depth, t)");
+  }
+  if (pose === FLAT_POSE) pose = flatFrame(thickness);
+  checkPose(pose, "sheetToWorld");
+  if (!finiteN(uv, 2)) throw new Error(`sheetToWorld: point must be a finite [u, v], got ${JSON.stringify(uv)}`);
+  if (typeof depth !== "number" || !Number.isFinite(depth)) throw new Error(`sheetToWorld: depth must be a finite number (mm), got ${JSON.stringify(depth)}`);
+  const { X, Y, F, at } = poseFrame(pose);
+  return [0, 1, 2].map((i) => at[i] + uv[0] * X[i] + uv[1] * Y[i] - depth * F[i] + 0);
+}
+
+// World [x, y, z] → drawing [u, v]; the component along the face normal is dropped.
+export function worldToSheet(pose, xyz) {
+  if (pose === FLAT_POSE) pose = flatFrame(0);
+  checkPose(pose, "worldToSheet");
+  if (!finiteN(xyz, 3)) throw new Error(`worldToSheet: point must be a finite [x, y, z], got ${JSON.stringify(xyz)}`);
+  const { X, Y, at } = poseFrame(pose);
+  const rel = [xyz[0] - at[0], xyz[1] - at[1], xyz[2] - at[2]];
+  return [dot(rel, X) + 0, dot(rel, Y) + 0];
+}

package/src/framework/sheet/resolve.js

@@ -0,0 +1,133 @@
+// Resolve a sheet sub-part's declaration at (p, d) into shapes, and build its preview.
+//
+// PROBE-SAFE: everything here calls kernel and Shape2D METHODS only — no toContours,
+// isEmpty, area, boundingBox or regions (the pose/parameter probes treat those as
+// queries, poison trust and hand back dummies; pose-probe-core.js), and never branches
+// on geometry. That is what keeps every sheet part's pose trusted, so a pose-only
+// slider drag re-poses instead of rebuilding.
+//
+// Paper-free (the oracle imports this module — test/oracle-no-paper.test.js): a score
+// line's groove is a plain butt-capped rectangle, never geometry/stroke-outline.js,
+// which reaches paper through contour-ops.js.
+import { EMPTY_MARK_RE, MARK_DEPTH, MARK_OVERCUT, SCORE_WIDTH, sheetGroup } from "./constants.js";
+import { poseSteps, validatePose } from "./pose.js";
+import { recoverArcs } from "../geometry/arc-fit.js";
+
+const fail = (sp, problem) => new Error(`sheet part${sp.label ? ` "${sp.label}"` : ""}: ${problem}`);
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+const isLine = (e) => Array.isArray(e) && e.length === 2
+  && e.every((pt) => Array.isArray(pt) && pt.length === 2 && isNum(pt[0]) && isNum(pt[1]));
+
+// Run `make`; a mark that turned out empty (an empty Shape2D extruded, an offset that
+// collapsed) comes back null instead of failing the build. Matched by MESSAGE, never
+// by asking the shape whether it is empty — that would be a probe query.
+function orEmpty(make) {
+  try {
+    return make();
+  } catch (e) {
+    if (EMPTY_MARK_RE.test(e?.message ?? "")) return null;
+    throw e;
+  }
+}
+
+// A score line as a SCORE_WIDTH-wide rectangle, butt-capped at both ends (CCW).
+function lineGroove(k, [a, b]) {
+  const len = Math.hypot(b[0] - a[0], b[1] - a[1]);
+  const nx = (-(b[1] - a[1]) / len) * (SCORE_WIDTH / 2), ny = ((b[0] - a[0]) / len) * (SCORE_WIDTH / 2);
+  return k.shape2d([[a[0] - nx, a[1] - ny], [b[0] - nx, b[1] - ny], [b[0] + nx, b[1] + ny], [a[0] + nx, a[1] + ny]]);
+}
+
+// A closed score shape: every boundary grooved, SCORE_WIDTH wide, centred on it. A
+// shape too small to keep an inside collapses under the inward offset; it is then
+// scored solid (the outward offset alone).
+function shapeGroove(shape) {
+  const outer = shape.offset(SCORE_WIDTH / 2);
+  return orEmpty(() => outer.cut(shape.offset(-SCORE_WIDTH / 2))) ?? outer;
+}
+
+// → ResolvedSheet: { process, material, thickness, group, label, pose, profile,
+//   score: { lines, shapes }, engrave, grooves, customBuild, trustedShape2d, recoverArcs }.
+//   Throws a `sheet part "<label>": …` error for a field that resolves to something
+//   unusable. `trustedShape2d` is the kernel's lift for machine-produced regions (no
+//   profile validation, arcs kept), or null where the kernel has none (a probe): the
+//   process checks rebuild the profile from its own rings with it, less the holes a width
+//   search can leave out (process/laser/descriptor.js). `recoverArcs` (geometry/arc-fit.js)
+//   reads a run of cubics that lies on one circle as that circle's arcs, the fit the cut
+//   files are drawn with; the checks run their width searches on those arcs. Both are
+//   handed over rather than imported, because a process descriptor imports nothing.
+export function resolveSheet(k, sp, p, d) {
+  const s = sp.sheet;
+  const thickness = typeof s.thickness === "function" ? s.thickness(p, d) : s.thickness;
+  if (!isNum(thickness) || thickness <= 0) throw fail(sp, `thickness must be a finite number > 0 (mm), got ${thickness}`);
+  const material = typeof s.material === "function" ? s.material(p, d) : s.material;
+  if (typeof material !== "string" || material.trim() === "") throw fail(sp, `material must be a non-empty string, got ${JSON.stringify(material)}`);
+
+  let pose = null;
+  if (s.pose !== null) {
+    pose = typeof s.pose === "function" ? s.pose(p, d) : s.pose;
+    if (pose !== null) {
+      const reason = validatePose(pose);
+      if (reason) throw fail(sp, reason);
+    }
+  }
+
+  const drawn = s.profile(k, p, d);
+  if (drawn === null || drawn === undefined) throw fail(sp, "profile(k, p, d) returned nothing — return a Shape2D or profile");
+  const profile = k.shape2d(drawn);
+
+  const lines = [], shapes = [];
+  if (s.score) {
+    const entries = s.score(k, p, d);
+    if (entries !== null && entries !== undefined) {
+      if (!Array.isArray(entries)) throw fail(sp, "score(k, p, d) must return an array of lines [[x, y], [x, y]] and shapes");
+      for (const entry of entries) {
+        if (entry === null || entry === undefined) continue;          // a mark switched off
+        if (!isLine(entry)) { shapes.push(k.shape2d(entry)); continue; } // a point list is a polygon
+        const [a, b] = entry;
+        // A zero-length line marks nothing. Dropped HERE, not just from the grooves, so
+        // the preview and the cut file (which draws score.lines) always agree.
+        if (Math.hypot(b[0] - a[0], b[1] - a[1]) > 1e-9) lines.push([[a[0], a[1]], [b[0], b[1]]]);
+      }
+    }
+  }
+  const engraved = s.engrave ? s.engrave(k, p, d) : null;
+  const engrave = engraved === null || engraved === undefined ? null : k.shape2d(engraved);
+
+  const grooves = [
+    ...lines.map((ln) => lineGroove(k, ln)),
+    ...shapes.map(shapeGroove),
+  ];
+
+  return {
+    process: s.process, material, thickness, group: sheetGroup(material, thickness),
+    label: sp.label ?? null, pose, profile, score: { lines, shapes }, engrave, grooves,
+    customBuild: sp.build !== s.generatedBuild,
+    trustedShape2d: typeof k.shape2d?.trusted === "function" ? k.shape2d.trusted : null,
+    recoverArcs,
+  };
+}
+
+// The default preview: the profile extruded to the thickness, the engrave pocketed and
+// each groove cut MARK_DEPTH deep. Each mark tool spans z = t − MARK_DEPTH to
+// t + MARK_OVERCUT, so its top face is never coplanar with the laser face; the removed
+// volume is still MARK_DEPTH × area(marks ∩ profile).
+export function sheetPreview(k, s) {
+  const t = s.thickness;
+  const body = s.profile.extrude({ h: t });
+  const tools = [s.engrave, ...s.grooves]
+    .filter(Boolean)
+    .map((mark) => orEmpty(() => mark.extrude({ h: MARK_DEPTH + MARK_OVERCUT }).translate([0, 0, t - MARK_DEPTH])))
+    .filter(Boolean);
+  return tools.length ? body.cutAll(tools) : body;
+}
+
+// Carry a canonical solid (z ∈ [0, t]) to its pose — translate and rotate only, so
+// display and export differ by nothing and the probe keeps trusting the pose. A null
+// pose is no transform.
+export function applyPose(solid, pose, t) {
+  if (pose === null) return solid;
+  return poseSteps(pose, t).reduce(
+    (s, st) => (st.t === "translate" ? s.translate(st.v) : s.rotate(st.deg, st.center, st.axis)),
+    solid,
+  );
+}

package/src/framework/verify-metrics.js

@@ -10,7 +10,11 @@
 // `verify.expect` metrics is part of the PartDefinition CONTRACT, which both the
 // verify runner (oracle/verify.js) and the linter (partforge/lint) must agree on.
 // Keeping it here lets the linter import the vocabulary without reaching
-// measure.js, which pulls in the geometry kernels. Must stay import-free.
+// measure.js, which pulls in the geometry kernels. Its one import is the process
+// registry, whose closure is import-free in turn (the process descriptors,
+// sheet/constants.js, lint/finding.js) — so the linter's stays kernel-free.
+import { SHEET_METRICS } from "./process/registry.js";
+
 export const SUBPART_METRICS = {
   holes: { kind: "gate", manifoldOnly: true, extract: (s) => s.holes,
     hint: "genus is wrong — an unintended tunnel exists or an intended bore is blocked; make cut tools pierce fully (overcut past the faces)" },
@@ -78,6 +82,9 @@ export const SUBPART_METRICS = {
     hint: "rebuild volume differs from the reference import by more than the allowed percentage — a feature is missing, doubled, or mis-scaled vs the reference" },
   refBboxDelta: { kind: "gate", extract: (s) => s.deviation?.bboxDelta ?? null,
     hint: "the rebuild's bounding-box corners drift from the reference import — check overall dimensions and that the rebuild is aligned to the reference's coordinates" },
+  // Sheet parts (sheetPart(), partforge/geometry): each process's own checks. verify
+  // volunteers them on every sheet sub-part; an author may declare them like any other.
+  ...SHEET_METRICS,
 };
 export const VIEW_METRICS = {
   bbox: { kind: "gate", extract: (r) => r.aggregate.bbox,

package/src/parts/laser-box.js

@@ -0,0 +1,108 @@
+// 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 } } },
+};

package/src/parts/material-swatches.js

@@ -6,13 +6,23 @@ import { PRESETS } from "../framework/materials/presets.js";
 const ids = Object.keys(PRESETS);
 const COLS = 6, PITCH = 40;
 
+// Common filament colours for the "PLA colours" and "PETG colours" views: how
+// each print finish reads across light, dark and saturated tints, since a preset
+// tuned on one colour can wash out another. The last is the no-material blue-grey.
+const FILAMENT_COLOURS = [
+  ["White", 0xf2f0eb], ["Cream (preset)", PRESETS["pla-print"].color], ["Light grey", 0xa3a6a8],
+  ["Charcoal", 0x4a4c50], ["Black", 0x1e1f21], ["No-material blue-grey", 0x9fb4cc],
+  ["Red", 0xc8102e], ["Orange", 0xe0592a], ["Yellow", 0xf2c500],
+  ["Green", 0x2e8b3d], ["Blue", 0x1f5fbf], ["Purple", 0x6b3fa0],
+];
+
 const withHole = (k) =>
   k.box({ size: [30, 30, 12] }).fillet({ r: 3 }).cut(k.cylinder({ r: 5, h: 20 }).translate([0, 0, -4]));
 
 export default {
   meta: { title: "Material swatches", units: "mm", environment: "studio" },
   defaults: {},
-  views: { all: { label: "All presets", default: true }, print: { label: "Layer lines" } },
+  views: { all: { label: "All presets", default: true }, colours: { label: "PLA colours" }, petg: { label: "PETG colours" }, print: { label: "Layer lines" } },
   parts: {
     ...Object.fromEntries(ids.map((id, i) => [id.replaceAll("-", "_"), {
       label: PRESETS[id].label,
@@ -27,6 +37,18 @@ export default {
       views: ["all"],
       build: (k) => withHole(k).translate([(ids.length % COLS) * PITCH, -Math.floor(ids.length / COLS) * PITCH, 0]),
     },
+    ...Object.fromEntries(FILAMENT_COLOURS.map(([label, color], i) => [`pla_${i}`, {
+      label: `PLA — ${label}`,
+      views: ["colours"],
+      build: (k) => withHole(k).translate([(i % COLS) * PITCH, -Math.floor(i / COLS) * PITCH, 0]),
+      display: { material: "pla-print", color },
+    }])),
+    ...Object.fromEntries(FILAMENT_COLOURS.map(([label, color], i) => [`petg_${i}`, {
+      label: `PETG — ${label}`,
+      views: ["petg"],
+      build: (k) => withHole(k).translate([(i % COLS) * PITCH, -Math.floor(i / COLS) * PITCH, 0]),
+      display: { material: "petg-print", color },
+    }])),
     upright_pla: {
       label: "PLA, displayed upright, printed flat",
       views: ["print"],

package/types/geometry.d.ts

@@ -8,15 +8,27 @@ import type {
   Contour,
   Corner2D,
   CornerSelector,
+  GeometryKernel,
   MirrorAxis2,
   Point2,
   Point3,
   PointsContour,
   Region2D,
+  Shape2D,
   Solid,
 } from "./kernel.js";
+import type {
+  AxisWord,
+  Derived,
+  PlaceContext,
+  ResolvedParams,
+  SheetPose,
+  SheetScoreEntry,
+  SubPartDefinition,
+} from "./part.js";
 
 export type { ArcContour, Contour, Corner2D, CornerSelector, MirrorAxis2, Point2, Point3, PointsContour, Region2D, Solid };
+export type { AxisWord, SheetPose };
 
 /**
  * Anything the 2-D editing ops below accept: a plain point list, a curve-native
@@ -282,3 +294,106 @@ export interface ProfileIssue {
  * geometric badness — only an unrecognized `input` shape throws.
  */
 export function validateProfile(input: ProfileInput): { ok: boolean; issues: ProfileIssue[] };
+
+// --- sheet parts (docs/AUTHORING-PARTS.md "Sheet parts") --------------------
+
+/**
+ * What `sheetPart` accepts. A field needing the kernel is `(k, p, d)`; a plain value
+ * is a literal or `(p, d)`. Unknown keys throw at load and name the fix (`kerf` is
+ * chosen at download, `outline`/`cut` are `profile`, `build` is supplied).
+ */
+export interface SheetPartSpec<P = ResolvedParams, D = Derived> {
+  /** Stock label ("birch plywood"); groups pieces in the kit. The LOOK is `display.material`. */
+  material: string | ((p: P, d: D) => string);
+  /** The MEASURED sheet thickness in mm: the extrusion depth and every joint's depth. */
+  thickness: number | ((p: P, d: D) => number);
+  /** The CUT layer: outline plus holes, seen from the laser face. */
+  profile: (k: GeometryKernel, p: P, d: D) => Shape2D | ProfileInput;
+  /** Exactly two points is a line; any other entry is a shape whose boundaries are scored. */
+  score?: ((k: GeometryKernel, p: P, d: D) => SheetScoreEntry[] | null) | null;
+  /** Filled regions burned into the laser face (`k.text2d`, `k.vector2d`, a Shape2D). */
+  engrave?: ((k: GeometryKernel, p: P, d: D) => Shape2D | ProfileInput | null) | null;
+  /** Where the piece sits, for display AND export. Omitted: flat, no transform. */
+  pose?: SheetPose | ((p: P, d: D) => SheetPose | null) | null;
+  process?: "laser";
+  label?: string;
+  views: string[];
+  display?: SubPartDefinition<P, D>["display"];
+  export?: { name: string };
+  enabled?: (p: P) => unknown;
+  exportable?: boolean;
+  reference?: string;
+  /** Your own placement; runs AFTER the pose. */
+  place?: (solid: Solid, ctx: PlaceContext<P, D>) => Solid;
+}
+
+/** A sub-part cut from flat stock: an ordinary sub-part with `build`, `place` and `sheet` filled in. */
+export function sheetPart<P = ResolvedParams, D = Derived>(spec: SheetPartSpec<P, D>): SubPartDefinition<P, D>;
+
+/** A metric screw size `tSlots` knows. */
+export type ScrewSize = "M2.5" | "M3" | "M4";
+
+/** One edge's joint — plain, JSON-safe data (it lives in `derive()` output). A plain edge is `undefined`. */
+export type EdgeJoint =
+  | { joint: "fingers"; thickness: number; clearance: number; finger: number; side: "outer" | "inner" }
+  | { joint: "tabs"; thickness: number; count: number; width: number }
+  | { joint: "tslots"; thickness: number; screw: ScrewSize; screwLength: number; at: number[]; clearance: number };
+
+/** Finger joint. `clearance` is the TOTAL play per finger; outer fingers protrude, inner ones notch. */
+export function fingers(opts: { thickness: number; clearance?: number; finger?: number; side?: "outer" | "inner" }): Extract<EdgeJoint, { joint: "fingers" }>;
+
+/** Tongues protruding `thickness` from the edge, `count` of them, each `width` wide. */
+export function tabs(opts: { thickness: number; count?: number; width?: number }): Extract<EdgeJoint, { joint: "tabs" }>;
+
+/** A screw-and-nut joint: a shank slot crossed by a nut trap, at fractions `at` along the edge. */
+export function tSlots(opts: { thickness: number; screw?: ScrewSize; screwLength?: number; at?: number[]; clearance?: number }): Extract<EdgeJoint, { joint: "tslots" }>;
+
+/** A panel's four edges, in CCW order; an omitted edge is plain. */
+export interface SheetPanelEdges {
+  bottom?: EdgeJoint;
+  right?: EdgeJoint;
+  top?: EdgeJoint;
+  left?: EdgeJoint;
+}
+
+/** A panel outline: nominal box [0, W] × [0, H] with each edge's joint; `size` includes protrusions. */
+export function sheetPanel(opts: { width: number; height: number; edges?: SheetPanelEdges }): { outline: PointsContour; size: [number, number] };
+
+/** The holes the OTHER panel needs for a tabs or T-slot edge; `line` is the tabbed panel's mid-plane in this panel's frame. */
+export function matchingSlots(joint: EdgeJoint, opts: { line: [Point2, Point2]; clearance?: number }): Contour[];
+
+/** One `fingerBox` panel: its outline in its own frame (bbox [0, 0]–size) and where it goes. */
+export interface FingerBoxPanel {
+  outline: PointsContour;
+  size: [number, number];
+  pose: SheetPose;
+}
+
+/** An open-top finger-jointed box, W × D × H outside: five panels, every corner owned once. */
+export function fingerBox(opts: {
+  width: number;
+  depth: number;
+  height: number;
+  thickness: number;
+  clearance?: number;
+  finger?: number;
+}): Record<"bottom" | "front" | "back" | "left" | "right", FingerBoxPanel>;
+
+/** A slot and the printed tongue that keys into it, from one spec; all the play is on the slot. */
+export function printedTab(opts: { size: [number, number]; thickness: number; clearance?: number }): { slot: PointsContour; tongue: [number, number, number] };
+
+/** An arc-exact round hole (a CCW circle of two arcs) for a sheet part's profile: `circleProfile(d / 2, at)`, named by diameter. */
+export function sheetHole(opts: { d: number; at: Point2 }): ArcContour;
+
+/** Clearance holes (ISO 273 medium) and hex nuts (ISO 4032) for `tSlots`, mm. */
+export const JOINERY_SCREWS: Readonly<Record<ScrewSize, { readonly hole: number; readonly nut: { readonly flats: number; readonly height: number } }>>;
+
+/**
+ * A drawing point on a posed sheet (`depth` mm into the material) → world [x, y, z].
+ * `pose` null (`FLAT_POSE`) is the canonical frame; it needs the sheet's `thickness`,
+ * since the laser face then sits at z = thickness. Otherwise `thickness` is unused.
+ */
+export function sheetToWorld(pose: SheetPose | null, uv: Point2, depth?: number, thickness?: number): [number, number, number];
+
+/** A world point → where it lands on a posed sheet's drawing, [u, v]. `pose` null is the canonical frame. */
+export function worldToSheet(pose: SheetPose | null, xyz: Point3): [number, number];

package/types/lint.d.ts

@@ -39,7 +39,10 @@ export interface Finding {
    * within `file`.
    */
   line?: number;
-  /** A stable ERROR-PATTERNS.md entry id, when one applies. */
+  /**
+   * A stable ERROR-PATTERNS.md entry id, when one applies — or `"sheet-parts"`,
+   * the authoring guide's "Sheet parts" section, on a sheet-part finding.
+   */
   pattern?: string;
 }
 

package/types/oracle.d.ts

@@ -9,7 +9,7 @@ export type { GeometryKernel, Mesh, PartDefinition, ResolvedParams, Solid } from
 export {
   // measurement + verification
   measure, verify, buildView,
-  type MeasureReport, type SubPartFacts, type AggregateFacts, type BuiltSubPart,
+  type MeasureReport, type SubPartFacts, type SheetFacts, type AggregateFacts, type BuiltSubPart,
   type VerifyReport, type VerifyCaseResult, type VerifyCheck, type CheckStatus,
   // mesh facts, gaps, BVH, min wall
   meshVolume, bboxSize, bounds, meshArea, assemblyGaps, meshGaps, buildBVH, meshTriangles, minWall, overhang,

package/types/part.d.ts

@@ -9,7 +9,7 @@
 // src/framework/oracle/verify.js + src/framework/verify-metrics.js (the `verify`
 // block's metric vocabulary).
 
-import type { BackendName, GeometryKernel, Solid } from "./kernel.js";
+import type { BackendName, GeometryKernel, Point2, Point3, ProfileInput, Solid } from "./kernel.js";
 
 /**
  * A value the control panel can hold. Sliders and number boxes write numbers;
@@ -400,6 +400,47 @@ export interface SubPartDefinition<P = ResolvedParams, D = Derived> {
   };
   /** Filename / object name on export; defaults to the key. */
   export?: { name: string };
+  /**
+   * Set by `sheetPart()` (partforge/geometry) on a sub-part cut from flat stock: its
+   * cut/score/engrave declaration, and the one marker framework code recognizes a
+   * sheet part by. Never written by hand.
+   */
+  sheet?: SheetDeclaration<P, D>;
+}
+
+// --- sheet parts ------------------------------------------------------------
+
+/** An axis direction, as a sheet pose names its face and up. */
+export type AxisWord = "+X" | "-X" | "+Y" | "-Y" | "+Z" | "-Z";
+
+/**
+ * Where a sheet part sits in the assembly (docs/AUTHORING-PARTS.md "Sheet parts").
+ * The part is drawn in its own frame — profile in XY, material over z ∈ [0, t], the
+ * laser face at z = t. `face` is the laser face's outward normal, `up` the drawing's
+ * +y (perpendicular to `face`), `at` where drawing [0, 0] lands; drawing +x is
+ * `up × face`, so a pose is always a proper rotation and never mirrors.
+ */
+export interface SheetPose {
+  face: AxisWord;
+  up: AxisWord;
+  at: Point3;
+}
+
+/** One `score` entry: exactly two points is a LINE; anything else is a shape whose boundaries are all scored. */
+export type SheetScoreEntry = [Point2, Point2] | ProfileInput | null;
+
+/** The plain-data declaration `sheetPart()` attaches as `sub.sheet`. */
+export interface SheetDeclaration<P = ResolvedParams, D = Derived> {
+  process: string;
+  material: string | ((p: P, d: D) => string);
+  thickness: number | ((p: P, d: D) => number);
+  profile: (k: GeometryKernel, p: P, d: D) => ProfileInput;
+  score: ((k: GeometryKernel, p: P, d: D) => SheetScoreEntry[] | null) | null;
+  engrave: ((k: GeometryKernel, p: P, d: D) => ProfileInput | null) | null;
+  /** `null` = flat: no transform. */
+  pose: SheetPose | ((p: P, d: D) => SheetPose | null) | null;
+  /** The build `sheetPart` made; `sub.build !== sub.sheet.generatedBuild` is a custom build. */
+  generatedBuild: (k: GeometryKernel, p: P, d: D) => Solid;
 }
 
 export interface ViewDefinition {
@@ -489,6 +530,21 @@ export interface SubPartExpectations {
   refVolumeDeltaPct?: Expectation;
   /** Bounding-box corner drift `[dx, dy, dz]` vs. the sub-part's declared `reference` import. */
   refBboxDelta?: Expectation;
+  /**
+   * Sheet parts only (`sheetPart()`): the narrowest web or finger in the cut
+   * profile, mm. verify checks it on every sheet part at `>=` max(half the
+   * thickness, 0.5 mm) as a volunteered warning; declare it to make it count.
+   * Nothing narrower than twice that floor reads as the ceiling, with a note.
+   */
+  sheetBridge?: Expectation;
+  /** Sheet parts only: the narrowest hole, slot or notch in the cut profile, mm. Same floor as `sheetBridge`. */
+  sheetGap?: Expectation;
+  /** Sheet parts only: engrave/score mark regions lying outside the cut (volunteered check: `0`). */
+  sheetMarks?: Expectation;
+  /** Sheet parts only: separate regions in the cut profile (volunteered check: `1`). */
+  sheetPieces?: Expectation;
+  /** Sheet parts with a custom `build` only: % volume drift from profile area × thickness minus the marks (volunteered check: `<=2`). */
+  sheetSolidMatch?: Expectation;
 }
 
 /**