@metamesh/modeling 0.14.0 → 0.16.0

package/dist/geometry/loft/loft.js

@@ -1,6 +1,7 @@
 import { GeometryError } from "../errors.js";
 import { resolveExtrusionControls, resolveExtrusionDivisions, } from "../extrusion.js";
 import { assertMeshAllocationWithinLimits, resolveModelingLimits } from "../model-limits.js";
+import { capturePath2Input, path2InputData } from "../paths/path-value.js";
 import { assertSamplingCount } from "../sampling-limits.js";
 import { pointLoftProfile, prepareLoftGeometry } from "./loft-geometry.js";
 import {} from "./loft-options.js";
@@ -14,6 +15,7 @@ export { triangulateContour } from "./loft-triangulation.js";
  * 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.
  *
  * @example Loft with explicit point correspondence
  * ```ts
@@ -30,21 +32,27 @@ export function loftMesh(stations, options) {
         throw new GeometryError("INVALID_ARGUMENT", "Loft requires at least two stations.", {
             operation: "loftMesh",
         });
-    const input = stations;
-    assertSamplingCount(input.length, "loftMesh", limits.maxPathPoints);
-    assertSamplingCount(input.reduce((sum, station) => {
-        if (!Array.isArray(station.profile))
-            throw new GeometryError("INVALID_ARGUMENT", "Pure loft profiles must be ordered point arrays.", { operation: "loftMesh" });
-        return sum + station.profile.length;
-    }, 0), "loftMesh", 1_000_000);
-    const profiles = input.map((station) => ({
-        ...station,
-        profile: pointLoftProfile(station.profile),
+    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);
 }
 /**
  * Linearly extrudes one simple profile along +Z with robust ear-clipped caps.
+ * Path2 profiles must be closed; raw point collections have an implicit closing edge.
  *
  * @example Extrude point data without an engine
  * ```ts
