npm - forgecad - Versions diffs - 0.1.4 → 0.1.5 - Mend

forgecad 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/README.md +11 -0
package/dist/assets/{evalWorker-1m873KWd.js → evalWorker-CbAa_9qg.js} +108 -108
package/dist/assets/{index-Dvz3nSDc.js → index-DFa4fntx.js} +335 -335
package/dist/assets/{manifold-C38sUiKu.js → manifold-BGMOVi-H.js} +1 -1
package/dist/assets/{manifold-rOWQW9fU.js → manifold-BNJTX3qf.js} +1 -1
package/dist/assets/{manifold-Dk2u-lhj.js → manifold-CL39pgcA.js} +1 -1
package/dist/assets/{reportWorker-Cj587shw.js → reportWorker-C5Ot2xSE.js} +122 -122
package/dist/index.html +1 -1
package/dist-cli/forgecad.js +59 -0
package/dist-skill/CONTEXT.md +102 -7
package/dist-skill/docs/API/model-building/assembly.md +41 -0
package/dist-skill/docs/API/model-building/reference.md +61 -7
package/dist-skill/docs/VISION.md +2 -1
package/examples/api/import-assembly-source.forge.js +22 -0
package/examples/api/import-assembly.forge.js +26 -0
package/package.json +1 -1

package/dist/index.html CHANGED Viewed

@@ -8,7 +8,7 @@
       * { margin: 0; padding: 0; box-sizing: border-box; }
       html, body, #root { width: 100%; height: 100%; overflow: hidden; background: var(--fc-bg); color: var(--fc-text); font-family: system-ui, -apple-system, sans-serif; }
     </style>
-    <script type="module" crossorigin src="/assets/index-Dvz3nSDc.js"></script>
+    <script type="module" crossorigin src="/assets/index-DFa4fntx.js"></script>
   </head>
   <body>
     <div id="root"></div>

package/dist-cli/forgecad.js CHANGED Viewed

@@ -14746,6 +14746,42 @@ var Assembly = class {
 function assembly(name) {
   return new Assembly(name);
 }
+var ImportedAssembly = class {
+  constructor(_assembly) {
+    this._assembly = _assembly;
+  }
+  /** The underlying Assembly — use for sweepJoint, addPart into parent, etc. */
+  get assembly() {
+    return this._assembly;
+  }
+  /** Solve the assembly at the given joint state (defaults to each joint's default value). */
+  solve(state) {
+    return this._assembly.solve(state);
+  }
+  /**
+   * Return a specific named part positioned at the given joint state.
+   * Result type mirrors SolvedAssembly.getPart(): Shape, TrackedShape, or ShapeGroup.
+   */
+  part(name, state) {
+    return this._assembly.solve(state).getPart(name);
+  }
+  /**
+   * Convert all assembly parts to a ShapeGroup with named children.
+   * Child names match the part names used in the assembly.
+   * Useful for embedding a solved sub-assembly in a parent group or assembly.
+   */
+  toGroup(state) {
+    const solved = this._assembly.solve(state);
+    const def = this._assembly.describe();
+    const children = [];
+    const childNames = [];
+    for (const p of def.parts) {
+      children.push(solved.getPart(p.name));
+      childNames.push(p.name);
+    }
+    return new ShapeGroup(children, childNames);
+  }
+};
 // src/forge/robotExport.ts
 var _collectedRobotExport = null;
@@ -17869,6 +17905,8 @@ function describeScriptResultType(value) {
   if (value instanceof Sketch) return "Sketch";
   if (value instanceof TrackedShape) return "TrackedShape";
   if (value instanceof ShapeGroup) return "ShapeGroup";
+  if (value instanceof Assembly) return "Assembly";
+  if (value instanceof ImportedAssembly) return "ImportedAssembly";
   if (Array.isArray(value)) return "Array";
   if (typeof value === "object" && typeof value.toShape === "function") {
     try {
@@ -18288,6 +18326,26 @@ function executeFile(code, fileName, allFiles, visited, scope = {}, options, exe
       logImportTrace(fileName, scope, options, "importGroup", resolvedPath, "error", { requested: name, got });
       throw new Error(`"${resolvedPath}" did not return a ShapeGroup (got ${got}). Use group(...) as the return value, or use importPart() for single-shape files.`);
     };
+    const importAssembly = (name, paramOverrides) => {
+      const { source: src, lookupKey, resolvedPath } = resolveImportSource(fileName, name, allFiles, options);
+      const localOverrides = parseImportParamArgs("importAssembly", name, paramOverrides);
+      const childScope = { namePrefix: makeChildScopePrefix(resolvedPath), localOverrides };
+      logImportTrace(fileName, scope, options, "importAssembly", resolvedPath, "start", { requested: name, overrides: localOverrides });
+      let result;
+      try {
+        result = executeFile(src, lookupKey, allFiles, visited, childScope, options);
+      } catch (error) {
+        logImportTrace(fileName, scope, options, "importAssembly", resolvedPath, "error", { requested: name, error: formatLogError(error) });
+        throw error;
+      }
+      if (result instanceof Assembly) {
+        logImportTrace(fileName, scope, options, "importAssembly", resolvedPath, "success", { requested: name, got: "Assembly" });
+        return new ImportedAssembly(result);
+      }
+      const got = describeScriptResultType(result);
+      logImportTrace(fileName, scope, options, "importAssembly", resolvedPath, "error", { requested: name, got });
+      throw new Error(`"${resolvedPath}" did not return an Assembly (got ${got}). Return the assembly() instance directly (before calling .solve()).`);
+    };
     const unwrap2 = (s) => s instanceof TrackedShape ? s.toShape() : s;
     const wrappedUnion = (...shapes) => union(...shapes.map(unwrap2));
     const wrappedDifference = (...shapes) => difference(...shapes.map(unwrap2));
@@ -18375,6 +18433,7 @@ function executeFile(code, fileName, allFiles, visited, scope = {}, options, exe
       importSketch,
       importPart,
       importGroup,
+      importAssembly,
       importSvgSketch,
       dim,
       dimLine,

package/dist-skill/CONTEXT.md CHANGED Viewed

@@ -1334,14 +1334,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
@@ -1351,6 +1404,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)
@@ -2741,9 +2795,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/assembly.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

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