partforge 0.41.0 → 0.44.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[];

package/types/index.d.ts

@@ -0,0 +1,240 @@
+// partforge — the app entry (DOM).
+//
+// This entry pulls in the three.js viewer and the control panel, so it must NOT
+// be imported from a part's build functions; those run in a Web Worker and take
+// their geometry helpers from "partforge/geometry".
+
+import type { BackendName } from "./kernel.js";
+import type { ParamValue, PartDefinition } from "./part.js";
+
+export * from "./kernel.js";
+export * from "./part.js";
+
+/** A canonical capture angle. */
+export type CanonicalView = "iso" | "front" | "back" | "left" | "right" | "top" | "bottom";
+
+/** Which pane a narrow layout shows. `null` hands selection back to partforge. */
+export type HostPane = "stage" | "rail" | null;
+
+/** An export file format. STEP is routed to OCCT automatically. */
+export type ExportFormat = "stl" | "step" | "3mf";
+
+/**
+ * A semantic click result: which sub-part was hit, where (in the sub-part's own
+ * local frame, quantized to 0.01 mm), the snapped surface normal, and only the
+ * params that sub-part actually reads.
+ */
+export interface Selection {
+  subPart: string;
+  point: [number, number, number];
+  normal: [number, number, number];
+  params: Record<string, ParamValue>;
+  /** Present when the hit surface carries a `Solid.label()` name. */
+  feature?: { label: string };
+}
+
+export interface PickEvent {
+  selection: Selection;
+  /** The feature label, the sub-part's label, or the sub-part name. */
+  label: string;
+  /** The selection formatted for an LLM prompt. */
+  prompt: string;
+  /** The selection formatted as a compact token. */
+  token: string;
+}
+
+/** Fired once per completed build. NOT fired for a pose-only edit. */
+export type BuildEvent =
+  | { status: "success"; ms?: number }
+  | { status: "error"; error: string };
+
+/** The bytes of a finished export, when the host supplies its own download sink. */
+export interface DownloadPayload {
+  data: ArrayBuffer | Uint8Array;
+  filename: string;
+  mime: string;
+}
+
+/**
+ * Element references. Every entry falls back to the legacy global-ID lookup
+ * (`#app`, `#controls`, `#panel`, `#part`, `#download*`, `#status`/`#busy`/
+ * `#phase`, `#reframe`/`#theme`/`#cutaway`/`#rail-toggle`), resolved
+ * exactly once at mount.
+ */
+export interface MountElements {
+  /** The viewer canvas host (`#app`). */
+  viewer?: HTMLElement | null;
+  /** The control panel host (`#controls`). */
+  controls?: HTMLElement | null;
+  /** The full-height controls rail (`#panel`). */
+  rail?: HTMLElement | null;
+  /**
+   * The positioned `.pf-shell` ancestor. Only needed when the rail is not a
+   * direct child of it — the resize seam is positioned against
+   * `rail.parentElement` otherwise.
+   */
+  shell?: HTMLElement | null;
+  status?: {
+    status?: HTMLElement | null;
+    busy?: HTMLElement | null;
+    phase?: HTMLElement | null;
+  };
+  /** The view-tab bar (`#part`); leave the element empty, `mount` fills it. */
+  tabs?: HTMLElement | null;
+  exports?: {
+    stl?: HTMLElement | null;
+    step?: HTMLElement | null;
+    threeMf?: HTMLElement | null;
+  };
+  chrome?: {
+    reframe?: HTMLElement | null;
+    theme?: HTMLElement | null;
+    cutaway?: HTMLElement | null;
+    railToggle?: HTMLElement | null;
+  };
+}
+
+export interface MountOptions {
+  /**
+   * Spawns a geometry worker. Called once per backend with `name` as the
+   * Worker's `name` option. The `new Worker(new URL(...))` call must stay
+   * inline in the app module or Vite will not bundle the worker.
+   */
+  createWorker: (name: BackendName) => Worker;
+  elements?: MountElements;
+  onBuild?: (event: BuildEvent) => void;
+  /**
+   * Programmatic click-to-select. Supplying this arms the picker permanently
+   * and takes precedence over the `?pick` and `?pickserver` URL modes.
+   */
+  onPick?: (event: PickEvent) => void;
+  /** Receive exported bytes instead of partforge's own DOM download. */
+  onDownload?: (file: DownloadPayload) => void;
+  /** @deprecated alias for `elements.viewer`. */
+  container?: HTMLElement | null;
+  /** @deprecated alias for `elements.controls`. */
+  controls?: HTMLElement | null;
+}
+
+export interface ExportPartsOptions {
+  /** Sub-part names, as `listExportableParts()` reports them. */
+  parts: string[];
+  format: ExportFormat;
+  /** Mesh quality for STL/3MF. Defaults to `"print"`. */
+  quality?: "preview" | "print";
+  onProgress?: (phase: string) => void;
+}
+
+export interface CaptureCurrentOptions {
+  /** Long-edge resolution in px, clamped into `[256, maxTextureSize]`. */
+  size?: number;
+  /** Keep the floor grid so the capture matches the on-screen look. */
+  hideGrid?: boolean;
+  /** JPEG quality, 0..1. */
+  quality?: number;
+}
+
+/** Where playback is: idle, swinging the camera to an intro cue, playing, or paused. */
+export type AnimationStatus = "idle" | "intro" | "playing" | "paused";
+
+export interface AnimationState {
+  /** The selected animation's key. */
+  animation: string;
+  status: AnimationStatus;
+  /** Position on the timeline, 0..1 over the animation's total duration. */
+  t: number;
+  /** Which step `t` falls in; 0 for a single-step animation. */
+  stepIndex: number;
+}
+
+/**
+ * Part-declared animation playback — the same engine the viewer's transport bar
+ * drives. Playback writes real params, so exporting while paused exports the
+ * posed state, and any user or host param edit pauses it.
+ */
+export interface AnimationRuntime {
+  /**
+   * Play, optionally switching to a named animation first. An unknown name
+   * warns and does nothing rather than playing whatever is selected.
+   */
+  play(name?: string): void;
+  pause(): void;
+  /** Jump to a position on the timeline, 0..1. Never moves the camera. */
+  seek(t: number): void;
+  /** Stop and restore the param values the animation started from. */
+  stop(): void;
+  state(): AnimationState;
+}
+
+/** The runtime handle `mount()` returns. See `makeHandle` in src/framework/mount.js. */
+export interface PartRuntime {
+  /** Resolves on the first successful build of the default view; rejects on a first-build error. */
+  ready: Promise<void>;
+  /** Full teardown of everything this mount created. Idempotent. */
+  dispose(): void;
+  /**
+   * Programmatic param entry point (the animation hook). Same change path as a
+   * slider edit: pose-only changes repair synchronously, geometry changes fall
+   * through to the regen loop.
+   */
+  setParams(partial: Record<string, ParamValue>): void;
+  /**
+   * Canonical-angle captures (fixed poses, framed to the visible assembly,
+   * 1024², grid hidden) — sized for feeding a vision model. Defaults to
+   * `["iso", "front", "top"]`; unknown names are dropped.
+   */
+  captureViews(viewNames?: CanonicalView[] | string[]): Array<{ view: string; dataUrl: string }>;
+  /**
+   * One offscreen render of the user's CURRENT framing at a chosen resolution —
+   * the showcase capture. Returns a `data:image/jpeg;base64,…` string, or `null`
+   * when disposed or nothing is built yet. Never throws.
+   */
+  captureCurrent(opts?: CaptureCurrentOptions): string | null;
+  /**
+   * Park/unpark the viewer: stops the render loop and releases the drawing
+   * buffer and cached capture target. For a host that hides the canvas without
+   * unmounting it. Captures still work while parked. Safe after `dispose()`.
+   */
+  setActive(active: boolean): void;
+  /**
+   * Subscribe to WebGL context loss — i.e. the GPU or the OS gave up — so a host
+   * can say so rather than showing a dead canvas. The listener takes no
+   * arguments (the underlying event is consumed and `preventDefault`ed).
+   * Returns an unsubscribe.
+   */
+  onContextLost(listener: () => void): () => void;
+  /**
+   * Every exportable sub-part — excludes any `exportable: false` part, respects
+   * each part's `enabled(params)` — INDEPENDENT of the active view.
+   */
+  listExportableParts(): Array<{ name: string; label: string }>;
+  /**
+   * Headless export of a chosen subset. Resolves once the file is written
+   * (handed to your `onDownload` sink, or downloaded directly); rejects on
+   * build/export failure or an empty selection.
+   */
+  exportParts(opts: ExportPartsOptions): Promise<void>;
+  /**
+   * Narrow-layout pane selection, for a host that draws its own tab bar.
+   * `null` hands selection back to partforge's built-in bar.
+   */
+  setHostPane(pane: HostPane): void;
+  /**
+   * Part-declared animation playback, or `null` when the part declares no
+   * `animations` block.
+   */
+  animation: AnimationRuntime | null;
+}
+
+/** Mount a full parametric-part app from a `PartDefinition`. */
+export function mount(part: PartDefinition, options: MountOptions): PartRuntime;
+
+/**
+ * The sub-parts a view shows: declared in the view and `enabled` for these
+ * params, in `Object.keys(part.parts)` order. Handy for app-side view logic.
+ */
+export function viewSubParts(
+  part: PartDefinition,
+  view: string,
+  params: Record<string, ParamValue>,
+): string[];