partforge 0.41.0 → 0.44.0

package/types/kernel.d.ts

@@ -0,0 +1,409 @@
+// Type declarations for the backend-agnostic geometry kernel.
+//
+// This is the TypeScript half of the contract stated twice already: the
+// `@typedef`s in src/framework/geometry/kernel.js (signatures) and
+// docs/KERNEL-CONTRACT.md (prose semantics). The op LISTS in kernel.js
+// (KERNEL_OPS / KERNEL_OPTIONAL_OPS / SOLID_OPS / SOLID_OPTIONAL_OPS /
+// SHAPE2D_OPS / OCCT_ONLY_OPS) are data, and test/types-surface.test.js holds
+// the interfaces below to them member-for-member — so an op added to the kernel
+// cannot silently go undeclared here.
+//
+// Units are millimetres throughout.
+
+/** A 2-D point, `[x, y]`. */
+export type Point2 = [number, number] | number[];
+/** A 3-D point or vector, `[x, y, z]`. */
+export type Point3 = [number, number, number] | number[];
+
+/** A closed CCW contour as a plain point list (the `polygon.js` helpers' output). */
+export type PointsContour = Point2[];
+
+/**
+ * A curve-native contour that carries arcs/béziers SYMBOLICALLY — the output of
+ * `roundedProfile()` and `pathProfile(...).close()`. OCCT turns these into exact
+ * B-rep edges (true circles in STEP); Manifold tessellates them at mesh LOD.
+ */
+export interface ArcContour {
+  start: Point2;
+  segments: Array<{ to: Point2; via?: Point2; c1?: Point2; c2?: Point2 }>;
+  /** Set by `roundedProfile`; absent on a `pathProfile` contour. */
+  arc?: boolean;
+}
+
+/** Either contour form. */
+export type Contour = PointsContour | ArcContour;
+
+/** A polygon-with-holes region: one outer contour and any number of hole contours. */
+export interface Region2D {
+  outer: Contour;
+  holes?: Contour[];
+}
+
+/** Anything the kernel accepts where a 2-D profile is wanted. */
+export type ProfileInput = Contour | Region2D | Shape2D;
+
+/** Mesh level of detail. Manifold bakes this in at primitive creation. */
+export type MeshQuality = "preview" | "print";
+
+/** A triangle soup (Manifold) or an indexed mesh (OCCT), as `Solid.toMesh()` returns it. */
+export interface Mesh {
+  positions: Float32Array;
+  normals: Float32Array;
+  /** Present on the OCCT backend; absent for a Manifold non-indexed soup. */
+  indices?: Uint32Array;
+  triangles: number;
+  /** Feature-edge line segments (Manifold). */
+  edges?: Float32Array;
+}
+
+/** The indexed mesh 3MF export needs. */
+export interface IndexedMesh {
+  positions: Float32Array;
+  indices: Uint32Array;
+}
+
+/** Axis-aligned bounds of a solid. */
+export interface BoundingBox3 {
+  min: number[];
+  max: number[];
+  center: number[];
+  size: number[];
+}
+
+/** Axis-aligned bounds of a 2-D shape. */
+export interface BoundingBox2 {
+  min: number[];
+  max: number[];
+}
+
+/** A materialized region: point rings only, arcs already flattened. */
+export interface MaterializedRegion {
+  outer: number[][];
+  holes: number[][][];
+}
+
+/** Which geometry backend a part builds on. */
+export type BackendName = "manifold" | "occt";
+
+/** Cardinal direction for `Solid.along()`. */
+export type AxisDirection = "+X" | "-X" | "+Y" | "-Y" | "+Z" | "-Z";
+/** A mirror plane. */
+export type MirrorPlane = "XY" | "XZ" | "YZ";
+/** A named world axis. */
+export type AxisName = "X" | "Y" | "Z";
+
+/** Convex-corner style for an offset. */
+export type OffsetCorners = "round" | "chamfer" | "sharp";
+
+// --- edge / face selectors (OCCT-only ops) ---------------------------------
+
+/**
+ * Which edges a `fillet`/`chamfer` applies to. Omit for every edge. The object
+ * forms are portable across backends-by-contract; a raw replicad finder callback
+ * is an OCCT-only escape hatch (see docs/KERNEL-CONTRACT.md).
+ */
+export type EdgeSelector =
+  | { dir: AxisName }
+  | { inPlane: MirrorPlane; at?: number }
+  | { near: Point3 }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- an opaque replicad EdgeFinder
+  | ((finder: any) => any);
+
+/** Which face(s) `shell` opens. Same forms as `EdgeSelector`. */
+export type FaceSelector = EdgeSelector;
+
+// --- Shape2D ----------------------------------------------------------------
+
+/**
+ * An opaque 2-D boolean value (Manifold wraps a CrossSection, OCCT a replicad
+ * Drawing). `_`-prefixed keys are backend internals and are not declared.
+ */
+export interface Shape2D {
+  union(other: Shape2D | Contour): Shape2D;
+  cut(other: Shape2D | Contour): Shape2D;
+  /** Batch subtract. */
+  cutAll(others: Array<Shape2D | Contour>): Shape2D;
+  intersect(other: Shape2D | Contour): Shape2D;
+  /**
+   * Grow (`delta > 0`) or inset (`delta < 0`). Curve-preserving on OCCT,
+   * faceted at mesh LOD on Manifold. Throws if the offset collapses the shape.
+   */
+  offset(delta: number, opts?: { corners?: OffsetCorners; segs?: number }): Shape2D;
+  /** Net area (outers minus holes), mm². */
+  area(): number;
+  boundingBox(): BoundingBox2;
+  /** Materialize into region arrays. */
+  toRegions(): MaterializedRegion[];
+  /** `toRegions()` unwrapped — throws unless there is exactly one region. */
+  simple(): MaterializedRegion;
+  /** Scission: each disjoint region as its own live `Shape2D`. */
+  regions(): Shape2D[];
+  clone(): Shape2D;
+  /** Sugar for `k.extrude({ profile: this, ... })`. */
+  extrude(opts: { h: number; twist?: number; scaleTop?: number }): Solid;
+  /** Sugar for `k.revolve({ profile: this, ... })`. */
+  revolve(opts?: { degrees?: number }): Solid;
+}
+
+// --- Solid ------------------------------------------------------------------
+
+/**
+ * An opaque handle to a backend solid. `_`-prefixed keys are backend internals
+ * and are not declared.
+ *
+ * On the OCCT backend a transform CONSUMES its operand — never reuse a solid
+ * after transforming it; `.clone()` first.
+ */
+export interface Solid {
+  cut(tool: Solid): Solid;
+  /** Batch subtract (backend-optimized). */
+  cutAll(tools: Solid[]): Solid;
+  intersect(other: Solid): Solid;
+  /** Boolean union with one other solid (n-ary: `k.union([...])`). */
+  union(other: Solid): Solid;
+  /** Independent copy. */
+  clone(): Solid;
+  /**
+   * Name this solid's surface for hover/pick feature attribution. Survives
+   * transforms and booleans; the same name on several solids merges into one
+   * feature.
+   */
+  label(name: string): Solid;
+  /** Axis-aligned bounds (a query, not a transform). */
+  boundingBox(): BoundingBox3;
+  /** Volume in mm³. */
+  volume(): number;
+  translate(v: Point3): Solid;
+  /** Internal primitive — prefer `rotateX`/`rotateY`/`rotateZ`/`rotateAbout`. */
+  rotate(deg: number, center: Point3, axis: Point3): Solid;
+  rotateX(deg: number): Solid;
+  rotateY(deg: number): Solid;
+  rotateZ(deg: number): Solid;
+  /** General rotation: `axis` names a world axis or gives a vector. */
+  rotateAbout(o: { axis: AxisName | Point3; deg: number; through?: Point3 }): Solid;
+  /** Orient the canonical +Z build axis along `dir`. */
+  along(dir: AxisDirection): Solid;
+  /** Place an origin-built solid at point `v` (readable alias of `translate`). */
+  at(v: Point3): Solid;
+  mirror(plane: MirrorPlane): Solid;
+  /** Uniform scale about `center` (default origin). */
+  scale(factor: number, center?: Point3): Solid;
+  toMesh(opts?: { quality?: MeshQuality }): Mesh;
+  toSTL(opts?: { quality?: MeshQuality }): Promise<ArrayBuffer>;
+  toIndexedMesh(): IndexedMesh;
+  /**
+   * Round edges — OCCT only (Manifold throws `KernelCapabilityError`, and the
+   * probe routes a part that calls this to OCCT). Legacy `(r, selector)` is
+   * accepted until contract v2.
+   */
+  fillet(r: number | { r: number; edges?: EdgeSelector }): Solid;
+  /** Bevel edges — OCCT only. Legacy `(d, selector)` accepted until contract v2. */
+  chamfer(d: number | { d: number; edges?: EdgeSelector }): Solid;
+  /**
+   * Hollow inward, wall `t`, opening the faces `open` selects — OCCT only.
+   * Closed (no open face) hollows are not supported.
+   */
+  shell(o: { t: number; open: FaceSelector }): Solid;
+  /** Through-hole count (Manifold only). */
+  genus?(): number;
+  /** No geometry at all (Manifold only). */
+  isEmpty?(): boolean;
+}
+
+// --- kernel op option objects ----------------------------------------------
+
+/** `k.cylinder` — a straight cylinder (`r`|`d`) or a frustum (`r1`,`r2` / `d1`,`d2`). */
+export interface CylinderOptions {
+  r?: number;
+  d?: number;
+  r1?: number;
+  r2?: number;
+  d1?: number;
+  d2?: number;
+  h: number;
+  /** Centre the solid on Z too (default: base at z = 0). */
+  center?: boolean;
+}
+
+export interface BoxOptions {
+  /** `[x, y, z]` — centred in X/Y with the base at z = 0. */
+  size?: Point3;
+  center?: boolean;
+  min?: Point3;
+  max?: Point3;
+}
+
+export interface PrismOptions {
+  points: PointsContour | ArcContour;
+  h: number;
+  /** Degrees of twist over the height. */
+  twist?: number;
+  /** Uniform top taper: 1 straight, < 1 taper in, 0 → a point. */
+  scaleTop?: number;
+}
+
+export interface ExtrudeOptions {
+  profile: ProfileInput;
+  h: number;
+  twist?: number;
+  scaleTop?: number;
+  /** 45° rim bevel (no `twist`/`scaleTop`; `bottom + top < h`). */
+  bevel?: number | { bottom?: number; top?: number };
+}
+
+export interface LoftRing {
+  polygon?: PointsContour;
+  sides?: number;
+  radius?: number;
+  z: number;
+  /** Degrees about Z. */
+  rotate?: number;
+  scale?: number | Point2;
+}
+
+export interface LoftOptions {
+  rings: LoftRing[];
+  /** `false` = smooth C2 blend, honoured only by OCCT. */
+  ruled?: boolean;
+  /** Capless loop — Manifold only. */
+  closed?: boolean;
+}
+
+export interface SweepOptions {
+  profile: PointsContour;
+  /** A 3-D polyline, `[[x, y, z], …]`. */
+  path: Point3[];
+  /** Capless loop (must be planar) — Manifold only. */
+  closed?: boolean;
+  cornerRadius?: number;
+  ruled?: boolean;
+  /** OCCT-native swept B-rep. */
+  smooth?: boolean;
+}
+
+/** `k.revolve` — a lathe profile `[[r, z], …]` with `r >= 0`, revolved about Z. */
+export interface RevolveOptions {
+  profile: ProfileInput;
+  degrees?: number;
+}
+
+export interface HelixSweptTubeOptions {
+  pathR: number;
+  profileR: number;
+  pitch: number;
+  turns: number;
+  z0: number;
+  lefthand: boolean;
+}
+
+export interface RoundedCylinderOptions {
+  r?: number;
+  d?: number;
+  h: number;
+  center?: boolean;
+  /** Rim round-over: a number (both rims) or per-rim. `round <= r`, `top + bottom <= h`. */
+  round: number | { top?: number; bottom?: number };
+}
+
+export interface RoundedBoxOptions {
+  size: Point3;
+  center?: boolean;
+  /** `side` = vertical edges, `top`/`bottom` = rims. */
+  round: number | { side?: number; top?: number; bottom?: number };
+}
+
+export interface TorusOptions {
+  rMajor: number;
+  rMinor: number;
+}
+
+export interface BoredCylinderOptions {
+  od: number;
+  h: number;
+  bore: number;
+}
+
+/** Horizontal alignment of a `text2d` block. */
+export type TextAlign = "center" | "left" | "right";
+/** Vertical alignment of a `text2d` block. */
+export type TextVAlign = "middle" | "baseline" | "top" | "bottom";
+
+export interface Text2dOptions {
+  /** Cap height in mm (the design height of a capital letter). */
+  size: number;
+  /** A name declared in the part's `fonts` map; omit for the bundled default. */
+  font?: string;
+  align?: TextAlign;
+  valign?: TextVAlign;
+  /** Baseline-to-baseline distance in mm; omit for the font-metrics default. */
+  lineHeight?: number;
+  /** Letter spacing in mm. */
+  tracking?: number;
+  /** Pair-wise kerning (default `true`). */
+  kerning?: boolean;
+}
+
+/** Anything `k.hull`/`k.hullChain` accepts as one input. */
+export type HullInput = Shape2D | Contour;
+
+// --- the kernel -------------------------------------------------------------
+
+/**
+ * The backend-agnostic kernel handed to `build(k, p, d)`. The same code runs on
+ * Manifold (mesh CSG) and OCCT/replicad (exact B-rep).
+ *
+ * Every multi-parameter op takes a single options object — the canonical calling
+ * convention. Legacy positional forms stay silently accepted until contract v2
+ * and are deliberately NOT declared here.
+ */
+export interface GeometryKernel {
+  cylinder(o: CylinderOptions): Solid;
+  /** Compound: a bored-through cylinder as one cache node. */
+  boredCylinder(o: BoredCylinderOptions): Solid;
+  /** Sphere centred at the origin; the bare `sphere(r)` form stays valid. */
+  sphere(o: { r?: number; d?: number } | number): Solid;
+  box(o: BoxOptions): Solid;
+  /** Extrude a polygon (or arc profile) from z = 0. */
+  prism(o: PrismOptions): Solid;
+  /** Extrude a polygon-with-holes region from z = 0. */
+  extrude(o: ExtrudeOptions): Solid;
+  /** Revolve a lathe profile around Z. */
+  revolve(o: RevolveOptions): Solid;
+  /** Stack polygon cross-sections into a solid. */
+  loft(o: LoftOptions): Solid;
+  /** Sweep a 2-D profile along a 3-D polyline. */
+  sweep(o: SweepOptions): Solid;
+  helixSweptTube(o: HelixSweptTubeOptions): Solid;
+  /** Rim round-overs via one lathe revolve; curve-exact in STEP. */
+  roundedCylinder(o: RoundedCylinderOptions): Solid;
+  torus(o: TorusOptions): Solid;
+  /** Selective edge rounding. Stays on Manifold (unlike `Solid.fillet`). */
+  roundedBox(o: RoundedBoxOptions): Solid;
+  /** N-ary boolean union. */
+  union(solids: Solid[]): Solid;
+  /** Lift a profile into a 2-D boolean value. */
+  shape2d(profile: ProfileInput): Shape2D;
+  /** Render outline-font text as a `Shape2D`. */
+  text2d(string: string, opts?: Text2dOptions): Shape2D;
+  /** Convex hull of all inputs → a convex (faceted) `Shape2D`. */
+  hull(inputs: HullInput[]): Shape2D;
+  /** Swept hull over an ordered sequence (>= 2 inputs). */
+  hullChain(inputs: HullInput[]): Shape2D;
+  /** STEP bytes — OCCT only (Manifold throws `KernelCapabilityError`). */
+  toSTEP(named: Array<{ name: string; solid: Solid }>): Promise<ArrayBuffer>;
+
+  // Backend-optional: the sub-part cache brackets and WASM lifetime hooks. Every
+  // framework caller reaches these through `?.`, so a third-party backend may
+  // omit them entirely.
+
+  /** Open a per-sub-part solid-cache round. */
+  beginSubPart?(name: string): void;
+  /** Close the cache round — always pair with `beginSubPart`. */
+  endSubPart?(): void;
+  /** Drop cache partitions idle for 3 rebinds. Never call mid-bracket. */
+  sweepCache?(): void;
+  cacheStats?(): { hits: number; misses: number };
+  resetCacheStats?(): void;
+  /** Free per-job WASM objects (Manifold backend); call after each job. */
+  cleanup?(): void;
+}

