partforge 0.155.0 → 0.157.0

package/docs/AUTHORING-PARTS.md

@@ -2037,7 +2037,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"`, `"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:`.
+Sheet parts download as one ZIP, the **cut & print kit** (`format: "bundle"`): `README.txt`, `parts.csv`, laid-out `sheets/`, a `parts/` file per distinct piece (plus `-marks.dxf` for a cutting service), `print/` for printed parts. Identical pieces share one `-xN` file named from `export: { name }`, else the key. Destination (`"own-laser"`, `"service"`, `"cnc-router"`), kerf, stock size and a two-sided routed piece's flip and file count are chosen at download: draw nominal, bind `thickness` to the measured control. A choice it cannot honour fails with `cut kit options:`.
 
 ### Limits
 
@@ -2179,8 +2179,8 @@ 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
+When it is machined from one or both faces of a flat board: an outline, pockets with
+flat floors, holes, all straight down from whichever face. A sculpted surface or
 anything that is not flat stock is an ordinary `build` (export it as STEP). A laser-cut
 plate is `sheetPart`.
 
@@ -2197,8 +2197,12 @@ plinth: routedPart({
   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" },
+    { region: k.shape2d(roundedRectProfile(40, 20, 3)).translate([60, 0]), depth: 4, face: "far", label: "felt recess" },
+  ],
+  drills: (p, d) => [
+    ...d.pegHoles.map(([x, y]) => ({ at: [x, y], d: p.pegHoleDia, depth: 10 })),
+    { at: [-60, 30], d: 8, depth: 6, face: "far", label: "foot socket" },   // from the underside
   ],
-  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]),
@@ -2213,21 +2217,22 @@ plinth: routedPart({
 `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.
+near face at z = `thickness` and the far face at z = 0; `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
+- **`pockets`** — `[{ region, depth, label?, face? }]`: a Shape2D or profile machined
+  `depth` mm into the stock from its 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`.
+- **`drills`** — `[{ at: [x, y], d, depth, label?, face? }]`: 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
+- **`extra`** — `[{ solid, footprint, label, method, face? }]`: 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 its 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.
@@ -2248,10 +2253,27 @@ 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
+README's LAYERS legend (layer, face, 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.
+extra op with its face, depth and method.
+
+### Both faces
+
+Every pocket, drill and extra op takes `face`: `"near"` (the default, machined down
+from z = `thickness`) or `"far"` (machined up from z = 0 — the board turned over); any
+other value is a build error. `depth` is measured from the op's own face. Model the part
+in place, as assembled; the kit does the flipping. Far ops go on their own layers —
+`FAR_POCKET_<depth>MM`, `FAR_DRILL_D<dia>_…`, `FAR_SECONDARY` — mirrored about the
+piece's centre so they read as the router sees the far face. Two kit options apply to a
+piece with far work: `flip` — `"left-right"` (the default, VCarve's Flip Direction =
+Horizontal) or `"end-over-end"` (Vertical) — sets the mirror axis; `twoSided` —
+`"one-file"` (the default: both faces' layers in the piece's one DXF) or `"two-files"`
+(the far layers in `parts/<name>-far.dxf`, behind the mirrored outline on `REFERENCE`
+for alignment). In the CAM, line the far vectors' outline up on the piece's outline as
+seen from the bottom; the README says so and orders the work far side first, through
+cut last. `routedBreakthrough` counts a near and a far pocket that overlap and together
+go deeper than the stock.
 
 ### What lint and verify check
 
@@ -2259,14 +2281,17 @@ Lint: `routed-drill-depth` (error) — a drill deeper than the stock at the defa
 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
+Verify volunteers four 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`).
+profile, `0`), `routedEmpty` (pockets that resolved empty, `0`), `routedPieces` (`1`),
+`routedBreakthrough` (a near-face and a far-face pocket that overlap and together go
+deeper than the stock, `0`).
 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`.
+- Far-side `reference` lines and far-side work in the sheets/ layouts are not drawn;
+  two-sided jobs are per-piece files.
 - 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.
