partforge 0.40.0 → 0.44.0

package/src/framework/viewer.js

@@ -5,6 +5,7 @@ import { LineSegments2 } from "three/addons/lines/LineSegments2.js";
 import { LineSegmentsGeometry } from "three/addons/lines/LineSegmentsGeometry.js";
 import { LineMaterial } from "three/addons/lines/LineMaterial.js";
 import { createCutaway } from "./cutaway.js";
+import { createCameraTween } from "./camera-tween.js";
 import { addViewerLights, captureLightPoses, createCaptureLights } from "./viewer-lighting.js";
 import { CANONICAL_VIEWS, cameraPoseForView } from "./view-angles.js";
 
@@ -94,6 +95,10 @@ export function createViewer(container, part) {
   renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
   container.appendChild(renderer.domElement);
 
+  // Declared up here, not beside setActive() below, because the initial resize()
+  // runs during construction and reads it.
+  let active = true;
+
   const scene = new THREE.Scene();
 
   // Light/dark scene palettes (the page chrome is themed separately, via CSS on the
@@ -109,8 +114,6 @@ export function createViewer(container, part) {
 
   const controls = new OrbitControls(camera, renderer.domElement);
   controls.enableDamping = true;
-  controls.autoRotate = true;
-  controls.autoRotateSpeed = 1.6;
 
   // --- lights + grid --------------------------------------------------------
   const liveLights = addViewerLights(scene);
@@ -210,6 +213,39 @@ export function createViewer(container, part) {
     cutaway.setSubpart(name, subMesh[name], subLines[name]);
   }
 
+  // --- animation hooks --------------------------------------------------------
+  // Frame listeners get dt (seconds, clamped so a background-tab return doesn't
+  // fast-forward playback) inside the render loop — so a parked viewer
+  // (setActive(false)) automatically halts playback too: no loop, no ticks.
+  const frameListeners = new Set();
+  function onFrame(cb) { frameListeners.add(cb); return () => frameListeners.delete(cb); }
+
+  const camTween = createCameraTween();
+  // Tween the orbit camera to a canonical angle, framed on what's visible now.
+  // Presentational only; a caller passing duration 0 gets a jump cut.
+  function tweenCameraTo(viewName, { duration = 0.6, onComplete } = {}) {
+    const box = getVisibleWorldBounds();
+    if (!box || box.isEmpty()) { onComplete?.(); return; }
+    const center = box.getCenter(new THREE.Vector3()).toArray();
+    const size = box.getSize(new THREE.Vector3());
+    // radius = full max extent (not half), matching frameTo's framing distance so a
+    // live camera cue doesn't land twice as close as the reframe button and crop the part.
+    const pose = cameraPoseForView(viewName, { center, radius: Math.max(size.x, size.y, size.z) || 12 });
+    camTween.start(
+      { position: camera.position.toArray(), target: controls.target.toArray() },
+      { position: pose.position, target: pose.target },
+      { duration, onComplete },
+    );
+  }
+  const cancelCameraTween = () => camTween.cancel();
+
+  // User grabbing the orbit cancels any cue tween (the user owns the camera) and
+  // tells subscribers (the animation driver disarms remaining cues).
+  const cameraStartListeners = new Set();
+  const onControlsStart = () => { camTween.cancel(); for (const cb of [...cameraStartListeners]) cb(); };
+  controls.addEventListener("start", onControlsStart);
+  function onCameraStart(cb) { cameraStartListeners.add(cb); return () => cameraStartListeners.delete(cb); }
+
   // Smooth shading within CREASE_ANGLE of a shared edge, hard edge past it — so the
   // round body and helical groove read smooth while bore rims, drum faces, and
   // groove walls stay crisp. Lower = more hard edges; raise toward Math.PI/3 for
@@ -326,18 +362,8 @@ export function createViewer(container, part) {
     frameTo(names.filter((n) => subMesh[n].visible && subCache[n]));
   }
 
-  let autoRotateRequested = true;
-  function syncAutoRotate() {
-    controls.autoRotate = autoRotateRequested && !cutaway.isEnabled;
-  }
-  function setAutoRotate(on) {
-    autoRotateRequested = !!on;
-    syncAutoRotate();
-  }
   function setCutawayEnabled(on) {
-    const changed = cutaway.setEnabled(on);
-    syncAutoRotate();
-    return changed;
+    return cutaway.setEnabled(on);
   }
 
   // Swap the scene background, grid, and edge-line colors for the given theme.
@@ -361,6 +387,10 @@ export function createViewer(container, part) {
   // --- resize ---------------------------------------------------------------
   // Size from the host container (not the window) so embedders control the pane.
   function resize() {
+    // Parked (see setActive): the buffer is deliberately 1x1 and must stay that
+    // way. iOS fires resizes constantly as the URL bar collapses, and every one
+    // of them would otherwise re-allocate a full MSAA buffer for a hidden pane.
+    if (!active) return;
     const w = container.clientWidth || 300, h = container.clientHeight || 150;
     renderer.setSize(w, h);
     camera.aspect = w / h;
@@ -481,12 +511,78 @@ export function createViewer(container, part) {
   }
 
   // --- render loop ----------------------------------------------------------
-  renderer.setAnimationLoop(() => {
+  // The tween is applied after controls.update() so the cue wins the frame, and
+  // the frame listeners run before render so a playback frame draws its own pose.
+  let lastFrameTime = null;
+  function renderFrame(time) {
+    const dt = lastFrameTime == null ? 0 : Math.min(0.1, (time - lastFrameTime) / 1000);
+    lastFrameTime = time;
     controls.update();
+    const tw = camTween.update(dt);
+    if (tw) {
+      camera.position.fromArray(tw.position);
+      controls.target.fromArray(tw.target);
+    }
+    for (const cb of [...frameListeners]) cb(dt);
     if (cutaway.isEnabled) cutaway.updateForCamera();
     renderer.render(scene, camera);
     cutaway.renderOverlay(renderer, camera);
-  });
+  }
+  renderer.setAnimationLoop(renderFrame);
+
+  // --- active / parked ------------------------------------------------------
+  // For a host that HIDES the viewer without unmounting it. partforge's own
+  // narrow layout uses `display: none` on the stage, which zeroes clientWidth
+  // and lets the ResizeObserver above collapse the buffer for free. An embedder
+  // that cannot do that — partforge-cloud's phone tab bar uses
+  // `visibility: hidden`, because the canvas has to keep its size for build
+  // screenshots — gets no such signal: the full-resolution MSAA drawing buffer
+  // stays resident and this loop keeps rendering the scene at 60fps behind an
+  // invisible pane. On an iPhone that is tens of megabytes and
+  // continuous GPU work nobody can see, so the host has to say so explicitly.
+  //
+  // Parking stops the loop and releases the drawing buffer. `setSize(1, 1,
+  // false)` leaves the canvas element's CSS box alone, so the host's layout
+  // does not move and the pane can be revealed again without a reflow.
+  function setActive(next) {
+    const want = next !== false;
+    if (disposed || want === active) return;
+    active = want;
+    if (!active) {
+      renderer.setAnimationLoop(null);
+      renderer.setSize(1, 1, false);
+      // The cached 1024² 4x-MSAA + stencil capture target is the other large
+      // allocation here — on a phone it is comparable to the canvas itself, so
+      // parking that kept it would leave half the memory behind. Dropping it
+      // costs one re-allocation on the next capture, which a parked viewer
+      // barely notices: the cache only ever hits on an exactly-square request,
+      // and a phone's capture aspect is not square, so those captures were
+      // allocating per call regardless.
+      _rt?.dispose();
+      _rt = null;
+      return;
+    }
+    resize(); // rebuild the buffer at whatever size the container is now
+    lastFrameTime = null; // parked time is not elapsed time — no dt jump on unpark
+    renderer.setAnimationLoop(renderFrame);
+  }
+
+  // --- context loss ---------------------------------------------------------
+  // Losing the WebGL context is how a memory-starved phone tells you it gave
+  // up. With no handler the canvas just freezes, indistinguishable from a hang,
+  // and three never re-initialises. preventDefault() is what makes the loss
+  // recoverable (three's own listener re-uploads on restore); the subscribers
+  // let an embedder surface it instead of showing a dead rectangle.
+  const contextLostListeners = new Set();
+  const onContextLostEvent = (event) => {
+    event.preventDefault();
+    for (const listener of [...contextLostListeners]) listener();
+  };
+  renderer.domElement.addEventListener("webglcontextlost", onContextLostEvent);
+  function onContextLost(listener) {
+    contextLostListeners.add(listener);
+    return () => contextLostListeners.delete(listener);
+  }
 
   // --- camera state (read/write for persistence; mount.js owns storage) -------
   function getCameraState() {
@@ -528,6 +624,15 @@ export function createViewer(container, part) {
     disposed = true;
     ro.disconnect();
     renderer.setAnimationLoop(null);
+    // Embedder callbacks must not outlive teardown — a disposed viewer has no
+    // context left to lose, and a surviving listener would keep the embedder's
+    // closure (and whatever it captured) alive.
+    renderer.domElement.removeEventListener("webglcontextlost", onContextLostEvent);
+    contextLostListeners.clear();
+    controls.removeEventListener("start", onControlsStart);
+    cameraStartListeners.clear();
+    frameListeners.clear();
+    camTween.cancel();
     controls.dispose();
     for (const t of flashTimers) clearTimeout(t);
     flashTimers.clear();
@@ -557,7 +662,12 @@ export function createViewer(container, part) {
     frame,
     captureCanonicalViews,
     captureCurrent,
-    setAutoRotate,
+    onFrame,
+    tweenCameraTo,
+    cancelCameraTween,
+    onCameraStart,
+    setActive,
+    onContextLost,
     setTheme,
     getCameraState,
     setCameraState,

package/src/hinged-box-worker.js

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

package/src/index.js

@@ -3,4 +3,4 @@
 // must NOT be imported from a part's build functions — those run in a Web Worker.
 // Part build functions import geometry helpers from "partforge/geometry" instead.
 export { mount } from "./framework/index.js";
-export { viewSubParts } from "./framework/jobs.js";
+export { viewSubParts } from "./framework/part-model.js";

package/src/parts/hinged-box.js

@@ -0,0 +1,94 @@
+// Animation reference part — a box with a hinged lid. Worked example for
+// docs/AUTHORING-PARTS.md "Animations": pose-only animated params (lidAngle,
+// lidLift) driven through place(), an intro camera + markdown description on
+// `open`, a looping `cycle`, and a stepped `assemble` with per-step cameras.
+export default {
+  meta: { title: "Hinged Box", units: "mm" },
+  parameters: [
+    {
+      id: "box",
+      title: "Box",
+      description: "Outer dimensions of the base. The lid is a flat plate of the same wall thickness.",
+      advanced: [
+        { key: "width", label: "Width", unit: "mm", min: 20, max: 120, step: 1,
+          description: "Outer width (X)." },
+        { key: "depth", label: "Depth", unit: "mm", min: 20, max: 120, step: 1,
+          description: "Outer depth (Y). The hinge runs along the rear edge." },
+        { key: "height", label: "Height", unit: "mm", min: 10, max: 80, step: 1,
+          description: "Outer height of the base (Z)." },
+        { key: "wall", label: "Wall", unit: "mm", min: 1.2, max: 5, step: 0.2,
+          description: "Wall and lid thickness." },
+      ],
+    },
+    {
+      id: "pose",
+      title: "Pose",
+      description: "Presentation pose. The **Open lid** and **Assemble** animations drive these — both are pose-only, so animating them never rebuilds geometry.",
+      advanced: [
+        { key: "lidAngle", label: "Lid angle", unit: "°", min: 0, max: 110, step: 1,
+          description: "Hinge opening angle about the rear top edge." },
+        { key: "lidLift", label: "Lid lift", unit: "mm", min: 0, max: 60, step: 1,
+          description: "Assembly explode offset: raises the lid straight up off the hinge." },
+      ],
+    },
+  ],
+  defaults: { width: 60, depth: 40, height: 24, wall: 2, lidAngle: 0, lidLift: 0 },
+  parts: {
+    base: {
+      label: "Base",
+      views: ["box"],
+      export: { name: "base" },
+      build: (k, p) =>
+        k.box({ min: [0, 0, 0], max: [p.width, p.depth, p.height] })
+          .cut(k.box({ min: [p.wall, p.wall, p.wall], max: [p.width - p.wall, p.depth - p.wall, p.height + 1] })),
+    },
+    lid: {
+      label: "Lid",
+      views: ["box"],
+      export: { name: "lid" },
+      build: (k, p) => k.box({ min: [0, 0, p.height], max: [p.width, p.depth, p.height + p.wall] }),
+      // Display: swing about the hinge line (rear top edge, axis +X through
+      // [0, depth, height]; negative angle opens upward), then the assembly
+      // lift. Export: the lid prints flat beside the base. Both poses are
+      // rigid motions of the same solid, and neither reads `view` — the two
+      // invariants lint's place rules hold every part to.
+      place: (s, { purpose, p }) =>
+        purpose === "export"
+          ? s.translate([p.width + 10, 0, -p.height])
+          : s.rotate(-p.lidAngle, [0, p.depth, p.height], [1, 0, 0]).translate([0, 0, p.lidLift]),
+    },
+  },
+  views: { box: { label: "Box" } },
+  animations: {
+    open: {
+      label: "Open lid",
+      description: "Swings the lid to **110°** about the rear hinge line.\n\nPose-only: playback runs at frame rate with no geometry rebuild.",
+      camera: "front",
+      duration: 1.2,
+      tracks: { lidAngle: [[0, 0], [1, 110]] },
+    },
+    cycle: {
+      label: "Open / close",
+      duration: 2.4,
+      loop: true,
+      easing: "linear",
+      autoplay: true,
+      tracks: { lidAngle: [[0, 0], [0.5, 110], [1, 0]] },
+    },
+    assemble: {
+      label: "Assemble",
+      description: "How the parts come together: the lid drops onto the base, then swings open to check hinge clearance.",
+      steps: [
+        { label: "Lower the lid", camera: "left", duration: 1.0, tracks: { lidLift: [[0, 40], [1, 0]] } },
+        { label: "Open to check clearance", camera: "iso", duration: 1.0, tracks: { lidAngle: [[0, 0], [1, 110]] } },
+      ],
+    },
+  },
+  verify: {
+    process: "fdm-pla",
+    expect: {
+      base: { bbox: "<=[200,200,200]" },
+      _view: { overlaps: 0 },
+    },
+  },
+};

package/src/testing/render.js

@@ -1,7 +1,8 @@
 import { writeFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
-import { buildView } from "./build.js";
-import { bounds } from "./mesh.js";
+import { join, resolve, sep } from "node:path";
+import { safeName } from "../framework/safe-name.js";
+import { buildView } from "../framework/oracle/build.js";
+import { bounds } from "../framework/oracle/mesh.js";
 
 // Canonical view directions in MODEL space (Z-up). `dir` is the direction from
 // the part centre toward the camera; `up` is the camera up vector.
@@ -22,7 +23,6 @@ export const RENDER_ANGLES = {
 };
 export const RENDER_VIEWS = Object.keys(RENDER_ANGLES);
 
-const slug = (s) => String(s).toLowerCase().replace(/\s+/g, "-");
 const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
 const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
 const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
@@ -33,7 +33,7 @@ const norm = (a) => { const l = Math.hypot(a[0], a[1], a[2]) || 1; return [a[0]
 // overlays). No native module, no browser. Returns the written file paths.
 // pngjs is lazy-imported so importing the testing barrel for measure never loads it.
 export async function renderViews(kernel, part, view = Object.keys(part.views)[0], {
-  views = ["iso", "front", "top"], out = "render", size = [800, 600], edges = true, params = {},
+  views = ["iso", "front", "top"], out = "render", size = [800, 600], edges = true, params = {}, tag = "",
 } = {}) {
   const { PNG } = await import("pngjs");
   const [W, H] = size;
@@ -54,8 +54,13 @@ export async function renderViews(kernel, part, view = Object.keys(part.views)[0
   const ambient = 0.35, diffuse = 0.75;
   const bias = radius * 0.02;           // edge depth bias so visible edges win ties
 
-  mkdirSync(out, { recursive: true });
-  const name = slug(part.meta?.title ?? view);
+  // `out` is operator-supplied (a CLI flag) and stays verbatim; the part-derived
+  // title and view key are sanitized, since this is the one place a part's
+  // strings reach the filesystem.
+  const outDir = resolve(out);
+  mkdirSync(outDir, { recursive: true });
+  const name = safeName(part.meta?.title ?? view);
+  const viewName = safeName(view);
   const written = [];
 
   for (const angle of views) {
@@ -121,7 +126,13 @@ export async function renderViews(kernel, part, view = Object.keys(part.views)[0
     for (let i = 0; i < W * H; i++) {
       png.data[i * 4] = color[i * 3]; png.data[i * 4 + 1] = color[i * 3 + 1]; png.data[i * 4 + 2] = color[i * 3 + 2]; png.data[i * 4 + 3] = 255;
     }
-    const file = join(out, `${name}-${view}-${angle}.png`);
+    // The animation frame tag goes through safeName() as well — one rule for
+    // every string that reaches a filename here.
+    const file = join(out, `${name}-${viewName}-${angle}${tag ? `-${safeName(tag)}` : ""}.png`);
+    // Belt and braces over safeName(): assert the escape never happened rather
+    // than trusting the slug, because a miss here writes bytes to disk. (The
+    // returned paths stay relative to `out` — the CLI echoes them.)
+    if (!resolve(file).startsWith(outDir + sep)) throw new Error(`renderViews: refusing to write outside ${out}`);
     writeFileSync(file, PNG.sync.write(png));
     written.push(file);
   }

package/src/testing.js

@@ -1,18 +1,25 @@
 // partforge/testing — utilities for testing parts headlessly (Manifold kernel, the
 // job loop, the assembly collision check, an OCCT kernel, and mesh measures).
 // See docs/AUTHORING-PARTS.md "Testing a part".
+//
+// Most of what this re-exports is NOT test-only code: the oracle (measure/verify/
+// buildView/gaps/BVH/min-wall) also runs inside the browser geometry worker, so it
+// lives in src/framework/oracle/. Only the Node-bound harness — the two kernel
+// booters, the PNG renderer — lives in src/testing/. This barrel is the published
+// entry point and hides that split from downstream consumers.
 export { createManifoldKernel } from "./framework/geometry/manifold-backend.js";
 export { bootManifoldKernel } from "./testing/manifold.js";
-export { handle, viewSubParts } from "./framework/jobs.js";
+export { handle } from "./framework/jobs.js";
+export { viewSubParts } from "./framework/part-model.js";
 export { resolveDerived } from "./framework/derive.js";
 export { relevantParamKeys, RELEVANT_ALL } from "./framework/param-deps.js";
 export { assemblyOverlaps } from "./framework/assembly.js";
-export { assemblyGaps, meshGaps } from "./testing/gaps.js";
+export { assemblyGaps, meshGaps } from "./framework/oracle/gaps.js";
 export { bootOcctKernel } from "./testing/occt.js";
-export { meshVolume, bboxSize } from "./testing/mesh.js";
-export { buildView } from "./testing/build.js";
-export { measure } from "./testing/measure.js";
+export { meshVolume, bboxSize } from "./framework/oracle/mesh.js";
+export { buildView } from "./framework/oracle/build.js";
+export { measure } from "./framework/oracle/measure.js";
 export { renderViews, RENDER_VIEWS } from "./testing/render.js";
-export { verify } from "./testing/verify.js";
-export { buildBVH } from "./testing/bvh.js";
-export { minWall } from "./testing/min-wall.js";
+export { verify } from "./framework/oracle/verify.js";
+export { buildBVH } from "./framework/oracle/bvh.js";
+export { minWall } from "./framework/oracle/min-wall.js";

package/types/derive.d.ts

@@ -0,0 +1,14 @@
+// partforge/derive — a lean, DOM-free entry so a part module (or a helper, or a
+// test) can merge a grouped `derive` exactly the way the framework does.
+
+import type { Derived, PartDefinition, ResolvedParams } from "./part.js";
+
+/**
+ * Resolve a part's `derive` into the derived-values object `d` builds receive.
+ *
+ * Both authoring forms are handled: one function computed in a single pass, or
+ * named groups run in declaration order (each seeing the merged outputs of the
+ * groups before it). A group that reads a key no earlier group produced throws.
+ * Returns `{}` when the part declares no `derive`.
+ */
+export function resolveDerived(part: Pick<PartDefinition, "derive">, p: ResolvedParams): Derived;

package/types/geometry.d.ts

@@ -0,0 +1,117 @@
+// partforge/geometry — pure 2-D profile helpers and solid patterns.
+//
+// DOM-free and kernel-free: this is the entry a part's build functions import
+// (importing "partforge" inside a worker throws `document is not defined`).
+
+import type { ArcContour, Point2, Point3, PointsContour, Region2D, Solid } from "./kernel.js";
+
+export type { ArcContour, Point2, Point3, PointsContour, Region2D, Solid };
+
+/** A pie/sector wedge with its tip at the origin. */
+export function piePolygon(tipR: number, arcDeg: number, segs?: number): PointsContour;
+
+/** A regular hexagon of circumradius `r`. */
+export function hexPolygon(r: number): PointsContour;
+
+/** A `w` × `h` rectangle centred at the origin with corner radius `r`. */
+export function roundedRectPolygon(w: number, h: number, r: number, segs?: number): PointsContour;
+
+/** A regular `n`-gon of circumradius `r`; `flat: true` seats a flat side down. */
+export function regularPolygon(n: number, r: number, opts?: { flat?: boolean }): PointsContour;
+
+export function ellipsePolygon(rx: number, ry: number, segs?: number): PointsContour;
+
+/** A stadium/slot; overall length is `length + 2r`. */
+export function slotPolygon(length: number, r: number, segs?: number): PointsContour;
+
+export function starPolygon(points: number, outerR: number, innerR: number): PointsContour;
+
+/** An annular sector. `arcDeg` must be < 360 — a full ring is a contour-with-hole. */
+export function ringSectorPolygon(innerR: number, outerR: number, arcDeg: number, segs?: number): PointsContour;
+
+/**
+ * A CCW circle of radius `r` centred at `center`, as a FACETED point list
+ * (`segs` segments). For curve-exact corners use `roundedProfile`/`pathProfile`.
+ */
+export function circleProfile(r: number, center?: Point2, segs?: number): PointsContour;
+
+/**
+ * Per-corner rounding geometry shared by `filletPolygon` and `roundedProfile`:
+ * the incoming/outgoing tangent points, the arc centre, the clamped radius, the
+ * short sweep and its start angle — or `null` for a corner that stays sharp.
+ */
+export function cornerArc(
+  p0: Point2,
+  p1: Point2,
+  p2: Point2,
+  r: number,
+): { a: number[]; b: number[]; c: number[]; rr: number; dA: number; a0: number } | null;
+
+/**
+ * Round every corner of a CCW polygon, BAKING each arc into line facets — so
+ * STEP corners are faceted. Use `roundedProfile` for true circular edges.
+ */
+export function filletPolygon(points: PointsContour, r: number, opts?: { segs?: number }): PointsContour;
+
+/**
+ * Round corners the same way as `filletPolygon` but keep them mathematically
+ * TRUE — the arc is carried symbolically, so STEP export gets real circular
+ * edges. A scalar `r` rounds every corner; a per-corner `r[]` (length = points)
+ * rounds selectively. Accepted by `prism`/`extrude`, not yet by `loft`.
+ */
+export function roundedProfile(points: PointsContour, r: number | number[]): ArcContour;
+
+/** The fluent builder `pathProfile` returns. `close()` snapshots the contour. */
+export interface PathProfileBuilder {
+  lineTo(to: Point2): PathProfileBuilder;
+  /** A circular arc to `to` passing through `via`. */
+  arcTo(to: Point2, via: Point2): PathProfileBuilder;
+  /** A cubic Bézier to `to` with control points `c1`/`c2`. */
+  cubicTo(to: Point2, c1: Point2, c2: Point2): PathProfileBuilder;
+  /** Close the contour and return it. Needs at least one segment. */
+  close(): ArcContour;
+}
+
+/**
+ * A fluent builder for a curve-native path contour. Cubic segments become exact
+ * B-rep spline edges on OCCT and facet at mesh LOD on Manifold.
+ */
+export function pathProfile(start: Point2): PathProfileBuilder;
+
+/** Convex-corner style for `offsetPolygon`. */
+export type OffsetCorners = "round" | "chamfer" | "sharp";
+
+/**
+ * Offset a point-list polygon or an `{ outer, holes }` region by `delta` mm —
+ * positive grows material, negative insets (regions offset material-wise).
+ * Simple polygon in, simple polygon out: an offset that would collapse or split
+ * the contour THROWS. Pure, so it works in `derive()` as well as `build()`.
+ */
+export function offsetPolygon(
+  profile: PointsContour,
+  delta: number,
+  opts?: { corners?: OffsetCorners; segs?: number },
+): PointsContour;
+export function offsetPolygon(
+  profile: Region2D,
+  delta: number,
+  opts?: { corners?: OffsetCorners; segs?: number },
+): Region2D;
+
+/** `count` copies of `solid` translated by `i * step`. Feed to `k.union` / `s.cutAll`. */
+export function linearPattern(solid: Solid, count: number, step: Point3): Solid[];
+
+/**
+ * `count` copies spaced `angle / count` degrees apart around `axis` through
+ * `center`. `rotateCopies: false` keeps each copy's original orientation.
+ */
+export function circularPattern(
+  solid: Solid,
+  count: number,
+  opts?: {
+    center?: Point3;
+    axis?: "X" | "Y" | "Z" | Point3;
+    angle?: number;
+    rotateCopies?: boolean;
+  },
+): Solid[];