forgecad 0.6.3 → 0.7.0

package/dist-skill/docs/API/sketch/regions.md

@@ -1,80 +0,0 @@
----
-skill-group: sketch
-skill-order: 11
----
-
-# Sketch Regions
-
-Decompose complex sketches into their individual filled areas. This is essential when a sketch operation produces multiple disconnected regions and you need to work with them independently.
-
-## `sketch.regions()`
-
-Decompose a sketch into its distinct filled regions, returned largest-first by area.
-
-A single sketch can contain several disconnected filled areas (e.g., two separate rectangles, a ring shape, or the result of a boolean that leaves islands). This method enumerates all top-level connected regions as independent `Sketch` objects.
-
-**Returns:** `Sketch[]` — Array of region sketches, sorted by area (largest first)
-
-```javascript
-// Two disconnected rectangles — get each one separately
-const pair = union2d(rect(40, 40), rect(40, 40).translate(60, 0));
-const [larger, smaller] = pair.regions();
-larger.extrude(10);
-smaller.extrude(5);
-
-// Ring shape — one region containing the ring
-const ring = circle2d(50).subtract(circle2d(30));
-const [ringRegion] = ring.regions();
-ringRegion.extrude(8);
-```
-
-## `sketch.region(seed)`
-
-Select the single filled region that contains a given 2D point. This lets you pick any enclosed area by pointing at it instead of sorting through all regions.
-
-**Parameters:**
-- `seed` (`[number, number]`) — A 2D point `[x, y]` strictly inside the desired region
-
-**Returns:** `Sketch` — The region containing the seed point
-
-**Throws:** If the seed is outside all regions, on a boundary edge, or inside a hole.
-
-```javascript
-// Donut — select the ring area at radius 40
-const donut = circle2d(50).subtract(circle2d(30));
-const ring = donut.region([40, 0]);
-ring.extrude(10);
-
-// Complex boolean result — pick a specific island
-const complex = union2d(rect(40, 40), rect(40, 40).translate(60, 0));
-const rightBox = complex.region([80, 20]);  // seed inside right box
-```
-
-> **Callout:** The seed point must be strictly inside the filled area — not on the boundary. If you're unsure where the regions are, use `.regions()` first to enumerate them. Each returned region has a `.bounds()` you can inspect.
-
-## Constrained Sketch Regions
-
-`ConstraintSketch` (from `constrainedSketch().solve()`) provides two additional methods for working with the line arrangement formed by its edges:
-
-### `cs.detectArrangement()`
-
-Enumerate all bounded regions formed by the non-construction line arrangement. Returns `Sketch[]` sorted largest-first.
-
-```javascript
-const sk = constrainedSketch();
-// ... add geometry and constraints ...
-const cs = sk.solve();
-const regions = cs.detectArrangement();
-regions[0].extrude(5);  // extrude the largest region
-```
-
-### `cs.detectArrangementRegion(seed)`
-
-Select a single arrangement region by seed point. Same semantics as `sketch.region(seed)` but operates on the constraint sketch's line arrangement (DCEL face detection).
-
-```javascript
-const region = cs.detectArrangementRegion([10, 10]);
-region.extrude(3);
-```
-
-> **Callout:** `detectArrangement()` and `detectArrangementRegion()` use the raw line/arc geometry from the constraint solver, not the boolean profile. This means construction lines are excluded and the regions are formed by the geometric arrangement of edges — useful when you need to select specific enclosed areas from a complex constrained sketch.

package/dist-skill/docs/API/sketch/text.md

