partforge 0.91.0 → 0.93.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.91.0",
+  "version": "0.93.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",
@@ -21,6 +21,7 @@
     "docs/AUTHORING-PARTS.md",
     "docs/ERROR-PATTERNS.md",
     "docs/KERNEL-CONTRACT.md",
+    "docs/VECTOR-FORMAT.md",
     "README.md"
   ],
   "types": "./types/index.d.ts",
@@ -53,6 +54,10 @@
       "types": "./types/testing.d.ts",
       "default": "./src/testing.js"
     },
+    "./ingest": {
+      "types": "./types/ingest.d.ts",
+      "default": "./src/ingest.js"
+    },
     "./tokens.css": "./src/framework/tokens.css",
     "./chrome.css": "./src/framework/chrome.css"
   },
@@ -75,6 +80,9 @@
       ],
       "testing": [
         "./types/testing.d.ts"
+      ],
+      "ingest": [
+        "./types/ingest.d.ts"
       ]
     }
   },

package/src/app-emblem.js

@@ -0,0 +1,15 @@
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
+import emblemPart from "./parts/emblem.js";
+import { mount } from "./framework/index.js";
+
+// Dev-only example app for the emblem part (the k.vector2d reference).
+// `npm run dev`, then open /emblem.html.
+window.__pfRuntime = mount(emblemPart, {
+  createWorker: (name) =>
+    new Worker(new URL("./emblem-worker.js", import.meta.url), { type: "module", name }),
+  onAnnotationSend: (payload) => {
+    window.__pfLastAnnotation = payload;
+    console.log("annotation payload", payload);
+  },
+});

package/src/emblem-worker.js

@@ -0,0 +1,3 @@
+import part from "./parts/emblem.js";
+import { runWorker } from "./framework/worker.js";
+runWorker(part);

package/src/framework/asset-resolve.js

@@ -1,11 +1,12 @@
-// Shared source-resolution core for fonts.js and imports.js. Both resolve a
+// Shared source-resolution core for fonts.js, imports.js, and vectors.js. All three resolve a
 // part's declared `{ name: source }` map before the synchronous build, where a
 // source is: an ArrayBuffer/typed-array view (bytes), a URL string, a `URL`
 // instance (fetched), or a thunk (possibly async) returning any of those —
 // including the `{ default: … }` shape a Vite dynamic `import('./x.ttf')`
-// yields. The two callers differ only in what they do with the resolved bytes
-// (fonts keep the raw ArrayBuffer; imports also stamp a digest + format), so
-// each owns its own cache Map and result shape; this module owns just the
+// yields. The three callers differ only in what they do with the resolved bytes
+// (fonts keep the raw ArrayBuffer; imports also stamp a digest + format; vectors
+// parses the bytes as a partforge-vector document), so each owns its own cache
+// Map and result shape; this module owns just the
 // source→bytes grammar and the identity-memoization rule (a source, e.g. a
 // thunk, is content-stable for a session — resolve it once). DOM-free and
 // node:-free so it stays safe in the geometry worker's import closure.

package/src/framework/geometry/arc-fit.js

