forgecad 0.9.2 → 0.9.3

package/dist-skill/CONTEXT.md

@@ -27,7 +27,8 @@ Prefer documented primitives, import rules, and placement strategies over invent
 
 ### Import and composition
 
-- `require("./file.forge.js", { Param: value })` for any model file, with optional param overrides.
+- Always include the extension in relative imports: `require("./file.forge.js", { Param: value })` for model files and `require("./helpers.js")` for plain helper modules. Do not write extensionless imports such as `require("./file")`; ForgeCAD resolves project imports by exact path.
+- ForgeCAD APIs are injected globals in `.forge.js` files. Use `bom()`, `box()`, `scene()`, `Shape`, etc. directly; do not destructure those names from helpers with patterns like `const { bom } = require("./bom.js")`. If a helper file is needed, import it under a project-specific name such as `const bomHelpers = require("./bom.js")`.
 - `importSvgSketch()` for SVG files (file format loader, not a module import).
 - `.placeReference('bottom', [0,0,0])` to align any built-in anchor to a world coordinate; also works with custom `.withReferences()`.
 - Plain `.js` modules for shared helpers/constants (not model imports).
@@ -102,6 +103,24 @@ const width = param("Width", 50, { min: 20, max: 100, unit: "mm" });
 return box(width, 30, 10);
 ```
 
+## Injected Runtime Names
+
+ForgeCAD API functions and classes are injected into every `.forge.js` script. Use them directly; do not import or destructure ForgeCAD API names from helper files.
+
+```javascript
+// BAD — `bom` and `bomToCsv` are already built-in runtime names.
+const { bom, bomToCsv } = require("./bom.js");
+
+// GOOD — use the built-in directly.
+bom(4, "M4 bolt");
+
+// GOOD — keep project helpers under their own local name.
+const bomHelpers = require("./bom.js");
+bomHelpers.addFasteners(...);
+```
+
+Top-level declarations such as `const bom = ...`, `let scene = ...`, or `class Shape {}` collide with the injected runtime names. If you need a local helper, choose a project-specific name like `projectBom`, `sceneConfig`, or `makeShape`.
+
 ## Execution Model
 
 - Scripts re-execute on every parameter change (400ms debounce)
@@ -114,6 +133,8 @@ Top-level assembly scripts can return an unsolved `Assembly` directly; ForgeCAD
 
 A script can return a plain object whose values include renderable geometry alongside non-renderable metadata. All renderable entries (Shape, Sketch, ShapeGroup, Assembly, SolvedAssembly, SdfShape, or Array of named objects) are rendered; non-renderable entries are silently skipped. This is useful for multi-file projects where a part needs to publish interface data (bolt positions, dimensions) to other files:
 
+When importing project files, include the full extension in every relative path: `require('./motor-mount.forge.js')` for model files and `require('./helpers.js')` for plain helper modules. ForgeCAD resolves project imports by exact path and does not infer `.forge.js` or `.js` from `require('./motor-mount')`.
+
 ```javascript
 // motor-mount.forge.js — renders standalone, exports metadata via require()
 const holePositions = [[17, 15], [-29, 15], [17, -15], [-29, -15]];
@@ -165,6 +186,12 @@ Shapes carry semantic face labels through their lifecycle. The flow is:
 
 You resolve labels to geometry with `.face(name)` or `.face(query)` — see the Shape class docs for the full query API. Operations like `.pocket()`, `.boss()`, `.hole()`, and `faceProfile()` all consume face references.
 
+## Text vs Viewport Labels
+
+Use `text2d()` only when the letters are part of the model: raised text, engraving, cut labels, serial plates, exported markings, or geometry that should survive into STL/STEP output. `text2d()` builds filled sketch geometry from font outlines, so it can make exact/OCCT workflows slower.
+
+Use `Viewport.label(text, [x, y, z], options)` when the goal is to explain the model in the viewport. Render labels are annotations only: they do not create meshes, do not export, do not enter the B-rep path, and do not add face labels.
+
 ## SDF Modeling
 
 For organic shapes, smooth blending, TPMS lattices, and surface deformations. Return `SdfShape` values directly, or return a plain object/array tree of SDF leaves, for native raymarch preview. Use `.toShape()` or `toShape(...)` only when you need mesh-backed CAD/export behavior. See [sdf-primitives.md](sdf-primitives.md).
