forgecad 0.7.0 → 0.8.0

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

@@ -1,52 +0,0 @@
----
-skill-group: cli
-skill-order: 4
----
-
-# ForgeCAD CLI: Studio & Publishing
-
-## Studio & Dev Server
-
-```bash
-forgecad dev [path] [--blank] [--port n] [--host] [--open]    # Vite dev server
-forgecad studio [path] [--blank] [--port n]                   # Production static server
-forgecad web [--open]                                         # Web/embeddable mode
-```
-
-`forgecad open` is an alias for `forgecad studio`.
-
-## New File from Template
-
-```bash
-forgecad new mypart                     # Part template (default)
-forgecad new bracket --template sketch  # Constrained sketch template
-forgecad new robot --template assembly  # Multi-part assembly template
-```
-
-## Publishing & Sharing
-
-```bash
-forgecad publish model.forge.js --title "My Model"   # Publish; get shareable URL
-forgecad publish model.forge.js --no-sync             # Publish without auto-pushing
-forgecad shares list                                  # List all published models
-forgecad shares delete <share-id> [--force]
-forgecad link <gist-url-or-id>                        # Share link from GitHub Gist
-```
-
-Published at `forgecad.io/m/<shareId>`. Shares are live references — always reflect current version, not a snapshot. Requires a project directory (`forgecad.json`).
-
-## Adding New CLI Commands
-
-1. Create/extend a module under `cli/`
-2. Import from `../src/forge/headless`; call `await init()` then `runScript(code, fileName, allFiles)`
-3. Register in `cli/forgecad.ts`
-
-Pass all project files (keyed by project-relative path) to `runScript` when using `require()` / `importSvgSketch()`. Use `require("./file.forge.js", { Param: value })` for model files; `importSvgSketch()` for SVG assets.
-
-## Local Branch Cleanup
-
-```bash
-uv run cli/forge-prune-local-branches.py [--dry-run] [--base mainline]
-```
-
-Finds merged local branches with no matching remote, prompts before deleting. Removes linked worktrees first when a branch is checked out there.

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

@@ -1,66 +0,0 @@
----
-skill-group: cli
-skill-order: 2
----
-
-# ForgeCAD CLI: Validation & Debugging
-
-## Script Validation
-
-```bash
-forgecad run examples/cup.forge.js
-forgecad run examples/cup.forge.js --debug-imports
-forgecad run examples/cup.forge.js --param "Wall Thickness=3"
-forgecad run examples/cup.forge.js --param "Show Lid=0"
-forgecad run examples/cup.forge.js --param "Pan Style=wok"
-forgecad run examples/constraints/06-complex-spectrogram.forge.js --solver-debug-out tmp/spectrogram-debug
-```
-
-`--param "Key=Value"` overrides: numeric, boolean (`1`/`0`), or string (displayed label) params.
-
-`--debug-imports` prints source file, target file, overrides, return type, and success/error phase.
-
-`--solver-debug-out <dir>` writes a per-sketch constructive transcript + SVG snapshots bundle.
-
-## Parameter Validation
-
-```bash
-forgecad check params examples/shoe-rack-doors.forge.js [--samples 10]
-```
-
-Samples each parameter across its range; checks runtime errors, degenerate geometry (volume~0), and new collisions. `--samples N` (default 8).
-
-## Check Commands
-
-```bash
-forgecad check transforms           # Math-level transform/frame composition invariants
-forgecad check compiler [--case <name>] [--update]    # Compiler regression snapshots
-forgecad check query-propagation [--update]           # Topology-rewrite propagation snapshots
-forgecad check examples [--family <f>] [--example <path>]  # Checked example manifest
-forgecad check suite                # Full invariant suite (CI / release gate)
-forgecad check suite --profile local  # Faster local invariant suite
-forgecad check dimensions           # Shape dimension propagation invariants
-```
-
-## Invariant Test Suite
-
-```bash
-npm test                        # Faster local invariant suite
-npm run test:full              # Full invariant suite
-npm run test:examples           # Example architecture gate
-npm run test:compiler           # Compiler snapshot suite
-npm run test:compiler:update    # Refresh compiler snapshots after intentional change
-npm run test:query-propagation
-npm run test:query-propagation:update
-```
-
-## Debug Commands
-
-```bash
-forgecad debug dimensions /path/to/file.forge.js [--all] [--dim-angle-tol 12]
-forgecad debug compiler /path/to/file.forge.js [--compact]
-```
-
-`debug dimensions` prints total/per-view dimension counts, ownership routing, and coordinate list.
-
-`debug compiler` prints JSON with compile plans, CadQuery/OCCT lowering diagnostics, faceted fallback eligibility, and runtime/compiler Manifold summaries.

