partforge 0.150.1 → 0.151.0

package/src/framework/process/cnc-router/descriptor.js

@@ -0,0 +1,174 @@
+// CNC routing — process module #2. Flat stock machined from ONE face: through cuts
+// (profile), flat-floored pockets at a depth, drilled holes at a depth, and `extra`
+// operations the operator does with another tool after the flat milling. The
+// drawing is one layered DXF per piece, depth on the layer name and colour.
+//
+// Import-free apart from sheet/constants.js and lint/finding.js (test/sheet-layering):
+// lint and the oracle read the registry. The resolver that turns pockets/drills/extra
+// into shapes lives in sheet/routed-resolve.js (it may import geometry); the writer in
+// process/cnc-router/export.js (it reaches paper), loaded only by the kit.
+import {
+  EMPTY_MARK_RE, MARK_DEPTH, MARK_OVERCUT, ROUTED_DOC_ID, ROUTED_KEYS, LOSS_TOL_MM2, isSheetPart, sheetMeta, fmtMm,
+} from "../../sheet/constants.js";
+import { err } from "../../lint/finding.js";
+
+// The preview: the profile extruded to the thickness, each pocket cut `depth` down from
+// the machined face (z = t), each drill as a cylinder from the face to its depth —
+// through holes and through pockets (depth = thickness) clear BOTH faces by MARK_OVERCUT so no cap is coplanar with a face
+// (OCCT's coplanar booleans are fragile) — each extra solid subtracted as given, and
+// the reference grooves cut like a laser score. A tool whose region turned out empty
+// (EMPTY_MARK_RE) is dropped, never a build failure; matched by message, never by
+// asking the shape, so this stays probe-safe.
+function orEmpty(make) {
+  try { return make(); } catch (e) { if (EMPTY_MARK_RE.test(e?.message ?? "")) return null; throw e; }
+}
+function routedPreview(k, s) {
+  const t = s.thickness;
+  const body = s.profile.extrude({ h: t });
+  const { pockets, drills, extra } = s.routed;
+  const tools = [
+    ...pockets.map((pk) => orEmpty(() => (pk.depth >= t
+      ? pk.region.extrude({ h: t + 2 * MARK_OVERCUT }).translate([0, 0, -MARK_OVERCUT])
+      : pk.region.extrude({ h: pk.depth + MARK_OVERCUT }).translate([0, 0, t - pk.depth])))),
+    ...drills.map((dr) => (dr.through
+      ? k.cylinder({ d: dr.d, h: t + 2 * MARK_OVERCUT }).translate([dr.at[0], dr.at[1], -MARK_OVERCUT])
+      : k.cylinder({ d: dr.d, h: dr.depth + MARK_OVERCUT }).translate([dr.at[0], dr.at[1], t - dr.depth]))),
+    ...extra.map((x) => x.solid),
+    ...s.grooves.map((g) => orEmpty(() => g.extrude({ h: MARK_DEPTH + MARK_OVERCUT }).translate([0, 0, t - MARK_DEPTH]))),
+  ].filter(Boolean);
+  return tools.length ? body.cutAll(tools) : body;
+}
+
+// ── facts: the operations table ───────────────────────────────────────────────
+// In the laser facts' shape (the laser-only readings null), so oracle/measure.js's
+// sheetRowFacts reads a routed row unchanged; `routed` carries what the router does.
+// `at2d.outside` is the 2-D spot of the first region found outside the profile;
+// `at.outside` (its 3-D place) is left null here — measure.js's sheetRowFacts lifts it.
+const round2 = (x) => Math.round(x * 100) / 100;
+const sizeOf = (shape) => { const { min, max } = shape.boundingBox(); return [max[0] - min[0], max[1] - min[1]]; };
+// The centre of the bounding box of `shape`'s largest region; null when empty.
+function centreOfLargest(shape) {
+  if (shape.isEmpty()) return null;
+  let best = null, bestArea = -Infinity;
+  for (const region of shape.regions()) { const a = region.area(); if (a > bestArea) { best = region; bestArea = a; } }
+  const { min, max } = best.boundingBox();
+  return [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2];
+}
+// Does `shape` leave the profile? Its part outside, when it has an area.
+function outsideOf(shape, profile) {
+  const off = shape.cut(profile);
+  return off.isEmpty() || off.area() <= LOSS_TOL_MM2 ? null : off;
+}
+
+function routedFacts(s) {
+  const { profile, thickness: t } = s;
+  const pieces = profile.toContours().length;
+  const area = pieces ? profile.area() : 0;
+  const flat = pieces ? sizeOf(profile) : [0, 0];
+  const { pockets, drills, extra } = s.routed;
+
+  let outside = 0, empty = 0, outsideAt = null;
+  const noteOutside = (shape) => { const off = outsideOf(shape, profile); if (off) { outside++; outsideAt ??= centreOfLargest(off); } };
+
+  const pocketRows = [];
+  for (const pk of pockets) {
+    if (pk.region.isEmpty()) { empty++; continue; }
+    const [w, h] = sizeOf(pk.region);
+    pocketRows.push({ label: pk.label, depth: pk.depth, w: round2(w), h: round2(h), area: round2(pk.region.area()) });
+    noteOutside(pk.region);
+  }
+  // Drills grouped by (d, depth, through): one row per tool setting, labels joined.
+  const drillGroups = new Map();
+  for (const dr of drills) {
+    const key = `${dr.d}|${dr.depth}|${dr.through}`;
+    const g = drillGroups.get(key) ?? { labels: [], d: dr.d, depth: dr.depth, through: dr.through, count: 0 };
+    g.count++;
+    if (dr.label && !g.labels.includes(dr.label)) g.labels.push(dr.label);
+    drillGroups.set(key, g);
+    noteOutside(dr.shape);
+  }
+  const drillRows = [...drillGroups.values()].map(({ labels, d, depth, through, count }) =>
+    ({ label: labels.length ? labels.join(", ") : null, d, depth, through, count }));
+  // An extra op whose footprint resolved to nothing draws nothing: counted under
+  // `empty` with the empty pockets, never a row (its size has no bounding box).
+  const extraRows = [];
+  for (const x of extra) {
+    if (x.footprint.isEmpty()) { empty++; continue; }
+    const [w, h] = sizeOf(x.footprint);
+    noteOutside(x.footprint);
+    // How deep the op reaches below the machined face (z = t), within the stock. An
+    // empty solid has no bounding box and reaches nothing.
+    const bb = x.solid.boundingBox();
+    const bottom = bb?.min?.[2];
+    const reach = Number.isFinite(bottom) ? t - bottom : 0;
+    extraRows.push({ label: x.label, method: x.method, w: round2(w), h: round2(h), maxDepth: round2(Math.max(0, Math.min(t, reach))) });
+  }
+
+  return {
+    process: s.process, material: s.material, thickness: t, group: s.group,
+    flat, area, pieces, customBuild: s.customBuild,
+    marksArea: null, bridge: null, bridgeCapped: false, gap: null, gapCapped: false, marksOutside: null, solidMatchPct: null,
+    at2d: { bridge: null, gap: null, marks: null, outside: outsideAt },
+    at: { bridge: null, gap: null, marks: null, outside: null },
+    readErrors: { bridge: null, gap: null, marks: null, marksArea: null },
+    evaluated: true,
+    routed: { profile: { w: round2(flat[0]), h: round2(flat[1]) }, pockets: pocketRows, drills: drillRows, extra: extraRows, outside, empty },
+  };
+}
+
+// ── verify metrics: all warnings, volunteered by checks() ─────────────────────
+// None is `budgeted` and none has a `readError`: a routed part's facts are taken
+// whole, so nothing is budget-withheld.
+const METRICS = {
+  routedOutside: { kind: "warn", doc: ROUTED_DOC_ID,
+    extract: (s) => s.sheet?.routed?.outside ?? null,
+    locate: (s) => s.sheet?.at?.outside ?? null,
+    hint: "a pocket, drill or extra-op footprint of this routed part lies partly outside its profile — the router would cut air or the next piece; move it inside the outline, or widen the profile" },
+  routedEmpty: { kind: "warn", doc: ROUTED_DOC_ID,
+    extract: (s) => s.sheet?.routed?.empty ?? null,
+    hint: "a pocket or extra-op footprint of this routed part resolved to an empty region at these parameters, so nothing is drawn for it — check the region's size and position, or drop the entry" },
+  routedPieces: { kind: "warn", doc: ROUTED_DOC_ID,
+    extract: (s) => s.sheet?.pieces ?? null,
+    hint: "the profile is not exactly one piece — a routed part must cut out as one region; join the pieces or split them into separate routedPart sub-parts" },
+};
+
+// ── lint ──────────────────────────────────────────────────────────────────────
+const DRILL_DEPTH_HINT = "A drill's depth is measured from the machined face; a depth at or past the stock thickness is a through hole. Lower the depth, raise the stock thickness control, or set depth to the thickness to drill through.";
+const ROUTER_RULES = [{
+  id: "routed-drill-depth",
+  run: ({ part, p, d, deriveError }) => {
+    if (deriveError || !part?.parts || typeof part.parts !== "object") return [];
+    return Object.entries(part.parts).flatMap(([name, sp]) => {
+      if (!isSheetPart(sp) || sp.sheet.process !== "cnc-router" || typeof sp.sheet.drills !== "function") return [];
+      const meta = sheetMeta(sp, p, d);
+      if (!meta) return [];
+      let drills;
+      try { drills = sp.sheet.drills(p, d); } catch { return []; }   // a throwing drills() is the build rules' business
+      if (!Array.isArray(drills)) return [];
+      return drills.flatMap((dr, i) => {
+        if (!dr || typeof dr.depth !== "number" || !(dr.depth > meta.thickness)) return [];
+        const who = typeof dr.label === "string" && dr.label.trim() ? `drill "${dr.label.trim()}"` : `drill ${i + 1}`;
+        return [err("routed-drill-depth", `sub-part "${name}": ${who} is ${fmtMm(dr.depth)} mm deep in ${fmtMm(meta.thickness)} mm stock`,
+          DRILL_DEPTH_HINT, `parts.${name}.sheet.drills`, ROUTED_DOC_ID)];
+      });
+    });
+  },
+}];
+
+export const ROUTER = {
+  id: "cnc-router",
+  label: "CNC routing",
+  stock: "sheet",
+  docId: ROUTED_DOC_ID,
+  // profile = the through cut; reference = vector lines (centerlines); pockets,
+  // drills and extra footprints = filled regions at a depth.
+  layers: { profile: "region", reference: "line", pockets: "region", drills: "region", extra: "region" },
+  keys: ROUTED_KEYS,
+  reservedKeys: [],
+  preview: routedPreview,
+  destinations: [{ id: "cnc-router", cutFormat: "dxf" }],
+  facts: routedFacts,
+  checks: () => ({ routedOutside: "0", routedEmpty: "0", routedPieces: "1" }),
+  metrics: METRICS,
+  lintRules: ROUTER_RULES,
+};

