@metamesh/modeling 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @metamesh/modeling
 
+## 0.11.0
+
+### Minor Changes
+
+- b5da778: Replace prepare/build with typed generation programs, optional computed values and authoritative
+  part placement. Add isolated session caches and deferred geometry with explicit snapshot ownership.
+  Expose immutable fluent Solid and Section methods for transforms, subtraction, finishing, and
+  Section-to-Solid construction, replacing the corresponding standalone operations and public
+  context facade. Generator packages require format 4 and runtime 4; previous executable contracts are unsupported.
+- bfb7a63: Keep computed dependencies correct after conditional removal and re-registration, and prevent
+  caught evaluation failures from returning earlier cached values. Reduce immutable data copying,
+  centralize geometry finalization, and validate newly delivered resources once while preserving
+  per-revision part and aggregate resource checks.
+
+  Replace transparent cached typed arrays with explicit immutableBuffer and immutableMesh capture
+  helpers. Cached numeric data exposes length, at(), and copy(); uncaptured typed arrays in computed
+  results or bindings now reject. Snapshot and Worker output buffers remain ordinary typed arrays.
+
+### Patch Changes
+
+- 88f5336: Correct immutable cache comparisons, recapture mutable mesh inputs on every run, and preserve
+  session ownership during concurrent Testkit operations. Reject unsupported hidden data fields
+  instead of silently dropping them, and reuse native operation contexts during recipe evaluation.
+- 6c90e9d: Capture computed data in one validated traversal, reuse unchanged bindings and repeated dependency
+  analysis, and share recorded operation calls across result handles. Derive internal fluent dispatch
+  from the public shape contracts and skip cache retention work when caching is disabled.
+
+  Keep failed assertions attached to their revision even when author code catches them, preventing
+  invalid snapshots and cache commits.
+
+- 60c458f: Validate placed manufacturing geometry under the requested solid policy after Float32 rounding.
+  Share world buffers between identical placed instances while still counting each instance toward
+  output limits, and include retained object storage and field names in optional cache estimates.
+- a1f5aba: Reuse evaluated computed geometry as native operands across session runs without changing the public
+  API. Preserve anchor and profile metadata, bound optional retention, and release native allocations
+  on failed candidate generation, eviction, cache clearing, and session disposal.
+- d4ffce7: Release obsolete computation callbacks and prior revision graphs when a revision closes, keeping
+  cached numerical recipes from retaining unrelated work. Consolidate recipe traversal and revision
+  cleanup without changing the public Modeling API.
+
+## 0.10.0
+
+### Minor Changes
+
+- 9d7052c: Separate parameter values from local UI metadata, add strict parameter-document diagnostics and a generated JSON Schema, and rename the side-profile and contour APIs. Generator packages and modules now require format 3 and runtime 3.0.0.
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -1,459 +1,103 @@
 # `@metamesh/modeling`
 
-Standalone geometry foundations and a modeling engine for Node applications, browser Workers, and MetaMesh Generators.
+Build parametric 3D parts with TypeScript and export the finished meshes to 3MF. Use Modeling in
+Node applications, browser Workers, or MetaMesh Generators, with no SDK or Testkit required.
 
-> **Preview:** `0.x` minor releases may break compatibility. Patches remain compatible within the same minor line. Stable support requires an explicit `1.0.0` review.
+> **Preview:** `0.x` minor releases may break compatibility. Patches remain compatible within the
+> same minor line. Stable support requires an explicit `1.0.0` review.
 
-Applications initialize one engine and build models with imported functions. Generator hosts supply
-the same execution scope and own WASM initialization and native cleanup. Modeling requires no SDK
-or Testkit.
-
-## API discovery and ownership
-
-| Entry point                   | Responsibility                                                                              |
-| ----------------------------- | ------------------------------------------------------------------------------------------- |
-| `@metamesh/modeling`          | Imported modeling functions, opaque handles, output descriptors, and finalized results      |
-| `@metamesh/modeling/geometry` | Pure math, paths, profiles, regions, transforms, meshes, mechanical kernels, and SVG import |
-| `@metamesh/modeling/engine`   | Host initialization, scoped modeling, finalization, resource limits, and snapshot export    |
-| `@metamesh/modeling/text`     | Optional font-byte preparation and synchronous vector layout                                |
-
-These four entry points are the complete workspace and published API. Pure helpers cannot import
-the engine, native kernel, browser APIs, Studio, or Generators. Fontkit and WOFF2 decoding are optional
-peers used only by `/text`. Hosts own acquisition, worker lifecycle, and loading. API reports define
-supported symbols; consumer fixtures verify published use.
-
-## Modeling and lifecycle
-
-Install the package and create an engine in the application:
+## Start modeling
 
 ```bash
 pnpm add @metamesh/modeling
 ```
 
