partforge 0.155.0 → 0.157.0

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

@@ -6,10 +6,11 @@
 //
 // Colours: `ctx.palette` (drawing.js routedPalette, built by the kit over EVERY routed
 // piece) when given, so one depth is one colour across the kit; without it — a direct
-// call — the piece ranks its own depths. Each named layer also carries its `depth` (mm,
+// call — routedPalette over the piece alone. Each named layer also carries its `depth` (mm,
 // two decimals) and drills `through`, which the README's layer legend reads.
 import {
   refitRing, ringsOf, cutRings, drawingBounds, routedLayerName, depthToken, drillKey, ROUTED_COLORS,
+  routedPalette, FLIP_AXIS, mirrorRings,
 } from "../../export/drawing.js";
 import { KIT_OPTIONS_ERROR } from "../../export/formats.js";
 
@@ -18,57 +19,79 @@ const refitRegions = (regions) => regions.map((rg) => ({ outer: refitRing(rg.out
 const allRings = (regions) => { const r = ringsOf(regions); return [...r.outer, ...r.holes]; };
 const ringsOfShape = (shape) => allRings(refitRegions(shape.toContours())).map(closedPath);
 
-function drawing(s, o, k, ctx = {}) {
-  const label = ctx.label ?? s.label ?? "routed part";
-  if (o?.kerf > 0) throw new Error(`${KIT_OPTIONS_ERROR} kerf does not apply to a CNC router — the CAM applies the tool offset; set kerf to 0 ("${label}")`);
-  const nominal = refitRegions(s.profile.toContours());
-  if (nominal.length === 0) throw new Error(`cut kit: "${label}" has an empty profile — nothing to cut`);
-  const cut = cutRings(nominal);
-  const { pockets, drills, extra } = s.routed;
-
+// One face's operation layers: SECONDARY, then drills grouped by (d, depth, through) in
+// first-seen order, then pockets grouped by two-decimal depth, shallowest first. `place`
+// maps each layer's paths (identity for the near face, the flip's mirror for the far);
+// a far layer's id is prefixed `far-` and it carries `face: "far"` — a near layer has
+// no face key, so a one-sided piece draws exactly as before two-sided parts existed.
+function opLayers({ pockets, drills, extra }, palette, place) {
+  const tag = place ? { face: "far" } : {};
+  const id = (base) => (place ? `far-${base}` : base);
+  const at = place ?? ((paths) => paths);
   const layers = [];
-  const reference = [
-    ...s.score.lines.map(([a, b]) => ({ start: [a[0], a[1]], segments: [{ to: [b[0], b[1]] }], closed: false })),
-    ...s.score.shapes.flatMap(ringsOfShape),
-  ];
-  if (reference.length) layers.push({ id: "reference", name: "REFERENCE", ...ROUTED_COLORS.reference, paths: reference });
   const secondary = extra.flatMap((x) => ringsOfShape(x.footprint));
-  if (secondary.length) layers.push({ id: "secondary", name: "SECONDARY", ...ROUTED_COLORS.secondary, paths: secondary });
+  if (secondary.length) layers.push({ id: id("secondary"), name: place ? "FAR_SECONDARY" : "SECONDARY", ...ROUTED_COLORS.secondary, ...tag, paths: at(secondary) });
 
-  // Drills grouped by (d, depth, through) in first-seen order; each hole a closed ring
-  // of two exact arcs, which dxf.js writes as a CIRCLE.
-  const palette = ctx.palette ?? null;
+  // Each hole a closed ring of two exact arcs, which dxf.js writes as a CIRCLE.
   const drillGroups = new Map();
   drills.forEach((dr) => {
     const key = drillKey(dr);
-    const colour = palette?.drill.get(key) ?? ROUTED_COLORS.drill[drillGroups.size % ROUTED_COLORS.drill.length];
-    const g = drillGroups.get(key) ?? { id: `drill-${key}`, name: routedLayerName("drill", dr), ...colour,
-      depth: Number(depthToken(dr.depth)), through: dr.through, paths: [] };
-    g.paths.push(...ringsOfShape(dr.shape));
+    const g = drillGroups.get(key) ?? { id: id(`drill-${key}`), name: routedLayerName("drill", dr), ...palette.drill.get(key),
+      depth: Number(depthToken(dr.depth)), through: dr.through, ...tag, paths: [] };
+    g.paths.push(...at(ringsOfShape(dr.shape)));
     drillGroups.set(key, g);
   });
   layers.push(...drillGroups.values());
 
-  // Pockets grouped by two-decimal depth, shallowest layer first; an empty region draws nothing.
+  // An empty region draws nothing.
   const pocketGroups = new Map();
   for (const pk of pockets) {
     const paths = ringsOfShape(pk.region);
     if (paths.length === 0) continue;
     const key = depthToken(pk.depth);
-    const g = pocketGroups.get(key) ?? { id: `pocket-${key}`, name: routedLayerName("pocket", pk), depth: Number(key), paths: [] };
-    g.paths.push(...paths);
+    const g = pocketGroups.get(key) ?? { id: id(`pocket-${key}`), name: routedLayerName("pocket", pk), depth: Number(key), ...tag, paths: [] };
+    g.paths.push(...at(paths));
     pocketGroups.set(key, g);
   }
-  [...pocketGroups.values()].sort((a, b) => a.depth - b.depth).forEach((g, i) => {
-    const colour = palette?.pocket.get(depthToken(g.depth)) ?? ROUTED_COLORS.pocket[i % ROUTED_COLORS.pocket.length];
-    layers.push({ ...g, ...colour });
-  });
+  [...pocketGroups.values()].sort((a, b) => a.depth - b.depth)
+    .forEach((g) => layers.push({ ...g, ...palette.pocket.get(depthToken(g.depth)) }));
+  return layers;
+}
+
+function drawing(s, o, k, ctx = {}) {
+  const label = ctx.label ?? s.label ?? "routed part";
+  if (o?.kerf > 0) throw new Error(`${KIT_OPTIONS_ERROR} kerf does not apply to a CNC router — the CAM applies the tool offset; set kerf to 0 ("${label}")`);
+  const nominal = refitRegions(s.profile.toContours());
+  if (nominal.length === 0) throw new Error(`cut kit: "${label}" has an empty profile — nothing to cut`);
+  const cut = cutRings(nominal);
+  const { pockets, drills, extra } = s.routed;
+
+  const layers = [];
+  const reference = [
+    ...s.score.lines.map(([a, b]) => ({ start: [a[0], a[1]], segments: [{ to: [b[0], b[1]] }], closed: false })),
+    ...s.score.shapes.flatMap(ringsOfShape),
+  ];
+  if (reference.length) layers.push({ id: "reference", name: "REFERENCE", ...ROUTED_COLORS.reference, paths: reference });
+  // Near ops as they are; far ops (cut after the piece is turned over by the kit's flip)
+  // on their own `far-` layers, every ring mirrored about the piece's centre so the far
+  // face is drawn as the router sees it. One palette for both faces: a depth or drill
+  // setting is one colour whichever face it is on.
+  const palette = ctx.palette ?? routedPalette([s]);
+  const nb = drawingBounds([{ id: "cut-outer", paths: ringsOf(nominal).outer.map(closedPath) }]);
+  const axis = FLIP_AXIS[o?.flip ?? "left-right"];
+  const centre = axis === "x" ? (nb.min[0] + nb.max[0]) / 2 : (nb.min[1] + nb.max[1]) / 2;
+  const isFar = (op) => op.face === "far";
+  const near = opLayers({ pockets: pockets.filter((op) => !isFar(op)), drills: drills.filter((op) => !isFar(op)), extra: extra.filter((op) => !isFar(op)) }, palette);
+  const far = opLayers({ pockets: pockets.filter(isFar), drills: drills.filter(isFar), extra: extra.filter(isFar) }, palette,
+    (paths) => mirrorRings(paths, axis, centre));
+  layers.push(...near, ...far);
 
   if (cut.inner.length) layers.push({ id: "cut-inner", paths: cut.inner.map(closedPath) });
   layers.push({ id: "cut-outer", paths: cut.outer.map(closedPath) });
 
-  const nb = drawingBounds([{ id: "cut-outer", paths: ringsOf(nominal).outer.map(closedPath) }]);
-  return { layers, bounds: drawingBounds(layers), nominal: [nb.max[0] - nb.min[0], nb.max[1] - nb.min[1]], kerf: 0 };
+  const out = { layers, bounds: drawingBounds(layers), nominal: [nb.max[0] - nb.min[0], nb.max[1] - nb.min[1]], kerf: 0 };
+  if (far.length) out.farOutline = mirrorRings(ringsOf(nominal).outer, axis, centre).map(closedPath);
+  return out;
 }
 
 export default { drawing };

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

@@ -16,6 +16,13 @@ const depthOf = (sp, entry, who) => {
   if (!isNum(entry.depth) || entry.depth <= 0) throw fail(sp, `${who} depth must be a finite number > 0 (mm), got ${JSON.stringify(entry.depth)}`);
   return entry.depth;
 };
+// Which face an op is machined from: "near" (z = thickness, the default) or "far" (z = 0).
+const faceOf = (sp, entry, who) => {
+  const f = entry.face;
+  if (f === undefined || f === null) return "near";
+  if (f === "near" || f === "far") return f;
+  throw fail(sp, `${who} face must be "near" or "far", got ${JSON.stringify(f)}`);
+};
 const labelOf = (entry) => (typeof entry.label === "string" && entry.label.trim() ? entry.label.trim() : null);
 const list = (sp, fn, args, what, shape) => {
   if (!fn) return [];
@@ -26,7 +33,9 @@ const list = (sp, fn, args, what, shape) => {
 };
 
 // `base` is resolveSheet's ResolvedSheet so far (profile, thickness, score…); the
-// return value is merged onto it as `routed`.
+// return value is merged onto it as `routed`. Every op carries `face`: "near" (machined
+// from z = thickness, the default) or "far" (from z = 0, the stock flipped over); depth
+// is measured from that face either way.
 export function resolveRouted(k, sp, p, d, base) {
   const s = sp.sheet;
   const t = base.thickness;
@@ -35,8 +44,9 @@ export function resolveRouted(k, sp, p, d, base) {
     const who = name(e, i, "pocket");
     if (!e || typeof e !== "object" || e.region === null || e.region === undefined) throw fail(sp, `${who} needs a region (a Shape2D or profile)`);
     const depth = depthOf(sp, e, who);
+    const face = faceOf(sp, e, who);
     if (depth > t) throw fail(sp, `${who} is ${e.depth} mm deep in ${t} mm stock — a pocket may be at most the thickness; make it a through cut in \`profile\` if it should go through`);
-    return { region: k.shape2d(e.region), depth, label: labelOf(e) };
+    return { region: k.shape2d(e.region), depth, label: labelOf(e), face };
   });
 
   const drills = list(sp, s.drills, [p, d], "drills(p, d)", "{ at, d, depth }").map((e, i) => {
@@ -44,18 +54,20 @@ export function resolveRouted(k, sp, p, d, base) {
     if (!e || typeof e !== "object" || !isPoint(e.at)) throw fail(sp, `${who} needs at: [x, y]`);
     if (!isNum(e.d) || e.d <= 0) throw fail(sp, `${who} d must be a finite number > 0 (mm), got ${JSON.stringify(e.d)}`);
     const depth = depthOf(sp, e, who);
+    const face = faceOf(sp, e, who);
     const through = depth >= t;
-    return { shape: k.shape2d(circleRing(e.at, e.d / 2)), at: [e.at[0], e.at[1]], d: e.d, depth: through ? t : depth, through, label: labelOf(e) };
+    return { shape: k.shape2d(circleRing(e.at, e.d / 2)), at: [e.at[0], e.at[1]], d: e.d, depth: through ? t : depth, through, label: labelOf(e), face };
   });
 
   const extra = list(sp, s.extra, [k, p, d], "extra(k, p, d)", "{ solid, footprint, label, method }").map((e, i) => {
     const label = labelOf(e);
     if (!label) throw fail(sp, `extra op ${i + 1} needs a label — say what it is ("12° domino slot")`);
     const who = `extra op "${label}"`;
+    const face = faceOf(sp, e, who);
     if (typeof e.method !== "string" || !e.method.trim()) throw fail(sp, `${who} needs a method — say how the operator makes it ("table saw, blade tilted 12°")`);
     if (!isSolid(e.solid)) throw fail(sp, `${who} needs a solid — the geometry it removes, for the preview and the STEP`);
     if (e.footprint === null || e.footprint === undefined) throw fail(sp, `${who} needs a footprint — its outline on the machined face, for the drawing`);
-    return { solid: e.solid, footprint: k.shape2d(e.footprint), label, method: e.method.trim() };
+    return { solid: e.solid, footprint: k.shape2d(e.footprint), label, method: e.method.trim(), face };
   });
 
   return { pockets, drills, extra };

package/types/geometry.d.ts

@@ -338,12 +338,14 @@ export function sheetPart<P = ResolvedParams, D = Derived>(spec: SheetPartSpec<P
 
 // --- routed parts (docs/AUTHORING-PARTS.md "Routed parts") --------------------
 
-/** A flat-floored pocket machined `depth` mm down from the machined face. */
-export interface RoutedPocket { region: Shape2D | ProfileInput; depth: number; label?: string }
+/** Which face of the stock an op is machined from: `"near"` (z = thickness, the default) or `"far"` (z = 0). */
+export type RoutedFace = "near" | "far";
+/** A flat-floored pocket machined `depth` mm into the stock from its face. */
+export interface RoutedPocket { region: Shape2D | ProfileInput; depth: number; label?: string; face?: RoutedFace }
 /** A drilled hole; `depth` equal to the stock thickness drills through — deeper is a `routed-drill-depth` lint error. */
-export interface RoutedDrill { at: Point2; d: number; depth: number; label?: string }
+export interface RoutedDrill { at: Point2; d: number; depth: number; label?: string; face?: RoutedFace }
 /** An operation done with another tool after the flat milling: the solid is cut in the preview and the STEP, the footprint is drawn, label and method go in the README. */
-export interface RoutedExtra { solid: Solid; footprint: Shape2D | ProfileInput; label: string; method: string }
+export interface RoutedExtra { solid: Solid; footprint: Shape2D | ProfileInput; label: string; method: string; face?: RoutedFace }
 
 /**
  * What `routedPart` accepts: `sheetPart`'s stock, profile and pose, plus pockets,

package/types/gltf.d.ts

@@ -23,7 +23,10 @@ export interface PreviewMesh {
   /**
    * Feature-edge segments, endpoint pairs `[x0,y0,z0, x1,y1,z1, …]` in the same posed
    * frame as `positions` (encoder version 2+). Written as a LINES primitive on the
-   * sub-part's mesh. Empty or absent writes none, and decodes as "no feature edges".
+   * sub-part's mesh — since version 3, indices into the surface's own POSITION
+   * accessor (each endpoint snapped to the surface vertex at its position, or
+   * appended past the surface's vertices when it lies on none). Empty or absent
+   * writes none, and decodes as "no feature edges".
    */
   edges?: Float32Array | null;
 }
@@ -37,7 +40,7 @@ export interface EncodePreviewInput {
   view?: string | null;
 }
 
-/** Bumped whenever the encoder writes different bytes for the same input (2: feature edges). */
+/** Bumped whenever the encoder writes different bytes for the same input (2: feature edges; 3: edges as indices into the surface's vertices). */
 export const PREVIEW_ENCODER_VERSION: number;
 
 /** Encode one view's posed meshes as a welded, quantized, meshopt-compressed GLB (Y-up, millimetres). Deterministic. */

package/types/index.d.ts

@@ -67,6 +67,10 @@ export interface KitOptions {
   printFormat?: "stl" | "3mf";
   /** Whole number, 1–20. Default 1. */
   sets?: number;
+  /** Which way a two-sided board is turned over between sides — the axis far-side layers are mirrored about. Default `"left-right"`. */
+  flip?: "left-right" | "end-over-end";
+  /** Two-sided pieces: one layered file per piece (`"one-file"`, default), or a near file plus a `-far` file (`"two-files"`). */
+  twoSided?: "one-file" | "two-files";
 }
 
 /**
@@ -830,6 +834,8 @@ export const KIT_DEFAULTS: Readonly<{
   spacing: number;
   printFormat: "stl";
   sets: number;
+  flip: "left-right";
+  twoSided: "one-file";
 }>;
 
 /** Normalise kit options — defaults filled, `cutFormat` derived — or throw a `"cut kit options: …"` error. */

package/types/part.d.ts

@@ -576,6 +576,8 @@ export interface SubPartExpectations {
   routedEmpty?: Expectation;
   /** Routed parts only: separate regions in the cut profile (volunteered check: `1`). */
   routedPieces?: Expectation;
+  /** Routed parts only: overlapping near- and far-face pocket pairs whose depths together exceed the stock (volunteered check: `0`). */
+  routedBreakthrough?: Expectation;
 }
 
 /**