package/src/framework/process/cnc-router/export.js

@@ -0,0 +1,74 @@
+// The cnc-router exporter: one resolved routed piece → one Drawing whose layers carry
+// their own DXF name and colour (drawing.js ROUTED_COLORS). Loaded only through
+// process/exporters.js. Kerf never applies: the CAM offsets for the tool, and
+// validateKitOptions has already refused a kerf for this destination — the check here
+// is the belt for a laser destination carrying a routed piece.
+//
+// Colours: `ctx.palette` (drawing.js routedPalette, built by the kit over EVERY routed
+// piece) when given, so one depth is one colour across the kit; without it — a direct
+// call — the piece ranks its own depths. Each named layer also carries its `depth` (mm,
+// two decimals) and drills `through`, which the README's layer legend reads.
+import {
+  refitRing, ringsOf, cutRings, drawingBounds, routedLayerName, depthToken, drillKey, ROUTED_COLORS,
+} from "../../export/drawing.js";
+import { KIT_OPTIONS_ERROR } from "../../export/formats.js";
+
+const closedPath = (ring) => ({ start: ring.start, segments: ring.segments, closed: true });
+const refitRegions = (regions) => regions.map((rg) => ({ outer: refitRing(rg.outer), holes: rg.holes.map(refitRing) }));
+const allRings = (regions) => { const r = ringsOf(regions); return [...r.outer, ...r.holes]; };
+const ringsOfShape = (shape) => allRings(refitRegions(shape.toContours())).map(closedPath);
+
+function drawing(s, o, k, ctx = {}) {
+  const label = ctx.label ?? s.label ?? "routed part";
+  if (o?.kerf > 0) throw new Error(`${KIT_OPTIONS_ERROR} kerf does not apply to a CNC router — the CAM applies the tool offset; set kerf to 0 ("${label}")`);
+  const nominal = refitRegions(s.profile.toContours());
+  if (nominal.length === 0) throw new Error(`cut kit: "${label}" has an empty profile — nothing to cut`);
+  const cut = cutRings(nominal);
+  const { pockets, drills, extra } = s.routed;
+
+  const layers = [];
+  const reference = [
+    ...s.score.lines.map(([a, b]) => ({ start: [a[0], a[1]], segments: [{ to: [b[0], b[1]] }], closed: false })),
+    ...s.score.shapes.flatMap(ringsOfShape),
+  ];
+  if (reference.length) layers.push({ id: "reference", name: "REFERENCE", ...ROUTED_COLORS.reference, paths: reference });
+  const secondary = extra.flatMap((x) => ringsOfShape(x.footprint));
+  if (secondary.length) layers.push({ id: "secondary", name: "SECONDARY", ...ROUTED_COLORS.secondary, paths: secondary });
+
+  // Drills grouped by (d, depth, through) in first-seen order; each hole a closed ring
+  // of two exact arcs, which dxf.js writes as a CIRCLE.
+  const palette = ctx.palette ?? null;
+  const drillGroups = new Map();
+  drills.forEach((dr) => {
+    const key = drillKey(dr);
+    const colour = palette?.drill.get(key) ?? ROUTED_COLORS.drill[drillGroups.size % ROUTED_COLORS.drill.length];
+    const g = drillGroups.get(key) ?? { id: `drill-${key}`, name: routedLayerName("drill", dr), ...colour,
+      depth: Number(depthToken(dr.depth)), through: dr.through, paths: [] };
+    g.paths.push(...ringsOfShape(dr.shape));
+    drillGroups.set(key, g);
+  });
+  layers.push(...drillGroups.values());
+
+  // Pockets grouped by two-decimal depth, shallowest layer first; an empty region draws nothing.
+  const pocketGroups = new Map();
+  for (const pk of pockets) {
+    const paths = ringsOfShape(pk.region);
+    if (paths.length === 0) continue;
+    const key = depthToken(pk.depth);
+    const g = pocketGroups.get(key) ?? { id: `pocket-${key}`, name: routedLayerName("pocket", pk), depth: Number(key), paths: [] };
+    g.paths.push(...paths);
+    pocketGroups.set(key, g);
+  }
+  [...pocketGroups.values()].sort((a, b) => a.depth - b.depth).forEach((g, i) => {
+    const colour = palette?.pocket.get(depthToken(g.depth)) ?? ROUTED_COLORS.pocket[i % ROUTED_COLORS.pocket.length];
+    layers.push({ ...g, ...colour });
+  });
+
+  if (cut.inner.length) layers.push({ id: "cut-inner", paths: cut.inner.map(closedPath) });
+  layers.push({ id: "cut-outer", paths: cut.outer.map(closedPath) });
+
+  const nb = drawingBounds([{ id: "cut-outer", paths: ringsOf(nominal).outer.map(closedPath) }]);
+  return { layers, bounds: drawingBounds(layers), nominal: [nb.max[0] - nb.min[0], nb.max[1] - nb.min[1]], kerf: 0 };
+}
+
+export default { drawing };

