@metamesh/modeling 0.18.0 → 0.20.0

package/dist/docs/guides/recipes.md

@@ -1,782 +1,128 @@
 # Modeling recipes
 
-Build plates, cups, routed tubes, lofts, repeated features, SVG shapes, and lettering with complete modeling examples.
+Choose an illustrated construction technique by the part you want to make.
 
-Choose a recipe, inspect its render, and copy the complete source into a Studio
-[code Project](https://metamesh.studio/docs/develop/code-projects). Each illustrated recipe renders that same source;
-open its interactive preview to orbit the result.
+Choose the shape or feature you need. Each guide pairs rendered geometry with the checked source
+that creates it, explains the important constraints, and links to the exact API.
 
-| You want to make         | Start here                                                     | Main decision                                             |
-| ------------------------ | -------------------------------------------------------------- | --------------------------------------------------------- |
-| A flat part with holes   | [Sections and extrusion](#section-hole-offset-and-extrusion)   | Solve the filled outline before adding thickness          |
-| A badge from artwork     | [SVG extrusion](#svg-parameter-and-extrusion)                  | Set physical size and preserve holes                      |
-| A lathed cup or knob     | [Revolution](#revolve-a-radial-profile)                        | Describe radius and height in one closed wall profile     |
-| A hub with repeated arms | [Radial placement](#primitive-booleans-and-repeated-placement) | Position one feature before repeating it                  |
-| A routed strip or tube   | [Path sweep](#rotation-minimizing-path-sweep)                  | Choose how the section is oriented along the path         |
-| A transition or adapter  | [Section loft](#matched-section-loft)                          | Keep corresponding landmarks between stations             |
-| A relief tile            | [Heightfield](#sample-a-heightfield)                           | Choose physical samples and triangle diagonals            |
-| A pair of mating pieces  | [Anchors](#named-anchors-and-custom-frames)                    | Define the mating datum rather than duplicate coordinates |
-| Raised lettering         | [Prepared text](#text-from-a-font-parameter)                   | Cache the selected font layout during generation          |
+New to Modeling? [Start with a complete part](https://metamesh.studio/docs/modeling#start-with-one-part), then return here
+when you want to build a different shape.
 
-All dimensions in these recipes are millimetres. MetaMesh uses a right-handed coordinate system
-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
-source values to controls.
+## Choose a technique
 
-## Section, hole, offset, and extrusion
 
 
 
-```ts
-import { circle, rectangle } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
+### [Profiles and extrusion](profiles-and-extrusion.md)
 
-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);
-  // Keep the plate centered about Z = 0 for later symmetric placement.
-  return [part("model", rimmedPlate.extrude({ height: 5, center: true }))];
-});
-```
+Outline → solid
 
-Subtract the opening in 2D, offset the filled material, then extrude it into one plate.
+Extrude plates and gaskets, revolve cups, and finish housings and rims.
 
+![A tapered cup with an open top and closed floor](https://metamesh.studio/docs/develop/section-revolve.webp)
 
 
-`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.
 
-Positive offset grows material on every boundary: this example grows the outside by `1.2 mm` and
-reduces the hole radius from `4 mm` to `2.8 mm`. If the final bore must remain `8 mm` in diameter,
-offset the outside first and subtract the hole afterward. See
-[`Section.offset`](../reference/model/Section.md#offset) and [`Section.extrude`](../reference/model/Section.md#extrude).
 
-## SVG parameter and extrusion
 
-Pass an SVG control's string value from `params` directly to `svgSection`. This example aliases
-`params` as `parameters`:
+### [Sweeps, lofts, and reliefs](sweeps-and-lofts.md)
 
+Path or stations → solid
 
+Route a ribbon, blend changing profiles, or sample a surface over an XY grid.
 
-```ts
-import { svgSection } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
+![A transition between rounded rectangular sections](https://metamesh.studio/docs/develop/section-loft.webp)
 
-export default generate(({ params: parameters, part }) => {
-  const profile = svgSection(parameters.profile6);
-  return [part("model", profile.extrude({ height: 3, center: true }))];
-});
-```
 
 
 
-The property name matches the ID in **Model controls**: `profile6` in this example, or
-`parameters.logo` for a control with ID `logo`.
 
-`svgSection` also accepts literal SVG documents. Here two nested subpaths make a badge
-with a rectangular opening:
+### [Transforms and placement](transforms-and-placement.md)
 
+One feature → coordinated parts
 
+Repeat features, share placements, and align parts by their anchors.
 
-```ts
-import { svgSection } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
+![A radial hub with six repeated arms](https://metamesh.studio/docs/develop/primitive-array.webp)
 
-export default generate(({ part }) => {
-  // Physical root units make the imported artwork exactly 48 × 32 mm.
-  // Even-odd filling turns the second closed subpath into an opening.
-  const badge = svgSection(`
-    <svg xmlns="http://www.w3.org/2000/svg" width="48mm" height="32mm" viewBox="0 0 48 32">
-      <path
-        fill-rule="evenodd"
-        d="M 0 0 H 48 V 32 H 0 Z M 14 8 H 34 V 24 H 14 Z"
-      />
-    </svg>
-  `);
-  // Check the imported topology before using it in the manufacturing solid.
-  const measurements = badge.inspect();
-  if (measurements.componentCount !== 1 || measurements.contourCount !== 2) {
-    throw new Error("Expected one badge with one rectangular opening.");
-  }
-  return [part("model", badge.extrude({ height: 4, center: true }))];
-});
-```
 
-The 48 × 32 mm SVG document retains its physical size and even-odd opening after extrusion.
 
 
 
-`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.
+### [Solid joins](solid-joins.md)
 
-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:
+Base + feature → connection
 
+Connect a separately modeled boss or rib with a smooth or straight transition.
 
+![A mounting boss blended into a flat base](https://metamesh.studio/docs/develop/solid-join.webp)
 
-```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). 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 you can describe the wall and opening together.
 
 
 
-```ts
-import { polygon } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
-
-export default generate(({ part }) => {
-  // Here Section X means radius and Section Y becomes the final Z height.
-  // Walk the filled wall counterclockwise, omitting a repeated closing point.
-  const wall = polygon([
-    [0, 0],
-    [16, 0],
-    [16, 4],
-    [12, 4],
-    [10, 28],
-    [7, 28],
-    [9, 4],
-    [0, 4],
-  ]);
-  // A full revolution creates the floor, tapered wall, and open top together.
-  return [part("model", wall.revolve())];
-});
-```
-
-One radial wall profile revolved around +Z creates the floor and tapered cup wall.
-
-
-
-[`polygon`](../reference/model/polygon.md) fills the ordered contour.
-[`Section.revolve`](../reference/model/Section.md#revolve) defaults to a complete `360°` turn. Set
-`degrees: 270` for a capped partial turn that exposes the cross section. Keep the closed
-profile free of self-intersections and never repeat its first point at the end.
-
-For an open side outline, [`sampleSideProfile`](../reference/geometry/sampleSideProfile.md)
-returns physical `[radius, height]` points. [`closeToAxis`](../reference/geometry/closeToAxis.md)
-adds the horizontal bottom/top edges needed for a solid body. Fill the result with `polygon`,
-then revolve it. Hollow walls and mounting bores need their own closed material contour.
-
-## Choose a primitive
-
-Start with the factory that most closely describes the shape. The first row below contains ready
-Solids; the second contains filled Sections extruded to `5 mm` thickness. Each result remains a
-separate named part so you can inspect it in the interactive preview.
-
 
+### [SVG and lettering](svg-and-text.md)
 
-```ts
-import { ellipse, regularPolygon, sphere, star, torus, transform3, tube } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
+Artwork → material
 
-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 }),
-      transform: transform3().translate([0, 0, 7]),
-      color: "#60a5fa",
-    }),
-    part("torus", {
-      geometry: torus({ majorRadius: 7, minorRadius: 2 }),
-      transform: transform3().translate([24, 0, 2]),
-      color: "#34d399",
-    }),
-    part("tube", {
-      geometry: tube({ outerRadius: 7, innerRadius: 4, height: 10, center: false }),
-      transform: transform3().translate([48, 0, 0]),
-      color: "#f59e0b",
-    }),
-    part("ellipse", {
-      geometry: ellipse({ size: [18, 12] }).extrude({ height: 5 }),
-      transform: transform3().translate([0, 24, 0]),
-      color: "#c084fc",
-    }),
-    part("star", {
-      geometry: star({ outerRadius: 9, innerRadius: 4.5, points: 5 }).extrude({ height: 5 }),
-      transform: transform3().translate([24, 24, 0]),
-      color: "#fb7185",
-    }),
-    part("hexagon", {
-      geometry: regularPolygon({ radius: 7, sides: 6, sizing: "face" }).extrude({ height: 5 }),
-      transform: transform3().translate([48, 24, 0]),
-      color: "#22d3ee",
-    }),
-  ];
-});
-```
-
-Sphere, torus, and tube are solid factories. Ellipse, star, and regular polygon create Sections that can be extruded.
-
-
-
-Use a [`tube`](../reference/model/tube.md) when the bore is concentric; it avoids a separate cutter.
-A [`torus`](../reference/model/torus.md) uses the distance to the circular profile's center as its
-major radius. [`regularPolygon`](../reference/model/regularPolygon.md) has an exact side count;
-`sizing: "face"` makes the specified radius reach the faces instead of the vertices. Keep physical
-curve tolerance for ordinary round shapes and use exact segment counts for deliberate faceting.
-
-## Primitive booleans and repeated placement
-
-
-
-```ts
-import { box, cylinder, radialPattern, union } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
-
-export default generate(({ part }) => {
-  const hub = cylinder({ height: 12, radius: 14 });
-  const arm = box({ size: [30, 6, 6] });
-  // Translate first, then rotate the whole arm about the world origin.
-  // Its inner end overlaps the hub so union creates one connected part.
-  const arms = radialPattern(arm.translate([18, 0, 0]).rotate([0, 0, 30]), {
-    count: 6,
-    axis: [0, 0, 1],
-    angle: 60,
-  });
-  // 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))];
-});
-```
-
-Position and rotate one arm, repeat it about +Z, union the overlaps, then cut a common bore.
-
-
-
-Transforms apply in written order: `arm.translate(...).rotate(...)` moves the arm first, then rotates
-its position about the origin. Reversing those calls rotates the arm locally before moving it.
-Keep a deliberate overlap between each arm and the hub so the result is one connected solid.
-
-Exact signatures: [`box`](../reference/model/box.md),
-[`cylinder`](../reference/model/cylinder.md), and
-[`radialPattern`](../reference/model/radialPattern.md).
-
-## Reuse a 2D placement
-
-Build one [`transform2`](../reference/geometry/transform2.md) chain when the same placement applies
-to a Section and its plain point data. This placement rotates around `[2, 1]`, then translates:
-
-
-
-```ts
-import { path2, pathPattern, polygon, rectangle, transform2, union } from "@metamesh/modeling";
-
-const planarPlacement = transform2()
-  .rotate(90, { pivot: [2, 1] })
-  .translate([10, 0]);
-const outline = [
-  [0, 0],
-  [4, 0],
-  [0, 2],
-] as const;
-
-// Shape construction and composition are pure; the host evaluates the finished body.
-export const placedBody = polygon({ outer: outline, holes: [] })
-  .transform(planarPlacement)
-  .extrude({ height: 8 });
-
-// Paths accept the same placement. Matrices and tuples remain available for interchange.
-export const sectionMatrix = planarPlacement.toData();
-export const placedContour = path2(outline, { closed: true }).transform(planarPlacement);
-```
-
-
-
-Pass the placement directly to `section.transform(planarPlacement)` or `path.transform(planarPlacement)`.
-Fill the transformed closed path with `polygon(placedContour)` when you need material.
-[`transformRegionData`](../reference/geometry/transformRegionData.md) serves serialized filled data.
+Extrude painted SVG shapes or exact-font lettering and fit the visible outlines.
 
-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 rebuilding the chain for every point. Use `toData()` when another
-system needs the matrix.
+![A scalloped badge with a star-shaped opening](https://metamesh.studio/docs/develop/svg-document-extrusion.webp)
 
-Section path patterns consume `Path2` values directly. Tangent orientation aligns the Section's
-local +X direction with the path while preserving its XY plane:
 
 
 
-```ts
-const guide = path2([
-  [0, 0],
-  [12, 0],
-  [12, 12],
-]);
-const tabs = pathPattern(rectangle({ size: [4, 2] }), guide, {
-  count: 5,
-  orientation: "tangent",
-});
-export const patternedTabs = union(tabs).extrude({ height: 3 });
-```
 
+### [Printable threads](https://metamesh.studio/docs/develop/printable-threads)
 
+Shared dimensions → mating parts
 
-Linear Section patterns use XY directions. Radial Section patterns rotate about an optional XY
-`pivot` using the implicit +Z axis; spatial Solid patterns retain their explicit rotation axis.
+Make a threaded rod and nut with shared profiles, end treatments, and fit allowances.
 
-## Rotation-minimizing path sweep
+![A threaded rod and matching nut](https://metamesh.studio/docs/modeling-guides/printable-threads/threaded-parts.webp)
 
 
 
-```ts
-import { rectangle } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
 
-export default generate(({ part }) => {
-  // An asymmetric section makes the frame orientation visible in the result.
-  const section = rectangle({
-    size: [8, 3],
-    treatment: { kind: "round", radius: 0.8 },
-  });
-  const path = [
-    [0, 0, 0],
-    [15, 0, 8],
-    [25, 10, 18],
-    [25, 25, 24],
-  ] as const;
-  // The initial normal sets profile +X; transport carries it along the path.
-  // The path is open, so the sweep closes both ends with caps.
-  return [
-    part(
-      "model",
-      section.sweep(path, { orientation: { kind: "transport", initialNormal: [0, 1, 0] } })
-    ),
-  ];
-});
-```
 
-The asymmetric section makes its transported orientation visible as the path turns.
+### [Gear geometry](https://metamesh.studio/docs/develop/gear-geometry)
 
+Pitch + tooth count → gear pair
 
+Resolve dimensions, sample tooth outlines, and place a pinion, wheel, or rack.
 
-`section.sweep(path, options)` transports a filled shape along a path:
-
-- `orientation: { kind: "transport", initialNormal: [0, 1, 0] }` chooses the starting profile-X
-  direction. Fixed normals, directed normal guides, and discrete Frenet frames are alternatives;
-  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.
-- `closed: true` joins an implicitly closed path without repeated endpoints. Orientation, scales,
-  and `seamProfileOffset` must describe a compatible closing seam.
-
-Start with the open path above, inspect the first cap and the turns, then replace the rectangle
-with a [`circle`](../reference/model/circle.md) for a round rod. A sweep follows the supplied path
-stations; it does not infer a smooth curve between them. Sample a curve with the
-[path helpers](../reference/geometry/categories/curves-paths.md) when you need a curved trajectory.
-
-## Named anchors and custom frames
+![A golden pinion and blue wheel with meshing teeth](https://metamesh.studio/docs/develop/gear-pair.webp)
 
 
 
-```ts
-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", base.anchor("top"), {
-    gap: 0.2,
-  });
-  // Keep the gap and the two physical pieces instead of unioning the assembly.
-  return [part("base", { geometry: base }), part("pin", { geometry: pin })];
-});
-```
-
-The pin's bottom mates to the base's top with a 0.2 mm gap. They remain two named parts.
-
-
-
-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
-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.
-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.
-Regular polygons and stars expose only `center`. Custom `Anchor3` frames, including pure
-`boxAnchor3` and `cylinderAnchor3` helpers, work wherever a source or target frame is required.
-
-Primitive `attachment` uses the same source/target anchor, `alignment`, `gap`, and `spin`
-options as `attach`, including a named `source`. It applies after local construction; Section
-attachment must preserve the XY plane.
-
-The `gap` here separates the two pieces along the target normal; it is a placement distance, not
-a radial fit clearance. Keep separate named parts for an assembly. For one fused part, remove the
-gap, add a small intended overlap, and [`union`](../reference/model/union.md) the solids.
-
-## Printable threaded rod and nut
-
-Follow [Build printable threads](https://metamesh.studio/docs/develop/printable-threads) for a runnable rod-and-nut example
-and guidance on profiles, fit, lead, end treatments, resolution, and calibration.
-
-## Treated boxes, frustums, and mirrored arrays
-
-
-
-```ts
-import { box, cylinder, gridPattern } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
-
-export default generate(({ part }) => {
-  const housing = box({
-    size: [46, 30, 12],
-    treatment: { kind: "round", radius: 3 },
-  });
-  const taperedBore = cylinder({
-    // The centered cutter extends beyond both faces of the 12 mm housing.
-    height: 16,
-    // Tuples run from the bottom diameter to the top diameter along +Z.
-    diameter: [8, 6],
-    sizing: "face",
-    ends: { top: { kind: "chamfer", distance: 0.8 } },
-  });
-  // Pattern the already-positioned tool; X varies fastest through the array.
-  const perforations = gridPattern(taperedBore.translate([-13, -6, 0]), {
-    count: [3, 2],
-    spacing: [13, 12],
-  });
-  // Mirror the completed housing across the plane with normal +X.
-  return [part("model", housing.subtract(perforations).mirror([1, 0, 0]))];
-});
-```
-
-Six non-overlapping cutters share the same taper and rim treatment; the completed housing is mirrored.
-
-
-
-Paired cylinder radii or diameters are always `[bottom, top]` in +Z order. A zero endpoint makes a cone;
-chamfers under `ends.bottom` and `ends.top` may treat either nonzero end and follow the tapered side.
-Boxes and rectangles share `round`, `chamfer`, `smooth`, and explicit `profile` treatments. Boxes
-can select disjoint named edges or groups; rectangles can select each corner. `gridPattern` places
-the cutters on an XY grid, with X varying fastest.
-Zero rounding radius or zero chamfer/smooth setbacks disable that treatment, so an adjustable
-feature can remain in the options object when switched off.
-
-The bores use `diameter: [8, 6]` and `13 × 12 mm` spacing to leave material between them. Check
-the widest cutter diameter and the outer wall when changing either value. In this example the
-tool's top chamfer lies above the housing; it shapes the cutter end, not the finished hole's rim.
-Use an explicitly shaped cutting profile if the finished mouth needs a countersink.
-
-## Matched-section loft
-
-
-
-```ts
-import { loft, rectangle } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
-
-export default generate(({ part }) => {
-  const base = rectangle({
-    size: [24, 16],
-    treatment: { kind: "round", radius: 3 },
-  });
-  // Transform the Section in its XY plane; loft supplies the station heights.
-  // Keeping the original rectangle landmarks preserves corner correspondence.
-  const top = base.scale([0.8, 1.2]).rotate(10).translate([3, 0]);
-  return [
-    part(
-      "model",
-      loft([
-        {
-          profile: base,
-          z: 0,
-        },
-        {
-          profile: top,
-          z: 18,
-        },
-      ])
-    ),
-  ];
-});
-```
-
-The two rounded rectangles retain matching corner identities while their size and pose change.
-
-
-
-This [`loft`](../reference/model/loft.md) example places a rounded rectangle at two heights. Use
-`scale`, `rotate` and `translate` to pose the top profile in XY; `rotate` takes degrees. Each
-station uses `z` for an ordinary horizontal plane. To tilt a station, pass
-`frame: anchorFrame3(anchor3(position, direction, up))` instead; the direction chooses its
-normal and a nonparallel `up` vector chooses its roll.
-
-The primitive retains its corner identities, so `loft` pairs corresponding landmarks without
-extra setup. The same approach works when corners become square or fully rounded. For a hollow
-adapter, loft the outer shape and bore separately, then subtract the bore.
-
-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 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.
-
-## Sample a heightfield
-
-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 [`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
-[`mesh.immutable`](../reference/mesh/immutable.md) when returning it from a cached computation.
-
-
-
-```ts
-import { heightfield } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
-
-export default generate(({ part }) => {
-  return [
-    part(
-      "model",
-      heightfield({
-        coordinates: {
-          x: [-20, -18, -14, -8, 0, 8, 14, 18, 20],
-          y: [-12, -10, -6, 0, 6, 10, 12],
-        },
-        triangulation: "min-edge",
-        height: ([x, y]) => 3 + 0.8 * Math.cos(x / 6) * Math.cos(y / 5),
-      })
-    ),
-  ];
-});
-```
-
-
-
-The uneven axes place more samples near the border. Coordinates are absolute millimetres, strictly
-increasing, and must remain distinct in Float32 storage. For a uniform grid, replace `coordinates`
-with `size: [40, 24]` and `segments: [40, 24]`; this centers the footprint unless `origin` supplies
-its lower-left corner. Choose one sampling form per call.
-
-`baseZ` defaults to zero. Every height is an absolute Z coordinate strictly above that base;
-the builder preserves the sampled heights without rescaling them. It closes the top with shared
-boundary walls and a flat underside.
-
-| `triangulation`  | Selection per top cell                                                       |
-| ---------------- | ---------------------------------------------------------------------------- |
-| `"fixed"`        | The default lower-left to upper-right diagonal                               |
-| `"min-edge"`     | The shorter 3D diagonal, using the existing corner heights                   |
-| `"center-error"` | The diagonal whose interpolated center is closest to one extra height sample |
-
-All choices keep two triangles per cell and the same vertices. Center matching evaluates one
-additional physical midpoint per cell. Both selection policies use the fixed diagonal for ties.
-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.
-[`mesh.preflightHeightfield`](../reference/mesh/preflightHeightfield.md) reports output counts and
-checks limits without evaluating heights.
-
-## Text from a Font parameter
-
-Use this recipe for a label, plaque, or raised lettering whose font remains adjustable.
-
-1. Open **Model controls**, add a **Font** control with ID `font`, and choose its default face and
-   weight. Outfit and JetBrains Mono are bundled starter fonts.
-2. Choose **Apply & return** and use the generation program below in `model.ts`.
-   Studio prepares the selected font before the program lays out and extrudes its text.
-3. To make the wording adjustable, add a **Text** control with ID `label` and a non-empty default,
-   then replace the literal `"MetaMesh"` with `params.label`.
-
-
-
-```ts
-import { textSection } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
-
-export default generate(({ params, services, part }) => {
-  // The host has loaded the exact selected font before generation.
-  const layout = services.text.layout("MetaMesh", {
-    fontSize: 8,
-    font: params.font,
-    letterSpacing: 0.15,
-  });
-  // textSection preserves counters, such as the enclosed hole in the letter a.
-  return [part("label", textSection(layout).extrude({ height: 1.2 }))];
-});
-```
 
-The poster uses a pinned bundled Outfit face and preserves the counters inside each letter.
+### [Resolution and inspection](resolution-and-inspection.md)
 
+Model → checked result
 
+Choose physical curve detail, understand preflight guarantees, and inspect completed geometry.
 
-`textSection(layout)` converts prepared vector curves into a filled section, preserving holes in
-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.
+![A sampled relief tile with a rippled surface](https://metamesh.studio/docs/develop/heightfield.webp)
 
-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. Choose a minimum readable letter height
-and write parameter-specific error messages for your model.
 
 
 
-```ts
-import {
-  bounds2,
-  fitTextLayout,
-  type FittedTextLayout,
-  type VectorTextLayout,
-} from "@metamesh/modeling/geometry";
+For vectors, sampled
+boundaries, and profile correspondence, read [geometry values](geometry-values.md).
 
-export function labelFits(layout: VectorTextLayout): boolean {
-  const ink = layout.metrics.bounds;
-  return ink !== null && bounds2({ size: [40, 12] }).containsBounds(ink);
-}
+## Run and adapt an example
 
-export function fitLabel(layout: VectorTextLayout): FittedTextLayout {
-  // Fit visible ink while preserving proportions and preventing enlargement.
-  return fitTextLayout(layout, bounds2({ size: [40, 12] }), { maxScale: 1 });
-}
-```
+The guides identify their execution host. Most use a [Studio code Project](https://metamesh.studio/docs/develop/code-projects),
+where Studio supplies typed controls and prepared services. A [standalone model](standalone-model.md)
+uses the same shape operations with generation imported from `@metamesh/modeling`.
 
+1. Read the model beside its source, then inspect its optional interactive preview when orientation
+   or separate parts matter.
+2. Adapt the dimensions and connect them to [controls and validation](https://metamesh.studio/docs/develop/parameters-and-validation).
+3. Check the defaults, supported extremes, and optional features with
+   [resolution and inspection](resolution-and-inspection.md) before [exporting](https://metamesh.studio/docs/use/export-3mf).
 
-
-| Setting         | Meaning                                                                        |
-| --------------- | ------------------------------------------------------------------------------ |
-| `font`          | The complete Font control value, including the exact face revision and weight  |
-| `fontSize`      | Em size in millimetres; visible capital height depends on the font             |
-| `letterSpacing` | Extra millimetres between shaped glyph clusters                                |
-| `align`         | Left, center, or right alignment using the text's advance                      |
-| `verticalAlign` | First-line baseline by default, or top, center, or bottom using visible bounds |
-| `lineHeight`    | Baseline-spacing multiplier; omitted uses the font's natural line spacing      |
-
-For a circular label, add a [`baseline`](../reference/text/VectorTextArcBaseline.md) with
-`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. 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
-for that expected input; a missing glyph also requires different wording or a font that supports it.
-See [`TextSectionOptions`](../reference/model/TextSectionOptions.md) for exact options.
-
-Studio loads declared fonts before generation. Export uses the captured visible mesh. Saving a Project
-preserves the exact selection, including its revision, without embedding font bytes. Fonts beyond
-the bundled starters can require internet; ordinary browser caching does not guarantee them offline.
-If loading fails, Studio preserves the selection and last valid model so you can retry or choose a
-replacement. Studio does not support custom font uploads.
-
-## Solid inspection
-
-Use `solid.inspect()` during generation to check bounds, volume, and component count:
-
-
-
-```ts
-import { box } from "@metamesh/modeling";
-import { generate } from "@metamesh/project";
-
-export default generate(({ part }) => {
-  const result = box({ size: [40, 30, 5] });
-  const measurements = result.inspect();
-
-  if (measurements.bounds.min[2] < -2.5 || measurements.componentCount !== 1) {
-    throw new Error("Unexpected placement or disconnected result.");
-  }
-
-  return [part("model", result)];
-});
-```
-
-
-
-Use [`layoutRow`](../reference/geometry/layoutRow.md) to arrange pieces along +X with an explicit
-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, 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((piece) => piece.inspect().bounds),
-    { gap: 4 }
-  );
-  return pieces.map((geometry, index) =>
-    part(`piece-${index}`, { geometry, transform: transform3().translate(positions[index]!) })
-  );
-});
-```
-
-
-
-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
-every optional feature. Inspect the current result in Studio before exporting it. Continue with
-the [source and result contract](generation.md), or use the
-[Modeling API reference](../reference/model.md) for exact signatures and options.
+Keep expensive unchanged work in [memoized helpers](generation.md#reuse-unchanged-work)
+once the basic construction works. Mechanical fit needs a representative physical test as well as
+valid generated geometry.