forgecad 0.9.14 → 0.9.16

package/dist-skill/SKILL.md

@@ -17,7 +17,7 @@ Author or modify ForgeCAD models, sketches, assemblies, and CLI workflows. Prefe
 5. Default to a concrete first pass — easy iteration beats speculative design review.
 6. If an existing model is broken, replace the weak structure rather than preserving bad architecture.
 7. Validate with `forgecad run <file>` (add `--debug-imports` for import chain issues, and pass `--backend manifold|occt|truck` when the backend matters).
-8. For `jointsView()` animations, keep wrapped revolute tracks continuous across branch cuts; do not assume the viewport will auto-fix `-180/180` jumps.
+8. For moving assemblies, return the `Assembly` directly so runtime controls re-solve the link/edge kinematics model instead of stacking viewport-only transforms.
 9. 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.
 10. 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 `inspect sections` after the artifact exists.
 
@@ -40,6 +40,7 @@ Load groups top-to-bottom, stopping when you have what the task needs.
 Execution model, colors, coordinate system, primitives, booleans, patterns, imports, parameters, topology, edge queries.
 
 - `{{SKILL_DIR}}/docs/API/core/concepts.md`
+- `{{SKILL_DIR}}/docs/generated/runtime-names.md`
 - `{{SKILL_DIR}}/docs/generated/core.md`
 
 ### 2. Static Assembly and Positioning (for any multi-part model)
@@ -89,7 +90,7 @@ Parametric bolts, nuts, washers, standard hardware, gears, pipes, and structural
 
 ### 9. Runtime Viewport APIs (for cut planes, exploded views, hiding, and animation playback)
 
-Viewer-only APIs such as cutPlane, explodeView, jointsView, and animation behavior.
+Viewer-only APIs such as cutPlane, explodeView, render labels, comparison references, and runtime display behavior.
 
 - `{{SKILL_DIR}}/docs/generated/viewport.md`
 

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

@@ -28,7 +28,32 @@ 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`.
+Top-level lexical declarations such as `const bom = ...`, `let slot = ...`, `const lib = ...`, `const joint = ...`, or `class Shape {}` collide with the injected runtime names. This is checked when the script runs, so agents should treat these names as reserved before executing the model.
+
+Use project-specific local names instead:
+
+```javascript
+// BAD — `lib` and `slot` are injected runtime names.
+const lib = require("./wheel-lib.js");
+const slot = rect(20, 5);
+
+// GOOD — local names describe the project role.
+const wheelLib = require("./wheel-lib.js");
+const axleSlotSketch = rect(20, 5);
+```
+
+If a helper module exports a name that matches a ForgeCAD runtime name, keep the module under one local object name or rename during destructuring:
+
+```javascript
+// GOOD — no top-level `slot` declaration.
+const wheelHelpers = require("./wheel-helpers.js");
+const axleSlot = wheelHelpers.slot(...);
+
+// GOOD — imported helper is renamed.
+const { slot: makeAxleSlot } = require("./wheel-helpers.js");
+```
+
+The complete collision-reserved list is generated from the runtime source in [Runtime Names](../../generated/runtime-names.md). Check that list before using natural local names such as `lib`, `slot`, `joint`, `group`, `path`, `text2d`, `scene`, or `Shape`.
 
 ## Execution Model
 
@@ -67,6 +92,44 @@ return {
 };
 ```
 
+### Forge-Aware Builder Modules
+
+A `.forge.js` file can also return builder functions. Those functions keep access to
+the ForgeCAD runtime names from their defining file, so this is the supported way
+to share sketch, profile, shape, or assembly builders that need APIs such as
+`path()`, `circle2d()`, `box()`, or `assembly()`.
+
+This pattern works well when a file should be both directly inspectable and
+importable: render the flat profiles or part preview when the file is opened on
+its own, and export builders under a named object for the assembly file.
+
+```javascript
+// profiles.forge.js - inspectable on its own, reusable through require()
+function wheelProfile() {
+  return circle2d(40).subtract(circle2d(18));
+}
+
+return {
+  preview: [{ name: 'Wheel profile', sketch: wheelProfile() }],
+  make: { wheelProfile },
+};
+```
+
+```javascript
+// main.forge.js - reuses the exact inspected profile
+const profiles = require('./profiles.forge.js');
+const wheel = profiles.make.wheelProfile().extrude(8);
+return wheel;
+```
+
+Keep builder modules pure over top-level constants, top-level `param()` values,
+or explicit function arguments. Do not declare new `param()` values inside an
+exported builder if callers need `require('./profiles.forge.js', { Width: 80 })`
+overrides: import overrides are validated while the module loads, before any
+exported builder is called. For plain constants, tables, math helpers, and
+formatting code that does not construct ForgeCAD geometry, use `.js` helper
+modules instead.
+
 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

