@metamesh/modeling 0.12.0 → 0.13.0

package/dist/docs/guides/generation.md

@@ -0,0 +1,221 @@
+# 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 deferred recipes owned by the session. Observations such as
+`inspectSolid` realize their required geometry synchronously and return copied facts. Native
+allocations belong only to the active transaction and are cleaned on success and failure. Authors
+do not dispose native handles or use them across sessions. 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,88 @@
+# 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" })];
+    })
+  );
+  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();
+    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.