@metamesh/modeling 0.18.0 → 0.20.0

package/dist/docs/guides/exporting.md

@@ -0,0 +1,88 @@
+# Export completed parts
+
+Serialize one completed result as 3MF, STL, or GLB, preserving its placement and reporting format limitations.
+
+Use `@metamesh/modeling/export` when your application has completed part geometry to save or deliver.
+Start with [a working host](hosting.md#build-and-export-a-plate) if you have not generated
+a result yet. For Studio's download interface, use [Export a model](https://metamesh.studio/docs/use/export-3mf).
+
+
+
+**Export works from the completed result**
+
+No running engine or renderer is needed. Serialize `model.parts`, including after its session
+  closes, without evaluating the source again.
+
+
+
+## Serialize completed parts
+
+Import `export3mf`, `exportStl`, or `exportGlb` from `@metamesh/modeling/export`. Every exporter accepts completed parts with local
+`geometry`, an optional placement transform, and optional display color and material identity.
+
+This helper accepts a completed engine result and requests solid-mesh validation before writing 3MF:
+
+
+
+```ts
+import type { ModelResult } from "@metamesh/modeling/engine";
+import { export3mf, type ExportedFile } from "@metamesh/modeling/export";
+
+export function exportAssembly(model: ModelResult): Promise<ExportedFile> {
+  return export3mf(model.parts, { name: "Assembly", meshValidation: "solid" });
+}
+```
+
+
+
+Call `await exportAssembly(model)` and save or download its returned `bytes`. Review `diagnostics`
+for expected format losses; invalid inputs and failed delivery reject.
+
+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.
+
+## Choose a format
+
+Inputs use millimetres and Z-up coordinates. Every writer preserves the supplied physical sampling.
+
+| Format  | Coordinates                     | What it preserves                                                                      |
+| ------- | ------------------------------- | -------------------------------------------------------------------------------------- |
+| **3MF** | Millimetres, Z-up               | Named manufacturing parts, placement, colors, and explicit material identities         |
+| **STL** | Placed triangles in millimetres | Triangle geometry; diagnostics report lost names, appearance, and material assignments |
+| **GLB** | Metres, Y-up                    | Named display parts, shared geometry, placement, colors, and crease-aware shading      |
+
+## Keep color and material identity separate
+
+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. Full slicer projects and device-specific
+configuration require a separate application adapter.
+
+
+
+**Portable materials describe intent**
+
+A material ID and display color travel with supported output. Your downstream application still
+  chooses printer profiles, filament slots, and device settings.
+
+
+
+## Set validation and output limits
+
+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.
+
+## Stream large output
+
+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.
+
+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/fonts.md

@@ -4,7 +4,7 @@ Prepare licensed font bytes and a reusable text layout before building a model o
 
 To add lettering outside Studio, load a font you're licensed to use and prepare it through the
 optional `@metamesh/modeling/text` entry point before synchronous generation. In Studio, use the
-[Font control recipe](recipes.md#text-from-a-font-parameter).
+[Font control recipe](svg-and-text.md#text-from-a-font-parameter).
 
 ## Install font support
 
@@ -27,7 +27,8 @@ another weight.
 
 
 ```ts
-import { prepareVectorFont, type VectorTextLayout } from "@metamesh/modeling/text";
+import { type VectorTextLayout } from "@metamesh/modeling/geometry";
+import { prepareVectorFont } from "@metamesh/modeling/text";
 
 export async function makeLabelLayout(fontBytes: Uint8Array): Promise<{
   readonly layout: VectorTextLayout;
@@ -50,12 +51,13 @@ measurements in millimetres, with Y pointing up, plus a separate `svg` string.
 
 Pass the `layout` to [`textSection`](../reference/model/textSection.md) inside generation, then
 extrude the filled section. Prepare layouts ahead of time, or supply a deterministic text service
-and cache layouts with `computed`.
+and cache layouts with `memo`.
 
 The same layout options support horizontal lines or one circular line through
 [`VectorTextArcBaseline`](../reference/text/VectorTextArcBaseline.md). The
-[text recipe](recipes.md#text-from-a-font-parameter) explains units, alignment,
+[text recipe](svg-and-text.md#text-from-a-font-parameter) explains units, alignment,
 metrics, and circular-text constraints.
 
 Use the [Font preparation reference](../reference/text.md) for font and layout options, or
-[Run Modeling in your application](hosting.md) for engine setup, export, and cleanup.
+[Run Modeling in your application](hosting.md) for execution and cleanup, and
+[Export completed parts](exporting.md) for file delivery.

package/dist/docs/guides/fundamentals.md

@@ -33,7 +33,7 @@ export default generate(({ part }) => {
   // 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))];
+  return part("model", plate.subtract(hole));
 });
 ```
 
@@ -65,7 +65,8 @@ the final translations separate the results for comparison.
 
 
 ```ts
-import { box, cylinder, transform3 } from "@metamesh/modeling";
+import { box, cylinder } from "@metamesh/modeling";
+import { transform3 } from "@metamesh/modeling/geometry";
 import { generate } from "@metamesh/project";
 
 export default generate(({ part }) => {
@@ -103,35 +104,22 @@ Use intentional overlap for joined features and overtravel for through-cutters.
 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 doesn't 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.
-
-Empty or zero-volume output is invalid; non-empty output still needs engineering checks.
-
-## Geometry ownership
-
-Studio creates and cleans up the native resources needed to evaluate your `Section` and `Solid`
-recipes. Don't initialize the kernel or manually delete shapes in `model.ts`.
-
-Use `shape.inspect()` for measurements such as bounds, area, volume, and
-`componentCount`. `shape.components()` returns disconnected material pieces, preserving holes and
-enclosed cavities. A sealed hollow box is one component; adding a loose ball inside its cavity
-makes two. Recombining the pieces preserves the original material.
 
-Snapshot `stats.partCount` counts named `part(...)` declarations; one part may contain several
-material components. Return one declaration or an array for Studio to preview and export.
 
+**A valid solid still needs engineering checks**
 
+Closed geometry does not establish fit, wall thickness, strength, or printability. Validate your
+  supported dimensions and check the result with your intended material and manufacturing process.
 
-**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 [Model API reference](../reference/model.md).
 
+## Let the host manage geometry
 
+Studio and standalone hosts evaluate the recipes and clean up native resources. Keep kernel
+initialization and manual deletion out of your model. Use
+[inspection](resolution-and-inspection.md#lifecycle-and-inspection) to check evaluated
+dimensions and components; use the [Model API reference](../reference/model.md) for exact symbols.
+The upstream Manifold documentation provides background on the underlying mathematics.
 
 - [Try geometry recipes](recipes.md)
 - [Read the Project contract](generation.md)

package/dist/docs/guides/generation.md

@@ -7,10 +7,13 @@ Studio compiles it, prepares services, runs the modeling engine, saves the Proje
 
 ## Source boundary
 
-Keep helpers in the single editable `model.ts` file. Import modeling operations from
-`@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.
+Keep helpers in the single editable `model.ts` file. Import shapes from `@metamesh/modeling` and
+the typed `generate` helper from `@metamesh/project`. The Geometry, Math, Mechanical, and Mesh
+modules in the [import map](concepts.md#import-by-the-work-you-are-doing) are
+also available.
+
+For font-selection metadata, import `isFontSelection` and `type FontSelection` from
+`@metamesh/generator-sdk/fonts`. These approved modules and declarations work offline.
 Source can't install packages, fetch modules, or initialize another kernel.
 
 ## Start with generate
@@ -23,8 +26,8 @@ Default-export one synchronous program:
 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] }));
