forgecad 0.1.1 → 0.1.3

package/dist-skill/docs/CODING.md

@@ -0,0 +1,345 @@
+# ForgeCAD Coding Guidelines
+
+## Development Workflow
+
+### Building & Running
+```bash
+npm install          # Install dependencies
+npm link             # Install the local forgecad binary
+forgecad studio      # Start the browser studio (localhost:5173)
+npm run build        # Production build
+npm run preview      # Preview production build
+```
+
+### CLI Tools
+```bash
+forgecad export svg examples/frame.sketch.js     # Export sketch to SVG (Node, no browser)
+forgecad render examples/cup.forge.js            # Render to PNG (Puppeteer + Chrome)
+```
+
+See [CLI.md](CLI.md) for full CLI documentation.
+
+### Project Structure
+```
+src/
+├── forge/                # Core geometry engine (shared by browser + CLI)
+│   ├── kernel.ts         # Manifold WASM wrapper, Shape class, primitives
+│   ├── headless.ts       # Single entry point for all contexts (browser + Node CLI)
+│   ├── index.ts          # Browser entry point (re-exports from headless.ts)
+│   ├── runner.ts         # Script sandbox — executes user scripts and resolves imported .svg assets
+│   ├── params.ts         # Parameter system (param() → UI sliders)
+│   ├── library.ts        # Part library (lib.boltHole, lib.pipe, etc.)
+│   ├── section.ts        # Plane intersection / projection
+│   ├── meshToGeometry.ts # Manifold mesh → Three.js BufferGeometry
+│   ├── sceneBuilder.ts   # Three.js scene setup (shared with CLI renderer)
+│   └── sketch/           # 2D sketch system
+│       ├── core.ts       # Sketch class
+│       ├── primitives.ts # rect, circle2d, polygon, ngon, etc.
+│       ├── transforms.ts # translate, rotate, scale, mirror
+│       ├── booleans.ts   # add, subtract, intersect, union2d, hull2d
+│       ├── operations.ts # offset, hull, simplify, warp
+│       ├── extrude.ts    # extrude, revolve (2D → 3D)
+│       ├── path.ts       # PathBuilder, stroke
+│       ├── anchor.ts     # attachTo positioning
+│       ├── constraints.ts # Constraint solver (18 types)
+│       ├── entities.ts   # Point2D, Line2D, Circle2D, Rectangle2D, Constraint helpers
+│       ├── topology.ts   # TrackedShape, face/edge naming
+│       ├── patterns.ts   # linearPattern, circularPattern, mirrorCopy
+│       ├── fillets.ts    # filletEdge, chamferEdge
+│       ├── arcBridge.ts  # arcBridgeBetweenRects
+│       └── index.ts      # Re-exports everything
+├── components/           # React UI components
+│   ├── Viewport.tsx      # 3D viewport (Three.js + R3F)
+│   ├── CodeEditor.tsx    # Monaco editor with ForgeCAD types
+│   ├── FileExplorer.tsx  # Project file tree
+│   ├── ViewPanel.tsx     # Render mode, views, object settings
+│   ├── ParamPanel.tsx    # Parameter sliders
+│   └── ExportPanel.tsx   # STL export
+├── store/
+│   └── forgeStore.ts     # Zustand global state
+├── App.tsx               # Main application shell
+└── main.tsx              # React entry point
+
+cli/
+├── forgecad.ts           # Top-level CLI entrypoint and command routing
+├── forge-svg.ts          # SVG export (uses real engine via headless.ts)
+├── forge-render.mjs      # PNG render launcher (Puppeteer)
+├── render.ts             # Headless render entry (loaded in browser by Puppeteer)
+└── render.html           # HTML shell for headless render
+
+examples/                 # Example scripts
+├── *.forge.js            # 3D part examples
+└── *.sketch.js           # 2D sketch examples
+```
+
+## Coding Standards
+
+### Minimal Implementation
+Write only the code needed to solve the problem. No verbose implementations, no speculative features.
+
+## Domain Localization Standard (Required)
+
+This standard is package-wide for any new user-facing concept or API family.
+
+### Contract
+- Each concept family must have a clear primary home in both code and docs.
+- Extend the module that already owns the mental model instead of scattering helpers across unrelated files.
+- When a feature spans multiple layers, pick one domain owner and make the other layers mirror that owner.
+- Keep related runtime code, examples, checks, and docs close to the same domain name whenever practical.
+
+### Examples
+- Assembly and kinematics live under `src/forge/assembly.ts` and `docs/permanent/API/model-building/assembly.md`.
+- Sketch constraints live under `src/forge/sketch/constraints.ts` and the sketch/entity API docs.
+- Transform/placement helpers should stay grouped with transform and positioning surfaces, not reappear as ad-hoc helpers in unrelated modules.
+
+### Enforcement
+- Before adding a new API, state which domain owns it.
+- If a concept currently has no clean home, create one instead of spreading the first implementation across multiple files.
+
+## Backend Compiler Standard (Required)
+
+This standard is package-wide for any geometry feature that affects runtime lowering, exact export, or backend capability routing.
+
+Read [API/internals/compiler.md](API/internals/compiler.md) before changing this area.
+For large multi-agent migrations or architecture programs, also read [PROGRAM-LEAD.md](PROGRAM-LEAD.md).
+
+### Contract
+- Forge semantic intent comes first. Backends are lowerers, not the authoring model.
+- Scene-level capability routing must stay centralized. Do not re-derive export/runtime policy ad hoc in unrelated modules.
+- Public feature APIs must not hide backend-specific behavior directly in their callsites. Backend code belongs in the lowerers.
+- New backend limitations must surface as diagnostics, not silent fallback or silent exactness loss.
+
+### Enforcement
+- If a feature is compile-covered, update the canonical compile graph and the scene compiler.
+- If a feature is not yet dual-lowered, add explicit unsupported diagnostics for the missing backend rather than bypassing the compiler.
+- Any geometry feature change must update invariant coverage and the living backend-compiler tracker.
+
+## Multi-Agent Program Standard (Required For Large Migrations)
+
+For work that spans multiple agent branches or staged dependency waves, the Program Lead role in [PROGRAM-LEAD.md](PROGRAM-LEAD.md) is the default operating model.
+
+Use it when:
+
+- one missing foundation blocks several feature lanes
+- multiple agents need isolated tasks with dependency ordering
+- the repo needs a living task graph and capability tracker to stay truthful
+
+The key rule is simple:
+
+- solve the deepest shared prerequisite first
+- only then open the parallel wave that builds on top of it
+
+### TypeScript
+- Use explicit types for function parameters and return values
+- Avoid `any` - use `unknown` or proper types
+- Prefer interfaces for object shapes
+
+### React Components
+- Functional components only
+- Inline styles for simplicity (no CSS files unless necessary)
+- Extract reusable logic to custom hooks or store actions
+
+### State Management
+- All global state lives in `forgeStore.ts`
+- Use Zustand selectors to prevent unnecessary re-renders
+- Keep actions pure and synchronous where possible
+
+## Frame Composition Standard (Required)
+
+This standard is package-wide for any code that composes transforms (`Transform`, joints, assemblies, kinematic helpers).
+
+### Contract
+- `A.mul(B)` means **apply A, then B**
+- Use `composeChain(...)` for 3+ composed transforms instead of manual `.mul()` chains
+- In assembly/kinematics, always express composition in this canonical order:
+  - `local -> childBase -> jointMotion -> jointFrame -> parentWorld`
+
+### Why this is mandatory
+Transform order bugs can produce geometry that "looks valid" but is globally wrong (detached mechanism segments, drifting pivots, mirrored motion paths) and often pass casual visual checks.
+
+### 5-Why (2026-02 Assembly disconnect incident)
+1. Why were arm segments disconnected?  
+Because child world transforms were composed in the wrong order in `assembly.solve()`.
+2. Why was order wrong?  
+Because `.mul()` chain semantics (apply self, then other) were interpreted inconsistently with matrix notation.
+3. Why was that ambiguity possible?  
+Because there was no single canonical frame equation documented and enforced in code review.
+4. Why didn’t tests catch it immediately?  
+Because there was no invariant test comparing assembly-solved frame origins against an analytic kinematic oracle.
+5. Why no invariant test existed?  
+Because we had feature-level example checks, but no package-wide transform convention gate.
+
+Root cause: **missing, enforced transform/frame composition contract across code + tests.**
+
+### Enforcement
+- Any change touching transforms, joints, or assembly solving must run:
+  - `forgecad check transforms`
+- If the change affects user-facing geometry behavior, also run:
+  - `forgecad run <affected-example>`
+
+## Editor Declaration Parity Standard (Required)
+
+This standard is package-wide for any user-facing API exposed to scripts.
+
+### Contract
+- Runtime API and editor declarations must ship together:
+  - Runtime surface: `src/forge/*` exports + `src/forge/runner.ts` sandbox bindings
+  - Editor surface: `src/components/CodeEditor.tsx` `FORGE_TYPES`
+  - Docs surface: `docs/permanent/API/**/*.md`
+- If an important feature is missing from editor declarations, you must either:
+  - implement declarations in the same change, or
+  - create a tracked task in `tasks/` that explicitly names the missing surface and scope.
+
+### Enforcement
+- Before merge, verify new/changed script APIs are present in all three surfaces above.
+- Do not ship runtime-only features without either declaration parity or a tracking task.
+
+## Script API Contract Standard (Required)
+
+This standard is package-wide for any API exposed to user scripts.
+
+### Contract
+- Collection-shaped script APIs must accept the intuitive collection forms the docs advertise:
+  - variadic operands when the operation naturally works on many inputs
+  - a single array of operands when that keeps call sites composable
+- Method syntax and function syntax must mirror each other for the same operation family.
+- User-facing APIs must not silently ignore extra arguments. Unsupported arity or operand types must throw a direct runtime error with the API name in the message.
+- If a future API needs configuration, do not smuggle it in as an ambiguous trailing object on an operand list. Use a distinct helper or a clearly named options-bearing API.
+
+### Enforcement
+- Any change to user-facing script APIs must run:
+  - `forgecad check api`
+- If the change also affects transforms, dimensions, placement refs, or geometry semantics, run the relevant existing invariant checks too.
+
+## Git Workflow
+
+### Commit Every Major Change
+Each logical unit of work should be a separate commit:
+
+```bash
+git add <files>
+git commit -m "Add file explorer panel"
+```
+
+### Commit Message Format
+```
+<verb> <what>
+
+Examples:
+- Add file explorer panel
+- Fix measure mode toggle
+- Update parameter slider styling
+- Remove unused imports
+```
+
+Use present tense verbs: Add, Fix, Update, Remove, Refactor
+
+### What Counts as "Major"
+- New feature or component
+- Bug fix
+- Refactoring that changes structure
+- Performance improvement
+- Breaking API change
+
+### What to Commit Together
+- Related files for a single feature
+- Tests with the code they test
+- Documentation with the feature it describes
+
+### Example Workflow
+```bash
+# Feature: Add file explorer
+git add src/components/FileExplorer.tsx
+git add src/store/forgeStore.ts
+git add src/App.tsx
+git commit -m "Add file explorer panel"
+
+# Next feature: Add keyboard shortcuts
+git add src/hooks/useKeyboard.ts
+git add src/App.tsx
+git commit -m "Add keyboard shortcuts for file operations"
+```
+
+## Testing
+
+### Manual Testing Checklist
+Before committing UI changes:
+- [ ] Test in browser at localhost:5173
+- [ ] Check console for errors
+- [ ] Verify responsive behavior
+- [ ] Test with example scripts
+
+### Integration Testing
+- Load example files and verify they render
+- Test parameter sliders update geometry
+- Verify STL export produces valid files
+- Check measure mode calculates correctly
+
+## Code Review
+
+### Self-Review Before Commit
+1. Remove console.logs and debug code
+2. Check for unused imports
+3. Verify TypeScript has no errors
+4. Test the change works as intended
+5. Read the diff - does it make sense?
+
+### What to Look For
+- Does this solve the problem with minimal code?
+- Are there edge cases not handled?
+- Is the code readable without comments?
+- Does it follow existing patterns?
+
+## Performance
+
+### Geometry Operations
+- Manifold operations are expensive - minimize boolean ops
+- Cache geometry results when parameters don't change
+- Use debouncing for real-time updates (already implemented)
+
+### React Rendering
+- Use Zustand selectors to prevent unnecessary re-renders
+- Memoize expensive computations with `useMemo`
+- Keep component tree shallow
+
+## Common Patterns
+
+### Adding a New Sketch Primitive
+1. Add function to `src/forge/sketch/primitives.ts`
+2. It's auto-exported via `sketch/index.ts` → `headless.ts` → `index.ts`
+3. Add it to the sandbox in `src/forge/runner.ts` (both the `new Function()` args and the call)
+4. Add TypeScript hints in `src/components/CodeEditor.tsx` (`FORGE_TYPES`)
+5. Update `docs/permanent/API/model-building/sketch-primitives.md`
+6. Commit: "Add [primitive] sketch primitive"
+
+### Adding a New 3D Primitive
+1. Add function to `src/forge/kernel.ts`
+2. Export from `headless.ts`
+3. Add to runner sandbox in `src/forge/runner.ts`
+4. Add TypeScript hints in `src/components/CodeEditor.tsx`
+5. Update `docs/permanent/API/model-building/reference.md`
+6. Commit: "Add [primitive] 3D primitive"
+
+### Adding a New CLI Command
+1. Create `cli/your-command.ts`
+2. Import from `../src/forge/headless`
+3. Call `await init()` then use `runScript()`
+4. Add script to `package.json`
+5. Update `docs/permanent/CLI.md`
+6. Commit: "Add [command] CLI command"
+
+### Adding UI State
+1. Add to `src/store/forgeStore.ts` interface
+2. Add initial value and actions
+3. Wire up to component
+4. Commit: "Add [feature] UI state"
+
+### Adding a Component
+1. Create in `src/components/`
+2. Import and use in `App.tsx` or parent
+3. Commit: "Add [Component] component"
+
+### Key Architecture Rule: Single Source of Truth
+All geometry logic lives in `src/forge/`. CLI tools import from `src/forge/headless.ts`.
+**Never** duplicate forge logic in CLI scripts. If you need something in CLI, make sure
+it's exported from `headless.ts` and import it.

