@metamesh/modeling 0.15.0 → 0.17.0

package/dist/geometry/index.js

@@ -1,5 +1,7 @@
 /** Pure geometry foundations without host initialization. @packageDocumentation */
-export { boundsFromSize, boundsSize, boundsCenter, containsBounds, fitBounds, layoutRow, } from "./bounds.js";
+export { bounds2, bounds3, } from "./bounds-value.js";
+export { boundsSize, boundsCenter, fitBounds, layoutRow, } from "./bounds.js";
+export { resolveCircularSampling, } from "./circular-sampling.js";
 export { fitTextLayout } from "./text-fitting.js";
 export { gridPatternTransforms, linearPatternTransforms, radialPatternTransforms, pathPatternTransforms, } from "./patterns.js";
 export { validateSolidMesh } from "./mesh/mesh-solid.js";
@@ -12,7 +14,7 @@ export { defaultGeometrySamplingLimits, resolveGeometrySamplingLimits, } from ".
 export { GeometryError, isGeometryError, } from "./errors.js";
 export { resolveExtrusionDivisions, } from "./extrusion.js";
 export { extrudeMesh, loftMesh, triangulateContour, } from "./loft/loft.js";
-export { transform2, transform3, } from "./transform-chain.js";
+export { transform2, transform3, } from "./transform-value.js";
 export { vector2, vector3, } from "./math/vector-value.js";
 export { add2, subtract2, scale2, dot2, cross2, length2, distance2, normalize2, lerp2, rotate2, } from "./math/vector2.js";
 export { add3, cross3, dot3, length3, distance3, lerp3, normalize3, projectOntoPlane3, scale3, subtract3, } from "./math/vector3.js";
