@metamesh/modeling 0.14.0 → 0.15.0

package/dist/api/text.d.ts

@@ -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
@@ -30,6 +31,7 @@ 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

@@ -26,7 +26,7 @@ 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       |
 
-Construct immutable shapes, vectors, and transforms in ordinary TypeScript and reuse them in
+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.
 
@@ -40,8 +40,9 @@ 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.
 - `PolygonData` contains one outer contour and its holes. `RegionData` is the plain serialized
   representation of filled 2D geometry, including disconnected polygons.
@@ -77,6 +78,20 @@ Every form returns the same `Section` type as `circle` or `rectangle`; subsequen
 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`
 when loft stations or a sweep need authored holes, seams, or landmarks beyond ordinary primitives.
@@ -105,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
@@ -135,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.
 
@@ -147,7 +162,7 @@ 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

package/dist/docs/guides/fundamentals.md

@@ -118,11 +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, 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.
+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/hosting.md

@@ -53,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.
-
-A session owns optional computed caches and deferred Solid/Section recipes. It may retain evaluated
+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 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 });
@@ -269,8 +269,7 @@ to a Section and its plain point data. This placement rotates around `[2, 1]`, t
 
 
 ```ts
-import { polygon, transform2 } from "@metamesh/modeling";
-import { transformContour } from "@metamesh/modeling/geometry";
+import { path2, pathPattern, polygon, rectangle, transform2, union } from "@metamesh/modeling";
 
 const planarPlacement = transform2()
   .rotate(90, { pivot: [2, 1] })
@@ -286,24 +285,46 @@ export const placedBody = polygon({ outer: outline, holes: [] })
   .transform(planarPlacement)
   .extrude({ height: 8 });
 
-// Point-data helpers accept the same placement. Matrices remain available for interchange.
+// Paths accept the same placement. Matrices and tuples remain available for interchange.
 export const sectionMatrix = planarPlacement.toMatrix();
-export const placedContour = transformContour(outline, planarPlacement);
+export const placedContour = path2(outline, { closed: true }).transform(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).
+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 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;
+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
 
 
@@ -342,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.
@@ -381,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.
@@ -392,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
@@ -494,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
@@ -648,7 +669,7 @@ export function fitLabel(layout: VectorTextLayout): FittedTextLayout {
 
 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
+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.
@@ -676,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.");
   }