@metamesh/modeling 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,191 @@
 # @metamesh/modeling
 
+## 0.19.0
+
+### Minor Changes
+
+- c9de510: Extend straight extrusion end finishing to concave outlines, holes, and disconnected regions.
+  Add independent-solid `join` with a feature datum and a smooth (default) or straight width/height
+  transition against validated planar, angled, and curved sampled support patches. Both profiles use
+  the same support, collar, and whole-volume containment proofs.
+
+  Breaking: compiled Generators require Modeling runtime major 12. Rebuild packages for the new
+  host contract; old compiled runtimes are rejected. Joining preserves the supplied operands and
+  does not promise a circular fillet radius or perform automatic placement.
+
+  Replace named lazy `computed` readers with eager `memo(fn, ...args)` values. Stable pure helpers
+  reuse immutable arguments and tracked current params/context reads, with bounded recent histories
+  and native geometry retention. Update Studio diagnostics to warn about fresh function identities.
+  All authored and compiled callers must use the new API; there is no compatibility surface.
+
+- de3d234: Add runtime-neutral STL, 3MF, and GLB export under `@metamesh/modeling/export`, with isolated
+  format entry points and backpressure-aware streaming writers. All formats consume captured local
+  geometry, placement, and appearance, with independent limits, cancellation, and structured
+  information-loss diagnostics. Standard 3MF color groups carry appearance, while base materials
+  and multiproperties retain explicit material identities independently of RGB values. These
+  properties do not assign slicer filaments or physical device trays. Add `mesh.render()` for
+  shared crease-aware display buffers that preserve exact triangle coordinates.
+
+  Breaking: remove `export3mf` and export types from `/engine`, remove SDK export request protocols
+  and `toWorldMeshes`, and return owned `Uint8Array` bytes with format metadata from the shared
+  exporters. Studio uses one export worker for every format. CLI captures use format version 3;
+  replace `run --export-3mf` with `metamesh export RUN_DIRECTORY --format 3mf --output model.3mf`.
+  Captured-run export also supports STL and GLB without rerunning source. No legacy export paths
+  or capture readers are retained.
+
+## 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

package/README.md

@@ -1,7 +1,8 @@
 # `@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. Combine shapes, add holes and threads, and change the
+dimensions without rewriting the model. Run it in Node.js or a browser Worker. Use the resulting
+meshes in your own application or export them for printing.
 
 > **Preview:** `0.x` minor releases may break compatibility. Patches remain compatible within the
 > same minor line.
