partforge 0.156.0 → 0.158.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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.156.0",
+  "version": "0.158.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/pose.js

@@ -91,3 +91,23 @@ export function rotateNormals(normals, m) {
     normals[i + 2] = m[2] * x + m[6] * y + m[10] * z;
   }
 }
+
+// Whether a column-major mat4 is a rigid motion within `tol`: finite, affine
+// (last row 0 0 0 1), an orthonormal 3x3 block (RᵀR = I) with det = +1 — no
+// scale, shear or mirror. The preview GLB's encoder refuses any other pose, and
+// the sampler (preview-animation.js) applies the same test so its output never
+// trips that refusal.
+export function isRigid(m, tol = 1e-6) {
+  if (!Array.isArray(m) && !ArrayBuffer.isView(m)) return false;
+  if (m.length !== 16 || !Array.prototype.every.call(m, Number.isFinite)) return false;
+  if (Math.abs(m[3]) > tol || Math.abs(m[7]) > tol || Math.abs(m[11]) > tol || Math.abs(m[15] - 1) > tol) return false;
+  const col = (c) => [m[c * 4], m[c * 4 + 1], m[c * 4 + 2]];
+  const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+  const cols = [col(0), col(1), col(2)];
+  for (let i = 0; i < 3; i++) {
+    for (let j = 0; j < 3; j++) if (Math.abs(dot(cols[i], cols[j]) - (i === j ? 1 : 0)) > tol) return false;
+  }
+  const [a, b, c] = cols;
+  const det = a[0] * (b[1] * c[2] - b[2] * c[1]) - b[0] * (a[1] * c[2] - a[2] * c[1]) + c[0] * (a[1] * b[2] - a[2] * b[1]);
+  return Math.abs(det - 1) <= tol;
+}

package/src/framework/gltf/decode-preview.js

@@ -24,9 +24,25 @@
 // which the viewer reads as "no feature edges" (never undefined, which would
 // make it derive lines by angle).
 //
+// The baked animation (encoder version 4) comes back as `animation`, null for a
+// file without the partforgeAnimation extra (every version 1–3 file):
+// { ...the extra (name, label, loop, duration, cues, opacity, steps, animated),
+//   tracks: { <sub>: { times, translations, rotations } }, rest: { <sub>: mat16 } }.
+// `times` are seconds; `translations` xyz triples and `rotations` xyzw quads are
+// the node's TRS keyframes, which the writer expresses in the root's LOCAL frame
+// — the part's Z-up MODEL frame — so they need no conversion (positions do: they
+// go through the node's world matrix, root rotation included). Only sub-parts
+// that move have a track; `rest[name]` is the column-major mat4 of a track's
+// first keyframe (t = 0), the pose already baked into that sub-part's
+// positions — meshes decode at the OPENING pose. Channels are read off the raw
+// glTF JSON and resolved through the parser, never by AnimationClip track name
+// (three sanitizes node names). An animated sub-part's mesh sits on an unnamed
+// child of its node (quantize() moves it there), so a mesh's sub-part is found
+// by walking up to the nearest node carrying partforgeSubPart.
+//
 // Rejects on anything that is not a decodable GLB; the callers (mount's
 // `preview`, mountPreview) decide what a failure means for them.
-import { Matrix3, Matrix4, Vector3 } from "three";
+import { Matrix3, Matrix4, Quaternion, Vector3 } from "three";
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
 import { MeshoptDecoder } from "three/addons/libs/meshopt_decoder.module.js";
 
@@ -64,16 +80,72 @@ function metaOf(extras) {
   return Object.keys(out).length ? out : null;
 }
 
-// The object standing for a glTF node: the object itself when its node had one
-// primitive, else the Group GLTFLoader made for a multi-primitive mesh — the
-// one carrying the node's extras / name (a primitive's own Mesh has neither).
+// The object standing for a glTF node: the nearest of the object and its
+// ancestors (below the scene root) carrying the writer's partforgeSubPart — an
+// animated sub-part's mesh sits one or two levels under it (quantize()'s unnamed
+// child, then GLTFLoader's Group for a multi-primitive mesh). Failing that, the
+// object itself when its node had one primitive, else the Group GLTFLoader made
+// for a multi-primitive mesh — the one carrying the node's extras / name (a
+// primitive's own Mesh has neither).
 function nodeObjectOf(obj) {
+  for (let o = obj; o && o.parent; o = o.parent) {
+    if (typeof o.userData?.partforgeSubPart === "string") return o;
+  }
   const own = obj.userData ?? {};
   if ("partforgeSubPart" in own || "name" in own) return obj;
   const parent = obj.parent;
   return parent?.isGroup && parent.userData && ("partforgeSubPart" in parent.userData || "name" in parent.userData) ? parent : obj;
 }
 
