forgecad 0.10.3 → 0.10.5

package/dist-skill/CONTEXT.md

@@ -135,18 +135,18 @@ activateBackend, Analysis, arcSlot, assembly, Assembly, Blend, bom, box
 cameraTrajectory, Carrier, chamfer, circle2d, Circle2D, circularLayout, circularPattern, circularPattern2d
 coalesceEdges, compareWith, connector, console, constrainedSketch, Curve, Curve3D, cutPlane
 cylinder, difference, difference2d, dim, draft, ellipse, explodeView, faceProfile
-fillet, Function, gcode, GCodeBuilder, getActiveBackend, global, globalThis, group
-Import, ImportedAssembly, initKernel, intersection, intersection2d, intersectWithPlane, joint, Laser
-lib, Line2D, linearPattern, linearPattern2d, loadFont, loft, Loft, mirrorCopy
-mock, ngon, NurbsCurve3D, NurbsSurface, offsetSolid, param, Param, path
-Point2D, Points, polygon, polygonVertices, port, Product, ProductPanelBuilder, ProductRibbonBuilder
-ProductSkin, ProductSkinBuilder, ProductStationBuilder, ProductSurfaceBuilder, ProductSurfaceRef, projectToPlane, queueMicrotask, rect
-Rectangle2D, roundedRect, Route3D, scene, Sculpt, sdf, SdfShape, selectEdge
-selectEdges, self, setActiveBackend, setImmediate, setInterval, setTimeout, Shape, ShapeGroup
-sheetMetal, SheetMetalPart, sheetStock, Sim, Sketch, sketchToDxf, sketchToSvg, slot
-SolvedAssembly, spec, sphere, spline2d, stroke, Surface, SurfaceBody, SurfaceMembers
-sweep, text2d, textWidth, torus, toShape, Transform, union, union2d
-variableSweep, verify, Viewport, window, Wood
+Fea, fillet, Function, gcode, GCodeBuilder, getActiveBackend, global, globalThis
+group, Import, ImportedAssembly, initKernel, intersection, intersection2d, intersectWithPlane, joint
+Laser, lib, Line2D, linearPattern, linearPattern2d, loadFont, loft, Loft
+mirrorCopy, mock, ngon, NurbsCurve3D, NurbsSurface, offsetSolid, param, Param
+path, Point2D, Points, polygon, polygonVertices, port, Product, ProductPanelBuilder
+ProductRibbonBuilder, ProductSkin, ProductSkinBuilder, ProductStationBuilder, ProductSurfaceBuilder, ProductSurfaceRef, projectToPlane, queueMicrotask
+rect, Rectangle2D, roundedRect, Route3D, scene, Sculpt, sdf, SdfShape
+selectEdge, selectEdges, self, setActiveBackend, setImmediate, setInterval, setTimeout, Shape
+ShapeGroup, sheetMetal, SheetMetalPart, sheetStock, Sim, Sketch, sketchToDxf, sketchToSvg
+slot, SolvedAssembly, spec, sphere, spline2d, stroke, Surface, SurfaceBody
+SurfaceMembers, sweep, text2d, textWidth, torus, toShape, Transform, union
+union2d, variableSweep, verify, Viewport, window, Wood, Wrap
 ```
 
 `showLabels` is also a runtime global, but it is not part of the top-level collision check. Avoid reusing it unless you intentionally want a local value with that name.
@@ -170,13 +170,12 @@ variableSweep, verify, Viewport, window, Wood
 - [Grouping & Local Coordinates](#grouping-local-coordinates)
 - [Section & Projection](#section-projection)
 - [Verification](#verification)
-- [Shape](#shape) — Appearance, Face Topology, Edge Topology, Transforms, Booleans & Cutting, Features, Placement, Connectors, References, Measurement
+- [Shape](#shape) — Freeform Construction, Appearance, Face Topology, Edge Topology, Transforms, Booleans & Cutting, Features, Placement, Connectors, References, Measurement
 - [Transform](#transform)
 - [ShapeGroup](#shapegroup) — Children, Transforms, Placement, Connectors, References
 - [SurfacePattern](#surfacepattern)
 - [Pattern2D](#pattern2d)
 - [Pattern2DBuilder](#pattern2dbuilder)
-- [Sheet](#sheet)
 - [CurveNetBuilder](#curvenetbuilder)
 - [MatchEdgeBuilder](#matchedgebuilder)
 - [BridgeBuilder](#bridgebuilder)
@@ -186,6 +185,7 @@ variableSweep, verify, Viewport, window, Wood
 - [Points](#points)
 - [connector](#connector)
 - [Import](#import)
+- [Wrap](#wrap)
 
 ## Functions
 
@@ -856,6 +856,96 @@ Supports transforms (translate, rotate, scale, mirror, transform, rotateAround,
 |----------|------|-------------|
 | `materialProps` | `ShapeMaterialProps \| undefined` | — |
 
+**Freeform Construction**
+
+#### `slicePerpendicularToX(x: number, profile: Sketch, options?: FromSlicesAxisSliceOptions): FromSlicesSlice` — Create a slice descriptor perpendicular to the X axis.
+
+The profile is drawn in the YZ plane. `options.center` is `[y, z]`, so authors can place changing section centers without manually translating sketches in ForgeCAD's internal plane axes.
+
+```js
+Shape.fromSlices([
+  Shape.slicePerpendicularToX(-20, ellipse(10, 2), { center: [0, 3] }),
+  Shape.slicePerpendicularToX(20, ellipse(8, 1.5), { center: [0, 6] }),
+]);
+```
+
+**`FromSlicesAxisSliceOptions`**
+- `center?: FromSlicesVec2` — Plane-local profile center. XY uses [x, y], XZ uses [x, z], YZ uses [y, z].
+
+#### `slicePerpendicularToY(y: number, profile: Sketch, options?: FromSlicesAxisSliceOptions): FromSlicesSlice` — Create a slice descriptor perpendicular to the Y axis.
+
+The profile is drawn in the XZ plane. `options.center` is `[x, z]`.
+
+#### `slicePerpendicularToZ(z: number, profile: Sketch, options?: FromSlicesAxisSliceOptions): FromSlicesSlice` — Create a slice descriptor perpendicular to the Z axis.
+
+The profile is drawn in the XY plane. `options.center` is `[x, y]`.
+
+#### `sliceThrough(center: FromSlicesVec3, normal: FromSlicesVec3, profile: Sketch): FromSlicesSlice` — Create a slice descriptor through a world point with an arbitrary plane normal.
+
+The profile origin lands at `center`. Use this when the section plane is not one of the world XY/XZ/YZ planes.
+
+#### `sliceOnFrame(frame: FromSlicesFrameInput, profile: Sketch): FromSlicesSlice` — Create a slice descriptor on a full 3D work frame.
+
+Sheet frame helpers return the right shape for `frame`. Use `Sheet.frameAt()` for tangent construction planes, or `Sheet.framePerpendicularToU()` / `Sheet.framePerpendicularToV()` for cross-sections normal to a surface path. On the Manifold backend, framed slices are lofted in input order when every slice comes from a frame.
+
+**`FromSlicesFrameInput`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `point?` | `FromSlicesVec3` | World-space frame origin. Sheet frame helpers return this as `point`. |
+| `origin?` | `FromSlicesVec3` | Alias for `point` when using generic CAD frame terminology. |
+| `normal` | `FromSlicesVec3` | World-space frame normal. |
+| `tangentU?` | `FromSlicesVec3` | World-space direction for the profile's local X axis. Sheet frame helpers return this as `tangentU`. |
+| `tangentV?` | `FromSlicesVec3` | Optional world-space direction for the profile's local Y axis. Sheet frame helpers return this as `tangentV`. |
+| `xAxis?` | `FromSlicesVec3` | Alias for `tangentU`. |
+| `yAxis?` | `FromSlicesVec3` | Alias for `tangentV`. |
+
+#### `fromSlices(slices: FromSlicesSlice[], options?: FromSlicesOptions): Shape` — Construct a 3D shape from cross-section slices on one or more planes.
+
+On the Manifold backend, slices created with `Shape.sliceOnFrame()` are lofted in their input order while preserving each full 3D frame. Other slices with the same normal direction are lofted together. Slices with different normals are combined via smooth radial blending — each silhouette constrains the shape's extent, producing smooth ellipsoidal cross-sections.
+
+```js
+// Egg from two orthogonal silhouettes
+const eggProfile = ellipse(15, 25);
+return Shape.fromSlices([
+  { on: 'xz', at: 0, profile: eggProfile },
+  { on: 'yz', at: 0, profile: eggProfile },
+]);
+```
+
+```js
+// Vase with cross-section transitions
+return Shape.fromSlices([
+  Shape.slicePerpendicularToZ(0, circle2d(20)),
+  Shape.slicePerpendicularToZ(40, rect(25, 25)),
+  Shape.slicePerpendicularToZ(80, circle2d(8)),
+  Shape.slicePerpendicularToY(0, vaseOutline),
+]);
+```
+
+**`FromSlicesSlice`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `on` | `SlicePlane` | Plane normal: axis name or arbitrary unit vector. |
+| `at?` | `number` | Signed offset along the normal from the origin. Omit when `center` defines the plane. |
+| `center?` | `FromSlicesVec3` | World-space point where the 2D profile origin should land on the slice plane. |
+| `profile` | `Sketch` | 2D cross-section profile on that plane. |
+| `frame?` | `FromSlicesFramePlacement` | Full 3D section frame, preserved for ordered lofts through rotating planes. |
+
+**`FromSlicesFramePlacement`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `point` | `FromSlicesVec3` | World-space frame origin. |
+| `normal` | `FromSlicesVec3` | World-space section normal. |
+| `tangentU` | `FromSlicesVec3` | World-space direction for the profile's local X axis. |
+| `tangentV` | `FromSlicesVec3` | World-space direction for the profile's local Y axis. |
+
+**`FromSlicesOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing (Manifold only).
+- `boundsPadding?: number` — Extra bounding-box padding (Manifold only).
+
 **Appearance**
 
 #### `color(value: string | undefined): Shape` — Set the color of this shape (hex string, e.g. "#ff0000"). Returns a new Shape with the color applied.