@@ -49,3 +51,4 @@ export { IDENTITY_TRANSFORM3, applyTransformDirection3, applyTransformPoint3, co
 export { sampleTextContours } from "./text-contours.js";
 export { sampleCurve2, sampleCurve3 } from "./curves/sampling.js";
 export { resamplePolyline2, resamplePolyline3, } from "./paths/resampling.js";
+export { resolveKnuckleHinge, } from "./mechanical/knuckle-hinge.js";

package/dist/geometry/math/immutable-value.js

@@ -1,5 +1,5 @@
 // A versioned realm protocol lets separately bundled authoring values cross the host boundary.
-const immutableMath = Symbol.for("@metamesh/modeling/immutable-math/7");
+const immutableMath = Symbol.for("@metamesh/modeling/immutable-math/9");
 /**
  * Brands and freezes only this constructor's prototype. Pure-annotated callers let bundlers
  * discard unused classes without dropping initialization for classes that remain reachable.

package/dist/geometry/math/vector-value.js

@@ -34,7 +34,7 @@ const tupleData = (input, dimensions) => {
         return invalidVector(dimensions);
     let values = input;
     if (!Array.isArray(input)) {
-        const method = Reflect.get(input, "toArray");
+        const method = Reflect.get(input, "toData");
         if (typeof method !== "function")
             return invalidVector(dimensions);
         values = Reflect.apply(method, input, []);
@@ -88,7 +88,7 @@ const PlanarVector = /* @__PURE__ */ immutableMathClass(class PlanarVector {
     distance(other) {
         return finite(distance2(this.values, operand2(other, "vector2.distance")), "vector2.distance");
     }
-    toArray() {
+    toData() {
         return this.values;
     }
 });
@@ -136,15 +136,19 @@ const SpatialVector = /* @__PURE__ */ immutableMathClass(class SpatialVector {
     distance(other) {
         return finite(distance3(this.values, operand3(other, "vector3.distance")), "vector3.distance");
     }
-    toArray() {
+    toData() {
         return this.values;
     }
 });
 /**
  * Creates immutable XY arithmetic from a finite tuple or vector, snapshotting the coordinates.
+ *
  * Values and results are finite. Invalid dimensions throw `INVALID_ARGUMENT`; nonfinite coordinates
  * and overflow throw `NON_FINITE_VALUE` GeometryError.
  * Use transform2().applyDirection(value) for rotations and nonuniform scaling.
+ *
+ * Use `toData()` for frozen tuple interchange, or
+ * [normalize2](/docs/reference/geometry/normalize2) for tuple-based normalization in numerical loops.
  */
 export function vector2(input) {
     const values = operand2(input, "vector2");
@@ -152,10 +156,14 @@ export function vector2(input) {
 }
 /**
  * Creates immutable XYZ arithmetic from a finite tuple or vector, snapshotting the coordinates.
+ *
  * Values and results are finite. Invalid dimensions throw `INVALID_ARGUMENT`; nonfinite coordinates
  * and overflow throw `NON_FINITE_VALUE` GeometryError.
  * Use transform3().applyDirection(value) for rotations and nonuniform scaling.
  *
+ * Use `toData()` for frozen tuple interchange, or
+ * [normalize3](/docs/reference/geometry/normalize3) for tuple-based normalization in numerical loops.
+ *
  * @example
  * ```ts
  * const direction = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);

package/dist/geometry/math/vector2.js

@@ -21,6 +21,7 @@ export const length2 = (vector) => Math.hypot(vector[0], vector[1]);
 export const distance2 = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1]);
 /**
  * Returns a unit vector; `epsilon` is a finite, non-negative length threshold (default `1e-12`).
+ *
  * Rejects invalid thresholds, nonfinite lengths, and lengths at or below the threshold with
  * `INVALID_TOLERANCE`, `NON_FINITE_VALUE`, and `DEGENERATE_GEOMETRY` respectively.
  */

package/dist/geometry/math/vector3.js

@@ -61,6 +61,7 @@ export const length3 = (vector) => Math.hypot(vector[0], vector[1], vector[2]);
 export const distance3 = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
 /**
  * Returns a unit vector; `epsilon` is a finite, non-negative length threshold (default `1e-12`).
+ *
  * Rejects invalid thresholds, nonfinite lengths, and lengths at or below the threshold with
  * `INVALID_TOLERANCE`, `NON_FINITE_VALUE`, and `DEGENERATE_GEOMETRY` respectively.
  */

package/dist/geometry/mechanical/index.js

@@ -11,3 +11,4 @@ export { preflightHelicalThreadSolidMesh } from "./thread-mesh-plan.js";
 export { sampleConventionalThreadHelices as sampleThreadHelices } from "./thread-helices.js";
 export { compensateThreadDiameters, PRINTABLE_THREAD_FIT_POLICIES, resolvePrintableThreadFitPolicy, resolveThreadCircularSegments, } from "./threads.js";
 export { getMetricClearanceHoleDiameter, getMetricFastenerStandard, METRIC_FASTENER_STANDARDS, } from "./standards.js";
+export { resolveKnuckleHinge, } from "./knuckle-hinge.js";

package/dist/geometry/mechanical/knuckle-hinge.js

@@ -0,0 +1,110 @@
+import { GeometryError } from "../errors.js";
+import { assertPositivePrimitive, assertPrimitiveOptions } from "../primitive-resolvers.js";
+import { resolveAlignedCircularSegments } from "../resolution.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+/** @internal Shared fixed frame; ordinary transforms place the joint in a model. */
+export const knuckleHingeAxis = Object.freeze({
+    position: Object.freeze([0, 0, 0]),
+    direction: Object.freeze([1, 0, 0]),
+    up: Object.freeze([0, 0, 1]),
+});
+const invalid = (message) => {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation: "resolveKnuckleHinge" });
+};
+/**
+ * Resolves equal alternating knuckles along +X, centered at the origin, in millimetres.
+ *
+ * Both faces of each running pair use a common polygon count; face-sized bores contain the
+ * shaft's complete rotational envelope. Adaptive sampling satisfies both face and vertex error
+ * bounds; an insufficient ceiling rejects instead of reducing quality. Exact counts are intentional
+ * facets. Zero allowances describe ideal contact, not a printable running fit.
+ *
+ * Rejects nonfinite or nonpositive dimensions, invalid mode/count combinations, exhausted axial
+ * length, missing/excessive lift-off engagement, and nonpositive conservative faceted barrel walls.
+ * Manufacturing minima, strength, mounting, retention, handedness, and motion remain caller policy.
+ */
+export function resolveKnuckleHinge(spec, options = {}) {
+    assertPrimitiveOptions(spec, "resolveKnuckleHinge");
+    assertPrimitiveOptions(options, "resolveKnuckleHinge");
+    for (const key of ["length", "barrelDiameter", "pinDiameter"])
+        assertPositivePrimitive(spec[key], key, "resolveKnuckleHinge");
+    for (const key of ["radialClearance", "axialGap"])
+        if (!Number.isFinite(spec[key]) || spec[key] < 0)
+            invalid(`${key} must be finite and nonnegative.`);
+    if (!Number.isSafeInteger(spec.knuckleCount) || spec.knuckleCount < 2)
+        invalid("knuckleCount must be a safe integer of at least two.");
+    if (!["print-in-place", "inserted-pin", "lift-off"].includes(spec.mode))
+        invalid("Unknown hinge mode.");
+    if (spec.mode === "print-in-place" && spec.knuckleCount % 2 !== 1)
+        invalid("Print-in-place needs an odd count.");
+    if (spec.mode === "lift-off" && spec.knuckleCount !== 2)
+        invalid("Lift-off needs two knuckles.");
+    if (spec.mode !== "lift-off" && spec.pinEngagement !== undefined)
+        invalid("pinEngagement requires lift-off mode.");
+    const limits = resolveGeometrySamplingLimits(options.limits);
+    assertSamplingCount(spec.knuckleCount, "resolveKnuckleHinge", limits.maxPathPoints);
+    const knuckleLength = (spec.length - (spec.knuckleCount - 1) * spec.axialGap) / spec.knuckleCount;
+    if (!Number.isFinite(knuckleLength) || knuckleLength <= 0)
+        invalid("Axial gaps consume the knuckles.");
+    if (spec.mode === "lift-off" &&
+        (!Number.isFinite(spec.pinEngagement) ||
+            spec.pinEngagement <= 0 ||
+            spec.pinEngagement > knuckleLength))
+        invalid("pinEngagement must be positive and fit the socket.");
+    const barrelRadius = spec.barrelDiameter / 2;
+    const pinRadius = spec.pinDiameter / 2;
+    const boreRadius = pinRadius + spec.radialClearance;
+    if (!(pinRadius > 0) || !(boreRadius < barrelRadius))
+        invalid("Pin and bore must fit inside the barrel.");
+    const segments = resolveAlignedCircularSegments(barrelRadius, {
+        ...options,
+        sizing: "face",
+        alignTo: [4],
+        minSegments: 4,
+    });
+    const cosine = Math.cos(Math.PI / segments);
+    const boreOuterRadius = boreRadius / cosine;
+    const minimumBarrelWall = barrelRadius * cosine - boreOuterRadius;
+    if (minimumBarrelWall <= 0)
+        invalid("Facets consume the wall; increase segments or barrel diameter.");
+    const common = {
+        length: spec.length,
+        knuckleCount: spec.knuckleCount,
+        barrelDiameter: spec.barrelDiameter,
+        pinDiameter: spec.pinDiameter,
+        radialClearance: spec.radialClearance,
+        axialGap: spec.axialGap,
+    };
+    const copied = Object.freeze(spec.mode === "lift-off"
+        ? {
+            ...common,
+            mode: spec.mode,
+            knuckleCount: spec.knuckleCount,
+            pinEngagement: spec.pinEngagement,
+        }
+        : { ...common, mode: spec.mode });
+    return Object.freeze({
+        spec: copied,
+        barrelRadius,
+        pinRadius,
+        boreRadius,
+        boreOuterRadius,
+        minimumBarrelWall,
+        knuckleLength,
+        segments,
+        knuckles: Object.freeze(Array.from({ length: spec.knuckleCount }, (_, index) => Object.freeze({
+            side: index % 2 === 0 ? "a" : "b",
+            start: -spec.length / 2 + index * (knuckleLength + spec.axialGap),
+            length: knuckleLength,
+        }))),
+        pin: spec.mode === "inserted-pin"
+            ? null
+            : Object.freeze({
+                start: -spec.length / 2,
+                length: spec.mode === "lift-off"
+                    ? knuckleLength + spec.axialGap + spec.pinEngagement
+                    : spec.length,
+            }),
+        axis: knuckleHingeAxis,
+    });
+}

package/dist/geometry/mechanical/thread-mesh-plan.js

@@ -348,8 +348,13 @@ export const resolveHelicalThreadSolidMeshPreflight = (options, operation) => {
     });
 };
 /**
- * Validates a direct thread solid and returns its conservative allocation estimate without
- * constructing vertex or index buffers.
+ * Checks thread dimensions, profile, end treatments, sampling, and conservative estimates against output limits.
+ *
+ * This pure operation needs no engine and constructs planning data without vertex or index buffers.
+ * `circularSegments` is the selected count; row and triangle counts are conservative estimates.
+ * Successful preflight leaves generated coordinate and topology checks to mesh construction.
+ *
+ * @see {@link helicalThreadSolidMesh}
  */
 export function preflightHelicalThreadSolidMesh(options) {
     return resolveHelicalThreadSolidMeshPreflight(options, "preflightHelicalThreadSolidMesh")

package/dist/geometry/mechanical/thread-solids.js

@@ -96,11 +96,30 @@ export const resolveCompensatedThreadSolidMesh = (options, role) => {
     });
 };
 const preflightCompensatedThreadSolid = (options, role) => preflightHelicalThreadSolidMesh(resolveCompensatedThreadSolidMesh(options, role).meshOptions);
