partforge 0.92.0 → 0.93.0

package/src/framework/geometry/vector-format.js

@@ -0,0 +1,334 @@
+// The `partforge-vector` JSON format: constants, validation, and the mapping to
+// and from this engine's internal region IR.
+//
+// This is a PUBLISHED format — agents read it, and (since ingest needs a
+// browser) may hand-write it — so it is explicit where the internal IR is
+// implicit. The internal IR infers a segment's type from which keys are present
+// (`c1` → cubic, `via` → arc, neither → line) and calls an arc's third point
+// `via`. Both are fine for code and hostile to anyone writing a file by hand, so
+// the JSON tags every segment with `kind` and names the arc point `through` —
+// "the arc passes through here", which `via` does not say.
+//
+// This file is the ONLY place the two vocabularies meet. Upstream speaks JSON,
+// downstream speaks the internal IR, and nothing else needs to know both.
+//
+// Pure leaf: DOM-free, node:-free. Both halves of the feature import it.
+import { profileBounds } from "./contour-ops.js";
+
+export const VECTOR_FORMAT = "partforge-vector";
+export const VECTOR_VERSION = 1;
+
+export const FORMAT_NOTE =
+  "Filled 2-D outlines for k.vector2d. `units` is \"mm\" (coordinates are millimetres, placed as "
+  + "authored) or \"artwork\" (no physical meaning; a size is required at every call site). `shapes` "
+  + "maps a name to a list of filled regions; each region's `outer` is its boundary and `holes` are "
+  + "subtracted from it. A contour is a `kind`: \"path\", \"circle\", \"rect\", or \"polygon\". Path "
+  + "segments run head-to-tail from `start`, and the contour closes implicitly from the last `to` "
+  + "back to `start`. y points UP. See docs/VECTOR-FORMAT.md.";
+
+const BBOX_TOL = 1e-3;        // mm-free: these are artwork units, and 6dp rounding is finer
+const ROUND = 1e6;            // 6 decimal places
+
+const round6 = (n) => Math.round(n * ROUND) / ROUND;
+const isPt = (v) => Array.isArray(v) && v.length === 2 && Number.isFinite(v[0]) && Number.isFinite(v[1]);
+const num = (v) => Number.isFinite(v);
+
+// Every message carries the vectors key and the position, because the reader is as
+// likely to be an agent that generated the file as a human who wrote it.
+const fail = (label, where, what, fix) => {
+  throw new Error(`vector2d: "${label}" ${where} ${what}${fix ? ` — ${fix}` : ""}`);
+};
+
+const EPS = 1e-12;
+const CONTOUR_KINDS = '"path", "circle", "rect", or "polygon"';
+
+// Every primitive expands to the SAME internal contour a hand-written "path"
+// would produce, right here at the JSON boundary. Nothing downstream —
+// placement, Shape2D, either backend, the exporters — knows primitives exist.
+//
+// circle and rect wind counter-clockwise by construction; polygon follows the
+// author's point order. None of them needs to know whether it is an outer or a
+// hole: ensureRegionWinding reorients from that label when the region is lifted
+// into a Shape2D, so stored winding carries no information.
+const expandCircle = ({ center: [cx, cy], r }) => ({
+  start: [cx + r, cy],
+  segments: [
+    { to: [cx - r, cy], via: [cx, cy + r] },
+    { to: [cx + r, cy], via: [cx, cy - r] },
+  ],
+});
+
+const expandRect = ({ center: [cx, cy], width, height, radius = 0 }) => {
+  const hw = width / 2, hh = height / 2;
+  if (!(radius > 0)) {
+    return { start: [cx - hw, cy - hh], segments: [
+      { to: [cx + hw, cy - hh] }, { to: [cx + hw, cy + hh] }, { to: [cx - hw, cy + hh] },
+    ] };
+  }
+  const r = radius, k = r / Math.SQRT2;
+  const start = [cx - hw + r, cy - hh];
+  const raw = [
+    { to: [cx + hw - r, cy - hh] },
+    { to: [cx + hw, cy - hh + r], via: [cx + hw - r + k, cy - hh + r - k] },
+    { to: [cx + hw, cy + hh - r] },
+    { to: [cx + hw - r, cy + hh], via: [cx + hw - r + k, cy + hh - r + k] },
+    { to: [cx - hw + r, cy + hh] },
+    { to: [cx - hw, cy + hh - r], via: [cx - hw + r - k, cy + hh - r + k] },
+    { to: [cx - hw, cy - hh + r] },
+    { to: [cx - hw + r, cy - hh], via: [cx - hw + r - k, cy - hh + r - k] },
+  ];
+  // At radius = min(w,h)/2 two (or four) edges collapse to a point. Emitting a
+  // zero-length line would hand a degenerate edge to the boolean engine.
+  const out = [];
+  let prev = start;
+  for (const seg of raw) {
+    if (!seg.via && Math.abs(seg.to[0] - prev[0]) < EPS && Math.abs(seg.to[1] - prev[1]) < EPS) continue;
+    out.push(seg);
+    prev = seg.to;
+  }
+  return { start, segments: out };
+};
+
+const expandPolygon = ({ points }) => ({
+  start: [...points[0]],
+  segments: points.slice(1).map((p) => ({ to: [...p] })),
+});
+
+function checkContour(label, where, c) {
+  if (!c || typeof c !== "object") fail(label, where, "is not an object");
+  if (typeof c.kind !== "string") {
+    fail(label, where, 'has no "kind"', `every contour needs a kind — ${CONTOUR_KINDS}`);
+  }
+  if (c.kind === "circle") {
+    if (!isPt(c.center)) fail(label, where, 'has "kind": "circle" but no valid "center"', "center must be an [x, y] pair of finite numbers");
+    if (!num(c.r) || c.r <= 0) fail(label, where, `has "kind": "circle" but a non-positive r (${JSON.stringify(c.r)})`, "r must be a finite number greater than 0");
+    return;
+  }
+  if (c.kind === "rect") {
+    if (!isPt(c.center)) fail(label, where, 'has "kind": "rect" but no valid "center"', "center must be an [x, y] pair of finite numbers");
+    for (const k of ["width", "height"]) {
+      if (!num(c[k]) || c[k] <= 0) fail(label, where, `has "kind": "rect" but a non-positive ${k} (${JSON.stringify(c[k])})`, `${k} must be a finite number greater than 0`);
+    }
+    if (c.radius != null) {
+      if (!num(c.radius) || c.radius < 0) fail(label, where, `has "kind": "rect" but an invalid radius (${JSON.stringify(c.radius)})`, "radius must be a finite number of 0 or more");
+      const max = Math.min(c.width, c.height) / 2;
+      if (c.radius > max) {
+        fail(label, where, `has "kind": "rect" with radius ${c.radius} exceeds the maximum ${round6(max)}`,
+          "a corner radius cannot be more than half the shorter side");
+      }
+    }
+    return;
+  }
+  if (c.kind === "polygon") {
+    if (!Array.isArray(c.points) || c.points.length < 3) {
+      fail(label, where, `has "kind": "polygon" with ${c.points?.length ?? 0} points`, "a polygon needs at least 3 points");
+    }
+    c.points.forEach((p, i) => { if (!isPt(p)) fail(label, `${where} point ${i + 1}`, "is not a valid [x, y] pair of finite numbers"); });
+    return;
+  }
+  if (c.kind !== "path") {
+    fail(label, where, `has unknown "kind": ${JSON.stringify(c.kind)}`, `kind must be ${CONTOUR_KINDS}`);
+  }
+  // "path" — the explicit form.
+  if (!isPt(c.start)) fail(label, where, 'has no valid "start"', "start must be a [x, y] pair of finite numbers");
+  if (!Array.isArray(c.segments) || c.segments.length === 0) {
+    fail(label, where, `has too few segments (${c.segments?.length ?? 0})`,
+      "a closed contour needs at least one segment; it closes implicitly from the last `to` back to `start`");
+  }
+  c.segments.forEach((s, i) => {
+    const at = `${where} segment ${i + 1}`;
+    if (!s || typeof s !== "object") fail(label, at, "is not an object");
+    if (!isPt(s.to)) fail(label, at, 'has no valid "to"', "every segment needs a `to` [x, y] pair of finite numbers");
+    if (s.kind === "line") return;
+    if (s.kind === "arc") {
+      if (!isPt(s.through)) {
+        fail(label, at, 'has "kind": "arc" but no valid "through" point',
+          "an arc needs a point it passes through, between the previous point and `to`");
+      }
+      return;
+    }
+    if (s.kind === "cubic") {
+      if (!isPt(s.c1)) fail(label, at, 'has "kind": "cubic" but no valid "c1"', "a cubic needs both control points, c1 and c2");
+      if (!isPt(s.c2)) fail(label, at, 'has "kind": "cubic" but no valid "c2"', "a cubic needs both control points, c1 and c2");
+      return;
+    }
+    fail(label, at, `has unknown "kind": ${JSON.stringify(s.kind)}`, 'kind must be "line", "arc", or "cubic"');
+  });
+  // How few segments can bound area? It depends on whether they are straight.
+  // Two straight edges plus the implicit closure is the fewest — a triangle. But
+  // ONE curved segment plus the closing chord bounds area perfectly well: that is
+  // a lens, a half-disc, a petal, and arc recovery produces exactly it (a filled
+  // half-disc arrives as two quarter-cubics, which merge into one ≤180° arc).
+  // A lone straight segment is the only single-segment contour that encloses
+  // nothing, because it and the closure are the same line.
+  if (c.segments.length === 1 && c.segments[0].kind === "line") {
+    fail(label, where, "has a single straight segment, which encloses no area",
+      "a straight-edged contour needs at least two segments — with the implicit closure that is a triangle, "
+      + "the fewest that can bound area. A single `arc` or `cubic` segment is fine: it bounds area against the closing chord");
+  }
+}
+
+export const VECTOR_UNITS = ["mm", "artwork"];
+
+const ROLES = ["add", "subtract"];
+
+// A shape is either a bare region array — the common case, role "add" — or
+// { role, regions }. Two forms rather than one because "add" is an honest
+// default: a painted region adds material, which is what every file written
+// before roles existed already meant.
+//
+// The default applies when `role` is ABSENT, not merely falsy — an explicit
+// `"role": null` (or any other present-but-wrong value) must fall through to
+// the unknown-role check below, not silently become "add". `"role" in v` is
+// safe here: the array branch has already returned, so `v` is a non-array
+// object (validateVectorDocument rejects a non-object shape value before
+// either caller of this function reaches a bare-object shape).
+const shapeParts = (v) => (Array.isArray(v) ? { role: "add", regions: v } : { role: "role" in v ? v.role : "add", regions: v.regions });
+
+export function validateVectorDocument(doc, label = "(unnamed)") {
+  if (!doc || typeof doc !== "object") fail(label, "file", "is not an object", "expected parsed JSON");
+  if (doc.format !== VECTOR_FORMAT) {
+    fail(label, "file", `has format ${JSON.stringify(doc.format)}`,
+      `expected ${JSON.stringify(VECTOR_FORMAT)} — this is not a partforge-vector file`);
+  }
+  // Floor as well as ceiling: version 0 and negatives used to load.
+  if (!Number.isInteger(doc.version) || doc.version < 1 || doc.version > VECTOR_VERSION) {
+    fail(label, "file", `has version ${JSON.stringify(doc.version)}`,
+      `this build understands version ${VECTOR_VERSION} — re-ingest the artwork, or upgrade partforge`);
+  }
+  if (!VECTOR_UNITS.includes(doc.units)) {
+    fail(label, "file", `has no valid \`units\` (${JSON.stringify(doc.units)})`,
+      '`units` must be "mm" (coordinates are millimetres, placed as authored) or "artwork" '
+      + "(coordinates have no physical meaning; a size is required at every call site)");
+  }
+  if (doc.note != null && typeof doc.note !== "string") fail(label, "file", "has a non-string `note`", "`note` is free text and is ignored on load");
+  if (doc.source != null && typeof doc.source !== "string") fail(label, "file", "has a non-string `source`", "`source` is provenance only and may be omitted");
+  // A stale draft in the pre-shapes envelope gets its own message rather than
+  // the generic "has no shapes", which would send the reader looking for a typo.
+  if (doc.shapes == null && Array.isArray(doc.regions)) {
+    fail(label, "file", 'has a "regions" array, which this build does not read',
+      'regions now live under a named shape in "shapes", e.g. { "shapes": { "artwork": [ …regions… ] } }');
+  }
+  const names = doc.shapes && typeof doc.shapes === "object" && !Array.isArray(doc.shapes) ? Object.keys(doc.shapes) : [];
+  if (names.length === 0) {
+    fail(label, "file", "has no shapes", 'a vector file needs at least one named shape: { "shapes": { "artwork": [ …regions… ] } }');
+  }
+  let anyAdd = false;
+  for (const name of names) {
+    const where = `shape ${JSON.stringify(name)}`;
+    const raw = doc.shapes[name];
+    if (!raw || typeof raw !== "object") fail(label, where, "is not an array of regions or a { role, regions } object");
+    const { role, regions } = shapeParts(raw);
+    if (!ROLES.includes(role)) {
+      fail(label, where, `has an unknown \`role\` ${JSON.stringify(role)}`,
+        '`role` must be "add" (the default, may be omitted) or "subtract"');
+    }
+    if (role === "add") anyAdd = true;
+    if (!Array.isArray(regions)) fail(label, where, "is not an array of regions");
+    if (regions.length === 0) fail(label, where, "is empty", "a shape needs at least one region");
+    regions.forEach((rg, i) => {
+      const at = `${where} region ${i + 1}`;
+      if (!rg || typeof rg !== "object") fail(label, at, "is not an object");
+      checkContour(label, `${at} outer`, rg.outer);
+      if (rg.holes != null && !Array.isArray(rg.holes)) fail(label, at, "has a non-array `holes`");
+      (rg.holes ?? []).forEach((h, j) => checkContour(label, `${at} hole ${j + 1}`, h));
+    });
+  }
+  if (!anyAdd) {
+    fail(label, "file", 'has no shape with role "add"',
+      "a file whose every shape subtracts composes to nothing — at least one shape must add material");
+  }
+
+  // bbox is a CACHE, not an authority: placement recomputes it anyway. It is
+  // OPTIONAL — an author should not have to compute analytic curve extrema to
+  // satisfy a checksum — but when a generator writes one, a stale value is a
+  // named error rather than silently wrong sizing at build time.
+  if (doc.bbox == null) return;
+  if (!["minX", "minY", "maxX", "maxY"].every((k) => Number.isFinite(doc.bbox[k]))) {
+    fail(label, "file", "has an invalid `bbox`", "bbox is optional, but when present it needs finite minX, minY, maxX, maxY");
+  }
+  const actual = regionsBbox(allRegionsUnchecked(doc));
+  for (const k of ["minX", "minY", "maxX", "maxY"]) {
+    if (Math.abs(actual[k] - doc.bbox[k]) > BBOX_TOL) {
+      fail(label, "file", `has a bbox that disagrees with its geometry (${k}: header ${doc.bbox[k]}, actual ${round6(actual[k])})`,
+        "re-ingest the artwork, or omit `bbox` — it is optional and recomputed either way");
+    }
+  }
+}
+
+const toSeg = (s) =>
+  s.kind === "arc" ? { to: [...s.to], via: [...s.through] }
+  : s.kind === "cubic" ? { to: [...s.to], c1: [...s.c1], c2: [...s.c2] }
+  : { to: [...s.to] };
+
+function toContour(c) {
+  if (c.kind === "circle") return expandCircle(c);
+  if (c.kind === "rect") return expandRect(c);
+  if (c.kind === "polygon") return expandPolygon(c);
+  const segments = c.segments.map(toSeg);
+  // A file may spell the implicit closure out. Dropping it here keeps one
+  // internal representation, so downstream never has to ask which form it got.
+  const last = segments.at(-1);
+  if (!last.via && !last.c1 && last.to[0] === c.start[0] && last.to[1] === c.start[1]) segments.pop();
+  return { start: [...c.start], segments };
+}
+
+const toRegion = (rg) => ({ outer: toContour(rg.outer), holes: (rg.holes ?? []).map(toContour) });
+
+const allRegionsUnchecked = (doc) =>
+  Object.values(doc.shapes).flatMap((v) => shapeParts(v).regions).map(toRegion);
+
+export function toInternalDocument(doc, label = "(unnamed)") {
+  validateVectorDocument(doc, label);
+  return {
+    units: doc.units,
+    shapes: new Map(Object.entries(doc.shapes).map(([name, v]) => {
+      const { role, regions } = shapeParts(v);
+      return [name, { role, regions: regions.map(toRegion) }];
+    })),
+  };
+}
+
+// Exported: vector2d.js needs the same tight bbox at build time, and two copies of
+// this loop would be two places to fix a bounds bug.
+//
+// Built on contour-ops.js's profileBounds — an EXACT bbox (paper.js computes a
+// curve's analytic extrema, not a sampled approximation) rather than the fixed
+// 64-segment tessellation this used to walk. That mattered in practice, not
+// just in theory: 64-segment sampling can undershoot a true arc extremum by
+// roughly 1.2e-3 × radius — comfortably past BBOX_TOL below — which meant a
+// hand-authored document with the mathematically CORRECT tight bbox could be
+// rejected by validateVectorDocument's "disagrees with its geometry" check.
+// profileBounds also folds in holes, which regions never needed excluded: a
+// hole is by construction inside its own outer, so its bounds can only sit
+// within the outer's and never move minX/minY/maxX/maxY.
+export function regionsBbox(regions) {
+  if (regions.length === 0) return { minX: Infinity, minY: Infinity, maxX: -Infinity, maxY: -Infinity };
+  const { min, max } = profileBounds(regions);
+  return { minX: min[0], minY: min[1], maxX: max[0], maxY: max[1] };
+}
+
+const fromSeg = (s) =>
+  s.via ? { kind: "arc", to: [round6(s.to[0]), round6(s.to[1])], through: [round6(s.via[0]), round6(s.via[1])] }
+  : s.c1 ? { kind: "cubic", to: [round6(s.to[0]), round6(s.to[1])],
+             c1: [round6(s.c1[0]), round6(s.c1[1])], c2: [round6(s.c2[0]), round6(s.c2[1])] }
+  : { kind: "line", to: [round6(s.to[0]), round6(s.to[1])] };
+
+const fromContour = (c) => ({
+  kind: "path",
+  start: [round6(c.start[0]), round6(c.start[1])],
+  segments: c.segments.map(fromSeg),
+});
+
+export function fromInternalRegions(regions, { source = null, units = "artwork", shape = "artwork" } = {}) {
+  const bb = regionsBbox(regions);
+  return {
+    format: VECTOR_FORMAT,
+    version: VECTOR_VERSION,
+    units,
+    note: FORMAT_NOTE,
+    source,
+    bbox: { minX: round6(bb.minX), minY: round6(bb.minY), maxX: round6(bb.maxX), maxY: round6(bb.maxY) },
+    shapes: { [shape]: regions.map((rg) => ({ outer: fromContour(rg.outer), holes: (rg.holes ?? []).map(fromContour) })) },
+  };
+}

