@metamesh/modeling 0.13.0 → 0.15.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. */
@@ -11,6 +11,7 @@ export declare const MAX_VECTOR_FONT_BYTES: number;
 
 /**
  * Parses bounded font bytes using optional fontkit and WOFF2 peers; no font fetching occurs here.
+ * Argument and resource failures use GeometryError; parser and decoder exceptions propagate unchanged.
  *
  * @example Prepare a label before building geometry
  * ```ts
@@ -26,10 +27,11 @@ 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.
+ * Invalid arguments and bounded-work failures use GeometryError; unexpected dependency errors propagate.
  */
 export declare interface VectorFont {
   /** Shape horizontal lines or one circular line; bounded to 512 UTF-16 units and supports blank text. */
@@ -59,7 +61,7 @@ export declare interface VectorTextArcBaseline {
   /** Baseline radius in millimetres, greater than zero and at most 10000. */
   readonly radius: number;
   /** Alignment datum in degrees counterclockwise from +X; defaults to 90. */
-  readonly centerAngleDegrees?: number;
+  readonly centerAngle?: number;
   /** Reading direction around the circle; defaults to clockwise. */
   readonly direction?: "clockwise" | "counterclockwise";
 }

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, paths, 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
 
@@ -39,11 +40,12 @@ For lettering, [prepare exact font bytes](fonts.md) before building.
 
 The public API names values by modeling role:
 
-- A `Path3` is an ordered 3D trajectory.
-- A `Path2` is an ordered 2D trajectory.
+- `Path2` and `Path3` are immutable sampled trajectories created by `path2` and `path3`.
+  Each owns its closure, traversal order, and finite coordinates.
+- `Path2Data` and `Path3Data` are tuple collections for path interchange.
 - 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 +53,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 +73,24 @@ 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.
+
+Use `path2(points, { closed: true })` for a reusable boundary. Its `length()` includes the closing
+edge, and `closestPoint(query)` returns a fluent point, distance, edge index, and fraction within
+that edge. Queries measure the sampled boundary; they do not measure a filled interior or an
+underlying analytic curve. Chain `transform`, `reverse`, and equal-distance `resample` to create
+new paths. Closed paths omit the duplicated endpoint. Open paths may be empty; their bounds are
+`undefined`, and closest-point queries need at least two points.
+
+Pass paths directly to `polygon`, `stroke`, sweeps, and path patterns in the matching dimension.
+`polygon(path)` requires a closed planar value and establishes exterior/hole winding. A path's
+transform preserves traversal even after reflection. Individual vector inputs and authored point
+collections accept fluent vectors as well as tuples; serialized data contracts remain tuple-only.
+`toArray()` returns frozen tuples for interchange and does not encode closure. Keep the path value
+when passing closure between operations.
 
 `rectangleProfile({ size: [width, height], treatment: { kind: "round", radius }, id })` describes
 identified spans for custom geometry. Prepare a complete explicit family with `matchProfiles`
@@ -97,8 +120,8 @@ filled Section and `box({ size: [24, 16, 6] })` creates a Solid. `union` and `in
 combine same-dimensional arrays. `shape.subtract(cutters)` accepts an array of same-dimensional
 cutters. `section.offset(distance, options)` stays in the filled XY plane.
 
-`section.extrude({ height, twistDegrees, scaleTop })` adds +Z depth, with its bottom at zero unless
-`center: true` is requested. `section.revolve({ revolveDegrees })` rotates radial/Z geometry around
+`section.extrude({ height, twist, scaleTop })` adds +Z depth, with its bottom at zero unless
+`center: true` is requested. `section.revolve({ degrees })` rotates radial/Z geometry around
 +Z. `loft` pairs retained landmarks in compatible primitive Sections, including zero and fully
 rounded rectangle corners, and circle/ellipse stations transitioning to rectangles. This also works
 after invertible XY transforms with consistent handedness. It accepts explicit corresponding
@@ -112,6 +135,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
@@ -124,7 +150,7 @@ match point for point. Use physical chord and segment limits for ordinary printa
 requested tolerance cannot fit within the safety cap, the operation fails instead of silently
 returning a coarser shape.
 
-`regularPolygon({ radius, sides, rotationDegrees, sizing })` makes a filled regular polygon.
+`regularPolygon({ radius, sides, rotation, sizing })` makes a filled regular polygon.
 `sizing: "vertex"` uses the specified vertex radius; `"face"` compensates faceting so the faces
 meet the nominal radius. `circle` and `cylinder` support the same radial convention.
 
@@ -136,9 +162,97 @@ Zero rounding radius, zero chamfer/smooth distance, or an all-zero distance pair
 selected feature untreated. Other setback pairs must have two positive values; negative and
 nonfinite amounts reject. Disabled extrusion end treatments retain ordinary extrusion support,
 including holes and twist.
-`placement` maps a named or explicit shape-local anchor to a world anchor after local
+`attachment` 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 +283,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 +304,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

@@ -118,9 +118,14 @@ Geometry values allocate resources outside ordinary JavaScript objects. Studio's
 those resources for each run and cleans them up deterministically. Authored code should never
 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.
+Use `inspectSection()` or `inspectSolid()` for measurements such as bounds, area, volume, and
+`componentCount`. `components()` returns disconnected material pieces, preserving holes and
+enclosed cavities. A sealed hollow box is one component; adding a loose ball inside its cavity
+makes two. Recombining the pieces preserves the original material.
+
+Snapshot `stats.partCount` counts the named output parts declared with `part(...)`. One output
+part may contain several material components. Return one declaration or an array of them to hand
+the 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();
   }
 }
@@ -50,27 +53,37 @@ move engine initialization out of the function and reuse that engine and its mod
 
 ## Keep execution synchronous
 
-Acquire assets before generation. Imported modeling functions run inside its synchronous callback;
-computations and observations cannot cross an async boundary. Sessions cannot execute nested runs
-in one realm. Services are explicit synchronous capabilities supplied at session creation.
+Acquire assets before generation. Ordinary immutable Solid/Section recipes, vectors, paths and
+transforms can be constructed without an engine and reused across sessions. Explicit resolution
+settings stay with a recipe; omitted settings inherit the evaluating host's defaults. Computed
+readers and geometry observations require active synchronous generation and cannot cross an async
+boundary. Sessions cannot execute nested runs in one realm. Services are explicit synchronous
+capabilities supplied at session creation.
 
-A session owns optional computed caches and deferred Solid/Section recipes. It may retain evaluated
+A session owns evaluation, optional computed caches and native resources. It may retain evaluated
 computed shapes privately for later cuts or Booleans; temporary native allocations are cleaned after
-each run. Separate expensive base geometry from finishing operations to reuse it. A returned snapshot
-owns copied manufacturing buffers until `snapshot.dispose()`; `session.dispose()` releases caches
-while retained snapshots remain usable. Keep captured output for rendering/export and release it
-when its consumer is done.
+each run. Separate expensive base geometry from finishing operations to reuse it. Observed
+`components()` selections depend on evaluated topology and remain restricted to their originating
+session; ordinary recipes remain portable.
+
+A returned snapshot retains captured manufacturing buffers independently of its session. Accessing
+a part's `positions` or `indices`, including through its local `geometry` resource, returns a fresh
+owned copy on every read. Read each field once when processing its buffer. `session.dispose()`
+releases caches while captured snapshots remain usable. `snapshot.dispose()` releases its references
+and makes subsequent `parts`, `bounds` and `stats` access invalid; diagnostics, dependencies and parts
+already obtained remain usable. Disposing a snapshot does not affect another snapshot or an export
+already in progress. Release captured output when its consumer is done.
 
 ## Load WASM in a browser Worker
 
 The package includes its matching JS/WASM kernel. Node and unbundled browser modules resolve the
 installed WASM asset automatically. A browser bundler must retain or emit that relative asset;
 [`modelingWasmUrl`](../reference/engine/modelingWasmUrl.md) can supply the emitted URL through
-`createModelEngine({ locateFile })`.
+`createModelEngine({ wasmUrl: modelingWasmUrl })`.
 
 Your application owns Worker creation and message handling. Separate Workers have independent
 execution scopes. Transfer owned copies of completed buffers; transferring cache backing storage
-would detach it. Native geometry never crosses Workers or runs.
+would detach it. Native handles remain private to their engine.
 
 ## Set resource limits
 

package/dist/docs/guides/recipes.md

@@ -101,7 +101,7 @@ export default generate(({ part }) => {
   `);
   // Check the imported topology before using it in the manufacturing solid.
   const measurements = inspectSection(badge);
