forgecad 0.1.3 → 0.1.5

package/dist-skill/docs/API/model-building/assembly.md

@@ -131,9 +131,50 @@ show(solved.toScene());
 
 That keeps mechanism setup in earlier cells and collision/sweep investigation in the current preview cell.
 
+## Importing assemblies from other files
+
+Use `importAssembly(fileName, paramOverrides?)` to import an assembly defined in another file. The source file must `return` the `Assembly` instance directly (not `.solve()`).
+
+```javascript
+// arm.forge.js — source file
+const mech = assembly("Arm")
+  .addPart("Base", box(80, 80, 20, true))
+  .addPart("Link", box(140, 24, 24).translate(0, -12, -12))
+  .addRevolute("shoulder", "Base", "Link", {
+    axis: [0, 1, 0],
+    min: -30,
+    max: 120,
+    default: 25,
+    frame: Transform.identity().translate(0, 0, 20),
+  });
+
+return mech; // return Assembly, not mech.solve()
+```
+
+```javascript
+// scene.forge.js — consumer
+const arm = importAssembly("arm.forge.js");
+
+// Access named parts by name (positioned at default or given joint state)
+const base = arm.part("Base");
+const link = arm.part("Link", { shoulder: 60 });
+
+// Convert to a ShapeGroup — children named after assembly part names
+const g = arm.toGroup({ shoulder: 45 });
+const baseChild = g.child("Base");
+
+// Full kinematic access
+arm.assembly.sweepJoint("shoulder", -30, 120, 24);
+const solved = arm.solve({ shoulder: 45 });
+console.log(solved.bom());
+
+return arm.toGroup({ shoulder: 45 });
+```
+
 ## Common pitfalls
 - If parts vanish in the viewport, check whether a cut plane is active before debugging kinematics. The viewer-side APIs live in [../runtime/viewport.md](../runtime/viewport.md).
 - If a returned object is empty, Forge logs a warning in script output.
+- `importAssembly()` requires the source file to return the `Assembly` object before calling `.solve()`. If you call `.solve()` in the source file and return a `SolvedAssembly`, use `importGroup()` instead (convert with `.toScene()` → group).
 
 ## Metadata
 - `addPart(..., { metadata })` attaches per-part metadata to an assembly part.

package/dist-skill/docs/API/model-building/reference.md

