@metamesh/modeling 0.12.0 → 0.14.0

package/dist/docs/reference/model/categories/threads.md

@@ -0,0 +1,50 @@
+# Printable threads
+
+Construct compensated thread forms and inspect allocation-free preflight facts.
+
+Thread pitch is adjacent axial spacing; lead equals pitch times starts. Prepare shared thread dimensions once. Constructors enforce safety automatically; optional preflight provides resource estimates or early control-specific validation. Native rods, internal cutters, and nuts share printable fit and end-treatment options. These forms do not certify a structural rating or a metrology class.
+
+## Functions
+
+| API | Summary |
+| --- | --- |
+| [internalThreadCutter](../internalThreadCutter.md) | Compensated internal threaded cutter. |
+| [preflightInternalThreadCutter](../preflightInternalThreadCutter.md) | Allocation-free internal-thread facts. |
+| [preflightThreadedNut](../preflightThreadedNut.md) | Allocation-free nut/cutter facts. |
+| [preflightThreadedRod](../preflightThreadedRod.md) | Allocation-free external-thread facts. |
+| [threadedNut](../threadedNut.md) | Compensated threaded nut. |
+| [threadedRod](../threadedRod.md) | Compensated external threaded rod. |
+| [threadRidge](../threadRidge.md) | Helical ridge mesh construction. |
+
+## Interfaces
+
+| API | Summary |
+| --- | --- |
+| [HelicalThreadRidgeMeshOptions](../HelicalThreadRidgeMeshOptions.md) | Runtime-neutral options for the dedicated helical ridge mesher. |
+| [HelicalThreadSolidMeshPreflight](../HelicalThreadSolidMeshPreflight.md) | Conservative allocation facts resolved before constructing a direct thread solid mesh. |
+| [InternalThreadCutterOptions](../InternalThreadCutterOptions.md) | Options for a compensated internal-thread subtraction tool along +Z. |
+| [PrintableThreadFitPolicy](../PrintableThreadFitPolicy.md) | Explicit radial and axial allowances for a mating printed thread pair. |
+| [ThreadedNutOptions](../ThreadedNutOptions.md) | Options for a compensated nut with an internal thread. |
+| [ThreadedNutPreflight](../ThreadedNutPreflight.md) | Allocation-free body, cutter, and end-face facts resolved for a threaded nut. |
+| [ThreadedRodOptions](../ThreadedRodOptions.md) | Options for a compensated external threaded rod along +Z. |
+| [ThreadEndTreatmentOptions](../ThreadEndTreatmentOptions.md) | Axial end controls for a generated ridge. |
+| [ThreadProfile](../ThreadProfile.md) | A validated immutable periodic thread profile in `[axial, radial]` millimetres. |
+
+## Type aliases
+
+| API | Summary |
+| --- | --- |
+| [PrintableThreadFit](../PrintableThreadFit.md) | Named baseline fit policies for calibrated FDM-style printed threads. |
+| [ThreadedNutBevel](../ThreadedNutBevel.md) | Nut-edge bevel selection. |
+| [ThreadedNutShape](../ThreadedNutShape.md) | Supported printable nut body shapes. |
+| [ThreadEndStyle](../ThreadEndStyle.md) | End shape of a generated helical ridge. |
+| [ThreadHandedness](../ThreadHandedness.md) | Direction in which a conventional helical thread advances around +Z. |
+| [ThreadLeadInEnvelope](../ThreadLeadInEnvelope.md) | Radial envelope toward which a blunt lead-in collapses. |
+| [ThreadLeadInShape](../ThreadLeadInShape.md) | BOSL2-compatible cross-section scaling curve for a blunt thread lead-in. |
+| [ThreadRidgeOptions](../ThreadRidgeOptions.md) | Parameters for a helical ridge before solid construction. |
+
+## Guides
+
+- [Build printable threads](https://metamesh.studio/docs/develop/printable-threads#build-the-first-mating-pair)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/model/categories/transforms-placement.md

@@ -0,0 +1,57 @@
+# Transforms, Vectors & Placement
+
+Calculate with immutable vectors, reuse transforms, and arrange geometry with explicit placement contracts.
+
+Use vector2/vector3 for immutable arithmetic and transform2/transform3 for reusable placements. Tuples are accepted as operands; scalar dot, length and distance return numbers. Shape.transform accepts a matching transform directly. Operations apply in written order, rotations use degrees, and optional `{ pivot }` points use world coordinates, defaulting to the origin. andThen composes placements in execution order. applyPoint includes translation, applyDirection retains scale without translation, and applyNormal uses the inverse transpose and returns a unit vector. toArray and toMatrix expose canonical data for interchange. Solid.attach and primitive placement share source/target anchors, alignment, millimetre gap and degree spin. XY placements can be explicitly embedded with to3D; to2D rejects plane changes. Part placement can reuse finished geometry.
+
+## Functions
+
+| API | Summary |
+| --- | --- |
+| [transform2](../transform2.md) | Creates an immutable XY transform, identity by default. Matrices are copied and validated. Pass it directly to Section.transform() and planar data helpers; to3D() explicitly crosses into XYZ. Zero scales and singular matrices throw GeometryError; negative scales reflect. |
+| [transform3](../transform3.md) | Creates an immutable XYZ transform, identity by default. Matrices are copied and validated. Calls apply in written order; rotations use degrees and pivots use current world coordinates. Zero scales, singular matrices, nonfinite inputs and zero rotation axes throw GeometryError. Use frameTransform3(frame) as the input for existing orthonormal frame placement. |
+| [vector2](../vector2.md) | Creates immutable XY arithmetic from a finite tuple or vector, snapshotting the coordinates. Values and results are finite. Invalid dimensions throw `INVALID_ARGUMENT`; nonfinite coordinates and overflow throw `NON_FINITE_VALUE` GeometryError. Use transform2().applyDirection(value) for rotations and nonuniform scaling. |
+| [vector3](../vector3.md) | Creates immutable XYZ arithmetic from a finite tuple or vector, snapshotting the coordinates. Values and results are finite. Invalid dimensions throw `INVALID_ARGUMENT`; nonfinite coordinates and overflow throw `NON_FINITE_VALUE` GeometryError. Use transform3().applyDirection(value) for rotations and nonuniform scaling. |
+| [anchor](../anchor.md) | Reads a copied, immutable named anchor from this exact active generation. |
+| [gridPattern](../gridPattern.md) | XY or XYZ copies, optionally centered or placed in an explicit frame. |
+| [linearPattern](../linearPattern.md) | Repeats one solid along a normalized direction. |
+| [pathPattern](../pathPattern.md) | Physical arc-length copies along a sampled path, with optional tangent orientation. |
+| [radialPattern](../radialPattern.md) | Repeats one solid about an axis. |
+
+## Interfaces
+
+| API | Summary |
+| --- | --- |
+| [Transform2](../Transform2-type.md) | Immutable reusable XY placement. Methods apply in written order; angles are degrees. |
+| [Transform3](../Transform3-type.md) | Immutable reusable XYZ placement. Methods apply in written order; angles are degrees. |
+| [Pivot2Options](../Pivot2Options.md) | A fixed XY point in world coordinates; omitted pivots use the coordinate origin. |
+| [Pivot3Options](../Pivot3Options.md) | A fixed XYZ point in world coordinates; omitted pivots use the coordinate origin. |
+| [Vector2](../Vector2-type.md) | Immutable XY arithmetic; vector operations return new values and measurements return numbers. |
+| [Vector3](../Vector3-type.md) | Immutable XYZ arithmetic; vector operations return new values and measurements return numbers. |
+| [Anchor3](../Anchor3.md) | An attachment pose on a solid or assembly. |
+| [AttachOptions](../AttachOptions.md) | Degree-based anchor attachment controls for a scoped solid. |
+| [PathPatternOptions](../PathPatternOptions.md) | Equal physical arc-length placements along an open or implicitly closed sampled path. |
+| [PrimitivePlacement](../PrimitivePlacement.md) | Placement shared by solid and filled-section factories. |
+| [PrimitivePlacementOptions](../PrimitivePlacementOptions.md) | Maps an explicit or named shape-local attachment anchor onto a world-space anchor. |
+| [RadialPatternOptions](../RadialPatternOptions.md) | Options for repeating one solid around an axis through a center point. |
+
+## Type aliases
+
+| API | Summary |
+| --- | --- |
+| [Transform2Input](../Transform2Input.md) | An immutable XY transform or its canonical row-major matrix for interchange. |
+| [Transform3Input](../Transform3Input.md) | An immutable XYZ transform or its canonical row-major matrix for interchange. |
+| [Vector2Input](../Vector2Input.md) | An XY tuple or immutable fluent vector accepted by vector operations. |
+| [Vector3Input](../Vector3Input.md) | An XYZ tuple or immutable fluent vector accepted by vector operations. |
+| [GridPatternOptions](../GridPatternOptions.md) | XY or XYZ grid with X varying fastest. The first item starts at the local origin. |
+| [LinearPatternOptions](../LinearPatternOptions.md) | Equal linear intervals determined by exactly two of count, spacing and total length. |
+| [PatternSource](../PatternSource.md) | One immutable shape, or a synchronous factory called once per copy in index order. |
+| [Transform2Matrix](../Transform2Matrix.md) | A row-major affine 3x3 XY matrix applied to column vectors. Translation occupies indices 2 and 5; the final row is `[0, 0, 1]`. |
+| [Transform3Matrix](../Transform3Matrix.md) | A row-major affine 4x4 matrix applied to column vectors. |
+
+## Guides
+
+- [Named anchors and custom frames](../../../guides/recipes.md#named-anchors-and-custom-frames)
+- [Primitive booleans and repeated placement](../../../guides/recipes.md#primitive-booleans-and-repeated-placement)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/model/circle.md

@@ -0,0 +1,39 @@
+# circle
+
+Centered circular section.
+
+**circle**(`options`: [`CircleOptions`](CircleOptions.md)): [`Section`](Section.md)
+
+
+
+## Example: Size to polygon faces
+
+```ts
+circle({ diameter: 12, sizing: "face" });
+```
+
+## Parameters
+
+<a id="options"></a>
+
+**`options`** · [`CircleOptions`](CircleOptions.md) · Required
+
+
+
+## Returns
+
+[`Section`](Section.md)
+
+
+## Related APIs
+
+- [CircleOptions](CircleOptions.md)
+- [Section](Section.md)
+
+## Guides
+
+- [Section, hole, offset, and extrusion](../../guides/recipes.md#section-hole-offset-and-extrusion)
+- [SVG sections: fills and strokes are different inputs](../../guides/concepts.md#svg-sections-fills-and-strokes-are-different-inputs)
+- [Text and font variability](../../guides/concepts.md#text-and-font-variability)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/model/components.md

@@ -0,0 +1,71 @@
+# components
+
+Observes a solid's disconnected surface shells as session-restricted solid selections.
+
+## Call Signature
+
+
+
+**components**(`solid`: [`Solid`](Solid.md)): readonly [`Solid`](Solid.md)[]
+
+
+
+## Example: Move disconnected pieces independently
+
+```ts
+const islands = union([box({ size: 8 }), box({ size: 8 }).translate([12, 0, 0])]);
+const pieces = components(islands);
+// Component order is unspecified; the index only sets a display height here.
+union(pieces.map((piece, index) => piece.translate([0, 0, index * 6])));
+```
+
+Observes a solid's disconnected surface shells as session-restricted solid selections.
+
+For solids without enclosed cavities, these shells are the disconnected material islands.
+Enclosed cavities produce separate inward shells with negative signed volume; these cannot
+be finalized alone as manufacturing parts. This does not cut connected geometry.
+Selection order and cardinality depend on evaluated topology. Results and recipes using them
+can only be evaluated in this session; composition itself requires no engine.
+
+### Parameters
+
+<a id="solid"></a>
+
+**`solid`** · [`Solid`](Solid.md) · Required
+
+
+
+### Returns
+
+readonly [`Solid`](Solid.md)[]
+
+## Call Signature
+
+
+
+**components**(`section`: [`Section`](Section.md)): readonly [`Section`](Section.md)[]
+
+
+
+Observes filled 2D islands, retaining each island's holes; empty gives [].
+Selections and recipes using them can only be evaluated in this session.
+
+### Parameters
+
+<a id="section"></a>
+
+**`section`** · [`Section`](Section.md) · Required
+
+
+
+### Returns
+
+readonly [`Section`](Section.md)[]
+
+
+## Related APIs
+
+- [Section](Section.md)
+- [Solid](Solid.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/model/compose.md

@@ -0,0 +1,31 @@
+# compose
+
+Combines disjoint components without resolving overlap.
+
+**compose**(`solids`: readonly [`Solid`](Solid.md)[]): [`Solid`](Solid.md)
+
+
+
+## Parameters
+
+<a id="solids"></a>
+
+**`solids`** · readonly [`Solid`](Solid.md)[] · Required
+
+
+
+## Returns
+
+[`Solid`](Solid.md)
+
+
+## Related APIs
+
+- [Solid](Solid.md)
+
+## Guides
+
+- [Choose the Boolean by the material you want](../../guides/fundamentals.md#choose-the-boolean-by-the-material-you-want)
+- [Primitive booleans and repeated placement](../../guides/recipes.md#primitive-booleans-and-repeated-placement)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/model/cylinder.md

@@ -0,0 +1,52 @@
+# cylinder
+
++Z cylinder or frustum. Face sizing compensates polygon faceting.
+
+**cylinder**(`options`: [`CylinderOptions`](CylinderOptions.md)): [`Solid`](Solid.md)
+
+
+
+## Example: Cylinder
+
+
+
+```ts
+cylinder({ height: 20, radius: 10 });
+```
+
+
+
+## Example: Cone
+
+
+
+```ts
+cylinder({ height: 20, radius: [10, 0] });
+```
+
+
+
+## Parameters
+
+<a id="options"></a>
+
+**`options`** · [`CylinderOptions`](CylinderOptions.md) · Required
+
+
+
+## Returns
+
+[`Solid`](Solid.md)
+
+
+## Related APIs
+
+- [CylinderOptions](CylinderOptions.md)
+- [Solid](Solid.md)
+
+## Guides
+
+- [Choose a primitive](../../guides/recipes.md#choose-a-primitive)
+- [Treated boxes, frustums, and mirrored arrays](../../guides/recipes.md#treated-boxes-frustums-and-mirrored-arrays)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/model/distance.md

@@ -0,0 +1,45 @@
+# distance
+
+Measures the minimum separation between two nonempty solids in millimetres.
+
+**distance**(`solid`: [`Solid`](Solid.md), `other`: [`Solid`](Solid.md)): `number`
+
+
+
+## Example: Measure the gap between two blocks
+
+```ts
+const left = box({ size: 10 });
+const right = box({ size: 10 }).translate([13, 0, 0]);
+const gap = distance(left, right); // 3 mm
+```
+
+Uses actual geometry, not bounding-box separation or distance between object origins.
+Contact or overlapping material returns zero, including one solid inside another.
+The kernel's search range is managed internally; the result is not capped at a caller limit.
+Empty geometry and component selections from another session reject. Results follow native numeric precision.
+
+## Parameters
+
+<a id="solid"></a>
+
+**`solid`** · [`Solid`](Solid.md) · Required
+
+
+
+<a id="other"></a>
+
+**`other`** · [`Solid`](Solid.md) · Required
+
+
+
+## Returns
+
+`number`
+
+
+## Related APIs
+
+- [Solid](Solid.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/model/ellipse.md

@@ -0,0 +1,39 @@
+# ellipse
+
+Centered elliptical section.
+
+**ellipse**(`options`: [`EllipseOptions`](EllipseOptions.md)): [`Section`](Section.md)
+
+
+
+## Example: Ellipse by full dimensions
+
+```ts
+ellipse({ size: [30, 20] });
+```
+
+## Parameters
+
+<a id="options"></a>
+
+**`options`** · [`EllipseOptions`](EllipseOptions.md) · Required
+
+
+
+## Returns
+
+[`Section`](Section.md)
+
+
+## Related APIs
+
+- [EllipseOptions](EllipseOptions.md)
+- [Section](Section.md)
+
+## Guides
+
+- [Section, hole, offset, and extrusion](../../guides/recipes.md#section-hole-offset-and-extrusion)
+- [SVG sections: fills and strokes are different inputs](../../guides/concepts.md#svg-sections-fills-and-strokes-are-different-inputs)
+- [Text and font variability](../../guides/concepts.md#text-and-font-variability)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/model/extrude.md

@@ -0,0 +1,83 @@
+# extrude
+
+Extrudes explicit corresponding contours along +Z with degree twist and top scaling. Filled Sections use `section.extrude(options)`.
+
+**extrude**(`shape`: [`CorrespondingProfile`](CorrespondingProfile.md), `options`: [`ExtrudeOptions`](ExtrudeOptions.md)): [`Solid`](Solid.md)
+
+
+
+## Example: Extrude
+
+```ts
+import { extrude, matchProfiles } from "@metamesh/modeling";
+import { rectangleProfile } from "@metamesh/modeling/geometry";
+
+const [profile] = matchProfiles([rectangleProfile({ size: [30, 20] })]);
+extrude(profile!, { height: 8 });
+```
+
+## Parameters
+
+<a id="shape"></a>
+
+**`shape`** · [`CorrespondingProfile`](CorrespondingProfile.md) · Required
+
+
+
+<a id="options"></a>
+
+**`options`** · [`ExtrudeOptions`](ExtrudeOptions.md) · Required
+
+- [`height`](ExtrudeOptions.md#height) · `number` · Required
+
+  Positive extrusion height in millimetres.
+
+- [`center`](ExtrudeOptions.md#center) · `boolean` · Optional
+
+  Center the extrusion on Z; otherwise its bottom is at zero. Defaults to false.
+
+- [`ends`](ExtrudeOptions.md#ends) · [`EndTreatments`](EndTreatments.md) · Optional
+
+  Independent inward end treatments on straight convex single-contour extrusions.
+
+- [`divisions`](ExtrudeOptions.md#divisions) · `number` · Optional
+
+  Exact number of intermediate profiles, nonnegative; overrides physical sampling.
+
+- [`limits`](ExtrudeOptions.md#limits) · `Partial`\<[`ModelingLimits`](ModelingLimits.md)\> · Optional
+
+  Explicit output and sampling allocation ceilings.
+
+- [`resolution`](ExtrudeOptions.md#resolution) · [`GeometryResolution`](GeometryResolution.md) · Optional
+
+  Operation-level physical policy over the nearest model scope.
+
+- [`scaleTop`](ExtrudeOptions.md#scaletop) · `number` \| [`Vector2Tuple`](Vector2Tuple.md) · Optional
+
+  Finite uniform or XY scale of the top profile; defaults to one.
+
+- [`twistDegrees`](ExtrudeOptions.md#twistdegrees) · `number` · Optional
+
+  Finite rotation of the top profile about +Z, in degrees; defaults to zero.
+
+
+
+## Returns
+
+[`Solid`](Solid.md)
+
+
+## Related APIs
+
+- [CorrespondingProfile](CorrespondingProfile.md)
+- [ExtrudeOptions](ExtrudeOptions.md)
+- [Solid](Solid.md)
+
+## Guides
+
+- [Revolve a radial profile](../../guides/recipes.md#revolve-a-radial-profile)
+- [Rotation-minimizing path sweep](../../guides/recipes.md#rotation-minimizing-path-sweep)
+- [Matched-section loft](../../guides/recipes.md#matched-section-loft)
+- [Choose a modeling path](../../guides/concepts.md#choose-a-modeling-path)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/model/generate.md

@@ -0,0 +1,46 @@
+# generate
+
+Defines a typed model without executing it. Use `computed` only for work worth reusing.
+
+**generate**\<`P`, `S` = `Record`\<`never`, `never`\>\>(`callback`: [`GenerateCallback`](GenerateCallback.md)\<`P`, `S`\>): [`ModelProgram`](ModelProgram.md)\<`P`, `S`\>
+
+
+
+## Example: A simple model
+
+```ts
+const model = generate<{ height: number }>(({ params, part, assert }) => {
+  assert(params.height > 0, "Height must be positive.");
+  return part("body", box({ size: [10, 10, params.height] }));
+});
+```
+
+## Type Parameters
+
+### P
+
+`P`
+
+### S
+
+`S` = `Record`\<`never`, `never`\>
+
+## Parameters
+
+<a id="callback"></a>
+
+**`callback`** · [`GenerateCallback`](GenerateCallback.md)\<`P`, `S`\> · Required
+
+
+
+## Returns
+
+[`ModelProgram`](ModelProgram.md)\<`P`, `S`\>
+
+
+## Related APIs
+
+- [GenerateCallback](GenerateCallback.md)
+- [ModelProgram](ModelProgram.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/model/gridPattern.md

@@ -0,0 +1,80 @@
+# gridPattern
+
+XY or XYZ copies, optionally centered or placed in an explicit frame.
+
+## Call Signature
+
+
+
+**gridPattern**(`source`: [`PatternSource`](PatternSource.md), `options`: [`GridPatternOptions`](GridPatternOptions.md)): readonly [`Solid`](Solid.md)[]
+
+
+
+## Example: Centered XY grid
+
+```ts
+gridPattern(box({ size: 4 }), { count: [3, 2], spacing: [10, 10], center: true });
+```
+
+XY or XYZ copies, optionally centered or placed in an explicit frame.
+
+### Parameters
+
+<a id="source"></a>
+
+**`source`** · [`PatternSource`](PatternSource.md) · Required
+
+
+
+<a id="options"></a>
+
+**`options`** · [`GridPatternOptions`](GridPatternOptions.md) · Required
+
+
+
+### Returns
+
+readonly [`Solid`](Solid.md)[]
+
+## Call Signature
+
+
+
+**gridPattern**(`source`: [`PatternSource`](PatternSource.md)\<[`Section`](Section.md)\>, `options`: [`GridPatternOptions`](GridPatternOptions.md)): readonly [`Section`](Section.md)[]
+
+
+
+Repeats a filled Section on a grid; placements must preserve its XY plane.
+
+### Parameters
+
+<a id="source-1"></a>
+
+**`source`** · [`PatternSource`](PatternSource.md)\<[`Section`](Section.md)\> · Required
+
+
+
+<a id="options-1"></a>
+
+**`options`** · [`GridPatternOptions`](GridPatternOptions.md) · Required
+
+
+
+### Returns
+
+readonly [`Section`](Section.md)[]
+
+
+## Related APIs
+
+- [GridPatternOptions](GridPatternOptions.md)
+- [PatternSource](PatternSource.md)
+- [Section](Section.md)
+- [Solid](Solid.md)
+
+## Guides
+
+- [Named anchors and custom frames](../../guides/recipes.md#named-anchors-and-custom-frames)
+- [Primitive booleans and repeated placement](../../guides/recipes.md#primitive-booleans-and-repeated-placement)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/model/heightfield.md

@@ -0,0 +1,40 @@
+# heightfield
+
+Closed rectilinear top above a flat base, with uniform or explicit XY coordinates. Samples each grid height once; center-error triangulation also samples each cell centre. The retained callback must capture independent immutable inputs, not live session readers or parameters.
+
+**heightfield**(`options`: [`HeightfieldOptions`](HeightfieldOptions.md)): [`Solid`](Solid.md)
+
+
+
+## Example: Heightfield
+
+
+
+```ts
+heightfield({
+  size: [30, 20], segments: [24, 16],
+  height: ([x, y]) => 3 + Math.cos(x / 5) * Math.cos(y / 5),
+});
+```
+
+
+
+## Parameters
+
+<a id="options"></a>
+
+**`options`** · [`HeightfieldOptions`](HeightfieldOptions.md) · Required
+
+
+
+## Returns
+
+[`Solid`](Solid.md)
+
+
+## Related APIs
+
+- [HeightfieldOptions](HeightfieldOptions.md)
+- [Solid](Solid.md)
+
+Package: `@metamesh/modeling@0.14.0`.