forgecad 0.9.4 → 0.9.6

package/dist-skill/CONTEXT.md

@@ -25,6 +25,7 @@ Prefer documented primitives, import rules, and placement strategies over invent
 
 - `.forge.js` — parametric part or assembly script; return a `Shape`, `Sketch`, `ShapeGroup`, `Assembly`, `SolvedAssembly`, array of renderables, or metadata object. Assemblies render directly; do not add `.toGroup()` unless you need `ShapeGroup` behavior.
 - Model the physical artifact, not an educational diagram. Do not add explanatory labels, arrows, legends, or text plaques unless the user explicitly asks for a presentation or teaching view. Product markings are allowed only when they would exist on the real object.
+- Build the real closed CAD first. Do not bake cutaways, sectioned shells, permanently exploded layouts, or hidden-parts views into the default model just to show internals. Use viewer-only cut planes, `explodeView`, object hiding, transparency, or `render inspect` section channels after the artifact exists.
 
 ### Import and composition
 
@@ -58,10 +59,12 @@ Use the CLI to validate, inspect, and export the model the AI is editing. Keep c
 forgecad run path/to/model.forge.js
 forgecad run path/to/model.forge.js --debug-imports
 forgecad run path/to/model.forge.js --backend occt
+forgecad check print path/to/model.forge.js --json
 forgecad check params path/to/model.forge.js --samples 12
 ```
 
 - `forgecad run` prints geometry diagnostics, object summaries, collisions, verification results, and solver info.
+- `forgecad check print` reports collisions, mesh health, sampled walls, overhangs, and bed contact.
 - `forgecad check params` sweeps declared parameter ranges and reports crashes, degenerates, and new collisions.
 
 ## Visual Checks
@@ -126,7 +129,7 @@ Top-level declarations such as `const bom = ...`, `let scene = ...`, or `class S
 
 - Scripts re-execute on every parameter change (400ms debounce)
 - Geometry operations are **immutable** — shapes, sketches, groups, imported assemblies, and wood boards return new values instead of modifying in place
-- Must return one of: `Shape`, `Sketch`, `ShapeGroup`, `Assembly`, `SolvedAssembly`, `SdfShape`, `Array` of renderables, `Array` of `{ name, shape?, sketch?, group?, color? }`, or a **metadata object** (see below)
+- Must return one of: `Shape`, `Sketch`, `ShapeGroup`, `Assembly`, `SolvedAssembly`, `SdfShape`, `Array` of renderables, `Array` of `{ name, tags?, shape?, sketch?, group?, color? }`, or a **metadata object** (see below)
 
 Top-level assembly scripts can return an unsolved `Assembly` directly; ForgeCAD solves it at default joint values for display. Return `assembly.solve(state)` when you want a specific pose. Do not call `.toGroup()` just to make an assembly render — use `.toGroup()` only when you specifically need `ShapeGroup` composition, group-style transforms, or named-child lookup.
 
@@ -159,6 +162,16 @@ return {
 };
 ```
 
+Named return objects and named `group(...)` children can include `tags`. Tags are viewport metadata: they do not affect geometry, exports, face labels, or BOM rows, but the command palette can hide, show only, or focus every object with a selected tag.
+
+```javascript
+return [
+  { name: 'Base Plate', tags: ['printed', 'structural'], shape: base },
+  { name: 'M4 Bolt A', tags: 'fastener', shape: boltA },
+  { name: 'M4 Bolt B', tags: 'fastener', shape: boltB },
+];
+```
+
 ## Coordinate System
 
 Z-up right-handed: X = left/right, Y = forward/back, Z = up/down.
@@ -218,15 +231,15 @@ For organic shapes, smooth blending, TPMS lattices, and surface deformations. Re
 - [Grouping & Local Coordinates](#grouping-local-coordinates) — `group`
 - [Section & Projection](#section-projection) — `intersectWithPlane`, `faceProfile`, `projectToPlane`
 - [Transforms](#transforms) — `composeChain`
-- [Backend Runtime](#backend-runtime) — `initKernel`, `setActiveBackend`, `activateBackend`, `getActiveBackend`
 - [Verification](#verification) — `spec`
 - [Shape](#shape) — 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)
 - [ShapeRef](#shaperef)
 - [ANCHOR3D_NAMES](#anchor3d-names)
-- [DEFAULT_ACTIVE_BACKEND](#default-active-backend)
 - [verify](#verify)
 - [Constraint](#constraint)
 - [Points](#points)
@@ -321,9 +334,11 @@ intersection(...inputs: ShapeOperandInput[]): Shape
 
 ### Edge Features
 
-#### `fillet()` — Apply fillets (rounded edges) to one or more edges of a shape.
+#### `fillet()` — Apply experimental fillets (rounded edges) to one or more edges of a shape.
 
-Works on edge selections from any active backend. Truck and OCCT route edge finishes through native kernel operations; unsupported selections fail as explicit kernel gaps instead of using TypeScript geometry fallbacks.
+**Experimental**: fillets are still backend-sensitive. The Manifold backend is known to produce incorrect results for some edge-finish cases, and the OCCT backend can be very slow, especially with broad edge selections. Prefer targeted edge selectors and inspect the result before treating it as production-ready geometry.
+
+Edge selections compile into backend operations; unsupported selections fail as explicit kernel gaps instead of using TypeScript geometry fallbacks.
 
 The `edges` parameter is flexible:
 
@@ -349,9 +364,11 @@ fillet(myShape, 3, edges)
 fillet(shape: Shape, radius: number, edges?: EdgeSelector, segments?: number): Shape
 ```
 
-#### `chamfer()` — Apply chamfers (beveled edges) to one or more edges of a shape.
+#### `chamfer()` — Apply experimental chamfers (beveled edges) to one or more edges of a shape.
+
+**Experimental**: chamfers are still backend-sensitive. The Manifold backend is known to produce incorrect results for some edge-finish cases, and the OCCT backend can be very slow, especially with broad edge selections. Prefer targeted edge selectors and inspect the result before treating it as production-ready geometry.
 
-Produces a 45° bevel at the specified `size` (distance from edge). Works on edge selections from any active backend. Truck and OCCT route chamfers through native kernel operations; unsupported selections fail as explicit kernel gaps instead of using TypeScript geometry fallbacks.
+Produces a 45° bevel at the specified `size` (distance from edge). Edge selections compile into backend operations; unsupported selections fail as explicit kernel gaps instead of using TypeScript geometry fallbacks.
 
 The `edges` parameter accepts the same options as `fillet()`: inline `EdgeQuery`, pre-selected `EdgeSegment`/`EdgeSegment[]`, or `undefined` (all sharp edges).
 
@@ -576,11 +593,8 @@ selectEdges(shape: Shape, query?: EdgeQuery): EdgeSegment[]
 | `normalA` | `Vec3` | Normal of first adjacent face. |
 | `normalB` | `Vec3` | Normal of second adjacent face (same as normalA for boundary edges). |
 | `boundary` | `boolean` | true if this is a boundary (unmatched) edge — unusual for closed solids. |
-| `nativeTopology?` | `EdgeNativeTopologyRef` | Native kernel topology identity when the active backend can provide one. |
 | `start`, `end`, `midpoint`, `length` | | — |
 
-`EdgeNativeTopologyRef`: `{ backend: "truck", edge: number }`
-
 #### `selectEdge()` — Select the single best-matching edge from a shape.
 
 When `near` is specified, returns the edge whose midpoint is closest to that point. Otherwise returns the first matching edge in mesh order. Throws if no edges match the query — useful as a guard when you expect exactly one result.
@@ -681,7 +695,7 @@ importSvgSketch(fileName: string, options?: SvgImportOptions): Sketch
 importMesh(fileName: string, options?: { scale?: number; center?: boolean; }): Shape
 ```
 
-#### `importStep()` — Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires `setActiveBackend('occt')`.
+#### `importStep()` — Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires running with the OCCT backend.
 
 ```ts
 importStep(fileName: string): Shape