+Initialize an engine, then build and export a plate with a hole:
+
 ```ts
-import { box, cylinder, subtract } from "@metamesh/modeling";
+import { box, cylinder, generate } from "@metamesh/modeling";
 import { createModelEngine } from "@metamesh/modeling/engine";
 
 const engine = await createModelEngine();
-const snapshot = engine.build(
-  () => {
-    const body = box({ size: [30, 20, 6] });
-    const bore = cylinder({ height: 8, radius: 3, sizing: "face" });
-    return [{ id: "plate", solid: subtract(body, [bore]), color: "#67e8f9" }];
-  },
-  { resolution: { maxChordError: 0.025 } }
-);
+const model = generate<Record<never, never>>(({ part }) => {
+  const body = box({ size: [30, 20, 6] });
+  const bore = cylinder({ height: 8, radius: 3, sizing: "face" });
+  return [part("plate", { geometry: body.subtract([bore]), color: "#67e8f9" })];
+});
+const session = engine.createSession(model, { resolution: { maxChordError: 0.025 } });
+const snapshot = session.run({});
 const bytes = await engine.export3mf(snapshot.parts, { name: "Plate" });
+snapshot.dispose();
+session.dispose();
 ```
 
-The package includes the pinned Manifold JS/WASM kernel and its license, without Manifold's CLI or glTF dependency tree. Node and unbundled browser modules resolve the installed WASM automatically. Browser bundlers must retain or emit the relative asset and can pass their emitted URL explicitly:
-
-```ts
-import { box } from "@metamesh/modeling";
-import { createModelEngine, modelingWasmUrl } from "@metamesh/modeling/engine";
-
-const engine = await createModelEngine({ locateFile: () => modelingWasmUrl });
-const snapshot = engine.build(() => box({ size: [10, 20, 30] }));
-```
-
-Imported functions and `ModelingContext` methods execute the same operations. Imports do not
-initialize the kernel. The host binds the active context through a versioned symbol shared across
-bundles, then clears it in `finally`. Calls outside `build` throw.
-
-Builds are synchronous and cannot nest, including across engines in one JavaScript realm.
-Hosts finish asynchronous loading and service preparation before `build`; separate Workers have
-independent execution scopes.
-An engine rejects builds or exports while its asynchronous exporter is busy.
-
-`Solid` and `Section` are opaque immutable handles belonging to one synchronous build. Sections are
-native filled XY shapes, including holes and disconnected components. `union`, `subtract`, and
-`intersect` accept either Solid or Section operands and reject mixed dimensions. Offsets and Booleans
-retain native sections; `fromRegion` and `toRegion` are explicit conversion boundaries. Repeated
-sweeps and loft stations extract each Section once per execution; `toRegion` returns fresh immutable
-snapshots.
-
-Handles cannot cross builds or survive disposal. All native values dispose in reverse construction
-order from `finally`, including on failure. Installed bundles call host-owned methods, avoiding
-package-local native class or module identity.
-
-Builds return a bare solid (part ID `model`) or named `{ id, solid, color? }` / `{ id, mesh, color? }`
-descriptors. IDs are unique lowercase kebab-case strings of at most 64 characters; colors are
-six-digit hex RGB. Direct meshes are copied and checked for finite, nondegenerate, oriented closed
-topology and kernel reconstructability without copying them back from the kernel. Native extraction
-allows one bounded retry for collapsed Float32 stitches.
-
-Descriptors for the same Solid share one extraction, copied manufacturing buffers, and immutable
-facts. `toTriangleMesh` inspection returns independent copies; mutable mesh inputs are captured and
-validated afresh for every build. Finalized parts retain shared bounds, counts, signed volume, area,
-and topology facts. Render normals remain outside manufacturing data.
-
-Default limits are 64 parts, 1,000,000 vertices, 2,000,000 triangles, and 96 MiB of unique backing storage. Trusted applications may configure higher or lower ceilings through `createModelEngine({ limits })`. Per-build limits may only lower those configured ceilings, and snapshot export uses them too. Generator hosts own ceilings; generators receive no engine. Predictable allocations preflight safe-integer counts. Algorithm-specific numeric limits remain documented by their operations. Complexity fails explicitly instead of reducing fidelity.
-
-The same `limits` policy includes `maxPathPoints` (100,000), `maxProfilePoints` (100,000),
-`maxSweepProfilePoints` (4,096), and `maxCircularSegments` (512). Pure helpers accept explicit
-limits and use these defaults when omitted. Mesh constructors also accept the selected output
-budgets. Engines supply their configured policy to bound operations; operation limits may lower
-it. Exact samples override physical sampling without raising an allocation ceiling. Excessive
-counts fail before predictable array or mesh-buffer allocation, with required and allowed counts.
-
-SVG, text, strokes and gear outlines also honor these selected sampling ceilings. Separate SVG
-source, XML and recursion bounds, region intersection work limits, and native implicit-field
-work limits remain fixed operation safeguards.
-
-`engine.export3mf` consumes selected finalized buffers without preparation or generation. Its lazy ZIP/XML serializer preserves exact selected vertices, triangle indices, semantic part names, and optional RGB display colors without a native or glTF conversion. Hosts own revisions, appearance overrides, filenames, delivery, and persistence.
-
-Build and 3MF export accept `meshValidation: "solid"` for bounded geometric validation in addition
-to their default indexed topology checks. This rejects intersecting/touching separate shells and
-incorrectly oriented nested boundaries while preserving inward cavity shells. Checks apply to each
-part independently; separate semantic parts may intentionally overlap. It uses the same pure
-`validateSolidMesh` capability described below. Finalization reuses fresh topology facts for its
-privately owned selected buffers; export captures mutable input before fresh analysis. Within one
-operation, identical buffer ranges share checks. No caller-supplied or cross-operation facts are
-trusted. Its additional work and failure ceilings are explicit;
-the default `"topology"` mode retains the existing large-model workflow.
-
-## Resolution and conventions
-
-Primitive and pure loop factories share named options and these conventions:
-
-| Concept       | Convention                                                                                                                                                                                                                            |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Units         | Lengths are millimetres; modeling rotations use degrees. Pure transform constructors require explicit `{ degrees }` or `{ radians }`.                                                                                                 |
-| Dimensions    | `rectangle` / `rectangleLoop` take `size: number \| [width, depth]`. `circle` / `circleLoop` and `sphere` take exactly one `radius` or `diameter`. `ellipse` / `ellipseLoop` take exactly one XY `radius` tuple or full `size` tuple. |
-| Cylinders     | +Z height and exactly one `radius` or `diameter`; either a uniform scalar or `[bottom, top]` tuple. One tuple end may be zero for a cone.                                                                                             |
-| Origins       | Shapes are centered by default. `center: false` places the box/rectangle minimum corner or cylinder/tube bottom at zero. Circles, ellipses, spheres and regular polygons remain centered.                                             |
-| Radial sizing | Circle, cylinder and regular polygon `sizing` defaults to `"vertex"`; `"face"` compensates polygon faceting to reach the nominal dimension at faces. Physical clearance is separate from Boolean overtravel.                          |
-| Treatments    | Corners and supported rims share `round` (radius), `chamfer` (distance), `smooth` (tangent setbacks), and `profile` (explicit millimetre points). Offsets use lowercase `join: "round" \| "miter" \| "square"`.                       |
-| Sampling      | Exact local `segments` override physical `resolution`; selected allocation ceilings still apply. Pure circle/ellipse loops use physical defaults when `segments` is omitted.                                                          |
-
-Applicable edges, corners and supported rims share `EdgeTreatment`. `{ kind: "round", radius }`
-uses an actual circular radius; `{ kind: "chamfer", distance }` uses equal setbacks, or
-`distance: [first, second]` for unequal setbacks. `{ kind: "smooth", distance }` uses the same
-setbacks with a cubic transition whose curvature reaches zero at both straight joins.
-Its size is a setback, rather than a circular radius. Round `segments` describes a complete
-circle and must divide by four for rectangle corners; smooth `segments` is an exact cubic
-interval count. Physical cubic sampling uses chord error and segment length.
-
-Rectangles select a uniform treatment or a tuple ordered top-right, top-left, bottom-left,
-bottom-right; the tuple accepts `{ kind: "square" }`. Boxes select a uniform treatment or a map
-of named edges and groups, such as `treatment: { top: { kind: "round", radius: 1 }, bottom:
-{ kind: "chamfer", distance: 1 } }`. Groups select the four top/bottom rim edges or `vertical`
-edges; individual names include `"top-front"` and `"front-left"`. Overlapping selections fail.
-Named faces use +Z top, +Y front
-and +X right. Selected edge masks meet by intersection; they do not promise spherical three-edge
-blends. Omitted selection retains the spherical all-edge circular box treatment.
-
-`ends: { bottom, top }` independently finishes cylinder/frustum rims and straight convex
-extrusions. Cylinder rounds account for the actual sloped side's angle. Extrusion finishing
-requires one strictly convex contour without holes, twist, top scaling or divisions. Inward
-parallel offsets preserve its original edge correspondence; disappearing/reversed edges fail.
-Use explicit loft profiles for concave or holed transitions.
-
-Custom `{ kind: "profile", profile }` treatments use exact sampled points from `[positive, 0]`
-to `[0, positive]`, with decreasing first and increasing second coordinates. These are setbacks
-along the two inward surface directions, in millimetres. Cylinder/extrusion ends use cap inset
-first and side setback second. Rectangle corners follow the incoming and outgoing CCW edges.
-For a named box edge, the first coordinate lies on the first named face and the second on the
-second named face. Samples are captured per call, checked for fit and bounded before allocation;
-no analytic curve or outward moulding is inferred. Ordinary curve helpers can prepare the points.
-
-Primitive `placement: { source, target, ... }` maps a named or explicit local anchor onto a world
-anchor, with optional alignment, gap and degree spin. Placement follows local construction,
-including `center`; Section placement must preserve the XY plane.
-
-Rectangle round radii may vary from zero (square corners) through half the smallest dimension
-(a capsule or circle). Saturated tangent endpoints are emitted once. Uniform rectangle chamfers
-and all-edge box rounds/chamfers require positive sizes smaller than half every dimension.
-Selected box treatments must leave positive flat space between opposing setbacks.
-
-Authored box, cylinder/frustum, tube, sphere, torus, rectangle, circle and ellipse handles know
-`center`, `left`, `right`, `back`, `front`, `bottom` and `top` anchors. `left/right` follow −X/+X,
-`back/front` follow −Y/+Y and `bottom/top` follow −Z/+Z. Regular polygons and stars provide `center`.
-These are nominal construction datums: sampling and finishing do not move them; tube cap and torus
-axial centers may lie over an opening. A cone omits the cap anchor at its zero-radius apex.
-`anchor(shape, name)` reads its immutable frame, and `attach(pin, "bottom", anchor(base, "top"))`
-mates opposed directions by default. Affine transforms and patterns carry positions, outward
-normals and roll tangents with the shape, including nonuniform scaling and reflection.
-
-`withAnchors(shape, { mount: createAnchor3(position, direction, up) })` returns a new same-kind handle
-with copied definitions, retaining existing names unless replaced. Each shape supports at most 128
-lowercase kebab-case names of at most 64 characters. Looking up an absent name reports the available
-names. Shape lookup requires the exact active build; the returned `Anchor3` is copied plain data.
-Boolean and other geometry construction results require deliberate definitions rather than
-inheriting anchors that may no longer describe their surfaces. Custom rigid frames remain useful;
-pure `boxAnchor3` and `cylinderAnchor3` calculate dimension-based frames without a native shape.
-
-`GeometryResolution` defaults to 0.05 mm maximum chord error and 16–512 segments per complete circle.
-Precedence is exact local segments, operation resolution, context-derived resolution, then engine
-defaults. Exact counts express deliberate faceting or fixed correspondence; adaptive curves retain
-physical deviation and edge-length constraints.
-
-`model.withResolution(policy)` and imported `modelingFunctions(policy)` return a local method set
-for the same build. Destructure those methods to apply the local policy; other imports retain the
-original build policy. There is no global resolution or font state.
-
-Revolution `segments` describes a complete circle; partial revolutions scale that count to the
-angular span and round up. Native filled revolutions need at least three intervals: adaptive
-sampling refines to that minimum, while exact counts below it fail explicitly. Pure `revolveMesh`
-supports one interval.
+Constructors and fluent shape methods declare immutable recipes inside synchronous generation.
+Use shape methods for transforms, subtraction, and finishing; collection operations such as
+`union`, patterns, and observations remain functions. Calls apply in written order about the origin.
+A method preserves its input; no-op operations may reuse a handle. A session owns optional
+computed caches; captured snapshots stay usable after the session is disposed. Keep the finalized
+snapshot for rendering or export, then dispose it. For browser WASM setup and host lifecycle, follow
+[Run Modeling in your application](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/engine/hosting.mdx).
 
