@metamesh/modeling 0.15.0 → 0.17.0

package/dist/api/text.d.ts

@@ -1,9 +1,9 @@
-/** Axis-aligned bounds in two-dimensional model space. */
-export declare interface Bounds2 {
+/** Plain axis-aligned XY bounds for interchange; use bounds2 for immutable measurement methods. */
+export declare interface Bounds2Data {
   /** Inclusive maximum X/Y coordinates. */
-  readonly max: Vector2Tuple;
+  readonly max: Vector2Data;
   /** Inclusive minimum X/Y coordinates. */
-  readonly min: Vector2Tuple;
+  readonly min: Vector2Data;
 }
 
 /** Limits apply before parsing or shaping untrusted font data. */
@@ -27,7 +27,7 @@ export declare function prepareVectorFont(
 ): Promise<VectorFont>;
 
 /** A two-dimensional Cartesian vector or point. */
-export declare type Vector2Tuple = readonly [x: number, y: number];
+export declare type Vector2Data = readonly [x: number, y: number];
 
 /**
  * A prepared font owns its parsed bytes; keep handles local to their Worker or invocation.
@@ -93,7 +93,7 @@ export declare interface VectorTextLayoutOptions extends VectorTextOptions {
 /** Text measurements from the same immutable layout that supplies geometry and SVG outlines. */
 export declare interface VectorTextMetrics {
   /** Visible curve bounds after alignment, or null when the text has no ink. */
-  readonly bounds: Bounds2 | null;
+  readonly bounds: Bounds2Data | null;
   /** Unaligned logical advance and negative baseline displacement in mm; arcs retain [arc length, 0]. */
   readonly advance: readonly [number, number];
   /** Maximum logical line advance in millimetres, including spaces; arc length on circular baselines. */

package/dist/docs/guides/concepts.md

@@ -1,8 +1,9 @@
 # Geometry API concepts
 
-Choose the public Modeling modules, understand geometry and lifecycle conventions, and use them in Studio or a standalone Node or Worker host.
+Choose shapes, paths, profiles, and modules, then compose immutable geometry with clear sampling and preflight limits.
 
-Import modeling functions from the package root:
+Use Sections for filled 2D shapes, Solids for 3D material, and paths or profiles for boundaries
+and correspondence. Import modeling functions from the package root:
 
 
 
@@ -13,9 +14,30 @@ import { generate } from "@metamesh/project";
 
 
 
-Studio supplies this API and its runtime to code Projects. Standalone applications use the same
-values in a generation program. The [Model API reference](../reference/model.md) provides
-exact signatures; this guide explains how the concepts fit together.
+Studio supplies the API and runtime to code Projects. Standalone applications use the same
+values in a generation program. Use the [Model API reference](../reference/model.md) for exact
+signatures.
+
+## Choose a modeling path
+
+| Starting intent                               | Construction                                                                                                                                     | Main decision                                                                  |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| A block, cylinder, sphere, or cone            | Primitives and [solid Booleans](fundamentals.md#choose-the-boolean-by-the-material-you-want)                                 | Combine material or remove it with cutters                                     |
+| A plate, gasket, logo, or outline with holes  | A filled `Section`, section Booleans or offsets, then [extrusion](recipes.md#section-hole-offset-and-extrusion)              | Solve the outline before adding thickness                                      |
+| A hollow sleeve with a flange, cup, or knob   | [Revolve a closed radial profile](recipes.md#revolve-a-radial-profile) around +Z                                             | Describe the material, including walls and bores, in radius/height coordinates |
+| A routed strip or tube                        | [Sweep a section along a path](recipes.md#rotation-minimizing-path-sweep)                                                    | Choose section orientation and the closed seam                                 |
+| A transition between different cross sections | [Loft corresponding boundaries](recipes.md#matched-section-loft)                                                             | Match landmarks and holes between stations                                     |
+| Repeated holes or features                    | [Patterns and placement](recipes.md#primitive-booleans-and-repeated-placement)                                               | Position one feature before repeating it                                       |
+| Separate mating parts                         | [Explicit anchors](recipes.md#named-anchors-and-custom-frames) and [shared thread settings](https://metamesh.studio/docs/develop/printable-threads) | Share a mating datum and clearance decisions                                   |
+
+Combine these constructions as needed: join a flange to a sleeve, then bore either with a
+repeated cutter. Prefer an existing primitive when it fits; use `tube` for a concentric straight
+sleeve.
+
+Start with synchronous generation and return named parts. Geometry values are immutable recipes
+that the host evaluates. Add `computed` when expensive work stays unchanged across edits. See
+[generation and parameter changes](generation.md#start-with-generate) and the
+[standalone CLI entry contract](https://metamesh.studio/docs/develop/agent-authoring#model-entries).
 
 ## Choose the module for your host
 
@@ -26,36 +48,33 @@ exact signatures; this guide explains how the concepts fit together.
 | [`@metamesh/modeling/engine`](../reference/engine.md)     | Standalone initialization, model finalization, and 3MF export       | Your Node application or browser Worker |
 | [`@metamesh/modeling/text`](../reference/text.md)         | Prepare exact font bytes and vector layouts outside Studio          | Your host acquires the font bytes       |
 
-Construct immutable shapes, vectors, paths, and transforms in ordinary TypeScript and reuse them in
-synchronous generation. A host evaluates geometry and owns observations and export. Add pure
-geometry helpers for custom calculations.
+Construct shapes, vectors, paths, and transforms in ordinary TypeScript and reuse them in
+synchronous generation. The host owns evaluation, observations, and export.
 
 ## Use Modeling outside Studio
 
-Follow [Run Modeling in your application](hosting.md)
+Start with a [complete standalone model](standalone-model.md), or follow
+[Run Modeling in your application](hosting.md)
 to initialize the engine, build a model, load WASM, and export its completed snapshot.
 For lettering, [prepare exact font bytes](fonts.md) before building.
 
 ## Geometry vocabulary
 
-The public API names values by modeling role:
-
-- `Path2` and `Path3` are immutable sampled trajectories created by `path2` and `path3`.
-  Each owns its closure, traversal order, and finite coordinates.
-- `Path2Data` and `Path3Data` are tuple collections for path interchange.
-- A `Contour` is plain point data for a closed 2D boundary, without a repeated closing point.
-- `PolygonData` contains one outer contour and its holes. `RegionData` is the plain serialized
-  representation of filled 2D geometry, including disconnected polygons.
-- A `Profile` specifies identified components, contours and spans for a related shape family.
-- A `CorrespondingProfile` contains the shared sampled landmarks produced by `matchProfiles`.
-- A `Section` is a filled 2D shape used for section Booleans, offsets, extrusion, revolution,
-  sweeps, and lofts.
-- A `Solid` is a valid three-dimensional result that can participate in solid Booleans and become
-  model output.
-- An `Anchor3` is an explicit local frame used to place one solid against another.
-- `Vector2` and `Vector3` are immutable arithmetic values created by `vector2` and `vector3`.
-- `Vector2Tuple` and `Vector3Tuple` are fixed numeric tuples for coordinate interchange and kernels.
-- `Bounds2` and `Bounds3` contain finite minimum and maximum tuples for measurements and placement.
+Choose the representation by the information you need to retain:
+
+| Representation                                           | Retains                                                              | Typical use                          |
+| -------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------ |
+| `Vector2` / `Vector3`                                    | Immutable finite coordinates and arithmetic methods                  | Readable calculations                |
+| `Path2` / `Path3`                                        | Sampled points, traversal order, and closure                         | Trajectories and boundary queries    |
+| `Contour`                                                | One closed boundary's point tuples, without a repeated endpoint      | Custom calculations and meshing      |
+| `PolygonData` / `RegionData`                             | One exterior plus holes / a collection of filled polygons            | Serialized filled topology           |
+| `Profile` / `ProfileContour2`                            | Identified family topology / one closed boundary of identified spans | Correspondence across related shapes |
+| `CorrespondingProfile`                                   | Shared sampled landmarks from `matchProfiles`                        | Loft or sweep stations               |
+| `Section` / `Solid`                                      | Immutable filled 2D / 3D recipes                                     | Booleans and model construction      |
+| `Vector2Data` / `Vector3Data`, `Path2Data` / `Path3Data` | Vector tuples and complete path records                              | Interchange and numerical kernels    |
+| `Bounds2` / `Bounds3`                                    | Immutable axis-aligned extents and measurement methods               | Containment and placement queries    |
+| `Bounds2Data` / `Bounds3Data`                            | Plain min/max coordinates                                            | Measurements and interchange         |
+| `Anchor3`                                                | An attachment frame                                                  | Relative placement                   |
 
 `Section` and `Solid` are opaque immutable recipes. Construction and composition need no engine;
 ordinary recipes can be reused across sessions regardless of where they were constructed.
@@ -64,33 +83,28 @@ host's defaults. The host owns evaluation caches and native kernel values. `comp
 observation: its selected shapes, and recipes using them, can only be evaluated in the originating
 session because component identity depends on evaluated topology.
 
-Ordinary models use root Sections for shapes, Booleans, extrusion, sweeps, and lofts. The pure
-`/geometry` entry supplies point data through `circleContour`, `rectangleContour`, and other contour factories
-when custom calculations or mesh construction need it. `rectangle`, `rectangleContour`, and
-`rectangleProfile` share size, center, corner treatment, and sampling options; their result type
-reflects the operation's role.
-
-Use [`polygon(points)`](../reference/model/polygon.md) to fill one contour. The explicit
-`polygon({ outer, holes })` form validates exterior/hole topology and normalizes winding.
-`polygon({ contours, fillRule })` resolves compound paths with `"nonzero"` fill by default or
-explicit `"evenodd"` fill. Use `polygon({ polygons: data })` for existing `RegionData`.
-Every form returns the same `Section` type as `circle` or `rectangle`; subsequent Booleans may
-produce holes or disconnected components. `section.toRegionData()` observes the evaluated shape
-inside synchronous generation. Keep serialized point data for interchange or pure preparation.
-
-Use `path2(points, { closed: true })` for a reusable boundary. Its `length()` includes the closing
-edge, and `closestPoint(query)` returns a fluent point, distance, edge index, and fraction within
-that edge. Queries measure the sampled boundary; they do not measure a filled interior or an
-underlying analytic curve. Chain `transform`, `reverse`, and equal-distance `resample` to create
-new paths. Closed paths omit the duplicated endpoint. Open paths may be empty; their bounds are
-`undefined`, and closest-point queries need at least two points.
-
-Pass paths directly to `polygon`, `stroke`, sweeps, and path patterns in the matching dimension.
-`polygon(path)` requires a closed planar value and establishes exterior/hole winding. A path's
-transform preserves traversal even after reflection. Individual vector inputs and authored point
-collections accept fluent vectors as well as tuples; serialized data contracts remain tuple-only.
-`toArray()` returns frozen tuples for interchange and does not encode closure. Keep the path value
-when passing closure between operations.
+Use Sections from the root module for Booleans, extrusion, sweeps, and lofts. Use `/geometry`
+contour factories such as `circleContour` and `rectangleContour` when custom calculations or
+meshing need point data. These rectangle factories share size, center, corner treatment, and
+sampling options:
+
+| You need                                          | Choose                                                          | Result    |
+| ------------------------------------------------- | --------------------------------------------------------------- | --------- |
+| Filled material for Booleans or extrusion         | [`rectangle`](../reference/model/rectangle.md)                  | `Section` |
+| Sampled boundary coordinates                      | [`rectangleContour`](../reference/geometry/rectangleContour.md) | `Contour` |
+| Stable edge and corner identities across stations | [`rectangleProfile`](../reference/geometry/rectangleProfile.md) | `Profile` |
+
+[`polygon`](../reference/model/polygon.md) fills boundaries in four forms:
+
+- `polygon(points)` fills one contour.
+- `polygon({ outer, holes })` validates exterior/hole topology and normalizes winding.
+- `polygon({ contours, fillRule })` resolves compound paths with `"nonzero"` fill by default or
+  explicit `"evenodd"` fill.
+- `polygon({ polygons: data })` accepts existing `RegionData`.
+
+Each returns a `Section`, like `circle` or `rectangle`. Later Booleans may produce holes or
+disconnected components. Use `section.toRegionData()` inside synchronous generation to observe
+the evaluated shape; keep serialized point data for interchange or pure preparation.
 
 `rectangleProfile({ size: [width, height], treatment: { kind: "round", radius }, id })` describes
 identified spans for custom geometry. Prepare a complete explicit family with `matchProfiles`
@@ -101,16 +115,96 @@ Identified spans also accept cubic Béziers with the same endpoints and controls
 grid; physical sampling refines every member before choosing the family count. Collapsed spans
 retain repeated logical slots, while the completed loft removes degenerate faces.
 
-## Choose a modeling path
+## Choose fluent values or standalone algorithms
+
+Use methods for ordinary composition and queries on a value, such as `path.transform(...)`,
+`path.closestPoint(...)`, or `vector.normalize()`. Use standalone algorithms for specialized
+outputs, such as [`computeParallelTransportFrames`](../reference/geometry/computeParallelTransportFrames.md),
+[`sweepMesh`](../reference/geometry/sweepMesh.md), or
+[`resolveCylindricalGear`](../reference/geometry/resolveCylindricalGear.md).
+
+### Fluent vector and tuple arithmetic
+
+Tuple kernels remain useful in numerical loops. The same arithmetic can be written in either form:
+
+
+
+```ts
+import { vector3 } from "@metamesh/modeling";
+import { add3, normalize3, scale3 } from "@metamesh/modeling/geometry";
+
+export const fluentDirection = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
+export const tupleDirection = scale3(normalize3(add3([1, 2, 3], [4, 0, 0])), 10);
+// fluentDirection.toData() and tupleDirection contain the same coordinates.
+```
+
+
+
+Fluent vectors validate finite inputs and results and allocate immutable values. Basic tuple
+arithmetic such as `add3` avoids those wrappers and assumes valid inputs; overflow can produce
+nonfinite results. Individual kernels document additional checks, such as zero-length rejection
+in `normalize3`.
+
+## Value and data naming
+
+Modeling values use domain names such as `Vector2`, `Transform2`, `Path2`, and `Bounds2`.
+Their plain representations consistently use `Data`: `Vector2Data`, `Transform2Data`,
+`Path2Data`, and `Bounds2Data`. Each value exposes `toData()` for a stable, deeply frozen
+representation, and its factory accepts that data again. `Input` types describe accepted values,
+data, and any supported construction shorthand.
+
+Vector data is a coordinate tuple, transform data a canonical matrix, bounds data a min/max record,
+and path data a record with `dimension`, `points`, and `closed`. Use `path.toData().points`
+when a numerical algorithm needs only coordinates; use the full record to retain topology.
+Options, reports, geometry descriptors, and recipes keep their descriptive contracts. Use
+`toTriangleMesh()` or `toRegionData()` during active host execution to evaluate a Solid as a mesh
+or a Section as a region.
+
+## Query paths and preserve closure
+
+Use `path2(points, { closed: true })` or `path3(points, { closed: true })` for a reusable boundary.
+`length()` includes the closing edge. [`closestPoint`](../reference/geometry/Path3-type.md#closestpoint)
+returns a [`PathLocation`](../reference/geometry/PathLocation.md): a fluent `point`, `distance` in
+millimetres, `edgeIndex`, and clamped `fraction` within that edge. Equal-distance ties select the
+first edge in traversal order. The fraction is local to an edge; it is not a whole-path or analytic
+curve parameter.
+
+### Path coordinate round trip
+
+
+
+```ts
+import { path3 } from "@metamesh/modeling";
+
+export const boundary = path3(
+  [
+    [0, 0, 0],
+    [10, 0, 0],
+    [10, 10, 0],
+    [0, 10, 0],
+  ],
+  { closed: true }
+);
+export const nearest = boundary.closestPoint([-2, 5, 0]);
+// point: [0, 5, 0], distance: 2, edgeIndex: 3, fraction: 0.5
+export const restoredPath = path3(boundary.toData());
+// Both paths include the closing edge and have length 40 mm.
+```
+
 
-| Starting intent                    | Typical operations                                                                                                                                                                                                                        |
-| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| A block, cylinder, sphere, or cone | Primitive solids, transforms, then [solid Booleans](fundamentals.md#choose-the-boolean-by-the-material-you-want)                                                                                                      |
-| A plate, gasket, logo, or profile  | Build a `Section`, use section Booleans or offsets, then [extrude](recipes.md#section-hole-offset-and-extrusion)                                                                                                      |
-| A rotational part                  | [Revolve a closed radial profile](recipes.md#revolve-a-radial-profile) around +Z                                                                                                                                      |
-| A tube or routed shape             | [Sweep one supported section](recipes.md#rotation-minimizing-path-sweep) along an open or closed path                                                                                                                 |
-| A transition between profiles      | [Loft corresponding boundaries](recipes.md#matched-section-loft) with holes                                                                                                                                           |
-| Repeated or mating parts           | [Patterns](recipes.md#primitive-booleans-and-repeated-placement), [explicit anchors](recipes.md#named-anchors-and-custom-frames), and [reusable thread settings](https://metamesh.studio/docs/develop/printable-threads) |
+
+`toData()` returns a deeply frozen record with `dimension`, `points`, and `closed`. Pass the path
+value directly where supported, or restore the full record with `path2(data)` or `path3(data)`.
+Closed paths omit the duplicated endpoint. Open paths may be empty; their bounds are `undefined`,
+and nearest-edge queries require at least two vertices. Queries measure the sampled boundary,
+not a filled interior or underlying analytic curve.
+
+Chain `transform`, `reverse`, and equal-distance `resample` to create new paths. Transforming a path
+preserves traversal even after reflection. `polygon(path)` requires a closed planar value and
+establishes exterior/hole winding; `stroke`, sweeps, and path patterns accept paths in the matching
+dimension. Authored point collections accept fluent vectors or tuples; serialized data uses tuples.
+
+## Compose modeling operations
 
 Name meaningful intermediate values and choose a curve tolerance that preserves the required
 shape. Many high-resolution Boolean operands increase generation time.
@@ -120,30 +214,35 @@ filled Section and `box({ size: [24, 16, 6] })` creates a Solid. `union` and `in
 combine same-dimensional arrays. `shape.subtract(cutters)` accepts an array of same-dimensional
 cutters. `section.offset(distance, options)` stays in the filled XY plane.
 
-`section.extrude({ height, twist, scaleTop })` adds +Z depth, with its bottom at zero unless
-`center: true` is requested. `section.revolve({ degrees })` rotates radial/Z geometry around
-+Z. `loft` pairs retained landmarks in compatible primitive Sections, including zero and fully
-rounded rectangle corners, and circle/ellipse stations transitioning to rectangles. This also works
-after invertible XY transforms with consistent handedness. It accepts explicit corresponding
-Profile stations for custom topology. Boolean Sections and point contours need a selected
-`correspondence` method (`"direct"`, `"reindex"`, `"fast-distance"`, or `"distance"`) or explicit
-profiles; Boolean contour order does not establish semantic correspondence.
-`section.sweep(path, options)` supports open or closed paths,
-degree twist, uniform/XY/per-station scales and an explicit compatible closed seam.
+- `section.extrude({ height, twist, scaleTop })` adds +Z depth, with its bottom at zero unless
+  `center: true` is requested.
+- `section.revolve({ degrees })` rotates radial/Z geometry around +Z.
+- `loft` pairs retained landmarks in compatible primitive Sections, including zero and fully
+  rounded rectangle corners, and circle/ellipse stations transitioning to rectangles. Invertible
+  XY transforms must keep consistent handedness. Use corresponding Profile stations for custom
+  topology. Boolean Sections and point contours need a `correspondence` method (`"direct"`,
+  `"reindex"`, `"fast-distance"`, or `"distance"`) or explicit profiles; contour order alone does
+  not establish semantic correspondence.
+- `section.sweep(path, options)` supports open or closed paths, degree twist, uniform/XY/per-station
+  scales, and an explicit compatible closed seam.
 
 ## Coordinates, units, and resolution
 
 MetaMesh uses a right-handed coordinate system with **+Z up**. Authored dimensions and curve
 tolerances are millimetres; angular arguments such as `rotate` use degrees.
-Pure [`rotate2`](../reference/geometry/rotate2.md) and transform-chain rotations also take degrees.
+Pure [`rotate2`](../reference/geometry/rotate2.md) and transform-value rotations also take degrees.
 The low-level [`rotationTransform3`](../reference/geometry/rotationTransform3.md) constructor
 requires an explicit `{ degrees }` or `{ radians }` angle.
 
-`GeometryResolution` controls sampled curves in physical space. The default maximum chord error is
-`0.05 mm`, with 16–512 segments for a complete circle and no default maximum segment length. An
-operation-specific `segments` or `circularSegments` value takes priority, followed by its local
-`resolution`, and then host session defaults. A shape does not carry a sampling policy into later
-operations; pass the policy explicitly where needed.
+`GeometryResolution` controls sampled curves in physical space. Defaults are a `0.05 mm` maximum
+chord error, 16–512 segments per complete circle, and no maximum segment length. Settings apply
+in this order:
+
+1. An operation-specific `segments` or `circularSegments` count.
+2. The operation's local `resolution`.
+3. Host session defaults.
+
+A shape does not carry its sampling policy into later operations; pass it explicitly where needed.
 
 Use an exact segment count for intentionally faceted geometry or when two sampled contours must
 match point for point. Use physical chord and segment limits for ordinary printable curves. If a
@@ -154,16 +253,17 @@ returning a coarser shape.
 `sizing: "vertex"` uses the specified vertex radius; `"face"` compensates faceting so the faces
 meet the nominal radius. `circle` and `cylinder` support the same radial convention.
 
-Finishing shares `round` (radius), `chamfer` (setbacks), `smooth` (cubic setbacks), and exact
-`profile` points across applicable box edges, rectangle corners, and cylinder/extrusion ends.
-Boxes can select disjoint named edges or groups; rectangles can select individual corners.
-Cylinder/frustum and straight convex extrusion rims use independent `ends.bottom` and `ends.top`.
-Zero rounding radius, zero chamfer/smooth distance, or an all-zero distance pair leaves the
-selected feature untreated. Other setback pairs must have two positive values; negative and
-nonfinite amounts reject. Disabled extrusion end treatments retain ordinary extrusion support,
-including holes and twist.
-`attachment` maps a named or explicit shape-local anchor to a world anchor after local
-construction, using alignment, millimetre gap and degree spin. Section placement must stay in XY.
+Finishing options share `round` (radius), `chamfer` (setbacks), `smooth` (cubic setbacks), and exact
+`profile` points:
+
+- Boxes select disjoint named edges or groups; rectangles select individual corners.
+- Cylinder/frustum and straight convex extrusion rims use independent `ends.bottom` and `ends.top`.
+- Zero radius, zero chamfer/smooth distance, or an all-zero distance pair leaves a feature untreated.
+  Other setback pairs require two positive values; negative and nonfinite amounts reject.
+- Disabled extrusion end treatments retain ordinary support, including holes and twist.
+
+`attachment` maps a shape-local anchor to a world anchor after construction, using alignment,
+millimetre gap, and degree spin. It accepts named or explicit anchors; Sections must stay in XY.
 
 ## Reuse a transform across shapes and coordinates
 
@@ -186,7 +286,7 @@ export const placedDirection = placement.applyDirection([10, 0, 0]); // approxim
 
 
 Pass a transform directly to `solid.transform(placement)`, `section.transform(placement)` and
-matching path helpers. `toMatrix()` supplies a canonical matrix when another system needs it.
+matching path helpers. `toData()` supplies a canonical matrix when another system needs it.
 Construct the placement once and reuse it across point collections.
 
 `current.andThen(next)` applies `current` first and `next` second, accepting another chain or a
@@ -196,23 +296,43 @@ return new chains, so shared placements can branch safely.
 Use `rotate(degrees, { pivot })` or `scale(factors, { pivot })` to work around a world-space pivot after
 the preceding operations. In 3D, `rotate` takes XYZ Euler degrees, applied about global X, Y, then
 Z; `rotateAxis(axis, degrees, { pivot })` normalizes its nonzero axis. Omitted pivots use the
-coordinate origin. Uniform and per-axis scales
-must be finite and nonzero; negative factors reflect. Nonfinite inputs, invalid axes, and singular
-matrices throw `GeometryError`.
+coordinate origin. Uniform and per-axis scales must be finite and nonzero; negative factors reflect.
+Nonfinite inputs, invalid axes, and singular matrices throw `GeometryError`.
 
 `applyPoint` includes translation. `applyDirection` excludes translation and preserves scale;
 its result is not normalized. `applyNormal` applies the inverse transpose and returns a unit normal,
 including under nonuniform scaling; it rejects zero normals. All three return fluent vectors.
 
-`Transform2` works directly with Sections and pure XY helpers; its `Transform2Matrix` is the same
+`Transform2` works directly with Sections and pure XY helpers; its `Transform2Data` is the same
 canonical 3x3 representation throughout. Use `to3D()` when that XY placement
 also needs to position a Solid or 3D path. The reverse `to2D()` conversion rejects transforms
 that move the XY plane or collapse its dimensions; it does not project 3D points.
 See the [2D placement recipe](recipes.md#reuse-a-2d-placement).
 
+### Transform composition order
+
 For low-level matrix interoperability, the factories accept existing canonical matrices. Use
 `transform3(frameTransform3(frame))` for an orthonormal frame. The raw constructors and
-`composeTransform3(after, before)` remain available; composition applies `before` first.
+`composeTransform3(after, before)` remain available; composition applies `before` first:
+
+
+
+```ts
+import { transform3 } from "@metamesh/modeling";
+import { applyTransformPoint3, composeTransform3 } from "@metamesh/modeling/geometry";
+
+const current = transform3().rotate([0, 0, 90]);
+const next = transform3().translate([20, 0, 5]);
+export const chainedPoint = current.andThen(next).applyPoint([10, 0, 0]);
+export const composedPoint = applyTransformPoint3(
+  composeTransform3(next.toData(), current.toData()),
+  [10, 0, 0]
+); // Both results are approximately [20, 10, 5].
+export const reversedPoint = next.andThen(current).applyPoint([10, 0, 0]);
+// approximately [0, 30, 5]
+```
+
+
 
 ## Calculate with vectors
 
@@ -229,7 +349,7 @@ export const alignment = direction.dot([0, 0, 1]); // number
 
 
 
-Values snapshot their input and operations return new values. `toArray()` returns the value's
+Values snapshot their input and operations return new values. `toData()` returns the value's
 frozen coordinate tuple without allocating another copy. Normalization rejects zero-length vectors;
 nonfinite coordinates, scalar parameters and overflowing results throw `GeometryError`.
 
@@ -247,11 +367,60 @@ export const perpendicular = normal.dot(tangent); // approximately 0
 
 
 
-The tuple arithmetic kernels remain available for dense numerical loops. Fluent values add
-validation and immutable object allocation; they are an authoring convenience, not a speedup.
-Fluent math, shape transforms and part placement accept vector values directly; geometry
-specifications and point collections use canonical tuples.
-Keep simple coordinate expressions and equations intrinsic to the model beside the model.
+Fluent math, shape transforms, and part placement accept vector values directly. Serialized
+geometry and low-level kernels use tuples. Keep model-specific equations beside the model.
+
+## Measure and compare bounds
+
+Use [`bounds2`](../reference/geometry/bounds2.md) and
+[`bounds3`](../reference/geometry/bounds3.md) for immutable axis-aligned bounds. `size()` and
+`center()` return fluent vectors. `containsBounds(other)` tests positioned containment in the
+same coordinate frame, including touching boundaries. It does not establish a manufacturing fit.
+
+
+
+```ts
+import { bounds3 } from "@metamesh/modeling";
+import {
+  extrudeMesh,
+  fitBounds,
+  layoutRow,
+  meshBounds,
+  rectangleContour,
+} from "@metamesh/modeling/geometry";
+
+export const envelope = bounds3({ min: [-10, -5, 0], max: [10, 5, 8] });
+export const size = envelope.size(); // Vector3: [20, 10, 8] mm
+export const center = envelope.center(); // Vector3: [0, 0, 4] mm
+
+const mesh = extrudeMesh(rectangleContour({ size: [12, 6] }), { height: 4 });
+// Mesh measurements are plain data. Wrap once for fluent queries.
+export const measured = bounds3(meshBounds(mesh));
+export const fits = envelope.containsBounds(measured); // true
+export const data = measured.toData(); // Frozen { min, max } record for interchange.
+
+// Collection and placement algorithms accept bounds values directly.
+export const fitting = fitBounds(measured, envelope, { maxScale: 1 });
+export const positions = layoutRow([measured, envelope], { gap: 2 });
+```
+
+
+
+Factories snapshot finite, ordered coordinates with finite extents; zero extents are valid.
+Alternatively construct from nonnegative dimensions with `bounds2({ size: [30, 18] })` or
+`bounds3({ size: [30, 18, 8], center: false })`. Size construction centers on the origin by default;
+size and min/max construction are mutually exclusive.
+`min` and `max` are frozen tuples, and `toData()` returns the value's stable frozen plain record.
+Path `bounds()` queries return matching fluent bounds, or `undefined` for an empty path.
+Mesh and region measurements, inspection results, and engine snapshots retain plain
+`Bounds2Data` or `Bounds3Data`; wrap a measurement when you need fluent queries.
+Compiled Generator packages passing bounds values to host recipes or computed data require
+runtime `9.0.0` or newer in major 9.
+
+Keep [`fitBounds`](../reference/geometry/fitBounds.md) and
+[`layoutRow`](../reference/geometry/layoutRow.md) as standalone algorithms: they compute placement
+reports and collection layouts. Both accept values or plain records. Supply bounds after any
+intended rotation; an axis-aligned box alone does not describe the underlying shape.
 
 ## SVG sections: fills and strokes are different inputs
 
@@ -296,13 +465,36 @@ one profile and fit policy across mating parts, then prove them with a short cal
 Follow [Build printable threads](https://metamesh.studio/docs/develop/printable-threads) for the illustrated workflow,
 complete source, profile and fit choices, end treatments, and links into the exact API contracts.
 
+## Check preflight guarantees
+
+Preflights expose operation-specific checks and reports. Read their return contracts before
+using a successful result as a guarantee:
+
+- [`preflightHeightfield`](../reference/geometry/preflightHeightfield.md) checks grid dimensions,
+  coordinate precision, and allocation limits. It returns exact output-buffer vertex, triangle,
+  and byte counts without evaluating heights.
+- [`preflightHelicalThreadSolidMesh`](../reference/geometry/preflightHelicalThreadSolidMesh.md)
+  and related thread preflights check dimensions, sampling, and conservative allocation estimates.
+  They return the sampling plan without constructing the final mesh or native solid.
+- [`preflightSvgRegion`](../reference/geometry/preflightSvgRegion.md) parses and samples supported
+  SVG geometry, returning a normalized region and import diagnostics. Its counts measure the region
+  at the selected resolution; they do not predict later mesh allocation.
+
+The `/geometry` preflights run without an engine and use explicit options or package defaults.
+The root [`preflightThreadedRod`](../reference/model/preflightThreadedRod.md),
+[`preflightInternalThreadCutter`](../reference/model/preflightInternalThreadCutter.md), and
+[`preflightThreadedNut`](../reference/model/preflightThreadedNut.md) require active synchronous
+model execution and use the host's resolution and limits.
+
+Passing a preflight covers its documented checks. Construction can still fail during callback
+evaluation, meshing, or native evaluation. Constructors enforce their applicable limits even when
+you omit an explicit preflight; preflight is an optional planning and diagnostics step.
+
 ## Lifecycle and inspection
 
-Studio or your standalone engine owns geometry initialization, cleanup, and mesh finalization.
-The host owns Worker recovery, preview, and file delivery. Do not manually delete `Section` or `Solid`
-values. Use
-`inspectSection()` and `inspectSolid()` for supported bounds, topology counts, area, and volume
-measurements.
+Studio or your standalone host owns initialization, cleanup, finalization, Worker recovery,
+preview, and file delivery. Do not manually delete `Section` or `Solid` values. Use
+`inspectSection()` and `inspectSolid()` for bounds, topology counts, area, and volume.
 
 Observations, including `section.toRegionData()`, require the host's active synchronous generation.
 Constructing or composing a recipe outside generation does not evaluate it.

package/dist/docs/guides/fonts.md

@@ -2,9 +2,9 @@
 
 Prepare licensed font bytes and a reusable text layout before building a model outside Studio.
 
-Your host acquires exact licensed font bytes before synchronous generation.
-Studio authors use the [Font control recipe](recipes.md#text-from-a-font-parameter);
-standalone applications use the optional `@metamesh/modeling/text` entry point.
+Load font bytes before synchronous generation. Your application supplies bytes for a font you
+are licensed to use and prepares them through the optional `@metamesh/modeling/text` entry point.
+In Studio, use the [Font control recipe](recipes.md#text-from-a-font-parameter).
 
 ## Install font support
 
@@ -44,11 +44,12 @@ export async function makeLabelLayout(fontBytes: Uint8Array): Promise<{
 
 
 
-Call `makeLabelLayout(fontBytes)` with the acquired bytes. It returns a `layout` and a separate
-`svg` string. The layout contains paths and metrics in Y-up millimetres. Pass the returned `layout` to
-[`textSection`](../reference/model/textSection.md) inside generation, then extrude its filled
-section with the ordinary modeling operations. A host can prepare layouts ahead of time or inject
-a deterministic text service and cache layouts with `computed`.
+Call `makeLabelLayout(fontBytes)` with your font bytes. It returns a `layout` with paths and metrics
+in Y-up millimetres, plus a separate `svg` string.
+
+Pass the `layout` to [`textSection`](../reference/model/textSection.md) inside generation, then
+extrude the filled section. Prepare layouts ahead of time, or supply a deterministic text service
+and cache layouts with `computed`.
 
 The same layout options support horizontal lines or one circular line through
 [`VectorTextArcBaseline`](../reference/text/VectorTextArcBaseline.md). The