fluidcad 0.0.32 → 0.0.34

package/llm-docs/.coverage-allowlist.txt

@@ -0,0 +1,9 @@
+# llm-docs coverage allowlist
+#
+# Each non-blank, non-comment line names a public symbol from
+# website/scripts/api-doc-config.ts that is intentionally undocumented in
+# llm-docs/. Append a "# reason" comment per entry so reviewers can see why an
+# opt-out exists.
+#
+# Empty by default — once the Phase 11 migration drained every slice the
+# allowlist is no longer needed for normal coverage.

package/llm-docs/api/arc.md

@@ -0,0 +1,48 @@
+---
+id: api/arc
+title: arc(end) / arc(radius, startAngle, endAngle)
+summary: Circular arc. Point form runs from the cursor (or explicit start) to `end`; angle form sweeps an angular range. Angles are relative to the current tangent and in degrees.
+tags: [api, 2d, primitive, curve]
+symbols: [arc]
+seeAlso: [api/circle, api/bezier, api/line]
+---
+
+# arc
+
+Imported from `fluidcad/core`.
+
+```ts
+arc(endPoint: Point2D)                        // from cursor through implicit center
+arc(startPoint, endPoint)
+arc(radius, startAngle?, endAngle?)           // angle form (defaults 0..180)
+arc(targetPlane, endPoint)
+arc(targetPlane, startPoint, endPoint)
+arc(targetPlane, radius, startAngle, endAngle)
+```
+
+## Point form — `ArcPoints`
+
+- `.radius(value)` — bulge radius. Positive bulges CCW; negative bulges CW.
+- `.center(point)` — fix the center explicitly (mutually exclusive with `.radius()`).
+
+## Angle form — `ArcAngles`
+
+- `.centered()` — center the sweep around the start angle.
+- Angles are degrees, relative to the **current tangent**.
+
+## Example
+
+```fluid.js
+import { arc, extrude, line, sketch } from "fluidcad/core";
+
+sketch("xy", () => {
+  line([0, 0], [60, 0]);
+  arc([100, 40]).radius(50);   // bulge from cursor to (100,40)
+  line([100, 60]);
+  line([0, 60]);
+  line([0, 0]);
+});
+extrude(5);
+```
+
+See [[api/circle]] for full circles and [[api/bezier]] for free curves.

package/llm-docs/api/axis.md

@@ -0,0 +1,42 @@
+---
+id: api/axis
+title: axis(reference, options?)
+summary: Builds a reference axis from a world axis name, an edge, or the midaxis between two axes. Used by revolve, repeat, and 3D rotations.
+tags: [api, reference, geometry]
+symbols: [axis]
+seeAlso: [api/plane, api/local, api/revolve, api/rotate]
+---
+
+# axis
+
+Imported from `fluidcad/core`.
+
+```ts
+axis(axis: AxisLike)
+axis(axis: AxisLike, options: AxisTransformOptions)
+axis(source: SceneObject)                           // from an edge
+axis(source: SceneObject, options)
+axis(axis: Axis, options)
+axis(a1: AxisLike, a2: AxisLike, options?)          // midaxis
+axis(a1: Axis, a2: Axis, options?)
+```
+
+`AxisLike` is `"x"` / `"y"` / `"z"`, a direction vector, or an
+`{ point?, direction }` record. `AxisTransformOptions` includes
+`offsetX`, `offsetY`, `offsetZ`, `flip`, etc.
+
+## Example
+
+```fluid.js
+import { axis, move, rect, revolve, sketch } from "fluidcad/core";
+
+sketch("xz", () => {
+  move([20, 0]);
+  rect(10, 30);
+});
+const raised = axis("z", { offsetX: 50 });           // Z axis shifted +50 along X
+revolve(raised);
+```
+
+See [[api/plane]] for planar references and [[api/local]] for sketch-
+local axes.

package/llm-docs/api/bezier.md