-`resamplePolyline2` and `resamplePolyline3` share physical sampling options and return immutable
-points with directed unit tangents. Open paths retain both endpoints; `closed: true` includes the
-closing edge and omits a repeated seam vertex. Exact closed counts require at least three segments.
+## Reuse unchanged work
 
-`regularPolygonLoop({ radius, sides, rotationDegrees, sizing })` creates a centered CCW point loop
-with an implicit seam. `RadialSizing` defaults to `"vertex"`; `"face"` compensates polygon faceting
-so the requested radius reaches the faces. `CylinderOptions` uses the same sizing option.
-
-`normalizeLoop2`, `normalizePolygon2`, and `normalizeRegion2` return immutable geometry and may reuse internally validated results. External objects are validated even when frozen. Mutable mesh buffers are analyzed freshly at external boundaries; engine facts are reused inside their owner.
-
-## Profiles and mechanical construction
-
-`sampleOpenProfile` samples upward radius/height line and cubic chains. Consumers own closure and
-product constraints. `sampleCrossSection` samples 2–32 explicitly closed XY line/cubic segments
-after positive width/height scaling, using the shared physical curve policy. It returns one
-immutable CCW loop without a repeated seam, rejecting sampled self-intersections, zero area,
-nonfinite coordinates, and exhausted budgets. Its default unique vertex ceiling is the smaller of
-4096 and `limits.maxProfilePoints`; each segment also obeys `limits.maxPathPoints`. It accepts plain
-curve coordinates without an SDK dependency, editor modes, or a normalized-range requirement.
-`circleLoop`, `rectangleLoop`, and other point factories return ordered loops.
-`Profile` owns identified components, contours, and landmarks; `CorrespondingProfile` retains their
-shared sampled slots.
-
-`rectangle`, `rectangleLoop`, and `rectangleProfile` share `size`, `center`, and `treatment` options.
-Use root primitives for ordinary modeling and pure loops/profiles for custom data and explicit
-correspondence. Native filled sections do not promise stable vertex ordering.
-
-For a closed planar XYZ path, map the canonical loop with
-`rectangleLoop(options).map(([x, y]) => [x, y, 0] as const)`. Before sampling, cap its
-`limits.maxProfilePoints` at the smaller selected profile and path point ceilings. This keeps
-path allocation bounded and preserves all corner tangent endpoints and the implicit seam.
-
-### Extrusion and sweep
-
-`extrude(shape, { height, ... })`, `revolve(shape, options)` and `sweep(shape, path, options)` accept a filled Section or CorrespondingProfile, including holes and disconnected components. Open sweeps have watertight end caps; `closed: true` joins the path back to its beginning. Sweep options share degree twist, positive uniform or XY scale, and an XY scale pair per normalized path station. Closed scales interpolate along the implicit closing edge. A rotational symmetry seam uses `seamProfileOffset`, a counterclockwise logical point advance that reverses for clockwise hole contours; every contour must geometrically match the total twist. Incompatible seams fail explicitly.
-
-Adaptive extrusion sampling bounds the entire side triangles, including the interaction between
-profile edges, twist and unequal top scaling. `resolveExtrusionDivisions(profile, height, options)`
-accepts a `Loop2` or filled `Region2` and measures every outer and hole edge; it is an optional estimate
-using the same policy as construction. Exact `divisions` and deliberate angular counts retain their
-precedence. Tight physical requests reject at selected sampling or output ceilings.
-
-Nonzero sweep twist inserts stations according to `resolution`, including the deviation of side
-triangles across profile edges. A full turn on a two-point path remains a full turn. Original
-path stations retain their scales, twist progression and orientation-guide indices; `twistBy`
-defaults to `"length"`, so angular progression follows physical path travel, including the implicit
-closing edge. Choose `"stations"` for a deliberately authored station schedule. Inserted
-stations interpolate centers, scales and shortest frame rotations. Guides run once per original
-normalized station. Zero twist preserves the supplied path's existing mesh sampling. Explicit
-`resolution.circularSegments` selects deliberate angular faceting; allocation ceilings still
-apply. Adaptive scale changes can require subdivisions independently of angular travel; those
-gaps use the selected full-curve interval ceiling. Refinement checks path and mesh budgets before
-allocating the added station arrays.
-
-Sweep `orientation` is one explicit policy shared by pure, filled, open and closed construction:
-`{ kind: "transport", initialNormal? }` (default), `{ kind: "fixed-normal", normal }`,
-`{ kind: "guide", normal: (point, index) => vector }`, or `{ kind: "frenet" }`. Transport minimizes
-rotation and initially projects +X, then +Y, then +Z when no preference is supplied. A preferred
-normal sets profile X; fixed and guide normals remain directed and project perpendicular to each
-local tangent. Guide signs are preserved. Frenet uses projected neighboring sampled tangent changes
-as curvature normals. Zero curvature and parallel explicit normals reject instead of switching
-policies. For a planar closed path whose profile X should stay vertical, request
-`orientation: { kind: "transport", initialNormal: [0, 0, 1] }`. Closed policies use cyclic tangents
-and the same first frame on their closing gap.
-
-### Loft correspondence
-
-`loft(stations, options)` accepts a `profile` and exactly one horizontal `z` height or explicit
-right-handed `frame` per station. Stations stay in input order. Ordinary primitives keep the
-simple case at the root entry point:
-
-```ts
-import { circle, loft, rectangle } from "@metamesh/modeling";
-
-export function build() {
-  return loft([
-    { profile: circle({ diameter: 20 }), z: 0 },
-    { profile: rectangle({ size: [30, 15], treatment: { kind: "round", radius: 3 } }), z: 40 },
-  ]);
-}
-```
-
-With omitted `correspondence`, compatible rectangle stations, circle/ellipse rings, equal-sided
-regular polygons and equal-pointed stars use their retained authored landmarks. Rectangle corners
-can change among square, round and chamfer treatments, including collapsed or saturated rounds.
-Circle/ellipse and rectangle stations also share those quadrant/corner landmarks: a circular
-inlet can become a rounded rectangle directly.
-Exact circular counts for this mixed family must divide by four; other deliberately faceted counts
-need an explicit geometric method. Adaptive counts align upward within the selected ceilings.
-XY affine transforms preserve these identities; this semantic path requires consistent handedness.
-Other unlike retained primitive families use direct perimeter subdivision from their construction-local
-+X ray seam. Every physical input vertex remains, including corner tangent endpoints. Retained
-curves use the selected loft resolution under every method, accounting for transform magnification.
-Exact primitive samples preserve deliberate faceting; `refine` can deliberately add collinear density.
-When an exact primitive is paired with a finer member, a shared union of parameter knots retains
-its original polygon and inserts only collinear points on its facets. Adaptive members retain
-physical curve sampling. Circle face sizing uses the actual minimum facet support from the local
-origin, so collapsed slots, unequal quarter counts and collinear refinements preserve nominal clearance.
-
-Boolean, offset and import operations discard primitive identity. Their Sections and plain point
-loops require an explicitly selected correspondence method. This choice associates ordered
-contours by component and hole index; it does not identify arbitrary components or repair changed
-topology. Use identified profiles when those identities matter. Explicitly choosing a method on
-known primitives also runs that geometric method, rather than substituting semantic matching.
-
-| `correspondence`  | Association                                                                                                                             |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `"direct"`        | Preserve each seam and subdivide edges to a common count without dropping vertices.                                                     |
-| `"reindex"`       | Direct subdivision, then choose the next contour's cyclic phase with the least total world-space connection length.                     |
-| `"fast-distance"` | Keep the supplied seams and minimize connection length over ordered closed vertex associations, repeating vertices for triangular fans. |
-| `"distance"`      | The same ordered optimization over every cyclic phase of the next contour.                                                              |
-
-One method applies to every gap; an array supplies one per gap. `distribution` defaults to
-`"perimeter"` for direct/reindex and `"segments"` when any distance method is present. It controls
-where extra subdivisions go; distance methods require segments. `refine` is a positive integer
-multiplier, uniformly or per input profile. `slices` is a nonnegative intermediate-profile count,
-uniformly or per gap. Slices interpolate the corresponding placed world vertices, never frame axes.
-Insertions propagate across a shared grid, so mixed methods retain each middle profile without
-T-junctions. Phase ties keep the earliest phase; ordered optimization prefers diagonal, previous-only,
-then next-only advances. Its objective sums connection lengths with the closing seam counted once.
-No tangent/supporting-plane association is exposed: general concave and spatial stations do not
-provide the convexity contract that such a method needs.
-
-Identified `ProfileSpan2` supports lines, arcs, and cubic Béziers with `start`, `control1`, `control2`,
-and `end`. Cubics reuse the curve evaluator and physical subdivision policy, selecting one uniform
-parameter grid for corresponding spans. Fully collapsed spans retain logical slots without moving
-endpoints. Sampled contours and components use `CorrespondingContour` and `CorrespondingComponent`.
-Pass the complete family to `matchProfiles` with optional `limits.maxProfilePoints`; its default is
-100,000 points per profile, while a separate one-million-slot family work bound remains in force.
-
-For precise custom correspondence, prepare `matchProfiles` over explicit `Profile` specifications.
-It chooses the maximum physical interval count for each paired span across the family, including
-span-local `resolution`; identified line, arc and cubic kinds may change while IDs, order and
-connected endpoints remain valid. `CorrespondingProfile` landmarks are authoritative, so geometric
-remapping methods are rejected; direct refinement preserves every paired slot. `rectangleProfile`
-is the canonical identified rectangle factory. Changed IDs, winding or filled topology fail.
-Lofting merges coincident world vertices, omits degenerate faces and triangulates hole caps natively.
-
-All loft routes share `LoftOptions`. Pure `loftMesh` requires an explicit method and returns a
-closed simple-loop mesh without an engine. Selected sampling/output budgets apply before expanded
-grids and mesh buffers; fixed aggregate safeguards bound correspondence at eight million comparisons
-and the complete grid at one million logical slots. Simple-loop cap triangulation also has an
-eight-million-comparison work ceiling. Caps whose minimum comparison count exceeds that ceiling
-reject before ear clipping; other caps retain the running work check. Complexity rejects instead of
-reducing fidelity or substituting another method. Pure counterparts also include `sweepMesh`,
-`extrudeMesh` and `revolveMesh`.
-
-### Patterns and bounded surfaces
-
-`linearPattern(shape, { count, length })` determines equal intervals from exactly two of `count`,
-signed `spacing`, and signed total `length`; its direction defaults to +X. Length and spacing must
-fit a whole interval count. `gridPattern(shape, { count: [3, 2], spacing: [10, 8] })` supports XY
-or XYZ tuples, optional centering and an explicit frame; X varies fastest. `pathPattern(shape,
-path, { count })` distributes copies by physical arc length, including both endpoints for open
-paths and omitting a repeated closed seam. Its optional `orientation: "tangent"` aligns local +Z
-to the containing segment by the shortest rotation from world +Z (a -Z tangent uses a +X half turn);
-the default preserves source orientation. These placements transform the source's local origin.
-All four pattern families, including `radialPattern`, accept a same-build Solid or an `(index) =>
-Solid` factory for per-copy variation. Factories run once in ascending index order. The 100000-copy
-algorithm ceiling and selected output budgets reject before predictable native copy allocation;
-varying factories are checked cumulatively before each transform. Path input and placement counts
-also obey `maxPathPoints`. Copies use the shared transform and lifetime checks.
-
-`heightfield` returns a Solid for transforms and booleans; `heightfieldMesh` returns the same
-closed construction as pure indexed data. Supply `size`, `segments`, and optional `origin` for a
-uniform grid, or `coordinates: { x, y }` for absolute, unevenly spaced XY samples. Explicit axes
-must increase strictly and remain distinct in Float32. This lets callers refine narrow borders
-without remapping mesh vertices. Heights remain absolute Z values strictly above `baseZ` (default
-zero); sampling never rescales the field.
-
-`triangulation` defaults to `"fixed"`, preserving the lower-left to upper-right diagonal.
-`"min-edge"` chooses the shorter 3D diagonal without extra sampling. `"center-error"` samples the
-physical cell centre once and chooses the diagonal whose interpolated height is closer there.
-Ties retain the fixed diagonal. Every policy uses two top triangles per cell and the same closed
-walls and flat base; centre agreement does not guarantee accuracy elsewhere. Allocation and
-coordinate precision are checked before height callbacks. Each grid point is sampled once, with
-one additional callback per cell for `"center-error"`.
+Caching is optional. A named computation tracks parameter and other computation reads; part
+placement and color stay separate from its geometry:
 
 ```ts
-heightfield({
-  coordinates: { x: [-15, -14.5, 0, 14.5, 15], y: [-10, -9.5, 0, 9.5, 10] },
-  triangulation: "min-edge",
-  height: ([x, y]) => 3 + Math.cos(x / 5) * Math.cos(y / 5),
+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] })];
 });
 ```
 
