@metamesh/modeling 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,198 @@
 # @metamesh/modeling
 
+## 0.18.0
+
+### Minor Changes
+
+- 2eea694: Consolidate model authoring, execution, and testing around fluent shapes and durable immutable
+  results. Upgrade all four packages together; these Preview API changes have no compatibility
+  aliases. Rebuild compiled Generators for module format 5 and Modeling runtime major 11. Older
+  module formats and incompatible runtime versions are rejected before execution.
+
+  ### Modeling imports and operations
+
+  | Previous API                                                                                            | 0.18 API                                                                                                  |
+  | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+  | `body.subtract([cutter])` for a single operand                                                          | `body.subtract(cutter)`; fluent `union`, `intersect`, and `subtract` accept one shape or a readonly array |
+  | `compose(shapes)`                                                                                       | `union(shapes)`                                                                                           |
+  | Free shape inspection, emptiness, component, and anchor queries                                         | `shape.inspect()`, `shape.isEmpty()`, `shape.components()`, and `shape.anchor(name)`                      |
+  | Free Solid distance/segment queries and splitting functions                                             | `solid.distance(other)`, `solid.castSegment(...)`, `solid.split(cutter)`, and `solid.splitByPlane(plane)` |
+  | `solid.toTriangleMesh()`                                                                                | `solid.toMesh()`                                                                                          |
+  | Named `mesh` import from `/geometry`, or standalone triangle-mesh functions                             | `import * as mesh from "@metamesh/modeling/geometry/mesh"`                                                |
+  | Standalone `immutableMesh(...)`                                                                         | `mesh.immutable(...)`                                                                                     |
+  | `helicalThreadRidgeMesh`, `helicalThreadSolidMesh`, and `preflightHelicalThreadSolidMesh`               | `mesh.threadRidge`, `mesh.threadSolid`, and `mesh.preflightThreadSolid`                                   |
+  | `HelicalThreadRidgeMeshOptions`, `HelicalThreadSolidMeshOptions`, and `HelicalThreadSolidMeshPreflight` | `ThreadRidgeOptions`, `ThreadSolidOptions`, and `ThreadSolidPreflight`, exported from the mesh module     |
+  | Mesh `connectedComponentCount`                                                                          | `shellCount`; native inspection `componentCount` still counts material components                         |
+  | Inspection extrema on the inspection result                                                             | Immutable `inspection.bounds.min` and `inspection.bounds.max`                                             |
+  | `starContour(outerRadius, points, innerRadius, limits)`                                                 | `starContour({ outerRadius, innerRadius, points, limits })`                                               |
+
+  Free `union(shapes)` and `intersect(shapes)` remain for collections of peers and reject empty
+  collections. Fluent Boolean methods with an empty array return the receiver.
+
+  Use `section.extrude(options)` in fluent modeling, `extrude(profile, options)` for generic
+  `Section | CorrespondingProfile` inputs, and `mesh.extrude(contour, options)` for pure triangle
+  buffers. The same fluent/generic distinction applies to revolution and sweeping. Pure extrusion
+  uses `ExtrudeMeshOptions` and rejects `ends`; use Section extrusion for native end treatments.
+  Construction, transforms, and splitting remain deferred recipes; observations and `toMesh()`
+  require active model execution.
+
+  Point-loop and arbitrary Section lofts default to direct correspondence when the method is
+  omitted; known primitive landmarks remain preserved. Dimension inputs accept fluent vectors.
+  Tube sizing accepts complete inner/outer radius or diameter pairs. Both star factories require
+  an explicit inner radius and support degree rotation; use `innerRadius: outerRadius / 2` to retain
+  the contour helper's former default.
+
+  Rod and internal-cutter `bevelBottom`, `bevelTop`, and `bevelSize` become `bevel`. The shared
+  `Bevel` contract accepts a nonnegative size, `"auto"`, or a readonly `[bottom, top]` pair; zero
+  disables an end and omission preserves factory defaults. Complete-thread mesh builders use the
+  same contract, with thread termination under `ends`. Nuts replace bevel selection, `chamferSize`,
+  and `flushBuildPlateBottom` with independent `innerBevel` and `outerBevel`. For a flat outside
+  bottom that retains its inner opening bevel, use `outerBevel: [0, "auto"]`. Nut preflight exposes
+  resolved inner/outer pairs and checks face walls pairwise; each end's reservation and automatic
+  sizing are resolved independently, including internal-cutter axial extension.
+
+  Primitive contours and their points are immutable and can be explicit `computed` dependencies.
+  Copy the outer array and any points before editing. Geometry errors are available from the
+  Modeling root; operation option/result types are exported beside their owning operations.
+  Topology analysis with `includeTopology: true`, finalized parts, and local geometry resources
+  include required `shellCount` and `edgeCount`. Bounds construction options describe inputs only;
+  existing fluent bounds remain accepted.
+
+  ### Part placement and result ownership
+
+  Replace `part(id, { geometry, position, rotation })` with
+  `part(id, { geometry, transform })`. The optional transform accepts a fluent `transform3()` value,
+  a row-major 16-number matrix, or a computed reader; omission means identity. Pattern and
+  attachment matrices pass directly to `part()`. Only rigid placement is supported: scale, shear,
+  reflection, perspective, and non-finite values are rejected. Geometry-only and geometry-or-options
+  union inputs remain accepted without casts.
+
+  Use `PartDeclaration` for authored parts. Replace `ModelSnapshot` / `FinalizedModel` with
+  `ModelResult`, and `SnapshotPart` / `FinalizedPart` with `ModelPart`. `engine.run()`, `session.run()`,
+  and Testkit's `runModel()` return durable immutable results. Dispose sessions and runners to release their
+  caches; completed results remain valid and need no disposal. `model.part(id)` returns a required
+  semantic part or throws with available IDs; `model.parts` preserves output order.
+
+  Finalized buffers expose stable, iterable `ImmutableBuffer` values. Use `.copy()` for mutable
+  storage. A `ModelPart`'s top-level positions and indices are already in world space; apply its
+  immutable `transform` only to the reusable local buffers under `geometry`. Worker deliveries also
+  nest local resources under `geometry`. Host integrations use `ModelDeliveryEncoder`,
+  `PartDeliveryDecoder`, and `toWorldMeshes` for owned transfer and manufacturing output.
+  Replace `engine.export3mf(...)` with standalone `export3mf(parts, options)` from `/engine`, which
+  accepts completed meshes with explicit resource limits, independently of engine initialization.
+
+  Statistics rename `volumeMm3` → `signedVolume`, `finalizationMs` → `finalizeMs`, and
+  `generationMs` → `generateMs`; `buildMs` measures declarations.
+  `ModelResult.stats.byteCount` means bytes occupied by finalized world-space position and index buffers,
+  counting shared buffers once. Worker statistics preserve engine `generateMs`; host elapsed time
+  is `timings.totalMs`, with `paramsMs` for parameter work. Other host timing stages are optional:
+  an omitted stage is unmeasured.
+
+  Model parameter roots must be object maps. Captured parameters and computed results expose
+  deeply readonly `ImmutableValue<T>` views; supported mutable caller input is still accepted and
+  recaptured on every revision, including mutable children inside frozen objects. Deeply immutable
+  data retains identity reuse. Assertions and warnings accept bounded immutable nested `path`
+  metadata. Replace `validateModel` with `checkModel` and session/runner `.validate()` with `.check()`.
+  These check declarations and reached assertions without finalizing geometry; unexpected execution
+  failures still throw.
+
+  ### Generator SDK and Testkit
+
+  | Previous API                                                               | 0.18 API                                                                                                                |
+  | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+  | Nested compiled Generator module                                           | Flat format-5 model program; bind an existing program with `defineGeneratorModule({ definition, program })`             |
+  | `isGeneratorModule(value)`                                                 | `parseGeneratorModule(value, definition)`                                                                               |
+  | `executeGenerator({ ..., parsedParameters })`                              | `executeGenerator({ ..., parameters })`; current-definition validation always runs                                      |
+  | Callback-scoped `withModel`, `ModelTestOptions`, or `runner.withModel`     | `await runModel(programOrCallback, ...)` for one-off results; explicit sessions or Generator runners for repeated edits |
+  | Generator test `runner.execute(...)`                                       | `runner.run(...)`, returning `GeneratorTestResult`                                                                      |
+  | `expectSerializableDefinition`                                             | `assertValidDefinition`                                                                                                 |
+  | `expectValidDefaults`, `expectValidPresets`, and `expectValidParts`        | `assertValidDefaults`, `assertValidPresets`, and `assertValidParts`                                                     |
+  | `expectMeshMeasurements`                                                   | `assertMeshMeasurements`                                                                                                |
+  | `canonicalizeParameters(definition, parameters)` from `/parameters`        | `canonicalizeParameters(parameters)` from `/runtime`                                                                    |
+  | `GeneratedPartsDecoder`, `parseGeneratedParts`, and `GeneratedPartsLimits` | `PartDeliveryDecoder`, `parseModelParts`, and `PartDeliveryLimits`                                                      |
+  | `GeneratedPart` and `GeneratedModel`                                       | `ModelPartData` and `ModelData`                                                                                         |
+  | `GeneratedPartDelivery` and `GeneratedModelDelivery`                       | `PartDelivery` and `ModelDelivery`                                                                                      |
+
+  Testkit `runModel` accepts existing `ModelProgram` values and synchronous inline callbacks;
+  typed callbacks use `runModel<Parameters, Services>`. Its definition-bound Generator overload
+  validates inputs and prepares services. The SDK Modeling adapter adds definition-inferred
+  `GeneratorModel` and `parseGeneratorModel`. Ordinary model tests preserve definition-inferred
+  input types. Reusable Generator runners accept physical generation policy plus `cache` and
+  `verifyCache` for edit sequences; dispose the runner after use.
+
+  Generator execution and ordinary tests strictly require complete canonical parameter maps.
+  Use the parameter codec for strict input and `normalizeParameters` for forgiving recovery;
+  replace `prepareParameters`, `validateParameters`, and `PreparedParameters` with
+  `createParamCodec(definition).parse(...)` or `.safeParse(...)`. Schema adapters remain private.
+  Codec failures provide structured issues without a substitute parameter map. For deliberate
+  malformed-input assertion probes, replace `runner.validate(parameters, { normalize: false })`
+  with `runner.check(parameters, { validateInput: false })`.
+  Defaults are selected only by omission or `undefined` where supported; a `null` parameter map is
+  rejected. Parameterless model calls can omit the empty map. Definition and preset helpers catch
+  nested key typos and validate immediately while retaining literal inference.
+
+  `assertValidParts` checks the supplied world-space buffers, closed topology, and exact agreement
+  with local geometry under `transform`; it no longer hides corrupted output by reconstructing it.
+  Always await `assertValidParts(parts, engine)` (or omit the engine): failures reject, and supplying
+  an engine changes resource reuse only.
+  `assertValidDefinition` also checks the canonical JSON round trip. New `assertEqualBuffer` and
+  `assertEqualMesh` compare exact ordered contents without copying; equivalent shapes with different
+  triangulations can differ. `ContentMismatchError` identifies the first differing element or
+  length, while malformed input and reader failures retain their errors. Optional `contentMatchers`
+  support `expect.extend`, including negation, without a test-framework dependency.
+
+  ### CLI and package requirements
+
+  Rename the type-only CLI command `metamesh check` to `metamesh typecheck`; no alias is retained.
+  Node authoring APIs and Modeling/Testkit declaration-check methods retain their names. Generator
+  runs use `overrides` / `--overrides`, merged with defaults before strict parsing; standalone models
+  use `params` / `--params`. Supplying the other entry kind's input option is rejected.
+
+  Captured runs use format 2 with transform-only placement. The bundled capture renderer resolves
+  from the installed CLI package so published installations can render captures.
+  Public packages require Node.js 24 or newer, ESM imports, and TypeScript 6.0 or newer with strict
+  checking for TypeScript consumers.
+
+## 0.17.0
+
+### Minor Changes
+
+- Expose `resolveCircularSampling` for the resolved count and actual vertex/face radii of a sampled
+  circle without allocating points. It shares sampling rules with `resolveCircularSegments`, aligned
+  counts, and `circleContour`, including exact-count precedence and physical error ceilings.
+
+  Construct fluent bounds directly with `bounds2({ size: [width, height] })` and
+  `bounds3({ size: [width, depth, height], center: false })`. Size construction accepts finite
+  nonnegative dimensions, centers by default, and is mutually exclusive with min/max construction.
+  Remove `boundsFromSize`, `BoundsFromSizeOptions`, and the standalone `containsBounds` export.
+  Containment remains available on `Bounds2` and `Bounds3`, including touching boundaries.
+
+  Migration: replace `boundsFromSize(size, { center })` with the dimension-specific
+  `bounds2({ size, center })` or `bounds3({ size, center })`. Use `.toData()` when a plain record is
+  required. For sampled bore and wall checks, use `vertexRadius` and `faceRadius` from
+  `resolveCircularSampling` instead of repeating faceting trigonometry.
+  Replace `containsBounds(outer, inner)` with `bounds2(outer).containsBounds(inner)` or the matching
+  XYZ bounds value's method.
+
+- d0cc194: Rename per-half `barrelChamfer` to `chamfer` in `knuckleHinge`. The same 45-degree setback now finishes barrel outer rims and exposed web edges. Keep the buried root square and share bevel coordinates with the barrel and mounting body to avoid microscopic steps and collapsed placement triangles. Reject chamfers that consume the web band or collapse its end contours.
+- Add deferred `holeCutter` recipes for circular screw holes and existing Section pocket profiles.
+  Circular cutters support counterbores and countersinks; convex single-contour profiles support
+  45-degree entry chamfers. Explicit `overrun.bottom` and `overrun.top` preserve blind-pocket floors
+  unless the caller deliberately extends the cutter.
+  Circular entry chamfers retain nominal circular radii; Section entry chamfers offset the supplied
+  sampled contour's edges.
+
+  Advance the Modeling host runtime to major 9 for hole cutters and fitted SVG recipe options.
+  Rebuild Generator packages against the new library set; old host/runtime packages are rejected.
+
+  Migration tip: reuse `regularPolygon`, `rectangle`, or other Section constructors as the cutter's
+  `profile`. Position a blind cutter at its intended floor and set only `overrun.top` for opening
+  padding. Keep allowances, minimum floor thickness and feature-specific assertions in your model.
+
+- Add an optional positioned XY `fit` target to `preflightSvgRegion` and `svgSection`. Reuse `fitBounds` for uniform scale and translation while resampling original SVG curves at the final millimetre tolerance and edge spacing. Normalize fitted source units before topology checks, and use relative matrix conditioning so tiny well-conditioned SVG coordinates can be enlarged safely. Preserve holes, painted strokes, exact circular-count overrides, bounded work, and host-owned sampling ceilings. Preflight results expose the applied fit for registered layers and measure the final region.
+
+  Migration tip: replace import → measure → scale → re-import code with `preflightSvgRegion(svg, { fit: bounds2({ size: [30, 18] }), resolution: { maxChordError: 0.05 } })`. `svgSection` preserves positioned fit targets instead of centering them again.
+
 ## 0.16.0
 
 ### Minor Changes