package/dist-skill/docs/PROGRAM-LEAD.md

@@ -0,0 +1,180 @@
+# Program Lead Role
+
+This document formalizes the reusable role Forge uses for large architectural projects that involve multiple agent branches and staged dependency waves.
+
+Use this role when the work is too deep or too cross-cutting to split safely into ad hoc feature tickets.
+
+## Role Name
+
+Program Lead
+
+Short version:
+
+- owns the architectural through-line
+- decides what must be solved before parallelization
+- turns the program into explicit tasks, waves, and merge rules
+- reviews landed work for truthfulness, scope, and regression safety
+
+This is not a people-manager role. It is a technical integration and program-shaping role.
+
+## Mission
+
+Keep multi-agent technical work coherent.
+
+The Program Lead protects three things:
+
+1. one clear source of truth for architecture
+2. honest task decomposition with real dependency boundaries
+3. a repo state that tells the truth about what is landed, supported, blocked, and next
+
+If those three drift apart, the program stops scaling.
+
+## Responsibilities
+
+### 1. Identify the deepest prerequisite
+
+Before parallelizing, find the one core problem everything else depends on.
+
+Examples:
+
+- shared query/reference backbone
+- topology-rewrite propagation
+- backend-neutral compile graph
+
+The Program Lead should prefer foundation before breadth. If several features all feel blocked by the same missing layer, that missing layer becomes the next core lane.
+
+### 2. Shape the work into waves
+
+Every program should have:
+
+- one current core lane
+- one parallel wave that becomes safe after that lane lands
+- one follow-on wave that depends on the first parallel wave
+- one closeout lane for corpus, docs, and capability truthfulness
+
+The Program Lead owns that wave plan and updates it as the repo changes.
+
+### 3. Write explicit task contracts
+
+Each task should define:
+
+- problem definition
+- description
+- requirements
+- isolation rule
+- dependencies
+- parallelization notes
+- status log
+
+The point is not bureaucracy. The point is merge safety and honest scope.
+
+### 4. Own the integration seam
+
+Agents should build feature logic in isolated modules first.
+
+The Program Lead owns:
+
+- the shared branch
+- the thin shared-file integration seams
+- the sequencing of merges when multiple tasks touch central compiler files
+
+### 5. Review landed work before opening the next wave
+
+Before the next wave starts, the Program Lead reviews:
+
+- implementation against task scope
+- tests and regression coverage
+- docs and task/tracker truthfulness
+- hidden capability inflation
+
+The Program Lead should explicitly say whether the program should move forward or not.
+
+### 6. Keep capability claims honest
+
+The Program Lead is responsible for making sure docs do not overstate support.
+
+If the implementation only supports a defended subset, the docs must say so.
+
+### 7. Maintain the living docs
+
+At minimum, the Program Lead keeps these current:
+
+- temporary program README
+- mission tracker
+- task graph
+- task files
+- permanent architecture docs when contracts change
+
+## Operating Rules
+
+### One branch of truth
+
+- Keep one program branch as the integration branch.
+- Agent branches should merge into that branch, not bypass it.
+- Reviews and go/no-go decisions should happen against that branch, not stale side worktrees.
+
+### One architectural center
+
+- Do not let each task invent its own local semantic model.
+- If several tasks need the same concept, the Program Lead should create or demand a shared contract first.
+
+### Explicit unsupported is good
+
+- Unsupported or ambiguous cases should be recorded in diagnostics and docs.
+- Silent fallback is program debt.
+
+### Foundation before convenience
+
+- Do not widen feature breadth by bypassing a missing architectural layer.
+- If a feature needs a missing core layer, stop and create the layer task.
+
+### Close each wave honestly
+
+Before moving on:
+
+- regression coverage must exist
+- docs must match reality
+- task graph must reflect the new queue
+
+## Expected Outputs
+
+For a healthy multi-agent program, the Program Lead should leave behind:
+
+- a readable explainer
+- a living mission tracker
+- a dependency graph
+- scoped task files
+- regression expectations
+- explicit next-step guidance after each review
+
+## Anti-Patterns
+
+These are warning signs that the Program Lead should stop and correct:
+
+- "just start all the feature tasks"
+- "we can clean the tracker later"
+- "this branch probably has the latest state"
+- "the snapshot changed, it is probably fine"
+- "let's add one shortcut in this feature instead of solving the shared layer"
+
+## Success Criteria
+
+The role is working if:
+
+- agents can work in parallel without constant semantic collisions
+- merges are mostly thin and predictable
+- tasks describe real isolated work instead of vague ambition
+- docs tell a new contributor where the program really is
+- the next wave opens only when the previous wave actually earned it
+
+## Default Hand-off Pattern
+
+For each review checkpoint, the Program Lead should answer:
+
+1. What landed?
+2. What is still missing?
+3. Is there any blocker to moving forward?
+4. Which tasks can start now?
+5. Which tasks must still wait?
+
+That hand-off pattern should be reusable across projects, not just ForgeCAD.

