forgecad 0.6.3 → 0.8.0

package/dist-skill/docs/API/core/edge-queries.md

@@ -1,130 +0,0 @@
----
-skill-group: core
-skill-order: 4
----
-
-# Edge Queries
-
-Select and operate on edges of any 3D shape by geometric properties — direction, position, angle, convexity. This is the primary way to apply fillets and chamfers to specific edges without needing tracked topology.
-
-## Selecting Edges
-
-### `selectEdges(shape, query?)`
-
-Find all edges that match a geometric query. Edges are extracted from the mesh as sharp features (dihedral angle > 1°).
-
-**Parameters:**
-- `shape` (Shape | TrackedShape) — The solid to query
-- `query` (EdgeQuery, optional) — Filters to apply (see below)
-
-**Returns:** `EdgeSegment[]` — Matching edge segments
-
-### `selectEdge(shape, query?)`
-
-Find the single best-matching edge. When `near` is specified, returns the closest match. Throws if no edges match.
-
-**Parameters:** Same as `selectEdges()`
-
-**Returns:** `EdgeSegment` — The best-matching edge
-
-**Throws:** If no edges match the query
-
-### EdgeQuery Filters
-
-| Filter | Type | Description |
-|--------|------|-------------|
-| `near` | `[x, y, z]` | Sort by proximity to this point (closest first) |
-| `parallel` | `[x, y, z]` | Edge direction ~parallel to this vector |
-| `perpendicular` | `[x, y, z]` | Edge direction ~perpendicular to this vector |
-| `convex` | `boolean` | Only convex (outside corner) edges |
-| `concave` | `boolean` | Only concave (inside corner) edges |
-| `minAngle` | `number` | Minimum dihedral angle (degrees) |
-| `maxAngle` | `number` | Maximum dihedral angle (degrees) |
-| `minLength` | `number` | Minimum edge length |
-| `maxLength` | `number` | Maximum edge length |
-| `within` | `BoundingRegion` | Edge midpoint must be inside this box |
-| `atZ` | `number` | Edge midpoint Z ≈ this value (shorthand for `within`) |
-| `tolerance` | `number` | Position tolerance. Default: `1.0` |
-| `angleTolerance` | `number` | Angular tolerance in degrees. Default: `10` |
-
-**BoundingRegion:** `{ xMin?, xMax?, yMin?, yMax?, zMin?, zMax? }` — any combination of axis bounds.
-
-```javascript
-const part = box(50, 30, 20);
-
-// All vertical edges
-const verticals = selectEdges(part, { parallel: [0, 0, 1] });
-
-// Top-face edges only
-const topEdges = selectEdges(part, { atZ: 20 });
-
-// Nearest convex edge to a point
-const nearest = selectEdge(part, { near: [50, 30, 20], convex: true });
-```
-
-### `coalesceEdges(segments, tolerance?)`
-
-Merge collinear edge segments into longer logical edges. Mesh tessellation often splits a single geometric edge into multiple short segments — this function recombines them.
-
-**Parameters:**
-- `segments` (EdgeSegment[]) — Edge segments to merge
-- `tolerance` (number) — Collinearity tolerance. Default: `0.01`
-
-**Returns:** `EdgeSegment[]` — Merged edge segments
-
-```javascript
-const edges = selectEdges(shape, { parallel: [0, 0, 1] });
-const merged = coalesceEdges(edges);
-// merged has fewer, longer edges
-```
-
-## Applying Features
-
-### `filletEdgeSegment(shape, segment, radius, segments?)`
-
-Apply a fillet (rounded edge) to a mesh-selected edge. Works on any straight edge — not limited to tracked topology.
-
-**Parameters:**
-- `shape` (Shape | TrackedShape) — The solid to modify
-- `segment` (EdgeSegment) — From `selectEdge()` / `selectEdges()`
-- `radius` (number) — Fillet radius
-- `segments` (number) — Arc segments. Default: `16`
-
-**Returns:** `Shape` — New shape with fillet applied
-
-### `chamferEdgeSegment(shape, segment, size)`
-
-Apply a chamfer (beveled edge) to a mesh-selected edge.
-
-**Parameters:**
-- `shape` (Shape | TrackedShape) — The solid to modify
-- `segment` (EdgeSegment) — From `selectEdge()` / `selectEdges()`
-- `size` (number) — Chamfer distance from edge
-
-**Returns:** `Shape` — New shape with chamfer applied
-
-```javascript
-const part = box(50, 30, 20);
-
-// Fillet all top edges
-const topEdges = selectEdges(part, { atZ: 20, perpendicular: [0, 0, 1] });
-let result = part;
-for (const edge of coalesceEdges(topEdges)) {
-  result = filletEdgeSegment(result, edge, 2);
-}
-
-// Chamfer a single bottom edge
-const bottomEdge = selectEdge(part, { near: [25, 0, 0], atZ: 0 });
-result = chamferEdgeSegment(result, bottomEdge, 1.5);
-```
-
-> **Callout:** These functions work alongside the tracked-topology `filletEdge()` and `chamferEdge()` (which take an `EdgeRef` from a `TrackedShape`). Use edge queries when you don't have tracked topology — e.g., after boolean operations that strip topology, or on imported shapes.
-
-## Comparison: Edge Queries vs. Tracked Topology
-
-| Approach | Input | When to use |
-|----------|-------|-------------|
-| `filletEdge(shape, edge, radius)` | `EdgeRef` from `TrackedShape` | Simple boxes/cylinders, before booleans |
-| `filletEdgeSegment(shape, segment, radius)` | `EdgeSegment` from `selectEdge()` | After booleans, complex shapes, imported geometry |
-
-Both produce the same result — the query-based approach is more flexible but requires describing the edge geometrically instead of by name.

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

