partforge 0.133.3 → 0.134.0

package/src/framework/export/drawing.js

@@ -0,0 +1,356 @@
+// The kit's drawing stage: the process-agnostic Drawing IR every cut-file writer reads,
+// plus the two contour passes that run before any writer sees a ring. A Drawing is a
+// sheet piece in its CANONICAL frame — mm, y up, the laser face seen from above —
+// built from the piece's resolved 2-D declaration alone. Nothing here reads a pose or a
+// solid (design spec D.1): the 3-D model is a preview of the cut file, never its source.
+//
+// The Drawing IR (contract §5.5): `layers` in LAYER_ORDER, each `{ id, paths }`, a path
+// being `{ start, segments, closed }` whose segments ARE the contour IR (profile.js:
+// `{to}` line, `{to, via}` three-point arc, `{to, c1, c2}` cubic) — there is no second
+// segment type. `bounds` covers every layer after kerf; `nominal` is the cut layer's
+// size before kerf, which the README's scale check prints.
+//
+// Why two refits. Every Shape2D boolean turns arcs into cubics (paper-bridge.js), so a
+// hole cut with cutAll comes back as four cubics, and so does every exact arc a *Profile
+// helper drew (circleProfile's two, since partforge 0.132) once a boolean has touched
+// it; recoverArcs (arc-fit.js) turns those back into exact arcs. But a point list draws
+// its curves as polygons — circlePolygon is a 48-gon, the round *Polygon helpers'
+// corners and ends are chords, a hand-sampled arc is its samples — and a laser traces
+// every facet. refitLineRuns is the conservative second pass for those:
+// a run becomes arcs only when at least `minVerts` consecutive vertices sit on one
+// circle AND every step turns by at most `maxTurnDeg`, all the same way. A hexagon (60°
+// turns) or a star (alternating turns) never qualifies; when the test misses something
+// the output is dense, never wrong — and "never wrong" is held in millimetres: no
+// authored vertex ends up more than REFIT_MAX_MOVE_MM from the output.
+//
+// LAZY: reachable only through process/exporters.js's dynamic import (and, from P2b,
+// export/bundle.js's). It reaches paper (offsetRegions: contour-offset.js →
+// paper-bridge.js — arc-fit.js is now a paper-free leaf, so recoverArcs no longer
+// carries this), which is why lint, the oracle and partforge/geometry must never
+// import it (test/kit-export-guards.test.js). It runs in the geometry worker, so it
+// stays DOM-free and node:-free.
+import { recoverArcs } from "../geometry/arc-fit.js";
+import { arcCenterAndSweep } from "../geometry/arc-math.js";
+import { cubicAt } from "../geometry/contour-ops.js";
+import { offsetRegions } from "../geometry/contour-offset.js";
+import { closeContourGap } from "../geometry/profile.js";
+import { KIT_OPTIONS_ERROR } from "./formats.js";
+
+// The cut order: marks first (the piece is still held by the sheet), holes before the
+// outline that frees the piece. Writers emit layers in this order.
+export const LAYER_ORDER = Object.freeze(["engrave", "score", "cut-inner", "cut-outer"]);
+// engrave is a filled region; the rest are vector lines.
+export const LAYER_KIND = Object.freeze({ engrave: "fill", score: "line", "cut-inner": "line", "cut-outer": "line" });
+
+const TAU = 2 * Math.PI;
+const CLOSE_EPS = 1e-9;   // mm — the storage invariant's "explicitly closed"
+const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1]);
+const wrapPi = (a) => { a %= TAU; if (a > Math.PI) a -= TAU; else if (a <= -Math.PI) a += TAU; return a; };
+const wrapTau = (a) => ((a % TAU) + TAU) % TAU;
+const isLine = (s) => !s.via && !s.c1;
+
+// Signed turn (radians, CCW positive) from edge a→b to edge b→c; NaN when an edge has no
+// length (a duplicate vertex has no direction, so it can never sit inside a run).
+function turnAt(a, b, c) {
+  const u = [b[0] - a[0], b[1] - a[1]], v = [c[0] - b[0], c[1] - b[1]];
+  if (Math.hypot(u[0], u[1]) < CLOSE_EPS || Math.hypot(v[0], v[1]) < CLOSE_EPS) return NaN;
+  return Math.atan2(u[0] * v[1] - u[1] * v[0], u[0] * v[0] + u[1] * v[1]);
+}
+
+// The refit's promise, in mm: no authored vertex ends up farther than this from the arcs
+// that replace its run. It caps the fit band — a band relative to the radius alone grows
+// with it, and the three-point circle of a gently curving stretch can be metres wide —
+// and every run is measured against its real output arcs before it is kept.
+export const REFIT_MAX_MOVE_MM = 0.005;
+// A run's radius may be at most this many times its chord (its diameter, for a run of
+// half a turn or more): past that the "arc" is a flat stretch of some other curve, which
+// the laser should trace as drawn, not a faceted circle to recover.
+const REFIT_MAX_FLATNESS = 50;
+
+// Fit the circle through vertices k..e of Q (via k, the one-third and the two-thirds
+// vertex — three distinct points even when the run is a whole ring and Q[e] is Q[k]),
+// then require EVERY vertex within tolerance of it, stepping round the centre in the
+// run's turning direction. Returns the run's circle and accumulated sweep, or null.
+function fitRun(Q, k, e, sign) {
+  const m = e - k;
+  const c = arcCenterAndSweep(Q[k], Q[k + Math.round(m / 3)], Q[k + Math.round((2 * m) / 3)]);
+  if (!c || !(c.r > 0)) return null;
+  const run = { center: c.center, r: c.r, tol: Math.min(Math.max(1e-6, 1e-4 * c.r), REFIT_MAX_MOVE_MM), sign, sweep: 0 };
+  if (Math.abs(dist(Q[k], run.center) - run.r) > run.tol) return null;
+  for (let i = k + 1; i <= e; i++) if (!extendRun(run, Q[i - 1], Q[i])) return null;
+  return run;
+}
+
+// Does `q` continue `run` from `p` — on the circle, stepping the same way round, the
+// whole run staying within one turn? Advances run.sweep when it does.
+function extendRun(run, p, q) {
+  if (Math.abs(dist(q, run.center) - run.r) > run.tol) return false;
+  const ang = (x) => Math.atan2(x[1] - run.center[1], x[0] - run.center[0]);
+  const step = wrapPi(ang(q) - ang(p));
+  if (Math.sign(step) !== run.sign || Math.abs(run.sweep + step) > TAU + 1e-9) return false;
+  run.sweep += step;
+  return true;
+}
+
+// The arc from `from` to `to` about the run's circle as three-point arcs of at most 180°
+// (the three-point form is ambiguous past that), `via` at each piece's angular middle,
+// the final `to` pinned to the run's real last vertex.
+function arcPieces(from, to, { center, r, sweep }) {
+  const a0 = Math.atan2(from[1] - center[1], from[0] - center[0]);
+  const n = Math.max(1, Math.ceil(Math.abs(sweep) / Math.PI - 1e-9));
+  const at = (t) => [center[0] + r * Math.cos(t), center[1] + r * Math.sin(t)];
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    const s0 = a0 + (sweep * i) / n, s1 = a0 + (sweep * (i + 1)) / n;
+    out.push({ to: at(s1), via: at((s0 + s1) / 2) });
+  }
+  out[n - 1].to = [to[0], to[1]];
+  return out;
+}
+
+// How far q is from the three-point arc from → via → to: the radial gap when q lies
+// inside the sweep, else the distance to the nearer end.
+function arcGap(q, from, { via, to }) {
+  const g = arcCenterAndSweep(from, via, to);
+  if (!g) return Infinity;
+  const a0 = Math.atan2(from[1] - g.center[1], from[0] - g.center[0]);
+  const along = wrapTau(Math.sign(g.dA) * (Math.atan2(q[1] - g.center[1], q[0] - g.center[0]) - a0));
+  if (along <= Math.abs(g.dA) + 1e-12) return Math.abs(dist(q, g.center) - g.r);
+  return Math.min(dist(q, from), dist(q, to));
+}
+
+// Keep a fitted run k..e only when it is a circle to recover and its arcs are faithful:
+// not far flatter than it is long, and every vertex it replaces within
+// REFIT_MAX_MOVE_MM of the arcs actually written (whose ends are the run's real,
+// slightly off-circle, first and last vertices — so this is measured, not assumed).
+function keepRun(Q, k, e, run, pieces) {
+  const chord = Math.abs(run.sweep) >= Math.PI ? 2 * run.r : dist(Q[k], Q[e]);
+  if (run.r > REFIT_MAX_FLATNESS * chord) return false;
+  for (let i = k + 1; i < e; i++) {
+    let from = Q[k], gap = Infinity;
+    for (const s of pieces) { gap = Math.min(gap, arcGap(Q[i], from, s)); from = s.to; }
+    if (!(gap <= REFIT_MAX_MOVE_MM)) return false;
+  }
+  return true;
+}
+
+// Runs of straight segments that trace a circle → three-point arcs. Curves pass through
+// untouched and break runs. A closed ring is first re-seated at a "hard break" (a vertex
+// no run can pass: a curve meets it, or it turns out of band) so a run that wraps the
+// ring's start is seen whole; a ring with no hard break — a faceted circle — is tried as
+// one run all the way round. Orientation is preserved. When nothing is refit the input
+// contour is returned as-is (same object). Linear in the vertex count.
+export function refitLineRuns(contour, { minVerts = 8, maxTurnDeg = 15 } = {}) {
+  const segs = contour.segments;
+  const n = segs.length;
+  if (n < minVerts - 1) return contour;
+  const maxTurn = (maxTurnDeg * Math.PI) / 180 + 1e-9;
+  const inBand = (t) => Math.abs(t) > 1e-12 && Math.abs(t) <= maxTurn;   // NaN fails both
+  const P = [contour.start, ...segs.map((s) => s.to)];
+  const closed = dist(P[0], P[n]) <= CLOSE_EPS;
+
+  let off = 0;
+  if (closed) {
+    for (let i = 0; i < n; i++) {
+      const prev = (i + n - 1) % n;
+      if (!isLine(segs[prev]) || !isLine(segs[i]) || !inBand(turnAt(P[prev], P[i], P[i + 1]))) { off = i; break; }
+    }
+  }
+  const Q = closed ? [...P.slice(off, n), ...P.slice(0, off), P[off]] : P;
+  const S = closed ? [...segs.slice(off), ...segs.slice(0, off)] : segs;
+
+  const out = [];
+  let changed = false;
+  let k = 0, j = 0, sign = 0;
+  while (k < n) {
+    // Segments k..j-1 are straight, and every joint between them turns in band, one way.
+    // Scanned once per run, not once per vertex: while a joint of the run lies ahead of
+    // k (k + 1 < j), the run from k is the same run — same end, same turning sign.
+    if (k + 1 >= j) {
+      j = k; sign = 0;
+      while (j < n && isLine(S[j])) {
+        if (j > k) {
+          const t = turnAt(Q[j - 1], Q[j], Q[j + 1]);
+          if (!inBand(t) || (sign !== 0 && Math.sign(t) !== sign)) break;
+          sign = Math.sign(t);
+        }
+        j++;
+      }
+    }
+    let e = k + minVerts - 1;
+    const run = sign !== 0 && e <= j ? fitRun(Q, k, e, sign) : null;
+    if (!run) { out.push(S[k]); k++; continue; }
+    while (e < j && extendRun(run, Q[e], Q[e + 1])) e++;
+    const pieces = arcPieces(Q[k], Q[e], run);
+    // A refused run stays as drawn, whole: any run inside it lies on the same circle.
+    if (keepRun(Q, k, e, run, pieces)) { out.push(...pieces); changed = true; }
+    else for (let i = k; i < e; i++) out.push(S[i]);
+    k = e;
+  }
+  return changed ? { start: [Q[0][0], Q[0][1]], segments: out } : contour;
+}
+
+// Both refits, in order: cubic runs → arcs (recoverArcs), then line runs → arcs.
+export const refitRing = (ring) => refitLineRuns(recoverArcs(ring));
+
+// Split regions (Shape2D.toContours() form) into outer rings and hole rings, region by
+// region — the cut-outer / cut-inner split, and the ring list a region layer draws.
+export function ringsOf(regions) {
+  return {
+    outer: regions.map((rg) => rg.outer),
+    holes: regions.flatMap((rg) => rg.holes),
+  };
+}
+
+// Is point p inside `ring` (either winding)? The winding number, exact for lines and
+// arcs — an arc sweeps its chord's angle, plus a whole turn when p lies in the circular
+// segment between chord and arc — with cubics flattened. Exact matters: an island can
+// sit a fraction of a millimetre inside the hole around it, where any chorded stand-in
+// for the hole's arcs would put it outside.
+function encloses(ring, p) {
+  const turn = (a, b) => {
+    const ux = a[0] - p[0], uy = a[1] - p[1], vx = b[0] - p[0], vy = b[1] - p[1];
+    return Math.atan2(ux * vy - uy * vx, ux * vx + uy * vy);
+  };
+  const side = (a, b, q) => (b[0] - a[0]) * (q[1] - a[1]) - (b[1] - a[1]) * (q[0] - a[0]);
+  let w = 0, from = ring.start;
+  for (const s of ring.segments) {
+    if (s.c1) {
+      let a = from;
+      for (let i = 1; i <= 32; i++) { const b = i === 32 ? s.to : cubicAt(from, s.c1, s.c2, s.to, i / 32); w += turn(a, b); a = b; }
+    } else {
+      w += turn(from, s.to);
+      const g = s.via ? arcCenterAndSweep(from, s.via, s.to) : null;
+      if (g && dist(p, g.center) < g.r && Math.sign(side(from, s.to, p)) === Math.sign(side(from, s.to, s.via)))
+        w += Math.sign(g.dA) * TAU;
+    }
+    from = s.to;
+  }
+  return Math.abs(w) > Math.PI;
+}
+
+// The cut layer's rings in CUT ORDER: every ring before any ring that encloses it, so no
+// outline is cut on a piece that something else has already freed. A ring's depth is how
+// many other rings enclose it (rings of a valid profile never cross, so its start point
+// answers for all of it); deepest first, region order within a depth. `inner` is every
+// enclosed ring — holes, and islands standing in a hole with their own holes — and
+// `outer` the top-level outlines, the cuts that free the pieces. A piece of one region
+// comes back as its holes then its outline, exactly as ringsOf splits it.
+export function cutRings(regions) {
+  const rings = regions.flatMap((rg) => [rg.outer, ...rg.holes]);
+  let depth;
+  if (regions.length === 1) depth = rings.map((_, i) => (i === 0 ? 0 : 1));
+  else {
+    // a ring can only enclose a point inside its own bounding box
+    const box = rings.map((r) => drawingBounds([{ paths: [r] }]));
+    const inBox = (i, [x, y]) => x >= box[i].min[0] && x <= box[i].max[0] && y >= box[i].min[1] && y <= box[i].max[1];
+    depth = rings.map((r, i) => rings.reduce((n, q, j) => n + (j !== i && inBox(j, r.start) && encloses(q, r.start) ? 1 : 0), 0));
+  }
+  const order = rings.map((_, i) => i).sort((a, b) => depth[b] - depth[a] || a - b);
+  return {
+    inner: order.filter((i) => depth[i] > 0).map((i) => rings[i]),
+    outer: order.filter((i) => depth[i] === 0).map((i) => rings[i]),
+  };
+}
+
+// Exact bounding box of every path in `layers` — arcs by their axis extremes inside the
+// sweep, cubics by the roots of their derivative — or null when there is no path at all.
+export function drawingBounds(layers) {
+  let min = null, max = null;
+  const add = ([x, y]) => {
+    if (!min) { min = [x, y]; max = [x, y]; return; }
+    if (x < min[0]) min[0] = x; if (y < min[1]) min[1] = y;
+    if (x > max[0]) max[0] = x; if (y > max[1]) max[1] = y;
+  };
+  for (const layer of layers) for (const path of layer.paths) {
+    add(path.start);
+    let from = path.start;
+    for (const s of path.segments) {
+      add(s.to);
+      if (s.via) addArcExtremes(add, from, s);
+      else if (s.c1) addCubicExtremes(add, from, s);
+      from = s.to;
+    }
+  }
+  return min ? { min, max } : null;
+}
+
+function addArcExtremes(add, from, s) {
+  const g = arcCenterAndSweep(from, s.via, s.to);
+  if (!g) return;                                   // collinear: the endpoints bound it
+  const a0 = Math.atan2(from[1] - g.center[1], from[0] - g.center[0]);
+  for (let q = 0; q < 4; q++) {
+    const theta = (q * Math.PI) / 2;
+    const along = g.dA >= 0 ? wrapTau(theta - a0) : wrapTau(a0 - theta);
+    if (along <= Math.abs(g.dA)) add([g.center[0] + g.r * Math.cos(theta), g.center[1] + g.r * Math.sin(theta)]);
+  }
+}
+
+function addCubicExtremes(add, from, s) {
+  for (const axis of [0, 1]) {
+    const a = from[axis], b = s.c1[axis], c = s.c2[axis], d = s.to[axis];
+    // B'(t) / 3 = A t² + B t + C
+    const A = -a + 3 * b - 3 * c + d, B = 2 * (a - 2 * b + c), C = b - a;
+    const roots = [];
+    if (Math.abs(A) < 1e-12) { if (Math.abs(B) > 1e-12) roots.push(-C / B); }
+    else {
+      const disc = B * B - 4 * A * C;
+      if (disc >= 0) { const q = Math.sqrt(disc); roots.push((-B + q) / (2 * A), (-B - q) / (2 * A)); }
+    }
+    for (const t of roots) if (t > 0 && t < 1) add(cubicAt(from, s.c1, s.c2, s.to, t));
+  }
+}
+
+// The identity P2b's dedupe confirms with: the drawing translated so bounds.min is the
+// origin, every number rounded to 1e-4 mm, as JSON. A hash of this only NOMINATES a
+// duplicate; string equality of the key confirms it (design spec D.4).
+export function canonicalDrawingKey(drawing) {
+  const [ox, oy] = drawing.bounds.min;
+  const r = (v) => { const x = Math.round(v * 1e4) / 1e4; return x === 0 ? 0 : x; };
+  const pt = (p) => [r(p[0] - ox), r(p[1] - oy)];
+  const seg = (s) => (s.c1 ? { to: pt(s.to), c1: pt(s.c1), c2: pt(s.c2) } : s.via ? { to: pt(s.to), via: pt(s.via) } : { to: pt(s.to) });
+  return JSON.stringify({
+    kerf: r(drawing.kerf),
+    layers: drawing.layers.map((l) => ({
+      id: l.id,
+      paths: l.paths.map((p) => ({ closed: p.closed, start: pt(p.start), segments: p.segments.map(seg) })),
+    })),
+  });
+}
+
+const arcCount = (regions) => regions.reduce(
+  (n, rg) => n + [rg.outer, ...rg.holes].reduce((m, ring) => m + ring.segments.filter((s) => s.via).length, 0), 0);
+const holeCounts = (regions) => regions.map((rg) => rg.holes.length).sort((a, b) => a - b).join(",");
+
+// Offset the CUT regions (already refit) by +kerf/2 with round corners, so outlines grow
+// and holes shrink — the storage winding invariant (outer CCW, holes CW) makes one signed
+// offset do both (contour-offset.js). Lines and arcs offset exactly, so recovered arcs
+// stay arcs; the result is refit again for any cubic the offset produced.
+//
+// The offset engine silently DROPS a hole narrower than the offset, and merges regions
+// that grow into each other, so the before/after topology is compared and any change is
+// an options error naming the piece (design spec D.2): region count (fewer → pieces
+// joined), per-region hole counts sorted (any change → a slot closed or a mouth sealed),
+// arc count (fewer → an arc feature was consumed). `gap`, when known, is the piece's
+// narrowest opening (SheetFacts.gap) — the likeliest slot to have closed. kerf 0 returns
+// the SAME array: a zero kerf must be byte-identical to no kerf.
+export function applyKerf(regions, kerf, { label = "sheet part", gap = null } = {}) {
+  if (!(kerf > 0)) return regions;
+  const head = `${KIT_OPTIONS_ERROR} kerf ${kerf.toFixed(2)} mm`;
+  const intact = `${head} could not keep the outline of "${label}" intact — lower kerf, or set it to 0 and compensate in your laser software`;
+  let grown;
+  try {
+    grown = offsetRegions(regions, kerf / 2, { corners: "round" });
+  } catch (err) {
+    throw new Error(intact, { cause: err });
+  }
+  const out = grown.map((rg) => ({ outer: refitRing(closeContourGap(rg.outer)), holes: rg.holes.map((h) => refitRing(closeContourGap(h))) }));
+  if (out.length < regions.length) throw new Error(`${head} joins separate pieces of "${label}" — space them apart or lower kerf`);
+  if (out.length > regions.length) throw new Error(intact);
+  if (holeCounts(out) !== holeCounts(regions)) {
+    const slot = Number.isFinite(gap) ? `a ${gap.toFixed(2)} mm slot` : "a slot";
+    throw new Error(`${head} closes ${slot} in "${label}" — widen it or lower kerf`);
+  }
+  if (arcCount(out) < arcCount(regions)) throw new Error(intact);
+  return out;
+}