@@ -52,9 +60,9 @@ export function loftMesh(stations, options) {
  * extrudeMesh(outline, { height: 8 });
  * ```
  */
-export function extrudeMesh(profile, options) {
+export function extrudeMesh(input, options) {
     const { height } = options;
-    const { center, scales, twistDegrees } = resolveExtrusionControls(height, options, "extrudeMesh");
+    const { center, scales, twist } = resolveExtrusionControls(height, options, "extrudeMesh");
     if (!Number.isFinite(height) || height <= 0) {
         throw new GeometryError("INVALID_ARGUMENT", "Extrusion height must be finite and positive.", {
             operation: "extrudeMesh",
@@ -63,6 +71,7 @@ export function extrudeMesh(profile, options) {
     }
     const bottom = center ? -height / 2 : 0;
     const limits = resolveModelingLimits(options.limits);
+    const profile = path2InputData(input, true, { maxPathPoints: limits.maxProfilePoints }).points;
     assertSamplingCount(profile.length, "extrudeMesh", limits.maxProfilePoints);
     const divisions = resolveExtrusionDivisions(profile, height, options);
     const count = profile.length * (divisions + 2);
@@ -76,7 +85,7 @@ export function extrudeMesh(profile, options) {
     });
     const stations = Array.from({ length: divisions + 2 }, (_, index) => {
         const amount = index / (divisions + 1);
-        const angle = ((twistDegrees * Math.PI) / 180) * amount;
+        const angle = ((twist * Math.PI) / 180) * amount;
         const cosine = Math.cos(angle), sine = Math.sin(angle);
         const sx = 1 + (scales[0] - 1) * amount, sy = 1 + (scales[1] - 1) * amount;
         return {

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/6");
+const immutableMath = Symbol.for("@metamesh/modeling/immutable-math/8");
 /**
  * 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/gear-motion.js

@@ -71,12 +71,12 @@ export function measureInternalCylindricalGearPairMotion(spec, options = {}) {
     const ringSpace = sampleInternalCylindricalGearSpaceOutline(spec.driven, options.outline);
     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;
+    const initialRingPhase = pair.driven.toothCount % 2 === 0 ? 0 : pair.driven.angularPitchRadians / 2;
+    const initialDriverPhase = pair.driver.toothCount % 2 === 0 ? 0 : pair.driver.angularPitchRadians / 2;
     let maximumOverlapArea = 0;
     let maximumPhase = initialDriverPhase;
     for (let sample = 0; sample < samples; sample += 1) {
-        const phase = (pair.driver.angularPitch * sample) / samples;
+        const phase = (pair.driver.angularPitchRadians * sample) / samples;
         const driverPhase = initialDriverPhase + phase;
         const drivenPhase = initialRingPhase + phase / pair.ratio;
         const posedDriver = clippingPolygon(transformedLoop(driver, driverPhase));

package/dist/geometry/mechanical/gears.js

@@ -33,22 +33,22 @@ const freezePoints = (points) => {
  * count `z_v = z / cos³(beta)`, so increasing helix angle can reduce the physical tooth count.
  */
 export function minimumCylindricalGearToothCountWithoutUndercut(spec = {}) {
-    const pressureAngleDegrees = finite(spec.pressureAngleDegrees ?? DEFAULT_PRESSURE_ANGLE_DEGREES, "Pressure angle", "minimumCylindricalGearToothCountWithoutUndercut");
-    const helixAngleDegrees = finite(spec.helixAngleDegrees ?? 0, "Helix angle", "minimumCylindricalGearToothCountWithoutUndercut");
-    if (!(pressureAngleDegrees > 0 && pressureAngleDegrees < 45)) {
+    const pressureAngle = finite(spec.pressureAngle ?? DEFAULT_PRESSURE_ANGLE_DEGREES, "Pressure angle", "minimumCylindricalGearToothCountWithoutUndercut");
+    const helixAngle = finite(spec.helixAngle ?? 0, "Helix angle", "minimumCylindricalGearToothCountWithoutUndercut");
+    if (!(pressureAngle > 0 && pressureAngle < 45)) {
         throw new GeometryError("INVALID_ARGUMENT", "Pressure angle must be greater than 0 and less than 45 degrees.", {
             operation: "minimumCylindricalGearToothCountWithoutUndercut",
-            details: { pressureAngleDegrees },
+            details: { pressureAngle },
         });
     }
-    if (!(Math.abs(helixAngleDegrees) < 45)) {
+    if (!(Math.abs(helixAngle) < 45)) {
         throw new GeometryError("INVALID_ARGUMENT", "The absolute helix angle must be less than 45 degrees.", {
             operation: "minimumCylindricalGearToothCountWithoutUndercut",
-            details: { helixAngleDegrees },
+            details: { helixAngle },
         });
     }
-    const pressureAngleRadians = degreesToRadians(pressureAngleDegrees);
-    const helixAngleRadians = degreesToRadians(helixAngleDegrees);
+    const pressureAngleRadians = degreesToRadians(pressureAngle);
+    const helixAngleRadians = degreesToRadians(helixAngle);
     const exact = (2 * Math.cos(helixAngleRadians) ** 3) / Math.sin(pressureAngleRadians) ** 2;
     // Exact boundary cases such as alpha=30° should not round up because of floating-point noise.
     return Math.ceil(exact - Math.max(1, Math.abs(exact)) * 1e-12);
@@ -64,7 +64,7 @@ const resolveSimpleInvoluteProfileFacts = (dimensions, operation) => {
     const halfAngleAtTip = halfAngleAt(dimensions.outsideRadius);
     if (!(startRadius <= dimensions.outsideRadius) ||
         !(halfAngleAtTip > 0) ||
-        !(halfAngleAtStart < dimensions.angularPitch / 2)) {
+        !(halfAngleAtStart < dimensions.angularPitchRadians / 2)) {
         throw new GeometryError("DEGENERATE_GEOMETRY", "The selected tooth proportions cannot form a simple involute outline.", {
             operation,
             details: { halfAngleAtStart, halfAngleAtTip, startRadius },
@@ -73,7 +73,7 @@ const resolveSimpleInvoluteProfileFacts = (dimensions, operation) => {
     return Object.freeze({ halfAngleAt, halfAngleAtStart, halfAngleAtTip, startRadius });
 };
 const internalCylindricalGearSpaceDimensions = (dimensions) => {
-    const circularPitch = dimensions.angularPitch * dimensions.pitchRadius;
+    const circularPitch = dimensions.angularPitchRadians * dimensions.pitchRadius;
     return Object.freeze({
         ...dimensions,
         outsideRadius: dimensions.pitchRadius + dimensions.dedendum,
@@ -90,8 +90,8 @@ const internalCylindricalGearSpaceDimensions = (dimensions) => {
 const resolveCylindricalGearDimensions = (spec, profile) => {
     const toothCount = finite(spec.toothCount, "Tooth count");
     const module = finite(spec.module, "Module");
-    const pressureAngleDegrees = finite(spec.pressureAngleDegrees ?? DEFAULT_PRESSURE_ANGLE_DEGREES, "Pressure angle");
-    const helixAngleDegrees = finite(spec.helixAngleDegrees ?? 0, "Helix angle");
+    const pressureAngle = finite(spec.pressureAngle ?? DEFAULT_PRESSURE_ANGLE_DEGREES, "Pressure angle");
+    const helixAngle = finite(spec.helixAngle ?? 0, "Helix angle");
     const backlash = finite(spec.backlash ?? 0, "Backlash");
     const clearanceFactor = finite(spec.clearanceFactor ?? DEFAULT_CLEARANCE_FACTOR, "Clearance factor");
     if (!Number.isInteger(toothCount) || toothCount < 6 || toothCount > MAXIMUM_TOOTH_COUNT) {
@@ -103,29 +103,29 @@ const resolveCylindricalGearDimensions = (spec, profile) => {
             details: { module },
         });
     }
-    if (!(pressureAngleDegrees > 0 && pressureAngleDegrees < 45)) {
-        throw new GeometryError("INVALID_ARGUMENT", "Pressure angle must be greater than 0 and less than 45 degrees.", { operation: "resolveCylindricalGear", details: { pressureAngleDegrees } });
+    if (!(pressureAngle > 0 && pressureAngle < 45)) {
+        throw new GeometryError("INVALID_ARGUMENT", "Pressure angle must be greater than 0 and less than 45 degrees.", { operation: "resolveCylindricalGear", details: { pressureAngle } });
     }
-    if (!(Math.abs(helixAngleDegrees) < 45)) {
-        throw new GeometryError("INVALID_ARGUMENT", "The absolute helix angle must be less than 45 degrees.", { operation: "resolveCylindricalGear", details: { helixAngleDegrees } });
+    if (!(Math.abs(helixAngle) < 45)) {
+        throw new GeometryError("INVALID_ARGUMENT", "The absolute helix angle must be less than 45 degrees.", { operation: "resolveCylindricalGear", details: { helixAngle } });
     }
     if (backlash < 0 || clearanceFactor < 0) {
         throw new GeometryError("INVALID_ARGUMENT", "Backlash and clearance factor must be non-negative.", { operation: "resolveCylindricalGear" });
     }
-    const pressureAngleRadians = degreesToRadians(pressureAngleDegrees);
-    const helixAngleRadians = degreesToRadians(helixAngleDegrees);
+    const pressureAngleRadians = degreesToRadians(pressureAngle);
+    const helixAngleRadians = degreesToRadians(helixAngle);
     const minimumToothCountWithoutUndercut = minimumCylindricalGearToothCountWithoutUndercut({
-        helixAngleDegrees,
-        pressureAngleDegrees,
+        helixAngle,
+        pressureAngle,
     });
     const virtualToothCount = toothCount / Math.cos(helixAngleRadians) ** 3;
     if (profile === "external" && toothCount < minimumToothCountWithoutUndercut) {
-        throw new GeometryError("INVALID_ARGUMENT", `An unshifted full-depth external involute at ${pressureAngleDegrees}° pressure angle and ${Math.abs(helixAngleDegrees)}° helix angle requires at least ${minimumToothCountWithoutUndercut} teeth to avoid undercut; profile shift is not supported.`, {
+        throw new GeometryError("INVALID_ARGUMENT", `An unshifted full-depth external involute at ${pressureAngle}° pressure angle and ${Math.abs(helixAngle)}° helix angle requires at least ${minimumToothCountWithoutUndercut} teeth to avoid undercut; profile shift is not supported.`, {
             operation: "resolveCylindricalGear",
             details: {
-                helixAngleDegrees,
+                helixAngle,
                 minimumToothCountWithoutUndercut,
-                pressureAngleDegrees,
+                pressureAngle,
                 toothCount,
                 virtualToothCount,
             },
@@ -151,7 +151,7 @@ const resolveCylindricalGearDimensions = (spec, profile) => {
     }
     const dimensions = Object.freeze({
         addendum,
-        angularPitch: (Math.PI * 2) / toothCount,
+        angularPitchRadians: (Math.PI * 2) / toothCount,
         backlash,
         baseRadius: pitchRadius * Math.cos(transversePressureAngleRadians),
         dedendum,
@@ -199,12 +199,12 @@ export function resolveCylindricalGearPair(spec) {
     // separate tip/interference constraints are checked by the pair and coupled-motion validators.
     const driven = resolveCylindricalGearDimensions(spec.driven, spec.mesh);
     const epsilon = 1e-10;
-    const driverHelixDegrees = spec.driver.helixAngleDegrees ?? 0;
-    const drivenHelixDegrees = spec.driven.helixAngleDegrees ?? 0;
-    const requiredDrivenHelixAngleDegrees = spec.mesh === "external" ? -driverHelixDegrees : driverHelixDegrees;
+    const driverHelixDegrees = spec.driver.helixAngle ?? 0;
+    const drivenHelixDegrees = spec.driven.helixAngle ?? 0;
+    const requiredDrivenHelixAngle = spec.mesh === "external" ? -driverHelixDegrees : driverHelixDegrees;
     if (Math.abs(driver.module - driven.module) > epsilon ||
         Math.abs(driver.pressureAngleRadians - driven.pressureAngleRadians) > epsilon ||
-        Math.abs(drivenHelixDegrees - requiredDrivenHelixAngleDegrees) > epsilon) {
+        Math.abs(drivenHelixDegrees - requiredDrivenHelixAngle) > epsilon) {
         throw new GeometryError("INVALID_ARGUMENT", "Mating gears must share normal module and pressure angle with conjugate helix hands.", { operation: "resolveCylindricalGearPair" });
     }
     if (spec.mesh === "internal" && driven.pitchRadius <= driver.outsideRadius) {
@@ -218,7 +218,7 @@ export function resolveCylindricalGearPair(spec) {
         driven,
         drivenDirection: spec.mesh === "external" ? -1 : 1,
         ratio: driven.toothCount / driver.toothCount,
-        requiredDrivenHelixAngleDegrees,
+        requiredDrivenHelixAngle,
     });
 }
 const exactSampleCount = (value, label, minimum, maximum, operation) => {
@@ -345,7 +345,7 @@ const sampleResolvedCylindricalGearOutline = (dimensions, options, operation) =>
     const { halfAngleAt, halfAngleAtStart, halfAngleAtTip, startRadius } = resolveSimpleInvoluteProfileFacts(dimensions, operation);
     const limits = resolveGeometrySamplingLimits(options.limits);
     const resolution = resolveGeometryResolution(options.resolution, limits);
-    const rootArcAngle = dimensions.angularPitch / 2 - halfAngleAtStart;
+    const rootArcAngle = dimensions.angularPitchRadians / 2 - halfAngleAtStart;
     const rootArcSamples = options.rootArcSamples === undefined
         ? resolveAdaptiveArcSamples(dimensions.rootRadius, rootArcAngle, resolution, limits)
         : exactSampleCount(options.rootArcSamples, "Root arc samples", 1, limits.maxCircularSegments, operation);
@@ -361,10 +361,12 @@ const sampleResolvedCylindricalGearOutline = (dimensions, options, operation) =>
         : exactSampleCount(options.flankSamples, "Flank samples", 2, maximumFlankSamples, operation);
     const estimatedPoints = dimensions.toothCount * (flankSamples * 2 + fixedPerTooth);
     assertSamplingCount(estimatedPoints, operation, limits.maxProfilePoints);
-    const points = [polarPoint(dimensions.rootRadius, -dimensions.angularPitch / 2)];
+    const points = [
+        polarPoint(dimensions.rootRadius, -dimensions.angularPitchRadians / 2),
+    ];
     for (let tooth = 0; tooth < dimensions.toothCount; tooth += 1) {
-        const centerAngle = tooth * dimensions.angularPitch;
-        const valleyBefore = centerAngle - dimensions.angularPitch / 2;
+        const centerAngle = tooth * dimensions.angularPitchRadians;
+        const valleyBefore = centerAngle - dimensions.angularPitchRadians / 2;
         const leftRootAngle = centerAngle - halfAngleAtStart;
         for (let sample = 1; sample <= rootArcSamples; sample += 1) {
             const amount = sample / rootArcSamples;
@@ -391,7 +393,7 @@ const sampleResolvedCylindricalGearOutline = (dimensions, options, operation) =>
         if (startRadius > dimensions.rootRadius) {
             points.push(polarPoint(dimensions.rootRadius, rightRootAngle));
         }
-        const valleyAfter = centerAngle + dimensions.angularPitch / 2;
+        const valleyAfter = centerAngle + dimensions.angularPitchRadians / 2;
         for (let sample = 1; sample <= rootArcSamples; sample += 1) {
             const amount = sample / rootArcSamples;
             points.push(polarPoint(dimensions.rootRadius, rightRootAngle + (valleyAfter - rightRootAngle) * amount));
@@ -431,11 +433,9 @@ export function resolveRackPitch(spec) {
     const reference = resolveCylindricalGear({
         ...(spec.backlash === undefined ? {} : { backlash: spec.backlash }),
         ...(spec.clearanceFactor === undefined ? {} : { clearanceFactor: spec.clearanceFactor }),
-        ...(spec.helixAngleDegrees === undefined ? {} : { helixAngleDegrees: spec.helixAngleDegrees }),
+        ...(spec.helixAngle === undefined ? {} : { helixAngle: spec.helixAngle }),
         module: spec.module,
-        ...(spec.pressureAngleDegrees === undefined
-            ? {}
-            : { pressureAngleDegrees: spec.pressureAngleDegrees }),
+        ...(spec.pressureAngle === undefined ? {} : { pressureAngle: spec.pressureAngle }),
         // Rack pitch facts do not depend on this cylindrical reference count. Use the maximum so the
         // reference remains undercut-free for every supported normal pressure and helix angle.
         toothCount: MAXIMUM_TOOTH_COUNT,

package/dist/geometry/mechanical/index.js

@@ -5,9 +5,10 @@
  */
 export { minimumCylindricalGearToothCountWithoutUndercut, resolveCylindricalGear, resolveCylindricalGearPair, resolveRackPitch, sampleCylindricalGearOutline, sampleInternalCylindricalGearSpaceOutline, sampleRackToothPath, } from "./gears.js";
 export { measureInternalCylindricalGearPairMotion } from "./gear-motion.js";
-export { buildHelicalThreadRidgeMesh, buildHelicalThreadSolidMesh } from "./thread-mesh.js";
-export { compensateThreadProfileAxially, compensateThreadProfileForFaceting, createThreadProfile, } from "./thread-profiles.js";
+export { helicalThreadRidgeMesh, helicalThreadSolidMesh } from "./thread-mesh.js";
+export { compensateThreadProfileAxially, compensateThreadProfileForFaceting, threadProfile, } from "./thread-profiles.js";
 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 { getMetricClearanceHole, getMetricFastenerStandard, METRIC_FASTENER_STANDARDS, } from "./standards.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/standards.js

@@ -50,7 +50,7 @@ export function getMetricFastenerStandard(size) {
     return METRIC_FASTENER_STANDARDS[size];
 }
 /** Returns one recommended metric clearance-hole diameter in millimetres. */
-export function getMetricClearanceHole(size, fit = "normal") {
+export function getMetricClearanceHoleDiameter(size, fit = "normal") {
     const holes = getMetricFastenerStandard(size).clearanceHoles;
     const diameter = fit === "close"
         ? holes.close

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

@@ -29,10 +29,9 @@ export function sampleConventionalThreadHelices(options) {
     const count = Math.max(1, Math.ceil(turns * density));
     assertSamplingCount(starts * (count + 1), operation, resolveGeometrySamplingLimits(options.limits).maxPathPoints);
     const direction = handedness === "right" ? 1 : -1;
-    const phase = assertFiniteThreadNumber((assertFiniteThreadNumber(options.phaseDegrees ?? 0, "phaseDegrees", operation) * Math.PI) /
-        180, "phase", operation);
+    const phaseRadians = assertFiniteThreadNumber((assertFiniteThreadNumber(options.phase ?? 0, "phase", operation) * Math.PI) / 180, "phase", operation);
     const paths = Object.freeze(Array.from({ length: starts }, (_, start) => {
-        const initial = phase + (direction * 2 * Math.PI * start) / starts;
+        const initial = phaseRadians + (direction * 2 * Math.PI * start) / starts;
         return Object.freeze(Array.from({ length: count + 1 }, (_, index) => {
             const t = index / count;
             const z = length * t;

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

@@ -133,9 +133,9 @@ export const resolveHelicalThreadMeshOptions = (options, operation, circularSamp
         throw new GeometryError("INVALID_ARGUMENT", "Exact circularSegments must be divisible by the requested thread starts.", { operation, details: { circularSegments: base, starts } });
     }
     const segments = Math.ceil(base / starts) * starts;
-    const maximumSegments = resolution.maximumSegments;
-    if (segments > maximumSegments) {
-        throw new GeometryError("COMPLEXITY_LIMIT", "Start-aligned thread tessellation exceeds the configured segment safety limit.", { operation, details: { maximumSegments, segments } });
+    const maxSegments = resolution.maxSegments;
+    if (segments > maxSegments) {
+        throw new GeometryError("COMPLEXITY_LIMIT", "Start-aligned thread tessellation exceeds the configured segment safety limit.", { operation, details: { maxSegments, segments } });
     }
     const handedness = options.handedness ?? "right";
     if (handedness !== "left" && handedness !== "right")
@@ -199,8 +199,7 @@ export const resolveHelicalThreadMeshOptions = (options, operation, circularSamp
         leadInLength,
         leadInShape,
         length,
-        phase: (assertFiniteThreadNumber(options.phaseDegrees ?? 0, "phaseDegrees", operation) * Math.PI) /
-            180,
+        phase: (assertFiniteThreadNumber(options.phase ?? 0, "phase", operation) * Math.PI) / 180,
         section,
         segments,
         starts,
@@ -349,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-mesh.js

@@ -1,6 +1,6 @@
 /** Closed ridge and complete-solid mesh construction from resolved thread plans. */
 import { triangulateContour } from "../loft/loft.js";
-import { joinTriangleMeshes, measureTriangleMesh, reverseTriangleMesh, validateTriangleMesh, } from "../mesh/mesh.js";
+import { analyzeTriangleMesh, joinTriangleMeshes, 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";
@@ -61,7 +61,7 @@ const buildThreadRidgeComponent = (options) => {
         indices: new Uint32Array(indices),
     };
     validateTriangleMesh(mesh, { requireClosed: true });
-    if (measureTriangleMesh(mesh, { requireClosed: true }).signedVolume < 0)
+    if (analyzeTriangleMesh(mesh, { requireClosed: true }).signedVolume < 0)
         mesh = reverseTriangleMesh(mesh);
     return mesh;
 };
@@ -74,8 +74,8 @@ const buildThreadRidgeComponent = (options) => {
  * conservative pre-allocation estimate rejects excessive meshes before constructing position
  * arrays.
  */
-export function buildHelicalThreadSolidMesh(options) {
-    const operation = "buildHelicalThreadSolidMesh";
+export function helicalThreadSolidMesh(options) {
+    const operation = "helicalThreadSolidMesh";
     const { maximumAxialSegmentLength, resolved } = resolveHelicalThreadSolidMeshPreflight(options, operation);
     const positions = [];
     const columns = Array.from({ length: resolved.segments }, (_, column) => buildThreadSurfaceColumn(options.profile, resolved, options, resolved.phase + (column * 2 * Math.PI) / resolved.segments, maximumAxialSegmentLength, positions));
@@ -103,7 +103,7 @@ export function buildHelicalThreadSolidMesh(options) {
         indices: new Uint32Array(indices),
     };
     validateTriangleMesh(mesh, { requireClosed: true });
-    if (measureTriangleMesh(mesh, { requireClosed: true }).signedVolume < 0) {
+    if (analyzeTriangleMesh(mesh, { requireClosed: true }).signedVolume < 0) {
         mesh = reverseTriangleMesh(mesh);
     }
     return mesh;
@@ -113,8 +113,8 @@ export function buildHelicalThreadSolidMesh(options) {
  * shaft's radial/axial frame. The mesh is intended for union with its
  * minor-envelope cylinder and never owns WASM objects.
  */
-export function buildHelicalThreadRidgeMesh(options) {
-    const operation = "buildHelicalThreadRidgeMesh";
+export function helicalThreadRidgeMesh(options) {
+    const operation = "helicalThreadRidgeMesh";
     const resolved = resolveHelicalThreadMeshOptions(options, operation);
     const z0 = resolved.bottomBoundary - resolved.section[0][0];
     const z1 = resolved.topBoundary - resolved.section.at(-1)[0];

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

@@ -237,11 +237,11 @@ const standardProfile = (kind, pitch, depth, root, crest, leftRun, rightRun) =>
  *
  * @example Printable triangular thread profile
  * ```ts
- * createThreadProfile({ kind: "triangular", pitch: 1.75 });
+ * threadProfile({ kind: "triangular", pitch: 1.75 });
  * ```
  */
-export function createThreadProfile(spec) {
-    const operation = "createThreadProfile";
+export function threadProfile(spec) {
+    const operation = "threadProfile";
     const pitch = assertFiniteThreadNumber(spec.pitch, "pitch", operation);
     const tolerance = resolveGeometryTolerance(Math.abs(pitch), spec.tolerance);
     if (!(pitch > tolerance.linear))
@@ -358,9 +358,9 @@ export function createThreadProfile(spec) {
     }
     const includedAngle = spec.kind === "acme"
         ? 29
-        : assertFiniteThreadNumber(spec.threadAngle ?? 30, "threadAngle", operation);
+        : assertFiniteThreadNumber(spec.includedAngle ?? 30, "includedAngle", operation);
     if (includedAngle < 0 || includedAngle >= 180) {
-        throw new GeometryError("INVALID_ARGUMENT", "threadAngle must be at least 0 degrees and below 180 degrees.", { operation });
+        throw new GeometryError("INVALID_ARGUMENT", "includedAngle must be at least 0 degrees and below 180 degrees.", { operation });
     }
     const halfIncludedAngle = includedAngle / 2;
     const flankRun = depth * (halfIncludedAngle === 45 ? 1 : Math.tan((halfIncludedAngle * Math.PI) / 180));