fluidcad 0.0.32 → 0.0.34

package/llm-docs/api/types/sweep.md

@@ -0,0 +1,189 @@
+---
+id: api/types/sweep
+title: Sweep
+summary: "The Sweep type. Extends BooleanOperation; adds 15 methods."
+tags: [api, type, interface]
+symbols: [Sweep, ISweep]
+seeAlso: [api/sweep, api/types/boolean-operation]
+---
+# Sweep
+
+```ts
+interface Sweep extends BooleanOperation {
+  startFaces(...args: (number | FaceFilter)[]): SceneObject;
+  endFaces(...args: (number | FaceFilter)[]): SceneObject;
+  sideFaces(...args: (number | FaceFilter)[]): SceneObject;
+  startEdges(...args: (number | EdgeFilter)[]): SceneObject;
+  endEdges(...args: (number | EdgeFilter)[]): SceneObject;
+  sideEdges(...args: (number | EdgeFilter)[]): SceneObject;
+  internalFaces(...args: (number | FaceFilter)[]): SceneObject;
+  internalEdges(...args: (number | EdgeFilter)[]): SceneObject;
+  draft(value: number | [number, number]): this;
+  endOffset(value: number): this;
+  drill(value?: boolean): this;
+  pick(...points: Point2DLike[]): this;
+  thin(offset: number): this;
+  thin(offset1: number, offset2: number): this;
+  capFaces(...args: (number | FaceFilter)[]): SceneObject;
+  capEdges(...args: (number | EdgeFilter)[]): SceneObject;
+}
+```
+
+Extends [[api/types/boolean-operation]].
+
+## Methods
+
+### `startFaces()`
+
+Selects faces at the start (profile plane) of the sweep.
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `FaceFilter`)[] | Numeric indices or FaceFilterBuilder instances to filter the selection. *(optional)* |
+
+### `endFaces()`
+
+Selects faces at the end of the sweep path.
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `FaceFilter`)[] | Numeric indices or FaceFilterBuilder instances to filter the selection. *(optional)* |
+
+### `sideFaces()`
+
+Selects the lateral faces generated by sweeping the profile along the path.
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `FaceFilter`)[] | Numeric indices or FaceFilterBuilder instances to filter the selection. *(optional)* |
+
+### `startEdges()`
+
+Selects edges on the start faces of the sweep.
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `EdgeFilter`)[] | Numeric indices or EdgeFilterBuilder instances to filter the selection. *(optional)* |
+
+### `endEdges()`
+
+Selects edges on the end faces of the sweep.
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `EdgeFilter`)[] | Numeric indices or EdgeFilterBuilder instances to filter the selection. *(optional)* |
+
+### `sideEdges()`
+
+Selects edges on the side faces, excluding edges shared with start/end faces.
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `EdgeFilter`)[] | Numeric indices or EdgeFilterBuilder instances to filter the selection. *(optional)* |
+
+### `internalFaces()`
+
+Selects faces created inside the solid during the sweep (e.g., from holes).
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `FaceFilter`)[] | Numeric indices or FaceFilterBuilder instances to filter the selection. *(optional)* |
+
+### `internalEdges()`
+
+Selects edges bounding the internal geometry created during the sweep.
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `EdgeFilter`)[] | Numeric indices or EdgeFilterBuilder instances to filter the selection. *(optional)* |
+
+### `draft()`
+
+Applies a draft (taper) angle to the sweep walls.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value` | `number` \| `[number, number]` | A single angle for uniform draft, or a `[start, end]` tuple for asymmetric draft. |
+
+### `endOffset()`
+
+Offsets the end face by a specified distance along the sweep direction.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value` | `number` | The offset distance. |
+
+### `drill()`
+
+Enables or disables drill mode.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value` | `boolean` | `true` to enable (default), `false` to disable. *(optional)* |
+
+### `pick()`
+
+Restricts the sweep to only the sketch regions containing the given points.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...points` | [[api/types/point2dlike]][] | 2D points in the sketch plane identifying regions to sweep. *(optional)* |
+
+### `thin()`
+
+```ts
+thin(offset: number): this
+thin(offset1: number, offset2: number): this
+```
+
+Enables thin sweep mode — offsets the profile edges to create a thin-walled
+swept shell instead of sweeping filled faces. Positive values offset outward,
+negative values offset inward.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `offset1` | `number` | The first wall offset distance. Positive = outward, negative = inward. |
+| `offset2` | `number` | The second wall offset distance, in the opposite direction of offset1. |
+
+### `capFaces()`
+
+Selects the cap faces at the open ends of a thin-walled sweep from an open profile.
+These are the small faces connecting the inner and outer walls at the profile endpoints.
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `FaceFilter`)[] | Numeric indices or FaceFilterBuilder instances to filter the selection. *(optional)* |
+
+### `capEdges()`
+
+Selects edges on the cap faces of a thin-walled sweep from an open profile.
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `EdgeFilter`)[] | Numeric indices or EdgeFilterBuilder instances to filter the selection. *(optional)* |
+
+## Inherited
+
+From [[api/types/boolean-operation]]: `add()`, `'new'()`, `remove()`, `scope()`
+
+From [[api/types/scene-object]]: `name()`, `reusable()`

