forgecad 0.6.3 → 0.8.0

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

@@ -5,109 +5,337 @@ skill-order: 100
 
 # Curves & Surfacing
 
-> **Auto-generated** from `src/forge/forge-public-api.ts`. Do not edit by hand — run `npm run gen:docs` to regenerate.
-
 Smooth curves, lofted surfaces, swept solids, and splines.
 
+## Contents
+
+- [Curves & Surfacing](#curves-surfacing) — `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
+- [Curve3D](#curve3d)
+- [NurbsCurve3D](#nurbscurve3d)
+- [NurbsSurface](#nurbssurface)
+- [PathBuilder](#pathbuilder) — Line Segments, Arcs, Curves, Closing & Output
+- [HermiteCurve3D](#hermitecurve3d)
+- [QuinticHermiteCurve3D](#quintichermitecurve3d)
+
 ## Functions
 
 ### Curves & Surfacing
 
-Create smooth curves, lofted surfaces, and swept solids.
+#### `hermiteTransitionG2()` — Create a quintic Hermite transition curve between two edge endpoints (G2 continuity).
 
-#### `spline2d()`
+The curve starts at `a.point` tangent to `a.tangent` with curvature `a.curvature`, and ends at `b.point` tangent to `b.tangent` with curvature `b.curvature`, with smooth G2-continuous interpolation matching position, tangent, and curvature.
 
 ```ts
-spline2d(points: Vec2[], options?: Spline2DOptions): Sketch
+hermiteTransitionG2(a: QuinticHermiteCurveEndpoint, b: QuinticHermiteCurveEndpoint): QuinticHermiteCurve3D
 ```
 
-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.
+**`QuinticHermiteCurveEndpoint`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `point` | `Vec3` | Position |
+| `tangent` | `Vec3` | Tangent direction (will be normalized internally) |
+| `curvature?` | `Vec3` | Second derivative / curvature vector. Default [0, 0, 0]. |
+| `weight?` | `number` | Weight: scales tangent magnitude relative to chord length. Default 1.0. |
+
+#### `nurbs3d()` — Create a NURBS curve from control points.
 
-<details><summary><code>Spline2DOptions</code></summary>
+With default options, creates a cubic non-rational B-spline with uniform clamped knots. Set `weights` for rational curves (exact circles, conics). Set `degree` for linear (1), quadratic (2), cubic (3), or higher-order curves.
+
+```js
+// Simple cubic B-spline through control points
+const curve = nurbs3d([[0,0,0], [10,5,0], [20,-5,10], [30,0,5]]);
+const tube = sweep(circle(2), curve);
+```
+
+```js
+// Rational quadratic — exact circular arc
+const arc = nurbs3d(
+  [[10,0,0], [10,10,0], [0,10,0]],
+  { degree: 2, weights: [1, Math.SQRT1_2, 1] }
+);
+```
 
 ```ts
-interface Spline2DOptions {
-  /** Closed loop (default true). */
-  closed?: boolean;
-  /** Catmull-Rom tension in [0, 1]. 0 = very round, 1 = linear-ish. Default 0.5. */
-  tension?: number;
-  /** Samples per segment (minimum 3). Default 16. */
-  samplesPerSegment?: number;
-  /** For open splines, provide stroke width to return a solid Sketch. If omitted for open splines, an error is thrown. */
-  strokeWidth?: number;
-  /** Stroke join for open splines. Default 'Round'. */
-  join?: "Round" | "Square";
-}
+nurbs3d(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D
 ```
 
-</details>
+**`NurbsCurve3DOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `degree?` | `number` | Polynomial degree (default 3 = cubic). Must be ≥ 1. |
+| `weights?` | `number[]` | Rational weights, one per control point (default: all 1.0 = non-rational). |
+| `knots?` | `number[]` | Knot vector (default: uniform clamped). Must have length = controlPoints.length + degree + 1. |
+| `closed?` | `boolean` | Whether the curve is closed/periodic (default false). |
+
+#### `spline2d()` — Build a smooth Catmull-Rom spline sketch from 2D control points.
 
-#### `spline3d()`
+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
-spline3d(points: Vec3$4[], options?: Spline3DOptions): Curve3D
+spline2d(points: Vec2[], options?: Spline2DOptions): Sketch
 ```
 
-Create a reusable 3D spline curve object (Catmull-Rom). The returned Curve3D provides sample(), pointAt(t), tangentAt(t), and length() for downstream use in sweep() or manual path operations.
+**`Spline2DOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `closed?` | `boolean` | Closed loop (default true). |
+| `tension?` | `number` | Catmull-Rom tension in [0, 1]. 0 = very round, 1 = linear-ish. Default 0.5. |
+| `samplesPerSegment?` | `number` | Samples per segment (minimum 3). Default 16. |
+| `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'. |
+
+#### `spline3d()` — Create a reusable 3D spline curve object (Catmull-Rom).
 
-<details><summary><code>Spline3DOptions</code></summary>
+The returned Curve3D provides sample(), pointAt(t), tangentAt(t), and length() for downstream use in sweep() or manual path operations.
 
 ```ts
-interface Spline3DOptions {
-  /** Closed loop (default false). */
-  closed?: boolean;
-  /** Catmull-Rom tension in [0, 1]. 0 = very round, 1 = linear-ish. Default 0.5. */
-  tension?: number;
-}
+spline3d(points: Vec3[], options?: Spline3DOptions): Curve3D
 ```
 
-</details>
+**`Spline3DOptions`**
+- `closed?: boolean` — Closed loop (default false).
+- `tension?: number` — Catmull-Rom tension in [0, 1]. 0 = very round, 1 = linear-ish. Default 0.5.
 
-#### `loft()`
+#### `loft()` — 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 export through the OCCT exact route.
+
+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
 ```
 
-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 export through the OCCT exact route. Performance note: loft is significantly heavier than primitive/extrude/revolve. If the part is axis-symmetric (bottles, vases, knobs), prefer revolve().
+**`LoftOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
+- `boundsPadding?: number` — Optional extra bounds padding.
+
+#### `loftAlongSpine()` — Loft between multiple profiles positioned along an arbitrary 3D spine curve.
 
-<details><summary><code>LoftOptions</code></summary>
+Unlike loft() which only supports Z heights, loftAlongSpine() places each profile at a position along a 3D spine, oriented perpendicular to the spine tangent. This enables lofting along curved paths — e.g., a wing root-to-tip transition that follows a swept-back leading edge.
+
+The tValues array specifies where each profile sits along the spine (0 = start, 1 = end). Must have the same length as profiles and be in [0, 1].
+
+Internally uses variableSweep infrastructure with SDF interpolation.
+
+Performance note: uses level-set meshing, heavier than simple loft().
 
 ```ts
-interface LoftOptions {
-  /** Marching-grid edge length for level-set meshing. Smaller = finer. */
-  edgeLength?: number;
-  /** Optional extra bounds padding. */
-  boundsPadding?: number;
-}
+loftAlongSpine(profiles: Sketch[], spine: Curve3D | Vec3[], tValues: number[], options?: LoftAlongSpineOptions): Shape
 ```
 
-</details>
+**`LoftAlongSpineOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `samples?` | `number` | Number of samples when spine is a Curve3D. Default 48. |
+| `edgeLength?` | `number` | Marching-grid edge length for level-set meshing. Smaller = finer. |
+| `boundsPadding?` | `number` | Optional extra bounds padding. |
+| `up?` | `Vec3` | Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. |
 
 #### `sweep()`
 
 ```ts
-sweep(profile: Sketch, path: Curve3D | Vec3$4[], options?: SweepOptions): Shape
+sweep(profile: Sketch, path: SweepPathInput, options?: SweepOptions): Shape
 ```
 
-Sweep a 2D profile along a 3D path to create a solid. Path can be a Curve3D from spline3d() or an array of [x,y,z] points (polyline). The profile is interpreted in the local frame normal plane. Compatible sweeps can export through the OCCT exact route using the canonical path representation. Performance note: sweep uses level-set meshing internally. Prefer direct primitives/extrude/revolve when they can express the same shape.
+**`SweepOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `samples?` | `number` | Number of samples when path is a Curve3D. Default 48. |
+| `edgeLength?` | `number` | Marching-grid edge length for level-set meshing. Smaller = finer. |
+| `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.
 
-<details><summary><code>SweepOptions</code></summary>
+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.
+
+Each section specifies a t parameter (0 = start, 1 = end of spine) and a 2D profile sketch. The SDF-based level-set mesher smoothly blends between profiles at intermediate positions.
+
+Performance note: like sweep(), this uses level-set meshing internally.
 
 ```ts
-interface SweepOptions {
-  /** Number of samples when path is a Curve3D. Default 48. */
-  samples?: number;
-  /** Marching-grid edge length for level-set meshing. Smaller = finer. */
-  edgeLength?: number;
-  /** Optional extra bounds padding. */
-  boundsPadding?: number;
-  /** Preferred "up" vector for local profile frame. Auto fallback is used near parallel segments. */
-  up?: Vec3$4;
-}
+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.
+
+**`VariableSweepOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `samples?` | `number` | Number of samples when spine is a Curve3D. Default 48. |
+| `edgeLength?` | `number` | Marching-grid edge length for level-set meshing. Smaller = finer. |
+| `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 });
 ```
 
-</details>
+```ts
+nurbsSurface(controlGrid: Vec3[][], options?: NurbsSurfaceOptions): Shape
+```
+
+**`NurbsSurfaceOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `degreeU?` | `number` | Degree in U direction (default 3). |
+| `degreeV?` | `number` | Degree in V direction (default 3). |
+| `weights?` | `number[][]` | Weights grid — same dimensions as controlGrid (default: all 1.0). |
+| `knotsU?` | `number[]` | Knot vector in U direction (default: uniform clamped). |
+| `knotsV?` | `number[]` | Knot vector in V direction (default: uniform clamped). |
+| `thickness?` | `number` | Sheet thickness — if > 0, thickens the surface into a solid (default 0 = surface only). |
+| `resolution?` | `number` | Tessellation resolution — points per direction (default 32). |
+
+#### `surfacePatch()` — Create a smooth surface patch from 4 boundary curves (Coons patch).
+
+The four curves form the boundary of a quadrilateral patch:
+
+- 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.5.
+
+#### `transitionCurve()` — Create a smooth transition curve between two edges.
+
+Returns a `HermiteCurve3D` that starts at `edgeA.point` tangent to `edgeA.tangent` and ends at `edgeB.point` tangent to `edgeB.tangent`.
+
+The curve maintains G1 continuity (matching tangent direction) at both endpoints. Weight parameters control the shape of the transition.
+
+```js
+```js
+
+// Connect two edges with a balanced transition const curve = transitionCurve( { point: [0, 0, 0], tangent: [1, 0, 0] }, { point: [10, 5, 0], tangent: [1, 0, 0] }, );
+
+```
+
+// Weighted: curve hugs edge A longer
+const weighted = transitionCurve(
+  { point: [0, 0, 0], tangent: [1, 0, 0] },
+  { point: [10, 5, 0], tangent: [1, 0, 0] },
+  { weightA: 2.0, weightB: 0.5 },
+);
+```
+
+```ts
+transitionCurve(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionCurveOptions): HermiteCurve3D
+```
+
+**`TransitionEdge`**
+- `point: Vec3` — Connection point on the edge. Can be any point along the edge where the transition should connect.
+- `tangent: Vec3` — Tangent direction at the connection point. This is the direction the curve should initially follow when leaving this edge. For a straight edge, this is typically the edge direction pointing "outward" (away from the body of the edge, toward the other edge).
+- `normal?: Vec3` — Surface normal at the connection point (optional). Used as a hint for the sweep frame's up vector.
+
+**`TransitionCurveOptions`**
+- `weightA?: number` — Weight for the start edge. Controls tangent magnitude at the start. - 1.0 (default): balanced transition - > 1.0: curve follows start edge longer before turning - < 1.0: curve turns sooner at the start
+- `weightB?: number` — Weight for the end edge. Controls tangent magnitude at the end. - 1.0 (default): balanced transition - > 1.0: curve follows end edge longer before turning - < 1.0: curve turns sooner at the end
+- `samples?: number` — Number of sample points for the output polyline. Default 64. Higher values give smoother curves at the cost of more geometry.
+
+#### `transitionSurface()` — Create a solid transition surface between two edges by sweeping a profile along a Hermite transition curve.
+
+This produces a watertight solid that smoothly connects the two edges. Works with both Manifold and OCCT backends.
+
+```js
+```js
+
+// Circular tube connecting two edges const tube = transitionSurface( { point: [0, 0, 0], tangent: [1, 0, 0] }, { point: [10, 5, 3], tangent: [0, 1, 0] }, { radius: 0.5 }, );
+
+```
+
+// Custom profile with weights
+const custom = transitionSurface(
+  { point: [0, 0, 0], tangent: [1, 0, 0] },
+  { point: [10, 5, 3], tangent: [0, 1, 0] },
+  { profile: mySketch, weightA: 1.5, weightB: 0.8 },
+);
+```
+
+```ts
+transitionSurface(edgeA: TransitionEdge, edgeB: TransitionEdge, options?: TransitionSurfaceOptions): Shape
+```
+
+
+**`TransitionSurfaceOptions`** extends TransitionCurveOptions
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `profile?` | `Sketch` | Cross-section profile to sweep along the transition curve. If omitted, a circular profile with `radius` is used. |
+| `radius?` | `number` | Radius of circular cross-section (used when `profile` is omitted). Default: 5% of chord length. |
+| `up?` | `Vec3` | Preferred up vector for the sweep frame. Default: auto-detected. |
+| `edgeLength?` | `number` | Edge length for level-set meshing. Smaller = finer. |
+| `boundsPadding?` | `number` | Extra bounds padding for level-set meshing. |
+| `width`, `height` | | — |
+
+#### `connectEdges()` — Create a transition surface or solid bridge between two edge segments.
+
+Tangents can be inferred from neighboring geometry or supplied explicitly through `options`. This is useful for loft-like blends where you want a direct connection between two edge spans.
+
+```ts
+connectEdges(edgeA: EdgeSegment, edgeB: EdgeSegment, options?: ConnectEdgesOptions): Shape
+```
+
+**`EdgeSegment`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `index` | `number` | Stable index within the extraction (deterministic for a given mesh). |
+| `direction` | `Vec3` | Normalized direction from start → end. |
+| `dihedralAngle` | `number` | Dihedral angle in degrees (0 = coplanar, 180 = knife edge). |
+| `convex` | `boolean` | true = outside corner (convex), false = inside corner (concave). |
+| `normalA` | `Vec3` | Normal of first adjacent face. |
+| `normalB` | `Vec3` | Normal of second adjacent face (same as normalA for boundary edges). |
+| `boundary` | `boolean` | true if this is a boundary (unmatched) edge — unusual for closed solids. |
+| `start`, `end`, `midpoint`, `length` | | — |
+
+
+**`ConnectEdgesOptions`** extends TransitionSurfaceOptions
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `endA?` | `EdgeEnd` | Which end of edge A to connect. Default: 'start'. |
+| `endB?` | `EdgeEnd` | Which end of edge B to connect. Default: 'start'. |
+| `tangentModeA?` | `TangentMode` | Tangent mode for edge A. Default: 'along'. |
+| `tangentModeB?` | `TangentMode` | Tangent mode for edge B. Default: 'along'. |
+| `tangentA?` | `Vec3` | Explicit tangent for edge A. |
+| `tangentB?` | `Vec3` | Explicit tangent for edge B. |
+| `flipA?` | `boolean` | Flip tangent A. |
+| `flipB?` | `boolean` | Flip tangent B. |
 
 ---
 
@@ -119,94 +347,509 @@ interface SweepOptions {
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `points` | `Vec3$4[]` | — |
+| `points` | `Vec3[]` | — |
 | `closed` | `boolean` | — |
 | `tension` | `number` | — |
 
 **Methods:**
 
-- `sampleBySegment()` — sampleBySegment(samplesPerSegment?: number): Vec3$4[]
-- `sample()` — sample(count?: number): Vec3$4[]
-- `pointAt()` — pointAt(t: number): Vec3$4
-- `tangentAt()` — tangentAt(t: number): Vec3$4
-- `length()` — length(samples?: number): number
+#### `sampleBySegment()` — Sample the curve with a fixed number of points per segment.
 
-### `HermiteCurve3D`
+```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
+```
 
-A cubic Hermite curve in 3D space. Interpolates between two endpoints matching position and tangent (G1 continuity). Weight parameters control tangent magnitude, affecting the "reach" of the curve along each edge's direction before turning.
+#### `tangentAt()` — Return a unit tangent vector at normalized parameter `t` in `[0, 1]`. O(1), analytical derivative.
+
+```ts
+tangentAt(t: number): Vec3
+```
+
+#### `length()` — Approximate the curve length by polyline sampling.
+
+```ts
+length(samples?: number): number
+```
+
+### `NurbsCurve3D`
 
 **Properties:**
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `p0` | `Vec3$5` | Start position |
-| `p1` | `Vec3$5` | End position |
-| `t0` | `Vec3$5` | Scaled tangent at start (direction * weight * chordLength) |
-| `t1` | `Vec3$5` | Scaled tangent at end (direction * weight * chordLength) |
-| `chordLength` | `number` | Chord length (straight-line distance between endpoints) |
+| `controlPoints` | `Vec3[]` | — |
+| `weights` | `number[]` | — |
+| `knots` | `number[]` | — |
+| `degree` | `number` | — |
+| `closed` | `boolean` | — |
 
 **Methods:**
 
-- `pointAt()` — Evaluate position at parameter t ∈ [0, 1]
-- `tangentAt()` — Evaluate tangent (first derivative) at parameter t ∈ [0, 1]
-- `curvatureAt()` — Evaluate curvature vector (second derivative) at parameter t ∈ [0, 1]
-- `sample()` — Sample the curve as a polyline of evenly-spaced parameter values.
-- `length()` — Approximate arc length by sampling.
-- `sampleAdaptive()` — Sample with adaptive density — more points where curvature is higher. Returns at least `minCount` points, up to `maxCount`.
-- `toPolyline()` — Convert to a format compatible with sweep() path input.
+#### `pointAt()` — Evaluate the curve at parameter t ∈ [0, 1]. Uses De Boor's algorithm — exact, O(degree²).
 
-### `QuinticHermiteCurve3D`
+```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.
 
-A quintic Hermite curve in 3D space. Interpolates between two endpoints matching position, tangent, and second derivative (G2 / curvature continuity). Uses degree-5 Hermite basis functions. Weight parameters scale tangent magnitudes relative to chord length. Curvature vectors are scaled by weight² * chordLength² for consistent behavior.
+```ts
+sample(count?: number): Vec3[]
+```
+
+#### `sampleAdaptive()` — Sample with adaptive density — more points in high-curvature regions.
+
+```ts
+sampleAdaptive(minCount?: number, maxCount?: number): Vec3[]
+```
+
+#### `length()` — Approximate arc length by summing polyline segment lengths.
+
+```ts
+length(samples?: number): number
+```
+
+#### `toPolyline()` — Convert to a format compatible with sweep() path input.
+
+```ts
+toPolyline(samples?: number): Vec3[]
+```
+
+### `NurbsSurface`
 
 **Properties:**
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `p0` | `Vec3$5` | Start position |
-| `p1` | `Vec3$5` | End position |
-| `t0` | `Vec3$5` | Scaled tangent at start (direction * weight * chordLength) |
-| `t1` | `Vec3$5` | Scaled tangent at end (direction * weight * chordLength) |
-| `c0` | `Vec3$5` | Scaled second derivative at start (curvature * weight² * chordLength²) |
-| `c1` | `Vec3$5` | Scaled second derivative at end (curvature * weight² * chordLength²) |
-| `chordLength` | `number` | Chord length (straight-line distance between endpoints) |
+| `controlGrid` | `Vec3[][]` | — |
+| `weightsGrid` | `number[][]` | — |
+| `knotsU` | `number[]` | — |
+| `knotsV` | `number[]` | — |
+| `degreeU` | `number` | — |
+| `degreeV` | `number` | — |
+| `nU` | `number` | — |
+| `nV` | `number` | — |
 
 **Methods:**
 
-- `pointAt()` — Evaluate position at parameter t ∈ [0, 1]
-- `tangentAt()` — Evaluate tangent (first derivative, normalized) at parameter t ∈ [0, 1]
-- `curvatureAt()` — Evaluate curvature vector (second derivative) at parameter t ∈ [0, 1]
-- `sample()` — Sample the curve as a polyline of evenly-spaced parameter values.
-- `length()` — Approximate arc length by sampling.
-- `sampleAdaptive()` — Sample with adaptive density — more points where curvature is higher. Returns at least `minCount` points, up to `maxCount`.
-- `toPolyline()` — Convert to a format compatible with sweep() path input.
+#### `pointAt()` — Evaluate the surface at parameters (u, v) ∈ [0, 1]². Uses tensor product evaluation: evaluate basis functions in U and V independently.
+
+```ts
+pointAt(u: number, v: number): Vec3
+```
+
+#### `normalAt()` — Evaluate the surface normal at (u, v) via cross product of partial derivatives.
+
+```ts
+normalAt(u: number, v: number): Vec3
+```
+
+#### `tessellate()` — Tessellate the surface into a triangle mesh. Returns positions, normals, and triangle indices.
+
+```ts
+tessellate(resU?: number, resV?: number): { positions: Vec3[]; normals: Vec3[]; indices: number[]; }
+```
 
 ### `PathBuilder`
 
+**Line Segments**
+
+#### `moveTo()` — 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.
+
+```ts
+lineTo(x: number, y: number): this
+```
+
+#### `lineH()` — 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.
+
+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.
+
+Angle convention: `0°` points right (+X), `90°` points up (+Y).
+
+```ts
+// L-bracket with angled return
+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.
+
+```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.
+
+```ts
+tangentArcTo(x: number, y: number): this
+```
+
+**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
+```
+
+**Closing & Output**
+
+#### `close()` — 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.
+
+Edge labels (assigned with `.label('name')`) are transferred to the resulting sketch and propagate through `extrude()`, `revolve()`, `loft()`, and `sweep()` into named faces on the resulting [`Shape`](/docs/core#shape).
+
+```ts
+const triangle = path().moveTo(0, 0).lineH(50).lineV(30).close();
+
+// With a hole (second sub-path)
+const frame = path()
+  .moveTo(0, 0).lineH(40).lineV(30).lineH(-40).close(); // outer
+  // (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
+```
+
+#### [`stroke()`](/docs/sketch#stroke) — 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/core#filletcorners).
+
+```ts
+// Square-join L-bracket
+const bracket = path().moveTo(0, 0).lineH(50).lineV(-70).lineAngled(20, 235).stroke(4);
+
+// Round-join rib
+const rib = path().moveTo(0, 0).lineH(60).stroke(6, 'Round');
+
+// Equivalent standalone form
+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.
+
+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.
+
+```ts
+getY(): number
+```
+
+#### `lineBy()` — Draw a line by a relative `(dx, dy)` displacement from the current cursor.
+
+```ts
+lineBy(dx: number, dy: number): this
+```
+
+#### `arcBy()` — Draw an arc to a point offset from the current cursor.
+
+```ts
+arcBy(dx: number, dy: number, radius: number, clockwise?: boolean): this
+```
+
+#### `bezierBy()` — Draw a cubic Bezier using control points relative to the current cursor.
+
+```ts
+bezierBy(dcp1x: number, dcp1y: number, dcp2x: number, dcp2y: number, dx: number, dy: number): this
+```
+
+#### `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.
+
+```js
+// Arc 90° CCW around (50, 50)
+path().moveTo(70, 50).arcAround(50, 50, 90)
+// Arc 45° CW around the origin
+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.
+
+```js
+// Arc 90° CCW around a center 20 units to the right
+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()` — 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.
+
+```ts
+smoothCapTo(endX: number, endY: number, cornerRadius: number, capRadius: number): this
+```
+
+#### `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).
+
+The second control point `(cp2x, cp2y)` must be provided — it controls the arrival curvature. For a fully automatic smooth curve, see `smoothThrough`.
+
+```ts
+tangentBezierTo(cp2x: number, cp2y: number, x: number, y: number, weight?: number): this
+```
+
+#### `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.
+
+Unlike `arcTo()` which tessellates to a polyline, this preserves the exact arc definition. When extruded through the OCCT backend, it produces a true cylindrical face — not a faceted approximation.
+
+```ts
+exactArcTo(x: number, y: number, opts?: { radius?: number; clockwise?: boolean; }): this
+```
+
+#### [`fillet()`](/docs/core#fillet) — Round the last corner (the junction between the previous two segments) with a tangent arc of the given radius.
+
+Must be called after at least two line/arc segments that form a corner. The fillet trims back both segments and inserts a tangent arc.
+
+```js
+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.
+
+```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.
+
+'y' mirrors across the local Y-axis (flips X), or `[nx, ny]` for an arbitrary axis direction.
+
+```js
+// Build right half, mirror to get full symmetric profile
+path().moveTo(0,0).lineTo(10,0).lineTo(10,5).mirror('x').close()
+```
+
+```ts
+mirror(axis: "x" | "y" | [ number, number ]): this
+```
+
+#### `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
+```
+
+### `HermiteCurve3D`
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `p0` | `Vec3` | Start position |
+| `p1` | `Vec3` | End position |
+| `t0` | `Vec3` | Scaled tangent at start (direction * weight * chordLength) |
+| `t1` | `Vec3` | Scaled tangent at end (direction * weight * chordLength) |
+| `chordLength` | `number` | Chord length (straight-line distance between endpoints) |
+
+**Methods:**
+
+#### `pointAt()` — Evaluate position at parameter t ∈ [0, 1]
+
+```ts
+pointAt(t: number): Vec3
+```
+
+#### `tangentAt()` — Evaluate tangent (first derivative) at parameter t ∈ [0, 1]
+
+```ts
+tangentAt(t: number): Vec3
+```
+
+#### `curvatureAt()` — Evaluate curvature vector (second derivative) at parameter t ∈ [0, 1]
+
+```ts
+curvatureAt(t: number): Vec3
+```
+
+#### `sample()` — Sample the curve as a polyline of evenly-spaced parameter values.
+
+```ts
+sample(count?: number): Vec3[]
+```
+
+#### `length()` — Approximate arc length by sampling.
+
+```ts
+length(samples?: number): number
+```
+
+#### `sampleAdaptive()` — Sample with adaptive density — more points where curvature is higher. Returns at least `minCount` points, up to `maxCount`.
+
+```ts
+sampleAdaptive(minCount?: number, maxCount?: number): Vec3[]
+```
+
+#### `toPolyline()` — Convert to a format compatible with sweep() path input.
+
+```ts
+toPolyline(samples?: number): Vec3[]
+```
+
+### `QuinticHermiteCurve3D`
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `p0` | `Vec3` | Start position |
+| `p1` | `Vec3` | End position |
+| `t0` | `Vec3` | Scaled tangent at start (direction * weight * chordLength) |
+| `t1` | `Vec3` | Scaled tangent at end (direction * weight * chordLength) |
+| `c0` | `Vec3` | Scaled second derivative at start (curvature * weight² * chordLength²) |
+| `c1` | `Vec3` | Scaled second derivative at end (curvature * weight² * chordLength²) |
+| `chordLength` | `number` | Chord length (straight-line distance between endpoints) |
+
 **Methods:**
 
-- `getX()` — Current cursor X position.
-- `getY()` — Current cursor Y position.
-- `moveTo()` — moveTo(x: number, y: number): this
-- `lineTo()` — lineTo(x: number, y: number): this
-- `lineH()` — lineH(dx: number): this
-- `lineV()` — lineV(dy: number): this
-- `lineAngled()` — lineAngled(length: number, degrees: number): this
-- `lineBy()` — lineBy(dx: number, dy: number): this
-- `arcBy()` — arcBy(dx: number, dy: number, radius: number, clockwise?: boolean): this
-- `bezierBy()` — bezierBy(dcp1x: number, dcp1y: number, dcp2x: number, dcp2y: number, dx: number,
-- `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.
-- `tangentArcTo()` — G1-continuous arc — radius derived from current tangent + endpoint. Throws if endpoint is collinear with current direction.
-- `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. ```js // Arc centered at (10, 0), radius 50, from -30° to +30° path().arc(10, 0, 50, -30, 30).stroke(8, 'Round') ```
-- `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. ```js // Arc 90° CCW around (50, 50) path().moveTo(70, 50).arcAround(50, 50, 90) // Arc 45° CW around the origin path().moveTo(10, 0).arcAround(0, 0, -45) ```
-- `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. ```js // Arc 90° CCW around a center 20 units to the right path().moveTo(50, 50).arcAroundRelative(20, 0, 90) // Equivalent to: path().moveTo(50, 50).arcAround(70, 50, 90) ```
-- `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.
-- `bezierTo()` — Cubic bezier from current position to (x, y) via two control points.
-- `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). The second control point `(cp2x, cp2y)` must be provided — it controls the arrival curvature. For a fully automatic smooth curve, see `smoothThrough`.
-- `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.
-- `fillet()` — Round the last corner (the junction between the previous two segments) with a tangent arc of the given radius. Must be called after at least two line/arc segments that form a corner. The fillet trims back both segments and inserts a tangent arc. ```js path().moveTo(0,0).lineTo(10,0).lineTo(10,10).fillet(2).lineTo(0,10).close() ```
-- `chamfer()` — 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() ```
-- `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. 'y' mirrors across the local Y-axis (flips X), or `[nx, ny]` for an arbitrary axis direction. ```js // Build right half, mirror to get full symmetric profile path().moveTo(0,0).lineTo(10,0).lineTo(10,5).mirror('x').close() ```
-- `close()` — Close the path and return a filled Sketch. If the path contains multiple sub-paths (multiple moveTo calls), the first sub-path is the outer contour and subsequent sub-paths are holes (subtracted from the outer contour).
-- `closeOffset()` — Close the path and return an offset version of the filled Sketch. Positive delta expands outward, negative shrinks inward.
-- `stroke()` — stroke(width: number, join?: "Round" | "Square"): Sketch
+#### `pointAt()` — Evaluate position at parameter t ∈ [0, 1]
+
+```ts
+pointAt(t: number): Vec3
+```
+
+#### `tangentAt()` — Evaluate tangent (first derivative, normalized) at parameter t ∈ [0, 1]
+
+```ts
+tangentAt(t: number): Vec3
+```
+
+#### `curvatureAt()` — Evaluate curvature vector (second derivative) at parameter t ∈ [0, 1]
+
+```ts
+curvatureAt(t: number): Vec3
+```
+
+#### `sample()` — Sample the curve as a polyline of evenly-spaced parameter values.
+
+```ts
+sample(count?: number): Vec3[]
+```
+
+#### `length()` — Approximate arc length by sampling.
+
+```ts
+length(samples?: number): number
+```
+
+#### `sampleAdaptive()` — Sample with adaptive density — more points where curvature is higher. Returns at least `minCount` points, up to `maxCount`.
+
+```ts
+sampleAdaptive(minCount?: number, maxCount?: number): Vec3[]
+```
+
+#### `toPolyline()` — Convert to a format compatible with sweep() path input.
+
+```ts
+toPolyline(samples?: number): Vec3[]
+```