@metamesh/modeling 0.15.0 → 0.16.0

package/dist/engine/knuckle-hinge-operation.js

@@ -0,0 +1,85 @@
+import { GeometryError } from "../geometry/errors.js";
+import { resolveKnuckleHinge } from "../geometry/mechanical/knuckle-hinge.js";
+import { assertPrimitiveOptions } from "../geometry/primitive-resolvers.js";
+import { assertSamplingCount } from "../geometry/sampling-limits.js";
+/** Composes existing scoped operations after resolving both halves against one host policy. */
+export function createKnuckleHingeOperation(environment, operations) {
+    return (options) => {
+        environment.assertActive();
+        assertPrimitiveOptions(options, "knuckleHinge");
+        const resolved = environment.withResolutionDefaults(options);
+        const d = resolveKnuckleHinge(options, resolved);
+        assertSamplingCount(d.segments * d.spec.knuckleCount * 2, "knuckleHinge", resolved.limits.maxVertices);
+        const invalid = (message) => {
+            throw new GeometryError("INVALID_ARGUMENT", message, { operation: "knuckleHinge" });
+        };
+        const validateHalf = (half = {}) => {
+            assertPrimitiveOptions(half, "knuckleHinge");
+            const chamfer = half.barrelChamfer ?? 0;
+            if (!Number.isFinite(chamfer) ||
+                chamfer < 0 ||
+                2 * chamfer >= d.knuckleLength ||
+                chamfer >= d.minimumBarrelWall)
+                invalid("barrelChamfer must be nonnegative and leave a positive axial band and faceted barrel wall.");
+            const web = half.web;
+            if (web !== undefined) {
+                assertPrimitiveOptions(web, "knuckleHinge");
+                if (web.direction !== "positive-y" && web.direction !== "negative-y")
+                    invalid("Unknown web direction.");
+                if (!Number.isFinite(web.reach) ||
+                    web.reach <= 0 ||
+                    !Number.isFinite(web.thickness) ||
+                    web.thickness <= 0 ||
+                    !Number.isFinite(web.zMin) ||
+                    !Number.isFinite(web.zMin + web.thickness))
+                    invalid("Web dimensions must be finite, with positive reach and thickness.");
+                const innerRadius = d.barrelRadius * Math.cos(Math.PI / d.segments);
+                if (web.zMin >= innerRadius || web.zMin + web.thickness <= -innerRadius)
+                    invalid("A web must overlap the interior of its barrel.");
+            }
+            return { chamfer, web };
+        };
+        // Validate both attachments before allocating either half.
+        const a = validateHalf(options.halfA);
+        const b = validateHalf(options.halfB);
+        const axial = (radius, start, length, bore = false, chamfer = 0) => operations.translate(operations.rotate(operations.cylinder({
+            radius,
+            height: length,
+            center: false,
+            segments: d.segments,
+            sizing: bore ? "face" : "vertex",
+            ...(chamfer === 0
+                ? {}
+                : {
+                    ends: {
+                        bottom: { kind: "chamfer", distance: chamfer },
+                        top: { kind: "chamfer", distance: chamfer },
+                    },
+                }),
+        }), [0, 90, 0]), [start, 0, 0]);
+        const buildHalf = (side, { chamfer, web }) => {
+            const features = [];
+            for (const interval of d.knuckles) {
+                if (interval.side !== side)
+                    continue;
+                features.push(axial(d.barrelRadius, interval.start, interval.length, false, chamfer));
+                if (web !== undefined)
+                    features.push(operations.translate(operations.box({
+                        size: [interval.length, web.reach, web.thickness],
+                        center: false,
+                    }), [interval.start, web.direction === "positive-y" ? 0 : -web.reach, web.zMin]));
+            }
+            if (side === "a" && d.pin !== null)
+                features.push(axial(d.pinRadius, d.pin.start, d.pin.length));
+            const solid = operations.union(features);
+            // Overtravel is numerical cutter extent, independent of the physical radial/axial allowances.
+            const overtravel = Math.min(d.knuckleLength, d.barrelRadius) * 0.01;
+            return side === "a" && d.pin !== null
+                ? solid
+                : operations.subtract(solid, [
+                    axial(d.boreRadius, -d.spec.length / 2 - overtravel, d.spec.length + 2 * overtravel, true),
+                ]);
+        };
+        return Object.freeze({ halfA: buildHalf("a", a), halfB: buildHalf("b", b), axis: d.axis });
+    };
+}

package/dist/engine/loft-operations.js

@@ -8,7 +8,7 @@ import { assertSamplingCount } from "../geometry/sampling-limits.js";
 import { correspondingPrimitiveProfiles, rectangularPrimitiveFamily, } from "./primitive-profiles.js";
 import { buildProfileLoftMesh } from "./profile-mesh.js";
 const explicitProfile = (value) => typeof value === "object" && value !== null && "components" in value;