@@ -1,122 +0,0 @@
----
-skill-group: core
-skill-order: 2
----
-
-# Parameters
-
-ForgeCAD scripts declare parameters that automatically generate UI controls (sliders, checkboxes, dropdowns). Parameters make models interactive — change a value, see the geometry update.
-
-## `param(name, default, options?)`
-
-Declare a numeric parameter. Creates a slider in the UI.
-
-**Parameters:**
-- `name` (string) — Display name in the parameter panel
-- `default` (number) — Initial value
-- `options` (object, optional):
-  - `min` (number) — Minimum slider value. Default: `0`
-  - `max` (number) — Maximum slider value. Default: `default * 4`
-  - `step` (number) — Slider increment. Auto-calculated if omitted
-  - `unit` (string) — Display unit label, e.g. `"mm"`, `"°"`, `"%"`
-  - `integer` (boolean) — Round to whole numbers; step defaults to `1`. Use for counts, sides, quantities
-  - `reverse` (boolean) — Invert the slider direction
-
-**Returns:** `number` — Current parameter value (default or overridden)
-
-```javascript
-const width = param("Width", 50);
-const angle = param("Angle", 45, { min: 0, max: 180, unit: "°" });
-const thick = param("Thickness", 2, { min: 0.5, max: 10, step: 0.5, unit: "mm" });
-const sides = param("Sides", 6, { min: 3, max: 12, integer: true });
-```
-
-## `boolParam(name, default)`
-
-Declare a boolean parameter. Creates a checkbox in the UI.
-
-**Parameters:**
-- `name` (string) — Display name in the parameter panel
-- `default` (boolean) — Initial checkbox state
-
-**Returns:** `boolean` — Current boolean value
-
-```javascript
-const showHoles = boolParam("Show Holes", true);
-const centerOrigin = boolParam("Center at Origin", false);
-
-// Conditional geometry
-const plate = box(100, 60, 5);
-if (showHoles) {
-  return difference(plate, cylinder(10, 5).translate(50, 30, 0));
-}
-return plate;
-```
-
-> **Callout:** `boolParam` was added to complement `param()` for on/off toggles. It renders as a checkbox rather than a slider. Internally the boolean is stored as `0`/`1`.
-
-## `choiceParam(name, default, choices)`
-
-Declare a string choice parameter. Creates a dropdown in the UI.
-
-**Parameters:**
-- `name` (string) — Display name in the parameter panel
-- `default` (string) — Initial selected label. Must exactly match one of the entries in `choices`
-- `choices` (string[]) — Ordered list of allowed labels shown in the dropdown
-
-**Returns:** `string` — The currently selected choice label
-
-```javascript
-const panStyle = choiceParam("Pan Style", "frying-pan", [
-  "frying-pan",
-  "saute-pan",
-  "saucepan",
-  "wok",
-]);
-
-const finish = choiceParam("Finish", "stainless", [
-  "stainless",
-  "cast-iron",
-  "copper",
-]);
-
-if (panStyle === "wok") {
-  return buildWok();
-}
-return buildPan();
-```
-
-Use `choiceParam()` when a numeric slider would hide intent. It keeps scripts readable and makes CLI/import overrides self-describing.
-
-## Parameter Overrides
-
-When importing files with `require()`, you can override their parameters via an optional second argument:
-
-```javascript
-const bracket = require("./bracket.forge.js", { Width: 80, Thickness: 3 });
-const logo = require("./logo.forge.js", { Scale: 0.5 });
-const pan = require("./pan.forge.js", { "Pan Style": "wok", "Show Lid": 0 });
-```
-
-You can also override parameters from the CLI:
-
-```bash
-forgecad run model.forge.js --param "Wall Thickness=3"
-forgecad run model.forge.js --param "Show Lid=0"
-forgecad run model.forge.js --param "Pan Style=wok"
-```
-
-Override keys must match the `name` string passed to `param()`, `boolParam()`, or `choiceParam()` in the script.
-
-- `param()` expects a number
-- `boolParam()` expects `1`/`0` or `true`/`false` semantics via the UI; in CLI/import overrides, use `1` for true and `0` for false
-- `choiceParam()` accepts either the string label or a numeric index, but the string label is recommended because it is clearer and more stable
-
-Use `importSvgSketch()` for SVG files (SVG import does not use param overrides).
-
-## Tips
-
-- **Avoid recomputation**: Parameters trigger a full script re-execution on every change. Keep expensive operations behind boolean guards when possible.
-- **Use `integer: true`** for discrete quantities (bolt count, polygon sides, array copies) — it prevents fractional values that would produce invalid geometry.
-- **Unit labels are cosmetic**: The `unit` option only affects the UI display; it does not convert values.
-- **Prefer `choiceParam()` for presets and named modes**: dropdown labels such as `"wok"` or `"saute-pan"` are easier to understand than numeric style ids.

