forgecad 0.6.3 → 0.8.0

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

@@ -1,91 +0,0 @@
----
-skill-group: sketch
-skill-order: 5
----
-
-# Sketch Booleans
-
-2D boolean operations for combining, subtracting, and intersecting sketches.
-
-## Methods
-
-### `.add(...others)`
-Combines sketches (union). Accepts `sketch.add(a, b)` and `sketch.add([a, b])`.
-
-```javascript
-const combined = rect(50, 30).add(
-  circle2d(20).translate(25, 15),
-  ngon(6, 15).translate(40, 15)
-);
-```
-
-### `.subtract(...others)`
-Subtracts one or more sketches from this one. Accepts `sketch.subtract(a, b)` and `sketch.subtract([a, b])`.
-
-```javascript
-const plate = rect(100, 80);
-const hole = circle2d(10);
-const slotCut = rect(18, 8).translate(41, 36);
-const result = plate.subtract(hole.translate(25, 40), slotCut);
-```
-
-### `.intersect(...others)`
-Keeps only the area shared by every operand. Accepts `sketch.intersect(a, b)` and `sketch.intersect([a, b])`.
-
-```javascript
-const overlap = rect(50, 50).intersect(
-  circle2d(30).translate(25, 25),
-  rect(40, 20).translate(5, 15)
-);
-```
-
-## Functions
-
-### `union2d(...sketches)`
-Combines multiple sketches into one.
-
-```javascript
-const combined = union2d(
-  rect(50, 30),
-  circle2d(20).translate(25, 15),
-  ngon(6, 15).translate(75, 15)
-);
-```
-
-`union2d([a, b, c])` is also supported when your sketches are already in an array.
-
-### `difference2d(...sketches)`
-Subtracts sketches[1..n] from sketches[0].
-
-```javascript
-const plate = rect(100, 80);
-const hole1 = circle2d(10).translate(25, 40);
-const hole2 = circle2d(10).translate(75, 40);
-const result = difference2d(plate, hole1, hole2);
-```
-
-`difference2d([base, cutter1, cutter2])` works too.
-
-### `intersection2d(...sketches)`
-Keeps only the area where all sketches overlap.
-
-```javascript
-const overlap = intersection2d(
-  rect(50, 50),
-  circle2d(30).translate(25, 25)
-);
-```
-
-`intersection2d([a, b, c])` is also supported.
-
-## Performance Note
-
-The multi-argument functions (`union2d`, `difference2d`, `intersection2d`) use Manifold's batch operations internally, which are faster than chaining `.add()` / `.subtract()` calls one by one. Prefer them when combining many sketches.
-
-```javascript
-// Fast — single batch operation
-const combined = union2d(s1, s2, s3, s4, s5);
-
-// Slower — sequential pairwise operations
-const combined = s1.add(s2).add(s3).add(s4).add(s5);
-```

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

@@ -1,73 +0,0 @@
----
-skill-group: sketch
-skill-order: 1
----
-
-# Sketch Core
-
-The `Sketch` class is an immutable wrapper around Manifold's `CrossSection` that provides a chainable 2D API.
-
-## Class: Sketch
-
-Represents a 2D profile that can be transformed, combined with other sketches, or converted to 3D.
-
-### Color
-
-#### `.color(hex: string): Sketch`
-Set the display color of this sketch. Returns a new Sketch.
-
-```javascript
-const red = rect(50, 30).color('#ff0000');
-const blue = circle2d(25).color('#0066ff');
-```
-
-Colors are preserved through transforms and boolean operations.
-
-#### `.clone()` / `.duplicate()`
-Create an explicit duplicate of a sketch wrapper.
-
-```javascript
-const base = rect(50, 30);
-const a = base.clone();
-const b = base.duplicate().translate(60, 0);
-```
-
-### Query Methods
-
-#### `.area(): number`
-Returns the area of the sketch.
-
-```javascript
-const sq = rect(50, 50);
-console.log(sq.area()); // 2500
-```
-
-#### `.bounds()`
-Returns the bounding box: `{ min: [x, y], max: [x, y] }`.
-
-```javascript
-const c = circle2d(25);
-const b = c.bounds();
-// b.min ≈ [-25, -25], b.max ≈ [25, 25]
-```
-
-#### `.isEmpty(): boolean`
-Returns true if the sketch has no area.
-
-#### `.numVert(): number`
-Returns the number of vertices in the contour.
-
-#### `.toPolygons()`
-Returns raw polygon contours for rendering (internal use).
-
-## Type: Anchor
-
-Anchor points for positioning sketches:
-- `'center'` — geometric center
-- `'top-left'`, `'top-right'`, `'bottom-left'`, `'bottom-right'` — corners
-- `'top'`, `'bottom'`, `'left'`, `'right'` — edge midpoints
-
-## Dimensions
-
-Use `dim()` / `dimLine()` for visual measurement callouts and report annotations.
-See [../output/dimensions.md](../output/dimensions.md) for options and ownership behavior.

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