-/** Preflights the exact compensated direct mesh used by the threaded rod constructor. */
+/**
+ * Resolves compensated rod dimensions and checks conservative mesh estimates against output limits.
+ *
+ * This pure operation uses explicit resolution and limits or package defaults, without an active
+ * host execution. It creates planning data without mesh buffers or native objects; returned row
+ * and triangle counts are estimates. Mesh validity and native construction are checked later.
+ *
+ * @see {@link preflightHelicalThreadSolidMesh}
+ * @see {@link helicalThreadSolidMesh}
+ */
 export function preflightThreadedRodSolid(options) {
     return preflightCompensatedThreadSolid(options, "male");
 }
-/** Preflights the exact extended mesh used by the internal thread cutter constructor. */
+/**
+ * Resolves compensated cutter dimensions and checks extended mesh estimates against output limits.
+ *
+ * This pure operation uses explicit resolution and limits or package defaults, without an active
+ * host execution. It includes the cutter's one-pitch extension beyond each requested face and
+ * creates planning data without mesh buffers or native objects. Row and triangle counts are
+ * estimates; mesh validity and native construction are checked later.
+ *
+ * @see {@link preflightHelicalThreadSolidMesh}
+ * @see {@link helicalThreadSolidMesh}
+ */
 export function preflightInternalThreadCutterSolid(options) {
     return preflightCompensatedThreadSolid(options, "female");
 }