package/src/framework/export/dxf.js

@@ -0,0 +1,150 @@
+// The kit's DXF writer: a SheetDoc → one AutoCAD R12 (AC1009) DXF string, the dialect
+// every cutting service and laser package reads. A paper-free leaf (arc-math.js only).
+//
+// R12 has LINE, CIRCLE and the old two-part POLYLINE / VERTEX / SEQEND; it has no
+// LWPOLYLINE, no SPLINE and no HATCH, which fixes the whole mapping:
+//   - A closed ring is a closed POLYLINE. Its arcs ride as BULGES, tan(θ/4) with θ the
+//     signed sweep (positive = CCW), stored on the vertex that STARTS the segment — so
+//     the vertices are the start plus every segment's `to` except the last (which is
+//     the start again), and the closing segment's bulge sits on the final vertex.
+//   - A ring whose segments are ALL arcs on one centre and radius (relative 1e-6),
+//     sweeping ±360° in total, is a CIRCLE, whatever the arc count: recoverArcs hands a
+//     hole cut with cutAll back as three arcs, and a service quotes a CIRCLE as a hole.
+//   - A two-point open path (a score line) is a LINE.
+//   - A cubic is flattened to lines within FLATTEN_MM of the curve.
+//   - ENGRAVE carries outlines only (no HATCH in R12); the README says to set it to fill.
+// Units are mm ($INSUNITS 4 — an R12 reader may ignore it, which is why the README
+// prints a scale check per piece); y is NOT flipped, DXF is y-up like the Drawing.
+import { arcCenterAndSweep } from "../geometry/arc-math.js";
+import { placer } from "./placement.js";
+
+export const DXF_LAYERS = Object.freeze({ CUT: 1, SCORE: 5, ENGRAVE: 7 });   // layer → ACI colour
+const LAYER_FOR = Object.freeze({ engrave: "ENGRAVE", score: "SCORE", "cut-inner": "CUT", "cut-outer": "CUT" });
+const INCLUDE_FOR = Object.freeze({ engrave: "engrave", score: "score", "cut-inner": "cut", "cut-outer": "cut" });
+// The entity order is the cut order — drawing.js's LAYER_ORDER, which this leaf cannot
+// import (drawing.js reaches paper); test/kit-dxf.test.js pins them equal.
+const ORDER = Object.keys(LAYER_FOR);
+const INCLUDES = ["cut", "score", "engrave"];
+const TAU = 2 * Math.PI;
+const FLATTEN_MM = 0.01;
+const CIRCLE_REL = 1e-6;
+
+// DXF reals: fixed precision, -0 → 0, and always a decimal point (a bare "5" is legal,
+// but a strict reader of real-valued group codes may want "5.0").
+const fixed = (x, digits) => { const v = Number(x.toFixed(digits)); const s = String(v === 0 ? 0 : v); return s.includes(".") ? s : `${s}.0`; };
+const coord = (x) => fixed(x, 6);
+const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1]);
+
+// Distance from q to the SEGMENT a–b (not the infinite line: a cubic that overshoots an
+// endpoint is not flat).
+function segDist(q, a, b) {
+  const dx = b[0] - a[0], dy = b[1] - a[1], L2 = dx * dx + dy * dy;
+  const t = L2 < 1e-24 ? 0 : Math.max(0, Math.min(1, ((q[0] - a[0]) * dx + (q[1] - a[1]) * dy) / L2));
+  return Math.hypot(q[0] - (a[0] + t * dx), q[1] - (a[1] + t * dy));
+}
+
+// Points p1…pN (excluding p0) of a polyline within FLATTEN_MM of the cubic. The curve
+// lies inside its control polygon's convex hull, so it is within max(segDist(c1),
+// segDist(c2)) of the chord; split at t = ½ until that is small enough.
+function flattenCubic(p0, c1, c2, p1, depth = 0, out = []) {
+  if (depth >= 16 || Math.max(segDist(c1, p0, p1), segDist(c2, p0, p1)) <= FLATTEN_MM) { out.push(p1); return out; }
+  const mid = (a, b) => [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2];
+  const a = mid(p0, c1), b = mid(c1, c2), c = mid(c2, p1), d = mid(a, b), e = mid(b, c), m = mid(d, e);
+  flattenCubic(p0, a, d, m, depth + 1, out);
+  flattenCubic(m, e, c, p1, depth + 1, out);
+  return out;
+}
+
+// A path's segments as lines and arcs in its drawing frame: { to, dA } (dA 0 = a line),
+// arcs also carrying their centre and radius.
+function primitives(path) {
+  const out = [];
+  let from = path.start;
+  for (const s of path.segments) {
+    if (s.c1) for (const q of flattenCubic(from, s.c1, s.c2, s.to)) out.push({ to: q, dA: 0 });
+    else if (s.via) {
+      const g = arcCenterAndSweep(from, s.via, s.to);
+      out.push(g ? { to: s.to, dA: g.dA, center: g.center, r: g.r } : { to: s.to, dA: 0 });
+    } else out.push({ to: s.to, dA: 0 });
+    from = s.to;
+  }
+  return out;
+}
+
+function asCircle(prims) {
+  if (prims.length === 0 || prims.some((p) => !p.center)) return null;
+  const { center, r, dA } = prims[0];
+  const tol = CIRCLE_REL * r;
+  let sweep = 0;
+  for (const p of prims) {
+    if (Math.abs(p.r - r) > tol || dist(p.center, center) > tol || Math.sign(p.dA) !== Math.sign(dA)) return null;
+    sweep += p.dA;
+  }
+  return Math.abs(Math.abs(sweep) - TAU) <= 1e-6 ? { center, r } : null;
+}
+
+function writeEntity(g, layer, path, place) {
+  const prims = primitives(path);
+  if (!path.closed && prims.length === 1 && prims[0].dA === 0) {
+    const [x1, y1] = place(path.start), [x2, y2] = place(prims[0].to);
+    g(0, "LINE"); g(8, layer);
+    g(10, coord(x1)); g(20, coord(y1)); g(30, "0.0");
+    g(11, coord(x2)); g(21, coord(y2)); g(31, "0.0");
+    return;
+  }
+  const circle = path.closed ? asCircle(prims) : null;
+  if (circle) {
+    const [cx, cy] = place(circle.center);
+    g(0, "CIRCLE"); g(8, layer); g(10, coord(cx)); g(20, coord(cy)); g(30, "0.0"); g(40, coord(circle.r));
+    return;
+  }
+  const verts = [path.start, ...prims.map((p) => p.to)];
+  if (path.closed) verts.pop();                    // the last `to` is the start again
+  g(0, "POLYLINE"); g(8, layer); g(66, 1); g(10, "0.0"); g(20, "0.0"); g(30, "0.0"); g(70, path.closed ? 1 : 0);
+  verts.forEach((v, i) => {
+    const [x, y] = place(v);
+    g(0, "VERTEX"); g(8, layer); g(10, coord(x)); g(20, coord(y)); g(30, "0.0");
+    const dA = prims[i]?.dA ?? 0;                  // the segment this vertex starts (none after an open end)
+    if (dA !== 0) g(42, fixed(Math.tan(dA / 4), 10));
+  });
+  g(0, "SEQEND"); g(8, layer);
+}
+
+// `include` picks the layers: a cutting service gets one cut-only file per piece and a
+// separate marks file (["score", "engrave"]). Only the included layers are declared.
+export function renderDxf(doc, { include = INCLUDES } = {}) {
+  for (const inc of include)
+    if (!INCLUDES.includes(inc)) throw new Error(`renderDxf: include lists "cut", "score" and "engrave" only, got ${JSON.stringify(inc)}`);
+  const want = new Set(include);
+  const ids = ORDER.filter((id) => want.has(INCLUDE_FOR[id]));
+  const names = [...new Set(ids.map((id) => LAYER_FOR[id]))];
+  const out = [];
+  const g = (code, value) => { out.push(String(code).padStart(3), String(value)); };
+
+  g(0, "SECTION"); g(2, "HEADER");
+  g(9, "$ACADVER"); g(1, "AC1009");
+  g(9, "$INSUNITS"); g(70, 4);
+  g(0, "ENDSEC");
+
+  g(0, "SECTION"); g(2, "TABLES");
+  g(0, "TABLE"); g(2, "LTYPE"); g(70, 1);
+  g(0, "LTYPE"); g(2, "CONTINUOUS"); g(70, 0); g(3, "Solid line"); g(72, 65); g(73, 0); g(40, "0.0");
+  g(0, "ENDTAB");
+  g(0, "TABLE"); g(2, "LAYER"); g(70, names.length);
+  for (const name of names) { g(0, "LAYER"); g(2, name); g(70, 0); g(62, DXF_LAYERS[name]); g(6, "CONTINUOUS"); }
+  g(0, "ENDTAB");
+  g(0, "ENDSEC");
+
+  g(0, "SECTION"); g(2, "ENTITIES");
+  for (const id of ids) {
+    for (const placement of doc.placements) {
+      const layer = placement.drawing.layers.find((l) => l.id === id);
+      if (!layer) continue;
+      const place = placer(placement);
+      for (const path of layer.paths) writeEntity(g, LAYER_FOR[id], path, place);
+    }
+  }
+  g(0, "ENDSEC");
+  g(0, "EOF");
+  return `${out.join("\n")}\n`;
+}

