forgecad 0.1.1 → 0.1.3

package/dist-skill/docs/API/model-building/sketch-primitives.md

@@ -0,0 +1,104 @@
+# Sketch Primitives
+
+2D primitive shapes for creating sketches.
+
+## Functions
+
+### `rect(width, height, center?)`
+Creates a rectangle.
+
+**Parameters:**
+- `width` (number) - Width
+- `height` (number) - Height
+- `center` (boolean, optional) - If true, centers at origin. Default: false (corner at origin)
+
+```javascript
+const r = rect(50, 30);
+const centered = rect(50, 30, true);
+```
+
+### `circle2d(radius, segments?)`
+Creates a circle.
+
+**Parameters:**
+- `radius` (number) - Circle radius
+- `segments` (number, optional) - Number of segments. Default: auto (smooth)
+
+```javascript
+const c = circle2d(25);
+const octagon = circle2d(25, 8);
+```
+
+### `roundedRect(width, height, radius, center?)`
+Creates a rectangle with rounded corners.
+
+**Parameters:**
+- `width` (number) - Width
+- `height` (number) - Height
+- `radius` (number) - Corner radius
+- `center` (boolean, optional) - If true, centers at origin. Default: false
+
+```javascript
+const rounded = roundedRect(60, 40, 5);
+```
+
+### `polygon(points)`
+Creates a polygon from an array of [x, y] points or Point2D objects.
+
+**Parameters:**
+- `points` (([number, number] | Point2D)[]) - Array of vertex coordinates or Point2D objects
+
+```javascript
+const triangle = polygon([[0, 0], [50, 0], [25, 40]]);
+
+// Also accepts Point2D objects
+const p1 = point(0, 0), p2 = point(50, 0), p3 = point(25, 40);
+const triangle2 = polygon([p1, p2, p3]);
+```
+
+### `ngon(sides, radius)`
+Creates a regular polygon (equilateral).
+
+**Parameters:**
+- `sides` (number) - Number of sides
+- `radius` (number) - Radius from center to vertex
+
+```javascript
+const hex = ngon(6, 25);
+const triangle = ngon(3, 30);
+```
+
+### `ellipse(rx, ry, segments?)`
+Creates an ellipse.
+
+**Parameters:**
+- `rx` (number) - X radius
+- `ry` (number) - Y radius
+- `segments` (number, optional) - Number of segments. Default: 64
+
+```javascript
+const oval = ellipse(40, 20);
+```
+
+### `slot(length, width)`
+Creates an oblong shape (rectangle with semicircle ends).
+
+**Parameters:**
+- `length` (number) - Total length
+- `width` (number) - Width
+
+```javascript
+const oblong = slot(60, 20);
+```
+
+### `star(points, outerRadius, innerRadius)`
+Creates a star shape.
+
+**Parameters:**
+- `points` (number) - Number of star points
+- `outerRadius` (number) - Outer radius (tip of points)
+- `innerRadius` (number) - Inner radius (between points)
+
+```javascript
+const star5 = star(5, 30, 15);
+```

package/dist-skill/docs/API/model-building/sketch-transforms.md

