@metamesh/modeling 0.18.0 → 0.20.0

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

@@ -0,0 +1,251 @@
+# 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, using `"nonzero"` by default or
+  explicit `"evenodd"` fill.
+- `polygon({ polygons: data })` accepts existing `RegionData`.
+
+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.
+
+## Fluent values, plain data, and descriptors
+
+Import geometric values from `@metamesh/modeling/geometry`. They provide immutable methods for
+calculations and placement:
+
+| 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         |
+
+`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.
+
+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.
+
+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.
+
+### Choose arithmetic for the job
+
+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/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);
+// fluentDirection.toData() and tupleDirection contain the same coordinates.
+```
+
+
+
+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.
+
+
+
+```ts
+// Both paths include the closing edge and have length 40 mm.
+```
+
+
+
+[`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. 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.
+
+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 { path2, path3, spline2 } from "@metamesh/modeling/geometry";
+
+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());
+
+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 },
+  }
+);
+```
+
+
+
+`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.
+
+## Cross the evaluation boundary deliberately
+
+| 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                      |
+
+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.
+
+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 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, build a model, and export it as 3MF.
+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 3MF. 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
@@ -25,27 +27,28 @@ This complete function returns the 3MF bytes for a plate with a hole:
 
 ```ts
 import { box, cylinder, generate } from "@metamesh/modeling";
-import { createModelEngine, export3mf } from "@metamesh/modeling/engine";
+import { createModelEngine } from "@metamesh/modeling/engine";
+import { export3mf } from "@metamesh/modeling/export";
 
-export async function makePlate3mf(): Promise<ArrayBuffer> {
+export async function makePlate3mf(): Promise<Uint8Array> {
   const engine = await createModelEngine();
   const model = engine.run(
     generate(({ part }) => {
       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 export3mf(model.parts, { name: "Plate" });
+  return (await export3mf(model.parts, { name: "Plate" })).bytes;
 }
 ```
 
 
 
-Call `makePlate3mf()` and save or download its returned `ArrayBuffer`. If your application stays
+Call `makePlate3mf()` and save or download its returned `Uint8Array`. If your application stays
 open across edits, initialize the engine once and reuse it. Keep an explicit model session when
-edits should reuse computed geometry.
+edits should reuse memoized geometry.
 
 `engine.run(program, parameters, options?)` returns a durable result after releasing its temporary
 session. Both `engine.run()` and `session.run()` return the same durable immutable `ModelResult`.
@@ -58,10 +61,44 @@ 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
-a run or session. Computed readers and geometry queries run inside synchronous generation: they can't
+a run or session. Memo helpers and geometry queries run inside synchronous generation: they can't
 cross an async boundary. A session also can't run inside another session run in the same
 JavaScript realm.
 
@@ -70,8 +107,8 @@ Keep these lifetimes in mind when reusing shapes:
 - Immutable `Solid` and `Section` recipes, vectors, paths, and transforms can be created without an
   engine and reused across sessions. Explicit resolution settings stay with a recipe; omitted
   settings inherit the evaluating host's defaults.
-- A session runs the model, keeps optional computed caches, and manages native resources. It
-  cleans up temporary native geometry after each run. Computed shapes can stay cached for later
+- A session runs the model, keeps optional memo caches, and manages native resources. It
+  cleans up temporary native geometry after each run. Memoized shapes can stay cached for later
   cuts or Booleans; keep expensive base geometry separate from finishing operations to reuse it.
 - Selections returned by `shape.components()` depend on the evaluated shape. Keep them, and any recipes
   that use them, in the session they came from. Ordinary recipes remain portable.
@@ -98,64 +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, toWorldMeshes } 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 { export3mf, type ModelResult } from "@metamesh/modeling/engine";
-
-export async function transferAndExport(model: ModelResult): Promise<ArrayBuffer> {
-  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 export3mf(toWorldMeshes(parts), { name: "Transferred model" });
-}
-```
-
-
-
-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. Call `toWorldMeshes(parts)` before manufacturing export; engine
-`ModelResult.parts` already contain world-space buffers and go directly to `export3mf`.
+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
 
@@ -163,20 +153,8 @@ buffers immutable and attached. Call `toWorldMeshes(parts)` before manufacturing
 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` from `@metamesh/modeling/engine` and call `export3mf(model.parts, options)`.
-It captures the selected parts before awaiting, uses no engine or kernel, and never blocks generation
-or runs the model again. Set `options.limits` explicitly when your exporting host uses nondefault
-resource ceilings. Your application chooses the filename, saves or downloads the bytes, and saves any model
-revisions or appearance overrides you want to keep.
-
-The package exports 3MF directly. For a custom renderer or another exporter, copy each part's
-world-space `positions` and `indices` into owned typed arrays; its placement is already applied.
-Renderer adapters can instead use local `part.geometry` and apply `part.transform` once.
-The placement is a frozen row-major 16-number rigid matrix; convert its layout explicitly if your
-renderer expects column-major storage.
-Studio supplies its own STL and GLB adapters.
+## Continue with delivery
 
-Use the [Engine API reference](../reference/engine.md) for exact options and result types, and
-[Modeling guides](https://metamesh.studio/docs/modeling) to choose geometry operations.
+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.