forgecad 0.6.3 → 0.8.0

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

@@ -5,336 +5,230 @@ skill-order: 100
 
 # Output & Annotations
 
-> **Auto-generated** from `src/forge/forge-public-api.ts`. Do not edit by hand — run `npm run gen:docs` to regenerate.
-
 Dimensions, BOM entries, verification checks, and sketch export.
 
-## Functions
+## Contents
 
-### Annotations & Output
+- [Annotations & Output](#annotations-output) — `bom`, `robotExport`, `dim`, `dimLine`
+- [Sketch Export](#sketch-export) — `sketchToDxf`, `sketchToSvg`
 
-Add dimensions, BOM entries, verification checks, and robot export.
+## Functions
 
-#### `bom()`
+### Annotations & Output
 
-```ts
-bom(quantity: number, description: string, opts?: BomOpts): void
-```
+#### `bom()` — Register a Bill of Materials entry for report export.
 
-Add a bill-of-materials entry.
+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.
 
-<details><summary><code>BomOpts</code></summary>
+- `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.
 
 ```ts
-interface BomOpts {
-  /** Quantity unit label, e.g. "mm", "pieces", "kg". Default: "pieces" */
-  unit?: string;
-  /** Optional explicit grouping key used during report aggregation. */
-  key?: string;
-}
-```
-
-</details>
+const tubeLen = param("Tube Length", 1200, { min: 300, max: 4000, unit: "mm" });
+const boltCount = param("Bolt Count", 16, { min: 0, max: 200, integer: true });
 
-#### `robotExport()`
+bom(tubeLen, "iron tube 30 x 20", { unit: "mm" });
+bom(boltCount, "M4 bolt, 16 mm length");
+bom(4, "rubber foot", { key: "foot-rubber" }); // explicit aggregation key
 
-```ts
-robotExport(options: RobotExportOptions): CollectedRobotExport
+// Structured metadata for richer reports:
+bom(tubeLen, "rectangular steel tube", {
+  unit: "mm",
+  material: "steel",
+  section: [30, 20],
+  wall: 3,
+});
 ```
 
-Declare that the current script should export an assembly as a robot package for the SDF CLI. Configures inertial properties, joint limits, and optional plugins (e.g. diff-drive for Gazebo).
-
-<details><summary><code>RobotExportOptions</code></summary>
-
 ```ts
-interface RobotExportOptions {
-  assembly: Assembly;
-  modelName?: string;
-  state?: JointState;
-  static?: boolean;
-  selfCollide?: boolean;
-  allowAutoDisable?: boolean;
-  links?: Record<string, RobotLinkExportOptions>;
-  joints?: Record<string, RobotJointExportOptions>;
-  diffDrive?: RobotDiffDrivePluginOptions;
-  jointStatePublisher?: RobotJointStatePublisherOptions;
-  world?: RobotWorldOptions;
-}
+bom(quantity: number, description: string, opts?: BomOpts): void
 ```
 
-</details>
+**`BomOpts`**
 
-<details><summary><code>RobotLinkExportOptions</code></summary>
+| Option | Type | Description |
+|--------|------|-------------|
+| `unit?` | `string` | Quantity unit label, e.g. "mm", "pieces", "kg". Default: "pieces" |
+| `key?` | `string` | Optional explicit grouping key used during report aggregation. |
+| `material?` | `string` | Material name, e.g. "steel", "birch plywood", "nylon" |
+| `dimensions?` | `number[]` | Overall dimensions `[width, height]` or `[width, height, thickness]` in the entry's unit |
+| `section?` | `number[]` | Cross-section dimensions `[w, h]` for tubes and profiles |
+| `wall?` | `number` | Wall thickness for hollow sections (mm) |
+| `diameter?` | `number` | Diameter for round stock, bolts, dowels (mm) |
+| `length?` | `number` | Length for fasteners (mm) |
+| `process?` | `string` | Manufacturing process, e.g. "laser cut", "CNC", "welded" |
+| `notes?` | `string` | Free-form notes |
+| `grain?` | `string` | Wood grain direction, e.g. "long", "cross" |
 
-```ts
-interface RobotLinkExportOptions {
-  massKg?: number;
-  densityKgM3?: number;
-  collision?: "visual" | "convex" | "box" | "none";
-}
-```
-
-</details>
-
-<details><summary><code>RobotJointExportOptions</code></summary>
+#### `robotExport()` — Declare that this script should export the assembly as a SDF/URDF robot package.
 
-```ts
-interface RobotJointExportOptions {
-  effort?: number;
-  velocity?: number;
-  damping?: number;
-  friction?: number;
-}
-```
+Call `robotExport()` alongside your assembly definition. The CLI commands `forgecad export sdf` and `forgecad export urdf` pick up the declaration and produce a robot package with:
 
-</details>
+- Mesh-based inertia tensors (full 6-component, not bounding-box approximations)
+- Separate collision meshes (convex hull by default — ~50–80% smaller)
+- Joint mimic elements derived from `addJointCoupling` / `addGearCoupling`
 
-<details><summary><code>RobotDiffDrivePluginOptions</code></summary>
+**Collision mesh modes** (set per-link via `links["PartName"].collision`):
 
-```ts
-interface RobotDiffDrivePluginOptions {
-  leftJoints: string[];
-  rightJoints: string[];
-  wheelSeparationMm: number;
-  wheelRadiusMm: number;
-  topic?: string;
-  odomTopic?: string;
-  tfTopic?: string;
-  frameId?: string;
-  odomFrameId?: string;
-  maxLinearVelocity?: number;
-  maxAngularVelocity?: number;
-  linearAcceleration?: number;
-  angularAcceleration?: number;
-}
-```
+| Mode | Description | Default | |------|-------------|---------| | `'convex'` | Convex hull (separate `_collision.stl`) | Yes | | `'box'` | AABB primitive — fastest physics | | | `'visual'` | Same mesh as visual — exact but slow | | | `'none'` | No collision geometry | |
 
-</details>
+**Unit conventions:**
 
-<details><summary><code>RobotJointStatePublisherOptions</code></summary>
+- Revolute `velocity` is in degrees/second in Forge; exporters convert to rad/s.
+- Prismatic distances are in mm in Forge; exported in meters.
+- `massKg` is preferred; `densityKgM3` is used when mass is unknown.
+- Couplings with multiple terms: only the primary term (largest ratio) maps to `<mimic>` — SDF/URDF support single-leader mimic only. Dropped terms emit a warning.
 
 ```ts
-interface RobotJointStatePublisherOptions {
-  enabled?: boolean;
-  joints?: string[];
-  topic?: string;
-  updateRate?: number;
-}
-```
-
-</details>
+const rover = assembly("Scout")
+  .addPart("Chassis", box(300, 220, 50, true))
+  .addPart("Left Wheel", cylinder(30, 60, undefined, 48, true))
+  .addRevolute("leftWheel", "Chassis", "Left Wheel", {
+    axis: [0, 1, 0],
+    frame: Transform.identity().translate(90, 140, 60),
+    effort: 20, velocity: 1080,
+  });
 
-<details><summary><code>RobotWorldOptions</code></summary>
-
-```ts
-interface RobotWorldOptions {
-  name?: string;
-  generateDemoWorld?: boolean;
-  spawnPose?: RobotPose6;
-  keyboardTeleop?: RobotWorldKeyboardTeleopOptions;
-}
+robotExport({
+  assembly: rover,
+  modelName: "Scout",
+  links: {
+    Chassis: { massKg: 10 },
+    "Left Wheel": { massKg: 0.8 },
+  },
+  plugins: {
+    diffDrive: {
+      leftJoints: ["leftWheel"], rightJoints: ["rightWheel"],
+      wheelSeparationMm: 280, wheelRadiusMm: 60,
+    },
+  },
+  world: { generateDemoWorld: true },
+});
 ```
 
-</details>
+**CLI usage**
 
-<details><summary><code>RobotWorldKeyboardTeleopOptions</code></summary>
+```bash
+forgecad export sdf model.forge.js   # SDF package (Gazebo/Ignition)
+forgecad export urdf model.forge.js  # URDF package (ROS/PyBullet/MuJoCo)
+```
 
 ```ts
-interface RobotWorldKeyboardTeleopOptions {
-  enabled?: boolean;
-  linearStep?: number;
-  angularStep?: number;
-}
+robotExport(options: RobotExportOptions): CollectedRobotExport
 ```
 
-</details>
+**`RobotExportOptions`**: `assembly: Assembly`, `modelName?: string`, `state?: JointState`, `static?: boolean`, `selfCollide?: boolean`, `allowAutoDisable?: boolean`, `links?: Record<string, RobotLinkExportOptions>`, `joints?: Record<string, RobotJointExportOptions>`, `diffDrive?: RobotDiffDrivePluginOptions`, `jointStatePublisher?: RobotJointStatePublisherOptions`, `world?: RobotWorldOptions`
 
-<details><summary><code>CollectedRobotExport</code></summary>
+`RobotLinkExportOptions`: `{ massKg?: number, densityKgM3?: number, collision?: "visual" | "convex" | "box" | "none" }`
 
-```ts
-interface CollectedRobotExport {
-  modelName: string;
-  assembly: AssemblyDefinition;
-  state: JointState;
-  static: boolean;
-  selfCollide: boolean;
-  allowAutoDisable: boolean;
-  links: Record<string, RobotLinkExportOptions>;
-  joints: Record<string, RobotJointExportOptions>;
-  diffDrive?: RobotDiffDrivePluginOptions;
-  jointStatePublisher?: RobotJointStatePublisherOptions;
-  world: RobotWorldOptions | null;
-}
-```
+`RobotJointExportOptions`: `{ effort?: number, velocity?: number, damping?: number, friction?: number }`
 
-</details>
+**`RobotDiffDrivePluginOptions`**: `leftJoints: string[]`, `rightJoints: string[]`, `wheelSeparationMm: number`, `wheelRadiusMm: number`, `topic?: string`, `odomTopic?: string`, `tfTopic?: string`, `frameId?: string`, `odomFrameId?: string`, `maxLinearVelocity?: number`, `maxAngularVelocity?: number`, `linearAcceleration?: number`, `angularAcceleration?: number`
 
-<details><summary><code>AssemblyDefinition</code></summary>
+`RobotJointStatePublisherOptions`: `{ enabled?: boolean, joints?: string[], topic?: string, updateRate?: number }`
 
-```ts
-interface AssemblyDefinition {
-  name: string;
-  parts: AssemblyPartDef[];
-  joints: AssemblyJointDef[];
-  jointCouplings: AssemblyJointCouplingDef[];
-}
-```
+`RobotWorldOptions`: `{ name?: string, generateDemoWorld?: boolean, spawnPose?: RobotPose6, keyboardTeleop?: RobotWorldKeyboardTeleopOptions }`
 
-</details>
+`RobotWorldKeyboardTeleopOptions`: `{ enabled?: boolean, linearStep?: number, angularStep?: number }`
 
-<details><summary><code>AssemblyPartDef</code></summary>
+**`CollectedRobotExport`**: `modelName: string`, `assembly: AssemblyDefinition`, `state: JointState`, `static: boolean`, `selfCollide: boolean`, `allowAutoDisable: boolean`, `links: Record<string, RobotLinkExportOptions>`, `joints: Record<string, RobotJointExportOptions>`, `diffDrive?: RobotDiffDrivePluginOptions`, `jointStatePublisher?: RobotJointStatePublisherOptions`, `world: RobotWorldOptions | null`
 
-```ts
-interface AssemblyPartDef {
-  name: string;
-  part: AssemblyPart;
-  base: Transform;
-  metadata?: PartMetadata;
-}
-```
+`AssemblyDefinition`: `{ name: string, parts: AssemblyPartDef[], joints: AssemblyJointDef[], jointCouplings: AssemblyJointCouplingDef[] }`
 
-</details>
+`AssemblyPartDef`: `{ name: string, part: AssemblyPart, base: Transform, metadata?: PartMetadata }`
 
-<details><summary><code>PartMetadata</code></summary>
+**`PartMetadata`**: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`
 
-```ts
-interface PartMetadata {
-  material?: string;
-  process?: string;
-  tolerance?: string;
-  qty?: number;
-  notes?: string;
-  densityKgM3?: number;
-  massKg?: number;
-}
-```
+**`AssemblyJointDef`**: `name: string`, `type: JointType`, `parent: string`, `child: string`, `frame: Transform`, `axis: Vec3`, `min?: number`, `max?: number`, `defaultValue: number`, `unit?: string`, `effort?: number`, `velocity?: number`, `damping?: number`, `friction?: number`
 
-</details>
+`AssemblyJointCouplingDef`: `{ joint: string, terms: JointCouplingTermRecord[], offset: number }`
 
-<details><summary><code>AssemblyJointDef</code></summary>
+`JointCouplingTermRecord`: `{ joint: string, ratio: number }`
 
-```ts
-interface AssemblyJointDef {
-  name: string;
-  type: JointType;
-  parent: string;
-  child: string;
-  frame: Transform;
-  axis: Vec3;
-  min?: number;
-  max?: number;
-  defaultValue: number;
-  unit?: string;
-  effort?: number;
-  velocity?: number;
-  damping?: number;
-  friction?: number;
-}
-```
-
-</details>
+#### `dim()` — Add a dimension annotation between two points.
 
-<details><summary><code>AssemblyJointCouplingDef</code></summary>
+Dimension annotations are purely visual callouts rendered in the viewport and report export. They do not affect geometry or constrain the model.
 
-```ts
-interface AssemblyJointCouplingDef {
-  joint: string;
-  terms: JointCouplingTermRecord[];
-  offset: number;
-}
-```
+Point arguments accept 2D tuples `[x, y]`, 3D tuples `[x, y, z]`, or [`Point2D`](/docs/sketch#point2d) objects (Z is treated as 0 for 2D inputs).
 
-</details>
+**Ownership Rules (Report Pages)**
 
-<details><summary><code>JointCouplingTermRecord</code></summary>
+- `currentComponent: true` — deterministic ownership by the calling import instance. Use when authoring reusable imported parts.
+- `component: "Part Name"` — route dimension to another named returned object.
+- Multiple owners: dimension is shared and appears on the assembly overview page.
+- No ownership set: report export infers ownership via endpoint-in-bbox.
 
 ```ts
-interface JointCouplingTermRecord {
-  joint: string;
-  ratio: number;
-}
+dim([-w / 2, 0, 0], [w / 2, 0, 0], { label: "Width" });
+dim([0, 0, -h / 2], [0, 0, h / 2], { label: "Height", offset: 14 });
+dim([0, 0, 0], [100, 0, 0], { component: "Base", color: "#00AAFF" });
 ```
 
-</details>
-
-#### `dim()`
+`component` (string or string[] — report ownership), `currentComponent` (boolean)
 
 ```ts
-dim(from: PointArg$1, to: PointArg$1, opts?: DimOpts): void
+dim(from: PointArg, to: PointArg, opts?: DimOpts): void
 ```
 
-Add a dimension annotation between two points.
+`DimOpts`: `{ offset?: number, label?: string, color?: string, component?: string | string[], currentComponent?: boolean }`
+
+#### `dimLine()` — Add a dimension annotation along a [`Line2D`](/docs/sketch#line2d).
 
-<details><summary><code>DimOpts</code></summary>
+Convenience wrapper around { points from a constrained-sketch [`Line2D`](/docs/sketch#line2d) entity. All `opts` are forwarded unchanged.
 
 ```ts
-interface DimOpts {
-  offset?: number;
-  label?: string;
-  color?: string;
-  component?: string | string[];
-  currentComponent?: boolean;
-}
+const a = point(0, 0);
+const b = point(100, 0);
+dimLine(line(a, b), { label: "Span", offset: -8 });
 ```
 
-</details>
-
-#### `dimLine()`
-
 ```ts
 dimLine(l: Line2D, opts?: DimOpts): void
 ```
 
-Add a dimension annotation along a Line2D.
-
 ### Sketch Export
 
-Export 2D sketches to SVG or DXF format strings.
+#### `sketchToDxf()` — Export a 2D sketch as a DXF string (R12/AC1009 — maximally compatible).
 
-#### `sketchToDxf()`
+For regular sketches, each polygon loop becomes a closed `LWPOLYLINE`. For constrained sketches, exports raw `LINE`, `CIRCLE`, and `ARC` entities from the constraint edge geometry, which preserves internal/shared edges that `toPolygons()` would merge away.
+
+The R12 format is chosen for maximum compatibility with CAM tools, laser-cutter software, and older CAD readers.
 
 ```ts
-sketchToDxf(sketch: Sketch, options?: SketchDxfOptions): string
+const s = rect(100, 60);
+const dxf = sketchToDxf(s, { layer: 'cut' });
 ```
 
-Export a 2D sketch as a DXF string (R12/AC1009 — maximally compatible). For regular sketches, each polygon loop becomes a closed LWPOLYLINE. For constraint sketches, exports LINE, CIRCLE, and ARC entities from the constraint edge geometry.
-
-<details><summary><code>SketchDxfOptions</code></summary>
-
 ```ts
-interface SketchDxfOptions {
-  /** DXF layer name. Default: "0" */
-  layer?: string;
-  /** DXF color index (1–255, AutoCAD ACI). Default: 7 (white/black) */
-  colorIndex?: number;
-}
+sketchToDxf(sketch: Sketch, options?: SketchDxfOptions): string
 ```
 
-</details>
+**`SketchDxfOptions`**
+- `layer?: string` — DXF layer name. Default: "0"
+- `colorIndex?: number` — DXF color index (1–255, AutoCAD ACI). Default: 7 (white/black)
 
-#### `sketchToSvg()`
+#### `sketchToSvg()` — Export a 2D sketch as an SVG string.
 
-```ts
-sketchToSvg(sketch: Sketch, options?: SketchSvgOptions): string
-```
+For regular sketches, exports filled polygon regions. For constrained sketches, exports raw edge geometry (LINE, ARC, CIRCLE) which preserves internal/shared edges that `toPolygons()` would merge away.
 
-Export a 2D sketch as an SVG string. For regular sketches, exports filled polygon regions. For constraint sketches, exports line/arc/circle edge geometry. The SVG uses the sketch's native coordinate system (Y-up) with a transform that flips Y so the output renders correctly in SVG's Y-down space. Coordinates are in sketch units (typically mm).
+The SVG uses the sketch's native coordinate system (Y-up) with a CSS transform that flips Y so the output renders correctly in SVG's Y-down space. Coordinates are in sketch units (typically mm).
 
-<details><summary><code>SketchSvgOptions</code></summary>
+```ts
+const s = rect(100, 60);
+const svg = sketchToSvg(s, { stroke: '#333', strokeWidth: 0.8 });
+```
 
 ```ts
-interface SketchSvgOptions {
-  /** Stroke color. Default: "black" */
-  stroke?: string;
-  /** Stroke width in sketch units. Default: 0.5 */
-  strokeWidth?: number;
-  /** Fill color. Default: "none" */
-  fill?: string;
-  /** Padding around the sketch bounding box in sketch units. Default: 2 */
-  padding?: number;
-  /** If set, scale so 1 sketch-unit = this many px. Otherwise auto-fit. */
-  pixelsPerUnit?: number;
-}
+sketchToSvg(sketch: Sketch, options?: SketchSvgOptions): string
 ```
 
-</details>
+**`SketchSvgOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `stroke?` | `string` | Stroke color. Default: "black" |
+| `strokeWidth?` | `number` | Stroke width in sketch units. Default: 0.5 |
+| `fill?` | `string` | Fill color. Default: "none" |
+| `padding?` | `number` | Padding around the sketch bounding box in sketch units. Default: 2 |
+| `pixelsPerUnit?` | `number` | If set, scale so 1 sketch-unit = this many px. Otherwise auto-fit. |

package/dist/docs-raw/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.