forgecad 0.9.14 → 0.9.16

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

@@ -9,15 +9,13 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 
 ## Contents
 
-- [Curves & Surfacing](#curves-surfacing) — `Loft.station`, `Loft.leftRail`, `Loft.rightRail`, `Loft.frontRail`, `Loft.backRail`, `Loft.centerRail`, `Loft.pathOnXz`, `Loft.pathOnYz`, `Loft.pathOnXy`, `Loft.withGuideRails`, `Helix.path`, `Helix.coil`, `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
+- [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`
 - [Curve3D](#curve3d)
-- [HelixCurve](#helixcurve)
+- [Route3D](#route3d)
 - [NurbsCurve3D](#nurbscurve3d)
 - [NurbsSurface](#nurbssurface)
 - [PathBuilder](#pathbuilder) — Line Segments, Arcs, Curves, Closing & Output
-- [HermiteCurve3D](#hermitecurve3d)
-- [QuinticHermiteCurve3D](#quintichermitecurve3d)
 - [ProductSkin](#productskin)
 - [ProductSurfaceRef](#productsurfaceref)
 - [ProductSurfaceBuilder](#productsurfacebuilder)
@@ -39,6 +37,7 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 - [SurfaceJoinBuilder](#surfacejoinbuilder)
 - [CounterboreBuilder](#counterborebuilder)
 - [RoundedSlotBuilder](#roundedslotbuilder)
+- [Curve](#curve)
 - [Surface](#surface)
 - [Blend](#blend)
 - [Analysis](#analysis)
@@ -48,97 +47,186 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 - [Slot](#slot)
 - [Counterbore](#counterbore)
 - [Ribs](#ribs)
-- [Helix](#helix)
 
 ## Functions
 
 ### Curves & Surfacing
 
-#### `Loft.station()` — Create a loft station from a 2D profile and an axis position.
+#### `Curve.Blend()` — 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.
+
+```js
+const rail = Curve.Blend(
+  { point: [0, 0, 0], tangent: [1, 0, 0], weight: 0.8 },
+  { point: [40, 20, 8], tangent: [0, 1, 0], weight: 0.8 },
+);
+const tube = sweep(circle2d(2), rail);
+```
 
 ```ts
-Loft.station(profile: Sketch, position: number): LoftStation
+Curve.Blend(start: CurveBlendEndpoint, end: CurveBlendEndpoint): NurbsCurve3D
 ```
 
-`LoftStation`: `{ profile: Sketch, position: number }`
+**`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.
 
-#### `Loft.leftRail()` — Create a guide rail that constrains the section-local negative-X side.
+#### `Curve.BlendG2()` — 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.
+
+```js
+const rail = Curve.BlendG2(
+  { point: [0, 0, 0], tangent: [1, 0, 0], curvature: [0, 0.02, 0] },
+  { point: [50, 20, 0], tangent: [0, 1, 0], curvature: [-0.02, 0, 0] },
+);
+```
 
 ```ts
-Loft.leftRail(path: LoftGuideRailPath): LoftGuideRail
+Curve.BlendG2(start: CurveBlendG2Endpoint, end: CurveBlendG2Endpoint): NurbsCurve3D
 ```
 
-`LoftGuideRail`: `{ side: LoftGuideRailSide, path: LoftGuideRailPath }`
+**`CurveBlendG2Endpoint`** extends CurveBlendEndpoint
+- `curvature?: Vec3` — Optional endpoint curvature/second-derivative vector. Default is zero.
 
-#### `Loft.rightRail()` — Create a guide rail that constrains the section-local positive-X side.
+#### `Curve.Arc()` — 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.
+
+```js
+const rail = Curve.Arc({
+  start: [40, 0, 0],
+  end: [0, 40, 0],
+  tangent: [0, 1, 0],
+});
+const tube = sweep(circle2d(2), rail);
+```
 
 ```ts
-Loft.rightRail(path: LoftGuideRailPath): LoftGuideRail
+Curve.Arc(options: CurveArcOptions): NurbsCurve3D
 ```
 
-#### `Loft.frontRail()` — Create a guide rail that constrains the section-local positive-Y side.
+**`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.
+
+```js
+const rail = Curve.Line([0, 0, 0], [80, 0, 15]);
+const rib = sweep(circle2d(2), rail);
+```
 
 ```ts
-Loft.frontRail(path: LoftGuideRailPath): LoftGuideRail
+Curve.Line(start: Vec3, end: Vec3): NurbsCurve3D
 ```
 
-#### `Loft.backRail()` — Create a guide rail that constrains the section-local negative-Y side.
+#### `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
-Loft.backRail(path: LoftGuideRailPath): LoftGuideRail
+Curve.Polyline(points: Vec3[]): Vec3[]
 ```
 
-#### `Loft.centerRail()` — Create a guide rail that moves section centers along the loft.
+#### `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
-Loft.centerRail(path: LoftGuideRailPath): LoftGuideRail
+Curve.Spline(points: Vec3[], options?: Spline3DOptions): Curve3D
 ```
 
-#### `Loft.pathOnXz()` — Place a 2D guide path onto the XZ plane.
+**`Spline3DOptions`**
+- `closed?: boolean` — Closed loop (default false).
+- `tension?: number` — Catmull-Rom tension in [0, 1]. 0 = very round, 1 = linear-ish. Default 0.5.
 
-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).
+#### `Curve.Nurbs()` — 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
-Loft.pathOnXz(path: LoftPath2D, y?: number): Vec3[]
+Curve.Nurbs(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D
 ```
 
-#### `Loft.pathOnYz()` — Place a 2D guide path onto the YZ plane.
+**`NurbsCurve3DOptions`**
 
-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).
+| 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). |
+
+#### `Curve.Fit()` — 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`.
+
+```js
+const rail = Curve.Fit(
+  [[0, 0, 0], [20, 8, 12], [50, -4, 18], [80, 0, 0]],
+  { degree: 3, tolerance: 0.001 },
+);
+const tube = sweep(circle2d(2), rail);
+```
 
 ```ts
-Loft.pathOnYz(path: LoftPath2D, x?: number): Vec3[]
+Curve.Fit(points: Vec3[], options?: CurveFitOptions): NurbsCurve3D
 ```
 