@@ -584,6 +611,8 @@ coalesceEdges(segments: EdgeSegment[], tolerance?: number): EdgeSegment[]
 
 When importing a `.forge.js` file, the return value is what the script returns. If the script returns a metadata object (e.g. `{ shape: myShape, bolts: {...} }`), the caller receives the full object — renderable values and metadata together.
 
+**Path rule:** Always include the file extension in relative imports: use `require("./part.forge.js")` for model files and `require("./helpers.js")` for plain helper modules. ForgeCAD does not apply Node-style extension inference, so `require("./part")` will not find `part.forge.js` or `part.js`.
+
 **Parameter scoping:** Parameters declared in required files are automatically namespaced with a `"filename#N / "` prefix (e.g. `"bracket.forge.js#1 / Width"`). This prevents collisions when multiple files declare same-named params. Each file's params appear as separate sliders.
 
 **Parameter overrides:** When passing overrides, use the bare param name (not the scoped name). Overrides are type-checked — unrecognized keys throw an error with typo suggestions.
@@ -2571,6 +2600,8 @@ loadFont(source: string | ArrayBuffer, cacheKey?: string): opentype.Font
 
 The Sketch origin is at the left end of the text baseline by default. Use `align` and `baseline` options to adjust placement. Text is rendered using the bundled Inter font by default, or any TTF/OTF/WOFF font you provide.
 
+`text2d()` creates real geometry. For non-exported explanatory labels in the viewport, prefer `Viewport.label()` so the text stays off the geometry and OCCT compile paths.
+
 Alignment reference table:
 
 | `align`    | `baseline`   | Origin                              |