package/src/framework/export/formats.js

@@ -0,0 +1,142 @@
+// The cut & print kit's option contract and the export-format table. IMPORT-FREE on
+// purpose: three very different readers load this file — the kit's lazy writers in the
+// worker, the runtime on the main thread (listExportFormats), and partforge-cloud, whose
+// coupling test imports KIT_OPTIONS_ERROR from "partforge" — and none of them may pay
+// for paper or a kernel to read a table (test/kit-export-guards.test.js holds it).
+//
+// validateKitOptions checks MEANING: enums, ranges, stock entries. A host's own inbound
+// validator checks only shape and size; that split is deliberate (design spec E.1), so
+// every refusal here is written for the person at the export dialog. Each one starts
+// with KIT_OPTIONS_ERROR, the prefix cloud routes to "Back to options" instead of
+// offering to have the assistant fix a part that is not broken.
+
+export const KIT_OPTIONS_ERROR = "cut kit options:";
+
+// Every format partforge can export. `needsSheet`: the format exists only when at least
+// one checked part is a sheet part (the kit). A host intersects this with its own table.
+export const EXPORT_FORMATS = Object.freeze([
+  Object.freeze({ id: "stl", label: "STL", ext: "stl", mime: "model/stl", needsSheet: false }),
+  Object.freeze({ id: "step", label: "STEP", ext: "step", mime: "application/step", needsSheet: false }),
+  Object.freeze({ id: "3mf", label: "3MF", ext: "3mf", mime: "model/3mf", needsSheet: false }),
+  Object.freeze({ id: "bundle", label: "Cut and print kit", ext: "zip", mime: "application/zip", needsSheet: true }),
+]);
+
+// Destination → the cut-file format it writes. Pinned equal to the laser descriptor's
+// `destinations` by test/kit-formats.test.js — two spellings of one fact.
+export const DESTINATIONS = Object.freeze({ "own-laser": "svg", service: "dxf" });
+
+// 300 × 300 mm until the paying user's machine is known (design spec decision 12).
+export const DEFAULT_STOCK_SIZE = Object.freeze([300, 300]);
+
+export const KIT_LIMITS = Object.freeze({
+  kerf: Object.freeze([0, 0.5]),
+  margin: Object.freeze([0, 50]),
+  // min 1 mm: two pieces never share a cut line (the laser would cut it twice).
+  spacing: Object.freeze([1, 50]),
+  sets: Object.freeze([1, 20]),
+  stockEntries: 20,
+  stockSide: Object.freeze([10, 3000]),
+  sheetsPerGroup: 50,
+  pieces: 200,
+});
+
+export const KIT_DEFAULTS = Object.freeze({
+  destination: "own-laser", kerf: 0, colors: "lightburn", stock: null,
+  margin: 5, spacing: 3, printFormat: "stl", sets: 1,
+});
+
+const OPTION_KEYS = ["destination", "cutFormat", "kerf", "colors", "stock", "margin", "spacing", "printFormat", "sets"];
+
+const fail = (message) => new Error(`${KIT_OPTIONS_ERROR} ${message}`);
+const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v)
+  && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+const inRange = (v, [lo, hi]) => typeof v === "number" && Number.isFinite(v) && v >= lo && v <= hi;
+
+// `undefined` means "all defaults" (a caller that sent no options at all); anything else
+// that is not a plain object is refused. Returns a fresh, fully populated object with
+// `cutFormat` derived from the destination.
+export function validateKitOptions(o) {
+  const opts = o === undefined ? {} : o;
+  if (!isPlainObject(opts)) throw fail("options must be an object");
+  for (const key of Object.keys(opts))
+    if (!OPTION_KEYS.includes(key)) throw fail(`unknown option "${key}" — the options are ${OPTION_KEYS.join(", ")}`);
+  const pick = (key) => (opts[key] === undefined ? KIT_DEFAULTS[key] : opts[key]);
+
+  const destination = pick("destination");
+  if (typeof destination !== "string" || !Object.hasOwn(DESTINATIONS, destination))
+    throw fail(`destination must be "own-laser" or "service", got ${JSON.stringify(destination)}`);
+  const cutFormat = DESTINATIONS[destination];
+  if (opts.cutFormat !== undefined && opts.cutFormat !== cutFormat)
+    throw fail(`cutFormat ${JSON.stringify(opts.cutFormat)} does not match destination "${destination}" (which writes ${cutFormat})`);
+
+  const kerf = pick("kerf");
+  if (!inRange(kerf, KIT_LIMITS.kerf))
+    throw fail(`kerf must be a number from ${KIT_LIMITS.kerf[0]} to ${KIT_LIMITS.kerf[1]} mm, got ${JSON.stringify(kerf)}`);
+  const colors = pick("colors");
+  if (colors !== "lightburn") throw fail(`colors must be "lightburn", got ${JSON.stringify(colors)}`);
+  const stock = normalizeStock(opts.stock);
+  const margin = pick("margin");
+  if (!inRange(margin, KIT_LIMITS.margin))
+    throw fail(`margin must be a number from ${KIT_LIMITS.margin[0]} to ${KIT_LIMITS.margin[1]} mm, got ${JSON.stringify(margin)}`);
+  const spacing = pick("spacing");
+  if (!inRange(spacing, KIT_LIMITS.spacing))
+    throw fail(`spacing must be a number from ${KIT_LIMITS.spacing[0]} to ${KIT_LIMITS.spacing[1]} mm, got ${JSON.stringify(spacing)}`);
+  const printFormat = pick("printFormat");
+  if (printFormat !== "stl" && printFormat !== "3mf")
+    throw fail(`printFormat must be "stl" or "3mf", got ${JSON.stringify(printFormat)}`);
+  const sets = pick("sets");
+  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 };
+}
+
+// null/undefined → null ("every group gets DEFAULT_STOCK_SIZE"); otherwise fresh
+// `{ group, size: [w, h] }` copies. A group key is sheetGroup()'s `"<material>|<t>"`, or
+// "*" for an explicit default — which groups exist is only known once the parts are
+// resolved, so matching happens later, in resolveStock.
+function normalizeStock(stock) {
+  if (stock === undefined || stock === null) return null;
+  if (!Array.isArray(stock)) throw fail("stock must be an array of { group, size: [w, h] }");
+  if (stock.length > KIT_LIMITS.stockEntries)
+    throw fail(`stock has ${stock.length} entries — at most ${KIT_LIMITS.stockEntries}`);
+  const seen = new Set();
+  return stock.map((entry, i) => {
+    const shaped = isPlainObject(entry) && Object.keys(entry).every((k) => k === "group" || k === "size")
+      && typeof entry.group === "string" && entry.group.length > 0
+      && Array.isArray(entry.size) && entry.size.length === 2;
+    if (!shaped) throw fail(`stock entry ${i + 1} needs a group and a size [w, h] in mm`);
+    const { group, size } = entry;
+    const [lo, hi] = KIT_LIMITS.stockSide;
+    if (!size.every((v) => inRange(v, KIT_LIMITS.stockSide)))
+      throw fail(`stock "${group}" size must be two numbers from ${lo} to ${hi} mm, got ${JSON.stringify(size)}`);
+    if (seen.has(group)) throw fail(`stock names "${group}" twice`);
+    seen.add(group);
+    return { group, size: [size[0], size[1]] };
+  });
+}
+
+// Match validated stock entries to the kit's groups (`[{ group, label }]`, definition
+// order; label = `${material} ${fmtMm(t)} mm`). Never a silent fallback: an entry naming
+// no group, or a group with neither its own entry nor a "*" default, is an options error
+// (design spec D.3). Returns group → [w, h].
+export function resolveStock(stock, groups) {
+  const sizes = new Map();
+  if (stock === null || stock === undefined) {
+    for (const { group } of groups) sizes.set(group, [DEFAULT_STOCK_SIZE[0], DEFAULT_STOCK_SIZE[1]]);
+    return sizes;
+  }
+  const known = new Set(groups.map((g) => g.group));
+  const byGroup = new Map();
+  for (const { group, size } of stock) {
+    if (group !== "*" && !known.has(group))
+      throw fail(`stock names "${group}", which no checked sheet part uses — the kit's groups are ${groups.map((g) => JSON.stringify(g.group)).join(", ")}`);
+    byGroup.set(group, size);
+  }
+  for (const { group, label } of groups) {
+    const size = byGroup.get(group) ?? byGroup.get("*");
+    if (!size) throw fail(`no stock size for "${group}" (${label}) — add a stock entry for it or a "*" default`);
+    sizes.set(group, [size[0], size[1]]);
+  }
+  return sizes;
+}