@metamesh/modeling 0.16.0 → 0.18.0

package/dist/docs/guides/recipes.md

@@ -19,7 +19,8 @@ open its interactive preview to orbit the result.
 | Raised lettering         | [Prepared text](#text-from-a-font-parameter)                   | Cache the selected font layout during generation          |
 
 All dimensions in these recipes are millimetres. MetaMesh uses a right-handed coordinate system
-with +Z up, degrees for angular arguments including `rotate`, and non-duplicated contour seams.
+with +Z up and degrees for angular arguments including `rotate`. Don't repeat the first point at
+the end of a closed contour.
 The examples default-export a synchronous `generate` program. Use assertions for constraints
 and optional `computed` values to cache expensive shared calculations, geometry, or text layouts.
 [Define parameters and validation](https://metamesh.studio/docs/develop/parameters-and-validation) connects
@@ -37,7 +38,7 @@ export default generate(({ part }) => {
   const plate = rectangle({ size: [80, 45] });
   const hole = circle({ radius: 4 });
   // Positive offset expands material: the outer edge grows and the hole shrinks.
-  const rimmedPlate = plate.subtract([hole]).offset(1.2);
+  const rimmedPlate = plate.subtract(hole).offset(1.2);
   // Keep the plate centered about Z = 0 for later symmetric placement.
   return [part("model", rimmedPlate.extrude({ height: 5, center: true }))];
 });
@@ -47,8 +48,9 @@ Subtract the opening in 2D, offset the filled material, then extrude it into one
 
 
 
-`rectangle` and `circle` take object options and return filled Sections. `section.subtract(cutters)`,
-`union`, and `intersect` also support Solids; every operand in a call must have the same dimension.
+`rectangle` and `circle` take object options and return filled Sections. The `union`, `subtract`, and
+`intersect` methods accept one shape or an array and also support Solids; every operand in a call
+must have the same dimension. Use collection `union(shapes)` or `intersect(shapes)` to combine peers.
 `section.offset(distance)` offsets the filled material. `section.extrude({ height })` preserves
 holes and places the bottom at zero unless `center: true` is requested.
 
@@ -85,7 +87,7 @@ with a rectangular opening:
 
 
 ```ts
-import { inspectSection, svgSection } from "@metamesh/modeling";
+import { svgSection } from "@metamesh/modeling";
 import { generate } from "@metamesh/project";
 
 export default generate(({ part }) => {
@@ -100,7 +102,7 @@ export default generate(({ part }) => {
     </svg>
   `);
   // Check the imported topology before using it in the manufacturing solid.
-  const measurements = inspectSection(badge);
+  const measurements = badge.inspect();
   if (measurements.componentCount !== 1 || measurements.contourCount !== 2) {
     throw new Error("Expected one badge with one rectangular opening.");
   }
@@ -112,23 +114,51 @@ The 48 × 32 mm SVG document retains its physical size and even-odd opening afte
 
 
 
-`svgSection` imports painted geometry, not browser-rendered SVG. The even-odd fill rule makes the
-second subpath a hole regardless of winding. Complete documents honor supported physical root units
+`svgSection` turns supported filled shapes and bounded strokes into a Section. The even-odd fill
+rule makes the second subpath a hole regardless of winding. Complete documents honor supported physical root units
 and `viewBox`, convert SVG's Y-down coordinates to MetaMesh Y-up, and center the filled bounds by
 default. Use `svgPathSection` for path-data strings where one user unit should equal 1 mm, or pass
 its `scale` option to choose another millimetres-per-unit conversion.
 
+To choose the finished artwork size, pass `fit` with positioned XY bounds. Fitting preserves
+aspect ratio and centers the painted geometry inside the target; unused SVG canvas margins do
+not reserve space. Adaptive curve tolerance and edge spacing apply at the final millimetre size:
+
+
+
+```ts
+import { bounds2, svgSection } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const artwork = svgSection('<svg><circle r="1"/></svg>', {
+    fit: bounds2({ size: [30, 18] }),
+    resolution: { maxChordError: 0.05 },
+  });
+  return part("artwork", artwork.extrude({ height: 0.8 }));
+});
+```
+
+
+
+To prepare SVG without an engine, `preflightSvgRegion` from `@metamesh/modeling/geometry` accepts
+the same fit target and returns its applied `fit`, final region, and review metrics. The scale
+and translation map the selected origin's SVG millimetres to model millimetres. Reuse them to
+align layers imported with the same document coordinate system and origin.
+Exact circular segment counts retain precedence over adaptive sampling. Empty artwork cannot
+be fitted, and fitting rejects a requested resolution that exceeds the sampling limits.
+
 Visible fills and bounded strokes contribute geometry; editor metadata is ignored. Editor text is
 outlined to visible paths on Apply. Live `<text>`, images, `<use>`, external resources, class-based
 stylesheets, clipping, masks, filters, and percentage dimensions are rejected. To generate lettering
-directly, use the [text recipe](#text-from-a-font-parameter). SVG export, project assets, custom font
-uploads, text on paths, and general SVG layout are outside this API.
+directly, use the [text recipe](#text-from-a-font-parameter). These helpers don't support SVG export,
+project assets, custom font uploads, text on paths, or general SVG layout.
 
 ## Revolve a radial profile
 
 Use revolution when one side outline can describe the entire part around an axis. In the Section
 below, X is radius and Y is final Z height; radii must stay nonnegative. The closed loop includes
-the cup's floor, outside, rim, and inside, so the opening remains intentional.
+the cup's floor, outside, rim, and inside, so you can describe the wall and opening together.
 
 
 
@@ -177,37 +207,41 @@ separate named part so you can inspect it in the interactive preview.
 
 
 ```ts
-import { ellipse, regularPolygon, sphere, star, torus, tube } from "@metamesh/modeling";
+import { ellipse, regularPolygon, sphere, star, torus, transform3, tube } from "@metamesh/modeling";
 import { generate } from "@metamesh/project";
 
 export default generate(({ part }) => {
   // Solid primitives are ready for placement; filled Sections need depth first.
   // Place finished parts on two rows while keeping local geometry reusable.
   return [
-    part("sphere", { geometry: sphere({ diameter: 14 }), position: [0, 0, 7], color: "#60a5fa" }),
+    part("sphere", {
+      geometry: sphere({ diameter: 14 }),
+      transform: transform3().translate([0, 0, 7]),
+      color: "#60a5fa",
+    }),
     part("torus", {
       geometry: torus({ majorRadius: 7, minorRadius: 2 }),
-      position: [24, 0, 2],
+      transform: transform3().translate([24, 0, 2]),
       color: "#34d399",
     }),
     part("tube", {
       geometry: tube({ outerRadius: 7, innerRadius: 4, height: 10, center: false }),
-      position: [48, 0, 0],
+      transform: transform3().translate([48, 0, 0]),
       color: "#f59e0b",
     }),
     part("ellipse", {
       geometry: ellipse({ size: [18, 12] }).extrude({ height: 5 }),
-      position: [0, 24, 0],
+      transform: transform3().translate([0, 24, 0]),
       color: "#c084fc",
     }),
     part("star", {
       geometry: star({ outerRadius: 9, innerRadius: 4.5, points: 5 }).extrude({ height: 5 }),
-      position: [24, 24, 0],
+      transform: transform3().translate([24, 24, 0]),
       color: "#fb7185",
     }),
     part("hexagon", {
       geometry: regularPolygon({ radius: 7, sides: 6, sizing: "face" }).extrude({ height: 5 }),
-      position: [48, 24, 0],
+      transform: transform3().translate([48, 24, 0]),
       color: "#22d3ee",
     }),
   ];
@@ -245,7 +279,7 @@ export default generate(({ part }) => {
   // Both shapes are Z-centered; extra cutter height clears both hub faces.
   const bore = cylinder({ height: 16, radius: 4 });
   // Combine the repeated features once, then cut the common bore.
-  return [part("model", union([hub, ...arms]).subtract([bore]))];
+  return [part("model", union([hub, ...arms]).subtract(bore))];
 });
 ```
 
@@ -299,8 +333,8 @@ Fill the transformed closed path with `polygon(placedContour)` when you need mat
 A negative scale factor reflects the placement. Paths retain traversal order, including closed
 paths; filled Sections and serialized regions restore outer and hole winding. `andThen(next)`
 composes another placement in execution order;
-reuse the placement instead of building a chain inside each point iteration. `toData()` is
-available for matrix interchange.
+reuse the placement instead of rebuilding the chain for every point. Use `toData()` when another
+system needs the matrix.
 
 Section path patterns consume `Path2` values directly. Tangent orientation aligns the Section's
 local +X direction with the path while preserving its XY plane:
@@ -364,7 +398,7 @@ The asymmetric section makes its transported orientation visible as the path tur
 
 - `orientation: { kind: "transport", initialNormal: [0, 1, 0] }` chooses the starting profile-X
   direction. Fixed normals, directed normal guides, and discrete Frenet frames are alternatives;
-  singular selected policies reject.
+  the sweep rejects a selected policy that becomes singular.
 - `twist` adds total rotation by physical path length. Set `twistBy: "stations"` to use the authored
   station schedule instead.
 - `scale` accepts a positive uniform size, an XY pair, or one XY pair per normalized station.
@@ -381,14 +415,14 @@ stations; it does not infer a smooth curve between them. Sample a curve with the
 
 
 ```ts
-import { anchor, box, cylinder } from "@metamesh/modeling";
+import { box, cylinder } from "@metamesh/modeling";
 import { generate } from "@metamesh/project";
 
 export default generate(({ part }) => {
   const base = box({ size: [40, 24, 6], center: false });
   // Named anchors follow dimensions: no duplicated half-height calculation.
   // Mating bottom to top opposes the two outward normals automatically.
-  const pin = cylinder({ diameter: 8, height: 12 }).attach("bottom", anchor(base, "top"), {
+  const pin = cylinder({ diameter: 8, height: 12 }).attach("bottom", base.anchor("top"), {
     gap: 0.2,
   });
   // Keep the gap and the two physical pieces instead of unioning the assembly.
@@ -400,16 +434,18 @@ The pin's bottom mates to the base's top with a 0.2 mm gap. They remain two name
 
 
 
-Ordinary primitives know their named anchors, so `anchor(base, "top")` follows the box's dimensions
-and placement. `pin.attach("bottom", anchor(base, "top"))` mates opposed directions. Transforms and
+Ordinary primitives know their named anchors, so `base.anchor("top")` follows the box's dimensions
+and placement. `pin.attach("bottom", base.anchor("top"))` mates opposed directions. Transforms and
 patterns carry those frames with the shape, with outward normals preserved under nonuniform scale
 and reflection. The axis names are `left/right` (−X/+X), `back/front` (−Y/+Y) and `bottom/top` (−Z/+Z).
 
 Use `shape.withAnchors({ mount: anchor3(position, direction, up) })` to define a custom datum
-on a new handle. Existing names remain unless replaced; definitions are copied and immutable.
+without changing the original shape. Existing names remain unless replaced; definitions are copied
+and immutable.
 Boolean and other constructed shapes need explicit definitions because their surfaces may change.
 Anchor names use lowercase kebab-case, with at most 64 characters and 128 definitions per shape.
-Lookup realizes the required recipe in the active generation transaction. Returned frames are plain data.
+Look up anchors during active synchronous generation; the lookup evaluates the required recipe.
+Returned frames are plain data.
 
 Primitive anchors describe nominal construction dimensions. Finishing and curve sampling do not
 move them. Tube and torus axial datums may lie over an opening; a cone has no cap anchor at its apex.
@@ -529,9 +565,9 @@ Custom hole topology or disconnected components can use an explicit
 [`Profile`](../reference/geometry/Profile.md) family with stable component, contour, and span IDs.
 Prepare [`matchProfiles`](../reference/geometry/matchProfiles.md) once and pass its
 [`CorrespondingProfile`](../reference/geometry/CorrespondingProfile.md) stations to the same `loft`
-function. Topology must remain constant across stations. Arbitrary Boolean Sections need deliberate
-`correspondence: "direct"`, `"reindex"`, `"fast-distance"`, or `"distance"`, or explicit profiles;
-contour order does not establish landmarks. Direct association preserves the supplied seams;
+function. Topology must remain constant across stations. Arbitrary Boolean Sections default to
+`correspondence: "direct"`; choose `"reindex"`, `"fast-distance"`, or `"distance"` to change the
+association strategy, or use explicit profiles for landmarks. Direct association preserves the supplied seams;
 reindex also chooses a cyclic phase, while distance methods optimize ordered connections. See
 [`LoftOptions`](../reference/model/LoftOptions.md) for sampling and work limits.
 
@@ -539,9 +575,9 @@ reindex also chooses a cyclic phase, while distance methods optimize ordered con
 
 Build a relief tile from absolute Z heights over a rectangular XY grid.
 [`heightfield`](../reference/model/heightfield.md) returns a Solid for Booleans and placement during
-generation. Pure [`heightfieldMesh`](../reference/geometry/heightfieldMesh.md) accepts the same options
+generation. Pure [`mesh.heightfield`](../reference/mesh/heightfield.md) accepts the same options
 and returns an indexed mesh without an engine. Pass it directly as a mesh part, or wrap it in
-[`immutableMesh`](../reference/model/immutableMesh.md) when returning it from a cached computation.
+[`mesh.immutable`](../reference/mesh/immutable.md) when returning it from a cached computation.
 
 
 
@@ -588,7 +624,7 @@ additional physical midpoint per cell. Both selection policies use the fixed dia
 Choose sample spacing for the surface detail you need: these policies do not adapt the grid or
 guarantee accuracy throughout each cell. Explicit axes let your model refine selected regions
 while keeping allocation bounded.
-[`preflightHeightfield`](../reference/geometry/preflightHeightfield.md) reports output counts and
+[`mesh.preflightHeightfield`](../reference/mesh/preflightHeightfield.md) reports output counts and
 checks limits without evaluating heights.
 
 ## Text from a Font parameter
@@ -628,21 +664,20 @@ The poster uses a pinned bundled Outfit face and preserves the counters inside e
 letters. Extrude that section or combine it with other sections and solids. Use `layout.metrics`
 and its visible `bounds` to size a backing plate or reject text without visible outlines.
 
-Check a positioned label with [`containsBounds`](../reference/geometry/containsBounds.md),
-using [`boundsFromSize`](../reference/geometry/boundsFromSize.md) for the available rectangle.
+Check a positioned label with [`bounds.containsBounds()`](../reference/geometry/bounds2.md),
+using [`bounds2({ size })`](../reference/geometry/bounds2.md) for the available rectangle.
 Horizontal `align: "center"` centers advance width; visible ink can remain asymmetric.
 To resize the ink uniformly and center it inside a target, use
 [`fitTextLayout`](../reference/geometry/fitTextLayout.md) before `textSection`. It transforms
 the retained vector paths before sampling, keeping curve tolerance in final millimetres.
-`maxScale: 1` permits shrinking without enlargement. Minimum readable letter height and
-parameter-specific error messages remain model decisions.
+`maxScale: 1` permits shrinking without enlargement. Choose a minimum readable letter height
+and write parameter-specific error messages for your model.
 
 
 
 ```ts
 import {
-  boundsFromSize,
-  containsBounds,
+  bounds2,
   fitTextLayout,
   type FittedTextLayout,
   type VectorTextLayout,
@@ -650,12 +685,12 @@ import {
 
 export function labelFits(layout: VectorTextLayout): boolean {
   const ink = layout.metrics.bounds;
-  return ink !== null && containsBounds(boundsFromSize([40, 12]), ink);
+  return ink !== null && bounds2({ size: [40, 12] }).containsBounds(ink);
 }
 
 export function fitLabel(layout: VectorTextLayout): FittedTextLayout {
   // Fit visible ink while preserving proportions and preventing enlargement.
-  return fitTextLayout(layout, boundsFromSize([40, 12]), { maxScale: 1 });
+  return fitTextLayout(layout, bounds2({ size: [40, 12] }), { maxScale: 1 });
 }
 ```
 
@@ -674,8 +709,8 @@ For a circular label, add a [`baseline`](../reference/text/VectorTextArcBaseline
 `kind: "arc"` and a positive `radius` in millimetres to the layout options. The baseline is centered
 at the XY origin; `centerAngle` chooses its alignment datum and `direction` chooses the
 reading direction. Each shaped glyph group rotates without bending. Circular text requires one
-line and baseline vertical alignment; its default horizontal alignment is centered. Arbitrary
-path text and automatic wrapping are outside this API.
+line and baseline vertical alignment; its default horizontal alignment is centered. These helpers
+don't support arbitrary path text or automatic wrapping.
 
 Text uses positive Y upward and supports line breaks, with at most 512 UTF-16 units and 16 lines.
 Empty or whitespace-only text can be measured but cannot create a section. Return a parameter error
@@ -690,19 +725,19 @@ replacement. Studio does not support custom font uploads.
 
 ## Solid inspection
 
-Use `inspectSolid()` during generation to check bounds, volume, and component count:
+Use `solid.inspect()` during generation to check bounds, volume, and component count:
 
 
 
 ```ts
-import { box, inspectSolid } from "@metamesh/modeling";
+import { box } from "@metamesh/modeling";
 import { generate } from "@metamesh/project";
 
 export default generate(({ part }) => {
   const result = box({ size: [40, 30, 5] });
-  const measurements = inspectSolid(result);
+  const measurements = result.inspect();
 
-  if (measurements.min[2] < -2.5 || measurements.componentCount !== 1) {
+  if (measurements.bounds.min[2] < -2.5 || measurements.componentCount !== 1) {
     throw new Error("Unexpected placement or disconnected result.");
   }
 
@@ -713,29 +748,32 @@ export default generate(({ part }) => {
 
 
 Use [`layoutRow`](../reference/geometry/layoutRow.md) to arrange pieces along +X with an explicit
-gap and ground their minimum Y/Z at zero. Pass bounds after any intended rotation; the returned
-translations belong in `part` placement options so geometry remains reusable.
+gap and place their minimum Y/Z at zero. Pass bounds after any intended rotation, then use the
+returned translations in `part` placement options so you can reuse the geometry.
 
 
 
 ```ts
-import { box, generate, inspectSolid } from "@metamesh/modeling";
+import { box, generate, transform3 } from "@metamesh/modeling";
 import { layoutRow } from "@metamesh/modeling/geometry";
 
 export const rowModel = generate<Record<never, never>>(({ part }) => {
   const pieces = [box({ size: [20, 10, 6] }), box({ size: [12, 16, 8] })];
-  const positions = layoutRow(pieces.map(inspectSolid), { gap: 4 });
+  const positions = layoutRow(
+    pieces.map((piece) => piece.inspect().bounds),
+    { gap: 4 }
+  );
   return pieces.map((geometry, index) =>
-    part(`piece-${index}`, { geometry, position: positions[index]! })
+    part(`piece-${index}`, { geometry, transform: transform3().translate(positions[index]!) })
   );
 });
 ```
 
 
 
-Inspection copies supported native facts. Manufacturing finalization checks finite, closed,
-oriented and reconstructable output before it becomes the preview or export snapshot. These
-checks do not certify manufacturability. Keep minimum walls, overhangs, fits, and parameter
+Inspection reports measurements from the evaluated geometry. Before a result becomes available
+for preview or export, finalization checks that it's finite, closed, oriented, and reconstructable.
+Those checks don't certify manufacturability. Keep minimum walls, overhangs, fits, and parameter
 messages in your model's validation.
 
 After adapting a recipe, check its default, the largest and smallest supported dimensions, and

package/dist/docs/guides/standalone-model.md

@@ -2,8 +2,9 @@
 
 Write a TypeScript model for a plate with a hole, then check and run it with the CLI.
 
-A standalone model uses `@metamesh/modeling` and default-exports a synchronous generation program.
-The CLI or your application supplies the engine.
+Write a model with `@metamesh/modeling` when you want to run it from a local script or your own
+application. It default-exports a synchronous generation program; the CLI or your application
+supplies the engine.
 
 ## Minimal model entry
 
@@ -17,14 +18,14 @@ import { box, cylinder, generate } from "@metamesh/modeling";
 export default generate<Record<never, never>>(({ part }) => {
   const body = box({ size: [30, 20, 6] });
   const bore = cylinder({ height: 8, radius: 3, sizing: "face" });
-  return part("plate", body.subtract([bore]));
+  return part("plate", body.subtract(bore));
 });
 ```
 
 
 
 The cutter extends beyond both faces of the centered plate. `part("plate", ...)` gives the output
-a stable identity. This model takes an empty parameter map.
+a stable ID so you can identify the plate in the result. This model takes an empty parameter map.
 
 ## Check and run
 
@@ -32,11 +33,11 @@ With [Modeling and the CLI installed](https://metamesh.studio/docs/develop/agent
 check the source and generate a captured result:
 
 ```bash
-pnpm exec metamesh check model.ts --kind model
+pnpm exec metamesh typecheck model.ts --kind model
 pnpm exec metamesh run model.ts --kind model
 ```
 
 Continue with [inspection and rendering](https://metamesh.studio/docs/develop/agent-authoring#inspect-the-captured-result),
 or [host the program in your application](hosting.md).
-Use the [construction chooser](concepts.md#choose-a-modeling-path) when you
-need to select another modeling approach.
+When you're ready for a different shape, the
+[construction chooser](concepts.md#choose-a-modeling-path) helps you pick an approach.