@@ -0,0 +1,42 @@
+---
+id: api/bezier
+title: bezier(...points)
+summary: Free-form bezier curve. The last point is the endpoint; preceding points are control points (degree = args − 1).
+tags: [api, 2d, primitive, curve]
+symbols: [bezier]
+seeAlso: [api/arc, api/line]
+---
+
+# bezier
+
+Imported from `fluidcad/core`.
+
+```ts
+bezier(...points: Point2D[])
+```
+
+The last argument is the endpoint; preceding arguments are control points.
+
+| Args | Degree   | Shape              |
+|------|----------|--------------------|
+| 1    | 1 (line) | straight segment   |
+| 2    | 2        | quadratic bezier   |
+| 3    | 3        | cubic bezier       |
+
+The curve starts from the current cursor and ends at the final argument;
+intermediate arguments are control handles that shape the curve.
+
+## Example
+
+```fluid.js
+import { bezier, extrude, line, sketch } from "fluidcad/core";
+
+sketch("xy", () => {
+  line([0, 0], [0, 40]);
+  bezier([20, 80], [80, 80], [100, 40]);   // cubic bezier
+  line([0, 0]);
+});
+extrude(4);
+```
+
+See [[api/arc]] for circular curves with exact radii.

package/llm-docs/api/booleans.md

@@ -0,0 +1,44 @@
+---
+id: api/booleans
+title: fuse / subtract / common
+summary: Explicit 3D boolean operations. Most of the time auto-fusion does the right thing — reach for these when you need exact control.
+tags: [api, 3d, boolean]
+symbols: [fuse, subtract, common]
+seeAlso: [api/extrude, api/cut, concepts/scene-graph]
+---
+
+# fuse / subtract / common
+
+Imported from `fluidcad/core`.
+
+```ts
+fuse()
+fuse(...objects)                       // union of objects
+subtract(object1, object2)             // object1 − object2
+common()
+common(...objects)                     // intersection
+```
+
+The no-argument forms operate on the implicit last objects in scope; the
+explicit forms operate on the arguments you pass. Most modeling work can
+rely on auto-fusion (touching solids merge automatically and `.remove()`
+chained on `extrude` already covers subtraction). Reach for these when:
+
+- You need to fuse non-touching solids deliberately.
+- An op didn't auto-fuse the way you wanted and you want to be explicit.
+- You want an explicit intersection rather than a per-feature `.scope()`.
+
+## Example
+
+```fluid.js
+import { circle, extrude, rect, sketch, subtract } from "fluidcad/core";
+
+sketch("xy", () => rect(60, 60).centered());
+const a = extrude(20).new();
+sketch("xy", () => circle(35));
+const b = extrude(20).new();
+subtract(a, b);
+```
+
+See [[api/extrude]] for chained boolean scope (`.add()`, `.remove()`,
+`.new()`, `.scope()`) and [[api/cut]] for the subtractive extrude.

package/llm-docs/api/chamfer.md

@@ -0,0 +1,40 @@
+---
+id: api/chamfer
+title: chamfer(distance, ...edges?)
+summary: Flat angled break on a 3D edge. Symmetric, asymmetric (d1 × d2), or distance + angle forms.
+tags: [api, 3d, modifier, edges]
+symbols: [chamfer]
+seeAlso: [api/fillet, api/extrude]
+---
+
+# chamfer
+
+Imported from `fluidcad/core`.
+
+```ts
+chamfer(distance?)                                  // default 1, uses last selection
+chamfer(distance, ...sceneObjects)
+chamfer(d1, d2, isAngle?)                           // asymmetric or distance + angle
+chamfer(d1, d2, isAngle, ...sceneObjects)
+```
+
+Returns a `SceneObject`. Operates on the last selection when no edges
+are passed, just like [[api/fillet]].
+
+## When to reach for chamfer vs fillet
+
+Chamfers are cheaper computationally and faster to spec from a drawing —
+prefer them for manufacturing edge breaks. Save fillets for visually
+styled rounds or stress-relief features.
+
+## Example
+
+```fluid.js
+import { chamfer, extrude, rect, sketch } from "fluidcad/core";
+
+sketch("xy", () => rect(60, 40).centered());
+const e = extrude(20);
+chamfer(2, e.endEdges());
+```
+
+See [[api/fillet]] for the rounded counterpart.

package/llm-docs/api/circle.md

@@ -0,0 +1,36 @@
+---
+id: api/circle
+title: circle(diameter?)
+summary: Draws a circle on the active sketch plane. The numeric argument is the diameter, not the radius.
+tags: [api, 2d, primitive]
+symbols: [circle]
+seeAlso: [api/sketch, api/ellipse, api/arc]
+---
+
+# circle
+
+Imported from `fluidcad/core`.
+
+```ts
+circle(diameter?)                       // at cursor, default diameter 40
+circle(center: Point2D, diameter?)
+circle(targetPlane, diameter)
+```
+
+Returns `ExtrudableGeometry`. The argument is the **diameter** — not the
+radius. With no `center`, the circle is drawn at the current cursor.
+
+## Example
+
+```fluid.js
+import { circle, extrude, sketch } from "fluidcad/core";
+
+sketch("xy", () => {
+  circle(50);                 // at the origin/cursor
+  circle([60, 0], 20);        // smaller circle offset to the right
+});
+extrude(10);
+```
+
+See [[api/ellipse]] for asymmetric diameters and [[api/arc]] for partial
+circles.

package/llm-docs/api/color.md

@@ -0,0 +1,34 @@
+---
+id: api/color
+title: color(value, selection?)
+summary: Paints a face, edge, or solid. Accepts CSS color strings (named, hex, rgb). Without a target, paints the last selection.
+tags: [api, utility, appearance]
+symbols: [color]
+seeAlso: [api/select, api/face-filter]
+---
+
+# color
+
+Imported from `fluidcad/core`.
+
+```ts
+color(value: string)                                // CSS color, applies to last selection
+color(value: string, selection: SceneObject)
+```
+
+Accepts named CSS colors (`"red"`), hex (`"#3498db"`), or `rgb(...)`.
+With no explicit target, paints the last selection — pair with
+`select(...)` or a direct accessor like `e.endFaces()`.
+
+## Example
+
+```fluid.js
+import { color, extrude, rect, sketch } from "fluidcad/core";
+
+sketch("xy", () => rect(80, 60).centered());
+const e = extrude(20);
+color("#3498db", e.endFaces());
+```
+
+See [[api/select]] for the implicit-selection model that `color` plugs
+into.

package/llm-docs/api/connect.md

@@ -0,0 +1,41 @@
+---
+id: api/connect
+title: connect(mode?)
+summary: Bridges the open ends of the current sketch's edges into one closed wire. Pass `"arc"` to bridge with tangent arcs instead of straight segments.
+tags: [api, 2d, primitive]
+symbols: [connect]
+seeAlso: [api/line, api/arc, api/sketch]
+---
+
+# connect
+
+Imported from `fluidcad/core`.
+
+```ts
+connect(mode?: "line" | "arc")
+```
+
+Sweeps all previously drawn edges in the active sketch and stitches them
+into a closed wire, inserting bridge segments (or tangent arcs in `"arc"`
+mode) between consecutive endpoints — including the final closing bridge
+back to the first edge.
+
+Use `connect` for sketches built from a few discrete curves (e.g., an
+open arc) that need to be closed into an extrudable face. For outlines
+already built from contiguous `line` / `hLine` / `vLine` segments,
+explicit closing segments are clearer than `connect`.
+
+## Example
+
+```fluid.js
+import { arc, connect, extrude, sketch } from "fluidcad/core";
+
+sketch("xy", () => {
+  arc(30);            // half-circle starting at the cursor
+  connect();          // close it into a half-disc face
+});
+extrude(5);
+```
+
+See [[api/arc]] for the curve being closed and [[api/line]] for the
+explicit closing-segment alternative.

package/llm-docs/api/constraint-qualifiers.md

@@ -0,0 +1,48 @@
+---
+id: api/constraint-qualifiers
+title: outside / enclosed / enclosing / unqualified
+summary: Wrap a geometry to disambiguate which solution a constrained primitive (tLine/tArc/tCircle) should pick.
+tags: [api, 2d, constrained, selection]
+symbols: [outside, enclosed, enclosing, unqualified]
+seeAlso: [api/tline, api/tarc, api/tcircle]
+---
+
+# Constraint qualifiers
+
+Imported from `fluidcad/constraints`.
+
+```ts
+outside(obj)
+enclosing(obj)
+enclosed(obj)
+unqualified(obj)
+```
+
+Constrained primitives like `tLine`, `tArc`, and `tCircle` can produce
+multiple valid solutions (e.g., the 4 internal/external tangents between
+two circles, or up to 8 tangent circles). These qualifiers wrap a
+candidate geometry to narrow which solution is selected.
+
+- `outside(obj)` — the result must be external to `obj` (no shared
+  interior).
+- `enclosing(obj)` — the result wraps around `obj`.
+- `enclosed(obj)` — the result sits inside `obj`.
+- `unqualified(obj)` — clears any prior qualification on `obj`.
+
+Importable from `fluidcad/constraints`.
+
+## Example
+
+```fluid.js
+import { outside } from "fluidcad/constraints";
+
+sketch("xy", () => {
+  const c1 = circle([0, 0], 40).reusable();
+  const c2 = circle([100, 0], 40).reusable();
+  tLine(outside(c1), outside(c2));      // the external tangent between c1 and c2
+});
+extrude(2);
+```
+
+See [[api/tline]], [[api/tarc]], and [[api/tcircle]] for the primitives
+these qualifiers disambiguate.

package/llm-docs/api/copy.md

@@ -0,0 +1,63 @@
+---
+id: api/copy
+title: copy(kind, axis | plane, options, ...objects)
+summary: Duplicates a finished shape at multiple positions. Each copy is independent of the original. Use `repeat()` when you instead want the modeling feature itself re-applied.
+tags: [api, transform, pattern]
+symbols: [copy]
+seeAlso: [api/repeat, api/translate, api/mirror]
+---
+
+# copy
+
+Imported from `fluidcad/core`.
+
+```ts
+// Linear
+copy("linear", axis: AxisLike, options, ...objects)
+copy("linear", axes: AxisLike[], options, ...objects)
+
+// Circular
+copy("circular", axis: AxisLike, options, ...objects)        // 3D
+copy("circular", center: Point2D, options, ...objects)       // inside a sketch
+```
+
+## Linear options (`LinearCopyOptions` / `LinearRepeatOptions`)
+
+**Required:** `count` plus exactly one of `offset` or `length`.
+
+- `count: number | number[]` — instances per axis (including original).
+- `offset: number | number[]` — spacing between instances. Mutually
+  exclusive with `length`.
+- `length: number | number[]` — total span; instances are evenly
+  distributed. Mutually exclusive with `offset`.
+- `centered: boolean` — center the pattern around the original.
+- `skip: number[][]` — index tuples to skip (per-axis).
+
+## Circular options (`CircularCopyOptions` / `CircularRepeatOptions`)
+
+**Required:** `count` plus exactly one of `offset` or `angle`.
+
+- `count: number` — instances (including original).
+- `angle: number` — total sweep in degrees; instances are evenly
+  distributed. Mutually exclusive with `offset`.
+- `offset: number` — angular spacing in degrees between instances.
+  Mutually exclusive with `angle`.
+- `centered: boolean` — center the pattern around the original.
+- `skip: number[]` — indices to skip.
+
+`copy()` snapshots the finished shape — copies don't share the
+modeling history of the source. For feature-aware patterns (where each
+position re-runs the original op) use [[api/repeat]].
+
+## Example
+
+```fluid.js
+import { circle, copy, extrude, sketch } from "fluidcad/core";
+
+sketch("xy", () => circle(8));
+const pin = extrude(20).new();
+copy("linear", "x", { count: 4, offset: 25 }, pin);
+```
+
+See [[api/repeat]] for the feature-replay alternative and
+[[api/translate]] for the single-instance case.

package/llm-docs/api/cursor-lines.md

@@ -0,0 +1,50 @@
+---
+id: api/cursor-lines
+title: hLine / vLine / aLine
+summary: Axis-aligned and angle-relative line segments that start from the current cursor — the idiomatic substitute for hand-computed endpoint coordinates.
+tags: [api, 2d, cursor, primitive]
+symbols: [hLine, vLine, aLine]
+seeAlso: [api/line, api/cursor-move, api/sketch]
+---
+
+# hLine / vLine / aLine
+
+Imported from `fluidcad/core`.
+
+```ts
+hLine(distance)
+hLine(target: SceneObject)              // ends at the nearest intersection with target
+hLine(start, distance)
+hLine(targetPlane, distance)
+
+vLine(distance | target | start+distance | targetPlane+distance)
+
+aLine(angle, length)                    // angle in degrees, length along that angle
+aLine(angle, target)
+aLine(targetPlane, angle, length)
+```
+
+All three return cursor-aware geometries (`HLine`, `VLine`, `ALine`),
+each with `.centered(value?)` to center the line on the cursor instead
+of starting from it.
+
+Prefer these over `line([x + d, y])`-style absolute coordinates: the
+intent ("a 40-unit horizontal segment") stays legible, and `target`
+forms let the solver find the intersection for you.
+
+## Example
+
+```fluid.js
+import { extrude, hLine, sketch, vLine } from "fluidcad/core";
+
+sketch("xy", () => {
+  hLine(60);                 // → (60, 0)
+  vLine(40);                 // → (60, 40)
+  hLine(-60);                // → (0, 40)
+  vLine(-40);                // → (0, 0)  closes the wire
+});
+extrude(5);
+```
+
+See [[api/cursor-move]] for moving the cursor without drawing, and
+[[api/line]] for explicit-endpoint segments.

package/llm-docs/api/cursor-move.md

@@ -0,0 +1,61 @@
+---
+id: api/cursor-move
+title: move / hMove / vMove / rMove / pMove / center / back
+summary: Cursor positioning primitives. They move the active sketch's cursor (and tangent, for rMove) without drawing geometry.
+tags: [api, 2d, cursor]
+symbols: [move, hMove, vMove, rMove, pMove, center]
+seeAlso: [api/cursor-lines, api/sketch]
+---
+
+# Cursor movement
+
+Imported from `fluidcad/core`.
+
+```ts
+move()                                  // jump back to the sketch plane origin
+move(to: Point2D)                       // absolute move
+
+hMove(distance)
+hMove(target: SceneObject)              // move horizontally until hitting target
+
+vMove(distance)
+vMove(target)
+
+rMove(angle)                            // rotate the tangent by `angle` (degrees)
+rMove(angle, pivot: Point2D)
+
+pMove(radius, angle)                    // polar move relative to current tangent
+pMove(target, angle)
+
+center()                                // jump to plane origin (alias for move() with no args)
+
+back()                                  // revert one cursor change
+back(count)                             // revert `count` cursor changes
+```
+
+These never produce edges — they reposition the cursor (and, for
+`rMove`, the tangent) so the next drawing call lands where you want.
+Reach for them instead of computing absolute coordinates by hand.
+
+## Example
+
+```fluid.js
+import { extrude, hLine, sketch, vLine, vMove } from "fluidcad/core";
+
+sketch("xy", () => {
+  // Two L-shaped pieces sharing a sketch — vMove repositions without drawing.
+  hLine(40);
+  vLine(10);
+  hLine(-40);
+  vLine(-10);
+
+  vMove(30);                 // jump up — no edge drawn
+  hLine(20);
+  vLine(10);
+  hLine(-20);
+  vLine(-10);
+});
+extrude(4);
+```
+
+See [[api/cursor-lines]] for the drawing counterparts.

package/llm-docs/api/cut.md

@@ -0,0 +1,55 @@
+---
+id: api/cut
+title: cut(distance?, target?)
+summary: Subtractive extrude. Same calling conventions as extrude, but always removes material. Positive distance cuts opposite the sketch normal (into the solid); negative cuts along it. No-arg form goes through all.
+tags: [api, 3d, solid]
+symbols: [cut]
+seeAlso: [api/extrude, api/sketch, concepts/last-selection]
+---
+
+# cut
+
+Imported from `fluidcad/core`.
+
+```ts
+cut()                                  // through-all using the last sketch
+cut(target: SceneObject)
+cut(distance, target?)
+cut(distance1, distance2, target?)
+cut(face: SceneObject)                 // cut up to a face
+cut("first-face")
+cut("last-face")
+cut(face, target)
+```
+
+Returns `Cut`. Always subtractive — equivalent to `extrude(...).remove()`.
+Same chain set as `extrude` except no `.add()` / `.new()`: `.symmetric()`,
+`.draft()`, `.endOffset()`, `.thin()`, `.pick()`, `.scope()`, plus
+`.startEdges()`, `.endEdges()`, `.internalEdges()`, `.internalFaces()`.
+
+## Direction convention
+
+`cut` is the mirror of `extrude` — it goes *into* the material, not
+out of it:
+
+- **Positive `distance`** cuts in the **opposite direction of the
+  sketch normal** (into the solid the sketch sits on). This is the
+  normal pocket case.
+- **Negative `distance`** cuts **along the sketch normal** (out of the
+  same side the sketch faces).
+- **`cut()` with no args** is **through-all**, again opposite the sketch
+  normal.
+
+## Example
+
+```fluid.js
+import { circle, cut, extrude, rect, sketch } from "fluidcad/core";
+
+sketch("xy", () => rect(120, 80).centered());
+const block = extrude(30);
+sketch(block.endFaces(), () => circle(20));
+cut(10);                               // 10mm-deep blind pocket
+```
+
+See [[api/extrude]] for the additive counterpart and
+[[concepts/last-selection]] for the implicit-sketch consumption model.

package/llm-docs/api/draft.md

@@ -0,0 +1,36 @@
+---
+id: api/draft
+title: draft(angle, ...faces?)
+summary: Applies a draft angle to selected faces — pulls them outward (positive) or inward (negative) along a reference direction.
+tags: [api, 3d, modifier]
+symbols: [draft]
+seeAlso: [api/extrude, api/shell]
+---
+
+# draft
+
+Imported from `fluidcad/core`.
+
+```ts
+draft(angle)                                        // uses last selection
+draft(angle, ...selections)
+```
+
+Returns `Draft`. Tilts the selected faces by `angle` degrees. Use it for
+mold-release surfaces or any side wall that needs a taper distinct from
+its base extrusion.
+
+For draft applied during the pull itself, reach for
+`extrude(d).draft(angle)` — the inline form is usually less plumbing.
+
+## Example
+
+```fluid.js
+import { draft, extrude, rect, sketch } from "fluidcad/core";
+
+sketch("xy", () => rect(80, 50).centered());
+const e = extrude(30);
+draft(5, e.sideFaces());
+```
+
+See [[api/extrude]] for inline draft and [[api/shell]] for hollowing.