@@ -817,18 +831,21 @@ Param.list<T extends Record<string, number | boolean | string>>(name: string, de
 
 Unlike union(), child colors and individual identities are preserved. Children can be plain shapes, named descriptors ({ name, shape/sketch/group }), or nested groups. The returned ShapeGroup supports all Shape transforms (translate, rotate, etc.).
 
+Named descriptors can include `tags` for viewport organization. Tags do not affect geometry; they let the command palette hide, show only, or focus all objects with the same tag.
+
 **Local coordinate pattern:** Build child parts at the origin (local coordinates), then group and translate once to place the whole assembly. This eliminates the error-prone pattern of manually adding parent offsets to every sub-part.
 
 ```js
-// BAD — every sub-part repeats the parent's global offset
-const unitX = 0, unitY = -18, unitZ = 70;
-const body = roundedBox(100, 20, 32, 4).translate(unitX, unitY, unitZ);
-const panel = box(98, 2, 18).translate(unitX, unitY - 12, unitZ + 4);
-const louver = box(88, 2, 6).translate(unitX, unitY - 14, unitZ - 11);
+const body = roundedBox(100, 20, 32, 4);
+const panel = box(98, 2, 18).translate(0, -12, 4);
+const louver = box(88, 2, 6).translate(0, -14, -11);
+const indoorUnit = group(
+  { name: 'Body', shape: body },
+  { name: 'Panel', tags: 'cover', shape: panel },
+  { name: 'Louver', tags: ['cover', 'moving'], shape: louver },
+).translate(0, -18, 70);
 ```
 
-// GOOD — build at origin, group, translate once const body = roundedBox(100, 20, 32, 4); const panel = box(98, 2, 18).translate(0, -12, 4); const louver = box(88, 2, 6).translate(0, -14, -11); const indoorUnit = group( { name: 'Body', shape: body }, { name: 'Panel', shape: panel }, { name: 'Louver', shape: louver }, ).translate(0, -18, 70);
-
 ```ts
 group(...items: GroupInput[]): ShapeGroup
 ```
@@ -863,32 +880,6 @@ projectToPlane(shape: Shape, plane: PlaneSpec): Sketch
 composeChain(...steps: TransformInput[]): Transform
 ```
 
-### Backend Runtime
-
-#### `initKernel()`
-
-```ts
-initKernel(): Promise<unknown>
-```
-
-#### `setActiveBackend()`
-
-```ts
-setActiveBackend(backend: ActiveBackend): void
-```
-
-#### `activateBackend()` — Set the active backend and ensure its WASM module is initialized. Call this instead of `setActiveBackend` when you're about to execute code — it guarantees the backend is ready, not just selected.
-
-```ts
-activateBackend(backend: ActiveBackend): Promise<void>
-```
-
-#### `getActiveBackend()`
-
-```ts
-getActiveBackend(): ActiveBackend
-```
-
 ### Verification
 
 #### `spec()` — Create a named, reusable bundle of verification checks.
@@ -1874,6 +1865,82 @@ color(hex: string): ShapeGroup
 | `body` | `string` | Function body: receives (u, v) in surface mm, returns height displacement. |
 | `constants` | `Record<string, number>` | Named constants injected into the function. |
 
+### `Pattern2D`
+
+#### `add()` — Add this pattern to one or more patterns or constant height offsets.
+
+```ts
+add(...patterns: Pattern2DInput[]): Pattern2D
+```
+
+#### `subtract()` — Subtract another pattern or constant height offset from this pattern.
+
+```ts
+subtract(pattern: Pattern2DInput): Pattern2D
+```
+
+#### `multiply()` — Multiply this pattern by one or more patterns or numeric scale factors.
+
+```ts
+multiply(...patterns: Pattern2DInput[]): Pattern2D
+```
+
+#### `min()` — Keep the lower height between this pattern and one or more other patterns.
+
+```ts
+min(...patterns: Pattern2DInput[]): Pattern2D
+```
+
+#### `max()` — Keep the higher height between this pattern and one or more other patterns.
+
+```ts
+max(...patterns: Pattern2DInput[]): Pattern2D
+```
+
+#### `clamp()` — Limit pattern height to the inclusive `[min, max]` range in millimeters.
+
+```ts
+clamp(min: number, max: number): Pattern2D
+```
+
+#### `abs()` — Convert negative heights to positive heights.
+
+```ts
+abs(): Pattern2D
+```
+
+#### `negate()` — Flip the pattern height sign.
+
+```ts
+negate(): Pattern2D
+```
+
+### `Pattern2DBuilder`
+
+#### `constant()` — Create a constant-height pattern in millimeters.
+
+```ts
+constant(value?: number): Pattern2D
+```
+
+#### `sineWave()` — Create a sinusoidal wave pattern in UV space.
+
+```ts
+sineWave(options: Pattern2DSineWaveOptions): Pattern2D
+```
+
+#### `stripes()` — Create recessed stripe bands in UV space.
+
+```ts
+stripes(options: Pattern2DStripesOptions): Pattern2D
+```
+
+#### `overUnderWeave()` — Create an over-under woven relief pattern in UV space.
+
+```ts
+overUnderWeave(options: Pattern2DOverUnderWeaveOptions): Pattern2D
+```
+
 ### `ShapeRef`
 
 A first-class reference path over a shape's semantic faces and face relationships.
@@ -1996,10 +2063,6 @@ toString(): string
 
 ### `ANCHOR3D_NAMES`
 
-### `DEFAULT_ACTIVE_BACKEND`
-
-Default geometry backend when no explicit backend is selected.
-
 ### `verify`
 
 - `that(label: string, check: () => boolean, message?: string): void` — Custom predicate check.
@@ -3769,7 +3832,15 @@ detectArrangement(): Sketch[]
 #### `detectArrangementRegion()` — Select the single arrangement region that contains the given seed point. Throws if no region contains the seed.
 
 ```ts
-detectArrangementRegion(seed: [ number, number ]): Sketch
+detectArrangementRegion(_seed: [ number, number ]): Sketch
+```
+
+#### `toPolyline()` — Return the solved constrained path as a sampled 2D polyline.
+
+Use this when a construction rail was authored with `constrainedSketch()` and should feed another operation such as `Loft.pathOnXz(...)`. The sketch must contain exactly one profile path.
+
+```ts
+toPolyline(samples?: number): [ number, number ][]
 ```
 
 #### `withUpdatedConstraint()` — Re-solve the sketch after changing the value of one existing constraint.
@@ -4124,8 +4195,8 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 
 ## Contents
 
-- [Curves & Surfacing](#curves-surfacing) — `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
-- [Surface Members](#surface-members) — `surfaceBand`, `compileSurfaceMember`, `SurfaceBody`
+- [Curves & Surfacing](#curves-surfacing) — `Loft.station`, `Loft.leftRail`, `Loft.rightRail`, `Loft.frontRail`, `Loft.backRail`, `Loft.centerRail`, `Loft.pathOnXz`, `Loft.pathOnYz`, `Loft.pathOnXy`, `Loft.withGuideRails`, `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
+- [Surface Members](#surface-members) — `surfaceBand`, `SurfaceBody`
 - [Curve3D](#curve3d)
 - [NurbsCurve3D](#nurbscurve3d)
 - [NurbsSurface](#nurbssurface)
@@ -4142,7 +4213,6 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 - [ProductSpoutBuilder](#productspoutbuilder)
 - [ProductHandleBuilder](#producthandlebuilder)
 - [ProductHandleFeature](#producthandlefeature)
-- [ProductRibbonBuilder](#productribbonbuilder)
 - [CylinderCarrier](#cylindercarrier)
 - [PlaneCarrier](#planecarrier)
 - [ProductSkinCarrier](#productskincarrier)
@@ -4168,6 +4238,87 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 
 ### Curves & Surfacing
 
+#### `Loft.station()` — Create a loft station from a 2D profile and an axis position.
+
+```ts
+Loft.station(profile: Sketch, position: number): LoftStation
+```
+
+`LoftStation`: `{ profile: Sketch, position: number }`
+
+#### `Loft.leftRail()` — Create a guide rail that constrains the section-local negative-X side.
+
+```ts
+Loft.leftRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+`LoftGuideRail`: `{ side: LoftGuideRailSide, path: LoftGuideRailPath }`
+
+#### `Loft.rightRail()` — Create a guide rail that constrains the section-local positive-X side.
+
+```ts
+Loft.rightRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.frontRail()` — Create a guide rail that constrains the section-local positive-Y side.
+
+```ts
+Loft.frontRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.backRail()` — Create a guide rail that constrains the section-local negative-Y side.
+
+```ts
+Loft.backRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.centerRail()` — Create a guide rail that moves section centers along the loft.
+
+```ts
+Loft.centerRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.pathOnXz()` — Place a 2D guide path onto the XZ plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Z. Use this for left/right silhouette rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+
+```ts
+Loft.pathOnXz(path: LoftPath2D, y?: number): Vec3[]
+```
+
+#### `Loft.pathOnYz()` — Place a 2D guide path onto the YZ plane.
+
+The path's first coordinate becomes Y and its second coordinate becomes Z. Use this for front/back crown rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+
+```ts
+Loft.pathOnYz(path: LoftPath2D, x?: number): Vec3[]
+```
+
+#### `Loft.pathOnXy()` — Place a 2D guide path onto the XY plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Y. Use this when lofting along X or Y and a rail lives in a horizontal sketch plane.
+
+```ts
+Loft.pathOnXy(path: LoftPath2D, z?: number): Vec3[]
+```
+
+#### `Loft.withGuideRails()` — Loft through profile stations while forcing generated sections to follow guide rails.
+
+Stations define the cross-section family. Guide rails define the side or center paths the loft must pass through. With opposite side rails, the section is scaled to touch both rails. With one side rail, the section keeps its interpolated size unless a center rail is also present.
+
+```ts
+Loft.withGuideRails(stations: LoftStation[], rails: LoftGuideRail[], options?: LoftWithGuideRailsOptions): Shape
+```
+
+**`LoftOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
+- `boundsPadding?: number` — Optional extra bounds padding.
+
+**`LoftWithGuideRailsOptions`** extends LoftOptions
+- `axis?: LoftAxis` — Primary station axis. Default Z.
+- `samples?: number` — Number of generated loft stations including ends. Default scales with station count.
+- `railSamples?: number` — Number of points sampled from curve-backed rails before axis interpolation. Default 64.
+
 #### `hermiteTransitionG2()` — Create a quintic Hermite transition curve between two edge endpoints (G2 continuity).
 
 The curve starts at `a.point` tangent to `a.tangent` with curvature `a.curvature`, and ends at `b.point` tangent to `b.tangent` with curvature `b.curvature`, with smooth G2-continuous interpolation matching position, tangent, and curvature.
@@ -4256,10 +4407,6 @@ Performance note: loft is significantly heavier than primitive/extrude/revolve.
 loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape
 ```
 
-**`LoftOptions`**
-- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
-- `boundsPadding?: number` — Optional extra bounds padding.
-
 #### `loftAlongSpine()` — Loft between multiple profiles positioned along an arbitrary 3D spine curve.
 
 Unlike loft() which only supports Z heights, loftAlongSpine() places each profile at a position along a 3D spine, oriented perpendicular to the spine tangent. This enables lofting along curved paths — e.g., a wing root-to-tip transition that follows a swept-back leading edge.
@@ -4490,11 +4637,8 @@ connectEdges(edgeA: EdgeSegment, edgeB: EdgeSegment, options?: ConnectEdgesOptio
 | `normalA` | `Vec3` | Normal of first adjacent face. |
 | `normalB` | `Vec3` | Normal of second adjacent face (same as normalA for boundary edges). |
 | `boundary` | `boolean` | true if this is a boundary (unmatched) edge — unusual for closed solids. |
-| `nativeTopology?` | `EdgeNativeTopologyRef` | Native kernel topology identity when the active backend can provide one. |
 | `start`, `end`, `midpoint`, `length` | | — |
 
-`EdgeNativeTopologyRef`: `{ backend: "truck", edge: number }`
-
 
 **`ConnectEdgesOptions`** extends TransitionSurfaceOptions
 
@@ -4517,63 +4661,6 @@ connectEdges(edgeA: EdgeSegment, edgeB: EdgeSegment, options?: ConnectEdgesOptio
 surfaceBand<C extends SurfaceCoordinate>(path: SurfacePath<C> | SurfacePathBuilder<C>, width: WidthProfile, cap?: SurfaceBandCap): SurfaceBand<C>
 ```
 
-#### `compileSurfaceMember()`
-
-```ts
-compileSurfaceMember<C extends SurfaceCoordinate>(input: Omit<SurfaceMemberSpec<C>, "section"> & { section: MemberSection | MemberSectionInput; }): CompiledSurfaceMember
-```
-
-**`SurfaceMemberSpec`**: `name: string`, `kind: SurfaceMemberKind`, `path?: SurfacePath<C> | SurfacePathBuilder<C>`, `anchor?: SurfaceAnchor<C>`, `size?: { width: number; height: number; }`, `section: MemberSection`, `features: MemberFeature[]`, `capStyle?: SurfaceBandCap`, `explicitAnchors?: SurfaceMemberExplicitAnchor<C>[]`
-
-`SurfaceAnchor`: `{ carrier: CarrierSurface<C>, coordinate: C }`
-
-`CarrierSurface`: `{ name: string, kind: SurfaceCarrierKind }`
-
-**`MemberSection`**: `width?: number`, `thickness: number`, `edgeRadius: number`, `direction: MemberOutwardDirection`, `material?: ProductMaterial`, `stations: MemberSectionStation[]`
-
-`ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
-
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
-`MemberSectionStation`: `{ t: number, width?: number, thickness?: number }`
-
-**`MemberFeature`**: `type: MemberFeatureType`, `name?: string`, `length?: number`, `width?: number`, `diameter?: number`, `counterboreDiameter?: number`, `clearanceDiameter?: number`, `height?: number`, `depth?: number`, `count?: number`, `along?: number`, `across?: number`, `verticalTravel?: number`
-
-`SurfaceMemberExplicitAnchor`: `{ name: string, coordinate: C, carrierName?: string }`
-
-**`MemberSectionInput`**: `width?: number`, `thickness: number`, `edgeRadius?: number`, `direction?: MemberOutwardDirection`, `material?: ProductMaterial`, `stations?: MemberSectionStation[]`
-
-**`CompiledSurfaceMember`**: `name: string`, `shape: Shape`, `mesh: MemberMesh`, `diagnostics: SurfaceDiagnostic[]`, `anchors: { start?: CompiledSurfaceMemberAnchor; end?: CompiledSurfaceMemberAnchor; center: CompiledSurfaceMemberAnchor; landings?: CompiledSurfaceMemberAnchor[]; boundaries?: CompiledSurfaceMemberAnchor[]; features?: CompiledSurfaceMemberAnchor[]; explicit?: CompiledSurfaceMemberAnchor[]; }`
-
-`MemberMesh`: `{ vertices: Vec3[], triangles: Array<[ number, number, number ]> }`
-
-**`SurfaceDiagnostic`**
-- `code?: SurfaceDiagnosticCode` — Stable machine-readable repair hook. Messages may change; codes should not.
-- Also: `category: "carrier" | "path" | "region" | "member" | "feature" | "join" | "compiler", level: "info" | "warning" | "error", message: string, subject?: string`
-
-**`SurfaceMemberAnchorIR`**: `role: SurfaceMemberAnchorRole`, `kind: "member-end" | "member-center" | "member-landing" | "member-boundary" | "plate-edge" | "plate-center" | "plate-landing" | "feature-center" | "surface-coordinate"`, `name?: string`, `point: Vec3`, `normal?: Vec3`
-
-`CompiledSurfaceMemberAnchor`: `{ frame?: SurfaceFrame }`
-
-**`SurfaceFrame`**: `point: Vec3`, `normal: Vec3`, `tangentAlong: Vec3`, `tangentAcross: Vec3`, `matrix: Mat4`, `carrier: string`, `representation: SurfaceCarrierKind | string`, `coordinate: SurfaceCoordinate`
-
 #### `SurfaceBody()` — Start a surface-member body builder for straps, inlays, guards, braces, cuffs, and similar physical members that live on a carrier surface.
 
 ```js
@@ -4997,6 +5084,21 @@ path().moveTo(0,0).lineTo(10,0).lineTo(10,5).mirror('x').close()
 mirror(axis: "x" | "y" | [ number, number ]): this
 ```
 
+#### `toPolyline()` — Return the open path as a sampled 2D polyline.
+
+This is for construction geometry such as guide rails, measured centerlines, and curve-driven helpers where the authored path should stay open instead of becoming a filled sketch or stroked profile.
+
+```ts
+const rail = path()
+  .moveTo(24, 0)
+  .bezierTo(32, 44, 28, 92, 18, 120)
+  .toPolyline();
+```
+
+```ts
+toPolyline(): [ number, number ][]
+```
+
 #### `closeOffset()` — Close the path and return an offset version of the filled Sketch. Positive delta expands outward, negative shrinks inward.
 
 ```ts
@@ -5149,18 +5251,6 @@ with(...children: GroupInput[]): ShapeGroup
 integrate(...details: Shape[]): Shape
 ```
 
-#### `diagnostics()` — Return lowering representation, station names, rail names, and warnings.
-
-```ts
-diagnostics(): ProductSkinDiagnostics
-```
-
-**`ProductSkinDiagnostics`**: `representation: ProductSkinRepresentation`, `lowering: string[]`, `warnings: string[]`, `stationNames: string[]`, `railNames: string[]`
-
-**`ProductSkinRepresentation`** — Reported lowering mode for ProductSkin and conformal feature diagnostics.
-
-`"exact" | "sampled" | "mixed" | "fallback"`
-
 #### `uv()` — Create a side/u/v surface-ref query on this skin.
 
 ```ts
@@ -5216,7 +5306,7 @@ stationAt(vOrAxis: number): { ... }
 frame(query: ProductSkinRefQuery): ProductSurfaceFrame
 ```
 
-**`ProductSurfaceFrame`**: `point: Vec3`, `normal: Vec3`, `tangentU: Vec3`, `tangentV: Vec3`, `matrix: Mat4`, `skin: string`, `representation: ProductSkinRepresentation`
+`ProductSurfaceFrame`: `{ point: Vec3, normal: Vec3, tangentU: Vec3, tangentV: Vec3, matrix: Mat4, skin: string }`
 
 ### `ProductSurfaceRef`
 
@@ -5234,25 +5324,6 @@ frame(query: ProductSkinRefQuery): ProductSurfaceFrame
 frame(overrides?: Partial<ProductSkinRefQuery>): ProductSurfaceFrame
 ```
 
-**`ProductSkinRefQuery`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `side` | `ProductSkinSide` | Side of the product skin. `front` is the minimum axis cap, `rear`/`back` is the maximum axis cap. |
-| `u?` | `number` | Across-side parameter for side refs. Defaults to 0.5. |
-| `v?` | `number` | Along-axis parameter, 0 at the first cap and 1 at the rear/back cap. Defaults to 0.5. |
-| `offset?` | `number` | Positive distance away from the surface along the resolved normal. |
-
-**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
-
-`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
-
-**`ProductSurfaceFrame`**: `point: Vec3`, `normal: Vec3`, `tangentU: Vec3`, `tangentV: Vec3`, `matrix: Mat4`, `skin: string`, `representation: ProductSkinRepresentation`
-
-**`ProductSkinRepresentation`** — Reported lowering mode for ProductSkin and conformal feature diagnostics.
-
-`"exact" | "sampled" | "mixed" | "fallback"`
-
 #### `with()` — Return a copy of this ref with side/u/v/offset overrides.
 
 ```ts
@@ -5297,31 +5368,12 @@ ref(u?: number, v?: number, offset?: number): ProductSurfaceRef
 uv(u?: number, v?: number, offset?: number): ProductSkinRefQuery
 ```
 
-**`ProductSkinRefQuery`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `side` | `ProductSkinSide` | Side of the product skin. `front` is the minimum axis cap, `rear`/`back` is the maximum axis cap. |
-| `u?` | `number` | Across-side parameter for side refs. Defaults to 0.5. |
-| `v?` | `number` | Along-axis parameter, 0 at the first cap and 1 at the rear/back cap. Defaults to 0.5. |
-| `offset?` | `number` | Positive distance away from the surface along the resolved normal. |
-
-**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
-
-`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
-
 #### `frame()` — Resolve a point/frame on this surface using the builder's side.
 
 ```ts
 frame(query?: Partial<ProductSkinRefQuery>): ProductSurfaceFrame
 ```
 
-**`ProductSurfaceFrame`**: `point: Vec3`, `normal: Vec3`, `tangentU: Vec3`, `tangentV: Vec3`, `matrix: Mat4`, `skin: string`, `representation: ProductSkinRepresentation`
-
-**`ProductSkinRepresentation`** — Reported lowering mode for ProductSkin and conformal feature diagnostics.
-
-`"exact" | "sampled" | "mixed" | "fallback"`
-
 #### `ribbon()` — Start a conformal ribbon on this skin side.
 
 Path points use side-local `u`/`v` coordinates; this builder supplies the side. The returned ProductRibbonBuilder is already bound to the source skin and can be further configured before build(). Use `widthSamples` >= 3 when the ribbon must visibly wrap over curved product sections instead of behaving like a flat strip.
@@ -5399,11 +5451,7 @@ stations(stations: Array<ProductStationBuilder | ProductStationSpec>): this
 
 `ProductStationProfile`: `{ sketch: Sketch, width: number, depth: number, kind: ProductProfileKind, radius?: number, exponent?: number }`
 
-**`ProductProfileKind`**
-
-`"oval" | "roundedRect" | "circle" | "superEllipse" | "custom"`
-
-#### `rails()` — Attach guide rails as ProductSkin IR metadata and diagnostics.
+#### `rails()` — Attach named guide rails for product-skin construction and downstream surface references.
 
 ```ts
 rails(rails: Record<string, ProductRailSpec>): this
@@ -5421,19 +5469,6 @@ rails(rails: Record<string, ProductRailSpec>): this
 ref(name: string, query: ProductSkinRefQuery): this
 ```
 
-**`ProductSkinRefQuery`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `side` | `ProductSkinSide` | Side of the product skin. `front` is the minimum axis cap, `rear`/`back` is the maximum axis cap. |
-| `u?` | `number` | Across-side parameter for side refs. Defaults to 0.5. |
-| `v?` | `number` | Along-axis parameter, 0 at the first cap and 1 at the rear/back cap. Defaults to 0.5. |
-| `offset?` | `number` | Positive distance away from the surface along the resolved normal. |
-
-**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
-
-`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
-
 #### `refs()` — Publish multiple named semantic surface refs on the skin.
 
 ```ts
@@ -5452,32 +5487,11 @@ uv(side: ProductSkinSide, u?: number, v?: number): ProductSkinRefQuery
 material(material: ProductMaterial): this
 ```
 
-`ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
+#### `color()` — Apply a simple color override to the lowered skin.
 
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
-#### `color()` — Apply a simple color override to the lowered skin.
-
-```ts
-color(color: string): this
-```
+```ts
+color(color: string): this
+```
 
 #### `edgeLength()` — Set the sampled loft target edge length.
 
@@ -5485,7 +5499,7 @@ color(color: string): this
 edgeLength(value: number): this
 ```
 
-#### `wall()` — Records a target wall thickness; v1 keeps exterior skin lowering sampled and reports wall as a diagnostic.
+#### `wall()` — Record intended wall thickness for product design metadata. Use explicit shelling when the model needs real inner-wall geometry.
 
 ```ts
 wall(thickness: number): this
@@ -5563,7 +5577,7 @@ circle(diameter: number, options?: { segments?: number; }): this
 custom(sketch: Sketch, width: number, depth: number): this
 ```
 
-#### `crown()` — Stores a semantic crown amount for diagnostics and future rail solving.
+#### `crown()` — Set the station crown amount for soft product-section intent.
 
 ```ts
 crown(amount: number): this
@@ -5575,14 +5589,6 @@ crown(amount: number): this
 toSpec(): ProductStationSpec
 ```
 
-`ProductStationSpec`: `{ name: string, center: Vec3, profile: ProductStationProfile, crown?: number }`
-
-`ProductStationProfile`: `{ sketch: Sketch, width: number, depth: number, kind: ProductProfileKind, radius?: number, exponent?: number }`
-
-**`ProductProfileKind`**
-
-`"oval" | "roundedRect" | "circle" | "superEllipse" | "custom"`
-
 ### `ProductPanelBuilder`
 
 **Properties:**
@@ -5623,27 +5629,6 @@ thickness(thickness: number): this
 material(material: ProductMaterial): this
 ```
 
-`ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
-
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
 #### `color()` — Apply a simple color override to the panel.
 
 ```ts
@@ -5666,23 +5651,9 @@ attachTo(ref: ProductRefInput, options?: ProductPanelAttachOptions): Shape
 
 `ProductSurfaceRef`
 
-`ProductAttachOptions`: `{ offset?: number, inset?: number }`
 
 `ProductPanelAttachOptions`: `{ at?: Partial<ProductSkinRefQuery>, thickness?: number, material?: ProductMaterial, color?: string }`
 
-**`ProductSkinRefQuery`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `side` | `ProductSkinSide` | Side of the product skin. `front` is the minimum axis cap, `rear`/`back` is the maximum axis cap. |
-| `u?` | `number` | Across-side parameter for side refs. Defaults to 0.5. |
-| `v?` | `number` | Along-axis parameter, 0 at the first cap and 1 at the rear/back cap. Defaults to 0.5. |
-| `offset?` | `number` | Positive distance away from the surface along the resolved normal. |
-
-**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
-
-`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
-
 ### `ProductRibbonBuilder`
 
 Builder for thin trim, label, grip, and split-line features that bend with a ProductSkin surface.
@@ -5707,53 +5678,6 @@ on(skin: ProductSkin, points: ProductRibbonPathPoint[], options?: ProductRibbonB
 
 `ProductSkinRefQuery | ProductSurfaceRef`
 
-**`ProductSkinRefQuery`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `side` | `ProductSkinSide` | Side of the product skin. `front` is the minimum axis cap, `rear`/`back` is the maximum axis cap. |
-| `u?` | `number` | Across-side parameter for side refs. Defaults to 0.5. |
-| `v?` | `number` | Along-axis parameter, 0 at the first cap and 1 at the rear/back cap. Defaults to 0.5. |
-| `offset?` | `number` | Positive distance away from the surface along the resolved normal. |
-
-**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
-
-`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
-
-**`ProductRibbonBuildOptions`** — Options shared by Product.ribbon() builders and Product.surface(...).ribbon(...).
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `width?` | `number` | Width across the surface in millimeters. |
-| `thickness?` | `number` | Solid thickness outward from the source surface in millimeters. |
-| `offset?` | `number` | Positive clearance between the source surface and the ribbon's inner face. |
-| `samples?` | `number` | Samples along the ribbon path. Higher values bend more smoothly. |
-| `widthSamples?` | `number` | Samples across the ribbon width. Use 3+ to visibly wrap over curved cross-sections. |
-| `resolution?` | `number` | Tessellation resolution passed to the lowered NURBS surface. |
-| `material?` | `ProductMaterial` | Apply a product material preset to the ribbon. |
-| `color?` | `string` | Apply a simple color override. |
-
-`ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
-
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
 #### `fromRefs()` — Follow explicit surface refs.
 
 Useful for named refs or paths assembled elsewhere. The builder resolves each ref frame and interpolates between those frames; use on(skin, points) when you need full skin-side sampling between sparse control points.
@@ -5816,48 +5740,6 @@ color(color: string): this
 build(options?: ProductRibbonBuildOptions): Shape
 ```
 
-#### `buildWithDiagnostics()` — Build a conformal ribbon and return surface-feature diagnostics.
-
-Use this while validating API usage or model fidelity; diagnostics report sampling counts, side-span clamping, lowering mode, and warnings that should be visible in reviews.
-
-```ts
-buildWithDiagnostics(options?: ProductRibbonBuildOptions): ProductRibbonResult
-```
-
-**`ProductRibbonResult`** — Shape plus diagnostics returned by ProductRibbonBuilder.buildWithDiagnostics().
-- `shape: Shape` — Lowered conformal ribbon shape.
-- `diagnostics: ProductRibbonDiagnostics` — Sampling and lowering diagnostics for the returned shape.
-
-**`ProductRibbonDiagnostics`** — Diagnostics describing how a conformal ribbon was sampled and lowered.
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `name` | `string` | Ribbon shape name. |
-| `skin?` | `string` | Source skin name when the ribbon follows a ProductSkin directly. |
-| `side?` | `ProductSkinSide` | Source skin side when all path points are on one semantic side. |
-| `pathPointCount` | `number` | Number of control path points supplied before interpolation. |
-| `width` | `number` | Final ribbon width in millimeters. |
-| `thickness` | `number` | Final ribbon solid thickness in millimeters. |
-| `offset` | `number` | Final normal offset from the source surface in millimeters. |
-| `samples` | `number` | Final sample count along the ribbon path. |
-| `widthSamples` | `number` | Final sample count across the ribbon width. |
-| `resolution` | `number` | NURBS tessellation resolution used for the lowered surface. |
-| `lowering` | `"nurbsSurface"` | Lowering primitive used for the ribbon shape. |
-| `expectedFidelity` | `ProductSkinRepresentation` | Expected fidelity inherited from the source skin/ref sampling mode. |
-| `clampedUCount` | `number` | Number of generated width samples clamped to the valid side span. |
-| `maxUClampDistance` | `number` | Largest absolute u-distance lost to side-span clamping. |
-| `warnings` | `string[]` | Non-fatal sampling and lowering warnings. |
-
-**`ProductSkinRepresentation`** — Reported lowering mode for ProductSkin and conformal feature diagnostics.
-
-`"exact" | "sampled" | "mixed" | "fallback"`
-
-#### `diagnostics()` — Return diagnostics from the most recent build, if this builder has been built.
-
-```ts
-diagnostics(): ProductRibbonDiagnostics | undefined
-```
-
 ### `ProductSpoutBuilder`
 
 **Properties:**
@@ -5880,14 +5762,6 @@ from(ref: ProductSurfaceRef): this
 sections(sections: Array<Sketch | ProductStationBuilder | ProductStationSpec>): this
 ```
 
-`ProductStationSpec`: `{ name: string, center: Vec3, profile: ProductStationProfile, crown?: number }`
-
-`ProductStationProfile`: `{ sketch: Sketch, width: number, depth: number, kind: ProductProfileKind, radius?: number, exponent?: number }`
-
-**`ProductProfileKind`**
-
-`"oval" | "roundedRect" | "circle" | "superEllipse" | "custom"`
-
 #### `projection()` — Set the projection length along the source ref normal.
 
 ```ts
@@ -5906,27 +5780,6 @@ edgeLength(value: number): this
 material(material: ProductMaterial): this
 ```
 
-`ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
-
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
 #### `color()` — Apply a simple color override to the spout.
 
 ```ts
@@ -5945,8 +5798,6 @@ build(): Shape
 attach(options?: ProductAttachOptions): Shape
 ```
 
-`ProductAttachOptions`: `{ offset?: number, inset?: number }`
-
 ### `ProductHandleBuilder`
 
 **Properties:**
@@ -5969,12 +5820,6 @@ between(upper: ProductSurfaceRef, lower: Vec3): this
 spine(points: Vec3[] | ProductRailSpec): this
 ```
 
-`ProductRailSpec`: `{ kind: ProductRailKind, points: Vec3[], degree?: number, name?: string }`
-
-**`ProductRailKind`**
-
-`"bezier" | "nurbs" | "polyline"`
-
 #### `grip()` — Set the grip cross-section profile.
 
 ```ts
@@ -5987,27 +5832,6 @@ grip(profile: Sketch): this
 material(material: ProductMaterial): this
 ```
 
-`ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
-
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
 #### `padMaterial()` — Apply a product material preset to handle landing pads.
 
 ```ts
@@ -6056,181 +5880,6 @@ toShape(): Shape
 toGroup(): ShapeGroup
 ```
 
-### `ProductRibbonBuilder`
-
-Builder for thin trim, label, grip, and split-line features that bend with a ProductSkin surface.
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | `string` | — |
-
-**Methods:**
-
-#### `on()` — Follow a ProductSkin with side/u/v path queries or refs.
-
-This is the highest-fidelity mode because every interpolated sample is resolved through ProductSkin.frame(), so the ribbon bends along the selected side as station width/depth changes. All query path points must stay on one side; split side transitions into separate ribbons.
-
-```ts
-on(skin: ProductSkin, points: ProductRibbonPathPoint[], options?: ProductRibbonBuildOptions): this
-```
-
-**`ProductRibbonPathPoint`** — Path point for Product.ribbon().on(...): either a side/u/v query or a resolved surface ref.
-
-`ProductSkinRefQuery | ProductSurfaceRef`
-
-**`ProductSkinRefQuery`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `side` | `ProductSkinSide` | Side of the product skin. `front` is the minimum axis cap, `rear`/`back` is the maximum axis cap. |
-| `u?` | `number` | Across-side parameter for side refs. Defaults to 0.5. |
-| `v?` | `number` | Along-axis parameter, 0 at the first cap and 1 at the rear/back cap. Defaults to 0.5. |
-| `offset?` | `number` | Positive distance away from the surface along the resolved normal. |
-
-**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
-
-`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
-
-**`ProductRibbonBuildOptions`** — Options shared by Product.ribbon() builders and Product.surface(...).ribbon(...).
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `width?` | `number` | Width across the surface in millimeters. |
-| `thickness?` | `number` | Solid thickness outward from the source surface in millimeters. |
-| `offset?` | `number` | Positive clearance between the source surface and the ribbon's inner face. |
-| `samples?` | `number` | Samples along the ribbon path. Higher values bend more smoothly. |
-| `widthSamples?` | `number` | Samples across the ribbon width. Use 3+ to visibly wrap over curved cross-sections. |
-| `resolution?` | `number` | Tessellation resolution passed to the lowered NURBS surface. |
-| `material?` | `ProductMaterial` | Apply a product material preset to the ribbon. |
-| `color?` | `string` | Apply a simple color override. |
-
-`ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
-
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
-#### `fromRefs()` — Follow explicit surface refs.
-
-Useful for named refs or paths assembled elsewhere. The builder resolves each ref frame and interpolates between those frames; use on(skin, points) when you need full skin-side sampling between sparse control points.
-
-```ts
-fromRefs(points: ProductSurfaceRef[], options?: ProductRibbonBuildOptions): this
-```
-
-#### `width()` — Set ribbon width in millimeters.
-
-```ts
-width(width: number): this
-```
-
-#### `thickness()` — Set solid thickness outward from the source surface in millimeters.
-
-```ts
-thickness(thickness: number): this
-```
-
-#### `offset()` — Set positive clearance between the source surface and the ribbon's inner face.
-
-```ts
-offset(offset: number): this
-```
-
-#### `samples()` — Set samples along the path.
-
-```ts
-samples(samples: number): this
-```
-
-#### `widthSamples()` — Set samples across the width. Use 3+ to bend over curved cross-sections.
-
-```ts
-widthSamples(samples: number): this
-```
-
-#### `resolution()` — Set NURBS tessellation resolution.
-
-```ts
-resolution(resolution: number): this
-```
-
-#### `material()` — Apply a product material preset.
-
-```ts
-material(material: ProductMaterial): this
-```
-
-#### `color()` — Apply a simple color override.
-
-```ts
-color(color: string): this
-```
-
-#### `build()` — Build a conformal ribbon as a thin NURBS surface solid.
-
-```ts
-build(options?: ProductRibbonBuildOptions): Shape
-```
-
-#### `buildWithDiagnostics()` — Build a conformal ribbon and return surface-feature diagnostics.
-
-Use this while validating API usage or model fidelity; diagnostics report sampling counts, side-span clamping, lowering mode, and warnings that should be visible in reviews.
-
-```ts
-buildWithDiagnostics(options?: ProductRibbonBuildOptions): ProductRibbonResult
-```
-
-**`ProductRibbonResult`** — Shape plus diagnostics returned by ProductRibbonBuilder.buildWithDiagnostics().
-- `shape: Shape` — Lowered conformal ribbon shape.
-- `diagnostics: ProductRibbonDiagnostics` — Sampling and lowering diagnostics for the returned shape.
-
-**`ProductRibbonDiagnostics`** — Diagnostics describing how a conformal ribbon was sampled and lowered.
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `name` | `string` | Ribbon shape name. |
-| `skin?` | `string` | Source skin name when the ribbon follows a ProductSkin directly. |
-| `side?` | `ProductSkinSide` | Source skin side when all path points are on one semantic side. |
-| `pathPointCount` | `number` | Number of control path points supplied before interpolation. |
-| `width` | `number` | Final ribbon width in millimeters. |
-| `thickness` | `number` | Final ribbon solid thickness in millimeters. |
-| `offset` | `number` | Final normal offset from the source surface in millimeters. |
-| `samples` | `number` | Final sample count along the ribbon path. |
-| `widthSamples` | `number` | Final sample count across the ribbon width. |
-| `resolution` | `number` | NURBS tessellation resolution used for the lowered surface. |
-| `lowering` | `"nurbsSurface"` | Lowering primitive used for the ribbon shape. |
-| `expectedFidelity` | `ProductSkinRepresentation` | Expected fidelity inherited from the source skin/ref sampling mode. |
-| `clampedUCount` | `number` | Number of generated width samples clamped to the valid side span. |
-| `maxUClampDistance` | `number` | Largest absolute u-distance lost to side-span clamping. |
-| `warnings` | `string[]` | Non-fatal sampling and lowering warnings. |
-
-**`ProductSkinRepresentation`** — Reported lowering mode for ProductSkin and conformal feature diagnostics.
-
-`"exact" | "sampled" | "mixed" | "fallback"`
-
-#### `diagnostics()` — Return diagnostics from the most recent build, if this builder has been built.
-
-```ts
-diagnostics(): ProductRibbonDiagnostics | undefined
-```
-
 ### `CylinderCarrier`
 
 **Properties:**
@@ -6362,12 +6011,6 @@ bounds(): SurfaceBounds
 offset(distance: number): CylinderCarrier
 ```
 
-#### `diagnostics()`
-
-```ts
-diagnostics(): SurfaceDiagnostic[]
-```
-
 #### `mirrorCoordinate()`
 
 ```ts
@@ -6487,12 +6130,6 @@ bounds(): SurfaceBounds
 offset(distance: number): PlaneCarrier
 ```
 
-#### `diagnostics()`
-
-```ts
-diagnostics(): SurfaceDiagnostic[]
-```
-
 #### `mirrorCoordinate()`
 
 ```ts
@@ -6517,10 +6154,6 @@ mirrorCoordinate(coordinate: PlaneSurfaceCoordinate): PlaneSurfaceCoordinate
 surface(side: ProductSkinSide): ProductSkinCarrier
 ```
 
-**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
-
-`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
-
 #### [`path()`](/docs/sketch#path)
 
 ```ts
@@ -6609,16 +6242,6 @@ bounds(): SurfaceBounds
 offset(distance: number): ProductSkinCarrier
 ```
 
-#### `diagnostics()`
-
-```ts
-diagnostics(): SurfaceDiagnostic[]
-```
-
-**`SurfaceDiagnostic`**
-- `code?: SurfaceDiagnosticCode` — Stable machine-readable repair hook. Messages may change; codes should not.
-- Also: `category: "carrier" | "path" | "region" | "member" | "feature" | "join" | "compiler", level: "info" | "warning" | "error", message: string, subject?: string`
-
 #### `mirrorCoordinate()`
 
 ```ts
@@ -6761,12 +6384,6 @@ withHole(name: string, input: SurfaceBandHoleInput): SurfaceBand<C>
 holes(): SurfaceBandHoleRegion[]
 ```
 
-#### `diagnostics()`
-
-```ts
-diagnostics(samples?: number): SurfaceDiagnostic[]
-```
-
 ### `SurfaceBodyBuilder`
 
 **Properties:**
@@ -6807,18 +6424,6 @@ autoJoinAtSharedAnchors(): this
 build(): Shape | ShapeGroup
 ```
 
-#### `buildWithDiagnostics()`
-
-```ts
-buildWithDiagnostics(): SurfaceBodyBuildResult
-```
-
-#### `buildDebug()`
-
-```ts
-buildDebug(): SurfaceBodyBuildResult
-```
-
 ### `SurfaceMemberBuilder`
 
 #### `plate()`
@@ -6881,7 +6486,7 @@ cutout(name: string, feature: MemberFeature | RoundedSlotBuilder): this
 counterbore(name: string, feature: MemberFeature | CounterboreBuilder): this
 ```
 
-#### `anchorAt()` — Add a named anchor at a carrier surface coordinate for diagnostics, debug views, and future named-anchor joins.
+#### `anchorAt()` — Add a named anchor at a carrier surface coordinate for explicit member joins.
 
 ```ts
 anchorAt(name: string, coordinate: C | SurfaceAnchor<C>): this
@@ -6929,18 +6534,6 @@ autoJoinAtSharedAnchors(): SurfaceBodyBuilder
 build(): Shape | ShapeGroup
 ```
 
-#### `buildWithDiagnostics()`
-
-```ts
-buildWithDiagnostics(): SurfaceBodyBuildResult
-```
-
-#### `buildDebug()`
-
-```ts
-buildDebug(): SurfaceBodyBuildResult
-```
-
 ### `SurfaceJoinBuilder`
 
 #### `betweenAnchors()` — Select named anchors on the source and target members before lowering this join.
@@ -7023,7 +6616,6 @@ toFeature(name?: string): MemberFeature
 
 - `Edge(options: BlendEdgeOptions): Shape`
 - `Surface(options: BlendSurfaceOptions): Shape`
-- `CornerY(options: BlendCornerYOptions): Shape` — Current implementation uses continuity-controlled edge fillets on solid edges. It does not yet provide a dedicated open-sheet or multi-patch Y-corner solver. Follow progress: https://github.com/KoStard/forgecad-private/issues/162
 
 ### `Analysis`
 
@@ -7062,15 +6654,12 @@ toFeature(name?: string): MemberFeature
 - `cylinder(name: string): CylinderCarrier` — Create an analytic cylinder carrier for bottles, limbs, tubes, guards, and cuffs.
 - `plane(name: string): PlaneCarrier` — Create an analytic plane carrier for plates and local flat construction surfaces.
 - `productSkin(skin: ProductSkin): ProductSkinCarrier` — Adapt an existing ProductSkin into the general surface-member carrier protocol.
-- `mesh(name: string): never` — Reserved stub for future parameterized mesh carriers; arbitrary mesh parameterization is not implemented yet.
-- `scan(name: string): never` — Reserved stub for future scan/body-fit carriers; arbitrary scan parameterization is not implemented yet.
 
 ### `SurfaceMembers`
 
 - `Body(name: string): SurfaceBodyBuilder` — Start a surface-member body builder for straps, inlays, guards, braces, cuffs, and similar physical members that live on a carrier surface.
 - `Band: typeof SurfaceBand`
 - `band<C extends SurfaceCoordinate>(path: SurfacePath<C> | SurfacePathBuilder<C>, width: WidthProfile, cap?: SurfaceBandCap): SurfaceBand<C>`
-- `compileMember<C extends SurfaceCoordinate>(input: Omit<SurfaceMemberSpec<C>, "section"> & { section: MemberSection | MemberSectionInput; }): CompiledSurfaceMember`
 
 ### `Slot`
 
@@ -7114,7 +6703,12 @@ bomToCsv(rows: BomRow[]): string
 
 **`BomRow`**: `part: string`, `qty: number`, `material?: string`, `process?: string`, `tolerance?: string`, `notes?: string`, `metadata?: PartMetadata`
 
-**`PartMetadata`**: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`
+**`PartMetadata`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `tags?` | `string \| readonly string[]` | Viewport organization tags applied to scene objects produced from this part. |
+| `material?`, `process?`, `tolerance?`, `qty?`, `notes?`, `densityKgM3?`, `massKg?` | | — |
 
 #### `assembly()` — Create an assembly container with named parts and joints for kinematic mechanisms.
 
@@ -7755,13 +7349,13 @@ toGroup(): ShapeGroup
 Each part becomes `{ name, shape }` or `{ name, group: [...] }` if the part is a [`ShapeGroup`](/docs/core#shapegroup). Top-level scripts should normally return the `SolvedAssembly` directly. Use `toGroup()` when you need [`ShapeGroup`](/docs/core#shapegroup) behavior; use this method only for advanced scene-graph control where you need access to the flat per-part array with metadata.
 
 ```ts
-toSceneObjects(): Array<{ name: string; shape?: Shape; group?: Array<{ name: string; shape: Shape; }>; metadata?: PartMetadata; }>
+toSceneObjects(): Array<{ name: string; shape?: Shape; group?: Array<{ name: string; shape: Shape; tags?: string[]; }>; metadata?: PartMetadata; }>
 ```
 
 #### `toScene()` — Backward-compatible alias for `toSceneObjects()`.
 
 ```ts
-toScene(): Array<{ name: string; shape?: Shape; group?: Array<{ name: string; shape: Shape; }>; metadata?: PartMetadata; }>
+toScene(): Array<{ name: string; shape?: Shape; group?: Array<{ name: string; shape: Shape; tags?: string[]; }>; metadata?: PartMetadata; }>
 ```
 
 #### [`bom()`](/docs/output#bom) — Generate a bill of materials for all parts in the solved assembly.
@@ -8522,7 +8116,12 @@ robotExport(options: RobotExportOptions): CollectedRobotExport
 
 `AssemblyPartDef`: `{ name: string, part: AssemblyPart, base: Transform, metadata?: PartMetadata }`
 
-**`PartMetadata`**: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`
+**`PartMetadata`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `tags?` | `string \| readonly string[]` | Viewport organization tags applied to scene objects produced from this part. |
+| `material?`, `process?`, `tolerance?`, `qty?`, `notes?`, `densityKgM3?`, `massKg?` | | — |
 
 **`AssemblyJointDef`**: `name: string`, `type: JointType`, `parent: string`, `child: string`, `frame: Transform`, `axis: Vec3`, `min?: number`, `max?: number`, `defaultValue: number`, `unit?: string`, `effort?: number`, `velocity?: number`, `damping?: number`, `friction?: number`, `connectorRefs?: JointConnectorRefs`
 
@@ -8630,6 +8229,7 @@ Pre-built fasteners, gears, pipes, structural profiles, and utility shapes. Acce
 ## Contents
 
 - [TangentLoop2D](#tangentloop2d)
+- [DriveWheelBuilder](#drivewheelbuilder)
 - [lib](#lib)
 
 ---
@@ -8670,6 +8270,32 @@ toProfile(): Sketch
 offsetBand(thickness: number): Sketch
 ```
 
+### `DriveWheelBuilder`
+
+#### `addSpurTeethBetween()` — Add an involute spur-tooth window on part of the pitch circle.
+
+```ts
+addSpurTeethBetween(options: DriveWheelSpurTeethRegionOptions): this
+```
+
+#### `addSolidArcBetween()` — Add a constant-radius solid arc region such as a dwell, stop, or pusher.
+
+```ts
+addSolidArcBetween(options: DriveWheelSolidArcRegionOptions): this
+```
+
+#### `addShapeRegion()` — Add a fully custom region shape while preserving region metadata.
+
+```ts
+addShapeRegion(name: string, shape: Shape, options?: DriveWheelShapeRegionOptions): this
+```
+
+#### `build()` — Build the final wheel shape with a bore connector and region metadata.
+
+```ts
+build(): Shape
+```
+
 ---
 
 ## Constants
@@ -8678,7 +8304,7 @@ offsetBand(thickness: number): Sketch
 
 Pre-built parametric parts available in user scripts as `lib.*`.
 
-Every key in this object becomes a method on the `lib` namespace exposed to `.forge.js` scripts. The catalog includes:
+Every key in this object becomes a method or namespace on the `lib` object exposed to `.forge.js` scripts. The catalog includes:
 
 **Fasteners:** `bolt`, `nut`, `washer`, `fastenerSet`, `fastenerHole`, `boltHole`, `counterbore`, `hexNut`, `holePattern`
 
@@ -8688,7 +8314,9 @@ Every key in this object becomes a method on the `lib` namespace exposed to `.fo
 
 **Threads:** `thread`
 
-**Gears:** `spurGear`, `bevelGear`, `faceGear`, `sideGear`, `ringGear`, `rackGear`, `gearPair`, `bevelGearPair`, `faceGearPair`, `sideGearPair`
+**Gears:** `spurGear`, `sectorGear`, `driveWheel`, `bevelGear`, `faceGear`, `sideGear`, `ringGear`, `rackGear`, `gearPair`, `bevelGearPair`, `faceGearPair`, `sideGearPair`
+
+**Gear bodies:** `gearBodies.disk`, `gearBodies.diskWithHub`, `gearBodies.spoked`, `gearBodies.fromProfile` plus direct aliases `gearBodyDisk`, `gearBodyDiskWithHub`, `gearBodySpoked`, `gearBodyFromProfile`
 
 **Gear ratios (pure math helpers):** `gearRatio`, `rackRatio`, `planetaryRatio`
 
@@ -8696,7 +8324,7 @@ Every key in this object becomes a method on the `lib` namespace exposed to `.fo
 
 **Utilities:** `explode`
 
-Extend this by adding new entries here and registering the corresponding runner binding in `runner.ts`. Sizes outside the supported ranges will throw at runtime with a descriptive error.
+Sizes outside the supported ranges will throw at runtime with a descriptive error.
 
 - `boltHole(diameter: number, depth: number): Shape` — Simple cylindrical through-hole cutter centered on Z=0. Subtract the result from a part to produce a plain cylindrical clearance hole. For ISO metric sizes with fit classes and counterbore/countersink, use {
 - `fastenerHole(opts: FastenerHoleOptions): Shape` — ISO metric fastener hole cutter with optional counterbore or countersink. **Details** Returns a cutter shape (subtract from a solid to produce the hole). Sizes outside M2–M10 will throw. Extend `METRIC_HOLE_TABLE` in this file to add new sizes. **Example** ```ts const plate = box(60, 40, 8) .subtract(lib.fastenerHole({ size: 'M5', fit: 'normal', depth: 8 }) .translate(15, 10, 4)); ```
@@ -8734,6 +8362,14 @@ Extend this by adding new entries here and registering the corresponding runner
 - `rackRatio(module: number, pinionTeeth: number): number` — Coupling ratio between a pinion and a rack. When the pinion rotates by `θ` degrees, the rack slides by `θ × (π × module × teeth / 360)` mm. Equivalently, 1mm of rack travel = `180 / (π × pitchRadius)` degrees of pinion rotation.
 - `planetaryRatio(sunTeeth: number, ringTeeth: number): number` — Planetary gear reduction ratio when the ring is held fixed. Input: sun. Output: carrier. Ratio: `1 + ringTeeth / sunTeeth`. One turn of the sun produces `1 / ratio` turns of the carrier.
 - `boltPattern(options: BoltPatternOptions): BoltPattern` — Define a bolt pattern once and cut it from multiple parts. const base = bolts.cut(box(60, 50, 10), 12, { from: -1 }); const cover = bolts.cut(box(60, 50, 3), 5, { from: -1 }); // Same positions in both parts — guaranteed aligned. ```
+- `driveWheel(options?: DriveWheelOptions): DriveWheelBuilder` — Start a composable exceptional gear or drive wheel.
+- `readDriveWheelMeta(shape: Shape): DriveWheelMeta | null` — Read the functional-region metadata attached by `driveWheel().build()`.
+- `sectorGear(options: SectorGearOptions): Shape` — Involute sector gear with teeth on only part of the pitch circle. Specify the full-circle pitch as `teethOnFullCircle`, then choose the active tooth window with `firstTooth` and `toothCount`. The body is separate from the tooth region: pass a `gearBody...` shape for spokes, hubs, and product styling, or omit it for a simple root-radius disk. **Example** ```ts const body = lib.gearBodies.spoked({ outerRadius: 22, rimWidth: 3, hubDiameter: 10, spokeCount: 5, spokeWidth: 2.5, faceWidth: 8, boreDiameter: 5, }); const sector = lib.sectorGear({ module: 1.25, teethOnFullCircle: 36, toothCount: 10, faceWidth: 8, body, }); ```
+- `gearBodies: { ... }` — Gear body preset namespace: disk, diskWithHub, spoked, and fromProfile.
+- `gearBodyDisk(options: GearBodyDiskOptions): Shape` — Solid disk/ring gear body, independent from any tooth geometry.
+- `gearBodyDiskWithHub(options: GearBodyDiskWithHubOptions): Shape` — Disk gear body with a raised center hub.
+- `gearBodySpoked(options: GearBodySpokedOptions): Shape` — Spoked gear body with an outer rim, center hub, and radial spokes.
+- `gearBodyFromProfile(profile: Sketch, options: GearBodyFromProfileOptions): Shape` — Extrude a custom 2D profile into a gear body.
 
 ---
 
@@ -8903,7 +8539,7 @@ When `lights` is specified, **all** default lights are removed. You must include
 
 Setting `camera.position` overrides auto-framing — the viewport will no longer auto-fit the geometry on script reload.
 
-Named render views let scripts check in repeatable cameras next to the model code. The canonical shape is `{ camera: { position, target } }`, and a direct camera shorthand `{ position, target }` is also accepted. Use the canonical shape when you may add view metadata later. Use it from the CLI with `forgecad render 3d model.forge.js --view hero`.
+Named render views let scripts check in repeatable cameras next to the model code. The canonical shape is `{ camera: { position, target } }`, and a direct camera shorthand `{ position, target }` is also accepted. Use the canonical shape when you may add view metadata later. Use it from the CLI with `--view hero` on `forgecad render 3d`, `forgecad render hq`, or `forgecad capture`.
 
 Model journeys let scripts check in a compact guided path through named objects. Each journey has ordered `steps`; each step can name a `focus` target by object name/tree path, provide a caption, and optionally provide an explicit camera. In the viewer, journeys are opt-in: they appear as a small Explore control and do not move the camera until the user starts them. Use `forgecad run model.forge.js --journeys` or `--journeys-json` to inspect resolved targets.
 
@@ -8972,7 +8608,6 @@ scene(options: SceneOptions): void
 | `behavior?` | `"opt-in" \| "auto"` | Whether the viewer should offer or auto-open the journey. First slice supports opt-in. |
 | `steps` | `SceneJourneyStepConfig[]` | Ordered journey spine. Branches can be added later without changing this core contract. |
 | `valid?` | `boolean` | True unless any journey or step diagnostic has level "error". |
-| `diagnostics?` | `SceneJourneyDiagnostic[]` | Whole-journey diagnostics, including unresolved startsAt and step target diagnostics. |
 
 **`SceneJourneyStepConfig`**
 
@@ -8985,9 +8620,6 @@ scene(options: SceneOptions): void
 | `camera?` | `SceneViewCameraConfig` | Optional explicit camera for this step. When omitted, the viewer fits `focus`. |
 | `resolvedFocusId?` | `string \| null` | Resolved object id after script execution, when `focus` matched exactly one object. |
 | `resolvedFocusPath?` | `string \| null` | Resolved object tree path or name after script execution. |
-| `diagnostics?` | `SceneJourneyDiagnostic[]` | Resolution diagnostics for this step. |
-
-`SceneJourneyDiagnostic`: `{ level: SceneJourneyDiagnosticLevel, message: string, stepId?: string, suggestions?: string[] }`
 
 **`SceneLightConfig`**
 
@@ -9063,10 +8695,6 @@ viewConfig({
 viewConfig(options?: ViewConfigOptions): void
 ```
 
-`ViewConfigOptions`: `{ jointOverlay?: JointOverlayViewConfigOptions }`
-
-**`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`
-
 #### `explodeView()` — Configure how the viewport explode slider offsets returned objects.
 
 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.
@@ -9576,8 +9204,9 @@ Setting `KNUCK_R = H / 2` exactly makes the body cross-section a stadium that pe
 
 `forgecad render inspect` writes a deterministic directory bundle for agents,
 tests, and automation. Use it when a single shaded PNG is too ambiguous and the
-consumer needs geometry-aware signals such as depth, normals, part identity,
-physical connected components, collisions, local thickness, or cross-sections.
+consumer needs geometry-aware signals such as depth, normals, surface roughness,
+part identity, physical connected components, collisions, local thickness, or
+cross-sections.
 
 ## When To Use It
 
@@ -9597,14 +9226,16 @@ forgecad render inspect model.forge.js --channels rgb,mask,section
 forgecad render inspect model.forge.js --channels collisions --focus Bench
 forgecad render inspect model.forge.js --channels rgb,mask --hide "Bench.Slat0,Bench.Slat1"
 forgecad render inspect model.forge.js --channels thickness --min-thickness 1.2 --warn-thickness 2.0
+forgecad render inspect channels
 ```
 
 The default output directory is `<script-name>-inspect/` next to the input file.
 Pass `--force` to replace an existing bundle directory.
 
 There are no default channels. Pass `--channels` every time as a
-comma-separated subset. Keep bundles targeted to the current question so heavy
-analyses do not run unnecessarily.
+comma-separated subset. Run `forgecad render inspect channels` to list the
+supported channels in the installed CLI. Keep bundles targeted to the current
+question so heavy analyses do not run unnecessarily.
 
 `--focus` and `--hide` use the same object-name filtering semantics as
 `forgecad run` and `forgecad render 3d`. A bare `--focus` hides mock objects;
@@ -9660,12 +9291,13 @@ implemented channel in one bundle:
 
 ```bash
 forgecad render inspect model.forge.js --channels depth,normals
+forgecad render inspect model.forge.js --channels rgb,roughness
 forgecad render inspect model.forge.js --channels rgb,mask,collisions
 forgecad render inspect model.forge.js --channels rgb,section,thickness
 ```
 
-Supported channels are `rgb`, `depth`, `normals`, `mask`, `connectivity`,
-`distance`, `collisions`, `thickness`, and `section`.
+Supported channels are `rgb`, `depth`, `normals`, `roughness`, `mask`,
+`connectivity`, `distance`, `collisions`, `thickness`, and `section`.
 
 ## Channel Semantics
 
@@ -9692,6 +9324,27 @@ normal = normalize((rgb / 255) * 2 - 1)
 
 Background pixels are black and should be treated as `null`.
 
+`roughness` emits a mesh-dihedral surface-quality heatmap. Smooth and gently
+curved triangles render as a faint translucent shadow over black, while
+triangles adjacent to sharp, harsh, boundary, or non-manifold mesh edges render
+in orange or magenta:
+
+```text
+shadow  = max adjacent angle < sharpAngleDeg
+orange  = sharpAngleDeg <= angle < harshAngleDeg
+magenta = angle >= harshAngleDeg, boundary, or non-manifold
+```
+
+The default thresholds are `smoothAngleDeg=5`, `sharpAngleDeg=30`, and
+`harshAngleDeg=90`. The manifest stores the method, thresholds, palette, object
+list, per-object triangle and edge counts, area percentages by smooth,
+moderate, sharp, and harsh classes, angle percentiles, maximum angle, quality
+score, and warnings. Moderate angles are reported in the manifest but stay in
+the shadow layer by default so intentionally curved surfaces do not light up as
+defects. Use this channel to spot spiky tessellation, accidental faceting,
+jagged boolean residue, and dense sharp-corner regions without losing the
+silhouette of otherwise smooth surfaces.
+
 `mask` emits one object-color image per view. Black is background. Non-black
 pixels resolve through `manifest.channels.mask.objects`, which includes object
 index, RGB color, object id, name, group, tree path, and mock flag. Edge pixels
@@ -9734,9 +9387,15 @@ root = largest component by body count, object count, then bbox volume
 rootDistance = shortest accumulated gap distance from root component
 ```
 
+For large scenes the manifest does not materialize the complete component gap
+graph, because that graph is quadratic in the number of components. The
+`gapEdgeCount` field reports the logical complete-graph edge count used by the
+analysis. `gapEdges` stores a compact evidence subset containing nearest-gap
+and root-parent edges.
+
 The PNG colors components from green at the root/near distances through yellow to
 red at the farthest rooted component. The manifest stores the root component,
-maximum rooted distance, complete component gap edge list, nearest-gap data, and
+maximum rooted distance, compact gap edge evidence, nearest-gap data, and
 shortest-path parent fields. The current v1 metric is bbox-based: it measures air
 gaps between component bounding boxes, not exact closest mesh-surface distance.
 
@@ -9753,8 +9412,8 @@ collision = boolean intersection volume > 0.1mm^3
 ```
 
 The manifest stores the inspected objects, collision pair names/ids, overlap
-volume, warnings, render style, and each collision finding's `groupIndex`,
-`color`, and `hex`. Exact interior pixels can be matched against
+volume, broadphase counters, warnings, render style, and each collision finding's
+`groupIndex`, `color`, and `hex`. Exact interior pixels can be matched against
 `manifest.channels.collisions.collisions[].color`; antialiased edges may blend
 with the ghosted source geometry. If `--focus PartA,PartB` is used, everything
 except those objects is hidden, `PartA` and `PartB` are ghosted, and their
@@ -10026,6 +9685,36 @@ intersect(...others: SdfShape[]): SdfShape
 clipBox(x: number, y: number, z: number): SdfShape
 ```
 
+#### `fillWith()` — Keep only the material where this shape overlaps another SDF pattern.
+
+```ts
+fillWith(pattern: SdfShape): SdfShape
+```
+
+#### `fillWithGyroid()` — Keep only the gyroid lattice inside this shape.
+
+```ts
+fillWithGyroid(options: TpmsOptions): SdfShape
+```
+
+#### `fillWithSchwarzP()` — Keep only the Schwarz-P lattice inside this shape.
+
+```ts
+fillWithSchwarzP(options: TpmsOptions): SdfShape
+```
+
+#### `fillWithDiamond()` — Keep only the diamond TPMS lattice inside this shape.
+
+```ts
+fillWithDiamond(options: TpmsOptions): SdfShape
+```
+
+#### `fillWithLidinoid()` — Keep only the lidinoid TPMS lattice inside this shape.
+
+```ts
+fillWithLidinoid(options: TpmsOptions): SdfShape
+```
+
 #### `smoothUnion()` — Smooth union — blends shapes together with a smooth radius.
 
 ```ts
@@ -10104,6 +9793,14 @@ bend(radius: number): SdfShape
 repeat(spacing: Vec3, count?: Vec3): SdfShape
 ```
 
+#### `circularArray()` — Arrange this SDF in a circular array around the Z axis.
+
+The source shape is translated by `offset` in +X before arraying. This uses angular domain folding, so evaluation stays O(1): the source SDF is sampled twice no matter how many copies are requested.
+
+```ts
+circularArray(count: number, offset?: number): SdfShape
+```
+
 #### `shell()` — Hollow out, keeping only a shell of given thickness.
 
 ```ts
@@ -10116,8 +9813,8 @@ shell(thickness: number): SdfShape
 // Function displacement
 shape.displace((x, y, z) => Math.sin(x) * 0.5)
 
-// Pattern displacement (e.g. basketWeave)
-shape.displace(sdf.basketWeave({ threads: 16, spacing: 3 }))
+// Pattern displacement from a 3D SDF field
+shape.displace(sdf.knurl({ pitch: 2, depth: 0.3 }))
 ```
 
 ```ts
@@ -10130,10 +9827,16 @@ Automatically detects the shape's UV parametrization (sphere, cylinder, torus) f
 
 UV coordinates are in **surface millimeters** — patterns defined with `spacing: 3` always produce 3mm spacing, regardless of shape size.
 
+Prefer `sdf.pattern2d()` or built-in surface patterns when the relief should stay on the native shader and meshing path. Callback functions are supported for experimentation, but they are opaque to the typed pattern optimizer.
+
 ```js
-// Surface-following basket weave — auto-detects sphere UV
+// Native typed pattern — auto-detects sphere UV
+const p = sdf.pattern2d()
+const ribs = p.stripes({ spacing: 3, width: 0.8, depth: 0.35 })
+  .add(p.sineWave({ direction: [0, 1], wavelength: 14, amplitude: 0.08 }))
+
 sdf.sphere(27).shell(3)
-  .surfaceDisplace(sdf.basketWeave({ spacing: 3, depth: 0.8 }))
+  .surfaceDisplace(ribs)
   .toShape()
 
 // Custom 2D pattern via function
@@ -10205,9 +9908,11 @@ return {
 - `brick(options?: BrickOptions): SdfShape` — Brick/stone wall pattern — running bond with mortar grooves.
 - `weave(options?: WeaveOptions): SdfShape` — Grid lattice pattern — two families of infinite slabs crossing at 90°.
 - `basketWeave(options?: BasketWeaveOptions): SurfacePattern` — Basket weave surface pattern — threads with over-under crossings in UV space. Returns a SurfacePattern for use with `.surfaceDisplace()`.
+- `pattern2d(): Pattern2DBuilder` — Create typed, composable 2D surface patterns for `.surfaceDisplace()`.
 - `twist(shape: SdfShape, degreesPerUnit: number): SdfShape` — Twist an SDF shape around the Z axis.
 - `bend(shape: SdfShape, radius: number): SdfShape` — Bend an SDF shape around the Z axis.
 - `repeat(shape: SdfShape, spacing: Vec3, count?: Vec3): SdfShape` — Repeat an SDF shape in space.
+- `circularArray(shape: SdfShape, count: number, offset?: number): SdfShape` — Arrange an SDF shape in a circular array around the Z axis with O(1) folded-domain evaluation.
 - `SurfacePattern: typeof SurfacePattern` — A 2D surface pattern — a heightmap function for use with `.surfaceDisplace()`.
 - `fromFunction(fn: SdfFunctionSource, options: SdfFunctionOptions): SdfShape` — Create a custom SDF from one expression; shader-safe expressions raymarch directly.
 - `Sculpt: { sphere: (radius: number) => SdfShape; box: (x: number, y: number, z: number, options?: SculptBoxOptions) => SdfShape; cylinder: (height: number, radius: number) => SdfShape; disk: (radius: number, thickness?: number) => SdfShape; circle: (radius: number, thickness?: number) => SdfShape; capsule: (height: number, radius: number) => SdfShape; torus: (majorRadius: number, minorRadius: number) => SdfShape; cone: (height: number, radius: number) => SdfShape; tube: (points: SculptPointList, options?: SculptTubeOptions) => SdfShape; curve: (points: SculptPointList, options?: SculptTubeOptions) => SdfShape; path: (points: SculptPointList, options?: SculptTubeOptions) => SdfShape; blend: (first?: SculptBlendInput | SculptBlendOptions, optionsOrShape?: SculptBlendInput | SculptBlendOptions, ...rest: (SculptBlendInput | SculptBlendOptions)[]) => SdfShape; union: (first?: SculptBlendInput, ...rest: SculptBlendInput[]) => SdfShape; carve: (base: SdfShape, cutters: SculptBlendInput, options?: SculptBlendOptions) => SdfShape; keep: (first?: SculptBlendInput | SculptBlendOptions, optionsOrShape?: SculptBlendInput | SculptBlendOptions, ...rest: (SculptBlendInput | SculptBlendOptions)[]) => SdfShape; polish: (shape: SdfShape, input?: SculptPolishInput) => SdfShape; material: (input?: SculptPolishInput) => ShapeMaterialProps & { color?: string; }; look: (preset?: SculptLookPreset) => SceneOptions; knownMaterials: typeof knownSculptMaterialPresets; }` — Sculpt-like facade: friendly liquid-modeling verbs backed by the same SDF kernel.