package/dist-skill/docs/CLI.md

@@ -48,6 +48,8 @@ ForgeCAD includes a local editor. Open it around a dedicated project folder, edi
 
 `forgecad studio <project-path>` is the normal installed-CLI command for users. `forgecad dev <project-path>` starts the Vite dev server and is mainly for ForgeCAD source development.
 
+Keep one long-running `forgecad studio <project-path> [project-path ...]` process open with every active project folder listed in its arguments; the user opens the single printed localhost port once, and AI agents should only create or edit files under those folders so the browser updates live without starting more servers.
+
 <details>
 <summary>Common flags for studio / dev</summary>
 
@@ -162,11 +164,12 @@ Inspect a model by asking for one explicit kind of evidence.
 
 `forgecad inspect` is the evidence-first inspection surface. Pick the job you want to verify, then choose the view like you would with `render 3d`.
 
+- `inspect sketch` — returned sketch/profile regions, selector dry-runs, and extrusion compatibility
 - `inspect history` — final-object feature recipes and feedback anchors
 - `inspect design-trace` — raw construction DAG, source spans, and cache diagnostics
 - `inspect section` — agent-native one-off section probe with optional ray rulers and replay JSON
 - `inspect replay` — rerun a saved section probe on the same or another source
-- `inspect visual image|cutaway|depth|normals|objects` — visual context, clipped 3D cutaways, depth, normals, and identity evidence
+- `inspect visual image|cutaway|depth|normals|rig|objects` — visual context, clipped 3D cutaways, depth, normals, rig skeletons, and identity evidence
 - `inspect surface zebra|roughness` — surface continuity and roughness evidence
 - `inspect physical components|floating|gaps` — physical component graph evidence
 - `inspect fit interference` — positive-volume overlap evidence
@@ -189,8 +192,27 @@ forgecad inspect sections stack main.forge.js --plane yz --every 1
 forgecad inspect compare overlay candidate.forge.js --with reference.3mf
 ```
 
+### `forgecad inspect sketch`
+
+Inspect returned sketches and profile regions used by returned shapes.
+
+Runs a model and reports inspectable 2D sketch/profile regions without requiring model code to register inspection hooks. The command inspects returned Sketch objects and profile-bearing shape compile plans such as extrude, cut, and revolve. Use `--seed x,y` to dry-run which region a point selector would consume, and `--operation extrude` to check extrusion compatibility.
+
+```bash
+forgecad inspect sketch examples/api/sketch-regions.forge.js
+forgecad inspect sketch model.forge.js --object "Profile" --seed 45,15
+forgecad inspect sketch model.forge.js --json --object "Body" --seed 45,15 --operation extrude
+```
+
+`inspect sketch` is external inspection: it runs the script, then reads returned scene objects and shape compile plans. Model code should not call an inspection API. It reports selectable 2D `regions` from returned `Sketch` / `ConstraintSketch` objects and from profile-bearing returned shapes (`extrude.profile`, `cut.profile`, `revolve.profile`).
+
+JSON contract: `targets[]` are inspectable sketches/profile uses; `regions[]` are filled selectable areas sorted largest-first with run-local ids like `R0`; `holes[]` are excluded interiors; `selection` is present only with `--seed`; `profileTree` is compile-plan provenance, not JavaScript variable names. Stable selection v1 is `--seed x,y`, not region id.
+
+Seed failures are explicit and exit nonzero when no target matches: outside every region, on a boundary, inside a hole, ambiguous, no regions, or incompatible operation. `--operation extrude` only checks whether the selected filled region can be consumed by extrusion; open path/rail selection is intentionally unsupported in v1.
+
 | Command | Description |
 |---------|-------------|
+| `inspect sketch` | Inspect returned sketches and profile regions used by returned shapes. |
 | `inspect visual image` | Capture standard shaded viewport evidence. |
 | `inspect visual objects` | Capture object identity evidence. |
 | `inspect section` | Run one exact section probe with optional ray rulers. |
@@ -229,7 +251,7 @@ forgecad render hq examples/products/cup.forge.js --preset dramatic
 
 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.
+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. Each render uses a private renderer server by default, so parallel renders do not compete for the same Vite port.
 
 The input can be a `.forge.js` script or a direct `.stl`, `.obj`, `.3mf`, `.step`, or `.stp` asset. Direct STEP/STP rendering auto-selects OCCT unless you pass `--backend`.
 
@@ -299,9 +321,9 @@ forgecad render hq examples/products/cup.forge.js --transparent --preset glass
 
 ### `forgecad capture gif|mp4` **\[Pro\]**
 
-Animated orbit or joint playback.
+Animated orbit, section sweep, or named 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. Use `--view`, `--camera`, `--camera-json`, or `--scene <file>` to choose the orbit base camera or the fixed camera for animations and section sweeps.
+Renders an animated sequence by either orbiting the camera around the model or playing back a named joint animation. Use `--capture orbit` (default) for a turntable rotation, `--capture animation --animation <name>` to play a named joint 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/products/cup.forge.js
@@ -311,7 +333,7 @@ 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/products/cup.forge.js
-forgecad capture mp4 examples/api/runtime-joints-view.forge.js out/step.mp4 --capture animation --animation Step
+forgecad capture mp4 examples/api/assembly-kinematics-four-bar.forge.js out/four-bar.mp4 --view iso
 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
@@ -346,6 +368,7 @@ forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edge
 |--------|-------------|
 | `--param <Key=Value>` | Override a parameter value (Key=Value). Repeatable. |
 | `-p <Key=Value>` | Shorthand for --param |
+| `--joint <JointName=Value>` | Override a Motion tab joint value (JointName=Value). Repeatable. |
 | `--focus <names>` | Focus: no arg hides mocks; comma-separated names/globs show only those |
 | `--hide <names>` | Hide comma-separated object names/globs |
 | `--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. |