package/src/framework/geometry/vector2d.js

@@ -0,0 +1,96 @@
+// Place ingested vector regions: one uniform scale about the document origin,
+// then an alignment translate. That is the entire runtime half of k.vector2d —
+// everything else happened once, at ingest.
+//
+// Both steps default to no-ops for millimetre files: an mm file's coordinates
+// already mean something, so "as authored" (scale 1, no translate) is the
+// identity. Artwork units carry no physical meaning, so a size is required and
+// the artwork is re-centred by default — that half is unchanged from before
+// units existed at all.
+//
+// The transform is uniform by construction, so arcs stay arcs and the OCCT
+// backend still gets true circular B-rep edges.
+//
+// Pure leaf: DOM-free, node:-free.
+import { regionsBbox } from "./vector-format.js";
+
+const EXTENT_EPS = 1e-9;
+const ALIGN = new Set(["left", "center", "right"]);
+const VALIGN = new Set(["bottom", "middle", "top"]);
+const SIZE_KEYS = ["width", "height", "fit"];
+
+// Same lead as vector-format.js's `fail()`, and for the same reason: the format
+// doc promises, without qualification, that every error names the part's declared
+// `vectors` key. The errors below are the ones a new author hits MOST — they are
+// call-shape mistakes, not file mistakes — and they used to be the only ones with
+// no name in them, leaving an agent authoring cold to bisect its own call sites.
+const bad = (name, what) => { throw new Error(`vector2d: "${name}" ${what}`); };
+
+function scaleFor(opts, units, w, h, name) {
+  const given = SIZE_KEYS.filter((k) => opts[k] != null);
+  if (given.length > 1) {
+    bad(name, `pass only one of width, height, or fit — got ${given.join(", ")}`);
+  }
+  if (given.length === 0) {
+    // Millimetre coordinates already mean something; artwork units do not, so
+    // there is no honest default for artwork. (k.text2d can default `size`
+    // because a cap height is a real measurement; an SVG viewBox unit is not.)
+    if (units === "mm") return 1;
+    bad(name, "a size is required for artwork units — pass one of { width }, { height }, or { fit } in millimetres");
+  }
+  const [key] = given;
+  const v = opts[key];
+  if (!(Number.isFinite(v) && v > 0)) bad(name, `${key} must be a positive number of millimetres`);
+  const extent = key === "width" ? w : key === "height" ? h : Math.max(w, h);
+  if (!(extent > EXTENT_EPS)) bad(name, `artwork has no ${key === "fit" ? "extent" : key} to size against`);
+  return v / extent;
+}
+
+const place = (c, s, dx, dy) => {
+  const T = ([x, y]) => [x * s + dx, y * s + dy];
+  return {
+    start: T(c.start),
+    segments: c.segments.map((seg) => {
+      const m = { to: T(seg.to) };
+      if (seg.via) m.via = T(seg.via);
+      if (seg.c1) { m.c1 = T(seg.c1); m.c2 = T(seg.c2); }
+      return m;
+    }),
+  };
+};
+
+// `measureAgainst` is the region set the transform is DERIVED from; `regions` is
+// what it is applied to. They differ in exactly one case: a role-composed call,
+// where the "add" group and the "subtract" group are placed by separate calls but
+// must land on ONE transform. Measuring each group against its own bounds instead
+// scales the subtracts relative to the adds — silently, since the adds still
+// govern the composed bbox — which is a wrong-geometry bug, not a wrong-size one.
+// Selecting a single shape with { shape } deliberately keeps the default: you
+// asked for that shape, so it is sized against its own bounds.
+//
+// `name` is the part's declared `vectors` key, carried only so the errors above
+// can say which document the bad call was for.
+export function placeRegions(regions, units, opts = {}, { measureAgainst = regions, name = "(unnamed)" } = {}) {
+  // An mm file places where it was drawn; only artwork has to be re-centred,
+  // because its own coordinates mean nothing. `null` here is "no translate" —
+  // distinct from `align: "center"`, which does translate (to the origin).
+  const align = opts.align ?? (units === "mm" ? null : "center");
+  const valign = opts.valign ?? (units === "mm" ? null : "middle");
+  // No silent default for a bad value: align/valign each pick their branch by
+  // string equality below, and any value that fails all three comparisons
+  // (a typo — "centre" for "center" — or any other garbage) would otherwise
+  // fall through to the middle/center case with no error, placing the artwork
+  // somewhere the caller never asked for. Every other op in this feature
+  // refuses instead of guessing (scaleFor above, right on this same function);
+  // this closes the one silent-default gap.
+  if (align != null && !ALIGN.has(align)) bad(name, `align must be "left", "center", or "right" — got ${JSON.stringify(align)}`);
+  if (valign != null && !VALIGN.has(valign)) bad(name, `valign must be "bottom", "middle", or "top" — got ${JSON.stringify(valign)}`);
+  const { minX, minY, maxX, maxY } = regionsBbox(measureAgainst);
+  const s = scaleFor(opts, units, maxX - minX, maxY - minY, name);
+  const dx = align == null ? 0 : align === "left" ? -minX * s : align === "right" ? -maxX * s : -((minX + maxX) / 2) * s;
+  const dy = valign == null ? 0 : valign === "bottom" ? -minY * s : valign === "top" ? -maxY * s : -((minY + maxY) / 2) * s;
+  return regions.map((r) => ({
+    outer: place(r.outer, s, dx, dy),
+    holes: r.holes.map((c) => place(c, s, dx, dy)),
+  }));
+}

