@metamesh/modeling 0.12.0 → 0.13.0

package/dist/docs/guides/recipes.md

@@ -0,0 +1,668 @@
+# Modeling recipes
+
+Adapt typechecked patterns for sections, SVG, text, extrusion, sweeps, heightfields, booleans, placement, anchors, and inspection.
+
+Build a plate, route a section through space, join profiles, or place repeated features. Each
+illustrated recipe pairs its complete source with a render of that exact source. Open
+the interactive preview to orbit the result; copy the code into a Studio code Project to edit it.
+
+| 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          |
+
+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.
+The examples default-export a synchronous `generate` program. Use ordinary assertions for constraints
+and optional `computed` values for expensive/shared dimensions, geometry or text layouts.
+[Define parameters and validation](https://metamesh.studio/docs/develop/parameters-and-validation) connects
+source values to controls.
+
+## Section, hole, offset, and extrusion
+
+
+
+```ts
+import { circle, rectangle } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+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 }))];
+});
+```
+
+Subtract the opening in 2D, offset the filled material, then extrude it into one plate.
+
+
+
+`rectangle` and `circle` take object options and return filled Sections. `section.subtract(cutters)` and the `union` and `intersect` functions also support Solids,
+with same-dimensional operands in each call. `section.offset(distance)` preserves the filled
+topology. `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
+
+An SVG control is exposed to authored code as a string on the immutable `parameters` argument. Pass
+that string directly to `svgSection`; no DOM parsing or editor-specific JSON is needed.
+
+
+
+```ts
+import { svgSection } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ params: parameters, part }) => {
+  const profile = svgSection(parameters.profile6);
+  return [part("model", profile.extrude({ height: 3, center: true }))];
+});
+```
+
+
+
+The property name is the control ID shown in the model-controls editor. For example, use
+`parameters.logo` when the SVG control ID is `logo`.
+
+The same function also accepts literal SVG documents. Here two nested paths produce one badge
+with a rectangular opening:
+
+
+
+```ts
+import { inspectSection, svgSection } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+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 = inspectSection(badge);
+  if (measurements.parts !== 1 || measurements.contours !== 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` 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
+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.
+
+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.
+
+## 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.
+
+
+
+```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
+`revolveDegrees: 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.
+
+
+
+```ts
+import { ellipse, regularPolygon, sphere, star, torus, 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("torus", {
+      geometry: torus({ majorRadius: 7, minorRadius: 2 }),
+      position: [24, 0, 2],
+      color: "#34d399",
+    }),
+    part("tube", {
+      geometry: tube({ outerRadius: 7, innerRadius: 4, height: 10, center: false }),
+      position: [48, 0, 0],
+      color: "#f59e0b",
+    }),
+    part("ellipse", {
+      geometry: ellipse({ size: [18, 12] }).extrude({ height: 5 }),
+      position: [0, 24, 0],
+      color: "#c084fc",
+    }),
+    part("star", {
+      geometry: star({ outerRadius: 9, innerRadius: 4.5, points: 5 }).extrude({ height: 5 }),
+      position: [24, 24, 0],
+      color: "#fb7185",
+    }),
+    part("hexagon", {
+      geometry: regularPolygon({ radius: 7, sides: 6, sizing: "face" }).extrude({ height: 5 }),
+      position: [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],
+    angleDegrees: 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).
+
+## Rotation-minimizing path sweep
+
+
+
+```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.
+
+
+
+`section.sweep(path, options)` transports the filled shape along the path. Choose the starting profile-X direction with
+`orientation: { kind: "transport", initialNormal: [0, 1, 0] }`. Fixed normals, directed normal guides
+and discrete Frenet frames are explicit alternative policies; singular selected policies reject.
+`twistDegrees` adds total rotation, following physical path length by default; `twistBy: "stations"`
+uses the authored station schedule. `scale` accepts a positive uniform size, 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
+
+
+
+```ts
+import { anchor, 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"), {
+    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 `anchor(base, "top")` follows the box's dimensions
+and placement. `pin.attach("bottom", anchor(base, "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: createAnchor3(position, direction, up) })` to define a custom datum
+on a new handle. 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.
+
+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 `placement` uses the same source/target anchor, `alignment`, `gap` and `spinDegrees`
+vocabulary as `attach`, including a named `source`. It applies after local shape construction. Filled Section placement 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(createAnchor3(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 need deliberate
+`correspondence: "direct"`, `"reindex"`, `"fast-distance"`, or `"distance"`, or explicit profiles;
+contour order does not establish 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. Imported
+[`heightfield`](../reference/model/heightfield.md) returns a Solid for booleans and placement during
+generation. Pure [`heightfieldMesh`](../reference/geometry/heightfieldMesh.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.
+
+
+
+```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.
+[`preflightHeightfield`](../reference/geometry/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.
+
+
+
+`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.
+
+Check a positioned label with [`containsBounds`](../reference/geometry/containsBounds.md),
+using [`boundsFromSize`](../reference/geometry/boundsFromSize.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.
+
+
+
+```ts
+import {
+  boundsFromSize,
+  containsBounds,
+  fitTextLayout,
+  type FittedTextLayout,
+  type VectorTextLayout,
+} from "@metamesh/modeling/geometry";
+
+export function labelFits(layout: VectorTextLayout): boolean {
+  const ink = layout.metrics.bounds;
+  return ink !== null && containsBounds(boundsFromSize([40, 12]), ink);
+}
+
+export function fitLabel(layout: VectorTextLayout): FittedTextLayout {
+  // Fit visible ink while preserving proportions and preventing enlargement.
+  return fitTextLayout(layout, boundsFromSize([40, 12]), { maxScale: 1 });
+}
+```
+
+
+
+| 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 each line's advance width               |
+| `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      |
+
+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. Custom font uploads and text on paths are not supported.
+
+## Solid inspection
+
+
+
+```ts
+import { box, inspectSolid } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const result = box({ size: [40, 30, 5] });
+  const measurements = inspectSolid(result);
+
+  if (measurements.min[2] < -2.5 || measurements.parts !== 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 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.
+
+
+
+```ts
+import { box, generate, inspectSolid } 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 });
+  return pieces.map((geometry, index) =>
+    part(`piece-${index}`, { geometry, position: 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: product-specific minimum walls, overhangs, fits and
+parameter messages remain the Generator's job.
+
+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.