@metamesh/modeling 0.19.0 → 0.20.0

package/dist/docs/guides/geometry-values.md

@@ -1,103 +1,81 @@
-# Choose geometry values and representations
-
-Choose filled shapes, paths, profiles, and plain data, and understand when geometry is evaluated.
-
-Choose a value by the information your next operation needs. Filled Sections and Solids represent
-material; paths retain traversal and closure; identified profiles retain correspondence between
-cross sections. Pure calculations do not need a host engine.
-
-## 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:
+# Choose geometry representations
+
+Move between filled shapes, paths, profiles, fluent values, and plain data without losing information.
+
+Choose the representation that retains the information your next operation needs. A Section
+retains filled material, a path retains traversal and closure, and an identified Profile retains
+landmarks that can correspond across changing cross sections.
+
+For ordinary parts, start with Sections and Solids. Use the other representations when a
+calculation or construction needs their extra information.
+
+## Material, boundaries, and matching profiles
+
+| You need                                          | Choose                                 | Example or next step                                                                |
+| ------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------- |
+| Filled 2D material for Booleans or extrusion      | `Section`                              | [`rectangle({ size: [30, 20] })`](../reference/model/rectangle.md)                  |
+| Filled 3D material for a finished part            | `Solid`                                | [`box({ size: [30, 20, 6] })`](../reference/model/box.md)                           |
+| One closed boundary as sampled coordinates        | `Contour`                              | [`rectangleContour({ size: [30, 20] })`](../reference/geometry/rectangleContour.md) |
+| Ordered samples with explicit closure and queries | `Path2` or `Path3`                     | [Path queries and round trips](#keep-path-closure-and-traversal)                    |
+| Stable corners, seams, or holes across stations   | `Profile`, then `CorrespondingProfile` | [Sweeps and lofts](sweeps-and-lofts.md#matched-section-loft)             |
+| Triangle buffers for a renderer or algorithm      | `TriangleMesh`                         | [Mesh API](../reference/mesh.md)                                                    |
+
+A `Contour` does not repeat its first point at the end. `PolygonData` stores an exterior and its
+holes; `RegionData` stores a collection of filled polygons. These are plain coordinate data,
+while a Section describes filled geometry that can be combined and evaluated.
+
+[`polygon`](../reference/model/polygon.md) captures those boundaries as a Section:
 
 - `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
+- `polygon({ contours, fillRule })` resolves compound paths, using `"nonzero"` 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.
+For a straightforward plate, subtract holes from a Section and extrude it. Use
+[`rectangleProfile`](../reference/geometry/rectangleProfile.md) and
+[`matchProfiles`](../reference/geometry/matchProfiles.md) when related stations need explicit
+correspondence. Profile IDs identify components, contours, and spans; matching preserves those
+landmarks while preparing a shared sampling grid. See the
+[loft guide](sweeps-and-lofts.md#matched-section-loft) for the topology requirements.
 
-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.
+## Fluent values, plain data, and descriptors
 
-## Choose fluent values or standalone algorithms
+Import geometric values from `@metamesh/modeling/geometry`. They provide immutable methods for
+calculations and placement:
 
-### Convert representations deliberately
+| Value                       | Plain representation                                      | Useful operations                                         |
+| --------------------------- | --------------------------------------------------------- | --------------------------------------------------------- |
+| `Vector2` / `Vector3`       | `Vector2Data` / `Vector3Data`: coordinate tuples          | Arithmetic, normalization, distance, projection           |
+| `Transform2` / `Transform3` | `Transform2Data` / `Transform3Data`: canonical matrices   | Composition, inversion, point/direction/normal transforms |
+| `Bounds2` / `Bounds3`       | `Bounds2Data` / `Bounds3Data`: min/max records            | Size, center, containment                                 |
+| `Path2` / `Path3`           | `Path2Data` / `Path3Data`: points, dimension, and closure | Length, closest point, transformation, resampling         |
 
-| 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    |
+`toData()` returns a stable, deeply frozen plain representation. The matching factory accepts
+that data again. An `Input` type describes the values, data, and construction shorthand accepted
+by a particular operation; check its contract when crossing representations.
 
-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.
+Value queries return matching fluent values: a bound's `min`, `max`, `center()`, and `size()` are
+vectors; a path's `bounds()` is a bounds value, or `undefined` when the path is empty.
+Inspection reports, serialized regions, mesh measurements, and engine snapshots use plain data.
+Wrap that data with `bounds3(...)` or another matching factory when you need fluent queries.
 
-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).
+Not every factory creates a fluent value. `Frame3` and `Anchor3` are validated, frozen plain
+geometric descriptors. A Profile describes identified geometry; a Section or Solid describes a
+modeling recipe. They keep names that describe their role rather than adopting `Data` merely
+because they are records.
 
-### Fluent vector and tuple arithmetic
+### Choose arithmetic for the job
 
-Tuple kernels remain useful in numerical loops. The same arithmetic can be written in either form:
+Methods make ordinary calculations easy to follow. Tuple kernels from
+[`@metamesh/modeling/geometry/math`](../reference/math.md) are useful when processing coordinate
+arrays or interoperating with another numerical system:
 
 
 
 ```ts
-import { vector3 } from "@metamesh/modeling";
-import { add3, normalize3, scale3 } from "@metamesh/modeling/geometry";
+import { vector3 } from "@metamesh/modeling/geometry";
+import { add3, normalize3, scale3 } from "@metamesh/modeling/geometry/math";
 
 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);
@@ -106,41 +84,96 @@ export const tupleDirection = scale3(normalize3(add3([1, 2, 3], [4, 0, 0])), 10)
 
 
 
-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`.
+Both examples calculate the same direction. Fluent vectors validate finite inputs and results
+and allocate immutable values. Basic tuple arithmetic such as `add3` assumes valid inputs;
+overflow can produce nonfinite results. Individual kernels document additional checks, such as
+zero-length rejection in `normalize3`.
+
+Use a value's methods for composition and common queries, including
+`vector3(...).projectOntoPlane(normal)`. Specialized algorithms such as
+[`computeParallelTransportFrames`](../reference/geometry/computeParallelTransportFrames.md) and
+[`mesh.sweep`](../reference/mesh/sweep.md) remain standalone functions.
+
+## Frames, anchors, and transforms
+
+Choose a frame when the origin and orthonormal axes express your datum. Choose a transform when
+you need to compose placement or include affine deformation:
+
+| Known information               | Construction                                            |
+| ------------------------------- | ------------------------------------------------------- |
+| Rotation, translation, or scale | `transform3().rotate([0, 0, 45]).translate([0, 0, 30])` |
+| An existing canonical matrix    | `transform3(matrix)`                                    |
+| An origin and coordinate axes   | `frame3({ origin, xAxis, yAxis, zAxis })`               |
+| A mating position and direction | `anchor3({ position, direction, up })`                  |
+
+[`frame3`](../reference/geometry/frame3.md) copies and deeply freezes its record and coordinate
+tuples. Origins use millimetres; axes must form a right-handed orthonormal basis. Only accepted
+numerical roundoff is normalized. Scaled, skewed, or left-handed bases reject.
+
+`transform3(frame)` provides affine methods for a frame. `Transform3Input` accepts `Frame3`, a
+fluent `Transform3`, or canonical matrix data. Pass those inputs directly to compatible shapes,
+loft stations, sweeps, and parts. Final part placement permits translation and proper rotation;
+geometry operations also accept affine deformation. Helpers such as `gridPatternTransforms` and
+`attachmentTransform3` return fluent transforms that can be passed on directly.
+
+Use `transform3(frame).toData()` when a numerical algorithm needs matrix coefficients. Obtain
+that data once per station, rather than allocating a fluent result for each point. Freezing a
+frame does not freeze a containing Profile or array; prepare those inputs separately before
+using them as memo arguments.
+
+The [placement guide](transforms-and-placement.md) covers composition order, pivots,
+normal transforms, patterns, and attachment.
+
+## Keep path closure and traversal
+
+Use `path2(points, { closed: true })` or `path3(points, { closed: true })` when closure is part of
+the geometry. `length()` includes the closing edge, without a repeated endpoint.
+
 
-## 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.
+```ts
+// Both paths include the closing edge and have length 40 mm.
+```
 
-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
+[`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.
+first edge in traversal order. That fraction is local to an edge; it is not a whole-path or
+analytic-curve parameter.
+
+Keep the complete `toData()` record when restoring a path: it contains `dimension`, `points`, and
+`closed`. Use `path.toData().points` only when the receiving algorithm needs coordinates alone.
+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 curve.
+
+Chain `transform`, `reverse`, and equal-distance `resample` to produce new paths. Reflection
+preserves traversal order. `polygon(path)` requires a closed planar path and establishes
+exterior/hole winding. Stroke, sweep, and path-pattern operations accept paths in their matching
+dimension. Authored point collections accept fluent vectors or tuples; serialized data uses tuples.
+
+Use `atDistance(distance)` to query an offset in model units, or `atFraction(fraction)` for progress
+from zero to one measured by arc length. Both return a `PathStation` with a fluent point and unit
+tangent, the arc-length `offset`, and the original edge index and local fraction. Zero-length edges
+are skipped. Exact interior vertices use their outgoing edge; an open final endpoint uses its
+incoming edge. A closed path's full length selects its outgoing seam. Path distribution and tangent
+patterns follow the same convention. Out-of-range queries and paths with no usable edge reject.
+
+`splitAt(distance)` cuts strictly inside one traversal and returns two open paths. `trim(start, end)`
+extracts a strictly increasing range within that traversal as an open path. Both retain original
+interior vertices and use the authored seam for closed paths. Trimming a complete closed traversal
+returns an open path with its first point repeated at the end.
 
-### Path coordinate round trip
+Use `subdivide({ maxSegmentLength })` to refine each edge while retaining every original vertex.
+Equal-distance `resample` can bridge corners; subdivision preserves them. Both enforce their
+selected sampling ceilings without reducing requested detail. A resampling count that would repeat
+a closed seam rejects rather than returning invalid path data.
 
 
 
 ```ts
-import { path3 } from "@metamesh/modeling";
+import { path2, path3, spline2 } from "@metamesh/modeling/geometry";
 
 export const boundary = path3(
   [
@@ -154,40 +187,65 @@ export const boundary = path3(
 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.
-```
 
+export const trajectory = path2(
+  [
+    [0, 0],
+    [10, 0],
+    [10, 10],
+    [0, 10],
+  ],
+  { closed: true }
+);
+export const atCorner = trajectory.atDistance(10);
+// The outgoing tangent is [0, 1]; offset is 10 mm.
+export const middle = trajectory.atFraction(0.5);
+export const pieces = trajectory.splitAt(15);
+export const trimmed = trajectory.trim(5, 25);
+export const refined = trajectory.subdivide({ maxSegmentLength: 2 });
+// Each original edge is subdivided independently, preserving all four corners.
+export const smoothRoute = spline2(
+  [
+    [0, 0],
+    [10, 8],
+    [25, 0],
+  ],
+  {
+    resolution: { maxChordError: 0.02, maxSegmentLength: 2 },
+  }
+);
+```
 
 
-`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.
+`spline2` and `spline3` interpolate waypoints with a centripetal Catmull–Rom spline and return
+sampled path values. Open endpoints use one-sided secants; closed paths are periodic. Consecutive
+duplicate waypoints and repeated closed endpoints reject. The default physical sampling policy
+bounds every cubic span. Use `segmentsPerSpan` only when exact parameter intervals are required;
+it overrides physical sampling. All waypoints remain in the sampled result, and one aggregate
+point ceiling bounds the complete path.
 
-## Compose modeling operations
+## Cross the evaluation boundary deliberately
 
-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.
+| From                       | Conversion                                  | What happens                                                    |
+| -------------------------- | ------------------------------------------- | --------------------------------------------------------------- |
+| `Contour` / `RegionData`   | `polygon(...)` to `Section`                 | Captures a recipe without an engine                             |
+| `Profile` family           | `matchProfiles(...)`                        | Pure matching retains identified landmarks                      |
+| Closed `Path2` / `Contour` | `mesh.extrude(...)` to `TriangleMesh`       | Constructs buffers without an engine                            |
+| `TriangleMesh`             | `solidFromMesh(...)` to `Solid`             | Captures a recipe; native validation occurs during evaluation   |
+| `Section`                  | `section.toRegionData()`                    | Reads filled geometry during synchronous generation             |
+| `Solid`                    | `solid.toMesh()`                            | Copies evaluated triangle buffers during synchronous generation |
+| `Solid` / `TriangleMesh`   | `part(...)`, then a host run to `ModelPart` | Finalizes durable immutable buffers                             |
+| `ModelPart`                | Mesh analysis or export                     | Uses completed data without a live session                      |
 
-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.
+Pure mesh extrusion supports height, centering, twist, top scale, and sampling. Native
+`Section.extrude` also supports `ends` treatments. Passing `ends` to `mesh.extrude` rejects; it does
+not silently return unfinished geometry.
 
-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.
+Ordinary recipes can be reused across sessions. `shape.components()` is different: it selects
+evaluated topology, so the selected shapes and recipes that use them can only be evaluated in
+their original session. The host owns evaluation caches and native resources.
 
-For construction details, choose [profiles and extrusion](profiles-and-extrusion.md),
-[sweeps and lofts](sweeps-and-lofts.md), or a
-[worked recipe](recipes.md).
+For completed immutable buffers, use `copy()` when you need mutable storage. Read
+[resolution and inspection](resolution-and-inspection.md#lifecycle-and-inspection) for
+shape observations and [Engine hosting](hosting.md) for finalization and export.

package/dist/docs/guides/hosting.md

@@ -1,9 +1,11 @@
 # Run Modeling in your application
 
-Set up the engine in Node or a browser Worker, then export a captured model as STL, 3MF, or GLB.
+Initialize Modeling, run a program, and manage sessions and completed results in your application.
 
-Build a model in your own application, then export its parts as STL, 3MF, or GLB. Install Modeling in your
-Node application or browser Worker project:
+Start with one engine and one model run. Use this guide for host setup, synchronous execution,
+session lifetime, and resource limits. For terminal commands, use the [CLI](https://metamesh.studio/docs/develop/cli).
+
+Install Modeling in your Node application or browser Worker project:
 
 ```bash
 pnpm add @metamesh/modeling
@@ -26,7 +28,7 @@ This complete function returns the 3MF bytes for a plate with a hole:
 ```ts
 import { box, cylinder, generate } from "@metamesh/modeling";
 import { createModelEngine } from "@metamesh/modeling/engine";
-import { export3mf } from "@metamesh/modeling/export/3mf";
+import { export3mf } from "@metamesh/modeling/export";
 
 export async function makePlate3mf(): Promise<Uint8Array> {
   const engine = await createModelEngine();
@@ -35,7 +37,7 @@ export async function makePlate3mf(): Promise<Uint8Array> {
       const plate = box({ size: [30, 20, 6] });
       // Extend the cutter beyond both faces to avoid coincident Boolean surfaces.
       const bore = cylinder({ radius: 3, height: 8, sizing: "face" });
-      return [part("plate", { geometry: plate.subtract(bore), color: "#67e8f9" })];
+      return part("plate", plate.subtract(bore));
     })
   );
   return (await export3mf(model.parts, { name: "Plate" })).bytes;
@@ -59,6 +61,40 @@ or throws an error listing the available IDs. IDs match exactly. Keep using the
 array for iteration, export, and assertions about output order; use `model.parts.find(...)` when
 absence is expected.
 
+## Reuse a session across edits
+
+Use `engine.run()` for independent one-off builds. Create a session when edits should reuse memoized
+geometry. Dispose it in `finally` when the editing workflow ends:
+
+
+
+```ts
+import { box, generate } from "@metamesh/modeling";
+import { createModelEngine, type ModelResult } from "@metamesh/modeling/engine";
+
+const plate = generate<{ readonly width: number }>(({ params, part }) =>
+  part("plate", box({ size: [params.width, 20, 6] }))
+);
+
+export async function buildPlateRevisions(): Promise<readonly ModelResult[]> {
+  const engine = await createModelEngine();
+  const session = engine.createSession(plate);
+
+  try {
+    const initial = session.run({ width: 30 });
+    const wider = session.run({ width: 40 });
+    return [initial, wider];
+  } finally {
+    session.dispose();
+  }
+}
+```
+
+
+
+Both returned results remain usable after cleanup. An application can keep its session open for
+the editing lifetime instead; the `finally` block shows where that owner releases it.
+
 ## Keep execution synchronous
 
 Load fonts and other assets before generation, and supply any synchronous services when creating
@@ -99,66 +135,17 @@ geometry. Both return diagnostics; unexpected authoring and geometry errors stil
 | `session.check`              | Declarations, assertions, and reached geometry observations | Returned parts are not all evaluated or finalized                                              |
 | `engine.run` / `session.run` | The model and every returned part                           | Finalizes output under the selected topology, mesh-validation, resolution, and resource policy |
 
-A successful check does not evaluate every deferred recipe. For example, an invalid dimension in a
-returned shape may fail only during `run()`. Run representative valid inputs to verify finalized
-geometry. Programs accepting an empty parameter map allow both `session.check()` and `session.run()`.
-For example, checking a returned `box({ size: -1 })` can succeed while running it throws.
-
-## Load WASM in a browser Worker
 
-The package includes its matching JS/WASM kernel. Node and unbundled browser modules resolve the
-installed WASM asset automatically. A browser bundler must retain or emit that relative asset;
-[`modelingWasmUrl`](../reference/engine/modelingWasmUrl.md) can supply the emitted URL through
-`createModelEngine({ wasmUrl: modelingWasmUrl })`.
 
-Create Workers and handle their messages in your application. Each Worker runs independently.
-Transfer copies of completed buffers that you own; transferring cache backing storage would
-detach it. Native handles stay inside their engine.
+**Run the parts you intend to ship**
 
-For incremental delivery, the optional `@metamesh/generator-sdk/modeling` adapter provides
-`ModelDeliveryEncoder`. Its copies can be transferred while the engine result remains usable.
-`PartDeliveryDecoder` from `@metamesh/generator-sdk/runtime` hydrates later resource references:
+A successful check does not evaluate every deferred recipe. Invalid dimensions in a returned shape
+  can fail only during `run()`. Execute representative inputs to verify finalized geometry.
 
 
 
-```ts
-import { ModelDeliveryEncoder } from "@metamesh/generator-sdk/modeling";
-// eslint-disable-next-line no-restricted-imports -- Host documentation snippet; Web only displays this code.
-import { PartDeliveryDecoder } from "@metamesh/generator-sdk/runtime";
-import { type ModelResult } from "@metamesh/modeling/engine";
-import { export3mf } from "@metamesh/modeling/export/3mf";
-
-export async function transferAndExport(model: ModelResult): Promise<Uint8Array> {
-  const encoder = new ModelDeliveryEncoder("preview");
-  const delivery = encoder.encode(model, {
-    revisionId: "preview-1",
-    requestId: 1,
-    bounds: model.bounds,
-    warnings: model.diagnostics,
-  });
-  const buffers = delivery.parts.flatMap(({ geometry }) =>
-    geometry.positions === undefined ? [] : [geometry.positions.buffer, geometry.indices!.buffer]
-  );
-  // This clone exercises the same ownership transfer as worker.postMessage(delivery, buffers).
-  const received = structuredClone(delivery, { transfer: buffers });
-  const decoder = new PartDeliveryDecoder({
-    maxParts: 64,
-    maxVertices: 1_000_000,
-    maxTriangles: 2_000_000,
-    maxBytes: 96 * 1024 * 1024,
-  });
-  const parts = decoder.decode(received.parts);
-  return (await export3mf(parts, { name: "Transferred model" })).bytes;
-}
-```
-
-
-
-Keep one encoder and decoder per ordered connection. Clear both when the receiver is replaced.
-Decoded parts contain **local** buffers under `geometry`, plus world placement. Keep these received
-buffers immutable and attached. Pass decoded parts directly to the shared exporters. They read
-local geometry and apply each part's placement once, preserving shared resources where the format
-permits it. Engine `ModelResult.parts` use that same export contract.
+Programs accepting an empty parameter map allow both `session.check()` and `session.run()`.
+For example, checking a returned `box({ size: -1 })` can succeed while running it throws.
 
 ## Set resource limits
 
@@ -166,40 +153,8 @@ permits it. Engine `ModelResult.parts` use that same export contract.
 Individual runs and sessions may lower those ceilings. Requests that exceed a selected sampling or output
 budget fail explicitly; the engine does not silently reduce modeling fidelity.
 
-## Export the completed result
-
-Import `export3mf`, `exportStl`, or `exportGlb` from `@metamesh/modeling/export`, or load one format
-from `/export/3mf`, `/export/stl`, or `/export/glb`. Every exporter accepts completed parts with local
-`geometry`, an optional placement transform, and optional display color and material identity.
-No engine or renderer is required, and export never reruns the model.
-
-The result contains `bytes: Uint8Array`, `mediaType`, `extension`, `byteLength`, and structured
-`diagnostics`. The host chooses the filename and saves or downloads the bytes. Resolve selected
-parts and appearance overrides before exporting so the file belongs to one captured revision.
-
-Inputs use millimetres and Z-up coordinates. 3MF retains those units; GLB converts to metres and
-Y-up. Binary STL writes placed triangles and reports dropped appearance, material assignments,
-and part names. GLB preserves named parts, shared geometry, placement, and crease-aware shading.
-Export preserves the supplied physical sampling; no writer silently simplifies geometry.
-
-Use explicit `materialId` values with `options.materials` when material identity matters. Two
-materials may share the same RGB value and remain distinct. Per-part display color overrides do
-not change the selected material identity. 3MF carries portable material names and standard
-Materials-extension color groups separately; assigned parts combine those properties with
-`multiproperties`. Slicer support for those properties varies, and this metadata does not select a
-filament or physical tray. Full slicer projects, printer/process presets, and device/filament mapping
-require a separate application adapter.
-
-Exports have their own input and output ceilings through `options.limits`; they do not inherit an
-engine's policy. `meshValidation: "solid"` requests the bounded geometric checks in addition to
-the format's structural requirements. Pass an `AbortSignal` to cancel bounded work.
-
-For large output, `write3mf(parts, sink, options)`, `writeStl`, and `writeGlb` await each sink write
-before continuing and return metadata and diagnostics without collecting the complete output.
-Browser applications own Worker execution; an async function alone does not move CPU work off
-the UI thread. Format entry points isolate runtime loading, while npm installs the containing
-package's dependencies together.
-
-Use the [Export API reference](../reference/export.md) for serialization options,
-the [Engine API reference](../reference/engine.md) for execution, and
-[Modeling guides](https://metamesh.studio/docs/modeling) to choose geometry operations.
+## Continue with delivery
+
+Run your browser host in a [Worker](workers.md) to keep generation off the UI
+thread. [Export the completed parts](exporting.md) when your application needs 3MF, STL,
+or GLB bytes. Those steps consume the result; they do not rerun the model.