@metamesh/modeling 0.17.0 → 0.19.0

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

@@ -0,0 +1,133 @@
+# 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/geometry/rotate2.md) and transform-value rotations also take degrees.
+The low-level [`rotationTransform3`](../reference/geometry/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.
+
+The `/geometry` and `mesh` preflights run without an engine and use explicit options or package defaults.
+The root [`preflightThreadedRod`](../reference/model/preflightThreadedRod.md),
+[`preflightInternalThreadCutter`](../reference/model/preflightInternalThreadCutter.md), and
+[`preflightThreadedNut`](../reference/model/preflightThreadedNut.md) require active synchronous
+model execution and use the host's resolution and limits.
+
+Passing a preflight covers only its documented checks. Construction can still fail while running
+callbacks, meshing, or evaluating native geometry. Constructors enforce their limits even when
+you skip a preflight; use one when its plan or diagnostics help you make a decision.
+
+## Lifecycle and inspection
+
+Studio or your standalone host handles initialization, cleanup, finalization, Worker recovery,
+preview, and file delivery. Don't manually delete `Section` or `Solid` values. Use
+`shape.inspect()` for bounds, topology counts, area, and volume.
+Its immutable extrema are nested under `facts.bounds.min` and `facts.bounds.max`.
+Native `componentCount` counts disconnected material components. Mesh analysis and signatures use
+`shellCount` for surfaces connected by shared indexed edges: one sealed hollow body has one material
+component and two shells. Open mesh analysis can also count open shells; this count does not certify
+closed topology or geometric validity.
+
+Queries such as `shape.inspect()`, `shape.isEmpty()`, `shape.components()`, `shape.anchor(name)`,
+`solid.distance(other)`, and `solid.castSegment(origin, endpoint)` read evaluated geometry.
+These queries and interchange with `solid.toMesh()` or `section.toRegionData()` require the host's
+active synchronous generation. `solid.split(cutter)` returns the intersection and remainder;
+`solid.splitByPlane(plane)` returns the positive and negative sides of the plane.
+Constructing or combining a recipe outside generation doesn't evaluate it.
+
+An inspection result describes the generated geometry; it doesn't certify wall thickness,
+overhangs, fits, loads, or manufacturability. Express those requirements in your parameters and
+validation, then check them in your manufacturing workflow.
+
+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 } 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]!) })
+  );
+});
+```
+
+
+
+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,126 @@
+# 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([0, 0, 2], [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.
+
+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, transform3 } from "@metamesh/modeling";
+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

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

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

@@ -0,0 +1,215 @@
+# 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
+
+Pass an SVG control's string value from `params` directly to `svgSection`. This example aliases
+`params` as `parameters`:
+
+
+
+```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 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:
+
+
+
+```ts
+import { 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 = 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.
+
+
+
+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 { 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, 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 {
+  bounds2,
+  fitTextLayout,
+  type FittedTextLayout,
+  type VectorTextLayout,
+} from "@metamesh/modeling/geometry";
+
+export function labelFits(layout: VectorTextLayout): boolean {
+  const ink = layout.metrics.bounds;
+  return ink !== null && bounds2({ size: [40, 12] }).containsBounds(ink);
+}
+
+export function fitLabel(layout: VectorTextLayout): FittedTextLayout {
+  // Fit visible ink while preserving proportions and preventing enlargement.
+  return fitTextLayout(layout, bounds2({ size: [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 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/geometry/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.