@metamesh/modeling 0.13.0 → 0.14.0

package/dist/api/text.d.ts

@@ -1,9 +1,9 @@
 /** Axis-aligned bounds in two-dimensional model space. */
 export declare interface Bounds2 {
   /** Inclusive maximum X/Y coordinates. */
-  readonly max: Vector2;
+  readonly max: Vector2Tuple;
   /** Inclusive minimum X/Y coordinates. */
-  readonly min: Vector2;
+  readonly min: Vector2Tuple;
 }
 
 /** Limits apply before parsing or shaping untrusted font data. */
@@ -26,7 +26,7 @@ export declare function prepareVectorFont(
 ): Promise<VectorFont>;
 
 /** A two-dimensional Cartesian vector or point. */
-export declare type Vector2 = readonly [x: number, y: number];
+export declare type Vector2Tuple = readonly [x: number, y: number];
 
 /**
  * A prepared font owns its parsed bytes; keep handles local to their Worker or invocation.

package/dist/docs/guides/concepts.md

@@ -14,7 +14,7 @@ import { generate } from "@metamesh/project";
 
 
 Studio supplies this API and its runtime to code Projects. Standalone applications use the same
-operations inside a generation program. The [Model API reference](../reference/model.md) provides
+values in a generation program. The [Model API reference](../reference/model.md) provides
 exact signatures; this guide explains how the concepts fit together.
 
 ## Choose the module for your host
@@ -26,8 +26,9 @@ exact signatures; this guide explains how the concepts fit together.
 | [`@metamesh/modeling/engine`](../reference/engine.md)     | Standalone initialization, model finalization, and 3MF export       | Your Node application or browser Worker |
 | [`@metamesh/modeling/text`](../reference/text.md)         | Prepare exact font bytes and vector layouts outside Studio          | Your host acquires the font bytes       |
 
-Call root modeling operations inside synchronous generation. Add pure geometry helpers for custom
-calculations.
+Construct immutable shapes, vectors, and transforms in ordinary TypeScript and reuse them in
+synchronous generation. A host evaluates geometry and owns observations and export. Add pure
+geometry helpers for custom calculations.
 
 ## Use Modeling outside Studio
 
@@ -42,8 +43,8 @@ The public API names values by modeling role:
 - A `Path3` is an ordered 3D trajectory.
 - A `Path2` is an ordered 2D trajectory.
 - A `Contour` is plain point data for a closed 2D boundary, without a repeated closing point.
-- A `Polygon` is explicit point data for one outer contour and its holes. A `Region` contains
-  disjoint polygons; neither is an engine-owned modeling handle.
+- `PolygonData` contains one outer contour and its holes. `RegionData` is the plain serialized
+  representation of filled 2D geometry, including disconnected polygons.
 - A `Profile` specifies identified components, contours and spans for a related shape family.
 - A `CorrespondingProfile` contains the shared sampled landmarks produced by `matchProfiles`.
 - A `Section` is a filled 2D shape used for section Booleans, offsets, extrusion, revolution,
@@ -51,11 +52,16 @@ The public API names values by modeling role:
 - A `Solid` is a valid three-dimensional result that can participate in solid Booleans and become
   model output.
 - An `Anchor3` is an explicit local frame used to place one solid against another.
-- `Vector2` and `Vector3` are fixed numeric tuples for low-level coordinates.
+- `Vector2` and `Vector3` are immutable arithmetic values created by `vector2` and `vector3`.
+- `Vector2Tuple` and `Vector3Tuple` are fixed numeric tuples for coordinate interchange and kernels.
 - `Bounds2` and `Bounds3` contain finite minimum and maximum tuples for measurements and placement.
 
-`Section` and `Solid` are opaque, evaluator-owned handles. Authored code chains their immutable
-methods and combines collections through imported functions. The engine owns native kernel values.
+`Section` and `Solid` are opaque immutable recipes. Construction and composition need no engine;
+ordinary recipes can be reused across sessions regardless of where they were constructed.
+Explicitly supplied resolution settings are captured; unspecified settings inherit the evaluating
+host's defaults. The host owns evaluation caches and native kernel values. `components()` is an
+observation: its selected shapes, and recipes using them, can only be evaluated in the originating
+session because component identity depends on evaluated topology.
 
 Ordinary models use root Sections for shapes, Booleans, extrusion, sweeps, and lofts. The pure
 `/geometry` entry supplies point data through `circleContour`, `rectangleContour`, and other contour factories
@@ -66,8 +72,10 @@ reflects the operation's role.
 Use [`polygon(points)`](../reference/model/polygon.md) to fill one contour. The explicit
 `polygon({ outer, holes })` form validates exterior/hole topology and normalizes winding.
 `polygon({ contours, fillRule })` resolves compound paths with `"nonzero"` fill by default or
-explicit `"evenodd"` fill. These constructors return the same `Section` type as `circle` or
-`rectangle`; subsequent Booleans may produce holes or disconnected components.
+explicit `"evenodd"` fill. Use `polygon({ polygons: data })` for existing `RegionData`.
+Every form returns the same `Section` type as `circle` or `rectangle`; subsequent Booleans may
+produce holes or disconnected components. `section.toRegionData()` observes the evaluated shape
+inside synchronous generation. Keep serialized point data for interchange or pure preparation.
 
 `rectangleProfile({ size: [width, height], treatment: { kind: "round", radius }, id })` describes
 identified spans for custom geometry. Prepare a complete explicit family with `matchProfiles`
@@ -112,6 +120,9 @@ degree twist, uniform/XY/per-station scales and an explicit compatible closed se
 
 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-chain 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. The default maximum chord error is
 `0.05 mm`, with 16–512 segments for a complete circle and no default maximum segment length. An
@@ -139,6 +150,94 @@ including holes and twist.
 `placement` maps a named or explicit shape-local anchor to a world anchor after local
 construction, using alignment, millimetre gap and degree spin. Section placement must stay in XY.
 
+## Reuse a transform across shapes and coordinates
+
+Use [`transform2`](../reference/geometry/transform2.md) and
+[`transform3`](../reference/geometry/transform3.md) chains for reusable placements. They are immutable
+and pure; no engine initialization is needed. Calls apply in written order. A rotation followed
+by a translation rotates around the origin, then moves the result:
+
+
+
+```ts
+import { transform3, vector3 } from "@metamesh/modeling";
+
+// Calls apply in written order: rotate, then translate.
+const placement = transform3().rotate([0, 0, 90]).translate([20, 0, 5]);
+export const placedPoint = placement.applyPoint([10, 0, 0]); // approximately [20, 10, 5]
+export const placedDirection = placement.applyDirection([10, 0, 0]); // approximately [0, 10, 0]
+```
+
+
+
+Pass a transform directly to `solid.transform(placement)`, `section.transform(placement)` and
+matching path helpers. `toMatrix()` supplies a canonical matrix when another system needs it.
+Construct the placement once and reuse it across point collections.
+
+`current.andThen(next)` applies `current` first and `next` second, accepting another chain or a
+same-dimensional matrix. `inverse()` returns the reverse placement. Transform-building operations
+return new chains, so shared placements can branch safely.
+
+Use `rotate(degrees, { pivot })` or `scale(factors, { pivot })` to work around a world-space pivot after
+the preceding operations. In 3D, `rotate` takes XYZ Euler degrees, applied about global X, Y, then
+Z; `rotateAxis(axis, degrees, { pivot })` normalizes its nonzero axis. Omitted pivots use the
+coordinate origin. Uniform and per-axis scales
+must be finite and nonzero; negative factors reflect. Nonfinite inputs, invalid axes, and singular
+matrices throw `GeometryError`.
+
+`applyPoint` includes translation. `applyDirection` excludes translation and preserves scale;
+its result is not normalized. `applyNormal` applies the inverse transpose and returns a unit normal,
+including under nonuniform scaling; it rejects zero normals. All three return fluent vectors.
+
+`Transform2` works directly with Sections and pure XY helpers; its `Transform2Matrix` is the same
+canonical 3x3 representation throughout. Use `to3D()` when that XY placement
+also needs to position a Solid or 3D path. The reverse `to2D()` conversion rejects transforms
+that move the XY plane or collapse its dimensions; it does not project 3D points.
+See the [2D placement recipe](recipes.md#reuse-a-2d-placement).
+
+For low-level matrix interoperability, the factories accept existing canonical matrices. Use
+`transform3(frameTransform3(frame))` for an orthonormal frame. The raw constructors and
+`composeTransform3(after, before)` remain available; composition applies `before` first.
+
+## Calculate with vectors
+
+Use [`vector2`](../reference/geometry/vector2.md) and [`vector3`](../reference/geometry/vector3.md)
+for readable arithmetic chains. Operands accept tuples or vectors; `dot`, `length` and `distance`
+return numbers. `cross` returns a signed scalar in 2D and a right-handed vector in 3D.
+
+
+
+```ts
+export const direction = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
+export const alignment = direction.dot([0, 0, 1]); // number
+```
+
+
+
+Values snapshot their input and operations return new values. `toArray()` returns the value's
+frozen coordinate tuple without allocating another copy. Normalization rejects zero-length vectors;
+nonfinite coordinates, scalar parameters and overflowing results throw `GeometryError`.
+
+For rotations and nonuniform scaling, use a reusable transform's `applyDirection`. Use
+`applyNormal` for surface normals:
+
+
+
+```ts
+const stretched = transform3().scale([2, 1, 1]);
+export const normal = stretched.applyNormal([1, 1, 0]);
+export const tangent = stretched.applyDirection([1, -1, 0]);
+export const perpendicular = normal.dot(tangent); // approximately 0
+```
+
+
+
+The tuple arithmetic kernels remain available for dense numerical loops. Fluent values add
+validation and immutable object allocation; they are an authoring convenience, not a speedup.
+Fluent math, shape transforms and part placement accept vector values directly; geometry
+specifications and point collections use canonical tuples.
+Keep simple coordinate expressions and equations intrinsic to the model beside the model.
+
 ## SVG sections: fills and strokes are different inputs
 
 [`svgSection`](../reference/model/svgSection.md) converts a bounded complete SVG document into one
@@ -169,7 +268,8 @@ ambient font provider or repeated shaping during export. Declare a Text control
 and a Font control for the face and weight.
 
 Font size is the em size in millimetres, not the height of a particular letter. Layout supports
-multiple lines, spacing, and alignment. Follow the
+horizontal lines, spacing, and alignment, or a single circular baseline through
+[`VectorTextArcBaseline`](../reference/text/VectorTextArcBaseline.md). Follow the
 [text recipe](recipes.md#text-from-a-font-parameter) for the control setup,
 layout conventions, and font availability limits.
 
@@ -189,6 +289,9 @@ values. Use
 `inspectSection()` and `inspectSolid()` for supported bounds, topology counts, area, and volume
 measurements.
 
+Observations, including `section.toRegionData()`, require the host's active synchronous generation.
+Constructing or composing a recipe outside generation does not evaluate it.
+
 An inspection result describes the generated geometry; it does not certify wall thickness,
 overhangs, fits, loads, or manufacturability. Keep those product decisions in parameters,
 validation, and your downstream manufacturing checks.

package/dist/docs/guides/fonts.md

@@ -18,6 +18,9 @@ pnpm add woff2-encoder
 TTF, OTF, and WOFF input use fontkit directly. WOFF2 decoding loads only when needed. The library
 does not fetch fonts; your application supplies their bytes.
 
+For a static face whose actual weight is not 400, pass that weight through `staticWeight` when
+preparing it. This identifies the supplied face; it does not synthesize another weight.
+
 ## Prepare one reusable layout
 
 
@@ -47,5 +50,10 @@ Call `makeLabelLayout(fontBytes)` with the acquired bytes. It returns a `layout`
 section with the ordinary modeling operations. A host can prepare layouts ahead of time or inject
 a deterministic text service and cache layouts with `computed`.
 
+The same layout options support horizontal lines or one circular line through
+[`VectorTextArcBaseline`](../reference/text/VectorTextArcBaseline.md). The
+[text recipe](recipes.md#text-from-a-font-parameter) explains units, alignment,
+metrics, and circular-text constraints.
+
 Use the [Font preparation reference](../reference/text.md) for font and layout options, or
 [Run Modeling in your application](hosting.md) for the host lifecycle.

package/dist/docs/guides/fundamentals.md

@@ -119,8 +119,10 @@ those resources for each run and cleans them up deterministically. Authored code
 initialize the kernel or manually delete a `Section` or `Solid`.
 
 Use `inspectSection()` or `inspectSolid()` when you need supported measurements such as bounds,
-area, volume, or part counts. Return an array of `part(...)` declarations to hand the final result
-back to Studio for preview and export.
+area, or volume. A Section's `parts` count describes disconnected filled components; a Solid's
+`parts` count describes connected surface shells, including inward cavity shells. Neither counts
+the named output parts you declare with `part(...)`. Return one declaration or an array of them
+to hand the final result back to Studio for preview and export.
 
 
 

package/dist/docs/guides/generation.md

@@ -199,10 +199,12 @@ instance limits, including cache hits. Empty output is invalid.
 
 ## Ownership and recovery
 
-Solids and Sections describe deferred recipes owned by the session. Observations such as
-`inspectSolid` realize their required geometry synchronously and return copied facts. Native
-allocations belong only to the active transaction and are cleaned on success and failure. Authors
-do not dispose native handles or use them across sessions. Nested or asynchronous execution rejects.
+Solids and Sections describe immutable deferred recipes. Ordinary recipes are reusable across
+sessions regardless of where constructed; unspecified resolution settings inherit the evaluating
+host's defaults. Observations such as `inspectSolid` realize required geometry synchronously and
+return copied facts. `components()` selections, and recipes using them, can only be evaluated in
+the originating session because their identity depends on evaluated topology. The host owns
+native allocations and cleanup on success and failure. Nested or asynchronous execution rejects.
 Apply local resolution explicitly to each affected constructor or Section operation.
 
 Source/control-definition changes invalidate the program session. Parameter edits reuse it.

package/dist/docs/guides/hosting.md

@@ -32,12 +32,15 @@ export async function makePlate3mf(): Promise<ArrayBuffer> {
       return [part("plate", { geometry: plate.subtract([bore]), color: "#67e8f9" })];
     })
   );
-  const model = session.run({});
-  // Generation already disposed native handles. These finalized meshes remain usable.
   try {
-    return await engine.export3mf(model.parts, { name: "Plate" });
+    const model = session.run({});
+    // Generation already disposed native handles. These finalized meshes remain usable.
+    try {
+      return await engine.export3mf(model.parts, { name: "Plate" });
+    } finally {
+      model.dispose();
+    }
   } finally {
-    model.dispose();
     session.dispose();
   }
 }

package/dist/docs/guides/recipes.md

@@ -261,6 +261,49 @@ 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 { polygon, transform2 } from "@metamesh/modeling";
+import { transformContour } from "@metamesh/modeling/geometry";
+
+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 });
+
+// Point-data helpers accept the same placement. Matrices remain available for interchange.
+export const sectionMatrix = planarPlacement.toMatrix();
+export const placedContour = transformContour(outline, planarPlacement);
+```
+
+
+
+Pass the placement directly to `section.transform(planarPlacement)`. The same placement works with
+[`transformContour`](../reference/geometry/transformContour.md),
+[`transformRegionData`](../reference/geometry/transformRegionData.md), and
+[`transformPath2`](../reference/geometry/transformPath2.md).
+
+A negative scale factor reflects the placement. Paths retain their supplied point order;
+contours restore their original winding, and regions restore outer and hole winding. Choose the
+helper that matches the data's role. `andThen(next)` composes another placement in execution order;
+reuse the placement instead of building a chain inside each point iteration. `toMatrix()` is
+available for matrix interchange.
+
 ## Rotation-minimizing path sweep
 
 
@@ -599,10 +642,17 @@ export function fitLabel(layout: VectorTextLayout): FittedTextLayout {
 | `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               |
+| `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; `centerAngleDegrees` chooses its alignment datum and `direction` chooses the
+reading direction. Each shaped glyph group rotates without bending. Circular text requires one
+line and baseline vertical alignment; its default horizontal alignment is centered. Arbitrary
+path text and automatic wrapping are outside this API.
+
 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.
@@ -612,7 +662,7 @@ Studio loads declared fonts before generation. Export uses the captured visible
 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.
+replacement. Studio does not support custom font uploads.
 
 ## Solid inspection