-Pure mechanical modules own thread profiles, sampling, printable fit, meshes, and allocation-free `preflightThreadedRod`, `preflightInternalThreadCutter`, and `preflightThreadedNut`. Engine methods own native construction. `pitch` is adjacent axial spacing; `lead = pitch × starts` is advance per turn. Internal cutters extend beyond requested faces and compensate faceting while preserving end treatments. Printable modeling forms are not certified thread classes or structural ratings.
+Changing `gap` reuses the body's validated geometry. Changing `height` recomputes it. Computations
+are pure and synchronous: bind changing locals explicitly with `computed(id, { value }, inputs => ...)`.
 
-`split(solid, cutter)` returns intersection followed by subtraction as two same-build handles.
-`splitByPlane(solid, { normal, offset })` returns the positive-normal side followed by the negative
-side. Destructure `[positive]` or `[, negative]` to retain just one side. The nonzero normal is
-normalized and `offset` is the signed distance from the world origin in millimetres (default zero).
-Empty results are valid handles
-for `isEmpty`, inspection and further operations, but cannot be finalized as manufacturing parts.
+Capture cached numeric arrays with `immutableBuffer(values)`: read `length` or `at(index)`, and
+call `copy()` for an owned mutable typed array. Capture cached meshes with `immutableMesh(mesh)`
+and pass their readers directly to `part`. Computed results and bindings reject raw typed arrays;
+ordinary transient mesh inputs, snapshots, and Worker output still use normal typed arrays.
 
