forgecad 0.10.4 → 0.11.0

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

@@ -18,13 +18,15 @@ skill-order: 100
 - [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)
+- [Path2DParamValue](#path2dparamvalue)
+- [Spline2DParamValue](#spline2dparamvalue)
+- [Placement2DParamValue](#placement2dparamvalue)
 - [CurveNetBuilder](#curvenetbuilder)
 - [MatchEdgeBuilder](#matchedgebuilder)
 - [BridgeBuilder](#bridgebuilder)
@@ -353,11 +355,11 @@ for (const edge of coalesceEdges(topEdges)) {
 
 ### Imports & Composition
 
-#### `require(path: string, paramOverrides?: Record<string, number | string>): any` — Import a module with optional ForgeCAD parameter overrides. Returns the module's exports.
+#### `require(path: string): any` — Import a ForgeCAD or helper module. Returns the file's returned value.
 
-When importing a `.forge.js` file, most return values are passed through exactly as the script returns them. Assembly returns have one extra composition rule: an unsolved [`Assembly`](/docs/assembly#assembly) is wrapped as an [`ImportedAssembly`](/docs/assembly#importedassembly), preserving `solve(state)` and `mergeInto()` across file boundaries, while a returned [`SolvedAssembly`](/docs/assembly#solvedassembly) stays a [`SolvedAssembly`](/docs/assembly#solvedassembly). If the script returns a metadata object (e.g. `{ shape: myShape, bolts: {...} }`), the caller receives the full object — renderable values and metadata together.
+When importing a `.forge.js` file, return values are passed through exactly as the script returns them, except for unsolved assemblies: a returned [`Assembly`](/docs/assembly#assembly) is wrapped as an [`ImportedAssembly`](/docs/assembly#importedassembly), preserving `solve(state)` and `mergeInto()` across file boundaries. A returned [`SolvedAssembly`](/docs/assembly#solvedassembly) stays a [`SolvedAssembly`](/docs/assembly#solvedassembly).
 
-**Script return contract:** a `.forge.js` script returns one of three shapes: a single renderable (Shape, ShapeGroup, Sketch, SdfShape, Assembly), an array of renderables or named descriptors (`{ name, shape|sketch|group }`), or a metadata object mixing renderable values with plain data. When a script runs directly, renderable entries of a metadata object are rendered under their key names and non-renderable entries are silently skipped — both halves of the metadata contract: one return value serves the viewport and `require()` callers.
+**Script return contract:** a `.forge.js` script should return one of three shapes: a single renderable (Shape, ShapeGroup, Sketch, SdfShape, Assembly), an array of renderables or named descriptors (`{ name, shape|sketch|group }`) for previews and multi-object display, or a module interface object. Reusable part files should return builders such as `return { buildBracket }`; files that already build useful geometry may return `{ shape, connectors, boltPattern }`. When a script runs directly, renderable entries of a plain object are rendered under their key names and non-renderable entries are skipped.
 
 **Assembly return contract**
 
@@ -370,52 +372,56 @@ When importing a `.forge.js` file, most return values are passed through exactly
 
 **Path rule:** Always include the file extension in relative imports: use `require("./part.forge.js")` for model files and `require("./helpers.js")` for plain helper modules. ForgeCAD does not apply Node-style extension inference, so `require("./part")` will not find `part.forge.js` or `part.js`.
 
-**Parameter scoping:** Parameters declared in required files are automatically namespaced with a `"filename#N / "` prefix (e.g. `"bracket.forge.js#1 / Width"`). This prevents collisions when multiple files declare same-named params. Each file's params appear as separate sliders.
-
-**Parameter overrides:** When passing overrides, use the bare param name (not the scoped name). Overrides are type-checked — unrecognized keys throw an error with typo suggestions.
-
-**Multi-file assembly pattern** — pass cross-cutting design values from the assembly to parts:
+**Multi-file assembly pattern** — the assembly owns params and passes ordinary props to child builders:
 
 ```js
 // assembly.forge.js — owns cross-cutting params, passes to parts
 const wall = param("Wall", 3);
 const baseH = param("Base Height", 20);
 
-const mount = require('./motor-mount.forge.js', { Wall: wall });
-const base  = require('./base-body.forge.js', { Wall: wall, Height: baseH });
+const mountModule = require('./motor-mount.forge.js');
+const baseModule = require('./base-body.forge.js');
+
+const mount = mountModule.buildMount({ wall });
+const base = baseModule.buildBase({ wall, height: baseH });
 ```
 
-**Metadata pattern** — parts publish interface data alongside geometry:
+**Builder result pattern** — parts publish interface data alongside geometry:
 
 ```js
 // motor-mount.forge.js
-return { shape: mount, bolts: { dia: 5.3, pos: holePositions } };
+function buildMount({ wall }) {
+  const shape = box(80, 40, wall);
+  return { shape, boltPattern: { dia: 5.3, positions: [[-25, 0], [25, 0]] } };
+}
 
 // base-body.forge.js
 const mount = require('./motor-mount.forge.js');
-mount.bolts.pos  // access the metadata
-mount.shape       // access the geometry
+const built = mount.buildMount({ wall: 3 });
+built.boltPattern  // access interface data
+built.shape        // access geometry
 ```
 
 **Forge-aware builder module pattern** — use `.forge.js` modules for reusable sketch, profile, shape, or assembly builders that need ForgeCAD runtime APIs:
 
 ```js
-// profiles.forge.js — inspectable on its own, reusable through require()
+// profiles.forge.js
 function wheelProfile() {
   return circle2d(40).subtract(circle2d(18));
 }
 
-return {
-  preview: [{ name: 'Wheel profile', sketch: wheelProfile() }],
-  make: { wheelProfile },
-};
+if (require.main === module) {
+  return [{ name: 'Wheel profile', sketch: wheelProfile() }];
+}
+
+return { wheelProfile };
 
 // main.forge.js
 const profiles = require('./profiles.forge.js');
-const wheel = profiles.make.wheelProfile().extrude(8);
+const wheel = profiles.wheelProfile().extrude(8);
 ```
 
-Keep exported builders pure over top-level constants, top-level `param()` values, or explicit function arguments. Do not declare new `param()` values inside an exported builder if callers need `require('./profiles.forge.js', { Width: 80 })` overrides: import overrides are validated while the module loads, before any exported builder is called. Use plain `.js` modules only for pure constants, tables, math helpers, and formatting code that does not construct ForgeCAD geometry.
+Keep returned builders pure over top-level constants or explicit function arguments. Put preview-only `param()` values inside `if (require.main === module)` so parent assemblies stay in charge of design parameters. Use plain `.js` modules only for pure constants, tables, math helpers, and formatting code that does not construct ForgeCAD geometry.
 
 **Entry detection (Node semantics):** `require.main` is the entry script's module object, so `require.main === module` is true only in the file being run directly. Part files use it to build standalone preview geometry only when opened directly — importers then skip that work entirely:
 
@@ -423,16 +429,30 @@ Keep exported builders pure over top-level constants, top-level `param()` values
 // part.forge.js
 function bracket() { ... }
 if (require.main === module) {
-  return { preview: [{ name: 'Bracket', shape: bracket() }] }; // direct run: render it
+  return bracket({ width: param('Width', 80), height: param('Height', 40) });
 }
-return { make: { bracket } };                                  // imported: builders only
+return { bracket };
 ```
 
 ### Parameters
 
-#### `Param.number(name: string, defaultValue: number, opts?: { min?: number; max?: number; step?: number; unit?: string; integer?: boolean; reverse?: boolean; }): number` — Declare a numeric parameter that renders as a slider in the UI.
+#### `Param.anchor: { ... }` — Viewport anchor builders for spatial parameter editing.
+
+Anchors are metadata only: they do not change geometry. The editor uses them to show clickable parameter pins and manual-editing sheets in the 3D viewport. Use point anchors for scalar/text/list parameters and sheet anchors for `path2d`, [`spline2d`](/docs/curves#spline2d), and `placement2d` editors.
+
+A sheet anchor's origin is a world/model-space point. Its plane selects how the 2D editor coordinates map into the viewport:
+
+- `sheetOnXY([x, y, z])`: editor x/y map to world X/Y at fixed Z.
+- `sheetOnXZ([x, y, z])`: editor x/y map to world X/Z at fixed Y.
+- `sheetOnYZ([x, y, z])`: editor x/y map to world Y/Z at fixed X.
+
+Omitting `anchor` still registers the parameter in the parameter panel; it just will not create a viewport pin/sheet.
+
+`ParamAnchorOptions`: `{ label?: string, color?: string }`
 
-Each call registers a slider control. When the user moves the slider the entire script re-executes with the new value. Parameter values are also overridable from `require()` imports or the CLI `--param` flag — the `name` string is the key used in both cases.
+#### `Param.number(name: string, defaultValue: number, opts?: NumberParamOptions): number` — Declare a numeric parameter that renders as a slider in the UI.
+
+Each call registers a slider control. When the user moves the slider the entire script re-executes with the new value. The `name` string is the UI label and the CLI `--param` key.
 
 Default range rules when options are omitted:
 
@@ -448,38 +468,35 @@ const angle = Param.number("Angle", 45, { min: 0, max: 180, unit: "°" });
 const sides = Param.number("Sides", 6, { min: 3, max: 12, integer: true });
 ```
 
-**Parameter overrides** — key must match `name` exactly:
-
-```ts
-// Via require()
-const bracket = require("./bracket.forge.js", { Width: 80 });
+CLI overrides use the parameter name:
 
-// Via CLI
-// forgecad run model.forge.js --param "Wall Thickness=3"
+```bash
+forgecad run model.forge.js --param "Wall Thickness=3"
 ```
 
 Also available as the shorthand alias `param()`.
 
-#### `Param.string(name: string, defaultValue: string, opts?: { maxLength?: number; }): string` — Declare a string parameter that renders as a text input in the UI.
+`ParamAnchorableOptions`: `{ anchor?: ParamAnchorDef }`
+
+`NumberParamOptions`: `{ min?: number, max?: number, step?: number, unit?: string, integer?: boolean, reverse?: boolean }`
+
+#### `Param.string(name: string, defaultValue: string, opts?: StringParamOptions): string` — Declare a string parameter that renders as a text input in the UI.
 
-String parameters let users type free-form text — labels, names, inscriptions, file paths, etc. The `name` string is the override key.
+String parameters let users type free-form text — labels, names, inscriptions, file paths, etc.
 
 ```ts
 const label = Param.string("Label", "Hello World");
 const name  = Param.string("Name", "Part-001", { maxLength: 20 });
 ```
 
-Override via import:
+Only available as `Param.string()` — no standalone alias.
 
-```ts
-const tag = require("./tag.forge.js", { Label: "Custom Text" });
-```
 
-Only available as `Param.string()` — no standalone alias.
+`StringParamOptions`: `{ maxLength?: number }`
 
-#### `Param.bool(name: string, defaultValue: boolean): boolean` — Declare a boolean parameter that renders as a checkbox in the UI.
+#### `Param.bool(name: string, defaultValue: boolean, opts?: ParamAnchorableOptions): boolean` — Declare a boolean parameter that renders as a checkbox in the UI.
 
-Internally stored as `0`/`1`. When overriding from CLI or `require()`, pass `1` for true and `0` for false. The `name` string is the override key.
+Internally stored as `0`/`1` for CLI overrides. Pass `1` for true and `0` for false.
 
 ```ts
 const showHoles = Param.bool("Show Holes", true);
@@ -487,29 +504,17 @@ if (showHoles) return difference(plate, cylinder(10, 5).translate(50, 30, 0));
 return plate;
 ```
 
-Override via import:
-
-```ts
-const pan = require("./pan.forge.js", { "Show Lid": 0 });
-```
-
-#### `Param.choice(name: string, defaultValue: string, choices: string[]): string` — Declare a choice parameter that renders as a dropdown in the UI.
+#### `Param.choice(name: string, defaultValue: string, choices: string[], opts?: ParamAnchorableOptions): string` — Declare a choice parameter that renders as a dropdown in the UI.
 
 `defaultValue` must exactly match one entry in `choices`. Returns the selected string label. Prefer `Param.choice` over `Param.number` when a slider would hide intent — named choices like `"wok"` are self-describing.
 
-Overrides may be passed as the choice label string (preferred) or as a numeric index. The `name` string is the override key.
+CLI overrides may be passed as the choice label string (preferred) or as a numeric index.
 
 ```ts
 const panStyle = Param.choice("Pan Style", "frying-pan", ["frying-pan", "saute-pan", "wok"]);
 if (panStyle === "wok") return buildWok();
 ```
 
-Override via import:
-
-```ts
-const pan = require("./pan.forge.js", { "Pan Style": "wok" });
-```
-
 Override via CLI:
 
 ```bash
@@ -528,6 +533,94 @@ Field types:
 
 `ListParamFieldDef`: `{ min?: number, max?: number, step?: number, unit?: string, integer?: boolean, boolean?: boolean, choices?: string[] }`
 
+#### `Param.path2d(name: string, defaultPoints: Path2DPointInput[], opts?: Path2DParamOptions): Path2DParamValue` — Declare an editable 2D path parameter.
+
+Use this for hand-shaped 2D profile data: plate outlines, slice profiles, stroke centerlines, and sweep rails. The returned value keeps the model code deterministic while the editor can render a drag-handle path UI.
+
+Override keys use the same explicit row-field form as list params: `Path Name[0].x`, `Path Name[0].y`, and `Path Name.__count__`.
+
+```ts
+const outline = Param.path2d("Bracket Outline", [
+  [-40, -20],
+  [40, -20],
+  [36, 24],
+  [-30, 28],
+], {
+  closed: true,
+  anchor: Param.anchor.sheetOnXY([0, 0, 8], { label: "Bracket outline" }),
+});
+
+return outline.toSketch().filletCorners(4).extrude(5);
+```
+
+
+**`Path2DParamOptions`** extends ParamAnchorableOptions: `closed?: boolean`, `minPoints?: number`, `maxPoints?: number`, `x?: Partial<Path2DParamAxisDef>`, `y?: Partial<Path2DParamAxisDef>`, `unit?: string`
+
+**`Path2DParamAxisDef`**
+- `min: number` — Initial editor-frame minimum. Points may move outside this range on the infinite canvas.
+- `max: number` — Initial editor-frame maximum. Points may move outside this range on the infinite canvas.
+- Also: `step: number`.
+
+#### `Param.spline2d(name: string, defaultPoints: Spline2DPointInput[], opts?: Spline2DParamOptions): Spline2DParamValue` — Declare an editable 2D spline parameter.
+
+Use this when the model wants hand-shaped smooth curve data instead of a numeric table: handle spines, bowl station curves, sweep rails, and class-A guide profiles. Each node stores `g`, a continuity intent:
+
+- `"G0"` starts/ends a hard curve segment at that point
+- `"G1"` keeps the point in a tangent-smooth run
+- `"G2"` keeps the point in a curvature-smooth cubic run
+
+Override keys use explicit row-field form: `Curve Name[0].x`, `Curve Name[0].y`, `Curve Name[0].g`, and `Curve Name.__count__`.
+
+```ts
+const spine = Param.spline2d("Handle Spine", [
+  { x: 0, y: 0, g: "G2" },
+  { x: 35, y: 8, g: "G2" },
+  { x: 80, y: 2, g: "G1" },
+], {
+  anchor: Param.anchor.sheetOnXZ([0, -18, 0], { label: "Side-view spine" }),
+});
+
+return sweep(circle2d(2), spine.toCurveOnXZ());
+```
+
+
+**`Spline2DParamOptions`** extends ParamAnchorableOptions: `closed?: boolean`, `degree?: number`, `defaultContinuity?: Spline2DContinuity`, `minPoints?: number`, `maxPoints?: number`, `x?: Partial<Path2DParamAxisDef>`, `y?: Partial<Path2DParamAxisDef>`, `unit?: string`
+
+#### `Param.placement2d(name: string, spec: Placement2DParamOptions): Placement2DParamValue` — Declare an editable 2D placement sheet parameter.
+
+Use this when the user should arrange named model roles rather than draw geometry: batteries inside an enclosure, rooms across floors, controls on a panel, robot modules on a chassis, or other semantic blockouts.
+
+The script declares stable item IDs, footprints, optional rectangular zones, and interaction rules. The returned value exposes named placements as data; the model code decides what those placements mean geometrically.
+
+Override keys are item-ID based: `Layout.battery.x`, `Layout.battery.y`, `Layout.battery.angle`, and `Layout.battery.zone`.
+
+```ts
+const layout = Param.placement2d("Internal Layout", {
+  frame: { size: [120, 80] },
+  items: [
+    { id: "battery", footprint: { type: "rect", size: [42, 24] }, at: [-25, 0] },
+    { id: "speaker", footprint: { type: "circle", radius: 12 }, at: [32, 8] },
+  ],
+  rules: { bounds: "prevent", collisions: "warn", snap: 1 },
+  anchor: Param.anchor.sheetOnXY([0, 0, 12], { label: "Internal layout" }),
+});
+
+const battery = layout.item("battery");
+const batteryPocket = box(42, 24, 6).translate(battery.x, battery.y, 3);
+```
+
+
+**`Placement2DParamOptions`** extends ParamAnchorableOptions: `frame?: Placement2DFrameInput`, `zones?: Placement2DZoneInput[]`, `items: Placement2DItemInput[]`, `rules?: Partial<Placement2DRulesDef>`, `unit?: string`
+
+`Placement2DFrameInput`: `{ width?: number, height?: number, size?: Vec2, center?: Placement2DPointInput, at?: Placement2DPointInput }`
+
+
+`Placement2DZoneInput`: `{ id: string, label?: string, frame?: Placement2DFrameInput }`
+
+**`Placement2DItemInput`**: `id: string`, `label?: string`, `footprint: Placement2DFootprintInput`, `at?: Placement2DPointInput`, `center?: Placement2DPointInput`, `angle?: number`, `zone?: string`, `locked?: boolean`
+
+`Placement2DRulesDef`: `{ bounds: Placement2DRuleMode, collisions: Placement2DRuleMode, snap: number }`
+
 ### Grouping & Local Coordinates
 
 #### `group(...items: GroupInput[]): ShapeGroup` — Group multiple shapes/sketches for joint transforms without merging into a single mesh.
@@ -705,6 +798,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.
@@ -1115,7 +1298,7 @@ cylinder(60, 20).wrapTexture(label, Wrap.aroundCylinder({ axis: 'z' }));  // wra
 
 #### `ref(path: string): ShapeRef` — Resolve a semantic reference path like `lid`, `lid/back`, or a midpoint selector on `lid/back`.
 
-#### `thicken(thickness: number): Shape` — Offset-thicken an exact open surface or shell into a solid.
+#### `thicken(thickness: ThicknessInput): Shape` — Offset-thicken an exact open surface or shell into a solid.
 
 #### `getMesh(): ShapeRuntimeMesh` — Extract triangle mesh for Three.js rendering
 
@@ -1355,57 +1538,200 @@ 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`
+### `Path2DParamValue`
+
+Runtime value returned by `Param.path2d()`.
+
+Use closed paths as editable profile outlines via `toSketch()`. Use open paths as editable centerlines via `toStroke(width)`.
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `closed` | `boolean` | True when this path is intended to close back to its first point. |
+
+**Methods:**
+
+#### `points(): Vec2[]` — Return the current points as `[x, y]` pairs in the editor coordinate system.
+
+#### `toSketch(): Sketch` — Convert a closed editable path into a sketch profile.
+
+This is the common path for hand-edited plates, outlines, and 2D section profiles that will be extruded, subtracted, or used in sketch booleans. Throws for open paths; use `toStroke(width)` for editable centerlines.
+
+#### `toStroke(width: number, join?: "Round" | "Square"): Sketch` — Convert an editable path into a stroked sketch with physical width.
 
-A parametric open surface value (control grid + knots + analytic differential geometry).
+Use this for rails, ribs, cable routes, gasket paths, and other open centerlines. Closed paths can also be stroked when the intent is a looped band rather than a filled profile.
+
+### `Spline2DParamValue`
+
+Runtime value returned by `Param.spline2d()`.
+
+Spline params preserve both editable point coordinates and each point's continuity intent (`G0`, `G1`, or `G2`). Convert them to curves for sweeps and loft rails, or to sampled paths when an API expects plain points.
 
 **Properties:**
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `surface` | `BSplineSurface` | — |
+| `closed` | `boolean` | True when this spline is intended to close back to its first point. |
+| `degree` | `number` | Requested fitting degree before any automatic reduction for short spans. |
 
 **Methods:**
 
-#### `get frontEdge(): SheetEdge` — Edge naming follows parameter direction (documented): front=v0, rear=v1, left=u0, right=u1.
+#### `points(): Vec2[]` — Return the current control nodes as `[x, y]` pairs without continuity metadata.
+
+#### `nodes(): Spline2DPointDef[]` — Return the current editable nodes, including per-point `g` continuity values.
+
+#### `continuities(): Spline2DContinuity[]` — Return only the per-node continuity intents in point order.
+
+#### `toPolyline(samples?: number): Vec2[]` — Sample the spline into 2D `[x, y]` points.
+
+Use this when downstream code needs a polyline instead of a curve object.
+
+#### `toCurveOnXY(z?: number, options?: Spline2DCurveOptions): NurbsCurve3D` — Fit the editable spline as a 3D curve on the XY plane at constant `z`.
+
+The point's `x` maps to world X and `y` maps to world Y.
+
+`Spline2DCurveOptions`: `{ degree?: number, tolerance?: number, samples?: number }`
+
+#### `toCurveOnXZ(y?: number, options?: Spline2DCurveOptions): NurbsCurve3D` — Fit the editable spline as a 3D curve on the XZ plane at constant `y`.
+
+The point's `x` maps to world X and `y` maps to world Z. This is useful for side-view height/depth profiles such as spoon bowls, handles, and rails.
+
+#### `toCurveOnYZ(x?: number, options?: Spline2DCurveOptions): NurbsCurve3D` — Fit the editable spline as a 3D curve on the YZ plane at constant `x`.
+
+The point's `x` maps to world Y and `y` maps to world Z.
+
+#### `toCurveSegmentsOnXY(z?: number, options?: Spline2DCurveOptions): NurbsCurve3D[]` — Fit the spline on XY and return separate curve segments split at `G0` nodes.
+
+Use segment output when a hard break should remain visible to downstream code instead of being joined into one continuous curve.
 
-#### `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).
+#### `toCurveSegmentsOnXZ(y?: number, options?: Spline2DCurveOptions): NurbsCurve3D[]` — Fit the spline on XZ and return separate curve segments split at `G0` nodes.
 
-#### `matchEdge(edge: SheetEdge): MatchEdgeBuilder` — Per-edge continuity match against a neighbor (returns a NEW Sheet).
+#### `toCurveSegmentsOnYZ(x?: number, options?: Spline2DCurveOptions): NurbsCurve3D[]` — Fit the spline on YZ and return separate curve segments split at `G0` nodes.
+
+#### `toPathOnXY(z?: number, options?: Spline2DCurveOptions): Vec3[]` — Sample the spline as 3D points on the XY plane at constant `z`.
+
+This is useful for sweeps and surface helpers that accept point paths.
+
+#### `toPathOnXZ(y?: number, options?: Spline2DCurveOptions): Vec3[]` — Sample the spline as 3D points on the XZ plane at constant `y`.
+
+#### `toPathOnYZ(x?: number, options?: Spline2DCurveOptions): Vec3[]` — Sample the spline as 3D points on the YZ plane at constant `x`.
+
+### `Placement2DParamValue`
+
+Runtime value returned by `Param.placement2d()`.
+
+Placement sheets return semantic item positions. The model decides what each item means geometrically, so users can drag named blocks without editing the construction code.
+
+#### `items(): Placement2DItemPlacement[]` — Return all current item placements as immutable copies.
+
+#### `positions(): Record<string, Placement2DItemPlacement>` — Return current placements keyed by item id for table-style lookup.
+
+#### `item(id: string): Placement2DItemPlacement` — Return one named item placement.
+
+Throws if `id` was not declared in the sheet, which keeps model code tied to stable semantic item IDs rather than fragile list indices.
+
+### `CurveNetBuilder`
+
+#### `alongRails(railA: CurveInput, railB: CurveInput): this` — Use two lengthwise boundary curves as guide rails.
+
+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.
+
+#### `sections(...curves: CurveInput[]): this` — Add crosswise section curves.
+
+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.
+
+#### `resolution(samples: number): this` — Set the sampling resolution used to build curve-family surface grids.
+
+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.
+
+#### `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`
+- `thickenInsideBy(thickness: ThicknessInput, 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`