@metamesh/modeling 0.0.0-stage → 0.7.0

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

@@ -0,0 +1,433 @@
+/** Periodic surface columns and their phase-aware zipper stitching. */
+import { cross3, dot3, length3, subtract3 } from "../math/vector3.js";
+import { applyThreadSurfaceBevel, requirePositiveThreadSurfaceRadius, threadSurfaceBevelBoundaryAt, } from "./thread-mesh-plan.js";
+const threadLeadInScale = (progress, shape, leadInLength) => {
+    if (shape === "cut")
+        return progress > 0 ? { height: 1, width: 1 } : { height: 0, width: 1 };
+    if (progress <= 0)
+        return { height: 0, width: shape === "linear" ? 0.325 : 0.2875 };
+    if (progress > 1)
+        return { height: 1, width: 1 };
+    if (shape === "linear") {
+        const scale = 0.1 + 0.9 * progress;
+        return { height: scale, width: 0.75 * scale + 0.25 };
+    }
+    if (shape === "smooth") {
+        const radius = (leadInLength * leadInLength + (1 - 0.05 * 0.05)) / (2 * (1 - 0.05));
+        const scale = Math.sqrt(radius * radius - (leadInLength * (1 - progress)) ** 2) - (radius - 1);
+        return { height: scale, width: 0.75 * scale + 0.25 };
+    }
+    const scale = Math.sqrt(progress + 0.05 * 0.05 * (1 - progress));
+    return { height: scale, width: 0.75 * scale + 0.25 };
+};
+const threadLeadInScaleAtCenter = (center, resolved) => {
+    if (resolved.leadInShape === "cut" || !(resolved.leadInAxialLength > 0)) {
+        return { height: 1, width: 1 };
+    }
+    const progressFromTip = (distance) => Math.abs(distance) <= resolved.tolerance.linear ? 0 : distance / resolved.leadInAxialLength;
+    const bottom = resolved.bottom === "blunt"
+        ? threadLeadInScale(progressFromTip(center - resolved.bottomLeadTipCenter), resolved.leadInShape, resolved.leadInLength)
+        : { height: 1, width: 1 };
+    const top = resolved.top === "blunt"
+        ? threadLeadInScale(progressFromTip(resolved.topLeadTipCenter - center), resolved.leadInShape, resolved.leadInLength)
+        : { height: 1, width: 1 };
+    return { height: Math.min(bottom.height, top.height), width: Math.min(bottom.width, top.width) };
+};
+const wrappedThreadCoordinate = (value, pitch) => {
+    const wrapped = (((value + pitch / 2) % pitch) + pitch) % pitch;
+    return wrapped - pitch / 2;
+};
+const threadSectionRadialAt = (section, envelopeRadial, coordinate, linearTolerance) => {
+    if (coordinate < section[0][0] - linearTolerance ||
+        coordinate > section.at(-1)[0] + linearTolerance) {
+        return envelopeRadial;
+    }
+    for (let index = 1; index < section.length; index += 1) {
+        const previous = section[index - 1];
+        const next = section[index];
+        if (coordinate > next[0] + linearTolerance)
+            continue;
+        const run = next[0] - previous[0];
+        if (run <= linearTolerance)
+            return Math.max(previous[1], next[1]);
+        const factor = Math.max(0, Math.min(1, (coordinate - previous[0]) / run));
+        return previous[1] + (next[1] - previous[1]) * factor;
+    }
+    return envelopeRadial;
+};
+const periodicThreadSectionRadialAt = (section, envelopeRadial, axial, pitch, linearTolerance) => threadSectionRadialAt(section, envelopeRadial, wrappedThreadCoordinate(axial, pitch), linearTolerance);
+const threadEndFactor = (z, profile, resolved) => {
+    const lower = resolved.bottomBoundary;
+    const upper = resolved.topBoundary;
+    if (z < lower - resolved.tolerance.linear || z > upper + resolved.tolerance.linear)
+        return 0;
+    const bottomFactor = resolved.bottom === "tapered" ? Math.max(0, (z - lower) / profile.depth) : 1;
+    const topFactor = resolved.top === "tapered" ? Math.max(0, (upper - z) / profile.depth) : 1;
+    return Math.max(0, Math.min(1, bottomFactor, topFactor));
+};
+/** @internal Emits one angular column with semantic profile and end stations. */
+export const buildThreadSurfaceColumn = (profile, resolved, options, angle, maximumAxialSegmentLength, positions) => {
+    const rootRadius = resolved.diameter / 2 - profile.depth;
+    const majorRadius = resolved.diameter / 2;
+    const usesMajorEnvelopeSurface = resolved.leadInEnvelope === "major" &&
+        resolved.leadInAxialLength > 0 &&
+        (resolved.bottom === "blunt" || resolved.top === "blunt");
+    const leadInEnvelopeRadial = usesMajorEnvelopeSurface ? 0 : -profile.depth;
+    const leadInEnvelopeRadius = usesMajorEnvelopeSurface ? majorRadius : rootRadius;
+    const phaseShift = resolved.surfacePhaseBase +
+        (resolved.direction * resolved.lead * (angle - resolved.phase)) / (2 * Math.PI);
+    const profileSegmentOrdinalAt = (axial) => {
+        const period = Math.round((axial - phaseShift) / profile.pitch);
+        const localAxial = axial - phaseShift - period * profile.pitch;
+        for (let segment = 0; segment < resolved.surfaceSection.length - 1; segment += 1) {
+            const start = resolved.surfaceSection[segment][0];
+            const end = resolved.surfaceSection[segment + 1][0];
+            if (localAxial < start - resolved.tolerance.linear)
+                continue;
+            if (localAxial > end + resolved.tolerance.linear)
+                continue;
+            return period * resolved.surfaceSection.length + segment + 0.5;
+        }
+        return undefined;
+    };
+    const usesScaledLeadIn = resolved.leadInAxialLength > 0 && (resolved.bottom === "blunt" || resolved.top === "blunt");
+    const bevelOffset = options.bevelOffset ?? 0;
+    const scaledRadiusAt = (axial) => {
+        if ((resolved.bottom !== "standard" && axial < resolved.bottomBoundary) ||
+            (resolved.top !== "standard" && axial > resolved.topBoundary)) {
+            return leadInEnvelopeRadius;
+        }
+        const period = Math.round((axial - phaseShift) / profile.pitch);
+        const center = phaseShift + period * profile.pitch;
+        const scale = threadLeadInScaleAtCenter(center, resolved);
+        const localAxial = (axial - center) / scale.width;
+        const profileRadius = majorRadius +
+            threadSectionRadialAt(resolved.surfaceSection, leadInEnvelopeRadial, localAxial, resolved.tolerance.linear);
+        return leadInEnvelopeRadius + (profileRadius - leadInEnvelopeRadius) * scale.height;
+    };
+    const rawRadiusAt = (sample, axial) => {
+        if (sample.surfaceRadius !== undefined) {
+            return sample.surfaceRadius;
+        }
+        if (usesScaledLeadIn) {
+            return scaledRadiusAt(axial);
+        }
+        const endFactor = sample.endFactor ?? threadEndFactor(axial, profile, resolved);
+        const profileRadius = majorRadius +
+            (sample.profileRadial ??
+                periodicThreadSectionRadialAt(resolved.surfaceSection, leadInEnvelopeRadial, axial - phaseShift, profile.pitch, resolved.tolerance.linear));
+        const radial = leadInEnvelopeRadius + (profileRadius - leadInEnvelopeRadius) * endFactor;
+        return radial;
+    };
+    const radiusAt = (sample, axial) => {
+        return applyThreadSurfaceBevel(rawRadiusAt(sample, axial), axial, profile, resolved, options);
+    };
+    const candidates = [];
+    let order = 0;
+    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({
+            z: Math.max(0, Math.min(resolved.length, z)),
+            kind,
+            order: order++,
+            ...(profileRadial === undefined ? {} : { profileRadial }),
+            ...(endFactor === undefined ? {} : { endFactor }),
+            ...(surfaceRadius === undefined ? {} : { surfaceRadius }),
+            ...(profileOrdinal === undefined ? {} : { profileOrdinal }),
+            ...(atLeadTip ? { atLeadTip: true } : {}),
+        });
+    };
+    add(0);
+    add(resolved.length);
+    const bottomBevelSize = Math.min(options.bevelBottomSize ?? options.bevelSize ?? profile.depth, resolved.length / 2);
+    const topBevelSize = Math.min(options.bevelTopSize ?? options.bevelSize ?? profile.depth, resolved.length / 2);
+    const fixedSamples = [resolved.bottomBoundary, resolved.topBoundary];
+    if (resolved.bottom === "tapered")
+        fixedSamples.push(resolved.bottomBoundary + profile.depth);
+    if (resolved.top === "tapered")
+        fixedSamples.push(resolved.topBoundary - profile.depth);
+    if (options.bevelBottom === true) {
+        fixedSamples.push(bevelOffset, bevelOffset + bottomBevelSize);
+    }
+    if (options.bevelTop === true) {
+        fixedSamples.push(resolved.length - bevelOffset - topBevelSize, resolved.length - bevelOffset);
+    }
+    if (options.bevelBottom === true && options.bevelTop === true) {
+        const bottomBevelEnd = bevelOffset + bottomBevelSize;
+        const topBevelStart = resolved.length - bevelOffset - topBevelSize;
+        if (bottomBevelEnd >= topBevelStart) {
+            fixedSamples.push((bottomBevelEnd + topBevelStart) / 2);
+        }
+    }
+    for (const z of fixedSamples)
+        add(z);
+    const activeMinimum = Math.max(0, resolved.bottomBoundary);
+    const activeMaximum = Math.min(resolved.length, resolved.topBoundary);
+    if (usesScaledLeadIn) {
+        const firstPeriod = Math.floor((activeMinimum - phaseShift) / profile.pitch) - 1;
+        const lastPeriod = Math.ceil((activeMaximum - phaseShift) / profile.pitch) + 1;
+        for (let period = firstPeriod; period <= lastPeriod; period += 1) {
+            const center = phaseShift + period * profile.pitch;
+            const scale = threadLeadInScaleAtCenter(center, resolved);
+            const atBottomTip = resolved.bottom === "blunt" &&
+                Math.abs(center - resolved.bottomLeadTipCenter) <= resolved.tolerance.linear;
+            const atTopTip = resolved.top === "blunt" &&
+                Math.abs(center - resolved.topLeadTipCenter) <= resolved.tolerance.linear;
+            if (scale.height <= resolved.tolerance.linear && !atBottomTip && !atTopTip)
+                continue;
+            // Keep only the exact zero-height, width-scaled tip copy. Its collinear envelope vertices give
+            // the first raised angular column matching profile ordinals to taper into; omitting it makes
+            // the zipper collapse the whole tip into one abrupt fan/wedge. More zero-height copies are
+            // 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);
+            }
+        }
+    }
+    else {
+        for (const [profileIndex, [profileAxial, profileRadial]] of resolved.surfaceSection.entries()) {
+            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);
+            }
+        }
+    }
+    if (resolved.bottom === "blunt" &&
+        !usesScaledLeadIn &&
+        resolved.bottomBoundary > resolved.tolerance.linear &&
+        resolved.bottomBoundary < resolved.length - resolved.tolerance.linear) {
+        add(resolved.bottomBoundary, "forced-bottom", undefined, 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);
+    }
+    candidates.sort((left, right) => left.z - right.z || left.order - right.order);
+    const normalized = [];
+    for (let start = 0; start < candidates.length;) {
+        let end = start + 1;
+        while (end < candidates.length &&
+            Math.abs(candidates[end].z - candidates[start].z) <= resolved.tolerance.linear) {
+            end += 1;
+        }
+        const group = candidates.slice(start, end);
+        const profiles = group.filter((sample) => sample.kind === "profile");
+        const regular = group.find((sample) => sample.kind === "regular");
+        let surfaceSamples = profiles.length > 0 ? profiles : regular === undefined ? [] : [regular];
+        const canonicalZ = group.find((sample) => sample.kind === "forced-bottom" || sample.kind === "forced-top")?.z ??
+            regular?.z ??
+            group[0].z;
+        if (canonicalZ <= resolved.tolerance.linear && surfaceSamples.length > 1) {
+            surfaceSamples = [surfaceSamples.at(-1)];
+        }
+        else if (canonicalZ >= resolved.length - resolved.tolerance.linear &&
+            surfaceSamples.length > 1) {
+            surfaceSamples = [surfaceSamples[0]];
+        }
+        const selected = [
+            ...group.filter((sample) => sample.kind === "forced-bottom"),
+            ...surfaceSamples,
+            ...group.filter((sample) => sample.kind === "forced-top"),
+        ];
+        for (const sample of selected)
+            normalized.push({ ...sample, z: canonicalZ });
+        start = end;
+    }
+    const withBevelIntersections = [];
+    for (let index = 0; index < normalized.length; index += 1) {
+        const sample = normalized[index];
+        withBevelIntersections.push(sample);
+        const next = normalized[index + 1];
+        if (next === undefined || next.z - sample.z <= resolved.tolerance.linear)
+            continue;
+        const firstBoundary = threadSurfaceBevelBoundaryAt(sample.z, profile, resolved, options);
+        const secondBoundary = threadSurfaceBevelBoundaryAt(next.z, profile, resolved, options);
+        if (firstBoundary?.endStyle !== "standard" ||
+            secondBoundary?.endStyle !== "standard" ||
+            firstBoundary.kind !== secondBoundary.kind) {
+            continue;
+        }
+        const firstDelta = rawRadiusAt(sample, sample.z) - firstBoundary.radius;
+        const secondDelta = rawRadiusAt(next, next.z) - secondBoundary.radius;
+        if (!((firstDelta < -resolved.tolerance.linear && secondDelta > resolved.tolerance.linear) ||
+            (firstDelta > resolved.tolerance.linear && secondDelta < -resolved.tolerance.linear))) {
+            continue;
+        }
+        const factor = firstDelta / (firstDelta - secondDelta);
+        const crossingZ = sample.z + (next.z - sample.z) * factor;
+        if (crossingZ - sample.z <= resolved.tolerance.linear ||
+            next.z - crossingZ <= resolved.tolerance.linear) {
+            continue;
+        }
+        const crossingOrdinal = profileSegmentOrdinalAt(crossingZ);
+        withBevelIntersections.push({
+            kind: "regular",
+            order: order++,
+            ...(crossingOrdinal === undefined ? {} : { profileOrdinal: crossingOrdinal }),
+            surfaceRadius: firstBoundary.radius + (secondBoundary.radius - firstBoundary.radius) * factor,
+            z: crossingZ,
+        });
+    }
+    // A fixed standard-bevel station can land microscopically beside a semantic profile or bevel
+    // crossing. Keeping both creates a long, almost-collinear triangle around the circumference even
+    // though the radial difference is equally sub-facet. Preserve the fixed station so every column
+    // still meets the exact bevel-transition ring; favoring the nearby semantic sample instead makes
+    // that ring wander by one sub-facet and produces a visible bump. Faces, blunt transitions,
+    // vertical profile steps, forced boundaries, and pairs of semantic samples remain exact.
+    const stationSnapTolerance = Math.max(resolved.tolerance.linear, resolved.lead / resolved.segments / 16);
+    const isPlainStation = (sample) => sample.kind === "regular" &&
+        sample.profileOrdinal === undefined &&
+        sample.surfaceRadius === undefined;
+    const isCoalescibleStandardBevelStation = (sample) => isPlainStation(sample) &&
+        threadSurfaceBevelBoundaryAt(sample.z, profile, resolved, options)?.endStyle === "standard";
+    const isFace = (sample) => sample.z <= resolved.tolerance.linear ||
+        sample.z >= resolved.length - resolved.tolerance.linear;
+    const coalesced = [];
+    for (const sample of withBevelIntersections) {
+        const previous = coalesced.at(-1);
+        const previousIsPlain = previous !== undefined && isCoalescibleStandardBevelStation(previous);
+        const sampleIsPlain = isCoalescibleStandardBevelStation(sample);
+        const previousIsSemantic = previous !== undefined && !isPlainStation(previous);
+        const sampleIsSemantic = !isPlainStation(sample);
+        if (previous !== undefined &&
+            ((previousIsPlain && sampleIsSemantic) || (sampleIsPlain && previousIsSemantic)) &&
+            !(previousIsPlain ? isFace(previous) : isFace(sample)) &&
+            Math.abs(sample.z - previous.z) <= stationSnapTolerance &&
+            Math.abs(radiusAt(sample, sample.z) - radiusAt(previous, previous.z)) <= stationSnapTolerance) {
+            if (sampleIsPlain)
+                coalesced[coalesced.length - 1] = sample;
+            continue;
+        }
+        coalesced.push(sample);
+    }
+    const sampled = [];
+    for (let index = 0; index < coalesced.length; index += 1) {
+        const sample = coalesced[index];
+        sampled.push(sample);
+        const next = coalesced[index + 1];
+        if (next === undefined || maximumAxialSegmentLength === undefined)
+            continue;
+        const distance = next.z - sample.z;
+        if (distance <= resolved.tolerance.linear)
+            continue;
+        const intervals = Math.ceil(distance / maximumAxialSegmentLength);
+        for (let interval = 1; interval < intervals; interval += 1) {
+            sampled.push({
+                atLeadTip: sample.atLeadTip === true && next.atLeadTip === true,
+                kind: "regular",
+                order: order++,
+                z: sample.z + (distance * interval) / intervals,
+            });
+        }
+    }
+    const indices = [];
+    const leadTips = [];
+    const profileOrdinals = [];
+    const z = [];
+    const cosine = Math.cos(angle);
+    const sine = Math.sin(angle);
+    let previousRadius;
+    let previousStoredX;
+    let previousStoredY;
+    let previousStoredZ;
+    let previousZ;
+    for (const sample of sampled) {
+        const radius = radiusAt(sample, sample.z);
+        requirePositiveThreadSurfaceRadius(radius, resolved, "buildHelicalThreadSolidMesh");
+        if (previousRadius !== undefined &&
+            previousZ !== undefined &&
+            Math.abs(sample.z - previousZ) <= resolved.tolerance.linear &&
+            Math.abs(radius - previousRadius) <= resolved.tolerance.linear) {
+            continue;
+        }
+        // Topology is ultimately stored as Float32. Two double-precision axial samples can be farther
+        // apart than the modeling tolerance yet still become the same stored XYZ point, particularly
+        // where a regular sample lands within one Float32 ULP of a flat-profile breakpoint. Collapse
+        // that pair before stitching; same-Z vertical steps remain because their stored radii differ.
+        const storedX = Math.fround(radius * cosine);
+        const storedY = Math.fround(radius * sine);
+        const storedZ = Math.fround(sample.z);
+        if (storedX === previousStoredX && storedY === previousStoredY && storedZ === previousStoredZ) {
+            continue;
+        }
+        indices.push(positions.length / 3);
+        leadTips.push(sample.atLeadTip === true);
+        profileOrdinals.push(sample.profileOrdinal);
+        z.push(sample.z);
+        positions.push(storedX, storedY, storedZ);
+        previousRadius = radius;
+        previousStoredX = storedX;
+        previousStoredY = storedY;
+        previousStoredZ = storedZ;
+        previousZ = sample.z;
+    }
+    return { indices, leadTips, profileOrdinals, z };
+};
+/** @internal Joins adjacent phase grids while preserving duplicate-Z flank order. */
+export const stitchThreadSurfaceColumns = (first, second, direction, secondProfileOrdinalOffset, linearTolerance, positions, useConcaveLeadTip, indices) => {
+    const positionAt = (index) => {
+        const offset = index * 3;
+        return [positions[offset], positions[offset + 1], positions[offset + 2]];
+    };
+    const usesSecondDiagonal = (i1, i2, i3, i4, isLeadTipQuad) => {
+        if (!useConcaveLeadTip || !isLeadTipQuad)
+            return direction === -1;
+        const [logicalI1, logicalI2, logicalI3, logicalI4] = direction === 1 ? [i1, i2, i3, i4] : [i2, i1, i4, i3];
+        const firstPosition = positionAt(logicalI1);
+        const normal = cross3(subtract3(positionAt(logicalI2), firstPosition), subtract3(positionAt(logicalI3), firstPosition));
+        const normalLength = length3(normal);
+        if (normalLength <= linearTolerance * linearTolerance)
+            return direction === -1;
+        const signedHeight = direction * dot3(normal, subtract3(positionAt(logicalI4), firstPosition));
+        const planeTolerance = linearTolerance * normalLength;
+        // BOSL2 selects the locally concave diagonal for internal threads. Evaluate left-handed quads
+        // in their mirrored logical order, then map that logical diagonal back to our stored
+        // increasing-angle column order.
+        const logicalUsesSecondDiagonal = signedHeight <= planeTolerance;
+        return direction === 1 ? logicalUsesSecondDiagonal : !logicalUsesSecondDiagonal;
+    };
+    const profilesCorrespond = (firstOrdinal, secondOrdinal) => firstOrdinal !== undefined &&
+        secondOrdinal !== undefined &&
+        secondOrdinal === firstOrdinal + secondProfileOrdinalOffset;
+    let firstIndex = 0;
+    let secondIndex = 0;
+    while (firstIndex < first.indices.length - 1 || secondIndex < second.indices.length - 1) {
+        const nextFirst = first.z[firstIndex + 1] ?? Number.POSITIVE_INFINITY;
+        const nextSecond = second.z[secondIndex + 1] ?? Number.POSITIVE_INFINITY;
+        const a = first.indices[firstIndex];
+        const b = second.indices[secondIndex];
+        const currentProfilesCorrespond = profilesCorrespond(first.profileOrdinals[firstIndex], second.profileOrdinals[secondIndex]);
+        const nextProfilesCorrespond = profilesCorrespond(first.profileOrdinals[firstIndex + 1], second.profileOrdinals[secondIndex + 1]);
+        if ((currentProfilesCorrespond && nextProfilesCorrespond) ||
+            Math.abs(nextFirst - nextSecond) <= linearTolerance) {
+            const nextA = first.indices[firstIndex + 1];
+            const nextB = second.indices[secondIndex + 1];
+            const isLeadTipQuad = (first.leadTips[firstIndex] === true && first.leadTips[firstIndex + 1] === true) ||
+                (second.leadTips[secondIndex] === true && second.leadTips[secondIndex + 1] === true);
+            if (usesSecondDiagonal(a, b, nextB, nextA, isLeadTipQuad)) {
+                indices.push(a, b, nextA, b, nextB, nextA);
+            }
+            else {
+                indices.push(a, b, nextB, a, nextB, nextA);
+            }
+            firstIndex += 1;
+            secondIndex += 1;
+        }
+        else if (profilesCorrespond(first.profileOrdinals[firstIndex + 1], second.profileOrdinals[secondIndex]) ||
+            (!profilesCorrespond(first.profileOrdinals[firstIndex], second.profileOrdinals[secondIndex + 1]) &&
+                nextFirst < nextSecond)) {
+            indices.push(a, b, first.indices[firstIndex + 1]);
+            firstIndex += 1;
+        }
+        else {
+            indices.push(a, b, second.indices[secondIndex + 1]);
+            secondIndex += 1;
+        }
+    }
+};