-`hull` accepts Solid inputs/XYZ points or Section inputs/XY points. `components` and `simplify`
-also preserve either dimension. Solid components are disconnected surface shells: inward cavity
-shells count separately in `inspectSolid().parts` and cannot be finalized alone. Section components
-are filled islands that retain their holes. `inspectSolid` includes surface area, native tolerance and emptiness;
-`inspectSection` includes emptiness. Both return immutable native facts shared by repeated
-inspections of the same shape within one build, including aliases and derived resolution contexts.
-Transforms, Booleans and tolerance changes have their own facts. The execution clears these caches
-on disposal; retained facts contain no live native values.
+The optional session setting `verifyCache: true` reruns callbacks on cache hits and compares bounded
+data and recipes to diagnose observable missing dependencies. It can reject unsupported or large
+comparisons and cannot prove arbitrary JavaScript; production caching leaves this probe disabled.
 
-`distance(a, b)` measures the minimum separation between two nonempty solids in millimetres.
-It returns zero for contact or overlapping material. The kernel's search range is managed internally;
-there is no caller-supplied distance cutoff. Queries use native geometry and precision without
-extracting a triangle mesh; empty, expired and foreign-build handles reject.
+For expensive geometry followed by adjustable cuts or Booleans, put the base and finishing stage
+in separate computations. Sessions can retain the evaluated base privately, preserving native
+precision when it becomes an operand in a later run. Retention is bounded and optional; eviction
+rebuilds the original recipe. Clear or dispose the session to release retained native geometry.
 
