@metamesh/modeling 0.18.0 → 0.20.0

package/dist/docs/guides/resolution-and-inspection.md

@@ -0,0 +1,153 @@
+# Choose resolution and check geometry
+
+Set physical sampling, understand preflight limits, and inspect evaluated dimensions and topology.
+
+Choose enough geometric detail for the feature you are making, then check the generated result.
+Sampling policy, preflight reports, and inspection answer different questions; a successful check
+does not establish a suitable manufacturing fit.
+
+## Coordinates, units, and resolution
+
+MetaMesh uses a right-handed coordinate system with **+Z up**. Authored dimensions and curve
+tolerances are millimetres; angular arguments such as `rotate` use degrees.
+Pure [`rotate2`](../reference/math/rotate2.md) and transform-value rotations also take degrees.
+The low-level [`rotationTransform3`](../reference/math/rotationTransform3.md) constructor
+requires an explicit `{ degrees }` or `{ radians }` angle.
+
+`GeometryResolution` controls sampled curves in physical space. Defaults are a `0.05 mm` maximum
+chord error, 16–512 segments per complete circle, and no maximum segment length. Settings apply
+in this order:
+
+1. An operation-specific `segments` or `circularSegments` count.
+2. The operation's local `resolution`.
+3. Host session defaults.
+
+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 can't fit within the safety cap, the operation fails instead of silently
+returning a coarser shape.
+
+## Check preflight guarantees
+
+Use a preflight to check inputs and see what an operation will require. Each preflight checks
+different things, so read what its report covers:
+
+- [`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.
+- [`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.
+
+Preflights are pure calculations: they run without an engine and use explicit options or package
+defaults. Threaded-part preflights live in `/geometry/mechanical`, including
+[`preflightThreadedRod`](../reference/mechanical/preflightThreadedRod.md),
+[`preflightInternalThreadCutter`](../reference/mechanical/preflightInternalThreadCutter.md), and
+[`preflightThreadedNut`](../reference/mechanical/preflightThreadedNut.md).
+
+Inside generation, pass the callback's effective `resolution` and `limits` to a preflight or
+[`matchProfiles`](../reference/geometry/matchProfiles.md) when its sampling and work budget must
+agree with the host. A pure helper never reads an ambient session.
+
+
+
+**Preflight is a plan, not a finished part**
+
+Passing covers only the report's documented checks. Callbacks, meshing, or native evaluation can
+  still fail. Run representative inputs and inspect the completed geometry.
+
+
+
+Constructors enforce their limits even when you skip preflight. Use a report when its sampling
+plan or diagnostics help you make a decision.
+
+## Lifecycle and inspection
+
+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.
+
+Before preview or export, the host finalizes returned geometry under its configured validation
+and resource policy. Inspecting one shape does not finalize every returned part.
+
+## Solid inspection
+
+Use `solid.inspect()` during generation to check bounds, volume, and component count. This example
+runs inside a [Studio code Project](https://metamesh.studio/docs/develop/code-projects); a standalone program uses the
+same queries inside its synchronous generation callback:
+
+
+
+```ts
+import { box, cylinder } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const plate = box({ size: [40, 30, 5] });
+  const bore = cylinder({ diameter: 10, height: 7 });
+  const result = plate.subtract(bore);
+  const facts = result.inspect();
+
+  if (facts.bounds.min[2] !== -2.5 || facts.componentCount !== 1) {
+    throw new Error("Expected one connected plate centered on Z.");
+  }
+
+  return part("plate", result);
+});
+```
+
+Inspect the cut block during generation, then return the same checked geometry as a part.
+
+
+
+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 } from "@metamesh/modeling";
+import { layoutRow, transform3 } from "@metamesh/modeling/geometry";
+
+export default 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]!),
+      color: index === 0 ? "#f6ad55" : "#60a5fa",
+    })
+  );
+});
+```
+
+Use each part’s evaluated bounds to place its geometry along +X with a deliberate gap.
+
+
+
+Check the default, smallest and largest supported dimensions, and every optional feature after
+adapting a recipe. Inspect the current result before [exporting it](https://metamesh.studio/docs/use/export-3mf).

package/dist/docs/guides/solid-joins.md

@@ -0,0 +1,136 @@
+# Join a feature to a base
+
+Add a smooth or straight transition between independently modeled solids while retaining their geometry.
+
+Use a solid join to connect a mounting boss, handle root, or similar feature to a base. Model and
+position the complete feature first. Choose a smooth blend or straight transition; both retain
+the supplied solids and their existing details.
+
+Run the examples in a [Studio code Project](https://metamesh.studio/docs/develop/code-projects), where Studio supplies
+typed controls and prepared services. For a local model, follow the
+[standalone workflow](standalone-model.md) and use its host entry point.
+
+## Join an independently modeled feature
+
+
+
+```ts
+import { box, cylinder } from "@metamesh/modeling";
+import { anchor3 } from "@metamesh/modeling/geometry";
+import { generate } from "@metamesh/project";
+
+const base = box({ size: [40, 28, 6] });
+const feature = cylinder({
+  diameter: 12,
+  height: 14,
+  center: false,
+  ends: { top: { kind: "chamfer", distance: 0.5 } },
+})
+  .translate([0, 0, 2])
+  .subtract(
+    cylinder({ diameter: 4, height: 16, center: false }).rotate([90, 0, 0]).translate([0, 8, 12])
+  )
+  // Boolean geometry defines its own datum; the collar below the cross-bore stays straight.
+  .withAnchors({ mount: anchor3({ position: [0, 0, 2], direction: [0, 0, -1] }) });
+
+const mount = base.join(feature, {
+  source: "mount",
+  transition: { width: 3, height: 4 },
+});
+
+export default generate(({ part }) => part("mount", mount));
+```
+
+The supplied boss keeps its top chamfer and cross-bore; the join adds only the root transition.
+
+
+
+Construct and position the feature independently. Here its lower cap lies inside the plate,
+and a straight collar remains below the cross-bore. The Boolean-composed feature defines a
+`mount` datum with its outward normal pointing toward the base. `source: "mount"` resolves that
+datum when the join evaluates, so the completed recipe can be declared before an engine exists.
+
+
+
+**Place the feature before joining**
+
+A join adds the root transition to an already positioned feature. Check the collar and support
+  requirements below; joining does not close a gap or move the feature into place.
+
+
+
+The result has no inherited anchors. Define result datums with `withAnchors` when later work needs them.
+
+## Define the connection
+
+Call [`solid.join(feature, options)`](../reference/model/Solid.md#join) after constructing and
+positioning the feature. Supply `source`, a named feature datum or explicit `Anchor3`, and a
+`transition` with `width`, `height`, and optional `kind`. The named datum resolves lazily;
+recipe declaration needs no engine.
+The source plane may lie in empty space when the existing feature already spans the selected
+support patch; it is a lower datum, not a required contact plane.
+Joining preserves both operands and adds material, while `union` remains ordinary Boolean fusion.
+
+The datum selects the complete feature section in its plane. Holes and disconnected roots are
+supported when each satisfies the same connection requirements. Two straight roots sharing a
+datum plane and axis can therefore receive their transitions in one join; the datum is not a
+selector for the nearest root.
+
+Only the local feature collar must be straight and constant-section. The rest of the feature may
+contain bores or other geometry. The actual support patch may be planar, tilted, or curved when
+it forms a continuous height chart along that collar's axis. Unsupported or ambiguous contact,
+an incomplete collar, a gap, or exhausted validation rejects. Joining never positions or extends
+the feature. The straight collar must continue by `height` beyond the highest support contact
+anywhere under the expanded footprint, including its outer transition boundary.
+
+Join `width` is the projected normal offset from the feature boundary and `height` is reach along
+its collar axis above local contact. Miter corners can extend farther than the width. Both dimensions
+must be positive, or both zero to disable added blending while still validating the connection.
+
+## Choose the transition
+
+
+
+```ts
+import { box } from "@metamesh/modeling";
+import { transform3 } from "@metamesh/modeling/geometry";
+import { generate } from "@metamesh/project";
+
+const base = box({ size: [24, 20, 4] });
+const rib = box({ size: [8, 4, 12] }).translate([0, 0, 7]);
+
+const smooth = base.join(rib, {
+  source: "bottom",
+  transition: { width: 2, height: 3 },
+});
+const straight = base.join(rib, {
+  source: "bottom",
+  transition: { kind: "straight", width: 2, height: 3 },
+});
+
+export default generate(({ part }) => [
+  part("smooth", {
+    geometry: smooth,
+    color: "#6f9eaa",
+    transform: transform3().translate([-16, 0, 0]),
+  }),
+  part("straight", {
+    geometry: straight,
+    color: "#d6aa58",
+    transform: transform3().translate([16, 0, 0]),
+  }),
+]);
+```
+
+
+
+- `"smooth"` is the default and adds a tangent-matching cubic blend.
+- `"straight"` adds a linear planar bevel along each sampled support facet. On curved support,
+  this does not imply one constant bevel angle around the connection.
+
+These settings describe transition width and height, rather than a circular fillet radius.
+`"chamfer"` and `"round"` are not join kinds, and a `radius` option is rejected. Use the
+[`JoinOptions`](../reference/model/JoinOptions.md) contract for exact fields. Apply independent
+[free-end finishing](profiles-and-extrusion.md#finish-a-profile-with-a-hole) while
+constructing the feature. Sampling follows the physical policy and preserves the operands'
+supplied facets.

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

@@ -22,6 +22,8 @@ export default generate<Record<never, never>>(({ part }) => {
 });
 ```
 
