forgecad 0.10.5 → 0.11.0

package/dist-skill/CONTEXT.md

@@ -28,7 +28,8 @@ Author or modify ForgeCAD models, sketches, assemblies, and CLI workflows. Prefe
 
 ### Import and composition
 
-- Always include the extension in relative imports: `require("./file.forge.js", { Param: value })` for model files, `require("./helpers.js")` for plain helper modules. Extensionless imports such as `require("./file")` do not resolve; ForgeCAD resolves project imports by exact path.
+- Always include the extension in relative imports: `require("./file.forge.js")` for model files, `require("./helpers.js")` for plain helper modules. Extensionless imports such as `require("./file")` do not resolve; ForgeCAD resolves project imports by exact path.
+- Reusable `.forge.js` part files should return builder functions such as `return { buildPart }`; direct-run preview params belong inside `if (require.main === module)`.
 - ForgeCAD APIs are injected globals in `.forge.js` files. Use `bom()`, `box()`, `scene()`, `Shape`, etc. directly; never destructure those names from helpers (`const { bom } = require("./bom.js")`). Import helper files under a project-specific name such as `const bomHelpers = require("./bom.js")`.
 - For static multi-part models, connectors + `matchTo()` are the default way to assemble touching parts.
 - Top-level scripts can return `Assembly` or `SolvedAssembly` directly. Do not call `.toGroup()` just to render an assembly; use it only when you need `ShapeGroup` composition, transforms, or named-child lookup.
@@ -77,10 +78,10 @@ A `.forge.js` script is plain JavaScript that returns geometry. The entire forge
 
 All geometry operations are **immutable** — shapes, sketches, groups, assemblies, and boards return new values, never mutate in place.
 
-A script must return one of three shapes:
+A script should return one of three shapes:
 
 1. **A single renderable** — `Shape`, `Sketch`, `ShapeGroup`, `Assembly`, `SolvedAssembly`, or `SdfShape`.
-2. **An array** of renderables or named descriptors `{ name, tags?, shape | sketch | group, color? }`:
+2. **An array** of renderables or named descriptors `{ name, tags?, shape | sketch | group, color? }`, usually for direct-run previews and multi-object display:
 
    ```javascript
    return [
@@ -89,11 +90,38 @@ A script must return one of three shapes:
    ];
    ```
 
-3. **A metadata object** — a plain object whose renderable values are rendered and whose non-renderable values (numbers, hole tables, builder functions) are silently skipped at render but flow to importers via `require()`. Each key becomes a named group, so don't pile independent parts into one array key (`{ parts: [a, b, c] }`) — the integrity gate reads that as a single fragmented part. Give each part its own key (`{ collar12, collar16, plug }`) or use named descriptors (form 2).
+3. **A module interface object** — usually builder functions, optionally a built shape plus interface data:
+
+   ```javascript
+   return { buildBracket };
+   // or, when the file's useful output is already built:
+   return { shape, connectors, boltPattern };
+   ```
+
+For reusable part files, prefer a builder export and keep direct-run preview controls inside the entry guard:
+
+```javascript
+function buildThing(props) {
+  return box(props.width, props.depth, props.height);
+}
+
+if (require.main === module) {
+  const previewProps = {
+    width: param("Width", 80),
+    depth: param("Depth", 40),
+    height: param("Height", 12),
+  };
+  return buildThing(previewProps);
+}
+
+return { buildThing };
+```
+
+When a plain object is returned directly, renderable values are shown in the viewport and non-renderable values are available to importers through `require()`.
 
 Return an unsolved `Assembly` directly — ForgeCAD solves it at default joint values for display. Use `assembly.solve(state)` for a specific pose. Never call `.toGroup()` just to make an assembly render; use it only when you need `ShapeGroup` composition or named-child lookup.
 
-For multi-file projects — import path rules, the metadata pattern, and Forge-aware builder modules — see the [`require()` docs](../../generated/core.md).
+For multi-file projects, import path rules, and reusable builder modules, see the [`require()` docs](../../generated/core.md).
 
 ## Identity
 
@@ -145,14 +173,144 @@ 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
+SurfaceMembers, sweep, text2d, textWidth, Thickness, 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.
 
 ---
 
