fluidcad 0.0.36 → 0.0.38

package/llm-docs/api/helix.md

@@ -0,0 +1,64 @@
+---
+id: api/helix
+title: helix(axis | source)
+summary: Creates a helical wire around an axis or derived from existing geometry (cylindrical/conical face, line or circular edge) — the path for springs, threads, and coils. Sweep a profile along it to make material.
+tags: [api, 3d, wire]
+symbols: [helix]
+seeAlso: [api/sweep, api/axis, api/select, api/types/helix]
+---
+
+# helix
+
+Imported from `fluidcad/core`.
+
+```ts
+helix(axis: AxisLike)          // e.g. "z", an axis() object, or axis-like
+helix(source: SceneObject)     // face or edge selection
+```
+
+Returns `Helix` (extends `SceneObject`) — a helical **wire**, not a solid.
+Pass it as the path to `sweep(path, profile)` to build springs and threads.
+
+Chain to configure geometry; any two of pitch/turns/height determine the
+third:
+
+- `.pitch(p)` — axial rise per full revolution.
+- `.turns(n)` — number of revolutions (fractional allowed; default 1).
+- `.height(h)` — total axial extent (default 50, or `pitch × turns`).
+- `.radius(r)` — start radius (default 20 for axis/line input; for a
+  cylindrical face defaults to the face radius).
+- `.endRadius(r)` — end radius; when ≠ `radius()` the helix tapers
+  conically. Ignored for face/circular-edge sources.
+- `.startOffset(mm)` / `.endOffset(mm)` — shift the start/end along the
+  axis (negative start offset or positive end offset extends past the
+  source's bounds — useful for threads that run off the stock).
+
+With a `SceneObject` source the frame is derived from the geometry:
+a **cylindrical face** supplies axis, radius, and height; a **conical
+face** makes the helix follow the cone's taper (radii derived, overrides
+ignored); a **line edge** becomes the axis with height = line length; a
+**circular edge** supplies axis (circle normal) and radius. Multi-shape
+sources must be narrowed with `select(...)` to one face or edge.
+
+Constraints: turns > 0, pitch ≠ 0, radii > 0 over the whole height.
+
+## Example
+
+```fluid.js
+import { sketch, circle, hMove, helix, sweep } from "fluidcad/core";
+
+const path = helix("z").radius(15).pitch(10).turns(5);
+
+const profile = sketch("left", () => {
+    hMove(15);
+    circle(2);
+});
+
+sweep(path, profile);
+```
+
+For a thread, build the helix at a cylinder's surface radius (or directly
+from the face via `helix(select(face().cylinder()))`) and sweep a profile —
+the sweep fuses with the cylinder by default; chain `.remove()` on the
+sweep to carve a groove instead. See [[api/sweep]] for sweep options and
+[[api/types/helix]] for the full method list.

package/llm-docs/api/index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-06-06T08:18:55.590Z",
+  "generatedAt": "2026-06-21T11:15:51.248Z",
   "symbols": {
     "arc": "api/arc",
     "axis": "api/axis",
@@ -33,6 +33,7 @@
     "extrude": "api/extrude",
     "face": "api/face-filter",
     "fillet": "api/fillet",
+    "helix": "api/helix",
     "line": "api/line",
     "load": "api/load",
     "local": "api/local",
@@ -61,6 +62,7 @@
     "sweep": "api/sweep",
     "tArc": "api/tarc",
     "tCircle": "api/tcircle",
+    "text": "api/text",
     "tLine": "api/tline",
     "translate": "api/translate",
     "ALine": "api/types/aline",
@@ -88,6 +90,8 @@
     "IExtrude": "api/types/extrude",
     "Geometry": "api/types/geometry",
     "IGeometry": "api/types/geometry",
+    "Helix": "api/types/helix",
+    "IHelix": "api/types/helix",
     "HLine": "api/types/hline",
     "IHLine": "api/types/hline",
     "LinearRepeatOptions": "api/types/linear-repeat-options",
@@ -125,6 +129,8 @@
     "ISweep": "api/types/sweep",
     "TangentArcTwoObjects": "api/types/tangent-arc-two-objects",
     "ITangentArcTwoObjects": "api/types/tangent-arc-two-objects",
+    "Text": "api/types/text",
+    "IText": "api/types/text",
     "Transformable": "api/types/transformable",
     "ITransformable": "api/types/transformable",
     "Trim": "api/types/trim",
@@ -134,6 +140,9 @@
     "Vertex": "api/types/vertex",
     "LazyVertex": "api/types/vertex",
     "VLine": "api/types/vline",
-    "IVLine": "api/types/vline"
+    "IVLine": "api/types/vline",
+    "Wrap": "api/types/wrap",
+    "IWrap": "api/types/wrap",
+    "wrap": "api/wrap"
   }
 }

