forgecad 0.9.16 → 0.10.1

package/dist-skill/docs/generated/runtime-names.md

@@ -14,27 +14,22 @@ Agents should avoid declaring these names with top-level `const`, `let`, destruc
 These collision-reserved names are case-sensitive:
 
 ```text
-activateBackend, Analysis, arcSlot, assembly, Assembly, assemblyInstructions, assemblyPreview, Blend
-bom, bomToCsv, boolParam, box, cameraTrajectory, Carrier, chamfer, chamferTrackedEdge
-choiceParam, circle, circle2d, Circle2D, circularLayout, circularPattern, circularPattern2d, coalesceEdges
-combine, COMMON_KERFS, compareWith, composeChain, connector, console, constrainedSketch, Constraint
-Counterbore, Curve, Curve3D, cutPlane, cylinder, degrees, difference, difference2d
-dim, dimLine, draft, ellipse, explodeView, faceProfile, fillet, filletCorners
-filletTrackedEdge, fingerJoint, flatPanel, flatPart, formatInstructions, Function, gcode, GCodeBuilder
-getActiveBackend, global, globalThis, group, highlight, Import, ImportedAssembly, importMesh
-importStep, importSvgSketch, initKernel, intersection, intersection2d, intersectWithPlane, joint, jointsView
-laserKit, lib, line, Line2D, linearPattern, linearPattern2d, listParam, loadFont
-loft, Loft, lookupKerf, mirrorCopy, mock, ngon, NurbsCurve3D, nurbsSurface
-NurbsSurface, offsetSolid, param, Param, path, point, Point2D, Points
-polygon, polygonVertices, port, Product, ProductHandleBuilder, ProductHandleFeature, ProductPanelBuilder, ProductRibbonBuilder
-ProductSkin, ProductSkinBuilder, ProductSpoutBuilder, ProductStationBuilder, ProductSurfaceBuilder, ProductSurfaceRef, projectToPlane, queueMicrotask
-radians, rect, Rectangle2D, Ribs, robotExport, roundedRect, Route3D, scene
-Sculpt, sdf, SdfShape, selectEdge, selectEdges, self, setActiveBackend, setImmediate
-setInterval, setTimeout, Shape, ShapeGroup, sheetMetal, SheetMetalPart, sheetStock, Sketch
-sketchToDxf, sketchToSvg, slot, Slot, SolvedAssembly, spec, sphere, spline2d
-star, stroke, Surface, SurfaceBody, SurfaceMembers, surfacePatch, sweep, tabSlot
-text2d, textWidth, torus, toShape, Transform, union, union2d, variableSweep
-verify, viewConfig, Viewport, window, Wood
+activateBackend, Analysis, arcSlot, assembly, Assembly, Blend, bom, box
+cameraTrajectory, Carrier, chamfer, circle2d, Circle2D, circularLayout, circularPattern, circularPattern2d
+coalesceEdges, compareWith, connector, console, constrainedSketch, Curve, Curve3D, cutPlane
+cylinder, difference, difference2d, dim, draft, ellipse, explodeView, faceProfile
+fillet, Function, gcode, GCodeBuilder, getActiveBackend, global, globalThis, group
+Import, ImportedAssembly, initKernel, intersection, intersection2d, intersectWithPlane, joint, Laser
+lib, Line2D, linearPattern, linearPattern2d, loadFont, loft, Loft, mirrorCopy
+mock, ngon, NurbsCurve3D, NurbsSurface, offsetSolid, param, Param, path
+Point2D, Points, polygon, polygonVertices, port, Product, ProductPanelBuilder, ProductRibbonBuilder
+ProductSkin, ProductSkinBuilder, ProductStationBuilder, ProductSurfaceBuilder, ProductSurfaceRef, projectToPlane, queueMicrotask, rect
+Rectangle2D, robotExport, roundedRect, Route3D, scene, Sculpt, sdf, SdfShape
+selectEdge, selectEdges, self, setActiveBackend, setImmediate, setInterval, setTimeout, Shape
+ShapeGroup, sheetMetal, SheetMetalPart, sheetStock, Sim, Sketch, sketchToDxf, sketchToSvg
+slot, SolvedAssembly, spec, sphere, spline2d, stroke, Surface, SurfaceBody
+SurfaceMembers, sweep, text2d, textWidth, torus, toShape, Transform, union
+union2d, variableSweep, verify, Viewport, window, Wood
 ```
 
 `showLabels` is also a runtime global, but it is not part of the top-level collision check. Avoid reusing it unless you intentionally want a local value with that name.

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