package/README.md

@@ -1,7 +1,7 @@
 # `@metamesh/modeling`
 
-Build parametric 3D parts in TypeScript. Combine solids, work with pure geometry, and export 3MF
-from Node applications, browser Workers, or MetaMesh Generators.
+Build parametric 3D models in TypeScript. Compose immutable shapes with a fluent API, run them in
+Node or browser Workers, and work with the resulting geometry in your own application.
 
 > **Preview:** `0.x` minor releases may break compatibility. Patches remain compatible within the
 > same minor line.
@@ -12,176 +12,171 @@ from Node applications, browser Workers, or MetaMesh Generators.
 pnpm add @metamesh/modeling
 ```
 
-Modeling works on its own; the Generator SDK and Testkit are optional.
+The package publishes ES modules only. Use Node.js 24 or newer. TypeScript consumers need
+TypeScript 6.0 or newer, `strict` checking, and `NodeNext` or `Bundler` module resolution.
+Browser hosts need an ES2023-compatible runtime and WebAssembly; run the engine in a Worker.
+
+Modeling works independently of Studio and the Generator SDK. Add the SDK when you need Generator
+controls and presets, Testkit for testing helpers, or the CLI for local authoring tools.
 
 ## Start modeling
 
-Build a plate with a hole, then export its finished geometry:
+Define a plate with an adjustable width and a through hole, then build it with the engine:
 
 ```ts
 import { box, cylinder, generate } from "@metamesh/modeling";
 import { createModelEngine } from "@metamesh/modeling/engine";
 