package/src/framework/process/exporters.js

@@ -8,6 +8,7 @@
 // test/kit-export-guards.test.js fails until the two id lists agree.
 export const EXPORTER_LOADERS = Object.freeze({
   laser: () => import("./laser/export.js"),
+  "cnc-router": () => import("./cnc-router/export.js"),
 });
 
 // The process's ProcessExporter ({ drawing(s, o, k, ctx) }), loaded on first use.

package/src/framework/process/registry.js

@@ -6,8 +6,9 @@
 // the descriptors are: lint and the oracle read this file.
 import { isSheetPart } from "../sheet/constants.js";
 import { LASER } from "./laser/descriptor.js";
+import { ROUTER } from "./cnc-router/descriptor.js";
 
-export const PROCESSES = [LASER];
+export const PROCESSES = [LASER, ROUTER];
 export const PROCESS_IDS = PROCESSES.map((d) => d.id);
 
 export const processById = (id) => PROCESSES.find((d) => d.id === id) ?? null;

package/src/framework/sheet/constants.js

@@ -17,6 +17,13 @@
 // lint finding and DFM check carries it as `pattern`, which survives the host's
 // truncation of message/hint.
 export const SHEET_DOC_ID = "sheet-parts";
+// The routed-parts guide section id ("## Routed parts" in docs/AUTHORING-PARTS.md):
+// every cnc-router lint finding and check carries it as `pattern`.
+export const ROUTED_DOC_ID = "routed-parts";
+// The keys only routedPart() admits, on top of SHEET_KEYS. `reference` is stored on
+// the sheet record as `score` (same array shape, same preview groove) and drawn on
+// the REFERENCE layer; the other three are resolved by sheet/routed.js.
+export const ROUTED_KEYS = Object.freeze(["pockets", "drills", "extra", "reference"]);
 
 // The six axis words a SheetPose names its face and up with.
 export const AXIS_WORDS = Object.freeze(["+X", "-X", "+Y", "-Y", "+Z", "-Z"]);

