@metamesh/modeling 0.12.0 → 0.14.0

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

@@ -0,0 +1,168 @@
+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";
+const finite = (value, operation) => {
+    if (!Number.isFinite(value)) {
+        throw new GeometryError("NON_FINITE_VALUE", "Vector coordinates and results must be finite.", {
+            operation,
+        });
+    }
+    return value;
+};
+const validateCoordinates = (values, operation) => {
+    for (const coordinate of values)
+        finite(coordinate, operation);
+};
+const operand2 = (input, operation) => {
+    const values = vector2Data(input);
+    validateCoordinates(values, operation);
+    return values;
+};
+const operand3 = (input, operation) => {
+    const values = vector3Data(input);
+    validateCoordinates(values, operation);
+    return values;
+};
+function invalidVector(dimensions) {
+    throw new GeometryError("INVALID_ARGUMENT", `Expected a ${dimensions}D vector or coordinate tuple.`, {
+        operation: `vector${dimensions}`,
+    });
+}
+const tupleData = (input, dimensions) => {
+    if (typeof input !== "object" || input === null)
+        return invalidVector(dimensions);
+    let values = input;
+    if (!Array.isArray(input)) {
+        const method = Reflect.get(input, "toArray");
+        if (typeof method !== "function")
+            return invalidVector(dimensions);
+        values = Reflect.apply(method, input, []);
+    }
+    if (!Array.isArray(values) || values.length !== dimensions)
+        return invalidVector(dimensions);
+    return values;
+};
+/** Internal tuple view; validates dimension and shape without allocating or checking finiteness. */
+export const vector2Data = (input) => tupleData(input, 2);
+/** Internal tuple view; validates dimension and shape without allocating or checking finiteness. */
+export const vector3Data = (input) => tupleData(input, 3);
+const PlanarVector = /* @__PURE__ */ immutableMathClass(class PlanarVector {
+    values;
+    constructor(values, operation = "vector2") {
+        this.values = values;
+        validateCoordinates(values, operation);
+        Object.freeze(values);
+        Object.freeze(this);
+    }
+    get x() {
+        return this.values[0];
+    }
+    get y() {
+        return this.values[1];
+    }
+    add(other) {
+        return new PlanarVector(add2(this.values, operand2(other, "vector2.add")), "vector2.add");
+    }
+    subtract(other) {
+        return new PlanarVector(subtract2(this.values, operand2(other, "vector2.subtract")), "vector2.subtract");
+    }
+    scale(factor) {
+        return new PlanarVector(scale2(this.values, finite(factor, "vector2.scale")), "vector2.scale");
+    }
+    normalize(epsilon) {
+        return new PlanarVector(normalize2(this.values, epsilon), "vector2.normalize");
+    }
+    lerp(other, t) {
+        return new PlanarVector(lerp2(this.values, operand2(other, "vector2.lerp"), finite(t, "vector2.lerp")), "vector2.lerp");
+    }
+    dot(other) {
+        return finite(dot2(this.values, operand2(other, "vector2.dot")), "vector2.dot");
+    }
+    cross(other) {
+        return finite(cross2(this.values, operand2(other, "vector2.cross")), "vector2.cross");
+    }
+    length() {
+        return finite(length2(this.values), "vector2.length");
+    }
+    distance(other) {
+        return finite(distance2(this.values, operand2(other, "vector2.distance")), "vector2.distance");
+    }
+    toArray() {
+        return this.values;
+    }
+});
+const SpatialVector = /* @__PURE__ */ immutableMathClass(class SpatialVector {
+    values;
+    constructor(values, operation = "vector3") {
+        this.values = values;
+        validateCoordinates(values, operation);
+        Object.freeze(values);
+        Object.freeze(this);
+    }
+    get x() {
+        return this.values[0];
+    }
+    get y() {
+        return this.values[1];
+    }
+    get z() {
+        return this.values[2];
+    }
+    add(other) {
+        return new SpatialVector(add3(this.values, operand3(other, "vector3.add")), "vector3.add");
+    }
+    subtract(other) {
+        return new SpatialVector(subtract3(this.values, operand3(other, "vector3.subtract")), "vector3.subtract");
+    }
+    scale(factor) {
+        return new SpatialVector(scale3(this.values, finite(factor, "vector3.scale")), "vector3.scale");
+    }
+    normalize(epsilon) {
+        return new SpatialVector(normalize3(this.values, epsilon), "vector3.normalize");
+    }
+    lerp(other, t) {
+        return new SpatialVector(lerp3(this.values, operand3(other, "vector3.lerp"), finite(t, "vector3.lerp")), "vector3.lerp");
+    }
+    dot(other) {
+        return finite(dot3(this.values, operand3(other, "vector3.dot")), "vector3.dot");
+    }
+    cross(other) {
+        return new SpatialVector(cross3(this.values, operand3(other, "vector3.cross")), "vector3.cross");
+    }
+    length() {
+        return finite(length3(this.values), "vector3.length");
+    }
+    distance(other) {
+        return finite(distance3(this.values, operand3(other, "vector3.distance")), "vector3.distance");
+    }
+    toArray() {
+        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.
+ */
+export function vector2(input) {
+    const values = operand2(input, "vector2");
+    return new PlanarVector([values[0], values[1]]);
+}
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const direction = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
+ * const alignment = direction.dot([0, 0, 1]);
+ * ```
+ */
+export function vector3(input) {
+    const values = operand3(input, "vector3");
+    return new SpatialVector([values[0], values[1], values[2]]);
+}

package/dist/geometry/math/vector2.js

@@ -0,0 +1,80 @@
+import { GeometryError } from "../errors.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. */
+export const subtract2 = (a, b) => [
+    a[0] - b[0],
+    a[1] - b[1],
+];
+/** Multiplies a vector by a dimensionless scalar. */
+export const scale2 = (vector, scale) => [
+    vector[0] * scale,
+    vector[1] * 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`. */
+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`).
+ * Rejects invalid thresholds, nonfinite lengths, and lengths at or below the threshold with
+ * `INVALID_TOLERANCE`, `NON_FINITE_VALUE`, and `DEGENERATE_GEOMETRY` respectively.
+ */
+export const normalize2 = (vector, epsilon = 1e-12) => {
+    const operation = "normalize2";
+    if (!Number.isFinite(epsilon) || epsilon < 0) {
+        throw new GeometryError("INVALID_TOLERANCE", "epsilon must be finite and non-negative.", {
+            operation,
+        });
+    }
+    const length = length2(vector);
+    if (!Number.isFinite(length)) {
+        throw new GeometryError("NON_FINITE_VALUE", "Cannot normalize a vector without finite length.", {
+            operation,
+        });
+    }
+    if (length <= epsilon) {
+        throw new GeometryError("DEGENERATE_GEOMETRY", "Cannot normalize a zero-length vector.", {
+            operation,
+        });
+    }
+    // Subnormal lengths lose relative precision; rescale only this rare case before division.
+    if (length < 2 ** -1022) {
+        const maximum = Math.max(Math.abs(vector[0]), Math.abs(vector[1]));
+        const x = vector[0] / maximum;
+        const y = vector[1] / maximum;
+        const scaledLength = Math.hypot(x, y);
+        return [x / scaledLength, y / scaledLength];
+    }
+    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.
+ * Throws `NON_FINITE_VALUE` for nonfinite coordinates, angles, or derived coordinates.
+ */
+export const rotate2 = (vector, degrees) => {
+    if (!Number.isFinite(vector[0]) || !Number.isFinite(vector[1]) || !Number.isFinite(degrees)) {
+        throw new GeometryError("NON_FINITE_VALUE", "Rotation coordinates and angle must be finite.", {
+            operation: "rotate2",
+        });
+    }
+    const radians = degrees * (Math.PI / 180);
+    const cosine = Math.cos(radians);
+    const sine = Math.sin(radians);
+    const rotated = [
+        vector[0] * cosine - vector[1] * sine,
+        vector[0] * sine + vector[1] * cosine,
+    ];
+    if (!Number.isFinite(rotated[0]) || !Number.isFinite(rotated[1])) {
+        throw new GeometryError("NON_FINITE_VALUE", "Rotated coordinates must remain finite.", {
+            operation: "rotate2",
+        });
+    }
+    return rotated;
+};

package/dist/geometry/math/vector3.js

@@ -1,3 +1,4 @@
+import { GeometryError } from "../errors.js";
 /**
  * Adds two finite XYZ vectors component-wise.
  * @example
@@ -5,7 +6,11 @@
  * add3([1, 2, 3], [4, 5, 6]); // [5, 7, 9]
  * ```
  */
-export const add3 = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+export const add3 = (a, b) => [
+    a[0] + b[0],
+    a[1] + b[1],
+    a[2] + b[2],
+];
 /**
  * Subtracts `b` from `a`.
  * @example
@@ -13,7 +18,11 @@ export const add3 = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
  * subtract3([4, 5, 6], [1, 2, 3]); // [3, 3, 3]
  * ```
  */
-export const subtract3 = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+export const subtract3 = (a, b) => [
+    a[0] - b[0],
+    a[1] - b[1],
+    a[2] - b[2],
+];
 /**
  * Multiplies a vector by a dimensionless scalar.
  * @example
@@ -48,23 +57,48 @@ export const cross3 = (a, b) => [
 ];
 /** Returns Euclidean vector length in the vector's coordinate units. */
 export const length3 = (vector) => Math.hypot(vector[0], vector[1], vector[2]);
-/** Normalizes a finite vector and rejects nonfinite lengths or lengths at or below `epsilon`. */
+/** 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`).
+ * Rejects invalid thresholds, nonfinite lengths, and lengths at or below the threshold with
+ * `INVALID_TOLERANCE`, `NON_FINITE_VALUE`, and `DEGENERATE_GEOMETRY` respectively.
+ */
 export const normalize3 = (vector, epsilon = 1e-12) => {
+    const operation = "normalize3";
+    if (!Number.isFinite(epsilon) || epsilon < 0) {
+        throw new GeometryError("INVALID_TOLERANCE", "epsilon must be finite and non-negative.", {
+            operation,
+        });
+    }
     const length = length3(vector);
     if (!Number.isFinite(length)) {
-        throw new Error("Cannot normalize a vector without finite length.");
+        throw new GeometryError("NON_FINITE_VALUE", "Cannot normalize a vector without finite length.", {
+            operation,
+        });
     }
     if (length <= epsilon) {
-        throw new Error("Cannot normalize a zero-length vector.");
+        throw new GeometryError("DEGENERATE_GEOMETRY", "Cannot normalize a zero-length vector.", {
+            operation,
+        });
+    }
+    // Subnormal lengths lose relative precision; rescale only this rare case before division.
+    if (length < 2 ** -1022) {
+        const maximum = Math.max(Math.abs(vector[0]), Math.abs(vector[1]), Math.abs(vector[2]));
+        const x = vector[0] / maximum;
+        const y = vector[1] / maximum;
+        const z = vector[2] / maximum;
+        const scaledLength = Math.hypot(x, y, z);
+        return [x / scaledLength, y / scaledLength, z / scaledLength];
     }
-    return scale3(vector, 1 / length);
+    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. */
 export const projectOntoPlane3 = (vector, normal) => subtract3(vector, scale3(normal, dot3(vector, normal)));
-/** Rotates a vector right-handed around an axis by `angle` radians. */
-export const rotateAroundAxis3 = (vector, axis, angle) => {
+/** Rotates a vector right-handed around a unit axis by `angle` radians. */
+export const rotateAroundAxis3Radians = (vector, axis, angle) => {
     const cosine = Math.cos(angle);
     const sine = Math.sin(angle);
     return add3(add3(scale3(vector, cosine), scale3(cross3(axis, vector), sine)), scale3(axis, dot3(axis, vector) * (1 - cosine)));

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

@@ -50,7 +50,8 @@ const multiPolygonArea = (multiPolygon) => multiPolygon.reduce((total, polygon)
 /**
  * Measures sampled kinematic interference over one tooth cycle of an internal gear pair.
  *
- * The driver and ring rotate in the same direction at their resolved tooth-count ratio. Each
+ * 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.
@@ -71,11 +72,13 @@ export function measureInternalCylindricalGearPairMotion(spec, options = {}) {
     const ringTipRadius = pair.driven.pitchRadius - pair.driven.addendum;
     const contactWindow = contactWindowPolygon(pair.centerDistance, pair.driver.outsideRadius, ringTipRadius);
     const initialRingPhase = pair.driven.toothCount % 2 === 0 ? 0 : pair.driven.angularPitch / 2;
+    const initialDriverPhase = pair.driver.toothCount % 2 === 0 ? 0 : pair.driver.angularPitch / 2;
     let maximumOverlapArea = 0;
-    let maximumPhase = 0;
+    let maximumPhase = initialDriverPhase;
     for (let sample = 0; sample < samples; sample += 1) {
-        const driverPhase = (pair.driver.angularPitch * sample) / samples;
-        const drivenPhase = initialRingPhase + driverPhase / pair.ratio;
+        const phase = (pair.driver.angularPitch * sample) / samples;
+        const driverPhase = initialDriverPhase + phase;
+        const drivenPhase = initialRingPhase + phase / pair.ratio;
         const posedDriver = clippingPolygon(transformedLoop(driver, driverPhase));
         const posedSpace = clippingPolygon(transformedLoop(ringSpace, drivenPhase, pair.centerDistance));
         const contactDriver = polygonClipping.intersection(posedDriver, contactWindow);

package/dist/geometry/mechanical/gears.js

@@ -1,5 +1,5 @@
 import { GeometryError } from "../errors.js";
-import { signedAreaLoop2 } from "../regions.js";
+import { signedContourArea } from "../regions.js";
 import { resolveCircularSegments, resolveGeometryResolution, } from "../resolution.js";
 import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
 const DEFAULT_PRESSURE_ANGLE_DEGREES = 20;
@@ -398,7 +398,7 @@ const sampleResolvedCylindricalGearOutline = (dimensions, options, operation) =>
         }
     }
     points.pop();
-    if (!(signedAreaLoop2(points) > 0)) {
+    if (!(signedContourArea(points) > 0)) {
         throw new GeometryError("INVALID_TOPOLOGY", "The sampled gear outline must be counter-clockwise.", {
             operation,
         });

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

@@ -1,6 +1,6 @@
 /** Closed ridge and complete-solid mesh construction from resolved thread plans. */
-import { triangulateLoop2 } from "../loft.js";
-import { joinTriangleMeshes, measureTriangleMesh, reverseTriangleMesh, validateTriangleMesh, } from "../mesh.js";
+import { triangulateContour } from "../loft/loft.js";
+import { joinTriangleMeshes, measureTriangleMesh, reverseTriangleMesh, validateTriangleMesh, } from "../mesh/mesh.js";
 import { assertMeshAllocationWithinLimits, resolveModelingLimits } from "../model-limits.js";
 import { resolveHelicalThreadMeshOptions, resolveHelicalThreadSolidMeshPreflight, } from "./thread-mesh-plan.js";
 import { buildThreadSurfaceColumn, stitchThreadSurfaceColumns } from "./thread-surface.js";
@@ -45,7 +45,7 @@ const buildThreadRidgeComponent = (options) => {
             const c = (column + 1) * size + next, d = (column + 1) * size + point;
             indices.push(a, b, c, a, c, d);
         }
-    const capTriangles = triangulateLoop2([...section].reverse());
+    const capTriangles = triangulateContour([...section].reverse());
     const cap = (column, top) => {
         for (let offset = 0; offset < capTriangles.length; offset += 3) {
             const a = column * size + (size - 1 - capTriangles[offset]);

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

@@ -1,6 +1,6 @@
 /** Periodic thread profiles and axial/radial fit compensation. */
 import { GeometryError } from "../errors.js";
-import { triangulateLoop2 } from "../loft.js";
+import { triangulateContour } from "../loft/loft.js";
 import { resolveGeometryTolerance } from "../tolerance.js";
 const BUTTRESS_DEFAULT_DEPTH_RATIO = 0.66271;
 const BUTTRESS_CREST_FLAT_RATIO = 0.16316;
@@ -207,7 +207,7 @@ export const createThreadRidgeSection = (points, minimum, linearTolerance, opera
     // closing the ridge section retraces its minor-envelope edge, creating overlapping cap faces and
     // zero-area triangles. Keep exactly the connected tooth plus its two root transition points.
     const section = points.slice(firstRaised - 1, lastRaised + 2);
-    triangulateLoop2([...section].reverse());
+    triangulateContour([...section].reverse());
     return section;
 };
 const standardProfile = (kind, pitch, depth, root, crest, leftRun, rightRun) => {

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

@@ -124,7 +124,7 @@ export const buildThreadSurfaceColumn = (profile, resolved, options, angle, maxi
     };
     const candidates = [];
     let order = 0;
-    const add = (z, kind = "regular", profileRadial, endFactor, surfaceRadius, profileOrdinal, atLeadTip = false) => {
+    const add = (z, { kind = "regular", profileRadial, endFactor, surfaceRadius, profileOrdinal, atLeadTip = false, } = {}) => {
         if (z < -resolved.tolerance.linear || z > resolved.length + resolved.tolerance.linear)
             return;
         candidates.push({
@@ -182,7 +182,12 @@ export const buildThreadSurfaceColumn = (profile, resolved, options, angle, maxi
             // redundant in this sparse mesher and would reintroduce dense, near-collinear triangles.
             for (const [profileIndex, [profileAxial, profileRadial],] of resolved.surfaceSection.entries()) {
                 const profileRadius = majorRadius + profileRadial;
-                add(center + profileAxial * scale.width, "profile", undefined, undefined, leadInEnvelopeRadius + (profileRadius - leadInEnvelopeRadius) * scale.height, period * resolved.surfaceSection.length + profileIndex, atBottomTip || atTopTip);
+                add(center + profileAxial * scale.width, {
+                    kind: "profile",
+                    surfaceRadius: leadInEnvelopeRadius + (profileRadius - leadInEnvelopeRadius) * scale.height,
+                    profileOrdinal: period * resolved.surfaceSection.length + profileIndex,
+                    atLeadTip: atBottomTip || atTopTip,
+                });
             }
         }
     }
@@ -191,7 +196,11 @@ export const buildThreadSurfaceColumn = (profile, resolved, options, angle, maxi
             const firstPeriod = Math.ceil((activeMinimum - phaseShift - profileAxial - resolved.tolerance.linear) / profile.pitch);
             const lastPeriod = Math.floor((activeMaximum - phaseShift - profileAxial + resolved.tolerance.linear) / profile.pitch);
             for (let period = firstPeriod; period <= lastPeriod; period += 1) {
-                add(phaseShift + profileAxial + period * profile.pitch, "profile", profileRadial, undefined, undefined, period * resolved.surfaceSection.length + profileIndex);
+                add(phaseShift + profileAxial + period * profile.pitch, {
+                    kind: "profile",
+                    profileRadial,
+                    profileOrdinal: period * resolved.surfaceSection.length + profileIndex,
+                });
             }
         }
     }
@@ -199,14 +208,14 @@ export const buildThreadSurfaceColumn = (profile, resolved, options, angle, maxi
         !usesScaledLeadIn &&
         resolved.bottomBoundary > resolved.tolerance.linear &&
         resolved.bottomBoundary < resolved.length - resolved.tolerance.linear) {
-        add(resolved.bottomBoundary, "forced-bottom", undefined, 0);
+        add(resolved.bottomBoundary, { kind: "forced-bottom", endFactor: 0 });
     }
     const upperThreadBoundary = resolved.topBoundary;
     if (resolved.top === "blunt" &&
         !usesScaledLeadIn &&
         upperThreadBoundary > resolved.tolerance.linear &&
         upperThreadBoundary < resolved.length - resolved.tolerance.linear) {
-        add(upperThreadBoundary, "forced-top", undefined, 0);
+        add(upperThreadBoundary, { kind: "forced-top", endFactor: 0 });
     }
     candidates.sort((left, right) => left.z - right.z || left.order - right.order);
     const normalized = [];

package/dist/geometry/{mesh-centroid.js → mesh/mesh-centroid.js}

@@ -1,4 +1,4 @@
-import { GeometryError } from "./errors.js";
+import { GeometryError } from "../errors.js";
 import { analyzeTriangleMesh } from "./mesh.js";
 /**
  * Computes the uniform-density volume centroid of an oriented closed solid, including cavity shells.

package/dist/geometry/{mesh-planar.js → mesh/mesh-planar.js}

@@ -1,4 +1,4 @@
-import { GeometryError } from "./errors.js";
+import { GeometryError } from "../errors.js";
 import { buildTriangleMeshQualityAnalysis, } from "./mesh-quality.js";
 const DEFAULT_MAXIMUM_FLIP_ATTEMPTS = 1_000_000;
 const DEFAULT_MAXIMUM_PATCH_TRIANGLE_COUNT = 50_000;

package/dist/geometry/{mesh-quality.js → mesh/mesh-quality.js}

@@ -1,5 +1,5 @@
-import { GeometryError } from "./errors.js";
-import { resolveGeometryTolerance, } from "./tolerance.js";
+import { GeometryError } from "../errors.js";
+import { resolveGeometryTolerance, } from "../tolerance.js";
 const DEFAULT_MAXIMUM_TRIANGLE_COUNT = 200_000;
 const FLOAT32_EPSILON = 2 ** -23;
 const MINIMUM_PLANAR_ANGULAR_TOLERANCE = 1e-5;

package/dist/geometry/{mesh-signature.js → mesh/mesh-signature.js}

@@ -1,5 +1,5 @@
-import { GeometryError } from "./errors.js";
-import { analyzeTriangleMesh, validateTriangleMesh, } from "./mesh.js";
+import { GeometryError } from "../errors.js";
+import { analyzeTriangleMesh, validateTriangleMesh } from "./mesh.js";
 const DEFAULT_POSITION_TOLERANCE = 1e-5;
 const DEFAULT_VOLUME_TOLERANCE = 1e-4;
 const DEFAULT_MAXIMUM_TRIANGLE_COUNT = 200_000;

package/dist/geometry/{mesh-solid-intersections.js → mesh/mesh-solid-intersections.js}

@@ -1,4 +1,8 @@
-const subtract = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const subtract = (a, b) => [
+    a[0] - b[0],
+    a[1] - b[1],
+    a[2] - b[2],
+];
 const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
 const cross = (a, b) => [
     a[1] * b[2] - a[2] * b[1],

package/dist/geometry/{mesh-solid.js → mesh/mesh-solid.js}

@@ -1,8 +1,8 @@
-import { GeometryError } from "./errors.js";
+import { GeometryError } from "../errors.js";
+import { resolveGeometryTolerance } from "../tolerance.js";
 import { IndexedMeshEdgeTable } from "./mesh-edge-table.js";
 import { prepareSolidTriangle, trianglesIntersectBeyondSharedBoundary, triangleSolidAngle, } from "./mesh-solid-intersections.js";
 import { analyzeTriangleMesh } from "./mesh.js";
-import { resolveGeometryTolerance } from "./tolerance.js";
 const MAXIMUM_TRIANGLES = 200_000;
 const MAXIMUM_TESTS = 2_000_000;
 /**

package/dist/geometry/{mesh.js → mesh/mesh.js}

@@ -1,8 +1,8 @@
-import { GeometryError } from "./errors.js";
+import { GeometryError } from "../errors.js";
+import { writeMeshVertex } from "../numeric.js";
+import { resolveGeometryTolerance } from "../tolerance.js";
+import { transformDeterminant3, validateTransform3 } from "../transform3.js";
 import { IndexedMeshEdgeTable } from "./mesh-edge-table.js";
-import { writeMeshVertex } from "./numeric.js";
-import { resolveGeometryTolerance } from "./tolerance.js";
-import { transformDeterminant3, validateTransform3 } from "./transform3.js";
 function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = false) {
     // Snapshot meshes can expose owned-copy accessors. Read each buffer once before traversal.
     const source = { positions: mesh.positions, indices: mesh.indices };
@@ -161,10 +161,9 @@ export function analyzeTriangleMesh(mesh, options = {}) {
 /**
  * Validates mesh buffers, indices, triangle area, and optionally closed topology.
  *
- * Closed validation requires each edge to occur exactly twice with opposite
- * directions, rejecting boundary and non-manifold edges. Validation does not
- * mutate or copy the mesh. This establishes edge connectivity, not the absence
- * of geometric self-intersections between faces.
+ * Closed validation requires exactly two oppositely directed uses per edge, rejecting boundary
+ * and non-manifold edges. It establishes edge connectivity without detecting geometric
+ * self-intersections between faces. The mesh is neither mutated nor copied.
  *
  * @param mesh - Mesh to inspect.
  * @param options - Empty-mesh, topology, and tolerance policy.

package/dist/geometry/paths/closest-point.js

@@ -0,0 +1,74 @@
+import { GeometryError } from "../errors.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+export function closestPointOnPath(path, point, options = {}) {
+    const fail = (message, code = "INVALID_ARGUMENT") => {
+        throw new GeometryError(code, message, { operation: "closestPointOnPath" });
+    };
+    const dimensions = point.length;
+    const closed = options.closed ?? false;
+    if (typeof closed !== "boolean" || (dimensions !== 2 && dimensions !== 3))
+        fail("Use a 2D or 3D point and a boolean closed option.");
+    assertSamplingCount(path.length, "closestPointOnPath", resolveGeometrySamplingLimits(options.limits).maxPathPoints);
+    if (path.length < (closed ? 3 : 2))
+        fail("Open paths need two points; closed paths need three.");
+    const validate = (value) => {
+        if (value.length !== dimensions)
+            fail("Path and query points must have the same dimension.");
+        if (!Number.isFinite(value[0]) ||
+            !Number.isFinite(value[1]) ||
+            (dimensions === 3 && !Number.isFinite(value[2])))
+            fail("Path and query coordinates must be finite.", "NON_FINITE_VALUE");
+    };
+    validate(point);
+    validate(path[0]);
+    let bestDistance = Infinity, bestSquared = Infinity, edgeIndex = 0, fraction = 0;
+    let bestX = 0, bestY = 0, bestZ = 0;
+    const count = closed ? path.length : path.length - 1;
+    for (let i = 0; i < count; i++) {
+        const a = path[i], b = path[(i + 1) % path.length];
+        validate(b);
+        const dx = b[0] - a[0], dy = b[1] - a[1], dz = (b[2] ?? 0) - (a[2] ?? 0);
+        const px = point[0] - a[0], py = point[1] - a[1], pz = (point[2] ?? 0) - (a[2] ?? 0);
+        const lengthSquared = dx * dx + dy * dy + dz * dz;
+        let projection = (px * dx + py * dy + pz * dz) / lengthSquared;
+        if (!Number.isFinite(projection)) {
+            // Normalize only extreme extents; ordinary boundary scans use scalar squared arithmetic.
+            const scale = Math.max(Math.abs(dx), Math.abs(dy), Math.abs(dz));
+            if (!Number.isFinite(scale))
+                fail("Path extent exceeds finite arithmetic.", "NON_FINITE_VALUE");
+            if (scale === 0)
+                projection = 0;
+            else {
+                const ux = dx / scale, uy = dy / scale, uz = dz / scale;
+                const denominator = ux * ux + uy * uy + uz * uz;
+                projection =
+                    (px * (ux / denominator) + py * (uy / denominator) + pz * (uz / denominator)) / scale;
+            }
+        }
+        const t = Math.max(0, Math.min(1, projection));
+        const x = a[0] + t * dx, y = a[1] + t * dy, z = (a[2] ?? 0) + t * dz;
+        const rx = point[0] - x, ry = point[1] - y, rz = (point[2] ?? 0) - z;
+        const squared = rx * rx + ry * ry + rz * rz;
+        if (squared > 0 && Number.isFinite(squared) && squared >= bestSquared)
+            continue;
+        const distance = squared > 0 && Number.isFinite(squared) ? Math.sqrt(squared) : Math.hypot(rx, ry, rz);
+        if (!Number.isFinite(distance))
+            fail("Path distance exceeds finite arithmetic.", "NON_FINITE_VALUE");
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            bestSquared = squared;
+            edgeIndex = i;
+            fraction = t;
+            bestX = x;
+            bestY = y;
+            bestZ = z;
+        }
+    }
+    const position = dimensions === 2 ? [bestX, bestY] : [bestX, bestY, bestZ];
+    return Object.freeze({
+        point: Object.freeze(position),
+        distance: bestDistance,
+        edgeIndex,
+        fraction,
+    });
+}