@metamesh/modeling 0.18.0 → 0.19.0

package/dist/docs/guides/generation.md

@@ -32,12 +32,12 @@ export default generate(({ params: parameters, part }) => {
 
 The helper infers `params` from **Model controls** as readonly numbers, strings, and structured
 values. Import `type Parameters` from `@metamesh/project` when a separate helper needs the type.
-Parameters and computed results use `ImmutableValue<T>` views: nested objects, arrays, and tuples
+Parameters and memo results use `ImmutableValue<T>` views: nested objects, arrays, and tuples
 are readonly in TypeScript and frozen when captured at runtime. Create a copy for editable working
 data. Fluent Modeling methods and explicit buffer `copy()` calls retain their normal return types.
 
 The outer callback runs for each edit. Return a single `part(...)` or a readonly array of parts.
-You can add `computed` when you need it.
+You can add `memo` when you need it.
 Export only the default program; keep helpers local to `model.ts`. Definitions and presets remain
 serializable metadata. There are no separate preparation/build exports.
 
@@ -61,8 +61,8 @@ assert(
 
 Assertions follow normal code order. Put cheap checks before costly reads so invalid dimensions
 can stop the work early. An assertion that reads geometry must evaluate that geometry first.
-Warnings belong in the outer callback; assertions can also run inside computed values, whenever
-that computation evaluates.
+Warnings belong in the outer callback; assertions can also run inside a memo helper when it
+evaluates. Pass the full generation context to a helper that needs `assert` or fixed services.
 
 ## Reuse unchanged work
 
@@ -70,79 +70,86 @@ that computation evaluates.
 
 **Caching is optional**
 
-Start with ordinary generation code. If parameter edits become slow, add `computed` around
-  expensive work that can stay unchanged across edits. Cheap arithmetic and part placement usually
-  do not need caching.
+Start with ordinary generation code. If parameter edits become slow, add `memo` around expensive
+  work that can stay unchanged across edits. Cheap arithmetic and part placement usually do not need
+  caching.
 
 
 
-`computed(id, callback)` creates a lazy reader of cached data or geometry. Calling it evaluates the
-calculation when needed; passing it directly to `part` defers evaluation until the outer callback
-succeeds. **Read `params`, derive values, and destructure inside the computed callback.** These
-reads are tracked automatically, including reads made by synchronous helpers called there:
+`memo(fn, ...args)` calls a synchronous helper and returns its immutable result directly. Repeated
+calls with the same function and unchanged inputs can reuse that result. Define helpers at module
+scope so their identity stays stable between generations.
+
+Pass the exact `params` object when a helper needs several parameters. MetaMesh tracks the fields
+read while the helper runs, including reads made by synchronous helpers it calls:
 
 
 
 ```ts
-const body = computed("body", () => {
-    const { width, height } = params;
-    return box({ size: [width, 10, height] });
-  });
+function buildTrackedBody(params: Readonly<Parameters>) {
+  const { width, height } = params;
+  return box({ size: [width, 10, height] });
+}
 ```
 
 
 
-Call other computed readers inside the callback too: `computed("finished", () => base().subtract(...))`
-tracks the base result automatically. In **New project → Cached panels**, changing **Gap** only
-moves the second panel; changing **Notch width** reuses the hole pattern for the finishing cut.
+You can also pass ordinary arguments, just as you would call the function normally. These are the
+function's inputs, not a separate dependency declaration:
+
+
+
+```ts
+function buildBody(width: number, height: number) {
+  return box({ size: [width, 10, height] });
+}
+```
+
 
-An earlier read such as `const { height } = params` captures the value at that moment. Using it
-inside a computation doesn't track the parameter and can reuse stale geometry. Move the read
-inside the callback. If a changing value must be prepared outside, such as a loop item, list it
-in the optional third argument:
+
+Inside `generate`, both forms return values ready for `part` or the next memo:
 
 
 
 ```ts
-const { height } = params;
-  const capturedBody = computed("captured-body", () => box({ size: [params.width, 10, height] }), [
-    height,
-  ]);
+const body = memo(buildTrackedBody, params);
+  const argumentBody = memo(buildBody, params.width, params.height);
 ```
 
 
 
-Both examples rebuild when width or height changes. The array supplements automatic tracking;
-`params.width` is still tracked inside the second callback, and even `[]` keeps automatic reads.
+Both rebuild when width or height changes. Unrelated parameters can change without rebuilding.
+Compose stages by passing memo results directly: `memo(finishBody, body, params)`.
+In **New project → Cached panels**, changing **Gap** only moves the second panel; changing
+**Notch width** reuses the hole pattern for the finishing cut.
 
-The same capture rule applies to an eagerly read result such as `const value = otherComputed()`.
-Select and call readers inside the callback when possible. Studio warns about common hidden captures
-while Code is open; its advisory checks cannot prove arbitrary JavaScript correct.
+A function defined inside `generate`, including an inline arrow, gets a new identity each run.
+It still computes correctly, but cannot reuse previous runs. Studio warns about common cases while
+Code is open; factories, dynamic aliases, and arbitrary JavaScript aren't always identifiable.
 
 Test representative parameter edits in the same session when using cached computations. An isolated
 run cannot expose stale reuse. Standalone sessions and Testkit's Generator runner accept
 `verifyCache: true` to check retained results against fresh computation. The probe is bounded;
-compare finalized output with `cache: false` when it cannot compare a model's computations.
-
-Dependency entries use `Object.is`, without comparing object or array contents. Use immutable
-parameter values, computed results, or scalar inputs; other objects must be deeply frozen. Create
-temporary options inside the callback, since fresh object or array dependencies prevent reuse.
-Studio warns about obvious fresh dependencies without running generation.
+compare finalized output with `cache: false` when it cannot compare a model's calculations.
 
-IDs identify logical computations, so loops and conditions work without hook call-order rules.
-IDs must be unique lowercase hyphen-separated alphanumeric names of at most 64 characters within
-their namespace.
+Ordinary arguments use `Object.is`, without comparing object or array contents. Use immutable
+parameter values, memo results, or scalar inputs; other objects must be deeply frozen. Creating a
+fresh frozen object each generation still misses the cache. Create temporary options inside the
+helper, and pass its scalar inputs. A TypeScript `readonly` annotation doesn't freeze runtime data.
+An array is one argument; use `memo(fn, ...tuple)` to spread several arguments.
 
 Keep calculations synchronous and pure: do not mutate cached values, read clocks or randomness,
-perform effects, or return promises or functions. The physical result must remain the same after
+perform effects, or return promises or functions. Pass every changing input explicitly; a helper
+that reads changing module state can reuse stale output. Neither editor warnings nor runtime
+tracking can prove purity. The physical result must remain the same after
 cache eviction or a worker restart. Cache expensive layouts or grids; cheap arithmetic usually
 does not need its own computation.
 
-For cached numeric data, call [`immutableBuffer`](../reference/model/immutableBuffer.md) and use
+For cached numeric data, call [`immutableBuffer`](../reference/geometry/immutableBuffer.md) and use
 its `length`, `at(index)`, standard iteration, or `copy()` method. Copy once before a dense sampling callback so its
 inner loop reads an ordinary typed array. Capture a cached indexed mesh with
-[`mesh.immutable`](../reference/mesh/immutable.md); its reader can pass directly to `part`.
-Raw typed arrays in computed results or dependencies reject with guidance to use these helpers.
+[`mesh.immutable`](../reference/mesh/immutable.md); its value can pass directly to `part`.
+Raw typed arrays in memo results or arguments reject with guidance to use these helpers.
 
 ## Text services
 
@@ -174,7 +181,7 @@ export default generate(({ params, services, part }) => {
 
 Use `part("body", geometry)` for the simple form, or pass an object with `geometry`,
 `transform` and `color`. Geometry accepts a Solid or indexed manufacturing mesh.
-Geometry and placement accept values or computed readers. Give each part a stable ID:
+Geometry and placement accept values. Give each part a stable ID:
 
 
 

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

@@ -0,0 +1,193 @@
+# 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:
+
+- `polygon(points)` fills one contour.
+- `polygon({ outer, holes })` validates exterior/hole topology and normalizes winding.
+- `polygon({ contours, fillRule })` resolves compound paths with `"nonzero"` fill by default or
+  explicit `"evenodd"` fill.
+- `polygon({ polygons: data })` accepts existing `RegionData`.
+
+Each returns a `Section`, like `circle` or `rectangle`. Later Booleans may produce holes or
+disconnected components. Use `section.toRegionData()` inside synchronous generation to read
+the evaluated shape; keep serialized point data for interchange or calculations outside generation.
+
+`rectangleProfile({ size: [width, height], treatment: { kind: "round", radius }, id })` describes
+identified spans for custom geometry. Use `matchProfiles` to prepare a complete family when loft
+stations or a sweep need holes, seams, or landmarks beyond ordinary primitives.
+
+Identified spans also accept cubic Béziers with the same endpoints and controls as
+[`CubicBezierCurve2`](../reference/geometry/CubicBezierCurve2.md). Paired spans share one parameter
+grid; physical sampling refines every member before choosing the family count. Collapsed spans
+retain repeated logical slots, while the completed loft removes degenerate faces.
+
+## Choose fluent values or standalone algorithms
+
+### Convert representations deliberately
+
+| From                       | Conversion                                     | Evaluation and ownership                                       |
+| -------------------------- | ---------------------------------------------- | -------------------------------------------------------------- |
+| `Contour` / `RegionData`   | `polygon(...)` to `Section`                    | Captures a recipe without an engine                            |
+| `Section`                  | `section.toRegionData()`                       | Observes evaluated geometry inside a host execution            |
+| `Profile`                  | `matchProfiles(...)`                           | Pure matching retains identified boundaries and landmarks      |
+| Closed `Path2` / `Contour` | `mesh.extrude(...)` to `TriangleMesh`          | Pure mesh construction; no `ends` treatments                   |
+| `TriangleMesh`             | `solidFromMesh(...)` to `Solid`                | Captures a recipe; native validation happens during evaluation |
+| `Solid` / `TriangleMesh`   | `part(...)`, then an engine run to `ModelPart` | Host finalizes durable immutable manufacturing buffers         |
+| `ModelPart`                | Pass directly to mesh analysis or `export3mf`  | No live session needed; use buffer `copy()` before mutation    |
+
+Pure extrusion uses `ExtrudeMeshOptions` for height, centering, twist, top scale, and sampling.
+Native `Section.extrude` also supports `ends` through `ExtrudeOptions`; requesting them from
+`mesh.extrude` throws instead of silently returning unfinished geometry.
+
+Use methods for ordinary composition and queries on a value, such as `path.transform(...)`,
+`path.closestPoint(...)`, or `vector.normalize()`. Use standalone algorithms for specialized
+outputs, such as [`computeParallelTransportFrames`](../reference/geometry/computeParallelTransportFrames.md),
+[`mesh.sweep`](../reference/mesh/sweep.md), or
+[`resolveCylindricalGear`](../reference/geometry/resolveCylindricalGear.md).
+
+### Fluent vector and tuple arithmetic
+
+Tuple kernels remain useful in numerical loops. The same arithmetic can be written in either form:
+
+
+
+```ts
+import { vector3 } from "@metamesh/modeling";
+import { add3, normalize3, scale3 } from "@metamesh/modeling/geometry";
+
+export const fluentDirection = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
+export const tupleDirection = scale3(normalize3(add3([1, 2, 3], [4, 0, 0])), 10);
+// fluentDirection.toData() and tupleDirection contain the same coordinates.
+```
+
+
+
+Fluent vectors validate finite inputs and results and allocate immutable values. Basic tuple
+arithmetic such as `add3` avoids those wrappers and assumes valid inputs; overflow can produce
+nonfinite results. Individual kernels document additional checks, such as zero-length rejection
+in `normalize3`.
+
+## Value and data naming
+
+Modeling values use domain names such as `Vector2`, `Transform2`, `Path2`, and `Bounds2`.
+Their plain representations consistently use `Data`: `Vector2Data`, `Transform2Data`,
+`Path2Data`, and `Bounds2Data`. Each value exposes `toData()` for a stable, deeply frozen
+representation, and its factory accepts that data again. `Input` types describe accepted values,
+data, and any supported construction shorthand.
+
+Vector data is a coordinate tuple, transform data a canonical matrix, bounds data a min/max record,
+and path data a record with `dimension`, `points`, and `closed`. Use `path.toData().points`
+when a numerical algorithm needs only coordinates; keep the full record when closure matters too.
+Options, reports, geometry descriptors, and recipes keep their own descriptive names. Use
+`toMesh()` or `toRegionData()` during active host execution to evaluate a Solid as a triangle mesh
+or a Section as a region.
+
+## Query paths and preserve closure
+
+Use `path2(points, { closed: true })` or `path3(points, { closed: true })` for a reusable boundary.
+`length()` includes the closing edge. [`closestPoint`](../reference/geometry/Path3-type.md#closestpoint)
+returns a [`PathLocation`](../reference/geometry/PathLocation.md): a fluent `point`, `distance` in
+millimetres, `edgeIndex`, and clamped `fraction` within that edge. Equal-distance ties select the
+first edge in traversal order. The fraction is local to an edge; it is not a whole-path or analytic
+curve parameter.
+
+### Path coordinate round trip
+
+
+
+```ts
+import { path3 } from "@metamesh/modeling";
+
+export const boundary = path3(
+  [
+    [0, 0, 0],
+    [10, 0, 0],
+    [10, 10, 0],
+    [0, 10, 0],
+  ],
+  { closed: true }
+);
+export const nearest = boundary.closestPoint([-2, 5, 0]);
+// point: [0, 5, 0], distance: 2, edgeIndex: 3, fraction: 0.5
+export const restoredPath = path3(boundary.toData());
+// Both paths include the closing edge and have length 40 mm.
+```
+
+
+
+`toData()` returns a deeply frozen record with `dimension`, `points`, and `closed`. Pass the path
+value directly where supported, or restore the full record with `path2(data)` or `path3(data)`.
+Don't repeat the endpoint of a closed path. Open paths may be empty; their bounds are `undefined`,
+and nearest-edge queries require at least two vertices. Queries measure the sampled boundary,
+not a filled interior or underlying analytic curve.
+
+Chain `transform`, `reverse`, and equal-distance `resample` to create new paths. Transforming a path
+preserves traversal even after reflection. `polygon(path)` requires a closed planar value and
+establishes exterior/hole winding; `stroke`, sweeps, and path patterns accept paths in the matching
+dimension. Authored point collections accept fluent vectors or tuples; serialized data uses tuples.
+
+## Compose modeling operations
+
+Give intermediate shapes meaningful names and choose a curve tolerance that preserves the detail
+you need. Many high-resolution Boolean operands take longer to build.
+
+Dimension inputs accept matching fluent vectors or plain coordinate tuples, such as
+`box({ size: vector3([30, 20, 6]) })`. Use `section.extrude(options)`, `section.revolve(options)`,
+and `section.sweep(path, options)` in fluent modeling sequences. Imported `extrude`, `revolve`, and
+`sweep` accept `Section | CorrespondingProfile`, so reusable profile functions can use either input
+without branching. Both forms use the same operation contracts. Use `mesh.extrude(contour, options)`
+when constructing triangle buffers directly.
+
+Primitive factories take one options object. For example, `rectangle({ size: [24, 16] })` creates a
+filled Section and `box({ size: [24, 16, 6] })` creates a Solid. The `union`, `subtract`, and `intersect`
+methods accept one same-dimensional shape or a readonly array; an empty array preserves the receiver.
+Collection `union(shapes)` and `intersect(shapes)` combine peers and require at least one shape.
+`section.offset(distance, options)` stays in the filled XY plane.
+
+For construction details, choose [profiles and extrusion](profiles-and-extrusion.md),
+[sweeps and lofts](sweeps-and-lofts.md), or a
+[worked recipe](recipes.md).

package/dist/docs/guides/hosting.md

@@ -1,8 +1,8 @@
 # Run Modeling in your application
 
-Set up the engine in Node or a browser Worker, build a model, and export it as 3MF.
+Set up the engine in Node or a browser Worker, then export a captured model as STL, 3MF, or GLB.
 
-Build a model in your own application, then export its parts as 3MF. Install Modeling in your
+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:
 
 ```bash
@@ -25,9 +25,10 @@ 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/3mf";
 
-export async function makePlate3mf(): Promise<ArrayBuffer> {
+export async function makePlate3mf(): Promise<Uint8Array> {
   const engine = await createModelEngine();
   const model = engine.run(
     generate(({ part }) => {
@@ -37,15 +38,15 @@ export async function makePlate3mf(): Promise<ArrayBuffer> {
       return [part("plate", { geometry: plate.subtract(bore), color: "#67e8f9" })];
     })
   );
-  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`.
@@ -61,7 +62,7 @@ absence is expected.
 ## 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 +71,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.
@@ -121,12 +122,13 @@ For incremental delivery, the optional `@metamesh/generator-sdk/modeling` adapte
 
 
 ```ts
-import { ModelDeliveryEncoder, toWorldMeshes } from "@metamesh/generator-sdk/modeling";
+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 { export3mf, type ModelResult } from "@metamesh/modeling/engine";
+import { type ModelResult } from "@metamesh/modeling/engine";
+import { export3mf } from "@metamesh/modeling/export/3mf";
 
-export async function transferAndExport(model: ModelResult): Promise<ArrayBuffer> {
+export async function transferAndExport(model: ModelResult): Promise<Uint8Array> {
   const encoder = new ModelDeliveryEncoder("preview");
   const delivery = encoder.encode(model, {
     revisionId: "preview-1",
@@ -146,7 +148,7 @@ export async function transferAndExport(model: ModelResult): Promise<ArrayBuffer
     maxBytes: 96 * 1024 * 1024,
   });
   const parts = decoder.decode(received.parts);
-  return export3mf(toWorldMeshes(parts), { name: "Transferred model" });
+  return (await export3mf(parts, { name: "Transferred model" })).bytes;
 }
 ```
 
@@ -154,8 +156,9 @@ export async function transferAndExport(model: ModelResult): Promise<ArrayBuffer
 
 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`.
+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.
 
 ## Set resource limits
 
@@ -165,18 +168,38 @@ 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.
-
-Use the [Engine API reference](../reference/engine.md) for exact options and result types, and
+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.