forgecad 0.6.3 → 0.7.0

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

@@ -1,205 +0,0 @@
----
-skill-group: core
-skill-order: 0
-skill-tiers: [one-file]
----
-
-# ForgeCAD Skill Guide — Concepts & Patterns
-
-Conceptual knowledge that complements the auto-generated API index. The API index covers every function signature; this file covers the patterns, gotchas, and composition strategies that signatures alone cannot convey.
-
-## Core Concepts
-
-ForgeCAD scripts are JavaScript code that returns geometry. The forge API is globally available — no imports needed.
-
-### Basic Structure
-```javascript
-const width = param("Width", 50, { min: 20, max: 100, unit: "mm" });
-const shape = box(width, 30, 10);
-return shape;
-```
-
-### Execution Model
-- Scripts execute on every parameter change (400ms debounce)
-- All operations are **immutable** — they return new shapes, never modify in place
-- Must return one of:
-  - A `Shape` (3D solid)
-  - A `Sketch` (2D profile — rendered flat on XY plane)
-  - A `TrackedShape` (3D solid with named faces/edges — auto-unwrapped)
-  - A `ShapeGroup` (multiple shapes/sketches grouped for joint transforms)
-  - An `Array` of shapes/sketches/groups (multi-object scene)
-  - An `Array` of `{ name, shape?, sketch?, color? }` objects (named multi-object scene)
-
-### Unions Remove Colors
-
-`union()` merges into a single solid — individual colors are lost. Return an array of named objects instead:
-
-```javascript
-// BAD: colors lost after union
-return union(red, blue);
-
-// GOOD: each object keeps its color
-return [
-  { name: "Red Box", shape: red, color: '#ff0000' },
-  { name: "Blue Box", shape: blue, color: '#0066ff' },
-];
-```
-
-### Coordinate System
-Z-up right-handed: X = left/right, Y = forward/back, Z = up/down.
-
-## Returning Multiple Objects
-
-```javascript
-return [
-  { name: "Base", shape: box(100, 100, 5), color: "#888888" },
-  { name: "Column", shape: cylinder(50, 10).translate(50, 50, 5), color: "#4488cc" },
-];
-```
-
-Each object must have `name` (string) and `shape` or `sketch`. Optional `color` sets display color.
-
-## Positioning & Connectors
-
-### Connectors + `.matchTo()` — Primary positioning method
-
-Define named connectors on parts, then use `matchTo()` for automatic alignment. Connectors are stable (don't shift with geometry changes), semantic (typed and gendered), and oriented (full coordinate frame).
-
-```javascript
-const bracket = box(40, 10, 60, true).withConnectors({
-  mount: connector.male("bolt", { origin: [0, -5, 0], axis: [0, -1, 0] }),
-});
-const wall = box(200, 5, 200, true).withConnectors({
-  slot: connector.female("bolt", { origin: [50, 2.5, 30], axis: [0, 1, 0] }),
-});
-const placed = bracket.matchTo(wall, "mount", "slot");
-```
-
-Query connector distances to derive dimensions:
-```javascript
-const pipeLen = frame.connectorDistance('inlet', 'outlet');
-```
-
-### `.attachTo()` — Quick bounding-box positioning
-
-For simple stacking where connectors aren't needed. Uses bounding-box anchors — fast but fragile.
-
-```javascript
-const column = cylinder(50, 8).attachTo(base, 'top', 'bottom');
-```
-
-### `.onFace(parent, face, opts?)`
-
-Place a shape on a specific face of a parent. Face-local coordinates: `u`/`v` offset from center, `protrude` outward.
-
-```javascript
-const vent = box(80, 2, 12, true)
-  .onFace(body, 'front', { v: -15, protrude: 2 });
-```
-
-**When to use:** `onFace()` for surface details (vents, displays). Connectors for assembly interfaces. `attachTo()` for quick prototyping.
-
-## Multi-File Projects
-
-### File Types
-- `.forge.js` — parametric part/assembly script
-- `.forge-notebook.json` — multi-cell notebook
-- `.svg` — vector artwork, imported as sketch geometry
-
-### Import Function
-
-Use `require(path, paramOverrides?)` to import any `.forge.js` file. The second argument is optional param overrides.
-
-```javascript
-const bracket = require("./bracket.forge.js");
-const bracket2 = require("./bracket.forge.js", { Width: 100, Thickness: 3 });
-```
-
-The return value matches what the imported file exports:
-- File `return`s a `Shape` → you get a `Shape`
-- File `return`s an `Assembly` → you get an `ImportedAssembly`
-- File `return`s a `ShapeGroup` → you get a `ShapeGroup`
-- File uses `exports.name = value` → you get an object with named properties
-
-Use `importSvgSketch()` for SVG files (separate function — SVG is a file format loader, not a module import).
-
-### Import Rules
-- Paths: `./file.forge.js` resolves relative to caller; bare paths resolve from project root
-- Param overrides only affect that import call
-- Circular imports throw an error
-- Each import call is a fresh execution
-
-### Placement References
-
-Attach named reference points/edges/surfaces to shapes for precise cross-file positioning:
-
-```javascript
-// In part file:
-return union(base, post).withReferences({
-  points: { mount: [0, -16, -4] },
-  surfaces: { mountingFace: { center: [0, -16, 0], normal: [0, -1, 0] } },
-  objects: { base, post },
-});
-
-// In assembly file:
-const widget = require("./widget.forge.js")
-  .placeReference("mount", [120, 40, 0]);
-const cap = box(18, 18, 8, true)
-  .attachTo(widget, "objects.post.top", "bottom");
-```
-
-References survive transforms and import round-trips.
-
-### Plain JS Module Imports
-
-Regular `import`/`require()` works for utility modules. Don't mix explicit exports with top-level `return` in the same module.
-
-### Typical Project Structure
-```
-my-project/
-├── base-profile.forge.js     ← 2D cross-section (returns Sketch)
-├── bracket.forge.js           ← extrudes the sketch, adds holes
-└── assembly.forge.js          ← imports multiple parts, positions them
-```
-
-## Compiler-Owned Operations
-
-### `shape.shell(thickness, options?)`
-Hollows out a solid. Supports `box()`, `cylinder()`, straight `extrude()`. Optional `openFaces: ['top' | 'bottom']`.
-
-```javascript
-const cup = roundedRect(80, 50, 6, true)
-  .extrude(30).shell(2.5, { openFaces: ['top'] });
-```
-
-### `shape.hole(face, options)`
-Circular hole anchored to a face. `depth` omitted = through-hole. Supports `counterbore`/`countersink`, `upToFace`, two-sided `extent`.
-
-```javascript
-const body = block
-  .hole('front', { diameter: 8, u: 0, v: 2 })
-  .hole('top', { diameter: 6, u: -18, v: 10, depth: 10 })
-  .hole('top', { diameter: 5, u: 18, v: 10, upToFace: exitFace,
-    counterbore: { diameter: 9, depth: 4 } });
-```
-
-### `shape.cutout(sketch, options?)`
-Cut-extrude using a sketch placed with `Sketch.onFace(...)`. Same extent options as `hole()`. Supports `taperScale` on circle/rect/roundedRect profiles.
-
-### `sheetMetal(options)`
-Sheet-metal builder: base panel → `.flange()` → `.cutout()` → `.folded()` or `.flatPattern()`.
-
-## Group Patterns
-
-`group()` combines shapes without merging — colors and identities preserved.
-
-```javascript
-const housing = group(
-  { name: 'Shell', shape: shell },
-  { name: 'Lid', shape: lid },
-).withReferences({
-  points: { mountCenter: [0, 30, 20] },
-});
-```
-
-ShapeGroup supports all transforms, placement references, and child access (`.child("Name")`).

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

@@ -1,186 +0,0 @@
-# Specs — Named Requirement Bundles
-
-A **Spec** is a named, reusable group of `verify.*` checks. When you call `spec.check(shape)`, every `verify` call inside the check function is tagged with the spec name and displayed as a collapsible section in the Checks panel.
-
-## Why Specs
-
-Bare `verify.*` calls produce a flat list. With 15 checks across 3 different concerns, the panel becomes hard to scan. Specs add structure:
-
-- **Grouping** — related checks appear under a named, collapsible header
-- **Reusability** — one spec, applied to many shapes: `printable.check(bracket); printable.check(standoff);`
-- **Composability** — combine independent specs: check fit, strength, and printability separately
-- **Separation** — define what "good" looks like before building geometry (spec-first / TDD workflow)
-
-## Quick Start
-
-```javascript
-// Define a spec
-const printable = spec("Fits printer bed", (shape) => {
-  verify.notEmpty("Has geometry", shape);
-  const bb = shape.boundingBox();
-  const size = [bb.max[0] - bb.min[0], bb.max[1] - bb.min[1], bb.max[2] - bb.min[2]];
-  verify.lessThan("Width  < 220mm", size[0], 220);
-  verify.lessThan("Depth  < 220mm", size[1], 220);
-  verify.lessThan("Height < 250mm", size[2], 250);
-});
-
-// Build something
-const part = box(100, 80, 40);
-
-// Check it
-printable.check(part);
-
-return part;
-```
-
-The Checks panel shows:
-
-```
-▼ ✓ Fits printer bed — 4/4
-    ✓ Has geometry
-    ✓ Width  < 220mm
-    ✓ Depth  < 220mm
-    ✓ Height < 250mm
-```
-
-## API
-
-### `spec(name, checkFn)`
-
-Create a named spec.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | Display name in the Checks panel |
-| `checkFn` | `(...args) => void` | Function that calls `verify.*` methods |
-
-Returns a `Spec` object with a `.check()` method.
-
-### `Spec.check(...args)`
-
-Run the spec's check function. Any `verify.*` calls inside are grouped under the spec name.
-
-Returns a `SpecResult`:
-
-```typescript
-interface SpecResult {
-  name: string;     // Spec name
-  passed: number;   // Checks that passed
-  total: number;    // Total checks
-  results: VerificationResult[];
-}
-```
-
-The return value is optional — you can ignore it and just let the Checks panel show the results.
-
-## Patterns
-
-### Reusable Spec — Apply to Multiple Shapes
-
-```javascript
-const structural = spec("Structural", (shape) => {
-  verify.greaterThan("Min volume", shape.volume(), 500);
-  verify.notEmpty("Not degenerate", shape);
-});
-
-structural.check(bracket);
-structural.check(plate);
-structural.check(standoff);
-// Each call adds a "Structural" group to the panel
-```
-
-### Multi-Shape Spec — Check Relationships
-
-Specs can accept multiple arguments for checking relationships between parts:
-
-```javascript
-const fitSpec = spec("Assembly fit", (partA, partB) => {
-  verify.notColliding("No interference", partA, partB, 10);
-  verify.minClearance("Min gap 0.3mm", partA, partB, 0.3, 10);
-  verify.parallel("Mating faces aligned",
-    partA.face('top'), partB.face('bottom'));
-});
-
-fitSpec.check(bracket, standoff);
-```
-
-### Importable Spec Library
-
-Specs can live in separate `.forge.js` files and be imported via `require()`:
-
-```javascript
-// specs/printers.forge.js
-const prusaMK3S = spec("Prusa MK3S", (shape) => {
-  const bb = shape.boundingBox();
-  const size = [bb.max[0]-bb.min[0], bb.max[1]-bb.min[1], bb.max[2]-bb.min[2]];
-  verify.lessThan("X", size[0], 220);
-  verify.lessThan("Y", size[1], 220);
-  verify.lessThan("Z", size[2], 250);
-});
-
-return { prusaMK3S };
-```
-
-```javascript
-// my-part.forge.js
-const { prusaMK3S } = require("./specs/printers.forge.js");
-const part = box(100, 80, 40);
-prusaMK3S.check(part);
-return part;
-```
-
-### Reference Geometry in Specs
-
-Specs can create shapes internally as test fixtures — these are used only for checking and never rendered:
-
-```javascript
-const fitsInEnclosure = spec("Fits in enclosure", (shape) => {
-  // Reference geometry — not returned, not rendered
-  const enclosure = box(200, 150, 100);
-  const overlap = shape.intersect(enclosure);
-
-  verify.that("Fully contained", () =>
-    Math.abs(overlap.volume() - shape.volume()) < 1
-  );
-  verify.minClearance("2mm clearance", shape, enclosure, 2.0, 20);
-});
-```
-
-### Spec-First Workflow (TDD for CAD)
-
-Write specs before geometry. Watch checks go from red to green as you build:
-
-```javascript
-// Step 1: Define what we need
-const caseSpec = spec("Phone case", (shape) => {
-  verify.notEmpty("Has geometry", shape);
-  verify.that("Is hollow (< 40% fill)", () => {
-    const bb = shape.boundingBox();
-    const bboxVol = (bb.max[0]-bb.min[0]) * (bb.max[1]-bb.min[1]) * (bb.max[2]-bb.min[2]);
-    return shape.volume() < bboxVol * 0.4;
-  });
-  verify.greaterThan("Weighs under 30g (PLA)", 30, shape.volume() * 0.00124);
-});
-
-// Step 2: Build iteratively — specs tell you when you're done
-const myCase = box(75, 150, 12).shell(2, { openFaces: ['top'] });
-caseSpec.check(myCase);
-return myCase;
-```
-
-## Mixing Specs and Plain Verify Calls
-
-Plain `verify.*` calls (outside any spec) still work. They appear ungrouped below the spec sections:
-
-```javascript
-// Grouped under spec name
-printable.check(part);
-
-// Ungrouped — shown separately
-verify.greaterThan("Custom check", someValue, 10);
-```
-
-## See Also
-
-- **[Verification demo](../../../examples/api/verification-demo.forge.js)** — all `verify.*` methods
-- **[Spec demo](../../../examples/api/spec-demo.forge.js)** — `spec()` in action