package/dist-skill/docs-dev/API/core/sdf-advanced.md

@@ -1,92 +0,0 @@
----
-skill-group: dev-sdf
-skill-order: 2
----
-
-# SDF Advanced Operations
-
-## TPMS Lattices
-
-```javascript
-sdf.gyroid({ cellSize, thickness })    // most common for 3D printing
-sdf.schwarzP({ cellSize, thickness })  // isotropic pores
-sdf.diamond({ cellSize, thickness })   // stiffest structure
-```
-
-TPMS fills all space — **always clip with an intersect before `.toShape()`**:
-
-```javascript
-const lattice = sdf.gyroid({ cellSize: 8, thickness: 1.2 })
-  .intersect(sdf.sphere(25))
-  .toShape();
-```
-
-`cellSize`: larger = coarser. `thickness`: thicker = denser.
-
-## Domain Operations
-
-### Twist
-Rotates slices around Y axis as function of Y position.
-```javascript
-sdf.cylinder(50, 8).twist(0.9).toShape()  // 45° total over 50mm (0.9 deg/mm)
-```
-
-### Bend
-Bends around Z axis. Smaller radius = tighter arc.
-```javascript
-sdf.cylinder(60, 5).bend(20).toShape()  // arch shape
-```
-
-### Repeat
-Tiles in space. Spacing `0` = no repeat on that axis. Count `0` = infinite.
-```javascript
-sdf.sphere(4).repeat([15, 15, 0], [3, 3, 0]).toShape()  // 3×3 grid
-```
-
-### Shell
-Hollows to surface shell of given thickness.
-```javascript
-sdf.sphere(20).shell(2).subtract(sdf.box(60, 60, 30).translate(0, 0, -15)).toShape()
-```
-
-### Displace
-Offsets surface by a function of position.
-```javascript
-sdf.sphere(15).displace((x, y, z) => Math.sin(x * 0.8) * Math.sin(y * 0.8) * Math.sin(z * 0.8) * 2).toShape()
-```
-
-**Critical gotcha for `displace()` and `fromFunction()`:** The function is serialized as a string and re-evaluated via `new Function("x","y","z", "return ...")`. This means:
-- **No closure variables** — cannot reference `param()` values inside
-- **Single expression only** — no `const`, `let`, `if`, `for`
-- Multi-statement blocks **silently produce bad geometry**
-
-### Onion
-Concentric shells.
-```javascript
-sdf.sphere(20).onion(3, 2).toShape()  // 3 shells, 2mm apart
-```
-
-## Morphing
-
-Interpolate between two shapes. `t=0` = a, `t=1` = b.
-```javascript
-sdf.morph(sdf.sphere(12), sdf.box(20, 20, 20), 0.5).toShape()
-a.morph(b, t)  // method form
-```
-
-## Custom SDF Functions
-
-```javascript
-sdf.fromFunction(fn, { min: [x0, y0, z0], max: [x1, y1, z1] })
-```
-
-`fn(x, y, z)` returns signed distance: negative = inside, positive = outside, zero = surface. Bounds are required — provide tightly to avoid wasted computation.
-
-```javascript
-const heart = sdf.fromFunction(
-  (x, y, z) => (x*x + z*z*1.1 + y*y - 1)**3 - x*x*y*y*y - z*z*y*y*y * 0.11,
-  { min: [-20, -25, -15], max: [20, 20, 15] }
-).toShape();
-```
-
-Same serialization gotcha as `displace()` — no closure variables, single expression only.