package/src/framework/ingest/svg-ingest.js

@@ -0,0 +1,212 @@
+// SVG -> the partforge-vector JSON format. The browser half of k.vector2d, run ONCE
+// per artwork by the host — never at build time, never in the geometry worker.
+//
+// This is the ONLY DOM-dependent file in the feature, and that is the whole
+// point: with a real DOM, paper.js's importSVG does the work six hand-rolled
+// modules would otherwise do. It bakes ancestor transforms into coordinates,
+// resolves per-item style, and handles <use>, <defs> and CSS — none of which a
+// DOM-free parser could reach.
+//
+// Never import this from the worker graph. test/worker-layering.test.js proves
+// you have not: it walks the worker's import closure and fails on any module
+// that so much as names `document`.
+import paper from "paper/dist/paper-core.js";
+import { toContour, toOpenContour, booleanRegions } from "../geometry/paper-bridge.js";
+import { resolveCurveFill } from "../geometry/curve-fill.js";
+import { outlineStroke } from "../geometry/stroke-outline.js";
+import { recoverArcs } from "../geometry/arc-fit.js";
+import { fromInternalRegions, validateVectorDocument } from "../geometry/vector-format.js";
+import { reverseContour } from "../geometry/profile.js";
+
+// A private scope, never paper's package-global project — another consumer in
+// the same page may import paper too. Same rule paper-bridge.js follows.
+let _scope = null;
+function scope() {
+  if (!_scope) { _scope = new paper.PaperScope(); _scope.setup(new _scope.Size(1, 1)); }
+  return _scope;
+}
+
+// SVG is y-down; the model frame is y-up. Applied after paper has baked
+// transforms and before arc recovery, so everything downstream is in one frame.
+const flipContourRaw = (c) => ({
+  start: [c.start[0], -c.start[1]],
+  segments: c.segments.map((s) => {
+    const m = { to: [s.to[0], -s.to[1]] };
+    if (s.via) m.via = [s.via[0], -s.via[1]];
+    if (s.c1) { m.c1 = [s.c1[0], -s.c1[1]]; m.c2 = [s.c2[0], -s.c2[1]]; }
+    return m;
+  }),
+});
+
+// Negating y REVERSES orientation, so every contour must also be reversed to
+// restore the storage winding invariant (outer CCW, holes CW in the y-up frame)
+// that contour-offset.js and contour-winding.js depend on. Without the reverse
+// this silently emits outers as CW and holes as CCW, and a later offset would
+// grow holes and shrink outers with no crash and no error.
+const flipContour = (c) => reverseContour(flipContourRaw(c));
+
+const flipRegion = (r) => ({ outer: flipContour(r.outer), holes: r.holes.map(flipContour) });
+
+// A paper Path/CompoundPath -> this engine's contours, one per subpath.
+function itemContours(item) {
+  const paths = item.className === "CompoundPath" ? item.children : [item];
+  return paths
+    .filter((p) => p.segments && p.segments.length >= 2)
+    .map((p) => ({ contour: p.closed ? toContour(p) : toOpenContour(p), closed: !!p.closed }));
+}
+
+const LINECAP = { butt: "butt", round: "round", square: "square" };
+const LINEJOIN = { miter: "miter", round: "round", bevel: "bevel" };
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+const XLINK_NS = "http://www.w3.org/1999/xlink";
+
+// paper's <use> importer (paper-core.js's `use:` entry) resolves its target
+// through `SvgElement.get(node, "href")`, which is hard-wired to read that
+// attribute from the XLINK namespace ONLY (`attributeNamespace.href = xlink`
+// in paper-core.js). A bare SVG2 `href="#id"` — what every modern authoring
+// tool emits — lives in no namespace at all, so `getAttributeNS(xlink, href)`
+// returns null and the `<use>` silently resolves to nothing. This is true in
+// any DOM, real browser included; it is not a test-environment gap. Patch it
+// ourselves before handing the tree to paper: mirror a bare `href` onto
+// `xlink:href` on every `<use>` that doesn't already have one. Do this by
+// parsing the markup into a real DOM tree (paper's importSVG accepts a node
+// as readily as a string) rather than string-munging the SVG text, so this
+// survives whatever quoting/whitespace the source happens to use.
+function normalizeUseHref(svgText) {
+  const doc = new DOMParser().parseFromString(svgText, "image/svg+xml");
+  const uses = doc.getElementsByTagNameNS(SVG_NS, "use");
+  for (let i = 0; i < uses.length; i++) {
+    const use = uses[i];
+    if (use.hasAttribute("href") && !use.hasAttributeNS(XLINK_NS, "href")) {
+      use.setAttributeNS(XLINK_NS, "xlink:href", use.getAttribute("href"));
+    }
+  }
+  return doc;
+}
+
+export function ingestSvg(svgText, { strokes = "outline", source = null } = {}) {
+  if (typeof svgText !== "string" || !svgText.trim()) {
+    throw new Error("svg: ingestSvg needs the SVG document as a non-empty string");
+  }
+  const sc = scope();
+  let root;
+  try {
+    root = sc.project.importSVG(normalizeUseHref(svgText), { expandShapes: true, insert: false });
+  } catch (e) {
+    throw new Error(`svg: could not parse the SVG document — ${e?.message ?? e}`);
+  }
+  if (!root) throw new Error("svg: could not parse the SVG document");
+
+  const resolved = [];
+  const visit = (item) => {
+    // A <use> that resolves to a <symbol> (rather than a plain element)
+    // imports as a paper SymbolItem, not a Group/Path — paper keeps the
+    // symbol's geometry in one shared SymbolDefinition and never clones it
+    // per <use>, so it has no .children and no .segments of its own and
+    // would otherwise fall straight through to the `return` below, silently
+    // contributing nothing. Unwrap it: clone the definition's item and bake
+    // this particular <use>'s placement matrix into the clone, then recurse
+    // into the (now ordinary) Group/Path. Note that fill/stroke set directly
+    // on the <use> element does NOT carry over — paper resolves each
+    // element's paint from the real DOM's computed style at that element's
+    // own position in the document, and a <symbol>'s content is parsed once
+    // as a *sibling* of <use>, never as its descendant, so paint must live on
+    // the symbol's own shapes (or an ancestor they actually share).
+    if (item.className === "SymbolItem") {
+      const inner = item.definition.item.clone();
+      // A SymbolDefinition's item is kept with applyMatrix=false — its shared
+      // geometry stays in LOCAL coordinates and each SymbolItem carries only
+      // its own placement matrix, so multiple <use>s of one <symbol> reuse
+      // one set of segment points. item.transform(item.matrix) would only
+      // update the clone's own decomposed matrix, not its segments — every
+      // placement would then read back the same untransformed local points.
+      // append + apply(true, true) bakes the placement into real segment
+      // coordinates (recursively, and flips applyMatrix to true on the way),
+      // which is what itemContours/toContour below actually read.
+      inner.matrix.append(item.matrix);
+      inner.matrix.apply(true, true);
+      visit(inner);
+      return;
+    }
+    // A CompoundPath has .children too (its subpaths), but it is ONE paintable
+    // item — recursing into its children would split it into independent
+    // single-subpath items and lose the fill-rule relationship between them
+    // (e.g. the counter of an "O" would stop being a hole). Only Groups and
+    // Layers get walked; CompoundPath and Path are both handled as leaves.
+    if (item.className !== "CompoundPath" && item.children && item.children.length) {
+      item.children.forEach(visit);
+      return;
+    }
+    if (!item.segments && item.className !== "CompoundPath") return;   // the root clip Shape lands here
+
+    const subpaths = itemContours(item);
+    if (subpaths.length === 0) return;
+
+    // Colour is read only as present-or-absent: this produces geometry, not paint.
+    if (item.fillColor) {
+      // Per ITEM, not per subpath: a fill rule applies across an item's own
+      // subpaths, which is what makes the counter of an "O" a hole.
+      resolved.push(...resolveCurveFill(subpaths.map((s) => s.contour),
+        { fillRule: item.fillRule === "evenodd" ? "evenodd" : "nonzero" }));
+    }
+    if (strokes !== "ignore" && item.strokeColor && item.strokeWidth > 0) {
+      const style = {
+        strokeWidth: item.strokeWidth,
+        linecap: LINECAP[item.strokeCap] ?? "butt",
+        linejoin: LINEJOIN[item.strokeJoin] ?? "miter",
+      };
+      // Per SUBPATH: each is stroked on its own, with its own open/closed sense.
+      for (const { contour, closed } of subpaths) resolved.push(...outlineStroke(contour, closed, style));
+    }
+  };
+  visit(root);
+
+  if (resolved.length === 0) {
+    throw new Error('svg: no painted geometry — every element is fill="none" with no stroke, hidden, or empty');
+  }
+
+  // One union across every item. `resolved` entries are already RESOLVED
+  // regions (each item's own fill/stroke geometry, holes included) — folding
+  // them together needs an actual planar boolean union, not another
+  // resolveCurveFill("nonzero") pass over the flattened contour list: paper's
+  // `compound.unite(compound)` self-unite trick (which resolveCurveFill uses
+  // internally to normalize crossings under a fill rule) special-cases the
+  // "unite with itself" call and does not correctly union two *disjoint*
+  // same-winding shapes — two overlapping same-fill rects came back with the
+  // overlap cancelled (evenodd-shaped) instead of merged, undercounting the
+  // union's area. booleanRegions performs a real A.unite(B) between distinct
+  // paper compound paths per pair, which does not hit that case, and it
+  // already carries the storage winding invariant on its output.
+  let union = [];
+  for (const r of resolved) union = booleanRegions(union, [r], "unite");
+  if (union.length === 0) throw new Error("svg: geometry cancelled to nothing under the fill rule");
+
+  const flipped = union.map(flipRegion);
+  const withArcs = flipped.map((r) => ({ outer: recoverArcs(r.outer), holes: r.holes.map(recoverArcs) }));
+  // fromInternalRegions rounds every coordinate to 6dp itself when it serializes
+  // the document, and computes doc.bbox (regionsBbox, vector-format.js) from
+  // these UNROUNDED regions first — an EXACT bbox (paper.js's analytic curve
+  // bounds), not the fixed-step tessellation this file used to have to
+  // pre-round coordinates to work around: that old sampling grid could shift
+  // an extremum by ~1e-3 on an unrounded-vs-rounded ULP nudge, which is gone
+  // now that the bbox check isn't sampling a grid at all.
+  const doc = fromInternalRegions(withArcs, { source, units: "artwork", shape: "artwork" });
+  // Ingest must never emit a document its own loader refuses. It used to: a
+  // filled half-disc reduced to a ONE-segment contour (the implicit chord is
+  // dropped, and arc recovery merged two quarter-cubics into a single ≤180°
+  // arc) and validateVectorDocument then required two. The file wrote fine and
+  // died at the first build that touched it, telling the author to hand-edit a
+  // generated file the docs say never to hand-edit.
+  //
+  // The rule was the wrong one and is fixed, but the CLASS of bug is closed
+  // here: this is the reference implementation VECTOR-FORMAT.md invites third
+  // parties to diff against, so the loader's own gate runs on the way out. A
+  // throw here is a partforge bug, not an author's — say so.
+  try {
+    validateVectorDocument(doc, source ?? "(ingested)");
+  } catch (e) {
+    throw new Error(`svg: ingest produced a document this build cannot load — that is a partforge bug, please report it with the SVG.\n  ${e.message}`);
+  }
+  return doc;
+}