@metamesh/modeling 0.17.0 → 0.19.0

package/dist/docs/guides/hosting.md

@@ -1,19 +1,24 @@
 # 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, then export a captured model as STL, 3MF, or GLB.
 
-Install the public package in a Node application or browser Worker project:
+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
 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:
 
 
@@ -21,63 +26,83 @@ 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";
 
-export async function makePlate3mf(): Promise<ArrayBuffer> {
+export async function makePlate3mf(): Promise<Uint8Array> {
   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 (await export3mf(model.parts, { name: "Plate" })).bytes;
 }
 ```
 
 
 
-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 `Uint8Array`. If your application stays
+open across edits, initialize the engine once and reuse it. Keep an explicit model session when
+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`.
+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. 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.
 
-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 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.
+
+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 +111,95 @@ 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 } 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.
 
 ## 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.
-
-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.

package/dist/docs/guides/profiles-and-extrusion.md

@@ -0,0 +1,252 @@
+# Build solids from profiles and primitives
+
+Choose primitives, extrude filled outlines, revolve radial profiles, and finish their rims.
+
+Start with a primitive when it already describes the material. For a plate, gasket, cup, or knob,
+solve the filled cross section first, then add depth or revolve it around an axis.
+
+Run the examples in a [Studio code Project](https://metamesh.studio/docs/develop/code-projects), where Studio supplies
+typed controls and prepared services. For a local model, follow the
+[standalone workflow](standalone-model.md) and use its host entry point.
+
+## Choose a primitive
+
+Start with the factory that most closely describes the shape. The first row below contains ready
+Solids; the second contains filled Sections extruded to `5 mm` thickness. Each result remains a
+separate named part so you can inspect it in the interactive preview.
+
+
+
+```ts
+import { ellipse, regularPolygon, sphere, star, torus, transform3, tube } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  // Solid primitives are ready for placement; filled Sections need depth first.
+  // Place finished parts on two rows while keeping local geometry reusable.
+  return [
+    part("sphere", {
+      geometry: sphere({ diameter: 14 }),
+      transform: transform3().translate([0, 0, 7]),
+      color: "#60a5fa",
+    }),
+    part("torus", {
+      geometry: torus({ majorRadius: 7, minorRadius: 2 }),
+      transform: transform3().translate([24, 0, 2]),
+      color: "#34d399",
+    }),
+    part("tube", {
+      geometry: tube({ outerRadius: 7, innerRadius: 4, height: 10, center: false }),
+      transform: transform3().translate([48, 0, 0]),
+      color: "#f59e0b",
+    }),
+    part("ellipse", {
+      geometry: ellipse({ size: [18, 12] }).extrude({ height: 5 }),
+      transform: transform3().translate([0, 24, 0]),
+      color: "#c084fc",
+    }),
+    part("star", {
+      geometry: star({ outerRadius: 9, innerRadius: 4.5, points: 5 }).extrude({ height: 5 }),
+      transform: transform3().translate([24, 24, 0]),
+      color: "#fb7185",
+    }),
+    part("hexagon", {
+      geometry: regularPolygon({ radius: 7, sides: 6, sizing: "face" }).extrude({ height: 5 }),
+      transform: transform3().translate([48, 24, 0]),
+      color: "#22d3ee",
+    }),
+  ];
+});
+```
+
+Sphere, torus, and tube are solid factories. Ellipse, star, and regular polygon create Sections that can be extruded.
+
+
+
+Use a [`tube`](../reference/model/tube.md) when the bore is concentric; it avoids a separate cutter.
+A [`torus`](../reference/model/torus.md) uses the distance to the circular profile's center as its
+major radius. [`regularPolygon`](../reference/model/regularPolygon.md) has an exact side count;
+`sizing: "face"` makes the specified radius reach the faces instead of the vertices. Keep physical
+curve tolerance for ordinary round shapes and use exact segment counts for deliberate faceting.
+
+`circle` and `cylinder` support the same vertex or face sizing convention.
+`tube` accepts a complete pair of inner/outer radii or diameters, with independent `innerSizing`
+and `outerSizing`. For example, `tube({ innerDiameter: 8, outerDiameter: 12, height: 10,
+innerSizing: "face" })` preserves an 8 mm clear bore between the sampled faces. Both defaults are
+`"vertex"`; compensation that removes the wall rejects. Sampling and sizing do not establish a
+manufacturing fit allowance.
+
+## Section, hole, offset, and extrusion
+
+
+
+```ts
+import { circle, rectangle } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const plate = rectangle({ size: [80, 45] });
+  const hole = circle({ radius: 4 });
+  // Positive offset expands material: the outer edge grows and the hole shrinks.
+  const rimmedPlate = plate.subtract(hole).offset(1.2);
+  // Keep the plate centered about Z = 0 for later symmetric placement.
+  return [part("model", rimmedPlate.extrude({ height: 5, center: true }))];
+});
+```
+
+Subtract the opening in 2D, offset the filled material, then extrude it into one plate.
+
+
+
+`rectangle` and `circle` take object options and return filled Sections. The `union`, `subtract`, and
+`intersect` methods accept one shape or an array and also support Solids; every operand in a call
+must have the same dimension. Use collection `union(shapes)` or `intersect(shapes)` to combine peers.
+`section.offset(distance)` offsets the filled material. `section.extrude({ height })` preserves
+holes and places the bottom at zero unless `center: true` is requested.
+
+Ordinary extrusion also accepts `twist` and `scaleTop`. Keep those operations separate from
+enabled end treatments, which require a straight extrusion.
+
+Positive offset grows material on every boundary: this example grows the outside by `1.2 mm` and
+reduces the hole radius from `4 mm` to `2.8 mm`. If the final bore must remain `8 mm` in diameter,
+offset the outside first and subtract the hole afterward. See
+[`Section.offset`](../reference/model/Section.md#offset) and [`Section.extrude`](../reference/model/Section.md#extrude).
+
+## Revolve a radial profile
+
+Use revolution when one side outline can describe the entire part around an axis. In the Section
+below, X is radius and Y is final Z height; radii must stay nonnegative. The closed loop includes
+the cup's floor, outside, rim, and inside, so you can describe the wall and opening together.
+
+
+
+```ts
+import { polygon } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  // Here Section X means radius and Section Y becomes the final Z height.
+  // Walk the filled wall counterclockwise, omitting a repeated closing point.
+  const wall = polygon([
+    [0, 0],
+    [16, 0],
+    [16, 4],
+    [12, 4],
+    [10, 28],
+    [7, 28],
+    [9, 4],
+    [0, 4],
+  ]);
+  // A full revolution creates the floor, tapered wall, and open top together.
+  return [part("model", wall.revolve())];
+});
+```
+
+One radial wall profile revolved around +Z creates the floor and tapered cup wall.
+
+
+
+[`polygon`](../reference/model/polygon.md) fills the ordered contour.
+[`Section.revolve`](../reference/model/Section.md#revolve) defaults to a complete `360°` turn. Set
+`degrees: 270` for a capped partial turn that exposes the cross section. Keep the closed
+profile free of self-intersections and never repeat its first point at the end.
+
+For an open side outline, [`sampleSideProfile`](../reference/geometry/sampleSideProfile.md)
+returns physical `[radius, height]` points. [`closeToAxis`](../reference/geometry/closeToAxis.md)
+adds the horizontal bottom/top edges needed for a solid body. Fill the result with `polygon`,
+then revolve it. Hollow walls and mounting bores need their own closed material contour.
+
+## Treated boxes, frustums, and mirrored arrays
+
+
+
+```ts
+import { box, cylinder, gridPattern } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const housing = box({
+    size: [46, 30, 12],
+    treatment: { kind: "round", radius: 3 },
+  });
+  const taperedBore = cylinder({
+    // The centered cutter extends beyond both faces of the 12 mm housing.
+    height: 16,
+    // Tuples run from the bottom diameter to the top diameter along +Z.
+    diameter: [8, 6],
+    sizing: "face",
+    ends: { top: { kind: "chamfer", distance: 0.8 } },
+  });
+  // Pattern the already-positioned tool; X varies fastest through the array.
+  const perforations = gridPattern(taperedBore.translate([-13, -6, 0]), {
+    count: [3, 2],
+    spacing: [13, 12],
+  });
+  // Mirror the completed housing across the plane with normal +X.
+  return [part("model", housing.subtract(perforations).mirror([1, 0, 0]))];
+});
+```
+
+Six non-overlapping cutters share the same taper and rim treatment; the completed housing is mirrored.
+
+
+
+Paired cylinder radii or diameters are always `[bottom, top]` in +Z order. A zero endpoint makes a cone;
+chamfers under `ends.bottom` and `ends.top` may treat either nonzero end and follow the tapered side.
+Boxes and rectangles share `round`, `chamfer`, `smooth`, and explicit `profile` treatments. Boxes
+can select disjoint named edges or groups; rectangles can select each corner. `gridPattern` places
+the cutters on an XY grid, with X varying fastest.
+Zero rounding radius or zero chamfer/smooth setbacks disable that treatment, so an adjustable
+feature can remain in the options object when switched off.
+
+The bores use `diameter: [8, 6]` and `13 × 12 mm` spacing to leave material between them. Check
+the widest cutter diameter and the outer wall when changing either value. In this example the
+tool's top chamfer lies above the housing; it shapes the cutter end, not the finished hole's rim.
+Use an explicitly shaped cutting profile if the finished mouth needs a countersink.
+
+## Finish a profile with a hole
+
+
+
+```ts
+import { circle, rectangle } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+const profile = rectangle({ size: [36, 24] })
+  .subtract(rectangle({ size: [8, 8] }).translate([18, 0]))
+  .subtract(circle({ diameter: 10 }));
+
+const plate = profile.extrude({
+  height: 6,
+  ends: {
+    top: { kind: "round", radius: 1.5 },
+    bottom: { kind: "chamfer", distance: 0.5 },
+  },
+});
+
+export default generate(({ part }) => part("finished-plate", plate));
+```
+
+One treatment finishes every material boundary at each end, including the notch and the hole.
+
+
+
+Form the complete filled profile first, then apply `ends.top` and `ends.bottom` during extrusion.
+The same treatment follows the outer outline, concave notch, and hole. Removing material at the
+top contracts the outside and opens the hole mouth; the plan-view corners remain mitered.
+Choose amounts that leave every boundary distinct and a positive straight wall interval.
+
+Finishing options share `round` (radius), `chamfer` (setbacks), `smooth` (cubic setbacks), and exact
+`profile` points:
+
+- Boxes select disjoint named edges or groups; rectangles select individual corners.
+- Cylinder/frustum and straight extrusion rims use independent `ends.bottom` and `ends.top`.
+- Straight extrusions admit concave outlines, holes, and disconnected material components when
+  every source boundary survives the treatment without contact, collapse, or topology changes.
+  One treatment applies to every material boundary at that end; inward material trimming expands
+  hole mouths. Enabled treatments exclude twist, top scaling, and exact divisions.
+- Zero radius, zero chamfer/smooth distance, or an all-zero distance pair leaves a feature untreated.
+  Other setback pairs require two positive values; negative and nonfinite amounts reject.
+- Disabled extrusion end treatments retain ordinary support, including holes and twist.
+
+For a local connection between completed solids, use [solid joins](solid-joins.md).