-const model = generate<Record<never, never>>(({ part }) => {
-  const body = box({ size: [30, 20, 6] });
+const model = generate<{ width: number }>(({ params, part }) => {
+  const plate = box({ size: [params.width, 20, 6] });
   const bore = cylinder({ height: 8, radius: 3, sizing: "face" });
-  return part("plate", body.subtract([bore]));
+  return part("plate", plate.subtract(bore));
 });
 
 const engine = await createModelEngine();
-const session = engine.createSession(model, { resolution: { maxChordError: 0.025 } });
-try {
-  const snapshot = session.run({});
-  try {
-    const bytes = await engine.export3mf(snapshot.parts, { name: "Plate" });
-    // Save or send the 3MF bytes.
-  } finally {
-    snapshot.dispose();
-  }
-} finally {
-  session.dispose();
-}
-```
-
-Use `path2(points, { closed })` or `path3(points)` for reusable sampled trajectories.
-Paths own closure and chain `transform`, `reverse`, and `resample` immutably. `path.closestPoint(point)`
-returns the nearest boundary position, distance, edge index, and fraction within that edge.
-Use `stroke(path, { width, cap, join })` to fill a sampled XY path without conversion.
-
-Generation is synchronous. Return a single `part(...)` or a readonly array of parts. Shape constructors
-and methods create immutable recipes without an engine. Ordinary recipes can be reused across
-sessions regardless of where they were constructed. Explicit resolution settings are captured;
-unspecified settings inherit the evaluating host's defaults. Observed `components()` selections
-and recipes using them can only be evaluated in their originating session. The engine evaluates
-recipes into a snapshot for rendering or export. Sessions own evaluated caches and native resources,
-while snapshots remain usable after their session is disposed.
-Dispose both when finished. Export uses the captured geometry without running the model again.
-
-`components()` returns disconnected material pieces with their holes and enclosed cavities intact.
-Inspection `componentCount` counts these pieces; snapshot `stats.partCount` counts declared output
-parts. Snapshot `stats.vertexCount` and `stats.triangleCount` count all instances, while
-`stats.byteCount` counts shared backing storage once.
+const result = engine.run(model, { width: 30 }, { resolution: { maxChordError: 0.025 } });
 
-Lengths use millimetres and modeling rotations use degrees. Physical resolution controls curve
-sampling for both preview and manufacturing output. See the
-[hosting guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/engine/hosting.mdx)
-for browser WASM setup, resource limits, and lifecycle details.
-
-## Reusable math and shapes
+console.log(result.bounds, result.stats.signedVolume, result.stats.generateMs);
+```
 
-Use immutable fluent vectors, paths, bounds, and transforms for ordinary modeling. Transform chains apply in written order,
-rotations use degrees, and an optional `pivot` is a fixed world-space point:
+`generate` receives typed parameters and returns named parts. Use ordinary TypeScript functions,
+conditionals, and loops to organize the model. `result.parts` contains its manufacturing meshes,
+placement, colors, and measurements; `result.part("plate")` looks up a part by its semantic ID.
+Authored output uses `PartDeclaration`; completed engine output uses `ModelPart` and `ModelResult`
+from `/engine`. A completed part's top-level buffers are in world coordinates; `part.geometry`
+holds reusable local geometry.
+`stats.byteCount` counts finalized world-space position and index buffer bytes, counting shared
+buffers once; it does not measure local resources, transfer size, or total working memory.
+Both local and world-space completed measurements include `shellCount` and `edgeCount`;
+unlike optional topology analysis of arbitrary meshes, these counts are always available.
+
+Lengths use millimetres and rotations use degrees. Mesh and aggregate measurements use
+`signedVolume` in mm³ and `surfaceArea` in mm². Engine durations use `buildMs`, `finalizeMs`,
+and `generateMs`; `generateMs` includes cleanup. Physical curve resolution applies to both
+preview and manufacturing output. Browser hosts also configure the WASM asset; see the
+[hosting guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/engine/hosting.mdx).
+
+## Modeling capabilities
+
+| Area                  | Capabilities                                                                                                          |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Shapes and sections   | Solid primitives, filled 2D shapes with holes, Booleans, hulls, 2D offsets, splitting, and primitive edge treatments. |
+| Sweeps and surfaces   | Extrusion, revolution, sweeps, lofts with explicit profile correspondence, heightfields, and implicit surfaces.       |
+| Paths and placement   | Immutable vectors, paths, transforms, and bounds; anchors, layout, and linear, radial, grid, and path patterns.       |
+| SVG and text          | Bounded SVG fills and strokes, prepared font outlines, and vector text layout.                                        |
+| Mechanical geometry   | Printable threads, knuckle joints, gear profiles, fastener standards, and fit calculations.                           |
+| Meshes and inspection | Indexed mesh construction and conversion, measurements, spatial queries, topology checks, and bounded preflight.      |
+
+The [concepts guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/geometry-package.mdx)
+helps you choose a representation. The [recipes](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/geometry-recipes.mdx)
+show how these capabilities fit together.
+
+## Pure triangle meshes
+
+Import the mesh module as `mesh` from `@metamesh/modeling/geometry/mesh` to construct and process triangle
+buffers without an engine:
 
 ```ts
-import { polygon, transform2, vector3 } from "@metamesh/modeling";
-
-const placement = transform2()
-  .rotate(30, { pivot: [10, 5] })
-  .scale([2, 1])
-  .translate([20, 0]);
-const body = polygon({
-  outer: [
-    [0, 0],
-    [20, 0],
-    [10, 10],
-  ],
-  holes: [],
-})
-  .transform(placement)
-  .extrude({ height: 8 });
-const direction = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
-const alignment = direction.dot([0, 0, 1]);
+import { rectangleContour, transform3 } from "@metamesh/modeling/geometry";
+import * as mesh from "@metamesh/modeling/geometry/mesh";
+
+const plate = mesh.extrude(rectangleContour({ size: [30, 20] }), { height: 8 });
+const positioned = mesh.transform(plate, transform3().translate([10, 0, 0]));
+const facts = mesh.analyze(positioned, { requireClosed: true });
 ```
 
-Transforms apply separately to points, directions and normals with `applyPoint`, `applyDirection`
-and `applyNormal`. `andThen` composes placements in execution order; `inverse` reverses them.
-Value types use domain names (`Vector2`, `Transform2`, `Path2`, `Bounds2`); their plain
-representations use `Data`, and accepted construction forms use `Input`. Use `toData()` for
-canonical plain interchange, including path dimension and closure. Tuple arithmetic kernels remain available in
-`/geometry` for dense numerical loops.
-
-Primitive `attachment` maps a local anchor to a target anchor using the same degree-based
-`AttachOptions` as `solid.attach()`. Rotation references use `pivot`; immutable tolerance changes
-use `solid.withTolerance(value)`. Final part `position` and `rotation` remain rigid placement data,
-separate from reusable geometry.
-
-`Section` is the filled 2D modeling value. Its serialized representation is `RegionData`;
-`polygon({ polygons: data })` constructs a Section from it. `section.toRegionData()` and other
-geometry observations need an active synchronous host execution.
-`solid.toTriangleMesh()` follows the same observation rule and returns copied mesh buffers.
-Closed `Path2` values describe traversal, not material; `polygon(path)` fills them and normalizes
-winding. Path transforms preserve traversal under reflection. `toData()` supplies a frozen record with points, closure, and dimension for interchange.
-
-Use `bounds2({ min, max })` and `bounds3({ min, max })` for axis-aligned extents with fluent
-`size()`, `center()`, and `containsBounds()` queries. Path `bounds()` returns these values, or
-`undefined` for an empty path. Measurements and snapshots retain plain `Bounds2Data` / `Bounds3Data`;
-wrap them once for fluent queries and use `toData()` for a frozen min/max record.
-Containment includes touching boundaries in the same coordinate frame; it does not establish
-manufacturing fit. Pure `fitBounds` and `layoutRow` accept values or data for fitting and row placement.
-
-## Mechanical joints
-
-`knuckleHinge(options)` declares separate `halfA` and `halfB` solids with a centered +X pin axis
-and +Z roll guide. Choose `print-in-place`, `inserted-pin`, or `lift-off` construction. Captive
-joints require an odd knuckle count; lift-off joints require two knuckles and an explicit
-`pinEngagement`. Inserted-pin joints supply no pin or retention hardware.
-
-Each half accepts an optional rectangular web with its own Y direction, lower-face Z coordinate (`zMin`), thickness, and
-reach, or can remain barrels only. Optional `barrelChamfer` sets the 45-degree setback in millimetres at both ends of every barrel; web edges
-remain square. Consumers connect disconnected intervals to their plates or shells, preserve bores
-when adding material, and own mounting holes, part placement, and motion. Arbitrary attachments
-have no guaranteed opening range. Use `resolveKnuckleHinge(spec, sampling)` from `/geometry` for
-the immutable interval schedule, axis frame, integral pin extent, and conservative faceted wall.
-
-Radial clearance is a per-side allowance; axial gap is the total space between neighboring
-knuckle ends. Both may be zero for ideal contact, which does not establish a printable fit.
-Sampling follows the normal resolution contract; exact circular counts must be divisible by four.
+Constructors return ordinary `TriangleMesh` values with `positions` and `indices`.
+`mesh.join` concatenates meshes; overlapping geometry remains overlapping.
+`mesh.optimizePlanarPatches` returns the optimized mesh and its report.
+Use `mesh.threadRidge` for a helical ridge, `mesh.threadSolid` for a complete threaded cylinder,
+and `mesh.preflightThreadSolid` for its conservative sampling and allocation estimate.
+`mesh.loft(stations)` uses direct correspondence by default, retaining the supplied seams and vertices.
 
-## Reuse unchanged work
+Use `mesh.immutable` to capture mesh buffers in computed data. Primitive contour constructors
+return frozen arrays of frozen points, suitable for explicit `computed` dependencies. To edit a
+contour, create owned points first: `contour.map(([x, y]) => [x, y])`.
 
-Use optional `computed` values for expensive geometry or data. Keep ordinary arithmetic and part
-placement simple:
+Import the mesh module directly so bundlers can remove unused operations and their dependencies.
 
-```ts
-const model = generate<{ height: number; gap: number }>(({ params, computed, part }) => {
-  const body = computed("body", () => box({ size: [10, 10, params.height] }));
-  return [part("left", body), part("right", { geometry: body, position: [10 + params.gap, 0, 0] })];
-});
-```
-
-Changing `gap` reuses the body's geometry; changing `height` recomputes it. Read parameters and
-other computed readers inside the callback so their dependencies are tracked. Changing outer
-captures need an explicit dependency array. Callbacks are pure and synchronous; cached data is
-immutable. Use `immutableBuffer` and `immutableMesh` for cached typed arrays and meshes.
+## Reuse unchanged work
 
-The [computed-value guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/code-project-contract.mdx)
-covers dependency tracking, immutable data, cache verification, and part placement.
+Shape constructors and fluent methods create immutable recipes; they leave their inputs unchanged.
+Construction needs no engine. Generation and geometry observations run synchronously in a host
+execution, which owns native allocations and cleanup.
+
+Use shape methods for fluent modeling: `body.union(boss).subtract(bore).intersect(envelope)`.
+Each Boolean method accepts one same-dimensional shape or a readonly array; an empty array preserves
+the receiver. Collection `union(shapes)` and `intersect(shapes)` combine peers and need at least one
+shape. Queries use `shape.inspect()`, `shape.isEmpty()`, `shape.components()`, and `shape.anchor(name)`;
+Solids also support `distance`, `castSegment`, `split`, and `splitByPlane`. Use `solid.toMesh()` for
+copied triangle buffers during active generation.
+
+Prefer `section.extrude(options)` in a modeling sequence. Imported `extrude(profile, options)` accepts
+`Section | CorrespondingProfile` for reusable profile functions; `revolve` and `sweep` follow the same
+convention. Use `mesh.extrude(contour, options)` for pure triangle-buffer construction.
+
+Use `engine.run()` for an isolated build and `engine.createSession()` for repeated edits that reuse
+computations. `computed` caches expensive geometry or data: read parameters inside its callback for
+automatic tracking, and list changing outer captures explicitly. Keep final part placement separate
+from local geometry to move instances without rebuilding them. Both run methods return durable
+immutable results; dispose only reusable sessions when finished. Existing results remain usable.
+
+Use `part(id, { geometry, transform: transform3().rotate([0, 0, 90]).translate([20, 0, 0]) })`
+for final placement. The transform accepts a fluent value or row-major 16-number matrix, including
+pattern and attachment outputs; omission means identity. Only translation and proper rotation are
+allowed. Completed parts expose the copied frozen matrix as `part.transform`.
+
+Parameters and computed results expose `ImmutableValue<T>`: nested objects, arrays, and tuples are
+readonly, matching their captured runtime data. Copy data before editing it; fluent value methods
+and explicit buffer `copy()` methods retain their ordinary return types.
+
+Parameters use an object map; named interfaces and nested arrays or tuples remain supported.
+Each run recaptures mutable caller data, including mutable children of frozen objects. Sessions
+reuse unchanged complex parameter identities only when their complete data graph is immutable.
+Execution checks that values are capturable data. Ordinary class instances such as `Date`, functions,
+and mutable typed arrays reject at runtime; use scalar dates, prepared services, or explicit
+`immutableBuffer` captures as appropriate. TypeScript's structural object constraint rejects scalar
+parameter types but does not prove that an arbitrary object has a plain-data prototype.
+
+The context's `assert` reports generation diagnostics; it does not act as a TypeScript narrowing
+assertion. When narrowing is needed, use a conditional guard such as
+`if (params.size === undefined) return assert(false, "Size is required.")` before reading the value.
+
+Use `session.check(parameters)` or standalone `checkModel(program, parameters)` to check declarations
+and reached assertions without finalizing output. Use `run()` to evaluate and finalize geometry.
+Checks return expected assertion errors and warnings; unexpected execution and geometry failures throw.
+Export captured parts with standalone `export3mf(parts, options)` from `/engine`; it needs no engine
+and never blocks generation. Export limits are explicit. Immutable result buffers support standard
+iteration and `.at(index)` for reads, or `.copy()` for owned typed arrays.
+
+See [generation and caching](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/code-project-contract.mdx)
+for dependency rules, immutable data, and session ownership.
 
 ## API discovery and ownership
 
-| Import                                                                                                                                      | Use it for                                                            |
-| ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| [`@metamesh/modeling`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/model/index.mdx)             | Immutable shapes, vectors, paths, transforms, and modeling operations |
-| [`@metamesh/modeling/geometry`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/geometry/index.mdx) | Pure paths, profiles, meshes, and calculations                        |
-| [`@metamesh/modeling/engine`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/engine/index.mdx)     | Sessions, snapshots, limits, and 3MF export                           |
-| [`@metamesh/modeling/text`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/text/index.mdx)         | Optional font preparation and vector layouts                          |
+| Import                                                                                                                                       | Responsibility                                                                                     |
+| -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| [`@metamesh/modeling`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/model/index.mdx)              | Shapes, fluent values, modeling operations, and generation programs.                               |
+| [`@metamesh/modeling/geometry`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/geometry/index.mdx)  | Pure TypeScript geometry, sampling, numerical helpers, and mesh contracts without a native engine. |
+| [`@metamesh/modeling/geometry/mesh`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/mesh/index.mdx) | Triangle mesh construction, processing, and inspection through direct `mesh.*` imports.            |
+| [`@metamesh/modeling/engine`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/engine/index.mdx)      | Host initialization, execution, resource limits, and 3MF export.                                   |
+| [`@metamesh/modeling/text`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/text/index.mdx)          | Optional font preparation and reusable vector layouts from supplied bytes.                         |
+
+Font preparation requires the optional `fontkit` peer; add `woff2-encoder` for WOFF2 input. Models
+consume prepared layouts without fetching fonts during generation. Your host owns viewing,
+application state, asset loading, and export delivery.
 
 ## Documentation
 
-The installed package exposes `@metamesh/modeling/docs/manifest.json`: an exact-version index of
-plain Markdown guides and every public API symbol. Resolve that export from your project to find
-the documentation beside your installed release. Its paths are relative to the manifest.
-With `@metamesh/cli` installed, use `pnpm exec metamesh docs search "your topic"` and
-`pnpm exec metamesh docs show DOCUMENT_ID` for bounded offline lookup. Read
-`modeling/guide/standalone-model` for a short complete example, `modeling/guide/concepts` to choose
-geometry, or `modeling/guide/hosting` to run a program in your application.
+Resolve `@metamesh/modeling/docs/manifest.json` from your project for exact-version Markdown guides
+and API references. With [`@metamesh/cli`](https://github.com/JasonKoolman/metamesh/blob/main/packages/cli/README.md)
+installed, search and read them offline:
 
-- [Geometry concepts](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/geometry-package.mdx) — coordinates, resolution, and supported modeling paths.
-- [Geometry recipes](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/geometry-recipes.mdx) — primitives, sweeps, lofts, text, SVG, and booleans.
-- [Font preparation](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/engine/fonts.mdx) — prepare exact font bytes outside Studio.
+```bash
+pnpm exec metamesh docs search "sweep"
+pnpm exec metamesh docs show modeling/guide/concepts
+```
 
-Until the public documentation site launches, use these repository guides or
-[run the docs locally](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/README.md#local-use).
 For package development, see [Contributing](https://github.com/JasonKoolman/metamesh/blob/main/CONTRIBUTING.md).
 
 ## License