@metamesh/modeling 0.15.0 → 0.16.0

package/dist/docs/guides/fundamentals.md

@@ -1,15 +1,13 @@
 # Modeling fundamentals
 
-Understand watertight solids, coordinates, transforms, Boolean operations, and geometry ownership in Studio code Projects.
+Combine watertight solids with Booleans and transforms, and understand 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.
+Build parts by combining primitives, applying transforms, and removing material with cutters.
+MetaMesh uses [Manifold](https://manifoldcad.org/docs/jsapi/), a solid-modeling kernel that works
+with **manifold meshes**: closed, consistently oriented boundaries representing solid material.
 
-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.
+Studio code Projects use `@metamesh/modeling` to construct immutable `Section` and `Solid` recipes.
+The engine evaluates them and owns the underlying kernel values.
 
 ## Coordinates and units
 
@@ -47,9 +45,9 @@ The plate is centered about the origin. Its `4 mm` thickness occupies `Z = −2
 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.
+Name intermediate solids by their purpose. Arrange independent repeated cutters first, then
+subtract them together where possible. Many high-resolution Boolean steps increase generation
+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
@@ -109,30 +107,28 @@ The kernel can enforce solid topology, but it does not know your printer, materi
 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.
+Empty or zero-volume output is invalid; non-empty output still needs engineering checks.
 
 ## 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`.
+`Section` and `Solid` values are immutable recipes. Evaluating them creates native resources
+owned and cleaned up by Studio. Do not initialize the kernel or manually delete shapes in
+`model.ts`.
 
 Use `inspectSection()` or `inspectSolid()` for measurements such as bounds, area, volume, and
 `componentCount`. `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 the named output parts declared with `part(...)`. One output
-part may contain several material components. Return one declaration or an array of them to hand
-the result back to Studio for preview and export.
+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.
 
 
 
 **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).
+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).
 
 
 

package/dist/docs/guides/generation.md

@@ -1,6 +1,6 @@
 # Code Project contract
 
-Understand the supported source, computed values, parts, resource ownership, recovery, and visible-model export behavior.
+Understand Studio’s TypeScript source contract, computed caches, parts, resource ownership, and recovery.
 
 An authored Project has one control definition and one TypeScript entry file. Studio supplies the
 compiler, prepared services, modeling engine, persistence and preview.
@@ -29,9 +29,8 @@ export default generate(({ params: parameters, part }) => {
 
 
 
-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 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.
 
 The outer callback runs for each edit. Return a single `part(...)` or a readonly array of parts;
 `computed` is optional.
@@ -92,9 +91,10 @@ Call other computed readers inside the callback too: `computed("finished", () =>
 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:
+An earlier read such as `const { height } = params` captures a snapshot. Using it inside a
+computation does not 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:
 
 
 
@@ -114,19 +114,19 @@ The same capture rule applies to an eagerly read result such as `const value = o
 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.
+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.
 
-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.
+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
+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
 its `length`, `at(index)`, or `copy()` methods. Copy once before a dense sampling callback so its
@@ -185,7 +185,7 @@ export default generate(({ params: parameters, part }) => {
 
 
 
-Lengths are millimetres, rotation is degrees, coordinates are right-handed with **+Z up**.
+Lengths use millimetres and rotations use 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.
@@ -199,13 +199,14 @@ 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.
+Solids and Sections are immutable deferred recipes. Ordinary recipes can be reused across
+sessions; unspecified resolution settings inherit the evaluating host's defaults. Apply local
+resolution explicitly to each affected constructor or Section operation.
+
+Observations such as `inspectSolid` evaluate required geometry synchronously and return copied
+facts. `components()` selections and recipes using them can only be evaluated in their originating
+session because their identity depends on evaluated topology. The host cleans up native
+allocations on success and failure. Nested or asynchronous execution rejects.
 
 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.

package/dist/docs/guides/hosting.md

@@ -53,26 +53,31 @@ move engine initialization out of the function and reuse that engine and its mod
 
 ## Keep execution synchronous
 
-Acquire assets before generation. Ordinary immutable Solid/Section recipes, vectors, paths and
-transforms can be constructed without an engine and reused across sessions. Explicit resolution
-settings stay with a recipe; omitted settings inherit the evaluating host's defaults. Computed
-readers and geometry observations require active synchronous generation and 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 evaluation, optional computed caches and native resources. 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. Observed
-`components()` selections depend on evaluated topology and remain restricted to their originating
-session; ordinary recipes remain portable.
-
-A returned snapshot retains captured manufacturing buffers independently of its session. Accessing
-a part's `positions` or `indices`, including through its local `geometry` resource, returns a fresh
-owned copy on every read. Read each field once when processing its buffer. `session.dispose()`
-releases caches while captured snapshots remain usable. `snapshot.dispose()` releases its references
-and makes subsequent `parts`, `bounds` and `stats` access invalid; diagnostics, dependencies and parts
-already obtained remain usable. Disposing a snapshot does not affect another snapshot or an export
-already in progress. Release captured output when its consumer is done.
+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.
+
+Recipes and evaluated geometry have different lifetimes:
+
+- 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.
 
 ## Load WASM in a browser Worker
 

package/dist/docs/guides/recipes.md

@@ -1,10 +1,10 @@
 # Modeling recipes
 
-Adapt typechecked patterns for sections, SVG, text, extrusion, sweeps, heightfields, booleans, placement, anchors, and inspection.
+Build plates, cups, routed tubes, lofts, repeated features, SVG shapes, and lettering with complete modeling examples.
 
-Build a plate, route a section through space, join profiles, or place repeated features. Each
-illustrated recipe pairs its complete source with a render of that exact source. Open
-the interactive preview to orbit the result; copy the code into a Studio code Project to edit it.
+Choose a recipe, inspect its render, and copy the complete source into a Studio
+[code Project](https://metamesh.studio/docs/develop/code-projects). Each illustrated recipe renders that same source;
+open its interactive preview to orbit the result.
 
 | You want to make         | Start here                                                     | Main decision                                             |
 | ------------------------ | -------------------------------------------------------------- | --------------------------------------------------------- |
@@ -20,8 +20,8 @@ the interactive preview to orbit the result; copy the code into a Studio code Pr
 
 All dimensions in these recipes are millimetres. MetaMesh uses a right-handed coordinate system
 with +Z up, degrees for angular arguments including `rotate`, and non-duplicated contour seams.
-The examples default-export a synchronous `generate` program. Use ordinary assertions for constraints
-and optional `computed` values for expensive/shared dimensions, geometry or text layouts.
+The examples default-export a synchronous `generate` program. Use assertions for constraints
+and optional `computed` values to cache expensive shared calculations, geometry, or text layouts.
 [Define parameters and validation](https://metamesh.studio/docs/develop/parameters-and-validation) connects
 source values to controls.
 
@@ -47,9 +47,9 @@ Subtract the opening in 2D, offset the filled material, then extrude it into one
 
 
 
-`rectangle` and `circle` take object options and return filled Sections. `section.subtract(cutters)` and the `union` and `intersect` functions also support Solids,
-with same-dimensional operands in each call. `section.offset(distance)` preserves the filled
-topology. `section.extrude({ height })` preserves
+`rectangle` and `circle` take object options and return filled Sections. `section.subtract(cutters)`,
+`union`, and `intersect` also support Solids; every operand in a call must have the same dimension.
+`section.offset(distance)` offsets the filled material. `section.extrude({ height })` preserves
 holes and places the bottom at zero unless `center: true` is requested.
 
 Positive offset grows material on every boundary: this example grows the outside by `1.2 mm` and
@@ -59,8 +59,8 @@ offset the outside first and subtract the hole afterward. See
 
 ## SVG parameter and extrusion
 
-An SVG control is exposed to authored code as a string on the immutable `parameters` argument. Pass
-that string directly to `svgSection`; no DOM parsing or editor-specific JSON is needed.
+Pass an SVG control's string value from `params` directly to `svgSection`. This example aliases
+`params` as `parameters`:
 
 
 
@@ -76,10 +76,10 @@ export default generate(({ params: parameters, part }) => {
 
 
 
-The property name is the control ID shown in the model-controls editor. For example, use
-`parameters.logo` when the SVG control ID is `logo`.
+The property name matches the ID in **Model controls**: `profile6` in this example, or
+`parameters.logo` for a control with ID `logo`.
 
-The same function also accepts literal SVG documents. Here two nested paths produce one badge
+`svgSection` also accepts literal SVG documents. Here two nested subpaths make a badge
 with a rectangular opening:
 
 
@@ -286,7 +286,7 @@ export const placedBody = polygon({ outer: outline, holes: [] })
   .extrude({ height: 8 });
 
 // Paths accept the same placement. Matrices and tuples remain available for interchange.
-export const sectionMatrix = planarPlacement.toMatrix();
+export const sectionMatrix = planarPlacement.toData();
 export const placedContour = path2(outline, { closed: true }).transform(planarPlacement);
 ```
 
@@ -299,7 +299,7 @@ Fill the transformed closed path with `polygon(placedContour)` when you need mat
 A negative scale factor reflects the placement. Paths retain traversal order, including closed
 paths; filled Sections and serialized regions restore outer and hole winding. `andThen(next)`
 composes another placement in execution order;
-reuse the placement instead of building a chain inside each point iteration. `toMatrix()` is
+reuse the placement instead of building a chain inside each point iteration. `toData()` is
 available for matrix interchange.
 
 Section path patterns consume `Path2` values directly. Tangent orientation aligns the Section's
@@ -360,13 +360,16 @@ The asymmetric section makes its transported orientation visible as the path tur
 
 
 
-`section.sweep(path, options)` transports the filled shape along the path. Choose the starting profile-X direction with
-`orientation: { kind: "transport", initialNormal: [0, 1, 0] }`. Fixed normals, directed normal guides
-and discrete Frenet frames are explicit alternative policies; singular selected policies reject.
-`twist` adds total rotation, following physical path length by default; `twistBy: "stations"`
-uses the authored station schedule. `scale` accepts a positive uniform size, XY pair or one XY pair
-per normalized station. `closed: true` joins an implicitly closed path without repeated endpoints;
-orientation, scales and `seamProfileOffset` must describe a compatible closing seam.
+`section.sweep(path, options)` transports a filled shape along a path:
+
+- `orientation: { kind: "transport", initialNormal: [0, 1, 0] }` chooses the starting profile-X
+  direction. Fixed normals, directed normal guides, and discrete Frenet frames are alternatives;
+  singular selected policies reject.
+- `twist` adds total rotation by physical path length. Set `twistBy: "stations"` to use the authored
+  station schedule instead.
+- `scale` accepts a positive uniform size, an XY pair, or one XY pair per normalized station.
+- `closed: true` joins an implicitly closed path without repeated endpoints. Orientation, scales,
+  and `seamProfileOffset` must describe a compatible closing seam.
 
 Start with the open path above, inspect the first cap and the turns, then replace the rectangle
 with a [`circle`](../reference/model/circle.md) for a round rod. A sweep follows the supplied path
@@ -413,9 +416,9 @@ move them. Tube and torus axial datums may lie over an opening; a cone has no ca
 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`
-vocabulary as `attach`, including a named `source`. It applies after local shape construction. Filled Section attachment must
-preserve the XY plane.
+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
@@ -534,8 +537,8 @@ reindex also chooses a cyclic phase, while distance methods optimize ordered con
 
 ## Sample a heightfield
 
-Build a relief tile from absolute Z heights over a rectangular XY grid. Imported
-[`heightfield`](../reference/model/heightfield.md) returns a Solid for booleans and placement during
+Build a relief tile from absolute Z heights over a rectangular XY grid.
+[`heightfield`](../reference/model/heightfield.md) returns a Solid for Booleans and placement during
 generation. Pure [`heightfieldMesh`](../reference/geometry/heightfieldMesh.md) accepts the same options
 and returns an indexed mesh without an engine. Pass it directly as a mesh part, or wrap it in
 [`immutableMesh`](../reference/model/immutableMesh.md) when returning it from a cached computation.
@@ -687,6 +690,8 @@ replacement. Studio does not support custom font uploads.
 
 ## Solid inspection
 
+Use `inspectSolid()` during generation to check bounds, volume, and component count:
+
 
 
 ```ts
@@ -730,8 +735,8 @@ export const rowModel = generate<Record<never, never>>(({ part }) => {
 
 Inspection copies supported native facts. Manufacturing finalization checks finite, closed,
 oriented and reconstructable output before it becomes the preview or export snapshot. These
-checks do not certify manufacturability: product-specific minimum walls, overhangs, fits and
-parameter messages remain the Generator's job.
+checks do not certify manufacturability. Keep minimum walls, overhangs, fits, and parameter
+messages in your model's validation.
 
 After adapting a recipe, check its default, the largest and smallest supported dimensions, and
 every optional feature. Inspect the current result in Studio before exporting it. Continue with

package/dist/docs/guides/standalone-model.md

@@ -0,0 +1,42 @@
+# Write a standalone model
+
+Write a TypeScript model for a plate with a hole, then check and run it with the CLI.
+
+A standalone model uses `@metamesh/modeling` and default-exports a synchronous generation program.
+The CLI or your application supplies the engine.
+
+## Minimal model entry
+
+Save this complete example as `model.ts`. It makes a 30 × 20 × 6 mm plate with a through-hole:
+
+
+
+```ts
+import { box, cylinder, generate } from "@metamesh/modeling";
+
+export default generate<Record<never, never>>(({ part }) => {
+  const body = box({ size: [30, 20, 6] });
+  const bore = cylinder({ height: 8, radius: 3, sizing: "face" });
+  return part("plate", body.subtract([bore]));
+});
+```
+
+
+
+The cutter extends beyond both faces of the centered plate. `part("plate", ...)` gives the output
+a stable identity. This model takes an empty parameter map.
+
+## Check and run
+
+With [Modeling and the CLI installed](https://metamesh.studio/docs/develop/agent-authoring#install-and-discover-the-environment),
+check the source and generate a captured result:
+
+```bash
+pnpm exec metamesh check model.ts --kind model
+pnpm exec metamesh run model.ts --kind model
+```
+
+Continue with [inspection and rendering](https://metamesh.studio/docs/develop/agent-authoring#inspect-the-captured-result),
+or [host the program in your application](hosting.md).
+Use the [construction chooser](concepts.md#choose-a-modeling-path) when you
+need to select another modeling approach.