package/dist-skill/docs/API/core/reserved-terms.md

@@ -1,137 +0,0 @@
----
-skill-group: core
-skill-order: 0
-skill-tiers: [standard, one-file]
----
-
-# Reserved Terms
-
-Every `.forge.js` script runs in a sandbox with these names pre-defined as globals.
-**Do not use any of these as variable, parameter, or function names** — your local
-definition will shadow the built-in and silently break things.
-
-## Module system
-
-`exports`, `module`, `require`, `__filename`, `__dirname`
-
-## Primitives (3D)
-
-`box`, `cylinder`, `sphere`, `torus`
-
-## Boolean operations (3D)
-
-`union`, `difference`, `intersection`
-
-## Boolean operations (2D)
-
-`union2d`, `difference2d`, `intersection2d`
-
-## Sketch primitives
-
-`rect`, `arcSlot`, `circle2d`, `roundedRect`, `polygon`, `polygonVertices`, `ngon`, `ellipse`, `slot`, `star`, `path`, `stroke`
-
-## 2D geometry classes
-
-`Point2D`, `Line2D`, `Circle2D`, `Rectangle2D`
-
-## Constrained sketch
-
-`point`, `line`, `circle`, `Constraint`, `constrainedSketch`
-
-## Angles and coordinates
-
-`degrees`, `polar`, `radians`
-
-## Patterns and layout
-
-`linearPattern`, `circularPattern`, `circularLayout`, `linearPattern2d`, `circularPattern2d`, `mirrorCopy`
-
-## 2D fillets and chamfers
-
-`fillet2d`, `filletCorners`, `filletEdge`, `chamfer2d`, `chamferEdge`
-
-## Routing
-
-`route`, `routePerimeter`
-
-## Curves and surfaces
-
-`arcBridgeBetweenRects`, `Curve3D`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `HermiteCurve3D`, `QuinticHermiteCurve3D`, `hermiteTransition`, `hermiteTransitionG2`, `transitionCurve`, `transitionSurface`, `transitionCurveFromPoints`, `connectEdges`, `variableSweep`, `surfacePatch`
-
-## Sheet metal
-
-`sheetMetal`, `SheetMetalPart`
-
-## Parameters
-
-`param`, `boolParam`, `choiceParam`
-
-## Core classes
-
-`sdf`, `Shape`, `Sketch`
-
-## Part library
-
-`lib`
-
-## Assembly and joints
-
-`joint`, `Transform`, `composeChain`, `assembly`, `Assembly`, `port`, `connector`, `Points`, `SolvedAssembly`, `bomToCsv`
-
-## Section and projection
-
-`faceProfile`, `intersectWithPlane`, `projectToPlane`
-
-## Edge and face queries
-
-`selectEdge`, `selectEdges`, `coalesceEdges`, `filletEdgeSegment`, `chamferEdgeSegment`
-
-## 3D fillets, chamfers, and edge features
-
-`fillet`, `chamfer`, `draft`, `offsetSolid`
-
-## Import
-
-`importSvgSketch`, `importMesh`
-
-## Text and fonts
-
-`text2d`, `textWidth`, `loadFont`
-
-## Dimensions and annotations
-
-`dim`, `dimLine`
-
-## Visualization
-
-`highlight`
-
-## Export and format
-
-`sketchToSvg`, `sketchToDxf`, `bom`, `sheetStock`, `robotExport`
-
-## Grouping
-
-`group`, `ShapeGroup`
-
-## Viewport and scene
-
-`console`, `cutPlane`, `explodeView`, `jointsView`, `viewConfig`, `scene`
-
-## Verification
-
-`verify`, `spec`
-
-## G-Code
-
-`gcode`, `GCodeBuilder`
-
-## Laser kit
-
-`flatPanel`, `flatPart`, `fingerJoint`, `tabSlot`, `laserKit`, `assemblyPreview`, `assemblyInstructions`, `formatInstructions`, `fingerJointProfile`, `tabSlotProfile`, `livingHingeProfile`, `snapFitProfile`, `lookupKerf`, `COMMON_KERFS`
-
-## Virtual module specifiers
-
-These strings can be used with `require()` to import all runtime globals as a module (useful in plain `.js` helper files):
-
-`"forgecad"`, `"@forge/runtime"`, `"@forgecad/runtime"`