@metamesh/modeling 0.17.0 → 0.18.0

package/dist/docs/guides/concepts.md

@@ -2,8 +2,9 @@
 
 Choose shapes, paths, profiles, and modules, then compose immutable geometry with clear sampling and preflight limits.
 
-Use Sections for filled 2D shapes, Solids for 3D material, and paths or profiles for boundaries
-and correspondence. Import modeling functions from the package root:
+Use Sections for filled 2D shapes and Solids for 3D material. Paths describe routes and boundaries;
+profiles help you line up related boundaries for a loft or sweep. Import modeling functions from
+the package root:
 
 
 
@@ -14,8 +15,8 @@ import { generate } from "@metamesh/project";
 
 
 
-Studio supplies the API and runtime to code Projects. Standalone applications use the same
-values in a generation program. Use the [Model API reference](../reference/model.md) for exact
+Studio supplies the API and runtime in code Projects. You can use the same values in a standalone
+generation program. Use the [Model API reference](../reference/model.md) for exact
 signatures.
 
 ## Choose a modeling path
@@ -30,32 +31,34 @@ signatures.
 | Repeated holes or features                    | [Patterns and placement](recipes.md#primitive-booleans-and-repeated-placement)                                               | Position one feature before repeating it                                       |
 | Separate mating parts                         | [Explicit anchors](recipes.md#named-anchors-and-custom-frames) and [shared thread settings](https://metamesh.studio/docs/develop/printable-threads) | Share a mating datum and clearance decisions                                   |
 
-Combine these constructions as needed: join a flange to a sleeve, then bore either with a
-repeated cutter. Prefer an existing primitive when it fits; use `tube` for a concentric straight
-sleeve.
+Combine these approaches as your part needs them: join a flange to a sleeve, then add repeated
+holes with cutters. Start with an existing primitive when it fits; `tube` is ready for a
+concentric straight sleeve.
 
-Start with synchronous generation and return named parts. Geometry values are immutable recipes
-that the host evaluates. Add `computed` when expensive work stays unchanged across edits. See
+Start with synchronous generation and return named parts. Geometry values describe immutable
+recipes that Studio or your standalone engine evaluates. Add `computed` when expensive work
+stays unchanged across edits. See
 [generation and parameter changes](generation.md#start-with-generate) and the
 [standalone CLI entry contract](https://metamesh.studio/docs/develop/agent-authoring#model-entries).
 
 ## Choose the module for your host
 
-| Import                                                    | Use it for                                                          | Who owns execution                      |
-| --------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------- |
-| [`@metamesh/modeling`](../reference/model.md)             | Sections, Solids, transforms, Booleans, sweeps, lofts, and patterns | A synchronous generation program        |
-| [`@metamesh/modeling/geometry`](../reference/geometry.md) | Pure paths, profiles, calculations, and indexed meshes              | Your ordinary TypeScript code           |
-| [`@metamesh/modeling/engine`](../reference/engine.md)     | Standalone initialization, model finalization, and 3MF export       | Your Node application or browser Worker |
-| [`@metamesh/modeling/text`](../reference/text.md)         | Prepare exact font bytes and vector layouts outside Studio          | Your host acquires the font bytes       |
+| Import                                                     | Use it for                                                          | Who owns execution                      |
+| ---------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------- |
+| [`@metamesh/modeling`](../reference/model.md)              | Sections, Solids, transforms, Booleans, sweeps, lofts, and patterns | A synchronous generation program        |
+| [`@metamesh/modeling/geometry`](../reference/geometry.md)  | Pure paths, profiles, calculations, and indexed meshes              | Your ordinary TypeScript code           |
+| [`@metamesh/modeling/geometry/mesh`](../reference/mesh.md) | Triangle mesh construction, processing, and inspection              | Your ordinary TypeScript code           |
+| [`@metamesh/modeling/engine`](../reference/engine.md)      | Standalone initialization, model finalization, and 3MF export       | Your Node application or browser Worker |
+| [`@metamesh/modeling/text`](../reference/text.md)          | Prepare exact font bytes and vector layouts outside Studio          | Your host acquires the font bytes       |
 
 Construct shapes, vectors, paths, and transforms in ordinary TypeScript and reuse them in
-synchronous generation. The host owns evaluation, observations, and export.
+synchronous generation. Studio or your standalone engine handles evaluation, measurements, and export.
 
 ## Use Modeling outside Studio
 
 Start with a [complete standalone model](standalone-model.md), or follow
 [Run Modeling in your application](hosting.md)
-to initialize the engine, build a model, load WASM, and export its completed snapshot.
+to initialize the engine, build a model, load WASM, and export the completed result.
 For lettering, [prepare exact font bytes](fonts.md) before building.
 
 ## Geometry vocabulary
@@ -76,12 +79,14 @@ Choose the representation by the information you need to retain:
 | `Bounds2Data` / `Bounds3Data`                            | Plain min/max coordinates                                            | Measurements and interchange         |
 | `Anchor3`                                                | An attachment frame                                                  | Relative placement                   |
 
-`Section` and `Solid` are opaque immutable recipes. Construction and composition need no engine;
-ordinary recipes can be reused across sessions regardless of where they were constructed.
-Explicitly supplied resolution settings are captured; unspecified settings inherit the evaluating
-host's defaults. The host owns evaluation caches and native kernel values. `components()` is an
-observation: its selected shapes, and recipes using them, can only be evaluated in the originating
-session because component identity depends on evaluated topology.
+`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
@@ -103,12 +108,12 @@ sampling options:
 - `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 observe
-the evaluated shape; keep serialized point data for interchange or pure preparation.
+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. Prepare a complete explicit family with `matchProfiles`
-when loft stations or a sweep need authored holes, seams, or landmarks beyond ordinary primitives.
+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
@@ -117,10 +122,26 @@ 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),
-[`sweepMesh`](../reference/geometry/sweepMesh.md), or
+[`mesh.sweep`](../reference/mesh/sweep.md), or
 [`resolveCylindricalGear`](../reference/geometry/resolveCylindricalGear.md).
 
 ### Fluent vector and tuple arithmetic
@@ -155,9 +176,9 @@ 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; use the full record to retain topology.
-Options, reports, geometry descriptors, and recipes keep their descriptive contracts. Use
-`toTriangleMesh()` or `toRegionData()` during active host execution to evaluate a Solid as a mesh
+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
@@ -195,7 +216,7 @@ export const restoredPath = path3(boundary.toData());
 
 `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)`.
-Closed paths omit the duplicated endpoint. Open paths may be empty; their bounds are `undefined`,
+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.
 
@@ -206,13 +227,21 @@ dimension. Authored point collections accept fluent vectors or tuples; serialize
 
 ## Compose modeling operations
 
-Name meaningful intermediate values and choose a curve tolerance that preserves the required
-shape. Many high-resolution Boolean operands increase generation time.
+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. `union` and `intersect`
-combine same-dimensional arrays. `shape.subtract(cutters)` accepts an array of same-dimensional
-cutters. `section.offset(distance, options)` stays in the filled XY plane.
+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.
 
 - `section.extrude({ height, twist, scaleTop })` adds +Z depth, with its bottom at zero unless
   `center: true` is requested.
@@ -220,9 +249,9 @@ cutters. `section.offset(distance, options)` stays in the filled XY plane.
 - `loft` pairs retained landmarks in compatible primitive Sections, including zero and fully
   rounded rectangle corners, and circle/ellipse stations transitioning to rectangles. Invertible
   XY transforms must keep consistent handedness. Use corresponding Profile stations for custom
-  topology. Boolean Sections and point contours need a `correspondence` method (`"direct"`,
-  `"reindex"`, `"fast-distance"`, or `"distance"`) or explicit profiles; contour order alone does
-  not establish semantic correspondence.
+  topology. Boolean Sections and point contours default to `correspondence: "direct"`, preserving
+  their supplied seams. Select `"reindex"`, `"fast-distance"`, or `"distance"` to change the
+  association strategy. Contour order alone does not establish semantic correspondence.
 - `section.sweep(path, options)` supports open or closed paths, degree twist, uniform/XY/per-station
   scales, and an explicit compatible closed seam.
 
@@ -242,16 +271,21 @@ in this order:
 2. The operation's local `resolution`.
 3. Host session defaults.
 
-A shape does not carry its sampling policy into later operations; pass it explicitly where needed.
+A shape doesn't carry its sampling policy into later operations; pass it explicitly where needed.
 
 Use an exact segment count for intentionally faceted geometry or when two sampled contours must
 match point for point. Use physical chord and segment limits for ordinary printable curves. If a
-requested tolerance cannot fit within the safety cap, the operation fails instead of silently
+requested tolerance can't fit within the safety cap, the operation fails instead of silently
 returning a coarser shape.
 
 `regularPolygon({ radius, sides, rotation, sizing })` makes a filled regular polygon.
 `sizing: "vertex"` uses the specified vertex radius; `"face"` compensates faceting so the faces
 meet the nominal radius. `circle` and `cylinder` support the same radial convention.
+`tube` accepts a complete pair of inner/outer radii or diameters, with independent `innerSizing`
+and `outerSizing`. For example, `tube({ innerDiameter: 8, outerDiameter: 12, height: 10,
+innerSizing: "face" })` preserves an 8 mm clear bore between the sampled faces. Both defaults are
+`"vertex"`; compensation that removes the wall rejects. Sampling and sizing do not establish a
+manufacturing fit allowance.
 
 Finishing options share `round` (radius), `chamfer` (setbacks), `smooth` (cubic setbacks), and exact
 `profile` points:
@@ -269,8 +303,8 @@ millimetre gap, and degree spin. It accepts named or explicit anchors; Sections
 
 Use [`transform2`](../reference/geometry/transform2.md) and
 [`transform3`](../reference/geometry/transform3.md) chains for reusable placements. They are immutable
-and pure; no engine initialization is needed. Calls apply in written order. A rotation followed
-by a translation rotates around the origin, then moves the result:
+and pure, so you don't need an engine to build them. Calls apply in written order. A rotation
+followed by a translation rotates around the origin, then moves the result:
 
 
 
@@ -286,12 +320,14 @@ export const placedDirection = placement.applyDirection([10, 0, 0]); // approxim
 
 
 Pass a transform directly to `solid.transform(placement)`, `section.transform(placement)` and
-matching path helpers. `toData()` supplies a canonical matrix when another system needs it.
+matching path helpers. Finished parts accept rigid transforms through `part(id, { geometry, transform })`;
+pattern and attachment matrices work directly. Part placement rejects scale, shear and reflection.
+`toData()` supplies a canonical matrix when another system needs it.
 Construct the placement once and reuse it across point collections.
 
 `current.andThen(next)` applies `current` first and `next` second, accepting another chain or a
-same-dimensional matrix. `inverse()` returns the reverse placement. Transform-building operations
-return new chains, so shared placements can branch safely.
+same-dimensional matrix. `inverse()` returns the reverse placement. Each operation returns a new
+chain, so you can derive different placements from a shared starting point.
 
 Use `rotate(degrees, { pivot })` or `scale(factors, { pivot })` to work around a world-space pivot after
 the preceding operations. In 3D, `rotate` takes XYZ Euler degrees, applied about global X, Y, then
@@ -306,7 +342,7 @@ including under nonuniform scaling; it rejects zero normals. All three return fl
 `Transform2` works directly with Sections and pure XY helpers; its `Transform2Data` is the same
 canonical 3x3 representation throughout. Use `to3D()` when that XY placement
 also needs to position a Solid or 3D path. The reverse `to2D()` conversion rejects transforms
-that move the XY plane or collapse its dimensions; it does not project 3D points.
+that move the XY plane or collapse its dimensions; it doesn't project 3D points.
 See the [2D placement recipe](recipes.md#reuse-a-2d-placement).
 
 ### Transform composition order
@@ -367,7 +403,7 @@ export const perpendicular = normal.dot(tangent); // approximately 0
 
 
 
-Fluent math, shape transforms, and part placement accept vector values directly. Serialized
+Fluent math and shape transforms accept vector values directly; compose a transform for part placement. Serialized
 geometry and low-level kernels use tuples. Keep model-specific equations beside the model.
 
 ## Measure and compare bounds
@@ -375,27 +411,22 @@ geometry and low-level kernels use tuples. Keep model-specific equations beside
 Use [`bounds2`](../reference/geometry/bounds2.md) and
 [`bounds3`](../reference/geometry/bounds3.md) for immutable axis-aligned bounds. `size()` and
 `center()` return fluent vectors. `containsBounds(other)` tests positioned containment in the
-same coordinate frame, including touching boundaries. It does not establish a manufacturing fit.
+same coordinate frame, including touching boundaries. It doesn't establish a manufacturing fit.
 
 
 
 ```ts
 import { bounds3 } from "@metamesh/modeling";
-import {
-  extrudeMesh,
-  fitBounds,
-  layoutRow,
-  meshBounds,
-  rectangleContour,
-} from "@metamesh/modeling/geometry";
+import { fitBounds, layoutRow, rectangleContour } from "@metamesh/modeling/geometry";
+import * as mesh from "@metamesh/modeling/geometry/mesh";
 
 export const envelope = bounds3({ min: [-10, -5, 0], max: [10, 5, 8] });
 export const size = envelope.size(); // Vector3: [20, 10, 8] mm
 export const center = envelope.center(); // Vector3: [0, 0, 4] mm
 
-const mesh = extrudeMesh(rectangleContour({ size: [12, 6] }), { height: 4 });
+const triangleMesh = mesh.extrude(rectangleContour({ size: [12, 6] }), { height: 4 });
 // Mesh measurements are plain data. Wrap once for fluent queries.
-export const measured = bounds3(meshBounds(mesh));
+export const measured = bounds3(mesh.bounds(triangleMesh));
 export const fits = envelope.containsBounds(measured); // true
 export const data = measured.toData(); // Frozen { min, max } record for interchange.
 
@@ -417,10 +448,10 @@ Mesh and region measurements, inspection results, and engine snapshots retain pl
 Compiled Generator packages passing bounds values to host recipes or computed data require
 runtime `9.0.0` or newer in major 9.
 
-Keep [`fitBounds`](../reference/geometry/fitBounds.md) and
-[`layoutRow`](../reference/geometry/layoutRow.md) as standalone algorithms: they compute placement
-reports and collection layouts. Both accept values or plain records. Supply bounds after any
-intended rotation; an axis-aligned box alone does not describe the underlying shape.
+Use [`fitBounds`](../reference/geometry/fitBounds.md) to calculate a placement and
+[`layoutRow`](../reference/geometry/layoutRow.md) to arrange a collection. These standalone
+algorithms accept values or plain records. Supply bounds after any intended rotation; an
+axis-aligned box alone doesn't describe the underlying shape.
 
 ## SVG sections: fills and strokes are different inputs
 
@@ -430,7 +461,7 @@ handles supported shapes, paths, affine transforms, physical root units, `viewBo
 allowlisted inline fill and stroke presentation.
 
 [`svgPathSection`](../reference/model/svgPathSection.md) accepts SVG path-data text rather than a
-document. It is a **fill-only** path operation: stroke styling is not part of that contract. Path
+document. It is a **fill-only** path operation: it doesn't apply stroke styling. Path
 units default to millimetres and can be converted with its scale option.
 
 Both functions convert SVG's Y-down plane to MetaMesh's Y-up plane and center the final painted
@@ -438,8 +469,8 @@ bounds by default. Use `origin: "document"` with `svgSection` when the converted
 origin must remain meaningful. Adaptive flattening happens after supported transforms and unit
 conversion, so tolerances apply in final millimetre space.
 
-Unsupported layout or external content fails rather than disappearing silently. The current public
-contract does not include nested SVG viewports, `<use>`, images, live text, external stylesheets,
+Unsupported layout or external content fails rather than disappearing silently. These helpers
+don't support nested SVG viewports, `<use>`, images, live text, external stylesheets,
 clipping, masks, filters, scripts, animation, gradients, patterns, uploaded project assets, or
 custom font files. Use the [SVG extrusion recipe](recipes.md#svg-parameter-and-extrusion)
 for a complete authored example.
@@ -448,8 +479,8 @@ for a complete authored example.
 
 `services.text.layout()` shapes text inside generation. Cache an expensive shared layout with
 `computed`, measure its `metrics`, and pass it to `textSection(layout())`. There is no
-ambient font provider or repeated shaping during export. Declare a Text control for the wording
-and a Font control for the face and weight.
+ambient font provider, and exporting doesn't shape the text again. Declare a Text control for
+the wording and a Font control for the face and weight.
 
 Font size is the em size in millimetres, not the height of a particular letter. Layout supports
 horizontal lines, spacing, and alignment, or a single circular baseline through
@@ -467,41 +498,50 @@ complete source, profile and fit choices, end treatments, and links into the exa
 
 ## Check preflight guarantees
 
-Preflights expose operation-specific checks and reports. Read their return contracts before
-using a successful result as a guarantee:
+Use a preflight to check inputs and see what an operation will require. Each preflight checks
+different things, so read what its report covers:
 
-- [`preflightHeightfield`](../reference/geometry/preflightHeightfield.md) checks grid dimensions,
+- [`mesh.preflightHeightfield`](../reference/mesh/preflightHeightfield.md) checks grid dimensions,
   coordinate precision, and allocation limits. It returns exact output-buffer vertex, triangle,
   and byte counts without evaluating heights.
-- [`preflightHelicalThreadSolidMesh`](../reference/geometry/preflightHelicalThreadSolidMesh.md)
+- [`mesh.preflightThreadSolid`](../reference/mesh/preflightThreadSolid.md)
   and related thread preflights check dimensions, sampling, and conservative allocation estimates.
   They return the sampling plan without constructing the final mesh or native solid.
 - [`preflightSvgRegion`](../reference/geometry/preflightSvgRegion.md) parses and samples supported
   SVG geometry, returning a normalized region and import diagnostics. Its counts measure the region
   at the selected resolution; they do not predict later mesh allocation.
 
-The `/geometry` preflights run without an engine and use explicit options or package defaults.
+The `/geometry` and `mesh` preflights run without an engine and use explicit options or package defaults.
 The root [`preflightThreadedRod`](../reference/model/preflightThreadedRod.md),
 [`preflightInternalThreadCutter`](../reference/model/preflightInternalThreadCutter.md), and
 [`preflightThreadedNut`](../reference/model/preflightThreadedNut.md) require active synchronous
 model execution and use the host's resolution and limits.
 
-Passing a preflight covers its documented checks. Construction can still fail during callback
-evaluation, meshing, or native evaluation. Constructors enforce their applicable limits even when
-you omit an explicit preflight; preflight is an optional planning and diagnostics step.
+Passing a preflight covers only its documented checks. Construction can still fail while running
+callbacks, meshing, or evaluating native geometry. Constructors enforce their limits even when
+you skip a preflight; use one when its plan or diagnostics help you make a decision.
 
 ## Lifecycle and inspection
 
-Studio or your standalone host owns initialization, cleanup, finalization, Worker recovery,
-preview, and file delivery. Do not manually delete `Section` or `Solid` values. Use
-`inspectSection()` and `inspectSolid()` for bounds, topology counts, area, and volume.
-
-Observations, including `section.toRegionData()`, require the host's active synchronous generation.
-Constructing or composing a recipe outside generation does not evaluate it.
-
-An inspection result describes the generated geometry; it does not certify wall thickness,
-overhangs, fits, loads, or manufacturability. Keep those product decisions in parameters,
-validation, and your downstream manufacturing checks.
+Studio or your standalone host handles initialization, cleanup, finalization, Worker recovery,
+preview, and file delivery. Don't manually delete `Section` or `Solid` values. Use
+`shape.inspect()` for bounds, topology counts, area, and volume.
+Its immutable extrema are nested under `facts.bounds.min` and `facts.bounds.max`.
+Native `componentCount` counts disconnected material components. Mesh analysis and signatures use
+`shellCount` for surfaces connected by shared indexed edges: one sealed hollow body has one material
+component and two shells. Open mesh analysis can also count open shells; this count does not certify
+closed topology or geometric validity.
+
+Queries such as `shape.inspect()`, `shape.isEmpty()`, `shape.components()`, `shape.anchor(name)`,
+`solid.distance(other)`, and `solid.castSegment(origin, endpoint)` read evaluated geometry.
+These queries and interchange with `solid.toMesh()` or `section.toRegionData()` require the host's
+active synchronous generation. `solid.split(cutter)` returns the intersection and remainder;
+`solid.splitByPlane(plane)` returns the positive and negative sides of the plane.
+Constructing or combining a recipe outside generation doesn't evaluate it.
+
+An inspection result describes the generated geometry; it doesn't certify wall thickness,
+overhangs, fits, loads, or manufacturability. Express those requirements in your parameters and
+validation, then check them in your manufacturing workflow.
 
 - [Use geometry recipes](recipes.md)
 - [Browse exact signatures](../reference/model.md)

package/dist/docs/guides/fonts.md

@@ -2,9 +2,9 @@
 
 Prepare licensed font bytes and a reusable text layout before building a model outside Studio.
 
-Load font bytes before synchronous generation. Your application supplies bytes for a font you
-are licensed to use and prepares them through the optional `@metamesh/modeling/text` entry point.
-In Studio, use the [Font control recipe](recipes.md#text-from-a-font-parameter).
+To add lettering outside Studio, load a font you're licensed to use and prepare it through the
+optional `@metamesh/modeling/text` entry point before synchronous generation. In Studio, use the
+[Font control recipe](recipes.md#text-from-a-font-parameter).
 
 ## Install font support
 
@@ -15,11 +15,12 @@ pnpm add fontkit
 pnpm add woff2-encoder
 ```
 
-TTF, OTF, and WOFF input use fontkit directly. WOFF2 decoding loads only when needed. The library
-does not fetch fonts; your application supplies their bytes.
+TTF, OTF, and WOFF input use fontkit directly. WOFF2 decoding loads only when needed. Your
+application supplies the font bytes; the library doesn't fetch them.
 
-For a static face whose actual weight is not 400, pass that weight through `staticWeight` when
-preparing it. This identifies the supplied face; it does not synthesize another weight.
+If you're using a static face whose actual weight isn't 400, pass that weight through
+`staticWeight` when preparing it. This identifies the supplied face; it doesn't synthesize
+another weight.
 
 ## Prepare one reusable layout
 
@@ -44,8 +45,8 @@ export async function makeLabelLayout(fontBytes: Uint8Array): Promise<{
 
 
 
-Call `makeLabelLayout(fontBytes)` with your font bytes. It returns a `layout` with paths and metrics
-in Y-up millimetres, plus a separate `svg` string.
+Call `makeLabelLayout(fontBytes)` with your font bytes. It returns a `layout` with paths and
+measurements in millimetres, with Y pointing up, plus a separate `svg` string.
 
 Pass the `layout` to [`textSection`](../reference/model/textSection.md) inside generation, then
 extrude the filled section. Prepare layouts ahead of time, or supply a deterministic text service
@@ -57,4 +58,4 @@ The same layout options support horizontal lines or one circular line through
 metrics, and circular-text constraints.
 
 Use the [Font preparation reference](../reference/text.md) for font and layout options, or
-[Run Modeling in your application](hosting.md) for the host lifecycle.
+[Run Modeling in your application](hosting.md) for engine setup, export, and cleanup.

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.