@@ -3937,7 +3962,21 @@ shares build's `(k, p, d)` contract — against a geometry-free probe —
 `unknown-kernel-op`, `unknown-solid-op`, `invalid-op-options`, `build-throws`,
 `probe-throws`, `derive-throws`, `manifold-backend-uses-occt-op`,
 `build-runaway` (errors); `nondeterministic-build` (warning, from diffing two
-probe runs).
+probe runs). The probe has no geometry, so every **query** answers with a
+placeholder — `boundingBox()` a unit box, `area()` and `volume()` 1,
+`Shape2D.contains()` always `false`, `corners()`/`toRegions()` a unit square,
+`isEmpty()` `false`. A `build()` that throws *after* reading one of those may
+only have believed the placeholder — a helper that scans `contains()` to place
+ribs finds none and throws its own guard — so that throw is reported as a
+`build-throws` **note** naming the queries it read ("could not be evaluated
+geometry-free"), never an error: it does not block loading, `measure`, or
+`--strict`. A throw with no query read before it is the build's own logic and
+stays an error. Lint cannot tell which throws depended on the placeholder, so any
+throw after a query is a note; a real fault still surfaces when the real build
+runs. The ops the build would have called after the throw were never run, so lint
+did not check them (unknown ops, option keys, the Manifold pin, determinism). A
+declared probe that throws stays a `probe-throws` error whatever it read — at
+runtime a throwing probe only degrades quietly to `{ error }`.
 
 **Verify block** — `verify-unknown-metric`, `verify-unknown-subpart`,
 `verify-bad-expr`, `verify-bad-pair-check`, `verify-unknown-process`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.155.0",
+  "version": "0.157.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,15 +19,17 @@ 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, routedPalette } from "./drawing.js";
+import { canonicalDrawingKey, routedPalette, splitFaces } from "./drawing.js";
 import { renderSvg } from "./svg.js";
 import { renderDxf } from "./dxf.js";
 import { layoutGroup, marginFitsStock } from "./layout.js";
 import { renderReadme, renderPartsCsv, cleanLabel } from "./readme.js";
 
 // Every entry name the kit may write (spec D.10). test/kit-bundle.test.js pins every
-// kit it builds against it, and buildBundle asserts it again before zipping.
-export const KIT_ENTRY_RE = /^(README\.txt|parts\.csv|sheets\/[a-z0-9][a-z0-9._-]*\/sheet-\d+-of-\d+\.(svg|dxf)|parts\/[a-z0-9][a-z0-9._-]*(-x\d+)?(-marks)?\.(svg|dxf)|print\/[a-z0-9][a-z0-9._-]*(-x\d+)?\.(stl|3mf))$/;
+// kit it builds against it, and buildBundle asserts it again before zipping. A piece's
+// files are `<name>[-x<n>]` plus `-far` (a two-sided routed piece's far-face file, in
+// the two-files mode) or `-marks` (a laser piece's score and engrave lines).
+export const KIT_ENTRY_RE = /^(README\.txt|parts\.csv|sheets\/[a-z0-9][a-z0-9._-]*\/sheet-\d+-of-\d+\.(svg|dxf)|parts\/[a-z0-9][a-z0-9._-]*(-x\d+)?(-far)?(-marks)?\.(svg|dxf)|print\/[a-z0-9][a-z0-9._-]*(-x\d+)?\.(stl|3mf))$/;
 
 // A path segment from an author string. safeName already lowercases, collapses runs and
 // refuses a leading dot or dash; folding every run of dots on top means no entry name
@@ -192,27 +194,32 @@ 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);
+// The README's layer legend: every routed layer name in the kit, once, with its face,
+// 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 far face's layers follow
+// in the same order. The palette is kit-wide, so a name has one colour; the legend is
+// the authority when a palette cycles. It reads each piece's whole drawing, so the
+// far file's alignment outline (splitFaces' `far-outline`) is never listed.
+const LEGEND_RANK = { reference: 0, secondary: 1, drill: 2, pocket: 3, "far-secondary": 4, "far-drill": 5, "far-pocket": 6 };
+const legendKind = (l) => {
+  const m = /^(far-)?(drill|pocket)-/.exec(l.id);
+  return m ? `${m[1] ?? ""}${m[2]}` : 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,
+      rows.set(l.name, { name: l.name, kind, face: l.face === "far" ? "far" : "near", 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 }));
+      || (a.kind.endsWith("pocket") ? a.mm - b.mm : 0) || a.order - b.order)
+    .map(({ name, face, colour, depth }) => ({ name, face, colour, depth }));
 }
 
 // One export-bundle job's kit. `names` is the job's selected() — exportable, enabled, in