package/src/framework/sheet/part.js

@@ -26,8 +26,8 @@ import { applyPose, resolveSheet, sheetPreview } from "./resolve.js";
 import { PROCESSES, PROCESS_IDS, processById } from "../process/registry.js";
 
 const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
-const KNOWN = [...SHEET_KEYS, ...SUBPART_PASSTHROUGH_KEYS];
-const KEY_LIST = `${SHEET_KEYS.join(", ")}, plus the sub-part keys ${SUBPART_PASSTHROUGH_KEYS.join(", ")}`;
+const KNOWN_BASE = [...SHEET_KEYS, ...SUBPART_PASSTHROUGH_KEYS];
+const keyList = (processKeys) => `${[...SHEET_KEYS, ...processKeys].join(", ")}, plus the sub-part keys ${SUBPART_PASSTHROUGH_KEYS.join(", ")}`;
 const optionalFn = (v) => v === undefined || v === null || typeof v === "function";
 
 // Every mistake throws here, at module load, naming the fix — in the order a reader
@@ -43,11 +43,21 @@ function checkSpec(spec) {
   const reservedKeys = [...RESERVED_KEYS, ...PROCESSES.flatMap((proc) => proc.reservedKeys ?? [])];
   const reserved = keys.find((key) => reservedKeys.includes(key));
   if (reserved) throw new Error(`sheetPart: "${reserved}" is reserved for a future process and not supported yet`);
-  const unknown = keys.find((key) => !KNOWN.includes(key));
-  if (unknown) throw new Error(`sheetPart: unknown key "${unknown}" — the keys are ${KEY_LIST}`);
-
   const process = spec.process ?? "laser";
-  if (!processById(process)) throw new Error(`sheetPart: unknown process ${JSON.stringify(process)} — valid: ${PROCESS_IDS.join(", ")}`);
+  const desc = processById(process);
+  if (!desc) {
+    throw new Error(`sheetPart: unknown process ${JSON.stringify(process)} — valid: ${PROCESS_IDS.join(", ")}; for CNC-routed stock with pockets and drills at depth use routedPart()`);
+  }
+  // A process's own declaration keys (sheet/constants.js ROUTED_KEYS for cnc-router).
+  // `reference` is routedPart's name for the score layer and arrives here already
+  // mapped onto `score`, so it is not admitted on the record itself.
+  const processKeys = (desc.keys ?? []).filter((key) => key !== "reference");
+  const unknown = keys.find((key) => !KNOWN_BASE.includes(key) && !processKeys.includes(key));
+  if (unknown) throw new Error(`sheetPart: unknown key "${unknown}" — the keys are ${keyList(processKeys)}`);
+  for (const key of processKeys) {
+    if (!optionalFn(spec[key])) throw new Error(`sheetPart: ${key} must be a function (k, p, d) => …, or omitted`);
+  }
+
   const { material: m, thickness: t } = spec;
   if (!(typeof m === "function" || (typeof m === "string" && m.trim() !== "")))
     throw new Error('sheetPart: material must be a non-empty string or a (p, d) => string function — a stock label like "birch plywood"');
@@ -63,11 +73,11 @@ function checkSpec(spec) {
     if (reason) throw new Error(`sheetPart: ${reason}`);
   }
   if (spec.place !== undefined && typeof spec.place !== "function") throw new Error("sheetPart: place must be a function (solid, ctx) => solid");
-  return process;
+  return { process, processKeys };
 }
 
 export function sheetPart(spec) {
-  const process = checkSpec(spec);
+  const { process, processKeys } = checkSpec(spec);
   const sub = {};
   for (const key of SUBPART_PASSTHROUGH_KEYS)
     if (key !== "place" && spec[key] !== undefined) sub[key] = spec[key];
@@ -109,6 +119,7 @@ export function sheetPart(spec) {
     place: authorPlace,
     generatedBuild,
     generatedPlace,
+    ...Object.fromEntries(processKeys.map((key) => [key, spec[key] ?? null])),
   });
   sub.build = generatedBuild;
   if (generatedPlace) sub.place = generatedPlace;