-Installed Generators using these added host operations or Section overloads declare minimum runtime
-2.1.0. Imported operations require the current host context; package metadata declares the runtime
-capabilities the Generator uses.
+Use `assert(condition, message)` for a constraint that stops the revision and `warn(message)` for
+nonblocking guidance. Hosts bind prepared deterministic capabilities through session `services`.
+`validateModel` checks declarations and reached assertions without initializing a kernel; checks
+that observe geometry use an initialized session's `validate` method.
 
-`implicit` samples a finite positive-inside field within explicit bounds and grid spacing. Grid allocations and field evaluations are bounded. `components` returns same-build handles. `simplify` requires explicit millimetre tolerance and preserves native original-surface cleanup semantics.
-
-## Prepared text and SVG
-
-Preparation shapes text once with the host's exact font service and retains immutable `VectorTextLayout`. Imported `textSection(layout, options)` consumes vector paths directly, without font shaping, fetching, or ambient providers. Paths and metrics use Y-up millimetres and a baseline origin. Empty layouts are measurable but cannot create sections. Font preparation remains optional and outside synchronous builds.
-
-`baseline: { kind: "arc", radius }` places one line on a circle centered at the XY origin, in millimetres. Alignment defaults to `"center"` at `centerAngleDegrees` (90° from +X by default); `"left"` and `"right"` place the logical start and end at that datum. Direction defaults to `"clockwise"`, giving upright top lettering at 90°; `"counterclockwise"` at 270° gives upright bottom lettering. Shaped glyphs and attached zero-advance marks rotate rigidly, preserving their proportions, kerning and ligatures. Exact ink bounds describe the placed curves; `logicalWidth` and `advance[0]` retain the unwrapped arc length including spaces. Radius must be positive and at most 10000 mm. Arcs require baseline vertical alignment and reject multiline text, logical spans of a full revolution, and glyph outlines crossing the circle's center axis. Adjacent glyph collision and fit within a particular face remain consumer policy.
-
-Install `fontkit` to use `prepareVectorFont` from `/text`, and `woff2-encoder` when decoding WOFF2. These optional peers are loaded only when preparing fonts. `sampleTextContours` from `/geometry` and `textSection` share bounded path sampling and need no font dependencies for an already prepared layout.
-
-`svgSection` imports bounded painted SVG documents; `svgPathSection` imports filled path data. Y-down coordinates convert to Y-up; nonzero/even-odd filling preserves counters. Sampling applies after transforms and unit conversion. Basic shapes, groups, affine transforms, physical units, viewBox, fills, and strokes are supported. Text must be outlined. External resources, scripts, clipping, masks, filters, and unsupported content fail contextually. Pure parsers are shared with validation and the vector editor.
-
-Zero-alpha colors and zero-opacity paint channels contribute no geometry. Positive alpha contributes
-the full painted region; presentation transparency does not reduce its physical area.
-
-## Final triangle topology
-
-`analyzeTriangleMesh` validates and supplies bounds, counts, area, and signed volume in one traversal, with optional edge/component facts. Measurements, bounds, and signatures are independent immutable snapshots; external mutable buffers are inspected freshly on each call. Closed-edge checks require two oppositely wound faces per edge; they do not detect every geometric self-intersection. `createTriangleMeshSignature` adds quantized bounds, volume, topology, and a regression fingerprint, not a cryptographic digest.
+## API discovery and ownership
 
