@metamesh/modeling 0.17.0 → 0.19.0

package/dist/docs/guides/concepts.md

@@ -1,507 +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, Solids for 3D material, and paths or profiles for boundaries
-and correspondence. 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 to code Projects. Standalone applications use the same
-values in a 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 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
-
-| 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/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. The host owns evaluation, observations, 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 its completed snapshot.
-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` are opaque immutable recipes. Construction and composition need no engine;
-ordinary recipes can be reused across sessions regardless of where they were constructed.
-Explicitly supplied resolution settings are captured; unspecified settings inherit the evaluating
-host's defaults. The host owns evaluation caches and native kernel values. `components()` is an
-observation: its selected shapes, and recipes using them, can only be evaluated in the originating
-session because component identity depends on 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 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`
-when loft stations or a sweep need authored 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
-
-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.
-```
-
-
-
-`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.
-
-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. `union` and `intersect`
-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. 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-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 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
-requested tolerance cannot 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.
-
-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; no engine initialization is needed. 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. `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. Transform-building operations
-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`.
-
-`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 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:
-
-
-
-```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, 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
-
-[`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: stroke styling is not part of that contract. 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. The current public
-contract does not include 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 or repeated shaping during export. 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
-
-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 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.
-
-An inspection result describes the generated geometry; it does not certify wall thickness,
-overhangs, fits, loads, or manufacturability. Keep those product decisions in parameters,
-validation, and your downstream manufacturing checks.
-
-- [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

@@ -2,9 +2,9 @@
 
 Prepare licensed font bytes and a reusable text layout before building a model outside Studio.
 
-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).
+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](svg-and-text.md#text-from-a-font-parameter).
 
 ## Install font support
 
@@ -15,11 +15,12 @@ pnpm add fontkit
 pnpm add woff2-encoder
 ```
 
-TTF, OTF, and WOFF input use fontkit directly. WOFF2 decoding loads only when needed. The library
-does not fetch fonts; your application supplies their bytes.
+TTF, OTF, and WOFF input use fontkit directly. WOFF2 decoding loads only when needed. Your
+application supplies the font bytes; the library doesn't fetch them.
 
-For a static face whose actual weight is not 400, pass that weight through `staticWeight` when
-preparing it. This identifies the supplied face; it does not synthesize another weight.
+If you're using a static face whose actual weight isn't 400, pass that weight through
+`staticWeight` when preparing it. This identifies the supplied face; it doesn't synthesize
+another weight.
 
 ## Prepare one reusable layout
 
@@ -44,17 +45,17 @@ export async function makeLabelLayout(fontBytes: Uint8Array): Promise<{
 
 
 
-Call `makeLabelLayout(fontBytes)` with your font bytes. It returns a `layout` with paths and metrics
-in Y-up millimetres, plus a separate `svg` string.
+Call `makeLabelLayout(fontBytes)` with your font bytes. It returns a `layout` with paths and
+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
-[Run Modeling in your application](hosting.md) for the host lifecycle.
+[Run Modeling in your application](hosting.md) for engine setup, export, and cleanup.