-#### `Loft.pathOnXy()` — Place a 2D guide path onto the XY plane.
+**`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.
 
-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.
+#### `Curve.Trim()` — 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
-Loft.pathOnXy(path: LoftPath2D, z?: number): Vec3[]
+Curve.Trim<T extends CurveTrimInput>(curve: T, start: number, end: number): CurveTrimOutput<T>
 ```
 
-#### `Loft.withGuideRails()` — Loft through profile stations while forcing generated sections to follow guide rails.
+#### `Curve.Reverse()` — Reverse an exact curve without changing its geometry.
 
-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.
+`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
-Loft.withGuideRails(stations: LoftStation[], rails: LoftGuideRail[], options?: LoftWithGuideRailsOptions): Shape
+Curve.Reverse<T extends CurveTrimInput>(curve: T): CurveTrimOutput<T>
 ```
 
-**`LoftOptions`**
-- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
-- `boundsPadding?: number` — Optional extra bounds padding.
+#### `Curve.Route()` — Build analytic 3D line/arc routes for sweeps.
 
-**`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.
+`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.
+
+```js
+const route = Curve.Route.fromPolyline(
+  [[0, 0, 0], [0, 0, 50], [40, 0, 50]],
+  { cornerRadius: 12, startPort: 'inlet', endPort: 'outlet' },
+);
+const tube = sweep(circle2d(4), route);
+```
+
+```ts
+Curve.Route: typeof Route3D
+```
 
-#### `Helix.path()` — Create a metadata-bearing helical centerline around the Z axis.
+#### `Curve.Helix()` — 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.
+
+```js
+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
-Helix.path(options: HelixOptions): HelixCurve
+Curve.Helix: { path(options: HelixOptions): CurveHelixPath; coil: CurveHelixCoil; }
 ```
 
 **`HelixOptions`**
