@metamesh/modeling 0.17.0 → 0.19.0

package/dist/docs/guides/fundamentals.md

@@ -6,8 +6,8 @@ Build parts by combining primitives, applying transforms, and removing material
 MetaMesh uses [Manifold](https://manifoldcad.org/docs/jsapi/), a solid-modeling kernel that works
 with **manifold meshes**: closed, consistently oriented boundaries representing solid material.
 
-Studio code Projects use `@metamesh/modeling` to construct immutable `Section` and `Solid` recipes.
-The engine evaluates them and owns the underlying kernel values.
+In a Studio code Project, `@metamesh/modeling` describes your shapes as immutable `Section` and
+`Solid` recipes. The engine builds their geometry and takes care of the underlying kernel values.
 
 ## Coordinates and units
 
@@ -15,8 +15,8 @@ MetaMesh uses a right-handed coordinate system with **+Z up**. Model dimensions
 Place a part intentionally around the origin, then use transforms or anchors to relate it to other
 parts.
 
-Transform methods preserve the input and return immutable geometry recipes, so you can name
-meaningful stages and reuse a source shape without tracking hidden state.
+Transforms leave the original shape unchanged. Keep a base shape, give each stage a useful name,
+and reuse the same base for several features.
 
 ## Build solids compositionally
 
@@ -33,7 +33,7 @@ export default generate(({ part }) => {
   // Primitives are centered by default, so both faces get 2 mm of overtravel.
   // Overtravel is for robust subtraction; it does not enlarge the hole diameter.
   const hole = cylinder({ height: 8, radius: 3 });
-  return [part("model", plate.subtract([hole]))];
+  return [part("model", plate.subtract(hole))];
 });
 ```
 
@@ -42,16 +42,18 @@ The cylinder clears both faces of the plate, leaving a through-hole without coin
 
 
 The plate is centered about the origin. Its `4 mm` thickness occupies `Z = −2…2 mm`; the cutter
-occupies `Z = −4…4 mm`. That overtravel makes the subtraction deliberate while the hole radius
-stays `3 mm`. Derive cutter placement from the same datum as the body when changing dimensions.
+occupies `Z = −4…4 mm`. Extending the cutter beyond both faces makes a clear through-cut while the
+hole radius stays `3 mm`. Use the body's datum to place the cutter so they stay aligned when
+dimensions change.
 
 Name intermediate solids by their purpose. Arrange independent repeated cutters first, then
-subtract them together where possible. Many high-resolution Boolean steps increase generation
-time and obscure design intent.
+subtract them together where possible. Many high-resolution Boolean steps take longer to build
+and make it harder to see what each step contributes.
 
-The `union` and `intersect` functions and `shape.subtract(cutters)` also combine filled Sections
-in XY. Choose one dimension for every operand in a call. Keep a Section native through its Boolean
-and offset steps, then chain `.extrude({ height })` or `.revolve(options)` to make a Solid.
+The `union`, `subtract`, and `intersect` methods accept one shape or an array and also combine
+filled Sections in XY. Use collection `union(shapes)` and `intersect(shapes)` when combining peers.
+Use either Sections or Solids throughout each call. Keep an outline as a Section while
+combining and offsetting it, then chain `.extrude({ height })` or `.revolve(options)` to make a Solid.
 Transforms apply in written order about the origin: translating then rotating also rotates the
 translated position. Place finished parts through `part` options when their geometry can be reused.
 
@@ -63,7 +65,7 @@ the final translations separate the results for comparison.
 
 
 ```ts
-import { box, cylinder, intersect, union } from "@metamesh/modeling";
+import { box, cylinder, transform3 } from "@metamesh/modeling";
 import { generate } from "@metamesh/project";
 
 export default generate(({ part }) => {
@@ -72,15 +74,15 @@ export default generate(({ part }) => {
   // Reuse the same overlapping operands to compare the three operations.
   // Place finished parts separately so display spacing can reuse their geometry.
   return [
-    part("union", { geometry: union([block, tool]), color: "#60a5fa" }),
+    part("union", { geometry: block.union(tool), color: "#60a5fa" }),
     part("difference", {
-      geometry: block.subtract([tool]),
-      position: [42, 0, 0],
+      geometry: block.subtract(tool),
+      transform: transform3().translate([42, 0, 0]),
       color: "#f59e0b",
     }),
     part("intersection", {
-      geometry: intersect([block, tool]),
-      position: [84, 0, 0],
+      geometry: block.intersect(tool),
+      transform: transform3().translate([84, 0, 0]),
       color: "#34d399",
     }),
   ];
@@ -91,11 +93,11 @@ Left: all material from union. Center: block material outside the tool. Right: m
 
 
 
-| Operation                                                | Material retained                     | Common use                                               |
-| -------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------- |
-| [`union`](../reference/model/union.md)                   | Inside any operand                    | Join an overlapping boss or rib to a body                |
-| [`shape.subtract`](../reference/model/Solid.md#subtract) | Inside the base, outside every cutter | Cut holes, pockets, and clearance envelopes              |
-| [`intersect`](../reference/model/intersect.md)           | Inside every operand                  | Trim a feature to an envelope or isolate shared material |
+| Operation                                                  | Material retained                     | Common use                                               |
+| ---------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------- |
+| [`shape.union`](../reference/model/Solid.md#union)         | Inside any operand                    | Join an overlapping boss or rib to a body                |
+| [`shape.subtract`](../reference/model/Solid.md#subtract)   | Inside the base, outside every cutter | Cut holes, pockets, and clearance envelopes              |
+| [`shape.intersect`](../reference/model/Solid.md#intersect) | Inside every operand                  | Trim a feature to an envelope or isolate shared material |
 
 Use intentional overlap for joined features and overtravel for through-cutters. A face or point
 that only touches another feature is not a reliable connection for a manufacturing part. Inspect
@@ -103,7 +105,7 @@ the result when thin walls, tangencies, or disconnected components are possible.
 
 ## Valid solid does not mean manufacturable part
 
-The kernel can enforce solid topology, but it does not know your printer, material, load case,
+The kernel can enforce solid topology, but it doesn't know your printer, material, load case,
 tolerance stack, minimum wall, overhang strategy, or fit target. Encode supported input limits and
 cross-field errors in the Project, then verify the exported file in its downstream tool.
 
@@ -111,12 +113,11 @@ Empty or zero-volume output is invalid; non-empty output still needs engineering
 
 ## Geometry ownership
 
-`Section` and `Solid` values are immutable recipes. Evaluating them creates native resources
-owned and cleaned up by Studio. Do not initialize the kernel or manually delete shapes in
-`model.ts`.
+Studio creates and cleans up the native resources needed to evaluate your `Section` and `Solid`
+recipes. Don't initialize the kernel or manually delete shapes in `model.ts`.
 
-Use `inspectSection()` or `inspectSolid()` for measurements such as bounds, area, volume, and
-`componentCount`. `components()` returns disconnected material pieces, preserving holes and
+Use `shape.inspect()` for measurements such as bounds, area, volume, and
+`componentCount`. `shape.components()` returns disconnected material pieces, preserving holes and
 enclosed cavities. A sealed hollow box is one component; adding a loose ball inside its cavity
 makes two. Recombining the pieces preserves the original material.
 

package/dist/docs/guides/generation.md

@@ -1,16 +1,17 @@
 # Code Project contract
 
-Understand Studio’s TypeScript source contract, computed caches, parts, resource ownership, and recovery.
+Learn how Studio runs your TypeScript model, reuses work across edits, and keeps a preview available when an edit fails.
 
-An authored Project has one control definition and one TypeScript entry file. Studio supplies the
-compiler, prepared services, modeling engine, persistence and preview.
+An authored Project has one control definition and one TypeScript entry file. You write the model;
+Studio compiles it, prepares services, runs the modeling engine, saves the Project, and shows the preview.
 
 ## Source boundary
 
 Keep helpers in the single editable `model.ts` file. Import modeling operations from
-`@metamesh/modeling`, pure utilities from `@metamesh/modeling/geometry`, and the typed
+`@metamesh/modeling`, pure utilities from `@metamesh/modeling/geometry`, mesh operations from
+`@metamesh/modeling/geometry/mesh`, and the typed
 `generate` helper from `@metamesh/project`. These approved modules and declarations work offline.
-Source cannot install packages, fetch modules or initialize another kernel.
+Source can't install packages, fetch modules, or initialize another kernel.
 
 ## Start with generate
 
@@ -31,9 +32,12 @@ export default generate(({ params: parameters, part }) => {
 
 The helper infers `params` from **Model controls** as readonly numbers, strings, and structured
 values. Import `type Parameters` from `@metamesh/project` when a separate helper needs the type.
+Parameters and memo results use `ImmutableValue<T>` views: nested objects, arrays, and tuples
+are readonly in TypeScript and frozen when captured at runtime. Create a copy for editable working
+data. Fluent Modeling methods and explicit buffer `copy()` calls retain their normal return types.
 
-The outer callback runs for each edit. Return a single `part(...)` or a readonly array of parts;
-`computed` is optional.
+The outer callback runs for each edit. Return a single `part(...)` or a readonly array of parts.
+You can add `memo` when you need it.
 Export only the default program; keep helpers local to `model.ts`. Definitions and presets remain
 serializable metadata. There are no separate preparation/build exports.
 
@@ -55,9 +59,10 @@ assert(
 
 
 
-Assertions follow normal code order. Put cheap checks before costly reads. An assertion that reads
-geometry must evaluate that geometry first. Warnings belong in the outer callback; assertions can
-also run inside computed values, whenever that computation evaluates.
+Assertions follow normal code order. Put cheap checks before costly reads so invalid dimensions
+can stop the work early. An assertion that reads geometry must evaluate that geometry first.
+Warnings belong in the outer callback; assertions can also run inside a memo helper when it
+evaluates. Pass the full generation context to a helper that needs `assert` or fixed services.
 
 ## Reuse unchanged work
 
@@ -65,78 +70,90 @@ also run inside computed values, whenever that computation evaluates.
 
 **Caching is optional**
 
-Start with ordinary generation code. If parameter edits become slow, add `computed` around
-  expensive work that can stay unchanged across edits. Cheap arithmetic and part placement usually
-  do not need caching.
+Start with ordinary generation code. If parameter edits become slow, add `memo` around expensive
+  work that can stay unchanged across edits. Cheap arithmetic and part placement usually do not need
+  caching.
 
 
 
-`computed(id, callback)` creates a lazy reader of cached data or geometry. Calling it evaluates the
-calculation when needed; passing it directly to `part` defers evaluation until the outer callback
-succeeds. **Read `params`, derive values, and destructure inside the computed callback.** These
-reads are tracked automatically, including reads made by synchronous helpers called there:
+`memo(fn, ...args)` calls a synchronous helper and returns its immutable result directly. Repeated
+calls with the same function and unchanged inputs can reuse that result. Define helpers at module
+scope so their identity stays stable between generations.
+
+Pass the exact `params` object when a helper needs several parameters. MetaMesh tracks the fields
+read while the helper runs, including reads made by synchronous helpers it calls:
 
 
 
 ```ts
-const body = computed("body", () => {
-    const { width, height } = params;
-    return box({ size: [width, 10, height] });
-  });
+function buildTrackedBody(params: Readonly<Parameters>) {
+  const { width, height } = params;
+  return box({ size: [width, 10, height] });
+}
 ```
 
 
 
-Call other computed readers inside the callback too: `computed("finished", () => base().subtract(...))`
-tracks the base result automatically. In **New project → Cached panels**, changing **Gap** only
-moves the second panel; changing **Notch width** reuses the hole pattern for the finishing cut.
+You can also pass ordinary arguments, just as you would call the function normally. These are the
+function's inputs, not a separate dependency declaration:
+
+
+
+```ts
+function buildBody(width: number, height: number) {
+  return box({ size: [width, 10, height] });
+}
+```
+
+
 
-An earlier read such as `const { height } = params` captures a snapshot. Using it inside a
-computation does not track the parameter and can reuse stale geometry. Move the read inside the
-callback. If a changing value must be prepared outside, such as a loop item, list it in the optional
-third argument:
+Inside `generate`, both forms return values ready for `part` or the next memo:
 
 
 
 ```ts
-const { height } = params;
-  const capturedBody = computed("captured-body", () => box({ size: [params.width, 10, height] }), [
-    height,
-  ]);
+const body = memo(buildTrackedBody, params);
+  const argumentBody = memo(buildBody, params.width, params.height);
 ```
 
 
 
-Both examples rebuild when width or height changes. The array supplements automatic tracking;
-`params.width` is still tracked inside the second callback, and even `[]` keeps automatic reads.
+Both rebuild when width or height changes. Unrelated parameters can change without rebuilding.
+Compose stages by passing memo results directly: `memo(finishBody, body, params)`.
+In **New project → Cached panels**, changing **Gap** only moves the second panel; changing
+**Notch width** reuses the hole pattern for the finishing cut.
 
-The same capture rule applies to an eagerly read result such as `const value = otherComputed()`.
-Select and call readers inside the callback when possible. Studio warns about common hidden captures
-while Code is open; its advisory checks cannot prove arbitrary JavaScript correct.
+A function defined inside `generate`, including an inline arrow, gets a new identity each run.
+It still computes correctly, but cannot reuse previous runs. Studio warns about common cases while
+Code is open; factories, dynamic aliases, and arbitrary JavaScript aren't always identifiable.
 
-Dependency entries use `Object.is`, without comparing object or array contents. Use immutable
-parameter values, computed results, or scalar inputs; other objects must be deeply frozen. Create
-temporary options inside the callback, since fresh object or array dependencies prevent reuse.
-Studio warns about obvious fresh dependencies without running generation.
+Test representative parameter edits in the same session when using cached computations. An isolated
+run cannot expose stale reuse. Standalone sessions and Testkit's Generator runner accept
+`verifyCache: true` to check retained results against fresh computation. The probe is bounded;
+compare finalized output with `cache: false` when it cannot compare a model's calculations.
 
-IDs identify logical computations, so loops and conditions work without hook call-order rules.
-IDs must be unique lowercase hyphen-separated alphanumeric names of at most 64 characters within
-their namespace.
+Ordinary arguments use `Object.is`, without comparing object or array contents. Use immutable
+parameter values, memo results, or scalar inputs; other objects must be deeply frozen. Creating a
+fresh frozen object each generation still misses the cache. Create temporary options inside the
+helper, and pass its scalar inputs. A TypeScript `readonly` annotation doesn't freeze runtime data.
+An array is one argument; use `memo(fn, ...tuple)` to spread several arguments.
 
 Keep calculations synchronous and pure: do not mutate cached values, read clocks or randomness,
-perform effects, or return promises or functions. The physical result must remain the same after
+perform effects, or return promises or functions. Pass every changing input explicitly; a helper
+that reads changing module state can reuse stale output. Neither editor warnings nor runtime
+tracking can prove purity. The physical result must remain the same after
 cache eviction or a worker restart. Cache expensive layouts or grids; cheap arithmetic usually
 does not need its own computation.
 
-For cached numeric data, call [`immutableBuffer`](../reference/model/immutableBuffer.md) and use
-its `length`, `at(index)`, or `copy()` methods. Copy once before a dense sampling callback so its
+For cached numeric data, call [`immutableBuffer`](../reference/geometry/immutableBuffer.md) and use
+its `length`, `at(index)`, standard iteration, or `copy()` method. Copy once before a dense sampling callback so its
 inner loop reads an ordinary typed array. Capture a cached indexed mesh with
-[`immutableMesh`](../reference/model/immutableMesh.md); its reader can pass directly to `part`.
-Raw typed arrays in computed results or dependencies reject with guidance to use these helpers.
+[`mesh.immutable`](../reference/mesh/immutable.md); its value can pass directly to `part`.
+Raw typed arrays in memo results or arguments reject with guidance to use these helpers.
 
 ## Text services
 
-The host injects `services` into the callback after preparing exact selected font bytes.
+Studio prepares the exact selected font bytes before passing `services` to the callback.
 Call `services.text.layout()` synchronously, check its metrics, then pass the layout to
 `textSection(layout)`. Generation itself does no networking:
 
@@ -163,30 +180,33 @@ export default generate(({ params, services, part }) => {
 ## Parts and placement
 
 Use `part("body", geometry)` for the simple form, or pass an object with `geometry`,
-`position`, `rotation` and `color`. Geometry accepts a Solid or indexed manufacturing mesh.
-Geometry and placement accept values or computed readers. Keep stable semantic part IDs:
+`transform` and `color`. Geometry accepts a Solid or indexed manufacturing mesh.
+Geometry and placement accept values. Give each part a stable ID:
 
 
 
 ```ts
 export default generate(({ params: parameters, part }) => {
   const base = box({ size: [parameters.width, parameters.depth, parameters.height] });
-  const lid = box({ size: [parameters.width, parameters.depth, 2] }).translate([
-    0,
-    parameters.depth + 4,
-    0,
-  ]);
+  const lid = box({ size: [parameters.width, parameters.depth, 2] });
   return [
     part("base", { geometry: base, color: "#3b82f6" }),
-    part("lid", { geometry: lid, color: "#f59e0b" }),
+    part("lid", {
+      geometry: lid,
+      transform: transform3().translate([0, parameters.depth + 4, 0]),
+      color: "#f59e0b",
+    }),
   ];
 });
 ```
 
 
 
-Lengths use millimetres and rotations use degrees. Coordinates are right-handed with **+Z up**.
-Rotation applies about fixed X, then Y, then Z axes before translation. Part placement governs
+Use a `transform3()` value or a row-major 16-number matrix for translation and rotation;
+omitting it means identity placement. Scale, shear, reflection and perspective are rejected.
+Pattern and attachment transforms pass directly to this option.
+Lengths use millimetres and fluent rotations use degrees. Coordinates are right-handed with **+Z up**.
+Fluent transform calls apply in written order. Part placement governs
 preview, picking, measurements and all exports. Changing placement or color can reuse cached
 geometry and renderer buffers. Studio's native part-color overrides update appearance directly.
 Use modeling `translate`/`rotate` when moving a cutter or feature inside construction.
@@ -203,12 +223,12 @@ Solids and Sections are immutable deferred recipes. Ordinary recipes can be reus
 sessions; unspecified resolution settings inherit the evaluating host's defaults. Apply local
 resolution explicitly to each affected constructor or Section operation.
 
-Observations such as `inspectSolid` evaluate required geometry synchronously and return copied
-facts. `components()` selections and recipes using them can only be evaluated in their originating
-session because their identity depends on evaluated topology. The host cleans up native
+Calls such as `shape.inspect()` evaluate the required geometry synchronously and return copied
+measurements. `shape.components()` selections and recipes using them can only be evaluated in their
+originating session because their identity depends on evaluated topology. The host cleans up native
 allocations on success and failure. Nested or asynchronous execution rejects.
 
-Source/control-definition changes invalidate the program session. Parameter edits reuse it.
+Changing the source or control definition invalidates the program session. Parameter edits reuse it.
 Failed or stale requests retain the last valid preview; fatal failures replace the worker.
 Unsupported older Project data remains available through raw backup for manual source conversion;
 there is no old executor and no automatic destructive reset.

package/dist/docs/guides/geometry-values.md

@@ -0,0 +1,193 @@
+# Choose geometry values and representations
+
+Choose filled shapes, paths, profiles, and plain data, and understand when geometry is evaluated.
+
+Choose a value by the information your next operation needs. Filled Sections and Solids represent
+material; paths retain traversal and closure; identified profiles retain correspondence between
+cross sections. Pure calculations do not need a host engine.
+
+## Geometry vocabulary
+
+Choose the representation by the information you need to retain:
+
+| Representation                                           | Retains                                                              | Typical use                          |
+| -------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------ |
+| `Vector2` / `Vector3`                                    | Immutable finite coordinates and arithmetic methods                  | Readable calculations                |
+| `Path2` / `Path3`                                        | Sampled points, traversal order, and closure                         | Trajectories and boundary queries    |
+| `Contour`                                                | One closed boundary's point tuples, without a repeated endpoint      | Custom calculations and meshing      |
+| `PolygonData` / `RegionData`                             | One exterior plus holes / a collection of filled polygons            | Serialized filled topology           |
+| `Profile` / `ProfileContour2`                            | Identified family topology / one closed boundary of identified spans | Correspondence across related shapes |
+| `CorrespondingProfile`                                   | Shared sampled landmarks from `matchProfiles`                        | Loft or sweep stations               |
+| `Section` / `Solid`                                      | Immutable filled 2D / 3D recipes                                     | Booleans and model construction      |
+| `Vector2Data` / `Vector3Data`, `Path2Data` / `Path3Data` | Vector tuples and complete path records                              | Interchange and numerical kernels    |
+| `Bounds2` / `Bounds3`                                    | Immutable axis-aligned extents and measurement methods               | Containment and placement queries    |
+| `Bounds2Data` / `Bounds3Data`                            | Plain min/max coordinates                                            | Measurements and interchange         |
+| `Anchor3`                                                | An attachment frame                                                  | Relative placement                   |
+
+`Section` and `Solid` describe shapes as immutable recipes. You can construct and combine them
+without an engine, then reuse ordinary recipes across sessions. Explicit resolution settings
+stay with the recipe; omitted settings use the evaluating host's defaults. The host manages
+evaluation caches and native kernel values.
+
+Calling `shape.components()` reads evaluated geometry. Its selected shapes, and recipes using them,
+can only be evaluated in their original session because the selection depends on that session's
+evaluated topology.
+
+Use Sections from the root module for Booleans, extrusion, sweeps, and lofts. Use `/geometry`
+contour factories such as `circleContour` and `rectangleContour` when custom calculations or
+meshing need point data. These rectangle factories share size, center, corner treatment, and
+sampling options:
+
+| You need                                          | Choose                                                          | Result    |
+| ------------------------------------------------- | --------------------------------------------------------------- | --------- |
+| Filled material for Booleans or extrusion         | [`rectangle`](../reference/model/rectangle.md)                  | `Section` |
+| Sampled boundary coordinates                      | [`rectangleContour`](../reference/geometry/rectangleContour.md) | `Contour` |
+| Stable edge and corner identities across stations | [`rectangleProfile`](../reference/geometry/rectangleProfile.md) | `Profile` |
+
+[`polygon`](../reference/model/polygon.md) fills boundaries in four forms:
+
+- `polygon(points)` fills one contour.
+- `polygon({ outer, holes })` validates exterior/hole topology and normalizes winding.
+- `polygon({ contours, fillRule })` resolves compound paths with `"nonzero"` fill by default or
+  explicit `"evenodd"` fill.
+- `polygon({ polygons: data })` accepts existing `RegionData`.
+
+Each returns a `Section`, like `circle` or `rectangle`. Later Booleans may produce holes or
+disconnected components. Use `section.toRegionData()` inside synchronous generation to read
+the evaluated shape; keep serialized point data for interchange or calculations outside generation.
+
+`rectangleProfile({ size: [width, height], treatment: { kind: "round", radius }, id })` describes
+identified spans for custom geometry. Use `matchProfiles` to prepare a complete family when loft
+stations or a sweep need holes, seams, or landmarks beyond ordinary primitives.
+
+Identified spans also accept cubic Béziers with the same endpoints and controls as
+[`CubicBezierCurve2`](../reference/geometry/CubicBezierCurve2.md). Paired spans share one parameter
+grid; physical sampling refines every member before choosing the family count. Collapsed spans
+retain repeated logical slots, while the completed loft removes degenerate faces.
+
+## Choose fluent values or standalone algorithms
+
+### Convert representations deliberately
+
+| From                       | Conversion                                     | Evaluation and ownership                                       |
+| -------------------------- | ---------------------------------------------- | -------------------------------------------------------------- |
+| `Contour` / `RegionData`   | `polygon(...)` to `Section`                    | Captures a recipe without an engine                            |
+| `Section`                  | `section.toRegionData()`                       | Observes evaluated geometry inside a host execution            |
+| `Profile`                  | `matchProfiles(...)`                           | Pure matching retains identified boundaries and landmarks      |
+| Closed `Path2` / `Contour` | `mesh.extrude(...)` to `TriangleMesh`          | Pure mesh construction; no `ends` treatments                   |
+| `TriangleMesh`             | `solidFromMesh(...)` to `Solid`                | Captures a recipe; native validation happens during evaluation |
+| `Solid` / `TriangleMesh`   | `part(...)`, then an engine run to `ModelPart` | Host finalizes durable immutable manufacturing buffers         |
+| `ModelPart`                | Pass directly to mesh analysis or `export3mf`  | No live session needed; use buffer `copy()` before mutation    |
+
+Pure extrusion uses `ExtrudeMeshOptions` for height, centering, twist, top scale, and sampling.
+Native `Section.extrude` also supports `ends` through `ExtrudeOptions`; requesting them from
+`mesh.extrude` throws instead of silently returning unfinished geometry.
+
+Use methods for ordinary composition and queries on a value, such as `path.transform(...)`,
+`path.closestPoint(...)`, or `vector.normalize()`. Use standalone algorithms for specialized
+outputs, such as [`computeParallelTransportFrames`](../reference/geometry/computeParallelTransportFrames.md),
+[`mesh.sweep`](../reference/mesh/sweep.md), or
+[`resolveCylindricalGear`](../reference/geometry/resolveCylindricalGear.md).
+
+### Fluent vector and tuple arithmetic
+
+Tuple kernels remain useful in numerical loops. The same arithmetic can be written in either form:
+
+
+
+```ts
+import { vector3 } from "@metamesh/modeling";
+import { add3, normalize3, scale3 } from "@metamesh/modeling/geometry";
+
+export const fluentDirection = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
+export const tupleDirection = scale3(normalize3(add3([1, 2, 3], [4, 0, 0])), 10);
+// fluentDirection.toData() and tupleDirection contain the same coordinates.
+```
+
+
+
+Fluent vectors validate finite inputs and results and allocate immutable values. Basic tuple
+arithmetic such as `add3` avoids those wrappers and assumes valid inputs; overflow can produce
+nonfinite results. Individual kernels document additional checks, such as zero-length rejection
+in `normalize3`.
+
+## Value and data naming
+
+Modeling values use domain names such as `Vector2`, `Transform2`, `Path2`, and `Bounds2`.
+Their plain representations consistently use `Data`: `Vector2Data`, `Transform2Data`,
+`Path2Data`, and `Bounds2Data`. Each value exposes `toData()` for a stable, deeply frozen
+representation, and its factory accepts that data again. `Input` types describe accepted values,
+data, and any supported construction shorthand.
+
+Vector data is a coordinate tuple, transform data a canonical matrix, bounds data a min/max record,
+and path data a record with `dimension`, `points`, and `closed`. Use `path.toData().points`
+when a numerical algorithm needs only coordinates; keep the full record when closure matters too.
+Options, reports, geometry descriptors, and recipes keep their own descriptive names. Use
+`toMesh()` or `toRegionData()` during active host execution to evaluate a Solid as a triangle mesh
+or a Section as a region.
+
+## Query paths and preserve closure
+
+Use `path2(points, { closed: true })` or `path3(points, { closed: true })` for a reusable boundary.
+`length()` includes the closing edge. [`closestPoint`](../reference/geometry/Path3-type.md#closestpoint)
+returns a [`PathLocation`](../reference/geometry/PathLocation.md): a fluent `point`, `distance` in
+millimetres, `edgeIndex`, and clamped `fraction` within that edge. Equal-distance ties select the
+first edge in traversal order. The fraction is local to an edge; it is not a whole-path or analytic
+curve parameter.
+
+### Path coordinate round trip
+
+
+
+```ts
+import { path3 } from "@metamesh/modeling";
+
+export const boundary = path3(
+  [
+    [0, 0, 0],
+    [10, 0, 0],
+    [10, 10, 0],
+    [0, 10, 0],
+  ],
+  { closed: true }
+);
+export const nearest = boundary.closestPoint([-2, 5, 0]);
+// point: [0, 5, 0], distance: 2, edgeIndex: 3, fraction: 0.5
+export const restoredPath = path3(boundary.toData());
+// Both paths include the closing edge and have length 40 mm.
+```
+
+
+
+`toData()` returns a deeply frozen record with `dimension`, `points`, and `closed`. Pass the path
+value directly where supported, or restore the full record with `path2(data)` or `path3(data)`.
+Don't repeat the endpoint of a closed path. Open paths may be empty; their bounds are `undefined`,
+and nearest-edge queries require at least two vertices. Queries measure the sampled boundary,
+not a filled interior or underlying analytic curve.
+
+Chain `transform`, `reverse`, and equal-distance `resample` to create new paths. Transforming a path
+preserves traversal even after reflection. `polygon(path)` requires a closed planar value and
+establishes exterior/hole winding; `stroke`, sweeps, and path patterns accept paths in the matching
+dimension. Authored point collections accept fluent vectors or tuples; serialized data uses tuples.
+
+## Compose modeling operations
+
+Give intermediate shapes meaningful names and choose a curve tolerance that preserves the detail
+you need. Many high-resolution Boolean operands take longer to build.
+
+Dimension inputs accept matching fluent vectors or plain coordinate tuples, such as
+`box({ size: vector3([30, 20, 6]) })`. Use `section.extrude(options)`, `section.revolve(options)`,
+and `section.sweep(path, options)` in fluent modeling sequences. Imported `extrude`, `revolve`, and
+`sweep` accept `Section | CorrespondingProfile`, so reusable profile functions can use either input
+without branching. Both forms use the same operation contracts. Use `mesh.extrude(contour, options)`
+when constructing triangle buffers directly.
+
+Primitive factories take one options object. For example, `rectangle({ size: [24, 16] })` creates a
+filled Section and `box({ size: [24, 16, 6] })` creates a Solid. The `union`, `subtract`, and `intersect`
+methods accept one same-dimensional shape or a readonly array; an empty array preserves the receiver.
+Collection `union(shapes)` and `intersect(shapes)` combine peers and require at least one shape.
+`section.offset(distance, options)` stays in the filled XY plane.
+
+For construction details, choose [profiles and extrusion](profiles-and-extrusion.md),
+[sweeps and lofts](sweeps-and-lofts.md), or a
+[worked recipe](recipes.md).