partforge 0.150.0 → 0.151.0

package/src/framework/export/readme.js

@@ -8,13 +8,14 @@
 import { fmtMm } from "../sheet/constants.js";
 
 export const README_HEADINGS = Object.freeze([
-  "BEFORE YOU CUT", "SHEETS", "PIECES", "PRINTED PARTS", "CLEARANCES (design fit, not kerf)",
+  "BEFORE YOU CUT", "SHEETS", "PIECES", "ROUTER OPERATIONS", "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 ROUTER_LEGEND = "DXF layers: CUT (colour 1) is the through cut; POCKET_<depth>MM and DRILL_D<dia>_<depth>MM / _THRU carry one depth each; SECONDARY outlines operations done with another tool (see ROUTER OPERATIONS); REFERENCE is layout only. Laser pieces keep CUT/SCORE/ENGRAVE.";
 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
@@ -52,6 +53,7 @@ const labelsOf = (labels) => labels.map(cleanLabel).join(", ");
 export function renderReadme(m) {
   const k = m.kerf;
   const kerfed = k > 0;
+  const router = m.destination === "cnc-router";
   // 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.
@@ -60,14 +62,16 @@ export function renderReadme(m) {
     "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."]),
+      router
+        ? "Kerf: none — a CNC router's CAM applies the tool offset."
+        : 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 || router ? [] : ["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,
+      router ? ROUTER_LEGEND : 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."] : []),
@@ -78,12 +82,25 @@ export function renderReadme(m) {
       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)])),
+    "ROUTER OPERATIONS": [...(m.router ?? []).flatMap((r) => [
+      `${labelsOf(r.labels)} (${cleanLabel(r.material)} ${r.thickness.toFixed(2)} mm) — depths from the machined face:`,
+      ...table(["op", "label", "size", "depth", "method"], [
+        ...r.pockets.map((pk) => ["pocket", pk.label ? cleanLabel(pk.label) : "—", mm2([pk.w, pk.h]), `${pk.depth.toFixed(2)} mm`, "mill"]),
+        ...r.drills.map((dr) => ["drill", dr.label ? cleanLabel(dr.label) : "—", `Ø${fmtMm(dr.d)} mm × ${dr.count}`, dr.through ? "through" : `${dr.depth.toFixed(2)} mm`, "drill"]),
+        ...r.extra.map((x) => ["extra", cleanLabel(x.label), mm2([x.w, x.h]), `to ${x.maxDepth.toFixed(2)} mm`, cleanLabel(x.method)]),
+      ]),
+    ]),
+    // The layer legend: one colour per layer name across the whole kit.
+    ...((m.router ?? []).length && (m.layers ?? []).length
+      ? ["LAYERS (one colour per layer across the kit):", ...table(["layer", "colour", "depth"], m.layers.map((l) => [l.name, l.colour, l.depth]))]
+      : [])],
     "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) : [],
+    // Only a non-strict layout (a service, a CNC router) can leave a piece off the sheets.
+    "OVERSIZED PIECES": m.destination === "service" || router ? m.oversized.map(cleanLabel) : [],
     "RENAMED FILES": m.renamed.map(cleanLabel),
     LIMITS: [LIMITS_LINE],
   };

package/src/framework/export/svg.js

@@ -22,6 +22,7 @@ export const SVG_STROKE_MM = 0.025;   // a hairline: laser software cuts it as a
 // 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 SVG_HEX = /^#[0-9A-F]{6}$/i;
 
 const num = (x) => { const v = Number(x.toFixed(4)); return String(v === 0 ? 0 : v); };   // -0 → "0"
 const escapeXml = (s) => String(s)
@@ -74,13 +75,24 @@ export function renderSvg(doc) {
     `<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) {
+  // Group order mirrors dxf.js: engrave, score, every custom (named) layer in first-seen
+  // order across the placements, then cut-inner and cut-outer.
+  const custom = [];
+  for (const placement of doc.placements) for (const layer of placement.drawing.layers)
+    if (layer.name !== undefined && !custom.includes(layer.id)) custom.push(layer.id);
+  const ids = [...ORDER.filter((id) => !id.startsWith("cut")), ...custom, ...ORDER.filter((id) => id.startsWith("cut"))];
+  for (const id of ids) {
     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") {
+      if (layer.name !== undefined) {
+        // a routed layer: stroked in its own colour, never filled
+        if (!SVG_HEX.test(layer.svgColor ?? "")) throw new Error(`renderSvg: layer ${JSON.stringify(layer.id)} needs an svgColor`);
+        for (const p of layer.paths)
+          paths.push(`<path d="${pathData(p, place, H)}" fill="none" stroke="${layer.svgColor}" stroke-width="${SVG_STROKE_MM}"/>`);
+      } else 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(" ");

package/src/framework/geometry/polygon.js

@@ -625,5 +625,6 @@ export { translateProfile, rotateProfile, scaleProfile, mirrorProfile,
 // the drawing ↔ world converters. Plain JS over the contour IR — not kernel ops, so
 // they add nothing to the kernel contract's op lists.
 export { sheetPart } from "../sheet/part.js";
+export { routedPart } from "../sheet/routed.js";
 export { fingers, tabs, tSlots, sheetPanel, matchingSlots, fingerBox, printedTab, sheetHole, JOINERY_SCREWS } from "../sheet/joinery.js";
 export { sheetToWorld, worldToSheet } from "../sheet/pose.js";

package/src/framework/oracle/measure.js

@@ -166,7 +166,7 @@ function sheetRowFacts(kernel, part, name, view, { p, d }, budget, volume) {
   const expected = f.area * f.thickness - MARK_DEPTH * (f.marksArea ?? 0);
   return {
     ...f,
-    at: { bridge: lift(f.at2d.bridge), gap: lift(f.at2d.gap), marks: lift(f.at2d.marks) },
+    at: { bridge: lift(f.at2d.bridge), gap: lift(f.at2d.gap), marks: lift(f.at2d.marks), outside: lift(f.at2d.outside ?? null) },
     solidMatchPct: f.customBuild && f.marksArea != null && expected > 1e-9
       ? (100 * Math.abs(volume - expected)) / expected
       : null,
@@ -192,7 +192,7 @@ function unknownProcessFacts(kernel, sp, p, d) {
     process: sp.sheet.process, material: meta?.material ?? null, thickness: meta?.thickness ?? null, group: meta?.group ?? null,
     flat, area, pieces, customBuild: sp.build !== sp.sheet.generatedBuild,
     marksArea: null, bridge: null, bridgeCapped: false, gap: null, gapCapped: false, marksOutside: null, solidMatchPct: null,
-    at2d: { bridge: null, gap: null, marks: null }, at: { bridge: null, gap: null, marks: null },
+    at2d: { bridge: null, gap: null, marks: null, outside: null }, at: { bridge: null, gap: null, marks: null, outside: null },
     readErrors: { bridge: null, gap: null, marks: null, marksArea: null },
     evaluated: false,
   };

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 });
+  }
+}