+<!-- guides/manual-parameters.md -->
+
+# Manual Parameter Sheets
+
+Manual parameters are constrained design data: the script owns the structure and
+the user edits only the declared values. They are for cases where a numeric
+slider is the wrong shape of input.
+
+## Contents
+
+- Decision Ladder
+- Path2D
+- Spline2D
+- Placement2D
+- Spatial Anchors
+- Saving
+
+## Decision Ladder
+
+Use the smallest parameter type that matches the design intent:
+
+| Intent | Use |
+| --- | --- |
+| One scalar dimension, count, angle, or toggle | `Param.number()`, `Param.bool()`, `Param.choice()` |
+| A repeated table of named scalar fields | `Param.list()` |
+| A hand-shaped polygon, section outline, or open centerline | `Param.path2d()` |
+| A smooth hand-shaped curve with tangent/curvature intent | `Param.spline2d()` |
+| Named semantic blocks arranged in zones | `Param.placement2d()` |
+
+Do not use `path2d` or `spline2d` as a generic table. Use them when dragging
+points is meaningfully better than editing numbers.
+
+## Path2D
+
+`Param.path2d(name, points, opts)` returns a `Path2DParamValue`.
+
+- Closed paths are filled profile intent: call `.toSketch()`.
+- Open paths are centerline intent: call `.toStroke(width)`.
+- `x` and `y` ranges define the initial editor frame, not hard movement limits.
+- Override keys are `Name[0].x`, `Name[0].y`, and `Name.__count__`.
+
+```javascript
+const outline = Param.path2d('Outline', [[-30, -15], [30, -15], [24, 18], [-28, 16]], {
+  closed: true,
+  minPoints: 3,
+  maxPoints: 12,
+  unit: 'mm',
+  anchor: Param.anchor.sheetOnXY([0, 0, 8], { label: 'Top outline' }),
+});
+
+return outline.toSketch().extrude(4);
+```
+
+## Spline2D
+
+`Param.spline2d(name, points, opts)` returns a `Spline2DParamValue`.
+
+- Each point has `g`: `G0` for a hard break, `G1` for tangent smooth, `G2` for
+  curvature smooth.
+- Use `.toCurveOnXY()`, `.toCurveOnXZ()`, or `.toCurveOnYZ()` for sweeps and
+  curve consumers.
+- Use `.toPathOnXY()`, `.toPathOnXZ()`, or `.toPathOnYZ()` when an API expects
+  sampled points.
+- Override keys are `Name[0].x`, `Name[0].y`, `Name[0].g`, and `Name.__count__`.
+
+```javascript
+const sideProfile = Param.spline2d('Side Profile', [
+  { x: 0, y: 0, g: 'G2' },
+  { x: 35, y: 8, g: 'G2' },
+  { x: 70, y: 3, g: 'G1' },
+], {
+  unit: 'mm',
+  anchor: Param.anchor.sheetOnXZ([0, -20, 0], { label: 'Side profile' }),
+});
+
+const rail = sideProfile.toCurveOnXZ();
+```
+
+## Placement2D
+
+`Param.placement2d(name, spec)` returns a `Placement2DParamValue`.
+
+- The script declares stable item IDs, footprints, optional zones, and rules.
+- The user moves named items; the model decides what each item creates.
+- Use `.item(id)` for one placement or `.positions()` for keyed lookup.
+- Override keys are item based: `Layout.battery.x`, `Layout.battery.y`,
+  `Layout.battery.angle`, and `Layout.battery.zone`.
+
+```javascript
+const layout = Param.placement2d('Internal Layout', {
+  frame: { size: [120, 80] },
+  zones: [{ id: 'electronics', size: [70, 70], center: [-20, 0] }],
+  items: [
+    { id: 'battery', footprint: { type: 'rect', size: [42, 24] }, zone: 'electronics', 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 batteryBlock = box(42, 24, 6).translate(battery.x, battery.y, 3);
+```
+
+## Spatial Anchors
+
+Every parameter type can carry optional viewport metadata through `anchor`.
+Anchors do not change geometry.
+
+- `Param.anchor.point([x, y, z])` creates a clickable pin for scalar, string,
+  list, boolean, or choice parameters.
+- `Param.anchor.sheetOnXY([x, y, z])` places a 2D sheet in the XY plane at
+  fixed Z.
+- `Param.anchor.sheetOnXZ([x, y, z])` places a 2D sheet in the XZ plane at
+  fixed Y.
+- `Param.anchor.sheetOnYZ([x, y, z])` places a 2D sheet in the YZ plane at
+  fixed X.
+
+The parameter still appears in the parameter panel when `anchor` is omitted; it
+just has no 3D pin or spatial sheet.
+
+## Saving
+
+Dragging a manual sheet writes parameter overrides first. The source model keeps
+the declared defaults until those overrides are intentionally folded back into
+code. Use snapshots for named parameter states, and use the parameter panel's
+AI handoff for manual canvas edits when the desired result should become source.
+
+---
+
 <!-- generated/core.md -->
 
 # Core API