package/llm-docs/api/text.md

@@ -0,0 +1,52 @@
+---
+id: api/text
+title: text(string) / text(plane, string) / text(string, path)
+summary: Renders a text string as sketch geometry — glyph outlines that extrude, wrap, or follow a path like any other profile.
+tags: [api, 2d, sketch]
+symbols: [text]
+seeAlso: [api/sketch, api/wrap, api/extrude, api/types/text]
+---
+
+# text
+
+Imported from `fluidcad/core`.
+
+```ts
+text(text: string)                           // inside a sketch, at the cursor
+text(plane: PlaneLike | SceneObject, text: string)   // standalone, on a plane or face
+text(text: string, path: SceneObject)        // glyphs laid out along a sketch path
+```
+
+Returns `Text` (an extrudable geometry). Glyph outlines become regular
+sketch profiles: `extrude()` them for 3D text, `wrap()` them onto a
+cylinder, or use them as cut profiles. The string starts at the sketch
+cursor (or the plane origin) with the baseline along the local x axis.
+
+Chain methods:
+
+- `.size(height)` — cap height in mm (default 10).
+- `.font(name)` / `.weight(400 | "bold")` / `.bold()` / `.italic()` —
+  typeface selection; system fonts are resolved by family name.
+- `.align("left" | "center" | "right" | "start" | "end" | "space-between" | "space-around")` —
+  alignment relative to the cursor, or along a path; `"space-between"` and
+  `"space-around"` distribute glyphs over the whole path like the CSS
+  flexbox values (path text only).
+- `.lineSpacing(factor)` / `.letterSpacing(extra)` — multi-line and
+  tracking control.
+- Path layout only: `.offset(distance)` — shift glyphs off the path,
+  `.flip()` — mirror to the other side, `.startAt(distance)` — arc-length
+  start position.
+
+## Example
+
+```fluid.js
+import { extrude, sketch, text } from "fluidcad/core";
+
+sketch("xz", () => {
+    text("FluidCAD").size(14).bold();
+});
+extrude(4);
+```
+
+See [[api/wrap]] for wrapping text onto cylinders and cones, and
+[[api/types/text]] for the full chain-method reference.

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