@@ -0,0 +1,60 @@
+# Sketch Transforms
+
+2D transformations for sketches. All transforms are **chainable** and **immutable** (return new sketches). Colors are preserved through all transforms.
+
+## Methods
+
+### `.clone()` / `.duplicate()`
+Create an explicit copy handle of a sketch (same profile/color) so variants are easy to branch.
+
+```javascript
+const profile = rect(40, 20);
+const left = profile.clone().translate(-30, 0);
+const right = profile.duplicate().translate(30, 0);
+```
+
+### `.translate(x, y?)`
+Moves the sketch.
+
+```javascript
+const moved = rect(50, 30).translate(100, 50);
+```
+
+### `.rotate(degrees)`
+Rotates around the origin.
+
+```javascript
+const rotated = rect(50, 30).rotate(45);
+```
+
+### `.rotateAround(degrees, pivot)`
+Rotates around a specific point instead of origin.
+
+**Parameters:**
+- `degrees` (number) — Rotation angle
+- `pivot` ([number, number]) — Point to rotate around
+
+```javascript
+const hook = rect(4, 20).rotateAround(-35, [2, 0]);
+```
+
+### `.scale(v)`
+Scales the sketch.
+
+**Parameters:**
+- `v` (number | [number, number]) — Uniform scale or per-axis scale
+
+```javascript
+const bigger = circle2d(10).scale(2);
+const stretched = rect(10, 10).scale([2, 0.5]);
+```
+
+### `.mirror(normal)`
+Mirrors across a line defined by its normal vector.
+
+**Parameters:**
+- `normal` ([number, number]) — Line normal (doesn't need to be unit length)
+
+```javascript
+const mirrored = sketch.mirror([1, 0]); // Mirror across Y axis
+```

package/dist-skill/docs/API/output/bom.md

@@ -0,0 +1,53 @@
+# Bill of Materials
+
+These APIs annotate a model for report/export workflows. They do not change geometry, so they are outside the required model-building reading set.
+
+## `bom(quantity, description, opts?)`
+
+Register a bill-of-materials entry for report export.
+
+Use this for real-world parts or materials that cannot be inferred reliably from geometry alone.
+
+**Parameters:**
+- `quantity` (number) - must be finite and `>= 0`; `0` is ignored
+- `description` (string) - human-readable item description
+- `opts` (object, optional):
+  - `unit` (string) - default `"pieces"`
+  - `key` (string) - explicit aggregation key when multiple descriptions should collapse to one line item
+
+**Returns:** `void`
+
+```javascript
+const tubeLen = param("Tube Length", 1200, { min: 300, max: 4000, unit: "mm" });
+const boltCount = param("Bolt Count", 16, { min: 0, max: 200, integer: true });
+const boltLength = param("Bolt Length", 16, { min: 6, max: 80, unit: "mm" });
+
+bom(tubeLen, "iron tube 30 x 20", { unit: "mm" });
+bom(boltCount, `M4 bolt of ${boltLength} mm length`, { unit: "pieces" });
+```
+
+Aggregation behavior:
+- rows are grouped by normalized `description + unit`
+- `key` overrides the default grouping rule
+- grouped rows render on the report's Bill of Materials page
+
+## Assembly BOM Helpers
+
+Assembly graphs can also carry metadata for downstream reporting:
+
+- `addPart(name, shape, { metadata? })`
+- `solved.bom()`
+- `solved.bomCsv()`
+- `bomToCsv(rows)`
+
+```javascript
+const mech = assembly("Arm")
+  .addPart("base", box(80, 80, 20, true), {
+    metadata: { material: "PETG", process: "FDM", qty: 1 },
+  });
+
+const solved = mech.solve();
+const csv = solved.bomCsv();
+```
+
+See `examples/api/bill-of-materials.forge.js` for a complete script-authored BOM example.

package/dist-skill/docs/API/output/brep-export.md

@@ -0,0 +1,82 @@
+# BREP Export Parity
+
+This file tracks exact STEP/BREP export support. It is intentionally separated from the model-building docs because it describes output coverage, not the authoring surface itself.
+
+This table is the source of truth for ForgeCAD exact STEP/BREP export support.
+
+Update it whenever:
+- a Forge operation becomes exactly exportable
+- support becomes partial or regresses
+- a planned feature moves to implemented
+
+## Current Backend
+
+- Export executor: `uv run cli/forge-brep-export.py`
+- Compiler target: `cadquery-occt`
+- Exact kernel backend: CadQuery on OpenCascade
+- Default export policy: exact-subset only, never silent mesh-to-fake-BREP conversion
+- Optional CLI fallback: `--allow-faceted` exports closed mesh solids as explicit faceted OCCT solids for STEP/BREP; this is not exact replay
+
+## Parity Table
+
+| Forge Feature | Status | Exact Export | Notes |
+| --- | --- | --- | --- |
+| `box()` | Supported | Yes | Native OCCT solid replay |
+| `cylinder()` | Supported | Yes | Straight cylinder and cone-style `radiusTop` replay |
+| `sphere()` | Supported | Yes | Native OCCT solid replay |
+| `rect()` | Supported | Yes | As a profile for supported extrude/revolve flows |
+| `circle2d()` | Supported | Yes | As a profile for supported extrude/revolve flows |
+| `roundedRect()` | Supported | Yes | Replayed as an exact rounded wire/profile |
+| `rect(...).translate()` | Supported | Yes | Recorded as profile transforms |
+| `circle2d(...).translate()` | Supported | Yes | Recorded as profile transforms |
+| `roundedRect(...).translate()` | Supported | Yes | Recorded as profile transforms |
+| `rect(...).rotate()` | Supported | Yes | Recorded as profile transforms |
+| `circle2d(...).rotate()` | Supported | Yes | Recorded as profile transforms |
+| `roundedRect(...).rotate()` | Supported | Yes | Recorded as profile transforms |
+| `rect/circle/roundedRect.scale(...)` | Supported | Yes | Recorded as exact affine profile transforms |
+| `polygon()` / `ngon()` / polygon-backed `ellipse()` / `star()` | Supported | Yes | Replayed as exact line-segment profiles from recorded point loops |
+| `slot()` | Supported | Yes | Built from exact rect/circle booleans |
+| Sketch booleans (`union2d`, `difference2d`, `intersection2d`) | Supported | Yes | Only when every child profile is exact-exportable |
+| `rect/circle/roundedRect.extrude(height)` | Supported | Yes | `twist` / `divisions` must be absent |
+| `rect/circle/roundedRect.extrude(height, { scaleTop })` | Supported | Yes | Replayed as exact lofts; sketch booleans are decomposed into 3D booleans when needed |
+| `rect/circle/roundedRect.revolve(degrees)` | Supported | Yes | Replayed around Forge's revolve axis convention |
+| `Sketch.offset(delta, 'Round')` | Partial | Yes | Exact round-offset replay for exact-exportable profiles; `Square` / `Miter` still drop the plan |
+| `shape.translate()` | Supported | Yes | Recorded as exact solid transform |
+| `shape.rotate(x, y, z)` | Supported | Yes | Euler replay only |
+| `shape.scale(v)` | Supported | Yes | Recorded as an exact affine solid transform when every scale factor is finite and non-zero |
+| `rotateAround(...)` | Supported | Yes | Exact arbitrary-axis rotation is recorded with axis + pivot |
+| `pointAlong(...)` | Supported | Yes | Replayed via exact arbitrary-axis rotation from Forge's +Z axis |
+| `mirror(...)` | Supported | Yes | Replayed as an exact mirror transform across the origin plane normal |
+| `Shape.transform(matrix)` | Partial | Yes | Rigid affine subset only: orthonormal rotation + translation; scale/shear/perspective still unsupported |
+| `union()` | Supported | Yes | Only when every operand is exact-exportable |
+| `difference()` | Supported | Yes | Only when every operand is exact-exportable |
+| `intersection()` | Supported | Yes | Only when every operand is exact-exportable |
+| `split(cutter)` | Supported | Yes | Replayed as the exact pair `intersection(base, cutter)` and `difference(base, cutter)` when both operands are exact-exportable |
+| Returned multi-object scene | Supported | Yes | Exported as a STEP/BREP compound |
+| Returned mixed sketch + solid scene | Supported | Yes | Exact solids export; sketch-only objects are skipped with a warning |
+| Sketch `mirror()` | Supported | Yes | Recorded as an exact profile reflection across the origin line normal |
+| `loft()` | Partial | Yes | Forge now records loft intent in the compile graph and exports compatible section stacks through CadQuery/OCCT lofting, but runtime preview remains sampled/level-set and some mixed-topology stacks can still exceed OCCT loft compatibility |
+| `sweep()` | Partial | Yes | Forge now records sweep intent in the compile graph and exports compile-covered profiles along the canonical sampled polyline path; runtime preview remains sampled/level-set and `Curve3D` paths export through that sampled path representation |
+| `levelSet()` | Unsupported | No | Mesh/SDF output by design |
+| `smoothOut()` / `refine*()` / `simplify()` | Unsupported | No | Mesh post-processing, not exact BREP |
+| `warp()` | Unsupported | No | Deformation is mesh-domain today |
+| `hull3d()` / `Shape.hull()` / `hull2d()` / `Sketch.hull()` | Partial | No | Hull intent is now preserved in the Forge compile graph and reported explicitly, but there is still no exact convex-hull OCCT replay; `--allow-faceted` can export closed hull solids as faceted geometry |
+| `trimByPlane()` / `splitByPlane()` | Supported | Yes | Replayed through an exact plane half-space trim in CadQuery/OCCT; `splitByPlane()` lowers to the pair of positive-side and opposite-side trims |
+| `Shape.hole()` | Partial | Yes | Circular through/blind holes plus counterbores, countersinks, and planar `upToFace` termination on supported face-query targets now replay exactly; patterned, drafted/two-sided, threaded, and combined counterbore+countersink workflows are still outside the defended subset |
+| `Shape.cutout()` | Partial | Yes | Sketch must already be placed with `onFace(...)`; blind/through and planar `upToFace` cut extents on defended face-query targets stay exact, but drafted, two-sided, and pattern-owned cut workflows are still unsupported |
+| `sheetMetal(...).folded()` / `sheetMetal(...).flatPattern()` | Supported | Yes | Compiler-owned v1 sheet-metal subset: base panel, up to four `90°` edge flanges, explicit thickness/radius/K-factor, rectangular corner reliefs, and planar panel/flange cutouts all replay exactly from one semantic model; arbitrary solid conversion, hems, jogs, lofted bends, bend cutouts, and nonuniform thickness remain unsupported |
+| `projectToPlane()`-driven downstream features | Partial | Yes | Exact replay is supported when the source reduces to one defended planar basis: straight placed extrusions, compatible shell/hole/cut descendants, and compatible boolean unions on matching parallel target planes; boolean difference/intersection, trim/fillet/chamfer silhouette changes, and non-parallel bases still reject with diagnostics |
+| `Shape.shell(thickness, { openFaces })` | Partial | Yes | Compiler-owned shell v1 rewrites compatible `box()`, `cylinder()`, and straight `extrude()` bases plus rigid transforms into exact boolean/extrude/cylinder plans; tapered extrudes, scale transforms, and general boolean/revolve/loft/sweep/hull/trim bases are still unsupported |
+| `filletEdge()` / `chamferEdge()` | Partial | Yes | Compiler-owned tracked-edge subset: vertical edges from compile-covered `box()` bodies and `rectangle(...).extrude(...)` flows, plus preserved propagated sibling edges after earlier supported edge-finish rewrites when a later supported boolean union still records one defended lineage; shell, hole/cut, boolean difference/intersection, unsupported unions, and the already-finished merged edge itself are still outside the defended exact subset |
+| `TrackedShape` topology preservation | Partial | Synthetic only | Export succeeds for supported base solids, but named topology is not written to STEP/BREP |
+| Colors/materials in STEP/BREP | Partial | STEP only | Scene-object colors are written to STEP via CadQuery assembly export; `.brep` remains geometry-only |
+| STEP assembly structure/BOM metadata | Partial | Names only | STEP export writes a flat scene-object assembly to preserve names/colors; Forge assembly/BOM metadata is still not exported |
+
+The current defended exact subset is exercised by the ordinary-parts corpus in [`examples/compiler-corpus/README.md`](../../../../examples/compiler-corpus/README.md).
+
+## Planned Expansion Order
+
+1. Exact provenance-preserving replay for library helpers such as `lib.elbow()`, `lib.bolt()`, and related fastener/tube builders
+2. Safe exact affine scale replay where OCCT can preserve exact solids, especially scaled-sphere / pad workflows
+3. Broader exact OCCT-native feature coverage where BREP matters most: wider `shell()` coverage, broader fillet/chamfer coverage, richer face-driven feature ops
+4. Optional STEP product structure and metadata export

package/dist-skill/docs/API/output/dimensions.md

@@ -0,0 +1,62 @@
+# Dimension Annotations
+
+Dimension annotations are visual callouts used in the viewport and report export.
+They are not constraints and do not change geometry, so they live outside the core model-building docs.
+
+## `dim(from, to, opts?)`
+
+Add a dimension between two points.
+
+**Parameters:**
+- `from` (`[number, number] | [number, number, number] | Point2D`)
+- `to` (`[number, number] | [number, number, number] | Point2D`)
+- `opts` (optional):
+  - `offset` (number, default `10`)
+  - `label` (string)
+  - `color` (string hex, for example `"#ffaa44"`)
+  - `component` (`string | string[]`) - explicit report ownership by returned object name
+  - `currentComponent` (boolean) - bind to the owning returned component instance
+
+```javascript
+const w = 120;
+const h = 60;
+const plate = box(w, 30, h, true);
+
+dim([-w / 2, 0, 0], [w / 2, 0, 0], { label: "Width" });
+dim([0, 0, -h / 2], [0, 0, h / 2], { label: "Height", offset: 14 });
+
+return plate;
+```
+
+Ownership examples:
+
+```javascript
+dim([0, 0, 0], [0, 80, 0], {
+  label: "Leg Width",
+  currentComponent: true,
+});
+
+dim([0, 0, 0], [0, 0, 18], {
+  label: "Top Gap",
+  component: "Tabletop",
+});
+```
+
+## `dimLine(line, opts?)`
+
+Add a dimension along a `Line2D`.
+
+```javascript
+const a = point(0, 0);
+const b = point(100, 0);
+dimLine(line(a, b), { label: "Span", offset: -8 });
+```
+
+## Ownership Rules (Report Pages)
+
+- Use `currentComponent: true` when authoring imported parts and you want deterministic ownership by the calling instance.
+- Use `component: "Part Name"` to route a dimension to another named returned object.
+- If multiple owners are bound, the dimension is shared and appears on the assembly overview page.
+- If no ownership is set, report export attempts automatic ownership via endpoint-in-bbox inference.
+
+See `examples/api/dimensioned-bracket.forge.js` for baseline usage.

package/dist-skill/docs/API/runtime/viewport.md

@@ -0,0 +1,229 @@
+# Viewport Runtime APIs
+
+These APIs affect the viewer and scene presentation. They do not change the underlying model geometry contract, so they are not part of the required model-building reading set.
+
+## `cutPlane(name, normal, offsetOrOptions?, options?)`
+
+Define a named section plane for inspection.
+
+**Parameters:**
+- `name` (string) - label shown in the viewport controls
+- `normal` (`[number, number, number]`) - direction toward the clipped side
+- `offsetOrOptions` (number or object, optional):
+  - number: plane offset from origin along `normal`
+  - object: `{ offset?: number, exclude?: string | string[] }`
+- `options` (object, optional; used with numeric offset):
+  - `exclude` (`string | string[]`) - returned object `name` values to keep uncut
+
+**Returns:** `void`
+
+```javascript
+const cutZ = param("Cut Height", 10, { min: -50, max: 50, unit: "mm" });
+
+cutPlane("Inspection", [0, 0, 1], cutZ, {
+  exclude: ["Probe", "Fasteners"],
+});
+```
+
+Notes:
+- planes are registered per script run
+- viewport toggle state persists across parameter changes
+- clipping is applied to returned named objects, so `exclude` only works when names are stable
+- newly exposed section faces render with a hatched overlay; pre-existing coplanar boundary faces are left unhatched
+
+## `explodeView(options?)`
+
+Override how the viewport explode slider offsets returned objects.
+
+Explode offsets are resolved from the returned object tree, not from a flat list.
+In `radial` mode each node follows its parent branch direction, then adds a smaller
+local fan from the immediate parent/subassembly center, so nested assemblies peel
+apart level by level without losing their branch structure.
+
+In fixed-axis or fixed-vector modes, the branch itself follows that axis/vector, but
+nested descendants fan out perpendicular to the branch by default so deep trees do
+not keep stacking farther along the same axis.
+
+By default this is container-oriented: named groups/subassemblies advance along the
+tree, while plain leaves inside a group stay much closer and mostly fan locally
+around their parent cluster unless you override them explicitly.
+
+**Parameters:**
+- `enabled` (boolean) - disable explode offsets for this script when `false`
+- `amountScale` (number) - multiply the UI explode amount
+- `stages` (number[]) - per-depth multipliers (depth 1 = first level, defaults to `1, 1/2, 1/3, ...`)
+- `mode` (`'radial' | 'x' | 'y' | 'z' | [x, y, z]`) - default explode direction
+- `axisLock` (`'x' | 'y' | 'z'`) - optional global axis lock
+- `byName` (`Record<string, { stage?, direction?, axisLock? }>`)- per-object overrides keyed by returned object `name`
+- `byPath` (`Record<string, { stage?, direction?, axisLock? }>`)- per-tree-path overrides using slash-separated object tree paths such as `"Drive/Shaft"`
+
+**Returns:** `void`
+
+```javascript
+explodeView({
+  amountScale: 1.2,
+  stages: [0.35, 0.8],
+  mode: 'radial',
+  byPath: {
+    "Drive/Shaft": { direction: [1, 0, 0], stage: 1.6 },
+  },
+});
+```
+
+## `jointsView(options?)`
+
+Register viewport-only mechanism controls that animate returned objects without rerunning the script.
+
+Use this when you want interactive articulation in the viewer but the geometry itself stays fixed.
+
+Animation values are interpolated linearly between keyframes. Forge does **not**
+auto-wrap revolute values across `-180/180` or `0/360` for you, because doing
+that globally would break intentional multi-turn tracks.
+
+**Key options:**
+- `enabled`
+- `joints`: `{ name, child, parent?, type?, axis?, pivot?, min?, max?, default?, unit? }[]`
+- `couplings`: `{ joint, terms, offset? }[]`
+- `animations`: `{ name, duration?, loop?, continuous?, keyframes }[]`
+- `defaultAnimation`
+
+```javascript
+jointsView({
+  joints: [
+    {
+      name: "Shoulder",
+      child: "Upper Arm",
+      parent: "Base",
+      type: "revolute",
+      axis: [0, -1, 0],
+      pivot: [0, 0, 46],
+      min: -30,
+      max: 110,
+      default: 15,
+    },
+  ],
+  animations: [
+    {
+      name: "Walk Cycle",
+      duration: 1.6,
+      loop: true,
+      keyframes: [
+        { at: 0.0, values: { "Shoulder": 20 } },
+        { at: 0.5, values: { "Shoulder": -10 } },
+        { at: 1.0, values: { "Shoulder": 20 } },
+      ],
+    },
+  ],
+});
+```
+
+`continuous: true` is for looping tracks that should keep accumulating across
+cycles instead of snapping back to the first keyframe each time. Use it for
+monotonic multi-turn drives such as `0 -> 360 -> 720`.
+
+### Animation continuity for revolute joints
+
+If an animation channel comes from `atan2(...)`, `normalizeAngleDeg(...)`, or
+any other wrapped angle source, keep the sampled keyframes continuous before
+passing them to `jointsView()`.
+
+Bad branch-cut sample stream:
+
+```javascript
+keyframes: [
+  { at: 0.48, values: { "Power Rod": -171 } },
+  { at: 0.50, values: { "Power Rod": -180 } },
+  { at: 0.52, values: { "Power Rod": 171 } },
+]
+```
+
+That `-180 -> 171` jump is interpreted literally and the viewer will spin the
+part the long way around.
+
+Good continuous sample stream:
+
+```javascript
+keyframes: [
+  { at: 0.48, values: { "Power Rod": -171 } },
+  { at: 0.50, values: { "Power Rod": -180 } },
+  { at: 0.52, values: { "Power Rod": -189 } },
+]
+```
+
+Guidelines:
+- Keep high-speed multi-turn joints authored as continuous angles (`0`, `360`,
+  `720`, etc.).
+- Only unwrap channels that represent cyclic angles. Do not apply angle
+  unwrapping blindly to prismatic or other scalar values.
+- If you build sampled helper utilities, let them unwrap a named set of joints
+  instead of guessing from every numeric channel.
+
+## `viewConfig(options?)`
+
+Configure viewport helper visuals for the current script.
+
+Current support:
+- `jointOverlay.enabled`
+- joint overlay colors such as `axisColor`, `axisCoreColor`, `arcColor`, `zeroColor`
+- joint overlay sizing and tessellation controls such as `axisLengthScale`, `arcVisualLimitDeg`, `arcStepDeg`
+
+**Returns:** `void`
+
+```javascript
+viewConfig({
+  jointOverlay: {
+    axisColor: "#13dfff",
+    arcColor: "#ff7a1a",
+    axisLineRadiusScale: 0.03,
+    arcLineRadiusScale: 0.022,
+  },
+});
+```
+
+## `lib.explode(items, options?)`
+
+Apply deterministic exploded-view offsets to an assembly tree while preserving names, colors, and nesting.
+
+`radial` separation is branch-aware and parent-relative: each child follows the
+direction of its parent branch, then fans out locally inside that branch. This keeps
+subassemblies visually grouped while still letting their internals break apart.
+
+For non-radial fixed-axis or fixed-vector modes, nested descendants keep the branch
+offset but spread perpendicular to it by default.
+
+Default behavior is tree-like rather than flat: containers separate recursively,
+while unconfigured leaves inside a container use a smaller local fan so sibling parts
+stay visually associated with their parent group.
+
+Works with:
+- arrays of shapes/sketches/named items
+- nested `{ name, group: [...] }` structures
+- `ShapeGroup` outputs
+
+**Parameters:**
+- `items` (`ExplodeItem[] | ShapeGroup`)
+- `options`:
+  - `amount` (number)
+  - `stages` (number[])
+  - `mode` (`'radial' | 'x' | 'y' | 'z' | [x, y, z]`)
+  - `axisLock` (`'x' | 'y' | 'z'`)
+  - `byName`
+  - `byPath`
+
+Named items may also include:
+- `explode: { stage?, direction?, axisLock? }`
+
+**Returns:** same structure type as input, with translated geometry
+
+```javascript
+const explodeAmt = param("Explode", 0, { min: 0, max: 40, unit: "mm" });
+
+return lib.explode(assembly, {
+  amount: explodeAmt,
+  stages: [0.4, 0.8],
+  mode: 'radial',
+  byName: {
+    "Shaft": { direction: [1, 0, 0], stage: 1.4 },
+  },
+});
+```