forgecad 0.6.3 → 0.8.0

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

@@ -5,440 +5,509 @@ skill-order: 100
 
 # Viewport & Runtime
 
-> **Auto-generated** from `src/forge/forge-public-api.ts`. Do not edit by hand — run `npm run gen:docs` to regenerate.
-
 Cut planes, exploded views, joint animations, and scene configuration.
 
+## Contents
+
+- [Viewport & Runtime](#viewport-runtime) — `jointsView`, `explodeView`, `cutPlane`, `cutPlane`, `mock`, `scene`, `viewConfig`, `showLabels`, `highlight`, `highlight`, `highlight`, `highlight`, `highlight`, `highlight`, `highlight`, `highlight`
+- [RouteBuilder](#routebuilder)
+- [route](#route)
+
 ## Functions
 
 ### Viewport & Runtime
 
-Configure viewport behavior: cut planes, exploded views, joint controls.
+#### `jointsView()` — Register viewport-only mechanism controls that animate returned objects without re-running the script.
 
-#### `jointsView()`
+Defines joints (revolute or prismatic), optional gear/rack couplings, and named animations. The viewport resolves transforms through the joint chain at display time — the script geometry is computed only once at rest pose.
 
-```ts
-jointsView(options?: JointsViewOptions): void
+**Critical:** Solve the assembly at **rest pose** (all animated joints = 0). The viewport applies `jointsView` transforms on top of the returned scene. If geometry is already solved at non-zero angles, animation will double-rotate everything.
+
+```js
+// BAD — double rotation
+const solved = mech.solve({ shoulder: 45, elbow: 30 });
+jointsView({ joints: [{ name: 'shoulder', ... }] });
+return solved;
+
+// GOOD — rest pose, jointsView controls all posing
+const solved = mech.solve({ shoulder: 0, elbow: 0 });
+jointsView({
+  joints: [
+    { name: 'shoulder', child: 'Upper Arm', default: 45, ... },
+    { name: 'elbow', child: 'Forearm', parent: 'Upper Arm', default: 30, ... },
+  ],
+});
+return solved;
 ```
 
-Configure runtime joint controls that animate object transforms in the viewport without re-running the script.
+**Pivot coordinates** are world-space positions of each joint origin at rest pose. For `addRevolute('shoulder', 'Base', 'Link', { frame: Transform.identity().translate(0, 0, 20) })` where "Base" is at world origin, the pivot is `[0, 0, 20]`.
 
-<details><summary><code>JointsViewOptions</code></summary>
+**Fixed attachments** that must follow a parent during animation need a zero-angle revolute joint in the chain:
 
-```ts
-interface JointsViewOptions {
-  enabled?: boolean;
-  joints?: JointViewInput[];
-  couplings?: JointViewCouplingInput[];
-  animations?: JointViewAnimationInput[];
-  defaultAnimation?: string;
-}
+```js
+{ name: 'EE_Follow', child: 'End Effector', parent: 'Last Link',
+  type: 'revolute', axis: [0, 0, 1], pivot: [linkLength, 0, 0],
+  min: 0, max: 0, default: 0 }
 ```
 
-</details>
+Animation values are interpolated linearly between keyframes. ForgeCAD does **not** auto-wrap revolute values across `-180/180`. Keep keyframe values continuous — a `-180 -> 171` jump spins the part the long way around. Use `-180 -> -189` instead. Author high-speed multi-turn joints as accumulating angles (`0, 360, 720, ...`) with `continuous: true`.
 
-<details><summary><code>JointViewInput</code></summary>
+**Tick-based keyframes:** Omit `at` from all keyframes to auto-distribute by tick weight:
 
-```ts
-interface JointViewInput {
-  name: string;
-  child: string;
-  parent?: string;
-  type?: JointViewType;
-  axis?: JointViewAxis;
-  min?: number;
-  max?: number;
-  default?: number;
-  unit?: string;
-  hidden?: boolean;
-}
+```js
+keyframes: [
+  { ticks: 3, values: { Shoulder: 20 } },  // slow segment (3x weight)
+  { ticks: 1, values: { Shoulder: -10 } }, // fast segment (1x weight)
+  { values: { Shoulder: 20 } },            // last keyframe; ticks ignored
+]
+// positions: 0, 0.75, 1.0
 ```
 
-</details>
-
-<details><summary><code>JointViewCouplingInput</code></summary>
+Mixing explicit `at` and omitted `at` in the same animation is not allowed.
+
+```js
+jointsView({
+  joints: [{
+    name: 'Shoulder', child: 'Upper Arm', parent: 'Base',
+    type: 'revolute', axis: [0, -1, 0], pivot: [0, 0, 46],
+    min: -30, max: 110, default: 15,
+  }],
+  animations: [{
+    name: 'Walk Cycle', duration: 1.6, loop: true,
+    keyframes: [
+      { values: { Shoulder: 20 } },
+      { values: { Shoulder: -10 } },
+      { values: { Shoulder: 20 } },
+    ],
+  }],
+});
+```
 
 ```ts
-interface JointViewCouplingInput {
-  joint: string;
-  terms: JointViewCouplingTermInput[];
-  offset?: number;
-}
+jointsView(options?: JointsViewOptions): void
 ```
 
-</details>
+**`JointsViewOptions`**: `enabled?: boolean`, `joints?: JointViewInput[]`, `couplings?: JointViewCouplingInput[]`, `animations?: JointViewAnimationInput[]`, `defaultAnimation?: string`
 
-<details><summary><code>JointViewCouplingTermInput</code></summary>
+**`JointViewInput`**: `name: string`, `child: string`, `parent?: string`, `type?: JointViewType`, `axis?: JointViewAxis`, `min?: number`, `max?: number`, `default?: number`, `unit?: string`, `hidden?: boolean`
 
-```ts
-interface JointViewCouplingTermInput {
-  joint: string;
-  ratio?: number;
-}
-```
+`JointViewCouplingInput`: `{ joint: string, terms: JointViewCouplingTermInput[], offset?: number }`
+
+`JointViewCouplingTermInput`: `{ joint: string, ratio?: number }`
+
+`JointViewAnimationInput`: `{ name: string, duration?: number, loop?: boolean, continuous?: boolean, keyframes: JointViewAnimationKeyframeInput[] }`
+
+**`JointViewAnimationKeyframeInput`**
+- `at?: number` — Timeline position [0, 1]. If omitted from ALL keyframes, positions are auto-computed from tick weights.
+- `ticks?: number` — Relative weight of the segment from this keyframe to the next (default 1). Only used in tick-based mode (when `at` is omitted). Last keyframe's ticks value is ignored.
+- Also: `values: Record<string, number>`
 
-</details>
+#### `explodeView()` — Configure how the viewport explode slider offsets returned objects.
 
-<details><summary><code>JointViewAnimationInput</code></summary>
+Offsets are resolved from the returned object tree, not a flat list. In `radial` mode each node follows its parent branch direction, then fans locally from the immediate parent center — nested assemblies peel apart level by level. In fixed-axis or fixed-vector modes, the branch follows that axis/vector but nested descendants fan out perpendicular by default.
+
+Multiple calls merge — later values override earlier ones on a per-key basis. `byName` and `byPath` maps are merged entry-by-entry.
+
+For programmatic explode applied before returning (without the slider), use `lib.explode()` instead.
+
+```js
+explodeView({
+  amountScale: 1.2,
+  stages: [0.35, 0.8],
+  mode: 'radial',
+  byPath: { 'Drive/Shaft': { direction: [1, 0, 0], stage: 1.6 } },
+});
+```
 
 ```ts
-interface JointViewAnimationInput {
-  name: string;
-  duration?: number;
-  loop?: boolean;
-  continuous?: boolean;
-  keyframes: JointViewAnimationKeyframeInput[];
-}
+explodeView(options?: ExplodeViewOptions): void
 ```
 
-</details>
+**`ExplodeViewOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `enabled?` | `boolean` | Set false to disable viewport explode offsets for this script output. |
+| `amountScale?` | `number` | Scales the UI explode amount. Default: 1 |
+| `stages?` | `number[]` | Per-depth stage multipliers (depth 1 = first level). If depth exceeds this array, the last value is reused. Default when omitted: reciprocal depth (1, 1/2, 1/3, ...) |
+| `mode?` | `ExplodeViewDirection` | Global direction mode fallback. Default: 'radial' |
+| `axisLock?` | `ExplodeAxis` | Global axis lock fallback. |
+| `byName?` | `Record<string, ExplodeViewDirective>` | Per-object overrides by final object name. |
+| `byPath?` | `Record<string, ExplodeViewDirective>` | Per-tree-path overrides using slash-separated object tree segments. |
+
+**`ExplodeDirective`**
+- `stage?: number` — Multiplier applied to `amount` for this node
+- `direction?: ExplodeDirection` — Direction mode for this node
+- `axisLock?: ExplodeAxis` — Optional axis lock after direction is resolved
+
+#### `cutPlane()` — Define a named section plane for inspecting internal geometry.
+
+Registers a cut plane that appears as a toggle in the viewport View Panel. When enabled, geometry on the positive side of the plane (the side the normal points toward) is clipped away, revealing the internal cross-section. The newly exposed section faces render with a hatched overlay; pre-existing coplanar boundary faces are left unhatched.
 
-<details><summary><code>JointViewAnimationKeyframeInput</code></summary>
+Planes are registered once per script run. The viewport toggle state (on/off) persists across parameter changes without re-running the script. The `exclude` option only works correctly when the excluded object names are stable across parameter changes.
+
+Accepts two overloads: `cutPlane(name, normal, offset?, options?)` or `cutPlane(name, normal, options?)` where options may include `offset`.
+
+```js
+const cutZ = param('Cut Height', 10, { min: -50, max: 50, unit: 'mm' });
+cutPlane('Inspection', [0, 0, 1], cutZ, { exclude: ['Probe', 'Fasteners'] });
+```
 
 ```ts
-interface JointViewAnimationKeyframeInput {
-  /** Timeline position [0, 1]. If omitted from ALL keyframes, positions are auto-computed from tick weights. */
-  at?: number;
-  /** Relative weight of the segment from this keyframe to the next (default 1). Only used in tick-based mode (when `at` is omitted). Last keyframe's ticks value is ignored. */
-  ticks?: number;
-  values: Record<string, number>;
-}
+cutPlane(name: string, normal: [ number, number, number ], offset?: number, options?: CutPlaneOptions): void
 ```
 
-</details>
+**`CutPlaneOptions`**
+- `offset?: number` — Optional offset along the plane normal (primarily for object-form overload).
+- `exclude?: CutPlaneExcludeInput` — Object names to keep uncut for this plane.
 
-#### `explodeView()`
+#### `cutPlane()`
 
 ```ts
-explodeView(options?: ExplodeViewOptions): void
+cutPlane(name: string, normal: [ number, number, number ], options?: CutPlaneOptions): void
 ```
 
-Configure viewport exploded-view behavior for the current script execution. Multiple calls merge; later values override earlier ones.
+#### `mock()` — Register a mock (context) object for visualization and collision checking.
 
-<details><summary><code>ExplodeViewOptions</code></summary>
+Mock objects appear in the viewport and spatial analysis when you run a file directly, but are excluded when the file is imported via [`require()`](/docs/core#require). This lets you model the surrounding context — walls, bolts, mating parts — without polluting the module's exports.
+
+The shape is returned unchanged, so you can reference it for alignment, dimensioning, and `verify` checks.
+
+Mock objects participate in `forgecad run` collision detection and spatial analysis. Their names appear with a `(mock)` suffix in reports.
+
+In the viewport, mock objects render at reduced opacity so they are visually distinct from real geometry.
 
 ```ts
-interface ExplodeViewOptions {
-  /** Set false to disable viewport explode offsets for this script output. */
-  enabled?: boolean;
-  /** Scales the UI explode amount. Default: 1 */
-  amountScale?: number;
-  /** Per-depth stage multipliers (depth 1 = first level). If depth exceeds this array, the last value is reused. Default when omitted: reciprocal depth (1, 1/2, 1/3, ...) */
-  stages?: number[];
-  /** Global direction mode fallback. Default: 'radial' */
-  mode?: ExplodeViewDirection;
-  /** Global axis lock fallback. */
-  axisLock?: ExplodeAxis;
-  /** Per-object overrides by final object name. */
-  byName?: Record<string, ExplodeViewDirective>;
-  /** Per-tree-path overrides using slash-separated object tree segments. */
-  byPath?: Record<string, ExplodeViewDirective>;
-}
+// bracket.forge.js
+const wall = mock(box(100, 200, 10).translate(0, 0, -5), "wall");
+const bolt = mock(cylinder(3, 15).translate(10, 15, 0), "bolt");
+
+const bracket = box(20, 30, 5);
+verify.notColliding("bracket vs wall", bracket, wall);
+
+return bracket;
+// When imported: only bracket is exported
+// When run directly: bracket + wall + bolt all visible
 ```
 
-</details>
+```ts
+mock<T extends Shape>(shape: T, name?: string): T
+```
 
-<details><summary><code>ExplodeDirective</code></summary>
+#### `scene()` — Configure the scene environment for the current script execution.
+
+Controls camera position, lighting rig, background color or gradient, atmospheric fog, environment maps, post-processing effects, and capture parameters for the `forgecad capture` command. Multiple calls merge — later values override earlier ones on a per-key basis, so you can split configuration across multiple `scene()` calls.
+
+When `lights` is specified, **all** default lights are removed. You must include your own ambient light or the scene will be fully dark.
+
+Setting `camera.position` overrides auto-framing — the viewport will no longer auto-fit the geometry on script reload.
+
+Post-processing effects (`bloom`, `vignette`, `grain`) work in the browser viewport only. The CLI applies camera, lights, background, fog, and `toneMappingExposure` but skips shader effects.
+
+All numeric values accept `param()` expressions.
+
+```js
+scene({
+  background: { top: '#000814', bottom: '#001d3d' },
+  camera: { position: [160, -120, 100], target: [0, 0, 50], fov: 52 },
+  lights: [
+    { type: 'ambient', color: '#001233', intensity: 0.08 },
+    { type: 'point', position: [120, -80, 130], color: '#00f5d4', intensity: 4, distance: 400, decay: 1 },
+    { type: 'point', position: [-100, 60, 20], color: '#f72585', intensity: 3, distance: 350 },
+    { type: 'directional', position: [50, -30, 200], color: '#ffd60a', intensity: 1.2 },
+    { type: 'hemisphere', skyColor: '#003566', groundColor: '#000814', intensity: 0.2 },
+  ],
+  fog: { color: '#000814', near: 100, far: 450 },
+  postProcessing: {
+    bloom: { intensity: param('bloom', 1.5, 0, 4), threshold: 0.5, radius: 0.7 },
+    vignette: { darkness: 0.8, offset: 0.25 },
+    grain: { intensity: 0.08 },
+    toneMappingExposure: param('exposure', 1.5, 0.5, 4),
+  },
+});
+```
 
 ```ts
-interface ExplodeDirective {
-  /** Multiplier applied to `amount` for this node */
-  stage?: number;
-  /** Direction mode for this node */
-  direction?: ExplodeDirection;
-  /** Optional axis lock after direction is resolved */
-  axisLock?: ExplodeAxis;
-}
+scene(options: SceneOptions): void
 ```
 
-</details>
+**`SceneOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `capture?` | `SceneCaptureConfig` | Default capture parameters for `forgecad capture` — CLI flags override these. |
+| `background?`, `camera?`, `lights?`, `environment?`, `fog?`, `postProcessing?`, `ground?` | | — |
+
+`SceneBackgroundGradient`: `{ top: string, bottom: string }`
+
+`SceneCameraConfig`: `{ fov?: number, type?: "perspective" | "orthographic" }`
+
+**`SceneLightConfig`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `groundColor?` | `string` | Ground color for hemisphere lights |
+| `skyColor?` | `string` | Sky color alias for hemisphere lights (same as color) |
+| `angle?` | `number` | Spot light cone angle in radians |
+| `penumbra?` | `number` | Spot light penumbra (0–1) |
+| `decay?` | `number` | Point/spot light decay |
+| `distance?` | `number` | Point/spot light distance (0 = infinite) |
+| `castShadow?` | `boolean` | Whether this light casts shadows |
+| `type`, `color?`, `intensity?` | | — |
+
+**`SceneEnvironmentConfig`**
+- `preset?: "studio" | "sunset" | "dawn" | "warehouse" | "forest" | "apartment" | "lobby" | "city" | "park" | "night" | "none"` — Built-in preset name or 'none' to disable
+- `intensity?: number` — Environment map intensity
+- `background?: boolean` — Use environment map as scene background
+
+**`SceneFogConfig`**
+- `near?: number` — Linear fog near distance
+- `far?: number` — Linear fog far distance
+- `density?: number` — Exponential fog density (if set, uses FogExp2 instead of linear Fog)
+- Also: `color?: string`
+
+`ScenePostProcessingConfig`: `{ bloom?: SceneBloomConfig, vignette?: SceneVignetteConfig, grain?: SceneGrainConfig, toneMappingExposure?: number }`
+
+`SceneBloomConfig`: `{ intensity?: number, threshold?: number, radius?: number }`
 
-<details><summary><code>ExplodeViewDirective</code> extends ExplodeDirective</summary>
+`SceneVignetteConfig`: `{ darkness?: number, offset?: number }`
+
+`SceneGrainConfig`: `{ intensity?: number }`
+
+**`SceneGroundConfig`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `visible?` | `boolean` | Show a ground plane |
+| `color?` | `string` | Ground color |
+| `offset?` | `number` | Offset below the model's bounding box minimum Z. Default 0 (flush with model bottom). |
+| `receiveShadow?` | `boolean` | Receive shadows on the ground |
+
+**`SceneCaptureConfig`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `framesPerTurn?` | `number` | Frames for one full orbit rotation (default: 72) |
+| `holdFrames?` | `number` | Frozen frames before motion starts (default: 6) |
+| `pitchDeg?` | `number` | Orbit pitch angle in degrees (default: auto from camera) |
+| `fps?` | `number` | Output frame rate (default: 24) |
+| `size?` | `number` | Output frame size in pixels (default: 960) |
+| `background?` | `string` | Canvas background color for capture (default: '#252526') |
+
+#### `viewConfig()` — Configure viewport helper visuals for the current script execution.
+
+Controls renderer-only overlays that appear in the viewport but are not part of the geometry. Currently supports the joint overlay that renders axis arrows and arc indicators when `jointsView` is active. Multiple calls merge — later values override earlier ones per key.
+
+This does **not** trigger a geometry recompute; it only affects the visual helpers drawn on top of the 3D scene.
+
+```js
+viewConfig({
+  jointOverlay: {
+    axisColor: '#13dfff',
+    arcColor: '#ff7a1a',
+    axisLineRadiusScale: 0.03,
+    arcLineRadiusScale: 0.022,
+  },
+});
+```
 
 ```ts
-interface ExplodeViewDirective extends ExplodeDirective {
-}
+viewConfig(options?: ViewConfigOptions): void
 ```
 
-</details>
+`ViewConfigOptions`: `{ jointOverlay?: JointOverlayViewConfigOptions }`
 
-#### `cutPlane()`
+**`JointOverlayViewConfigOptions`**: `enabled?: boolean`, `axisColor?: string`, `axisCoreColor?: string`, `arcColor?: string`, `zeroColor?: string`, `arcVisualLimitDeg?: number`, `axisLengthScale?: number`, `axisLengthMin?: number`, `axisLineRadiusScale?: number`, `axisLineRadiusMin?: number`, `axisLineRadiusMax?: number`, `spokeLineRadiusScale?: number`, `spokeLineRadiusMin?: number`, `spokeLineRadiusMax?: number`, `arcLineRadiusScale?: number`, `arcLineRadiusMin?: number`, `arcLineRadiusMax?: number`, `axisDotRadiusScale?: number`, `axisDotRadiusMin?: number`, `axisArrowRadiusScale?: number`, `axisArrowRadiusMin?: number`, `axisArrowLengthScale?: number`, `axisArrowLengthMin?: number`, `axisArrowOffsetFactor?: number`, `arcRadiusScale?: number`, `arcRadiusMin?: number`, `arcDotRadiusScale?: number`, `arcDotRadiusMin?: number`, `arcArrowRadiusScale?: number`, `arcArrowRadiusMin?: number`, `arcArrowLengthScale?: number`, `arcArrowLengthMin?: number`, `arcArrowOffsetFactor?: number`, `arcStepDeg?: number`, `arcMinSteps?: number`, `arcTubeSegmentsMin?: number`, `arcTubeSegmentsFactor?: number`, `arcTubeRadialSegments?: number`
+
+#### `showLabels()` — Highlight all user-labeled faces on a shape for visual debugging.
+
+Shows each user-authored label name in the viewport for visual debugging. Returns the shape unchanged for chaining: `return showLabels(myShape)`.
 
 ```ts
-cutPlane(name: string, normal: [ number, number, number ], offset?: number, options?: CutPlaneOptions): void
+showLabels(shape: Shape): Shape
 ```
 
-Define a named section/cut plane. Appears as a toggle in the View Panel. When enabled, geometry on the positive side of the plane is clipped away.
+#### `highlight()` — Highlight any geometry for visual debugging in the viewport.
 
-<details><summary><code>CutPlaneOptions</code></summary>
+Supported inputs:
+
+- `string` — sketch entity ID (e.g. `'L0'`, `'P0'`, `'C0'`)
+- `[x, y, z]` — 3D point
+- `[[x1,y1,z1], [x2,y2,z2]]` — edge (line segment)
+- `{ normal: [x,y,z], offset: number }` — plane by normal + distance from origin
+- `{ normal: [x,y,z], point: [x,y,z] }` — plane by normal + point on plane
+- [`Shape`](/docs/core#shape) — highlight entire 3D shape
+- `FaceRef` (from `shape.face('top')`) — highlight as plane at face center
+- `EdgeRef` (from `shape.edge('left')`) — highlight as edge segment
 
 ```ts
-interface CutPlaneOptions {
-  /** Optional offset along the plane normal (primarily for object-form overload). */
-  offset?: number;
-  /** Object names to keep uncut for this plane. */
-  exclude?: CutPlaneExcludeInput;
-}
+highlight(entityId: string, opts?: HighlightOptions): void
 ```
 
-</details>
+**`HighlightOptions`**
+- `size?: number` — Size hint for points (radius in mm) or planes (disc radius in mm).
+- Also: `color?: string, label?: string, pulse?: boolean`
 
-#### `cutPlane()`
+#### `highlight()`
 
 ```ts
-cutPlane(name: string, normal: [ number, number, number ], options?: CutPlaneOptions): void
+highlight(point: [ number, number, number ], opts?: HighlightOptions): void
 ```
 
-#### `scene()`
+#### `highlight()`
 
 ```ts
-scene(options: SceneOptions): void
+highlight(edge: [ [ number, number, number ], [ number, number, number ] ], opts?: HighlightOptions): void
 ```
 
-Configure the scene environment for the current script execution. Controls camera, lighting, background, fog, and post-processing. Multiple calls merge; later values override earlier ones. ```js scene({ background: '#0a0a0a', camera: { position: [200, 100, 150], target: [0, 0, 30], fov: 60 }, lights: [ { type: 'ambient', color: '#1a1a2e', intensity: 0.2 }, { type: 'point', position: [0, 0, 100], color: '#ff6b35', intensity: 2 }, ], fog: { color: '#0a0a0a', near: 100, far: 500 }, postProcessing: { bloom: { intensity: 1.5, threshold: 0.8, radius: 0.4 }, }, }); ```
+#### `highlight()`
 
-<details><summary><code>SceneOptions</code></summary>
+```ts
+highlight(plane: { normal: [ number, number, number ]; offset: number; }, opts?: HighlightOptions): void
+```
+
+#### `highlight()`
 
 ```ts
-interface SceneOptions {
-  background?: string | SceneBackgroundGradient;
-  camera?: SceneCameraConfig;
-  lights?: SceneLightConfig[];
-  environment?: SceneEnvironmentConfig;
-  fog?: SceneFogConfig;
-  postProcessing?: ScenePostProcessingConfig;
-  ground?: SceneGroundConfig;
-  /** Default capture parameters for `forgecad capture` — CLI flags override these. */
-  capture?: SceneCaptureConfig;
-}
+highlight(plane: { normal: [ number, number, number ]; point: [ number, number, number ]; }, opts?: HighlightOptions): void
 ```
 
-</details>
+#### `highlight()`
+
+```ts
+highlight(shape: Shape, opts?: HighlightOptions): void
+```
 
-<details><summary><code>SceneBackgroundGradient</code></summary>
+#### `highlight()`
 
 ```ts
-interface SceneBackgroundGradient {
-  top: string;
-  bottom: string;
-}
+highlight(face: FaceRef, opts?: HighlightOptions): void
 ```
 
-</details>
+**`FaceRef`**
+- `query?: FaceQueryRef` — Compiler-owned face query when available.
+- `planar?: boolean` — True when the face can host a 2D sketch placement frame
+- `descendant?: FaceDescendantMetadata` — Shared descendant-resolution metadata when this face is a semantic region/set.
+- Also: `name: FaceName`
+
+**`FaceDescendantMetadata`**: `kind: "single" | "face-set"`, `semantic: FaceDescendantSemantic`, `memberCount: number`, `memberNames: string[]`, `coplanar: boolean`
 
-<details><summary><code>SceneCameraConfig</code></summary>
+#### `highlight()`
 
 ```ts
-interface SceneCameraConfig {
-  fov?: number;
-  type?: "perspective" | "orthographic";
-}
+highlight(edge: EdgeRef, opts?: HighlightOptions): void
 ```
 
-</details>
+**`EdgeRef`**
+- `query?: EdgeQueryRef` — Compiler-owned edge query when available.
+- Also: `name: EdgeName`
 
-<details><summary><code>SceneLightConfig</code></summary>
+---
+
+## Classes
+
+### `RouteBuilder`
+
+#### `up()` — Vertical line going +Y. Length is optional (solver determines it from constraints).
 
 ```ts
-interface SceneLightConfig {
-  type: SceneLightType;
-  color?: string;
-  intensity?: number;
-  /** Ground color for hemisphere lights */
-  groundColor?: string;
-  /** Sky color alias for hemisphere lights (same as color) */
-  skyColor?: string;
-  /** Spot light cone angle in radians */
-  angle?: number;
-  /** Spot light penumbra (0–1) */
-  penumbra?: number;
-  /** Point/spot light decay */
-  decay?: number;
-  /** Point/spot light distance (0 = infinite) */
-  distance?: number;
-  /** Whether this light casts shadows */
-  castShadow?: boolean;
-}
+up(length?: number): LineId
 ```
 
-</details>
+#### `down()` — Vertical line going -Y. Length is optional.
+
+```ts
+down(length?: number): LineId
+```
 
-<details><summary><code>SceneEnvironmentConfig</code></summary>
+#### `right()` — Horizontal line going +X. Length is optional.
 
 ```ts
-interface SceneEnvironmentConfig {
-  /** Built-in preset name or 'none' to disable */
-  preset?: "studio" | "sunset" | "dawn" | "warehouse" | "forest" | "apartment" | "lobby" | "city" | "park" | "night" | "none";
-  /** Environment map intensity */
-  intensity?: number;
-  /** Use environment map as scene background */
-  background?: boolean;
-}
+right(length?: number): LineId
 ```
 
-</details>
+#### `left()` — Horizontal line going -X. Length is optional.
 
-<details><summary><code>SceneFogConfig</code></summary>
+```ts
+left(length?: number): LineId
+```
+
+#### `lineAt()` — Line at an arbitrary angle (degrees from +X). Length is optional.
 
 ```ts
-interface SceneFogConfig {
-  color?: string;
-  /** Linear fog near distance */
-  near?: number;
-  /** Linear fog far distance */
-  far?: number;
-  /** Exponential fog density (if set, uses FogExp2 instead of linear Fog) */
-  density?: number;
-}
+lineAt(angleDeg: number, length?: number): LineId
 ```
 
-</details>
+#### [`line()`](/docs/sketch#line) — Line with solver-determined direction. Length is optional. Direction comes from tangency to previous arc or from constraints.
+
+```ts
+line(length?: number): LineId
+```
 
-<details><summary><code>ScenePostProcessingConfig</code></summary>
+#### `toward()` — Line toward a specific point. Length defaults to the distance to that point.
 
 ```ts
-interface ScenePostProcessingConfig {
-  bloom?: SceneBloomConfig;
-  vignette?: SceneVignetteConfig;
-  grain?: SceneGrainConfig;
-  toneMappingExposure?: number;
-}
+toward(x: number, y: number): LineId
 ```
 
-</details>
+#### `arcLeft()` — Tangent arc turning left relative to travel direction.
 
-<details><summary><code>SceneBloomConfig</code></summary>
+or `{ minSweep: degrees }` to seed the geometry without constraining. `minSweep` guides the solver to the correct branch for arcs that sweep more than the default 90° seed.
 
 ```ts
-interface SceneBloomConfig {
-  intensity?: number;
-  threshold?: number;
-  radius?: number;
-}
+arcLeft(radius?: number, sweepDegOrOpts?: number | { minSweep: number; }): ArcId
 ```
 
-</details>
+#### `arcRight()` — Tangent arc turning right relative to travel direction.
 
-<details><summary><code>SceneVignetteConfig</code></summary>
+or `{ minSweep: degrees }` to seed without constraining.
 
 ```ts
-interface SceneVignetteConfig {
-  darkness?: number;
-  offset?: number;
-}
+arcRight(radius?: number, sweepDegOrOpts?: number | { minSweep: number; }): ArcId
 ```
 
-</details>
-
-<details><summary><code>SceneGrainConfig</code></summary>
+#### `close()` — Close the route with a straight line back to the start point.
 
 ```ts
-interface SceneGrainConfig {
-  intensity?: number;
-}
+close(): void
 ```
 
-</details>
+#### `done()` — Close the route back to its start point and register as a profile loop.
 
-<details><summary><code>SceneGroundConfig</code></summary>
+No extra line segment is added. A coincident constraint connects the last point to the start, and tangency is added for G1 smoothness when arcs are at the junction. The session's incremental solver processes these constraints, keeping seed positions accurate for the final solve.
 
 ```ts
-interface SceneGroundConfig {
-  /** Show a ground plane */
-  visible?: boolean;
-  /** Ground color */
-  color?: string;
-  /** Offset below the model's bounding box minimum Z. Default 0 (flush with model bottom). */
-  offset?: number;
-  /** Receive shadows on the ground */
-  receiveShadow?: boolean;
-}
+done(): void
 ```
 
-</details>
+#### `start()` — PointId of the route's start point.
+
+```ts
+get start(): PointId
+```
 
-<details><summary><code>SceneCaptureConfig</code></summary>
+#### `end()` — PointId of the current cursor (route's end).
 
 ```ts
-interface SceneCaptureConfig {
-  /** Frames for one full orbit rotation (default: 72) */
-  framesPerTurn?: number;
-  /** Frozen frames before motion starts (default: 6) */
-  holdFrames?: number;
-  /** Orbit pitch angle in degrees (default: auto from camera) */
-  pitchDeg?: number;
-  /** Output frame rate (default: 24) */
-  fps?: number;
-  /** Output frame size in pixels (default: 960) */
-  size?: number;
-  /** Canvas background color for capture (default: '#252526') */
-  background?: string;
-}
+get end(): PointId
 ```
 
-</details>
+#### `startOf()` — Get the start point of a segment.
+
+```ts
+startOf(segId: LineId | ArcId): PointId
+```
 
-#### `viewConfig()`
+#### `endOf()` — Get the end point of a segment.
 
 ```ts
-viewConfig(options?: ViewConfigOptions): void
+endOf(segId: LineId | ArcId): PointId
 ```
 
-Configure runtime viewport visuals for the current script execution. Multiple calls merge; later values override earlier ones.
-
-<details><summary><code>ViewConfigOptions</code></summary>
-
-```ts
-interface ViewConfigOptions {
-  jointOverlay?: JointOverlayViewConfigOptions;
-}
-```
-
-</details>
-
-<details><summary><code>JointOverlayViewConfigOptions</code></summary>
-
-```ts
-interface JointOverlayViewConfigOptions {
-  enabled?: boolean;
-  axisColor?: string;
-  axisCoreColor?: string;
-  arcColor?: string;
-  zeroColor?: string;
-  arcVisualLimitDeg?: number;
-  axisLengthScale?: number;
-  axisLengthMin?: number;
-  axisLineRadiusScale?: number;
-  axisLineRadiusMin?: number;
-  axisLineRadiusMax?: number;
-  spokeLineRadiusScale?: number;
-  spokeLineRadiusMin?: number;
-  spokeLineRadiusMax?: number;
-  arcLineRadiusScale?: number;
-  arcLineRadiusMin?: number;
-  arcLineRadiusMax?: number;
-  axisDotRadiusScale?: number;
-  axisDotRadiusMin?: number;
-  axisArrowRadiusScale?: number;
-  axisArrowRadiusMin?: number;
-  axisArrowLengthScale?: number;
-  axisArrowLengthMin?: number;
-  axisArrowOffsetFactor?: number;
-  arcRadiusScale?: number;
-  arcRadiusMin?: number;
-  arcDotRadiusScale?: number;
-  arcDotRadiusMin?: number;
-  arcArrowRadiusScale?: number;
-  arcArrowRadiusMin?: number;
-  arcArrowLengthScale?: number;
-  arcArrowLengthMin?: number;
-  arcArrowOffsetFactor?: number;
-  arcStepDeg?: number;
-  arcMinSteps?: number;
-  arcTubeSegmentsMin?: number;
-  arcTubeSegmentsFactor?: number;
-  arcTubeRadialSegments?: number;
-}
-```
-
-</details>
+---
+
+## Constants
+
+### `route`
+
+Route step factories. Access via `route.line()`, `route.fillet()`, etc.