@@ -0,0 +1,105 @@
+---
+id: api/types/helix
+title: Helix
+summary: "A 3D helix wire — a single edge that traces a helix curve on a cylindrical or conical surface."
+tags: [api, type, interface]
+symbols: [Helix, IHelix]
+seeAlso: [api/types/scene-object]
+---
+# Helix
+
+```ts
+interface Helix extends SceneObject {
+  pitch(pitch: number): this;
+  turns(turns: number): this;
+  startOffset(offset: number): this;
+  endOffset(offset: number): this;
+  height(height: number): this;
+  radius(radius: number): this;
+  endRadius(radius: number): this;
+}
+```
+
+A 3D helix wire — a single edge that traces a helix curve on a cylindrical or
+conical surface. Used as a path for `sweep()` to produce springs, threads, and
+coils.
+
+Created from one of:
+- An axis (`AxisLike`): user supplies geometry via chained config.
+- A cylindrical or conical face: axis + radii + height derived from the face.
+- A line edge: axis = the line, height = line length.
+- A circular edge: axis = circle normal, radius = circle radius.
+
+Extends [[api/types/scene-object]].
+
+## Methods
+
+### `pitch()`
+
+Axial rise per turn (distance along the helix axis covered per full revolution).
+If unset, derived from `height / turns`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `pitch` | `number` |  |
+
+### `turns()`
+
+Number of full turns. Fractional values are allowed. Default 1.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `turns` | `number` |  |
+
+### `startOffset()`
+
+Shifts the start of the helix along its axis, in axial mm. Positive values
+trim the start (move it toward the end); negative values extend it. Default 0.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `offset` | `number` |  |
+
+### `endOffset()`
+
+Extends (positive) or trims (negative) the helix at its end, in axial mm.
+Default 0.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `offset` | `number` |  |
+
+### `height()`
+
+Total axial height. Overrides face/edge-derived height when set. For line-edge
+input, defaults to the line length. For circular-edge / pure-axis input,
+defaults to 50 if neither this nor `pitch * turns` determine it.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `height` | `number` |  |
+
+### `radius()`
+
+Start radius. Defaults to 20 for axis/line-edge input. For a cylindrical
+face input, defaults to the face's radius and may be overridden (useful for
+sweep/fuse workflows where the helix tube must overlap the cylinder
+volumetrically — offset by ~1mm to avoid pure tangency). Ignored on
+conical face input (radius is derived from face geometry).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `radius` | `number` |  |
+
+### `endRadius()`
+
+End radius — when different from `radius()`, produces a conical helix.
+Defaults to `radius()`. Ignored on face/circle inputs.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `radius` | `number` |  |
+
+## Inherited
+
+From [[api/types/scene-object]]: `name()`, `reusable()`

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

