@metamesh/modeling 0.0.0-bootstrap.0 → 0.6.0

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

@@ -0,0 +1,368 @@
+/** Periodic thread profiles and axial/radial fit compensation. */
+import { GeometryError } from "../errors.js";
+import { triangulateLoop2 } from "../loft.js";
+import { resolveGeometryTolerance } from "../tolerance.js";
+const BUTTRESS_DEFAULT_DEPTH_RATIO = 0.66271;
+const BUTTRESS_CREST_FLAT_RATIO = 0.16316;
+const BUTTRESS_PRESSURE_ANGLE_RADIANS = (7 * Math.PI) / 180;
+const BUTTRESS_CLEARANCE_ANGLE_RADIANS = Math.PI / 4;
+/** @internal Maximum periodic profile size accepted before meshing. */
+export const MAX_THREAD_PROFILE_POINTS = 1_024;
+/**
+ * Applies axial fit allowance to a validated periodic profile.
+ *
+ * Male crests/ridges narrow by the requested backlash; female cutter ridges
+ * widen by it. Periodic root endpoints remain fixed so pitch and lead do not
+ * change. The returned profile is a new deeply immutable value.
+ */
+export function compensateThreadProfileAxially(profile, axialBacklash, role) {
+    const operation = "compensateThreadProfileAxially";
+    const backlash = assertFiniteThreadNumber(axialBacklash, "axialBacklash", operation);
+    if (backlash < 0 || backlash >= profile.pitch / 2) {
+        throw new GeometryError("INVALID_ARGUMENT", "Axial backlash must be non-negative and below half the pitch.", { operation });
+    }
+    if (role !== "female" && role !== "male") {
+        throw new GeometryError("INVALID_ARGUMENT", "Unsupported thread role.", { operation });
+    }
+    if (backlash === 0)
+        return profile;
+    return shiftThreadProfileFlanks(profile, backlash / 4, role, operation);
+}
+const shiftThreadProfileFlanks = (profile, flankShift, role, operation) => {
+    const direction = role === "male" ? -1 : 1;
+    const crestPoints = profile.points.filter((point) => Math.abs(point[1]) <= Number.EPSILON);
+    const crestCenter = crestPoints.length === 0
+        ? 0
+        : (Math.min(...crestPoints.map((point) => point[0])) +
+            Math.max(...crestPoints.map((point) => point[0]))) /
+            2;
+    const points = profile.points.map(([axial, radial], index) => {
+        if (index === 0 || index === profile.points.length - 1 || axial === crestCenter)
+            return [axial, radial];
+        const shifted = axial + direction * Math.sign(axial - crestCenter) * flankShift;
+        return [Math.abs(shifted - crestCenter) <= 1e-12 ? crestCenter : shifted, radial];
+    });
+    if (points.some((point, index) => index > 0 && point[0] < points[index - 1][0])) {
+        throw new GeometryError("DEGENERATE_GEOMETRY", "Axial compensation collapses or reverses profile features.", { operation });
+    }
+    const frozen = freezeThreadProfilePoints(points);
+    return Object.freeze({
+        ...profile,
+        crestFlatWidth: flatWidthAtRadius(frozen, 0, 1e-12),
+        points: frozen,
+        rootFlatWidth: flatWidthAtRadius(frozen, -profile.depth, 1e-12),
+    });
+};
+/** @internal Rejects a nonfinite numeric thread input before arithmetic. */
+export const assertFiniteThreadNumber = (value, name, operation) => {
+    if (!Number.isFinite(value))
+        throw new GeometryError("NON_FINITE_VALUE", `${name} must be finite.`, { operation });
+    return value;
+};
+/** @internal Copies a periodic profile into an immutable point snapshot. */
+export const freezeThreadProfilePoints = (points) => Object.freeze(points
+    .filter((point, index) => index === 0 ||
+    Math.hypot(point[0] - points[index - 1][0], point[1] - points[index - 1][1]) > 1e-12)
+    .map(([x, y]) => Object.freeze([x, y])));
+/** @internal Scales only the radial dimensions of a validated profile. */
+export function scaleThreadProfileRadially(profile, scale) {
+    const radialScale = assertFiniteThreadNumber(scale, "scale", "scaleThreadProfileRadially");
+    if (!(radialScale > 0)) {
+        throw new GeometryError("INVALID_ARGUMENT", "Thread profile radial scale must be positive.", {
+            operation: "scaleThreadProfileRadially",
+        });
+    }
+    if (radialScale === 1)
+        return profile;
+    const depth = profile.depth * radialScale;
+    const points = freezeThreadProfilePoints(profile.points.map(([axial, radial]) => [axial, radial * radialScale]));
+    return Object.freeze({
+        ...profile,
+        crestFlatWidth: flatWidthAtRadius(points, 0, 1e-12),
+        depth,
+        points,
+        rootFlatWidth: flatWidthAtRadius(points, -depth, 1e-12),
+    });
+}
+/**
+ * Applies printable axial fit plus the conservative phase allowance required by circular facets.
+ *
+ * One triangulated facet spans `pitch * starts / circularSegments` axially. A directed zipper
+ * triangle can expose either end of that complete span when independently faceted parts rotate.
+ * This helper distributes the full conservative flank clearance between the male crest and female
+ * root according to their available flat widths, and rejects a resolution that cannot represent
+ * it exactly.
+ */
+export function compensateThreadProfileForFaceting(profile, axialBacklash, role, starts, circularSegments) {
+    const operation = "compensateThreadProfileForFaceting";
+    const startCount = assertFiniteThreadNumber(starts, "starts", operation);
+    const segments = assertFiniteThreadNumber(circularSegments, "circularSegments", operation);
+    if (!Number.isInteger(startCount) ||
+        startCount < 1 ||
+        startCount > 32 ||
+        !Number.isInteger(segments) ||
+        segments < 3 ||
+        segments % startCount !== 0) {
+        throw new GeometryError("INVALID_ARGUMENT", "Thread starts and circular segments must be positive aligned integers.", { operation });
+    }
+    const requestedBacklash = assertFiniteThreadNumber(axialBacklash, "axialBacklash", operation);
+    if (requestedBacklash < 0 || requestedBacklash >= profile.pitch / 2) {
+        throw new GeometryError("INVALID_ARGUMENT", "Axial backlash must be non-negative and below half the pitch.", { operation });
+    }
+    if (role !== "female" && role !== "male") {
+        throw new GeometryError("INVALID_ARGUMENT", "Unsupported thread role.", { operation });
+    }
+    const baseShift = requestedBacklash / 4;
+    const { femaleCapacity, maleCapacity } = axialCompensationCapacities(profile);
+    if (baseShift > maleCapacity + 1e-12 || baseShift > femaleCapacity + 1e-12) {
+        throw new GeometryError("DEGENERATE_GEOMETRY", "Requested axial backlash consumes a thread crest or root flat.", { operation });
+    }
+    const requiredExtra = (profile.pitch * startCount) / segments;
+    const maleAvailable = Math.max(0, maleCapacity - baseShift);
+    const femaleAvailable = Math.max(0, femaleCapacity - baseShift);
+    const minimumMaleExtra = Math.max(0, requiredExtra - femaleAvailable);
+    const maximumMaleExtra = Math.min(requiredExtra, maleAvailable);
+    if (minimumMaleExtra > maximumMaleExtra + 1e-12) {
+        throw new GeometryError("COMPLEXITY_LIMIT", "Circular thread resolution is too coarse for the requested starts and axial fit.", {
+            operation,
+            details: { requiredExtra, segments, starts: startCount },
+        });
+    }
+    const maleExtra = Math.max(minimumMaleExtra, Math.min(maximumMaleExtra, requiredExtra / 2));
+    const roleExtra = role === "male" ? maleExtra : requiredExtra - maleExtra;
+    try {
+        return shiftThreadProfileFlanks(profile, baseShift + roleExtra, role, operation);
+    }
+    catch (error) {
+        if (error instanceof GeometryError && error.code === "DEGENERATE_GEOMETRY") {
+            throw new GeometryError("COMPLEXITY_LIMIT", "Circular thread resolution cannot preserve this profile's asymmetric flats.", {
+                operation,
+                details: { requiredExtra, segments, starts: startCount },
+            });
+        }
+        throw error;
+    }
+}
+const axialCompensationCapacities = (profile) => {
+    const radialTolerance = 1e-12;
+    const crestPoints = profile.points.filter((point) => Math.abs(point[1]) <= radialTolerance);
+    if (crestPoints.length === 0) {
+        throw new GeometryError("INVALID_TOPOLOGY", "Thread profile does not reach its major envelope.", {
+            operation: "compensateThreadProfileForFaceting",
+        });
+    }
+    const crestMinimum = Math.min(...crestPoints.map(([axial]) => axial));
+    const crestMaximum = Math.max(...crestPoints.map(([axial]) => axial));
+    const crestCenter = (crestMinimum + crestMaximum) / 2;
+    const rootRadius = -profile.depth;
+    const firstRaised = profile.points.findIndex((point) => point[1] > rootRadius + radialTolerance);
+    let lastRaised = -1;
+    for (let index = profile.points.length - 1; index >= 0; index -= 1) {
+        if (profile.points[index][1] > rootRadius + radialTolerance) {
+            lastRaised = index;
+            break;
+        }
+    }
+    if (firstRaised <= 0 || lastRaised < firstRaised || lastRaised >= profile.points.length - 1) {
+        throw new GeometryError("INVALID_TOPOLOGY", "Thread profile has no bounded ridge.", {
+            operation: "compensateThreadProfileForFaceting",
+        });
+    }
+    const leftRootRun = profile.points[firstRaised - 1][0] - profile.points[0][0];
+    const rightRootRun = profile.points.at(-1)[0] - profile.points[lastRaised + 1][0];
+    return Object.freeze({
+        // Shifting is symmetric about the crest, but a custom profile need not have symmetric
+        // periodic root flats. The smaller side is the only clearance both flanks can realize.
+        femaleCapacity: Math.max(0, Math.min(leftRootRun, rightRootRun)),
+        maleCapacity: Math.max(0, Math.min(crestCenter - crestMinimum, crestMaximum - crestCenter)),
+    });
+};
+const flatWidthAtRadius = (points, radial, tolerance) => points.reduce((width, point, index) => {
+    if (index === 0)
+        return width;
+    const previous = points[index - 1];
+    return Math.abs(previous[1] - radial) <= tolerance && Math.abs(point[1] - radial) <= tolerance
+        ? width + point[0] - previous[0]
+        : width;
+}, 0);
+/** @internal Extracts the connected tooth section between its root transitions. */
+export const createThreadRidgeSection = (points, minimum, linearTolerance, operation) => {
+    const firstRaised = points.findIndex((point) => point[1] > minimum + linearTolerance);
+    let lastRaised = -1;
+    for (let index = points.length - 1; index >= 0; index -= 1) {
+        if (points[index][1] > minimum + linearTolerance) {
+            lastRaised = index;
+            break;
+        }
+    }
+    if (firstRaised <= 0 || lastRaised < firstRaised || lastRaised >= points.length - 1) {
+        throw new GeometryError("INVALID_TOPOLOGY", "Thread profiles must leave the minor envelope and return to it within one pitch.", { operation });
+    }
+    for (let index = firstRaised; index <= lastRaised; index += 1) {
+        if (points[index][1] <= minimum + linearTolerance) {
+            throw new GeometryError("INVALID_TOPOLOGY", "A thread profile must describe one connected ridge above the minor envelope.", { operation });
+        }
+    }
+    // Period endpoints and adjacent root flats belong to the root cylinder. Sweeping them and then
+    // closing the ridge section retraces its minor-envelope edge, creating overlapping cap faces and
+    // zero-area triangles. Keep exactly the connected tooth plus its two root transition points.
+    const section = points.slice(firstRaised - 1, lastRaised + 2);
+    triangulateLoop2([...section].reverse());
+    return section;
+};
+const standardProfile = (kind, pitch, depth, root, crest, leftRun, rightRun) => {
+    const half = pitch / 2;
+    return Object.freeze({
+        kind,
+        pitch,
+        depth,
+        rootFlatWidth: root,
+        crestFlatWidth: crest,
+        points: freezeThreadProfilePoints([
+            [-half, -depth],
+            [-half + root / 2, -depth],
+            [-half + root / 2 + leftRun, 0],
+            [half - root / 2 - rightRun, 0],
+            [half - root / 2, -depth],
+            [half, -depth],
+        ]),
+    });
+};
+/**
+ * Creates a periodic thread profile for the shaft-locked helical mesher.
+ *
+ * The open path spans one pitch. Radial zero is the major envelope; negative
+ * values point toward the shaft. Custom paths must be finite, axially
+ * non-decreasing, periodic at their endpoints, and reach radial zero.
+ */
+export function createThreadProfile(spec) {
+    const operation = "createThreadProfile";
+    const pitch = assertFiniteThreadNumber(spec.pitch, "pitch", operation);
+    const tolerance = resolveGeometryTolerance(Math.abs(pitch), spec.tolerance);
+    if (!(pitch > tolerance.linear))
+        throw new GeometryError("INVALID_ARGUMENT", "pitch must exceed tolerance.", { operation });
+    if (spec.kind === "custom") {
+        if (spec.points.length < 4)
+            throw new GeometryError("DEGENERATE_GEOMETRY", "A custom profile needs at least four points.", { operation });
+        if (spec.points.length > MAX_THREAD_PROFILE_POINTS)
+            throw new GeometryError("COMPLEXITY_LIMIT", `A custom profile accepts at most ${MAX_THREAD_PROFILE_POINTS} points.`, { operation, details: { pointCount: spec.points.length } });
+        const parsed = spec.points.map(([x, y], index) => [
+            assertFiniteThreadNumber(x, `points[${index}].x`, operation),
+            assertFiniteThreadNumber(y, `points[${index}].y`, operation),
+        ]);
+        const points = freezeThreadProfilePoints(parsed);
+        if (points.length < 4)
+            throw new GeometryError("DEGENERATE_GEOMETRY", "A custom profile needs at least four distinct consecutive points.", { operation });
+        if (Math.abs(points[0][0] + pitch / 2) > tolerance.linear ||
+            Math.abs(points.at(-1)[0] - pitch / 2) > tolerance.linear) {
+            throw new GeometryError("INVALID_ARGUMENT", "Custom profiles must span [-pitch/2, pitch/2].", { operation });
+        }
+        if (points.some((point, index) => index > 0 && point[0] < points[index - 1][0])) {
+            throw new GeometryError("INVALID_ARGUMENT", "Custom profile axial coordinates must not decrease.", { operation });
+        }
+        let equalAxialRun = 1;
+        for (let index = 1; index < points.length; index += 1) {
+            equalAxialRun =
+                Math.abs(points[index][0] - points[index - 1][0]) <= tolerance.linear
+                    ? equalAxialRun + 1
+                    : 1;
+            if (equalAxialRun > 2) {
+                throw new GeometryError("INVALID_TOPOLOGY", "Custom profiles may use one segment, but not a retracing chain, at one axial coordinate.", { operation });
+            }
+        }
+        if (Math.abs(points[0][1] - points.at(-1)[1]) > tolerance.linear) {
+            throw new GeometryError("INVALID_TOPOLOGY", "Custom profile endpoint radii must match.", {
+                operation,
+            });
+        }
+        const maximum = Math.max(...points.map((point) => point[1]));
+        const minimum = Math.min(...points.map((point) => point[1]));
+        if (Math.abs(maximum) > tolerance.linear || !(minimum < -tolerance.linear)) {
+            throw new GeometryError("INVALID_ARGUMENT", "Custom profiles must reach radial zero and have positive depth.", { operation });
+        }
+        if (Math.abs(points[0][1] - minimum) > tolerance.linear ||
+            Math.abs(points.at(-1)[1] - minimum) > tolerance.linear) {
+            throw new GeometryError("INVALID_TOPOLOGY", "Custom profile endpoints must lie on the minor envelope so periodic ridges join the shaft.", { operation });
+        }
+        // Canonicalize accepted envelope values so downstream fit/scaling helpers do not need to
+        // rediscover the caller's tolerance. This also keeps reported flat widths exact and truthful.
+        const normalizedPoints = freezeThreadProfilePoints(points.map(([axial, radial]) => [
+            axial,
+            Math.abs(radial) <= tolerance.linear
+                ? 0
+                : Math.abs(radial - minimum) <= tolerance.linear
+                    ? minimum
+                    : radial,
+        ]));
+        const firstCrest = normalizedPoints.findIndex((point) => point[1] === 0);
+        let lastCrest = firstCrest;
+        for (let index = normalizedPoints.length - 1; index >= firstCrest; index -= 1) {
+            if (normalizedPoints[index][1] === 0) {
+                lastCrest = index;
+                break;
+            }
+        }
+        if (normalizedPoints.slice(firstCrest, lastCrest + 1).some((point) => point[1] !== 0)) {
+            throw new GeometryError("INVALID_TOPOLOGY", "A custom thread profile must have one contiguous crest plateau.", { operation });
+        }
+        createThreadRidgeSection(normalizedPoints, minimum, tolerance.linear, operation);
+        return Object.freeze({
+            kind: spec.kind,
+            pitch,
+            depth: -minimum,
+            crestFlatWidth: flatWidthAtRadius(normalizedPoints, 0, tolerance.linear),
+            rootFlatWidth: flatWidthAtRadius(normalizedPoints, minimum, tolerance.linear),
+            points: normalizedPoints,
+        });
+    }
+    if (spec.kind === "triangular") {
+        const crestRatio = assertFiniteThreadNumber(spec.crestFlatRatio ?? 1 / 8, "crestFlatRatio", operation);
+        const rootRatio = assertFiniteThreadNumber(spec.rootFlatRatio ?? 1 / 4, "rootFlatRatio", operation);
+        if (crestRatio < 0 || rootRatio < 0 || crestRatio + rootRatio >= 1) {
+            throw new GeometryError("INVALID_ARGUMENT", "Flat ratios must be non-negative and sum below one.", { operation });
+        }
+        const crest = pitch * crestRatio;
+        const root = pitch * rootRatio;
+        const run = (pitch - crest - root) / 2;
+        const depth = run * Math.tan(Math.PI / 3);
+        if (!(depth > tolerance.linear))
+            throw new GeometryError("DEGENERATE_GEOMETRY", "Flats leave no triangular thread depth.", {
+                operation,
+            });
+        return standardProfile(spec.kind, pitch, depth, root, crest, run, run);
+    }
+    const depth = assertFiniteThreadNumber(spec.depth ?? (spec.kind === "buttress" ? pitch * BUTTRESS_DEFAULT_DEPTH_RATIO : pitch * 0.5), "depth", operation);
+    if (!(depth > tolerance.linear))
+        throw new GeometryError("INVALID_ARGUMENT", "depth must exceed tolerance.", { operation });
+    if (spec.kind === "square")
+        return standardProfile(spec.kind, pitch, depth, pitch / 2, pitch / 2, 0, 0);
+    if (spec.kind === "buttress") {
+        const side = spec.pressureFlankSide ?? "positive";
+        if (side !== "negative" && side !== "positive") {
+            throw new GeometryError("INVALID_ARGUMENT", "Unsupported buttress pressure-flank side.", {
+                operation,
+            });
+        }
+        const pressureRun = depth * Math.tan(BUTTRESS_PRESSURE_ANGLE_RADIANS);
+        const clearanceRun = depth * Math.tan(BUTTRESS_CLEARANCE_ANGLE_RADIANS);
+        const crest = pitch * BUTTRESS_CREST_FLAT_RATIO;
+        const root = pitch - pressureRun - clearanceRun - crest;
+        if (!(root > tolerance.linear))
+            throw new GeometryError("DEGENERATE_GEOMETRY", "depth leaves no root flat for the 7/45-degree buttress profile.", { operation });
+        return standardProfile(spec.kind, pitch, depth, root, crest, side === "positive" ? clearanceRun : pressureRun, side === "positive" ? pressureRun : clearanceRun);
+    }
+    const includedAngle = spec.kind === "acme"
+        ? 29
+        : assertFiniteThreadNumber(spec.threadAngle ?? 30, "threadAngle", operation);
+    if (includedAngle < 0 || includedAngle >= 180) {
+        throw new GeometryError("INVALID_ARGUMENT", "threadAngle 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));
+    const remaining = pitch - flankRun * 2;
+    if (!(remaining > tolerance.linear * 2))
+        throw new GeometryError("DEGENERATE_GEOMETRY", "depth leaves no crest/root flats.", {
+            operation,
+        });
+    return standardProfile(spec.kind, pitch, depth, remaining / 2, remaining / 2, flankRun, flankRun);
+}

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

@@ -0,0 +1,230 @@
+import { GeometryError } from "../errors.js";
+import { resolveCircularSegments } from "../resolution.js";
+import { resolveGeometryTolerance } from "../tolerance.js";
+import { compensateThreadDiameters, preflightHelicalThreadSolidMesh, resolveThreadCircularSegments, } from "./index.js";
+import { compensateThreadProfileForFaceting, scaleThreadProfileRadially, } from "./thread-profiles.js";
+const THREAD_FACETING_MARGIN = 0.001;
+const resolveCompensatedThreadBevelSize = (options, role, compensated, style) => {
+    if (options.bevelSize !== undefined)
+        return options.bevelSize;
+    if (style !== "blunt")
+        return options.profile.depth;
+    const envelopeDiameter = role === "female" ? compensated.majorDiameter : compensated.minorDiameter;
+    return envelopeDiameter / 12;
+};
+export const resolveCompensatedThreadSolidMesh = (options, role) => {
+    if (options.bevelSize !== undefined &&
+        (!Number.isFinite(options.bevelSize) || options.bevelSize < 0)) {
+        throw new GeometryError("INVALID_ARGUMENT", "Thread bevel size must be finite and non-negative.", {
+            operation: "threadedSolid",
+        });
+    }
+    const compensated = compensateThreadDiameters({
+        nominalMajorDiameter: options.nominalMajorDiameter,
+        threadDepth: options.profile.depth,
+        role,
+        ...(options.fit === undefined ? {} : { fit: options.fit }),
+    });
+    const compensatedFemale = role === "female"
+        ? compensated
+        : compensateThreadDiameters({
+            nominalMajorDiameter: options.nominalMajorDiameter,
+            threadDepth: options.profile.depth,
+            role: "female",
+            ...(options.fit === undefined ? {} : { fit: options.fit }),
+        });
+    const requestedEnds = options.ends ?? {};
+    const bottomStyle = requestedEnds.bottom ?? "blunt";
+    const topStyle = requestedEnds.top ?? "blunt";
+    const bottomBevelSize = resolveCompensatedThreadBevelSize(options, role, compensated, bottomStyle);
+    const topBevelSize = resolveCompensatedThreadBevelSize(options, role, compensated, topStyle);
+    const femaleBottomBevelSize = resolveCompensatedThreadBevelSize(options, "female", compensatedFemale, bottomStyle);
+    const femaleTopBevelSize = resolveCompensatedThreadBevelSize(options, "female", compensatedFemale, topStyle);
+    const starts = options.starts ?? 1;
+    const hypotheticalFemaleLength = options.length + options.profile.pitch * 2;
+    const femaleBevelOutset = (style, size) => style === "blunt"
+        ? Math.min(size, hypotheticalFemaleLength / 2)
+        : Math.max(0, Math.min(size, hypotheticalFemaleLength / 2) - options.profile.depth);
+    const maximumRadialOutset = Math.max(options.bevelBottom === true ? femaleBevelOutset(bottomStyle, femaleBottomBevelSize) : 0, options.bevelTop === true ? femaleBevelOutset(topStyle, femaleTopBevelSize) : 0);
+    const segments = resolveThreadCircularSegments({
+        nominalMajorDiameter: options.nominalMajorDiameter,
+        profile: options.profile,
+        starts,
+        maximumRadialOutset,
+        ...(options.limits === undefined ? {} : { limits: options.limits }),
+        ...(options.fit === undefined ? {} : { fit: options.fit }),
+        ...(options.resolution === undefined ? {} : { resolution: options.resolution }),
+    });
+    const resolution = { ...options.resolution, circularSegments: segments };
+    const faceting = role === "female" ? 1 / Math.cos(Math.PI / segments) : 1;
+    // A 1 µm diameter margin avoids Boolean contact caused by Float32 mesh roundoff without
+    // materially changing the requested printable allowance.
+    const majorDiameter = compensated.majorDiameter * faceting + (role === "female" ? THREAD_FACETING_MARGIN : 0);
+    // The shared helper distributes one complete zipper-facet phase span across the two roles, so
+    // independently triangulated mating surfaces remain nested at arbitrary screw rotations.
+    const compensatedProfile = compensateThreadProfileForFaceting(options.profile, compensated.axialBacklash, role, starts, segments);
+    const meshingProfile = scaleThreadProfileRadially(compensatedProfile, faceting);
+    // Internal tools extend beyond both requested faces so subtraction exposes
+    // the complete helical cavity rather than a ridge-center end cap.
+    const axialExtension = role === "female" ? options.profile.pitch : 0;
+    const workingLength = options.length + axialExtension * 2;
+    // End treatment coordinates belong to the requested solid, while the female cutter is meshed in
+    // an extended working interval. Include that extension in each reserved role-specific end so the
+    // translated cutter still starts and stops its thread at the caller's requested coordinates.
+    const ends = {
+        ...requestedEnds,
+        endLength: Math.max(requestedEnds.endLength ?? 0, options.bevelBottom === true && bottomStyle === "blunt" ? bottomBevelSize : 0, options.bevelTop === true && topStyle === "blunt" ? topBevelSize : 0) + axialExtension,
+        leadInEnvelope: role === "female" ? "major" : "minor",
+    };
+    return Object.freeze({
+        axialExtension,
+        circularSegments: segments,
+        meshOptions: Object.freeze({
+            ...options,
+            profile: meshingProfile,
+            majorDiameter,
+            length: workingLength,
+            resolution,
+            bevelBottomSize: bottomBevelSize,
+            bevelMode: role === "female" ? "outset" : "inset",
+            bevelOffset: axialExtension,
+            bevelTopSize: topBevelSize,
+            ...(options.bevelBottom === undefined ? {} : { bevelBottom: options.bevelBottom }),
+            ...(options.bevelTop === undefined ? {} : { bevelTop: options.bevelTop }),
+            ends,
+        }),
+    });
+};
+const preflightCompensatedThreadSolid = (options, role) => preflightHelicalThreadSolidMesh(resolveCompensatedThreadSolidMesh(options, role).meshOptions);
+/** Preflights the exact compensated direct mesh used by the threaded rod constructor. */
+export function preflightThreadedRodSolid(options) {
+    return preflightCompensatedThreadSolid(options, "male");
+}
+/** Preflights the exact extended mesh used by the internal thread cutter constructor. */
+export function preflightInternalThreadCutterSolid(options) {
+    return preflightCompensatedThreadSolid(options, "female");
+}
+const throwInvalidNutScalar = (label, parameter, requirement, operation) => {
+    throw new GeometryError("INVALID_ARGUMENT", `Threaded nut ${label} must be ${requirement}.`, {
+        operation,
+        details: { parameter },
+    });
+};
+export const resolveThreadedNutSolid = (options, operation) => {
+    // Keep these public boundary checks ahead of resolution and all Manifold body construction.
+    if (!Number.isFinite(options.width) || !(options.width > 0)) {
+        throwInvalidNutScalar("width", "width", "finite and greater than zero", operation);
+    }
+    if (!Number.isFinite(options.thickness) || !(options.thickness > 0)) {
+        throwInvalidNutScalar("thickness", "thickness", "finite and greater than zero", operation);
+    }
+    if (options.chamferSize !== undefined &&
+        (!Number.isFinite(options.chamferSize) || options.chamferSize < 0)) {
+        throwInvalidNutScalar("chamfer size", "chamferSize", "finite and non-negative", operation);
+    }
+    if (options.shape !== "hex" && options.shape !== "round" && options.shape !== "square") {
+        throw new GeometryError("INVALID_ARGUMENT", "Unsupported threaded nut shape.", {
+            operation,
+            details: { parameter: "shape" },
+        });
+    }
+    const bevel = options.bevel ?? "automatic";
+    if (bevel !== "automatic" &&
+        bevel !== "both" &&
+        bevel !== "inside" &&
+        bevel !== "none" &&
+        bevel !== "outside") {
+        throw new GeometryError("INVALID_ARGUMENT", "Unsupported threaded nut bevel selection.", {
+            operation,
+            details: { parameter: "bevel" },
+        });
+    }
+    const segments = options.shape === "hex"
+        ? 6
+        : options.shape === "square"
+            ? 4
+            : resolveCircularSegments(options.width / 2, options.bodyResolution ?? options.resolution, options.limits);
+    const sideCosine = Math.cos(Math.PI / segments);
+    const outerRadius = options.shape === "round" ? options.width / 2 : options.width / (2 * sideCosine);
+    const inside = bevel === "both" || bevel === "inside" || bevel === "automatic";
+    const outside = bevel === "both" || bevel === "outside" || bevel === "automatic";
+    const chamferSize = options.chamferSize ?? Math.min(options.profile.depth, options.thickness / 4);
+    if (!Number.isFinite(chamferSize) || chamferSize < 0) {
+        throwInvalidNutScalar("chamfer size", "chamferSize", "finite and non-negative", operation);
+    }
+    if ((inside || outside) && chamferSize > 0 && chamferSize * 2 >= options.thickness) {
+        throw new GeometryError("DEGENERATE_GEOMETRY", "Threaded nut chamfer size must be smaller than half the body thickness.", {
+            operation,
+            details: {
+                chamferSize,
+                parameter: "chamferSize",
+                reason: "insufficient-axial-space",
+                thickness: options.thickness,
+            },
+        });
+    }
+    const bevelBottom = outside && !options.flushBuildPlateBottom && chamferSize > 0;
+    const bevelTop = outside && chamferSize > 0;
+    const cutter = resolveCompensatedThreadSolidMesh({
+        ...options,
+        length: options.thickness,
+        bevelBottom: inside,
+        bevelTop: inside,
+        bevelSize: chamferSize,
+    }, "female");
+    const plainBodyFaceInradius = outerRadius * sideCosine;
+    const chamferedBodyFaceInradius = (outerRadius - chamferSize) * sideCosine;
+    const bottomBodyFaceInradius = bevelBottom ? chamferedBodyFaceInradius : plainBodyFaceInradius;
+    const topBodyFaceInradius = bevelTop ? chamferedBodyFaceInradius : plainBodyFaceInradius;
+    const minimumBodyFaceInradius = Math.min(bottomBodyFaceInradius, topBodyFaceInradius);
+    const cutterMajorRadius = cutter.meshOptions.majorDiameter / 2;
+    const cutterFaceRadiusFor = (style) => inside
+        ? cutterMajorRadius +
+            (style === "blunt" ? chamferSize : Math.max(0, chamferSize - options.profile.depth))
+        : cutterMajorRadius;
+    const bottomCutterFaceRadius = cutterFaceRadiusFor(options.ends?.bottom ?? "blunt");
+    const topCutterFaceRadius = cutterFaceRadiusFor(options.ends?.top ?? "blunt");
+    const cutterFaceRadius = Math.max(bottomCutterFaceRadius, topCutterFaceRadius);
+    const minimumFaceWall = Math.min(bottomBodyFaceInradius - bottomCutterFaceRadius, topBodyFaceInradius - topCutterFaceRadius);
+    const requiredFaceWall = Math.max(THREAD_FACETING_MARGIN, resolveGeometryTolerance(Math.max(options.width, options.thickness, cutter.meshOptions.majorDiameter), options.tolerance).linear);
+    if (!(minimumFaceWall > requiredFaceWall)) {
+        const chamferIsActive = (inside || outside) && chamferSize > 0;
+        throw new GeometryError("DEGENERATE_GEOMETRY", chamferIsActive
+            ? "Threaded nut chamfer must leave a positive end-face annulus around the compensated thread."
+            : "Threaded nut width must leave a positive end-face annulus around the compensated thread.", {
+            operation,
+            details: {
+                chamferSize,
+                cutterFaceRadius,
+                minimumBodyFaceInradius,
+                minimumFaceWall,
+                parameter: chamferIsActive ? "chamferSize" : "width",
+                reason: "insufficient-face-annulus",
+                requiredFaceWall,
+            },
+        });
+    }
+    const thread = preflightHelicalThreadSolidMesh(cutter.meshOptions);
+    return Object.freeze({
+        bevelBottom,
+        bevelTop,
+        cutter,
+        outerRadius,
+        preflight: Object.freeze({
+            bodySegments: segments,
+            chamferSize,
+            cutterFaceRadius,
+            minimumBodyFaceInradius,
+            minimumFaceWall,
+            thread,
+            threadCircularSegments: cutter.circularSegments,
+        }),
+    });
+};
+/**
+ * Resolves a nut's exact body/cutter chamfer and preflights its extended thread mesh without
+ * allocating Manifold WASM objects.
+ */
+export function preflightThreadedNutSolid(options) {
+    return resolveThreadedNutSolid(options, "preflightThreadedNutSolid").preflight;
+}