-  if (measurements.parts !== 1 || measurements.contours !== 2) {
+  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 }))];
@@ -160,7 +160,7 @@ One radial wall profile revolved around +Z creates the floor and tapered cup wal
 
 [`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
+`degrees: 270` for a capped partial turn that exposes the cross section. Keep the closed
 profile free of self-intersections and never repeat its first point at the end.
 
 For an open side outline, [`sampleSideProfile`](../reference/geometry/sampleSideProfile.md)
@@ -240,7 +240,7 @@ export default generate(({ part }) => {
   const arms = radialPattern(arm.translate([18, 0, 0]).rotate([0, 0, 30]), {
     count: 6,
     axis: [0, 0, 1],
-    angleDegrees: 60,
+    angle: 60,
   });
   // Both shapes are Z-centered; extra cutter height clears both hub faces.
   const bore = cylinder({ height: 16, radius: 4 });
@@ -261,6 +261,70 @@ Exact signatures: [`box`](../reference/model/box.md),
 [`cylinder`](../reference/model/cylinder.md), and
 [`radialPattern`](../reference/model/radialPattern.md).
 
+## Reuse a 2D placement
+
+Build one [`transform2`](../reference/geometry/transform2.md) chain when the same placement applies
+to a Section and its plain point data. This placement rotates around `[2, 1]`, then translates:
+
+
+
+```ts
+import { path2, pathPattern, polygon, rectangle, transform2, union } from "@metamesh/modeling";
+
+const planarPlacement = transform2()
+  .rotate(90, { pivot: [2, 1] })
+  .translate([10, 0]);
+const outline = [
+  [0, 0],
+  [4, 0],
+  [0, 2],
+] as const;
+
+// Shape construction and composition are pure; the host evaluates the finished body.
+export const placedBody = polygon({ outer: outline, holes: [] })
+  .transform(planarPlacement)
+  .extrude({ height: 8 });
+
+// Paths accept the same placement. Matrices and tuples remain available for interchange.
+export const sectionMatrix = planarPlacement.toMatrix();
+export const placedContour = path2(outline, { closed: true }).transform(planarPlacement);
+```
+
+
+
+Pass the placement directly to `section.transform(planarPlacement)` or `path.transform(planarPlacement)`.
+Fill the transformed closed path with `polygon(placedContour)` when you need material.
+[`transformRegionData`](../reference/geometry/transformRegionData.md) serves serialized filled data.
+
+A negative scale factor reflects the placement. Paths retain traversal order, including closed
+paths; filled Sections and serialized regions restore outer and hole winding. `andThen(next)`
+composes another placement in execution order;
+reuse the placement instead of building a chain inside each point iteration. `toMatrix()` is
+available for matrix interchange.
+
+Section path patterns consume `Path2` values directly. Tangent orientation aligns the Section's
+local +X direction with the path while preserving its XY plane:
+
+
+
+```ts
+const guide = path2([
+  [0, 0],
+  [12, 0],
+  [12, 12],
+]);
+const tabs = pathPattern(rectangle({ size: [4, 2] }), guide, {
+  count: 5,
+  orientation: "tangent",
+});
+export const patternedTabs = union(tabs).extrude({ height: 3 });
+```
+
+
+
+Linear Section patterns use XY directions. Radial Section patterns rotate about an optional XY
+`pivot` using the implicit +Z axis; spatial Solid patterns retain their explicit rotation axis.
+
 ## Rotation-minimizing path sweep
 
 
@@ -299,7 +363,7 @@ The asymmetric section makes its transported orientation visible as the path tur
 `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"`
+`twist` 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.
@@ -338,7 +402,7 @@ and placement. `pin.attach("bottom", anchor(base, "top"))` mates opposed directi
 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
+Use `shape.withAnchors({ mount: anchor3(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.
@@ -349,8 +413,8 @@ move them. Tube and torus axial datums may lie over an opening; a cone has no ca
 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
+Primitive `attachment` uses the same source/target anchor, `alignment`, `gap` and `spin`
+vocabulary as `attach`, including a named `source`. It applies after local shape construction. Filled Section attachment must
 preserve the XY plane.
 
 The `gap` here separates the two pieces along the target normal; it is a placement distance, not
@@ -451,7 +515,7 @@ The two rounded rectangles retain matching corner identities while their size an
 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
+`frame: anchorFrame3(anchor3(position, direction, up))` instead; the direction chooses its
 normal and a nonparallel `up` vector chooses its roll.
 
 The primitive retains its corner identities, so `loft` pairs corresponding landmarks without
@@ -599,10 +663,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; `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. 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 +683,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
 
@@ -626,7 +697,7 @@ export default generate(({ part }) => {
   const result = box({ size: [40, 30, 5] });
   const measurements = inspectSolid(result);
 
-  if (measurements.min[2] < -2.5 || measurements.parts !== 1) {
+  if (measurements.min[2] < -2.5 || measurements.componentCount !== 1) {
     throw new Error("Unexpected placement or disconnected result.");
   }