@@ -0,0 +1,146 @@
+// Circular-arc recovery: runs of cubic segments that lie on a common circle
+// become symbolic {to, via} arcs.
+//
+// paper.js has no arc primitive, so importSVG returns every curve as a cubic —
+// a <circle> arrives as four of them. Without this pass the OCCT backend would
+// build a spline where the artwork had a circle. Recovering at the CONTOUR level
+// rather than special-casing <circle> means arcs from `A` commands, rounded-rect
+// corners, and transformed circles all come back through one mechanism.
+//
+// The fit is exact, not approximate. Paper's kappa construction pins each
+// cubic's ENDPOINTS to the true circle and only the interior deviates, so a
+// three-point fit through endpoints recovers the original centre and radius to
+// float precision. The tolerances are therefore an acceptance test on the
+// interiors, not the accuracy of the result — see runFits for why there are two
+// of them and why a radius-relative one alone is not enough.
+//
+// Pure leaf: DOM-free, node-free.
+import { arcCenterAndSweep } from "./paper-bridge.js";
+import { cubicAt } from "./contour-ops.js";
+
+const ARC_TOL = 1e-3;            // relative to the FITTED radius
+const CHORD_TOL = 2e-3;          // relative to each cubic's OWN chord — see runFits
+const PROBE_TS = [0.125, 0.25, 0.375, 0.5, 0.625, 0.75, 0.875];
+const MAX_SWEEP = Math.PI;       // split arcs at 180° so the 3-point form stays unambiguous
+
+const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1]);
+
+// Does every probed interior point of every cubic in `run` lie on the circle?
+//
+// TWO bounds, and the tighter one wins. `ARC_TOL * r` alone is not a usable
+// acceptance test, because r is the FITTED radius: the flatter a curve is, the
+// bigger the circle it fits, so the band grows without limit exactly where the
+// author's own feature is smallest. A gentle asymmetric cubic — the single most
+// common thing in real logo artwork — fitted a circle of r = 913 and was accepted
+// with a maximum deviation of 0.70 against its own sagitta of 1.43. Half the
+// curve's depth, silently, and the stored file then claimed `"kind": "arc"`, so
+// nothing downstream could recover the intent.
+//
+// The second bound is relative to the cubic's own CHORD — the straight distance
+// between its endpoints. Chord is the right base rather than sagitta because it
+// stays finite and meaningful as the curve flattens (sagitta goes to zero, which
+// would reject genuine shallow arcs) and never degenerates on a closed run (the
+// whole run's chord does: a full circle's endpoints coincide). It is a scale the
+// artwork actually has, and it does not move when the fit does.
+//
+// CHORD_TOL is set with real headroom over what genuine circles need. Paper's
+// kappa construction pins each cubic's endpoints to the true circle and errs only
+// in the interior, by about 2.7e-4 * r for a 90° cubic and far less for shallower
+// ones. Measured against this module's own fit, over sweeps of 1°-90° and radii
+// from 0.5 to 1e5, the worst genuine deviation is 1.83e-4 of chord — so 2e-3
+// leaves an 11x margin. The two shallow non-circular cubics that used to be
+// accepted deviate by 3.1e-3 and 6.8e-3 of chord, comfortably outside it.
+function runFits(run, from, center, r) {
+  let p = from;
+  for (const s of run) {
+    const tol = Math.min(ARC_TOL * r, CHORD_TOL * dist(p, s.to));
+    for (const t of PROBE_TS) {
+      const q = cubicAt(p, s.c1, s.c2, s.to, t);
+      if (Math.abs(dist(q, center) - r) > tol) return false;
+    }
+    p = s.to;
+  }
+  return true;
+}
+
+// Fit through the run's first, middle and last ENDPOINT — all exact on the
+// source circle. A two-cubic run has three endpoints and uses them directly.
+// A one-cubic run has only two endpoints, so the three-point fit would
+// degenerate (the "middle" point would just be the last point again); use the
+// cubic's own midpoint instead. That point is NOT exact on the circle (it's
+// off by paper's kappa error), so the resulting centre/radius are only
+// approximate for a still-unextended single-cubic run — but they're accurate
+// enough to pass runFits's tolerance, and any later join with a second
+// segment re-fits through three real endpoints and recovers the exact circle.
+function fitCircle(run, from) {
+  const pts = [from, ...run.map((s) => s.to)];
+  const mid = pts.length >= 3
+    ? pts[Math.floor(pts.length / 2)]
+    : cubicAt(from, run[0].c1, run[0].c2, run[0].to, 0.5);
+  const c = arcCenterAndSweep(pts[0], mid, pts.at(-1));
+  if (!c || !Number.isFinite(c.r) || c.r <= 0) return null;
+  return c;
+}
+
+// One arc from `from` to `to` about `center`, split so no piece exceeds 180°.
+// `via` is placed at each piece's angular midpoint, which is what makes the
+// three-point form recoverable.
+function arcsBetween(from, to, center, r, sweepSign) {
+  const ang = (p) => Math.atan2(p[1] - center[1], p[0] - center[0]);
+  const a0 = ang(from);
+  let dA = ang(to) - a0;
+  const twoPi = 2 * Math.PI;
+  while (dA <= 0) dA += twoPi;
+  while (dA > twoPi) dA -= twoPi;
+  if (sweepSign < 0) dA -= twoPi;
+  const pieces = Math.max(1, Math.ceil(Math.abs(dA) / MAX_SWEEP - 1e-9));
+  const out = [];
+  for (let i = 0; i < pieces; i++) {
+    const s0 = a0 + dA * (i / pieces), s1 = a0 + dA * ((i + 1) / pieces);
+    const m = (s0 + s1) / 2;
+    const P = (t) => [center[0] + r * Math.cos(t), center[1] + r * Math.sin(t)];
+    out.push({ to: P(s1), via: P(m) });
+  }
+  out.at(-1).to = [to[0], to[1]];    // pin the exact endpoint
+  return out;
+}
+
+// The direction the run actually travels, from the first cubic's own geometry.
+function sweepSignOf(run, from, center) {
+  const a = [from[0] - center[0], from[1] - center[1]];
+  const q = cubicAt(from, run[0].c1, run[0].c2, run[0].to, 0.5);
+  const b = [q[0] - center[0], q[1] - center[1]];
+  return a[0] * b[1] - a[1] * b[0] >= 0 ? 1 : -1;
+}
+
+export function recoverArcs(contour) {
+  const segs = contour.segments;
+  const out = [];
+  let from = contour.start;
+  let i = 0;
+
+  while (i < segs.length) {
+    if (!segs[i].c1) { out.push(segs[i]); from = segs[i].to; i++; continue; }
+
+    // Greedy: extend the cubic run while it still fits one circle.
+    const runFrom = from;
+    let best = null, bestEnd = i;
+    let j = i;
+    while (j < segs.length && segs[j].c1) {
+      const run = segs.slice(i, j + 1);
+      const c = fitCircle(run, runFrom);
+      if (c && runFits(run, runFrom, c.center, c.r)) { best = c; bestEnd = j; }
+      j++;
+    }
+
+    if (!best) { out.push(segs[i]); from = segs[i].to; i++; continue; }
+
+    const run = segs.slice(i, bestEnd + 1);
+    const end = run.at(-1).to;
+    out.push(...arcsBetween(runFrom, end, best.center, best.r, sweepSignOf(run, runFrom, best.center)));
+    from = end;
+    i = bestEnd + 1;
+  }
+
+  return { start: [...contour.start], segments: out };
+}