@@ -12,197 +13,186 @@ 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.
+
+Use Modeling on its own, or add the [Generator SDK](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/README.md)
+for controls and presets, [Testkit](https://github.com/JasonKoolman/metamesh/blob/main/packages/testkit/README.md)
+for tests, and the [CLI](https://github.com/JasonKoolman/metamesh/blob/main/packages/cli/README.md)
+to check, run, and render local source. Studio isn't required.
 
 ## Start modeling
 
-Build a plate with a hole, then export its finished geometry:
+This Node.js example builds a plate with an adjustable width and a through hole:
 
 ```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();
-}
+const result = engine.run(model, { width: 30 }, { resolution: { maxChordError: 0.025 } });
+
+console.log(result.bounds, result.stats.signedVolume, result.stats.generateMs);
 ```
 
-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.
+The generation callback reads typed values through `params` and returns named parts. Organize the
+model with ordinary TypeScript functions, conditionals, and loops. `result.part("plate")` finds the plate by its ID;
+`result.parts` contains all the completed parts, with their meshes, placement, colors, and measurements.
+
+Lengths use millimetres and rotations use degrees. `maxChordError` controls physical curve
+sampling in both preview and manufacturing output. Browser hosts also configure the WebAssembly
+asset and run the engine in a Worker; see the
+[hosting guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/engine/hosting.mdx).
 
-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.
+## Modeling capabilities
 
-`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.
+| Area                  | Capabilities                                                                                                                        |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Shapes and sections   | Solid primitives, filled 2D shapes with holes, Booleans, hulls, 2D offsets, splitting, edge treatments, and controlled solid joins. |
+| 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.                    |
 
-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.
+The [geometry values guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/geometry-values.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.
 
-## Reusable math and shapes
+## Pure triangle meshes
 
-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:
+Use `@metamesh/modeling/geometry/mesh` when you want 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. Construct from dimensions with
-`bounds2({ size: [30, 18] })` or `bounds3({ size: [30, 18, 8], center: false })`; centered size
-construction is the default, and size cannot be combined with min/max. 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.
-
-## Hole and pocket cutters
-
-`holeCutter({ diameter, height })` declares a circular cutter from Z=0 to `height`.
-Use `profile: regularPolygon(...)` or `profile: rectangle(...)` instead of `diameter` for
-existing Section outlines. Plain profiles may have holes or disconnected regions. A positive
-`entryChamfer` must be smaller than `height`. Circular entries use nominal frustum radii;
-profile entries expand one strictly convex contour without holes by 45-degree parallel-edge
-offsets of its sampled boundary.
-
-Circular cutters additionally accept a `recess` with `kind: "counterbore"`, `diameter` and `depth`,
-or `kind: "countersink"`, `diameter` and full `includedAngle` in degrees. Recesses and entry chamfers
-are alternatives; `face` selects the top opening by default or the bottom opening explicitly.
-Both `overrun.bottom` and `overrun.top` default to zero. To preserve a blind pocket floor, position
-the cutter at that floor and extend only its top. Consumers own fit allowances and retained walls.
-
-## 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 per-half `chamfer` sets the
-45-degree setback in millimetres at both ends of every barrel and on exposed web edges. The root
-at the pin centreline stays square so its faces merge with the barrel. The setback defaults to
-zero and must leave a positive barrel wall and axial band. Web thickness must exceed twice the
-setback; web reach and knuckle length must exceed `2 * Math.SQRT2 * chamfer` to retain the end contours.
-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 `TriangleMesh` values with `positions` and `indices`. `mesh.join` concatenates
+buffers; it doesn't perform a solid union, so overlapping geometry remains overlapping.
+`mesh.loft(stations)` retains the supplied seams and vertices through direct correspondence by default.
+`mesh.optimizePlanarPatches` returns an optimized mesh together with its report.
 
-## Reuse unchanged work
+For threads, use `mesh.threadRidge` for a helical ridge or `mesh.threadSolid` for a complete threaded
+cylinder. `mesh.preflightThreadSolid` estimates sampling and allocation before construction.
 
-Use optional `computed` values for expensive geometry or data. Keep ordinary arithmetic and part
-placement simple:
+Use `mesh.immutable` to capture mesh buffers in memoized data. Primitive contour constructors
+return frozen arrays of frozen points, suitable for `memo` arguments. To edit a
+contour, create owned points first: `contour.map(([x, y]) => [x, y])`.
 
-```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] })];
-});
-```
+Import the mesh module directly so bundlers can remove unused operations and their dependencies.
 
-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, leaving their inputs unchanged.
+You can declare shapes before creating an engine. The engine evaluates them during a synchronous
+run and manages 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 a single build and `engine.createSession()` for repeated edits.
+Inside generation, `memo(fn, ...args)` reuses expensive pure calculations. Define helpers outside
+generation, pass immutable inputs, and pass the current `params` to track the fields a helper reads.
+Keep final part placement separate from local geometry so moving a part can reuse its mesh.
+Results are immutable and remain usable after later runs. Call `session.dispose()` when you're
+finished with a session; individual results need no disposal.
+
+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 validation
+
+Parameters and memo results use `ImmutableValue<T>`: nested objects, arrays, and tuples are
+readonly. Copy data before editing it. Fluent methods and explicit buffer `copy()` methods keep
+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.
+Values must be data the engine can capture. 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 types alone don't establish that an object
+contains supported data.
+
+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.
+
+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.
+
+## Inspect and export parts
+
+Authored parts use `PartDeclaration`; completed output uses `ModelPart` and `ModelResult` from
+`/engine`. A completed part's top-level buffers contain world coordinates; `part.geometry` holds
+reusable local geometry. Read immutable buffers through iteration or `.at(index)`, or use `.copy()`
+to get an owned typed array.
+
+Local and world-space measurements include `signedVolume` in mm³, `surfaceArea` in mm²,
+`shellCount`, and `edgeCount`. Completed parts always include the topology counts, even when
+optional topology analysis of an arbitrary mesh would omit them.
+
+Result statistics include `buildMs`, `finalizeMs`, and `generateMs`; `generateMs` includes cleanup.
+`stats.byteCount` counts finalized world-space position and index buffer bytes, counting shared
+buffers once. It doesn't measure local resources, transfer size, or total working memory.
+
+Export `result.parts` as STL, 3MF, or GLB with `@metamesh/modeling/export`. Export needs no engine.
+The [hosting guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/engine/hosting.mdx#export-the-completed-result)
+covers saving files and choosing a format.
 
 ## 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, and resource limits.                                               |
+| [`@metamesh/modeling/export`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/export/index.mdx)      | STL, 3MF, and GLB 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