package/dist/geometry/mechanical/threads.js

@@ -0,0 +1,138 @@
+import { GeometryError } from "../errors.js";
+import { resolveCircularSegments, resolveGeometryResolution, } from "../resolution.js";
+import { resolveGeometryTolerance } from "../tolerance.js";
+import { compensateThreadProfileForFaceting } from "./thread-profiles.js";
+const frozenFit = (maleRadialInset, femaleRadialOutset, axialBacklash) => Object.freeze({ axialBacklash, femaleRadialOutset, maleRadialInset });
+/**
+ * Conservative baseline print-fit policies in millimetres.
+ *
+ * These are modeling defaults, not manufacturing guarantees. A caller should
+ * calibrate them for its printer, material, layer height, and thread scale.
+ */
+export const PRINTABLE_THREAD_FIT_POLICIES = Object.freeze({
+    /** Small baseline clearance for calibrated, accurate printers. */
+    tight: frozenFit(0.06, 0.06, 0.05),
+    /** General-purpose baseline clearance. */
+    normal: frozenFit(0.12, 0.12, 0.1),
+    /** Generous baseline clearance for rougher prints or easy assembly. */
+    loose: frozenFit(0.2, 0.2, 0.2),
+});
+const finite = (value, label) => {
+    if (!Number.isFinite(value)) {
+        throw new GeometryError("NON_FINITE_VALUE", `${label} must be finite.`);
+    }
+    return value;
+};
+const validateFitPolicy = (policy) => {
+    const male = finite(policy.maleRadialInset, "Male radial inset");
+    const female = finite(policy.femaleRadialOutset, "Female radial outset");
+    const axial = finite(policy.axialBacklash, "Axial backlash");
+    if (male < 0 || female < 0 || axial < 0) {
+        throw new GeometryError("INVALID_ARGUMENT", "Thread fit allowances must be non-negative.");
+    }
+    return Object.freeze({ axialBacklash: axial, femaleRadialOutset: female, maleRadialInset: male });
+};
+/** Resolves and validates a named or caller-defined print-fit policy. */
+export function resolvePrintableThreadFitPolicy(fit = "normal") {
+    if (typeof fit !== "string")
+        return validateFitPolicy(fit);
+    const policy = PRINTABLE_THREAD_FIT_POLICIES[fit];
+    if (policy === undefined) {
+        throw new GeometryError("INVALID_ARGUMENT", `Unsupported printable thread fit: ${fit}.`);
+    }
+    return policy;
+}
+/**
+ * Applies role-specific radial compensation while preserving thread depth.
+ *
+ * Male envelopes move inward by the policy inset; female envelopes move
+ * outward by the policy outset. Combining both parts produces the sum of those
+ * allowances as radial mating clearance.
+ */
+export function compensateThreadDiameters(options) {
+    const nominalMajorDiameter = finite(options.nominalMajorDiameter, "Nominal major diameter");
+    const threadDepth = finite(options.threadDepth, "Thread depth");
+    const scale = Math.max(Math.abs(nominalMajorDiameter), Math.abs(threadDepth));
+    const tolerance = resolveGeometryTolerance(scale, options.tolerance);
+    if (!(nominalMajorDiameter > tolerance.linear) || !(threadDepth > tolerance.linear)) {
+        throw new GeometryError("INVALID_ARGUMENT", "Nominal major diameter and thread depth must be greater than tolerance.");
+    }
+    const nominalMinorDiameter = nominalMajorDiameter - threadDepth * 2;
+    if (!(nominalMinorDiameter > tolerance.linear)) {
+        throw new GeometryError("INVALID_ARGUMENT", "Thread depth consumes the nominal minor diameter.");
+    }
+    const policy = resolvePrintableThreadFitPolicy(options.fit);
+    if (options.role !== "male" && options.role !== "female") {
+        throw new GeometryError("INVALID_ARGUMENT", "Unsupported thread role.");
+    }
+    const radialShift = options.role === "male" ? -policy.maleRadialInset : policy.femaleRadialOutset;
+    const majorDiameter = nominalMajorDiameter + radialShift * 2;
+    const minorDiameter = nominalMinorDiameter + radialShift * 2;
+    if (!(minorDiameter > tolerance.linear) || !(majorDiameter > minorDiameter)) {
+        throw new GeometryError("DEGENERATE_GEOMETRY", "Thread compensation leaves invalid major or minor diameters.");
+    }
+    return Object.freeze({
+        axialBacklash: policy.axialBacklash,
+        majorDiameter,
+        minorDiameter,
+        radialShift,
+    });
+}
+/**
+ * Resolves a role-independent, start-aligned facet count from the larger female mating envelope.
+ *
+ * An exact `circularSegments` value must already be divisible by `starts`; it is never silently
+ * raised. Adaptive policies align upward and fail if that would exceed `maximumSegments`.
+ */
+export function resolveThreadCircularSegments(options) {
+    const operation = "resolveThreadCircularSegments";
+    const nominalMajorDiameter = finite(options.nominalMajorDiameter, "Nominal major diameter");
+    const maximumRadialOutset = finite(options.maximumRadialOutset ?? 0, "Maximum radial outset");
+    const pitch = finite(options.profile.pitch, "Profile pitch");
+    const starts = finite(options.starts ?? 1, "Starts");
+    if (!(nominalMajorDiameter > 0) ||
+        !(pitch > 0) ||
+        maximumRadialOutset < 0 ||
+        !Number.isInteger(starts) ||
+        starts < 1 ||
+        starts > 32) {
+        throw new GeometryError("INVALID_ARGUMENT", "Nominal diameter and pitch must be positive, maximum radial outset must be non-negative, and starts must be an integer from 1 through 32.", { operation });
+    }
+    const policy = resolvePrintableThreadFitPolicy(options.fit);
+    const resolution = resolveGeometryResolution(options.resolution, options.limits);
+    const femaleMajorDiameter = nominalMajorDiameter + policy.femaleRadialOutset * 2;
+    const maximumFemaleRadius = femaleMajorDiameter / 2 + maximumRadialOutset;
+    const effectiveRadius = Math.hypot(Math.PI * maximumFemaleRadius * 2, pitch * starts) / (Math.PI * 2);
+    const baseSegments = resolveCircularSegments(effectiveRadius, options.resolution, options.limits);
+    if (resolution.circularSegments !== undefined && baseSegments % starts !== 0) {
+        throw new GeometryError("INVALID_ARGUMENT", "Exact circularSegments must be divisible by the requested thread starts.", { operation, details: { circularSegments: baseSegments, starts } });
+    }
+    let segments = Math.ceil(baseSegments / starts) * starts;
+    if (segments > resolution.maximumSegments) {
+        throw new GeometryError("COMPLEXITY_LIMIT", "Start-aligned thread tessellation exceeds the configured segment safety limit.", { operation, details: { maximumSegments: resolution.maximumSegments, segments } });
+    }
+    // Physical circle error is only the lower bound for a mating thread grid. Independently
+    // triangulated male and female helices also need enough angular facets to distribute their full
+    // phase-span allowance without consuming either profile's crest or root flats. Adaptive policies
+    // therefore refine by complete start-aligned steps; an exact caller override remains exact and
+    // fails instead of being silently changed.
+    while (segments <= resolution.maximumSegments) {
+        try {
+            compensateThreadProfileForFaceting(options.profile, policy.axialBacklash, "male", starts, segments);
+            compensateThreadProfileForFaceting(options.profile, policy.axialBacklash, "female", starts, segments);
+            return segments;
+        }
+        catch (error) {
+            if (resolution.circularSegments !== undefined ||
+                !(error instanceof GeometryError) ||
+                error.code !== "COMPLEXITY_LIMIT") {
+                throw error;
+            }
+            segments += starts;
+        }
+    }
+    throw new GeometryError("COMPLEXITY_LIMIT", "Mating thread faceting requires more segments than the configured safety limit.", {
+        operation,
+        details: { maximumSegments: resolution.maximumSegments, starts },
+    });
+}