forgecad 0.9.4 → 0.9.6

package/dist-skill/docs/generated/lib.md

@@ -10,6 +10,7 @@ Pre-built fasteners, gears, pipes, structural profiles, and utility shapes. Acce
 ## Contents
 
 - [TangentLoop2D](#tangentloop2d)
+- [DriveWheelBuilder](#drivewheelbuilder)
 - [lib](#lib)
 
 ---
@@ -50,6 +51,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
@@ -58,7 +85,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`
 
@@ -68,7 +95,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`
 
@@ -76,7 +105,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)); ```
@@ -114,3 +143,11 @@ 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.

package/dist-skill/docs/generated/output.md

@@ -144,7 +144,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`
 

package/dist-skill/docs/generated/sdf.md

@@ -191,6 +191,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
@@ -269,6 +299,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
@@ -281,8 +319,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
@@ -295,10 +333,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
@@ -370,9 +414,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.

package/dist-skill/docs/generated/sketch.md

@@ -1457,7 +1457,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.

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

@@ -59,7 +59,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.
 
@@ -128,7 +128,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`**
 
@@ -141,9 +140,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`**
 
@@ -219,10 +215,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.

package/dist-skill/docs/guides/inspection-bundles.md

@@ -7,8 +7,9 @@ skill-order: 2
 
 `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
 
@@ -28,14 +29,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;
@@ -91,12 +94,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
 
@@ -123,6 +127,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
@@ -165,9 +190,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.
 
@@ -184,8 +215,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

package/dist-skill/docs-dev/API/core/concepts.md

@@ -34,7 +34,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.
 
@@ -67,6 +67,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.

package/dist-skill/docs-dev/CLI.md

@@ -113,12 +113,14 @@ forgecad run examples/constraints/06-complex-spectrogram.forge.js --solver-debug
 
 ### `forgecad render`
 
-Render a Forge scene. Use a subcommand — `3d`, `inspect`, `section`, `wireframe`, `sketch`, or `hq`.
+Render a Forge scene. Use a subcommand — `3d`, `inspect`, `views`, `section`, `wireframe`, `sketch`, or `hq`.
 
 `forgecad render` is a group of rendering subcommands. Pick one based on what you want:
 
 - `render 3d` — standard viewport PNG, the usual way to visually verify geometry
 - `render inspect` — machine-readable inspection bundle with geometry channels and a manifest
+- `render inspect channels` — list supported inspection channels
+- `render views` — list named cameras declared with `scene({ views })`
 - `render wireframe` — edges only, no shading
 - `render section` — 2D cross-section cut by a plane (SVG or PNG)
 - `render sketch` — 2D sketch script to PNG
@@ -127,6 +129,8 @@ Render a Forge scene. Use a subcommand — `3d`, `inspect`, `section`, `wirefram
 ```bash
 forgecad render 3d examples/cup.forge.js
 forgecad render inspect examples/api/static-assembly-connectors.forge.js --channels rgb,mask
+forgecad render inspect channels
+forgecad render views examples/cup.forge.js
 forgecad render wireframe examples/cup.forge.js
 forgecad render section examples/furniture/01-table.forge.js --plane XZ
 forgecad render hq examples/cup.forge.js --preset dramatic
@@ -138,7 +142,7 @@ Render a Forge scene to PNG using the real viewport renderer.
 
 Launches a headless Chrome instance, renders the scene with the same WebGL viewport as the editor, and saves a PNG. The output path defaults to `<script-name>.png` next to the input file.
 
-Use `--focus` to isolate specific parts (hides everything else) or `--hide` to remove clutter like mock objects. The `--view` flag selects a named camera declared in `scene({ views })`. The `--camera` flag accepts built-in views (`front`, `top`, `iso`), `azimuth:elevation` angles, or an exact `proj/pos/target/up/fov` camera spec — pass `--camera` multiple times to render several viewpoints in one run.
+Use `--focus` to isolate specific parts (hides everything else) or `--hide` to remove clutter like mock objects. The `--view` flag selects a named camera declared in `scene({ views })`. The `--camera` flag accepts built-in views (`front`, `top`, `iso`), `azimuth:elevation` angles, or an exact `proj/pos/target/up/fov` camera spec — pass `--camera` multiple times to render several viewpoints in one run. Use `--camera-json <file>` or `--scene <file>` for exact reproducible viewport cameras without shell escaping.
 
 Use `--edges=<off|thin|bold>` to control the edge overlay. For a pure wireframe look, use `render wireframe` instead.
 
@@ -152,16 +156,29 @@ forgecad render 3d examples/cup.forge.js --hide "wall,bolt"
 forgecad render 3d model.forge.js --view hero
 forgecad render 3d model.forge.js --camera 45:30
 forgecad render 3d model.forge.js --camera "proj=perspective;pos=200,-160,120;target=0,0,20;up=0,0,1;fov=38"
+forgecad render 3d model.forge.js --camera-json camera.json
+forgecad render 3d model.forge.js --scene scene.json
 forgecad render 3d model.forge.js --camera front --camera side
 forgecad render 3d model.forge.js --edges bold
 forgecad render 3d model.forge.js --edges off
 ```
 
+### `forgecad render views`
+
+List named camera views declared by a model with `scene({ views })`.
+
+Runs the script headlessly and prints every named render view with an exact camera spec that can be passed back to `render 3d`, `render hq`, or `capture`.
+
+```bash
+forgecad render views model.forge.js
+forgecad render views model.forge.js --json
+```
+
 ### `forgecad render inspect`
 
 Render a machine-readable inspection bundle with geometry channels and a manifest.
 
-Launches the headless viewport renderer and writes a directory bundle for agent and automation workflows. Every channel is opt-in with `--channels`; there is no default bundle. Selected channels emit canonical `front`, `right`, `top`, and `iso` views for RGB, depth, normals, object masks, physical connectivity, rooted component distance, collisions, and wall thickness, or a principal-plane section atlas, plus a root `manifest.json` with scene metadata, filters, object visibility, and relative file paths.
+Launches the headless viewport renderer and writes a directory bundle for agent and automation workflows. Every channel is opt-in with `--channels`; there is no default bundle. Selected channels emit canonical `front`, `right`, `top`, and `iso` views for RGB, depth, normals, surface roughness, object masks, physical connectivity, rooted component distance, collisions, and wall thickness, or a principal-plane section atlas, plus a root `manifest.json` with scene metadata, filters, object visibility, and relative file paths.
 
 Use `--focus` to isolate specific parts or hide mocks, and `--hide` to remove named clutter. Output defaults to `<script-name>-inspect/` next to the input file.
 
@@ -173,6 +190,15 @@ forgecad render inspect examples/api/static-assembly-connectors.forge.js out/ben
 forgecad render inspect examples/api/static-assembly-connectors.forge.js --channels rgb,mask,collisions --hide "Bench.Slat0" --force
 ```
 
+### `forgecad render inspect channels`
+
+List supported inspection bundle channels.
+
+```bash
+forgecad render inspect channels
+forgecad render inspect channels --json
+```
+
 ### `forgecad render wireframe`
 
 Render a Forge scene as a wireframe (edges only, no shading).
@@ -190,13 +216,15 @@ High-quality render via Blender Cycles — path-traced, HDRI, material presets.
 
 Exports the scene to Blender and renders with Cycles (path tracer). Requires Blender installed and on PATH.
 
-Choose a `--preset` for the look: `studio` (neutral product shot), `dramatic` (high-contrast), `clay` (matte, no color), `glass`, `metallic`, `toon`, `xray`, `normals`, `silhouette`, and more. Control quality vs speed with `--samples` (default 256). Use `--transparent` for a transparent background (compositing-ready).
+Choose a `--preset` for the look: `studio` (neutral product shot), `dramatic` (high-contrast), `clay` (matte, no color), `glass`, `metallic`, `toon`, `xray`, `normals`, `silhouette`, and more. Control quality vs speed with `--samples` (default 256). Use `--view`, `--camera`, `--camera-json`, or `--scene <file>` for still camera control, matching `render 3d`. Use `--transparent` for a transparent background (compositing-ready).
 
 Output defaults to `<script-name>-hq.png`. Great for documentation, marketing renders, and social media.
 
 ```bash
 forgecad render hq examples/cup.forge.js
 forgecad render hq examples/cup.forge.js hero.png --preset dramatic --samples 1024
+forgecad render hq examples/cup.forge.js hero.png --view hero
+forgecad render hq examples/cup.forge.js hero.png --camera-json camera.json
 forgecad render hq examples/cup.forge.js --preset clay --size 2048
 forgecad render hq examples/cup.forge.js --transparent --preset glass
 ```
@@ -205,16 +233,20 @@ forgecad render hq examples/cup.forge.js --transparent --preset glass
 
 Animated orbit or joint playback.
 
-Renders an animated sequence by either orbiting the camera around the model or playing back a `jointsView` animation. Use `--capture orbit` (default) for a turntable rotation, `--capture animation --animation <name>` to play a named joints clip, or `--capture section-sweep` to move a clipping plane through the model. Supports `--cut-plane` to animate with a static cross-section visible.
+Renders an animated sequence by either orbiting the camera around the model or playing back a `jointsView` animation. Use `--capture orbit` (default) for a turntable rotation, `--capture animation --animation <name>` to play a named joints clip, or `--capture section-sweep` to move a clipping plane through the model. Supports `--cut-plane` to animate with a static cross-section visible. Use `--view`, `--camera`, `--camera-json`, or `--scene <file>` to choose the orbit base camera or the fixed camera for animations and section sweeps.
 
 ```bash
 forgecad capture gif examples/cup.forge.js
 forgecad capture gif examples/3d-printer.forge.js out/section.gif --cut-plane "Front Section"
 forgecad capture gif model.forge.js out/raw.gif --param "Output=raw-sdf"
+forgecad capture gif model.forge.js out/front.gif --camera front
+forgecad capture gif model.forge.js out/hero.gif --view hero
 forgecad capture gif examples/3d-printer.forge.js out/sweep.gif --capture section-sweep --sweep-plane YZ
 forgecad capture mp4 examples/cup.forge.js
 forgecad capture mp4 examples/api/runtime-joints-view.forge.js out/step.mp4 --capture animation --animation Step
 forgecad capture mp4 model.forge.js out/raw.mp4 --param "Output=raw-sdf"
+forgecad capture mp4 model.forge.js out/front.mp4 --camera front
+forgecad capture mp4 model.forge.js out/hero.mp4 --view hero
 forgecad capture mp4 examples/3d-printer.forge.js out/sweep.mp4 --capture section-sweep --sweep-plane YZ --sweep-frames 180
 ```
 
@@ -247,18 +279,22 @@ forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edge
 | `--focus <names>` | Focus: no arg hides mocks; comma-separated names shows only those |
 | `--hide <names>` | Hide comma-separated object names |
 | `--camera <front\|back\|side\|right\|top\|iso\|az:el\|az:el:dist\|spec>` | Camera preset, spherical (az:el), or full spec such as `proj=perspective;pos=x,y,z;target=x,y,z;up=x,y,z;fov=45`. Repeatable. |
+| `--camera-json <file>` | Exact viewport camera JSON file |
 | `--view <name>` | Named camera view declared by the model with scene({ views }) |
 | `--size <px>` | Image size in pixels |
-| `--scene <json>` | Viewport scene state JSON |
+| `--scene <json\|file>` | Viewport scene state JSON or JSON file |
 | `--background <color>` | Canvas background override |
 | `--render-mode <solid\|wireframe>` | Shaded solid (default) or wireframe only |
-| `--edges <off\|thin\|bold>` | Edge overlay preset in solid mode (default: thin) |
+| `--edges <off\|thin\|bold>` | Edge overlay preset in solid mode (default: off) |
 | `--render-style <classic\|studio\|fast\|glass>` | Visual render style (default: classic) |
 | `--port <n>` | Vite dev server port |
+| `--fresh-server` | Start a fresh renderer instead of reusing an existing one |
 | `--chrome-path <path>` | Chrome or Chromium executable path |
 | `--output <path>` | Output file path |
-| `--channels <rgb,depth,normals,mask,connectivity,distance,collisions,thickness,section>` | Required inspection channels to emit; no default |
-| `--quality <default\|live\|high>` | Mesh/render quality |
+| `--json` | Print machine-readable JSON |
+| `--quality <default\|live\|high>` | Mesh quality preset |
+| `--backend <manifold\|occt\|truck>` | Geometry backend |
+| `--channels <rgb,depth,normals,roughness,mask,connectivity,distance,collisions,thickness,section>` | Required inspection channels to emit; no default |
 | `--force` | Replace an existing bundle directory |
 | `--min-thickness <mm>` | Critical thickness threshold in model units |
 | `--warn-thickness <mm>` | Warning thickness threshold in model units |
@@ -276,7 +312,6 @@ forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edge
 | `--frames <n>` | Video frames per revolution |
 | `--fps <n>` | Video frame rate |
 | `--pitch <deg>` | Camera pitch angle in degrees |
-| `--backend <manifold\|occt\|truck>` | Geometry backend |
 | `--format <gif\|mp4>` | Output format |
 | `--capture <orbit\|animation\|section-sweep>` | Capture preset |
 | `--animation <name>` | Named jointsView animation clip |
@@ -330,6 +365,7 @@ forgecad cut-list examples/api/sheet-stock-cut-list.forge.js
 forgecad export cutting-layout examples/api/sheet-stock-cut-list.forge.js --sheet-width 420 --sheet-height 594 --kerf 3
 
 # 3D printing
+forgecad check print bracket.forge.js
 forgecad export stl bracket.forge.js
 forgecad export 3mf bracket.forge.js --quality high
 
@@ -494,11 +530,26 @@ forgecad skill one-file ~/Desktop/forgecad-context.md
 forgecad skill flattened-files ~/Desktop/forgecad-skills
 ```
 
-> **Workflow:** Agent writes the model -> `forgecad run` validates it -> `forgecad render inspect` produces evidence -> `forgecad check params` sweeps the parameter range -> export ships the result. All in the terminal.
+> **Workflow:** Agent writes the model -> `forgecad run` validates it -> `forgecad check print` catches printability risks -> `forgecad render inspect` produces visual evidence -> `forgecad check params` sweeps parameter robustness -> export ships the result. All in the terminal.
 
 ## Validation
 
-Test parameter ranges and run invariant suites.
+Check printability, test parameter ranges, and run invariant suites.
+
+### `forgecad check print`
+
+Run fast 3D-print readiness checks for collisions, mesh health, walls, overhangs, and bed contact.
+
+Runs a Forge script with the headless kernel and emits a slicer-adjacent printability report without launching a browser. The check is designed for agents: JSON is stable, failures name the specific print risk, and the default profile is conservative for FDM PLA on a 0.4mm nozzle.
+
+Checks include script `verify.*` results, exact positive-volume object collisions, physical component count, mesh topology, sampled wall thickness, unsupported overhang budget, and bed-contact area. Use `--json` for automation and `--output` to save the full report while keeping the readable terminal summary.
+
+```bash
+forgecad check print examples/api/attachTo-basics.forge.js
+forgecad check print examples/api/verification-demo.forge.js --json
+forgecad check print model.forge.js --min-wall 1.2 --warn-wall 2
+forgecad check print model.forge.js --expect-components 1 -p "Wall Thickness=3"
+```
 
 ### `forgecad check params`
 
@@ -566,7 +617,7 @@ The CLI is free for core workflows and exports. Production outputs are free to r
 
 | Free | Production outputs | Pro |
 |------|--------------------|-----|
-| `run`, `dev`, `studio`, `render 3d`, `export stl`, `export 3mf`, `export svg`, `check params`, `check suite` | `cut-list`, `export sketch-pdf`, `export step`, `export brep`, `export gcode`, `export sdf`, `export urdf`, `export report`, `export cutting-layout` are free to run; Pro covers commercial use. | `render hq`, `capture gif`, `capture mp4` |
+| `run`, `dev`, `studio`, `render 3d`, `export stl`, `export 3mf`, `export svg`, `check print`, `check params`, `check suite` | `cut-list`, `export sketch-pdf`, `export step`, `export brep`, `export gcode`, `export sdf`, `export urdf`, `export report`, `export cutting-layout` are free to run; Pro covers commercial use. | `render hq`, `capture gif`, `capture mp4` |
 
 ```bash
 forgecad license                    # Check signed-in account status

package/dist-skill/docs-dev/generated/assembly.md

@@ -29,7 +29,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.
 
@@ -670,13 +675,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.