@@ -222,8 +241,14 @@ export const resolveThreadedNutSolid = (options, operation) => {
     });
 };
 /**
- * Resolves a nut's exact body/cutter chamfer and preflights its extended thread mesh without
- * allocating Manifold WASM objects.
+ * Checks nut dimensions, chamfers, end-face wall, and the extended compensated cutter's allocation plan.
+ *
+ * This pure operation uses explicit resolution and limits or package defaults, without an active
+ * host execution. It resolves body/cutter dimensions without mesh buffers or native objects.
+ * `thread` contains conservative cutter estimates, excluding the body and Boolean result.
+ * Successful preflight leaves mesh validity, native construction, and manufacturing fit to later checks.
+ *
+ * @see {@link preflightHelicalThreadSolidMesh}
  */
 export function preflightThreadedNutSolid(options) {
     return resolveThreadedNutSolid(options, "preflightThreadedNutSolid").preflight;

package/dist/geometry/mesh/mesh-centroid.js

@@ -2,6 +2,7 @@ import { GeometryError } from "../errors.js";
 import { analyzeTriangleMesh } from "./mesh.js";
 /**
  * Computes the uniform-density volume centroid of an oriented closed solid, including cavity shells.
+ *
  * Coordinates are millimetres. Indexed closure and positive aggregate volume are required; callers
  * may use validateSolidMesh first when geometric intersections and shell orientation are untrusted.
  * Fresh mutable input is inspected on every call, and buffers are never changed.

package/dist/geometry/mesh/mesh-solid.js

@@ -7,6 +7,7 @@ const MAXIMUM_TRIANGLES = 200_000;
 const MAXIMUM_TESTS = 2_000_000;
 /**
  * Checks closed indexed topology, triangle intersections, and alternating nested shell orientation.
+ *
  * Outward exterior shells and inward cavity shells are accepted. Separate shells must not touch,
  * intersect, or overlap as material. Indexed neighbours may share their own vertex or edge.
  *

package/dist/geometry/paths/frames.js

@@ -50,6 +50,7 @@ const transportNormal = (normal, previousTangent, tangent) => {
 };
 /**
  * Builds rotation-minimizing frames by parallel-transporting the previous normal.
+ *
  * This avoids the sudden profile flips produced by picking a fresh up-vector per ring.
  * Paths exceeding maxPathPoints (default 100000) reject before frame allocation or guide evaluation.
  * Requires open path values; raw tuples are interpreted as an open path. Invalid paths throw GeometryError.

package/dist/geometry/paths/helix.js

@@ -2,6 +2,7 @@ import { GeometryError } from "../errors.js";
 import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
 /**
  * Creates `segments + 1` points including exact helix endpoints from finite positive dimensions.
+ *
  * Integrated weights must remain finite. The maxPathPoints ceiling defaults to 100000; excessive
  * exact counts reject before evaluating axial weights or allocating sample arrays.
  * Invalid inputs use GeometryError; exceptions thrown by axialWeight propagate unchanged.

package/dist/geometry/paths/path-value.js

@@ -1,10 +1,11 @@
+import { bounds2, bounds3 } from "../bounds-value.js";
 import { GeometryError } from "../errors.js";
 import { immutableMathClass } from "../math/immutable-value.js";
 import { vector2, vector2Data, vector3, vector3Data, } from "../math/vector-value.js";
 import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
 import { transformPath2, transformPath3 } from "../transform-geometry.js";
 import { closestPointOnValidatedPath } from "./closest-point.js";
-import { resamplePath2Data, resamplePath3Data } from "./resampling.js";
+import { resamplePath2Points, resamplePath3Points } from "./resampling.js";
 const fail = (message, code = "INVALID_ARGUMENT") => {
     throw new GeometryError(code, message, { operation: "path" });
 };
@@ -19,9 +20,13 @@ function freezePoints(points) {
         Object.freeze(point);
     return Object.freeze(points);
 }
-function frozenArray(owner) {
+function frozenData(owner) {
     const state = stateOf(owner);
-    return (state.array ??= freezePoints(state.points.map((point) => [...point])));
+    return (state.data ??= Object.freeze({
+        dimension: owner.dimension,
+        closed: owner.closed,
+        points: freezePoints(state.points.map((point) => [...point])),
+    }));
 }
 function closedOption(closed) {
     if (closed !== undefined && typeof closed !== "boolean")
@@ -60,23 +65,25 @@ function validateClosure(points, closed) {
 function pathSource(input, closed, dimension) {
     if (Array.isArray(input))
         return { points: input, closed: closedOption(closed) };
-    if (typeof input !== "object" ||
-        input === null ||
-        !("toArray" in input) ||
-        typeof input.toArray !== "function" ||
-        !("closed" in input) ||
-        !("dimension" in input) ||
-        input.dimension !== dimension)
-        return fail("Expected a path or an array of coordinate tuples or vectors.");
-    if (typeof input.closed !== "boolean")
-        fail("Path closure metadata must be a boolean.");
-    const sourceClosed = input.closed;
+    if (typeof input !== "object" || input === null)
+        return fail("Expected a path value, path data, or an array of vectors.");
+    const own = pathStates.get(input);
+    const method = Reflect.get(input, "toData");
+    const data = own !== undefined
+        ? input
+        : typeof method === "function"
+            ? Reflect.apply(method, input, [])
+            : input;
+    if (typeof data !== "object" || data === null)
+        return fail("Expected complete path data.");
+    const sourceDimension = Reflect.get(data, "dimension");
+    const sourceClosed = Reflect.get(data, "closed");
+    const points = own?.points ?? Reflect.get(data, "points");
+    if (sourceDimension !== dimension || typeof sourceClosed !== "boolean" || !Array.isArray(points))
+        return fail("Path data requires matching dimension, boolean closure, and an array of vectors.");
     if (closed !== undefined && closedOption(closed) !== sourceClosed)
         fail("The closed option conflicts with the path's closure.");
-    const points = pathStates.get(input)?.points ?? input.toArray();
-    if (!Array.isArray(points))
-        fail("Path points must be an array of coordinate tuples or vectors.");
-    return { points, closed: sourceClosed };
+    return { points: points, closed: sourceClosed };
 }
 function measuredLength(owner) {
     const state = stateOf(owner);
@@ -106,7 +113,9 @@ function measuredBounds(points) {
             max[axis] = Math.max(max[axis], point[axis]);
         }
     }
-    return Object.freeze({ min: Object.freeze(min), max: Object.freeze(max) });
+    return min.length === 2
+        ? bounds2({ min: [min[0], min[1]], max: [max[0], max[1]] })
+        : bounds3({ min: [min[0], min[1], min[2]], max: [max[0], max[1], max[2]] });
 }
 function samplingOptions(options, closed) {
     if (typeof options !== "object" || options === null || Array.isArray(options))
@@ -123,8 +132,8 @@ const PlanarPath = /* @__PURE__ */ immutableMathClass(class PlanarPath {
         pathStates.set(this, { points });
         Object.freeze(this);
     }
-    toArray() {
-        return frozenArray(this);
+    toData() {
+        return frozenData(this);
     }
     length() {
         return measuredLength(this);
@@ -144,7 +153,7 @@ const PlanarPath = /* @__PURE__ */ immutableMathClass(class PlanarPath {
     }
     resample(options = {}) {
         const policy = samplingOptions(options, this.closed);
-        return new PlanarPath(resamplePath2Data(points2(this), policy), this.closed);
+        return new PlanarPath(resamplePath2Points(points2(this), policy), this.closed);
     }
 });
 const SpatialPath = /* @__PURE__ */ immutableMathClass(class SpatialPath {
@@ -155,8 +164,8 @@ const SpatialPath = /* @__PURE__ */ immutableMathClass(class SpatialPath {
         pathStates.set(this, { points });
         Object.freeze(this);
     }
-    toArray() {
-        return frozenArray(this);
+    toData() {
+        return frozenData(this);
     }
     length() {
         return measuredLength(this);
@@ -176,16 +185,19 @@ const SpatialPath = /* @__PURE__ */ immutableMathClass(class SpatialPath {
     }
     resample(options = {}) {
         const policy = samplingOptions(options, this.closed);
-        return new SpatialPath(resamplePath3Data(points3(this), policy), this.closed);
+        return new SpatialPath(resamplePath3Points(points3(this), policy), this.closed);
     }
 });
 /**
  * Snapshots finite XY coordinates as an immutable sampled path, independent of engine initialization.
+ *
  * Open paths may be empty or have one point; closed paths need three vertices and omit a duplicated
  * seam. Repeated adjacent vertices are retained. No winding normalization or filling is performed.
  * Malformed dimensions or topology throw INVALID_ARGUMENT; nonfinite coordinates or measurement
  * overflow throw NON_FINITE_VALUE; exhausted allocation ceilings throw COMPLEXITY_LIMIT GeometryError.
  * A path input retains its closure. Limits bound construction only; resampling takes its own limits.
+ *
+ * Use `toData()` for a frozen record that restores coordinates, closure, and dimension together.
  */
 export function path2(input, options = {}) {
     validateOptions(options);
@@ -198,6 +210,10 @@ export function path2(input, options = {}) {
 /**
  * Snapshots finite XYZ coordinates as an immutable sampled path with the same closure, seam,
  * allocation and error rules as path2. Analytic curves must be sampled explicitly first.
+ *
+ * Use `toData()` for a frozen record that restores coordinates, closure, and dimension together.
+ *
+ * @see {@link path2} for shared construction rules.
  */
 export function path3(input, options = {}) {
     validateOptions(options);
@@ -233,7 +249,7 @@ export function path2InputData(input, closed, limits) {
     assertSamplingCount(source.points.length, "path", policy.maxPathPoints);
     return {
         points: input instanceof PlanarPath
-            ? input.toArray()
+            ? input.toData().points
             : freezePoints(snapshot(source.points, 2, policy)),
         closed: source.closed,
     };
@@ -245,7 +261,7 @@ export function path3InputData(input, closed, limits) {
     assertSamplingCount(source.points.length, "path", policy.maxPathPoints);
     return {
         points: input instanceof SpatialPath
-            ? input.toArray()
+            ? input.toData().points
             : freezePoints(snapshot(source.points, 3, policy)),
         closed: source.closed,
     };

package/dist/geometry/paths/resampling.js

@@ -126,7 +126,7 @@ export function resamplePolyline2(path, options = {}) {
     return resamplePolyline(path, 2, options, createPlanarSampleWriter);
 }
 /** Internal points-only writer; Path2 owns these mutable coordinates and freezes public interchange. */
-export function resamplePath2Data(path, options) {
+export function resamplePath2Points(path, options) {
     const points = [];
     return resamplePolyline(path, 2, options, () => ({
         append: (point) => {
@@ -136,7 +136,7 @@ export function resamplePath2Data(path, options) {
     }), false);
 }
 /** Internal points-only writer; avoids calculating and allocating tangents discarded by Path3. */
-export function resamplePath3Data(path, options) {
+export function resamplePath3Points(path, options) {
     const points = [];
     return resamplePolyline(path, 3, options, () => ({
         append: (point) => {

package/dist/geometry/patterns/placements.js

@@ -28,9 +28,9 @@ const finite = (value, operation) => {
 const coordinates = (input, operation) => {
     const value = typeof input === "object" &&
         input !== null &&
-        "toArray" in input &&
-        typeof input.toArray === "function"
-        ? input.toArray()
+        "toData" in input &&
+        typeof input.toData === "function"
+        ? input.toData()
         : input;
     if (!Array.isArray(value) || (value.length !== 2 && value.length !== 3))
         fail(operation, "Pattern vectors require exact XY or XYZ coordinates.");

package/dist/geometry/patterns.js

@@ -16,7 +16,9 @@ export function gridPatternTransforms(options) {
     return transforms(gridPatternPlan(options));
 }
 /**
- * Equal physical arc-length placements along a sampled XYZ path. Tangent orientation maps +Z
+ * Equal physical arc-length placements along a sampled XYZ path.
+ *
+ * Tangent orientation maps +Z
  * onto the local path tangent; fixed orientation only translates. Closed paths omit a repeated seam.
  * Explicit sampling ceilings bound both input points and output placements.
  */

package/dist/geometry/profiles/contour.js

@@ -9,6 +9,7 @@ function invalid(message) {
 }
 /**
  * Samples 2–32 connected line/cubic segments into a simple, nonzero-area, immutable CCW XY loop.
+ *
  * Physical scaling precedes adaptive curve sampling; the final end must repeat start exactly.
  * Shared anchors and the closing seam are emitted once. Winding normalization may change the
  * starting vertex. The sampled loop is checked for self-intersection and degeneracy by

package/dist/geometry/profiles/matched.js

@@ -64,6 +64,7 @@ const contours = (component) => [
 ];
 /**
  * Explicitly matches identified component/contour/span topology across a family.
+ *
  * Every paired span uses the maximum physical subdivision count requested by any member.
  * Cubics share a checked uniform parameter grid, including grids selected by exact paired requests.
  * Input order and winding are preserved. Collapsed spans retain repeated logical slots, which

package/dist/geometry/profiles/profiles.js

@@ -1,6 +1,5 @@
+import { resolveCircularSampling } from "../circular-sampling.js";
 import { GeometryError } from "../errors.js";
-import { resolveCircularPrimitiveSegments } from "../primitive-resolution.js";
-import { assertPrimitiveOptions } from "../primitive-resolvers.js";
 import { requireFiniteProfileValues, requireProfileVertexCount } from "./validation.js";
 export { rectangleContour } from "./rectangle.js";
 /**
@@ -13,30 +12,11 @@ export { rectangleContour } from "./rectangle.js";
  */
 export const circleContour = (options) => {
     const operation = "circleContour";
-    assertPrimitiveOptions(options, operation);
-    if ((options.radius === undefined) === (options.diameter === undefined)) {
-        throw new GeometryError("INVALID_ARGUMENT", "Specify exactly one radius or diameter.", {
-            operation,
-        });
-    }
-    const radius = options.radius ?? options.diameter / 2;
-    requireFiniteProfileValues([radius], operation);
-    if (!(radius > 0)) {
-        throw new GeometryError("INVALID_ARGUMENT", "Circle radius must be positive.", { operation });
-    }
-    const segments = resolveCircularPrimitiveSegments(radius, options, operation);
+    const { segments, vertexRadius } = resolveCircularSampling(options);
     requireProfileVertexCount(segments, 3, operation, options.limits);
-    const sizing = options.sizing ?? "vertex";
-    if (sizing !== "vertex" && sizing !== "face") {
-        throw new GeometryError("INVALID_ARGUMENT", "Circle sizing must be vertex or face.", {
-            operation,
-        });
-    }
-    const sampledRadius = sizing === "face" ? radius / Math.cos(Math.PI / segments) : radius;
-    requireFiniteProfileValues([sampledRadius], operation);
     return Object.freeze(Array.from({ length: segments }, (_, index) => {
         const angle = (Math.PI * 2 * index) / segments;
-        return Object.freeze([sampledRadius * Math.cos(angle), sampledRadius * Math.sin(angle)]);
+        return Object.freeze([vertexRadius * Math.cos(angle), vertexRadius * Math.sin(angle)]);
     }));
 };
 /**

package/dist/geometry/profiles/rectangle.js

@@ -79,7 +79,11 @@ export function rectangleCornerSegments(corner, limits) {
     }) / 4);
 }
 /**
- * Creates an immutable CCW rectangle loop. Round radius zero is square; tangent saturated endpoints occur once.
+ * Creates an immutable sampled CCW rectangle boundary. Round radius zero is square; tangent saturated endpoints occur once.
+ *
+ * Use [rectangle](/docs/reference/model/rectangle) for a filled Section.
+ *
+ * @see {@link rectangleProfile} for identified edge/corner spans used by matchProfiles.
  *
  * @example Rounded rectangle outline
  * ```ts
@@ -148,6 +152,11 @@ export function rectangleContour(options) {
 /**
  * Creates an identified rectangle whose edge/corner spans survive zero and saturated round radii. Outer winding is CCW.
  *
+ * Use [rectangle](/docs/reference/model/rectangle) for a filled Section.
+ *
+ * @see {@link matchProfiles} to sample a family with shared landmark correspondence.
+ * @see {@link rectangleContour} for sampled boundary coordinates.
+ *
  * @example Retain rectangle landmarks
  * ```ts
  * rectangleProfile({ size: [30, 20], treatment: { kind: "round", radius: 3 } });

package/dist/geometry/profiles/side-profile.js

@@ -23,6 +23,7 @@ function distanceToChord(point, start, end) {
 }
 /**
  * Samples 1–31 line/cubic segments into a deeply immutable open [radius,height] polyline.
+ *
  * Anchors must progress strictly upward; nonnegative-radius cubic controls must have ordered
  * heights between their endpoints. Cubics use de Casteljau subdivision with a conservative
  * control-hull chord-error bound. Lines also obey the optional physical edge-length ceiling.
@@ -138,6 +139,7 @@ export function sampleSideProfile(curve, options = {}) {
 }
 /**
  * Closes an open, strictly upward [radius, height] side outline to the radius-zero axis.
+ *
  * Adds horizontal bottom/top edges at the endpoint heights, retaining axis endpoints once.
  * Returns a counterclockwise filled-boundary contour without a repeated seam vertex.
  * Radii must be nonnegative; the result must enclose nonzero area without touching itself.