@@ -356,9 +379,9 @@ forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edge
 | `--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: off) |
-| `--render-style <classic\|studio\|fast\|glass\|inspection\|precision\|hybrid\|scan>` | Visual render style (render default: classic; inspect default: inspection) |
+| `--render-style <classic\|studio\|fast\|glass\|inspection\|contour\|scan>` | Visual render style (render default: classic; inspect default: inspection) |
 | `--scan-granularity <12-144>` | Scan cells across the scene longest axis |
-| `--port <n>` | Vite dev server port |
+| `--port <n>` | Renderer 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 |
@@ -379,7 +402,7 @@ forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edge
 | `--pitch <deg>` | Camera pitch angle in degrees |
 | `--format <gif\|mp4>` | Output format |
 | `--capture <orbit\|animation\|section-sweep>` | Capture preset |
-| `--animation <name>` | Named jointsView animation clip |
+| `--animation <name>` | Named joint animation clip |
 | `--animation-loops <n>` | Repeat the selected animation clip |
 | `--cut-plane <name>` | Enable a named cut plane |
 | `--sweep-plane <XY\|XZ\|YZ>` | Moving plane for section-sweep |
@@ -448,9 +471,10 @@ forgecad export sdf rover.forge.js --output out/forge_scout
 
 | Option | Description |
 |--------|-------------|
+| `--joint <JointName=Value>` | Override a Motion tab joint value (JointName=Value). Repeatable. |
 | `--output <path>` | Output STEP path |
+| `--backend <occt\|truck>` | Exact BREP exporter: occt (default) or truck (native analytic kernel) |
 | `--quality <default\|live\|high>` | Forge quality preset |
-| `--backend <manifold\|occt\|truck>` | Geometry backend (default: manifold) |
 | `-o <path>` | Shorthand for --output |
 | `--dim-angle-tol <deg>` | Dimension routing tolerance in degrees |
 | `--format <pdf\|dxf>` | Output format |
@@ -484,7 +508,7 @@ cd start-here
 forgecad studio .
 ```
 
-`forgecad login` asks how you want to sign in, then prompts for either email/password or an API token. If your account was created through GitHub or Google, create an API token in Settings > API Tokens, run `forgecad login`, and choose API token. Use `FORGECAD_TOKEN=fc_pat_...` only for CI/CD and one-off automation. See [Platform authentication](platform/auth.md#cli-auth-for-oauth-accounts) for details.
+`forgecad login` asks how you want to sign in, then prompts for either email/password or an API token. If your account was created through GitHub or Google, create an API token in Settings > API Tokens, run `forgecad login`, and choose API token. Use `FORGECAD_TOKEN=fc_pat_...` only for CI/CD and one-off automation.
 
 `forgecad project init` creates the remote project, writes `forgecad.json`, pushes any existing local source files, and records server file IDs. `forgecad project push` syncs an already initialized project; it does not create a remote project from an arbitrary folder.