package/dist-skill/docs-dev/API/core/sdf-primitives.md

@@ -1,58 +0,0 @@
----
-skill-group: dev-sdf
-skill-order: 1
----
-
-# SDF Primitives & Booleans
-
-> **Experimental.** Slower render times than B-rep; lower mesh quality from marching-tetrahedra extraction. Use for organic forms, TPMS lattices, smooth blending. For mechanical parts, prefer B-rep.
-
-SDF operations are accessed via the globally available `sdf` namespace. All shapes live as a lazy expression tree until `.toShape()` is called.
-
-## Primitives
-
-All centered at origin unless noted.
-
-```javascript
-sdf.sphere(radius)
-sdf.box(x, y, z)                    // full dimensions — box(20,20,20) → 20mm cube
-sdf.cylinder(height, radius)        // axis along Y (rotate 90,0,0 for Z-axis)
-sdf.torus(majorRadius, minorRadius) // ring in XZ plane (hole axis = Y)
-sdf.capsule(height, radius)         // axis along Y
-sdf.cone(height, radius)            // base at y=0, tip at y=height (not centered)
-```
-
-## Boolean Operations
-
-```javascript
-// Sharp
-a.union(b, c, d); a.subtract(b); a.intersect(b)
-
-// Smooth — blend over transition radius
-sdf.smoothUnion(a, b, { radius: 5 })       // factory: radius in options object
-sdf.smoothDifference(a, b, { radius: 5 })
-sdf.smoothIntersection(a, b, { radius: 5 })
-
-a.smoothUnion(b, 5)      // method: radius as direct number
-a.smoothSubtract(b, 5)   // note: smoothSubtract, not smoothDifference
-a.smoothIntersect(b, 5)
-```
-
-**API mismatch:** Factory functions take `{ radius }` (object). Instance methods take `radius` (number). Don't mix them.
-
-## Transforms
-
-```javascript
-shape.translate(x, y, z)
-shape.rotateX(deg)               // also rotateY, rotateZ, rotate(axis, deg)
-shape.scale(factor)              // uniform only
-```
-
-## Reserved Names
-
-The global scope defines `sphere`, `box`, `cylinder`, `torus`, `capsule`, `cone`, `shell` as B-rep primitives. Always use `sdf.*` prefix — and avoid naming local variables after these globals:
-
-```javascript
-const orb = sdf.sphere(10);       // correct — not 'sphere'
-const s = sdf.sphere(10);         // bad — shadows global 'sphere' if named 'sphere'
-```

package/dist-skill/docs-dev/API/core/sdf-workflow.md

@@ -1,42 +0,0 @@
----
-skill-group: dev-sdf
-skill-order: 3
----
-
-# SDF Workflow & Mesh Quality
-
-## Converting to Shape
-
-```javascript
-shape.toShape()
-shape.toShape({ edgeLength: 0.5 })                        // finer mesh
-shape.toShape({ bounds: { min: [...], max: [...] } })     // override auto bounds
-```
-
-| Option | Default | Effect |
-|--------|---------|--------|
-| `edgeLength` | `maxDim / 100` | Smaller = smoother, slower |
-| `bounds` | auto-estimated | Override sampling volume |
-
-For smooth shapes use `0.3–0.5`. For fast previews use `1–2`.
-
-After meshing, Laplacian smoothing + SDF projection runs automatically (2 iterations) to reduce axis-aligned triangle artifacts.
-
-## Workflow Tips
-
-- **Start coarse, refine last** — design at `edgeLength: 2`, drop to `0.5` for output
-- **Clip TPMS before `toShape()`** — intersect with bounding shape first
-- **Compose before meshing** — do all booleans/deformations in SDF space, then call `.toShape()` once
-- **Mix with B-rep freely** — after `.toShape()`, use in `difference()`, `union()`, `.fillet()`, etc.
-
-```javascript
-const organicBase = sdf.smoothUnion(sdf.sphere(20), sdf.box(30, 30, 10), { radius: 8 }).toShape();
-return difference(organicBase, cylinder(15, 3));  // B-rep cut on SDF result
-```
-
-## Serialization Gotcha
-
-`displace()` and `fromFunction()` serialize the function body via `new Function("x","y","z", "return ...")`:
-- **No closure variables** — cannot reference `param()` values
-- **Single expression only** — no `const`, `let`, `if`, `for`
-- Multi-statement blocks silently produce bad geometry

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

