forgecad 0.7.0 → 0.8.0

package/dist-skill/docs/generated/curves.md

@@ -9,8 +9,10 @@ Smooth curves, lofted surfaces, swept solids, and splines.
 
 ## Contents
 
-- [Curves & Surfacing](#curves-surfacing) — `hermiteTransitionG2`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
+- [Curves & Surfacing](#curves-surfacing) — `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
 - [Curve3D](#curve3d)
+- [NurbsCurve3D](#nurbscurve3d)
+- [NurbsSurface](#nurbssurface)
 - [PathBuilder](#pathbuilder) — Line Segments, Arcs, Curves, Closing & Output
 - [HermiteCurve3D](#hermitecurve3d)
 - [QuinticHermiteCurve3D](#quintichermitecurve3d)
@@ -36,6 +38,37 @@ hermiteTransitionG2(a: QuinticHermiteCurveEndpoint, b: QuinticHermiteCurveEndpoi
 | `curvature?` | `Vec3` | Second derivative / curvature vector. Default [0, 0, 0]. |
 | `weight?` | `number` | Weight: scales tangent magnitude relative to chord length. Default 1.0. |
 
+#### `nurbs3d()` — Create a NURBS curve from control points.
+
+With default options, creates a cubic non-rational B-spline with uniform clamped knots. Set `weights` for rational curves (exact circles, conics). Set `degree` for linear (1), quadratic (2), cubic (3), or higher-order curves.
+
+```js
+// Simple cubic B-spline through control points
+const curve = nurbs3d([[0,0,0], [10,5,0], [20,-5,10], [30,0,5]]);
+const tube = sweep(circle(2), curve);
+```
+
+```js
+// Rational quadratic — exact circular arc
+const arc = nurbs3d(
+  [[10,0,0], [10,10,0], [0,10,0]],
+  { degree: 2, weights: [1, Math.SQRT1_2, 1] }
+);
+```
+
+```ts
+nurbs3d(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D
+```
+
+**`NurbsCurve3DOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `degree?` | `number` | Polynomial degree (default 3 = cubic). Must be ≥ 1. |
+| `weights?` | `number[]` | Rational weights, one per control point (default: all 1.0 = non-rational). |
+| `knots?` | `number[]` | Knot vector (default: uniform clamped). Must have length = controlPoints.length + degree + 1. |
+| `closed?` | `boolean` | Whether the curve is closed/periodic (default false). |
+
 #### `spline2d()` — Build a smooth Catmull-Rom spline sketch from 2D control points.
 
 A closed spline (default) returns a filled profile. An open spline requires a strokeWidth option to produce a solid sketch. Use tension (0..1, default 0.5) to control curve tightness.
@@ -143,6 +176,39 @@ variableSweep(spine: SweepPathInput, sections: VariableSweepSection[], options?:
 | `boundsPadding?` | `number` | Optional extra bounds padding. |
 | `up?` | `Vec3` | Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. |
 
+#### `nurbsSurface()` — Create a NURBS surface from a grid of control points.
+
+The control grid is indexed as `controlGrid[u][v]` — each row is a curve in the V direction, and columns trace curves in the U direction.
+
+With default options, creates a bicubic non-rational B-spline surface with uniform clamped knots.
+
+```js
+// Simple 4×4 control grid — a gently curved surface
+const grid = [
+  [[0,0,0], [10,0,2], [20,0,2], [30,0,0]],
+  [[0,10,1], [10,10,5], [20,10,5], [30,10,1]],
+  [[0,20,1], [10,20,5], [20,20,5], [30,20,1]],
+  [[0,30,0], [10,30,2], [20,30,2], [30,30,0]],
+];
+const surface = nurbsSurface(grid, { thickness: 2 });
+```
+
+```ts
+nurbsSurface(controlGrid: Vec3[][], options?: NurbsSurfaceOptions): Shape
+```
+
+**`NurbsSurfaceOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `degreeU?` | `number` | Degree in U direction (default 3). |
+| `degreeV?` | `number` | Degree in V direction (default 3). |
+| `weights?` | `number[][]` | Weights grid — same dimensions as controlGrid (default: all 1.0). |
+| `knotsU?` | `number[]` | Knot vector in U direction (default: uniform clamped). |
+| `knotsV?` | `number[]` | Knot vector in V direction (default: uniform clamped). |
+| `thickness?` | `number` | Sheet thickness — if > 0, thickens the surface into a solid (default 0 = surface only). |
+| `resolution?` | `number` | Tessellation resolution — points per direction (default 32). |
+
 #### `surfacePatch()` — Create a smooth surface patch from 4 boundary curves (Coons patch).
 
 The four curves form the boundary of a quadrilateral patch:
@@ -317,6 +383,91 @@ tangentAt(t: number): Vec3
 length(samples?: number): number
 ```
 
+### `NurbsCurve3D`
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `controlPoints` | `Vec3[]` | — |
+| `weights` | `number[]` | — |
+| `knots` | `number[]` | — |
+| `degree` | `number` | — |
+| `closed` | `boolean` | — |
+
+**Methods:**
+
+#### `pointAt()` — Evaluate the curve at parameter t ∈ [0, 1]. Uses De Boor's algorithm — exact, O(degree²).
+
+```ts
+pointAt(t: number): Vec3
+```
+
+#### `tangentAt()` — Evaluate the unit tangent vector at parameter t ∈ [0, 1].
+
+```ts
+tangentAt(t: number): Vec3
+```
+
+#### `sample()` — Sample the curve uniformly at `count` points.
+
+```ts
+sample(count?: number): Vec3[]
+```
+
+#### `sampleAdaptive()` — Sample with adaptive density — more points in high-curvature regions.
+
+```ts
+sampleAdaptive(minCount?: number, maxCount?: number): Vec3[]
+```
+
+#### `length()` — Approximate arc length by summing polyline segment lengths.
+
+```ts
+length(samples?: number): number
+```
+
+#### `toPolyline()` — Convert to a format compatible with sweep() path input.
+
+```ts
+toPolyline(samples?: number): Vec3[]
+```
+
+### `NurbsSurface`
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `controlGrid` | `Vec3[][]` | — |
+| `weightsGrid` | `number[][]` | — |
+| `knotsU` | `number[]` | — |
+| `knotsV` | `number[]` | — |
+| `degreeU` | `number` | — |
+| `degreeV` | `number` | — |
+| `nU` | `number` | — |
+| `nV` | `number` | — |
+
+**Methods:**
+
+#### `pointAt()` — Evaluate the surface at parameters (u, v) ∈ [0, 1]². Uses tensor product evaluation: evaluate basis functions in U and V independently.
+
+```ts
+pointAt(u: number, v: number): Vec3
+```
+
+#### `normalAt()` — Evaluate the surface normal at (u, v) via cross product of partial derivatives.
+
+```ts
+normalAt(u: number, v: number): Vec3
+```
+
+#### `tessellate()` — Tessellate the surface into a triangle mesh. Returns positions, normals, and triangle indices.
+
+```ts
+tessellate(resU?: number, resV?: number): { positions: Vec3[]; normals: Vec3[]; indices: number[]; }
+```
+
 ### `PathBuilder`
 
 **Line Segments**
@@ -532,6 +683,22 @@ tangentBezierTo(cp2x: number, cp2y: number, x: number, y: number, weight?: numbe
 smoothThrough(waypoints: [ number, number ][], tension?: number): this
 ```
 
+#### `nurbsTo()` — Rational B-spline edge to (x, y) with explicit control points and weights.
+
+The control points define the B-spline shape between the current position and (x, y). The current position is NOT included in `controlPoints` — it is automatically prepended. The endpoint (x, y) is the last control point.
+
+```ts
+nurbsTo(controlPoints: [ number, number ][], opts?: { weights?: number[]; degree?: number; }): this
+```
+
+#### `exactArcTo()` — Exact circular arc to (x, y) using a rational quadratic NURBS.
+
+Unlike `arcTo()` which tessellates to a polyline, this preserves the exact arc definition. When extruded through the OCCT backend, it produces a true cylindrical face — not a faceted approximation.
+
+```ts
+exactArcTo(x: number, y: number, opts?: { radius?: number; clockwise?: boolean; }): this
+```
+
 #### [`fillet()`](/docs/core#fillet) — Round the last corner (the junction between the previous two segments) with a tangent arc of the given radius.
 
 Must be called after at least two line/arc segments that form a corner. The fillet trims back both segments and inserts a tangent arc.

package/dist-skill/docs/generated/lib.md

@@ -17,13 +17,14 @@ Pre-built fasteners, gears, pipes, structural profiles, and utility shapes. Acce
 
 ### `lib`
 
-Pre-built parametric parts available in user scripts as `lib.*`. **Details** Every key in this object becomes a method on the `lib` namespace exposed to `.forge.js` scripts. The catalog includes: **Fasteners:** `bolt`, `nut`, `washer`, `fastenerSet`, `fastenerHole`, `boltHole`, `counterbore`, `hexNut`, `holePattern` **Structure:** `tube`, `pipe`, `bracket`, `pipeRoute`, `elbow`, `tSlotProfile`, `tSlotExtrusion`, `profile2020BSlot6Profile`, `profile2020BSlot6` **Threads:** `thread` **Gears:** `spurGear`, `bevelGear`, `faceGear`, `sideGear`, `ringGear`, `rackGear`, `gearPair`, `bevelGearPair`, `faceGearPair`, `sideGearPair` **Utilities:** `explode` Extend this by adding new entries here and registering the corresponding runner binding in `runner.ts`. Sizes outside the supported ranges will throw at runtime with a descriptive error.
+Pre-built parametric parts available in user scripts as `lib.*`. **Details** Every key in this object becomes a method on the `lib` namespace exposed to `.forge.js` scripts. The catalog includes: **Fasteners:** `bolt`, `nut`, `washer`, `fastenerSet`, `fastenerHole`, `boltHole`, `counterbore`, `hexNut`, `holePattern` **Structure:** `tube`, `pipe`, `bracket`, `pipeRoute`, `elbow`, `tSlotProfile`, `tSlotExtrusion`, `profile2020BSlot6Profile`, `profile2020BSlot6` **Threads:** `thread` **Gears:** `spurGear`, `bevelGear`, `faceGear`, `sideGear`, `ringGear`, `rackGear`, `gearPair`, `bevelGearPair`, `faceGearPair`, `sideGearPair` **Gear ratios (pure math helpers):** `gearRatio`, `rackRatio`, `planetaryRatio` **Bolt patterns:** `boltPattern` — define hole positions once, cut them from multiple parts **Utilities:** `explode` Extend this by adding new entries here and registering the corresponding runner binding in `runner.ts`. Sizes outside the supported ranges will throw at runtime with a descriptive error.
 
 - `boltHole(diameter: number, depth: number): Shape` — Simple cylindrical through-hole cutter centered on Z=0. Subtract the result from a part to produce a plain cylindrical clearance hole. For ISO metric sizes with fit classes and counterbore/countersink, use {
 - `fastenerHole(opts: FastenerHoleOptions): Shape` — ISO metric fastener hole cutter with optional counterbore or countersink. **Details** Returns a cutter shape (subtract from a solid to produce the hole). Sizes outside M2–M10 will throw. Extend `METRIC_HOLE_TABLE` in this file to add new sizes. **Example** ```ts const plate = box(60, 40, 8, true) .subtract(lib.fastenerHole({ size: 'M5', fit: 'normal', depth: 8 }) .translate(15, 10, 4)); ```
 - `counterbore(holeDia: number, boreDia: number, boreDepth: number, totalDepth: number): Shape` — Counterbore hole cutter — through-hole with a wider cylindrical recess at the top. Use for socket-head cap screws that must sit flush. Subtract from a solid. For ISO metric sizing and fit classes, prefer {
 - `tube(outerX: number, outerY: number, outerZ: number, wall: number): Shape` — Rectangular hollow tube (thin-wall box section). Both the outer and inner boxes are centered on the XY plane with their base at Z=0.
 - `pipe(height: number, outerRadius: number, wall: number, segments?: number): Shape` — Hollow cylindrical pipe. Centered on the XY plane, extending upward along +Z from z=0 to z=height. For complex routed pipe geometry, see `lib.pipeRoute`.
+- `explode<T extends ExplodeItem[] | ShapeGroup>(items: T, options?: ExplodeOptions): T` — Apply deterministic exploded-view offsets to an assembly tree. **Details** Traverses arrays of shapes/sketches/named items, nested `{ name, group: [...] }` structures, and [`ShapeGroup`](/docs/core#shapegroup) outputs, translating each node by a computed offset while preserving names, colors, and nesting. Returns the same structure type as the input. In `radial` mode the algorithm is branch-aware and parent-relative: each node fans out from its immediate parent's center, so nested assemblies peel apart level by level. Named items may also include an inline `explode: { stage?, direction?, axisLock? }` property to override per-item behavior. Use this function when you want to bake the explode offset into the geometry before returning (e.g. to drive the amount with a `param()` slider). For a viewport-only explode slider without rerunning the script, use [`explodeView()`](/docs/viewport#explodeview) instead. **Example** ```js const explodeAmt = param('Explode', 0, { min: 0, max: 40, unit: 'mm' }); return lib.explode(assembly, { amount: explodeAmt, stages: [0.4, 0.8], mode: 'radial', byName: { Shaft: { direction: [1, 0, 0], stage: 1.4 } }, }); ```
 - `hexNut(acrossFlats: number, height: number, holeDia: number): Shape` — Generic hex nut with a cylindrical bore. Constructed via intersection of three rotated rectangular slabs, then a bore is subtracted. Centered at origin, height along Z. For standard ISO metric nuts by thread size, use `lib.nut` instead.
 - `bracket(width: number, height: number, depth: number, thick: number, holeDia?: number): Shape` — L-shaped mounting bracket with optional through-holes. Produces a right-angle bracket: a horizontal base plate and a vertical wall. Both legs share `width`. Optional holes are drilled through the base (along Z) and the wall (along Y).
 - `holePattern(rows: number, cols: number, spacingX: number, spacingY: number, holeDia: number, depth: number): Shape` — Rectangular grid of cylindrical hole cutters. Returns the union of `rows × cols` cylinders laid out on a regular grid. Subtract from a solid to produce the full pattern. **Example** ```ts const pattern = lib.holePattern(3, 4, 20, 20, 4, 10); const panel = box(80, 70, 10, true).subtract(pattern.translate(-30, -30, 5)); ```
@@ -38,13 +39,17 @@ Pre-built parametric parts available in user scripts as `lib.*`. **Details** Eve
 - `tSlotExtrusion(length: number, options?: TSlotExtrusionOptions): Shape` — Build a T-slot extrusion from the generated 2D profile. Extrudes along +Z by default.
 - `profile2020BSlot6Profile(options?: Profile2020BSlot6ProfileOptions): Sketch` — Accurate-ish 2D profile for 20x20 B-type slot 6. Returns a drawing-ready Sketch centered at origin.
 - `profile2020BSlot6(length: number, options?: Profile2020BSlot6Options): Shape` — 20x20 B-type slot 6 extrusion with profile-accurate defaults. Pass option overrides if your supplier's profile differs slightly.
-- `spurGear(options: SpurGearOptions): Shape` — Involute external spur gear with optional center bore. Specify module, teeth, faceWidth as required parameters. Optional tuning includes pressureAngleDeg (default 20), backlash, clearance, addendum, dedendum, boreDiameter, and segmentsPerTooth (default 10).
-- `bevelGear(options: BevelGearOptions): Shape` — Conical bevel gear generated from a tapered involute extrusion. Specify pitchAngleDeg directly or derive it from mateTeeth + shaftAngleDeg.
+- `spurGear(options: SpurGearOptions): Shape` — Involute external spur gear with optional center bore. Specify module, teeth, faceWidth as required parameters. Optional tuning includes pressureAngleDeg (default 20), backlash, clearance, addendum, dedendum, boreDiameter, and segmentsPerTooth (default 10). **Connectors (for assembly-based positioning):** - `bore`: revolute connector at the bore center, axis along +Z. Carries measurements: `{ module, teeth, pitchRadius, outerRadius, faceWidth }`. Use `.connect("Housing.seat", "Gear.bore")` to mount a gear on a shaft seat.
+- `bevelGear(options: BevelGearOptions): Shape` — Conical bevel gear generated from a tapered involute extrusion. Specify pitchAngleDeg directly or derive it from mateTeeth + shaftAngleDeg. **Connectors (for assembly-based positioning):** - `bore`: revolute connector at the large-end bore center (Z=0), axis along -Z (away from teeth). - `apex`: connector at the cone apex above the gear (the point where the pitch cone converges), axis along +Z. Useful for meshing two bevel gears — their apices should coincide. Carries measurements: `{ module, teeth, pitchRadius, pitchAngleDeg, coneDistance, faceWidth }`.
 - `faceGear(options: FaceGearOptions): Shape` — Face gear (crown style) where teeth are on one face (top or bottom) instead of the outer rim. Uses the same involute tooth sizing as spurGear, then projects the tooth band axially from one side. Alias for sideGear (which is kept for backward compatibility).
 - `sideGear(options: SideGearOptions): Shape` — Crown/face style gear where the teeth project from one side of the disk instead of the outer cylindrical rim.
-- `ringGear(options: RingGearOptions): Shape` — Internal ring gear with involute-derived tooth spaces. Specify rimWidth or outerDiameter for the annular body.
-- `rackGear(options: RackGearOptions): Shape` — Linear rack gear with pressure-angle flanks. Use with spurGear for rack-and-pinion mechanisms.
+- `ringGear(options: RingGearOptions): Shape` — Internal ring gear with involute-derived tooth spaces. Specify rimWidth or outerDiameter for the annular body. **Connectors (for assembly-based positioning):** - `bore`: connector at the ring center, axis along +Z. For planetary gearboxes, this is where the ring mounts to the housing. Carries measurements: `{ module, teeth, pitchRadius, innerRadius, outerRadius, faceWidth }`.
+- `rackGear(options: RackGearOptions): Shape` — Linear rack gear with pressure-angle flanks. Use with spurGear for rack-and-pinion mechanisms. **Orientation:** teeth run along the X axis with tooth tips pointing +Y (pitch line at Y=0). The rack is extruded +Z by `faceWidth`. Rotate the rack to align with a different slide axis. **Connectors (for assembly-based positioning):** - `teeth`: prismatic connector at the pitch line center, axis along +X (slide direction). Carries measurements: `{ module, teeth, faceWidth, length }`. Connect to a housing's rack channel: ```js housing.withConnectors({ rack_channel: connector("rack-channel", { origin: [pitchR, 0, channelZ], axis: [1, 0, 0], kind: "prismatic", }), }); assembly.connect("Housing.rack_channel", "Rack.teeth", { as: "slide" }); ```
 - `gearPair(options: GearPairOptions): GearPairResult` — Build or validate a spur-gear pair and return ratio, backlash, and mesh diagnostics. Accepts either shapes from spurGear() or analytical specs for each member. When place is true (default), the gear is auto-positioned at the correct center distance.
 - `bevelGearPair(options: BevelGearPairOptions): BevelGearPairResult` — Build or validate a bevel-gear pair and return ratio diagnostics plus recommended joint placement vectors.
 - `faceGearPair(options: FaceGearPairOptions): FaceGearPairResult` — Build or validate a perpendicular pair between a face gear and a vertical spur gear.
 - `sideGearPair(options: SideGearPairOptions): SideGearPairResult` — Pair helper for side (crown/face) gear + perpendicular "vertical" spur gear. Auto-placement rotates the spur around +Y and positions it to mesh at the side tooth band.
+- `gearRatio(teethA: number, teethB: number, options?: { internal?: boolean; }): number` — Coupling ratio between two meshed spur gears. When gear A turns 1°, gear B turns `-teethA / teethB` degrees (negative because meshed external gears rotate in opposite directions). ```js assembly.addJointCoupling("B_spin", { terms: [{ joint: "A_spin", ratio: lib.gearRatio(12, 24) }], // -0.5 }); ``` Pass `{ internal: true }` for internal gear pairs (ring gear + spur/planet), where the two rotate in the same direction.
+- `rackRatio(module: number, pinionTeeth: number): number` — Coupling ratio between a pinion and a rack. When the pinion rotates by `θ` degrees, the rack slides by `θ × (π × module × teeth / 360)` mm. Equivalently, 1mm of rack travel = `180 / (π × pitchRadius)` degrees of pinion rotation. ```js // Pinion spin driven by rack slide: assembly.addJointCoupling("pinion_spin", { terms: [{ joint: "rack_slide", ratio: lib.rackRatio(1.5, 12) }], // ~6.37 deg/mm }); ```
+- `planetaryRatio(sunTeeth: number, ringTeeth: number): number` — Planetary gear reduction ratio when the ring is held fixed. Input: sun. Output: carrier. Ratio: `1 + ringTeeth / sunTeeth`. One turn of the sun produces `1 / ratio` turns of the carrier.
+- `boltPattern(options: BoltPatternOptions): BoltPattern` — Define a bolt pattern once and cut it from multiple parts. ```js const bolts = lib.boltPattern({ size: 'M5', positions: [[20, 15], [-20, 15], [20, -15], [-20, -15]], }); const base = bolts.cut(box(60, 50, 10), 12, { from: -1 }); const cover = bolts.cut(box(60, 50, 3), 5, { from: -1 }); // Same positions in both parts — guaranteed aligned. ```

package/dist-skill/docs/generated/output.md

@@ -20,7 +20,7 @@ Dimensions, BOM entries, verification checks, and sketch export.
 
 BOM entries are accumulated during script execution and exported alongside the model in report views. Rows are grouped by normalized `description + unit`. Pass an explicit `key` to force multiple descriptions to collapse into a single line item.
 
-- `quantity` must be a finite number `>= 0`. A quantity of `0` is silently ignored (useful for conditional scripting with [`param()`](/docs/core#param)-driven counts).
+- `quantity` must be a finite number `>= 0`. A quantity of `0` is silently ignored (useful for conditional scripting with `param()`-driven counts).
 - `unit` defaults to `"pieces"` when omitted or empty.
 - The assembly `solved.bom()` / `solved.bomCsv()` API is separate and covers per-part assembly metadata; this function is for free-form purchased-item annotation.
 

package/dist-skill/docs/generated/sdf.md

@@ -0,0 +1,208 @@
+---
+skill-group: sdf
+skill-order: 100
+---
+
+# SDF Modeling (Experimental)
+
+Signed Distance Field modeling for organic forms, smooth booleans, TPMS lattices, and deformations. Access via `sdf.*`. Experimental — slower render times and lower mesh quality than B-rep.
+
+## Contents
+
+- [SdfShape](#sdfshape)
+- [sdf](#sdf)
+
+---
+
+## Classes
+
+### `SdfShape`
+
+An immutable SDF expression. Supports SDF-specific operations (smooth booleans, domain warps, etc.) and converts to a ForgeCAD Shape via `.toShape()`.
+
+#### `toShape()` — Mesh this SDF into a ForgeCAD Shape via Manifold.levelSet(). Once converted, the result is a regular Shape — booleans, transforms, export all work.
+
+```ts
+toShape(options?: SdfToShapeOptions): Shape
+```
+
+#### [`union()`](/docs/core#union) — SDF union (sharp).
+
+```ts
+union(...others: SdfShape[]): SdfShape
+```
+
+#### `subtract()` — SDF difference (sharp) — subtracts others from this.
+
+```ts
+subtract(...others: SdfShape[]): SdfShape
+```
+
+#### `intersect()` — SDF intersection (sharp).
+
+```ts
+intersect(...others: SdfShape[]): SdfShape
+```
+
+#### `smoothUnion()` — Smooth union — blends shapes together with a smooth radius.
+
+```ts
+smoothUnion(other: SdfShape, radius: number): SdfShape
+```
+
+#### `smoothSubtract()` — Smooth difference — smoothly carves other from this.
+
+```ts
+smoothSubtract(other: SdfShape, radius: number): SdfShape
+```
+
+#### `smoothIntersect()` — Smooth intersection — smoothly intersects.
+
+```ts
+smoothIntersect(other: SdfShape, radius: number): SdfShape
+```
+
+#### `morph()` — Morph between this shape and another. t=0 → this, t=1 → other.
+
+```ts
+morph(other: SdfShape, t: number): SdfShape
+```
+
+#### `translate()`
+
+```ts
+translate(x: number, y: number, z: number): SdfShape
+```
+
+#### `rotate()` — Rotate around an arbitrary axis through the origin.
+
+```ts
+rotate(axis: [ number, number, number ], angleDeg: number): SdfShape
+```
+
+#### `rotateX()` — Rotate around the X axis by the given angle in degrees.
+
+```ts
+rotateX(angleDeg: number): SdfShape
+```
+
+#### `rotateY()` — Rotate around the Y axis by the given angle in degrees.
+
+```ts
+rotateY(angleDeg: number): SdfShape
+```
+
+#### `rotateZ()` — Rotate around the Z axis by the given angle in degrees.
+
+```ts
+rotateZ(angleDeg: number): SdfShape
+```
+
+#### `scale()`
+
+```ts
+scale(factor: number): SdfShape
+```
+
+#### `twist()` — Twist around the Z axis.
+
+```ts
+twist(degreesPerUnit: number): SdfShape
+```
+
+#### `bend()` — Bend around the Z axis with given radius.
+
+```ts
+bend(radius: number): SdfShape
+```
+
+#### `repeat()` — Repeat in space. Spacing of 0 on an axis means no repetition. Count of 0 = infinite.
+
+```ts
+repeat(spacing: Vec3, count?: Vec3): SdfShape
+```
+
+#### `shell()` — Hollow out, keeping only a shell of given thickness.
+
+```ts
+shell(thickness: number): SdfShape
+```
+
+#### `displace()` — Displace the surface by a function of position, or by a pattern SdfShape.
+
+```js
+// Function displacement
+shape.displace((x, y, z) => Math.sin(x) * 0.5)
+
+// Pattern displacement (e.g. basketWeave)
+shape.displace(sdf.basketWeave({ threads: 16, spacing: 3 }))
+```
+
+```ts
+displace(fn: ((x: number, y: number, z: number) => number) | SdfShape, constants?: Record<string, number>): SdfShape
+```
+
+#### `surfaceDisplace()` — Displace the surface using a 2D pattern in surface-local UV coordinates.
+
+Automatically detects the shape's UV parametrization (sphere, cylinder, torus) from the SDF tree. Falls back to triplanar mapping for arbitrary shapes.
+
+UV coordinates are in **surface millimeters** — patterns defined with `spacing: 3` always produce 3mm spacing, regardless of shape size.
+
+```js
+// Surface-following basket weave — auto-detects sphere UV
+sdf.sphere(27).shell(3)
+  .surfaceDisplace(sdf.basketWeave({ spacing: 3, depth: 0.8 }))
+  .toShape()
+
+// Custom 2D pattern via function
+shape.surfaceDisplace((u, v) => -Math.sin(u * 2) * 0.3)
+```
+
+```ts
+surfaceDisplace(pattern: SurfacePattern | ((u: number, v: number) => number), options?: SurfaceDisplaceOptions): SdfShape
+```
+
+#### `onion()` — Create concentric onion layers.
+
+```ts
+onion(layers: number, thickness: number): SdfShape
+```
+
+---
+
+## Constants
+
+### `sdf`
+
+SDF modeling — signed distance field primitives, smooth booleans, TPMS lattices, domain warps, and surface patterns. **Experimental.** Slower render times and lower mesh quality than B-rep. Use for organic forms, smooth blending, or TPMS lattices where these trade-offs are acceptable. For mechanical parts, prefer B-rep. All shapes live as a lazy expression tree until `.toShape()` is called, which meshes them via `Manifold.levelSet()` and returns a regular Shape. ```js const shape = sdf.smoothUnion(sdf.sphere(10), sdf.box(15, 15, 15), { radius: 3 }) .toShape({ edgeLength: 0.5 }) .color('#4488cc'); ```
+
+- `sphere(radius: number): SdfShape` — Create an SDF sphere centered at the origin.
+- `box(x: number, y: number, z: number): SdfShape` — Create an SDF box centered at the origin with given full dimensions (not half-extents).
+- `cylinder(height: number, radius: number): SdfShape` — Create an SDF cylinder centered at the origin, axis along Z.
+- `torus(majorRadius: number, minorRadius: number): SdfShape` — Create an SDF torus centered at the origin, lying in the XY plane.
+- `capsule(height: number, radius: number): SdfShape` — Create an SDF capsule centered at the origin, axis along Z.
+- `cone(height: number, radius: number): SdfShape` — Create an SDF cone with base at z=0 and tip at z=height.
+- `smoothUnion(a: SdfShape, b: SdfShape, options: { radius: number; }): SdfShape` — Smooth union — blends shapes together with a smooth transition radius.
+- `smoothDifference(a: SdfShape, b: SdfShape, options: { radius: number; }): SdfShape` — Smooth difference — smoothly subtracts b from a.
+- `smoothIntersection(a: SdfShape, b: SdfShape, options: { radius: number; }): SdfShape` — Smooth intersection — smoothly intersects a and b.
+- `morph(a: SdfShape, b: SdfShape, t: number): SdfShape` — Morph between two SDF shapes. t=0 → a, t=1 → b.
+- `blend(a: SdfShape, b: SdfShape, fn: (x: number, y: number, z: number) => number, options?: BlendOptions): SdfShape` — Spatially blend between two SDF patterns. The blend function receives (x, y, z) and returns 0..1: 0 = fully pattern `a`, 1 = fully pattern `b`.
+- `gyroid(options: TpmsOptions): SdfShape` — Gyroid TPMS lattice — the most common lattice for additive manufacturing.
+- `schwarzP(options: TpmsOptions): SdfShape` — Schwarz-P TPMS lattice — isotropic pore structure.
+- `diamond(options: TpmsOptions): SdfShape` — Diamond TPMS lattice — stiffest TPMS structure.
+- `lidinoid(options: TpmsOptions): SdfShape` — Lidinoid TPMS lattice — visually distinct from gyroid, popular in research and art.
+- `noise(options?: NoiseOptions): SdfShape` — 3D Simplex noise field — produces organic, natural-looking displacements.
+- `voronoi(options?: VoronoiOptions): SdfShape` — 3D Voronoi pattern — organic cellular structures like bone, coral, or soap bubbles.
+- `honeycomb(options?: HoneycombOptions): SdfShape` — Honeycomb (hexagonal) lattice pattern. Intersect with your shape to apply.
+- `waves(options?: WavesOptions): SdfShape` — Sinusoidal wave ridges — parallel ridges along an axis.
+- `knurl(options?: KnurlOptions): SdfShape` — Knurl pattern — crossed helical grooves for grips and handles.
+- `perforated(options?: PerforatedOptions): SdfShape` — Perforated plate pattern — regular array of cylindrical holes.
+- `scales(options?: ScalesOptions): SdfShape` — Fish/dragon scale pattern — overlapping circular scales in hex-packed rows.
+- `brick(options?: BrickOptions): SdfShape` — Brick/stone wall pattern — running bond with mortar grooves.
+- `weave(options?: WeaveOptions): SdfShape` — Grid lattice pattern — two families of infinite slabs crossing at 90°.
+- `basketWeave(options?: BasketWeaveOptions): SurfacePattern` — Basket weave surface pattern — threads with over-under crossings in UV space. Returns a SurfacePattern for use with `.surfaceDisplace()`.
+- `twist(shape: SdfShape, degreesPerUnit: number): SdfShape` — Twist an SDF shape around the Z axis.
+- `bend(shape: SdfShape, radius: number): SdfShape` — Bend an SDF shape around the Z axis.
+- `repeat(shape: SdfShape, spacing: Vec3, count?: Vec3): SdfShape` — Repeat an SDF shape in space.
+- `SurfacePattern: typeof SurfacePattern` — A 2D surface pattern — a heightmap function for use with `.surfaceDisplace()`.
+- `fromFunction(fn: (x: number, y: number, z: number) => number, bounds: { min: Vec3; max: Vec3; }, constants?: Record<string, number>): SdfShape` — Create an SDF shape from an arbitrary distance function. You must provide bounds since the function is opaque.