@@ -1,108 +0,0 @@
----
-skill-group: sketch
-skill-order: 10
----
-
-# 2D Text
-
-Create filled text geometry from strings. Supports both the built-in **Forge Mono** geometric font and any **TTF/OTF font file** for professional typography. Text sketches can be extruded, engraved, or used anywhere a normal `Sketch` is accepted.
-
-## `text2d(content, options?)`
-
-Build a filled 2D `Sketch` from a text string.
-
-**Parameters:**
-- `content` (string) — The text to render
-- `options` (TextOptions, optional):
-  - `size` (number) — Cap height in model units. Default: `10`. All proportions scale with this.
-  - `letterSpacing` (number) — Extra space between characters in model units. Negative tightens. Default: `0`
-  - `align` (`'left' | 'center' | 'right'`) — Horizontal alignment relative to x = 0. Default: `'left'`
-  - `baseline` (`'baseline' | 'center' | 'top'`) — Vertical alignment relative to y = 0. Default: `'baseline'`
-  - `font` (string | Font) — Path to a TTF/OTF font file, or a pre-loaded Font object from `loadFont()`. When omitted, uses the built-in Forge Mono font.
-  - `flattenTolerance` (number) — Bezier curve flattening tolerance in model units (font mode only). Smaller = smoother curves. Default: 0.5% of size.
-
-**Returns:** `Sketch` — Filled 2D text geometry
-
-```javascript
-// Built-in geometric font (default)
-text2d('FORGE CAD', { size: 8 }).extrude(1.2);
-
-// Using a real font — professional typography with proper curves
-text2d('Hello World', { size: 10, font: '/path/to/Arial.ttf' }).extrude(1);
-
-// Pre-load font for reuse across multiple text calls
-const font = loadFont('/path/to/Arial Bold.ttf');
-text2d('Title', { size: 12, font }).extrude(1.5);
-text2d('Subtitle', { size: 8, font, align: 'center' }).extrude(0.8);
-
-// Centered label
-text2d('V 2.0', { size: 6, align: 'center', baseline: 'center' });
-
-// Engraved text on top face of a box
-const label = text2d('REV A', { size: 5, align: 'center', baseline: 'center' });
-const plate = box(60, 20, 5);
-return plate.subtract(label.onFace(plate, 'top', { protrude: -0.5 }).extrude(1));
-```
-
-### Font Options
-
-**Real fonts (TTF/OTF)** — Pass a file path or pre-loaded Font to the `font` option:
-- Professional typography with proper bezier curves
-- Full character set: uppercase, lowercase, accented characters, symbols
-- Automatic kerning between character pairs
-- Any TTF or OTF font file works
-
-**Built-in: Forge Mono** (default when no `font` option) —
-- **Style:** Geometric monoline sans-serif, squared-off and futuristic
-- **Inspired by:** Eurostile, Chakra Petch
-- **Characteristics:** Uniform stroke weight, flat open ends, no serifs
-- **Character set:** Uppercase A–Z, digits 0–9, punctuation. Lowercase maps to uppercase
-- No external font files needed — every character is constructed from geometric primitives
-
-## `loadFont(source, cacheKey?)`
-
-Pre-load and cache a font for reuse across multiple `text2d()` calls.
-
-**Parameters:**
-- `source` (string | ArrayBuffer) — File path to a TTF/OTF font, or raw font data as ArrayBuffer
-- `cacheKey` (string, optional) — Cache key when passing ArrayBuffer
-
-**Returns:** Font object (pass to `text2d`'s `font` option)
-
-```javascript
-const font = loadFont('/System/Library/Fonts/Supplemental/Arial.ttf');
-text2d('Line 1', { size: 8, font }).extrude(1);
-text2d('Line 2', { size: 8, font }).extrude(1);
-```
-
-## `textWidth(content, options?)`
-
-Measure the rendered width of a string without creating geometry. Useful for layout calculations.
-
-**Parameters:**
-- `content` (string) — The text to measure
-- `options` (object, optional):
-  - `size` (number) — Cap height in model units. Default: `10`
-  - `letterSpacing` (number) — Extra spacing. Default: `0`
-
-**Returns:** `number` — Width of the rendered text in model units
-
-```javascript
-const label = 'SERIAL: 001';
-const w = textWidth(label, { size: 6 });
-
-// Create a plate that fits the text with padding
-const plate = box(w + 10, 12, 2);
-const text = text2d(label, { size: 6, align: 'center', baseline: 'center' })
-  .translate(w / 2 + 5, 6, 0);
-```
-
-## Alignment Quick Reference
-
-| `align` | `baseline` | Origin position |
-|---------|-----------|----------------|
-| `'left'` | `'baseline'` | Bottom-left of first character (default) |
-| `'center'` | `'center'` | Dead center of text block |
-| `'right'` | `'top'` | Top-right corner |
-
-The origin is at `(0, 0)` — alignment controls where the text sits relative to that point.

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

@@ -1,65 +0,0 @@
----
-skill-group: sketch
-skill-order: 4
----
-
-# 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 sketch's bounding-box center.
-
-```javascript
-const rotated = rect(50, 30).rotate(45);
-```
-
-### `.rotateAround(degrees, pivot)`
-Rotates around a specific point instead of the default center pivot.
-
-**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 from its bounding-box center.
-
-**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, passing through the sketch's bounding-box center.
-
-**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/toolbox/fasteners.md

@@ -1,129 +0,0 @@
----
-skill-group: toolbox
-skill-order: 1
----
-
-# Toolbox — Fastener Library
-
-Pre-built ISO metric fastener geometry available via `lib.*` in any ForgeCAD script.
-
-## Supported catalog
-
-This is the initial, intentionally small catalog. Coverage outside these items is not guaranteed.
-
-| Family | Sizes | Standard |
-|--------|-------|----------|
-| Hex bolt (`lib.bolt`) | M4 – M10 (parametric) | ISO 4762 lookalike |
-| Hex nut (`lib.nut`) | M4 – M10 (parametric) | ISO 4032 lookalike |
-| Flat washer (`lib.washer`) | M2, M2.5, M3, M4, M5, M6, M8, M10 | DIN 125-A |
-| Fastener hole (`lib.fastenerHole`) | M2, M2.5, M3, M4, M5, M6, M8, M10 | ISO metric fits |
-| Fastener set (`lib.fastenerSet`) | M2 – M10 | Combines all of the above |
-
-Sizes outside the table will throw. Extend `METRIC_HOLE_TABLE` / `WASHER_TABLE` in `library.ts` when adding new sizes.
-
-## `lib.washer(size, options?)`
-
-Returns a flat ring washer (DIN 125-A by default) centered at the origin, thickness along Z.
-
-```javascript
-const w = lib.washer("M5");
-// outer dia 10 mm, inner dia 5.3 mm, thickness 1 mm
-```
-
-**Parameters**
-
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `size` | `MetricSize` | required | ISO metric thread size string, e.g. `"M6"` |
-| `options.standard` | `'din-125-a'` | `'din-125-a'` | Washer standard (only DIN 125-A for now) |
-| `options.segments` | `number` | `48` | Circle segment count |
-
-**DIN 125-A dimensions**
-
-| Size | Inner dia (mm) | Outer dia (mm) | Thickness (mm) |
-|------|---------------|----------------|----------------|
-| M2   | 2.2 | 5.0  | 0.3 |
-| M2.5 | 2.7 | 6.0  | 0.5 |
-| M3   | 3.2 | 7.0  | 0.5 |
-| M4   | 4.3 | 9.0  | 0.8 |
-| M5   | 5.3 | 10.0 | 1.0 |
-| M6   | 6.4 | 12.0 | 1.6 |
-| M8   | 8.4 | 17.0 | 1.6 |
-| M10  | 10.5 | 21.0 | 2.0 |
-
-## `lib.fastenerSet(size, boltLength, options?)`
-
-Returns all geometry needed for one complete bolted joint: bolt, nut, washers, and hole cutters — un-positioned so you can place them freely.
-
-```javascript
-const hw = lib.fastenerSet("M5", 20);
-
-// Cut holes in two plates
-const topPlate = box(60, 40, 8, true)
-  .subtract(hw.clearanceHole.translate(15, 10, 0));
-const botPlate = box(60, 40, 8, true).translate(0, 0, -16)
-  .subtract(hw.tappedHole.translate(15, 10, -8));
-
-// Place hardware
-return [
-  { name: "Top Plate", shape: topPlate, color: "#9ab4cc" },
-  { name: "Bot Plate", shape: botPlate, color: "#b0b8c8" },
-  { name: "Bolt",  shape: hw.bolt.translate(15, 10, 4),  color: "#aaaaaa" },
-  { name: "Nut",   shape: hw.nut.translate(15, 10, -19), color: "#888888" },
-];
-```
-
-**Parameters**
-
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `size` | `MetricSize` | required | ISO metric thread size |
-| `boltLength` | `number` | required | Shaft length in mm (head excluded) |
-| `options.washerUnderHead` | `boolean` | `true` | Include a washer shape for under the head |
-| `options.washerUnderNut` | `boolean` | `true` | Include a washer shape for under the nut |
-| `options.fit` | `FastenerFit` | `'normal'` | Clearance hole fit: `close`, `normal`, `loose`, or `tap` |
-| `options.segments` | `number` | `36` | Thread/circle segment count |
-
-**Result fields**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `bolt` | `Shape` | Head top at z=0, shaft along −Z by `boltLength` |
-| `nut` | `Shape` | Hex nut centered at z=0 |
-| `washerUnderHead` | `Shape \| null` | Flat washer centered at z=0 |
-| `washerUnderNut` | `Shape \| null` | Flat washer centered at z=0 |
-| `clearanceHole` | `Shape` | Cutter cylinder for through-plate clearance, centered at z=0 |
-| `tappedHole` | `Shape` | Cutter cylinder for tap-drill hole, centered at z=0 |
-| `dims` | `FastenerSetDimensions` | Reference dimensions for placement and BOM |
-
-**`FastenerSetDimensions` fields**
-
-| Field | Description |
-|-------|-------------|
-| `size` | Thread size string |
-| `nominalDiameter` | Numeric thread diameter (mm) |
-| `boltLength` | As specified |
-| `clearanceDia` | Clearance hole diameter for chosen fit (mm) |
-| `tapDia` | Tap-drill diameter (mm) |
-| `nutAcrossFlats` | Hex nut width across flats (mm) |
-| `nutHeight` | Nut height (mm) |
-| `washerOuterDia` / `washerInnerDia` / `washerThickness` | DIN 125-A washer dimensions (mm) |
-
-## `lib.fastenerHole(opts)`
-
-Lower-level helper that returns only a hole cutter (cylinder ± counterbore/countersink). Supports M2–M10 with four fit classes and optional counterbore/countersink geometry. See the full API reference for details.
-
-## Pairing table
-
-Use this to pick the right cutter fit for your workflow:
-
-| Fit | Hole diameter | Use when |
-|-----|--------------|----------|
-| `close` | ≈ nominal + 0.2 mm | Press-location or close-tolerance slotting |
-| `normal` | ≈ nominal + 0.5 mm | Standard through-bolt clearance (default) |
-| `loose` | ≈ nominal + 1–2 mm | Adjustment slots or misaligned patterns |
-| `tap` | ISO tap drill | Tapped hole in the mating part |
-
-## Example
-
-See [`examples/toolbox/bolted-joint.forge.js`](../../../../examples/toolbox/bolted-joint.forge.js) for a complete two-plate bolted assembly with BOM and exploded view.