@@ -1,62 +0,0 @@
----
-skill-group: sketch
-skill-order: 8
----
-
-# Sketch Extrude & Revolve
-
-Convert 2D sketches into 3D shapes through extrusion or revolution. The sketch's color (if set) is carried over to the resulting Shape.
-
-If a sketch has been placed with [`onFace()`](sketch-on-face.md), extrusion follows that face normal instead of the global Z axis.
-
-## Methods
-
-### `.extrude(height, options?)`
-Extrudes sketch along Z axis.
-
-**Parameters:**
-- `height` (number) - Extrusion height
-- `options` (object, optional):
-  - `twist` (number) - Twist angle in degrees
-  - `divisions` (number) - Number of twist steps (needed for twist)
-  - `scaleTop` (number | [number, number]) - Scale factor at top
-  - `center` (boolean) - Center along Z axis
-
-**Returns:** `TrackedShape` (with faces: top, bottom, side)
-
-```javascript
-const simple = rect(50, 30).extrude(10);
-
-const twisted = ngon(6, 20).extrude(60, {
-  twist: 90,
-  divisions: 32
-});
-
-const tapered = circle2d(20).extrude(50, {
-  scaleTop: 0.5
-});
-
-const badge = roundedRect(28, 10, 2, true)
-  .onFace(box(120, 60, 40, true), 'front', { v: 8 })
-  .extrude(2);
-```
-
-### `.revolve(degrees?, segments?)`
-Revolves sketch around Y axis (becomes Z in result).
-
-Performance tip: prefer `revolve()` over `loft()` whenever the part is rotationally symmetric. Loft is for profile interpolation and is substantially heavier.
-
-**Parameters:**
-- `degrees` (number, optional) - Rotation angle. Default: 360 (full revolution)
-- `segments` (number, optional) - Number of segments. Default: auto
-
-**Returns:** `Shape`
-
-```javascript
-// Vase profile
-const profile = polygon([[20, 0], [25, 30], [20, 60]]);
-const vase = profile.revolve();
-
-// Partial revolution (C-shape)
-const partial = rect(5, 40).translate(20, 0).revolve(270);
-```

package/dist-skill/docs/API/sketch/on-face.md

