@metamesh/modeling 0.17.0 → 0.18.0

package/dist/docs/guides/generation.md

@@ -1,16 +1,17 @@
 # Code Project contract
 
-Understand Studio’s TypeScript source contract, computed caches, parts, resource ownership, and recovery.
+Learn how Studio runs your TypeScript model, reuses work across edits, and keeps a preview available when an edit fails.
 
-An authored Project has one control definition and one TypeScript entry file. Studio supplies the
-compiler, prepared services, modeling engine, persistence and preview.
+An authored Project has one control definition and one TypeScript entry file. You write the model;
+Studio compiles it, prepares services, runs the modeling engine, saves the Project, and shows the preview.
 
 ## Source boundary
 
 Keep helpers in the single editable `model.ts` file. Import modeling operations from
-`@metamesh/modeling`, pure utilities from `@metamesh/modeling/geometry`, and the typed
+`@metamesh/modeling`, pure utilities from `@metamesh/modeling/geometry`, mesh operations from
+`@metamesh/modeling/geometry/mesh`, and the typed
 `generate` helper from `@metamesh/project`. These approved modules and declarations work offline.
-Source cannot install packages, fetch modules or initialize another kernel.
+Source can't install packages, fetch modules, or initialize another kernel.
 
 ## Start with generate
 
@@ -31,9 +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
+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;
-`computed` is optional.
+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.
 Export only the default program; keep helpers local to `model.ts`. Definitions and presets remain
 serializable metadata. There are no separate preparation/build exports.
 