+export default generate(({ params, part }) => {
+  return part("model", box({ size: [params.width, params.depth, params.height] }));
 });
 ```
 
@@ -32,12 +35,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
+Parameters and memo 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.
-You can add `computed` when you need it.
+You can add `memo` 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.
 
@@ -61,94 +64,106 @@ assert(
 
 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.
+Warnings belong in the outer callback; assertions can also run inside a memo helper when it
+evaluates. Pass the full generation context to a helper that needs `assert` or fixed services.
 
 ## Reuse unchanged work
 
 
 
-**Caching is optional**
+**Start without caching**
+
+Start with ordinary generation code. If parameter edits become slow, add `memo` around expensive
+  work that can stay unchanged across edits. Cheap arithmetic and part placement usually do not need
+  caching.
 
-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.
 
 
+`memo(fn, ...args)` calls a synchronous helper and returns its immutable result directly. Repeated
+calls with the same function and unchanged inputs can reuse that result. Define helpers at module
+scope so their identity stays stable between generations.
 
-`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:
+Pass the exact `params` object when a helper needs several parameters. MetaMesh tracks the fields
+read while the helper runs, including reads made by synchronous helpers it calls:
 
 
 
 ```ts
-const body = computed("body", () => {
-    const { width, height } = params;
-    return box({ size: [width, 10, height] });
-  });
+function buildTrackedBody(params: Readonly<Parameters>) {
+  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.
+You can also pass ordinary arguments, just as you would call the function normally. These are the
+function's inputs, not a separate dependency declaration:
+
+
+
+```ts
+function buildBody(width: number, height: number) {
+  return box({ size: [width, 10, height] });
+}
+```
+
+
 
-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:
+Inside `generate`, both forms return values ready for `part` or the next memo:
 
 
 
 ```ts