+The centered 6 mm plate is cut by an 8 mm tall cylinder so the hole crosses both faces.
+
 
 
 The cutter extends beyond both faces of the centered plate. `part("plate", ...)` gives the output
@@ -29,7 +31,7 @@ a stable ID so you can identify the plate in the result. This model takes an emp
 
 ## Check and run
 
-With [Modeling and the CLI installed](https://metamesh.studio/docs/develop/agent-authoring#install-and-discover-the-environment),
+With [Modeling and the CLI installed](https://metamesh.studio/docs/develop/cli#install-and-discover-the-environment),
 check the source and generate a captured result:
 
 ```bash
@@ -37,7 +39,7 @@ 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),
+Continue with [inspection and rendering](https://metamesh.studio/docs/develop/cli#inspect-the-captured-result),
 or [host the program in your application](hosting.md).
 When you're ready for a different shape, the
-[construction chooser](concepts.md#choose-a-modeling-path) helps you pick an approach.
+[construction chooser](recipes.md#choose-a-technique) helps you pick an approach.

package/dist/docs/guides/svg-and-text.md

@@ -0,0 +1,252 @@
+# Make solids from SVG and text
+
+Extrude imported SVG artwork or exact-font lettering, and fit its visible outline in millimetres.
+
+Build a badge, sign, or label from vector artwork. SVG controls supply painted shapes; Font and
+Text controls supply exact lettering. Both become filled Sections that you can extrude or combine
+with other material.
+
+Run the examples in a [Studio code Project](https://metamesh.studio/docs/develop/code-projects), where Studio supplies
+typed controls and prepared services. For a local model, follow the
+[standalone workflow](standalone-model.md) and use its host entry point.
+
+## SVG sections: fills and strokes are different inputs
+
+Use `svgSection` for a complete SVG document, where supported visible fills and bounded strokes
+contribute material. Use `svgPathSection` for path-data text: it is fill-only and does not apply
+stroke styling. Both convert SVG’s Y-down coordinates to the model’s Y-up plane and center the
+painted bounds by default. `origin: "document"` retains the converted document viewport origin.
+
+## SVG parameter and extrusion
+
+Add an **SVG** control with ID `artwork` in **Model controls**, then pass its string value directly
+to `svgSection`:
+
+
+
+```ts
+import { svgSection } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ params, part }) => {
+  const profile = svgSection(params.artwork);
+  return part("model", profile.extrude({ height: 3, center: true }));
+});
+```
+
+
+
+`svgSection` also accepts a constant SVG document. This single path combines curved scallops
+and a star-shaped opening; the artwork stays outside `generate` because it does not depend on controls:
+
+
+
+```ts
+import { svgSection } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+// One path combines a curved outer edge with a star-shaped opening.
+const artwork = `
+  <svg xmlns="http://www.w3.org/2000/svg" width="48mm" height="32mm" viewBox="0 0 48 32">
+    <path
+      fill-rule="evenodd"
+      d="
+        M 24 0
+        C 28 0 29 4 33 4 C 37 2 41 4 41 8
+        C 45 8 48 12 48 16 C 48 20 45 24 41 24
+        C 41 28 37 30 33 28 C 29 28 28 32 24 32
+        C 20 32 19 28 15 28 C 11 30 7 28 7 24
+        C 3 24 0 20 0 16 C 0 12 3 8 7 8
+        C 7 4 11 2 15 4 C 19 4 20 0 24 0 Z
+        M 24 7 L 26.5 12.6 L 32.5 13.3 L 28 17.6 L 29.2 24
+        L 24 20.8 L 18.8 24 L 20 17.6 L 15.5 13.3 L 21.5 12.6 Z
+      "
+    />
+  </svg>
+`;
+
+export default generate(({ part }) => {
+  const badge = svgSection(artwork);
+  return part("badge", badge.extrude({ height: 4, center: true }));
+});
+```
+
+A 48 × 32 × 4 mm badge combines smooth cubic curves and a crisp star-shaped opening in one SVG path.
+
+
+
+The even-odd fill rule makes the second subpath a hole regardless of winding. Complete documents
+honor supported physical root units and `viewBox`. With `svgPathSection`, one user unit defaults
+to 1 mm; its `scale` option chooses 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 { rectangle, svgSection } from "@metamesh/modeling";
+import { bounds2 } from "@metamesh/modeling/geometry";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const target = bounds2({ size: [30, 18] });
+  const artwork = svgSection('<svg><circle r="1"/></svg>', {
+    fit: target,
+    resolution: { maxChordError: 0.05 },
+  });
+  // The outline marks the available 30 × 18 mm rectangle, outside the artwork.
+  const outline = rectangle({ size: [31, 19] }).subtract(rectangle({ size: [30, 18] }));
+  return [
+    part("artwork", { geometry: artwork.extrude({ height: 0.8 }), color: "#f6ad55" }),
+    part("target-outline", { geometry: outline.extrude({ height: 0.35 }), color: "#60a5fa" }),
+  ];
+});
+```
+
+Fit the painted outline in millimetres before sampling and extrusion, preserving its aspect ratio.
+
+
+
+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.
+
+Round stroke caps are outward semicircles aligned with their end segments. Each cap uses
+`ceil(circularSegments / 2)` intervals, following the shared arc-sampling policy; odd counts are
+accepted. This also applies to pure `strokeRegionData` and authored `stroke` Sections.
+
+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, nested SVG viewports, clipping, masks, filters, scripts, animation, gradients, patterns,
+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.
+
+## Text and font variability
+
+Studio prepares the selected font before generation. `services.text.layout()` shapes the text
+synchronously; cache an expensive shared layout with `memo`, then pass it to `textSection`. A
+stable helper that needs parameters and fixed services receives the full generation context.
+There is no ambient font provider, and export uses the captured mesh rather than shaping again.
+
+## 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 [`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 { rectangle, textSection } from "@metamesh/modeling";
+import {
+  bounds2,
+  fitTextLayout,
+  type FittedTextLayout,
+  type VectorTextLayout,
+} from "@metamesh/modeling/geometry";
+import { generate } from "@metamesh/project";
+
+function labelFits(layout: VectorTextLayout): boolean {
+  const ink = layout.metrics.bounds;
+  return ink !== null && bounds2({ size: [40, 12] }).containsBounds(ink);
+}
+
+function fitLabel(layout: VectorTextLayout): FittedTextLayout {
+  // Fit visible ink while preserving proportions and preventing enlargement.
+  return fitTextLayout(layout, bounds2({ size: [40, 12] }), { maxScale: 1 });
+}
+
+export default generate(({ services, params, part }) => {
+  const layout = services.text.layout("MetaMesh", { font: params.font, fontSize: 20 });
+  const fitted = fitLabel(layout);
+  if (!labelFits(fitted)) throw new Error("Keep the lettering inside the label area.");
+  const backing = rectangle({ size: [44, 16], treatment: { kind: "round", radius: 2 } }).extrude({
+    height: 2,
+  });
+  const lettering = textSection(fitted).extrude({ height: 0.8 }).translate([0, 0, 2]);
+  return [
+    part("backing", { geometry: backing, color: "#60a5fa" }),
+    part("lettering", { geometry: lettering, color: "#f6ad55" }),
+  ];
+});
+```
+
+Fit the visible letter outlines to the label area before turning them into material.
+
+
+
+| 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.
+
+
+
+**Prepare for offline lettering**
+
+Saving a Project keeps the exact font selection, not its bytes. Fonts beyond the bundled starters
+  can need internet. Check the [font and offline
+  rules](https://metamesh.studio/docs/use/projects-and-offline#fonts-while-offline) before relying on a model away from a
+  connection.