@@ -292,11 +299,14 @@ export async function buildBundle({ kernel, part, msg, p, d, posed, label, expor
   // 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);
+  // A routed piece with far-face work is two-sided: its sheets carry the near face only
+  // (`faces.near`), and the two-files mode writes its far face to a file of its own.
   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"),
-    }));
+    .map(({ item, members }) => {
+      const faces = splitFaces(item.drawing);
+      return { ...item, labels: members.map((m) => m.label), qty: members.length * o.sets, faces, twoSided: faces.far !== null,
+        hasMarks: item.drawing.layers.some((l) => l.id === "score" || l.id === "engrave") };
+    });
 
   // Names, in definition order. A name that was taken moves to name-2; the README's
   // RENAMED FILES says which file it was and who held the name (spec D.10). A piece
@@ -321,10 +331,12 @@ export async function buildBundle({ kernel, part, msg, p, d, posed, label, expor
     const sx = pc.qty > 1 ? `-x${pc.qty}` : "";
     // 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);
+    const far = pc.twoSided && o.twoSided === "two-files";
+    const name = claim(kitName(pc.fileKey), (n) => [`parts/${n}${sx}.${cutExt}`, ...(marks ? [`parts/${n}${sx}-marks.dxf`] : []),
+      ...(far ? [`parts/${n}${sx}-far.${cutExt}`] : []), `parts/${n}/`], pc.labels);
     pc.file = `parts/${name}${sx}.${cutExt}`;
     pc.marksFile = marks ? `parts/${name}${sx}-marks.dxf` : null;
+    pc.farFile = far ? `parts/${name}${sx}-far.${cutExt}` : null;
   }
 
   // Lay out each stock group. An own laser needs every piece to fit (layoutGroup
@@ -339,7 +351,7 @@ export async function buildBundle({ kernel, part, msg, p, d, posed, label, expor
     const stock = stockFor.get(g.group);
     const laid = layoutGroup({
       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 })),
+      pieces: inGroup.map((pc) => ({ key: pc.file, label: pc.labels[0], drawing: pc.faces.near, qty: pc.qty })),
     });
     if (laid.sheets.length > KIT_LIMITS.sheetsPerGroup) {
       throw new Error(`${KIT_OPTIONS_ERROR} ${g.material} ${fmtMm(g.thickness)} mm needs ${laid.sheets.length} sheets — at most ${KIT_LIMITS.sheetsPerGroup} per material; use larger stock or fewer sets`);
@@ -394,7 +406,8 @@ export async function buildBundle({ kernel, part, msg, p, d, posed, label, expor
   // 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.
+  // destination — or, two-sided in the two-files mode, its near face and its far face
+  // (behind a REFERENCE outline) as two.
   say("writing cut files");
   const title = cleanLabel(part.meta?.title ?? fileBase);
   const files = [];
@@ -404,8 +417,11 @@ export async function buildBundle({ kernel, part, msg, p, d, posed, label, expor
     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 }] };
+    const docOf = (drawing) => ({ title: pc.labels.join(", "), size: sizeOf(drawing.bounds),
+      placements: [{ drawing, at: [0, 0], rotated: false }] });
+    const render = cutExt === "svg" ? renderSvg : renderDxf;
+    if (pc.farFile) { put(pc.file, render(docOf(pc.faces.near))); put(pc.farFile, render(docOf(pc.faces.far))); continue; }
+    const doc = docOf(pc.drawing);
     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"] }));
@@ -416,15 +432,17 @@ export async function buildBundle({ kernel, part, msg, p, d, posed, label, expor
   const controls = collectControls(part.parameters);
   const readme = renderReadme({
     title, destination: o.destination, cutFormat: o.cutFormat, kerf: o.kerf,
+    flip: o.flip, twoSided: o.twoSided, anyTwoSided: pieces.some((pc) => pc.twoSided),
     stockNotes: [...groups.values()].map((g) => ({ material: g.material, thickness: g.thickness,
       control: thicknessControlLabel(controls, part.parts[g.first], p, d) })),
     scale: pieces.map((pc) => ({ label: pc.labels.join(", "), nominal: pc.drawing.nominal, drawn: sizeOf(pc.drawing.bounds) })),
     sheets: sheets.map((sh) => ({ file: sh.file, material: sh.group.material, thickness: sh.group.thickness,
       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,
+    pieces: pieces.map((pc) => ({ file: pc.file, marksFile: pc.marksFile, farFile: pc.farFile, 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 })),
+      labels: pc.labels, material: groups.get(pc.group).material, thickness: groups.get(pc.group).thickness, ...pc.facts.routed,
+      twoSided: pc.twoSided, farFile: pc.farFile })),
     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)
@@ -434,8 +452,11 @@ export async function buildBundle({ kernel, part, msg, p, d, posed, label, expor
     oversized, renamed,
   });
   const csv = renderPartsCsv([
-    ...pieces.map((pc) => ({ file: pc.file, kind: "sheet", labels: pc.labels, material: groups.get(pc.group).material,
-      thickness: groups.get(pc.group).thickness, width: pc.drawing.nominal[0], height: pc.drawing.nominal[1], quantity: pc.qty })),
+    ...pieces.flatMap((pc) => {
+      const row = { file: pc.file, kind: "sheet", labels: pc.labels, material: groups.get(pc.group).material,
+        thickness: groups.get(pc.group).thickness, width: pc.drawing.nominal[0], height: pc.drawing.nominal[1], quantity: pc.qty };
+      return pc.farFile ? [row, { ...row, file: pc.farFile, kind: "far" }] : [row];
+    }),
     ...prints.map((pp) => ({ file: pp.file, kind: "print", labels: pp.labels, material: pp.material, thickness: null,
       width: pp.size[0], height: pp.size[1], quantity: pp.qty })),
   ]);

package/src/framework/export/drawing.js

@@ -359,11 +359,44 @@ export function applyKerf(regions, kerf, { label = "sheet part", gap = null } =
 // 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)));
+// A far-face op's layer carries a FAR_ prefix; near names are unchanged.
 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`;
+  const far = op.face === "far" ? "FAR_" : "";
+  if (kind === "pocket") return `${far}POCKET_${depthToken(op.depth)}MM`;
+  if (kind === "drill") return far + (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)}`);
 }
+// How a piece is turned over to cut its far face, as the mirror axis of its drawing.
+export const FLIP_AXIS = Object.freeze({ "left-right": "x", "end-over-end": "y" });
+// A ring mirrored about the line `axis = c` ("x": x -> 2c - x; "y": y -> 2c - y), every
+// point mapped (start, to, via, c1, c2), then walked backwards so a CCW ring stays CCW:
+// an arc keeps its mirrored via, a cubic swaps its mirrored c1/c2. Other fields (closed)
+// carry over. Returns a new ring; the input is not touched.
+export function mirrorRing(ring, axis, c) {
+  const m = axis === "x" ? ([x, y]) => [2 * c - x, y] : ([x, y]) => [x, 2 * c - y];
+  const pts = [ring.start, ...ring.segments.map((s) => s.to)].map(m);
+  const segments = [];
+  for (let i = ring.segments.length - 1; i >= 0; i--) {
+    const s = ring.segments[i], to = pts[i];
+    if (s.via) segments.push({ to, via: m(s.via) });
+    else if (s.c1) segments.push({ to, c1: m(s.c2), c2: m(s.c1) });
+    else segments.push({ to });
+  }
+  return { ...ring, start: pts[pts.length - 1], segments };
+}
+export const mirrorRings = (rings, axis, c) => rings.map((r) => mirrorRing(r, axis, c));
+// A two-sided piece's drawing split by face. `near` keeps every layer not marked
+// face "far" (the input itself for a one-sided piece); `far` is null for a one-sided
+// piece, else the far layers behind a REFERENCE layer of `drawing.farOutline` (the
+// mirrored outer rings the exporter sets), both with the input's bounds/nominal/kerf.
+export function splitFaces(drawing) {
+  const farLayers = drawing.layers.filter((l) => l.face === "far");
+  if (farLayers.length === 0) return { near: drawing, far: null };
+  const { bounds, nominal, kerf } = drawing;
+  const near = { layers: drawing.layers.filter((l) => l.face !== "far"), bounds, nominal, kerf };
+  const outline = { id: "far-outline", name: "REFERENCE", ...ROUTED_COLORS.reference, face: "far", paths: drawing.farOutline };
+  return { near, far: { layers: [outline, ...farLayers], bounds, nominal, kerf } };
+}
 // 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)}`;

package/src/framework/export/formats.js

@@ -44,9 +44,10 @@ export const KIT_LIMITS = Object.freeze({
 export const KIT_DEFAULTS = Object.freeze({
   destination: "own-laser", kerf: 0, colors: "lightburn", stock: null,
   margin: 5, spacing: 3, printFormat: "stl", sets: 1,
+  flip: "left-right", twoSided: "one-file",
 });
 
-const OPTION_KEYS = ["destination", "cutFormat", "kerf", "colors", "stock", "margin", "spacing", "printFormat", "sets"];
+const OPTION_KEYS = ["destination", "cutFormat", "kerf", "colors", "stock", "margin", "spacing", "printFormat", "sets", "flip", "twoSided"];
 
 const fail = (message) => new Error(`${KIT_OPTIONS_ERROR} ${message}`);
 const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v)
@@ -91,7 +92,14 @@ export function validateKitOptions(o) {
   if (!Number.isInteger(sets) || sets < KIT_LIMITS.sets[0] || sets > KIT_LIMITS.sets[1])
     throw fail(`sets must be a whole number from ${KIT_LIMITS.sets[0]} to ${KIT_LIMITS.sets[1]}, got ${JSON.stringify(sets)}`);
 
-  return { destination, cutFormat, kerf, colors, stock, margin, spacing, printFormat, sets };
+  const flip = pick("flip");
+  if (flip !== "left-right" && flip !== "end-over-end")
+    throw fail(`flip must be "left-right" or "end-over-end", got ${JSON.stringify(flip)}`);
+  const twoSided = pick("twoSided");
+  if (twoSided !== "one-file" && twoSided !== "two-files")
+    throw fail(`twoSided must be "one-file" or "two-files", got ${JSON.stringify(twoSided)}`);
+
+  return { destination, cutFormat, kerf, colors, stock, margin, spacing, printFormat, sets, flip, twoSided };
 }
 
 // null/undefined → null ("every group gets DEFAULT_STOCK_SIZE"); otherwise fresh

package/src/framework/export/readme.js

@@ -15,7 +15,16 @@ export const CSV_HEADER = "file,kind,labels,material,thickness_mm,width_mm,heigh
 
 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 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. FAR_* layers are the same operations on the far face, drawn mirrored (see the flip note under each two-sided piece). Laser pieces keep CUT/SCORE/ENGRAVE.";
+// A two-sided routed piece: how its far layers were mirrored, how to line them up, and
+// where its through cut is made.
+const FLIP_NOTE = {
+  "left-right": "Far-side layers (FAR_*) are drawn as seen after flipping the board left-right, matching a VCarve two-sided job with Flip Direction = Horizontal.",
+  "end-over-end": "Far-side layers (FAR_*) are drawn as seen after flipping the board end over end, matching a VCarve two-sided job with Flip Direction = Vertical.",
+};
+const ALIGN_NOTE = "On the bottom side, move the imported far-side vectors so their outline sits on the piece's outline as the CAM shows it from that side. Shortcut: make the job's material the piece's size, then centre the imported vectors on the material (VCarve: Align Selected Objects → Centre); because the far layers are mirrored about the piece's own centre, they then land exactly.";
+const ONE_FILE_NOTE = "On the bottom side the CUT outline is for alignment only — cut the piece out from the near side.";
+const TWO_SIDED_ORDER = "Two-sided pieces: machine the far side first, flip, then the near side and the through cut last, so the board holds the piece until the end. Sheet layouts in sheets/ carry near-side work only; far-side work is in the per-piece files.";
 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
@@ -48,6 +57,7 @@ function settingValue(v) {
 
 const table = (header, rows) => (rows.length ? [header.join(" | "), ...rows.map((r) => r.join(" | "))] : []);
 const mm2 = ([w, h]) => `${w.toFixed(2)} × ${h.toFixed(2)} mm`;
+const faceOf = (op) => (op.face === "far" ? "far" : "near");
 const labelsOf = (labels) => labels.map(cleanLabel).join(", ");
 
 export function renderReadme(m) {
@@ -72,6 +82,7 @@ export function renderReadme(m) {
       ...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)"}`),
       router ? ROUTER_LEGEND : m.cutFormat === "dxf" ? DXF_LEGEND : SVG_LEGEND,
+      ...(m.anyTwoSided ? [TWO_SIDED_ORDER] : []),
       ...(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."] : []),
@@ -83,16 +94,18 @@ export function renderReadme(m) {
     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)]),
+      `${labelsOf(r.labels)} (${cleanLabel(r.material)} ${r.thickness.toFixed(2)} mm) — depths from each op's own face:`,
+      ...table(["op", "face", "label", "size", "depth", "method"], [
+        ...r.pockets.map((pk) => ["pocket", faceOf(pk), pk.label ? cleanLabel(pk.label) : "—", mm2([pk.w, pk.h]), `${pk.depth.toFixed(2)} mm`, "mill"]),
+        ...r.drills.map((dr) => ["drill", faceOf(dr), 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", faceOf(x), cleanLabel(x.label), mm2([x.w, x.h]), `to ${x.maxDepth.toFixed(2)} mm`, cleanLabel(x.method)]),
       ]),
+      ...(r.twoSided ? [FLIP_NOTE[m.flip] ?? FLIP_NOTE["left-right"], ALIGN_NOTE,
+        r.farFile ? `Far-side work is in ${r.farFile}; its REFERENCE outline is for alignment, not cutting.` : ONE_FILE_NOTE] : []),
     ]),
     // 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]))]
+      ? ["LAYERS (one colour per layer across the kit):", ...table(["layer", "face", "colour", "depth"], m.layers.map((l) => [l.name, faceOf(l), 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) =>

package/src/framework/geometry/probe.js

@@ -42,8 +42,11 @@ export class ProbeRunawayError extends Error {
 }
 
 // Shared proxy construction. `onCall(scope, op, args)` observes every op; queries
-// return realistic dummy values the build may read.
-function makeProbe(onCall) {
+// return realistic dummy values the build may read, and `onQuery(scope, op)` hears
+// each one — every answer in the three query tables below is FABRICATED (a unit
+// box, area 1, contains() always false, …), so a build that read one and then threw
+// may only have believed the placeholder (lint's build-throws reads this).
+function makeProbe(onCall, onQuery = () => {}) {
   const solidQueries = {
     boundingBox: () => ({ min: [0, 0, 0], max: [1, 1, 1], center: [0.5, 0.5, 0.5], size: [1, 1, 1] }),
     volume: () => 1,
@@ -78,6 +81,7 @@ function makeProbe(onCall) {
     toSTEP: () => Promise.resolve(new ArrayBuffer(0)),
     cleanup: () => {},
   };
+  const NOT_DATA = new Set(["cleanup"]); // answers nothing a build could act on
 
   // `ignore` keeps the proxy from masquerading as a thenable/internal/serializable
   // handle: symbols, `then` (so it's never await-unwrapped), `_`-prefixed internals,
@@ -100,7 +104,13 @@ function makeProbe(onCall) {
   const opProxy = (queries, scope, routeFor) => new Proxy({}, {
     get(_t, key) {
       if (ignore(key)) return undefined;
-      if (key in queries) return (...args) => { onCall(scope, key, args); return queries[key](...args); };
+      if (key in queries) {
+        return (...args) => {
+          onCall(scope, key, args);
+          if (!NOT_DATA.has(key)) onQuery(scope, key);
+          return queries[key](...args);
+        };
+      }
       return (...args) => { onCall(scope, key, args); return routeFor(key); };
     },
   });
@@ -135,6 +145,8 @@ export function createValidatingProbe({ maxOps = MAX_PROBE_OPS } = {}) {
   const issues = [];
   const used = new Set();
   const solidUsed = new Set();  // same split as createProbeKernel: non-Shape2D-handle ops
+  const queried = [];           // fabricated data queries read, as "scope.op", first-read order;
+                                // runValidatingProbe empties it before each build/probe call
   let count = 0;
   let solidProxy = null;
   let shape2dProxy = null;
@@ -169,17 +181,23 @@ export function createValidatingProbe({ maxOps = MAX_PROBE_OPS } = {}) {
     calls.push({ scope, op, args: args.map(describe) });
   };
 
-  const { kernel, proxy, shape2d } = makeProbe(onCall);
+  const onQuery = (scope, op) => {
+    const name = `${scope === "shape2d" ? "Shape2D" : scope === "kernel" ? "k" : "Solid"}.${op}()`;
+    if (!queried.includes(name)) queried.push(name);
+  };
+  const { kernel, proxy, shape2d } = makeProbe(onCall, onQuery);
   solidProxy = proxy;
   shape2dProxy = shape2d;
-  return { kernel, calls, issues, used, solidUsed };
+  return { kernel, calls, issues, used, solidUsed, queried };
 }
 
 /**
  * Execute every sub-part's build() — and every declared probe (`part.probes`,
  * same (k, p, d) contract, see oracle/measure.js) — against a validating probe.
  * Never throws: a build error becomes an entry in `throws` (probe entries land
- * in `probeThrows`), a runaway sets `runaway`.
+ * in `probeThrows`), a runaway sets `runaway`. Each entry carries `queried`: the
+ * fabricated data queries THAT call read before it threw (tracked per call, so one
+ * sub-part's reads never excuse another's throw).
  */
 export function runValidatingProbe(part, p, d, { maxOps = MAX_PROBE_OPS } = {}) {
   const probe = createValidatingProbe({ maxOps });
@@ -187,22 +205,23 @@ export function runValidatingProbe(part, p, d, { maxOps = MAX_PROBE_OPS } = {})
   const probeThrows = [];
   let runaway = false;
   const run = (fn, onThrow) => {
+    probe.queried.length = 0;
     try {
       fn(probe.kernel, p, d);
     } catch (e) {
       if (e instanceof ProbeRunawayError) { runaway = true; return false; }
-      onThrow(e?.message || String(e));
+      onThrow(e?.message || String(e), [...probe.queried]);
     }
     return true;
   };
   for (const [name, sp] of Object.entries(part?.parts ?? {})) {
     if (typeof sp?.build !== "function") continue; // no-buildable-parts already reports this
-    if (!run(sp.build, (m) => throws.push({ subpart: name, message: m }))) break;
+    if (!run(sp.build, (m, queried) => throws.push({ subpart: name, message: m, queried }))) break;
   }
   if (!runaway) {
     for (const [name, fn] of Object.entries(part?.probes ?? {})) {
       if (typeof fn !== "function") continue; // invalid-probes already reports this
-      if (!run(fn, (m) => probeThrows.push({ probe: name, message: m }))) break;
+      if (!run(fn, (m, queried) => probeThrows.push({ probe: name, message: m, queried }))) break;
     }
   }
   return { calls: probe.calls, issues: probe.issues, used: probe.used, solidUsed: probe.solidUsed, throws, probeThrows, runaway };