@metamesh/modeling 0.18.0 → 0.19.0

package/dist/docs/guides/concepts.md

@@ -1,547 +1,44 @@
 # Geometry API concepts
 
-Choose shapes, paths, profiles, and modules, then compose immutable geometry with clear sampling and preflight limits.
+Choose geometry representations and modules, then find the conventions and host setup for your model.
 
-Use Sections for filled 2D shapes and Solids for 3D material. Paths describe routes and boundaries;
-profiles help you line up related boundaries for a loft or sweep. Import modeling functions from
-the package root:
+Modeling separates the shape you describe from the host that evaluates it. Build immutable
+Sections and Solids for material, use pure geometry values for calculations, and let Studio or
+your standalone engine produce the finished result.
 
+## Choose the representation
 
+| You need                                               | Use                              |
+| ------------------------------------------------------ | -------------------------------- |
+| Filled material for Booleans, extrusion, or revolution | A `Section` or `Solid`           |
+| Sampled coordinates and traversal queries              | A `Path2`, `Path3`, or `Contour` |
+| Matching landmarks across cross sections               | An identified `Profile` family   |
+| Triangle buffers for a renderer or mesh algorithm      | A `TriangleMesh`                 |
 
-```ts
-import { box, cylinder } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
-```
+[Geometry values and representations](geometry-values.md) explains these choices,
+plain interchange data, and conversion between them. [Placement](transforms-and-placement.md)
+covers vectors, transforms, anchors, patterns, and bounds. [Resolution and inspection](resolution-and-inspection.md)
+explains sampling, preflight guarantees, and evaluated measurements.
 
+## Choose the module
 
+- [`@metamesh/modeling`](../reference/model.md): shapes, Booleans, construction, and generation programs.
+- [`@metamesh/modeling/geometry`](../reference/geometry.md): pure paths, profiles, transforms, and calculations.
+- [`@metamesh/modeling/geometry/mesh`](../reference/mesh.md): triangle mesh construction, processing, and inspection.
+- [`@metamesh/modeling/engine`](../reference/engine.md): standalone execution and finalization.
+- [`@metamesh/modeling/export`](../reference/export.md): renderer-independent STL, 3MF, and GLB export.
+- [`@metamesh/modeling/text`](../reference/text.md): exact font preparation and vector layouts.
 
