partforge 0.150.1 → 0.151.0

package/docs/AUTHORING-PARTS.md

@@ -1906,7 +1906,7 @@ plate: sheetPart({
 It returns an ordinary sub-part: `build`, the pose's placement and a plain-data `sheet`. A field
 needing the kernel is `(k, p, d) => …`; a plain value is a literal or `(p, d) => …`.
 `material`, `thickness` and `profile` are required; `score`, `engrave`, `pose`,
-`process` (default `"laser"`) are optional; `label`, `views`, `display`, `export`,
+`process` (default `"laser"`; `"cnc-router"` is `routedPart`, below) are optional; `label`, `views`, `display`, `export`,
 `enabled`, `exportable`, `reference` pass through; your `views` poses apply after the `pose`, in the viewer only. `build` is supplied — passing one throws, as do `kerf`, `outline`/`cut` and
 `quantity`; each error names the fix.
 
@@ -2020,7 +2020,7 @@ the assembled view, and `minWall` and the overhang check skip sheet parts.
 
 ### The kit
 
-A host downloads sheet parts as one ZIP, the **cut & print kit** (`format: "bundle"`): `README.txt`, `parts.csv`, laid-out `sheets/`, one `parts/` file per distinct piece (plus a `-marks.dxf` for a cutting service) and `print/` for printed parts. Identical pieces merge into one `-xN` file named from `export: { name }`, else the key. Destination (`"own-laser"` or `"service"`), kerf and stock size are chosen at download, so draw nominal and bind `thickness` to the measured control. A choice the kit cannot honour fails with `cut kit options:`.
+A host downloads sheet parts as one ZIP, the **cut & print kit** (`format: "bundle"`): `README.txt`, `parts.csv`, laid-out `sheets/`, one `parts/` file per distinct piece (plus a `-marks.dxf` for a cutting service) and `print/` for printed parts. Identical pieces merge into one `-xN` file named from `export: { name }`, else the key. Destination (`"own-laser"`, `"service"` or `"cnc-router"`), kerf and stock size are chosen at download, so draw nominal and bind `thickness` to the measured control. A choice the kit cannot honour fails with `cut kit options:`.
 
 ### Limits
 
@@ -2150,6 +2150,112 @@ export default {
 };
 ```
 
+## Routed parts
+
+CNC-routed parts from flat stock — hardwood, plywood, MDF, acrylic — for a 2.5D router
+CAM (Vectric VCarve, Carbide Create, Easel, Carveco): a through cut, flat-floored
+pockets at a depth, drilled holes at a depth, and operations done with another tool
+afterwards. Build each piece with `routedPart()` from `partforge/geometry`; the cut &
+print kit's **CNC router** destination writes one DXF per piece with one layer per depth,
+and a README table of every operation. A routed part is also the 3D sub-part — assembly,
+renders and STEP all come from the one declaration — so model it once.
+
+### When a sub-part is a routed part
+
+When it is machined from one face of a flat board: an outline, pockets with flat floors,
+holes, all straight down. A sculpted surface, a part machined from both faces, or
+anything that is not flat stock is an ordinary `build` (export it as STEP). A laser-cut
+plate is `sheetPart`.
+
+### routedPart
+
+```js
+import { routedPart, roundedRectProfile } from "partforge/geometry";
+
+plinth: routedPart({
+  label: "Hardwood base", views: { assembly: true, base: true }, display: { color: 0x6e3d23 },
+  material: "walnut",                           // stock label: groups pieces in the kit
+  thickness: (p) => p.baseThickness,            // the MEASURED board, from a control
+  profile: (k, p) => k.shape2d(roundedRectProfile(p.baseLength, p.baseWidth, 10)),   // the THROUGH cut
+  pockets: (k, p, d) => [
+    { region: k.shape2d(roundedRectProfile(d.vaultW, d.vaultL, 2)).translate([0, -9]), depth: 11.43, label: "peg vault" },
+    { region: k.shape2d(roundedRectProfile(d.pocketW, d.pocketL, 4)).translate([-58, -10]), depth: p.inlayThickness, label: "inlay pocket" },
+  ],
+  drills: (p, d) => d.pegHoles.map(([x, y]) => ({ at: [x, y], d: p.pegHoleDia, depth: 10 })),
+  extra: (k, p, d) => [{
+    solid: k.box({ size: [d.rackL, 12, 14] }).rotateX(-p.rackTilt).at([0, d.rackY, p.baseThickness - 9.5]),
+    footprint: k.shape2d(roundedRectProfile(d.rackL, 12, 2)).translate([0, d.rackY]),
+    label: "domino rack slot", method: `table saw, blade tilted ${p.rackTilt}°, 9.5 mm deep`,
+  }],
+  reference: (k, p) => [[[-p.baseLength / 2 + 10, 0], [p.baseLength / 2 - 10, 0]]],   // a centerline
+}),
+```
+
+`material`, `thickness` and `profile` are required; `pockets`, `drills`, `extra`,
+`reference` and `pose` are optional; `label`, `views`, `display`, `export`, `enabled`,
+`exportable` pass through. A field needing the kernel is `(k, p, d) => …`; `drills` is
+`(p, d) => …`. `build` is supplied — passing one throws, as do `kerf`, `score`,
+`engrave` and `process`; each error names the fix. The drawing is in XY with the
+machined face at z = `thickness`; `pose` places it exactly as a sheet part's does.
+
+### Pockets, drills, extra ops and reference lines
+
+- **`pockets`** — `[{ region, depth, label? }]`: a Shape2D or profile machined `depth`
+  mm down from the machined face, flat-floored. `depth` may equal `thickness` (a
+  through pocket); deeper is a build error naming the pocket. Pockets whose depths agree to
+  two decimals share a DXF layer.
+- **`drills`** — `[{ at: [x, y], d, depth, label? }]`: a round hole of diameter `d`.
+  Set `depth` to the thickness to drill through — deeper is a `routed-drill-depth`
+  lint error. Written as a DXF `CIRCLE`, which is what lets
+  the CAM offer a drilling toolpath instead of a profile cut.
+- **`extra`** — `[{ solid, footprint, label, method }]`: an operation the router cannot
+  do straight down — a tilted slot, a scooped thumb hold, an undercut. `solid` is cut in
+  the preview and the STEP; `footprint` (its outline on the machined face) is drawn on
+  the `SECONDARY` layer; `label` and `method` are REQUIRED and go in the README's
+  operations table so the operator knows what to make and how ("core box bit, 20 mm
+  radius"). Do not put a flat-floored pocket here to avoid stating its depth.
+- **`reference`** — the same entries as a sheet part's `score`: two points is a line,
+  anything else a shape whose boundaries are drawn. Centerlines and layout marks, on
+  the `REFERENCE` layer; they cut nothing (the preview grooves them 0.2 mm so they show).
+
+Keep these functions chainable — no branching on `isEmpty()`/`area()` — so pose-only
+sliders stay fast. `null` entries are skipped; an empty pocket region draws nothing and
+is counted by `routedEmpty`, as is an extra op whose footprint is empty.
+
+### The drawing
+
+One DXF per piece, R12, millimetres: `CUT` (colour 1) is the through cut — the outline and
+the profile's own holes; `POCKET_<depth>MM` one layer per distinct depth (colours 30, 40, 50, 20,
+10); `DRILL_D<dia>_<depth>MM` or `DRILL_D<dia>_THRU` per diameter
+and depth (colours 3, 4, 2, 140, 170); `SECONDARY` (6) the extra ops' footprints;
+`REFERENCE` (8) layout lines. Depth rides both the layer name and the colour, and colours
+are assigned per kit — pockets shallowest depth first, drills in the order they appear —
+so one layer name has one colour in every file. A palette cycles past five depths; the
+README's LAYERS legend (layer, colour, depth) is the authority. Kerf
+never applies — the CAM applies the tool offset, and the kit refuses a kerf for this
+destination. The README's ROUTER OPERATIONS table lists every pocket, drill group and
+extra op with its depth and method.
+
+### What lint and verify check
+
+Lint: `routed-drill-depth` (error) — a drill deeper than the stock at the defaults.
+Every sheet rule applies too (`sheet-thickness-literal`, `sheet-custom-build`, …); the
+laser's thickness range does not. A pocket deeper than the stock is a build error.
+
+Verify volunteers three warnings on every routed part, none counting toward
+`declared`/`evaluated`: `routedOutside` (pocket, drill or footprint regions outside the
+profile, `0`), `routedEmpty` (pockets that resolved empty, `0`), `routedPieces` (`1`).
+Each measured row carries `sheet.routed` — the operations table — beside the stock facts.
+
+### Limits
+
+- One machined face. A part worked from both faces is two routed parts or a `build`.
+- No tool-radius, dogbone or inside-corner checks: the CAM owns those.
+- No depth per extra op beyond its footprint and the solid's deepest point; the
+  `method` text is where the operator's instructions go.
+- A routed part is a sheet part of process `cnc-router` everywhere else: the sheet
+  checks' budget, stock grouping and the kit's layout apply unchanged.
+
 ## Convex hull
 
 `k.hull([a, b, …])` wraps its inputs (Shape2Ds, curve contours, or point lists) in a
@@ -3147,8 +3253,9 @@ returns instead:
   stock), `parts/<name>[-xN].svg` (one per distinct piece; identical pieces merge) and
   `print/<name>[-xN].stl` or `.3mf` (the printed parts, in their export pose). With
   `destination: "service"` each piece is a cut-only `.dxf` plus a `-marks.dxf` for its
-  score and engrave lines, and the DXF sheets are for reference. Every `options` key is
-  optional: `destination` (`"own-laser"`, the default, or `"service"`), `kerf` (0–0.5 mm,
+  score and engrave lines, and the DXF sheets are for reference. With `destination: "cnc-router"` every routed piece is one DXF carrying all its layers
+  (depth per layer), laser pieces are written as for a service, and kerf must be 0. Every `options` key is
+  optional: `destination` (`"own-laser"`, the default, `"service"` or `"cnc-router"`), `kerf` (0–0.5 mm,
   applied to the cut lines only), `stock: [{ group, size: [w, h] }]` (a row's
   `sheet.group`; a `"*"` entry sizes every group that has no entry of its own; 300 × 300
   mm when `stock` is omitted), `margin` (5 mm),
@@ -3958,6 +4065,9 @@ verify check". `no-buildable-parts` points a sub-part with a `sheet` but no `bui
 at `sheetPart()`, and `verify-unknown-process` answers `process: "laser"` the same
 way.
 
+**Routed parts** — `routed-drill-depth` (error): a `routedPart` drill deeper than
+the stock at the defaults. It carries `pattern: "routed-parts"`.
+
 A rule that itself throws yields an `internal-rule-error` **warning** and the run
 continues: `lintPart` never throws and never blocks a part because of a linter bug.
 

package/docs/KERNEL-CONTRACT.md

@@ -765,13 +765,15 @@ the helpers come along unmodified. (`test/kernel-contract.test.js` asserts every
   `arcTo` / `cubicTo` / `close`); cubic segments become exact B-rep on OCCT and
   facet at mesh LOD on Manifold.
 - **Sheet parts** — `sheetPart` wraps a laser-cut piece into an ordinary sub-part
-  (a generated `build` and `place` plus a plain-data `sheet` declaration); the
+  (a generated `build` and `place` plus a plain-data `sheet` declaration), and
+  `routedPart` is the same wrapper for a CNC-routed piece (process `cnc-router`); the
   joinery helpers `fingers`, `tabs`, `tSlots`, `sheetPanel`, `matchingSlots`,
   `fingerBox`, `printedTab`, `sheetHole` and the `JOINERY_SCREWS` table are pure
   functions returning plain data in this contract's input format; `sheetToWorld` /
   `worldToSheet` convert between a posed sheet's drawing and world coordinates. The
   generated build calls only ops from the tables above (`shape2d`, `extrude`,
-  `offset`, `cut`, `cutAll`, `translate`, `rotate`), so a sheet part is portable by
+  `offset`, `cut`, `cutAll`, `translate`, `rotate`, plus `cylinder` for a routed part's
+  drills), so a sheet part is portable by
   construction too. None of these is a kernel op.
 
 **Profile validation on the way in** (0.112). `prism`, `extrude`, `revolve`, `sweep`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.150.1",
+  "version": "0.151.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/export/bundle.js

@@ -19,7 +19,7 @@ import { resolveSheet } from "../sheet/resolve.js";
 import { processById, SHEET_METRICS } from "../process/registry.js";
 import { loadExporter } from "../process/exporters.js";
 import { validateKitOptions, resolveStock, KIT_OPTIONS_ERROR, KIT_LIMITS } from "./formats.js";
-import { canonicalDrawingKey } from "./drawing.js";
+import { canonicalDrawingKey, routedPalette } from "./drawing.js";
 import { renderSvg } from "./svg.js";
 import { renderDxf } from "./dxf.js";
 import { layoutGroup, marginFitsStock } from "./layout.js";
@@ -140,7 +140,6 @@ const wordsOf = (s) => String(s ?? "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").re
 // are listed, and "display", "outfit" and "profit" are not.
 const CLEARANCE_WORDS = new Set(["clearance", "clearances", "fit", "play"]);
 const isClearance = (c) => [...wordsOf(c.key), ...wordsOf(c.label)].some((w) => CLEARANCE_WORDS.has(w));
-const ALL_LAYERS = ["cut", "score", "engrave"];
 
 // Every control that owns a parameter key, whatever the section shape: authored
 // `controls` (groups nest), and the legacy `advanced`, `toggles`, `features` and a
@@ -193,6 +192,29 @@ function sheetMetaOrThrow(kernel, sp, p, d, name) {
   throw new Error(`sheet part "${name}": its material or thickness could not be evaluated`);
 }
 
+// The README's layer legend: every routed layer name in the kit, once, with its colour
+// (ACI in a DXF kit, hex in an SVG one) and depth — REFERENCE, SECONDARY, then drills in
+// palette order, then pockets shallowest first. The palette is kit-wide, so a name has
+// one colour; the legend is the authority when a palette cycles.
+const LEGEND_RANK = { reference: 0, secondary: 1, drill: 2, pocket: 3 };
+const legendKind = (l) => (l.id.startsWith("drill-") ? "drill" : l.id.startsWith("pocket-") ? "pocket" : l.id);
+function routedLegend(pieces, cutExt) {
+  const rows = new Map();
+  for (const pc of pieces) {
+    for (const l of pc.drawing.layers) {
+      if (l.name === undefined || rows.has(l.name)) continue;
+      const kind = legendKind(l);
+      rows.set(l.name, { name: l.name, kind, order: rows.size,
+        colour: cutExt === "svg" ? l.svgColor : String(l.color),
+        depth: l.through ? "through" : typeof l.depth === "number" ? `${l.depth.toFixed(2)} mm` : "—", mm: l.depth ?? 0 });
+    }
+  }
+  return [...rows.values()]
+    .sort((a, b) => (LEGEND_RANK[a.kind] ?? 9) - (LEGEND_RANK[b.kind] ?? 9)
+      || (a.kind === "pocket" ? a.mm - b.mm : 0) || a.order - b.order)
+    .map(({ name, colour, depth }) => ({ name, colour, depth }));
+}
+
 // One export-bundle job's kit. `names` is the job's selected() — exportable, enabled, in
 // definition order — and `posed`/`label`/`exportName` are jobs.js's own, so a kit's
 // printed parts are built exactly the way the STL and 3MF exports build them.
@@ -201,7 +223,8 @@ export async function buildBundle({ kernel, part, msg, p, d, posed, label, expor
   // not wait behind a build (spec D.3). An absent options object means every default.
   const o = validateKitOptions(msg.options ?? {});
   const service = o.destination === "service";
-  const cutExt = service ? "dxf" : "svg";
+  const router = o.destination === "cnc-router";
+  const cutExt = o.cutFormat;                       // svg for own-laser, dxf otherwise
   const say = (phase) => onProgress(clipPhase(phase));
   const nameOf = (name) => cleanLabel(label(name));
   if (names.length === 0) throw new Error("no exportable parts selected");
@@ -240,23 +263,36 @@ export async function buildBundle({ kernel, part, msg, p, d, posed, label, expor
 
   // Draw every sheet part flat, from its 2-D declaration, with its 2-D facts under ONE
   // budget for the whole kit.
+  // Resolved first, drawn second: a routed layer's colour comes from a palette over
+  // EVERY routed piece's depths (drawing.js routedPalette), so one depth is one colour
+  // in every file of the kit and on every sheet.
   const deadline = Date.now() + SHEET_CHECK_BUDGET_MS;
-  const drawn = [];
+  const resolved = [];
   for (const name of sheetNames) {
     say(`building ${nameOf(name)}`);
     const s = resolveSheet(kernel, part.parts[name], p, d);
     const desc = processById(s.process);
     if (!desc) throw new Error(`sheet part "${nameOf(name)}": unknown process "${s.process}"`);
-    const facts = desc.facts(s, { deadline });
+    resolved.push({ name, s, facts: desc.facts(s, { deadline }) });
+  }
+  const palette = routedPalette(resolved.filter((x) => x.s.process === "cnc-router").map((x) => x.s));
+  const drawn = [];
+  for (const { name, s, facts } of resolved) {
     const exporter = await loadExporter(s.process);
-    const drawing = exporter.drawing(s, o, kernel, { label: nameOf(name), facts });
+    const drawing = exporter.drawing(s, o, kernel, { label: nameOf(name), facts, palette });
+    // A routed piece is known by its process, never guessed from its layers: one with
+    // only a profile draws no named layer and is still routed.
     drawn.push({ name, label: nameOf(name), fileKey: exportName(name), group: groupOf.get(name),
-      drawing, facts, key: canonicalDrawingKey(drawing) });
+      drawing, facts, key: canonicalDrawingKey(drawing), routed: s.process === "cnc-router" });
   }
 
   // Identical pieces become one file ×N (spec D.4): the hash nominates; the canonical
   // drawing and the stock group confirm.
-  const pieces = dedupe(drawn, (x) => h(x.key), (a, b) => a.key === b.key && a.group === b.group)
+  // A routed piece's operations table is confirmed too: an extra op's depth and method,
+  // and the op labels, are not in its drawing — only the README carries them, so two
+  // pieces that draw alike but machine differently must stay two files.
+  const sameOps = (a, b) => JSON.stringify(a.facts?.routed ?? null) === JSON.stringify(b.facts?.routed ?? null);
+  const pieces = dedupe(drawn, (x) => h(x.key), (a, b) => a.key === b.key && a.group === b.group && sameOps(a, b))
     .map(({ item, members }) => ({
       ...item, labels: members.map((m) => m.label), qty: members.length * o.sets,
       hasMarks: item.drawing.layers.some((l) => l.id === "score" || l.id === "engrave"),
@@ -283,7 +319,8 @@ export async function buildBundle({ kernel, part, msg, p, d, posed, label, expor
   };
   for (const pc of pieces) {
     const sx = pc.qty > 1 ? `-x${pc.qty}` : "";
-    const marks = service && pc.hasMarks;
+    // A routed piece is never split: its depths are one layered file for the CAM.
+    const marks = (service || router) && pc.hasMarks && !pc.routed;
     const name = claim(kitName(pc.fileKey),
       (n) => [`parts/${n}${sx}.${cutExt}`, ...(marks ? [`parts/${n}${sx}-marks.dxf`] : []), `parts/${n}/`], pc.labels);
     pc.file = `parts/${name}${sx}.${cutExt}`;
@@ -301,7 +338,7 @@ export async function buildBundle({ kernel, part, msg, p, d, posed, label, expor
     say(`laying out ${g.material} ${fmtMm(g.thickness)} mm (${count} pieces)`);
     const stock = stockFor.get(g.group);
     const laid = layoutGroup({
-      group: g.group, label: g.label, stock, margin: o.margin, spacing: o.spacing, strict: !service,
+      group: g.group, label: g.label, stock, margin: o.margin, spacing: o.spacing, strict: !(service || router),
       pieces: inGroup.map((pc) => ({ key: pc.file, label: pc.labels[0], drawing: pc.drawing, qty: pc.qty })),
     });
     if (laid.sheets.length > KIT_LIMITS.sheetsPerGroup) {
@@ -354,20 +391,23 @@ export async function buildBundle({ kernel, part, msg, p, d, posed, label, expor
     if (!pp.bytes) pp.bytes = new Uint8Array(meshTo3MF([{ name: pp.fileKey, ...pp.mesh, color: pp.color }]));
   }
 
-  // The files (spec D.8): own laser — an SVG per sheet and per piece; service — a
-  // cut-only DXF per piece, a -marks.dxf where it has marks, and reference DXF sheets.
+  // The files (spec D.8): own laser — an SVG per sheet and per piece; service and CNC
+  // router — a cut-only DXF per laser piece, a -marks.dxf where it has marks, and
+  // reference DXF sheets. A routed piece is one file with every layer, whatever the
+  // destination.
   say("writing cut files");
   const title = cleanLabel(part.meta?.title ?? fileBase);
   const files = [];
   const put = (file, text) => files.push({ file, data: strToU8(text) });
   for (const sh of sheets) {
     const doc = { title: `${title} — ${sh.group.label} — sheet ${sh.index} of ${sh.count}`, size: sh.stock, placements: sh.placements };
-    put(sh.file, service ? renderDxf(doc, { include: ALL_LAYERS }) : renderSvg(doc));
+    put(sh.file, cutExt === "dxf" ? renderDxf(doc) : renderSvg(doc));
   }
   for (const pc of pieces) {
     const doc = { title: pc.labels.join(", "), size: sizeOf(pc.drawing.bounds),
       placements: [{ drawing: pc.drawing, at: [0, 0], rotated: false }] };
-    if (!service) { put(pc.file, renderSvg(doc)); continue; }
+    if (cutExt === "svg") { put(pc.file, renderSvg(doc)); continue; }
+    if (pc.routed) { put(pc.file, renderDxf(doc)); continue; }       // every layer, one file
     put(pc.file, renderDxf(doc, { include: ["cut"] }));
     if (pc.marksFile) put(pc.marksFile, renderDxf(doc, { include: ["score", "engrave"] }));
   }
@@ -383,6 +423,9 @@ export async function buildBundle({ kernel, part, msg, p, d, posed, label, expor
       size: sh.stock, pieces: sh.placements.length, used: sh.used })),
     pieces: pieces.map((pc) => ({ file: pc.file, marksFile: pc.marksFile, labels: pc.labels, material: groups.get(pc.group).material,
       thickness: groups.get(pc.group).thickness, size: pc.drawing.nominal, quantity: pc.qty })),
+    router: pieces.filter((pc) => pc.routed && pc.facts?.routed).map((pc) => ({
+      labels: pc.labels, material: groups.get(pc.group).material, thickness: groups.get(pc.group).thickness, ...pc.facts.routed })),
+    layers: routedLegend(pieces.filter((pc) => pc.routed), cutExt),
     printed: prints.map((pp) => ({ file: pp.file, labels: pp.labels, quantity: pp.qty })),
     clearances: controls.filter(isClearance)
       .map((c) => ({ label: c.label ?? c.key, value: p[c.key], unit: c.unit ?? "" })),

package/src/framework/export/drawing.js

@@ -354,3 +354,41 @@ export function applyKerf(regions, kerf, { label = "sheet part", gap = null } =
   if (arcCount(out) < arcCount(regions)) throw new Error(intact);
   return out;
 }
+
+// ── routed layers (process/cnc-router) ────────────────────────────────────────
+// Depth in millimetres as a layer-name token: up to two decimals, trailing zeros
+// dropped (11.43 → "11.43", 3 → "3"). Two depths that round alike share a layer.
+export const depthToken = (mm) => String(Number(mm.toFixed(2)));
+export function routedLayerName(kind, op) {
+  if (kind === "pocket") return `POCKET_${depthToken(op.depth)}MM`;
+  if (kind === "drill") return op.through ? `DRILL_D${depthToken(op.d)}_THRU` : `DRILL_D${depthToken(op.d)}_${depthToken(op.depth)}MM`;
+  throw new Error(`routedLayerName: unknown kind ${JSON.stringify(kind)}`);
+}
+// A drill's tool setting as a key: diameter and depth (or THRU), two-decimal tokens —
+// one layer per key, and the kit-wide palette's drill key.
+export const drillKey = (dr) => `D${depthToken(dr.d)}-${dr.through ? "THRU" : depthToken(dr.depth)}`;
+// Palettes: ACI colours for DXF, hex for SVG. Drills cycle; pockets are assigned by
+// ascending depth (shallowest first). In a kit the assignment is kit-wide
+// (routedPalette), so one depth is one colour in every file.
+export const ROUTED_COLORS = Object.freeze({
+  reference: { color: 8, svgColor: "#808080" },
+  secondary: { color: 6, svgColor: "#FF00FF" },
+  drill: Object.freeze([{ color: 3, svgColor: "#00AA00" }, { color: 4, svgColor: "#00AAAA" }, { color: 2, svgColor: "#AAAA00" }, { color: 140, svgColor: "#0055AA" }, { color: 170, svgColor: "#5500AA" }]),
+  pocket: Object.freeze([{ color: 30, svgColor: "#E07000" }, { color: 40, svgColor: "#E0A000" }, { color: 50, svgColor: "#C0C000" }, { color: 20, svgColor: "#A06000" }, { color: 10, svgColor: "#804000" }]),
+});
+
+// The kit-wide palette over every routed piece's resolved operations, so a layer name
+// carries one colour in every file of the kit: pocket depth tokens ranked ascending
+// (shallowest first), drill keys in first-seen order, each cycling its palette.
+// `sheets` are resolved routed sheets, in definition order.
+export function routedPalette(sheets) {
+  const pocketTokens = new Set(), drillKeys = new Set();
+  for (const s of sheets) {
+    for (const pk of s.routed.pockets) if (!pk.region.isEmpty()) pocketTokens.add(depthToken(pk.depth));
+    for (const dr of s.routed.drills) drillKeys.add(drillKey(dr));
+  }
+  const pocket = new Map([...pocketTokens].sort((a, b) => Number(a) - Number(b))
+    .map((tok, i) => [tok, ROUTED_COLORS.pocket[i % ROUTED_COLORS.pocket.length]]));
+  const drill = new Map([...drillKeys].map((key, i) => [key, ROUTED_COLORS.drill[i % ROUTED_COLORS.drill.length]]));
+  return { pocket, drill };
+}

package/src/framework/export/dxf.js

@@ -111,13 +111,50 @@ function writeEntity(g, layer, path, place) {
 }
 
 // `include` picks the layers: a cutting service gets one cut-only file per piece and a
-// separate marks file (["score", "engrave"]). Only the included layers are declared.
-export function renderDxf(doc, { include = INCLUDES } = {}) {
-  for (const inc of include)
+// separate marks file (["score", "engrave"]). Only the written layers are declared.
+// A layer carrying its own `name` (a routed layer) is written under that name and
+// colour; one without is a laser layer under LAYER_FOR/DXF_LAYERS. `include`
+// undefined writes every layer; a list writes only the named laser classes, so a
+// cutting service's cut-only and marks files never carry a routed layer by accident.
+const NAME_RE = /^[A-Z0-9_.]{1,31}$/;
+function layerNameOf(layer) {
+  if (layer.name === undefined) return LAYER_FOR[layer.id];
+  if (!NAME_RE.test(layer.name) || !Number.isInteger(layer.color)) throw new Error(`renderDxf: layer ${JSON.stringify(layer.id)} needs a DXF name (A-Z, 0-9, _ .) and an integer colour`);
+  return layer.name;
+}
+
+export function renderDxf(doc, { include } = {}) {
+  const all = include === undefined;
+  for (const inc of include ?? [])
     if (!INCLUDES.includes(inc)) throw new Error(`renderDxf: include lists "cut", "score" and "engrave" only, got ${JSON.stringify(inc)}`);
-  const want = new Set(include);
-  const ids = ORDER.filter((id) => want.has(INCLUDE_FOR[id]));
-  const names = [...new Set(ids.map((id) => LAYER_FOR[id]))];
+  const want = new Set(include ?? INCLUDES);
+  const selected = (layer) => (layer.name !== undefined ? all : want.has(INCLUDE_FOR[layer.id]));
+  // Entity order: engrave, score, every custom layer in first-seen order across the
+  // placements, then cut-inner and cut-outer — a routed piece's holes and pockets are
+  // milled while the sheet still holds it, and the outline frees it last.
+  const custom = [];
+  for (const placement of doc.placements) for (const layer of placement.drawing.layers)
+    if (layer.name !== undefined && selected(layer) && !custom.includes(layer.id)) custom.push(layer.id);
+  const ids = [...ORDER.filter((id) => !id.startsWith("cut") && want.has(INCLUDE_FOR[id])), ...custom, ...ORDER.filter((id) => id.startsWith("cut") && want.has(INCLUDE_FOR[id]))];
+  // The LAYER table, in the entity order. A laser-only document (no named layer written)
+  // declares every INCLUDED laser class whether or not a placement draws on it — the
+  // laser writer's bytes, unchanged. A document with a named (routed) layer declares
+  // only the layers actually present, laser classes included, so a router file carries
+  // no empty ENGRAVE/SCORE rows.
+  const present = (id) => doc.placements.some((pl) => pl.drawing.layers.some((l) => l.id === id));
+  const onlyPresent = custom.length > 0;
+  const names = [], colors = new Map();
+  const declare = (name, color) => { if (!names.includes(name)) { names.push(name); colors.set(name, color); } };
+  for (const id of ids) {
+    if (LAYER_FOR[id] !== undefined) {
+      if (!onlyPresent || present(id)) declare(LAYER_FOR[id], DXF_LAYERS[LAYER_FOR[id]]);
+      continue;
+    }
+    for (const placement of doc.placements) {
+      const layer = placement.drawing.layers.find((l) => l.id === id);
+      if (layer) declare(layerNameOf(layer), layer.color);
+    }
+  }
   const out = [];
   const g = (code, value) => { out.push(String(code).padStart(3), String(value)); };
 
@@ -131,7 +168,7 @@ export function renderDxf(doc, { include = INCLUDES } = {}) {
   g(0, "LTYPE"); g(2, "CONTINUOUS"); g(70, 0); g(3, "Solid line"); g(72, 65); g(73, 0); g(40, "0.0");
   g(0, "ENDTAB");
   g(0, "TABLE"); g(2, "LAYER"); g(70, names.length);
-  for (const name of names) { g(0, "LAYER"); g(2, name); g(70, 0); g(62, DXF_LAYERS[name]); g(6, "CONTINUOUS"); }
+  for (const name of names) { g(0, "LAYER"); g(2, name); g(70, 0); g(62, colors.get(name)); g(6, "CONTINUOUS"); }
   g(0, "ENDTAB");
   g(0, "ENDSEC");
 
@@ -141,7 +178,7 @@ export function renderDxf(doc, { include = INCLUDES } = {}) {
       const layer = placement.drawing.layers.find((l) => l.id === id);
       if (!layer) continue;
       const place = placer(placement);
-      for (const path of layer.paths) writeEntity(g, LAYER_FOR[id], path, place);
+      for (const path of layer.paths) writeEntity(g, layerNameOf(layer), path, place);
     }
   }
   g(0, "ENDSEC");

package/src/framework/export/formats.js

@@ -21,9 +21,10 @@ export const EXPORT_FORMATS = Object.freeze([
   Object.freeze({ id: "bundle", label: "Cut and print kit", ext: "zip", mime: "application/zip", needsSheet: true }),
 ]);
 
-// Destination → the cut-file format it writes. Pinned equal to the laser descriptor's
-// `destinations` by test/kit-formats.test.js — two spellings of one fact.
-export const DESTINATIONS = Object.freeze({ "own-laser": "svg", service: "dxf" });
+// Destination → the cut-file format it writes. Pinned equal to the union of every
+// process descriptor's `destinations` by test/routed-kit.test.js and
+// test/kit-formats.test.js — one fact, two spellings.
+export const DESTINATIONS = Object.freeze({ "own-laser": "svg", service: "dxf", "cnc-router": "dxf" });
 
 // 300 × 300 mm until the paying user's machine is known (design spec decision 12).
 export const DEFAULT_STOCK_SIZE = Object.freeze([300, 300]);
@@ -64,7 +65,7 @@ export function validateKitOptions(o) {
 
   const destination = pick("destination");
   if (typeof destination !== "string" || !Object.hasOwn(DESTINATIONS, destination))
-    throw fail(`destination must be "own-laser" or "service", got ${JSON.stringify(destination)}`);
+    throw fail(`destination must be "own-laser", "service" or "cnc-router", got ${JSON.stringify(destination)}`);
   const cutFormat = DESTINATIONS[destination];
   if (opts.cutFormat !== undefined && opts.cutFormat !== cutFormat)
     throw fail(`cutFormat ${JSON.stringify(opts.cutFormat)} does not match destination "${destination}" (which writes ${cutFormat})`);
@@ -72,6 +73,8 @@ export function validateKitOptions(o) {
   const kerf = pick("kerf");
   if (!inRange(kerf, KIT_LIMITS.kerf))
     throw fail(`kerf must be a number from ${KIT_LIMITS.kerf[0]} to ${KIT_LIMITS.kerf[1]} mm, got ${JSON.stringify(kerf)}`);
+  if (destination === "cnc-router" && kerf > 0)
+    throw fail("kerf does not apply to a CNC router — the CAM applies the tool offset; set kerf to 0");
   const colors = pick("colors");
   if (colors !== "lightburn") throw fail(`colors must be "lightburn", got ${JSON.stringify(colors)}`);
   const stock = normalizeStock(opts.stock);

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,
   };