package/dist-skill/docs/VISION.md

@@ -0,0 +1,77 @@
+# ForgeCAD — What It Is and Where It's Going
+
+## The Relationship with Manifold
+
+[Manifold](https://github.com/elalish/manifold) is a geometry kernel. It does boolean operations on triangle meshes, extrusion, revolution, smoothing, and SDF level sets. It's fast, correct, and runs in WASM. Think of it as the engine block.
+
+ForgeCAD is the car built around that engine. Manifold doesn't know what a "rectangle with named sides" is. It doesn't know what a "constraint" is. It doesn't have parameters, sliders, a code editor, or file imports. It gives you raw mesh operations — you give it polygons and get back polygons.
+
+Every serious CAD system has this split:
+- Fusion360 uses Parasolid/ACIS as its kernel
+- FreeCAD uses OpenCascade
+- ForgeCAD uses Manifold
+
+The kernel is not the product. The modeling layer on top is.
+
+## What ForgeCAD Adds Over Manifold
+
+### Already built
+- **Constraint solver** — 18 constraint types (coincident, parallel, perpendicular, tangent, equal, symmetric, concentric, collinear, distance, length, angle, radius, diameter, hDistance, vDistance, fixed, horizontal, vertical) with iterative relaxation solver. Detects under/over/fully-constrained states. Live constraint editing in the UI.
+- **Named 2D entities** — `Rectangle2D`, `Circle2D`, `Line2D`, `Point2D` with semantic access (`.side('top')`, `.vertex('bottom-left')`, `.pointAtAngle(90)`)
+- **Topology tracking** — `TrackedShape` preserves face/edge names through extrusion and translation. `shape.face('top')`, `shape.edge('vert-bl')`, `shape.rotateAroundEdge('top-bottom', 90)`.
+- **Sketch primitives** — `roundedRect`, `slot`, `star`, `ngon`, `ellipse`, `polygon`, path builder with stroke
+- **Patterns** — `linearPattern`, `circularPattern`, `mirrorCopy` for 3D shape arrays
+- **Fillets & chamfers** — `filletCorners()` for selective 2D polygon corners, plus `filletEdge()` / `chamferEdge()` for vertical 3D edges using topology references
+- **Arc bridge** — `arcBridgeBetweenRects()` for smooth arc surfaces between rectangular areas (e.g., laptop hinges)
+- **Parameters** — `param()` creates live UI sliders, code re-executes on change
+- **Multi-file** — `importSketch()`, `importPart()` with circular import detection, folder support
+- **Code-as-format** — plain JS/TS files, version-controllable, LLM-writable
+- **3D smoothing** — `smoothOut()` + `refine()` / `refineToLength()` / `refineToTolerance()` for edge rounding
+- **3D advanced ops** — `hull3d()` (convex hull of shapes + points), `levelSet()` (SDF-based shapes), `warp()`, `split()`, `splitByPlane()`, `trimByPlane()`
+- **Sketch on face** — `sketch.onFace(body, face, ...)` places a 2D sketch on canonical or tracked planar faces and extrudes from that face normal
+- **Part library** — bolt holes, counterbores, tubes, pipes, hex nuts, rounded boxes, brackets, hole patterns, threaded bolts/nuts (real helical threads via SDF levelSet)
+- **Colors** — `.color('#ff0000')` on both Shape and Sketch, preserved through transforms and booleans
+- **CLI tools** — SVG export (pure Node), PNG render (Puppeteer), all sharing the same engine via `headless.ts`
+- **Measurement tool** — Click-to-measure with vertex/edge/face snapping, draggable markers
+- **File management** — File explorer with folders, drag-and-drop, rename, create/delete, unsaved change indicators
+- **View controls** — Render modes (solid/wireframe/overlay), projection (perspective/orthographic), named views (front/back/left/right/top/bottom/iso), fit-to-view, zoom-to-selection
+- **STL export** — Binary STL export from the browser UI
+- **Cut planes** — `cutPlane()` defines named section planes for inspection. Viewport sectioning uses `trimByPlane()` for capped solids, with GPU clipping fallback on trim failures
+
+### Gaps to close (Fusion360 parity)
+
+| Feature | What it does | Why it matters | Difficulty |
+|---------|-------------|----------------|------------|
+| Arc entity | First-class arc in constraint system | Needed for fillet results to participate in constraints | Medium |
+| Shell operation | Hollow a solid with wall thickness | Enclosures, cases, containers | Medium |
+| Per-edge 3D fillet | Round specific edges by exact radius | The #1 most-used Fusion360 operation | Very Hard (mesh kernel) |
+| Trim/extend | Cut or extend sketch entities at intersections | Complex sketch editing | Medium |
+| Splines | B-spline curves in sketches | Organic shapes | Medium |
+| Loft | Blend between multiple cross-section profiles | Transition shapes, aerodynamic forms | Hard |
+| Thread/helix | Helical sweep for threads, springs | Mechanical fasteners | Medium (threads done via SDF, general helix sweep still missing) |
+
+### What we deliberately skip
+- **History tree / timeline** — code IS the history. You read it top to bottom. No need for a separate feature tree when the script is the tree.
+- **Direct modeling** — push/pull faces interactively. Not relevant for code-first CAD.
+- **Full GUI-style assembly mate solving** — Forge now supports code-level assembly graphs (`assembly()`, revolute/prismatic/fixed joints, collision checks, BOM metadata), but not full interactive face-mate workflows like Fusion's assembly workspace.
+- **Photorealistic rendering** — not a rendering tool. Basic viewport materials are sufficient. Export to STL for slicing or external renderers.
+
+## The Code-First Bet
+
+The thesis: parametric CAD expressed as code is strictly more powerful than GUI-based CAD for certain workflows:
+
+1. **LLM generation** — an AI can write and modify `.forge.js` files. It can't click buttons in Fusion360.
+2. **Version control** — git diff on a `.forge.js` file shows exactly what changed. Fusion360 files are opaque blobs.
+3. **Composition** — import a part, transform it, array it, subtract it. All in code. No manual assembly.
+4. **Parametric by default** — every `param()` is a slider. No extra work to make something parametric.
+5. **Extensibility** — if you need a new primitive, write a function. No plugin SDK needed.
+
+This doesn't replace Fusion360 for everything. Interactive sketching, direct face manipulation, complex surfacing — those are better with a GUI. But for parametric parts, enclosures, mechanical components, and especially for AI-assisted design, code-first wins.
+
+## Technical Direction
+
+- **Keep Manifold as the kernel.** It's actively maintained, fast, and handles the hard geometry problems. Don't reimplement CSG.
+- **Build the parametric layer.** Constraints, named entities, topology tracking, sketch operations — this is where ForgeCAD's value lives.
+- **Expose Manifold's power.** Things like `smoothOut`, `refine`, `levelSet` (SDF), `warp` — make them accessible from user scripts with clean APIs.
+- **Stay extensible.** Users should be able to define new primitives, new operations, new patterns inside their scripts. The API should be a toolkit, not a cage.
+- **Make Forge semantics own the backends.** Manifold and CadQuery/OCCT should be lowerers for the same Forge modeling system, not competing authoring models. See [API/internals/compiler.md](API/internals/compiler.md).

package/examples/api/import-group-assembly.forge.js

@@ -0,0 +1,34 @@
+// import-group-assembly.forge.js
+// Demonstrates importGroup(): bring in a multipart component and work on
+// the whole group or individual named children separately.
+
+// --- Import the full assembly as a ShapeGroup ---
+const bracketAssembly = importGroup("api/import-group-source.forge.js");
+
+// Place it using a named reference (same API as importPart)
+const placed = bracketAssembly.placeReference("mountCenter", [0, 0, 0]);
+
+// --- Access individual children by name ---
+// Each child is a Shape/TrackedShape/ShapeGroup you can manipulate independently.
+const leftBracket  = placed.child("Bracket Left");
+const rightBracket = placed.child("Bracket Right");
+const dowel        = placed.child("Dowel");
+
+// Make a highlight copy of the left bracket for visualisation
+const highlight = leftBracket.color('#ff4444');
+
+// --- A second instance, shifted and with overridden params ---
+const secondAssembly = importGroup("api/import-group-source.forge.js", {
+  "Height": 60,
+  "Width": 80,
+}).translate(150, 0, 0);
+
+return [
+  // Show the first assembly as individual named parts
+  { name: "Left Bracket (highlight)", shape: highlight },
+  { name: "Right Bracket",            shape: rightBracket },
+  { name: "Dowel",                    shape: dowel },
+
+  // Show the second (translated) assembly as a group
+  { name: "Second Assembly",          shape: secondAssembly },
+];

package/examples/api/import-group-source.forge.js

@@ -0,0 +1,35 @@
+// import-group-source.forge.js
+// A multipart bracket assembly exported as a named ShapeGroup.
+// Import with: importGroup("api/import-group-source.forge.js")
+
+const thickness = param("Thickness", 4, { min: 2, max: 8, unit: "mm" });
+const height    = param("Height",    40, { min: 20, max: 80, unit: "mm" });
+const width     = param("Width",     60, { min: 40, max: 120, unit: "mm" });
+
+// Left bracket
+const leftBracket = box(thickness, width, height)
+  .color('#5b7c8d');
+
+// Right bracket — mirror of left
+const rightBracket = box(thickness, width, height)
+  .translate(width + thickness, 0, 0)
+  .color('#5b7c8d');
+
+// Connecting dowel — runs along Y axis between the two brackets
+const dowel = cylinder(width, 3)
+  .rotate(90, 0, 0)
+  .translate(width / 2 + thickness, width, height / 2)
+  .color('#d38b4d');
+
+return group(
+  { name: "Bracket Left",  shape: leftBracket },
+  { name: "Bracket Right", shape: rightBracket },
+  { name: "Dowel",         shape: dowel },
+).withReferences({
+  points: {
+    // Semantic mount point at the center of the left face
+    mountCenter: [0, width / 2, height / 2],
+    // Top-center of the full assembly
+    topCenter:   [width / 2 + thickness, width / 2, height],
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgecad",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Code-first parametric CAD for JavaScript/TypeScript, in the browser and CLI.",
   "license": "BUSL-1.1",
   "type": "module",