forgecad 0.9.16 → 0.10.0

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

@@ -9,8 +9,8 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 
 ## Contents
 
-- [Curves & Surfacing](#curves-surfacing) — `Curve.Blend`, `Curve.BlendG2`, `Curve.Arc`, `Curve.Line`, `Curve.Polyline`, `Curve.Spline`, `Curve.Nurbs`, `Curve.Fit`, `Curve.Trim`, `Curve.Reverse`, `Curve.Route`, `Curve.Helix`, `Loft.station`, `Loft.leftRail`, `Loft.rightRail`, `Loft.frontRail`, `Loft.backRail`, `Loft.centerRail`, `Loft.pathOnXz`, `Loft.pathOnYz`, `Loft.pathOnXy`, `Loft.withGuideRails`, `spline2d`, `loft`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`
-- [Surface Members](#surface-members) — `surfaceBand`, `SurfaceBody`
+- [Curves & Surfacing](#curves-surfacing)
+- [Surface Members](#surface-members)
 - [Curve3D](#curve3d)
 - [Route3D](#route3d)
 - [NurbsCurve3D](#nurbscurve3d)
@@ -23,9 +23,6 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 - [ProductStationBuilder](#productstationbuilder)
 - [ProductPanelBuilder](#productpanelbuilder)
 - [ProductRibbonBuilder](#productribbonbuilder)
-- [ProductSpoutBuilder](#productspoutbuilder)
-- [ProductHandleBuilder](#producthandlebuilder)
-- [ProductHandleFeature](#producthandlefeature)
 - [CylinderCarrier](#cylindercarrier)
 - [PlaneCarrier](#planecarrier)
 - [ProductSkinCarrier](#productskincarrier)
@@ -44,15 +41,12 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 - [Product](#product)
 - [Carrier](#carrier)
 - [SurfaceMembers](#surfacemembers)
-- [Slot](#slot)
-- [Counterbore](#counterbore)
-- [Ribs](#ribs)
 
 ## Functions
 
 ### Curves & Surfacing
 
-#### `Curve.Blend()` — Create an exact G1 blend curve between two directed endpoints.
+#### `Curve.Blend(start: CurveBlendEndpoint, end: CurveBlendEndpoint): NurbsCurve3D` — Create an exact G1 blend curve between two directed endpoints.
 
 The returned curve is a cubic non-rational `NurbsCurve3D`: ForgeCAD converts the endpoint positions and tangents into Bezier control points, so the curve can feed `sweep` and exact surface boundaries through the existing `nurbs` IR rather than a sampled polyline.
 
@@ -64,16 +58,12 @@ const rail = Curve.Blend(
 const tube = sweep(circle2d(2), rail);
 ```
 
-```ts
-Curve.Blend(start: CurveBlendEndpoint, end: CurveBlendEndpoint): NurbsCurve3D
-```
-
 **`CurveBlendEndpoint`**
 - `point: Vec3` — Endpoint position.
 - `tangent: Vec3` — Tangent direction at this endpoint. Magnitude is ignored.
 - `weight?: number` — Tangent reach relative to the endpoint chord length. Default 1.
 
-#### `Curve.BlendG2()` — Create an exact G2 blend curve between two directed endpoints.
+#### `Curve.BlendG2(start: CurveBlendG2Endpoint, end: CurveBlendG2Endpoint): NurbsCurve3D` — Create an exact G2 blend curve between two directed endpoints.
 
 This is the curvature-aware companion to `Curve.Blend()`. It returns a degree-5 non-rational `NurbsCurve3D` that matches endpoint position, tangent direction, and optional curvature/second-derivative vectors.
 
@@ -84,14 +74,10 @@ const rail = Curve.BlendG2(
 );
 ```
 
-```ts
-Curve.BlendG2(start: CurveBlendG2Endpoint, end: CurveBlendG2Endpoint): NurbsCurve3D
-```
-
 **`CurveBlendG2Endpoint`** extends CurveBlendEndpoint
 - `curvature?: Vec3` — Optional endpoint curvature/second-derivative vector. Default is zero.
 
-#### `Curve.Arc()` — Create an exact circular 3D arc from start, end, and start tangent.
+#### `Curve.Arc(options: CurveArcOptions): NurbsCurve3D` — Create an exact circular 3D arc from start, end, and start tangent.
 
 The returned curve is a rational quadratic `NurbsCurve3D`, split into stable spans when needed, so it can feed `sweep` without sampling the authoring intent away.
 
@@ -104,57 +90,25 @@ const rail = Curve.Arc({
 const tube = sweep(circle2d(2), rail);
 ```
 
-```ts
-Curve.Arc(options: CurveArcOptions): NurbsCurve3D
-```
-
 **`CurveArcOptions`**
 - `start: Vec3` — Arc start point.
 - `end: Vec3` — Arc end point.
 - `tangent: Vec3` — Tangent direction at the start point. Magnitude is ignored.
 
-#### `Curve.Line()` — Create an exact straight 3D NURBS line segment.
+#### `Curve.Line(start: Vec3, end: Vec3): NurbsCurve3D` — Create an exact straight 3D NURBS line segment.
 
 ```js
 const rail = Curve.Line([0, 0, 0], [80, 0, 15]);
 const rib = sweep(circle2d(2), rail);
 ```
 
-```ts
-Curve.Line(start: Vec3, end: Vec3): NurbsCurve3D
-```
-
-#### `Curve.Polyline()` — Create a polyline path as cloned 3D points.
-
-Polylines are exact as route/path input to `sweep`. Use `Curve.Route` when the centerline needs bend and endpoint-frame metadata.
-
-```ts
-Curve.Polyline(points: Vec3[]): Vec3[]
-```
-
-#### `Curve.Spline()` — Create a smooth Catmull-Rom spline path.
-
-This is a smooth sampled curve object. Use `Curve.Nurbs` when the path must preserve exact control-point and knot data.
-
-```ts
-Curve.Spline(points: Vec3[], options?: Spline3DOptions): Curve3D
-```
-
-**`Spline3DOptions`**
-- `closed?: boolean` — Closed loop (default false).
-- `tension?: number` — Catmull-Rom tension in [0, 1]. 0 = very round, 1 = linear-ish. Default 0.5.
-
-#### `Curve.Nurbs()` — Create an exact NURBS 3D curve from control points, weights, knots, and degree.
+#### `Curve.Nurbs(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D` — Create an exact NURBS 3D curve from control points, weights, knots, and degree.
 
 ```js
 const rail = Curve.Nurbs([[0, 0, 0], [30, 4, 12], [60, -4, 12], [90, 0, 0]]);
 const tube = sweep(circle2d(2), rail);
 ```
 
-```ts
-Curve.Nurbs(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D
-```
-
 **`NurbsCurve3DOptions`**
 
 | Option | Type | Description |
@@ -164,9 +118,9 @@ Curve.Nurbs(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D
 | `knots?` | `number[]` | Knot vector (default: uniform clamped). Must have length = controlPoints.length + degree + 1. |
 | `closed?` | `boolean` | Whether the curve is closed/periodic (default false). |
 
-#### `Curve.Fit()` — Fit a non-rational NURBS curve that interpolates every input point.
+#### `Curve.Fit(points: Vec3[], options?: CurveFitOptions): NurbsCurve3D` — Fit a non-rational NURBS curve that interpolates every input point.
 
-This is global B-spline interpolation, not approximate curve reduction: ForgeCAD computes chord-length parameters, averaged clamped knots, solves the control points, then verifies the interpolation residual against `tolerance`.
+This is global B-spline interpolation, not approximate curve reduction: ForgeCAD computes chord-length parameters, averaged clamped knots, solves the control points, then verifies the interpolation residual against `tolerance`. With `{ closed: true }` the fit is standard periodic B-spline interpolation: the curve loops smoothly from the last point back to the first (do not repeat the first point at the end).
 
 ```js
 const rail = Curve.Fit(
@@ -174,33 +128,28 @@ const rail = Curve.Fit(
   { degree: 3, tolerance: 0.001 },
 );
 const tube = sweep(circle2d(2), rail);
-```
 
-```ts
-Curve.Fit(points: Vec3[], options?: CurveFitOptions): NurbsCurve3D
+// Closed loop through four points — no duplicated closing point
+const loop = Curve.Fit(
+  [[30, 0, 0], [0, 30, 0], [-30, 0, 0], [0, -30, 0]],
+  { closed: true },
+);
 ```
 
 **`CurveFitOptions`**
 - `degree?: number` — Polynomial degree. Default is cubic, reduced automatically for short point lists.
 - `tolerance?: number` — Maximum allowed interpolation residual in model units. Default 1e-7.
+- `closed?: boolean` — Interpolate a closed periodic loop through the points. The loop closes from the last point back to the first automatically — do not repeat the first point at the end.
 
-#### `Curve.Trim()` — Extract an exact curve segment from normalized parameter `start` to `end`.
+#### `Curve.Trim<T extends CurveTrimInput>(curve: T, start: number, end: number): CurveTrimOutput<T>` — Extract an exact curve segment from normalized parameter `start` to `end`.
 
 `NurbsCurve3D` inputs are trimmed with exact knot insertion/subdomain extraction. Polyline point arrays are trimmed by arclength over their exact line segments. Sampled `Curve3D` splines are rejected until ForgeCAD has a tolerance-controlled rebuild path.
 
-```ts
-Curve.Trim<T extends CurveTrimInput>(curve: T, start: number, end: number): CurveTrimOutput<T>
-```
-
-#### `Curve.Reverse()` — Reverse an exact curve without changing its geometry.
+#### `Curve.Reverse<T extends CurveTrimInput>(curve: T): CurveTrimOutput<T>` — Reverse an exact curve without changing its geometry.
 
 `NurbsCurve3D` inputs reverse control points, weights, and knots. Polyline point arrays are cloned and reversed. Sampled `Curve3D` splines are rejected until ForgeCAD has a tolerance-controlled rebuild path.
 
-```ts
-Curve.Reverse<T extends CurveTrimInput>(curve: T): CurveTrimOutput<T>
-```
-
-#### `Curve.Route()` — Build analytic 3D line/arc routes for sweeps.
+#### `Curve.Route: typeof Route3D` — Build analytic 3D line/arc routes for sweeps.
 
 `Curve.Route.fromPolyline()` is the canonical route API. It returns a `Route3D` value object, preserving exact route segments, named port frames, and the lowerable `route3d` sweep compile plan.
 
@@ -212,11 +161,7 @@ const route = Curve.Route.fromPolyline(
 const tube = sweep(circle2d(4), route);
 ```
 
-```ts
-Curve.Route: typeof Route3D
-```
-
-#### `Curve.Helix()` — Build helical paths and swept coils.
+#### `Curve.Helix: { path(options: HelixOptions): CurveHelixPath; coil: CurveHelixCoil; }` — Build helical paths and swept coils.
 
 `Curve.Helix` is the canonical namespace for helical paths and coils. It uses the same sweep-based lowering as other curve paths.
 
@@ -225,10 +170,6 @@ const guide = Curve.Helix.path({ radius: 20, pitch: 6, turns: 4 });
 const spring = Curve.Helix.coil({ radius: 20, pitch: 6, turns: 4, wireRadius: 1 });
 ```
 
-```ts
-Curve.Helix: { path(options: HelixOptions): CurveHelixPath; coil: CurveHelixCoil; }
-```
-
 **`HelixOptions`**
 
 | Option | Type | Description |
@@ -243,95 +184,59 @@ Curve.Helix: { path(options: HelixOptions): CurveHelixPath; coil: CurveHelixCoil
 
 `CurveHelixPath`: `{ radius: number, pitch: number, turns: number, height: number, startAngle: number, clockwise: boolean }`
 
-#### `Loft.station()` — Create a loft station from a 2D profile and an axis position.
-
-```ts
-Loft.station(profile: Sketch, position: number): LoftStation
-```
+#### `Loft.station(profile: Sketch, position: number): LoftStation` — Create a loft station from a 2D profile and an axis position.
 
 `LoftStation`: `{ profile: Sketch, position: number }`
 
-#### `Loft.leftRail()` — Create a guide rail that constrains the section-local negative-X side.
+#### `Loft.field(profiles: Sketch[], heights: number[], options?: FieldLoftOptions): Shape` — Loft by interpolating signed-distance fields instead of matching vertices.
 
-```ts
-Loft.leftRail(path: LoftGuideRailPath): LoftGuideRail
-```
-
-`LoftGuideRail`: `{ side: LoftGuideRailSide, path: LoftGuideRailPath }`
+Use this path when profiles change character, such as round shafts blending into flat, cruciform, or lobed tips. It is Manifold-only, mesh-based, and slower than stitched lofting, but it avoids profile-point correspondence artifacts because it blends profile fields instead of boundary vertices.
 
-#### `Loft.rightRail()` — Create a guide rail that constrains the section-local positive-X side.
+**`LoftOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
+- `boundsPadding?: number` — Optional extra bounds padding.
 
-```ts
-Loft.rightRail(path: LoftGuideRailPath): LoftGuideRail
-```
+**`FieldLoftOptions`** extends LoftOptions
+- `simplify?: boolean | "safe"` — Simplification control after field extraction. Default is topology-safe simplification.
+- `maxTriangles?: number` — Hard post-extraction triangle budget. Must be a positive integer. If safe simplification cannot reach it, the build fails.
 
-#### `Loft.frontRail()` — Create a guide rail that constrains the section-local positive-Y side.
+#### `Loft.leftRail(path: LoftGuideRailPath): LoftGuideRail` — Create a guide rail that constrains the section-local negative-X side.
 
-```ts
-Loft.frontRail(path: LoftGuideRailPath): LoftGuideRail
-```
+`LoftGuideRail`: `{ side: LoftGuideRailSide, path: LoftGuideRailPath }`
 
-#### `Loft.backRail()` — Create a guide rail that constrains the section-local negative-Y side.
+#### `Loft.rightRail(path: LoftGuideRailPath): LoftGuideRail` — Create a guide rail that constrains the section-local positive-X side.
 
-```ts
-Loft.backRail(path: LoftGuideRailPath): LoftGuideRail
-```
+#### `Loft.frontRail(path: LoftGuideRailPath): LoftGuideRail` — Create a guide rail that constrains the section-local positive-Y side.
 
-#### `Loft.centerRail()` — Create a guide rail that moves section centers along the loft.
+#### `Loft.backRail(path: LoftGuideRailPath): LoftGuideRail` — Create a guide rail that constrains the section-local negative-Y side.
 
-```ts
-Loft.centerRail(path: LoftGuideRailPath): LoftGuideRail
-```
+#### `Loft.centerRail(path: LoftGuideRailPath): LoftGuideRail` — Create a guide rail that moves section centers along the loft.
 
-#### `Loft.pathOnXz()` — Place a 2D guide path onto the XZ plane.
+#### `Loft.pathOnXz(path: LoftPath2D, y?: number): Vec3[]` — Place a 2D guide path onto the XZ plane.
 
 The path's first coordinate becomes X and its second coordinate becomes Z. Use this for left/right silhouette rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
 
-```ts
-Loft.pathOnXz(path: LoftPath2D, y?: number): Vec3[]
-```
-
-#### `Loft.pathOnYz()` — Place a 2D guide path onto the YZ plane.
+#### `Loft.pathOnYz(path: LoftPath2D, x?: number): Vec3[]` — Place a 2D guide path onto the YZ plane.
 
 The path's first coordinate becomes Y and its second coordinate becomes Z. Use this for front/back crown rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
 
-```ts
-Loft.pathOnYz(path: LoftPath2D, x?: number): Vec3[]
-```
-
-#### `Loft.pathOnXy()` — Place a 2D guide path onto the XY plane.
+#### `Loft.pathOnXy(path: LoftPath2D, z?: number): Vec3[]` — Place a 2D guide path onto the XY plane.
 
 The path's first coordinate becomes X and its second coordinate becomes Y. Use this when lofting along X or Y and a rail lives in a horizontal sketch plane.
 
-```ts
-Loft.pathOnXy(path: LoftPath2D, z?: number): Vec3[]
-```
-
-#### `Loft.withGuideRails()` — Loft through profile stations while forcing generated sections to follow guide rails.
+#### `Loft.withGuideRails(stations: LoftStation[], rails: LoftGuideRail[], options?: LoftWithGuideRailsOptions): Shape` — Loft through profile stations while forcing generated sections to follow guide rails.
 
 Stations define the cross-section family. Guide rails define the side or center paths the loft must pass through. With opposite side rails, the section is scaled to touch both rails. With one side rail, the section keeps its interpolated size unless a center rail is also present.
 
-```ts
-Loft.withGuideRails(stations: LoftStation[], rails: LoftGuideRail[], options?: LoftWithGuideRailsOptions): Shape
-```
-
-**`LoftOptions`**
-- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
-- `boundsPadding?: number` — Optional extra bounds padding.
-
 **`LoftWithGuideRailsOptions`** extends LoftOptions
 - `axis?: LoftAxis` — Primary station axis. Default Z.
 - `samples?: number` — Number of generated loft stations including ends. Default scales with station count.
 - `railSamples?: number` — Number of points sampled from curve-backed rails before axis interpolation. Default 64.
 
-#### `spline2d()` — Build a smooth Catmull-Rom spline sketch from 2D control points.
+#### `spline2d(points: Vec2[], options?: Spline2DOptions): Sketch` — 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.
 
-```ts
-spline2d(points: Vec2[], options?: Spline2DOptions): Sketch
-```
-
 **`Spline2DOptions`**
 
 | Option | Type | Description |
@@ -342,21 +247,15 @@ spline2d(points: Vec2[], options?: Spline2DOptions): Sketch
 | `strokeWidth?` | `number` | For open splines, provide stroke width to return a solid Sketch. If omitted for open splines, an error is thrown. |
 | `join?` | `"Round" \| "Square"` | Stroke join for open splines. Default 'Round'. |
 
-#### `loft()` — Loft between multiple sketches along Z stations.
+#### `loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape` — Loft between multiple sketches along Z stations.
 
 Profiles can differ in topology and vertex count: interpolation is done on signed-distance fields and meshed with level-set extraction. Heights must be strictly increasing. Compatible loft stacks can also stay on the maintained export-backend path.
 
-Performance note: loft is significantly heavier than primitive/extrude/revolve. If the part is axis-symmetric (bottles, vases, knobs), prefer revolve().
-
-```ts
-loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape
-```
+The surface is smooth through 3+ stations (C1 spanwise interpolation, like CAD lofts), so it can bow slightly past the straight ruling between stations; sections are matched exactly at their stations. Two-station lofts are ruled. `edgeLength` caps the sample spacing in curved or twisted regions (quality presets scale it); straight regions keep input density.
 
-#### `sweep()`
+Performance note: loft is significantly heavier than primitive/extrude/revolve. If the part is axis-symmetric (bottles, vases, knobs), prefer revolve().
 
-```ts
-sweep(profile: Sketch, path: SweepPathInput, options?: SweepOptions): Shape
-```
+#### `sweep(profile: Sketch, path: SweepPathInput, options?: SweepOptions): Shape`
 
 **`SweepOptions`**
 
@@ -367,7 +266,7 @@ sweep(profile: Sketch, path: SweepPathInput, options?: SweepOptions): Shape
 | `boundsPadding?` | `number` | Optional extra bounds padding. |
 | `up?` | `Vec3` | Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. |
 
-#### `variableSweep()` — Sweep a variable cross-section along a 3D spine curve.
+#### `variableSweep(spine: SweepPathInput, sections: VariableSweepSection[], options?: VariableSweepOptions): Shape` — Sweep a variable cross-section along a 3D spine curve.
 
 Unlike sweep(), which uses a single constant profile, variableSweep() interpolates between multiple profiles at different stations along the spine. This enables organic shapes like tapering tubes, bone-like structures, and sculptural forms.
 
@@ -375,10 +274,6 @@ Each section specifies a t parameter (0 = start, 1 = end of spine) and a 2D prof
 
 Performance note: like sweep(), this uses level-set meshing internally.
 
-```ts
-variableSweep(spine: SweepPathInput, sections: VariableSweepSection[], options?: VariableSweepOptions): Shape
-```
-
 **`VariableSweepSection`**
 - `t: number` — Parameter along the spine (0 = start, 1 = end).
 - `profile: Sketch` — Cross-section profile at this station.
@@ -392,98 +287,11 @@ 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). |
-| `domain?` | `SurfaceDomainOptions` | Optional rectangular parameter domain in normalized [0, 1] U/V space. |
-| `trim?` | `SurfaceTrimOptions` | Optional polygonal or NURBS-curve UV trim loops. Truck and OCCT support open trimmed surfaces; Manifold supports sampled thickened trimmed solids. |
-| `tessellation?` | `SurfaceTessellationOptions` | Optional Truck kernel tessellation controls for render mesh generation. |
-| `approximate?` | `boolean` | Explicit opt-in for sampled approximation paths on non-exact backends. |
-
-**`SurfaceDomainOptions`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `uMin?` | `number` | Lower U parameter bound in normalized surface space (default 0). |
-| `uMax?` | `number` | Upper U parameter bound in normalized surface space (default 1). |
-| `vMin?` | `number` | Lower V parameter bound in normalized surface space (default 0). |
-| `vMax?` | `number` | Upper V parameter bound in normalized surface space (default 1). |
-
-**`SurfaceTrimOptions`**
-- `outer: SurfaceTrimLoopInput` — Outer trim loop in normalized post-domain UV space.
-- `holes?: SurfaceTrimLoopInput[]` — Optional hole loops in normalized post-domain UV space.
-
-**`SurfaceTessellationOptions`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `mode?` | `"uniform" \| "adaptive"` | `uniform` uses resolution directly; `adaptive` lets the Truck kernel refine open sheets from chord error. |
-| `tolerance?` | `number` | Target chord-error tolerance in model units for adaptive Truck tessellation. |
-| `minResolution?` | `number` | Minimum adaptive samples per direction. |
-| `maxResolution?` | `number` | Maximum adaptive samples per direction. Defaults to `resolution` when omitted. |
-
-#### `surfacePatch()` — Create a smooth surface patch from 4 boundary curves (Coons patch).
-
-The four curves form the boundary of a quadrilateral patch:
-
-- bottom: u=0..1 at v=0 (from corner00 to corner10)
-- top: u=0..1 at v=1 (from corner01 to corner11)
-- left: v=0..1 at u=0 (from corner00 to corner01)
-- right: v=0..1 at u=1 (from corner10 to corner11)
-
-The interior is filled using bilinear Coons patch interpolation: P(u,v) = Lc(u,v) + Ld(u,v) - B(u,v)
-
-The result is a thin solid created by offsetting the surface mesh along its normals by the specified thickness.
-
-Note: curves should meet at corners. Small gaps are tolerated.
-
-```ts
-surfacePatch(curves: { ... }, options?: SurfacePatchOptions): Shape
-```
-
-**`SurfacePatchOptions`**
-- `resolution?: number` — Number of samples along each direction. Default 24.
-- `thickness?: number` — Thickness of the generated solid. Default 0 for an open exact sheet.
-- `approximate?: boolean` — Allow explicit approximation for non-exact curve inputs such as Curve3D samples.
-
 ### Surface Members
 
-#### `surfaceBand()`
+#### `surfaceBand<C extends SurfaceCoordinate>(path: SurfacePath<C> | SurfacePathBuilder<C>, width: WidthProfile, cap?: SurfaceBandCap): SurfaceBand<C>`
 
-```ts
-surfaceBand<C extends SurfaceCoordinate>(path: SurfacePath<C> | SurfacePathBuilder<C>, width: WidthProfile, cap?: SurfaceBandCap): SurfaceBand<C>
-```
-
-#### `SurfaceBody()` — Start a surface-member body builder for straps, inlays, guards, braces, cuffs, and similar physical members that live on a carrier surface.
+#### `SurfaceBody(name: string): SurfaceBodyBuilder` — Start a surface-member body builder for straps, inlays, guards, braces, cuffs, and similar physical members that live on a carrier surface.
 
 ```js
 const carrier = Carrier.cylinder('guard-envelope').diameter(84).height(36).clearance(2);
@@ -504,10 +312,6 @@ const guard = SurfaceBody('simple-guard')
   .build();
 ```
 
-```ts
-SurfaceBody(name: string): SurfaceBodyBuilder
-```
-
 ---
 
 ## Classes
@@ -524,35 +328,15 @@ SurfaceBody(name: string): SurfaceBodyBuilder
 
 **Methods:**
 
-#### `sampleBySegment()` — Sample the curve with a fixed number of points per segment.
-
-```ts
-sampleBySegment(samplesPerSegment?: number): Vec3[]
-```
-
-#### `sample()` — Sample the curve to an approximate total point count.
-
-```ts
-sample(count?: number): Vec3[]
-```
-
-#### `pointAt()` — Return the position on the curve at normalized parameter `t` in `[0, 1]`. O(1), no allocations.
-
-```ts
-pointAt(t: number): Vec3
-```
+#### `sampleBySegment(samplesPerSegment?: number): Vec3[]` — Sample the curve with a fixed number of points per segment.
 
-#### `tangentAt()` — Return a unit tangent vector at normalized parameter `t` in `[0, 1]`. O(1), analytical derivative.
+#### `sample(count?: number): Vec3[]` — Sample the curve to an approximate total point count.
 
-```ts
-tangentAt(t: number): Vec3
-```
+#### `pointAt(t: number): Vec3` — Return the position on the curve at normalized parameter `t` in `[0, 1]`. O(1), no allocations.
 
-#### `length()` — Approximate the curve length by polyline sampling.
+#### `tangentAt(t: number): Vec3` — Return a unit tangent vector at normalized parameter `t` in `[0, 1]`. O(1), analytical derivative.
 
-```ts
-length(samples?: number): number
-```
+#### `length(samples?: number): number` — Approximate the curve length by polyline sampling.
 
 ### `Route3D`
 
@@ -569,11 +353,7 @@ const pipe = sweep(difference2d(circle2d(8), circle2d(6)), route);
 const outlet = route.port("outlet");
 ```
 
-#### `fromPolyline()` — Build a line/arc route from virtual polyline corner points.
-
-```ts
-static fromPolyline(points: Route3DVec3[], options?: Route3DFromPolylineOptions): Route3D
-```
+#### `static fromPolyline(points: Route3DVec3[], options?: Route3DFromPolylineOptions): Route3D` — Build a line/arc route from virtual polyline corner points.
 
 **`Route3DFromPolylineOptions`**
 
@@ -584,41 +364,17 @@ static fromPolyline(points: Route3DVec3[], options?: Route3DFromPolylineOptions)
 | `endPort?` | `string` | Name for the end port. Default "end". |
 | `up?` | `Vec3` | Preferred up vector for deterministic port frames. Default [0, 0, 1]. |
 
-#### `length()` — Total centerline length, including line and bend arc segments.
+#### `get length(): number` — Total centerline length, including line and bend arc segments.
 
-```ts
-get length(): number
-```
-
-#### `segments()` — Exact line and arc segments that make up this route.
-
-```ts
-get segments(): Route3DSegment[]
-```
-
-#### `ports()` — Named port frames, keyed by port name.
-
-```ts
-get ports(): Record<string, RoutePortFrame>
-```
-
-#### `port()` — Return one named route port frame.
-
-```ts
-port(name: string): RoutePortFrame
-```
+#### `get segments(): Route3DSegment[]` — Exact line and arc segments that make up this route.
 
-#### `toSweepPathPlan()` — Convert this route to the compile plan consumed by sweep().
+#### `get ports(): Record<string, RoutePortFrame>` — Named port frames, keyed by port name.
 
-```ts
-toSweepPathPlan(): SweepPathCompilePlan
-```
+#### `port(name: string): RoutePortFrame` — Return one named route port frame.
 
-#### `toPolyline()` — Sample this analytic route as a polyline for inspection or backend lowering.
+#### `toSweepPathPlan(): SweepPathCompilePlan` — Convert this route to the compile plan consumed by sweep().
 
-```ts
-toPolyline(options?: number | Route3DToPolylineOptions): Route3DVec3[]
-```
+#### `toPolyline(options?: number | Route3DToPolylineOptions): Route3DVec3[]` — Sample this analytic route as a polyline for inspection or backend lowering.
 
 **`Route3DToPolylineOptions`**
 - `samples?: number` — Approximate target point count for the full route.
@@ -638,41 +394,17 @@ toPolyline(options?: number | Route3DToPolylineOptions): Route3DVec3[]
 
 **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.
+#### `pointAt(t: number): Vec3` — Evaluate the curve at parameter t ∈ [0, 1]. Uses De Boor's algorithm — exact, O(degree²).
 
-```ts
-sampleAdaptive(minCount?: number, maxCount?: number): Vec3[]
-```
+#### `tangentAt(t: number): Vec3` — Evaluate the unit tangent vector at parameter t ∈ [0, 1].
 
-#### `length()` — Approximate arc length by summing polyline segment lengths.
+#### `sample(count?: number): Vec3[]` — Sample the curve uniformly at `count` points.
 
-```ts
-length(samples?: number): number
-```
+#### `sampleAdaptive(minCount?: number, maxCount?: number): Vec3[]` — Sample with adaptive density — more points in high-curvature regions.
 
-#### `toPolyline()` — Convert to a format compatible with sweep() path input.
+#### `length(samples?: number): number` — Approximate arc length by summing polyline segment lengths.
 
-```ts
-toPolyline(samples?: number): Vec3[]
-```
+#### `toPolyline(samples?: number): Vec3[]` — Convert to a format compatible with sweep() path input.
 
 ### `NurbsSurface`
 
@@ -692,59 +424,31 @@ toPolyline(samples?: number): Vec3[]
 
 **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.
+#### `pointAt(u: number, v: number): Vec3` — Evaluate the surface at parameters (u, v) ∈ [0, 1]². Uses tensor product evaluation: evaluate basis functions in U and V independently.
 
-```ts
-normalAt(u: number, v: number): Vec3
-```
+#### `normalAt(u: number, v: number): Vec3` — Evaluate the surface normal at (u, v) via cross product of partial derivatives.
 
-#### `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[]; }
-```
+#### `tessellate(resU?: number, resV?: number): { positions: Vec3[]; normals: Vec3[]; indices: number[]; }` — Tessellate the surface into a triangle mesh. Returns positions, normals, and triangle indices.
 
 ### `PathBuilder`
 
 **Line Segments**
 
-#### `moveTo()` — Move the cursor to an absolute position without drawing a segment.
+#### `moveTo(x: number, y: number): this` — Move the cursor to an absolute position without drawing a segment.
 
 When called after the initial [`path()`](/docs/sketch#path), this establishes the start of the outline. Calling `moveTo` again mid-path starts a new sub-path (hole in `close()`, separate segment for [`stroke()`](/docs/sketch#stroke)).
 
-```ts
-moveTo(x: number, y: number): this
-```
-
-#### `lineTo()` — Draw a straight line from the current cursor to an absolute position.
+#### `lineTo(x: number, y: number): this` — Draw a straight line from the current cursor to an absolute position.
 
-```ts
-lineTo(x: number, y: number): this
-```
-
-#### `lineH()` — Draw a horizontal line segment by `dx` units from the current cursor.
+#### `lineH(dx: number): this` — Draw a horizontal line segment by `dx` units from the current cursor.
 
 Positive `dx` moves right; negative moves left.
 
-```ts
-lineH(dx: number): this
-```
-
-#### `lineV()` — Draw a vertical line segment by `dy` units from the current cursor.
+#### `lineV(dy: number): this` — Draw a vertical line segment by `dy` units from the current cursor.
 
 Positive `dy` moves up; negative moves down.
 
-```ts
-lineV(dy: number): this
-```
-
-#### `lineAngled()` — Draw a line at the given angle and length from the current cursor.
+#### `lineAngled(length: number, degrees: number): this` — Draw a line at the given angle and length from the current cursor.
 
 Angle convention: `0°` points right (+X), `90°` points up (+Y).
 
@@ -753,46 +457,26 @@ Angle convention: `0°` points right (+X), `90°` points up (+Y).
 path().moveTo(0, 0).lineH(50).lineV(-70).lineAngled(20, 235).stroke(4);
 ```
 
-```ts
-lineAngled(length: number, degrees: number): this
-```
-
 **Arcs**
 
-#### `arc()` — Draw an arc defined by center, radius, and angle range (no trig needed). If the path has no segments yet, automatically moves to the arc start. Positive sweep (startDeg < endDeg) = CCW, negative = CW.
+#### `arc(cx: number, cy: number, radius: number, startDeg: number, endDeg: number): this` — Draw an arc defined by center, radius, and angle range (no trig needed). If the path has no segments yet, automatically moves to the arc start. Positive sweep (startDeg < endDeg) = CCW, negative = CW.
 
 ```js
 // Arc centered at (10, 0), radius 50, from -30° to +30°
 path().arc(10, 0, 50, -30, 30).stroke(8, 'Round')
 ```
 
-```ts
-arc(cx: number, cy: number, radius: number, startDeg: number, endDeg: number): this
-```
-
-#### `arcTo()` — Draw a circular arc from the current position to (x, y) with the given radius. `clockwise=true` → arc curves to the right of the start→end direction. `clockwise=false` → arc curves to the left of the start→end direction.
-
-```ts
-arcTo(x: number, y: number, radius: number, clockwise?: boolean): this
-```
-
-#### `tangentArcTo()` — G1-continuous arc — radius derived from current tangent + endpoint. Throws if endpoint is collinear with current direction.
+#### `arcTo(x: number, y: number, radius: number, clockwise?: boolean): this` — Draw a circular arc from the current position to (x, y) with the given radius. `clockwise=true` → arc curves to the right of the start→end direction. `clockwise=false` → arc curves to the left of the start→end direction.
 
-```ts
-tangentArcTo(x: number, y: number): this
-```
+#### `tangentArcTo(x: number, y: number): this` — G1-continuous arc — radius derived from current tangent + endpoint. Throws if endpoint is collinear with current direction.
 
 **Curves**
 
-#### `bezierTo()` — Cubic bezier from current position to (x, y) via two control points.
-
-```ts
-bezierTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): this
-```
+#### `bezierTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): this` — Cubic bezier from current position to (x, y) via two control points.
 
 **Closing & Output**
 
-#### `close()` — Close the path and return a filled [`Sketch`](/docs/sketch#sketch).
+#### `close(): Sketch` — Close the path and return a filled [`Sketch`](/docs/sketch#sketch).
 
 The winding of the polygon is automatically corrected to CCW (the expected orientation for ForgeCAD sketches). If the path contains multiple sub-paths (started with subsequent `moveTo` calls), the first sub-path is the outer contour and subsequent sub-paths become holes subtracted from it.
 
@@ -807,21 +491,13 @@ const frame = path()
   // (hole would be added with another moveTo and line sequence before close)
 ```
 
-```ts
-close(): Sketch
-```
-
-#### `closeLabel()` — Label the closing segment and close the path. Shorthand for labeling the implicit line from the last point back to the start, then closing.
-
-```ts
-closeLabel(name: string): Sketch
-```
+#### `closeLabel(name: string): Sketch` — Label the closing segment and close the path. Shorthand for labeling the implicit line from the last point back to the start, then closing.
 
-#### [`stroke()`](/docs/sketch#stroke) — Thicken an open polyline (centerline) into a solid filled profile with uniform width.
+#### `stroke(width: number, join?: "Round" | "Square"): Sketch` — Thicken an open polyline (centerline) into a solid filled profile with uniform width.
 
 Expands the path into a closed profile `width` units wide (half-width on each side of the centerline). Use `'Round'` for ribs, wire traces, and organic profiles — it adds semicircular endcaps and rounds joins. Use `'Square'` (default) for sharp miter joins without endcaps.
 
-Not the same as rounding corners of a closed polygon — for mixed sharp-and-rounded outlines, build the polygon first and apply [`filletCorners()`](/docs/sketch#filletcorners).
+Not the same as rounding corners of a closed polygon — for mixed sharp-and-rounded outlines, build the polygon first and apply `.filletCorner([x, y], radius)` per corner.
 
 ```ts
 // Square-join L-bracket
@@ -836,51 +512,23 @@ const wire = stroke([[0, 0], [50, 0], [50, -70]], 4);
 
 and semicircular endcaps.
 
-```ts
-stroke(width: number, join?: "Round" | "Square"): Sketch
-```
-
-#### `label()` — Label the most recently added segment. Labels are born here and grow into face names when the sketch is extruded, lofted, swept, or revolved.
+#### `label(name: string): this` — Label the most recently added segment. Labels are born here and grow into face names when the sketch is extruded, lofted, swept, or revolved.
 
 Labels must be unique within a path. Each segment can have at most one label.
 
-```ts
-label(name: string): this
-```
-
 **Other**
 
-#### `getX()` — Current cursor X position.
-
-```ts
-getX(): number
-```
-
-#### `getY()` — Current cursor Y position.
+#### `getX(): number` — Current cursor X position.
 
-```ts
-getY(): number
-```
-
-#### `lineBy()` — Draw a line by a relative `(dx, dy)` displacement from the current cursor.
-
-```ts
-lineBy(dx: number, dy: number): this
-```
+#### `getY(): number` — Current cursor Y position.
 
-#### `arcBy()` — Draw an arc to a point offset from the current cursor.
-
-```ts
-arcBy(dx: number, dy: number, radius: number, clockwise?: boolean): this
-```
+#### `lineBy(dx: number, dy: number): this` — Draw a line by a relative `(dx, dy)` displacement from the current cursor.
 
-#### `bezierBy()` — Draw a cubic Bezier using control points relative to the current cursor.
+#### `arcBy(dx: number, dy: number, radius: number, clockwise?: boolean): this` — Draw an arc to a point offset from the current cursor.
 
-```ts
-bezierBy(dcp1x: number, dcp1y: number, dcp2x: number, dcp2y: number, dx: number, dy: number): this
-```
+#### `bezierBy(dcp1x: number, dcp1y: number, dcp2x: number, dcp2y: number, dx: number, dy: number): this` — Draw a cubic Bezier using control points relative to the current cursor.
 
-#### `arcAround()` — Arc around a known center point, sweeping by the given angle. Radius is derived from the distance between the current position and the center. Positive sweep = CCW (math convention), negative = CW.
+#### `arcAround(cx: number, cy: number, sweepDeg: number): this` — Arc around a known center point, sweeping by the given angle. Radius is derived from the distance between the current position and the center. Positive sweep = CCW (math convention), negative = CW.
 
 ```js
 // Arc 90° CCW around (50, 50)
@@ -889,11 +537,7 @@ path().moveTo(70, 50).arcAround(50, 50, 90)
 path().moveTo(10, 0).arcAround(0, 0, -45)
 ```
 
-```ts
-arcAround(cx: number, cy: number, sweepDeg: number): this
-```
-
-#### `arcAroundRelative()` — Arc around a center point given as an offset from the current position. `(dx, dy)` is the vector from the current point to the center. Positive sweep = CCW (math convention), negative = CW.
+#### `arcAroundRelative(dx: number, dy: number, sweepDeg: number): this` — Arc around a center point given as an offset from the current position. `(dx, dy)` is the vector from the current point to the center. Positive sweep = CCW (math convention), negative = CW.
 
 ```js
 // Arc 90° CCW around a center 20 units to the right
@@ -901,47 +545,23 @@ path().moveTo(50, 50).arcAroundRelative(20, 0, 90)
 // Equivalent to: path().moveTo(50, 50).arcAround(70, 50, 90)
 ```
 
-```ts
-arcAroundRelative(dx: number, dy: number, sweepDeg: number): this
-```
+#### `smoothCapTo(endX: number, endY: number, cornerRadius: number, capRadius: number): this` — Smooth three-arc end cap from the current position to (endX, endY). Inserts: small corner arc → large cap arc → small corner arc, all G1-continuous.
 
-#### `smoothCapTo()` — Smooth three-arc end cap from the current position to (endX, endY). Inserts: small corner arc → large cap arc → small corner arc, all G1-continuous.
+#### `tangentBezierTo(cp2x: number, cp2y: number, x: number, y: number, weight?: number): this` — G1-continuous cubic bezier — first control point is auto-derived from the current tangent direction. `weight` controls how far the auto-placed control point extends along the tangent (default: 1/3 of the chord).
 
-```ts
-smoothCapTo(endX: number, endY: number, cornerRadius: number, capRadius: number): this
-```
+The second control point `(cp2x, cp2y)` must be provided — it controls the arrival curvature. For a fully automatic smooth curve, see `smoothThrough`.
 
-#### `tangentBezierTo()` — G1-continuous cubic bezier — first control point is auto-derived from the current tangent direction. `weight` controls how far the auto-placed control point extends along the tangent (default: 1/3 of the chord).
+#### `smoothThrough(waypoints: Vec2[], tension?: number): this` — Catmull-Rom spline through a list of waypoints from the current position. The current position is included as the first point. The last waypoint becomes the new cursor position.
 
-The second control point `(cp2x, cp2y)` must be provided — it controls the arrival curvature. For a fully automatic smooth curve, see `smoothThrough`.
+#### `nurbsTo(controlPoints: Vec2[], opts?: { weights?: number[]; degree?: number; }): this` — Rational B-spline edge to (x, y) with explicit control points and weights.
 
-```ts
-tangentBezierTo(cp2x: number, cp2y: number, x: number, y: number, weight?: number): this
-```
+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.
 
-#### `smoothThrough()` — Catmull-Rom spline through a list of waypoints from the current position. The current position is included as the first point. The last waypoint becomes the new cursor position.
-
-```ts
-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.
+#### `exactArcTo(x: number, y: number, opts?: { radius?: number; clockwise?: boolean; }): this` — 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.
+#### `fillet(radius: number): this` — 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.
 
@@ -949,21 +569,13 @@ Must be called after at least two line/arc segments that form a corner. The fill
 path().moveTo(0,0).lineTo(10,0).lineTo(10,10).fillet(2).lineTo(0,10).close()
 ```
 
-```ts
-fillet(radius: number): this
-```
-
-#### [`chamfer()`](/docs/core#chamfer) — Chamfer the last corner with a straight cut of the given distance.
+#### `chamfer(distance: number): this` — Chamfer the last corner with a straight cut of the given distance.
 
 ```js
 path().moveTo(0,0).lineTo(10,0).lineTo(10,10).chamfer(2).lineTo(0,10).close()
 ```
 
-```ts
-chamfer(distance: number): this
-```
-
-#### `mirror()` — Mirror all existing segments across an axis and append the mirrored copy in reverse order, creating a symmetric path. The axis passes through the current cursor position.
+#### `mirror(axis: "x" | "y" | Vec2): this` — Mirror all existing segments across an axis and append the mirrored copy in reverse order, creating a symmetric path. The axis passes through the current cursor position.
 
 'y' mirrors across the local Y-axis (flips X), or `[nx, ny]` for an arbitrary axis direction.
 
@@ -972,11 +584,7 @@ chamfer(distance: number): this
 path().moveTo(0,0).lineTo(10,0).lineTo(10,5).mirror('x').close()
 ```
 
-```ts
-mirror(axis: "x" | "y" | [ number, number ]): this
-```
-
-#### `toPolyline()` — Return the open path as a sampled 2D polyline.
+#### `toPolyline(): Vec2[]` — Return the open path as a sampled 2D polyline.
 
 This is for construction geometry such as guide rails, measured centerlines, and curve-driven helpers where the authored path should stay open instead of becoming a filled sketch or stroked profile.
 
@@ -987,15 +595,7 @@ const rail = path()
   .toPolyline();
 ```
 
-```ts
-toPolyline(): [ number, number ][]
-```
-
-#### `closeOffset()` — Close the path and return an offset version of the filled Sketch. Positive delta expands outward, negative shrinks inward.
-
-```ts
-closeOffset(delta: number, join?: "Round" | "Square" | "Miter"): Sketch
-```
+#### `closeOffset(delta: number, join?: "Round" | "Square" | "Miter"): Sketch` — Close the path and return an offset version of the filled Sketch. Positive delta expands outward, negative shrinks inward.
 
 ### `ProductSkin`
 
@@ -1011,29 +611,13 @@ closeOffset(delta: number, join?: "Round" | "Square" | "Miter"): Sketch
 
 **Methods:**
 
-#### [`toShape()`](/docs/sdf#toshape) — Return the renderable shape generated for this product skin.
-
-```ts
-toShape(): Shape
-```
-
-#### `with()` — Create a group containing this skin plus named child details.
-
-```ts
-with(...children: GroupInput[]): ShapeGroup
-```
+#### `toShape(): Shape` — Return the renderable shape generated for this product skin.
 
-#### `integrate()` — Boolean-union structural details into the skin body.
-
-```ts
-integrate(...details: Shape[]): Shape
-```
+#### `with(...children: GroupInput[]): ShapeGroup` — Create a group containing this skin plus named child details.
 
-#### `uv()` — Create a side/u/v surface-ref query on this skin.
+#### `integrate(...details: Shape[]): Shape` — Boolean-union structural details into the skin body.
 
-```ts
-uv(side: ProductSkinSide, u?: number, v?: number): ProductSkinRefQuery
-```
+#### `uv(side: ProductSkinSide, u?: number, v?: number): ProductSkinRefQuery` — Create a side/u/v surface-ref query on this skin.
 
 **`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
 
@@ -1048,41 +632,21 @@ uv(side: ProductSkinSide, u?: number, v?: number): ProductSkinRefQuery
 | `v?` | `number` | Along-axis parameter, 0 at the first cap and 1 at the rear/back cap. Defaults to 0.5. |
 | `offset?` | `number` | Positive distance away from the surface along the resolved normal. |
 
-#### `ref()` — Resolve a named ref published with Product.skin().refs(...).
-
-```ts
-ref(name: string): ProductSurfaceRef
-```
+#### `ref(name: string): ProductSurfaceRef` — Resolve a named ref published with Product.skin().refs(...).
 
-#### `curveOnSurface()` — Create a sampled curve as a sequence of surface refs on this skin.
-
-```ts
-curveOnSurface(name: string, points: Array<Partial<ProductSkinRefQuery> & { side: ProductSkinSide; }>): ProductSurfaceRef[]
-```
+#### `curveOnSurface(name: string, points: Array<Partial<ProductSkinRefQuery> & { side: ProductSkinSide; }>): ProductSurfaceRef[]` — Create a sampled curve as a sequence of surface refs on this skin.
 
-#### `surface()` — Create a fluent surface helper for refs and conformal features on one side of this skin.
+#### `surface(side: ProductSkinSide): ProductSurfaceBuilder` — Create a fluent surface helper for refs and conformal features on one side of this skin.
 
 Use this when several refs or ribbons share the same skin side; side-local helpers keep path points concise and make it harder to mix sides accidentally.
 
-```ts
-surface(side: ProductSkinSide): ProductSurfaceBuilder
-```
-
-#### `stationAt()` — Interpolate center, width, and depth at a normalized v or absolute axis value.
-
-```ts
-stationAt(vOrAxis: number): { ... }
-```
+#### `stationAt(vOrAxis: number): { ... }` — Interpolate center, width, and depth at a normalized v or absolute axis value.
 
 **`ProductProfileKind`**
 
 `"oval" | "roundedRect" | "circle" | "superEllipse" | "custom"`
 
-#### `frame()` — Build a local surface frame from a side/u/v query.
-
-```ts
-frame(query: ProductSkinRefQuery): ProductSurfaceFrame
-```
+#### `frame(query: ProductSkinRefQuery): ProductSurfaceFrame` — Build a local surface frame from a side/u/v query.
 
 `ProductSurfaceFrame`: `{ point: Vec3, normal: Vec3, tangentU: Vec3, tangentV: Vec3, matrix: Mat4, skin: string }`
 
@@ -1092,35 +656,19 @@ frame(query: ProductSkinRefQuery): ProductSurfaceFrame
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `name` | `string | undefined` | — |
+| `name` | `string \| undefined` | — |
 
 **Methods:**
 
-#### `frame()` — Resolve this semantic surface ref into a point, normal, tangents, and placement matrix.
-
-```ts
-frame(overrides?: Partial<ProductSkinRefQuery>): ProductSurfaceFrame
-```
-
-#### `with()` — Return a copy of this ref with side/u/v/offset overrides.
-
-```ts
-with(overrides: Partial<ProductSkinRefQuery>): ProductSurfaceRef
-```
+#### `frame(overrides?: Partial<ProductSkinRefQuery>): ProductSurfaceFrame` — Resolve this semantic surface ref into a point, normal, tangents, and placement matrix.
 
-#### `attach()` — Place a detail shape or group on this ref's local surface frame.
+#### `with(overrides: Partial<ProductSkinRefQuery>): ProductSurfaceRef` — Return a copy of this ref with side/u/v/offset overrides.
 
-```ts
-attach(detail: Shape | ShapeGroup, options?: ProductAttachOptions): Shape | ShapeGroup
-```
+#### `attach(detail: Shape | ShapeGroup, options?: ProductAttachOptions): Shape | ShapeGroup` — Place a detail shape or group on this ref's local surface frame.
 
 `ProductAttachOptions`: `{ offset?: number, inset?: number }`
 
-#### `querySpec()` — Return the serializable side/u/v query behind this ref.
-
-```ts
-querySpec(): ProductSkinRefQuery
-```
+#### `querySpec(): ProductSkinRefQuery` — Return the serializable side/u/v query behind this ref.
 
 ### `ProductSurfaceBuilder`
 
@@ -1134,32 +682,16 @@ Fluent helper bound to one ProductSkin side for refs and side-local conformal fe
 
 **Methods:**
 
-#### `ref()` — Create a ref on this skin side.
-
-```ts
-ref(u?: number, v?: number, offset?: number): ProductSurfaceRef
-```
-
-#### `uv()` — Create a side/u/v query on this skin side.
-
-```ts
-uv(u?: number, v?: number, offset?: number): ProductSkinRefQuery
-```
+#### `ref(u?: number, v?: number, offset?: number): ProductSurfaceRef` — Create a ref on this skin side.
 
-#### `frame()` — Resolve a point/frame on this surface using the builder's side.
+#### `uv(u?: number, v?: number, offset?: number): ProductSkinRefQuery` — Create a side/u/v query on this skin side.
 
-```ts
-frame(query?: Partial<ProductSkinRefQuery>): ProductSurfaceFrame
-```
+#### `frame(query?: Partial<ProductSkinRefQuery>): ProductSurfaceFrame` — Resolve a point/frame on this surface using the builder's side.
 
-#### `ribbon()` — Start a conformal ribbon on this skin side.
+#### `ribbon(name: string, points: ProductSurfacePathPoint[], options?: ProductRibbonBuildOptions): ProductRibbonBuilder` — Start a conformal ribbon on this skin side.
 
 Path points use side-local `u`/`v` coordinates; this builder supplies the side. The returned ProductRibbonBuilder is already bound to the source skin and can be further configured before build(). Use `widthSamples` >= 3 when the ribbon must visibly wrap over curved product sections instead of behaving like a flat strip.
 
-```ts
-ribbon(name: string, points: ProductSurfacePathPoint[], options?: ProductRibbonBuildOptions): ProductRibbonBuilder
-```
-
 **`ProductSurfacePathPoint`** — Side-local path point for Product.surface(side).ribbon(...); the surface helper supplies `side`.
 - `u?: number` — Across-side parameter on the bound side. Defaults to 0.5.
 - `v?: number` — Along-axis parameter, 0 at the first cap and 1 at the rear/back cap. Defaults to 0.5.
@@ -1180,24 +712,7 @@ ribbon(name: string, points: ProductSurfacePathPoint[], options?: ProductRibbonB
 
 `ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
 
-**`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). |
+`ShapeMaterialProps` — defined in [core](/docs/core).
 
 ### `ProductSkinBuilder`
 
@@ -1209,31 +724,19 @@ ribbon(name: string, points: ProductSurfacePathPoint[], options?: ProductRibbonB
 
 **Methods:**
 
-#### `axis()` — Choose the primary station axis for the skin loft.
-
-```ts
-axis(axis: ProductSkinAxis): this
-```
+#### `axis(axis: ProductSkinAxis): this` — Choose the primary station axis for the skin loft.
 
 **`ProductSkinAxis`** — Primary world axis used to order ProductSkin loft stations.
 
 `"X" | "Y" | "Z"`
 
-#### `stations()` — Set named cross-section stations for the product skin.
-
-```ts
-stations(stations: Array<ProductStationBuilder | ProductStationSpec>): this
-```
+#### `stations(stations: Array<ProductStationBuilder | ProductStationSpec>): this` — Set named cross-section stations for the product skin.
 
 `ProductStationSpec`: `{ name: string, center: Vec3, profile: ProductStationProfile, crown?: number }`
 
 `ProductStationProfile`: `{ sketch: Sketch, width: number, depth: number, kind: ProductProfileKind, radius?: number, exponent?: number }`
 
-#### `rails()` — Attach named guide rails for product-skin construction and downstream surface references.
-
-```ts
-rails(rails: Record<string, ProductRailSpec>): this
-```
+#### `rails(rails: Record<string, ProductRailSpec>): this` — Attach named guide rails for product-skin construction and downstream surface references.
 
 `ProductRailSpec`: `{ kind: ProductRailKind, points: Vec3[], degree?: number, name?: string }`
 
@@ -1241,53 +744,21 @@ rails(rails: Record<string, ProductRailSpec>): this
 
 `"bezier" | "nurbs" | "polyline"`
 
-#### `ref()` — Publish a named semantic surface ref on the skin.
-
-```ts
-ref(name: string, query: ProductSkinRefQuery): this
-```
-
-#### `refs()` — Publish multiple named semantic surface refs on the skin.
-
-```ts
-refs(refs: Record<string, ProductSkinRefQuery>): this
-```
-
-#### `uv()` — Create a side/u/v surface-ref query for use in refs(...) or Product.ref(...).
-
-```ts
-uv(side: ProductSkinSide, u?: number, v?: number): ProductSkinRefQuery
-```
-
-#### `material()` — Apply a product material preset to the lowered skin.
-
-```ts
-material(material: ProductMaterial): this
-```
-
-#### `color()` — Apply a simple color override to the lowered skin.
+#### `ref(name: string, query: ProductSkinRefQuery): this` — Publish a named semantic surface ref on the skin.
 
-```ts
-color(color: string): this
-```
+#### `refs(refs: Record<string, ProductSkinRefQuery>): this` — Publish multiple named semantic surface refs on the skin.
 
-#### `edgeLength()` — Set the sampled loft target edge length.
+#### `uv(side: ProductSkinSide, u?: number, v?: number): ProductSkinRefQuery` — Create a side/u/v surface-ref query for use in refs(...) or Product.ref(...).
 
-```ts
-edgeLength(value: number): this
-```
+#### `material(material: ProductMaterial): this` — Apply a product material preset to the lowered skin.
 
-#### `wall()` — Record intended wall thickness for product design metadata. Use explicit shelling when the model needs real inner-wall geometry.
+#### `color(color: string): this` — Apply a simple color override to the lowered skin.
 
-```ts
-wall(thickness: number): this
-```
+#### `edgeLength(value: number): this` — Set the sampled loft target edge length.
 
-#### `build()` — Lower stations and refs into a ProductSkin body.
+#### `wall(thickness: number): this` — Record intended wall thickness for product design metadata. Use explicit shelling when the model needs real inner-wall geometry.
 
-```ts
-build(): ProductSkin
-```
+#### `build(): ProductSkin` — Lower stations and refs into a ProductSkin body.
 
 ### `ProductStationBuilder`
 
@@ -1299,73 +770,29 @@ build(): ProductSkin
 
 **Methods:**
 
-#### `at()` — Position this station in world coordinates.
-
-```ts
-at(point: Vec3): this
-```
-
-#### `z()` — Convenience for traditional Z-up section stacks.
-
-```ts
-z(z: number): this
-```
-
-#### `y()` — Convenience for product bodies running front-to-back along Y.
-
-```ts
-y(y: number): this
-```
-
-#### `x()` — Convenience for product bodies running left-to-right along X.
+#### `at(point: Vec3): this` — Position this station in world coordinates.
 
-```ts
-x(x: number): this
-```
+#### `z(z: number): this` — Convenience for traditional Z-up section stacks.
 
-#### `oval()` — Use an oval cross-section with full width and depth dimensions.
+#### `y(y: number): this` — Convenience for product bodies running front-to-back along Y.
 
-```ts
-oval(width: number, depth: number, options?: { segments?: number; }): this
-```
+#### `x(x: number): this` — Convenience for product bodies running left-to-right along X.
 
-#### `superEllipse()` — Use a superellipse cross-section for soft-square product surfaces.
+#### `oval(width: number, depth: number, options?: { segments?: number; }): this` — Use an oval cross-section with full width and depth dimensions.
 
-```ts
-superEllipse(width: number, depth: number, options?: ProductStationSuperEllipseOptions): this
-```
+#### `superEllipse(width: number, depth: number, options?: ProductStationSuperEllipseOptions): this` — Use a superellipse cross-section for soft-square product surfaces.
 
 `ProductStationSuperEllipseOptions`: `{ segments?: number, exponent?: number }`
 
-#### [`roundedRect()`](/docs/sketch#roundedrect) — Use a rounded-rectangle cross-section with the given corner radius.
-
-```ts
-roundedRect(width: number, depth: number, radius: number): this
-```
-
-#### [`circle()`](/docs/sketch#circle) — Use a circular cross-section from a full diameter.
+#### `roundedRect(width: number, depth: number, radius: number): this` — Use a rounded-rectangle cross-section with the given corner radius.
 
-```ts
-circle(diameter: number, options?: { segments?: number; }): this
-```
-
-#### `custom()` — Use a custom 2D sketch as the station cross-section.
-
-```ts
-custom(sketch: Sketch, width: number, depth: number): this
-```
+#### `circle(diameter: number, options?: { segments?: number; }): this` — Use a circular cross-section from a full diameter.
 
-#### `crown()` — Set the station crown amount for soft product-section intent.
-
-```ts
-crown(amount: number): this
-```
+#### `custom(sketch: Sketch, width: number, depth: number): this` — Use a custom 2D sketch as the station cross-section.
 
-#### `toSpec()` — Return the immutable station spec consumed by Product.skin().
+#### `crown(amount: number): this` — Set the station crown amount for soft product-section intent.
 
-```ts
-toSpec(): ProductStationSpec
-```
+#### `toSpec(): ProductStationSpec` — Return the immutable station spec consumed by Product.skin().
 
 ### `ProductPanelBuilder`
 
@@ -1377,53 +804,21 @@ toSpec(): ProductStationSpec
 
 **Methods:**
 
-#### `rounded()` — Use a rounded rectangle panel profile.
-
-```ts
-rounded(width: number, height: number, radius?: number): this
-```
-
-#### `oval()` — Use an oval panel profile.
-
-```ts
-oval(width: number, height: number): this
-```
-
-#### `profile()` — Use a custom 2D panel profile.
-
-```ts
-profile(profile: Sketch): this
-```
-
-#### `thickness()` — Set panel extrusion thickness.
-
-```ts
-thickness(thickness: number): this
-```
+#### `rounded(width: number, height: number, radius?: number): this` — Use a rounded rectangle panel profile.
 
-#### `material()` — Apply a product material preset to the panel.
-
-```ts
-material(material: ProductMaterial): this
-```
+#### `oval(width: number, height: number): this` — Use an oval panel profile.
 
-#### `color()` — Apply a simple color override to the panel.
+#### `profile(profile: Sketch): this` — Use a custom 2D panel profile.
 
-```ts
-color(color: string): this
-```
+#### `thickness(thickness: number): this` — Set panel extrusion thickness.
 
-#### `build()` — Build the panel in local coordinates.
+#### `material(material: ProductMaterial): this` — Apply a product material preset to the panel.
 
-```ts
-build(): Shape
-```
+#### `color(color: string): this` — Apply a simple color override to the panel.
 
-#### `attachTo()` — Build and attach this panel to a ProductSurfaceRef.
+#### `build(): Shape` — Build the panel in local coordinates.
 
-```ts
-attachTo(ref: ProductRefInput, options?: ProductPanelAttachOptions): Shape
-```
+#### `attachTo(ref: ProductRefInput, options?: ProductPanelAttachOptions): Shape` — Build and attach this panel to a ProductSurfaceRef.
 
 **`ProductRefInput`**
 
@@ -1443,691 +838,188 @@ Builder for thin trim, label, grip, and split-line features that bend with a Pro
 
 **Methods:**
 
-#### `on()` — Follow a ProductSkin with side/u/v path queries or refs.
+#### `on(skin: ProductSkin, points: ProductRibbonPathPoint[], options?: ProductRibbonBuildOptions): this` — Follow a ProductSkin with side/u/v path queries or refs.
 
 This is the highest-fidelity mode because every interpolated sample is resolved through ProductSkin.frame(), so the ribbon bends along the selected side as station width/depth changes. All query path points must stay on one side; split side transitions into separate ribbons.
 
-```ts
-on(skin: ProductSkin, points: ProductRibbonPathPoint[], options?: ProductRibbonBuildOptions): this
-```
-
 **`ProductRibbonPathPoint`** — Path point for Product.ribbon().on(...): either a side/u/v query or a resolved surface ref.
 
 `ProductSkinRefQuery | ProductSurfaceRef`
 
-#### `fromRefs()` — Follow explicit surface refs.
+#### `fromRefs(points: ProductSurfaceRef[], options?: ProductRibbonBuildOptions): this` — Follow explicit surface refs.
 
 Useful for named refs or paths assembled elsewhere. The builder resolves each ref frame and interpolates between those frames; use on(skin, points) when you need full skin-side sampling between sparse control points.
 
-```ts
-fromRefs(points: ProductSurfaceRef[], options?: ProductRibbonBuildOptions): this
-```
+#### `width(width: number): this` — Set ribbon width in millimeters.
 
-#### `width()` — Set ribbon width in millimeters.
+#### `thickness(thickness: number): this` — Set solid thickness outward from the source surface in millimeters.
 
-```ts
-width(width: number): this
-```
+#### `offset(offset: number): this` — Set positive clearance between the source surface and the ribbon's inner face.
 
-#### `thickness()` — Set solid thickness outward from the source surface in millimeters.
+#### `samples(samples: number): this` — Set samples along the path.
 
-```ts
-thickness(thickness: number): this
-```
+#### `widthSamples(samples: number): this` — Set samples across the width. Use 3+ to bend over curved cross-sections.
 
-#### `offset()` — Set positive clearance between the source surface and the ribbon's inner face.
+#### `resolution(resolution: number): this` — Set NURBS tessellation resolution.
 
-```ts
-offset(offset: number): this
-```
+#### `material(material: ProductMaterial): this` — Apply a product material preset.
 
-#### `samples()` — Set samples along the path.
+#### `color(color: string): this` — Apply a simple color override.
 
-```ts
-samples(samples: number): this
-```
+#### `build(options?: ProductRibbonBuildOptions): Shape` — Build a conformal ribbon as a thin NURBS surface solid.
 
-#### `widthSamples()` — Set samples across the width. Use 3+ to bend over curved cross-sections.
+### `CylinderCarrier`
 
-```ts
-widthSamples(samples: number): this
-```
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | — |
+| `kind` | `"cylinder"` | — |
 
-#### `resolution()` — Set NURBS tessellation resolution.
+**Methods:**
 
-```ts
-resolution(resolution: number): this
-```
+- `diameter(value: number): this`
+- `radius(value: number): this`
+- `height(value: number): this`
+- `clearance(value: number): this`
+- `center(point: Vec3): this`
+- `path(): SurfacePathBuilder<CylinderSurfaceCoordinate>`
+- `anchor(angle: number, z?: number, options?: { offset?: number; }): SurfaceAnchor<CylinderSurfaceCoordinate>`
+- `front(options?: { z?: number; offset?: number; }): SurfaceAnchor<CylinderSurfaceCoordinate>`
+- `back(options?: { z?: number; offset?: number; }): SurfaceAnchor<CylinderSurfaceCoordinate>`
+- `left(options?: { z?: number; offset?: number; }): SurfaceAnchor<CylinderSurfaceCoordinate>`
+- `right(options?: { z?: number; offset?: number; }): SurfaceAnchor<CylinderSurfaceCoordinate>`
+- `top(options?: { angle?: number; offset?: number; }): SurfaceAnchor<CylinderSurfaceCoordinate>`
+- `bottom(options?: { angle?: number; offset?: number; }): SurfaceAnchor<CylinderSurfaceCoordinate>`
+- `pointAt(coordinate: CylinderSurfaceCoordinate): Vec3`
+- `mirrorPoint(point: Vec3): Vec3`
+- `normalAt(coordinate: CylinderSurfaceCoordinate): Vec3`
+- `tangentAt(coordinate: CylinderSurfaceCoordinate, tangentHint?: Vec3): Vec3`
+- `frameAt(coordinate: CylinderSurfaceCoordinate, tangentHint?: Vec3): SurfaceFrame`
+- `bounds(): SurfaceBounds`
+- `offset(distance: number): CylinderCarrier`
+- `mirrorCoordinate(coordinate: CylinderSurfaceCoordinate): CylinderSurfaceCoordinate`
+- `radiusValueWithClearance(): number`
 
-#### `material()` — Apply a product material preset.
+`CylinderSurfaceCoordinate`: `{ kind?: "cylinder", angle: number, z: number, offset?: number }`
 
-```ts
-material(material: ProductMaterial): this
-```
+### `PlaneCarrier`
 
-#### `color()` — Apply a simple color override.
+**Properties:**
 
-```ts
-color(color: string): this
-```
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | — |
+| `kind` | `"plane"` | — |
+
+**Methods:**
 
-#### `build()` — Build a conformal ribbon as a thin NURBS surface solid.
+- `size(width: number, height: number): this`
+- `origin(point: Vec3): this`
+- `normal(normal: Vec3): this`
+- `path(): SurfacePathBuilder<PlaneSurfaceCoordinate>`
+- `anchor(x?: number, y?: number, options?: { offset?: number; }): SurfaceAnchor<PlaneSurfaceCoordinate>`
+- `left(options?: { y?: number; offset?: number; }): SurfaceAnchor<PlaneSurfaceCoordinate>`
+- `right(options?: { y?: number; offset?: number; }): SurfaceAnchor<PlaneSurfaceCoordinate>`
+- `top(options?: { x?: number; offset?: number; }): SurfaceAnchor<PlaneSurfaceCoordinate>`
+- `bottom(options?: { x?: number; offset?: number; }): SurfaceAnchor<PlaneSurfaceCoordinate>`
+- `pointAt(coordinate: PlaneSurfaceCoordinate): Vec3`
+- `mirrorPoint(point: Vec3): Vec3`
+- `normalAt(): Vec3`
+- `tangentAt(coordinate: PlaneSurfaceCoordinate, tangentHint?: Vec3): Vec3`
+- `frameAt(coordinate: PlaneSurfaceCoordinate, tangentHint?: Vec3): SurfaceFrame`
+- `bounds(): SurfaceBounds`
+- `offset(distance: number): PlaneCarrier`
+- `mirrorCoordinate(coordinate: PlaneSurfaceCoordinate): PlaneSurfaceCoordinate`
 
-```ts
-build(options?: ProductRibbonBuildOptions): Shape
-```
+`PlaneSurfaceCoordinate`: `{ kind?: "plane", x: number, y: number, offset?: number }`
 
-### `ProductSpoutBuilder`
+### `ProductSkinCarrier`
 
 **Properties:**
 
 | Property | Type | Description |
 |----------|------|-------------|
+| `skin` | `ProductSkin` | — |
 | `name` | `string` | — |
+| `kind` | `"productSkin"` | — |
 
 **Methods:**
 
-#### `from()` — Set the skin ref this spout projects from.
-
-```ts
-from(ref: ProductSurfaceRef): this
-```
+#### `sideTransition(fromSide: ProductSkinSide, toSide: ProductSkinSide, input?: ProductSkinSideTransitionInput): ProductSkinSideTransition` — Return matching side-local coordinates for an explicit split-member transition.
 
-#### `sections()` — Set local spout section profiles from root to mouth.
-
-```ts
-sections(sections: Array<Sketch | ProductStationBuilder | ProductStationSpec>): this
-```
+Each SurfacePath still stays on one ProductSkin side. Use this helper to create one member ending on `from`, another starting on `to`, then join named anchors.
 
-#### `projection()` — Set the projection length along the source ref normal.
+Rules: only adjacent `left`/`top`/`right`/`bottom` sides are supported — for front/rear caps use `Product.panel()`. `v` is normalized 0–1 along the shared boundary (default 0.5); `name` must be non-empty when provided; `offset` lifts both coordinates off the surface. Throws if the returned boundary coordinates are not physically coincident — check side order, `v`, and `offset`.
 
-```ts
-projection(length: number): this
-```
+`ProductSkinSideTransitionInput`: `{ name?: string, v?: number, offset?: number }`
 
-#### `edgeLength()` — Set the sampled loft target edge length for the spout.
+`ProductSkinSideTransition`: `{ name?: string, from: ProductSkinSurfaceCoordinate, to: ProductSkinSurfaceCoordinate }`
 
-```ts
-edgeLength(value: number): this
-```
+`ProductSkinSurfaceCoordinate`: `{ kind?: "productSkin", side?: ProductSkinSide, u?: number, v?: number, offset?: number }`
 
-#### `material()` — Apply a product material preset to the spout.
+#### `sideTransitionChain(sides: ProductSkinSide[], input?: ProductSkinSideTransitionInput): ProductSkinSideTransition[]` — Return a sequence of matching side-local coordinates for an explicit multi-side split-member route.
 
-```ts
-material(material: ProductMaterial): this
-```
+Each adjacent side pair becomes one named transition. Build one member per side segment, add transition anchors at each returned pair, then join the anchors. The same validation as `sideTransition()` applies to every adjacent pair.
 
-#### `color()` — Apply a simple color override to the spout.
+#### `sideRoute(input: ProductSkinSideRouteInput): ProductSkinSideRoute` — Return side-local member segments for a generated multi-side split-member route.
 
-```ts
-color(color: string): this
-```
+The route still compiles as explicit members plus named-anchor joins. This helper only generates the per-side segment endpoints and transition names.
 
-#### `build()` — Build the spout in local coordinates.
+**`ProductSkinSideRouteInput`**: `name?: string`, `sides: ProductSkinSide[]`, `from: ProductSkinSurfaceCoordinate`, `to: ProductSkinSurfaceCoordinate`, `v?: number`, `offset?: number`
 
-```ts
-build(): Shape
-```
+`ProductSkinSideRoute`: `{ name?: string, transitions: ProductSkinSideTransition[], segments: ProductSkinSideRouteSegment[] }`
 
-#### `attach()` — Build and place the spout on its source ref.
+**`ProductSkinSideRouteSegment`**: `name: string`, `side: ProductSkinSide`, `from: ProductSkinSurfaceCoordinate`, `to: ProductSkinSurfaceCoordinate`, `startAnchorName?: string`, `endAnchorName?: string`
 
-```ts
-attach(options?: ProductAttachOptions): Shape
-```
+- `surface(side: ProductSkinSide): ProductSkinCarrier`
+- `path(): SurfacePathBuilder<ProductSkinSurfaceCoordinate>`
+- `pointAt(coordinate: ProductSkinSurfaceCoordinate): Vec3`
+- `mirrorPoint(point: Vec3): Vec3`
+- `normalAt(coordinate: ProductSkinSurfaceCoordinate): Vec3`
+- `tangentAt(coordinate: ProductSkinSurfaceCoordinate, tangentHint?: Vec3): Vec3`
+- `frameAt(coordinate: ProductSkinSurfaceCoordinate, tangentHint?: Vec3): SurfaceFrame`
+- `bounds(): SurfaceBounds`
+- `offset(distance: number): ProductSkinCarrier`
+- `mirrorCoordinate(coordinate: ProductSkinSurfaceCoordinate): ProductSkinSurfaceCoordinate`
 
-### `ProductHandleBuilder`
+### `SurfacePath`
 
 **Properties:**
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `name` | `string` | — |
+| `carrier` | `CarrierSurface<C>` | — |
+| `points` | `C[]` | — |
+| `closedValue` | `boolean` | — |
 
 **Methods:**
 
-#### `between()` — Set the upper body ref and lower world anchor for the handle.
+- `closed(): SurfacePath<C>`
+- `mirror(): SurfacePath<C>`
+- `coordinateAt(t: number): C`
+- `sample(count?: number): SurfacePathSample<C>[]`
+- `length(samples?: number): number`
 
-```ts
-between(upper: ProductSurfaceRef, lower: Vec3): this
-```
+### `SurfacePathBuilder`
 
-#### `spine()` — Set an explicit handle centerline from points or a rail spec.
+**Properties:**
 
-```ts
-spine(points: Vec3[] | ProductRailSpec): this
-```
+| Property | Type | Description |
+|----------|------|-------------|
+| `carrier` | `CarrierSurface<C>` | — |
 
-#### `grip()` — Set the grip cross-section profile.
+**Methods:**
 
-```ts
-grip(profile: Sketch): this
-```
-
-#### `material()` — Apply a product material preset to the grip.
-
-```ts
-material(material: ProductMaterial): this
-```
-
-#### `padMaterial()` — Apply a product material preset to handle landing pads.
-
-```ts
-padMaterial(material: ProductMaterial): this
-```
-
-#### `edgeLength()` — Set the sampled loft target edge length for the grip.
-
-```ts
-edgeLength(value: number): this
-```
-
-#### `build()` — Build the handle grip and landing pads.
-
-```ts
-build(): ProductHandleFeature
-```
-
-### `ProductHandleFeature`
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `grip` | `Shape` | — |
-| `upperPad` | `Shape` | — |
-| `lowerPad` | `Shape` | — |
-
-**Methods:**
-
-#### `structural()` — Return the physical shapes that make up this handle feature.
-
-```ts
-structural(): Shape[]
-```
-
-#### [`toShape()`](/docs/sdf#toshape) — Boolean-union the handle feature into a single shape.
-
-```ts
-toShape(): Shape
-```
-
-#### `toGroup()` — Return the handle as a named ShapeGroup preserving child colors.
-
-```ts
-toGroup(): ShapeGroup
-```
-
-### `CylinderCarrier`
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | `string` | — |
-| `kind` | `"cylinder"` | — |
-
-**Methods:**
-
-#### `diameter()`
-
-```ts
-diameter(value: number): this
-```
-
-#### `radius()`
-
-```ts
-radius(value: number): this
-```
-
-#### `height()`
-
-```ts
-height(value: number): this
-```
-
-#### `clearance()`
-
-```ts
-clearance(value: number): this
-```
-
-#### `center()`
-
-```ts
-center(point: Vec3): this
-```
-
-#### [`path()`](/docs/sketch#path)
-
-```ts
-path(): SurfacePathBuilder<CylinderSurfaceCoordinate>
-```
-
-#### `anchor()`
-
-```ts
-anchor(angle: number, z?: number, options?: { offset?: number; }): SurfaceAnchor<CylinderSurfaceCoordinate>
-```
-
-#### `front()`
-
-```ts
-front(options?: { z?: number; offset?: number; }): SurfaceAnchor<CylinderSurfaceCoordinate>
-```
-
-#### `back()`
-
-```ts
-back(options?: { z?: number; offset?: number; }): SurfaceAnchor<CylinderSurfaceCoordinate>
-```
-
-#### `left()`
-
-```ts
-left(options?: { z?: number; offset?: number; }): SurfaceAnchor<CylinderSurfaceCoordinate>
-```
-
-#### `right()`
-
-```ts
-right(options?: { z?: number; offset?: number; }): SurfaceAnchor<CylinderSurfaceCoordinate>
-```
-
-#### `top()`
-
-```ts
-top(options?: { angle?: number; offset?: number; }): SurfaceAnchor<CylinderSurfaceCoordinate>
-```
-
-#### `bottom()`
-
-```ts
-bottom(options?: { angle?: number; offset?: number; }): SurfaceAnchor<CylinderSurfaceCoordinate>
-```
-
-#### `pointAt()`
-
-```ts
-pointAt(coordinate: CylinderSurfaceCoordinate): Vec3
-```
-
-`CylinderSurfaceCoordinate`: `{ kind?: "cylinder", angle: number, z: number, offset?: number }`
-
-#### `mirrorPoint()`
-
-```ts
-mirrorPoint(point: Vec3): Vec3
-```
-
-#### `normalAt()`
-
-```ts
-normalAt(coordinate: CylinderSurfaceCoordinate): Vec3
-```
-
-#### `tangentAt()`
-
-```ts
-tangentAt(coordinate: CylinderSurfaceCoordinate, tangentHint?: Vec3): Vec3
-```
-
-#### `frameAt()`
-
-```ts
-frameAt(coordinate: CylinderSurfaceCoordinate, tangentHint?: Vec3): SurfaceFrame
-```
-
-#### `bounds()`
-
-```ts
-bounds(): SurfaceBounds
-```
-
-#### `offset()`
-
-```ts
-offset(distance: number): CylinderCarrier
-```
-
-#### `mirrorCoordinate()`
-
-```ts
-mirrorCoordinate(coordinate: CylinderSurfaceCoordinate): CylinderSurfaceCoordinate
-```
-
-#### `radiusValueWithClearance()`
-
-```ts
-radiusValueWithClearance(): number
-```
-
-### `PlaneCarrier`
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | `string` | — |
-| `kind` | `"plane"` | — |
-
-**Methods:**
-
-#### `size()`
-
-```ts
-size(width: number, height: number): this
-```
-
-#### `origin()`
-
-```ts
-origin(point: Vec3): this
-```
-
-#### `normal()`
-
-```ts
-normal(normal: Vec3): this
-```
-
-#### [`path()`](/docs/sketch#path)
-
-```ts
-path(): SurfacePathBuilder<PlaneSurfaceCoordinate>
-```
-
-#### `anchor()`
-
-```ts
-anchor(x?: number, y?: number, options?: { offset?: number; }): SurfaceAnchor<PlaneSurfaceCoordinate>
-```
-
-#### `left()`
-
-```ts
-left(options?: { y?: number; offset?: number; }): SurfaceAnchor<PlaneSurfaceCoordinate>
-```
-
-#### `right()`
-
-```ts
-right(options?: { y?: number; offset?: number; }): SurfaceAnchor<PlaneSurfaceCoordinate>
-```
-
-#### `top()`
-
-```ts
-top(options?: { x?: number; offset?: number; }): SurfaceAnchor<PlaneSurfaceCoordinate>
-```
-
-#### `bottom()`
-
-```ts
-bottom(options?: { x?: number; offset?: number; }): SurfaceAnchor<PlaneSurfaceCoordinate>
-```
-
-#### `pointAt()`
-
-```ts
-pointAt(coordinate: PlaneSurfaceCoordinate): Vec3
-```
-
-`PlaneSurfaceCoordinate`: `{ kind?: "plane", x: number, y: number, offset?: number }`
-
-#### `mirrorPoint()`
-
-```ts
-mirrorPoint(point: Vec3): Vec3
-```
-
-#### `normalAt()`
-
-```ts
-normalAt(): Vec3
-```
-
-#### `tangentAt()`
-
-```ts
-tangentAt(coordinate: PlaneSurfaceCoordinate, tangentHint?: Vec3): Vec3
-```
-
-#### `frameAt()`
-
-```ts
-frameAt(coordinate: PlaneSurfaceCoordinate, tangentHint?: Vec3): SurfaceFrame
-```
-
-#### `bounds()`
-
-```ts
-bounds(): SurfaceBounds
-```
-
-#### `offset()`
-
-```ts
-offset(distance: number): PlaneCarrier
-```
-
-#### `mirrorCoordinate()`
-
-```ts
-mirrorCoordinate(coordinate: PlaneSurfaceCoordinate): PlaneSurfaceCoordinate
-```
-
-### `ProductSkinCarrier`
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `skin` | `ProductSkin` | — |
-| `name` | `string` | — |
-| `kind` | `"productSkin"` | — |
-
-**Methods:**
-
-#### `surface()`
-
-```ts
-surface(side: ProductSkinSide): ProductSkinCarrier
-```
-
-#### [`path()`](/docs/sketch#path)
-
-```ts
-path(): SurfacePathBuilder<ProductSkinSurfaceCoordinate>
-```
-
-`ProductSkinSurfaceCoordinate`: `{ kind?: "productSkin", side?: ProductSkinSide, u?: number, v?: number, offset?: number }`
-
-#### `sideTransition()` — Return matching side-local coordinates for an explicit split-member transition.
-
-Each SurfacePath still stays on one ProductSkin side. Use this helper to create one member ending on `from`, another starting on `to`, then join named anchors. The helper validates normalized `v`, non-empty names, adjacency, and physical coincidence before returning anchors.
-
-```ts
-sideTransition(fromSide: ProductSkinSide, toSide: ProductSkinSide, input?: ProductSkinSideTransitionInput): ProductSkinSideTransition
-```
-
-`ProductSkinSideTransitionInput`: `{ name?: string, v?: number, offset?: number }`
-
-`ProductSkinSideTransition`: `{ name?: string, from: ProductSkinSurfaceCoordinate, to: ProductSkinSurfaceCoordinate }`
-
-#### `sideTransitionChain()` — Return a sequence of matching side-local coordinates for an explicit multi-side split-member route.
-
-Each adjacent side pair becomes one named transition. Build one member per side segment, add transition anchors at each returned pair, then join the anchors. The same validation as `sideTransition()` applies to every adjacent pair.
-
-```ts
-sideTransitionChain(sides: ProductSkinSide[], input?: ProductSkinSideTransitionInput): ProductSkinSideTransition[]
-```
-
-#### `sideRoute()` — Return side-local member segments for a generated multi-side split-member route.
-
-The route still compiles as explicit members plus named-anchor joins. This helper only generates the per-side segment endpoints and transition names.
-
-```ts
-sideRoute(input: ProductSkinSideRouteInput): ProductSkinSideRoute
-```
-
-**`ProductSkinSideRouteInput`**: `name?: string`, `sides: ProductSkinSide[]`, `from: ProductSkinSurfaceCoordinate`, `to: ProductSkinSurfaceCoordinate`, `v?: number`, `offset?: number`
-
-`ProductSkinSideRoute`: `{ name?: string, transitions: ProductSkinSideTransition[], segments: ProductSkinSideRouteSegment[] }`
-
-**`ProductSkinSideRouteSegment`**: `name: string`, `side: ProductSkinSide`, `from: ProductSkinSurfaceCoordinate`, `to: ProductSkinSurfaceCoordinate`, `startAnchorName?: string`, `endAnchorName?: string`
-
-#### `pointAt()`
-
-```ts
-pointAt(coordinate: ProductSkinSurfaceCoordinate): Vec3
-```
-
-#### `mirrorPoint()`
-
-```ts
-mirrorPoint(point: Vec3): Vec3
-```
-
-#### `normalAt()`
-
-```ts
-normalAt(coordinate: ProductSkinSurfaceCoordinate): Vec3
-```
-
-#### `tangentAt()`
-
-```ts
-tangentAt(coordinate: ProductSkinSurfaceCoordinate, tangentHint?: Vec3): Vec3
-```
-
-#### `frameAt()`
-
-```ts
-frameAt(coordinate: ProductSkinSurfaceCoordinate, tangentHint?: Vec3): SurfaceFrame
-```
-
-**`SurfaceFrame`**: `point: Vec3`, `normal: Vec3`, `tangentAlong: Vec3`, `tangentAcross: Vec3`, `matrix: Mat4`, `carrier: string`, `representation: SurfaceCarrierKind | string`, `coordinate: SurfaceCoordinate`
-
-#### `bounds()`
-
-```ts
-bounds(): SurfaceBounds
-```
-
-**`SurfaceBounds`**: `u?: [ number, number ]`, `v?: [ number, number ]`, `angle?: [ number, number ]`, `z?: [ number, number ]`, `x?: [ number, number ]`, `y?: [ number, number ]`
-
-#### `offset()`
-
-```ts
-offset(distance: number): ProductSkinCarrier
-```
-
-#### `mirrorCoordinate()`
-
-```ts
-mirrorCoordinate(coordinate: ProductSkinSurfaceCoordinate): ProductSkinSurfaceCoordinate
-```
-
-### `SurfacePath`
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `carrier` | `CarrierSurface<C>` | — |
-| `points` | `C[]` | — |
-| `closedValue` | `boolean` | — |
-
-**Methods:**
-
-#### `closed()`
-
-```ts
-closed(): SurfacePath<C>
-```
-
-#### `mirror()`
-
-```ts
-mirror(): SurfacePath<C>
-```
-
-#### `coordinateAt()`
-
-```ts
-coordinateAt(t: number): C
-```
-
-#### `sample()`
-
-```ts
-sample(count?: number): SurfacePathSample<C>[]
-```
-
-#### `length()`
-
-```ts
-length(samples?: number): number
-```
-
-### `SurfacePathBuilder`
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `carrier` | `CarrierSurface<C>` | — |
-
-**Methods:**
-
-#### `from()`
-
-```ts
-from(coordinate: C): this
-```
-
-#### `through()`
-
-```ts
-through(coordinate: C): this
-```
-
-#### `to()`
-
-```ts
-to(coordinate: C): this
-```
-
-#### `around()`
-
-```ts
-around(input: { z: number; fromAngle: number; toAngle: number; offset?: number; }): this
-```
-
-#### `closed()`
-
-```ts
-closed(): this
-```
-
-#### `mirror()`
-
-```ts
-mirror(): SurfacePath<C>
-```
-
-#### `build()`
-
-```ts
-build(): SurfacePath<C>
-```
-
-#### `sample()`
-
-```ts
-sample(count?: number): SurfacePathSample<C>[]
-```
+- `from(coordinate: C): this`
+- `through(coordinate: C): this`
+- `to(coordinate: C): this`
+- `around(input: { z: number; fromAngle: number; toAngle: number; offset?: number; }): this`
+- `closed(): this`
+- `mirror(): SurfacePath<C>`
+- `build(): SurfacePath<C>`
+- `sample(count?: number): SurfacePathSample<C>[]`
 
 ### `SurfaceBand`
 
@@ -2141,34 +1033,19 @@ sample(count?: number): SurfacePathSample<C>[]
 
 **Methods:**
 
-#### `widthAt()`
-
-```ts
-widthAt(t: number): number
-```
-
-#### `boundaries()`
-
-```ts
-boundaries(samples?: number): SurfaceBandBoundarySample[]
-```
-
-#### `withHole()` — Return a new band with a named member-local rounded-slot hole region recorded as inspectable intent.
-
-```ts
-withHole(name: string, input: SurfaceBandHoleInput): SurfaceBand<C>
-```
+#### `withHole(name: string, input: SurfaceBandHoleInput): SurfaceBand<C>` — Return a new band with a named member-local rounded-slot hole region recorded as inspectable intent.
 
 `SurfaceBandHoleInput`: `{ length: number, width: number, along?: number, across?: number }`
 
-#### `holes()` — Resolve recorded hole regions into member-local across/along loops.
+#### `holes(): SurfaceBandHoleRegion[]` — Resolve recorded hole regions into member-local across/along loops.
 
-```ts
-holes(): SurfaceBandHoleRegion[]
-```
+- `widthAt(t: number): number`
+- `boundaries(samples?: number): SurfaceBandBoundarySample[]`
 
 ### `SurfaceBodyBuilder`
 
+Builder for a named surface-member body. Owns named members — `band()` or `plate()` — and the joins between them. Features (slots, cutouts, lips, cups, ribs) attach to a member's local coordinate system before lowering; this is not a global boolean recipe.
+
 **Properties:**
 
 | Property | Type | Description |
@@ -2177,215 +1054,65 @@ holes(): SurfaceBandHoleRegion[]
 
 **Methods:**
 
-#### `carrier()`
-
-```ts
-carrier(carrier: CarrierSurface): this
-```
-
-`CarrierSurface`: `{ name: string, kind: SurfaceCarrierKind }`
-
-#### `member()`
-
-```ts
-member(name: string): SurfaceMemberBuilder
-```
-
-#### `join()`
+#### `join(from: string, to: string | string[]): SurfaceJoinBuilder` — Declare a join between named members. Only a limited join set lowers to real geometry: close endpoint pairs, selected named-anchor pairs (`.betweenAnchors()`), and sampled band/plate landing pads. Farther, missing-anchor, or ambiguous joins remain diagnostic-only intent — decompose the design into supported joins instead of expecting a fallback.
 
-```ts
-join(from: string, to: string | string[]): SurfaceJoinBuilder
-```
+#### `autoJoinAtSharedAnchors(): this` — Lower only unambiguous shared-endpoint pairs (exactly two members sharing a point) into junction geometry. Shared points with more than two members produce a warning diagnostic — declare explicit `.join(...)` relationships instead.
 
-#### `autoJoinAtSharedAnchors()`
-
-```ts
-autoJoinAtSharedAnchors(): this
-```
+#### `build(): Shape | ShapeGroup` — Build and return only the member + junction geometry. Use `buildWithDiagnostics()` for the member graph and diagnostic codes.
 
-#### `build()`
+- `carrier(carrier: CarrierSurface): this`
+- `member(name: string): SurfaceMemberBuilder`
 
-```ts
-build(): Shape | ShapeGroup
-```
+`CarrierSurface`: `{ name: string, kind: SurfaceCarrierKind }`
 
 ### `SurfaceMemberBuilder`
 
-#### `plate()`
-
-```ts
-plate(): this
-```
-
-#### `band()`
-
-```ts
-band(): this
-```
-
-#### `at()`
-
-```ts
-at(anchor: SurfaceAnchor<C>): this
-```
+#### `anchorAt(name: string, coordinate: C | SurfaceAnchor<C>): this` — Add a named anchor at a carrier surface coordinate for explicit member joins.
 
 `SurfaceAnchor`: `{ carrier: CarrierSurface<C>, coordinate: C }`
 
-#### `size()`
-
-```ts
-size(width: number, height: number): this
-```
-
-#### [`path()`](/docs/sketch#path)
-
-```ts
-path(path: SurfacePath<C> | SurfacePathBuilder<C>): this
-```
-
-#### `section()`
-
-```ts
-section(section: MemberSectionInput): this
-```
+- `plate(): this`
+- `band(): this`
+- `at(anchor: SurfaceAnchor<C>): this`
+- `size(width: number, height: number): this`
+- `path(path: SurfacePath<C> | SurfacePathBuilder<C>): this`
+- `section(section: MemberSectionInput): this`
+- `cap(style: SurfaceBandCap): this`
+- `slot(name: string, feature: MemberFeature | RoundedSlotBuilder): this`
+- `cutout(name: string, feature: MemberFeature | RoundedSlotBuilder): this`
+- `counterbore(name: string, feature: MemberFeature | CounterboreBuilder): this`
+- `features(features: MemberFeature | MemberFeature[]): this`
+- `profile(name: string, options?: { depth?: number; height?: number; }): this`
+- `mirrorOf(memberName: string): SurfaceBodyBuilder`
+- `member(name: string): SurfaceMemberBuilder`
+- `join(from: string, to: string | string[]): SurfaceJoinBuilder`
+- `autoJoinAtSharedAnchors(): SurfaceBodyBuilder`
+- `build(): Shape | ShapeGroup`
 
 **`MemberSectionInput`**: `width?: number`, `thickness: number`, `edgeRadius?: number`, `direction?: MemberOutwardDirection`, `material?: ProductMaterial`, `stations?: MemberSectionStation[]`
 
 `MemberSectionStation`: `{ t: number, width?: number, thickness?: number }`
 
-#### `cap()`
-
-```ts
-cap(style: SurfaceBandCap): this
-```
-
-#### [`slot()`](/docs/sketch#slot)
-
-```ts
-slot(name: string, feature: MemberFeature | RoundedSlotBuilder): this
-```
-
 **`MemberFeature`**: `type: MemberFeatureType`, `name?: string`, `length?: number`, `width?: number`, `diameter?: number`, `counterboreDiameter?: number`, `clearanceDiameter?: number`, `height?: number`, `depth?: number`, `count?: number`, `along?: number`, `across?: number`, `verticalTravel?: number`
 
-#### `cutout()`
-
-```ts
-cutout(name: string, feature: MemberFeature | RoundedSlotBuilder): this
-```
-
-#### `counterbore()`
-
-```ts
-counterbore(name: string, feature: MemberFeature | CounterboreBuilder): this
-```
-
-#### `anchorAt()` — Add a named anchor at a carrier surface coordinate for explicit member joins.
-
-```ts
-anchorAt(name: string, coordinate: C | SurfaceAnchor<C>): this
-```
-
-#### `features()`
-
-```ts
-features(features: MemberFeature | MemberFeature[]): this
-```
-
-#### `profile()`
-
-```ts
-profile(name: string, options?: { depth?: number; height?: number; }): this
-```
-
-#### `mirrorOf()`
-
-```ts
-mirrorOf(memberName: string): SurfaceBodyBuilder
-```
-
-#### `member()`
-
-```ts
-member(name: string): SurfaceMemberBuilder
-```
-
-#### `join()`
-
-```ts
-join(from: string, to: string | string[]): SurfaceJoinBuilder
-```
-
-#### `autoJoinAtSharedAnchors()`
-
-```ts
-autoJoinAtSharedAnchors(): SurfaceBodyBuilder
-```
-
-#### `build()`
-
-```ts
-build(): Shape | ShapeGroup
-```
-
 ### `SurfaceJoinBuilder`
 
-#### `betweenAnchors()` — Select named anchors on the source and target members before lowering this join.
-
-```ts
-betweenAnchors(fromAnchor: string, toAnchor: string): this
-```
-
-#### `blend()`
+#### `betweenAnchors(fromAnchor: string, toAnchor: string): this` — Select named anchors on the source and target members before lowering this join.
 
-```ts
-blend(input?: { radius?: number; style?: string; priority?: number; continuity?: string; }): SurfaceBodyBuilder
-```
+- `blend(input?: { radius?: number; style?: string; priority?: number; continuity?: string; }): SurfaceBodyBuilder`
 
 ### `CounterboreBuilder`
 
-#### `at()`
-
-```ts
-at(input: { along?: number; across?: number; z?: number; }): this
-```
-
-#### `named()`
-
-```ts
-named(name: string): MemberFeature
-```
-
-#### `toFeature()`
-
-```ts
-toFeature(name?: string): MemberFeature
-```
+- `at(input: { along?: number; across?: number; z?: number; }): this`
+- `named(name: string): MemberFeature`
+- `toFeature(name?: string): MemberFeature`
 
 ### `RoundedSlotBuilder`
 
-#### `verticalTravel()`
-
-```ts
-verticalTravel(value: number): this
-```
-
-#### `at()`
-
-```ts
-at(input: { along?: number; across?: number; z?: number; }): this
-```
-
-#### `named()`
-
-```ts
-named(name: string): MemberFeature
-```
-
-#### `toFeature()`
-
-```ts
-toFeature(name?: string): MemberFeature
-```
+- `verticalTravel(value: number): this`
+- `at(input: { along?: number; across?: number; z?: number; }): this`
+- `named(name: string): MemberFeature`
+- `toFeature(name?: string): MemberFeature`
 
 ---
 
@@ -2397,18 +1124,7 @@ Canonical exact/smooth 3D curve constructors.
 
 `Curve.*` is the public home for reference curves and route centerlines that feed `sweep`, `variableSweep`, route visualization, and future path consumers. Standalone 3D curve constructors have been collapsed into this namespace.
 
-- `Blend(start: CurveBlendEndpoint, end: CurveBlendEndpoint): NurbsCurve3D` — Create an exact G1 blend curve between two directed endpoints. The returned curve is a cubic non-rational `NurbsCurve3D`: ForgeCAD converts the endpoint positions and tangents into Bezier control points, so the curve can feed `sweep` and exact surface boundaries through the existing `nurbs` IR rather than a sampled polyline.
-- `BlendG2(start: CurveBlendG2Endpoint, end: CurveBlendG2Endpoint): NurbsCurve3D` — Create an exact G2 blend curve between two directed endpoints. This is the curvature-aware companion to `Curve.Blend()`. It returns a degree-5 non-rational `NurbsCurve3D` that matches endpoint position, tangent direction, and optional curvature/second-derivative vectors.
-- `Arc(options: CurveArcOptions): NurbsCurve3D` — Create an exact circular 3D arc from start, end, and start tangent. The returned curve is a rational quadratic `NurbsCurve3D`, split into stable spans when needed, so it can feed `sweep` without sampling the authoring intent away.
-- `Line(start: Vec3, end: Vec3): NurbsCurve3D` — Create an exact straight 3D NURBS line segment.
-- `Polyline(points: Vec3[]): Vec3[]` — Create a polyline path as cloned 3D points. Polylines are exact as route/path input to `sweep`. Use `Curve.Route` when the centerline needs bend and endpoint-frame metadata.
-- `Spline(points: Vec3[], options?: Spline3DOptions): Curve3D` — Create a smooth Catmull-Rom spline path. This is a smooth sampled curve object. Use `Curve.Nurbs` when the path must preserve exact control-point and knot data.
-- `Nurbs(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D` — Create an exact NURBS 3D curve from control points, weights, knots, and degree.
-- `Fit(points: Vec3[], options?: CurveFitOptions): NurbsCurve3D` — Fit a non-rational NURBS curve that interpolates every input point. This is global B-spline interpolation, not approximate curve reduction: ForgeCAD computes chord-length parameters, averaged clamped knots, solves the control points, then verifies the interpolation residual against `tolerance`.
-- `Trim<T extends CurveTrimInput>(curve: T, start: number, end: number): CurveTrimOutput<T>` — Extract an exact curve segment from normalized parameter `start` to `end`. `NurbsCurve3D` inputs are trimmed with exact knot insertion/subdomain extraction. Polyline point arrays are trimmed by arclength over their exact line segments. Sampled `Curve3D` splines are rejected until ForgeCAD has a tolerance-controlled rebuild path.
-- `Reverse<T extends CurveTrimInput>(curve: T): CurveTrimOutput<T>` — Reverse an exact curve without changing its geometry. `NurbsCurve3D` inputs reverse control points, weights, and knots. Polyline point arrays are cloned and reversed. Sampled `Curve3D` splines are rejected until ForgeCAD has a tolerance-controlled rebuild path.
-- `Route: typeof Route3D` — Build analytic 3D line/arc routes for sweeps. `Curve.Route.fromPolyline()` is the canonical route API. It returns a `Route3D` value object, preserving exact route segments, named port frames, and the lowerable `route3d` sweep compile plan.
-- `Helix: { path(options: HelixOptions): CurveHelixPath; coil: CurveHelixCoil; }` — Build helical paths and swept coils. `Curve.Helix` is the canonical namespace for helical paths and coils. It uses the same sweep-based lowering as other curve paths.
+Members (full entries under [Curves & Surfacing](#curves-surfacing)): `Curve.Blend`, `Curve.BlendG2`, `Curve.Arc`, `Curve.Line`, `Curve.Nurbs`, `Curve.Fit`, `Curve.Trim`, `Curve.Reverse`, `Curve.Route`, `Curve.Helix`.
 
 ### `Surface`
 
@@ -2417,9 +1133,30 @@ Canonical exact/smooth 3D curve constructors.
 - `Cone(options: SurfaceConeOptions): Shape` — Create a finite analytic conical or frustum sheet, optionally bounded by start/end angles.
 - `Sphere(options: SurfaceSphereOptions): Shape` — Create a finite analytic spherical sheet bounded by longitude and latitude ranges.
 - `Torus(options: SurfaceTorusOptions): Shape` — Create a finite analytic torus sheet bounded by major and tube angle ranges.
-- `Nurbs(controlGrid: Vec3[][], options?: NurbsSurfaceOptions): Shape`
+- `Nurbs(controlGrid: Vec3[][], options?: NurbsSurfaceOptions): Shape` — Create an exact 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 this builds a bicubic non-rational B-spline sheet with uniform clamped knots; `NurbsSurfaceOptions` controls degrees, weights, knots, trim loops, tessellation, domain, and an optional `thickness` to return a thin solid instead of an open sheet.
+
+  ```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 sheet = Surface.Nurbs(grid);
+  const panel = Surface.Nurbs(grid, { thickness: 2 });
+  ```
 - `Ruled(curveA: ExactCurveInput, curveB: ExactCurveInput, options?: SurfaceCommonOptions): Shape`
-- `Patch(curves: { bottom: ExactCurveInput; top: ExactCurveInput; left: ExactCurveInput; right: ExactCurveInput; }, options?: SurfacePatchOptions): Shape`
+- `Patch(curves: { bottom: ExactCurveInput; top: ExactCurveInput; left: ExactCurveInput; right: ExactCurveInput; }, options?: SurfacePatchOptions): Shape` — Create a smooth open surface sheet from 4 boundary curves (Coons patch).
+
+  The four curves form the boundary of a quadrilateral patch and should meet at corners (small gaps are tolerated). Boundaries are exact by default: pass `NurbsCurve3D` values or `Shape.edge()` refs, or set `{ approximate: true }` to accept sampled `Curve3D`/`Vec3[]` boundaries. The result is an open sheet — call `.thicken(t)` for a thin solid.
+
+  ```js
+  const sheet = Surface.Patch({ bottom, top, left, right });
+  const panel = Surface.Patch({ bottom, top, left, right }).thicken(1.5);
+  ```
 - `Boundary(input: SurfaceBoundaryInput): Shape`
 - `Fill(input: SurfaceFillInput): Shape`
 - `Sew(shapes: Shape[], options?: { tolerance?: number; }): Shape`
@@ -2428,7 +1165,6 @@ Canonical exact/smooth 3D curve constructors.
 - `Trim(shape: Shape, tool: Shape | SurfacePlaneOp): Shape`
 - `Split(shape: Shape, tool: Shape | SurfacePlaneOp): [ Shape, Shape ]`
 - `Match(shape: Shape, options: { edge: "u0" | "u1" | "v0" | "v1"; target: EdgeRef; continuity?: SurfaceContinuity; }): Shape`
-- `MatchEdge(shape: Shape, options: { edge: "u0" | "u1" | "v0" | "v1"; target: EdgeRef; continuity?: SurfaceContinuity; }): Shape`
 
 ### `Blend`
 
@@ -2447,29 +1183,40 @@ Canonical exact/smooth 3D curve constructors.
 
 - `skin(name: string): ProductSkinBuilder` — Start a named product skin builder.
 - `station(name: string): ProductStationBuilder` — Start a named cross-section station for Product.skin(...).stations(...).
-- `rail: { bezier(points: Vec3[], options?: { name?: string; }): ProductRailSpec; nurbs(points: Vec3[], options?: { degree?: number; name?: string; }): ProductRailSpec; polyline(points: Vec3[], options?: { name?: string; }): ProductRailSpec; }` — Namespaced rail builders for product skin guide rails and handle spines.
-- `profiles: { ... }` — Namespaced product profile helpers for stations, panels, trims, and openings.
+- `rail: { ... }` — Namespaced rail builders for product skin guide rails and handle spines.
+- `profiles: { ... }` — Product profile helper namespace: oval, superEllipse, roundedRect, and circle — for stations, panels, trims, and openings.
 - `materials: { ... }` — Namespaced product material presets for molded plastic, rubber, metal, and transparent parts.
 - `applyMaterial(shape: Shape, preset: ProductMaterial | undefined): Shape` — Apply a product material preset to a Shape.
 - `scenePreset(name: ProductScenePreset): void` — Apply an opinionated scene preset for product review renders.
-- `ovalProfile(width: number, depth: number, options?: ProductProfileOptions): Sketch` — Create a centered oval profile from full width/depth dimensions.
-- `roundedRectProfile(width: number, depth: number, radius: number): Sketch` — Create a centered rounded-rectangle profile.
-- `circleProfile(diameter: number, options?: ProductProfileOptions): Sketch` — Create a centered circular profile from full diameter.
-- `superEllipseProfile(width: number, depth: number, options?: ProductSuperEllipseOptions): Sketch` — Create a centered superellipse profile for soft-square product sections.
 - `profileSize(sketch: Sketch): { width: number; depth: number; }` — Measure the width and depth of a 2D profile sketch.
 - `describeProfile(sketch: Sketch, kind?: ProductProfileKind, radius?: number): ProductProfileDescriptor` — Describe a custom sketch as a product profile.
 - `scaleProfileTo(sketch: Sketch, width: number, depth: number): Sketch` — Scale an existing profile sketch to a target width/depth.
 - `ref(skin: ProductSkin, query: ProductSkinRefQuery): ProductSurfaceRef` — Create an ad-hoc ProductSurfaceRef from a skin and side/u/v query.
-- `surface(skin: ProductSkin, side: ProductSkinSide): ProductSurfaceBuilder` — Create a fluent surface helper for refs and conformal features on one side of a skin. Equivalent to skin.surface(side), useful when writing in Product.* namespace style.
+- `surface(skin: ProductSkin, side: ProductSkinSide): ProductSurfaceBuilder` — Create a fluent surface helper for refs and conformal features on one side of a skin.
+
+  Equivalent to skin.surface(side), useful when writing in Product.* namespace style.
 - `panel(name: string): ProductPanelBuilder` — Start a panel feature builder.
-- `ribbon(name: string): ProductRibbonBuilder` — Start a conformal ribbon/trim builder for details that should bend with a ProductSkin. Call .on(skin, points) for side/u/v sampling or .fromRefs(points) for explicit surface refs, then configure width, thickness, offset, sampling, material, and color before build().
-- `spout(name: string): ProductSpoutBuilder` — Start a spout/nozzle feature builder.
-- `handle(name: string): ProductHandleBuilder` — Start a handle feature builder.
+- `ribbon(name: string): ProductRibbonBuilder` — Start a conformal ribbon/trim builder for details that should bend with a ProductSkin.
+
+  Call .on(skin, points) for side/u/v sampling or .fromRefs(points) for explicit surface refs, then configure width, thickness, offset, sampling, material, and color before build().
 - `place(detail: Shape | ShapeGroup, ref: ProductRefInput, options?: ProductAttachOptions): Shape | ShapeGroup` — Place a shape or group on a ProductSurfaceRef.
 - `landing(name: string, radius?: number, material?: ProductMaterial): Shape` — Small blended landing volume for manual structural bridges and connection proofs.
 
 ### `Carrier`
 
+Factory for carrier surfaces — the coordinate-and-frame owners that surface members (`SurfaceBody`) live on.
+
+A carrier owns surface-local coordinates and 3D frames; members and paths are authored in carrier coordinates, never in raw Cartesian math. Cylinder coordinates are `{ angle, z }` with `angle` in degrees — paths handle seam wrapping, so never compute positions with trig. `clearance()`/`offset()` lift geometry off the nominal surface. A ProductSkin carrier path stays on one side (`left`/`right`/`top`/`bottom`); for multi-side detail, split into one member per side and join them at the matching side-local coordinates from `sideTransition()` / `sideTransitionChain()` / `sideRoute()`.
+
+```ts
+// Bottle-cage arm: a curved band on a cylinder, authored in degrees + mm
+const bottle = Carrier.cylinder('bottle').diameter(74).height(170).clearance(1.5);
+const arm = bottle.path()
+  .from({ angle: -145, z: 18 })
+  .through({ angle: -80, z: 72 })
+  .to({ angle: -34, z: 112 });
+```
+
 - `cylinder(name: string): CylinderCarrier` — Create an analytic cylinder carrier for bottles, limbs, tubes, guards, and cuffs.
 - `plane(name: string): PlaneCarrier` — Create an analytic plane carrier for plates and local flat construction surfaces.
 - `productSkin(skin: ProductSkin): ProductSkinCarrier` — Adapt an existing ProductSkin into the general surface-member carrier protocol.
@@ -2477,17 +1224,48 @@ Canonical exact/smooth 3D curve constructors.
 ### `SurfaceMembers`
 
 - `Body(name: string): SurfaceBodyBuilder` — Start a surface-member body builder for straps, inlays, guards, braces, cuffs, and similar physical members that live on a carrier surface.
+
+  ```js
+  const carrier = Carrier.cylinder('guard-envelope').diameter(84).height(36).clearance(2);
+  const guard = SurfaceBody('simple-guard')
+    .carrier(carrier)
+    .member('left-strut')
+    .band()
+    .path(carrier.path().from({ angle: -132, z: 6 }).to({ angle: -58, z: 18 }))
+    .section({ width: 5.5, thickness: 2.8, edgeRadius: 0.6 })
+    .member('right-strut')
+    .mirrorOf('left-strut')
+    .member('front-hoop')
+    .band()
+    .path(carrier.path().around({ z: 18, fromAngle: -58, toAngle: 58 }))
+    .section({ width: 6.2, thickness: 3, edgeRadius: 0.7 })
+    .join('left-strut', 'front-hoop').blend({ radius: 3.2 })
+    .join('right-strut', 'front-hoop').blend({ radius: 3.2 })
+    .build();
+  ```
 - `Band: typeof SurfaceBand`
 - `band<C extends SurfaceCoordinate>(path: SurfacePath<C> | SurfacePathBuilder<C>, width: WidthProfile, cap?: SurfaceBandCap): SurfaceBand<C>`
+- `roundedSlot(input: { length: number; width: number; }): RoundedSlotBuilder` — Create a rounded member-local slot feature for `SurfaceMemberBuilder.slot()`/`.cutout()`.
 
-### `Slot`
+  Returns a fluent `RoundedSlotBuilder`: chain `.verticalTravel(mm)` to extend the slot for vertical bottle-drop style insertion (travel is summed into the slot length) and `.at({ along, across })` (or `{ z }`) to position it in member-local coordinates.
 
-- `rounded(input: { length: number; width: number; }): RoundedSlotBuilder` — Create a rounded member-local slot feature.
+  ```js
+  const arm = body.member('arm', armPath)
+    .slot('upper-mount-slot', SurfaceMembers.roundedSlot({ length: 12, width: 5.7 }).verticalTravel(6).at({ z: 82 }));
+  ```
+- `counterbore(input: { diameter: number; clearanceDiameter: number; depth: number; }): CounterboreBuilder` — Create a cylindrical member-local counterbore feature for `SurfaceMemberBuilder.counterbore()`.
 
-### `Counterbore`
+  `diameter` is the counterbore pocket diameter and must be larger than `clearanceDiameter`, the through-hole for the fastener shank. Chain `.at({ along, across })` (or `{ z }`) to position it in member-local coordinates.
 
-- `cylindrical(input: { diameter: number; clearanceDiameter: number; depth: number; }): CounterboreBuilder` — Create a cylindrical member-local counterbore feature.
+  ```js
+  const strap = body.member('strap', strapPath)
+    .counterbore('head-pocket', SurfaceMembers.counterbore({ diameter: 9.8, clearanceDiameter: 5.7, depth: 3 }).at({ z: 58 }));
+  ```
+- `ribs(input: { count: number; height: number; }): MemberFeature` — Create a repeated-rib stiffening feature for `SurfaceMemberBuilder.features()`.
 
-### `Ribs`
+  Ribs belong to the surface member and follow its carrier-surface lowering; `count` ribs of the given `height` are distributed along the member.
 
-- `repeated(input: { count: number; height: number; }): MemberFeature` — Create repeated ribs that belong to a surface member before lowering.
+  ```js
+  const grip = body.member('grip', gripPath)
+    .features(SurfaceMembers.ribs({ count: 18, height: 0.35 }));
+  ```