-Pure `validateSolidMesh(mesh, options)` adds spatial triangle tests, a single closed incident fan at
-every vertex, and shell containment/orientation checks, including cavity boundaries and islands.
-It never repairs or changes input buffers.
-Floating-point contacts within the selected `tolerance` reject conservatively; this is not an exact
-predicate or a manufacturing certification. Its fixed ceilings are 200,000 triangles and 2,000,000
-spatial/containment tests. `maximumTests` may lower the work ceiling. Exhaustion throws
-`COMPLEXITY_LIMIT` and never returns an unchecked result. All position vertices must be referenced.
+| Import                                                                                                                                      | Use it for                                                          |
+| ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| [`@metamesh/modeling`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/model/index.mdx)             | Fluent solids and sections, constructors, and collection 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                        |
 
-`computeTriangleMeshCentroid(mesh)` returns an immutable uniform-density volume centroid in
-millimetres for consistently oriented closed geometry, accounting for inward cavity shells.
-It checks indexed closure and positive aggregate volume; use solid validation first for untrusted
-geometric shell arrangements.
+## Documentation
 
-The optional `meshTopologyMode: "optimized"` build setting runs bounded planar edge flips for either
-execution lane. It preserves vertices, boundaries, winding, closure, reconstructability, area, and
-volume. This is local connectivity cleanup, not general remeshing; source buffers never change in place.
+- [Geometry concepts](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/geometry-package.mdx) — modules, coordinates, resolution, and supported modeling paths.
+- [Geometry recipes](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/geometry-recipes.mdx) — worked examples for primitives, sweeps, lofts, and repeated parts.
+- [Font preparation](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/engine/fonts.mdx) — supply exact font bytes outside Studio.
 
