@metamesh/modeling 0.19.0 → 0.20.0

package/dist/geometry/loft/{loft-geometry.js → geometry.js}

@@ -1,10 +1,9 @@
 import { GeometryError } from "../errors.js";
-import { normalizeContour, normalizeRegion, signedContourArea } from "../regions.js";
-import { resolveGeometryResolution } from "../resolution.js";
-import { assertSamplingCount } from "../sampling-limits.js";
-import { frameTransform3 } from "../transform3.js";
-import { alignLoftRows, assertLoftGrid, loftSubdivisions, sliceLoftRows, subdivideLoftRow, } from "./loft-correspondence.js";
-import { loftFrame, resolveLoftControls } from "./loft-options.js";
+import { normalizeContour, normalizeRegion, signedContourArea } from "../regions/operations.js";
+import { assertSamplingCount } from "../sampling/limits.js";
+import { resolveGeometryResolution } from "../sampling/resolution.js";
+import { alignLoftRows, assertLoftGrid, loftSubdivisions, sliceLoftRows, subdivideLoftRow, } from "./correspondence.js";
+import { loftTransform, resolveLoftControls } from "./options.js";
 const fail = (message) => {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: "loft" });
 };
@@ -76,10 +75,9 @@ export function prepareLoftGeometry(input, options, limits, authoritative, recip
     assertSamplingCount(input.reduce((sum, station) => sum + loftProfilePointCount(station.profile), 0), "loft", 1_000_000);
     if (authoritative && controls.methods.some((method) => method !== "direct"))
         fail("Identified loft landmarks are authoritative and cannot be remapped by geometric correspondence methods.");
-    const finalRows = input.length + controls.slices.reduce((sum, count) => sum + count, 0);
+    const finalRows = 1 + controls.slices.reduce((sum, count) => sum + count, 0);
     assertSamplingCount(finalRows, "loft", limits.maxPathPoints);
-    const frames = input.map((station) => loftFrame(station));
-    const transforms = frames.map((frame) => frameTransform3(frame));
+    const transforms = input.map((station) => loftTransform(station));
     const first = input[0].profile;
     if (!Array.isArray(first.components) ||
         first.components.length === 0 ||
@@ -153,21 +151,21 @@ export function prepareLoftGeometry(input, options, limits, authoritative, recip
         allSpans.push(spans);
     });
     const templates = first.components;
-    const stationFrames = [frames[0]];
+    const stationTransforms = [transforms[0]];
     for (let gap = 0; gap < controls.slices.length; gap++) {
-        // Intermediate frames are placeholders only. Their vertices use the explicit world grids.
-        for (let index = 0; index < controls.slices[gap]; index++)
-            stationFrames.push(frames[gap]);
-        stationFrames.push(frames[gap + 1]);
+        // Intermediate placements are placeholders; vertices use the explicit world grids.
+        for (let index = 1; index < controls.slices[gap]; index++)
+            stationTransforms.push(transforms[gap]);
+        stationTransforms.push(transforms[gap + 1]);
     }
-    const stations = stationFrames.map((frame, row) => {
+    const stations = stationTransforms.map((transform, row) => {
         let contourIndex = 0;
         const convert = (contour) => {
             const index = contourIndex++;
             return { ...contour, points: allRows[index][row].points, spans: allSpans[index] };
         };
         return {
-            frame,
+            transform,
             profile: {
                 components: templates.map((component) => ({
                     ...component,
@@ -179,6 +177,6 @@ export function prepareLoftGeometry(input, options, limits, authoritative, recip
     });
     return {
         stations,
-        world: stationFrames.map((_, row) => allRows.map((contour) => contour[row].world)),
+        world: stationTransforms.map((_, row) => allRows.map((contour) => contour[row].world)),
     };
 }

package/dist/geometry/loft/mesh.js

@@ -0,0 +1,53 @@
+import { GeometryError } from "../errors.js";
+import { resolveModelingLimits } from "../limits.js";
+import { capturePath2Input, path2InputData } from "../paths/value.js";
+import { assertSamplingCount } from "../sampling/limits.js";
+import { pointLoftProfile, prepareLoftGeometry } from "./geometry.js";
+import { simpleLoftMesh } from "./simple-mesh.js";
+/**
+ * Lofts simple point contours at z heights or explicit affine transforms, in input order.
+ *
+ * Correspondence defaults to direct. CCW-normalized contours retain their
+ * seam and original vertices; unequal counts gain subdivisions or repeated fan slots.
+ * Both ends use ear-clipped caps, supporting concave profiles without center fans.
+ * Intermediate slices interpolate placed world vertices, never frame axes.
+ * Transformed coordinates must fit finite Float32 mesh storage.
+ * Path2 profiles must be closed; raw point collections are interpreted as closed.
+ *
+ * @param stations - At least two XY profiles in connection order, each with Z height or affine placement.
+ *
+ * @example Loft with explicit point correspondence
+ * ```ts
+ * const bottom = rectangleContour({ size: [20, 12] });
+ * const top = rectangleContour({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+ * mesh.loft([{ profile: bottom, z: 0 }, { profile: top, z: 30 }], { correspondence: "reindex" });
+ * ```
+ */
+export function loftMesh(stations, options = {}) {
+    if (typeof options !== "object" || options === null || Array.isArray(options))
+        throw new GeometryError("INVALID_ARGUMENT", "Loft options must be an object.", {
+            operation: "loftMesh",
+        });
+    const limits = resolveModelingLimits(options.limits);
+    if (!Array.isArray(stations) || stations.length < 2)
+        throw new GeometryError("INVALID_ARGUMENT", "Loft requires at least two stations.", {
+            operation: "loftMesh",
+        });
+    assertSamplingCount(stations.length, "loftMesh", limits.maxPathPoints);
+    const inputs = stations;
+    const input = inputs.map(({ profile, ...placement }) => ({
+        ...placement,
+        source: capturePath2Input(profile, true),
+    }));
+    assertSamplingCount(input.reduce((sum, station) => sum + station.source.count, 0), "loftMesh", 1_000_000);
+    let remaining = 1_000_000;
+    const profiles = input.map(({ source, ...placement }) => {
+        const points = path2InputData(source.input, true, {
+            maxPathPoints: Math.max(1, Math.min(limits.maxProfilePoints, remaining)),
+        }).points;
+        assertSamplingCount(points.length, "loftMesh", remaining);
+        remaining -= points.length;
+        return { ...placement, profile: pointLoftProfile(points) };
+    });
+    return simpleLoftMesh(prepareLoftGeometry(profiles, options, limits, false), limits);
+}

package/dist/geometry/loft/{loft-options.js → options.js}

@@ -1,21 +1,23 @@
 import { GeometryError } from "../errors.js";
-import { frameTransform3 } from "../transform3.js";
-/** @internal Resolves placement without sorting stations or interpolating their axes. */
-export function loftFrame(placement, operation = "loft") {
+import { translationTransform3 } from "../transforms/affine3.js";
+import { transform3 } from "../transforms/value.js";
+/** @internal Resolves placement without sorting stations or interpolating transformations. */
+export function loftTransform(placement, operation = "loft") {
     if (typeof placement !== "object" ||
         placement === null ||
         Array.isArray(placement) ||
-        "z" in placement === "frame" in placement)
-        throw new GeometryError("INVALID_ARGUMENT", "Each loft station must specify exactly one z or frame.", { operation });
+        "frame" in placement ||
+        ("transform" in placement && placement.transform === undefined) ||
+        "z" in placement === "transform" in placement)
+        throw new GeometryError("INVALID_ARGUMENT", "Each loft station must specify exactly one z or transform.", { operation });
     if ("z" in placement) {
         if (!Number.isFinite(placement.z))
             throw new GeometryError("NON_FINITE_VALUE", "Loft station z must be finite millimetres.", {
                 operation,
             });
-        return { origin: [0, 0, placement.z], xAxis: [1, 0, 0], yAxis: [0, 1, 0], zAxis: [0, 0, 1] };
+        return translationTransform3([0, 0, placement.z]);
     }
-    frameTransform3(placement.frame);
-    return placement.frame;
+    return transform3(placement.transform).toData();
 }
 /** @internal Validated controls shared by every loft construction route. */
 export function resolveLoftControls(options, stationCount) {
@@ -42,13 +44,13 @@ export function resolveLoftControls(options, stationCount) {
     if (duplicate && distribution !== "segments")
         fail("Vertex-duplication correspondence requires segments distribution.");
     const refine = expand(options.refine, stationCount, 1, "refine");
-    const slices = expand(options.slices, stationCount - 1, 0, "slices");
+    const slices = expand(options.slices, stationCount - 1, 1, "slices");
     for (const count of refine)
         if (!Number.isSafeInteger(count) || count < 1)
             fail("Loft refine values must be positive safe integers.");
     for (const count of slices)
-        if (!Number.isSafeInteger(count) || count < 0)
-            fail("Loft slices values must be nonnegative safe integers.");
+        if (!Number.isSafeInteger(count) || count < 1)
+            fail("Loft slices values must be positive safe integers.");
     return { methods, distribution, refine, slices };
 }
 const fail = (message) => {

package/dist/geometry/loft/{loft-simple-mesh.js → simple-mesh.js}

@@ -1,12 +1,13 @@
 import { GeometryError } from "../errors.js";
-import { analyzeTriangleMesh, validateTriangleMesh } from "../mesh/mesh.js";
-import { assertMeshAllocationWithinLimits } from "../model-limits.js";
-import { writeMeshVertex } from "../numeric.js";
-import { triangulateContour } from "./loft-triangulation.js";
+import { assertMeshAllocationWithinLimits } from "../limits.js";
+import { analyzeTriangleMesh } from "../mesh/operations.js";
+import { reverseOwnedTriangleWinding } from "../mesh/winding.js";
+import { writeMeshVertex } from "../mesh/write-vertex.js";
+import { triangulateContour } from "../regions/triangulation.js";
 /** @internal Pure closed simple-contour strips, retaining repeated correspondence slots as shared physical vertices. */
-export function simpleLoftMesh(geometry, limits) {
+export function simpleLoftMesh(geometry, limits, closed = false) {
     const count = geometry.world[0][0].length, rowCount = geometry.world.length;
-    const maxVertices = count * rowCount, maximumTriangles = 2 * count * (rowCount - 1) + 2 * (count - 2);
+    const maxVertices = count * rowCount, maximumTriangles = 2 * count * (closed ? rowCount : rowCount - 1) + (closed ? 0 : 2 * (count - 2));
     const bytes = 12 * (maxVertices + maximumTriangles);
     assertMeshAllocationWithinLimits(maxVertices, maximumTriangles, bytes, "loftMesh", limits);
     const positions = new Float32Array(maxVertices * 3), indices = new Uint32Array(maximumTriangles * 3);
@@ -61,9 +62,9 @@ export function simpleLoftMesh(geometry, limits) {
         indices[cursor++] = b;
         indices[cursor++] = c;
     };
-    for (let row = 0; row < rows.length - 1; row++)
+    for (let row = 0; row < (closed ? rows.length : rows.length - 1); row++)
         for (let index = 0; index < count; index++) {
-            const next = (index + 1) % count, a = rows[row], b = rows[row + 1];
+            const next = (index + 1) % count, a = rows[row], b = rows[(row + 1) % rows.length];
             triangle(a.slots[index], a.slots[next], b.slots[next]);
             triangle(a.slots[index], b.slots[next], b.slots[index]);
         }
@@ -72,20 +73,28 @@ export function simpleLoftMesh(geometry, limits) {
         for (let index = 0; index < triangles.length; index += 3)
             triangle(contour.vertices[triangles[index]], contour.vertices[triangles[index + (top ? 1 : 2)]], contour.vertices[triangles[index + (top ? 2 : 1)]]);
     };
-    cap(0, false);
-    cap(rows.length - 1, true);
+    if (!closed) {
+        cap(0, false);
+        cap(rows.length - 1, true);
+    }
     const mesh = {
         positions: positions.slice(0, vertexCount * 3),
         indices: indices.slice(0, cursor),
     };
-    const volume = analyzeTriangleMesh(mesh).signedVolume;
+    let volume;
+    try {
+        volume = analyzeTriangleMesh(mesh, { requireClosed: true }).signedVolume;
+    }
+    catch (error) {
+        // Preserve the zero-volume diagnostic ahead of a closure failure for collapsed lofts.
+        // Only invalid output needs a second traversal; successful meshes are analyzed once.
+        volume = analyzeTriangleMesh(mesh).signedVolume;
+        if (volume !== 0)
+            throw error;
+    }
     if (volume === 0)
         throw new GeometryError("DEGENERATE_GEOMETRY", "Loft stations collapse to zero enclosed volume.", { operation: "loftMesh" });
     if (volume < 0)
-        for (let index = 0; index < mesh.indices.length; index += 3) {
-            const b = mesh.indices[index + 1];
-            mesh.indices[index + 1] = mesh.indices[index + 2];
-            mesh.indices[index + 2] = b;
-        }
-    return validateTriangleMesh(mesh, { requireClosed: true });
+        reverseOwnedTriangleWinding(mesh.indices);
+    return mesh;
 }

package/dist/geometry/math/interpolation.js

@@ -0,0 +1,9 @@
+/** Internal scalar interpolation with exact endpoints and finite convex combinations. */
+export function interpolateCoordinate(a, b, t) {
+    if (t === 0)
+        return a;
+    if (t === 1)
+        return b;
+    // Opposite signs can overflow b - a even when the interpolated coordinate is finite.
+    return a < 0 !== b < 0 ? a * (1 - t) + b * t : a + (b - a) * t;
+}

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

@@ -1,7 +1,7 @@
 import { GeometryError } from "../errors.js";
 import { immutableMathClass } from "./immutable-value.js";
 import { add2, cross2, distance2, dot2, length2, lerp2, normalize2, scale2, subtract2, } from "./vector2.js";
-import { add3, cross3, distance3, dot3, length3, lerp3, normalize3, scale3, subtract3, } from "./vector3.js";
+import { add3, cross3, distance3, dot3, length3, lerp3, normalize3, projectOntoPlane3, scale3, subtract3, } from "./vector3.js";
 const finite = (value, operation) => {
     if (!Number.isFinite(value)) {
         throw new GeometryError("NON_FINITE_VALUE", "Vector coordinates and results must be finite.", {
@@ -130,6 +130,9 @@ const SpatialVector = /* @__PURE__ */ immutableMathClass(class SpatialVector {
     cross(other) {
         return new SpatialVector(cross3(this.values, operand3(other, "vector3.cross")), "vector3.cross");
     }
+    projectOntoPlane(normal) {
+        return new SpatialVector(projectOntoPlane3(this.values, normalize3(operand3(normal, "vector3.projectOntoPlane"), 0)), "vector3.projectOntoPlane");
+    }
     length() {
         return finite(length3(this.values), "vector3.length");
     }
@@ -148,7 +151,9 @@ const SpatialVector = /* @__PURE__ */ immutableMathClass(class SpatialVector {
  * 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.
+ * [normalize2](/docs/reference/math/normalize2) for tuple-based normalization in numerical loops.
+ *
+ * @param input - Finite XY tuple or vector; coordinates are copied without changing their units.
  */
 export function vector2(input) {
     const values = operand2(input, "vector2");
@@ -162,10 +167,14 @@ export function vector2(input) {
  * 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.
+ * [normalize3](/docs/reference/math/normalize3) for tuple-based normalization in numerical loops.
+ *
+ * @param input - Finite XYZ tuple or vector; coordinates are copied without changing their units.
  *
  * @example
  * ```ts
+ * import { vector3 } from "@metamesh/modeling/geometry";
+ *
  * const direction = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
  * const alignment = direction.dot([0, 0, 1]);
  * ```

package/dist/geometry/math/vector2.js

@@ -1,4 +1,5 @@
 import { GeometryError } from "../errors.js";
+import { interpolateCoordinate } from "./interpolation.js";
 /** Adds two finite XY vectors component-wise. */
 export const add2 = (a, b) => [a[0] + b[0], a[1] + b[1]];
 /** Subtracts `b` from `a` component-wise. */
@@ -13,17 +14,20 @@ export const scale2 = (vector, scale) => [
 ];
 /** Returns the scalar dot product. */
 export const dot2 = (a, b) => a[0] * b[0] + a[1] * b[1];
-/** Returns the signed scalar cross product; positive means `b` is counter-clockwise from `a`. */
+/** Returns the signed scalar cross product; positive means `b` is counterclockwise from `a`. */
 export const cross2 = (a, b) => a[0] * b[1] - a[1] * b[0];
 /** Returns Euclidean vector length in the vector's coordinate units. */
 export const length2 = (vector) => Math.hypot(vector[0], vector[1]);
 /** Returns Euclidean point distance without allocating an intermediate difference vector. */
 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`).
+ * Returns a unit vector; `epsilon` is a finite, nonnegative 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.
+ *
+ * @param vector - Vector with length greater than epsilon.
+ * @param epsilon - Minimum length in coordinate units; finite, nonnegative, default 1e-12.
  */
 export const normalize2 = (vector, epsilon = 1e-12) => {
     const operation = "normalize2";
@@ -53,11 +57,20 @@ export const normalize2 = (vector, epsilon = 1e-12) => {
     }
     return [vector[0] / length, vector[1] / length];
 };
-/** Linearly interpolates two vectors; `t` is dimensionless and may extrapolate. */
-export const lerp2 = (a, b, t) => add2(a, scale2(subtract2(b, a), t));
 /**
- * Rotates a finite vector counter-clockwise in XY by `degrees` about the origin.
+ * Linearly interpolates two vectors; `t` is dimensionless and may extrapolate.
+ *
+ * @param t - Unclamped fraction: 0 selects a, 1 selects b.
+ */
+export const lerp2 = (a, b, t) => [
+    interpolateCoordinate(a[0], b[0], t),
+    interpolateCoordinate(a[1], b[1], t),
+];
+/**
+ * Rotates a finite vector counterclockwise in XY by `degrees` about the origin.
  * Throws `NON_FINITE_VALUE` for nonfinite coordinates, angles, or derived coordinates.
+ *
+ * @param degrees - Counterclockwise angle in degrees.
  */
 export const rotate2 = (vector, degrees) => {
     if (!Number.isFinite(vector[0]) || !Number.isFinite(vector[1]) || !Number.isFinite(degrees)) {

package/dist/geometry/math/vector3.js

@@ -1,8 +1,11 @@
 import { GeometryError } from "../errors.js";
+import { interpolateCoordinate } from "./interpolation.js";
 /**
  * Adds two finite XYZ vectors component-wise.
  * @example
  * ```ts
+ * import { add3 } from "@metamesh/modeling/geometry/math";
+ *
  * add3([1, 2, 3], [4, 5, 6]); // [5, 7, 9]
  * ```
  */
@@ -60,10 +63,13 @@ export const length3 = (vector) => Math.hypot(vector[0], vector[1], vector[2]);
 /** Returns Euclidean point distance without allocating an intermediate difference vector. */
 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`).
+ * Returns a unit vector; `epsilon` is a finite, nonnegative 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.
+ *
+ * @param vector - Vector with length greater than epsilon.
+ * @param epsilon - Minimum length in coordinate units; finite, nonnegative, default 1e-12.
  */
 export const normalize3 = (vector, epsilon = 1e-12) => {
     const operation = "normalize3";
@@ -94,11 +100,28 @@ export const normalize3 = (vector, epsilon = 1e-12) => {
     }
     return [vector[0] / length, vector[1] / length, vector[2] / length];
 };
-/** Linearly interpolates two vectors; `t` is dimensionless and may extrapolate. */
-export const lerp3 = (a, b, t) => add3(a, scale3(subtract3(b, a), t));
-/** Removes the component parallel to a normalized plane normal. */
+/**
+ * Linearly interpolates two vectors; `t` is dimensionless and may extrapolate.
+ *
+ * @param t - Unclamped fraction: 0 selects a, 1 selects b.
+ */
+export const lerp3 = (a, b, t) => [
+    interpolateCoordinate(a[0], b[0], t),
+    interpolateCoordinate(a[1], b[1], t),
+    interpolateCoordinate(a[2], b[2], t),
+];
+/**
+ * Removes the component parallel to a normalized plane normal.
+ *
+ * @param normal - Unit plane normal; used without normalization.
+ */
 export const projectOntoPlane3 = (vector, normal) => subtract3(vector, scale3(normal, dot3(vector, normal)));
-/** Rotates a vector right-handed around a unit axis by `angle` radians. */
+/**
+ * Rotates a vector right-handed around a unit axis by `angle` radians.
+ *
+ * @param axis - Unit rotation axis; used without normalization.
+ * @param angle - Right-handed angle in radians.
+ */
 export const rotateAroundAxis3Radians = (vector, axis, angle) => {
     const cosine = Math.cos(angle);
     const sine = Math.sin(angle);

package/dist/geometry/math-api.js

@@ -0,0 +1,4 @@
+/** Tuple arithmetic and affine matrix kernels without host state. @packageDocumentation */
+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";
+export { IDENTITY_TRANSFORM3, applyTransformDirection3, applyTransformPoint3, multiplyTransform3, eulerTransform3, inverseTransform3, rotationTransform3, scaleTransform3, transformDeterminant3, translationTransform3, validateTransform3, validateRigidTransform3, } from "./transforms/affine3.js";

package/dist/geometry/mechanical/gear-motion.js

@@ -1,5 +1,5 @@
 import { GeometryError } from "../errors.js";
-import { polygonClipping } from "../polygon-clipping.js";
+import { polygonClipping } from "../regions/clipping.js";
 import { resolveCylindricalGearPair, sampleCylindricalGearOutline, sampleInternalCylindricalGearSpaceOutline, } from "./gears.js";
 const DEFAULT_MOTION_SAMPLES = 24;
 const MAXIMUM_MOTION_SAMPLES = 360;
@@ -51,10 +51,12 @@ const multiPolygonArea = (multiPolygon) => multiPolygon.reduce((total, polygon)
  * Measures sampled kinematic interference over one tooth cycle of an internal gear pair.
  *
  * The driver and ring start with half-tooth offsets for odd tooth counts, then rotate in the
- * same direction at their resolved tooth-count ratio. Each
- * sampled pinion outline is subtracted from the ring's center-and-space opening; remaining area is
- * solid overlap. This catches involute, tip, and trimming interference that a single assembled pose
- * misses. It is a deterministic model check, not a certified gear-rating calculation.
+ * same direction at their resolved tooth-count ratio. Subtracting the ring's center-and-space
+ * opening from each sampled pinion outline leaves the area overlapping ring material. This detects
+ * involute, tip, and trimming interference that a single assembled pose misses.
+ * It is a deterministic model check, not a certified gear-rating calculation.
+ *
+ * @param spec - Internal pair: external driver pinion and internal driven ring.
  */
 export function measureInternalCylindricalGearPairMotion(spec, options = {}) {
     if (spec.mesh !== "internal") {

package/dist/geometry/mechanical/gears.js

@@ -1,7 +1,7 @@
 import { GeometryError } from "../errors.js";
-import { signedContourArea } from "../regions.js";
-import { resolveCircularSegments, resolveGeometryResolution, } from "../resolution.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+import { signedContourArea } from "../regions/operations.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling/limits.js";
+import { resolveCircularSegments, resolveGeometryResolution, } from "../sampling/resolution.js";
 const DEFAULT_PRESSURE_ANGLE_DEGREES = 20;
 const DEFAULT_CLEARANCE_FACTOR = 0.25;
 const MAXIMUM_TOOTH_COUNT = 1_000;
@@ -31,6 +31,8 @@ const freezePoints = (points) => {
  *
  * The normal-plane limit is `2 / sin²(alpha_n)`. Helical gears use the standard virtual tooth
  * count `z_v = z / cos³(beta)`, so increasing helix angle can reduce the physical tooth count.
+ *
+ * @param spec - Pressure and signed helix angles in degrees; defaults are 20 and zero.
  */
 export function minimumCylindricalGearToothCountWithoutUndercut(spec = {}) {
     const pressureAngle = finite(spec.pressureAngle ?? DEFAULT_PRESSURE_ANGLE_DEGREES, "Pressure angle", "minimumCylindricalGearToothCountWithoutUndercut");
@@ -177,6 +179,8 @@ const resolveCylindricalGearDimensions = (spec, profile) => {
  * The gear axis is +Z and the returned radii describe its XY pitch plane. Inputs below the
  * pressure- and helix-dependent no-undercut tooth count are rejected because profile shift is not
  * currently supported.
+ *
+ * @param spec - Nominal gear dimensions in millimetres and degrees.
  */
 export function resolveCylindricalGear(spec) {
     return resolveCylindricalGearDimensions(spec, "external");
@@ -187,6 +191,8 @@ export function resolveCylindricalGear(spec) {
  * Both gears must use the same normal module, pressure angle, and helix-angle
  * magnitude. An external pair uses opposite helix hands; an internal pair uses
  * the same hand. The function validates those conjugate pitch invariants.
+ *
+ * @param spec - Driver and driven gears using the same normal pitch system.
  */
 export function resolveCylindricalGearPair(spec) {
     if (spec.mesh !== "external" && spec.mesh !== "internal") {
@@ -413,6 +419,8 @@ const sampleResolvedCylindricalGearOutline = (dimensions, options, operation) =>
  * The returned loop is counter-clockwise, closed implicitly without a repeated
  * seam point, and contains no holes. Its center is the origin and its axis is
  * +Z. Bore, hub, keyway, twist, and face-width choices remain generator-owned.
+ *
+ * @param spec - External gear dimensions in millimetres and degrees; undercut profiles reject.
  */
 export function sampleCylindricalGearOutline(spec, options = {}) {
     return sampleResolvedCylindricalGearOutline(resolveCylindricalGear(spec), options, "sampleCylindricalGearOutline");
@@ -424,11 +432,17 @@ export function sampleCylindricalGearOutline(spec, options = {}) {
  * dedendum above it. At the pitch circle, positive backlash widens each sampled space
  * tangentially. The returned CCW loop encloses the center and is intended to be reversed
  * when used as a region hole.
+ *
+ * @param spec - Internal ring dimensions in millimetres and degrees; backlash widens tooth spaces.
  */
 export function sampleInternalCylindricalGearSpaceOutline(spec, options = {}) {
     return sampleResolvedCylindricalGearOutline(internalCylindricalGearSpaceDimensions(resolveCylindricalGearDimensions(spec, "internal")), options, "sampleInternalCylindricalGearSpaceOutline");
 }
-/** Resolves a rack segment that is conjugate with the same normal cylindrical pitch system. */
+/**
+ * Resolves a rack segment that is conjugate with the same normal cylindrical pitch system.
+ *
+ * @param spec - Rack dimensions in millimetres and degrees.
+ */
 export function resolveRackPitch(spec) {
     const reference = resolveCylindricalGear({
         ...(spec.backlash === undefined ? {} : { backlash: spec.backlash }),
@@ -464,6 +478,9 @@ export function resolveRackPitch(spec) {
  * The path begins and ends on the root line, omits duplicate adjacent points,
  * and leaves base thickness, mounting features, extrusion, and helical sweep to
  * the owning generator.
+ *
+ * @param spec - Rack dimensions in millimetres and degrees, along +X.
+ * @param limits - Sampling limits; exceeding them throws without coarsening.
  */
 export function sampleRackToothPath(spec, limits = {}) {
     const dimensions = resolveRackPitch(spec);

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

@@ -1,7 +1,7 @@
 import { GeometryError } from "../errors.js";
-import { assertPositivePrimitive, assertPrimitiveOptions } from "../primitive-resolvers.js";
-import { resolveAlignedCircularSegments } from "../resolution.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+import { assertPositivePrimitive, assertPrimitiveOptions } from "../primitives/resolvers.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling/limits.js";
+import { resolveAlignedCircularSegments } from "../sampling/resolution.js";
 /** @internal Shared fixed frame; ordinary transforms place the joint in a model. */
 export const knuckleHingeAxis = Object.freeze({
     position: Object.freeze([0, 0, 0]),
@@ -19,9 +19,11 @@ const invalid = (message) => {
  * 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.
+ * Rejects non-finite or non-positive dimensions, invalid mode/count combinations, exhausted axial
+ * length, missing/excessive lift-off engagement, and non-positive conservative faceted barrel walls.
  * Manufacturing minima, strength, mounting, retention, handedness, and motion remain caller policy.
+ *
+ * @param spec - Joint dimensions in millimetres, mode, and knuckle count.
  */
 export function resolveKnuckleHinge(spec, options = {}) {
     assertPrimitiveOptions(spec, "resolveKnuckleHinge");

package/dist/geometry/mechanical/threads/fit.js

@@ -1,5 +1,5 @@
 import { GeometryError } from "../../errors.js";
-import { resolveCircularSegments, resolveGeometryResolution, } from "../../resolution.js";
+import { resolveCircularSegments, resolveGeometryResolution, } from "../../sampling/resolution.js";
 import { resolveGeometryTolerance } from "../../tolerance.js";
 import { compensateThreadProfileForFaceting } from "./profiles.js";
 const frozenFit = (maleRadialInset, femaleRadialOutset, axialBacklash) => Object.freeze({ axialBacklash, femaleRadialOutset, maleRadialInset });
@@ -32,7 +32,11 @@ const validateFitPolicy = (policy) => {
     }
     return Object.freeze({ axialBacklash: axial, femaleRadialOutset: female, maleRadialInset: male });
 };
-/** Resolves and validates a named or caller-defined print-fit policy. */
+/**
+ * Resolves and validates a named or caller-defined print-fit policy.
+ *
+ * @param fit - Named fit or non-negative per-side radial and total axial allowances, in millimetres.
+ */
 export function resolvePrintableThreadFitPolicy(fit = "normal") {
     if (typeof fit !== "string")
         return validateFitPolicy(fit);
@@ -82,6 +86,8 @@ export function compensateThreadDiameters(options) {
  *
  * An exact `circularSegments` value must already be divisible by `starts`; it is never silently
  * raised. Adaptive policies align upward and fail if that would exceed `maxSegments`.
+ *
+ * @param options - Nominal diameter, uncompensated profile, and shared mating resolution.
  */
 export function resolveThreadCircularSegments(options) {
     const operation = "resolveThreadCircularSegments";

package/dist/geometry/mechanical/threads/helices.js

@@ -1,10 +1,12 @@
 /** Conventional thread helix sampling, independent of surface construction. */
 import { GeometryError } from "../../errors.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../../sampling-limits.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../../sampling/limits.js";
 import { assertFiniteThreadNumber } from "./profiles.js";
 /**
  * Samples evenly phased thread helices with finite `lead = pitch * starts`.
- * All starts together respect maxPathPoints (default 100000); excessive counts fail before allocation.
+ * All starts together respect `maxPathPoints`; excessive counts fail before allocation.
+ *
+ * @param options - Dimensions in millimetres; lead is pitch multiplied by starts.
  */
 export function sampleConventionalThreadHelices(options) {
     const operation = "sampleThreadHelices";

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

@@ -1,7 +1,7 @@
 /** Thread input resolution, end/bevel boundaries, and allocation preflight. */
 import { GeometryError } from "../../errors.js";
-import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "../../model-limits.js";
-import { resolveCircularSegments, resolveGeometryResolution, } from "../../resolution.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "../../limits.js";
+import { resolveCircularSegments, resolveGeometryResolution, } from "../../sampling/resolution.js";
 import { resolveGeometryTolerance } from "../../tolerance.js";
 import { resolveBevel } from "./bevel.js";
 import { assertFiniteThreadNumber, createThreadRidgeSection, freezeThreadProfilePoints, MAX_THREAD_PROFILE_POINTS, } from "./profiles.js";
@@ -341,6 +341,8 @@ export const resolveHelicalThreadSolidMeshPreflight = (options, operation) => {
  * Successful preflight leaves generated coordinate and topology checks to mesh construction.
  *
  * See `mesh.threadSolid` for standalone mesh construction.
+ *
+ * @param options - Dimensions in millimetres and a validated profile; apply any fit compensation first.
  */
 export function preflightThreadSolidMesh(options) {
     return resolveHelicalThreadSolidMeshPreflight(options, "preflightThreadSolidMesh").preflight;