package/src/framework/sheet/resolve.js

@@ -12,6 +12,7 @@
 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";
+import { resolveRouted } from "./routed-resolve.js";
 
 const fail = (sp, problem) => new Error(`sheet part${sp.label ? ` "${sp.label}"` : ""}: ${problem}`);
 const isNum = (v) => typeof v === "number" && Number.isFinite(v);
@@ -45,8 +46,16 @@ function shapeGroove(shape) {
   return orEmpty(() => outer.cut(shape.offset(-SCORE_WIDTH / 2))) ?? outer;
 }
 
+// A process's own resolver, keyed by id, producing the `routed`-style field its
+// descriptor's facts/preview and its exporter read. The laser has none. Lives here,
+// not on the descriptor, because a descriptor may import nothing but constants and
+// finding.js, and a resolver lifts shapes with the kernel.
+const PROCESS_RESOLVERS = Object.freeze({ "cnc-router": resolveRouted });
+
 // → ResolvedSheet: { process, material, thickness, group, label, pose, profile,
-//   score: { lines, shapes }, engrave, grooves, customBuild, trustedShape2d, recoverArcs }.
+//   score: { lines, shapes }, engrave, grooves, customBuild, trustedShape2d, recoverArcs,
+//   routed? } — `routed` ({ pockets, drills, extra }, sheet/routed-resolve.js) only for the
+//   cnc-router process; a laser sheet has no such field.
 //   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
@@ -98,13 +107,15 @@ export function resolveSheet(k, sp, p, d) {
     ...shapes.map(shapeGroove),
   ];
 
-  return {
+  const base = {
     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,
   };
+  const resolveProcess = PROCESS_RESOLVERS[s.process];
+  return resolveProcess ? { ...base, routed: resolveProcess(k, sp, p, d, base) } : base;
 }
 
 // The default preview: the profile extruded to the thickness, the engrave pocketed and

package/src/framework/sheet/routed-resolve.js

