@metamesh/modeling 0.19.0 → 0.20.0

package/dist/docs/guides/transforms-and-placement.md

@@ -9,6 +9,50 @@ Run the examples in a [Studio code Project](https://metamesh.studio/docs/develop
 typed controls and prepared services. For a local model, follow the
 [standalone workflow](standalone-model.md) and use its host entry point.
 
+## Primitive booleans and repeated placement
+
+
+
+```ts
+import { box, cylinder, radialPattern, union } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const hub = cylinder({ height: 12, radius: 14 });
+  const arm = box({ size: [30, 6, 6] });
+  // Translate first, then rotate the whole arm about the world origin.
+  // Its inner end overlaps the hub so union creates one connected part.
+  const arms = radialPattern(arm.translate([18, 0, 0]).rotate([0, 0, 30]), {
+    count: 6,
+    axis: [0, 0, 1],
+    angle: 60,
+  });
+  // Both shapes are Z-centered; extra cutter height clears both hub faces.
+  const bore = cylinder({ height: 16, radius: 4 });
+  // Combine the repeated features once, then cut the common bore.
+  return part("model", union([hub, ...arms]).subtract(bore));
+});
+```
+
+Position and rotate one arm, repeat it about +Z, union the overlaps, then cut a common bore.
+
+
+
+
+
+**Read a transform chain from left to right**
+
+`arm.translate(...).rotate(...)` moves the arm, then rotates its new position about the origin.
+  Reverse the calls to rotate locally before moving it.
+
+
+
+Keep a deliberate overlap between each arm and the hub so the result is one connected solid.
+
+Exact signatures: [`box`](../reference/model/box.md),
+[`cylinder`](../reference/model/cylinder.md), and
+[`radialPattern`](../reference/model/radialPattern.md).
+
 ## Reuse a transform across shapes and coordinates
 
 Use [`transform2`](../reference/geometry/transform2.md) and
@@ -19,7 +63,7 @@ followed by a translation rotates around the origin, then moves the result:
 
 
 ```ts
-import { transform3, vector3 } from "@metamesh/modeling";
+import { transform3, vector3 } from "@metamesh/modeling/geometry";
 
 // Calls apply in written order: rotate, then translate.
 const placement = transform3().rotate([0, 0, 90]).translate([20, 0, 5]);
@@ -31,12 +75,12 @@ export const placedDirection = placement.applyDirection([10, 0, 0]); // approxim
 
 Pass a transform directly to `solid.transform(placement)`, `section.transform(placement)` and
 matching path helpers. Finished parts accept rigid transforms through `part(id, { geometry, transform })`;
-pattern and attachment matrices work directly. Part placement rejects scale, shear and reflection.
+pattern and attachment transforms work directly. Part placement rejects scale, shear and reflection.
 `toData()` supplies a canonical matrix when another system needs it.
 Construct the placement once and reuse it across point collections.
 
 `current.andThen(next)` applies `current` first and `next` second, accepting another chain or a
-same-dimensional matrix. `inverse()` returns the reverse placement. Each operation returns a new
+same-dimensional matrix; 3D composition also accepts a `Frame3`. `inverse()` returns the reverse placement. Each operation returns a new
 chain, so you can derive different placements from a shared starting point.
 
 Use `rotate(degrees, { pivot })` or `scale(factors, { pivot })` to work around a world-space pivot after
@@ -58,20 +102,21 @@ See the [2D placement recipe](transforms-and-placement.md#reuse-a-2d-placement).
 ### Transform composition order
 
 For low-level matrix interoperability, the factories accept existing canonical matrices. Use
-`transform3(frameTransform3(frame))` for an orthonormal frame. The raw constructors and
-`composeTransform3(after, before)` remain available; composition applies `before` first:
+`frame3({ origin, xAxis, yAxis, zAxis })` for an immutable coordinate frame and pass it directly
+where a 3D placement is accepted. `transform3(frame)` adds affine methods when needed. The raw matrix constructors and
+[`multiplyTransform3(after, before)`](../reference/math/multiplyTransform3.md) live in `/geometry/math`; composition applies `before` first:
 
 
 
 ```ts
-import { transform3 } from "@metamesh/modeling";
-import { applyTransformPoint3, composeTransform3 } from "@metamesh/modeling/geometry";
+import { transform3 } from "@metamesh/modeling/geometry";
+import { applyTransformPoint3, multiplyTransform3 } from "@metamesh/modeling/geometry/math";
 
 const current = transform3().rotate([0, 0, 90]);
 const next = transform3().translate([20, 0, 5]);
 export const chainedPoint = current.andThen(next).applyPoint([10, 0, 0]);
 export const composedPoint = applyTransformPoint3(
-  composeTransform3(next.toData(), current.toData()),
+  multiplyTransform3(next.toData(), current.toData()),
   [10, 0, 0]
 ); // Both results are approximately [20, 10, 5].
 export const reversedPoint = next.andThen(current).applyPoint([10, 0, 0]);
@@ -80,6 +125,56 @@ export const reversedPoint = next.andThen(current).applyPoint([10, 0, 0]);
 
 
 
+## Named anchors and custom frames
+
+
+
+```ts
+import { box, cylinder } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const base = box({ size: [40, 24, 6], center: false });
+  // Named anchors follow dimensions: no duplicated half-height calculation.
+  // Mating bottom to top opposes the two outward normals automatically.
+  const pin = cylinder({ diameter: 8, height: 12 }).attach("bottom", base.anchor("top"), {
+    gap: 0.2,
+  });
+  // Keep the gap and the two physical pieces instead of unioning the assembly.
+  return [part("base", { geometry: base }), part("pin", { geometry: pin })];
+});
+```
+
+The pin's bottom mates to the base's top with a 0.2 mm gap. They remain two named parts.
+
+
+
+Ordinary primitives know their named anchors, so `base.anchor("top")` follows the box's dimensions
+and placement. `pin.attach("bottom", base.anchor("top"))` mates opposed directions. Transforms and
+patterns carry those frames with the shape, with outward normals preserved under nonuniform scale
+and reflection. The axis names are `left/right` (−X/+X), `back/front` (−Y/+Y) and `bottom/top` (−Z/+Z).
+
+Use `shape.withAnchors({ mount: anchor3({ position, direction, up }) })` to define a custom datum
+without changing the original shape. Existing names remain unless replaced; definitions are copied
+and immutable.
+Boolean and other constructed shapes need explicit definitions because their surfaces may change.
+Anchor names use lowercase kebab-case, with at most 64 characters and 128 definitions per shape.
+Look up anchors during active synchronous generation; the lookup evaluates the required recipe.
+Returned frames are plain data.
+
+Primitive anchors describe nominal construction dimensions. Finishing and curve sampling do not
+move them. Tube and torus axial datums may lie over an opening; a cone has no cap anchor at its apex.
+Regular polygons and stars expose only `center`. Custom `Anchor3` frames, including pure
+`boxAnchor3` and `cylinderAnchor3` helpers, work wherever a source or target frame is required.
+
+Primitive `attachment` uses the same source/target anchor, `alignment`, `gap`, and `spin`
+options as `attach`, including a named `source`. It applies after local construction; Section
+attachment must preserve the XY plane.
+
+The `gap` here separates the two pieces along the target normal; it is a placement distance, not
+a radial fit clearance. Keep separate named parts for an assembly. For one fused part, remove the
+gap, add a small intended overlap, and [`union`](../reference/model/union.md) the solids.
+
 ## Calculate with vectors
 
 Use [`vector2`](../reference/geometry/vector2.md) and [`vector3`](../reference/geometry/vector3.md)
@@ -126,8 +221,7 @@ same coordinate frame, including touching boundaries. It doesn't establish a man
 
 
 ```ts
-import { bounds3 } from "@metamesh/modeling";
-import { fitBounds, layoutRow, rectangleContour } from "@metamesh/modeling/geometry";
+import { bounds3, fitBounds, layoutRow, rectangleContour } from "@metamesh/modeling/geometry";
 import * as mesh from "@metamesh/modeling/geometry/mesh";
 
 export const envelope = bounds3({ min: [-10, -5, 0], max: [10, 5, 8] });
@@ -140,9 +234,9 @@ export const measured = bounds3(mesh.bounds(triangleMesh));
 export const fits = envelope.containsBounds(measured); // true
 export const data = measured.toData(); // Frozen { min, max } record for interchange.
 
-// Collection and placement algorithms accept bounds values directly.
-export const fitting = fitBounds(measured, envelope, { maxScale: 1 });
-export const positions = layoutRow([measured, envelope], { gap: 2 });
+// Pass plain bounds data to collection and placement algorithms.
+export const fitting = fitBounds(measured.toData(), envelope.toData(), { maxScale: 1 });
+export const positions = layoutRow([measured.toData(), envelope.toData()], { gap: 2 });
 ```
 
 
@@ -151,53 +245,18 @@ Factories snapshot finite, ordered coordinates with finite extents; zero extents
 Alternatively construct from nonnegative dimensions with `bounds2({ size: [30, 18] })` or
 `bounds3({ size: [30, 18, 8], center: false })`. Size construction centers on the origin by default;
 size and min/max construction are mutually exclusive.
-`min` and `max` are frozen tuples, and `toData()` returns the value's stable frozen plain record.
+`min` and `max` are fluent vectors, just like `size()` and `center()`. Use `toData()` for the
+value's stable frozen min/max record with coordinate tuples.
 Path `bounds()` queries return matching fluent bounds, or `undefined` for an empty path.
 Mesh and region measurements, inspection results, and engine snapshots retain plain
 `Bounds2Data` or `Bounds3Data`; wrap a measurement when you need fluent queries.
 
 Use [`fitBounds`](../reference/geometry/fitBounds.md) to calculate a placement and
 [`layoutRow`](../reference/geometry/layoutRow.md) to arrange a collection. These standalone
-algorithms accept values or plain records. Supply bounds after any intended rotation; an
+algorithms take plain bounds data; use `bounds.toData()` when you have a fluent value. Supply
+bounds after any intended rotation; an
 axis-aligned box alone doesn't describe the underlying shape.
 
-## Primitive booleans and repeated placement
-
-
-
-```ts
-import { box, cylinder, radialPattern, union } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
-
-export default generate(({ part }) => {
-  const hub = cylinder({ height: 12, radius: 14 });
-  const arm = box({ size: [30, 6, 6] });
-  // Translate first, then rotate the whole arm about the world origin.
-  // Its inner end overlaps the hub so union creates one connected part.
-  const arms = radialPattern(arm.translate([18, 0, 0]).rotate([0, 0, 30]), {
-    count: 6,
-    axis: [0, 0, 1],
-    angle: 60,
-  });
-  // Both shapes are Z-centered; extra cutter height clears both hub faces.
-  const bore = cylinder({ height: 16, radius: 4 });
-  // Combine the repeated features once, then cut the common bore.
-  return [part("model", union([hub, ...arms]).subtract(bore))];
-});
-```
-
-Position and rotate one arm, repeat it about +Z, union the overlaps, then cut a common bore.
-
-
-
-Transforms apply in written order: `arm.translate(...).rotate(...)` moves the arm first, then rotates
-its position about the origin. Reversing those calls rotates the arm locally before moving it.
-Keep a deliberate overlap between each arm and the hub so the result is one connected solid.
-
-Exact signatures: [`box`](../reference/model/box.md),
-[`cylinder`](../reference/model/cylinder.md), and
-[`radialPattern`](../reference/model/radialPattern.md).
-
 ## Reuse a 2D placement
 
 Build one [`transform2`](../reference/geometry/transform2.md) chain when the same placement applies
@@ -206,7 +265,8 @@ to a Section and its plain point data. This placement rotates around `[2, 1]`, t
 
 
 ```ts
-import { path2, pathPattern, polygon, rectangle, transform2, union } from "@metamesh/modeling";
+import { pathPattern, polygon, rectangle, union } from "@metamesh/modeling";
+import { path2, transform2 } from "@metamesh/modeling/geometry";
 
 const planarPlacement = transform2()
   .rotate(90, { pivot: [2, 1] })
@@ -261,53 +321,3 @@ export const patternedTabs = union(tabs).extrude({ height: 3 });
 
 Linear Section patterns use XY directions. Radial Section patterns rotate about an optional XY
 `pivot` using the implicit +Z axis; spatial Solid patterns retain their explicit rotation axis.
-
-## Named anchors and custom frames
-
-
-
-```ts
-import { box, cylinder } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
-
-export default generate(({ part }) => {
-  const base = box({ size: [40, 24, 6], center: false });
-  // Named anchors follow dimensions: no duplicated half-height calculation.
-  // Mating bottom to top opposes the two outward normals automatically.
-  const pin = cylinder({ diameter: 8, height: 12 }).attach("bottom", base.anchor("top"), {
-    gap: 0.2,
-  });
-  // Keep the gap and the two physical pieces instead of unioning the assembly.
-  return [part("base", { geometry: base }), part("pin", { geometry: pin })];
-});
-```
-
-The pin's bottom mates to the base's top with a 0.2 mm gap. They remain two named parts.
-
-
-
-Ordinary primitives know their named anchors, so `base.anchor("top")` follows the box's dimensions
-and placement. `pin.attach("bottom", base.anchor("top"))` mates opposed directions. Transforms and
-patterns carry those frames with the shape, with outward normals preserved under nonuniform scale
-and reflection. The axis names are `left/right` (−X/+X), `back/front` (−Y/+Y) and `bottom/top` (−Z/+Z).
-
-Use `shape.withAnchors({ mount: anchor3(position, direction, up) })` to define a custom datum
-without changing the original shape. Existing names remain unless replaced; definitions are copied
-and immutable.
-Boolean and other constructed shapes need explicit definitions because their surfaces may change.
-Anchor names use lowercase kebab-case, with at most 64 characters and 128 definitions per shape.
-Look up anchors during active synchronous generation; the lookup evaluates the required recipe.
-Returned frames are plain data.
-
-Primitive anchors describe nominal construction dimensions. Finishing and curve sampling do not
-move them. Tube and torus axial datums may lie over an opening; a cone has no cap anchor at its apex.
-Regular polygons and stars expose only `center`. Custom `Anchor3` frames, including pure
-`boxAnchor3` and `cylinderAnchor3` helpers, work wherever a source or target frame is required.
-
-Primitive `attachment` uses the same source/target anchor, `alignment`, `gap`, and `spin`
-options as `attach`, including a named `source`. It applies after local construction; Section
-attachment must preserve the XY plane.
-
-The `gap` here separates the two pieces along the target normal; it is a placement distance, not
-a radial fit clearance. Keep separate named parts for an assembly. For one fused part, remove the
-gap, add a small intended overlap, and [`union`](../reference/model/union.md) the solids.

package/dist/docs/guides/workers.md

@@ -0,0 +1,166 @@
+# Run models in a browser Worker
+
+Resolve the WASM asset, transfer completed geometry, and optionally reuse delivered resources across edits.
+
+Run the engine in a Worker when your browser application needs to keep modeling work off its UI
+thread. Follow [host setup](hosting.md) inside the Worker; your application owns its
+creation, messages, cancellation, and replacement.
+
+## Resolve the WASM asset
+
+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 })`.
+
+## Build once in a Worker
+
+This example makes a plate in a module Worker and returns owned geometry buffers. Save the Worker
+source as `model-worker.ts`; the client below resolves that sibling file through your bundler.
+
+
+
+```ts
+import { box, generate } from "@metamesh/modeling";
+import { createModelEngine, modelingWasmUrl } from "@metamesh/modeling/engine";
+
+const engine = createModelEngine({ wasmUrl: modelingWasmUrl });
+const plate = generate<{ readonly width: number }>(({ params, part }) =>
+  part("plate", box({ size: [params.width, 20, 6] }))
+);
+
+globalThis.addEventListener("message", async (event: MessageEvent<{ readonly width: number }>) => {
+  try {
+    const model = (await engine).run(plate, event.data);
+    const parts = model.parts.map((part) => ({
+      id: part.id,
+      transform: part.transform,
+      geometry: {
+        positions: part.geometry.positions.copy(),
+        indices: part.geometry.indices.copy(),
+      },
+    }));
+    const transfer = parts.flatMap(({ geometry }) => [
+      geometry.positions.buffer,
+      geometry.indices.buffer,
+    ]);
+    globalThis.postMessage({ ok: true, parts }, { transfer });
+  } catch (error) {
+    globalThis.postMessage({
+      ok: false,
+      message: error instanceof Error ? error.message : "Generation failed.",
+    });
+  }
+});
+```
+
+
+
+Call `buildPlateInWorker(30)` from your application. This one-shot client waits for the result and
+terminates its Worker in `finally`:
+
+
+
+```ts
+import type { ExportPart } from "@metamesh/modeling/export";
+
+type ModelWorkerReply =
+  | { readonly ok: true; readonly parts: readonly ExportPart[] }
+  | { readonly ok: false; readonly message: string };
+
+export async function buildPlateInWorker(width: number): Promise<readonly ExportPart[]> {
+  const worker = new Worker(new URL("./model-worker.ts", import.meta.url), { type: "module" });
+
+  try {
+    return await new Promise((resolve, reject) => {
+      worker.addEventListener(
+        "message",
+        (event: MessageEvent<ModelWorkerReply>) => {
+          if (event.data.ok) resolve(event.data.parts);
+          else reject(new Error(event.data.message));
+        },
+        { once: true }
+      );
+      worker.addEventListener("error", (event) => reject(new Error(event.message)), { once: true });
+      worker.postMessage({ width });
+    });
+  } finally {
+    worker.terminate();
+  }
+}
+```
+
+
+
+Pass the returned parts to your viewport or an [exporter](exporting.md). For an editor,
+keep the Worker and a model session alive across edits, identify each request, and ignore stale
+responses. Your application also owns deadlines and cancellation.
+
+## Transfer completed geometry
+
+
+
+**Transfer owned copies of buffers**
+
+Transferring a buffer detaches it from the sender. Copy completed data before transferring it;
+  keep native handles and cache backing storage inside their engine.
+
+
+
+## Use the optional delivery adapter
+
+For repeated delivery with shared resource references, install the optional SDK:
+
+```bash
+pnpm add @metamesh/generator-sdk
+```
+
+The `@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.
+This one-shot ownership demonstration uses `structuredClone` to exercise the same transfer as
+`worker.postMessage`; it does not create a Worker:
+
+
+
+```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";
+
+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.
+
+Continue with [exporting completed parts](exporting.md), or use the
+[Engine API reference](../reference/engine.md) for execution and snapshot contracts.