package/llm-docs/api/types/tangent-arc-two-objects.md

@@ -0,0 +1,46 @@
+---
+id: api/types/tangent-arc-two-objects
+title: TangentArcTwoObjects
+summary: "The TangentArcTwoObjects type. Extends Geometry; adds 2 methods."
+tags: [api, type, interface]
+symbols: [TangentArcTwoObjects, ITangentArcTwoObjects]
+seeAlso: [api/tarc, api/types/geometry]
+---
+# TangentArcTwoObjects
+
+```ts
+interface TangentArcTwoObjects extends Geometry {
+  start(index?: number): Vertex;
+  end(index?: number): Vertex;
+}
+```
+
+Extends [[api/types/geometry]].
+
+## Methods
+
+### `start()`
+
+Returns the start vertex of the tangent arc.
+
+**Returns**: [[api/types/vertex]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `index` | `number` | Solution index when multiple tangent arcs exist (defaults to 0). *(optional)* |
+
+### `end()`
+
+Returns the end vertex of the tangent arc.
+
+**Returns**: [[api/types/vertex]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `index` | `number` | Solution index when multiple tangent arcs exist (defaults to 0). *(optional)* |
+
+## Inherited
+
+From [[api/types/geometry]]: `guide()`, `start()`, `end()`, `tangent()`
+
+From [[api/types/scene-object]]: `name()`, `reusable()`

package/llm-docs/api/types/transformable.md

@@ -0,0 +1,93 @@
+---
+id: api/types/transformable
+title: Transformable
+summary: "Scene objects that can be chained with world-space transformations."
+tags: [api, type, interface]
+symbols: [Transformable, ITransformable]
+seeAlso: [api/types/scene-object, api/translate, api/rotate]
+---
+# Transformable
+
+```ts
+interface Transformable extends SceneObject {
+  transform(matrix: Matrix4): this;
+  translate(x: number): this;
+  translate(x: number, y: number): this;
+  translate(x: number, y: number, z: number): this;
+  translate(offset: PointLike): this;
+  rotate(angle: number): this;
+  rotate(axis: AxisLike, angle: number): this;
+  mirror(plane: PlaneLike): this;
+  mirror(axis: AxisLike): this;
+}
+```
+
+Scene objects that can be chained with world-space transformations.
+The chained form `obj.translate(...)` / `obj.rotate(...)` / `obj.mirror(...)`
+applies the transform to the object's built shapes; it does not create
+a separate history entry like the free-function `translate()` does.
+
+Container objects (sketches, parts, repeat/mirror features) deliberately
+do not expose this interface — apply transforms to their contents instead.
+
+Extends [[api/types/scene-object]].
+
+## Methods
+
+### `transform()`
+
+Composes a 4x4 transformation matrix onto this object. Applied to the
+object's own shapes after build. Chained calls compose left-to-right:
+`.translate(T).rotate(R)` applies translation first, then rotation.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `matrix` | `Matrix4` |  |
+
+### `translate()`
+
+```ts
+translate(x: number): this
+translate(x: number, y: number): this
+translate(x: number, y: number, z: number): this
+translate(offset: PointLike): this
+```
+
+Translate along X.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `x` | `number` |  |
+| `y` | `number` |  |
+| `z` | `number` |  |
+
+### `rotate()`
+
+```ts
+rotate(angle: number): this
+rotate(axis: AxisLike, angle: number): this
+```
+
+Rotate by an angle around world Z through the origin.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `axis` | [[api/types/axis-like]] | The axis to rotate around. Use `local(...)` to reference a sketch-local axis. |
+| `angle` | `number` | Rotation in degrees. |
+
+### `mirror()`
+
+```ts
+mirror(plane: PlaneLike): this
+mirror(axis: AxisLike): this
+```
+
+Mirror across a plane.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `plane` | [[api/types/plane-like]] |  |
+
+## Inherited
+
+From [[api/types/scene-object]]: `name()`, `reusable()`

package/llm-docs/api/types/trim.md

@@ -0,0 +1,27 @@
+---
+id: api/types/trim
+title: Trim
+summary: "The Trim type. Defines 1 method."
+tags: [api, type, interface]
+symbols: [Trim, ITrim]
+seeAlso: [api/split-trim]
+---
+# Trim
+
+```ts
+interface Trim {
+  pick(...points: Point2DLike[]): Trim;
+}
+```
+
+## Methods
+
+### `pick()`
+
+Enters interactive trimming mode, optionally trimming edges at the given points.
+
+**Returns**: [[api/types/trim]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...points` | [[api/types/point2dlike]][] | Points where geometry should be trimmed; the nearest edge segment to each point is removed. *(optional)* |

package/llm-docs/api/types/two-objects-tangent-line.md

@@ -0,0 +1,46 @@
+---
+id: api/types/two-objects-tangent-line
+title: TwoObjectsTangentLine
+summary: "The TwoObjectsTangentLine type. Extends Geometry; adds 2 methods."
+tags: [api, type, interface]
+symbols: [TwoObjectsTangentLine, ITwoObjectsTangentLine]
+seeAlso: [api/tline, api/types/geometry]
+---
+# TwoObjectsTangentLine
+
+```ts
+interface TwoObjectsTangentLine extends Geometry {
+  start(index?: number): Vertex;
+  end(index?: number): Vertex;
+}
+```
+
+Extends [[api/types/geometry]].
+
+## Methods
+
+### `start()`
+
+Returns the start vertex of the tangent line.
+
+**Returns**: [[api/types/vertex]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `index` | `number` | Solution index when multiple tangent lines exist (defaults to 0). *(optional)* |
+
+### `end()`
+
+Returns the end vertex of the tangent line.
+
+**Returns**: [[api/types/vertex]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `index` | `number` | Solution index when multiple tangent lines exist (defaults to 0). *(optional)* |
+
+## Inherited
+
+From [[api/types/geometry]]: `guide()`, `start()`, `end()`, `tangent()`
+
+From [[api/types/scene-object]]: `name()`, `reusable()`

package/llm-docs/api/types/vertex.md

@@ -0,0 +1,17 @@
+---
+id: api/types/vertex
+title: Vertex
+summary: "A lazy-evaluated vertex representing a point on existing geometry."
+tags: [api, type, union]
+symbols: [Vertex, LazyVertex]
+seeAlso: [api/types/point2dlike]
+---
+# Vertex
+
+```ts
+type Vertex = Vertex;
+```
+
+A lazy-evaluated vertex representing a point on geometry. Vertices are returned by methods like `start()`, `end()`, and `tangent()` on `Geometry` types.
+
+Vertices can be passed as a [[api/types/point2dlike]] to any function that accepts a 2D point, allowing you to reference points on existing geometry.

package/llm-docs/api/types/vline.md

@@ -0,0 +1,35 @@
+---
+id: api/types/vline
+title: VLine
+summary: "The VLine type. Extends Geometry; adds 1 method."
+tags: [api, type, interface]
+symbols: [VLine, IVLine]
+seeAlso: [api/line, api/types/geometry]
+---
+# VLine
+
+```ts
+interface VLine extends Geometry {
+  centered(value?: boolean): this;
+}
+```
+
+Extends [[api/types/geometry]].
+
+## Methods
+
+### `centered()`
+
+Controls whether the line is centered on the current position.
+When `true`, the line is offset backward by half its length so that the
+current position falls at its midpoint.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value` | `boolean` | `true` to center, `false` (default) to start from the current position. *(optional)* |
+
+## Inherited
+
+From [[api/types/geometry]]: `guide()`, `start()`, `end()`, `tangent()`
+
+From [[api/types/scene-object]]: `name()`, `reusable()`

package/llm-docs/concepts/coordinate-system.md

@@ -0,0 +1,45 @@
+---
+id: concepts/coordinate-system
+title: Coordinate systems and sketch axes
+summary: World axes are x, y, z. Standard planes are xy, xz, yz. "x"/"y"/"z" always mean world axes — even inside a sketch. Use local("x" | "y" | "z") for the sketch plane's local axes.
+tags: [concept, geometry]
+seeAlso: [api/sketch]
+---
+
+# Coordinate systems
+
+## World
+
+- Right-handed: `+X` right, `+Y` away, `+Z` up.
+- Axes: `"x"`, `"y"`, `"z"`.
+- Standard planes: `"xy"`, `"xz"`, `"yz"`. Aliases like `"front"` are
+  also recognized — `"front"` is the XZ plane.
+
+## Sketch-local axes
+
+`"x"`, `"y"`, `"z"` **always refer to world axes**, including inside a
+`sketch(...)` callback. To refer to the active sketch plane's local
+axes, use `local("x" | "y" | "z")`:
+
+```js
+sketch(tiltedPlane, () => {
+    // "x" here is still the WORLD x axis
+    mirror("x");
+
+    // use local(...) for the sketch plane's local X
+    mirror(local("x"));
+});
+
+// local(...) also works outside the sketch callback,
+// resolved against the currently active sketch plane:
+mirror(local("x"));
+```
+
+## Reference geometry
+
+- `plane(name | face, options)` — build a new plane offset/rotated from
+  an existing one, or derived from a face.
+- `axis(name | edge, options)` — same idea for axes.
+
+These are the only things that need to know about coordinate systems
+explicitly; everything else flows from the active sketch's plane.

package/llm-docs/concepts/history-and-rollback.md

@@ -0,0 +1,40 @@
+---
+id: concepts/history-and-rollback
+title: History and rollback
+summary: The feature tree is also a timeline. Rollback shows the scene at any earlier point; breakpoints stop evaluation there for inspection.
+tags: [concept, debug]
+seeAlso: [concepts/scene-graph]
+---
+
+# History and rollback
+
+The ordered feature tree is also a timeline. You can:
+
+- **Rollback** to any operation index: the renderer stops there and emits
+  the partial scene. The UI shows the same view as if the script ended at
+  that point.
+- **Set a breakpoint** at a source line: evaluation halts there, the
+  renderer marks `breakpointHit: true`, and downstream operations don't
+  run. Useful for inspecting an intermediate state without changing the
+  script.
+
+The MCP `rollback_to(index)` and `add_breakpoint(file, line)` /
+`clear_breakpoints()` tools drive both of these without editing source.
+
+## What rollback does NOT touch
+
+- The source file. Rollback is a render-time operation; the file on disk
+  is unchanged.
+- The previous cache. `SceneCompare` still reuses shapes from before the
+  rollback when re-rendering forward.
+
+## When to use rollback over editing the source
+
+- Inspecting whether a specific feature is the cause of a problem.
+- Capturing a screenshot of an intermediate step (e.g., the sketch before
+  the extrude consumes it).
+- Confirming the order of operations in the timeline matches what the
+  agent expects.
+
+After a rollback, re-issuing `recompute` or letting the file watcher fire
+the next `live-update` resets to the full scene.

package/llm-docs/concepts/last-selection.md

@@ -0,0 +1,49 @@
+---
+id: concepts/last-selection
+title: Implicit "last-X" context (last sketch, last selection)
+summary: Many operations have a default target. extrude consumes the last sketch; fillet consumes the last selection. Pass arguments explicitly to override.
+tags: [concept, architecture]
+seeAlso: [concepts/scene-graph, api/sketch, api/extrude, api/fillet]
+---
+
+# The "last-X" context
+
+FluidCAD threads several implicit contexts through a script so common
+patterns stay terse:
+
+| Op | Default target |
+|----|----------------|
+| `extrude` / `cut` / `revolve` / `sweep` | last sketch |
+| `loft` | all current sketches as profiles (or pass them explicitly) |
+| `fillet` / `chamfer` / `shell` / `color` / `draft` | last selection (`select(...)` or a direct accessor immediately before) |
+| `repeat` (no last arg) | last created operation |
+| `copy` (no last arg) | last object |
+| `subtract` / `fuse` / `common` (with args) | the given objects |
+
+## Patterns
+
+```fluid.js
+// Last-sketch consumption
+sketch("xy", () => rect(100, 60).centered());
+extrude(30);                              // ← consumes the rect
+
+// Last-selection consumption via direct accessor
+const e = extrude(30);
+fillet(5, e.endEdges());                  // explicit form (preferred)
+
+// Last-selection consumption via select()
+select(edge().verticalTo("xy"));
+fillet(3);                                // picks up the selection
+```
+
+## When the implicit form bites
+
+- A sketch is consumed exactly once. To use it twice, mark it `.reusable()`.
+- A selection is good for the very next op. If you do anything between
+  `select(...)` and the consumer, capture the selection in a variable.
+- For multi-step pipelines, explicit arguments are clearer than relying
+  on the implicit chain.
+
+When the agent is unsure which sketch will be consumed, use
+`get_scene_summary` to see the current tree and which operation pulled
+which inputs.

package/llm-docs/concepts/scene-graph.md

@@ -0,0 +1,37 @@
+---
+id: concepts/scene-graph
+title: The scene graph and feature tree
+summary: Each call to a feature (sketch, extrude, fillet, …) appends a SceneObject to an ordered feature tree. The tree drives history, rollback, and shape reuse across re-renders.
+tags: [concept, architecture]
+seeAlso: [concepts/last-selection, concepts/history-and-rollback, api/sketch, api/extrude]
+---
+
+# The scene graph
+
+A FluidCAD script is read top-to-bottom; each modeling call appends one
+`SceneObject` to an ordered **feature tree**. The tree is the canonical
+source for everything that happens later:
+
+- Renders walk it in order, producing meshes and an `id` per object.
+- Rollback shows the partial state at any point in the tree.
+- Re-renders compare the new tree against the previous one and **reuse**
+  unchanged OCC shapes (this is what makes parameter tweaks fast).
+
+Containers (like `part(...)`) introduce a sub-tree: their children only
+auto-fuse with each other, not with the outside world.
+
+## Implicit consumption
+
+Most features consume the **last** matching item (last sketch, last
+selection, last operation). See [[concepts/last-selection]] for the full
+rules. The feature tree records both the consumer and what it consumed —
+so swapping a sketch's parameters in source code can be reused without
+re-running everything downstream.
+
+## What the agent gets
+
+`get_scene_summary` returns the feature tree projected to a JSON-safe
+view: one entry per operation, with `kind` (`sketch`, `extrude`, …),
+`params` (operation-specific), `sourceLocation` (file + line), and
+`shapeIds`. `list_shapes` returns the flat shape list with the owning
+operation's id. Pair them when answering "what does shape X come from?"