@metamesh/modeling 0.12.0 → 0.14.0

package/dist/docs/guides/fundamentals.md

@@ -0,0 +1,137 @@
+# Modeling fundamentals
+
+Understand watertight solids, coordinates, transforms, Boolean operations, and geometry ownership in Studio code Projects.
+
+[Manifold](https://manifoldcad.org/docs/jsapi/) is the solid-modeling kernel behind MetaMesh. Its
+core idea is a **manifold** mesh: an oriented, watertight boundary in which every edge belongs to a
+valid solid. That invariant makes Boolean operations and manufacturing output more dependable than
+working with an arbitrary triangle soup.
+
+Studio code Projects use Manifold through the curated `@metamesh/modeling` API. The public
+contract combines constructors and collection functions with fluent, opaque `Section` and `Solid`
+recipes. The engine owns the underlying kernel values.
+
+## Coordinates and units
+
+MetaMesh uses a right-handed coordinate system with **+Z up**. Model dimensions are millimetres.
+Place a part intentionally around the origin, then use transforms or anchors to relate it to other
+parts.
+
+Transform methods preserve the input and return immutable geometry recipes, so you can name
+meaningful stages and reuse a source shape without tracking hidden state.
+
+## Build solids compositionally
+
+Start with primitives, position them, and subtract a cutter that extends beyond both body faces:
+
+
+
+```ts
+import { box, cylinder } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const plate = box({ size: [80, 50, 4] });
+  // Primitives are centered by default, so both faces get 2 mm of overtravel.
+  // Overtravel is for robust subtraction; it does not enlarge the hole diameter.
+  const hole = cylinder({ height: 8, radius: 3 });
+  return [part("model", plate.subtract([hole]))];
+});
+```
+
+The cylinder clears both faces of the plate, leaving a through-hole without coincident cutter ends.
+
+
+
+The plate is centered about the origin. Its `4 mm` thickness occupies `Z = −2…2 mm`; the cutter
+occupies `Z = −4…4 mm`. That overtravel makes the subtraction deliberate while the hole radius
+stays `3 mm`. Derive cutter placement from the same datum as the body when changing dimensions.
+
+Prefer a small number of named intermediate solids. If many repeated cutters are independent, build
+or arrange them first and perform one meaningful subtraction where the API allows it. Excessive
+high-resolution Boolean steps cost time and obscure design intent.
+
+The `union` and `intersect` functions and `shape.subtract(cutters)` also combine filled Sections
+in XY. Choose one dimension for every operand in a call. Keep a Section native through its Boolean
+and offset steps, then chain `.extrude({ height })` or `.revolve(options)` to make a Solid.
+Transforms apply in written order about the origin: translating then rotating also rotates the
+translated position. Place finished parts through `part` options when their geometry can be reused.
+
+## Choose the Boolean by the material you want
+
+These three parts use the same overlapping block and cylindrical tool. Only the operation changes;
+the final translations separate the results for comparison.
+
+
+
+```ts
+import { box, cylinder, intersect, union } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const block = box({ size: [24, 24, 8] });
+  const tool = cylinder({ diameter: 20, height: 12 }).translate([10, 0, 0]);
+  // Reuse the same overlapping operands to compare the three operations.
+  // Place finished parts separately so display spacing can reuse their geometry.
+  return [
+    part("union", { geometry: union([block, tool]), color: "#60a5fa" }),
+    part("difference", {
+      geometry: block.subtract([tool]),
+      position: [42, 0, 0],
+      color: "#f59e0b",
+    }),
+    part("intersection", {
+      geometry: intersect([block, tool]),
+      position: [84, 0, 0],
+      color: "#34d399",
+    }),
+  ];
+});
+```
+
+Left: all material from union. Center: block material outside the tool. Right: material shared by both operands.
+
+
+
+| Operation                                                | Material retained                     | Common use                                               |
+| -------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------- |
+| [`union`](../reference/model/union.md)                   | Inside any operand                    | Join an overlapping boss or rib to a body                |
+| [`shape.subtract`](../reference/model/Solid.md#subtract) | Inside the base, outside every cutter | Cut holes, pockets, and clearance envelopes              |
+| [`intersect`](../reference/model/intersect.md)           | Inside every operand                  | Trim a feature to an envelope or isolate shared material |
+
+Use intentional overlap for joined features and overtravel for through-cutters. A face or point
+that only touches another feature is not a reliable connection for a manufacturing part. Inspect
+the result when thin walls, tangencies, or disconnected components are possible.
+
+## Valid solid does not mean manufacturable part
+
+The kernel can enforce solid topology, but it does not know your printer, material, load case,
+tolerance stack, minimum wall, overhang strategy, or fit target. Encode supported input limits and
+cross-field errors in the Project, then verify the exported file in its downstream tool.
+
+Likewise, an empty or zero-volume result is invalid model output, but a non-empty result is not an
+engineering certification.
+
+## Geometry ownership
+
+Geometry values allocate resources outside ordinary JavaScript objects. Studio's evaluator owns
+those resources for each run and cleans them up deterministically. Authored code should never
+initialize the kernel or manually delete a `Section` or `Solid`.
+
+Use `inspectSection()` or `inspectSolid()` when you need supported measurements such as bounds,
+area, or volume. A Section's `parts` count describes disconnected filled components; a Solid's
+`parts` count describes connected surface shells, including inward cavity shells. Neither counts
+the named output parts you declare with `part(...)`. Return one declaration or an array of them
+to hand the final result back to Studio for preview and export.
+
+
+
+**Use the MetaMesh reference for authored code**
+
+The upstream Manifold documentation is useful background on the underlying mathematics. Exact
+  code-Project symbols and guarantees come from the [Geometry API reference](../reference/model.md).
+
+
+
+- [Try geometry recipes](recipes.md)
+- [Read the Project contract](generation.md)

package/dist/docs/guides/generation.md

@@ -0,0 +1,223 @@
+# Code Project contract
+
+Understand the supported source, computed values, parts, resource ownership, recovery, and visible-model export behavior.
+
+An authored Project has one control definition and one TypeScript entry file. Studio supplies the
+compiler, prepared services, modeling engine, persistence and 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
+`generate` helper from `@metamesh/project`. These approved modules and declarations work offline.
+Source cannot install packages, fetch modules or initialize another kernel.
+
+## Start with generate
+
+Default-export one synchronous program:
+
+
+
+```ts
+import { box } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ params: parameters, part }) => {
+  return part("model", box({ size: [parameters.width, parameters.depth, parameters.height] }));
+});
+```
+
+
+
+The helper infers `params` from **Model controls**. Values are ordinary readonly numbers,
+strings and structured controls; there is no global parameter type to remember. Import
+`type Parameters` from `@metamesh/project` when a separate helper needs that explicit type.
+
+The outer callback runs for each edit. Return a single `part(...)` or a readonly array of parts;
+`computed` is optional.
+Export only the default program; keep helpers local to `model.ts`. Definitions and presets remain
+serializable metadata. There are no separate preparation/build exports.
+
+## Assertions and warnings
+
+Use `assert(condition, message, { parameterId? })` for a constraint. The first false condition
+stops that revision and identifies the control to fix. `warn(message, { parameterId? })` allows
+generation to continue:
+
+
+
+```ts
+assert(
+    !params.addHole || params.holeDiameter < Math.min(params.width, params.depth),
+    "Hole diameter must be smaller than the body width and depth.",
+    { parameterId: "holeDiameter" }
+  );
+```
+
+
+
+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.
+
+## Reuse unchanged work
+
+
+
+**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.
+
+
+
+`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:
+
+
+
+```ts
+const body = computed("body", () => {
+    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.
+
+An earlier read such as `const { height } = params` is an ordinary snapshot. Capturing it in a
+computation does not track that parameter and can reuse stale geometry. Prefer moving the read inside. When a changing value
+must be prepared outside, such as a loop item, list it in the optional third argument:
+
+
+
+```ts
+const { height } = params;
+  const capturedBody = computed("captured-body", () => box({ size: [params.width, 10, height] }), [
+    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.
+
+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.
+
+Dependency entries compare with `Object.is`; object and array contents are not deeply compared.
+Use immutable parameter values, computed results, or scalar inputs. Other objects must be deeply
+frozen. Fresh object/array entries prevent cache reuse, so create temporary options inside the
+callback instead. Studio warns about obvious fresh dependencies without probing generation.
+
+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.
+
+Calculations are synchronous and pure. Do not mutate cached values, read clocks or randomness,
+perform effects, or return promises/functions. Cache eviction and a worker restart preserve the
+same physical result. Keep expensive pure layouts or grids in their own computation rather than
+caching every small arithmetic expression.
+
+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
+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`.
+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.
+Call `services.text.layout()` synchronously, check its metrics, then pass the layout to
+`textSection(layout)`. Generation itself does no networking:
+
+
+
+```ts
+import { textSection } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ params, services, part }) => {
+  // The host has loaded the exact selected font before generation.
+  const layout = services.text.layout("MetaMesh", {
+    fontSize: 8,
+    font: params.font,
+    letterSpacing: 0.15,
+  });
+  // textSection preserves counters, such as the enclosed hole in the letter a.
+  return [part("label", textSection(layout).extrude({ height: 1.2 }))];
+});
+```
+
+
+
+## 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:
+
+
+
+```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,
+  ]);
+  return [
+    part("base", { geometry: base, color: "#3b82f6" }),
+    part("lid", { geometry: lid, color: "#f59e0b" }),
+  ];
+});
+```
+
+
+
+Lengths are millimetres, rotation is degrees, coordinates are right-handed with **+Z up**.
+Rotation applies about fixed X, then Y, then Z axes before translation. 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.
+Try **New project → Orbit sculpture** for a small colored assembly with an adjustable ring tilt.
+
+Part IDs are unique lowercase hyphenated names of at most 64 characters. Studio permits 512 parts,
+one million aggregate vertices, two million triangles and 96 MiB of unique output backing storage.
+The engine enforces finite, closed, oriented, reconstructable manufacturing geometry and current
+instance limits, including cache hits. Empty output is invalid.
+
+## Ownership and recovery
+
+Solids and Sections describe immutable deferred recipes. Ordinary recipes are reusable across
+sessions regardless of where constructed; unspecified resolution settings inherit the evaluating
+host's defaults. Observations such as `inspectSolid` realize required geometry synchronously and
+return copied facts. `components()` selections, and recipes using them, can only be evaluated in
+the originating session because their identity depends on evaluated topology. The host owns
+native allocations and cleanup on success and failure. Nested or asynchronous execution rejects.
+Apply local resolution explicitly to each affected constructor or Section operation.
+
+Source/control-definition changes invalidate 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.
+
+## Export the visible snapshot
+
+**Export** captures the visible revision and appearance for 3MF, STL or GLB. An invalid draft leaves
+its last valid preview exportable. Exports never rerun the generator; later edits cannot alter a
+captured export. Check workspace status when you need the latest edit, then inspect the downloaded
+file in its downstream tool. [Exporting models](https://metamesh.studio/docs/use/export-3mf) explains format capabilities.
+
+- [Design the controls](https://metamesh.studio/docs/develop/parameters-and-validation)
+- [Browse the modeling API](../reference/model.md)

package/dist/docs/guides/hosting.md

@@ -0,0 +1,91 @@
+# Run Modeling in your application
+
+Initialize the engine in Node or a browser Worker, build a model, and export its completed snapshot.
+
+Install the public package in a Node application or browser Worker project:
+
+```bash
+pnpm add @metamesh/modeling
+```
+
+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.
+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";
+
+export async function makePlate3mf(): Promise<ArrayBuffer> {
+  const engine = await createModelEngine();
+  const session = engine.createSession(
+    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" })];
+    })
+  );
+  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();
+  }
+}
+```
+
+
+
+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.
+
+## Keep execution synchronous
+
+Acquire assets before generation. Imported modeling functions run inside its synchronous callback;
+computations and observations cannot cross an async boundary. Sessions cannot execute nested runs
+in one realm. Services are explicit synchronous capabilities supplied at session creation.
+
+A session owns optional computed caches and deferred Solid/Section recipes. It may retain evaluated
+computed shapes privately for later cuts or Booleans; temporary native allocations are cleaned after
+each run. Separate expensive base geometry from finishing operations to reuse it. A returned snapshot
+owns copied manufacturing buffers until `snapshot.dispose()`; `session.dispose()` releases caches
+while retained snapshots remain usable. Keep captured output for rendering/export and release it
+when its consumer is done.
+
+## Load WASM in a browser Worker
+
+The package includes its matching JS/WASM kernel. Node and unbundled browser modules resolve the
+installed WASM asset automatically. A browser bundler must retain or emit that relative asset;
+[`modelingWasmUrl`](../reference/engine/modelingWasmUrl.md) can supply the emitted URL through
+`createModelEngine({ locateFile })`.
+
+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 geometry never crosses Workers or runs.
+
+## 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
+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
+[Modeling guides](https://metamesh.studio/docs/modeling) to choose geometry operations.