-const pointProfile = (value) => Array.isArray(value) || (typeof value === "object" && value !== null && "toArray" in value);
+const pointProfile = (value) => Array.isArray(value) || (typeof value === "object" && value !== null && "toData" in value);
 const fail = (message) => {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: "loft" });
 };

package/dist/engine/mechanical-operations.js

@@ -1,6 +1,7 @@
+import { createKnuckleHingeOperation } from "./knuckle-hinge-operation.js";
 import * as kernel from "./native/index.js";
 /** Internal host-bound mechanical operations. */
-export function createMechanicalOperations(environment) {
+export function createMechanicalOperations(environment, construction) {
     const { resolution } = environment;
     const { scope, assertActive, wrapSolid, withResolutionDefaults } = environment;
     const nutOptions = (value) => ({
@@ -9,6 +10,7 @@ export function createMechanicalOperations(environment) {
     });
     // Explicit preflight preserves the stable error operation names exposed by these constructors.
     const operations = {
+        knuckleHinge: createKnuckleHingeOperation(environment, construction),
         threadRidge: (value) => {
             assertActive();
             return wrapSolid(kernel.threadRidge(scope, withResolutionDefaults(value)));

package/dist/engine/modeling-context.js

@@ -15,7 +15,14 @@ export function createModelingContext(owner, initialResolution) {
         const sections = createSectionOperations(environment, transforms);
         const primitives = createPrimitiveOperations(environment, transforms, sections);
         const construction = createConstructionOperations(environment, sections);
-        const mechanical = createMechanicalOperations(environment);
+        const mechanical = createMechanicalOperations(environment, {
+            cylinder: primitives.cylinder,
+            box: primitives.box,
+            union: construction.union,
+            rotate: transforms.operations.rotate,
+            translate: transforms.operations.translate,
+            subtract: construction.subtract,
+        });
         const patterns = createPatternOperations(environment, transforms);
         const inspection = createInspectionOperations(environment);
         return Object.freeze({

package/dist/engine/recipe-realization.js

@@ -36,7 +36,7 @@ export class RecipeRealization {
         const args = this.resolveValue(call.args, true);
         return this.duringNative(() => Reflect.apply(operation, undefined, args));
     }
-    /** Split/component handles share one operation result, even when selected separately. */
+    /** Joint/split/component handles share one operation result, even when selected separately. */
     evaluate(call) {
         if (!this.resolvedCalls.has(call))
             this.resolvedCalls.set(call, this.invoke(call));
@@ -76,7 +76,9 @@ export class RecipeRealization {
             return retained;
         }
         const result = this.evaluate(recipe.call);
-        const selected = recipe.index === undefined ? result : result[recipe.index];
+        const selected = recipe.index === undefined
+            ? result
+            : result[recipe.index];
         this.realized.set(shape, selected);
         return selected;
     }

package/dist/engine/section-operations.js

@@ -43,7 +43,7 @@ export function createSectionOperations(environment, transforms) {
         polygon: (input) => {
             assertActive();
             if (Array.isArray(input) ||
-                (typeof input === "object" && input !== null && "toArray" in input))
+                (typeof input === "object" && input !== null && ("toData" in input || "dimension" in input)))
                 return fromContours([input]);
             if (typeof input !== "object" || input === null)
                 throwGeometryError("INVALID_ARGUMENT", "polygon", "Use an outline or polygon options.");

package/dist/engine/transform-operations.js

@@ -1,8 +1,8 @@
 import { attachmentTransform3 } from "../geometry/anchors.js";
 import { vector2Data, vector3Data, } from "../geometry/math/vector-value.js";
 import { assertPrimitiveOptions } from "../geometry/primitive-resolvers.js";
-import { transform2, transform3, } from "../geometry/transform-chain.js";
 import { readTransformMatrix } from "../geometry/transform-matrix.js";
+import { transform2, transform3, } from "../geometry/transform-value.js";
 import { eulerTransform3, scaleTransform3, translationTransform3, validateTransform3, } from "../geometry/transform3.js";
 import * as kernel from "./native/index.js";
 import { transformPrimitiveSectionProfile } from "./primitive-profiles.js";
@@ -160,8 +160,8 @@ export function createTransformOperations(environment) {
     const transform = ((value, placement) => {
         const native = resolveHandle(value);
         const matrix = native.kind === "solid"
-            ? transform3(readTransformMatrix(placement, 3)).toMatrix()
-            : transform2(readTransformMatrix(placement, 2)).toMatrix();
+            ? transform3(readTransformMatrix(placement, 3)).toData()
+            : transform2(readTransformMatrix(placement, 2)).toData();
         if (native.kind === "solid") {
             validateCoordinates(matrix, 16, "transform");
             return environment.preserveAnchors(value, wrapSolid(kernel.transform(scope, native.value, matrix)), matrix);

package/dist/geometry/bounds-value.js

@@ -0,0 +1,93 @@
+import { boundsCenter, boundsSize, containsBounds, validateBounds } from "./bounds.js";
+import { GeometryError } from "./errors.js";
+import { immutableMathClass } from "./math/immutable-value.js";
+import { vector2, vector3 } from "./math/vector-value.js";
+function fail(dimension, message) {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation: `bounds${dimension}` });
+}
+function snapshot(input, dimension) {
+    if (typeof input !== "object" || input === null)
+        fail(dimension, "Bounds require minimum and maximum coordinate tuples.");
+    const { min, max } = input;
+    if (!Array.isArray(min) ||
+        !Array.isArray(max) ||
+        min.length !== dimension ||
+        max.length !== dimension)
+        fail(dimension, `Bounds require matching ${dimension}D minimum and maximum tuples.`);
+    const minimum = min, maximum = max;
+    const copy = (source) => Object.freeze(Array.from({ length: dimension }, (_, axis) => {
+        const value = source[axis];
+        return value === 0 ? 0 : value;
+    }));
+    const data = Object.freeze({ min: copy(minimum), max: copy(maximum) });
+    validateBounds(data, `bounds${dimension}`);
+    return data;
+}
+const PlanarBounds = /* @__PURE__ */ immutableMathClass(class PlanarBounds {
+    #data;
+    min;
+    max;
+    constructor(data) {
+        this.#data = data;
+        this.min = data.min;
+        this.max = data.max;
+        Object.freeze(this);
+    }
+    size() {
+        return vector2(boundsSize(this));
+    }
+    center() {
+        return vector2(boundsCenter(this));
+    }
+    containsBounds(other) {
+        return containsBounds(this, other);
+    }
+    toData() {
+        return this.#data;
+    }
+});
+const SpatialBounds = /* @__PURE__ */ immutableMathClass(class SpatialBounds {
+    #data;
+    min;
+    max;
+    constructor(data) {
+        this.#data = data;
+        this.min = data.min;
+        this.max = data.max;
+        Object.freeze(this);
+    }
+    size() {
+        return vector3(boundsSize(this));
+    }
+    center() {
+        return vector3(boundsCenter(this));
+    }
+    containsBounds(other) {
+        return containsBounds(this, other);
+    }
+    toData() {
+        return this.#data;
+    }
+});
+/**
+ * Snapshots finite ordered XY bounds in millimetres as an immutable fluent value.
+ *
+ * Zero extents are valid. Invalid dimensions, nonfinite coordinates, reversed bounds and
+ * overflowing extents throw `INVALID_ARGUMENT` GeometryError. Use `toData()` for plain records.
+ * Compiled Generator packages passing these values to host recipes or computed data require
+ * runtime 8.0.0 or newer in major 8.
+ */
+export function bounds2(input) {
+    return new PlanarBounds(snapshot(input, 2));
+}
+/**
+ * Snapshots finite ordered XYZ bounds in millimetres as an immutable fluent value.
+ *
+ * Zero extents are valid. Invalid dimensions, nonfinite coordinates, reversed bounds and
+ * overflowing extents throw `INVALID_ARGUMENT` GeometryError. Use `toData()` for plain records.
+ * Compiled Generator packages passing these values to host recipes or computed data require
+ * runtime 8.0.0 or newer in major 8.
+ */
+export function bounds3(input) {
+    return new SpatialBounds(snapshot(input, 3));
+}

package/dist/geometry/bounds.js

@@ -13,7 +13,8 @@ function vector(values, operation) {
         ? Object.freeze([normalized[0], normalized[1]])
         : Object.freeze([normalized[0], normalized[1], normalized[2]]);
 }
-function validate(bounds, operation) {
+/** Internal shared validation for tuple algorithms and immutable bounds snapshots. */
+export function validateBounds(bounds, operation) {
     if (typeof bounds !== "object" ||
         bounds === null ||
         !isArray(bounds.min) ||
@@ -54,23 +55,23 @@ export function boundsFromSize(dimensions, options = {}) {
     });
 }
 export function boundsSize(bounds) {
-    validate(bounds, "boundsSize");
+    validateBounds(bounds, "boundsSize");
     return vector(size(bounds), "boundsSize");
 }
 export function boundsCenter(bounds) {
-    validate(bounds, "boundsCenter");
+    validateBounds(bounds, "boundsCenter");
     return vector(center(bounds), "boundsCenter");
 }
 export function containsBounds(outer, inner) {
-    const dimension = validate(outer, "containsBounds");
-    if (validate(inner, "containsBounds") !== dimension)
+    const dimension = validateBounds(outer, "containsBounds");
+    if (validateBounds(inner, "containsBounds") !== dimension)
         fail("containsBounds", "Contained bounds must have the same dimension.");
     return outer.min.every((value, axis) => inner.min[axis] >= value && inner.max[axis] <= outer.max[axis]);
 }
 export function fitBounds(source, target, options = {}) {
     const operation = "fitBounds";
-    const dimension = validate(source, operation);
-    if (validate(target, operation) !== dimension)
+    const dimension = validateBounds(source, operation);
+    if (validateBounds(target, operation) !== dimension)
         fail(operation, "Source and target bounds must have the same dimension.");
     if (typeof options !== "object" || options === null || isArray(options))
         fail(operation, "Fitting options must be an object.");
@@ -94,6 +95,7 @@ export function fitBounds(source, target, options = {}) {
 }
 /**
  * Returns immutable translations for a +X row of finite XYZ bounds with a nonnegative gap.
+ *
  * Each minimum Y/Z becomes zero, and the first minimum X becomes zero. Supply bounds after
  * any intended part rotation; translations apply to those bounds. An empty input returns [].
  */
@@ -106,7 +108,7 @@ export function layoutRow(bounds, options = {}) {
         fail(operation, "Row gap must be finite and nonnegative.");
     let nextX = 0;
     return Object.freeze(Array.from(bounds, (item) => {
-        if (validate(item, operation) !== 3)
+        if (validateBounds(item, operation) !== 3)
             fail(operation, "Row layout requires XYZ bounds.");
         const position = vector([nextX - item.min[0], -item.min[1], -item.min[2]], operation);
         nextX += item.max[0] - item.min[0] + gap;

package/dist/geometry/curves/sampling.js

@@ -237,8 +237,7 @@ export function sampleCurve3(curve, options = {}) {
     return sampleCurve(curve, options, createSpatialSampleWriter);
 }
 /** Samples a planar curve with the same guarantees and policy as spatial sampling.
- * @remarks Private spatial scratch math is shared, while only final planar vectors are copied and
- * frozen. At stationary tangents, outgoing secants are preferred and endpoints use a backward fallback.
+ * @remarks Returned planar points and tangents are copied and frozen. At stationary tangents, outgoing secants are preferred and endpoints use a backward fallback.
  * @example
  * ```ts
  * const turn = sampleCurve2({kind: "arc", center: [0,0], radius: 10, sweepAngle: 90});

package/dist/geometry/errors.js

@@ -50,6 +50,7 @@ export class GeometryError extends Error {
 }
 /**
  * Recognizes structured geometry errors from separately bundled Modeling copies in the same realm.
+ *
  * Ordinary errors and unmarked code-shaped objects are rejected. The marker is execution-local and
  * does not survive structured cloning; worker protocols carry their own serialized error envelope.
  */

package/dist/geometry/heightfield.js

@@ -77,16 +77,27 @@ function planHeightfield(options, limits) {
         facts: Object.freeze({ sampleCount, vertexCount, triangleCount, byteCount }),
     };
 }
-/** Checks grid dimensions, coordinate precision, and allocation bounds before evaluating heights. */
+/**
+ * Checks grid options, Float32 axis precision, and output limits; returns exact mesh buffer counts.
+ *
+ * This pure operation needs no engine and neither evaluates `height` nor allocates mesh buffers.
+ * Successful preflight leaves height values, Float32 base storage, and generated mesh validity to
+ * construction. `byteCount` covers position and index buffers, not total working memory.
+ *
+ * @see {@link heightfieldMesh}
+ */
 export function preflightHeightfield(options, limits = {}) {
     return planHeightfield(options, limits).facts;
 }
 /**
  * Builds a closed indexed mesh from a rectilinear top, matched boundary walls, and flat base.
+ *
  * Heights run once per grid point after preflight; center-error adds one evaluation per cell.
  * Top winding is +Z, the base is -Z, and sides face outward. Coordinates and heights must fit
  * Float32 storage. Explicit axes are captured before sampling; shared wall vertices prevent cracks.
  *
+ * @see {@link preflightHeightfield}
+ *
  * @example Sample a closed wavy mesh
  * ```ts
  * heightfieldMesh({

package/dist/geometry/index.js

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

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

@@ -1,5 +1,5 @@
 // A versioned realm protocol lets separately bundled authoring values cross the host boundary.
-const immutableMath = Symbol.for("@metamesh/modeling/immutable-math/7");
+const immutableMath = Symbol.for("@metamesh/modeling/immutable-math/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/index.js

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

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

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

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

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