package/src/framework/geometry/contour-offset.js

@@ -126,6 +126,11 @@ function joinSegs(corner, aEnd, bStart, inTan, outTan, delta, corners) {
   return [{ via: add(corner, scl(norm(m), Math.abs(delta))), to: bStart }];
 }
 
+// Exposed for stroke-outline.js, which walks OPEN chains and so cannot use
+// _offsetContour's ring loop, but needs exactly this join vocabulary
+// (round/chamfer/sharp + miter limit) at its interior vertices.
+export const _joinSegs = joinSegs;
+
 // Offset one explicitly-closed ring. Returns { contour, dirty }.
 export function _offsetContour(contour, delta, corners) {
   const pts = [contour.start, ...contour.segments.map((s) => s.to)];

package/src/framework/geometry/curve-fill.js

@@ -2,11 +2,49 @@
 // simple, correctly-nested {outer,holes} curve regions under the requested font fill
 // rule. Beziers are split where needed but never flattened.
 //
-// The required recipe is:
-//   1. resolveCrossings() each contour individually;
-//   2. CompoundPath of all the simple sub-paths;
-//   3. set the font's nonzero/evenodd rule;
-//   4. unite(self) to normalize overlaps and crossings into simple paths.
+// TWO ROUTES, because paper.js cannot evaluate either fill rule directly on a
+// self-overlapping CompoundPath.
+//
+// The original recipe was: build a CompoundPath of every subpath, set its
+// fillRule, and unite it with itself. paper documents that trick and it resolves
+// NESTING correctly — a counter drawn against its outline becomes a hole, which
+// is what every glyph relies on. But it does not merge two subpaths that wind
+// the SAME way and overlap: it returns the even-odd answer regardless of the
+// fillRule set. Measured on two 10x10 squares overlapping in a 5x10 band, as two
+// subpaths of one <path>: area 100 (the band cancelled) where nonzero is 150.
+// Measured identical for both orientations, and for every compound-level variant
+// tried — unite against a clone, unite against an empty path, intersect with a
+// covering rectangle, resolveCrossings on the compound, reorient after it.
+//
+// So:
+//
+//   evenodd — XOR every subpath together. That IS the even-odd rule: a point is
+//     inside when an odd number of subpaths contain it, whatever their
+//     direction. Exact, and it replaces a path that used to THROW (see below).
+//
+//   nonzero, all subpaths wound alike — their union, folded pairwise. With no
+//     subpath wound against the others, no winding can cancel, so every point
+//     any of them covers has |winding| >= 1. Union is therefore exactly nonzero,
+//     and this is the case the compound recipe got wrong.
+//
+//   nonzero, mixed winding — the original compound recipe. Counters exist, so
+//     nesting has to be resolved rather than unioned away, and this is exact for
+//     the whole bundled charset (verified against Manifold's NonZero fill,
+//     glyph by glyph, in test/curve-fill.test.js).
+//
+// The mixed-winding route keeps one known divergence from true winding-number
+// nonzero, unchanged from before this split and documented under
+// docs/ERROR-PATTERNS.md#svg-overlapping-subpaths: where a subpath wound against
+// the others covers area that two or more same-wound subpaths already cover,
+// true nonzero keeps it (2 - 1 = 1) and this drops it. Fixing that needs a real
+// planar arrangement, not a fold of pairwise booleans.
+//
+// Both routes reorient before grouping: paper's booleans can hand back disjoint
+// pieces with OPPOSITE orientations (measured: an XOR returning +50 and -50 for
+// two disjoint rectangles), and groupPaperPaths reads orientation to tell an
+// outer from a hole — so ungrouped it called the second piece a hole with
+// nothing to contain it and threw "resolved hole has no containing outer". That
+// was a crash on ordinary even-odd artwork, not merely a wrong area.
 import { paperScope, toPaperPath, groupPaperPaths } from "./paper-bridge.js";
 
 export function resolveCurveFill(contours, { fillRule = "nonzero" } = {}) {
@@ -22,8 +60,20 @@ export function resolveCurveFill(contours, { fillRule = "nonzero" } = {}) {
       for (const k of kids) if (k.segments && k.segments.length >= 2) simple.push(k.clone({ insert: false }));
     }
     if (simple.length === 0) return [];
-    const compound = new scope.CompoundPath({ children: simple, fillRule });
-    const united = compound.unite(compound, { insert: false });
+
+    const fold = (xs, op) => (xs.length ? xs.reduce((a, b) => a[op](b, { insert: false })) : null);
+    let united;
+    if (fillRule === "evenodd") {
+      united = fold(simple, "exclude");
+    } else if (simple.every((p) => p.clockwise === simple[0].clockwise)) {
+      united = fold(simple, "unite");
+    } else {
+      const compound = new scope.CompoundPath({ children: simple, fillRule });
+      united = compound.unite(compound, { insert: false });
+    }
+    if (!united) return [];
+    united = united.reorient(fillRule === "nonzero", true);
+
     const paths = (united.className === "CompoundPath" ? united.children : [united])
       .filter((p) => p.segments && p.segments.length >= 2 && Math.abs(p.area) > 1e-9);
     return paths.length ? groupPaperPaths(paths) : [];

package/src/framework/geometry/kernel-front.js

@@ -20,6 +20,7 @@ const opentype = normalizeOpentype(opentypeNamespace);
 import { KernelCapabilityError } from "./errors.js";
 import { isPlainOptions, KERNEL_OP_SPECS } from "./op-options.js";
 import { textGlyphs } from "./text2d.js";
+import { placeRegions } from "./vector2d.js";
 import { beveledExtrude } from "./rim-bevel.js";
 import { DEFAULT_FONT_BYTES } from "./fonts/default-font.js";
 import { convexHull, hullPoints } from "./hull.js";
@@ -161,6 +162,51 @@ export function finishKernel(k) {
     return regions.map((r) => k.shape2d(r)).reduce((a, b) => a.union(b));
   };
 
+  // 2-D vector art as a Shape2D. Backend-agnostic for the same reason text2d is:
+  // it lowers to k.shape2d + union, so both backends get identical curve regions.
+  // Regions come from k._vectors, preloaded by name from the part's declared
+  // vector documents — this op does no SVG parsing at all, by design.
+  // k._vectors holds documents ({ units, shapes: Map<name, { role, regions }> }).
+  // With no `shape` option, every "add" shape is unioned and every "subtract"
+  // shape is cut from that union (role states the file's own composition; union
+  // is commutative so key order is moot within each group). `shape` selects one
+  // shape's own geometry by name, whatever its role, so the caller can compose
+  // shapes with ordinary booleans in the drawing's own frame.
+  k._vectors ??= new Map();
+  k.vector2d = (name, opts = {}) => {
+    if (typeof name !== "string" || !name)
+      throw new Error("vector2d: first argument must be the name of an entry in the part's `vectors` field");
+    const doc = k._vectors.get(name);
+    if (!doc) throw new Error(`vector2d: unknown vector "${name}" — declare it in the part's \`vectors\` field`);
+    const lift = (regions, measureAgainst = regions) =>
+      placeRegions(regions, doc.units, opts, { measureAgainst, name }).map((r) => k.shape2d(r)).reduce((a, b) => a.union(b));
+    if (opts.shape != null) {
+      const entry = doc.shapes.get(opts.shape);
+      if (!entry) {
+        throw new Error(`vector2d: "${name}" has no shape ${JSON.stringify(opts.shape)} — it declares: ${[...doc.shapes.keys()].join(", ")}`);
+      }
+      // Naming a shape is a request for THAT geometry; role governs only the
+      // default composition below.
+      return lift(entry.regions);
+    }
+    const adds = [...doc.shapes.values()].filter((e) => e.role === "add").flatMap((e) => e.regions);
+    const subs = [...doc.shapes.values()].filter((e) => e.role === "subtract").flatMap((e) => e.regions);
+    if (subs.length === 0) return lift(adds);
+    // ONE transform for the whole document — both groups are measured against
+    // the SAME regions, so a size or align option cannot scale the subtracts
+    // relative to the adds. (With no size and no align — the common millimetre
+    // case — the transform is the identity and this changes nothing.)
+    //
+    // Measured against the ADDS, not against every region. A subtract may
+    // legitimately overhang the adds — a rect that lops off a corner, an
+    // overhanging keyway — and that overhang is deleted before the caller sees
+    // anything, so sizing or aligning against it puts the visible edge where
+    // nobody asked for it. With a subtract reaching 5 mm past the adds' left,
+    // measuring against all of them put `{ align: "left" }` — no size option at
+    // all — 5 mm right of the origin.
+    return lift(adds).cut(lift(subs, adds));
+  };
+
   // Convex hull → Shape2D. Backend-agnostic: pure-JS monotone-chain hull of the inputs'
   // sampled points, lifted via k.shape2d. Faceted (curved inputs at a fixed LOD).
   k.hull = (inputs) => {

package/src/framework/geometry/kernel.js

@@ -21,7 +21,7 @@ export const CONTRACT_VERSION = 4;
 // Ops every backend kernel must implement.
 export const KERNEL_OPS = [
   "cylinder", "boredCylinder", "sphere", "box", "prism", "extrude", "revolve",
-  "loft", "sweep", "helixSweptTube", "screwSweep", "union", "shape2d", "text2d", "hull", "hullChain", "toSTEP",
+  "loft", "sweep", "helixSweptTube", "screwSweep", "union", "shape2d", "text2d", "vector2d", "hull", "hullChain", "toSTEP",
   "roundedCylinder", "torus", "roundedBox", "import",
   // Additive in 0.84 (no CONTRACT_VERSION bump — the import-op precedent).
   "loftSmooth",

package/src/framework/geometry/probe.js

@@ -31,7 +31,7 @@ const SOLID_ALLOWED = new Set([...SOLID_OPS, ...SOLID_OPTIONAL_OPS, ...SHAPE2D_O
 
 // Kernel ops whose result is a Shape2D, and Shape2D ops whose result is a Solid —
 // the only two places the probe's handle kind changes.
-const SHAPE2D_YIELDING_KERNEL_OPS = new Set(["shape2d", "text2d"]);
+const SHAPE2D_YIELDING_KERNEL_OPS = new Set(["shape2d", "text2d", "vector2d"]);
 const SOLID_YIELDING_SHAPE2D_OPS = new Set(["extrude", "revolve"]);
 
 export const MAX_PROBE_OPS = 100000;

package/src/framework/geometry/stroke-outline.js

@@ -0,0 +1,119 @@
+// Stroke → filled geometry. The half of paperjs-offset that contour-offset.js
+// did not port: `offsetStroke`.
+//
+// Both cases reduce to "offset the path, offset its reverse, let nonzero winding
+// assemble the result":
+//
+//   CLOSED  outer = offset(contour, +w/2), inner = offset(reverse(contour), +w/2).
+//           Two rings of opposite handedness -> an annulus. _offsetContour
+//           already does closed rings correctly, so this adds no geometry code.
+//   OPEN    the same two offsets as open CHAINS, joined end to end by caps into
+//           one closed ring.
+//
+// Pure leaf: DOM-free, node:-free.
+import { _joinSegs, _offsetContour, _offsetSegment } from "./contour-offset.js";
+import { SMOOTH_JOINT_DEG, segTangent } from "./contour-ops.js";
+import { closeContourGap, reverseContour } from "./profile.js";
+import { resolveCurveFill } from "./curve-fill.js";
+
+const JOIN_EPS = 1e-6;
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1]];
+const add = (a, b) => [a[0] + b[0], a[1] + b[1]];
+const scl = (v, s) => [v[0] * s, v[1] * s];
+const cross = (a, b) => a[0] * b[1] - a[1] * b[0];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1];
+const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1]);
+const rightOf = ([x, y]) => [y, -x];        // matches contour-offset.js:31 exactly
+
+// SVG's linejoin vocabulary is contour-offset.js's `corners` vocabulary under
+// different names.
+const CORNERS = { miter: "sharp", round: "round", bevel: "chamfer" };
+
+// Each segment's start point, with zero-length lines dropped (no direction, so
+// no offset).
+function chainParts(contour) {
+  const segs = [], froms = [];
+  let p = contour.start;
+  for (const s of contour.segments) {
+    if (s.c1 || s.via || dist(p, s.to) > 1e-9) { segs.push(s); froms.push(p); }
+    p = s.to;
+  }
+  return { segs, froms, end: p };
+}
+
+// Offset an OPEN chain, joining at interior vertices only. Mirrors
+// _offsetContour's join decision (gap side gets a join, overlap side gets a
+// bevel the winding rule then cancels) minus the wrap-around and the whole-ring
+// collapse predicate, neither of which means anything for a chain.
+function offsetOpenChain(contour, delta, corners) {
+  const { segs, froms } = chainParts(contour);
+  if (segs.length === 0) return null;
+  const pieces = segs.map((s, i) => _offsetSegment(froms[i], s, delta));
+  const out = [];
+  for (let i = 0; i < pieces.length; i++) {
+    if (i > 0) {
+      const aEnd = pieces[i - 1].segments.at(-1).to, bStart = pieces[i].start;
+      const inTan = segTangent(froms[i - 1], segs[i - 1], false);
+      const outTan = segTangent(froms[i], segs[i], true);
+      const turn = cross(inTan, outTan);
+      const turnDeg = (Math.atan2(Math.abs(turn), Math.max(-1, Math.min(1, dot(inTan, outTan)))) * 180) / Math.PI;
+      if (dist(aEnd, bStart) > JOIN_EPS && turnDeg >= SMOOTH_JOINT_DEG) {
+        // turn === 0 with a large turnDeg is an exact 180 degree reversal — the
+        // same ambiguity _offsetContour calls out; treat it as gap side so a
+        // round join is honored rather than flat-capped.
+        if (turn * delta > 0 || turn === 0) out.push(..._joinSegs(froms[i], aEnd, bStart, inTan, outTan, delta, corners));
+        else out.push({ to: [bStart[0], bStart[1]] });
+      }
+    }
+    out.push(...pieces[i].segments);
+  }
+  return { start: pieces[0].start, segments: out };
+}
+
+// Bridge to `to` around the path endpoint `tip`, where `tangent` points OUT of
+// the path at that end and `hw` is the half stroke width. The current position
+// on entry is tip + hw*rightOf(tangent).
+function capSegments(tip, tangent, hw, linecap, to) {
+  if (linecap === "round") return [{ via: add(tip, scl(tangent, hw)), to }];
+  if (linecap === "square") {
+    const ext = scl(tangent, hw), n = scl(rightOf(tangent), hw);
+    return [{ to: add(add(tip, n), ext) }, { to: add(sub(tip, n), ext) }, { to }];
+  }
+  return [{ to }];                                            // butt
+}
+
+export function outlineStroke(contour, closed, style) {
+  const hw = style.strokeWidth / 2;
+  if (!(hw > 0)) throw new Error("svg: cannot outline a stroke of zero width");
+  const corners = CORNERS[style.linejoin] ?? "sharp";
+
+  if (closed) {
+    const ring = closeContourGap(contour);
+    const a = _offsetContour(ring, hw, corners).contour;
+    const b = _offsetContour(closeContourGap(reverseContour(ring)), hw, corners).contour;
+    const rings = [a, b].filter(Boolean);
+    if (rings.length < 2) throw new Error("svg: stroke outline collapsed — stroke-width is too large for this shape");
+    return resolveCurveFill(rings, { fillRule: "nonzero" });
+  }
+
+  const fwd = offsetOpenChain(contour, hw, corners);
+  const rev = offsetOpenChain(reverseContour(contour), hw, corners);
+  if (!fwd || !rev) throw new Error("svg: stroke path has no length to outline");
+
+  const { segs, froms, end } = chainParts(contour);
+  const endTan = segTangent(froms.at(-1), segs.at(-1), false);
+  const startTanIn = segTangent(contour.start, segs[0], true);
+  const startTanOut = [-startTanIn[0], -startTanIn[1]];
+
+  const segments = [
+    ...fwd.segments,
+    ...capSegments(end, endTan, hw, style.linecap, rev.start),
+    ...rev.segments,
+    ...capSegments(contour.start, startTanOut, hw, style.linecap, fwd.start),
+  ];
+
+  // A stroke path that crosses itself makes this ring self-intersecting.
+  // resolveCurveFill under nonzero is exactly the normalizer for that — the same
+  // one the fill path uses, not a second mechanism.
+  return resolveCurveFill([{ start: fwd.start, segments }], { fillRule: "nonzero" });
+}