@@ -1,104 +0,0 @@
----
-skill-group: sketch
-skill-order: 7
----
-
-# Sketch On Face
-
-Attach a 2D sketch to a 3D face so it renders in-place and extrudes along that face normal.
-
-This supports:
-- canonical body faces: `front`, `back`, `left`, `right`, `top`, `bottom`
-- tracked planar faces on `TrackedShape`, like `side-left`
-- direct `FaceRef` targets from `tracked.face('top')`
-- supported compiler-owned created faces on `shell()` / `hole()` / `cutout()` results, such as `inner-side-right`, `floor`, `counterbore-floor`, and `wall-right`
-- supported compiler-owned created faces on `shell()` / `hole()` / `cutout()` results, such as `inner-side-right`, `floor`, `counterbore-floor`, and `wall-right`
-- defended preserved faces on compile-covered boolean results when one propagated descendant keeps a unique name
-- direct `FaceRef` targets from preserved/repeated descendants that still validate against a later compile-covered boolean target
-
-## `.onFace(parent, face, opts?)`
-
-Places a sketch onto a parent face using face-local coordinates.
-
-**Parameters:**
-- `parent` (`Shape | TrackedShape`) - target body
-- `face` (`'front' | 'back' | 'left' | 'right' | 'top' | 'bottom' | string | FaceRef`)
-- `opts` (object, optional):
-  - `u` (number) - face-local horizontal offset from the face center
-  - `v` (number) - face-local vertical offset from the face center
-  - `protrude` (number) - offset along the face normal. Positive = outward
-  - `selfAnchor` (`Anchor`) - which 2D sketch anchor aligns to the face center. Default: `'center'`
-
-**Returns:** `Sketch`
-
-## `.onFace(faceRef, opts?)`
-
-Places a sketch directly from a tracked or compiler-owned planar `FaceRef`.
-
-This is useful when the script has already selected a face semantically:
-
-```javascript
-const panel = Rectangle2D.from3Points(
-  point(-30, -18),
-  point(28, -6),
-  point(18, 24),
-).extrude(16);
-
-const cap = circle2d(5)
-  .onFace(panel.face('top'), { u: 12, protrude: 0.05 })
-  .extrude(1.2);
-```
-
-```javascript
-const cup = roundedRect(70, 42, 5, true)
-  .extrude(22)
-  .shell(2, { openFaces: ['top'] });
-
-const rib = rect(6, 4)
-  .onFace(cup, 'inner-side-right', { u: 0, v: 0, protrude: 0.05 })
-  .extrude(1.2);
-```
-
-```javascript
-const body = box(120, 60, 40, true).color('#d8dce3');
-
-const badge = roundedRect(28, 10, 2, true)
-  .onFace(body, 'front', { v: 8 })
-  .extrude(2)
-  .color('#1d2733');
-
-return [
-  { name: 'Body', shape: body },
-  { name: 'Badge', shape: badge },
-];
-```
-
-## Face-local coordinates
-
-- Canonical faces:
-  - `front` / `back`: `u = X`, `v = Z`
-  - `left` / `right`: `u` runs across the face, `v = Z`
-  - `top` / `bottom`: `u = X`, `v` runs across the face
-- Tracked planar faces use their own stored local frame:
-  - side faces of extruded rectangles: `u` follows the source edge, `v = Z`
-  - tracked `top` / `bottom` faces follow the source sketch axes
-  - direct `FaceRef` placement uses that face's `uAxis` / `vAxis`
-  - supported shell inner walls, blind-hole floors, counterbore shoulder floors, and defended cut walls reuse compiler-owned local frames for downstream workplanes
-- supported shell inner walls, blind-hole floors, counterbore shoulder floors, and defended cut walls reuse compiler-owned local frames for downstream workplanes
-  - compile-covered `Shape` targets now resolve defended named faces through the shared face-query table before falling back to bare canonical body heuristics
-
-The sketch's local `+Z` becomes the face normal, so `extrude(positive)` goes outward from that face.
-
-## Notes
-
-- This is a planar face-placement feature, not arbitrary curved-surface projection.
-- Tracked curved faces like `cylinder(...).face('side')` are rejected because they do not have a planar sketch frame.
-- Supported created-face names on compiler-owned feature results are intentionally narrow, but defended split descendants now stay visible as semantic regions where Forge can keep one stable source surface.
-- Hole/cut host faces, supported `upToFace` termination faces, and defended boolean-difference / boolean-intersection descendants can now stay queryable as face regions instead of collapsing straight to "missing face".
-- Coplanar boolean face sets now stay placeable through `onFace(shape, name, ...)` when Forge can defend one shared planar frame; non-coplanar sets stay explicit and reject planar placement honestly.
-- The placed sketch still supports normal 2D operations like `translate`, `rotate`, `scale`, and sketch booleans before extrusion.
-- If multiple sketches share the same face placement, their 2D booleans preserve that shared placement.
-- If booleans mix sketches with different 3D placements, the result drops back to an unplaced sketch.
-- Extruding a placed sketch keeps the tracked `top` / `bottom` / `side` metadata from that extrusion, transformed into world space.
-- Projection-driven follow-on sketches now keep compiler-visible provenance when you `projectToPlane()` a compatible projected source back onto a matching parallel plane. The defended exact subset now covers straight extrusions plus compatible shell/hole/cut/union descendants that reduce to one planar projection basis, but arbitrary projection targets still stay runtime-only.
-- `projectToPlane()` accepts a `FaceRef` as the target plane via `{ face: shape.face(name) }`. When the target is a defended descendant region (such as `inner-bottom` after a shell), the compiler stores a `targetFaceQuery` in the projection compile plan so later cuts, offsets, and stiffeners can explain which surface they originated from. The same parallel-plane replay constraints apply: the projected source basis must stay parallel to the target face normal.

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