@@ -0,0 +1,62 @@
+// Resolve a routed part's pockets, drills and extra ops at (p, d) — the cnc-router
+// process's half of resolveSheet (sheet/resolve.js dispatches here by process id).
+//
+// PROBE-SAFE like sheet/resolve.js: kernel and Shape2D METHODS only, no geometry
+// queries, no branching on geometry. The exact circle for a drill is written as the
+// contract's two-arc ring (sheetHole's form) rather than imported from joinery.js, which
+// the oracle's closure may not reach.
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+const isPoint = (q) => Array.isArray(q) && q.length === 2 && isNum(q[0]) && isNum(q[1]);
+const isSolid = (v) => !!v && typeof v === "object" && typeof v.cutAll === "function" && typeof v.translate === "function";
+const circleRing = ([x, y], r) => ({ start: [x + r, y], segments: [{ to: [x - r, y], via: [x, y + r] }, { to: [x + r, y], via: [x, y - r] }] });
+
+const fail = (sp, problem) => new Error(`routed part${sp.label ? ` "${sp.label}"` : ""}: ${problem}`);
+const name = (entry, i, kind) => (typeof entry.label === "string" && entry.label.trim() ? `${kind} "${entry.label}"` : `${kind} ${i + 1}`);
+const depthOf = (sp, entry, who) => {
+  if (!isNum(entry.depth) || entry.depth <= 0) throw fail(sp, `${who} depth must be a finite number > 0 (mm), got ${JSON.stringify(entry.depth)}`);
+  return entry.depth;
+};
+const labelOf = (entry) => (typeof entry.label === "string" && entry.label.trim() ? entry.label.trim() : null);
+const list = (sp, fn, args, what, shape) => {
+  if (!fn) return [];
+  const out = fn(...args);
+  if (out === null || out === undefined) return [];
+  if (!Array.isArray(out)) throw fail(sp, `${what} must return an array of ${shape}`);
+  return out.filter((e) => e !== null && e !== undefined);
+};
+
+// `base` is resolveSheet's ResolvedSheet so far (profile, thickness, score…); the
+// return value is merged onto it as `routed`.
+export function resolveRouted(k, sp, p, d, base) {
+  const s = sp.sheet;
+  const t = base.thickness;
+
+  const pockets = list(sp, s.pockets, [k, p, d], "pockets(k, p, d)", "{ region, depth, label? }").map((e, i) => {
+    const who = name(e, i, "pocket");
+    if (!e || typeof e !== "object" || e.region === null || e.region === undefined) throw fail(sp, `${who} needs a region (a Shape2D or profile)`);
+    const depth = depthOf(sp, e, who);
+    if (depth > t) throw fail(sp, `${who} is ${e.depth} mm deep in ${t} mm stock — a pocket may be at most the thickness; make it a through cut in \`profile\` if it should go through`);
+    return { region: k.shape2d(e.region), depth, label: labelOf(e) };
+  });
+
+  const drills = list(sp, s.drills, [p, d], "drills(p, d)", "{ at, d, depth }").map((e, i) => {
+    const who = name(e, i, "drill");
+    if (!e || typeof e !== "object" || !isPoint(e.at)) throw fail(sp, `${who} needs at: [x, y]`);
+    if (!isNum(e.d) || e.d <= 0) throw fail(sp, `${who} d must be a finite number > 0 (mm), got ${JSON.stringify(e.d)}`);
+    const depth = depthOf(sp, e, who);
+    const through = depth >= t;
+    return { shape: k.shape2d(circleRing(e.at, e.d / 2)), at: [e.at[0], e.at[1]], d: e.d, depth: through ? t : depth, through, label: labelOf(e) };
+  });
+
+  const extra = list(sp, s.extra, [k, p, d], "extra(k, p, d)", "{ solid, footprint, label, method }").map((e, i) => {
+    const label = labelOf(e);
+    if (!label) throw fail(sp, `extra op ${i + 1} needs a label — say what it is ("12° domino slot")`);
+    const who = `extra op "${label}"`;
+    if (typeof e.method !== "string" || !e.method.trim()) throw fail(sp, `${who} needs a method — say how the operator makes it ("table saw, blade tilted 12°")`);
+    if (!isSolid(e.solid)) throw fail(sp, `${who} needs a solid — the geometry it removes, for the preview and the STEP`);
+    if (e.footprint === null || e.footprint === undefined) throw fail(sp, `${who} needs a footprint — its outline on the machined face, for the drawing`);
+    return { solid: e.solid, footprint: k.shape2d(e.footprint), label, method: e.method.trim() };
+  });
+
+  return { pockets, drills, extra };
+}

package/src/framework/sheet/routed.js