@@ -893,6 +983,7 @@ box(100, 100, 10).color('#gold').material({ metalness: 0.95, roughness: 0.05 }).
 | `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
 | `specularColor?` | `string` | Specular highlight tint. |
 | `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
+| `texture?` | `{ image: string; projection: UvProjectionSpec; ...` | Projected bitmap texture set by `Shape.wrapTexture`. `image` is a self-contained `data:` URI; `projection` maps each vertex's final world position to (u,v) in the shader, so the texture survives transforms and boolean cuts. `imageWidth`/`imageHeight` are the intrinsic pixel dimensions. |
 
 **Face Topology**
 
@@ -1241,6 +1332,22 @@ Overloads:
 
 **Other**
 
+#### `wrapTexture(image: ImageHandle, projection: UvProjectionSpec): Shape` — Wrap an imported bitmap image around this shape using a projection.
+
+The `image` comes from `Import.image('path.png')`; the `projection` is one of the `Wrap.*` helpers — `Wrap.flat({ onto: 'top' })` lays it flat on a face, `Wrap.aroundCylinder({ axis: 'z' })` wraps it like a can label, `Wrap.onSphere()` maps it like a globe, and `Wrap.box()` cube-maps it onto the six sides.
+
+By default the image **auto-fits** the shape — one copy across the relevant extent, so no `width`/`height`/`size` is needed (pass them only to override). The (u,v) is derived from each vertex's final world position, so the image stays glued to the surface through transforms and boolean cuts with no UV layout to maintain — apply `wrapTexture` *after* positioning the shape. Returns a new Shape; the original is unchanged.
+
+```js
+const logo = Import.image('./logo.png');
+box(80, 80, 10).wrapTexture(logo, Wrap.flat({ onto: 'top' }));            // auto-fits the face
+
+const label = Import.image('./label.jpg');
+cylinder(60, 20).wrapTexture(label, Wrap.aroundCylinder({ axis: 'z' }));  // wraps the side
+```
+
+`ImageHandle`: `{ __forgeImage: true, dataUri: string, width: number, height: number, mimeType: string, byteLength: number }`
+
 #### `clone(): Shape` — Return a new Shape wrapper for explicit duplication in scripts.
 
 #### `geometryInfo(): GeometryInfo` — Inspect which backend/representation produced this solid.