@@ -1,91 +0,0 @@
----
-skill-group: cli
-skill-order: 3
----
-
-# ForgeCAD CLI: Export Commands
-
-## SVG Export
-
-```bash
-forgecad export svg examples/constraints/01-fully-constrained-rect.forge.js [output.svg]
-```
-
-Pure Node — no browser needed. Runs the sketch script through the forge engine and converts polygons to SVG paths.
-
-## STEP / BREP Export (exact subset, CadQuery)
-
-```bash
-forgecad export step examples/api/brep-exportable.forge.js [--output out/demo.step] [--python 3.11] [--uv /path/to/uv]
-forgecad export brep examples/api/brep-exportable.forge.js
-forgecad export step examples/chess-set.forge.js --allow-faceted
-```
-
-`uv`-first: provisions CadQuery automatically. Exact-subset only by default — fails with a reason rather than silently exporting degraded geometry. With `--allow-faceted`, unsupported mesh solids export as faceted OCCT solids (tessellation-driven, not exact replay).
-
-The maintained feature matrix: `docs/permanent/API/output/brep-export.md`.
-
-## G-code Toolpath Export
-
-```bash
-forgecad export gcode examples/gcode/parametric-vase.forge.js [--output out/vase.gcode]
-```
-
-The script must return a `GCodeBuilder` (from the `gcode()` factory). This is a toolpath scripting API, not a slicer — you define print movements in code. See `docs/permanent/API/output/gcode.md` for the full API.
-
-## SDF Robot Export (Gazebo)
-
-```bash
-forgecad export sdf examples/api/sdf-rover-demo.forge.js [--output out/forge_scout]
-```
-
-Writes a Gazebo-friendly package: `model.sdf`, `model.config`, `meshes/*.stl`, optional world file. Script must call `robotExport({...})` with an `assembly(...)` graph.
-
-Launch flow (macOS — use split `-s`/`-g`):
-```bash
-export GZ_SIM_RESOURCE_PATH="$PWD/out/forge_scout/models${GZ_SIM_RESOURCE_PATH:+:$GZ_SIM_RESOURCE_PATH}"
-gz sim -s -r out/forge_scout/worlds/forge_scout_trial.sdf
-gz sim -g out/forge_scout/worlds/forge_scout_trial.sdf
-```
-
-## URDF Export
-
-```bash
-forgecad export urdf examples/api/sdf-rover-demo.forge.js
-```
-
-## PNG Render (requires Chrome/Puppeteer)
-
-```bash
-forgecad render examples/cup.forge.js [output.png]
-forgecad render examples/cup.forge.js out/scene.png --scene '<json from viewport>'
-```
-
-Options: `--angles <front,side,top,iso>`, `--size <px>`, `--port <n>`, `--camera <spec>`, `--scene <json>`, `--background <color>`, `--chrome-path <path>`.
-
-## Animated Capture (GIF or MP4, requires Chrome)
-
-```bash
-forgecad capture gif examples/cup.forge.js [output.gif]
-forgecad capture mp4 examples/cup.forge.js [output.mp4]
-forgecad capture mp4 examples/api/runtime-joints-view.forge.js out/step.mp4 --capture animation --animation Step
-forgecad capture gif examples/3d-printer.forge.js out/section.gif --cut-plane "Front Section"
-```
-
-`--list` prints available animation clips and cut planes. Uses `ffmpeg` when available (better GIF colors, H.264 MP4); falls back to pure-JS GIF encoder.
-
-Key options: `--capture <orbit|animation>`, `--animation <name>`, `--cut-plane <name>`, `--camera <spec>`, `--scene <json>`, `--size <px>`, `--fps <n>`, `--frames-per-turn <n>`, `--quality <default|live|high>`.
-
-Use `Copy CLI --scene` from the View Panel to grab the current viewport framing and paste into `render` or `capture`.
-
-## PDF Report
-
-```bash
-forgecad export report examples/cup.forge.js [output.pdf] [--dim-angle-tol 18]
-```
-
-Generates a searchable PDF with BOM page, combined model page, and per-component pages. Dimensions included per view when their axis aligns with that view's projection plane (within `--dim-angle-tol` degrees, default 12).
-
-## STL Export
-
-Available in the browser UI via the Export panel (binary STL).

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