@@ -55,9 +59,10 @@ assert(
 
 
 
-Assertions follow normal code order. Put cheap checks before costly reads. 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.
+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.
 
 ## Reuse unchanged work
 
@@ -91,10 +96,10 @@ Call other computed readers inside the callback too: `computed("finished", () =>
 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.
 
-An earlier read such as `const { height } = params` captures a snapshot. Using it inside a
-computation does not 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:
+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:
 
 
 
@@ -114,6 +119,11 @@ The same capture rule applies to an eagerly read result such as `const value = o
 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.
 
+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.
@@ -129,14 +139,14 @@ cache eviction or a worker restart. Cache expensive layouts or grids; cheap arit
 does not need its own computation.
 
 For cached numeric data, call [`immutableBuffer`](../reference/model/immutableBuffer.md) and use
-its `length`, `at(index)`, or `copy()` methods. Copy once before a dense sampling callback so its
+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
-[`immutableMesh`](../reference/model/immutableMesh.md); its reader can pass directly to `part`.
+[`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.
 
 ## Text services
 
-The host injects `services` into the callback after preparing exact selected font bytes.
+Studio prepares the exact selected font bytes before passing `services` to the callback.
 Call `services.text.layout()` synchronously, check its metrics, then pass the layout to
 `textSection(layout)`. Generation itself does no networking:
 
@@ -163,30 +173,33 @@ export default generate(({ params, services, part }) => {
 ## Parts and placement
 
 Use `part("body", geometry)` for the simple form, or pass an object with `geometry`,
-`position`, `rotation` and `color`. Geometry accepts a Solid or indexed manufacturing mesh.
-Geometry and placement accept values or computed readers. Keep stable semantic part IDs:
+`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:
 
 
 
 ```ts
 export default generate(({ params: parameters, part }) => {
   const base = box({ size: [parameters.width, parameters.depth, parameters.height] });
-  const lid = box({ size: [parameters.width, parameters.depth, 2] }).translate([
-    0,
-    parameters.depth + 4,
-    0,
-  ]);
+  const lid = box({ size: [parameters.width, parameters.depth, 2] });
   return [
     part("base", { geometry: base, color: "#3b82f6" }),
-    part("lid", { geometry: lid, color: "#f59e0b" }),
+    part("lid", {
+      geometry: lid,
+      transform: transform3().translate([0, parameters.depth + 4, 0]),
+      color: "#f59e0b",
+    }),
   ];
 });
 ```
 
 
 
-Lengths use millimetres and rotations use degrees. Coordinates are right-handed with **+Z up**.
-Rotation applies about fixed X, then Y, then Z axes before translation. Part placement governs
+Use a `transform3()` value or a row-major 16-number matrix for translation and rotation;
+omitting it means identity placement. Scale, shear, reflection and perspective are rejected.
+Pattern and attachment transforms pass directly to this option.
+Lengths use millimetres and fluent rotations use degrees. Coordinates are right-handed with **+Z up**.
+Fluent transform calls apply in written order. Part placement governs
 preview, picking, measurements and all exports. Changing placement or color can reuse cached
 geometry and renderer buffers. Studio's native part-color overrides update appearance directly.
 Use modeling `translate`/`rotate` when moving a cutter or feature inside construction.
@@ -203,12 +216,12 @@ Solids and Sections are immutable deferred recipes. Ordinary recipes can be reus
 sessions; unspecified resolution settings inherit the evaluating host's defaults. Apply local
 resolution explicitly to each affected constructor or Section operation.
 
-Observations such as `inspectSolid` evaluate required geometry synchronously and return copied
-facts. `components()` selections and recipes using them can only be evaluated in their originating
-session because their identity depends on evaluated topology. The host cleans up native
+Calls such as `shape.inspect()` evaluate the required geometry synchronously and return copied
+measurements. `shape.components()` selections and recipes using them can only be evaluated in their
+originating session because their identity depends on evaluated topology. The host cleans up native
 allocations on success and failure. Nested or asynchronous execution rejects.
 
-Source/control-definition changes invalidate the program session. Parameter edits reuse it.
+Changing the source or control definition invalidates the program session. Parameter edits reuse it.
 Failed or stale requests retain the last valid preview; fatal failures replace the worker.
 Unsupported older Project data remains available through raw backup for manual source conversion;
 there is no old executor and no automatic destructive reset.

package/dist/docs/guides/hosting.md

@@ -1,83 +1,107 @@
 # Run Modeling in your application
 
-Initialize the engine in Node or a browser Worker, build a model, and export its completed snapshot.
+Set up the engine in Node or a browser Worker, build a model, and export it as 3MF.
 
-Install the public package in a Node application or browser Worker project:
+Build a model in your own application, then export its parts as 3MF. Install Modeling in your
+Node application or browser Worker project:
 
 ```bash
 pnpm add @metamesh/modeling
 ```
 
+Use Node.js 24 or newer for Node hosts. The package publishes ES modules only; TypeScript
+consumers use TypeScript 6.0 or newer with `strict` checking and `NodeNext` or `Bundler` resolution.
+Browser Workers need an ES2023-compatible runtime and WebAssembly.
+
 The package is in Preview: `0.x` minor releases may change its API, while patches remain compatible
 within a minor line. Keep your dependency and examples on the same minor version.
 
 ## Build and export a plate
 
-Initialize an engine, define a program with `generate`, then run it through a session.
+Initialize an engine, define a program with `generate`, then call `engine.run`.
 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 { createModelEngine, export3mf } from "@metamesh/modeling/engine";
 
 export async function makePlate3mf(): Promise<ArrayBuffer> {
   const engine = await createModelEngine();
-  const session = engine.createSession(
+  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", { geometry: plate.subtract(bore), color: "#67e8f9" })];
     })
   );
-  try {
-    const model = session.run({});
-    // Generation already disposed native handles. These finalized meshes remain usable.
-    try {
-      return await engine.export3mf(model.parts, { name: "Plate" });
-    } finally {
-      model.dispose();
-    }
-  } finally {
-    session.dispose();
-  }
+  return export3mf(model.parts, { name: "Plate" });
 }
 ```
 
 
 
-Call `makePlate3mf()` and save or download its returned `ArrayBuffer`. For a long-lived application,
-move engine initialization out of the function and reuse that engine and its model sessions across edits.
+Call `makePlate3mf()` and save or download its returned `ArrayBuffer`. 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.
+
+`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`.
+Parts, measurements, bounds, and statistics remain usable without cleanup, including after session disposal.
+Parameterless programs can omit parameters; configure them with
+`engine.run(program, undefined, options)`.
+
+Use `model.part("plate")` when you need a specific semantic part. It returns that part directly,
+or throws an error listing the available IDs. IDs match exactly. Keep using the ordered `model.parts`
+array for iteration, export, and assertions about output order; use `model.parts.find(...)` when
+absence is expected.
 
 ## Keep execution synchronous
 
-Acquire assets before generation and supply synchronous services when creating a session.
-Computed readers and geometry observations require active synchronous generation. They cannot
-cross an async boundary, and sessions cannot run inside another session run in the same realm.
+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
+cross an async boundary. A session also can't run inside another session run in the same
+JavaScript realm.
 
-Recipes and evaluated geometry have different lifetimes:
+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 owns evaluation, optional computed caches, and native resources. Temporary native
-  allocations are cleaned after each run. Computed shapes may stay cached for later cuts or
-  Booleans; separate expensive base geometry from finishing operations to reuse it.
-- Observed `components()` selections depend on evaluated topology and belong to their originating
-  session. Ordinary recipes remain portable.
-
-A snapshot retains captured manufacturing buffers independently of its session:
-
-- Reading a part's `positions` or `indices`, including through its local `geometry` resource,
-  returns a fresh owned copy. Read each field once when processing its buffer.
-- `session.dispose()` releases caches; captured snapshots remain usable.
-- `snapshot.dispose()` releases its references and invalidates later `parts`, `bounds`, and `stats`
-  access. Diagnostics, dependencies, and parts already obtained remain usable. Other snapshots
-  and exports already in progress are unaffected.
-
-Dispose each snapshot when its consumer is done.
+- 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
+  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.
+
+A result keeps the finished mesh data available even after you dispose its session:
+
+- A part's `positions` and `indices` are stable immutable values. The part uses world-space
+  coordinates; its local `geometry` resource keeps reusable geometry separate from placement.
+  Read `length`, `at(index)`, or iterate without copying. Use `copy()` for an owned mutable typed array;
+  geometry utilities and export accept the immutable mesh directly.
+- `session.dispose()` releases caches and native resources; captured results remain usable.
+- Results have no disposal method. Release your references when you no longer need their data.
+
+## Check declarations before running
+
+`checkModel(program, parameters)` checks declarations and reached assertions without initializing
+the kernel or finalizing output. Use `session.check(parameters)` when a reached assertion observes
+geometry. Both return diagnostics; unexpected authoring and geometry errors still throw.
+
+| Operation                    | Executes model code                                         | Geometry guarantee                                                                             |
+| ---------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| CLI `typecheck`              | No; checks TypeScript                                       | No geometry is evaluated                                                                       |
+| `checkModel`                 | Declarations and reached assertions                         | No kernel; geometry observations require a session                                             |
+| `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
 
@@ -86,21 +110,73 @@ installed WASM asset automatically. A browser bundler must retain or emit that r
 [`modelingWasmUrl`](../reference/engine/modelingWasmUrl.md) can supply the emitted URL through
 `createModelEngine({ wasmUrl: modelingWasmUrl })`.
 
-Your application owns Worker creation and message handling. Separate Workers have independent
-execution scopes. Transfer owned copies of completed buffers; transferring cache backing storage
-would detach it. Native handles remain private to their engine.
+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.
+
+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:
+
+
+
+```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`.
 
 ## Set resource limits
 
 [`createModelEngine`](../reference/engine/createModelEngine.md) accepts trusted host limits.
-Individual sessions may lower those ceilings. Requests that exceed a selected sampling or output
+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
 
-`engine.export3mf(snapshot.parts, options)` exports the selected finalized buffers without
-running the model again. Your host chooses the filename, saves or downloads the bytes, and owns
-any persisted model revisions or appearance overrides.
+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
 [Modeling guides](https://metamesh.studio/docs/modeling) to choose geometry operations.