@@ -153,66 +241,88 @@ Helix.path(options: HelixOptions): HelixCurve
 | `clockwise?` | `boolean` | Reverse winding direction when viewed from +Z. |
 | `samplesPerTurn?` | `number` | Point samples per turn for the metadata path. Default 32. |
 
-#### `Helix.coil()` — Create a solid helical coil by sweeping a profile through helix-local frames.
+`CurveHelixPath`: `{ radius: number, pitch: number, turns: number, height: number, startAngle: number, clockwise: boolean }`
 
-Overloads:
+#### `Loft.station()` — Create a loft station from a 2D profile and an axis position.
 
-- `Helix.coil(options: HelixCoilOptions): Shape`
-- `Helix.coil(profile: Sketch, options: HelixCoilOptions): Shape`
+```ts
+Loft.station(profile: Sketch, position: number): LoftStation
+```
 
+`LoftStation`: `{ profile: Sketch, position: number }`
 
-**`HelixCoilOptions`** extends HelixOptions
-- `wireRadius?: number` — Radius of the circular wire profile. Required unless a custom profile is passed.
-- `profileSegments?: number` — Segment count for the default circular wire profile. Default 24.
-- `divisionsPerTurn?: number` — Sweep path samples per turn. Default 32.
+#### `Loft.leftRail()` — Create a guide rail that constrains the section-local negative-X side.
 
-#### `hermiteTransitionG2()` — Create a quintic Hermite transition curve between two edge endpoints (G2 continuity).
+```ts
+Loft.leftRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+`LoftGuideRail`: `{ side: LoftGuideRailSide, path: LoftGuideRailPath }`
 
-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.
+#### `Loft.rightRail()` — Create a guide rail that constrains the section-local positive-X side.
 
 ```ts
-hermiteTransitionG2(a: QuinticHermiteCurveEndpoint, b: QuinticHermiteCurveEndpoint): QuinticHermiteCurve3D
+Loft.rightRail(path: LoftGuideRailPath): LoftGuideRail
 ```
 
-**`QuinticHermiteCurveEndpoint`**
+#### `Loft.frontRail()` — Create a guide rail that constrains the section-local positive-Y side.
 
-| 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. |
+```ts
+Loft.frontRail(path: LoftGuideRailPath): LoftGuideRail
+```
 
-#### `nurbs3d()` — Create a NURBS curve from control points.
+#### `Loft.backRail()` — Create a guide rail that constrains the section-local negative-Y side.
 
-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.
+```ts
+Loft.backRail(path: LoftGuideRailPath): LoftGuideRail
+```
 
-```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);
+#### `Loft.centerRail()` — Create a guide rail that moves section centers along the loft.
+
+```ts
+Loft.centerRail(path: LoftGuideRailPath): LoftGuideRail
 ```
 
-```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] }
-);
+#### `Loft.pathOnXz()` — 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.
+
+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
-nurbs3d(points: Vec3[], options?: NurbsCurve3DOptions): NurbsCurve3D
+Loft.pathOnYz(path: LoftPath2D, x?: number): Vec3[]
 ```
 
-**`NurbsCurve3DOptions`**
+#### `Loft.pathOnXy()` — Place a 2D guide path onto the XY plane.
 
-| 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). |
+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.
+
+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.
 
@@ -232,18 +342,6 @@ 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'. |
 
-#### `spline3d()` — 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.
-
-```ts
-spline3d(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.
-
 #### `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 also stay on the maintained export-backend path.
@@ -254,29 +352,6 @@ Performance note: loft is significantly heavier than primitive/extrude/revolve.
 loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape
 ```
 
-#### `loftAlongSpine()` — Loft between multiple profiles positioned along an arbitrary 3D spine curve.
-
-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
-loftAlongSpine(profiles: Sketch[], spine: Curve3D | Vec3[], tValues: number[], options?: LoftAlongSpineOptions): Shape
-```
-
-**`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
@@ -400,106 +475,6 @@ surfacePatch(curves: { ... }, options?: SurfacePatchOptions): Shape
 - `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.
 