@@ -1,107 +0,0 @@
----
-skill-group: cli
-skill-order: 1
----
-
-# ForgeCAD CLI: Projects & Setup
-
-## Install
-
-```bash
-npm install -g forgecad
-# Developers working on ForgeCAD itself:
-npm install && npm link
-```
-
-## When to use what
-
-| Context | Use |
-|---------|-----|
-| Using ForgeCAD as a tool | `forgecad *` commands |
-| Developing ForgeCAD itself | `npm run dev` / `npm run build` |
-| CI / publishing | `npm run build && npm run test:full` |
-
-## Dev vs production server
-
-```bash
-forgecad dev [path]        # Vite dev server, live reload
-forgecad studio [path]     # Static server for production build (requires dist/)
-```
-
-Both accept `--blank`, `--port <n>`, `--host`, `--open`, `--strict-port`.
-
-## Licensing
-
-```bash
-forgecad license                    # Show license status
-forgecad license activate <key>     # Activate a Pro license key
-forgecad license deactivate         # Remove license
-```
-
-| Tier | Included |
-|------|----------|
-| Free | dev, studio, run, render, export stl/3mf/svg, all checks, debug |
-| Pro  | export step/brep, render-hq, capture gif/mp4, gcode, report, cutting-layout, sdf, urdf, sketch-pdf |
-
-## Authentication
-
-```bash
-forgecad login                          # Interactive login
-forgecad login --server http://localhost:5174
-forgecad logout
-forgecad whoami                         # Show user, server, and license status
-```
-
-Credentials stored in `~/.forgecad/auth.json`.
-
-## Project Management
-
-```bash
-forgecad project init "My Project"      # Create on server + link current directory
-forgecad project clone my-project       # Download into ./my-project/
-forgecad project push [--force]         # Upload local changes
-forgecad project pull [--force]         # Download remote changes
-forgecad project status                 # Show local vs remote diff
-forgecad project list
-forgecad project info
-forgecad project rename "New Name"
-forgecad project set-visibility public  # private|shared|public
-forgecad project delete [--force]
-forgecad project open
-```
-
-Projects are linked to remote via `forgecad.json`.
-
-## File Management (Remote)
-
-```bash
-forgecad file list [path]
-forgecad file read <path>
-forgecad file save <path>               # Upload local file
-forgecad file save <path> --content "code here"
-cat model.forge.js | forgecad file save model.forge.js --stdin
-forgecad file delete <path> [--force]
-forgecad file rename <old> <new>
-forgecad file mkdir <path>
-forgecad file copy <source-slug> <path> [--dest <dest-path>]
-```
-
-Requires the current directory to have `forgecad.json`.
-
-## Member Management
-
-```bash
-forgecad project members
-forgecad project add-member alice@example.com          # editor by default
-forgecad project add-member bob@example.com --role viewer
-forgecad project remove-member alice@example.com
-forgecad project set-role bob@example.com editor
-```
-
-Roles: **owner** (full control), **editor** (read/write), **viewer** (read-only).
-
-## Shell Autocomplete
-
-```bash
-forgecad completion bash   # or zsh / fish
-```

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