@@ -0,0 +1,138 @@
+---
+id: api/types/text
+title: Text
+summary: "The Text type. Extends ExtrudableGeometry; adds 11 methods."
+tags: [api, type, interface]
+symbols: [Text, IText]
+seeAlso: [api/types/extrudable-geometry]
+---
+# Text
+
+```ts
+interface Text extends ExtrudableGeometry {
+  size(value: number): this;
+  font(name: string): this;
+  weight(value: string | number): this;
+  bold(): this;
+  italic(value?: boolean): this;
+  align(value: "left" | "right" | "center" | "start" | "end" | "space-between" | "space-around"): this;
+  lineSpacing(value: number): this;
+  letterSpacing(value: number): this;
+  offset(value: number): this;
+  flip(value?: boolean): this;
+  startAt(distance: number): this;
+}
+```
+
+Extends [[api/types/extrudable-geometry]].
+
+## Methods
+
+### `size()`
+
+Sets the text height (em size) in model units. Default 10.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value` | `number` | The em size. |
+
+### `font()`
+
+Sets the font. A name without a font extension (e.g. `"Arial"`) is resolved
+to a system font; a value ending in `.ttf`/`.otf`/`.ttc`/`.woff` (e.g.
+`"fonts/Brand.ttf"`) is loaded as a workspace-relative file. When omitted, a
+default system font is used.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | A system family name or a workspace-relative font file path. |
+
+### `weight()`
+
+Sets the font weight: a number (100–900) or a name such as `"regular"`,
+`"medium"`, or `"bold"`. Resolves to the matching face (or the wght axis of a
+variable font).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value` | `string` \| `number` | The weight as a number or name. |
+
+### `bold()`
+
+Shortcut for `weight(700)`.
+
+### `italic()`
+
+Renders the italic/oblique face of the font.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value` | `boolean` | Whether to use italic (defaults to true). *(optional)* |
+
+### `align()`
+
+Horizontal alignment of the text. For straight text it is relative to the
+origin point; for text along a path it positions the run against the
+path: `"start"` begins at the path's start, `"center"` centers on the
+midpoint, `"end"` finishes at the path's end, `"space-between"` justifies
+the glyphs evenly across the whole path, and `"space-around"` spreads
+them with half a gap before the first glyph and after the last, like the
+CSS flexbox value (both path text only). `"left"` and `"right"` are
+synonyms of `"start"` and `"end"`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value` | `"left"` \| `"right"` \| `"center"` \| `"start"` \| `"end"` \| `"space-between"` \| `"space-around"` | `"left"`/`"start"` (default), `"center"`, `"right"`/`"end"`, `"space-between"`, or `"space-around"`. |
+
+### `lineSpacing()`
+
+Line-height multiplier for multi-line text (newlines in the string).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value` | `number` | Multiplier on the font's natural line height (default 1). |
+
+### `letterSpacing()`
+
+Extra spacing added between glyphs, in model units (default 0).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value` | `number` | The additional advance per glyph. |
+
+### `offset()`
+
+Shifts the baseline perpendicular to the path, in model units: positive
+values move the text toward its "up" side, negative below the path.
+Only applies to text following a path (`text(string, path)`).
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value` | `number` | The perpendicular baseline shift. |
+
+### `flip()`
+
+Mirrors the text to the other side of the path, reversing the reading
+direction. On a closed path (circle, loop) text sits on the outside by
+default — `.flip()` moves it inside. On an open path it mirrors the text
+below the curve. Only applies to text following a path.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value` | `boolean` | Whether to flip (defaults to true). *(optional)* |
+
+### `startAt()`
+
+Shifts where the text starts along the path, as an arc-length distance
+from the path's start (combines with `align()`). On a closed path the
+text wraps around. Only applies to text following a path.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `distance` | `number` | The arc-length shift in model units. |
+
+## Inherited
+
+From [[api/types/geometry]]: `guide()`, `start()`, `end()`, `tangent()`
+
+From [[api/types/scene-object]]: `name()`, `reusable()`

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

@@ -0,0 +1,131 @@
+---
+id: api/types/wrap
+title: Wrap
+summary: "The Wrap type. Extends BooleanOperation; adds 10 methods."
+tags: [api, type, interface]
+symbols: [Wrap, IWrap]
+seeAlso: [api/types/boolean-operation]
+---
+# Wrap
+
+```ts
+interface Wrap extends BooleanOperation {
+  startFaces(...args: (number | FaceFilter)[]): SceneObject;
+  endFaces(...args: (number | FaceFilter)[]): SceneObject;
+  startEdges(...args: (number | EdgeFilter)[]): SceneObject;
+  endEdges(...args: (number | EdgeFilter)[]): SceneObject;
+  sideFaces(...args: (number | FaceFilter)[]): SceneObject;
+  sideEdges(...args: (number | EdgeFilter)[]): SceneObject;
+  internalFaces(...args: (number | FaceFilter)[]): SceneObject;
+  internalEdges(...args: (number | EdgeFilter)[]): SceneObject;
+  drill(value?: boolean): this;
+  pick(...points: Point2DLike[]): this;
+}
+```
+
+Extends [[api/types/boolean-operation]].
+
+## Methods
+
+### `startFaces()`
+
+Selects the faces lying on the target surface (the base of the wrap).
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `FaceFilter`)[] | Numeric indices or FaceFilterBuilder instances to filter the selection. *(optional)* |
+
+### `endFaces()`
+
+Selects the raised (or recessed) faces offset from the target surface by the wrap thickness.
+
+**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 base faces of the wrap.
+
+**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 offset faces of the wrap.
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `EdgeFilter`)[] | Numeric indices or EdgeFilterBuilder instances to filter the selection. *(optional)* |
+
+### `sideFaces()`
+
+Selects the wall faces created from the outer boundary of each wrapped region.
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `FaceFilter`)[] | Numeric indices or FaceFilterBuilder instances to filter the selection. *(optional)* |
+
+### `sideEdges()`
+
+Selects edges on the wall faces, excluding edges shared with base/offset faces.
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `EdgeFilter`)[] | Numeric indices or EdgeFilterBuilder instances to filter the selection. *(optional)* |
+
+### `internalFaces()`
+
+Selects the wall faces created from holes inside a wrapped region.
+
+**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 hole walls of the wrap.
+
+**Returns**: [[api/types/scene-object]].
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `...args` | (`number` \| `EdgeFilter`)[] | Numeric indices or EdgeFilterBuilder instances to filter the selection. *(optional)* |
+
+### `drill()`
+
+Enables or disables drill mode, which partitions the sketch into face regions
+before wrapping.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `value` | `boolean` | `true` to enable (default), `false` to disable. *(optional)* |
+
+### `pick()`
+
+Restricts wrapping 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 wrap. *(optional)* |
+
+## Inherited
+
+From [[api/types/boolean-operation]]: `add()`, `'new'()`, `remove()`, `scope()`
+
+From [[api/types/scene-object]]: `name()`, `reusable()`