-Models above 200,000 triangles skip optimization. Unsupported or failed candidates retain their
-original part, as do models whose optimized buffers would exceed an execution ceiling. Equal shared
-mesh views reuse one optimized candidate.
+The public docs are being prepared for `https://metamesh.studio/docs`. Until launch, use the
+repository links above or [run Web locally](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/README.md#local-use). Exact options,
+constraints, and examples live in source docblocks and the API reference generated from them.
 
-## Quality gates
+## Contributing
 
-Follow the [workspace instructions](https://github.com/JasonKoolman/metamesh/blob/main/packages/modeling/AGENTS.md#verification) for required checks. Timing and sampled process memory are diagnostics, not deterministic assertions or WASM heap measurements. The [publication contract](https://github.com/JasonKoolman/metamesh/blob/main/docs/continuous-delivery.md#public-library-publication) owns tarballs, clean standalone Node/Worker consumers, and release identity. Installed dependency size and browser bundles are measured separately; ZIP serialization and optional font dependencies load only through their capabilities.
+Start with [Update the Modeling API](https://github.com/JasonKoolman/metamesh/blob/main/docs/guides/update-the-geometry-api.md) and the
+[workspace instructions](https://github.com/JasonKoolman/metamesh/blob/main/packages/modeling/AGENTS.md) for checks and reference generation. Internal dependency and
+execution boundaries live in [architecture](https://github.com/JasonKoolman/metamesh/blob/main/docs/architecture.md#modeling-library-and-execution).
 
 ## License
 
-Apache-2.0. Bundled offline artifacts also carry `THIRD_PARTY_NOTICES.md`.
+Apache-2.0; see [LICENSE](https://github.com/JasonKoolman/metamesh/blob/main/packages/modeling/LICENSE) and [THIRD_PARTY_NOTICES.md](https://github.com/JasonKoolman/metamesh/blob/main/packages/modeling/THIRD_PARTY_NOTICES.md).