package/types/lint.d.ts

@@ -0,0 +1,85 @@
+// partforge/lint — static PartDefinition validation.
+//
+// Zero runtime dependencies: it never imports a geometry kernel or the DOM
+// viewer, so it runs unchanged in Node, a Web Worker, a sandboxed iframe, and
+// Deno.
+
+import type { Derived, PartDefinition, ResolvedParams } from "./part.js";
+
+/**
+ * `error` = the part is provably broken (it cannot behave as authored, whether
+ * or not that surfaces as a throw). `warning` = suspicious or lossy, but the
+ * part behaves as authored; a warning never blocks anything. `note` = neither
+ * broken nor suspicious — informational context for an authoring agent (e.g.
+ * "this animated track rebuilds geometry"); notes never gate `measure` or
+ * `--strict`.
+ */
+export type FindingSeverity = "error" | "warning" | "note";
+
+export interface Finding {
+  /** The rule id, e.g. `"features-requires-sliders"`. */
+  rule: string;
+  severity: FindingSeverity;
+  message: string;
+  /** One self-contained corrective sentence. Always present. */
+  hint: string;
+  /**
+   * A JS accessor path rooted at the PartDefinition —
+   * `parameters[1].features[0]`, `defaults.bore`, `parts.spacer.views[0]`.
+   * `""` for findings about the definition as a whole. For navigation only.
+   */
+  path: string;
+  /** A stable ERROR-PATTERNS.md entry id, when one applies. */
+  pattern?: string;
+}
+
+export interface LintReport {
+  /** True when there are no `error` findings. Warnings do not affect it. */
+  ok: boolean;
+  errors: Finding[];
+  warnings: Finding[];
+  /** Informational findings. Never affect `ok`, `measure`, or `--strict`. */
+  notes: Finding[];
+}
+
+/**
+ * Lint a PartDefinition. NEVER throws — a rule that throws yields an
+ * `internal-rule-error` warning and the run continues.
+ *
+ * @param part - the default-exported PartDefinition (deliberately `unknown`:
+ *   lint's whole job is to be handed something that may not be one).
+ * @param opts - `params` are layered over `part.defaults` for the probe pass.
+ */
+export function lintPart(part: unknown, opts?: { params?: ResolvedParams } | null): LintReport;
+
+/** The shared context a rule reads. */
+export interface LintContext {
+  part: unknown;
+  /** `{ ...part.defaults, ...params }`, or `{}` if building it threw. */
+  p: ResolvedParams;
+  /** `resolveDerived(part, p)`, or `{}` if it threw. */
+  d: Derived;
+  /** The message from a throwing `defaults`/`params` read, else `null`. */
+  pError: string | null;
+  /** The message from a throwing `derive()`, else `null`. */
+  deriveError: string | null;
+  /** A memoized geometry-free probe run of every `build`. */
+  probe(): unknown;
+  /** A second, un-memoized probe run — for the determinism diff. */
+  probeAgain(): unknown;
+  /** `verify.expect` resolved once per lint pass. */
+  resolveExpectOnce(): unknown;
+}
+
+export interface LintRule {
+  id: string;
+  run(ctx: LintContext): Finding[];
+}
+
+/**
+ * The rule registry — one rule object per finding id, so it doubles as the
+ * documented rule catalog.
+ */
+export const RULES: LintRule[];
+
+export type { PartDefinition };