-#### `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
-// 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
-// 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. |
-| `rectangleSection?` | `{ width: number; height: number; }` | Width and height for rectangular cross-section. Alternative to `radius` when `profile` is omitted. |
-| `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. |
-
-#### `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. |
-
 ### Surface Members
 
 #### `surfaceBand()`
@@ -579,47 +554,76 @@ tangentAt(t: number): Vec3
 length(samples?: number): number
 ```
 
-### `HelixCurve`
+### `Route3D`
 
-Metadata-bearing helical curve around the Z axis. Use `Helix.path(...)` for sampling, placement, or `sweep()`, and `Helix.coil(...)` for helix-oriented solids.
+Metadata-bearing analytic 3D route made from line and arc segments.
 
-**Properties:**
+Use `Curve.Route.fromPolyline()` when you know the virtual design skeleton points and bend radius. ForgeCAD computes tangent trim points, bend arcs, total length, and named start/end port frames. Pass the route directly to `sweep()`.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `radius` | `number` | — |
-| `pitch` | `number` | — |
-| `turns` | `number` | — |
-| `height` | `number` | — |
-| `startAngle` | `number` | — |
-| `clockwise` | `boolean` | — |
+```js
+const route = Curve.Route.fromPolyline(
+  [[0, 0, 0], [0, 0, 80], [60, 0, 80]],
+  { cornerRadius: 24, startPort: "inlet", endPort: "outlet" },
+);
+const pipe = sweep(difference2d(circle2d(8), circle2d(6)), route);
+const outlet = route.port("outlet");
+```
 
-**Methods:**
+#### `fromPolyline()` — Build a line/arc route from virtual polyline corner points.
 
-#### `pointAt()`
+```ts
+static fromPolyline(points: Route3DVec3[], options?: Route3DFromPolylineOptions): Route3D
+```
+
+**`Route3DFromPolylineOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `cornerRadius?` | `number` | Bend radius applied to every virtual interior corner. Default 0 keeps sharp polyline corners. |
+| `startPort?` | `string` | Name for the start port. Default "start". |
+| `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.
 
 ```ts
-pointAt(t: number): Vec3
+get length(): number
 ```
 
-#### `tangentAt()`
+#### `segments()` — Exact line and arc segments that make up this route.
 
 ```ts
-tangentAt(t: number): Vec3
+get segments(): Route3DSegment[]
 ```
 
-#### `sample()`
+#### `ports()` — Named port frames, keyed by port name.
 
 ```ts
-sample(count?: number): Vec3[]
+get ports(): Record<string, RoutePortFrame>
 ```
 
-#### `length()`
+#### `port()` — Return one named route port frame.
 
 ```ts
-length(): number
+port(name: string): RoutePortFrame
 ```
 
+#### `toSweepPathPlan()` — Convert this route to the compile plan consumed by sweep().
+
+```ts
+toSweepPathPlan(): SweepPathCompilePlan
+```
+
+#### `toPolyline()` — Sample this analytic route as a polyline for inspection or backend lowering.
+
+```ts
+toPolyline(options?: number | Route3DToPolylineOptions): Route3DVec3[]
+```
+
+**`Route3DToPolylineOptions`**
+- `samples?: number` — Approximate target point count for the full route.
+- `maxAngleDeg?: number` — Maximum angular spacing on arc segments. Default 6 degrees.
+
 ### `NurbsCurve3D`
 
 **Properties:**
@@ -993,120 +997,6 @@ toPolyline(): [ number, number ][]
 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:**
-
-#### `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[]
-```
-
 ### `ProductSkin`
 
 **Properties:**
@@ -1539,7 +1429,6 @@ attachTo(ref: ProductRefInput, options?: ProductPanelAttachOptions): Shape
 
 `ProductSurfaceRef`
 
-
 `ProductPanelAttachOptions`: `{ at?: Partial<ProductSkinRefQuery>, thickness?: number, material?: ProductMaterial, color?: string }`
 
 ### `ProductRibbonBuilder`
@@ -1863,6 +1752,8 @@ bottom(options?: { angle?: number; offset?: number; }): SurfaceAnchor<CylinderSu
 pointAt(coordinate: CylinderSurfaceCoordinate): Vec3
 ```
 