package/llm-docs/api/wrap.md

@@ -0,0 +1,62 @@
+---
+id: api/wrap
+title: wrap(thickness, sketch, face)
+summary: Develops a sketch onto a cylindrical or conical face and raises it by a thickness — embossed or engraved labels, logos, and features that follow a curved wall.
+tags: [api, 3d, solid]
+symbols: [wrap]
+seeAlso: [api/sketch, api/types/text, api/select, api/extrude]
+---
+
+# wrap
+
+Imported from `fluidcad/core`.
+
+```ts
+wrap(thickness, sketch: SceneObject, face: SceneObject)
+```
+
+Returns `Wrap` (extends `BooleanOperation`). Bends a flat sketch onto a
+curved face like a label onto a bottle: the sketch is developed onto the
+surface with lengths preserved (a true wrap, not a projection), then
+thickened by `thickness` along the surface normal. `thickness` must be
+positive; the operation mode picks the direction:
+
+- default / `.add()` — emboss: the pad is raised off the surface and fused.
+- `.remove()` — engrave: the sketch is sunk `thickness` deep into the surface.
+- `.new()` — keep the wrapped pad as a standalone solid.
+- `.scope(...)` — limit which solids are fused/cut.
+
+The target `face` must be **cylindrical or conical** (e.g.
+`select(face().cylinder())`). Placement: the sketch plane's origin lands on
+the nearest point of the surface, the surface axis direction maps to the
+matching in-plane sketch direction, and sketch coordinates are measured from
+there along the unrolled surface. The plane's offset from the surface is
+ignored; the plane must not be perpendicular to the target's axis, and the
+sketch cannot span more than one full turn.
+
+Sketch regions keep their holes (nested profiles are subtracted), and
+`.pick(point)` / `.drill(false)` work as in `extrude`. Face/edge accessors:
+`startFaces` (on the target surface), `endFaces` (raised/engraved faces),
+`sideFaces` (outer-boundary walls), `internalFaces` (hole walls), plus the
+matching `*Edges` variants.
+
+## Example
+
+```fluid.js
+import { cylinder, move, plane, select, sketch, text, wrap } from "fluidcad/core";
+import { face } from "fluidcad/filters";
+
+cylinder(25, 60);
+const target = select(face().cylinder());
+
+const decal = sketch(plane("front", 25), () => {
+    move([0, 24]);
+    text("FLUID").size(12);
+});
+
+wrap(1, decal, target);
+```
+
+Use `wrap(1, decal, target).remove()` on the same scene to engrave the text
+instead. See [[api/types/text]] for text options and [[api/select]] for
+picking the target face.