@@ -0,0 +1,44 @@
+// routedPart(spec) — a sub-part CNC-routed from flat stock: the profile is the through
+// cut, pockets are flat-floored regions at a depth, drills are round holes at a depth
+// (through when depth >= thickness), and `extra` entries are operations the operator
+// does with another tool after the flat milling (a tilted slot, a scooped thumb hold):
+// a solid for the preview and the STEP, a footprint for the drawing, a label and a
+// method for the README. It is sheetPart with process "cnc-router": one model, so the
+// assembly, the renders, the STEP and the kit all read the same declaration.
+//
+// Every mistake throws here, at module load, naming the fix. The per-(p, d) shapes are
+// resolved in resolveRouted (./routed-resolve.js), called by sheet/resolve.js for this process.
+import { sheetPart } from "./part.js";
+import { ROUTED_KEYS } from "./constants.js";
+
+const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+const optionalFn = (v) => v === undefined || v === null || typeof v === "function";
+
+const SIGNATURES = {
+  pockets: "pockets must be a function (k, p, d) => [{ region, depth, label? }], or omitted",
+  drills: "drills must be a function (p, d) => [{ at: [x, y], d, depth, label? }], or omitted",
+  extra: "extra must be a function (k, p, d) => [{ solid, footprint, label, method }], or omitted",
+  reference: "reference must be a function (k, p, d) => [[x, y], [x, y]] lines and shapes, or omitted",
+};
+
+export function checkRoutedSpec(spec) {
+  if (!isPlainObject(spec)) throw new Error("routedPart: expected an options object — routedPart({ material, thickness, profile, pockets, drills, views, … })");
+  const keys = Object.keys(spec);
+  if (keys.includes("score")) throw new Error('routedPart: "score" is not a routedPart key — centerlines and layout marks go in `reference`');
+  if (keys.includes("engrave")) throw new Error('routedPart: "engrave" is not a routedPart key — a routed part has no engraving; a shallow pocket is `pockets`');
+  if (keys.includes("process")) throw new Error('routedPart: "process" is not a routedPart key — routedPart is always the cnc-router process');
+  for (const key of ROUTED_KEYS) {
+    if (!optionalFn(spec[key])) throw new Error(`routedPart: ${SIGNATURES[key]}`);
+  }
+}
+
+export function routedPart(spec) {
+  checkRoutedSpec(spec);
+  const { reference, ...rest } = spec;
+  try {
+    return sheetPart({ ...rest, process: "cnc-router", ...(reference ? { score: reference } : {}) });
+  } catch (e) {
+    // sheetPart's own refusals, re-labelled so the author sees the helper they called.
+    throw new Error(String(e.message).replace(/^sheetPart:/, "routedPart:"), { cause: e });
+  }
+}

package/types/geometry.d.ts