-const { height } = params;
-  const capturedBody = computed("captured-body", () => box({ size: [params.width, 10, height] }), [
-    height,
-  ]);
+const body = memo(buildTrackedBody, params);
+  const argumentBody = memo(buildBody, params.width, params.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.
+Both rebuild when width or height changes. Unrelated parameters can change without rebuilding.
+Compose stages by passing memo results directly: `memo(finishBody, body, params)`.
+In **New project → Cached panels**, changing **Gap** only moves the second panel; changing
+**Notch width** reuses the hole pattern for the finishing cut.
 
-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.
+A function defined inside `generate`, including an inline arrow, gets a new identity each run.
+It still computes correctly, but cannot reuse previous runs. Studio warns about common cases while
+Code is open; factories, dynamic aliases, and arbitrary JavaScript aren't always identifiable.
 
 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.
+compare finalized output with `cache: false` when it cannot compare a model's calculations.
 
-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.
-Studio warns about obvious fresh dependencies without running 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.
+Ordinary arguments use `Object.is`, without comparing object or array contents. Use immutable
+parameter values, memo results, or scalar inputs; other objects must be deeply frozen. Creating a
+fresh frozen object each generation still misses the cache. Create temporary options inside the
+helper, and pass its scalar inputs. A TypeScript `readonly` annotation doesn't freeze runtime data.
+An array is one argument; use `memo(fn, ...tuple)` to spread several arguments.
 
 Keep calculations synchronous and pure: do not mutate cached values, read clocks or randomness,
-perform effects, or return promises or functions. The physical result must remain the same after
+perform effects, or return promises or functions. Pass every changing input explicitly; a helper
+that reads changing module state can reuse stale output. Neither editor warnings nor runtime
+tracking can prove purity. The physical result must remain the same after
 cache eviction or a worker restart. Cache expensive layouts or grids; cheap arithmetic usually
 does not need its own computation.
 
-For cached numeric data, call [`immutableBuffer`](../reference/model/immutableBuffer.md) and use
+For cached numeric data, call [`immutableBuffer`](../reference/geometry/immutableBuffer.md) and use
 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
-[`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.
+[`mesh.immutable`](../reference/mesh/immutable.md); its value can pass directly to `part`.
+Raw typed arrays in memo results or arguments reject with guidance to use these helpers.
 
 ## Text services
 
-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:
+
+
+**Studio prepares the selected font for you**
+
+The exact font bytes are ready before `generate` runs. Lay out text synchronously through
+  `services.text.layout()`, check its metrics, and pass the layout to `textSection`.
+
+
 
 
 
@@ -164,7 +179,7 @@ export default generate(({ params, services, part }) => {
     letterSpacing: 0.15,
   });
   // textSection preserves counters, such as the enclosed hole in the letter a.
-  return [part("label", textSection(layout).extrude({ height: 1.2 }))];
+  return part("label", textSection(layout).extrude({ height: 1.2 }));
 });
 ```
 
@@ -174,19 +189,19 @@ export default generate(({ params, services, part }) => {
 
 Use `part("body", geometry)` for the simple form, or pass an object with `geometry`,
 `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:
+Geometry and placement accept values. 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] });
+export default generate(({ params, part }) => {
+  const base = box({ size: [params.width, params.depth, params.height] });
+  const lid = box({ size: [params.width, params.depth, 2] });
   return [
     part("base", { geometry: base, color: "#3b82f6" }),
     part("lid", {
       geometry: lid,
-      transform: transform3().translate([0, parameters.depth + 4, 0]),
+      transform: transform3().translate([0, params.depth + 4, 0]),
       color: "#f59e0b",
     }),
   ];
@@ -195,7 +210,7 @@ export default generate(({ params: parameters, part }) => {
 
 
 
-Use a `transform3()` value or a row-major 16-number matrix for translation and rotation;
+Use a plain `Frame3`, `transform3()` value, or 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**.