@@ -1,78 +0,0 @@
----
-skill-group: sketch
-skill-order: 6
----
-
-# Sketch Operations
-
-2D operations for modifying sketch contours.
-
-## Methods
-
-All operations preserve the sketch's color.
-
-### `.offset(delta, join?)`
-Inflate (positive) or deflate (negative) the contour.
-
-**Parameters:**
-- `delta` (number) - Offset distance. Positive = outward, negative = inward
-- `join` ('Square' | 'Round' | 'Miter', optional) - Corner style. Default: 'Round'
-
-```javascript
-const outer = rect(50, 30).offset(5);      // Expand by 5mm
-const inner = circle2d(20).offset(-2);     // Shrink by 2mm
-const sharp = ngon(6, 20).offset(3, 'Miter');
-```
-
-Use the common `offset(-r).offset(+r)` pattern when you want to round **every convex corner** of a closed sketch.
-
-### `filletCorners(points, corners)`
-Round specific corners of a polygon point list (both convex and concave).
-
-**Parameters:**
-- `points` (([number, number] | Point2D)[]) - Closed polygon vertices in order
-- `corners` (`{ index: number, radius: number, segments?: number }[]`) - Which vertices to fillet
-
-**Returns:** `Sketch`
-
-```javascript
-const roofPoints = [
-  [0, 0],
-  [90, 0],
-  [90, 44],
-  [66, 74],
-  [45, 86],
-  [24, 74],
-  [0, 44],
-];
-
-const roof = filletCorners(roofPoints, [
-  { index: 3, radius: 19 },
-  { index: 4, radius: 19 },
-  { index: 5, radius: 19 },
-]);
-```
-
-Notes:
-- both convex and concave corners are supported; convex fillets cut the corner, concave fillets fill the concavity
-- collinear corners (straight edges) cannot be filleted
-- if two neighboring fillets would overlap on the same edge, the function throws
-- compare `polygon(points)` and `filletCorners(points, ...)` before extruding when debugging mixed sharp-and-rounded outlines
-
-## Choosing A Rounding Strategy
-
-- `offset(-r).offset(+r)` rounds all convex corners of an existing closed profile
-- `stroke(points, width, 'Round')` thickens a centerline path; use it for ribs, traces, and wire-like geometry
-- `filletCorners(points, ...)` is the right tool when some corners stay sharp and others need true tangent fillets
-- See `examples/api/sketch-rounding-strategies.forge.js` for a side-by-side comparison
-
-### `.simplify(epsilon?)`
-Removes vertices that don't significantly affect the shape.
-
-**Parameters:**
-- `epsilon` (number, optional) - Tolerance for vertex removal. Default: 1e-6
-
-```javascript
-const simplified = complexSketch.simplify(0.1);
-```
-

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