-Studio supplies the API and runtime in code Projects. You can use the same values in a standalone
-generation program. Use the [Model API reference](../reference/model.md) for exact
-signatures.
+Constructing and combining ordinary recipes doesn't need an engine. Geometry observations run
+inside synchronous generation. The host owns evaluation, prepared services, and native resources;
+[inspect the result](resolution-and-inspection.md#lifecycle-and-inspection) before relying
+on its dimensions.
 
-## Choose a modeling path
+## Choose where to run
 
-| 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                                   |
+- **Studio:** follow the [code Project path](https://metamesh.studio/docs/develop#follow-the-studio-path). Studio supplies
+  controls, prepared services, preview, and export.
+- **Locally:** follow the [standalone path](https://metamesh.studio/docs/engine#follow-the-standalone-path). The CLI or
+  your application supplies the host.
 
-Combine these approaches as your part needs them: join a flange to a sleeve, then add repeated
-holes with cutters. Start with an existing primitive when it fits; `tube` is ready for a
-concentric straight sleeve.
-
-Start with synchronous generation and return named parts. Geometry values describe immutable
-recipes that Studio or your standalone engine 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
-
-| Import                                                     | Use it for                                                          | Who owns execution                      |
-| ---------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------- |
-| [`@metamesh/modeling`](../reference/model.md)              | Sections, Solids, transforms, Booleans, sweeps, lofts, and patterns | A synchronous generation program        |
-| [`@metamesh/modeling/geometry`](../reference/geometry.md)  | Pure paths, profiles, calculations, and indexed meshes              | Your ordinary TypeScript code           |
-| [`@metamesh/modeling/geometry/mesh`](../reference/mesh.md) | Triangle mesh construction, processing, and inspection              | Your ordinary TypeScript code           |
-| [`@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 shapes, vectors, paths, and transforms in ordinary TypeScript and reuse them in
-synchronous generation. Studio or your standalone engine handles evaluation, measurements, and export.
-
-## Use Modeling outside Studio
-
-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 the completed result.
-For lettering, [prepare exact font bytes](fonts.md) before building.
-
-## Geometry vocabulary
-
-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` describe shapes as immutable recipes. You can construct and combine them
-without an engine, then reuse ordinary recipes across sessions. Explicit resolution settings
-stay with the recipe; omitted settings use the evaluating host's defaults. The host manages
-evaluation caches and native kernel values.
-
-Calling `shape.components()` reads evaluated geometry. Its selected shapes, and recipes using them,
-can only be evaluated in their original session because the selection depends on that session's
-evaluated topology.
-
-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 read
-the evaluated shape; keep serialized point data for interchange or calculations outside generation.
-
-`rectangleProfile({ size: [width, height], treatment: { kind: "round", radius }, id })` describes
-identified spans for custom geometry. Use `matchProfiles` to prepare a complete family when loft
-stations or a sweep need holes, seams, or landmarks beyond ordinary primitives.
-
-Identified spans also accept cubic Béziers with the same endpoints and controls as
-[`CubicBezierCurve2`](../reference/geometry/CubicBezierCurve2.md). Paired spans share one parameter
-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 fluent values or standalone algorithms
-
-### Convert representations deliberately
-
-| From                       | Conversion                                     | Evaluation and ownership                                       |
-| -------------------------- | ---------------------------------------------- | -------------------------------------------------------------- |
-| `Contour` / `RegionData`   | `polygon(...)` to `Section`                    | Captures a recipe without an engine                            |
-| `Section`                  | `section.toRegionData()`                       | Observes evaluated geometry inside a host execution            |
-| `Profile`                  | `matchProfiles(...)`                           | Pure matching retains identified boundaries and landmarks      |
-| Closed `Path2` / `Contour` | `mesh.extrude(...)` to `TriangleMesh`          | Pure mesh construction; no `ends` treatments                   |
-| `TriangleMesh`             | `solidFromMesh(...)` to `Solid`                | Captures a recipe; native validation happens during evaluation |
-| `Solid` / `TriangleMesh`   | `part(...)`, then an engine run to `ModelPart` | Host finalizes durable immutable manufacturing buffers         |
-| `ModelPart`                | Pass directly to mesh analysis or `export3mf`  | No live session needed; use buffer `copy()` before mutation    |
-
-Pure extrusion uses `ExtrudeMeshOptions` for height, centering, twist, top scale, and sampling.
-Native `Section.extrude` also supports `ends` through `ExtrudeOptions`; requesting them from
-`mesh.extrude` throws instead of silently returning unfinished geometry.
-
-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),
-[`mesh.sweep`](../reference/mesh/sweep.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; keep the full record when closure matters too.
-Options, reports, geometry descriptors, and recipes keep their own descriptive names. Use
-`toMesh()` or `toRegionData()` during active host execution to evaluate a Solid as a triangle 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.
-```
-
-
-
-`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)`.
-Don't repeat the endpoint of a closed path. 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
-
-Give intermediate shapes meaningful names and choose a curve tolerance that preserves the detail
-you need. Many high-resolution Boolean operands take longer to build.
-
-Dimension inputs accept matching fluent vectors or plain coordinate tuples, such as
-`box({ size: vector3([30, 20, 6]) })`. Use `section.extrude(options)`, `section.revolve(options)`,
-and `section.sweep(path, options)` in fluent modeling sequences. Imported `extrude`, `revolve`, and
-`sweep` accept `Section | CorrespondingProfile`, so reusable profile functions can use either input
-without branching. Both forms use the same operation contracts. Use `mesh.extrude(contour, options)`
-when constructing triangle buffers directly.
-
-Primitive factories take one options object. For example, `rectangle({ size: [24, 16] })` creates a
-filled Section and `box({ size: [24, 16, 6] })` creates a Solid. The `union`, `subtract`, and `intersect`
-methods accept one same-dimensional shape or a readonly array; an empty array preserves the receiver.
-Collection `union(shapes)` and `intersect(shapes)` combine peers and require at least one shape.
-`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. Invertible
-  XY transforms must keep consistent handedness. Use corresponding Profile stations for custom
-  topology. Boolean Sections and point contours default to `correspondence: "direct"`, preserving
-  their supplied seams. Select `"reindex"`, `"fast-distance"`, or `"distance"` to change the
-  association strategy. 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-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. 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 doesn't 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
-requested tolerance can't fit within the safety cap, the operation fails instead of silently
-returning a coarser shape.
-
-`regularPolygon({ radius, sides, rotation, sizing })` makes a filled regular polygon.
-`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.
-`tube` accepts a complete pair of inner/outer radii or diameters, with independent `innerSizing`
-and `outerSizing`. For example, `tube({ innerDiameter: 8, outerDiameter: 12, height: 10,
-innerSizing: "face" })` preserves an 8 mm clear bore between the sampled faces. Both defaults are
-`"vertex"`; compensation that removes the wall rejects. Sampling and sizing do not establish a
-manufacturing fit allowance.
-
-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
-
-Use [`transform2`](../reference/geometry/transform2.md) and
-[`transform3`](../reference/geometry/transform3.md) chains for reusable placements. They are immutable
-and pure, so you don't need an engine to build them. Calls apply in written order. A rotation
-followed by a translation rotates around the origin, then moves the result:
-
-
-
-```ts
-import { transform3, vector3 } from "@metamesh/modeling";
-
-// Calls apply in written order: rotate, then translate.
-const placement = transform3().rotate([0, 0, 90]).translate([20, 0, 5]);
-export const placedPoint = placement.applyPoint([10, 0, 0]); // approximately [20, 10, 5]
-export const placedDirection = placement.applyDirection([10, 0, 0]); // approximately [0, 10, 0]
-```
-
-
-
-Pass a transform directly to `solid.transform(placement)`, `section.transform(placement)` and
-matching path helpers. Finished parts accept rigid transforms through `part(id, { geometry, transform })`;
-pattern and attachment matrices work directly. Part placement rejects scale, shear and reflection.
-`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
-same-dimensional matrix. `inverse()` returns the reverse placement. Each operation returns a new
-chain, so you can derive different placements from a shared starting point.
-
-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`.
-
-`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 `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 doesn't 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:
-
-
-
-```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
-
-Use [`vector2`](../reference/geometry/vector2.md) and [`vector3`](../reference/geometry/vector3.md)
-for readable arithmetic chains. Operands accept tuples or vectors; `dot`, `length` and `distance`
-return numbers. `cross` returns a signed scalar in 2D and a right-handed vector in 3D.
-
-
-
-```ts
-export const direction = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
-export const alignment = direction.dot([0, 0, 1]); // number
-```
-
-
-
-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`.
-
-For rotations and nonuniform scaling, use a reusable transform's `applyDirection`. Use
-`applyNormal` for surface normals:
-
-
-
-```ts
-const stretched = transform3().scale([2, 1, 1]);
-export const normal = stretched.applyNormal([1, 1, 0]);
-export const tangent = stretched.applyDirection([1, -1, 0]);
-export const perpendicular = normal.dot(tangent); // approximately 0
-```
-
-
-
-Fluent math and shape transforms accept vector values directly; compose a transform for part placement. 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 doesn't establish a manufacturing fit.
-
-
-
-```ts
-import { bounds3 } from "@metamesh/modeling";
-import { fitBounds, layoutRow, rectangleContour } from "@metamesh/modeling/geometry";
-import * as mesh from "@metamesh/modeling/geometry/mesh";
-
-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 triangleMesh = mesh.extrude(rectangleContour({ size: [12, 6] }), { height: 4 });
-// Mesh measurements are plain data. Wrap once for fluent queries.
-export const measured = bounds3(mesh.bounds(triangleMesh));
-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.
-
-Use [`fitBounds`](../reference/geometry/fitBounds.md) to calculate a placement and
-[`layoutRow`](../reference/geometry/layoutRow.md) to arrange a collection. These standalone
-algorithms accept values or plain records. Supply bounds after any intended rotation; an
-axis-aligned box alone doesn't describe the underlying shape.
-
-## SVG sections: fills and strokes are different inputs
-
-[`svgSection`](../reference/model/svgSection.md) converts a bounded complete SVG document into one
-painted `Section`. Supported visible **fills and bounded strokes both contribute geometry**. It
-handles supported shapes, paths, affine transforms, physical root units, `viewBox` scaling, and
-allowlisted inline fill and stroke presentation.
-
-[`svgPathSection`](../reference/model/svgPathSection.md) accepts SVG path-data text rather than a
-document. It is a **fill-only** path operation: it doesn't apply stroke styling. Path
-units default to millimetres and can be converted with its scale option.
-
-Both functions convert SVG's Y-down plane to MetaMesh's Y-up plane and center the final painted
-bounds by default. Use `origin: "document"` with `svgSection` when the converted document viewport
-origin must remain meaningful. Adaptive flattening happens after supported transforms and unit
-conversion, so tolerances apply in final millimetre space.
-
-Unsupported layout or external content fails rather than disappearing silently. These helpers
-don't support nested SVG viewports, `<use>`, images, live text, external stylesheets,
-clipping, masks, filters, scripts, animation, gradients, patterns, uploaded project assets, or
-custom font files. Use the [SVG extrusion recipe](recipes.md#svg-parameter-and-extrusion)
-for a complete authored example.
-
-## Text and font variability
-
-`services.text.layout()` shapes text inside generation. Cache an expensive shared layout with
-`computed`, measure its `metrics`, and pass it to `textSection(layout())`. There is no
-ambient font provider, and exporting doesn't shape the text again. Declare a Text control for
-the wording and a Font control for the face and weight.
-
-Font size is the em size in millimetres, not the height of a particular letter. Layout supports
-horizontal lines, spacing, and alignment, or a single circular baseline through
-[`VectorTextArcBaseline`](../reference/text/VectorTextArcBaseline.md). Follow the
-[text recipe](recipes.md#text-from-a-font-parameter) for the control setup,
-layout conventions, and font availability limits.
-
-## Printable threads
-
-The public API provides coordinated external threads, internal cutters, and threaded nuts. Reuse
-one profile and fit policy across mating parts, then prove them with a short calibration print.
-
-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
-
-Use a preflight to check inputs and see what an operation will require. Each preflight checks
-different things, so read what its report covers:
-
-- [`mesh.preflightHeightfield`](../reference/mesh/preflightHeightfield.md) checks grid dimensions,
-  coordinate precision, and allocation limits. It returns exact output-buffer vertex, triangle,
-  and byte counts without evaluating heights.
-- [`mesh.preflightThreadSolid`](../reference/mesh/preflightThreadSolid.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` and `mesh` 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 only its documented checks. Construction can still fail while running
-callbacks, meshing, or evaluating native geometry. Constructors enforce their limits even when
-you skip a preflight; use one when its plan or diagnostics help you make a decision.
-
-## Lifecycle and inspection
-
-Studio or your standalone host handles initialization, cleanup, finalization, Worker recovery,
-preview, and file delivery. Don't manually delete `Section` or `Solid` values. Use
-`shape.inspect()` for bounds, topology counts, area, and volume.
-Its immutable extrema are nested under `facts.bounds.min` and `facts.bounds.max`.
-Native `componentCount` counts disconnected material components. Mesh analysis and signatures use
-`shellCount` for surfaces connected by shared indexed edges: one sealed hollow body has one material
-component and two shells. Open mesh analysis can also count open shells; this count does not certify
-closed topology or geometric validity.
-
-Queries such as `shape.inspect()`, `shape.isEmpty()`, `shape.components()`, `shape.anchor(name)`,
-`solid.distance(other)`, and `solid.castSegment(origin, endpoint)` read evaluated geometry.
-These queries and interchange with `solid.toMesh()` or `section.toRegionData()` require the host's
-active synchronous generation. `solid.split(cutter)` returns the intersection and remainder;
-`solid.splitByPlane(plane)` returns the positive and negative sides of the plane.
-Constructing or combining a recipe outside generation doesn't evaluate it.
-
-An inspection result describes the generated geometry; it doesn't certify wall thickness,
-overhangs, fits, loads, or manufacturability. Express those requirements in your parameters and
-validation, then check them in your manufacturing workflow.
-
-- [Use geometry recipes](recipes.md)
-- [Browse exact signatures](../reference/model.md)
+When you're ready to shape a part, choose a [worked modeling technique](recipes.md).

package/dist/docs/guides/fonts.md

@@ -4,7 +4,7 @@ Prepare licensed font bytes and a reusable text layout before building a model o
 
 To add lettering outside Studio, load a font you're licensed to use and prepare it through the
 optional `@metamesh/modeling/text` entry point before synchronous generation. In Studio, use the
-[Font control recipe](recipes.md#text-from-a-font-parameter).
+[Font control recipe](svg-and-text.md#text-from-a-font-parameter).
 
 ## Install font support
 
@@ -50,11 +50,11 @@ measurements in millimetres, with Y pointing up, 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`.
+and cache layouts with `memo`.
 
 The same layout options support horizontal lines or one circular line through
-[`VectorTextArcBaseline`](../reference/text/VectorTextArcBaseline.md). The
-[text recipe](recipes.md#text-from-a-font-parameter) explains units, alignment,
+[`VectorTextArcBaseline`](../reference/geometry/VectorTextArcBaseline.md). The
+[text recipe](svg-and-text.md#text-from-a-font-parameter) explains units, alignment,
 metrics, and circular-text constraints.
 
 Use the [Font preparation reference](../reference/text.md) for font and layout options, or