@@ -176,6 +334,9 @@ union2d, variableSweep, verify, Viewport, window, Wood, Wrap
 - [SurfacePattern](#surfacepattern)
 - [Pattern2D](#pattern2d)
 - [Pattern2DBuilder](#pattern2dbuilder)
+- [Path2DParamValue](#path2dparamvalue)
+- [Spline2DParamValue](#spline2dparamvalue)
+- [Placement2DParamValue](#placement2dparamvalue)
 - [CurveNetBuilder](#curvenetbuilder)
 - [MatchEdgeBuilder](#matchedgebuilder)
 - [BridgeBuilder](#bridgebuilder)
@@ -504,11 +665,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**
 
@@ -521,52 +682,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:
 
@@ -574,16 +739,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 }`
+
+#### `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. Parameter values are also overridable from `require()` imports or the CLI `--param` flag — the `name` string is the key used in both cases.
+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:
 
@@ -599,38 +778,34 @@ 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:
+CLI overrides use the parameter name:
 
-```ts
-// Via require()
-const bracket = require("./bracket.forge.js", { Width: 80 });
-
-// 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 }`
 
-String parameters let users type free-form text — labels, names, inscriptions, file paths, etc. The `name` string is the override key.
+`NumberParamOptions`: `{ min?: number, max?: number, step?: number, unit?: string, integer?: boolean, reverse?: boolean }`
 
-```ts
-const label = Param.string("Label", "Hello World");
-const name  = Param.string("Name", "Part-001", { maxLength: 20 });
-```
+#### `Param.string(name: string, defaultValue: string, opts?: StringParamOptions): string` — Declare a string parameter that renders as a text input in the UI.
 
-Override via import:
+String parameters let users type free-form text — labels, names, inscriptions, file paths, etc.
 
 ```ts
-const tag = require("./tag.forge.js", { Label: "Custom Text" });
+const label = Param.string("Label", "Hello World");
+const name  = Param.string("Name", "Part-001", { maxLength: 20 });
 ```
 
 Only available as `Param.string()` — no standalone alias.
 
-#### `Param.bool(name: string, defaultValue: boolean): boolean` — Declare a boolean parameter that renders as a checkbox in the UI.
+`StringParamOptions`: `{ maxLength?: number }`
 
-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.
+#### `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` for CLI overrides. Pass `1` for true and `0` for false.
 
 ```ts
 const showHoles = Param.bool("Show Holes", true);
@@ -638,29 +813,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
@@ -679,6 +842,90 @@ 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.
@@ -1356,7 +1603,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
 
@@ -1596,6 +1843,99 @@ 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. |
 
+### `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.
+
+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 |
+|----------|------|-------------|
+| `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:**
+
+#### `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.
+
+#### `toCurveSegmentsOnXZ(y?: number, options?: Spline2DCurveOptions): NurbsCurve3D[]` — Fit the spline on XZ and return separate curve segments split at `G0` nodes.
+
+#### `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.
@@ -1667,6 +2007,7 @@ Pass `{ edge }` to match an adjacent sheet's tangent (G1) or curvature (G2), or
 - `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`**
@@ -2884,6 +3225,7 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 - [Surface](#surface)
 - [Blend](#blend)
 - [Analysis](#analysis)
+- [Thickness](#thickness)
 - [Product](#product)
 - [Carrier](#carrier)
 - [SurfaceMembers](#surfacemembers)
@@ -3493,6 +3835,10 @@ Use this when the guide path runs in the surface V direction and the sketch prof
 
 #### `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).
 
+#### `thickenInsideBy(thickness: ThicknessInput, options?: { resolution?: number; }): Shape` — Thicken this sheet inward by a scalar UV thickness field.
+
+Numeric input delegates to `Sheet.thicken()`. `Thickness.*` fields produce a sampled solid because a variable normal offset is not generally an exact NURBS surface.
+
 #### `matchEdge(edge: SheetEdge): MatchEdgeBuilder` — Per-edge continuity match against a neighbor (returns a NEW Sheet).
 
 - `get rearEdge(): SheetEdge`
@@ -4368,6 +4714,14 @@ Members (full entries under [Curves & Surfacing](#curves-surfacing)): `Curve.Ble
 - `SurfaceHealth(shape: Shape, options?: { tinyEdgeThreshold?: number; sliverThreshold?: number; }): SurfaceHealthReport`
 - `BRepValidity(shape: Shape, options?: BRepValidityOptions): BRepValidityReport` — Validate B-rep/shell/solid structure and return closedness, manifoldness, orientation, and issue diagnostics.
 
+### `Thickness`
+
+- `constant: (thickness: number) => ThicknessField` — Use the same wall thickness everywhere on the sheet.
+- `alongU: (profile: ThicknessStation[] | ThicknessStationProfile) => ThicknessField` — Vary wall thickness across the sheet U direction.
+- `alongV: (profile: ThicknessStation[] | ThicknessStationProfile) => ThicknessField` — Vary wall thickness across the sheet V direction.
+- `grid: (values: number[][], options?: ThicknessGridOptions) => ThicknessField` — Bilinearly interpolate wall thickness from a rectangular UV grid.
+- `nurbs: (values: number[][], options?: ThicknessNurbsOptions) => ThicknessField` — Interpolate wall thickness from a scalar tensor-product B-spline over sheet UV.
+
 ### `Product`
 
 - `skin(name: string): ProductSkinBuilder` — Start a named product skin builder.
@@ -5388,6 +5742,17 @@ Use structural FEA when you want a ForgeCAD model to answer a load-case question
 
 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.
 
+## Contents
+
+- What You Get
+- What You Need Installed
+- Author The Study
+- Choose Stable Regions
+- Run The Flow
+- Read The Results
+- Current Scope
+- Troubleshooting
+
 ## What You Get
 
 A solved FEA result bundle can produce: