fluidcad 0.0.32 → 0.0.34

package/llm-docs/api/part.md

@@ -0,0 +1,40 @@
+---
+id: api/part
+title: part(name, callback)
+summary: Isolation boundary for assembly modeling. Shapes inside a part only auto-fuse with each other, never with siblings outside.
+tags: [api, utility, assembly]
+symbols: [part]
+seeAlso: [concepts/scene-graph]
+---
+
+# part
+
+Imported from `fluidcad/core`.
+
+```ts
+part(name: string, callback: () => void)
+```
+
+Creates an isolation boundary. Shapes inside the callback auto-fuse with
+each other but **not** with siblings outside the part. Reach for `part`
+when you have multiple distinct components in one assembly file.
+
+Wrapping `part(...)` in a function gives parametric, reusable parts.
+
+## Example
+
+```fluid.js
+import { cylinder, extrude, part, rect, sketch } from "fluidcad/core";
+
+part("base", () => {
+  sketch("xy", () => rect(120, 80).centered());
+  extrude(20);
+});
+
+part("pillar", () => {
+  cylinder(15, 50).translate(0, 0, 20);
+});
+```
+
+See [[concepts/scene-graph]] for how parts compose with the rest of the
+feature tree.

package/llm-docs/api/plane.md

@@ -0,0 +1,44 @@
+---
+id: api/plane
+title: plane(reference, options?)
+summary: Builds a reference plane from a standard name, an existing plane, a face, or the midpoint between two planes. Optional offset/rotation parametrize it.
+tags: [api, reference, geometry]
+symbols: [plane]
+seeAlso: [api/axis, api/local, api/sketch]
+---
+
+# plane
+
+Imported from `fluidcad/core`.
+
+```ts
+plane(plane: PlaneLike, options: PlaneTransformOptions)
+plane(plane: PlaneLike, offset: number)
+plane(selection: SceneObject)                       // from a face
+plane(selection: SceneObject, options)
+plane(selection: SceneObject, offset)
+plane(plane: Plane, options)                        // transform an existing plane
+plane(p1: PlaneLike, p2: PlaneLike, options?)       // midplane between two planes
+plane(p1: Plane, p2: Plane, options?)
+```
+
+`PlaneTransformOptions`:
+
+- `offset: number` — translate along the normal.
+- `rotateX`, `rotateY`, `rotateZ` — degrees.
+
+## Example
+
+```fluid.js
+import { circle, extrude, plane, rect, sketch } from "fluidcad/core";
+
+sketch("xy", () => rect(100, 60).centered());
+extrude(20);
+
+const top = plane("xy", 80);                        // XY shifted up 80
+sketch(top, () => circle(20));
+extrude(10);
+```
+
+See [[api/axis]] for the axis counterpart and [[api/local]] for the
+sketch-relative axes.

package/llm-docs/api/polygon.md

@@ -0,0 +1,37 @@
+---
+id: api/polygon
+title: polygon(n, diameter, mode?)
+summary: Regular n-sided polygon sized by the inscribed or circumscribed diameter — no manual `[r*cos, r*sin]` math.
+tags: [api, 2d, primitive]
+symbols: [polygon]
+seeAlso: [api/circle, api/sketch]
+---
+
+# polygon
+
+Imported from `fluidcad/core`.
+
+```ts
+polygon(numberOfSides, diameter, mode?)
+polygon(center, numberOfSides, diameter, mode?)
+polygon(targetPlane, numberOfSides, diameter)
+polygon(targetPlane, numberOfSides, diameter, mode)
+```
+
+Regular polygon. `mode` is `"inscribed"` (default — corners sit on the
+diameter circle) or `"circumscribed"` (edge midpoints sit on the diameter
+circle). Returns `Polygon` with `.getEdge(i)` / `.getVertex(i)` (0-based).
+
+## Example
+
+```fluid.js
+import { extrude, polygon, sketch } from "fluidcad/core";
+
+sketch("xy", () => polygon(6, 60));   // hexagon, 60 diameter
+extrude(10);
+```
+
+Prefer this over computing corner coordinates with trig — the kernel
+handles inscribed/circumscribed sizing exactly.
+
+See [[api/circle]] for the matching curve primitive.

package/llm-docs/api/primitive-solids.md

@@ -0,0 +1,39 @@
+---
+id: api/primitive-solids
+title: sphere / cylinder
+summary: Sketch-free primitive solids. Both return Transformable, so translate/rotate/mirror chain directly off the result.
+tags: [api, 3d, solid, primitive]
+symbols: [sphere, cylinder]
+seeAlso: [api/extrude, api/revolve]
+---
+
+# sphere / cylinder
+
+Imported from `fluidcad/core`.
+
+```ts
+sphere(radius)
+sphere(radius, angle)                  // partial sphere (degrees)
+
+cylinder(radius, height)
+```
+
+Both return `Transformable`, so you can chain `.translate()`, `.rotate()`,
+or `.mirror()` directly on the result instead of wrapping in a separate
+transform call.
+
+These primitives don't need a sketch — reach for them when you want a
+ball-bearing, dowel, or shaft and the parametric sketch+revolve dance
+would be ceremony.
+
+## Example
+
+```fluid.js
+import { cylinder, sphere } from "fluidcad/core";
+
+sphere(25).translate(0, 0, 100);
+cylinder(10, 50).rotate("x", 90);
+```
+
+See [[api/revolve]] for fully custom solids of revolution and
+[[api/extrude]] for the sketch-driven equivalent.

package/llm-docs/api/project-intersect.md

@@ -0,0 +1,48 @@
+---
+id: api/project-intersect
+title: project / intersect
+summary: Reduce 3D geometry to 2D sketch wires. `project` flattens edges along the sketch normal; `intersect` cuts the sketch plane through 3D objects.
+tags: [api, 2d, modifier, projection]
+symbols: [project, intersect]
+seeAlso: [api/sketch, api/offset]
+---
+
+# project / intersect
+
+Imported from `fluidcad/core`.
+
+```ts
+project(...sourceObjects: SceneObject[])
+project(targetPlane, sourceObjects)
+
+intersect(...sourceObjects: SceneObject[])
+intersect(targetPlane, sourceObjects)
+```
+
+Both operate inside a sketch context and return `ExtrudableGeometry`.
+
+- `project(obj)` projects the edges of 3D faces or edges down to the
+  active sketch plane along the normal — the resulting 2D wire matches
+  the silhouette of `obj`.
+- `intersect(obj)` cuts the sketch plane through `obj` and returns the
+  cross-section edges where they meet.
+
+Pair either with `extrude` / `cut` / `offset` to re-use 3D geometry as
+the input to a new 2D operation.
+
+## Example
+
+```fluid.js
+import { circle, extrude, intersect, sketch } from "fluidcad/core";
+
+sketch("xz", () => circle(40));
+const cyl = extrude(80).symmetric();
+
+sketch("xy", () => {
+  intersect(cyl);             // cross-section where xy slices the cylinder
+});
+extrude(3);
+```
+
+See [[api/offset]] for offsetting the resulting wire and [[api/sketch]]
+for the sketch context.

package/llm-docs/api/rect.md

@@ -0,0 +1,48 @@
+---
+id: api/rect
+title: rect(width, height?)
+summary: Draws an axis-aligned rectangle on the active sketch plane. Optional corner radii via `.radius(...)` and edge/vertex accessors for downstream selections.
+tags: [api, 2d, primitive]
+symbols: [rect]
+seeAlso: [api/sketch, api/extrude]
+---
+
+# rect
+
+Imported from `fluidcad/core`.
+
+```ts
+rect(width, height?)
+rect(start: Point2D, width, height?)
+rect(targetPlane, width, height)
+```
+
+Draws a rectangle. `height` defaults to `width` (square). Returns `Rect`.
+
+## Chain methods
+
+- `.centered(value?)` — `true` (default) to center on both axes;
+  `"horizontal"` or `"vertical"` to center on one axis only.
+- `.radius(...r)` — corner radii. `radius(5)` rounds all four. The
+  four-arg form is `[bottomLeft, bottomRight, topRight, topLeft]`.
+
+## Direct accessors
+
+```js
+const r = rect(100, 60);
+r.topEdge(); r.bottomEdge(); r.leftEdge(); r.rightEdge();
+r.topLeft(); r.topRight(); r.bottomLeft(); r.bottomRight();
+r.topLeftArcEdge();   // only present when a corner radius is applied
+```
+
+## Example
+
+```fluid.js
+import { extrude, rect, sketch } from "fluidcad/core";
+
+sketch("xy", () => rect(100, 60).centered().radius(8));
+extrude(15);
+```
+
+See [[api/sketch]] for the sketch context and [[api/extrude]] for the
+typical follow-up operation.

package/llm-docs/api/remove.md

@@ -0,0 +1,32 @@
+---
+id: api/remove
+title: remove(...objects)
+summary: Deletes scene objects. Most useful after `.reusable()` once a profile is no longer needed.
+tags: [api, utility]
+symbols: [remove]
+seeAlso: [api/sketch]
+---
+
+# remove
+
+Imported from `fluidcad/core`.
+
+```ts
+remove(...objects: SceneObject[])
+```
+
+Removes objects from the scene. The common pattern is cleaning up a
+`.reusable()` profile once every consumer has been built.
+
+## Example
+
+```fluid.js
+import { circle, extrude, remove, sketch } from "fluidcad/core";
+
+const profile = sketch("xy", () => circle(40)).reusable();
+extrude(20);
+extrude(40);
+remove(profile);                                 // clean up the profile
+```
+
+See [[api/sketch]] for `.reusable()`.

package/llm-docs/api/repeat.md

@@ -0,0 +1,79 @@
+---
+id: api/repeat
+title: repeat(kind, axis | plane, options, ...features)
+summary: Re-applies a modeling feature (extrude, cut, fillet, …) at multiple positions, producing one solid with N copies of the feature.
+tags: [api, pattern, transform]
+symbols: [repeat]
+seeAlso: [api/extrude, concepts/scene-graph]
+---
+
+# repeat
+
+Imported from `fluidcad/core`.
+
+```ts
+repeat("linear", axis | axes, options, ...objects)
+repeat("circular", axis, options, ...objects)
+repeat("mirror", plane, ...objects)
+repeat("rotate", axis, angle?, ...objects)   // angle defaults to 90°
+repeat(matrix: Matrix4, ...objects)
+```
+
+`repeat()` re-runs the modeling feature itself at new positions. Pass the
+result of an `extrude()`, `cut()`, `fillet()`, etc. as the trailing
+argument — each repetition re-executes that operation, so the output is
+**one solid with N copies of the feature**.
+
+## Required options
+
+- **`linear`** — `count` plus exactly one of `offset` (spacing between
+  instances) or `length` (total span, distributed evenly). For
+  multi-axis linear repeats, pass arrays.
+- **`circular`** — `count` plus exactly one of `offset` (degrees between
+  instances) or `angle` (total sweep, distributed evenly).
+
+Passing `count` alone is not enough — the runtime needs either the
+spacing or the span.
+
+## Examples
+
+```fluid.js
+import { circle, cut, extrude, rect, repeat, sketch } from "fluidcad/core";
+
+// Cut one pocket, then repeat the cut across a 4×2 grid → one solid with 8 pockets
+sketch("xy", () => rect(200, 100).centered());
+extrude(20);
+sketch("xy", () => circle(5));
+const pocket = cut(10);
+repeat("linear", ["x", "y"], { count: [4, 2], offset: [30, 30] }, pocket);
+```
+
+```js
+// Mirror a boss across the front plane
+const boss = extrude(15);
+repeat("mirror", "front", boss);
+
+// 6 circular copies evenly distributed around Z (full 360°)
+const spoke = extrude(20);
+repeat("circular", "z", { count: 6, angle: 360 }, spoke);
+
+// Same idea, but spec the angular spacing directly
+repeat("circular", "z", { count: 6, offset: 60 }, spoke);
+```
+
+## repeat() vs copy()
+
+| You want… | Use |
+|-----------|-----|
+| Re-run a feature so it cuts/extrudes into the same solid at each position | `repeat()` |
+| One solid with multiple pockets/bosses | `repeat()` with the cut/extrude result |
+| Clone the whole finished shape at new positions (each copy independent) | `copy()` |
+| Many separate solids of the same shape | `copy()` with `.new()` on the original |
+| Mirror a feature across a plane | `repeat("mirror", plane, feature)` |
+
+The key intuition: `copy()` duplicates a finished shape; `repeat()`
+re-executes a feature. The latter respects auto-fusion semantics, so
+overlapping copies merge rather than producing duplicate geometry.
+
+See [[api/extrude]] / [[concepts/scene-graph]] for the underlying feature
+model `repeat` re-applies.

package/llm-docs/api/revolve.md

@@ -0,0 +1,38 @@
+---
+id: api/revolve
+title: revolve(axis, angle?)
+summary: Sweeps the last sketch around an axis. Full 360 by default; supply an angle for partial revolutions. The sketch plane must contain the axis.
+tags: [api, 3d, solid]
+symbols: [revolve]
+seeAlso: [api/sketch, api/sweep, api/extrude]
+---
+
+# revolve
+
+Imported from `fluidcad/core`.
+
+```ts
+revolve(axis: AxisLike, target?: SceneObject)         // full 360
+revolve(axis: AxisLike, angle: number, target?)       // partial revolution
+```
+
+Returns `Revolve` (extends `BooleanOperation`). Chain: `.symmetric()`,
+`.thin()`, `.pick()`, plus the standard boolean scope methods.
+
+The **sketch plane must contain the axis**: to revolve around `"z"`,
+sketch on `"xz"` or `"yz"`.
+
+## Example
+
+```fluid.js
+import { move, rect, revolve, sketch } from "fluidcad/core";
+
+sketch("xz", () => {
+  move([20, 0]);
+  rect(10, 30);
+});
+revolve("z");                                          // ring
+```
+
+See [[api/sweep]] for path-driven solids and [[api/extrude]] for linear
+extrusion.

package/llm-docs/api/rib.md

@@ -0,0 +1,40 @@
+---
+id: api/rib
+title: rib(thickness, spine?)
+summary: Builds a rib from an open spine sketch. Extends in the sketch plane normal until it meets surrounding solids.
+tags: [api, 3d, solid]
+symbols: [rib]
+seeAlso: [api/sketch, api/extrude]
+---
+
+# rib
+
+Imported from `fluidcad/core`.
+
+```ts
+rib(thickness)                          // uses last sketch as spine
+rib(thickness, spine: SceneObject)
+```
+
+Returns `Rib` (extends `BooleanOperation`). Sign of `thickness` chooses
+direction: positive forward, negative backward. Chain methods:
+
+- `.parallel()` — extrude parallel to the sketch plane instead of the
+  normal direction.
+- `.extend()` — extend the rib ends so they blend with surrounding walls.
+
+Plus the standard face/edge accessors (`startFaces`, `endFaces`,
+`sideFaces`, etc.).
+
+## Example
+
+```fluid.js
+import { extrude, line, rect, rib, sketch } from "fluidcad/core";
+
+sketch("xy", () => rect(120, 80).centered());
+extrude(40);
+sketch("xz", () => line([-40, 5], [40, 5]));
+rib(3).extend();
+```
+
+See [[api/extrude]] for the base solid the rib connects into.

package/llm-docs/api/rotate.md

@@ -0,0 +1,37 @@
+---
+id: api/rotate
+title: rotate(axis, angle, ...targets?)
+summary: Rotates one or more objects around an axis (3D) or in the sketch plane (2D). Degrees, not radians.
+tags: [api, 3d, 2d, transform]
+symbols: [rotate]
+seeAlso: [api/translate, api/mirror]
+---
+
+# rotate
+
+Imported from `fluidcad/core`.
+
+```ts
+// 2D — inside a sketch, around the plane's Z (i.e., the sketch normal)
+rotate(angle, ...targets)
+rotate(angle, copy: boolean, ...targets)
+
+// 3D — around a world or custom axis
+rotate(axis: AxisLike, angle, ...targets)
+rotate(axis, angle, copy: boolean, ...targets)
+```
+
+Angles are degrees. `AxisLike` is `"x"` / `"y"` / `"z"`, a direction
+vector, or an `{ point?, direction }` record. `copy: true` clones the
+source rather than rotating it in place.
+
+## Example
+
+```fluid.js
+import { cylinder, rotate } from "fluidcad/core";
+
+const c = cylinder(8, 40);
+rotate("x", 90, c);                              // lay the cylinder on its side
+```
+
+See [[api/translate]] for moves and [[api/mirror]] for reflections.

package/llm-docs/api/select.md

@@ -0,0 +1,41 @@
+---
+id: api/select
+title: select(...filters)
+summary: Runs filters across the entire scene and stores the result as the implicit "last selection." The next op that needs a selection picks it up automatically.
+tags: [api, selection]
+symbols: [select]
+seeAlso: [api/face-filter, api/edge-filter, concepts/last-selection]
+---
+
+# select
+
+Imported from `fluidcad/core`.
+
+```ts
+select(...filters: (FaceFilter | EdgeFilter)[])
+```
+
+Each filter contributes candidates; the final selection is the **union**
+across all filter arguments (whereas chained calls within a single
+filter — `.line()` then `.onPlane(...)` — are ANDed). The selection is
+stored on the scene; the next op that takes a selection consumes it.
+
+For accessor-driven selections off a specific feature (e.g., the top
+faces of one extrude), use the direct accessor instead —
+`e.endFaces(...filters)` — to avoid scanning the rest of the scene.
+
+## Example
+
+```fluid.js
+import { extrude, fillet, rect, select, sketch } from "fluidcad/core";
+import { edge } from "fluidcad/filters";
+
+sketch("xy", () => rect(80, 60).centered());
+const e = extrude(20);
+select(edge().verticalTo("xy"));
+fillet(2);                              // consumes the selection above
+```
+
+See [[api/face-filter]] and [[api/edge-filter]] for the per-filter
+predicates, and [[concepts/last-selection]] for the implicit-consumption
+contract.

package/llm-docs/api/shell.md

@@ -0,0 +1,41 @@
+---
+id: api/shell
+title: shell(thickness, ...openFaces?)
+summary: Hollows a solid into a thin wall. Pass faces to remove (open the shell). Negative thickness shells inward; positive shells outward.
+tags: [api, 3d, modifier]
+symbols: [shell]
+seeAlso: [api/extrude, api/fillet]
+---
+
+# shell
+
+Imported from `fluidcad/core`.
+
+```ts
+shell(thickness?)                      // default thickness 2.5, walls inward (negative)
+shell(thickness, ...selections)        // remove these faces (open the shell)
+```
+
+Returns `Shell` with:
+
+- `.internalFaces()`, `.internalEdges()` — the new inner wall geometry.
+- `.join(type)` — corner join style: `"arc"` (default), `"intersection"`
+  (sharp), or `"tangent"`.
+
+**Sign of thickness matters.** Negative thickness shells inward
+(preserving the outer shape and hollowing out the interior). Positive
+shells outward (preserving the inner shape and adding wall material).
+
+## Example
+
+```fluid.js
+import { extrude, fillet, rect, shell, sketch } from "fluidcad/core";
+
+sketch("xy", () => rect(80, 60).centered());
+const e = extrude(40);
+const s = shell(-2, e.endFaces());     // open-top container, 2mm walls
+fillet(0.5, s.internalEdges());
+```
+
+See [[api/extrude]] for the base solid and [[api/fillet]] for refining
+the new inner edges.