@@ -315,7 +315,13 @@ export interface SheetPartSpec<P = ResolvedParams, D = Derived> {
   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";
+  process?: "laser" | "cnc-router";
+  /** `process: "cnc-router"` only: flat-floored pockets at a depth (as `routedPart`). */
+  pockets?: ((k: GeometryKernel, p: P, d: D) => (RoutedPocket | null)[] | null) | null;
+  /** `process: "cnc-router"` only: drilled holes at a depth (as `routedPart`). */
+  drills?: ((p: P, d: D) => (RoutedDrill | null)[] | null) | null;
+  /** `process: "cnc-router"` only: operations done with another tool (as `routedPart`). */
+  extra?: ((k: GeometryKernel, p: P, d: D) => (RoutedExtra | null)[] | null) | null;
   label?: string;
   views: string[] | Record<string, true | ((s: Solid, p: P, d: D) => Solid)>;
   display?: SubPartDefinition<P, D>["display"];
@@ -330,6 +336,43 @@ export interface SheetPartSpec<P = ResolvedParams, D = Derived> {
 /** 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>;
 
+// --- routed parts (docs/AUTHORING-PARTS.md "Routed parts") --------------------
+
+/** A flat-floored pocket machined `depth` mm down from the machined face. */
+export interface RoutedPocket { region: Shape2D | ProfileInput; depth: number; label?: string }
+/** A drilled hole; `depth` equal to the stock thickness drills through — deeper is a `routed-drill-depth` lint error. */
+export interface RoutedDrill { at: Point2; d: number; depth: number; label?: string }
+/** An operation done with another tool after the flat milling: the solid is cut in the preview and the STEP, the footprint is drawn, label and method go in the README. */
+export interface RoutedExtra { solid: Solid; footprint: Shape2D | ProfileInput; label: string; method: string }
+
+/**
+ * What `routedPart` accepts: `sheetPart`'s stock, profile and pose, plus pockets,
+ * drills and extra ops at depth. `score`/`engrave`/`process` are refused at load.
+ */
+export interface RoutedPartSpec<P = ResolvedParams, D = Derived> {
+  material: string | ((p: P, d: D) => string);
+  /** The MEASURED stock thickness in mm. */
+  thickness: number | ((p: P, d: D) => number);
+  /** The THROUGH cut: outline plus through holes, seen from the machined face. */
+  profile: (k: GeometryKernel, p: P, d: D) => Shape2D | ProfileInput;
+  pockets?: ((k: GeometryKernel, p: P, d: D) => (RoutedPocket | null)[] | null) | null;
+  drills?: ((p: P, d: D) => (RoutedDrill | null)[] | null) | null;
+  extra?: ((k: GeometryKernel, p: P, d: D) => (RoutedExtra | null)[] | null) | null;
+  /** Centerlines and layout marks: drawn on REFERENCE, cut nothing. Same entries as `score`. */
+  reference?: ((k: GeometryKernel, p: P, d: D) => SheetScoreEntry[] | null) | null;
+  pose?: SheetPose | ((p: P, d: D) => SheetPose | null) | null;
+  label?: string;
+  views: string[] | Record<string, true | ((s: Solid, p: P, d: D) => Solid)>;
+  display?: SubPartDefinition<P, D>["display"];
+  export?: { name: string };
+  enabled?: (p: P) => unknown;
+  exportable?: boolean;
+  place?: (solid: Solid, ctx: PlaceContext<P, D>) => Solid;
+}
+
+/** A sub-part CNC-routed from flat stock: an ordinary sub-part with `build`, `place` and a `sheet` record of process `"cnc-router"`. */
+export function routedPart<P = ResolvedParams, D = Derived>(spec: RoutedPartSpec<P, D>): SubPartDefinition<P, D>;
+
 /** A metric screw size `tSlots` knows. */
 export type ScrewSize = "M2.5" | "M3" | "M4";
 

package/types/index.d.ts

@@ -51,8 +51,8 @@ export interface ExportableSheetInfo {
  * starting `"cut kit options:"` for anything it cannot honour.
  */
 export interface KitOptions {
-  /** `"own-laser"` (default): SVG, laid out on sheets. `"service"`: DXF, one cut-only file per piece. */
-  destination?: "own-laser" | "service";
+  /** `"own-laser"` (default): SVG, laid out on sheets. `"service"`: DXF, one cut-only file per piece. `"cnc-router"`: DXF, one layered file per routed piece; kerf must be 0. */
+  destination?: "own-laser" | "service" | "cnc-router";
   /** Derived from `destination`; when given it must match. */
   cutFormat?: "svg" | "dxf";
   /** mm, 0–0.5: the cut lines move out by half of it. Default 0 (nominal geometry). */

package/types/part.d.ts

@@ -556,6 +556,12 @@ export interface SubPartExpectations {
   sheetPieces?: Expectation;
   /** Sheet parts with a custom `build` only: % volume drift from profile area × thickness minus the marks (volunteered check: `<=2`). */
   sheetSolidMatch?: Expectation;
+  /** Routed parts only: pocket, drill or extra-op footprint regions outside the profile (volunteered check: `0`). */
+  routedOutside?: Expectation;
+  /** Routed parts only: pockets whose region resolved empty (volunteered check: `0`). */
+  routedEmpty?: Expectation;
+  /** Routed parts only: separate regions in the cut profile (volunteered check: `1`). */
+  routedPieces?: Expectation;
 }
 
 /**

package/types/testing.d.ts

@@ -340,14 +340,33 @@ export interface SheetFacts {
   marksOutside: number | null;
   /** Custom builds only: `100·|volume − (area·thickness − 0.2·marksArea)| / (area·thickness − 0.2·marksArea)`. */
   solidMatchPct: number | null;
-  at2d: { bridge: [number, number] | null; gap: [number, number] | null; marks: [number, number] | null };
-  at: { bridge: number[] | null; gap: number[] | null; marks: number[] | null };
+  /** `outside` is a routed part's (the 2-D spot of the first op found outside the profile); a laser part's facts leave it out. */
+  at2d: { bridge: [number, number] | null; gap: [number, number] | null; marks: [number, number] | null; outside?: [number, number] | null };
+  /** `outside`: the 3-D place of `at2d.outside` when the part's pose is trusted, else `null`. */
+  at: { bridge: number[] | null; gap: number[] | null; marks: number[] | null; outside: [number, number, number] | null };
   /**
    * Why a reading is `null` although `evaluated` is true — the geometry engine refused
    * the profile, or the reading threw — or `null` for each one that was taken.
    */
   readErrors: { bridge: string | null; gap: string | null; marks: string | null; marksArea: string | null };
   evaluated: boolean;
+  /** A routed part's (`process: "cnc-router"`) operations table; absent on a laser part. */
+  routed?: RoutedFacts;
+}
+
+/** A routed part's operations table, as the README's ROUTER OPERATIONS block prints it. Sizes in mm to two decimals. */
+export interface RoutedFacts {
+  profile: { w: number; h: number };
+  /** One row per non-empty pocket. */
+  pockets: Array<{ label: string | null; depth: number; w: number; h: number; area: number }>;
+  /** One row per tool setting (d, depth, through), labels joined with ", ". */
+  drills: Array<{ label: string | null; d: number; depth: number; through: boolean; count: number }>;
+  /** One row per extra op with a non-empty footprint; `maxDepth` is how far its solid reaches below the machined face, within the stock. */
+  extra: Array<{ label: string; method: string; w: number; h: number; maxDepth: number }>;
+  /** How many pockets, drills and extra footprints leave the profile. */
+  outside: number;
+  /** How many pockets and extra footprints resolved to an empty region. */
+  empty: number;
 }
 
 export interface SubPartFacts {