partforge 0.41.0 → 0.45.0

package/types/testing.d.ts

@@ -0,0 +1,362 @@
+// partforge/testing — headless helpers for building, measuring and verifying a
+// part with no browser.
+//
+// Most of what this barrel re-exports is NOT test-only: the oracle
+// (measure/verify/buildView/gaps/BVH/min-wall) also runs inside the browser
+// geometry worker. Only the two kernel booters and the PNG renderer are
+// Node-bound.
+
+import type { GeometryKernel, Mesh, Point3, Solid } from "./kernel.js";
+import type { Derived, FontSource, PartDefinition, ResolvedParams } from "./part.js";
+
+export type { Derived, GeometryKernel, Mesh, PartDefinition, ResolvedParams, Solid };
+
+// --- kernels ----------------------------------------------------------------
+
+/**
+ * Wrap an already-instantiated Manifold WASM module as a `GeometryKernel`.
+ * `wasm` is the value of `await Module()` from `manifold-3d`, after `setup()`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- the opaque manifold-3d WASM module
+export function createManifoldKernel(wasm: any, opts?: { quality?: "preview" | "print" }): GeometryKernel;
+
+/**
+ * Boot the Manifold WASM module in a Node process and return a ready kernel.
+ * OCCT must NOT be booted in the same process — keep OCCT tests in their own
+ * files (vitest isolates per file).
+ */
+export function bootManifoldKernel(opts?: {
+  quality?: "preview" | "print";
+  fonts?: Record<string, FontSource>;
+}): Promise<GeometryKernel>;
+
+/** Boot OCCT/replicad in a Node process and return a ready kernel. */
+export function bootOcctKernel(opts?: { fonts?: Record<string, FontSource> }): Promise<GeometryKernel>;
+
+// --- the job loop -----------------------------------------------------------
+
+/** A job the worker loop accepts. */
+export interface WorkerJob {
+  type: "generate" | "export-stl" | "export-step" | "export-3mf" | "inspect";
+  view?: string;
+  params?: ResolvedParams;
+  /** `generate`: which sub-parts to build. */
+  subparts?: string[];
+  /** Export: an explicit sub-part selection, overriding the view's. */
+  parts?: string[];
+  quality?: "preview" | "print";
+  cache?: boolean;
+  /** Correlation id echoed on every reply. */
+  jobId?: number;
+  /** Single-file export name base. */
+  name?: string;
+}
+
+/**
+ * Run one worker job against `kernel`/`part`, posting replies through `post`.
+ * The same loop the geometry Web Worker runs, exposed so a test can exercise an
+ * export end to end without a Worker.
+ */
+export function handle(
+  kernel: GeometryKernel,
+  part: PartDefinition,
+  msg: WorkerJob,
+  post: (message: Record<string, unknown>, transfer?: Transferable[]) => void,
+  opts?: { isStale?: () => boolean },
+): Promise<void>;
+
+// --- the part model ---------------------------------------------------------
+
+/** The sub-parts a view shows, in definition order. */
+export function viewSubParts(part: PartDefinition, view: string, params: ResolvedParams): string[];
+
+/** Resolve a part's `derive` into the `d` object builds receive. */
+export function resolveDerived(part: Pick<PartDefinition, "derive">, p: ResolvedParams): Derived;
+
+/** Returned instead of a key set when the relevance analysis could not run. */
+export const RELEVANT_ALL: unique symbol;
+
+/**
+ * Which raw parameters affect the parts on screen in `view` — a `Set` of param
+ * keys, or `RELEVANT_ALL` when the build could not be analyzed.
+ */
+export function relevantParamKeys(
+  part: PartDefinition,
+  view: string,
+  params: ResolvedParams,
+): Set<string> | typeof RELEVANT_ALL;
+
+// --- assembly checks --------------------------------------------------------
+
+/** One interpenetrating pair. `location` is the intersection bbox centre. */
+export interface Overlap {
+  a: string;
+  b: string;
+  /** Intersection volume in mm³. */
+  volume: number;
+  location: Point3 | null;
+}
+
+/** One measured pair distance. `distance` 0 = touching or interpenetrating. */
+export interface Gap {
+  a: string;
+  b: string;
+  distance: number;
+  /** The midpoint between the pair's closest surface points. */
+  at: Point3 | null;
+}
+
+/**
+ * Build every sub-part of a view in its assembly pose and return the pairs whose
+ * solid-intersection volume exceeds `tolerance` mm³. Manifold-only (needs
+ * `Solid.intersect`).
+ */
+export function assemblyOverlaps(
+  kernel: GeometryKernel,
+  part: PartDefinition,
+  view: string,
+  params?: ResolvedParams,
+  opts?: { tolerance?: number },
+): Overlap[];
+
+/**
+ * The complement of `assemblyOverlaps`: sub-part pairs that ALMOST touch
+ * (0 < distance < `threshold` mm) in the display pose. Pure mesh math, so it
+ * runs on both backends.
+ */
+export function assemblyGaps(
+  kernel: GeometryKernel,
+  part: PartDefinition,
+  view: string,
+  params?: ResolvedParams,
+  opts?: { threshold?: number },
+): Gap[];
+
+/** One sub-part built in its display pose, as `buildView` returns it. */
+export interface BuiltSubPart {
+  name: string;
+  /** LIVE — valid only until `kernel.cleanup()`. */
+  solid: Solid;
+  /** JS-owned arrays; survives `cleanup()`. */
+  mesh: Mesh;
+}
+
+/**
+ * Minimum surface-to-surface distance for every pair of pre-built posed meshes.
+ * Pairs involving an empty mesh are skipped. `bvhCache` is a caller-owned `Map`
+ * so each mesh is indexed once across passes.
+ */
+export function meshGaps(built: BuiltSubPart[], opts?: { bvhCache?: Map<Mesh, BVH> }): Gap[];
+
+/**
+ * Build every sub-part of a view in its display pose. Keeps solids LIVE (does
+ * NOT call `kernel.cleanup()`) so callers can read exact solid facts first.
+ */
+export function buildView(
+  kernel: GeometryKernel,
+  part: PartDefinition,
+  view: string,
+  params?: ResolvedParams,
+): BuiltSubPart[];
+
+// --- mesh math --------------------------------------------------------------
+
+/** Signed-tetrahedron volume of a triangle mesh. Omit `indices` for a flat soup. */
+export function meshVolume(positions: ArrayLike<number>, indices?: ArrayLike<number>): number;
+
+/** `[dx, dy, dz]` extent of a flat position array. */
+export function bboxSize(positions: ArrayLike<number>): [number, number, number];
+
+// --- the BVH ----------------------------------------------------------------
+
+/** A triangle BVH over one mesh — nearest ray hit, nearest point, exact mesh distance. */
+export interface BVH {
+  /** Nearest hit along `dir` from `origin`, or `null`. `t` is the distance, `tri` the mesh triangle id. */
+  raycast(
+    origin: Point3,
+    dir: Point3,
+    opts?: { tMin?: number; tMax?: number; skipTri?: number },
+  ): { t: number; tri: number } | null;
+  /** Nearest surface point to `p`. */
+  closestPoint(p: Point3): { point: number[] | null; dist: number; tri: number };
+  /** Exact minimum surface-to-surface distance to another BVH. */
+  distanceTo(other: BVH): {
+    distance: number;
+    at: number[] | null;
+    pointA: number[] | null;
+    pointB: number[] | null;
+  };
+  triangleCount: number;
+  /** Flat, 9 coords per triangle, in mesh order. READ-ONLY — writing invalidates the tree. */
+  vertices: Float32Array | Float64Array;
+  /** The root AABB, `[minx, miny, minz, maxx, maxy, maxz]` (a copy). */
+  rootBounds: number[];
+  /** Diagnostic self-report of the four typed arrays' byte lengths. */
+  bytesAllocated: number;
+}
+
+/** Index a mesh (Manifold soup or OCCT indexed form) for spatial queries. */
+export function buildBVH(mesh: Mesh): BVH;
+
+/**
+ * Min wall thickness by inward ray-casting per surface triangle. `null` only for
+ * an EMPTY mesh; a mesh whose rays all miss returns `value: null` WITH the
+ * sampling accounting, so "we looked and found nothing" stays distinguishable
+ * from "nobody looked". A sampled reading is an upper bound on the true minimum.
+ */
+export function minWall(
+  mesh: Mesh,
+  opts?: { maxThickness?: number; maxSamples?: number; bvh?: BVH },
+): {
+  value: number | null;
+  location: Point3 | null;
+  sampled: boolean;
+  /** The sample BUDGET — triangles selected, not rays actually cast. */
+  sampledTriangles: number;
+  totalTriangles: number;
+} | null;
+
+// --- measure ----------------------------------------------------------------
+
+export interface SubPartFacts {
+  name: string;
+  /** Size only — `[dx, dy, dz]`. */
+  bbox: number[];
+  /** Where the geometry sits. */
+  bounds: { min: number[]; max: number[] };
+  /** Volume-weighted centroid, or `null` for a degenerate/zero-volume sub-part. */
+  centerOfMass: number[] | null;
+  volume: number;
+  surfaceArea: number;
+  triangleCount: number;
+  /** Manifold-only; `null` on OCCT. */
+  watertight: boolean | null;
+  /** Through-hole count (genus). Manifold-only; `null` on OCCT. */
+  holes: number | null;
+  /** `null` exactly when no reading exists. */
+  minWall: number | null;
+  minWallAt: number[] | null;
+  minWallSampled: boolean;
+  minWallSamples: { sampled: number; total: number } | null;
+}
+
+export interface AggregateFacts {
+  bbox: number[];
+  bounds: { min: number[]; max: number[] };
+  centerOfMass: number[] | null;
+  volume: number;
+  surfaceArea: number;
+  triangleCount: number;
+}
+
+export interface MeasureReport {
+  /** `part.meta.title`, falling back to the view name. */
+  part: string;
+  view: string;
+  /** Whether this run cast min-wall rays at all. */
+  measuredMinWall: boolean;
+  subparts: SubPartFacts[];
+  aggregate: AggregateFacts;
+  overlaps: Overlap[];
+  /** Every sub-part pair's minimum surface distance. */
+  gaps: Gap[];
+  /** The pairs with an unintended-looking gap under the threshold. */
+  nearMisses: Gap[];
+  /** Every sub-part watertight and nothing interpenetrating. Near misses never affect it. */
+  ok: boolean;
+}
+
+/** Headless geometric report for one view of a part. */
+export function measure(
+  kernel: GeometryKernel,
+  part: PartDefinition,
+  view?: string,
+  params?: ResolvedParams,
+  opts?: { minWall?: boolean; gapThreshold?: number },
+): MeasureReport;
+
+// --- verify -----------------------------------------------------------------
+
+export type CheckStatus = "pass" | "fail" | "warn" | "skip";
+
+export interface VerifyCheck {
+  scope: "view" | "subpart";
+  /** The sub-part name, `"a×b"` for a pair check, or `null` for a scalar view metric. */
+  subpart: string | null;
+  metric: string;
+  /** `gate` failures set a non-zero exit code; `warn` never blocks. */
+  kind: "gate" | "warn";
+  /** The asserted expression, stringified. */
+  expr: string;
+  actual: unknown;
+  status: CheckStatus;
+  pass: boolean | null;
+  message: string;
+  /** One self-contained corrective sentence (part-authored `hint` wins). */
+  hint?: string;
+  /** A stable ERROR-PATTERNS.md entry id. */
+  pattern?: string;
+  /** A caveat about HOW the value was measured — today only `minWall` sets one. */
+  note?: string;
+  /** `[x, y, z]` in mm, for the metrics that have one. */
+  location?: number[] | null;
+}
+
+export interface VerifyCaseResult {
+  /** `"defaults"` or a preset name. */
+  name: string;
+  params: ResolvedParams;
+  checks: VerifyCheck[];
+}
+
+export interface VerifyReport {
+  /** True when no check has status `"fail"`. */
+  ok: boolean;
+  view: string;
+  cases: VerifyCaseResult[];
+  /** Every failing check, flattened, each tagged with its `case`. */
+  failures: Array<VerifyCheck & { case: string }>;
+  warnings: Array<VerifyCheck & { case: string }>;
+}
+
+/**
+ * Enforce a part's `verify` block across the default config plus every preset
+ * (or its declared `cases`).
+ *
+ * `seed` lets a caller that has already measured the part hand the result in so
+ * verify does not recompute it. It is consulted only when the seed was measured
+ * with min wall (or this run needs none) and for the same view.
+ */
+export function verify(
+  kernel: GeometryKernel,
+  part: PartDefinition,
+  opts?: {
+    /** Force or override the DFM profile. */
+    process?: string | Record<string, unknown>;
+    view?: string;
+    measureFn?: typeof measure;
+    seed?: { params?: ResolvedParams; result: MeasureReport };
+  },
+): VerifyReport;
+
+// --- rendering --------------------------------------------------------------
+
+/** The canonical angle names `renderViews` accepts. */
+export const RENDER_VIEWS: string[];
+
+/**
+ * Render canonical-angle PNGs of one view with a pure-JS software rasterizer —
+ * no native module, no browser. Returns the written file paths.
+ */
+export function renderViews(
+  kernel: GeometryKernel,
+  part: PartDefinition,
+  view?: string,
+  opts?: {
+    views?: string[];
+    out?: string;
+    size?: [number, number];
+    edges?: boolean;
+    params?: ResolvedParams;
+  },
+): Promise<string[]>;

package/types/worker.d.ts

@@ -0,0 +1,21 @@
+// partforge/worker — the geometry Web Worker runtime shared by every part.
+//
+// The host spawns this entry twice, named "manifold" (preview + STL + 3MF) and
+// "occt" (STEP), via the Worker `name` option. Each instance lazily imports only
+// its own backend.
+
+import type { PartDefinition } from "./part.js";
+
+/** The rebind handle `runWorker` returns. */
+export interface WorkerHandle {
+  /**
+   * Swap the part this worker builds, cancelling stale builds, sweeping idle
+   * cache partitions and re-posting `ready` — so a remounting host gates its
+   * first generate exactly as on a fresh worker, without losing the warm kernel.
+   * The rebind contract is normative in docs/KERNEL-CONTRACT.md.
+   */
+  setPart(newPart: PartDefinition): void;
+}
+
+/** Run the worker job loop for `part`. Call once, at worker module top level. */
+export function runWorker(part: PartDefinition): WorkerHandle;