partforge 0.41.0 → 0.45.0

package/src/framework/viewer.js

@@ -5,7 +5,8 @@ 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 { addViewerLights, captureLightPoses, createCaptureLights } from "./viewer-lighting.js";
+import { createCameraTween } from "./camera-tween.js";
+import { addViewerLights, captureLightPoses, createCaptureLights, createHemisphereLight } from "./viewer-lighting.js";
 import { CANONICAL_VIEWS, cameraPoseForView } from "./view-angles.js";
 
 // three renders into a render target in the LINEAR working colour space: as of r184
@@ -113,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);
@@ -214,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
@@ -330,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.
@@ -405,7 +427,8 @@ export function createViewer(container, part) {
   // no error, live view unaffected, wrong only in the capture.
   const RT_OPTIONS = { samples: 4, stencilBuffer: true };
   function renderOffscreen({ position, up, target },
-                           { width = _rtSize, height = _rtSize, fov = 45, quality = 0.9 } = {}) {
+                           { width = _rtSize, height = _rtSize, fov = 45, quality = 0.9 } = {},
+                           renderScene = scene) {
     const cachedSize = width === _rtSize && height === _rtSize;
     const rt = cachedSize
       ? (_rt = _rt ?? new THREE.WebGLRenderTarget(_rtSize, _rtSize, RT_OPTIONS))
@@ -429,7 +452,7 @@ export function createViewer(container, part) {
     scene.add(capKey, capKey.target, capFill, capFill.target);
     try {
       renderer.setRenderTarget(rt);
-      renderer.render(scene, cam);
+      renderer.render(renderScene, cam);
       // render() resolves the multisample renderbuffer into the target texture, so this
       // reads antialiased pixels.
       renderer.readRenderTargetPixels(rt, 0, 0, width, height, buf);
@@ -488,9 +511,96 @@ export function createViewer(container, part) {
     });
   }
 
+  // Offscreen render of an arbitrary mesh set (a non-active view), for thumbnails.
+  // Assembles a THROWAWAY scene mirroring the live pivot convention, frames it from a
+  // canonical angle, renders through the parameterized renderOffscreen, and disposes
+  // everything. Never touches the live scene, camera, subMesh, or subCache. `payloads`
+  // is the worker's [{name, positions, normals, indices, …}] array — placement is
+  // already baked into shared-frame coords, so meshes are NOT recentred.
+  function renderMeshPayloads(payloads, { angle = "iso", size = 640, quality = 0.8 } = {}) {
+    if (disposed) return null; // same guard as captureCurrent/captureCanonicalViews — never touch a torn-down renderer
+    const tmpScene = new THREE.Scene();
+    const tmpPivot = new THREE.Group();
+    tmpPivot.rotation.x = -Math.PI / 2; // model Z (CAD up) -> vertical, same as live pivot
+    tmpScene.add(tmpPivot);
+
+    const built = [];
+    for (const payload of payloads) {
+      const geo = buildGeometry(payload); // shared-frame coords, NOT recentred
+      const mesh = new THREE.Mesh(geo, materialFor(payload.name));
+      tmpPivot.add(mesh);
+      built.push(mesh);
+    }
+
+    // Frame in WORLD space, AFTER the pivot rotation. The meshes are built in model
+    // coords but rendered rotated by tmpPivot, so a model-space bbox centre would aim
+    // the camera at the wrong point — an off-origin part would render off-centre or blank.
+    tmpPivot.updateMatrixWorld(true);
+    const box = new THREE.Box3().setFromObject(tmpPivot);
+    const center = box.getCenter(new THREE.Vector3()).toArray();
+    const radius = box.getSize(new THREE.Vector3()).length() / 2 || 1;
+    const pose = cameraPoseForView(angle, { center, radius });
+
+    // Light the throwaway scene ourselves: renderOffscreen's own key/fill (and the
+    // persistent hemisphere) live in the LIVE scene, which is never rendered here — so
+    // without our own ambient + camera-relative key/fill it comes back near-black.
+    const hemi = createHemisphereLight();
+    const capLights = createCaptureLights();
+    const poses = captureLightPoses(pose);
+    capLights.key.position.set(poses.key[0], poses.key[1], poses.key[2]);
+    capLights.fill.position.set(poses.fill[0], poses.fill[1], poses.fill[2]);
+    for (const light of [capLights.key, capLights.fill]) {
+      light.target.position.set(pose.target[0], pose.target[1], pose.target[2]);
+    }
+    tmpScene.add(hemi, capLights.key, capLights.key.target, capLights.fill, capLights.fill.target);
+
+    // Feature-edge lines, so the thumbnail carries the same hole/seam/chamfer outlines the
+    // live viewer shows. A dedicated LineMaterial at the render resolution (the live one is
+    // sized to the on-screen canvas); added after framing so it can't perturb the bbox.
+    const lineMat = new LineMaterial({ color: THEME.dark.line, linewidth: 1.0 });
+    lineMat.resolution.set(size, size);
+    for (const mesh of built) {
+      const edges = mesh.geometry.userData.edges;
+      if (edges) tmpPivot.add(new LineSegments2(edges, lineMat));
+    }
+
+    try {
+      // fov matches the live camera (and captureViews/captureCurrent) — cameraPoseForView's
+      // distance is tuned to it, so a narrower fov would crop long, thin parts.
+      return renderOffscreen(pose, { width: size, height: size, fov: camera.fov, quality }, tmpScene);
+    } finally {
+      for (const mesh of built) {
+        mesh.geometry.userData.edges?.dispose();
+        mesh.geometry.dispose();
+        if (mesh.material !== material) mesh.material.dispose(); // clone only — never the shared singleton
+      }
+      lineMat.dispose();
+      hemi.dispose?.();
+      capLights.key.dispose?.();
+      capLights.fill.dispose?.();
+    }
+  }
+
   // --- render loop ----------------------------------------------------------
-  function renderFrame() {
+  // 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);
+    }
+    // Per-listener guard, because three re-arms requestAnimationFrame only AFTER
+    // this callback returns (WebGLAnimation.onAnimationFrame): a listener that
+    // throws would stop the rAF chain outright and freeze the viewer for good, not
+    // just skip a frame. Containment belongs here rather than in every subscriber.
+    for (const cb of [...frameListeners]) {
+      try { cb(dt); } catch (e) { console.warn("partforge: frame listener failed", e); }
+    }
     if (cutaway.isEnabled) cutaway.updateForCamera();
     renderer.render(scene, camera);
     cutaway.renderOverlay(renderer, camera);
@@ -504,8 +614,8 @@ export function createViewer(container, part) {
   // 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 an auto-rotating scene at
-  // 60fps behind an invisible pane. On an iPhone that is tens of megabytes and
+  // 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,
@@ -530,6 +640,7 @@ export function createViewer(container, part) {
       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);
   }
 
@@ -595,6 +706,10 @@ export function createViewer(container, part) {
     // 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();
@@ -624,7 +739,11 @@ export function createViewer(container, part) {
     frame,
     captureCanonicalViews,
     captureCurrent,
-    setAutoRotate,
+    renderMeshPayloads,
+    onFrame,
+    tweenCameraTo,
+    cancelCameraTween,
+    onCameraStart,
     setActive,
     onContextLost,
     setTheme,

package/src/framework/worker.js

@@ -110,7 +110,11 @@ export function runWorker(part) {
           await handle(kernel, job.part, job.data, gated, { isStale });
         } catch (err) {
           // Same shape jobs.js posts for a failed build, so hosts need no new branch.
-          postMessage({ type: "error", message: String(err?.message || err) });
+          // Carry the job's jobId when it has one (capture/export are correlated by it):
+          // a boot failure hitting kernelFor here must reach the right controller, or a
+          // correlated caller (captureView, exportParts) would hang instead of settling.
+          const jobId = job.data?.jobId;
+          postMessage({ type: "error", message: String(err?.message || err), ...(jobId != null ? { jobId } : {}) });
         }
       }
     } finally {

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[];