partforge 0.41.0 → 0.45.0

package/types/index.d.ts

@@ -0,0 +1,259 @@
+// 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 { CanonicalView, ParamValue, PartDefinition } from "./part.js";
+
+export * from "./kernel.js";
+export * from "./part.js";
+
+/** 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;
+  /** The active view (tab) name — emitted once on mount, then on every change. */
+  onViewChange?: (view: string) => 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;
+}
+
+export interface CaptureViewOptions {
+  /** Square render resolution in px. Default 640. */
+  size?: number;
+  /** JPEG quality, 0..1. Default 0.8. */
+  quality?: number;
+  /** Canonical angle to render from. Default `"iso"`. */
+  angle?: CanonicalView | string;
+}
+
+/** 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;
+  /** The active view (tab) name. Never null once mounted. */
+  getView(): string;
+  /** Switch the active view; `false` if the part declares no such view. Persists per part for the session. */
+  setView(name: string): boolean;
+  /**
+   * Render a named view OFFSCREEN → a `data:image/jpeg;base64,…` string, or `null` on
+   * failure (a build error, a view with no sub-parts, or a disposed runtime). Omit
+   * `viewName` — or pass an unknown one — to render the part's DEFAULT view. Never
+   * disturbs the active tab, the live camera, or the on-screen scene.
+   */
+  captureView(viewName?: string, opts?: CaptureViewOptions): Promise<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[];

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;
+}