+`CylinderSurfaceCoordinate`: `{ kind?: "cylinder", angle: number, z: number, offset?: number }`
+
 #### `mirrorPoint()`
 
 ```ts
@@ -1982,6 +1873,8 @@ bottom(options?: { x?: number; offset?: number; }): SurfaceAnchor<PlaneSurfaceCo
 pointAt(coordinate: PlaneSurfaceCoordinate): Vec3
 ```
 
+`PlaneSurfaceCoordinate`: `{ kind?: "plane", x: number, y: number, offset?: number }`
+
 #### `mirrorPoint()`
 
 ```ts
@@ -2266,6 +2159,8 @@ boundaries(samples?: number): SurfaceBandBoundarySample[]
 withHole(name: string, input: SurfaceBandHoleInput): SurfaceBand<C>
 ```
 
+`SurfaceBandHoleInput`: `{ length: number, width: number, along?: number, across?: number }`
+
 #### `holes()` — Resolve recorded hole regions into member-local across/along loops.
 
 ```ts
@@ -2288,6 +2183,8 @@ holes(): SurfaceBandHoleRegion[]
 carrier(carrier: CarrierSurface): this
 ```
 
+`CarrierSurface`: `{ name: string, kind: SurfaceCarrierKind }`
+
 #### `member()`
 
 ```ts
@@ -2332,6 +2229,8 @@ band(): this
 at(anchor: SurfaceAnchor<C>): this
 ```
 
+`SurfaceAnchor`: `{ carrier: CarrierSurface<C>, coordinate: C }`
+
 #### `size()`
 
 ```ts
@@ -2350,6 +2249,10 @@ path(path: SurfacePath<C> | SurfacePathBuilder<C>): this
 section(section: MemberSectionInput): this
 ```
 
+**`MemberSectionInput`**: `width?: number`, `thickness: number`, `edgeRadius?: number`, `direction?: MemberOutwardDirection`, `material?: ProductMaterial`, `stations?: MemberSectionStation[]`
+
+`MemberSectionStation`: `{ t: number, width?: number, thickness?: number }`
+
 #### `cap()`
 
 ```ts
@@ -2362,6 +2265,8 @@ cap(style: SurfaceBandCap): this
 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
@@ -2486,6 +2391,25 @@ toFeature(name?: string): MemberFeature
 
 ## Constants
 
+### `Curve`
+
+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.
+
 ### `Surface`
 
 - `Plane(options: SurfacePlaneOptions): Shape` — Create a finite analytic plane sheet that can be trimmed, sewn, thickened, or used as a low-level face.
@@ -2567,17 +2491,3 @@ toFeature(name?: string): MemberFeature
 ### `Ribs`
 
 - `repeated(input: { count: number; height: number; }): MemberFeature` — Create repeated ribs that belong to a surface member before lowering.
-
-### `Helix`
-
-Helical curve helpers.
-
-```ts
-const guide = Helix.path({ radius: 20, pitch: 6, turns: 4 });
-const wire = Helix.coil({ radius: 20, pitch: 6, turns: 4, wireRadius: 1 });
-const rectangular = Helix.coil(rect(2, 1), { radius: 20, height: 30, turns: 5 });
-```
-
-- `path(options: HelixOptions): HelixCurve` — Create a metadata-bearing helical centerline around the Z axis.
-- `coil(options: HelixCoilOptions): Shape` — Create a solid helical coil by sweeping a circular profile through helix-local frames.
-- `coil(profile: Sketch, options: HelixCoilOptions): Shape` — Create a solid helical coil by sweeping a profile through helix-local frames.