@@ -1,75 +0,0 @@
----
-skill-group: sketch
-skill-order: 3
----
-
-# Sketch Path Builder
-
-Fluent API for tracing 2D outlines point by point.
-
-## Class: PathBuilder
-
-### `path()`
-Creates a new path builder.
-
-```javascript
-const triangle = path()
-  .moveTo(0, 0)
-  .lineH(50)
-  .lineV(30)
-  .close();
-```
-
-### Methods
-
-#### `.moveTo(x, y)`
-Set starting point.
-
-#### `.lineTo(x, y)`
-Line to absolute position.
-
-#### `.lineH(dx)`
-Horizontal line (relative).
-
-#### `.lineV(dy)`
-Vertical line (relative).
-
-#### `.lineAngled(length, degrees)`
-Line at angle (0°=right, 90°=up).
-
-#### `.close()`
-Close path into a `Sketch` (auto-fixes winding).
-
-#### `.stroke(width, join?)`
-Thicken path into solid profile (see below).
-
-## Stroke
-
-Thicken a polyline (centerline) into a solid profile with uniform width. Proper miter joins at vertices.
-
-### `path().stroke(width, join?)`
-### `stroke(points, width, join?)`
-
-**Parameters:**
-- `width` (number) — Profile thickness
-- `join` ('Square' | 'Round', optional) — Corner style. Default: 'Square' (miter)
-
-**Returns:** `Sketch`
-
-```javascript
-// Fluent path builder
-const bracket = path()
-  .moveTo(0, 0)
-  .lineH(50)
-  .lineV(-70)
-  .lineAngled(20, 235)
-  .stroke(4);
-
-// Or with point array
-const bracket = stroke([[0, 0], [50, 0], [50, -70]], 4);
-
-// Rounded corners
-const rounded = stroke([[0, 0], [50, 0], [50, -50]], 4, 'Round');
-```
-
-Use `stroke(..., 'Round')` for centerline-based geometry such as ribs, traces, and wire-like profiles. It is not the same as rounding selected corners of an existing closed polygon. For mixed sharp-and-rounded outlines, build the polygon first and use `filletCorners(...)`.

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

@@ -1,146 +0,0 @@
----
-skill-group: sketch
-skill-order: 2
----
-
-# 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);
-```
-
-### `text2d(content, options?)`
-Renders a string as a filled 2D sketch using the built-in "Forge Mono" geometric font — a clean, angular, monoline typeface designed to extrude and engrave crisply.  Supports A–Z (case-insensitive), 0–9, and common punctuation.
-
-**Parameters:**
-- `content` (string) - Text to render
-- `options.size` (number) - Cap height in model units. Default: `10`
-- `options.letterSpacing` (number) - Extra spacing between characters in model units. Default: `0`
-- `options.align` (`'left' | 'center' | 'right'`) - Horizontal alignment relative to x = 0. Default: `'left'`
-- `options.baseline` (`'baseline' | 'center' | 'top'`) - Vertical alignment relative to y = 0. Default: `'baseline'`
-
-**Returns:** `Sketch`
-
-```javascript
-// Extruded nameplate
-text2d('FORGE CAD', { size: 8 }).extrude(1.5)
-
-// Centered label
-text2d('V 2.0', { size: 6, align: 'center', baseline: 'center' }).extrude(0.8)
-
-// Engraved into a face
-myPart.cut(text2d('A-001', { size: 4 }).onFace(myPart, 'top'), { depth: 0.5 })
-```
-
-### `textWidth(content, options?)`
-Returns the rendered advance width of a string in model units, using the same metrics as `text2d`.
-
-**Parameters:**
-- `content` (string) - Text to measure
-- `options.size` (number) - Cap height in model units. Default: `10`
-- `options.letterSpacing` (number) - Extra spacing between characters. Default: `0`
-
-**Returns:** `number`
-
-```javascript
-const w = textWidth('HELLO', { size: 10 }); // total advance width
-```