forgecad 0.9.13 → 0.9.15

package/dist/docs-raw/generated/core.md

@@ -25,6 +25,8 @@ skill-order: 100
 - [SurfacePattern](#surfacepattern)
 - [Pattern2D](#pattern2d)
 - [Pattern2DBuilder](#pattern2dbuilder)
+- [HermiteCurve3D](#hermitecurve3d)
+- [QuinticHermiteCurve3D](#quintichermitecurve3d)
 - [ShapeRef](#shaperef)
 - [ANCHOR3D_NAMES](#anchor3d-names)
 - [verify](#verify)
@@ -364,9 +366,9 @@ selectEdges(shape: Shape, query?: EdgeQuery): EdgeSegment[]
 | `minLength?` | `number` | Filter: minimum edge length. |
 | `maxLength?` | `number` | Filter: maximum edge length. |
 | `within?` | `BoundingRegion` | Filter: edge midpoint must be within this bounding region. |
-| `atZ?` | `number` | Shorthand: edge midpoint Z ≈ this value (within `tolerance`). Equivalent to `within: { zMin: atZ - tol, zMax: atZ + tol }`. |
-| `tolerance?` | `number` | Position tolerance for approximate matches (default: `1.0`). Used by `atZ` and `near`. |
-| `angleTolerance?` | `number` | Angular tolerance in degrees for `parallel`/`perpendicular` filters (default: `10`). |
+| `atZ?` | `number` | Shorthand: edge midpoint Z is approximately this value within `tolerance`. |
+| `tolerance?` | `number` | Position tolerance for approximate matches. Used by `atZ` and `near`. Default: `1.0`. |
+| `angleTolerance?` | `number` | Angular tolerance in degrees for `parallel`/`perpendicular` filters. Default: `10`. |
 
 `BoundingRegion`: `{ xMin?: number, xMax?: number, yMin?: number, yMax?: number, zMin?: number, zMax?: number }`
 
@@ -418,7 +420,16 @@ coalesceEdges(segments: EdgeSegment[], tolerance?: number): EdgeSegment[]
 
 #### `require()` — Import a module with optional ForgeCAD parameter overrides. Returns the module's exports.
 
-When importing a `.forge.js` file, the return value is what the script returns. If the script returns a metadata object (e.g. `{ shape: myShape, bolts: {...} }`), the caller receives the full object — renderable values and metadata together.
+When importing a `.forge.js` file, most return values are passed through exactly as the script returns them. Assembly returns have one extra composition rule: an unsolved [`Assembly`](/docs/assembly#assembly) is wrapped as an [`ImportedAssembly`](/docs/assembly#importedassembly), preserving `solve(state)` and `mergeInto()` across file boundaries, while a returned [`SolvedAssembly`](/docs/assembly#solvedassembly) stays a [`SolvedAssembly`](/docs/assembly#solvedassembly). If the script returns a metadata object (e.g. `{ shape: myShape, bolts: {...} }`), the caller receives the full object — renderable values and metadata together.
+
+**Assembly return contract**
+
+| `.forge.js` return value | `require()` result |
+|---|---|
+| `Assembly` | `ImportedAssembly` |
+| `SolvedAssembly` | `SolvedAssembly` |
+
+[`ImportedAssembly`](/docs/assembly#importedassembly) exposes default-pose helpers such as `getPart()`, `collisionReport()`, and `minClearance()`. Use `solve(state)` first when inspecting a non-default pose.
 
 **Path rule:** Always include the file extension in relative imports: use `require("./part.forge.js")` for model files and `require("./helpers.js")` for plain helper modules. ForgeCAD does not apply Node-style extension inference, so `require("./part")` will not find `part.forge.js` or `part.js`.
 
@@ -449,6 +460,26 @@ mount.bolts.pos  // access the metadata
 mount.shape       // access the geometry
 ```
 
+**Forge-aware builder module pattern** — use `.forge.js` modules for reusable sketch, profile, shape, or assembly builders that need ForgeCAD runtime APIs:
+
+```js
+// profiles.forge.js — inspectable on its own, reusable through require()
+function wheelProfile() {
+  return circle2d(40).subtract(circle2d(18));
+}
+
+return {
+  preview: [{ name: 'Wheel profile', sketch: wheelProfile() }],
+  make: { wheelProfile },
+};
+
+// main.forge.js
+const profiles = require('./profiles.forge.js');
+const wheel = profiles.make.wheelProfile().extrude(8);
+```
+
+Keep exported builders pure over top-level constants, top-level `param()` values, or explicit function arguments. Do not declare new `param()` values inside an exported builder if callers need `require('./profiles.forge.js', { Width: 80 })` overrides: import overrides are validated while the module loads, before any exported builder is called. Use plain `.js` modules only for pure constants, tables, math helpers, and formatting code that does not construct ForgeCAD geometry.
+
 ```ts
 require(path: string, paramOverrides?: Record<string, number | string>): any
 ```
@@ -477,10 +508,18 @@ importSvgSketch(fileName: string, options?: SvgImportOptions): Sketch
 | `simplify?` | `number` | Simplification tolerance for final sketch cleanup. |
 | `invertY?` | `boolean` | Flip SVG Y-down coordinates to CAD Y-up. Enabled by default. |
 
-#### `importMesh()` — Import an external mesh file (STL, OBJ, 3MF) as a Shape.
+#### `importMesh()` — Import an external mesh file (STL, OBJ, 3MF).
+
+By default, 3MF build items are flattened into one Shape for compatibility. Use `separateObjects: true` to import 3MF build items/resource objects as a named ShapeGroup whose children are targetable by `forgecad ls`. Use `object` to import one item by the stable ref/name reported by `forgecad run`.
+
+```js
+const all = importMesh("./assembly.3mf", { separateObjects: true });
+const pin = all.child("Pin #001");
+const plate = importMesh("./assembly.3mf", { object: "3mf:build:001:object:7" });
+```
 
 ```ts
-importMesh(fileName: string, options?: { scale?: number; center?: boolean; }): Shape
+importMesh(fileName: string, options?: { scale?: number; center?: boolean; object?: string; separateObjects?: boolean; }): Shape | ShapeGroup
 ```
 
 #### `importStep()` — Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires running with the OCCT backend.
@@ -953,6 +992,25 @@ box(100, 100, 10).color('#gold').material({ metalness: 0.95, roughness: 0.05 }).
 material(props: ShapeMaterialProps): Shape
 ```
 
+**`ShapeMaterialProps`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
+| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
+| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
+| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
+| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
+| `wireframe?` | `boolean` | Render as wireframe. Default: false |
+| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
+| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
+| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
+| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
+| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
+| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
+| `specularColor?` | `string` | Specular highlight tint. |
+| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
+
 **Face Topology**
 
 #### `face()` — Resolve a face by user-authored label or compiler-owned name. Returns a `FaceRef` that can be passed to `.onFace()`, `projectToPlane()`, or used directly in placement.
@@ -1073,6 +1131,15 @@ body.edgesOf('top', { concave: true })
 edgesOf(faceLabel: string, options?: EdgesOfOptions): EdgeSegment[]
 ```
 
+**`EdgesOfOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `exclude?` | `string \| string[]` | Exclude edges shared with these named faces. |
+| `convex?` | `boolean` | Additional geometric filter: only convex edges. |
+| `concave?` | `boolean` | Additional geometric filter: only concave edges. |
+| `minLength?` | `number` | Minimum edge length filter. |
+
 #### `edgesBetween()` — Return edges shared between two named faces.
 
 An edge is "between" faces A and B when one of its adjacent mesh triangles belongs to A and the other belongs to B. This is the most precise topological edge selection — "fillet the edges where the top meets the wall."
@@ -1154,6 +1221,8 @@ rotateZ(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): Sh
 rotateAroundTo(axis: [ number, number, number ], pivot: [ number, number, number ], movingPoint: RotationPointLike, targetPoint: RotationPointLike, options?: RotateAroundToOptions): Shape
 ```
 
+`RotateAroundToOptions`: `{ mode?: RotateAroundToMode }`
+
 #### `transform()` — Apply a 4x4 affine transform matrix (column-major) or a Transform object.
 
 ```ts
@@ -1250,6 +1319,11 @@ box(100, 100, 20).pocket('top', 8, { scale: 0.8 })
 pocket(face: FaceSelector, depth: number, opts?: PocketOptions): Shape
 ```
 
+**`PocketOptions`**
+- `inset?: number` — Shrink the face boundary inward by this many mm before extruding. Produces angled walls when combined with depth. Default: 0 (full face).
+- `scale?: number` — Scale the face profile uniformly (e.g. 0.8 = 80% of the face area). Mutually exclusive with `inset`; `inset` takes precedence if both are set.
+- `join?: "Square" | "Round" | "Miter"` — Corner join style when using `inset`. Default: 'Round'.
+
 #### `boss()` — Add a boss (protrusion) from the named face.
 
 ```js
@@ -1272,6 +1346,30 @@ box(50, 50, 20).hole('top', { diameter: 6, counterbore: { diameter: 12, depth: 3
 hole(faceOrRef: SketchFaceTarget | FaceRef, opts: ShapeHoleOptions): Shape
 ```
 
+**`FaceRef`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `normal` | `[ number, number, number ]` | Normal direction of the face |
+| `center` | `[ number, number, number ]` | Center point of the face |
+| `query?` | `FaceQueryRef` | Compiler-owned face query when available. |
+| `planar?` | `boolean` | True when the face can host a 2D sketch placement frame |
+| `uAxis?` | `[ number, number, number ]` | Face-local horizontal axis for planar faces |
+| `vAxis?` | `[ number, number, number ]` | Face-local vertical axis for planar faces |
+| `surface?` | `FaceSurface` | Analytic surface family when the backend can identify one. |
+| `descendant?` | `FaceDescendantMetadata` | Shared descendant-resolution metadata when this face is a semantic region/set. |
+| `name` | | — |
+
+**`FaceDescendantMetadata`**: `kind: "single" | "face-set"`, `semantic: FaceDescendantSemantic`, `memberCount: number`, `memberNames: string[]`, `coplanar: boolean`
+
+**`ShapeHoleOptions`**: `diameter: number`, `depth?: number`, `upToFace?: SketchFaceTarget | FaceRef`, `extent?: ShapeFeatureExtentOptions`, `u?: number`, `v?: number`, `counterbore?: { diameter: number; depth: number; }`, `countersink?: { diameter: number; angleDeg?: number; }`, `thread?: ShapeHoleThreadOptions`
+
+`ShapeFeatureExtentOptions`: `{ forward: ShapeFeatureExtentSideOptions, reverse?: ShapeFeatureExtentSideOptions }`
+
+`ShapeFeatureExtentSideOptions`: `{ depth?: number, upToFace?: SketchFaceTarget | FaceRef, through?: boolean }`
+
+**`ShapeHoleThreadOptions`**: `designation?: string`, `pitch?: number`, `class?: string`, `handedness?: "right" | "left"`, `depth?: number`, `modeled?: boolean`
+
 #### `cutout()` — Cut a profile-shaped pocket through a face using a placed sketch.
 
 The sketch must be placed on a face with `Sketch.onFace(...)`. The cut follows the sketch's 2D profile.
@@ -1285,6 +1383,8 @@ body.cutout(profile, { depth: 5 })
 cutout(sketch: Sketch, opts?: ShapeCutoutOptions): Shape
 ```
 
+**`ShapeCutoutOptions`**: `depth?: number`, `upToFace?: SketchFaceTarget | FaceRef`, `extent?: ShapeFeatureExtentOptions`, `taperScale?: number | [ number, number ]`
+
 **Placement**
 
 #### `placeReference()` — Translate the shape so the given anchor or reference lands on the target coordinate.
@@ -1348,6 +1448,11 @@ mast.translate(0, station, radius + 50).seatInto(fuselage, 'mount', { depth: 'fl
 seatInto(target: Shape, surface: string, options?: SeatIntoOptions): Shape
 ```
 
+**`SeatIntoOptions`**
+- `along?: [ number, number, number ]` — Movement axis. Default: inverted face normal (points into target).
+- `depth?: "full" | "flush" | number` — How deep to embed. 'full' = entire face inside. 'flush' = nearest point touches. number = mm past flush. Default: 'full'.
+- `gap?: number` — Standoff gap in mm. Positive = gap between face and target. Negative = extra penetration. Default: 0.
+
 #### `seatOver()` — Slide this shape until a target's labeled face is fully covered (inside this shape).
 
 The inverse of `seatInto`: instead of embedding *your* face into the target, you move until the *target's* face is embedded inside you.
@@ -1372,6 +1477,10 @@ seatOver(target: Shape, targetSurface: string, options?: SeatIntoOptions): Shape
 withConnectors(connectors: Record<string, ConnectorInput>): Shape
 ```
 
+**`PortInput`**: `origin?: [ number, number, number ]`, `axis?: [ number, number, number ]`, `start?: [ number, number, number ]`, `end?: [ number, number, number ]`, `up?: [ number, number, number ]`, `kind?: JointType`, `min?: number`, `max?: number`
+
+`ConnectorInput`: `{ connectorType?: string, gender?: ConnectorGender, measurements?: Record<string, number | string> }`
+
 #### `connectorNames()` — List all connector names on this shape.
 
 ```ts
@@ -1408,6 +1517,8 @@ Overloads:
 matchTo(targetOrPairs: Shape | MatchTarget | Array<[ Shape | MatchTarget, string, string ]>, selfConnOrDict?: string | Record<string, string>, targetConnOrOptions?: string | MatchToOptions, maybeOptions?: MatchToOptions): Shape
 ```
 
+`MatchToOptions`: `{ force?: boolean, angle?: number, distance?: number }`
+
 **References**
 
 #### `withReferences()` — Attach named placement references that survive normal transforms and imports.
@@ -1416,6 +1527,12 @@ matchTo(targetOrPairs: Shape | MatchTarget | Array<[ Shape | MatchTarget, string
 withReferences(refs: PlacementReferenceInput): Shape
 ```
 
+**`PlacementReferenceInput`**: `points?: Record<string, [ number, number, number ]>`, `edges?: Record<string, PlacementEdgeRef>`, `surfaces?: Record<string, PlacementSurfaceRef>`, `objects?: Record<string, PlacementObjectInput>`
+
+`PlacementEdgeRef`: `{ start: Vec3, end: Vec3 }`
+
+`PlacementSurfaceRef`: `{ center: Vec3, normal: Vec3 }`
+
 #### `referenceNames()` — List named placement references carried by this shape.
 
 ```ts
@@ -1577,6 +1694,24 @@ translate(x: number, y: number, z: number): Transform
 rotateAxis(axis: Vec3, angleDeg: number, pivot?: Vec3): Transform
 ```
 
+#### `rotateX()` — Rotate about the X axis after the current transform (parity with `Shape.rotateX`).
+
+```ts
+rotateX(angleDeg: number, pivot?: Vec3): Transform
+```
+
+#### `rotateY()` — Rotate about the Y axis after the current transform (parity with `Shape.rotateY`).
+
+```ts
+rotateY(angleDeg: number, pivot?: Vec3): Transform
+```
+
+#### `rotateZ()` — Rotate about the Z axis after the current transform (parity with `Shape.rotateZ`).
+
+```ts
+rotateZ(angleDeg: number, pivot?: Vec3): Transform
+```
+
 #### `inverse()` — Return the inverse transform.
 
 ```ts
@@ -1920,18 +2055,160 @@ constant(value?: number): Pattern2D
 sineWave(options: Pattern2DSineWaveOptions): Pattern2D
 ```
 
+**`Pattern2DSineWaveOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `direction?` | `Vec2` | Direction the wave advances in UV space. Default: [1, 0]. |
+| `wavelength` | `number` | Distance between wave peaks in surface millimeters. |
+| `amplitude?` | `number` | Height amplitude in millimeters. Default: 1. |
+| `phase?` | `number` | Phase offset in radians. Default: 0. |
+| `bias?` | `number` | Constant height offset in millimeters. Default: 0. |
+
 #### `stripes()` — Create recessed stripe bands in UV space.
 
 ```ts
 stripes(options: Pattern2DStripesOptions): Pattern2D
 ```
 
+**`Pattern2DStripesOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `direction?` | `Vec2` | Direction perpendicular to the stripe bands in UV space. Default: [1, 0]. |
+| `spacing` | `number` | Center-to-center spacing in surface millimeters. |
+| `width` | `number` | Stripe width in surface millimeters. |
+| `depth?` | `number` | Stripe groove depth in millimeters. Default: 1. |
+
 #### `overUnderWeave()` — Create an over-under woven relief pattern in UV space.
 
 ```ts
 overUnderWeave(options: Pattern2DOverUnderWeaveOptions): Pattern2D
 ```
 
+**`Pattern2DOverUnderWeaveOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `spacing` | `number \| Vec2` | Thread center-to-center spacing. A number uses the same spacing for U and V. |
+| `threadWidth` | `number \| Vec2` | Thread width. A number uses the same width for U and V. |
+| `depth?` | `number` | Thread groove depth in millimeters. Default: 0.8. |
+| `underScale?` | `number` | Relative height of the under-crossing thread. Default: 0.15. |
+
+### `HermiteCurve3D`
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `p0` | `Vec3` | Start position |
+| `p1` | `Vec3` | End position |
+| `t0` | `Vec3` | Scaled tangent at start (direction * weight * chordLength) |
+| `t1` | `Vec3` | Scaled tangent at end (direction * weight * chordLength) |
+| `chordLength` | `number` | Chord length (straight-line distance between endpoints) |
+
+**Methods:**
+
+#### `pointAt()` — Evaluate position at parameter t ∈ [0, 1]
+
+```ts
+pointAt(t: number): Vec3
+```
+
+#### `tangentAt()` — Evaluate tangent (first derivative) at parameter t ∈ [0, 1]
+
+```ts
+tangentAt(t: number): Vec3
+```
+
+#### `curvatureAt()` — Evaluate curvature vector (second derivative) at parameter t ∈ [0, 1]
+
+```ts
+curvatureAt(t: number): Vec3
+```
+
+#### `sample()` — Sample the curve as a polyline of evenly-spaced parameter values.
+
+```ts
+sample(count?: number): Vec3[]
+```
+
+#### `length()` — Approximate arc length by sampling.
+
+```ts
+length(samples?: number): number
+```
+
+#### `sampleAdaptive()` — Sample with adaptive density — more points where curvature is higher. Returns at least `minCount` points, up to `maxCount`.
+
+```ts
+sampleAdaptive(minCount?: number, maxCount?: number): Vec3[]
+```
+
+#### `toPolyline()` — Convert to a format compatible with sweep() path input.
+
+```ts
+toPolyline(samples?: number): Vec3[]
+```
+
+### `QuinticHermiteCurve3D`
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `p0` | `Vec3` | Start position |
+| `p1` | `Vec3` | End position |
+| `t0` | `Vec3` | Scaled tangent at start (direction * weight * chordLength) |
+| `t1` | `Vec3` | Scaled tangent at end (direction * weight * chordLength) |
+| `c0` | `Vec3` | Scaled second derivative at start (curvature * weight² * chordLength²) |
+| `c1` | `Vec3` | Scaled second derivative at end (curvature * weight² * chordLength²) |
+| `chordLength` | `number` | Chord length (straight-line distance between endpoints) |
+
+**Methods:**
+
+#### `pointAt()` — Evaluate position at parameter t ∈ [0, 1]
+
+```ts
+pointAt(t: number): Vec3
+```
+
+#### `tangentAt()` — Evaluate tangent (first derivative, normalized) at parameter t ∈ [0, 1]
+
+```ts
+tangentAt(t: number): Vec3
+```
+
+#### `curvatureAt()` — Evaluate curvature vector (second derivative) at parameter t ∈ [0, 1]
+
+```ts
+curvatureAt(t: number): Vec3
+```
+
+#### `sample()` — Sample the curve as a polyline of evenly-spaced parameter values.
+
+```ts
+sample(count?: number): Vec3[]
+```
+
+#### `length()` — Approximate arc length by sampling.
+
+```ts
+length(samples?: number): number
+```
+
+#### `sampleAdaptive()` — Sample with adaptive density — more points where curvature is higher. Returns at least `minCount` points, up to `maxCount`.
+
+```ts
+sampleAdaptive(minCount?: number, maxCount?: number): Vec3[]
+```
+
+#### `toPolyline()` — Convert to a format compatible with sweep() path input.
+
+```ts
+toPolyline(samples?: number): Vec3[]
+```
+
 ### `ShapeRef`
 
 A first-class reference path over a shape's semantic faces and face relationships.