@@ -1,52 +0,0 @@
----
-skill-group: cli
-skill-order: 4
----
-
-# ForgeCAD CLI: Studio & Publishing
-
-## Studio & Dev Server
-
-```bash
-forgecad dev [path] [--blank] [--port n] [--host] [--open]    # Vite dev server
-forgecad studio [path] [--blank] [--port n]                   # Production static server
-forgecad web [--open]                                         # Web/embeddable mode
-```
-
-`forgecad open` is an alias for `forgecad studio`.
-
-## New File from Template
-
-```bash
-forgecad new mypart                     # Part template (default)
-forgecad new bracket --template sketch  # Constrained sketch template
-forgecad new robot --template assembly  # Multi-part assembly template
-```
-
-## Publishing & Sharing
-
-```bash
-forgecad publish model.forge.js --title "My Model"   # Publish; get shareable URL
-forgecad publish model.forge.js --no-sync             # Publish without auto-pushing
-forgecad shares list                                  # List all published models
-forgecad shares delete <share-id> [--force]
-forgecad link <gist-url-or-id>                        # Share link from GitHub Gist
-```
-
-Published at `forgecad.io/m/<shareId>`. Shares are live references — always reflect current version, not a snapshot. Requires a project directory (`forgecad.json`).
-
-## Adding New CLI Commands
-
-1. Create/extend a module under `cli/`
-2. Import from `../src/forge/headless`; call `await init()` then `runScript(code, fileName, allFiles)`
-3. Register in `cli/forgecad.ts`
-
-Pass all project files (keyed by project-relative path) to `runScript` when using `require()` / `importSvgSketch()`. Use `require("./file.forge.js", { Param: value })` for model files; `importSvgSketch()` for SVG assets.
-
-## Local Branch Cleanup
-
-```bash
-uv run cli/forge-prune-local-branches.py [--dry-run] [--base mainline]
-```
-
-Finds merged local branches with no matching remote, prompts before deleting. Removes linked worktrees first when a branch is checked out there.

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

@@ -1,66 +0,0 @@
----
-skill-group: cli
-skill-order: 2
----
-
-# ForgeCAD CLI: Validation & Debugging
-
-## Script Validation
-
-```bash
-forgecad run examples/cup.forge.js
-forgecad run examples/cup.forge.js --debug-imports
-forgecad run examples/cup.forge.js --param "Wall Thickness=3"
-forgecad run examples/cup.forge.js --param "Show Lid=0"
-forgecad run examples/cup.forge.js --param "Pan Style=wok"
-forgecad run examples/constraints/06-complex-spectrogram.forge.js --solver-debug-out tmp/spectrogram-debug
-```
-
-`--param "Key=Value"` overrides: numeric, boolean (`1`/`0`), or string (displayed label) params.
-
-`--debug-imports` prints source file, target file, overrides, return type, and success/error phase.
-
-`--solver-debug-out <dir>` writes a per-sketch constructive transcript + SVG snapshots bundle.
-
-## Parameter Validation
-
-```bash
-forgecad check params examples/shoe-rack-doors.forge.js [--samples 10]
-```
-
-Samples each parameter across its range; checks runtime errors, degenerate geometry (volume~0), and new collisions. `--samples N` (default 8).
-
-## Check Commands
-
-```bash
-forgecad check transforms           # Math-level transform/frame composition invariants
-forgecad check compiler [--case <name>] [--update]    # Compiler regression snapshots
-forgecad check query-propagation [--update]           # Topology-rewrite propagation snapshots
-forgecad check examples [--family <f>] [--example <path>]  # Checked example manifest
-forgecad check suite                # Full invariant suite (CI / release gate)
-forgecad check suite --profile local  # Faster local invariant suite
-forgecad check dimensions           # Shape dimension propagation invariants
-```
-
-## Invariant Test Suite
-
-```bash
-npm test                        # Faster local invariant suite
-npm run test:full              # Full invariant suite
-npm run test:examples           # Example architecture gate
-npm run test:compiler           # Compiler snapshot suite
-npm run test:compiler:update    # Refresh compiler snapshots after intentional change
-npm run test:query-propagation
-npm run test:query-propagation:update
-```
-
-## Debug Commands
-
-```bash
-forgecad debug dimensions /path/to/file.forge.js [--all] [--dim-angle-tol 12]
-forgecad debug compiler /path/to/file.forge.js [--compact]
-```
-
-`debug dimensions` prints total/per-view dimension counts, ownership routing, and coordinate list.
-
-`debug compiler` prints JSON with compile plans, CadQuery/OCCT lowering diagnostics, faceted fallback eligibility, and runtime/compiler Manifold summaries.