@@ -1489,57 +1596,106 @@ const bracket = group(
 | `depth?` | `number` | Thread groove depth in millimeters. Default: 0.8. |
 | `underScale?` | `number` | Relative height of the under-crossing thread. Default: 0.15. |
 
-### `Sheet`
+### `CurveNetBuilder`
 
-A parametric open surface value (control grid + knots + analytic differential geometry).
+#### `alongRails(railA: CurveInput, railB: CurveInput): this` — Use two lengthwise boundary curves as guide rails.
 
-**Properties:**
+Chain `.sections(...)` to create a bi-rail surface: the rails define the sheet edges while each section curve shapes the cross-span at its station.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `surface` | `BSplineSurface` | — |
+#### `sections(...curves: CurveInput[]): this` — Add crosswise section curves.
 
-**Methods:**
+By itself this skins the sections into a surface. After `.alongRails(...)`, the sections are fitted between the two rails so the surface follows both the boundary guide curves and the section profiles.
 
-#### `get frontEdge(): SheetEdge` — Edge naming follows parameter direction (documented): front=v0, rear=v1, left=u0, right=u1.
+#### `resolution(samples: number): this` — Set the sampling resolution used to build curve-family surface grids.
 
-#### `thicken(wall: number, options?: { resolution?: number; }): Shape` — Offset the sheet along its analytic normals into a watertight solid shell of the given wall thickness. Throws if the wall would self-intersect on a concave region (no silent degenerate solid).
+This affects `.lengthwise(...)`, `.crosswise(...)`, and `.alongRails(...).sections(...)` surfaces. It does not resample explicit `.cage(grid)` input because the cage already is the authored control net.
 
-#### `matchEdge(edge: SheetEdge): MatchEdgeBuilder` — Per-edge continuity match against a neighbor (returns a NEW Sheet).
+#### `matchStartU(condition: BoundaryCondition): this` — Enforce a continuity condition on the `u = 0` (left) boundary.
+
+Pass `{ edge }` to match an adjacent sheet's tangent (G1) or curvature (G2), or `{ tangent }` to impose an explicit cross-boundary direction. See `BoundaryCondition`.
+
+**`BoundaryCondition`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `edge?` | `SheetEdge` | Match the tangent (G1) and curvature (G2) of an existing sheet edge across this boundary. |
+| `tangent?` | `Vec3` | Or impose an explicit cross-boundary tangent direction in world space (auto-normalized). |
+| `tangentScale?` | `number` | Scalar magnitude for the imposed `tangent` ramp, in model units. Ignored when `edge` is given. Default: the local cross-boundary control-span length (chord-scaled), so the imposed tangent has the same strength as the surface already carries — no magic number. |
+| `continuity?` | `0 \| 1 \| 2` | Continuity order to enforce on this side. Default inferred: 1 if a tangent or edge is given, else 0. G2 (curvature) requires an `edge` to copy the neighbor's second difference. |
 
 **`SheetEdge`**
 - `fixed: "u" | "v"` — Which parameter is held fixed along this edge.
 - `value: 0 | 1` — The fixed value (0 or 1).
 - Also: `sheet: Sheet`.
 
-- `get rearEdge(): SheetEdge`
-- `get leftEdge(): SheetEdge`
-- `get rightEdge(): SheetEdge`
-- `pointAt(u: number, v: number): Vec3`
-- `normalAt(u: number, v: number): Vec3`
-- `curvatureAt(u: number, v: number): SurfaceCurvature`
+#### `matchEndU(condition: BoundaryCondition): this` — Enforce a continuity condition on the `u = 1` (right) boundary. See `matchStartU`.
 
-### `CurveNetBuilder`
+#### `matchStartV(condition: BoundaryCondition): this` — Enforce a continuity condition on the `v = 0` (front) boundary. See `matchStartU`.
+
+#### `matchEndV(condition: BoundaryCondition): this` — Enforce a continuity condition on the `v = 1` (rear) boundary. See `matchStartU`.
+
+#### `closedU(): this` — Weld the two ends of the U direction into a tangent-continuous periodic loop, so the `u = 0` and `u = 1` boundaries coincide with NO G0 kink (a closed tube/ring in U — e.g. a bowl's around-rim seam). The cage's first and last U rows must already be coincident (the loop must close in position).
+
+#### `closedV(): this` — Weld the two ends of the V direction into a tangent-continuous periodic loop. See `closedU`.
 
 #### `toSheet(): Sheet` — Build (once) and return the Sheet.
 
 - `lengthwise(...curves: CurveInput[]): this`
 - `crosswise(...curves: CurveInput[]): this`
-- `alongRails(railA: CurveInput, railB: CurveInput): this`
-- `sections(...curves: CurveInput[]): this`
 - `cage(grid: Vec3[][]): this`
 - `degree(u: number, v: number): this`
 - `get frontEdge(): SheetEdge`
 - `get rearEdge(): SheetEdge`
 - `get leftEdge(): SheetEdge`
 - `get rightEdge(): SheetEdge`
+- `get frontCurve(): NurbsCurve3D`
+- `get rearCurve(): NurbsCurve3D`
+- `get leftCurve(): NurbsCurve3D`
+- `get rightCurve(): NurbsCurve3D`
 - `get surface(): BSplineSurface`
 - `pointAt(u: number, v: number): Vec3`
 - `normalAt(u: number, v: number): Vec3`
+- `frameAt(u: number, v: number, options?: SheetFrameOptions): SheetFrame`
+- `framePerpendicularToU(u: number, v: number, options?: SheetFrameOptions): SheetFrame`
+- `framePerpendicularToV(u: number, v: number, options?: SheetFrameOptions): SheetFrame`
 - `curvatureAt(u: number, v: number): SurfaceCurvature`
+- `curveAlong(edge: SheetEdge): NurbsCurve3D`
+- `curveAlongU(v: number): NurbsCurve3D`
+- `curveAlongV(u: number): NurbsCurve3D`
+- `pathAlong(edge: SheetEdge, options?: SheetPathAlongOptions): Vec3[]`
+- `pathAlongBoundary(spans: SheetBoundaryPathSpan[], options?: SheetBoundaryPathOptions): Vec3[]`
+- `pathAlongU(v: number, options?: SheetPathAlongOptions): Vec3[]`
+- `pathAlongV(u: number, options?: SheetPathAlongOptions): Vec3[]`
 - `thicken(wall: number, options?: { resolution?: number; }): Shape`
 - `matchEdge(edge: SheetEdge): MatchEdgeBuilder`
 
+**`SheetFrameOptions`**
+- `normalOffset?: number` — Offset the frame origin along the analytic surface normal. Default 0.
+
+**`SheetPathAlongOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `samples?` | `number` | Samples along the path span. Default 32. |
+| `start?` | `number` | Normalized start parameter along the path. Default 0. |
+| `end?` | `number` | Normalized end parameter along the path. Default 1. |
+| `reverse?` | `boolean` | Return points from end to start after sampling the span. Default false. |
+| `normalOffset?` | `number` | Offset each path point along the analytic surface normal. Default 0. |
+
+**`SheetBoundaryPathSpan`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `edge` | `SheetEdge` | Boundary edge to sample for this span. |
+| `start?` | `SheetPathParameter` | Normalized edge parameter or world point projected to the closest edge parameter. Default 0. |
+| `end?` | `SheetPathParameter` | Normalized edge parameter or world point projected to the closest edge parameter. Default 1. |
+| `samples?` | `number` | Samples along this edge span. Defaults to options.samplesPerEdge or 32. |
+
+**`SheetBoundaryPathOptions`**
+- `samplesPerEdge?: number` — Samples for spans that do not specify their own count. Default 32.
+- `normalOffset?: number` — Offset each path point along the analytic surface normal. Default 0.
+- `tolerance?: number` — Maximum allowed gap between adjacent sampled spans. Default 1e-6.
+
 ### `MatchEdgeBuilder`
 
 - `toG0(neighbor: SheetEdge): Sheet`
@@ -1646,6 +1802,14 @@ Namespaced file-format import helpers — the single vocabulary for bringing ext
   const yUpPart = Import.mesh("./part.obj", { sourceFrame: { up: "+Y" } });
   ```
 - `step(fileName: string, options?: StepImportOptions): Shape` — Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires running with the OCCT backend. Use `sourceFrame: { up: "+Y" }` to rotate Y-up source files into ForgeCAD's Z-up world.
+- `image(fileName: string): ImageHandle` — Import a bitmap image (PNG, JPEG, or WebP) as an ImageHandle for projected texturing. Reads the pixel dimensions from the file header and embeds the bytes as a data URI. Pass the result to `Shape.wrapTexture(image, projection)` with a `Wrap.*` projection.
+
+### `Wrap`
+
+- `flat(opts: FlatWrapOptions): UvProjectionSpec` — Project the image flat onto an axis-aligned face — `onto` is one of top/bottom/front/back/left/right. Auto-fits the face (no width/height needed).
+- `aroundCylinder(opts: CylinderWrapOptions): UvProjectionSpec` — Wrap the image around a cylinder like a can label — `axis` is 'x' | 'y' | 'z'. Auto-fits one wrap around and the full height.
+- `onSphere(opts?: SphereWrapOptions): UvProjectionSpec` — Map the image over a sphere like a globe (longitude/latitude). Auto-centers on the sphere.
+- `box(opts?: BoxWrapOptions): UvProjectionSpec` — Cube-map the image onto a box — one copy per face. Auto-fits the box (no size needed).
 
 ---
 
@@ -2100,7 +2264,22 @@ donut.region([40, 0]).extrude(10); // seed at radius 40, inside the ring
 
 **Promotion**
 
-#### `extrude(height: number, opts?: { twist?: number; divisions?: number; scaleTop?: number | Vec2; }): Shape` — Extrude this 2D sketch along Z to create a 3D solid. Supports twist and scale tapering.
+#### `extrude(extent: number | EndCondition, opts?: { twist?: number; divisions?: number; scaleTop?: number | Vec2; }): Shape` — Extrude this 2D sketch along Z to create a 3D solid. Supports twist and scale tapering. The extent may be a numeric height or an `EndCondition` (up to a face, plane, or vertex).
+
+**`EndCondition`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `upToFace?` | `FaceRef \| SketchFaceTarget` | Terminate flush with a planar face perpendicular to the feature direction. |
+| `upToPlane?` | `PlaneOp` | Terminate at an arbitrary plane (ray-plane intersection along the direction). |
+| `upToVertex?` | `Vec3` | Terminate at the plane through this point, perpendicular to the direction. |
+| `offset?` | `number` | Signed offset PAST the resolved surface in the travel direction (default 0). |
+
+`FaceRef` — defined in [core](/docs/core).
+
+**`PlaneOp`**
+- `normal: Vec3` — Plane normal. Need not be unit length; it is normalized internally.
+- `offset?: number` — Signed offset of the plane along its normal from the world origin (default 0).
 
 #### `revolve(degrees?: number, segments?: number): Shape` — Revolve this 2D sketch around the world Z axis. Sketch X is radius; sketch Y becomes world Z height. Keep the profile at X > 0 unless it intentionally touches the axis.
 
@@ -2121,8 +2300,6 @@ const shifted = rect(4, 70).attachTo(plate, 'bottom-left', 'top-left', [5, 0]);
 
 Use this when a 2D profile should be oriented onto a 3D face before extrusion or other downstream operations.
 
-`FaceRef` — defined in [core](/docs/core).
-
 **Labels**
 
 #### `labelEdge(name: string): Sketch` — Label the single boundary edge (for circles, single-loop profiles). Returns a new sketch.
@@ -2683,6 +2860,7 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 - [Route3D](#route3d)
 - [NurbsCurve3D](#nurbscurve3d)
 - [NurbsSurface](#nurbssurface)
+- [Sheet](#sheet)
 - [PathBuilder](#pathbuilder) — Line Segments, Arcs, Curves, Closing & Output
 - [ProductSkin](#productskin)
 - [ProductSurfaceRef](#productsurfaceref)
@@ -2745,6 +2923,34 @@ const rail = Curve.BlendG2(
 **`CurveBlendG2Endpoint`** extends CurveBlendEndpoint
 - `curvature?: Vec3` — Optional endpoint curvature/second-derivative vector. Default is zero.
 
+#### `Curve.Bridge(options: CurveBridgeOptions): NurbsCurve3D` — Bridge two existing curve endpoints with inferred tangent or curvature continuity.
+
+This is the Onshape-style "select two curves and bridge them" primitive: ForgeCAD reads the endpoint positions, tangent directions, and NURBS curvature from the selected curves so callers do not hand-author tangent vectors. Use `continuity: 'G1'` for a cubic tangent bridge or the default `G2` for a quintic curvature bridge.
+
+```js
+const leftRim = Curve.Fit([[20, -12, 0], [0, -18, 2], [-30, -14, 1]]);
+const rightRim = Curve.Fit([[20, 12, 0], [0, 18, 2], [-30, 14, 1]]);
+const roundedNose = Curve.Bridge({
+  from: { curve: leftRim, at: 'end' },
+  to: { curve: rightRim, at: 'end' },
+  continuity: 'G2',
+});
+```
+
+**`CurveBridgeOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `from` | `CurveBridgeEndpoint` | Endpoint where the bridge starts. |
+| `to` | `CurveBridgeEndpoint` | Endpoint where the bridge ends. |
+| `continuity?` | `CurveBridgeContinuity` | Continuity target. Default `G2`. |
+| `weight?` | `number` | Tangent reach relative to bridge chord. Default 0.6. |
+
+**`CurveBridgeEndpoint`**
+- `curve: CurveTrimInput` — Existing curve endpoint to bridge from or to.
+- `at?: CurveBridgeEndpointAt` — Which endpoint of the curve to use. Default is `end`.
+- `weight?: number` — Tangent reach relative to bridge chord. Overrides `CurveBridgeOptions.weight` for this side.
+
 #### `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.
@@ -2809,6 +3015,52 @@ const loop = Curve.Fit(
 - `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.ProjectOnSurface(curve: NurbsCurve3D | Vec3[], sheet: Sheet, options?: CurveProjectOnSurfaceOptions): NurbsCurve3D` — Project a curve onto a `Sheet` along the surface normal and return the exact NURBS foot curve.
+
+This is the "drape a curve onto a surface" primitive: each sampled point of the source curve is inverted onto the sheet (closest surface point via the analytic jet), and the foot points are fitted with `Curve.Fit`. Use it to trace a planned trim line, seam, or graphic onto a freeform panel, then sweep or trim from the real on-surface curve.
+
+The source may be an exact `NurbsCurve3D` or a `Vec3[]` polyline (for example a placed 2D path). With `{ closed: true }` the result is a periodic loop, for draping a closed boundary onto the sheet. Set `maxGap` to require that every sample lands within a distance of the surface; the call throws if any sample misses (no silent fallback).
+
+```js
+const panel = Surface.Net().cage(cage);
+const guide = Curve.Line([-20, 0, 30], [20, 0, 30]);
+const seam = Curve.ProjectOnSurface(guide, panel);
+const bead = sweep(circle2d(0.6), seam);
+```
+
+**`CurveProjectOnSurfaceOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `samples?` | `number` | Coarse samples taken along the source curve before per-sample projection. Default 64. |
+| `refineIterations?` | `number` | Newton refinement iterations of the (u, v) foot-point per sample. Default 8. |
+| `tolerance?` | `number` | Interpolation tolerance passed to Curve.Fit for the result. Default 1e-4. |
+| `closed?` | `boolean` | Fit a closed periodic loop (use when the source curve is a closed loop). Default false. |
+| `maxGap?` | `number` | Max allowed projection gap; throws if any sample lands farther than this from the surface foot. Default Infinity (no gate). |
+
+#### `Curve.Intersect(sheetA: Sheet, sheetB: Sheet, options?: CurveIntersectOptions): NurbsCurve3D[]` — Intersect two `Sheet` surfaces and return the exact NURBS intersection branches.
+
+This is curve-following surface-surface intersection (SSI): a transversal marcher follows each intersection branch using the analytic surface jets (the intersection tangent is `cross(normalA, normalB)`), converging every step onto both surfaces, then fits each branch with `Curve.Fit`. A single pair of sheets can intersect in several disjoint curves, so the result is an array (empty when the sheets do not meet).
+
+Only transversal intersections (where the surfaces cross and the intersection tangent `cross(normalA, normalB)` is well defined) are detected. A tangential / grazing contact (where the surface normals are parallel and the tangent is undefined) is not marched and may be reported as no-intersection (an empty array) — tangential SSI is a documented follow-on, not a silent fallback.
+
+```js
+const wing = Surface.Net().cage(wingCage);
+const rib = Surface.Net().cage(ribCage);
+const [seam] = Curve.Intersect(wing, rib);
+const weld = sweep(circle2d(0.5), seam);
+```
+
+**`CurveIntersectOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `samples?` | `number` | Grid resolution per axis for seeding the marcher (samples x samples on sheetA). Default 48. |
+| `step?` | `number` | Marching step as a fraction of sheetA's average sample spacing. Default 0.5. |
+| `refineIterations?` | `number` | Newton iterations to converge each marched point onto both surfaces. Default 12. |
+| `tolerance?` | `number` | Convergence/coincidence tolerance in model units. Default 1e-4. |
+| `fitTolerance?` | `number` | Fit tolerance passed to Curve.Fit. Default 1e-3. |
+
 #### `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.
@@ -2817,6 +3069,67 @@ const loop = Curve.Fit(
 
 `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.
 
+#### `Curve.closestParameter(curve: CurveClosestParameterInput, point: Vec3, options?: CurveClosestParameterOptions): number` — Find the normalized parameter on an exact curve closest to a world point.
+
+This is the query companion to `Curve.Trim()`: use it to locate where a construction point lands on an existing rail, surface boundary, or edge curve, then trim/sweep from that real geometric station instead of copying the original construction points.
+
+`NurbsCurve3D` inputs are searched by curve parameter with coarse sampling plus local refinement. Polyline point arrays are projected onto their exact line segments and return an arclength-normalized parameter.
+
+```js
+const start = Curve.closestParameter(sheet.frontCurve, [-20, -12, 4]);
+const end = Curve.closestParameter(sheet.frontCurve, [20, -12, 4]);
+const rimRail = Curve.Trim(sheet.frontCurve, start, end);
+```
+
+**`CurveClosestParameterOptions`**
+- `samples?: number` — Coarse samples before local refinement. Default 96.
+
+#### `Curve.join(curves: CurveJoinInput[], options?: CurveJoinOptions): Vec3[]` — Join touching curve segments into one sampled sweep path.
+
+This is the composite-curve primitive for downstream features that need to follow several real edges as one path: rolled rims, seam beads, trim strips, weld beads, and surface-boundary inlays. ForgeCAD validates that adjacent segment endpoints touch; it will not silently reverse or bridge gaps.
+
+```js
+const rimPath = Curve.join([
+  Curve.Reverse(Curve.Trim(sheet.frontCurve, 0, u)),
+  sheet.leftCurve,
+  Curve.Trim(sheet.rearCurve, 0, u),
+]);
+const rim = sweep(ellipse(0.8, 0.35), rimPath);
+```
+
+**`CurveJoinOptions`**
+- `samples?: number` — Points sampled per exact curve segment. Default 32.
+- `tolerance?: number` — Maximum allowed gap between adjacent segment endpoints. Default 1e-6.
+
+#### `Curve.placeOnXY(path: CurvePath2D, z?: number, options?: CurvePathPlacementOptions): Vec3[]` — Place a 2D path onto the XY plane at world Z.
+
+The returned 3D point array can feed `Surface.Net`, `Curve.Fit`, `sweep`, `Curve.Trim`, and any other curve consumer that accepts points.
+
+```js
+const rail = Curve.placeOnXY(path().moveTo(0, 0).bezierTo(30, 8, 60, -4, 90, 0), 12);
+const smoothRail = Curve.Fit(rail);
+```
+
+**`CurvePathPlacementOptions`**
+- `samples?: number` — Optional sample count when [`path`](/docs/sketch#path) is a path-like object.
+
+#### `Curve.placeOnXZ(path: CurvePath2D, y?: number, options?: CurvePathPlacementOptions): Vec3[]` — Place a 2D path onto the XZ plane at world Y.
+
+The path's first coordinate becomes X and the second becomes Z.
+
+#### `Curve.placeOnYZ(path: CurvePath2D, x?: number, options?: CurvePathPlacementOptions): Vec3[]` — Place a 2D path onto the YZ plane at world X.
+
+The path's first coordinate becomes Y and the second becomes Z. This is the direct "sketch cross-sections on offset planes" primitive for surface nets.
+
+#### `Curve.placeOnPlane(path: CurvePath2D, options: CurvePlanePlacementOptions): Vec3[]` — Place a 2D path onto an arbitrary world plane.
+
+`origin` is the 2D sketch origin in world space. `xAxis` and `yAxis` are perpendicular world directions for the local sketch axes.
+
+**`CurvePlanePlacementOptions`** extends CurvePathPlacementOptions
+- `origin: Vec3` — World-space origin of the 2D sketch plane.
+- `xAxis: Vec3` — World-space direction for the sketch X axis.
+- `yAxis: Vec3` — World-space direction for the sketch Y axis.
+
 #### `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.
@@ -2915,7 +3228,7 @@ A closed spline (default) returns a filled profile. An open spline requires a st
 | `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(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape` — Loft between multiple sketches along Z stations.
+#### `loft(profiles: Sketch[], heights: (number | EndCondition)[], 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.
 
@@ -2923,6 +3236,8 @@ The surface is smooth through 3+ stations (C1 spanwise interpolation, like CAD l
 
 Performance note: loft is significantly heavier than primitive/extrude/revolve. If the part is axis-symmetric (bottles, vases, knobs), prefer revolve().
 
+`EndCondition` — defined in [sketch](/docs/sketch).
+
 #### `sweep(profile: Sketch, path: SweepPathInput, options?: SweepOptions): Shape`
 
 **`SweepOptions`**
@@ -3102,6 +3417,91 @@ Uses Algorithm A2.3 basis-function derivatives with the rational quotient rule,
 
 #### `tessellate(resU?: number, resV?: number): { positions: Vec3[]; normals: Vec3[]; indices: number[]; }` — Tessellate the surface into a triangle mesh. Returns positions, normals, and triangle indices.
 
+### `Sheet`
+
+A parametric open surface value (control grid + knots + analytic differential geometry).
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `surface` | `BSplineSurface` | — |
+
+**Methods:**
+
+#### `get frontEdge(): SheetEdge` — Edge naming follows parameter direction (documented): front=v0, rear=v1, left=u0, right=u1.
+
+#### `get frontCurve(): NurbsCurve3D` — Exact curve along the front boundary (`v = 0`).
+
+#### `get rearCurve(): NurbsCurve3D` — Exact curve along the rear boundary (`v = 1`).
+
+#### `get leftCurve(): NurbsCurve3D` — Exact curve along the left boundary (`u = 0`).
+
+#### `get rightCurve(): NurbsCurve3D` — Exact curve along the right boundary (`u = 1`).
+
+#### `curveAlong(edge: SheetEdge): NurbsCurve3D` — Extract an exact NURBS iso-curve from one of this sheet's boundary edges.
+
+Use this when a downstream feature should be driven by the actual sheet boundary, such as a swept rim, seam bead, trim strip, or adjacent blend.
+
+`SheetEdge` — defined in [core](/docs/core).
+
+#### `curveAlongU(vInput: number): NurbsCurve3D` — Extract an exact NURBS iso-curve in the sheet U direction at fixed `v`.
+
+Use this for centerline rails, ribs, beads, and trim features that live on the interior of a freeform sheet instead of on a boundary edge.
+
+#### `curveAlongV(uInput: number): NurbsCurve3D` — Extract an exact NURBS iso-curve in the sheet V direction at fixed `u`.
+
+Use this for cross-surface rails, seam lines, straps, and inspection paths that should be driven by the sheet parameterization rather than global axes.
+
+#### `pathAlong(edge: SheetEdge, options?: SheetPathAlongOptions): Vec3[]` — Sample a world-space path along a sheet boundary edge.
+
+Use this when a downstream feature should follow the real surface edge but does not need to stay an exact NURBS curve, for example a lip, gasket bead, trim strip, weld seam, or inlay lifted off the surface by `normalOffset`.
+
+`SheetPathAlongOptions` — defined in [core](/docs/core).
+
+#### `pathAlongBoundary(spans: SheetBoundaryPathSpan[], options?: SheetBoundaryPathOptions): Vec3[]` — Sample one connected path across ordered sheet boundary edge spans.
+
+This is the composite-boundary primitive for rolled rims, weld beads, gaskets, trim strips, and inlays that follow several sheet edges as one continuous rail. Span `start` / `end` values may be normalized parameters or world points; world points are resolved to the closest point on that edge so callers do not have to manually invoke `Curve.closestParameter()`.
+
+`SheetBoundaryPathSpan` — defined in [core](/docs/core).
+
+`SheetBoundaryPathOptions` — defined in [core](/docs/core).
+
+#### `pathAlongU(vInput: number, options?: SheetPathAlongOptions): Vec3[]` — Sample a world-space path in the sheet U direction at fixed `v`.
+
+Unlike `curveAlongU()`, this can lift points along the analytic normal with `normalOffset`, which is the common path for swept ribs, inlays, and raised details on a freeform carrier surface.
+
+#### `pathAlongV(uInput: number, options?: SheetPathAlongOptions): Vec3[]` — Sample a world-space path in the sheet V direction at fixed `u`.
+
+Use this for lifted cross-surface features where a sampled path is more useful than an exact iso-curve, for example straps, grooves, or probes.
+
+#### `frameAt(uInput: number, vInput: number, options?: SheetFrameOptions): SheetFrame` — Build an orthonormal local work frame on the sheet.
+
+This is the "construct tangent plane/frame on a surface" primitive for downstream sketches, profiles, fixtures, inspection probes, and features that must be oriented from the sheet itself rather than global axes.
+
+`SheetFrameOptions` — defined in [core](/docs/core).
+
+#### `framePerpendicularToU(uInput: number, vInput: number, options?: SheetFrameOptions): SheetFrame` — Build a section work frame perpendicular to the sheet's U direction.
+
+This is the "plane normal to path" primitive for ribs, raised handles, bosses, and other details whose cross-sections should be sketched across a carrier surface while marching along the surface U direction. The returned frame can be passed directly to `Shape.sliceOnFrame()`.
+
+#### `framePerpendicularToV(uInput: number, vInput: number, options?: SheetFrameOptions): SheetFrame` — Build a section work frame perpendicular to the sheet's V direction.
+
+Use this when the guide path runs in the surface V direction and the sketch profile should span the U direction while its height follows the surface normal. The returned frame can be passed directly to `Shape.sliceOnFrame()`.
+
+#### `toShape(options?: { resolution?: number; }): Shape` — Return this open sheet as a renderable surface Shape.
+
+#### `thicken(wall: number, options?: { resolution?: number; }): Shape` — Offset the sheet along its analytic normals into a watertight solid shell of the given wall thickness. Throws if the wall would self-intersect on a concave region (no silent degenerate solid).
+
+#### `matchEdge(edge: SheetEdge): MatchEdgeBuilder` — Per-edge continuity match against a neighbor (returns a NEW Sheet).
+
+- `get rearEdge(): SheetEdge`
+- `get leftEdge(): SheetEdge`
+- `get rightEdge(): SheetEdge`
+- `pointAt(u: number, v: number): Vec3`
+- `normalAt(u: number, v: number): Vec3`
+- `curvatureAt(u: number, v: number): SurfaceCurvature`
+
 ### `PathBuilder`
 
 **Line Segments**
@@ -3796,7 +4196,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.
 
-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`.
+Members (full entries under [Curves & Surfacing](#curves-surfacing)): `Curve.Blend`, `Curve.BlendG2`, `Curve.Bridge`, `Curve.Arc`, `Curve.Line`, `Curve.Nurbs`, `Curve.Fit`, `Curve.ProjectOnSurface`, `Curve.Intersect`, `Curve.Trim`, `Curve.Reverse`, `Curve.closestParameter`, `Curve.join`, `Curve.placeOnXY`, `Curve.placeOnXZ`, `Curve.placeOnYZ`, `Curve.placeOnPlane`, `Curve.Route`, `Curve.Helix`.
 
 ### `Surface`
 
@@ -3805,6 +4205,31 @@ Members (full entries under [Curves & Surfacing](#curves-surfacing)): `Curve.Ble
 - `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.
+- `Sweep(profile: SurfaceSweepProfileInput, spine: SweepPathInput, options?: SurfaceSweepOptions): Sheet` — Sweep an open 2D profile path along a 3D spine to create an open surface sheet.
+
+  This is the surface-first counterpart to the solid `sweep()` function. Use it for class-A/product workflows where the shape starts as an infinitely thin carrier sheet, then becomes physical material with `.thicken(...)`. The profile's local X axis maps across the sheet, local Y maps along the swept frame's up/normal direction, and the spine direction becomes sheet U.
+
+  ```js
+  const sideProfile = Curve.Fit(Curve.placeOnXZ(path().moveTo(0, 0).bezierTo(40, -8, 90, 8, 140, 3)));
+  const crossSection = path().moveTo(-20, 2).bezierTo(-8, -4, 8, -4, 20, 2);
+  const sheet = Surface.Sweep(crossSection, sideProfile);
+  const thinPart = sheet.thicken(1.2);
+  ```
+- `Loft(input: SurfaceLoftInput): Sheet` — Loft an open surface sheet through ordered profile stations.
+
+  This is the surface-first counterpart to solid lofts: profiles are open 2D section curves, point stations intentionally collapse a smooth tip, and guide curves can pin named connection landmarks such as rims or low points. The result is an open `Sheet`; call `.thicken(...)` to make physical material.
+
+  ```js
+  const sheet = Surface.Loft({
+    axis: 'X',
+    profiles: [
+      { at: -40, point: [-40, 0, 0] },
+      { at: 0, profile: path().moveTo(-12, 2).bezierTo(-4, -4, 4, -4, 12, 2) },
+      { at: 40, profile: path().moveTo(-5, 0).lineTo(5, 0) },
+    ],
+    connections: [{ name: 'lowPoint', profileParameter: 0.5 }],
+  });
+  ```
 - `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.
@@ -3830,20 +4255,109 @@ Members (full entries under [Curves & Surfacing](#curves-surfacing)): `Curve.Ble
   const panel = Surface.Patch({ bottom, top, left, right }).thicken(1.5);
   ```
 - `Boundary(input: SurfaceBoundaryInput): Shape`
-- `Fill(input: SurfaceFillInput): Shape`
+- `Fill(input: SurfaceFillInput): Shape` — Create an n-sided open surface sheet from 3 or more boundary curves (energy-minimizing constrained fill).
+
+  Boundaries form a closed loop of any size (n >= 3). They are exact by default: pass `NurbsCurve3D` values or `Shape.edge()` refs, or set `{ approximate: true }` to accept sampled `Curve3D`/`Vec3[]` boundaries. Use `match` to make a named boundary G0/G1/G2-tangent to a neighboring face. The result is an open sheet — call `.thicken(t)` for a thin solid.
+
+  Two optional fields pull the fill onto interior features (OCCT backend only; the Truck/SDF backends reject them):
+
+  - `through` — interior constraint curves the surface must pass through (not part of the boundary loop). These are matched positionally (G0) only; G1/G2 on a free interior curve is not honored, so a non-`'G0'` `continuity` throws.
+  - `points` — isolated interior points the surface must interpolate.
+
+  ```js
+  const skin = Surface.Fill({
+    boundaries: [
+      { name: 'a', curve: edgeA }, { name: 'b', curve: edgeB },
+      { name: 'c', curve: edgeC }, { name: 'd', curve: edgeD }, { name: 'e', curve: edgeE },
+    ],
+    match: { a: { target: neighbor.edge('top'), continuity: 'G1' } },
+    through: [{ curve: interiorSpine }], // pull the fill onto an internal feature line
+    points: [[10, 10, 4]],               // pin an interior bump
+  });
+  ```
 - `Sew(shapes: Shape[], options?: { tolerance?: number; }): Shape`
 - `Solid(input: Shape | Shape[], options?: SurfaceSolidOptions): Shape` — Sew surface faces or consume an existing sewn shell and make a solid B-rep.
 - `Extend(shape: Shape, options: SurfaceExtendOptions): Shape`
 - `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`
-- `Net(): CurveNet` — Begin a curve-network (Gordon) surface — the class-A keystone. Chain `.lengthwise(...)/.crosswise(...)` (or `.alongRails(a,b).sections(...)`, or `.cage(grid)`), then `.thicken(wall)` to get a solid Shape. Returns a fluent [`Sheet`](/docs/core#sheet) builder with analytic point/normal/curvature queries and named edges.
+- `Net(): CurveNet` — Begin a curve-network (Gordon) surface — the class-A keystone. Chain `.lengthwise(...)/.crosswise(...)` (or `.alongRails(a,b).sections(...)`, or `.cage(grid)`), then `.thicken(wall)` to get a solid Shape. Returns a fluent `Sheet` builder with analytic point/normal/curvature queries and named edges.
+- `BoundaryNet(): CurveNet` — Begin a **Boundary Surface** — the canonical class-A surfacing primitive (SolidWorks "Boundary Boss/Base", Onshape "Boundary surface", Rhino NetworkSrf). It fills a curve cage exactly like `Net` (same Gordon interior), then adds the two foundational boundary capabilities a real boundary surface has:
+
+  1. **Per-side continuity** — `.matchStartU/.matchEndU/.matchStartV/.matchEndV` enforce G0/G1/G2 across a side, either matching an adjacent sheet's edge (tangent/curvature) or imposing an explicit cross-boundary tangent.
+  2. **Closed / periodic form** — `.closedU()/.closedV()` weld a direction's two ends into a tangent-continuous loop, so a closed-rim surface (e.g. a bowl's around-rim seam) is smooth with NO G0 kink.
+
+  Returns the same fluent builder as `Net` (cage/families/degree plus the new boundary methods); finish with `.toSheet()` or `.thicken(wall)`. Verify a matched seam with `Analysis.EdgeMatch`.
+
+  ```js
+  // Smooth closed-rim dished bowl: a closed rim + radial sections, welded.
+  const bowl = Surface.BoundaryNet()
+    .lengthwise(...radialSections)   // rim -> center, one per around-rim station
+    .closedV()                       // weld the around-rim seam (no kink)
+    .thicken(1.2);
+  ```
+
+  ```js
+  // Match a fender panel to the hood with curvature (G2) continuity.
+  const fender = Surface.BoundaryNet()
+    .lengthwise(sill, belt, crown)
+    .crosswise(nose, aPillar)
+    .matchStartV({ edge: hood.rearEdge, continuity: 2 })
+    .toSheet();
+  ```
+
+  U-sides then V-sides, so clean continuity is guaranteed along edge interiors, not exactly at the four corners (same limitation as `Sheet.matchEdge`).
 
 ### `Blend`
 
-- `Edge(options: BlendEdgeOptions): Shape`
+- `Edge(options: BlendEdgeOptions): Shape` — Fillet one or more edges with constant or variable radius.
+
+  Pass `variableRadius` for a tapered or station-law blend — it overrides the constant `radius`. Variable radius requires `--backend occt`.
+
+  Orientation caveat: for a linear `{ start, end }` taper, `start` maps to the matched edge's first vertex (u=0), whose orientation is not guaranteed to match the named edge's start. If the taper runs the wrong way, pass a `stations` law (explicit `at` positions) or swap `start`/`end`.
+
+  ```js
+  // Constant radius
+  let b = box(40, 20, 10)
+  b = Blend.Edge({ edges: [b.edge('top-front')], radius: 3 })
+  ```
+
+  ```js
+  // Linear taper from 1mm to 5mm along the edge
+  b = Blend.Edge({ edges: [b.edge('top-front')], variableRadius: { start: 1, end: 5 } })
+  ```
+
+  ```js
+  // Station law — bulge in the middle
+  b = Blend.Edge({ edges: [b.edge('top-front')], variableRadius: {
+    stations: [{ at: 0, radius: 1 }, { at: 0.5, radius: 4 }, { at: 1, radius: 1 }] } })
+  ```
 - `Surface(options: BlendSurfaceOptions): Shape`
-- `Bridge(edgeA: SheetEdge, edgeB: SheetEdge): BridgeBuilder` — Build a transition strip between two `Surface.Net` sheet edges. Chain `.bulge(a, b)` then `.g0()/.g1()/.g2()` for the continuity order. Returns a [`Sheet`](/docs/core#sheet); verify the seam with `Analysis.EdgeMatch`.
+- `Bridge(edgeA: SheetEdge, edgeB: SheetEdge): BridgeBuilder` — Build a transition strip between two `Surface.Net` sheet edges. Chain `.bulge(a, b)` then `.g0()/.g1()/.g2()` for the continuity order. Returns a `Sheet`; verify the seam with `Analysis.EdgeMatch`.
+- `Face(options: BlendFaceOptions): Shape` — Fillet every edge SHARED by a pair of faces — a "face fillet". Resolves the shared edges of the two faces and rolls a constant or variable-radius blend along all of them. Requires `--backend occt`.
+
+  ```js
+  let body = box(80, 50, 30).faces({ lid: 'top', wall: 'side-left' })
+  body = Blend.Face({ faces: [body.face('lid'), body.face('wall')], radius: 4 })
+  ```
+
+  ```js
+  // Variable radius along the shared edges
+  body = Blend.Face({ faces: [body.face('lid'), body.face('wall')],
+    variableRadius: { start: 2, end: 6 } })
+  ```
+- `FullRound(options: BlendFullRoundOptions): Shape` — Full round — roll a blend over a narrow center face so it is consumed and its two neighbouring faces meet tangentially (classic 3-face full round). The radius defaults to half the center-face span. Requires `--backend occt`.
+
+  ```js
+  let bar = box(60, 8, 20).faces({ topRail: 'top', left: 'side-left', right: 'side-right' })
+  bar = Blend.FullRound({ centerFace: bar.face('topRail') })
+  ```
+
+  ```js
+  // Explicit neighbours
+  bar = Blend.FullRound({ centerFace: bar.face('topRail'),
+    sideFaces: [bar.face('left'), bar.face('right')] })
+  ```
 
 ### `Analysis`
 
@@ -3972,12 +4486,14 @@ Assembly-owned links, constraints, connectors, solved poses, and source-level si
 
 #### `Sim.body(options: SimBodyOptions): SimBodyDef` — Describe one assembly part as a physical body with mass/density, material, collider intent, and optional contact surfaces.
 
-**`SimBodyOptions`**: `massKg?: number`, `densityKgM3?: number`, `material?: SimMaterialDef`, `collider?: SimColliderDef`, `contacts?: Record<string, SimContactDef>`
+**`SimBodyOptions`**: `massKg?: number`, `densityKgM3?: number`, `material?: SimMaterialDef`, `collider?: SimColliderDef`, `contacts?: Record<string, SimContactDef>`, `motion?: SimMotionDef`
 
-`SimColliderDef`: `{ kind: "collider", mode: SimColliderMode, reason?: string }`
+`SimColliderDef`: `{ kind: "collider", mode: SimColliderMode, reason?: string, sdfResolution?: number }`
 
 `SimContactDef`: `{ kind: "wheelSurface" | "gripperSurface", connectorName: string }`
 
+`SimMotionDef`: `{ kind: "motion", mode: SimMotionMode }`
+
 `SimBodyDef`: `{ kind: "body" }`
 
 #### `Sim.collider` — Collision-geometry intent constructors for physical parts.
@@ -3985,8 +4501,15 @@ Assembly-owned links, constraints, connectors, solved poses, and source-level si
 - `Sim.collider.convexHull(): SimColliderDef` — Use a generated collision mesh for the part. This is the default fast rigid-body collider for irregular parts.
 - `Sim.collider.boundingBox(): SimColliderDef` — Use the part bounding box as the collision geometry. This is fastest and works well for chassis and simple blocks.
 - `Sim.collider.visualMesh(): SimColliderDef` — Use the visual mesh as collision geometry. This is exact but usually slower in physics engines.
+- `Sim.collider.sdfMesh: (options?: { resolution?: number` — Use an SDF mesh collider for complex concave contact geometry. Exporters warn when their target cannot encode it.
 - `Sim.collider.none(reason: string): SimColliderDef` — Disable collision for a part with an explicit reason, such as a sensor-only or decorative object.
 
+#### `Sim.motion` — Body motion-state intent for simulation export. Dynamic is the default when omitted.
+
+- `Sim.motion.dynamic(): SimMotionDef` — Simulate this body as a normal dynamic rigid body with mass and inertia.
+- `Sim.motion.kinematic(): SimMotionDef` — Simulate this body as kinematic: moved by the simulator/user, but not force-integrated.
+- `Sim.motion.static(): SimMotionDef` — Keep this body fixed in the world as a static collision/environment body.
+
 #### `Sim.drive` — Joint-drive intent constructors for passive or powered assembly joints.
 
 - `Sim.drive.passive(options?: SimPassiveDriveOptions): SimDriveDef` — Mark a joint as passive while preserving damping and friction metadata for simulation export.
@@ -4017,6 +4540,57 @@ Assembly-owned links, constraints, connectors, solved poses, and source-level si
 
 `SimDiffDriveControllerDef`: `{ kind: "diffDrive" }`
 
+#### `Fea.material(name: string, options: FeaMaterialOptions): FeaMaterialDef` — Create a named linear-elastic structural material for static stress studies.
+
+#### `Fea.body(options: FeaBodyOptions): FeaBodyDef` — Mark one assembly part as a structural body with a `Fea.material(...)` value.
+
+#### `Fea.region` — Stable explicit region references for solver package manifests.
+
+- `Fea.region.face(partName: string, faceName: string): FeaPartFaceRegionRef` — Reference a named face on a named assembly part without relying on object identity.
+- `Fea.region.plane(partName: string, faceName: string, options: FeaPlaneRegionOptions): FeaPartPlaneRegionRef` — Reference a planar face by a point on the face and its outward normal in part-local coordinates.
+
+`FeaPartFaceRegionRef`: `{ kind: "fea-region-face", partName: string, faceName: string }`
+
+`FeaPlaneRegionOptions`: `{ center: Vec3, normal: Vec3 }`
+
+`FeaPartPlaneRegionRef`: `{ kind: "fea-region-plane", partName: string, faceName: string, center: Vec3, normal: Vec3 }`
+
+#### `Fea.fix` — Fixture constructors over authored face/region references.
+
+- `Fea.fix.fixed(region: FeaRegionRef): FeaFixedFixtureDef` — Fully fix all translational degrees of freedom on a face/region.
+
+`FeaFixedFixtureDef`: `{ kind: "fixed", region: FeaRegionRef }`
+
+#### `Fea.load` — Load constructors over authored face/region references.
+
+- `Fea.load.force(region: FeaRegionRef, options: FeaForceLoadOptions): FeaForceLoadDef` — Apply a force with magnitude in newtons along the given direction vector.
+
+`FeaForceLoadOptions`: `{ newtons: number, direction: Vec3 }`
+
+`FeaForceLoadDef`: `{ kind: "force", region: FeaRegionRef }`
+
+#### `Fea.target` — Study target constructors used by feedback and pass/fail gates.
+
+- `Fea.target.minSafetyFactor(value: number): FeaMinSafetyFactorTargetDef` — Require the solved minimum safety factor to be at least `value`.
+
+`FeaMinSafetyFactorTargetDef`: `{ kind: "minSafetyFactor", value: number }`
+
+#### `Fea.mesh` — Volume mesh intent. V1 structural stress uses second-order tetrahedra only.
+
+- `Fea.mesh.quadraticTets(options: FeaQuadraticTetMeshOptions): FeaQuadraticTetMeshDef` — Request quadratic tetrahedral C3D10 elements with a maximum size in mm.
+
+`FeaQuadraticTetMeshOptions`: `{ maxSizeMm: number, minQuality?: number }`
+
+`FeaQuadraticTetMeshDef`: `{ kind: "quadraticTets", order: 2, element: "C3D10" }`
+
+#### `Fea.study` — Study constructors.
+
+- `Fea.study.staticStress(name: string, options: FeaStaticStressStudyOptions): FeaStaticStressStudyDef` — Create a linear static structural stress study.
+
+`FeaStaticStressStudyOptions`: `{ fixtures: FeaFixtureDef[], loads: FeaLoadDef[], target?: FeaTargetDef, mesh: FeaMeshDef }`
+
+`FeaStaticStressStudyDef`: `{ kind: "staticStress", name: string }`
+
 #### `assembly(name?: string): Assembly` — Create an assembly container with named parts, connectors, and kinematic links.
 
 **Use this from iteration 1 for any model with moving parts.** Do not build one static pose and retrofit motion later.
@@ -4150,7 +4724,7 @@ const housing = group(
 assembly.addPart("Base Assembly", housing);
 ```
 
-**`PartOptions`**: `transform?: TransformInput`, `metadata?: PartMetadata`, `sim?: SimBodyDef`, `mate?: AssemblyPartMateInput | AssemblyPartMateInput[]`, `bindToFrame?: string`
+**`PartOptions`**: `transform?: TransformInput`, `metadata?: PartMetadata`, `sim?: SimBodyDef`, `fea?: FeaBodyDef`, `mate?: AssemblyPartMateInput | AssemblyPartMateInput[]`, `bindToFrame?: string`
 
 **`PartMetadata`**
 
@@ -4160,6 +4734,12 @@ assembly.addPart("Base Assembly", housing);
 
 Also: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`.
 
+`FeaBodyDef`: `{ kind: "fea-body", material: FeaMaterialDef }`
+
+`FeaMaterialOptions`: `{ densityKgM3: number, youngsModulusMPa: number, poissonRatio: number, yieldStrengthMPa: number }`
+
+`FeaMaterialDef`: `{ kind: "fea-material", name: string }`
+
 **`AssemblyPartMateInput`**
 - `connector: string` — Name of a connector declared on the part (via `withConnectors()`).
 - `toLink: string` — Name of the link this connector's origin is pinned to.
@@ -4306,6 +4886,10 @@ Use this after adding physical parts and joints. Robot-body profiles require `ro
 
 `SimAssemblySimulationOptions`: `{ profile: SimProfileDef, rootPart?: string, controllers?: SimControllerDef[] }`
 
+#### `withFeaStudy(study: FeaStudyDef): Assembly` — Attach a structural FEA study to this assembly.
+
+The study is authored with `Fea.study.staticStress(...)` and consumed by `forgecad export fea`. This records load-case intent only; ForgeCAD refuses to invent fixtures, loads, mesh order, or region tags during export.
+
 #### `edgeBetweenFrames(a: string, b: string, options?: AssemblyFrameEdgeOptions): Assembly` — Add a visual skeleton edge between two rig frame origins.
 
 Frame edges follow the solved frame poses produced by `fixedJoint()`, `revoluteJoint()`, and `prismaticJoint()`. They do not add constraints, degrees of freedom, parts, or geometry; use them to make a frame-only rig readable in the Motion/rig inspection overlay.
@@ -4788,3 +5372,227 @@ Check the loop, not just the rest pose:
 3. Render each part with `--focus PartName`; the clevis end must show a visible gap between tines.
 4. Re-check at swept angles (30°/60°/90°) — rotation reveals collisions the rest pose hides.
 5. Backbend test at -10°: blocked = hard stop exists; rotates = add a stop.
+
+---
+
+<!-- guides/structural-fea.md -->
+
+# Structural FEA Stress Inspection
+
+Use structural FEA when you want a ForgeCAD model to answer a load-case question:
+
+- Where does this part see the highest stress?
+- How far does it deflect?
+- What is the minimum safety factor against the material yield strength?
+- Did the mesh and solver produce evidence that is good enough to inspect?
+
+ForgeCAD owns the authoring contract, solver orchestration, result feedback, and inspection report. The numerical solve is done out of process with Gmsh and CalculiX. Users author a study in the model, run `forgecad fea run`, and inspect a result bundle.
+
+## What You Get
+
+A solved FEA result bundle can produce:
+
+- max von Mises stress
+- max displacement
+- minimum safety factor
+- mesh quality and solver trust flags
+- region-level hot spots
+- `report.html`
+- `summary.json`
+- a safety-factor heatmap PNG
+- a solver stress heatmap PNG
+- a displacement magnitude heatmap PNG
+
+The deformed render is display-only. It helps explain the displacement shape; it does not change the stress, displacement, or safety-factor numbers reported by the solver.
+
+## What You Need Installed
+
+The ForgeCAD CLI creates the package and renders the heatmap. The package runner uses self-contained `uv` Python scripts for Gmsh so every package resolves the same Python dependency set by default.
+
+Run `forgecad doctor` to check these optional FEA tools in a separate section. Missing FEA tools do not block core ForgeCAD modeling, export, or render commands.
+
+| Tool | Used For | Quick Check |
+| --- | --- | --- |
+| `uv` | Runs the packaged Python scripts with pinned dependencies | `uv --version` |
+| CalculiX `ccx` | Solves the static stress deck | `ccx -v` |
+| Bash | Runs the package script | `bash --version` |
+| Chrome or Chromium | Renders PNG heatmaps from solved evidence | Chrome installed in a standard location, `CHROME_PATH=/path/to/chrome`, or `--chrome-path /path/to/chrome` |
+
+If `uv` is not on `PATH`, set `UV=/path/to/uv` when running `forgecad fea run` or `forgecad fea check`.
+
+If `ccx` is not on `PATH`, set `CCX=/path/to/ccx` when running `forgecad fea run` or `forgecad fea check`.
+
+If you need an offline or pre-provisioned Python environment, set `PYTHON=/path/to/python`. That opt-out Python must be able to `import gmsh`; use `GMSH_PYTHONPATH` / `GMSH_PYTHON_PATH` only for that override path.
+
+ForgeCAD does not bundle CalculiX. The generated `uv` scripts pin the Gmsh Python package, and `uv` downloads/caches it from the configured Python package index. If you redistribute solver binaries or Python wheels to customers, handle their licenses as part of your distribution.
+
+## Author The Study
+
+Structural FEA starts in the `.forge.js` file. The script should return an authored `assembly(...)` with:
+
+1. a structural part marked with `Fea.body(...)`
+2. one or more static stress studies from `Fea.study.staticStress(...)`
+3. explicit fixtures and loads
+4. a second-order tetrahedral mesh intent
+
+```js
+const aluminum = Fea.material("6061-T6", {
+  densityKgM3: 2700,
+  youngsModulusMPa: 68900,
+  poissonRatio: 0.33,
+  yieldStrengthMPa: 276,
+});
+
+const beam = box(120, 12, 12);
+
+return assembly("Cantilever Stress Study")
+  .addPart("Beam", beam, {
+    fea: Fea.body({ material: aluminum }),
+  })
+  .withFeaStudy(
+    Fea.study.staticStress("end-load", {
+      fixtures: [
+        Fea.fix.fixed(Fea.region.face("fixed-end", beam.face("left"))),
+      ],
+      loads: [
+        Fea.load.force(Fea.region.face("load-end", beam.face("right")), {
+          newtons: 80,
+          direction: [0, 0, -1],
+        }),
+      ],
+      target: Fea.target.minSafetyFactor(2),
+      mesh: Fea.mesh.quadraticTets({ maxSizeMm: 4 }),
+    }),
+  );
+```
+
+The complete API reference is generated from source in [Assembly](../generated/assembly.md). Keep reusable examples in `.forge.js` files; do not duplicate every API signature in handwritten docs.
+
+## Choose Stable Regions
+
+Fixtures and loads must name real geometric regions. ForgeCAD will not guess them later.
+
+Use `Fea.region.face(...)` when you can refer to a compiler-owned exact face, such as a simple box face or a named face from the model API.
+
+Use `Fea.region.plane(...)` when the target is a planar face created by profiles, booleans, or imported geometry and the face name is not stable enough. Make the plane specific enough that it matches exactly one STEP/Gmsh surface.
+
+During export, ForgeCAD writes a region map and a STEP tag plan. During the package run, the Gmsh preflight matches every authored fixture/load region against the STEP surfaces. Missing or ambiguous matches fail hard. That is intentional: a silent substitute face would make the stress result untrustworthy.
+
+## Run The Flow
+
+Installed users run the CLI as `forgecad`. Developers running inside this repository can replace `forgecad` with `node dist-cli/forgecad.js`.
+
+Run every authored FEA study and save an inspection result bundle:
+
+```bash
+forgecad fea run examples/analysis/structural-stress-fea.forge.js
+```
+
+Run one named study:
+
+```bash
+forgecad fea run bracket.forge.js --study side-load
+```
+
+Open the report:
+
+```bash
+forgecad fea open out/bracket-fea
+```
+
+Render a customer-facing safety view:
+
+```bash
+forgecad fea render out/bracket-fea/side-load --field safety
+```
+
+Render the engineering stress heatmap:
+
+```bash
+forgecad fea render out/bracket-fea/side-load --field stress
+```
+
+Render the displacement magnitude heatmap:
+
+```bash
+forgecad fea render out/bracket-fea/side-load --field displacement
+```
+
+Render a deformed stress view only when the displacement shape is useful to inspect:
+
+```bash
+forgecad fea render out/bracket-fea/side-load \
+  --field stress \
+  --shape deformed \
+  --exaggerate 10
+```
+
+The deformation scale only affects the render. It does not change the reported stress, displacement, or safety factor.
+
+Each solved study result directory includes:
+
+- `report.html` for the human inspection report
+- `summary.json` for automation
+- `renders/safety-factor.png` for the customer-facing safety heatmap
+- `renders/stress.png` for the engineering von Mises stress heatmap
+
+Displacement and deformed-shape PNGs are explicit render outputs from `forgecad fea render --field displacement` or `--shape deformed`.
+
+Compare two solved result bundles:
+
+```bash
+forgecad fea compare out/baseline-fea/side-load out/four-x-fea/side-load
+```
+
+Comparison renders use one shared camera, image size, and safety-factor legend.
+
+Run in CI and fail the process when authored targets fail:
+
+```bash
+forgecad fea check bracket.forge.js --json
+```
+
+## Read The Results
+
+Start with `report.html` or `summary.json` in the result directory. The important fields are the maximum stress, maximum displacement, minimum safety factor, hot spots, and any mesh or solver trust findings.
+
+The default user-facing result is safety factor because it answers "is this part okay?" Use stress when you need the raw engineering von Mises field.
+
+Advanced users can still run the lower-level package flow:
+
+```bash
+forgecad export fea model.forge.js --output out/beam.feapkg
+forgecad sim fea out/beam.feapkg --json
+forgecad inspect structural stress out/beam.feapkg --camera iso --output out/stress.png
+```
+
+Those commands are useful for debugging package evidence. Customer docs should prefer `forgecad fea ...`.
+
+## Current Scope
+
+Structural FEA V1 is intentionally narrow:
+
+- linear static stress only
+- one structural body per package
+- exact OCCT STEP export only
+- second-order tetrahedral elements only
+- fixed fixtures and force loads only
+- no contacts, bonded assemblies, thermal loads, buckling, fatigue, plasticity, or certification workflow
+
+ForgeCAD refuses mesh or faceted fallback for FEA export. If exact geometry export, region mapping, mesh quality, solver convergence, result parsing, or evidence trust fails, the command should fail with an actionable error instead of inventing a weaker path.
+
+## Troubleshooting
+
+| Symptom | What It Means | What To Do |
+| --- | --- | --- |
+| `FEA.TOOLCHAIN_UV_MISSING` | The package runner cannot find `uv`. | Install `uv` or run with `UV=/path/to/uv`. |
+| `FEA.TOOLCHAIN_PYTHON_MISSING` | A `PYTHON=...` override points to a missing Python executable. | Install Python 3 or fix the `PYTHON` path. |
+| `FEA.TOOLCHAIN_GMSH_MISSING` | The selected Python process cannot import Gmsh. | Prefer the default `uv` path, or install the Gmsh Python module for the `PYTHON=...` override. |
+| `FEA.TOOLCHAIN_CCX_MISSING` | CalculiX is not available as `ccx`. | Install CalculiX or run with `CCX=/path/to/ccx`. |
+| `FEA.GMSH_FACE_MATCH_NONE` | An authored fixture/load region did not match a STEP surface. | Use a more stable face reference or a more precise planar region. |
+| `FEA.GMSH_FACE_MATCH_AMBIGUOUS` | A region matched more than one STEP surface. | Make the target region more specific or change the model so the load/fixture face is unique. |
+| `FEA.MESH_QUALITY_BELOW_TARGET` | The mesh exists but did not meet the package quality target. | Reduce mesh size, simplify tiny features, or improve the geometry around the hot area. |
+| `FEA.SOLVER_FAILED` | CalculiX did not complete the solve. | Inspect `solver/static_stress.log`, then check fixtures, loads, material values, and over-constraint. |
+| `FEA.FIELD_UNTRUSTED` | The heatmap input is not trusted package evidence. | Run inspection on the `.feapkg` directory after `forgecad sim fea`, not a copied JSON file. |
+
+For command flags, use the [CLI reference](../CLI.md). For the public API, use the generated [Assembly reference](../generated/assembly.md).