package/llm-docs/api/sketch.md

@@ -0,0 +1,76 @@
+---
+id: api/sketch
+title: sketch(plane | face, sketcher)
+summary: Opens a 2D sketching context on a plane or a face. The active sketch is the implicit input to extrude/cut/revolve/sweep/loft.
+tags: [api, 2d, primitive]
+symbols: [sketch]
+seeAlso: [api/extrude, concepts/last-selection, concepts/scene-graph]
+---
+
+# sketch
+
+Imported from `fluidcad/core`.
+
+```ts
+sketch(plane: PlaneLike, sketcher: () => T): SceneObject
+sketch(face: SceneObject, sketcher: () => T): SceneObject
+sketch(plane: Plane, sketcher: () => T): SceneObject
+```
+
+Opens a sketch context. The callback draws 2D geometry; whatever the callback
+returns is attached as `.regions` on the resulting `SceneObject`, so named
+references can be carried out:
+
+```fluid.js
+import { circle, sketch } from "fluidcad/core";
+
+const s = sketch("xy", () => {
+    const outer = circle(60).reusable();
+    const inner = circle(20);
+    return { outer, inner };
+});
+
+// s.regions.outer  → reference to the outer circle
+```
+
+## Implicit consumption
+
+The sketch becomes the **last sketch**. The next 3D feature (`extrude`,
+`cut`, `revolve`, `sweep`, `loft`, `rib`) consumes it automatically:
+
+```fluid.js
+import { extrude, rect, sketch } from "fluidcad/core";
+
+sketch("xy", () => rect(100, 50).centered());
+extrude(20);  // consumes the sketch above
+```
+
+A consumed sketch is gone. To reuse a sketch across multiple operations,
+mark it `.reusable()`:
+
+```fluid.js
+import { circle, extrude, sketch } from "fluidcad/core";
+
+const profile = sketch("xy", () => circle(40)).reusable();
+extrude(30, profile);
+extrude(-10, profile);  // still available
+```
+
+## Sketching on a face
+
+Passing a face selection orients the sketch onto that face's plane. If the
+selection resolves to multiple faces, only the **first** face is used as the
+sketch plane:
+
+```fluid.js
+import { circle, cut, extrude, rect, sketch } from "fluidcad/core";
+
+sketch("xy", () => rect(100, 60).centered());
+const e = extrude(30);
+sketch(e.endFaces(), () => circle(15));
+cut(10);  // 10mm-deep pocket on the top face
+```
+
+See [[concepts/coordinate-system]] for how sketch axes are derived from the
+chosen plane, and [[concepts/last-selection]] for how implicit consumption
+chains operations.

package/llm-docs/api/slot.md

@@ -0,0 +1,36 @@
+---
+id: api/slot
+title: slot(distance, radius)
+summary: Stadium-shaped slot — a rectangle with semicircular end caps — defined by length and end-cap radius.
+tags: [api, 2d, primitive]
+symbols: [slot]
+seeAlso: [api/rect, api/sketch]
+---
+
+# slot
+
+Imported from `fluidcad/core`.
+
+```ts
+slot(distance, radius)
+slot(start: Point2D, distance, radius)
+slot(geometry, radius, deleteSource?)        // wrap around an existing edge
+slot(targetPlane, distance, radius)
+slot(targetPlane, geometry, radius)
+```
+
+Returns `Slot` with `.centered(value?)` and `.rotate(angle)`.
+
+## Example
+
+```fluid.js
+import { extrude, sketch, slot } from "fluidcad/core";
+
+sketch("xy", () => slot(80, 10).centered());
+extrude(8);
+```
+
+Reach for slot whenever you'd otherwise hand-compute the end-cap arc
+positions of a straight pocket.
+
+See [[api/rect]] for the sharp-cornered variant.