@@ -1284,14 +1284,67 @@ const rightOnly = bracketB.child("Bracket Right").translate(200, 0, 0);
 return [bracketA, leftOnly, rightOnly];
 ```
 
-**When to use `importGroup` vs `importPart`:**
+### `importAssembly(fileName, paramOverrides?)`
+Executes another file and returns its result as an `ImportedAssembly`. The target file **must** return an `Assembly` instance directly (before calling `.solve()`). Use this when the source file is authored with `assembly()` and you want to access named parts or kinematic structure without rewriting it as a `group()`.
 
-| | `importPart` | `importGroup` |
-|---|---|---|
-| Source returns | `Shape` or `TrackedShape` | `ShapeGroup` via `group(...)` |
-| Result type | `Shape` — chainable, supports all boolean ops | `ShapeGroup` — children stay separate |
-| Access children | Not possible | `group.child("Name")` |
-| Placement refs | `.withReferences()` on the Shape | `.withReferences()` on the group |
+**Parameters:**
+- `fileName` (string) — Import path (e.g. `"./sub-arm.forge.js"`)
+- `paramOverrides` (optional object) — Import-time parameter overrides by param name
+
+**Returns:** `ImportedAssembly` with the following methods:
+- `.assembly` — the raw `Assembly` for `sweepJoint`, `describe`, etc.
+- `.solve(state?)` — delegate to `Assembly.solve()`, returns `SolvedAssembly`
+- `.part(name, state?)` — returns the named part positioned at the given joint state (defaults to each joint's `default` value)
+- `.toGroup(state?)` — converts all parts to a `ShapeGroup` with children named after the assembly part names
+
+```javascript
+// sub-arm.forge.js  ← the source file — returns Assembly, not solved
+const mech = assembly("Sub Arm")
+  .addPart("Base", box(60, 60, 16, true))
+  .addPart("Link", box(120, 20, 20).translate(0, -10, -10))
+  .addRevolute("shoulder", "Base", "Link", {
+    axis: [0, 1, 0],
+    min: -45,
+    max: 120,
+    default: 30,
+    frame: Transform.identity().translate(0, 0, 16),
+  });
+
+return mech;  // return Assembly directly
+```
+
+```javascript
+// scene.forge.js  ← the consumer
+const angle = param("Angle", 45, { unit: "°" });
+
+const subArm = importAssembly("sub-arm.forge.js", { "Link Length": 100 });
+
+// Access a specific part positioned at a given state
+const baseShape = subArm.part("Base");
+const linkShape = subArm.part("Link", { shoulder: angle });
+
+// Convert to a named ShapeGroup — children match assembly part names
+const asGroup = subArm.toGroup({ shoulder: angle });
+const base = asGroup.child("Base");
+
+// Full kinematic access via the underlying assembly
+const swept = subArm.assembly.sweepJoint("shoulder", -45, 120, 20);
+
+// Place two copies at different joint states
+const copy1 = subArm.toGroup({ shoulder: 45 });
+const copy2 = subArm.toGroup({ shoulder: -20 }).translate(200, 0, 0);
+return [copy1, copy2];
+```
+
+**When to use `importGroup` vs `importAssembly`:**
+
+| | `importPart` | `importGroup` | `importAssembly` |
+|---|---|---|---|
+| Source returns | `Shape` or `TrackedShape` | `ShapeGroup` via `group(...)` | `Assembly` (unsolved) |
+| Result type | `Shape` | `ShapeGroup` | `ImportedAssembly` |
+| Access children | Not possible | `.child("Name")` | `.part("Name", state?)` or `.toGroup().child("Name")` |
+| Kinematic access | None | None | `.solve()`, `.assembly.sweepJoint()` |
+| Multiple poses | No | No | Yes — call `.toGroup(state)` with different states |
 
 ### Import Rules
 - Circular imports are detected and throw an error
@@ -1301,6 +1354,7 @@ return [bracketA, leftOnly, rightOnly];
 - Relative imports (`./` / `../`) are resolved from the current file path
 - `importPart()` accepts `Shape` or `TrackedShape` results and always returns a chainable `Shape`
 - `importGroup()` accepts only `ShapeGroup` results; use `group(...)` as the return value in the source file
+- `importAssembly()` accepts only `Assembly` results; return the `assembly(...)` instance before calling `.solve()`
 - Source files can attach placement references with `.withReferences({ points, edges, surfaces, objects })` — works on both `Shape` and `ShapeGroup`
 - Imported tracked solids keep their named faces/edges as `surfaces.<faceName>` and `edges.<edgeName>` references
 - SVG import supports deterministic region filtering (`regionSelection`, `maxRegions`, area thresholds)

package/dist-skill/docs/VISION.md

@@ -37,6 +37,7 @@ The kernel is not the product. The modeling layer on top is.
 - **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
+- **Compile plan inspector** — selecting a shape opens a Construction panel showing its build tree (Union → Box, Cylinder, Fillet, …). Clicking any node previews that sub-shape as an X-ray ghost in the viewport (visible through the parent solid). Navigate with arrow keys; Escape or clicking elsewhere exits.
 
 ### Gaps to close (Fusion360 parity)
 
@@ -51,7 +52,7 @@ The kernel is not the product. The modeling layer on top is.
 | 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.
+- **Editable 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. (Note: the compile plan inspector above is read-only — it shows what the code produced, not a parallel editable feature history.)
 - **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.

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

@@ -0,0 +1,22 @@
+// Source file for import-assembly demo.
+// Returns an Assembly directly (not solved) so the importer controls state.
+
+const linkLen = param("Link Length", 120, { min: 60, max: 200 });
+
+const base = box(60, 60, 16, true).translate(0, 0, 8).color("#6e7b88");
+const link = box(linkLen, 20, 20)
+  .translate(0, -10, -10)
+  .color("#5f87c6");
+
+const mech = assembly("Sub Arm")
+  .addPart("Base", base, { metadata: { material: "PETG", qty: 1 } })
+  .addPart("Link", link, { metadata: { material: "PETG-CF", qty: 1 } })
+  .addRevolute("shoulder", "Base", "Link", {
+    axis: [0, 1, 0],
+    min: -45,
+    max: 120,
+    default: 30,
+    frame: Transform.identity().translate(0, 0, 16),
+  });
+
+return mech;

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

@@ -0,0 +1,26 @@
+// importAssembly() demo
+// Shows how to import an Assembly, access named parts, and convert to a group.
+
+const angle = param("Shoulder Angle", 45, { min: -45, max: 120, unit: "°" });
+
+// Import the sub-assembly — get back an ImportedAssembly
+const subArm = importAssembly("api/import-assembly-source.forge.js", { "Link Length": 100 });
+
+// Access a specific part by name (positioned at default joint state)
+const baseShape = subArm.part("Base");
+const linkShape = subArm.part("Link", { shoulder: angle });
+
+// Solve the whole sub-assembly at a specific joint state
+const solved = subArm.solve({ shoulder: angle });
+console.log("BOM:", solved.bom());
+
+// Convert to a named ShapeGroup — children match part names
+const asGroup = subArm.toGroup({ shoulder: angle });
+const groupedBase = asGroup.child("Base");
+const groupedLink = asGroup.child("Link");
+
+// Place a copy of the full sub-assembly, and a shifted copy
+const copy1 = subArm.toGroup({ shoulder: angle });
+const copy2 = subArm.toGroup({ shoulder: -20 }).translate(200, 0, 0);
+
+return [copy1, copy2];

package/package.json

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