+// The sub-part key a node object stands for: the writer's own record of the key,
+// then the unsanitized glTF node name.
+function subPartNameOf(node) {
+  const { partforgeSubPart, name } = node.userData ?? {};
+  return typeof partforgeSubPart === "string" ? partforgeSubPart : (name ?? node.name);
+}
+
+// An accessor's elements as a Float32Array of `size` components each, through
+// getX/getY/getZ/getW so a normalized output would be denormalized (this writer
+// stores the channels as plain float32; the guard is for any other writer).
+function readComponents(attr, size) {
+  const out = new Float32Array(attr.count * size);
+  const get = [attr.getX, attr.getY, attr.getZ, attr.getW].slice(0, size);
+  for (let i = 0; i < attr.count; i++) for (let k = 0; k < size; k++) out[i * size + k] = get[k].call(attr, i);
+  return out;
+}
+
+// The baked animation (see the header): the partforgeAnimation extra plus the
+// first glTF animation's channels as model-frame keyframes per sub-part.
+async function readAnimation(gltf) {
+  const extra = gltf.userData?.partforgeAnimation;
+  if (!extra || typeof extra !== "object") return null;
+  const tracks = {};
+  const rest = {};
+  const def = gltf.parser.json.animations?.[0];
+  for (const channel of def?.channels ?? []) {
+    const path = channel.target?.path;
+    if ((path !== "translation" && path !== "rotation") || channel.target.node === undefined) continue;
+    const sampler = def.samplers[channel.sampler];
+    const node = await gltf.parser.getDependency("node", channel.target.node);
+    const [input, output] = await Promise.all([
+      gltf.parser.getDependency("accessor", sampler.input),
+      gltf.parser.getDependency("accessor", sampler.output),
+    ]);
+    const track = (tracks[subPartNameOf(nodeObjectOf(node))] ??= { times: null, translations: null, rotations: null });
+    track.times ??= readComponents(input, 1);
+    if (path === "translation") track.translations = readComponents(output, 3);
+    else track.rotations = readComponents(output, 4);
+  }
+  for (const [name, track] of Object.entries(tracks)) {
+    const t = track.translations ?? new Float32Array(3);
+    const r = track.rotations ?? Float32Array.of(0, 0, 0, 1);
+    rest[name] = new Matrix4()
+      .compose(new Vector3(t[0], t[1], t[2]), new Quaternion(r[0], r[1], r[2], r[3]).normalize(), new Vector3(1, 1, 1))
+      .toArray();
+  }
+  return { ...extra, tracks, rest };
+}
+
 // Line segments as endpoint pairs in model frame: an indexed LINES primitive
 // expanded back to pairs. Version 3's position attribute is the SURFACE's
 // (GLTFLoader hands both objects the same BufferAttribute), so only the
@@ -137,10 +209,9 @@ export async function decodePreviewGlb(bytes) {
     const indices = geometry.index ? Uint32Array.from(geometry.index.array) : null;
     const count = surfaceVertexCount(position, geometry.index);
     const node = nodeObjectOf(obj);
-    const { partforgeSubPart, partforgeDisplay, name: originalName } = node.userData;
+    const { partforgeDisplay } = node.userData;
     const payload = {
-      // The writer's own record of the key, then the unsanitized glTF node name.
-      name: typeof partforgeSubPart === "string" ? partforgeSubPart : (originalName ?? node.name),
+      name: subPartNameOf(node),
       positions: readVec3(position, toModel, false, count),
       normals: normal ? readVec3(normal, normalMatrix, true, count) : null,
       indices,
@@ -166,5 +237,6 @@ export async function decodePreviewGlb(bytes) {
     view: typeof extras.partforgeView === "string" ? extras.partforgeView : null,
     meta: metaOf(extras),
     meshes,
+    animation: await readAnimation(gltf),
   };
 }