@@ -4086,9 +4117,11 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 - [QuinticHermiteCurve3D](#quintichermitecurve3d)
 - [ProductSkin](#productskin)
 - [ProductSurfaceRef](#productsurfaceref)
+- [ProductSurfaceBuilder](#productsurfacebuilder)
 - [ProductSkinBuilder](#productskinbuilder)
 - [ProductStationBuilder](#productstationbuilder)
 - [ProductPanelBuilder](#productpanelbuilder)
+- [ProductRibbonBuilder](#productribbonbuilder)
 - [ProductSpoutBuilder](#productspoutbuilder)
 - [ProductHandleBuilder](#producthandlebuilder)
 - [ProductHandleFeature](#producthandlefeature)
@@ -4969,12 +5002,31 @@ integrate(...details: Shape[]): Shape
 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
 uv(side: ProductSkinSide, u?: number, v?: number): ProductSkinRefQuery
 ```
 
+**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
+
+`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
+
+**`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. |
+
 #### `ref()` — Resolve a named ref published with Product.skin().refs(...).
 
 ```ts
@@ -4987,18 +5039,32 @@ ref(name: string): ProductSurfaceRef
 curveOnSurface(name: string, points: Array<Partial<ProductSkinRefQuery> & { side: ProductSkinSide; }>): ProductSurfaceRef[]
 ```
 
+#### `surface()` — Create a fluent surface helper for refs and conformal features on one side of this skin.
+
+Use this when several refs or ribbons share the same skin side; side-local helpers keep path points concise and make it harder to mix sides accidentally.
+
+```ts
+surface(side: ProductSkinSide): ProductSurfaceBuilder
+```
+
 #### `stationAt()` — Interpolate center, width, and depth at a normalized v or absolute axis value.
 
 ```ts
-stationAt(vOrAxis: number): { center: Vec3; width: number; depth: number; dWidth: number; dDepth: number; axisValue: number; }
+stationAt(vOrAxis: number): { ... }
 ```
 
+**`ProductProfileKind`**
+
+`"oval" | "roundedRect" | "circle" | "superEllipse" | "custom"`
+
 #### `frame()` — Build a local surface frame from a side/u/v query.
 
 ```ts
 frame(query: ProductSkinRefQuery): ProductSurfaceFrame
 ```
 
+**`ProductSurfaceFrame`**: `point: Vec3`, `normal: Vec3`, `tangentU: Vec3`, `tangentV: Vec3`, `matrix: Mat4`, `skin: string`, `representation: ProductSkinRepresentation`
+
 ### `ProductSurfaceRef`
 
 **Properties:**
@@ -5015,6 +5081,25 @@ 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
@@ -5027,12 +5112,98 @@ with(overrides: Partial<ProductSkinRefQuery>): ProductSurfaceRef
 attach(detail: Shape | ShapeGroup, options?: ProductAttachOptions): Shape | ShapeGroup
 ```
 
+`ProductAttachOptions`: `{ offset?: number, inset?: number }`
+
 #### `querySpec()` — Return the serializable side/u/v query behind this ref.
 
 ```ts
 querySpec(): ProductSkinRefQuery
 ```
 
+### `ProductSurfaceBuilder`
+
+Fluent helper bound to one ProductSkin side for refs and side-local conformal features.
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `side` | `ProductSkinSide` | — |
+
+**Methods:**
+
+#### `ref()` — Create a ref on this skin side.
+
+```ts
+ref(u?: number, v?: number, offset?: number): ProductSurfaceRef
+```
+
+#### `uv()` — Create a side/u/v query on this skin side.
+
+```ts
+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"`
+
+#### `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.
+
+```ts
+ribbon(name: string, points: ProductSurfacePathPoint[], options?: ProductRibbonBuildOptions): ProductRibbonBuilder
+```
+
+**`ProductSurfacePathPoint`**
+- `u?: number` — Across-side parameter on the bound side. 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.
+
+**`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). |
+
 ### `ProductSkinBuilder`
 
 **Properties:**
@@ -5049,24 +5220,55 @@ querySpec(): ProductSkinRefQuery
 axis(axis: ProductSkinAxis): this
 ```
 
+**`ProductSkinAxis`** — Primary world axis used to order ProductSkin loft stations.
+
+`"X" | "Y" | "Z"`
+
 #### `stations()` — Set named cross-section stations for the product skin.
 
 ```ts
 stations(stations: Array<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"`
+
 #### `rails()` — Attach guide rails as ProductSkin IR metadata and diagnostics.
 
 ```ts
 rails(rails: Record<string, ProductRailSpec>): this
 ```
 
+`ProductRailSpec`: `{ kind: ProductRailKind, points: Vec3[], degree?: number, name?: string }`
+
+**`ProductRailKind`**
+
+`"bezier" | "nurbs" | "polyline"`
+
 #### `ref()` — Publish a named semantic surface ref on the skin.
 
 ```ts
 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
@@ -5085,6 +5287,27 @@ uv(side: ProductSkinSide, u?: number, v?: number): ProductSkinRefQuery
 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 lowered skin.
 
 ```ts
@@ -5155,6 +5378,8 @@ oval(width: number, depth: number, options?: { segments?: number; }): this
 superEllipse(width: number, depth: number, options?: ProductStationSuperEllipseOptions): this
 ```
 
+`ProductStationSuperEllipseOptions`: `{ segments?: number, exponent?: number }`
+
 #### [`roundedRect()`](/docs/sketch#roundedrect) — Use a rounded-rectangle cross-section with the given corner radius.
 
 ```ts
@@ -5185,6 +5410,14 @@ 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:**
@@ -5225,6 +5458,27 @@ 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
@@ -5243,6 +5497,202 @@ build(): Shape
 attachTo(ref: ProductRefInput, options?: ProductPanelAttachOptions): Shape
 ```
 
+**`ProductRefInput`**
+
+`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.
+
+**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
+```
+
 ### `ProductSpoutBuilder`
 
 **Properties:**
@@ -5265,6 +5715,14 @@ 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
@@ -5283,6 +5741,27 @@ 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
@@ -5301,6 +5780,8 @@ build(): Shape
 attach(options?: ProductAttachOptions): Shape
 ```
 
+`ProductAttachOptions`: `{ offset?: number, inset?: number }`
+
 ### `ProductHandleBuilder`
 
 **Properties:**
@@ -5323,6 +5804,12 @@ 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
@@ -5335,6 +5822,27 @@ 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
@@ -5431,7 +5939,9 @@ toGroup(): ShapeGroup
 - `describeProfile(sketch: Sketch, kind?: ProductProfileKind, radius?: number): ProductProfileDescriptor` — Describe a custom sketch as a product profile.
 - `scaleProfileTo(sketch: Sketch, width: number, depth: number): Sketch` — Scale an existing profile sketch to a target width/depth.
 - `ref(skin: ProductSkin, query: ProductSkinRefQuery): ProductSurfaceRef` — Create an ad-hoc ProductSurfaceRef from a skin and side/u/v query.
+- `surface(skin: ProductSkin, side: ProductSkinSide): ProductSurfaceBuilder` — Create a fluent surface helper for refs and conformal features on one side of a skin. Equivalent to skin.surface(side), useful when writing in Product.* namespace style.
 - `panel(name: string): ProductPanelBuilder` — Start a panel feature builder.
+- `ribbon(name: string): ProductRibbonBuilder` — Start a conformal ribbon/trim builder for details that should bend with a ProductSkin. Call .on(skin, points) for side/u/v sampling or .fromRefs(points) for explicit surface refs, then configure width, thickness, offset, sampling, material, and color before build().
 - `spout(name: string): ProductSpoutBuilder` — Start a spout/nozzle feature builder.
 - `handle(name: string): ProductHandleBuilder` — Start a handle feature builder.
 - `place(detail: Shape | ShapeGroup, ref: ProductRefInput, options?: ProductAttachOptions): Shape | ShapeGroup` — Place a shape or group on a ProductSurfaceRef.
@@ -6754,6 +7264,7 @@ BOM entries are accumulated during script execution and exported alongside the m
 - `quantity` must be a finite number `>= 0`. A quantity of `0` is silently ignored (useful for conditional scripting with `param()`-driven counts).
 - `unit` defaults to `"pieces"` when omitted or empty.
 - The assembly `solved.bom()` / `solved.bomCsv()` API is separate and covers per-part assembly metadata; this function is for free-form purchased-item annotation.
+- `bom()` is injected into every `.forge.js` script. Call it directly; do not write `const { bom } = require(...)`, because top-level declarations named `bom` collide with the built-in runtime name.
 
 ```ts
 const tubeLen = param("Tube Length", 1200, { min: 300, max: 4000, unit: "mm" });
@@ -7205,7 +7716,7 @@ Cut planes, exploded views, joint animations, and scene configuration.
 
 ## Contents
 
-- [Viewport & Runtime](#viewport-runtime) — `scene`, `viewConfig`, `explodeView`, `jointsView`, `cutPlane`, `mock`, `showLabels`, `highlight`
+- [Viewport & Runtime](#viewport-runtime) — `Viewport.label`, `scene`, `viewConfig`, `explodeView`, `jointsView`, `cutPlane`, `mock`, `showLabels`, `highlight`
 - [RouteBuilder](#routebuilder)
 - [route](#route)
 
@@ -7213,14 +7724,50 @@ Cut planes, exploded views, joint animations, and scene configuration.
 
 ### Viewport & Runtime
 
+#### `Viewport.label()` — Add a render-only viewport label at a world-space point.
+
+`Viewport.label()` is for explanatory text that helps a viewer understand the model. It does not create sketches, meshes, B-rep topology, exported text, or face labels, so it stays off the OCCT path. Use [`text2d()`](/docs/sketch#text2d) only when the letters should become manufactured geometry, such as raised lettering, engraved serial numbers, or exported nameplates.
+
+Labels are collected during script execution and rendered by the viewport as lightweight overlay annotations. They are ignored by exports and do not appear in `objects`.
+
+```js
+Viewport.label('Bearing bore', [0, 0, 18], {
+  color: '#f8fafc',
+  background: '#0f172acc',
+  offset: [0, 0, 8],
+  anchor: 'bottom',
+});
+
+return box(40, 30, 12);
+```
+
+```ts
+Viewport.label(text: string, at: [ number, number, number ], options?: RenderLabelOptions): void
+```
+
+**`RenderLabelOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `color?` | `string` | Text color as any CSS color string. |
+| `background?` | `string` | Background color as any CSS color string. Use `'transparent'` for no pill background. |
+| `size?` | `number` | Font size in CSS pixels. Defaults to 12. |
+| `offset?` | `[ number, number, number ]` | Additional world-space offset from `at`. |
+| `anchor?` | `RenderLabelAnchor` | Which point of the label box is anchored to `at`. Defaults to `'center'`. |
+| `alwaysOnTop?` | `boolean` | When false, the label is hidden when occluded by scene geometry. Defaults to true. |
+
 #### `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.
+Controls camera position, named render views, optional model journeys, 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.
 
+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`.
+
+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.
+
 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.
@@ -7229,6 +7776,22 @@ All numeric values accept `param()` expressions.
 scene({
   background: { top: '#000814', bottom: '#001d3d' },
   camera: { position: [160, -120, 100], target: [0, 0, 50], fov: 52 },
+  views: {
+    hero: {
+      camera: { position: [180, -140, 90], target: [0, 0, 25], up: [0, 0, 1], fov: 38 },
+    },
+    side: { position: [240, 0, 70], target: [0, 0, 25], fov: 34 },
+  },
+  journeys: {
+    grandTour: {
+      title: 'Grand Tour',
+      startsAt: 'overview',
+      steps: [
+        { id: 'overview', focus: 'Solar System', caption: 'Start with the whole model.' },
+        { id: 'earth', focus: 'Earth', caption: 'Fit and inspect Earth.' },
+      ],
+    },
+  },
   lights: [
     { type: 'ambient', color: '#001233', intensity: 0.08 },
     { type: 'point', position: [120, -80, 130], color: '#00f5d4', intensity: 4, distance: 400, decay: 1 },
@@ -7255,12 +7818,38 @@ scene(options: SceneOptions): void
 | Option | Type | Description |
 |--------|------|-------------|
 | `capture?` | `SceneCaptureConfig` | Default capture parameters for `forgecad capture` — CLI flags override these. |
-| `background?`, `camera?`, `lights?`, `environment?`, `fog?`, `postProcessing?`, `ground?` | | — |
+| `background?`, `camera?`, `views?`, `journeys?`, `lights?`, `environment?`, `fog?`, `postProcessing?`, `ground?` | | — |
 
 `SceneBackgroundGradient`: `{ top: string, bottom: string }`
 
 **`SceneCameraConfig`**: `position?: [ number, number, number ]`, `target?: [ number, number, number ]`, `up?: [ number, number, number ]`, `fov?: number`, `type?: "perspective" | "orthographic"`
 
+**`SceneJourneyConfig`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `title?` | `string` | Viewer-facing journey title. Defaults to the journey id. |
+| `startsAt?` | `string` | Optional starting step id. Defaults to the first step. |
+| `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`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `id` | `string` | Stable step id used by viewer links and Next/Back state. |
+| `title?` | `string` | Viewer-facing title. Defaults to the step id. |
+| `focus?` | `string` | Object name or slash-separated tree path to focus. |
+| `caption?` | `string` | Short optional viewer caption. |
+| `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`**
 
 | Option | Type | Description |