@@ -9,7 +9,7 @@ Signed Distance Field modeling for organic forms, smooth booleans, TPMS lattices
 
 ## Contents
 
-- [SDF Materialization](#sdf-materialization) — `toShape`, `combine`
+- [SDF Materialization](#sdf-materialization)
 - [SdfShape](#sdfshape)
 - [sdf](#sdf)
 - [Sculpt](#sculpt)
@@ -18,14 +18,10 @@ Signed Distance Field modeling for organic forms, smooth booleans, TPMS lattices
 
 ### SDF Materialization
 
-#### `toShape()` — Materialize one SDF leaf or all SDF leaves in a renderable tree.
+#### `toShape(value: unknown, options?: SdfToShapeOptions): ToShapeTreeResult` — Materialize one SDF leaf or all SDF leaves in a renderable tree.
 
 Raw `SdfShape` values become mesh-backed [`Shape`](/docs/core#shape)s. Plain objects and arrays preserve their renderable children as a [`ShapeGroup`](/docs/core#shapegroup) when more than one leaf is found. Non-renderable metadata is ignored for materialization and remains available to callers through normal [`require()`](/docs/core#require) return values.
 
-```ts
-toShape(value: unknown, options?: SdfToShapeOptions): ToShapeTreeResult
-```
-
 **`SdfToShapeOptions`**
 
 | Option | Type | Description |
@@ -36,21 +32,11 @@ toShape(value: unknown, options?: SdfToShapeOptions): ToShapeTreeResult
 | `tolerance?` | `number` | Preferred absolute surface tolerance in millimeters. |
 | `minFeatureSize?` | `number` | Smallest feature that should survive meshing, in millimeters. |
 | `simplify?` | `boolean \| "safe"` | Simplification control. `false` disables, `true` and `'safe'` use topology-validated simplification. |
-| `maxTriangles?` | `number` | Optional post-extraction triangle budget. |
+| `maxTriangles?` | `number` | Optional post-extraction triangle budget. Fractional values are floored for compatibility. |
 | `maxGridPoints?` | `number` | Optional pre-extraction grid-point budget. Default is browser-safe. |
 | `minEdgeLength?` | `number` | Lower clamp for resolved edge length. Default: 0.15mm. |
 | `diagnostics?` | `boolean` | Log resolved meshing settings and backend extraction timings. |
 
-#### `combine()` — Collapse a tree of SDF leaves into one continuous SDF field.
-
-This intentionally discards per-leaf color/material identity because the result is one scalar field. Use plain object returns for multi-material SDF preview, and use `combine(...)` only when you want one implicit body.
-
-```ts
-combine(value: unknown, options?: CombineOptions): SdfShape
-```
-
-`CombineOptions`: `{ op?: "union" | "intersection" }`
-
 ---
 
 ## Classes
@@ -59,288 +45,107 @@ combine(value: unknown, options?: CombineOptions): SdfShape
 
 An immutable SDF expression. Supports SDF-specific operations (smooth booleans, domain warps, etc.), can be returned directly for native preview, and converts to a ForgeCAD Shape via `.toShape()` when materialization is needed.
 
-#### `colorHex()` — Display color carried by this implicit leaf.
+#### `get colorHex(): string | undefined` — Display color carried by this implicit leaf.
 
-```ts
-get colorHex(): string | undefined
-```
+#### `get materialProps(): ShapeMaterialProps | undefined` — Display material carried by this implicit leaf.
 
-#### `materialProps()` — Display material carried by this implicit leaf.
+#### `get explicitBounds(): SdfBounds | undefined` — Explicit bounds carried by this implicit leaf, if any.
 
-```ts
-get materialProps(): ShapeMaterialProps | undefined
-```
+#### `clone(): SdfShape` — Clone this SDF expression and its visual metadata.
 
-#### `explicitBounds()` — Explicit bounds carried by this implicit leaf, if any.
+#### `toShape(options?: SdfToShapeOptions): Shape` — Mesh this SDF into a ForgeCAD Shape through ForgeCAD's Surface Nets pipeline. Once converted, the result is a regular Shape — booleans, transforms, export all work.
 
-```ts
-get explicitBounds(): SdfBounds | undefined
-```
+#### `color(value: string | undefined): SdfShape` — Set the display color for this implicit leaf.
 
-#### `clone()` — Clone this SDF expression and its visual metadata.
+#### `material(props: ShapeMaterialProps): SdfShape` — Set PBR display material properties for this implicit leaf.
 
-```ts
-clone(): SdfShape
-```
-
-#### `toShape()` — Mesh this SDF into a ForgeCAD Shape through ForgeCAD's Surface Nets pipeline. Once converted, the result is a regular Shape — booleans, transforms, export all work.
-
-```ts
-toShape(options?: SdfToShapeOptions): Shape
-```
+`ShapeMaterialProps` — defined in [core](/docs/core).
 
-#### `color()` — Set the display color for this implicit leaf.
-
-```ts
-color(value: string | undefined): SdfShape
-```
-
-#### `material()` — Set PBR display material properties for this implicit leaf.
-
-```ts
-material(props: ShapeMaterialProps): SdfShape
-```
-
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
-#### `bounds()` — Set explicit preview/meshing bounds for this implicit leaf.
-
-```ts
-bounds(bounds: SdfBounds | [ Vec3, Vec3 ]): SdfShape
-```
+#### `bounds(bounds: SdfBounds | [ Vec3, Vec3 ]): SdfShape` — Set explicit preview/meshing bounds for this implicit leaf.
 
 `SdfBounds`: `{ min: Vec3, max: Vec3 }`
 
-#### `at()` — Sculpt-style alias for translate().
-
-```ts
-at(x: number, y: number, z: number): SdfShape
-```
-
-#### `move()` — Sculpt-style alias for translate().
-
-```ts
-move(x: number, y: number, z: number): SdfShape
-```
-
-#### `spin()` — Sculpt-style alias for rotateZ().
-
-```ts
-spin(angleDeg: number): SdfShape
-```
-
-#### `tilt()` — Sculpt-style tilt around X, Y, Z, or a custom axis.
-
-```ts
-tilt(angleDeg: number, axis?: "x" | "y" | "z" | Vec3): SdfShape
-```
-
-#### `round()` — Sculpt-style rounded-box helper. Currently applies directly to primitive SDF boxes.
-
-```ts
-round(radius: number): SdfShape
-```
-
-#### `blend()` — Sculpt-style smooth blend with another implicit shape.
-
-```ts
-blend(other: SdfShape, options?: number | { radius?: number; }): SdfShape
-```
-
-#### `goop()` — Sculpt-style alias for blend().
-
-```ts
-goop(other: SdfShape, options?: number | { radius?: number; }): SdfShape
-```
-
-#### `carve()` — Sculpt-style smooth carve/subtract.
-
-```ts
-carve(other: SdfShape, options?: number | { radius?: number; }): SdfShape
-```
-
-#### `keep()` — Sculpt-style smooth intersection/keep operation.
-
-```ts
-keep(other: SdfShape, options?: number | { radius?: number; }): SdfShape
-```
-
-#### `polish()` — Apply a Sculpt material preset or direct material props.
-
-```ts
-polish(input?: SculptPolishInput): SdfShape
-```
-
-#### [`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).
+#### `at(x: number, y: number, z: number): SdfShape` — Sculpt-style alias for translate().
 
-```ts
-intersect(...others: SdfShape[]): SdfShape
-```
-
-#### `clipBox()` — Clip this SDF to an explicit box-shaped design space.
+#### `spin(angleDeg: number): SdfShape` — Sculpt-style alias for rotateZ().
 
-```ts
-clipBox(x: number, y: number, z: number): SdfShape
-```
+#### `tilt(angleDeg: number, axis?: "x" | "y" | "z" | Vec3): SdfShape` — Sculpt-style tilt around X, Y, Z, or a custom axis.
 
-#### `fillWith()` — Keep only the material where this shape overlaps another SDF pattern.
+#### `round(radius: number): SdfShape` — Round all edges of a primitive box while preserving its outer dimensions. Sugar over `offset()`: the box is shrunk by `radius` on every side, then dilated back out with `offset(radius)`, which rounds every edge and corner.
 
-```ts
-fillWith(pattern: SdfShape): SdfShape
-```
-
-#### `fillWithGyroid()` — Keep only the gyroid lattice inside this shape.
-
-```ts
-fillWithGyroid(options: TpmsOptions): SdfShape
-```
+For any other shape, use `.offset(radius)` directly (note it grows the part by `radius`), or `Sculpt.box(x, y, z, { radius })` for a rounded box.
 
-**`TpmsOptions`**
-- `thickness?: number` — Dimensionless field threshold kept for compatibility. Prefer `wallThickness` for approximate millimeter units.
-- `wallThickness?: number` — Approximate physical wall thickness in millimeters.
-- `tpmsThicknessMode?: TpmsThicknessMode` — Override TPMS thickness interpretation. Defaults to metric when `wallThickness` is used, field-threshold when `thickness` is used.
-- Also: `cellSize: number`
+#### `blend(other: SdfShape, options?: number | { radius?: number; }): SdfShape` — Sculpt-style smooth blend with another implicit shape.
 
-#### `fillWithSchwarzP()` — Keep only the Schwarz-P lattice inside this shape.
+#### `carve(other: SdfShape, options?: number | { radius?: number; }): SdfShape` — Sculpt-style smooth carve/subtract.
 
-```ts
-fillWithSchwarzP(options: TpmsOptions): SdfShape
-```
-
-#### `fillWithDiamond()` — Keep only the diamond TPMS lattice inside this shape.
-
-```ts
-fillWithDiamond(options: TpmsOptions): SdfShape
-```
-
-#### `fillWithLidinoid()` — Keep only the lidinoid TPMS lattice inside this shape.
-
-```ts
-fillWithLidinoid(options: TpmsOptions): 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
-```
+#### `polish(input?: SculptPolishInput): SdfShape` — Apply a Sculpt material preset or direct material props.
 
-#### `smoothIntersect()` — Smooth intersection — smoothly intersects.
+#### `union(...others: SdfShape[]): SdfShape` — SDF union (sharp).
 
-```ts
-smoothIntersect(other: SdfShape, radius: number): SdfShape
+```js
+sdf.box(20, 20, 8).union(sdf.cylinder(16, 6), sdf.sphere(7))
 ```
 
-#### `morph()` — Morph between this shape and another. t=0 → this, t=1 → other.
+#### `subtract(...others: SdfShape[]): SdfShape` — SDF difference (sharp) — subtracts others from this.
 
-```ts
-morph(other: SdfShape, t: number): SdfShape
-```
+#### `intersect(...others: SdfShape[]): SdfShape` — SDF intersection (sharp). Also the canonical way to fill a body with a lattice or clip an infinite field to a design space:
 
-#### `translate()` — Translate this SDF by the given offsets in millimeters.
+```js
+// Lattice fill — keep only the gyroid inside the body
+sdf.sphere(18).intersect(sdf.gyroid({ cellSize: 6, wallThickness: 0.8 }))
 
-```ts
-translate(x: number, y: number, z: number): SdfShape
+// Clip an infinite field to a box-shaped design space
+sdf.gyroid({ cellSize: 6, wallThickness: 0.8 }).intersect(sdf.box(40, 25, 16))
 ```
 
-#### `rotate()` — Rotate around an arbitrary axis through the origin.
+#### `smoothUnion(other: SdfShape, radius: number): SdfShape` — Smooth union — blends shapes together with a smooth radius.
 
-```ts
-rotate(axis: [ number, number, number ], angleDeg: number): SdfShape
-```
+#### `smoothSubtract(other: SdfShape, radius: number): SdfShape` — Smooth difference — smoothly carves other from this.
 
-#### `rotateX()` — Rotate around the X axis by the given angle in degrees.
+#### `smoothIntersect(other: SdfShape, radius: number): SdfShape` — Smooth intersection — smoothly intersects.
 
-```ts
-rotateX(angleDeg: number): SdfShape
-```
+#### `morph(other: SdfShape, t: number): SdfShape` — Morph between this shape and another. t=0 → this, t=1 → other.
 
-#### `rotateY()` — Rotate around the Y axis by the given angle in degrees.
+#### `translate(x: number, y: number, z: number): SdfShape` — Translate this SDF by the given offsets in millimeters.
 
-```ts
-rotateY(angleDeg: number): SdfShape
-```
+#### `rotate(axis: Vec3, angleDeg: number): SdfShape` — Rotate around an arbitrary axis through the origin.
 
-#### `rotateZ()` — Rotate around the Z axis by the given angle in degrees.
+#### `rotateX(angleDeg: number): SdfShape` — Rotate around the X axis by the given angle in degrees.
 
-```ts
-rotateZ(angleDeg: number): SdfShape
-```
+#### `rotateY(angleDeg: number): SdfShape` — Rotate around the Y axis by the given angle in degrees.
 
-#### `scale()` — Uniformly scale this SDF around the origin.
+#### `rotateZ(angleDeg: number): SdfShape` — Rotate around the Z axis by the given angle in degrees.
 
-```ts
-scale(factor: number): SdfShape
-```
+#### `scale(factor: number): SdfShape` — Uniformly scale this SDF around the origin.
 
-#### `twist()` — Twist around the Z axis.
+#### `twist(degreesPerUnit: number): SdfShape` — Twist around the Z axis.
 
-```ts
-twist(degreesPerUnit: number): SdfShape
-```
+#### `bend(radius: number): SdfShape` — Bend around the Z axis with given radius.
 
-#### `bend()` — Bend around the Z axis with given radius.
+#### `repeat(spacing: Vec3, count?: Vec3): SdfShape` — Repeat in space. Spacing of 0 on an axis means no repetition. Count of 0 = infinite.
 
-```ts
-bend(radius: number): SdfShape
-```
+#### `circularArray(count: number, offset?: number): SdfShape` — Arrange this SDF in a circular array around the Z axis.
 
-#### `repeat()` — Repeat in space. Spacing of 0 on an axis means no repetition. Count of 0 = infinite.
+The source shape is translated by `offset` in +X before arraying. This uses angular domain folding, so evaluation stays O(1): the source SDF is sampled twice no matter how many copies are requested.
 
-```ts
-repeat(spacing: Vec3, count?: Vec3): SdfShape
-```
+#### `shell(thickness: number): SdfShape` — Hollow out, keeping only a shell of given thickness.
 
-#### `circularArray()` — Arrange this SDF in a circular array around the Z axis.
+#### `offset(distance: number): SdfShape` — Offset the distance field by a constant amount in millimeters.
 
-The source shape is translated by `offset` in +X before arraying. This uses angular domain folding, so evaluation stays O(1): the source SDF is sampled twice no matter how many copies are requested.
+Positive `distance` dilates: every surface moves outward by `distance`, which rounds convex edges and corners — and grows the part by `distance`. Negative `distance` erodes: surfaces move inward, shrinking the part and thinning walls. This is the canonical SDF field offset (`d − distance`) and works on ANY implicit shape — sharp booleans, TPMS lattices, `sdf.fromFunction()` fields — not just primitives.
 
-```ts
-circularArray(count: number, offset?: number): SdfShape
-```
+Like `shell()`, the result is approximate on fields that are not exact distance fields (for example after `twist()`, `bend()`, or smooth booleans).
 
-#### `shell()` — Hollow out, keeping only a shell of given thickness.
+```js
+// Round every edge of a sharp union by 2mm (grows the part by 2mm)
+sdf.box(20, 20, 8).union(sdf.cylinder(16, 6)).offset(2)
 
-```ts
-shell(thickness: number): SdfShape
+// Erode a lattice by 0.2mm to compensate printed over-extrusion
+sdf.sphere(18).intersect(sdf.gyroid({ cellSize: 6, wallThickness: 1.2 })).offset(-0.2)
 ```
 
-#### `displace()` — Displace the surface by a function of position, or by a pattern SdfShape.
+#### `displace(fn: ((x: number, y: number, z: number) => number) | SdfShape, constants?: Record<string, number>): SdfShape` — Displace the surface by a function of position, or by a pattern SdfShape.
 
 ```js
 // Function displacement
@@ -350,11 +155,7 @@ shape.displace((x, y, z) => Math.sin(x) * 0.5)
 shape.displace(sdf.knurl({ pitch: 2, depth: 0.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.
+#### `surfaceDisplace(pattern: SurfacePattern | ((u: number, v: number) => number), options?: SurfaceDisplaceOptions): SdfShape` — 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.
 
@@ -376,19 +177,11 @@ sdf.sphere(27).shell(3)
 shape.surfaceDisplace((u, v) => -Math.sin(u * 2) * 0.3)
 ```
 
-```ts
-surfaceDisplace(pattern: SurfacePattern | ((u: number, v: number) => number), options?: SurfaceDisplaceOptions): SdfShape
-```
-
 **`SurfaceDisplaceOptions`**
 - `uv?: "auto" | "sphere" | "cylinder" | "torus" | "triplanar"` — Override auto-detected UV mode. Default: 'auto' (detects from SDF tree).
 - `triplanarSharpness?: number` — Triplanar blend sharpness — higher = crisper transitions. Default: 4. Only used in triplanar mode.
 
-#### `onion()` — Create concentric onion layers.
-
-```ts
-onion(layers: number, thickness: number): SdfShape
-```
+#### `onion(layers: number, thickness: number): SdfShape` — Create concentric onion layers.
 
 ---
 
@@ -398,20 +191,13 @@ onion(layers: number, thickness: number): SdfShape
 
 SDF modeling — signed distance field primitives, smooth booleans, TPMS lattices, domain warps, and surface patterns.
 
-Return `SdfShape` values directly from a ForgeCAD script for native raymarch preview. Plain objects and arrays of SDF leaves are renderable too, so object keys become named preview parts.
-
-Call `.toShape()` or `toShape(...)` only when you need a mesh-backed ForgeCAD Shape for export, mesh booleans, or mixed SDF/manifold projects. All shapes live as a lazy expression tree until that materialization boundary.
-
-SDF is inherently implicit and sampled, not B-rep/exact geometry. Use it with caution when precision, tolerances, or exact export matter.
+Return `SdfShape` values directly from a script for native raymarch preview; plain objects and arrays of SDF leaves render too (object keys become named preview parts). Shapes live as a lazy expression tree — call `.toShape()` / `toShape(...)` only at the materialization boundary: export, mesh booleans, or mixed SDF/manifold projects.
 
-```js
-return sdf.smoothUnion(sdf.sphere(10), sdf.box(15, 15, 15), { radius: 3 })
-  .color('#4488cc');
-```
+SDF geometry is implicit and sampled, not B-rep/exact. Use with caution when precision, tolerances, or exact export matter.
 
 ```js
 return {
-  shell: sdf.sphere(20).shell(2).color('#9be7ff'),
+  shell: sdf.smoothUnion(sdf.sphere(10), sdf.box(15, 15, 15), { radius: 3 }).shell(2),
   core: sdf.gyroid({ cellSize: 6, wallThickness: 0.8 })
     .intersect(sdf.sphere(18))
     .color('#ffcf5a'),
@@ -427,14 +213,11 @@ return {
 - `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.
-- `tpmsBlock(options: TpmsBlockOptions): SdfShape` — TPMS block preset clipped to an explicit design space.
-- `withinBox(shape: SdfShape, options: { size: Vec3; }): SdfShape` — Clip an SDF shape to a box-shaped design space.
 - `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.
@@ -446,13 +229,16 @@ return {
 - `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()`.
 - `pattern2d(): Pattern2DBuilder` — Create typed, composable 2D surface patterns for `.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.
-- `circularArray(shape: SdfShape, count: number, offset?: number): SdfShape` — Arrange an SDF shape in a circular array around the Z axis with O(1) folded-domain evaluation.
 - `SurfacePattern: typeof SurfacePattern` — A 2D surface pattern — a heightmap function for use with `.surfaceDisplace()`.
 - `fromFunction(fn: SdfFunctionSource, options: SdfFunctionOptions): SdfShape` — Create a custom SDF from one expression; shader-safe expressions raymarch directly.
-- `Sculpt: { sphere: (radius: number) => SdfShape; box: (x: number, y: number, z: number, options?: SculptBoxOptions) => SdfShape; cylinder: (height: number, radius: number) => SdfShape; disk: (radius: number, thickness?: number) => SdfShape; circle: (radius: number, thickness?: number) => SdfShape; capsule: (height: number, radius: number) => SdfShape; torus: (majorRadius: number, minorRadius: number) => SdfShape; cone: (height: number, radius: number) => SdfShape; tube: (points: SculptPointList, options?: SculptTubeOptions) => SdfShape; curve: (points: SculptPointList, options?: SculptTubeOptions) => SdfShape; path: (points: SculptPointList, options?: SculptTubeOptions) => SdfShape; blend: (first?: SculptBlendInput | SculptBlendOptions, optionsOrShape?: SculptBlendInput | SculptBlendOptions, ...rest: (SculptBlendInput | SculptBlendOptions)[]) => SdfShape; union: (first?: SculptBlendInput, ...rest: SculptBlendInput[]) => SdfShape; carve: (base: SdfShape, cutters: SculptBlendInput, options?: SculptBlendOptions) => SdfShape; keep: (first?: SculptBlendInput | SculptBlendOptions, optionsOrShape?: SculptBlendInput | SculptBlendOptions, ...rest: (SculptBlendInput | SculptBlendOptions)[]) => SdfShape; polish: (shape: SdfShape, input?: SculptPolishInput) => SdfShape; material: (input?: SculptPolishInput) => ShapeMaterialProps & { color?: string; }; look: (preset?: SculptLookPreset) => SceneOptions; knownMaterials: typeof knownSculptMaterialPresets; }` — Sculpt-like facade: friendly liquid-modeling verbs backed by the same SDF kernel.
+- `combine(value: unknown, options?: CombineOptions): SdfShape` — Collapse a plain object/array tree of SDF leaves into one continuous implicit field. Per-leaf color/material identity is intentionally discarded — the result is one scalar field. Use plain object returns for multi-material SDF preview, and `sdf.combine(...)` only when you want one implicit body. Explicit shape lists are covered by `a.union(b, c)`; pass `{ op: 'intersection' }` to intersect instead.
+
+  ```js
+  // Built a part as a named tree for preview, now need one field to shell:
+  const parts = { body: sdf.box(40, 30, 12), boss: sdf.cylinder(10, 8) };
+  return sdf.combine(parts).shell(1.2);
+  ```
+- `Sculpt: { ... }` — Sculpt-like facade: friendly liquid-modeling verbs backed by the same SDF kernel. See [`Sculpt`](#sculpt).
 
 ### `Sculpt`
 
@@ -460,13 +246,11 @@ return {
 - `box(x: number, y: number, z: number, options?: SculptBoxOptions): SdfShape` — Create a liquid SDF box; pass `{ radius }` for a rounded box.
 - `cylinder(height: number, radius: number): SdfShape` — Create a liquid SDF cylinder centered at the origin, axis along Z.
 - `disk(radius: number, thickness?: number): SdfShape` — Create a thin circular disk centered at the origin, axis along Z. Useful as a circular cutter or insert.
-- `circle(radius: number, thickness?: number): SdfShape` — Alias for `Sculpt.disk()`.
 - `capsule(height: number, radius: number): SdfShape` — Create a liquid SDF capsule centered at the origin, axis along Z.
 - `torus(majorRadius: number, minorRadius: number): SdfShape` — Create a liquid SDF torus lying in the XY plane.
 - `cone(height: number, radius: number): SdfShape` — Create a liquid SDF cone.
 - `tube(points: SculptPointList, options?: SculptTubeOptions): SdfShape` — Create a smooth tube through a list of 3D points.
 - `curve(points: SculptPointList, options?: SculptTubeOptions): SdfShape` — Create a smooth variable-thickness sweep through 3D control points.
-- `path(points: SculptPointList, options?: SculptTubeOptions): SdfShape` — Alias for `Sculpt.tube()`; points may use [x, y, z, radius] for variable thickness.
 - `blend(first?: SculptBlendArg, optionsOrShape?: SculptBlendArg, ...rest: SculptBlendArg[]): SdfShape` — Smoothly blend one or more SDF shapes into a continuous body.
 - `union(first?: SculptBlendInput, ...rest: SculptBlendInput[]): SdfShape` — Sharply union one or more SDF shapes.
 - `carve(base: SdfShape, cutters: SculptBlendInput, options?: SculptBlendOptions): SdfShape` — Smoothly subtract one or more cutter shapes from a base shape.