@metamesh/modeling 0.17.0 → 0.19.0

package/dist/geometry/loft/loft.js

@@ -10,7 +10,7 @@ export { triangulateContour } from "./loft-triangulation.js";
 /**
  * Lofts simple point loops at z heights or explicit right-handed frames, in input order.
  *
- * An explicit correspondence method is required. CCW-normalized loops retain their
+ * Correspondence defaults to direct. CCW-normalized loops retain their
  * seam and original vertices; unequal counts gain subdivisions or repeated fan slots.
  * Both ends use ear-clipped caps, supporting concave profiles without center fans.
  * Intermediate slices interpolate placed world vertices, never frame axes.
@@ -21,12 +21,14 @@ export { triangulateContour } from "./loft-triangulation.js";
  * ```ts
  * const bottom = rectangleContour({ size: [20, 12] });
  * const top = rectangleContour({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
- * loftMesh([{ profile: bottom, z: 0 }, { profile: top, z: 30 }], { correspondence: "reindex" });
+ * mesh.loft([{ profile: bottom, z: 0 }, { profile: top, z: 30 }], { correspondence: "reindex" });
  * ```
  */
-export function loftMesh(stations, options) {
-    if (options?.correspondence === undefined)
-        throw new GeometryError("INVALID_ARGUMENT", "Point-loop lofts require an explicit correspondence method.", { operation: "loftMesh" });
+export function loftMesh(stations, options = {}) {
+    if (typeof options !== "object" || options === null || Array.isArray(options))
+        throw new GeometryError("INVALID_ARGUMENT", "Loft options must be an object.", {
+            operation: "loftMesh",
+        });
     const limits = resolveModelingLimits(options.limits);
     if (!Array.isArray(stations) || stations.length < 2)
         throw new GeometryError("INVALID_ARGUMENT", "Loft requires at least two stations.", {
@@ -53,16 +55,19 @@ export function loftMesh(stations, options) {
 /**
  * Linearly extrudes one simple profile along +Z with robust ear-clipped caps.
  * Path2 profiles must be closed; raw point collections have an implicit closing edge.
+ * End treatments are unsupported and reject at runtime. Use Section.extrude for finished ends.
  *
  * @example Extrude point data without an engine
  * ```ts
  * const outline = rectangleContour({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
- * extrudeMesh(outline, { height: 8 });
+ * mesh.extrude(outline, { height: 8 });
  * ```
  */
 export function extrudeMesh(input, options) {
     const { height } = options;
     const { center, scales, twist } = resolveExtrusionControls(height, options, "extrudeMesh");
+    if ("ends" in options)
+        throw new GeometryError("INVALID_ARGUMENT", "extrudeMesh does not support end treatments. Use Section.extrude instead.", { operation: "extrudeMesh" });
     if (!Number.isFinite(height) || height <= 0) {
         throw new GeometryError("INVALID_ARGUMENT", "Extrusion height must be finite and positive.", {
             operation: "extrudeMesh",

package/dist/geometry/mechanical/index.js

@@ -5,10 +5,10 @@
  */
 export { minimumCylindricalGearToothCountWithoutUndercut, resolveCylindricalGear, resolveCylindricalGearPair, resolveRackPitch, sampleCylindricalGearOutline, sampleInternalCylindricalGearSpaceOutline, sampleRackToothPath, } from "./gears.js";
 export { measureInternalCylindricalGearPairMotion } from "./gear-motion.js";
-export { helicalThreadRidgeMesh, helicalThreadSolidMesh } from "./thread-mesh.js";
-export { compensateThreadProfileAxially, compensateThreadProfileForFaceting, threadProfile, } from "./thread-profiles.js";
-export { preflightHelicalThreadSolidMesh } from "./thread-mesh-plan.js";
-export { sampleConventionalThreadHelices as sampleThreadHelices } from "./thread-helices.js";
-export { compensateThreadDiameters, PRINTABLE_THREAD_FIT_POLICIES, resolvePrintableThreadFitPolicy, resolveThreadCircularSegments, } from "./threads.js";
+export { threadRidgeMesh, threadSolidMesh } from "./threads/mesh.js";
+export { compensateThreadProfileAxially, compensateThreadProfileForFaceting, threadProfile, } from "./threads/profiles.js";
+export { preflightThreadSolidMesh } from "./threads/mesh-plan.js";
+export { sampleConventionalThreadHelices as sampleThreadHelices } from "./threads/helices.js";
+export { compensateThreadDiameters, PRINTABLE_THREAD_FIT_POLICIES, resolvePrintableThreadFitPolicy, resolveThreadCircularSegments, } from "./threads/fit.js";
 export { getMetricClearanceHoleDiameter, getMetricFastenerStandard, METRIC_FASTENER_STANDARDS, } from "./standards.js";
 export { resolveKnuckleHinge, } from "./knuckle-hinge.js";

package/dist/geometry/mechanical/threads/bevel.js

@@ -0,0 +1,24 @@
+import { GeometryError } from "../../errors.js";
+/** @internal Validates and captures factory-specific automatic bevel sizes. */
+export function resolveBevel(value, automatic, defaults, operation, parameter = "bevel") {
+    if (value === undefined)
+        return Object.freeze([defaults[0], defaults[1]]);
+    const invalid = () => {
+        throw new GeometryError("INVALID_ARGUMENT", `${parameter} must be a nonnegative finite size, "auto", or a [bottom, top] pair.`, {
+            operation,
+            details: { parameter },
+        });
+    };
+    const pair = Array.isArray(value) ? value : [value, value];
+    if (pair.length !== 2)
+        invalid();
+    const size = (index) => {
+        const item = pair[index];
+        if (item === "auto")
+            return automatic[index];
+        if (typeof item !== "number" || !Number.isFinite(item) || item < 0)
+            return invalid();
+        return item;
+    };
+    return Object.freeze([size(0), size(1)]);
+}

package/dist/geometry/mechanical/{threads.js → threads/fit.js}

@@ -1,7 +1,7 @@
-import { GeometryError } from "../errors.js";
-import { resolveCircularSegments, resolveGeometryResolution, } from "../resolution.js";
-import { resolveGeometryTolerance } from "../tolerance.js";
-import { compensateThreadProfileForFaceting } from "./thread-profiles.js";
+import { GeometryError } from "../../errors.js";
+import { resolveCircularSegments, resolveGeometryResolution, } from "../../resolution.js";
+import { resolveGeometryTolerance } from "../../tolerance.js";
+import { compensateThreadProfileForFaceting } from "./profiles.js";
 const frozenFit = (maleRadialInset, femaleRadialOutset, axialBacklash) => Object.freeze({ axialBacklash, femaleRadialOutset, maleRadialInset });
 /**
  * Conservative baseline print-fit policies in millimetres.

package/dist/geometry/mechanical/{thread-helices.js → threads/helices.js}

@@ -1,7 +1,7 @@
 /** Conventional thread helix sampling, independent of surface construction. */
-import { GeometryError } from "../errors.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
-import { assertFiniteThreadNumber } from "./thread-profiles.js";
+import { GeometryError } from "../../errors.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../../sampling-limits.js";
+import { assertFiniteThreadNumber } from "./profiles.js";
 /**
  * Samples evenly phased thread helices with finite `lead = pitch * starts`.
  * All starts together respect maxPathPoints (default 100000); excessive counts fail before allocation.

package/dist/geometry/mechanical/{thread-mesh-plan.js → threads/mesh-plan.js}

@@ -1,9 +1,10 @@
 /** Thread input resolution, end/bevel boundaries, and allocation preflight. */
-import { GeometryError } from "../errors.js";
-import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "../model-limits.js";
-import { resolveCircularSegments, resolveGeometryResolution, } from "../resolution.js";
-import { resolveGeometryTolerance } from "../tolerance.js";
-import { assertFiniteThreadNumber, createThreadRidgeSection, freezeThreadProfilePoints, MAX_THREAD_PROFILE_POINTS, } from "./thread-profiles.js";
+import { GeometryError } from "../../errors.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "../../model-limits.js";
+import { resolveCircularSegments, resolveGeometryResolution, } from "../../resolution.js";
+import { resolveGeometryTolerance } from "../../tolerance.js";
+import { resolveBevel } from "./bevel.js";
+import { assertFiniteThreadNumber, createThreadRidgeSection, freezeThreadProfilePoints, MAX_THREAD_PROFILE_POINTS, } from "./profiles.js";
 const validateMeshingProfile = (profile, linearTolerance, operation) => {
     const pitch = assertFiniteThreadNumber(profile.pitch, "profile.pitch", operation);
     const depth = assertFiniteThreadNumber(profile.depth, "profile.depth", operation);
@@ -74,7 +75,7 @@ const reindexThreadSectionForMajorEnvelope = (section, pitch, linearTolerance, o
     return Object.freeze({ phaseOffset: cutPoint + pitch / 2, section: reindexed });
 };
 /** @internal Resolves shared ridge and solid sampling before construction. */
-export const resolveHelicalThreadMeshOptions = (options, operation, circularSamplingRadius) => {
+export const resolveHelicalThreadMeshOptions = (options, operation, circularSamplingRadius, reservations = [0, 0]) => {
     const diameter = assertFiniteThreadNumber(options.majorDiameter, "majorDiameter", operation);
     const length = assertFiniteThreadNumber(options.length, "length", operation);
     assertFiniteThreadNumber(options.profile.pitch, "profile.pitch", operation);
@@ -103,8 +104,8 @@ export const resolveHelicalThreadMeshOptions = (options, operation, circularSamp
             operation,
         });
     }
-    const bottomBoundary = bottom === "standard" ? 0 : endLength;
-    const topBoundary = top === "standard" ? length : length - endLength;
+    const bottomBoundary = bottom === "standard" ? 0 : Math.max(endLength, reservations[0]);
+    const topBoundary = top === "standard" ? length : length - Math.max(endLength, reservations[1]);
     const usable = topBoundary - bottomBoundary;
     if (!(diameter - 2 * options.profile.depth > tolerance.linear)) {
         throw new GeometryError("INVALID_ARGUMENT", "A positive minor diameter is required.", {
@@ -185,6 +186,7 @@ export const resolveHelicalThreadMeshOptions = (options, operation, circularSamp
         });
     }
     return {
+        bevel: [0, 0],
         bottom,
         bottomBoundary,
         bottomLeadFullCenter,
@@ -215,19 +217,14 @@ export const resolveHelicalThreadMeshOptions = (options, operation, circularSamp
 };
 /** @internal Resolves the active radial bevel boundary at one axial station. */
 export const threadSurfaceBevelBoundaryAt = (axial, profile, resolved, options) => {
-    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 [bottomBevelSize, topBevelSize] = resolved.bevel;
     const bevelOffset = options.bevelOffset ?? 0;
     const bottomFace = bevelOffset;
     const topFace = resolved.length - bevelOffset;
     // Include the zero-depth stations here so callers can solve the exact point where a linear
     // thread flank first meets the bevel. Applying the boundary at zero depth remains a no-op.
-    const bottomApplies = options.bevelBottom === true &&
-        bottomBevelSize > 0 &&
-        axial <= bottomFace + bottomBevelSize + resolved.tolerance.linear;
-    const topApplies = options.bevelTop === true &&
-        topBevelSize > 0 &&
-        axial >= topFace - topBevelSize - resolved.tolerance.linear;
+    const bottomApplies = bottomBevelSize > 0 && axial <= bottomFace + bottomBevelSize + resolved.tolerance.linear;
+    const topApplies = topBevelSize > 0 && axial >= topFace - topBevelSize - resolved.tolerance.linear;
     if (!bottomApplies && !topApplies)
         return undefined;
     const bottomDepth = bottomApplies
@@ -265,14 +262,9 @@ export const requirePositiveThreadSurfaceRadius = (radius, resolved, operation)
     }
 };
 const resolveMaximumThreadSurfaceRadius = (options, diameter, length, operation) => {
-    const bevelSize = assertFiniteThreadNumber(options.bevelSize ?? options.profile.depth, "bevelSize", operation);
-    const bottomBevelSize = assertFiniteThreadNumber(options.bevelBottomSize ?? bevelSize, "bevelBottomSize", operation);
-    const topBevelSize = assertFiniteThreadNumber(options.bevelTopSize ?? bevelSize, "bevelTopSize", operation);
+    const [bottomBevelSize, topBevelSize] = resolveBevel(options.bevel, [options.profile.depth, options.profile.depth], [0, 0], operation);
     const bevelOffset = assertFiniteThreadNumber(options.bevelOffset ?? 0, "bevelOffset", operation);
-    if (bevelSize < 0 ||
-        bottomBevelSize < 0 ||
-        topBevelSize < 0 ||
-        bevelOffset < 0 ||
+    if (bevelOffset < 0 ||
         bevelOffset * 2 > length ||
         (options.bevelMode !== undefined &&
             options.bevelMode !== "inset" &&
@@ -286,39 +278,33 @@ const resolveMaximumThreadSurfaceRadius = (options, diameter, length, operation)
         return majorRadius;
     const outsetRadius = (style, size) => (style === "blunt" ? majorRadius : majorRadius - options.profile.depth) +
         Math.min(size, length / 2);
-    return Math.max(majorRadius, options.bevelBottom === true
+    return Math.max(majorRadius, bottomBevelSize > 0
         ? outsetRadius(options.ends?.bottom ?? "blunt", bottomBevelSize)
-        : majorRadius, options.bevelTop === true
-        ? outsetRadius(options.ends?.top ?? "blunt", topBevelSize)
-        : majorRadius);
+        : majorRadius, topBevelSize > 0 ? outsetRadius(options.ends?.top ?? "blunt", topBevelSize) : majorRadius);
 };
 /** @internal Resolves the solid's sampling and conservative allocation plan. */
 export const resolveHelicalThreadSolidMeshPreflight = (options, operation) => {
-    const requestedEndLength = options.ends?.endLength ?? 0;
-    const sharedBevelSize = options.bevelSize ?? options.profile.depth;
-    const bottomBevelSize = options.bevelBottomSize ?? sharedBevelSize;
-    const topBevelSize = options.bevelTopSize ?? sharedBevelSize;
-    const bluntBevelReservation = Math.max(options.bevelBottom === true && (options.ends?.bottom ?? "blunt") === "blunt"
-        ? bottomBevelSize
-        : 0, options.bevelTop === true && (options.ends?.top ?? "blunt") === "blunt" ? topBevelSize : 0);
-    const effectiveBluntBevelReservation = Math.min(bluntBevelReservation, options.length / 2);
-    const resolvedOptions = effectiveBluntBevelReservation > 0
-        ? {
-            ...options,
-            ends: {
-                ...options.ends,
-                endLength: Math.max(requestedEndLength, effectiveBluntBevelReservation),
-            },
-        }
-        : options;
-    const resolved = resolveHelicalThreadMeshOptions(resolvedOptions, operation, (diameter, length) => resolveMaximumThreadSurfaceRadius(resolvedOptions, diameter, length, operation));
+    const sizes = resolveBevel(options.bevel, [options.profile.depth, options.profile.depth], [0, 0], operation);
+    const bottomBevelSize = Math.min(sizes[0], options.length / 2);
+    const topBevelSize = Math.min(sizes[1], options.length / 2);
+    const offset = options.bevelOffset ?? 0;
+    const base = resolveHelicalThreadMeshOptions(options, operation, (diameter, length) => resolveMaximumThreadSurfaceRadius(options, diameter, length, operation), [
+        bottomBevelSize > 0 && (options.ends?.bottom ?? "blunt") === "blunt"
+            ? offset + bottomBevelSize
+            : 0,
+        topBevelSize > 0 && (options.ends?.top ?? "blunt") === "blunt" ? offset + topBevelSize : 0,
+    ]);
+    const resolved = {
+        ...base,
+        bevel: [bottomBevelSize, topBevelSize],
+    };
     if ((options.bevelMode ?? "inset") === "inset") {
         const majorRadius = resolved.diameter / 2;
-        if (options.bevelBottom === true) {
-            requirePositiveThreadSurfaceRadius(applyThreadSurfaceBevel(majorRadius, 0, options.profile, resolved, resolvedOptions), resolved, operation);
+        if (bottomBevelSize > 0) {
+            requirePositiveThreadSurfaceRadius(applyThreadSurfaceBevel(majorRadius, 0, options.profile, resolved, options), resolved, operation);
         }
-        if (options.bevelTop === true) {
-            requirePositiveThreadSurfaceRadius(applyThreadSurfaceBevel(majorRadius, resolved.length, options.profile, resolved, resolvedOptions), resolved, operation);
+        if (topBevelSize > 0) {
+            requirePositiveThreadSurfaceRadius(applyThreadSurfaceBevel(majorRadius, resolved.length, options.profile, resolved, options), resolved, operation);
         }
     }
     const resolution = resolveGeometryResolution(options.resolution, options.limits);
@@ -354,9 +340,8 @@ export const resolveHelicalThreadSolidMeshPreflight = (options, operation) => {
  * `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}
+ * See `mesh.threadSolid` for standalone mesh construction.
  */
-export function preflightHelicalThreadSolidMesh(options) {
-    return resolveHelicalThreadSolidMeshPreflight(options, "preflightHelicalThreadSolidMesh")
-        .preflight;
+export function preflightThreadSolidMesh(options) {
+    return resolveHelicalThreadSolidMeshPreflight(options, "preflightThreadSolidMesh").preflight;
 }

package/dist/geometry/mechanical/{thread-mesh.js → threads/mesh.js}

@@ -1,9 +1,9 @@
 /** Closed ridge and complete-solid mesh construction from resolved thread plans. */
-import { triangulateContour } from "../loft/loft.js";
-import { analyzeTriangleMesh, joinTriangleMeshes, reverseTriangleMesh, validateTriangleMesh, } from "../mesh/mesh.js";
-import { assertMeshAllocationWithinLimits, resolveModelingLimits } from "../model-limits.js";
-import { resolveHelicalThreadMeshOptions, resolveHelicalThreadSolidMeshPreflight, } from "./thread-mesh-plan.js";
-import { buildThreadSurfaceColumn, stitchThreadSurfaceColumns } from "./thread-surface.js";
+import { triangulateContour } from "../../loft/loft.js";
+import { analyzeTriangleMesh, joinTriangleMeshes, reverseTriangleMesh, validateTriangleMesh, } from "../../mesh/mesh.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits } from "../../model-limits.js";
+import { resolveHelicalThreadMeshOptions, resolveHelicalThreadSolidMeshPreflight, } from "./mesh-plan.js";
+import { buildThreadSurfaceColumn, stitchThreadSurfaceColumns } from "./surface.js";
 const MINIMUM_TAPERED_RIDGE_HEIGHT = 0.0005;
 const buildThreadRidgeComponent = (options) => {
     const { profile } = options;
@@ -74,8 +74,8 @@ const buildThreadRidgeComponent = (options) => {
  * conservative pre-allocation estimate rejects excessive meshes before constructing position
  * arrays.
  */
-export function helicalThreadSolidMesh(options) {
-    const operation = "helicalThreadSolidMesh";
+export function threadSolidMesh(options) {
+    const operation = "threadSolidMesh";
     const { maximumAxialSegmentLength, resolved } = resolveHelicalThreadSolidMeshPreflight(options, operation);
     const positions = [];
     const columns = Array.from({ length: resolved.segments }, (_, column) => buildThreadSurfaceColumn(options.profile, resolved, options, resolved.phase + (column * 2 * Math.PI) / resolved.segments, maximumAxialSegmentLength, positions));
@@ -113,8 +113,8 @@ export function helicalThreadSolidMesh(options) {
  * shaft's radial/axial frame. The mesh is intended for union with its
  * minor-envelope cylinder and never owns WASM objects.
  */
-export function helicalThreadRidgeMesh(options) {
-    const operation = "helicalThreadRidgeMesh";
+export function threadRidgeMesh(options) {
+    const operation = "threadRidgeMesh";
     const resolved = resolveHelicalThreadMeshOptions(options, operation);
     const z0 = resolved.bottomBoundary - resolved.section[0][0];
     const z1 = resolved.topBoundary - resolved.section.at(-1)[0];

package/dist/geometry/mechanical/{thread-profiles.js → threads/profiles.js}

@@ -1,7 +1,7 @@
 /** Periodic thread profiles and axial/radial fit compensation. */
-import { GeometryError } from "../errors.js";
-import { triangulateContour } from "../loft/loft.js";
-import { resolveGeometryTolerance } from "../tolerance.js";
+import { GeometryError } from "../../errors.js";
+import { triangulateContour } from "../../loft/loft.js";
+import { resolveGeometryTolerance } from "../../tolerance.js";
 const BUTTRESS_DEFAULT_DEPTH_RATIO = 0.66271;
 const BUTTRESS_CREST_FLAT_RATIO = 0.16316;
 const BUTTRESS_PRESSURE_ANGLE_RADIANS = (7 * Math.PI) / 180;

package/dist/geometry/mechanical/{thread-solids.js → threads/solids.js}

@@ -1,24 +1,17 @@
-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";
+import { GeometryError } from "../../errors.js";
+import { resolveCircularSegments } from "../../resolution.js";
+import { resolveGeometryTolerance } from "../../tolerance.js";
+import { compensateThreadDiameters, preflightThreadSolidMesh, resolveThreadCircularSegments, } from "../index.js";
+import { resolveBevel } from "./bevel.js";
+import { compensateThreadProfileForFaceting, scaleThreadProfileRadially } from "./profiles.js";
 const THREAD_FACETING_MARGIN = 0.001;
-const resolveCompensatedThreadBevelSize = (options, role, compensated, style) => {
-    if (options.bevelSize !== undefined)
-        return options.bevelSize;
+const resolveCompensatedThreadBevelSize = (role, compensated, style, depth) => {
     if (style !== "blunt")
-        return options.profile.depth;
+        return 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,
@@ -36,16 +29,18 @@ export const resolveCompensatedThreadSolidMesh = (options, role) => {
     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 automatic = (dimensions, selectedRole) => [
+        resolveCompensatedThreadBevelSize(selectedRole, dimensions, bottomStyle, options.profile.depth),
+        resolveCompensatedThreadBevelSize(selectedRole, dimensions, topStyle, options.profile.depth),
+    ];
+    const bevel = resolveBevel(options.bevel, automatic(compensated, role), [0, 0], "threadedSolid");
+    const femaleBevel = resolveBevel(options.bevel, automatic(compensatedFemale, "female"), [0, 0], "threadedSolid");
     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 maxRadialOutset = Math.max(options.bevelBottom === true ? femaleBevelOutset(bottomStyle, femaleBottomBevelSize) : 0, options.bevelTop === true ? femaleBevelOutset(topStyle, femaleTopBevelSize) : 0);
+    const maxRadialOutset = Math.max(femaleBevelOutset(bottomStyle, femaleBevel[0]), femaleBevelOutset(topStyle, femaleBevel[1]));
     const segments = resolveThreadCircularSegments({
         nominalMajorDiameter: options.nominalMajorDiameter,
         profile: options.profile,
@@ -73,7 +68,7 @@ export const resolveCompensatedThreadSolidMesh = (options, role) => {
     // 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,
+        endLength: (requestedEnds.endLength ?? 0) + axialExtension,
         leadInEnvelope: role === "female" ? "major" : "minor",
     };
     return Object.freeze({
@@ -85,17 +80,14 @@ export const resolveCompensatedThreadSolidMesh = (options, role) => {
             majorDiameter,
             length: workingLength,
             resolution,
-            bevelBottomSize: bottomBevelSize,
+            bevel,
             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);
+const preflightCompensatedThreadSolid = (options, role) => preflightThreadSolidMesh(resolveCompensatedThreadSolidMesh(options, role).meshOptions);
 /**
  * Resolves compensated rod dimensions and checks conservative mesh estimates against output limits.
  *
@@ -103,8 +95,8 @@ const preflightCompensatedThreadSolid = (options, role) => preflightHelicalThrea
  * host execution. It creates planning data without mesh buffers or native objects; returned row
  * and triangle counts are estimates. Mesh validity and native construction are checked later.
  *
- * @see {@link preflightHelicalThreadSolidMesh}
- * @see {@link helicalThreadSolidMesh}
+ * See `mesh.preflightThreadSolid` for standalone mesh estimates.
+ * See `mesh.threadSolid` for standalone mesh construction.
  */
 export function preflightThreadedRodSolid(options) {
     return preflightCompensatedThreadSolid(options, "male");
@@ -117,8 +109,8 @@ export function preflightThreadedRodSolid(options) {
  * creates planning data without mesh buffers or native objects. Row and triangle counts are
  * estimates; mesh validity and native construction are checked later.
  *
- * @see {@link preflightHelicalThreadSolidMesh}
- * @see {@link helicalThreadSolidMesh}
+ * See `mesh.preflightThreadSolid` for standalone mesh estimates.
+ * See `mesh.threadSolid` for standalone mesh construction.
  */
 export function preflightInternalThreadCutterSolid(options) {
     return preflightCompensatedThreadSolid(options, "female");
@@ -137,27 +129,12 @@ export const resolveThreadedNutSolid = (options, 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"
@@ -165,73 +142,65 @@ export const resolveThreadedNutSolid = (options, operation) => {
             : 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 autoSize = Math.min(options.profile.depth, options.thickness / 4);
+    const automatic = [autoSize, autoSize];
+    const innerBevel = resolveBevel(options.innerBevel, automatic, automatic, operation, "innerBevel");
+    const outerBevel = resolveBevel(options.outerBevel, automatic, automatic, operation, "outerBevel");
+    for (const [parameter, sizes] of [
+        ["innerBevel", innerBevel],
+        ["outerBevel", outerBevel],
+    ]) {
+        if (sizes[0] + sizes[1] >= options.thickness) {
+            throw new GeometryError("DEGENERATE_GEOMETRY", "Nut bevels must leave a positive axial band.", {
+                operation,
+                details: { parameter, 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 cutter = resolveCompensatedThreadSolidMesh({ ...options, length: options.thickness, bevel: innerBevel }, "female");
+    const bodyFaceInradius = (size) => (outerRadius - size) * sideCosine;
+    const bottomBodyFaceInradius = bodyFaceInradius(outerBevel[0]);
+    const topBodyFaceInradius = bodyFaceInradius(outerBevel[1]);
     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 cutterFaceRadiusFor = (style, size) => cutterMajorRadius + (style === "blunt" ? size : Math.max(0, size - options.profile.depth));
+    const bottomCutterFaceRadius = cutterFaceRadiusFor(options.ends?.bottom ?? "blunt", innerBevel[0]);
+    const topCutterFaceRadius = cutterFaceRadiusFor(options.ends?.top ?? "blunt", innerBevel[1]);
     const cutterFaceRadius = Math.max(bottomCutterFaceRadius, topCutterFaceRadius);
-    const minimumFaceWall = Math.min(bottomBodyFaceInradius - bottomCutterFaceRadius, topBodyFaceInradius - topCutterFaceRadius);
+    const bottomFaceWall = bottomBodyFaceInradius - bottomCutterFaceRadius;
+    const topFaceWall = topBodyFaceInradius - topCutterFaceRadius;
+    const minimumFaceWall = Math.min(bottomFaceWall, topFaceWall);
     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;
+        const end = bottomFaceWall <= topFaceWall ? 0 : 1;
+        const parameter = outerBevel[end] > 0 ? "outerBevel" : innerBevel[end] > 0 ? "innerBevel" : "width";
+        const chamferIsActive = parameter !== "width";
         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,
+                innerBottomBevel: innerBevel[0],
+                innerTopBevel: innerBevel[1],
+                outerBottomBevel: outerBevel[0],
+                outerTopBevel: outerBevel[1],
                 cutterFaceRadius,
                 minimumBodyFaceInradius,
                 minimumFaceWall,
-                parameter: chamferIsActive ? "chamferSize" : "width",
+                parameter,
                 reason: "insufficient-face-annulus",
                 requiredFaceWall,
             },
         });
     }
-    const thread = preflightHelicalThreadSolidMesh(cutter.meshOptions);
+    const thread = preflightThreadSolidMesh(cutter.meshOptions);
     return Object.freeze({
-        bevelBottom,
-        bevelTop,
         cutter,
         outerRadius,
         preflight: Object.freeze({
             bodySegments: segments,
-            chamferSize,
+            innerBevel,
+            outerBevel,
             cutterFaceRadius,
             minimumBodyFaceInradius,
             minimumFaceWall,
@@ -248,7 +217,7 @@ export const resolveThreadedNutSolid = (options, operation) => {
  * `thread` contains conservative cutter estimates, excluding the body and Boolean result.
  * Successful preflight leaves mesh validity, native construction, and manufacturing fit to later checks.
  *
- * @see {@link preflightHelicalThreadSolidMesh}
+ * See `mesh.preflightThreadSolid` for standalone mesh estimates.
  */
 export function preflightThreadedNutSolid(options) {
     return resolveThreadedNutSolid(options, "preflightThreadedNutSolid").preflight;

package/dist/geometry/mechanical/{thread-surface.js → threads/surface.js}

@@ -1,6 +1,6 @@
 /** 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";
+import { cross3, dot3, length3, subtract3 } from "../../math/vector3.js";
+import { applyThreadSurfaceBevel, requirePositiveThreadSurfaceRadius, threadSurfaceBevelBoundaryAt, } from "./mesh-plan.js";
 const threadLeadInScale = (progress, shape, leadInLength) => {
     if (shape === "cut")
         return progress > 0 ? { height: 1, width: 1 } : { height: 0, width: 1 };
@@ -140,20 +140,19 @@ export const buildThreadSurfaceColumn = (profile, resolved, options, angle, maxi
     };
     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 [bottomBevelSize, topBevelSize] = resolved.bevel;
     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) {
+    if (bottomBevelSize > 0) {
         fixedSamples.push(bevelOffset, bevelOffset + bottomBevelSize);
     }
-    if (options.bevelTop === true) {
+    if (topBevelSize > 0) {
         fixedSamples.push(resolved.length - bevelOffset - topBevelSize, resolved.length - bevelOffset);
     }
-    if (options.bevelBottom === true && options.bevelTop === true) {
+    if (bottomBevelSize > 0 && topBevelSize > 0) {
         const bottomBevelEnd = bevelOffset + bottomBevelSize;
         const topBevelStart = resolved.length - bevelOffset - topBevelSize;
         if (bottomBevelEnd >= topBevelStart) {
@@ -348,7 +347,7 @@ export const buildThreadSurfaceColumn = (profile, resolved, options, angle, maxi
     let previousZ;
     for (const sample of sampled) {
         const radius = radiusAt(sample, sample.z);
-        requirePositiveThreadSurfaceRadius(radius, resolved, "helicalThreadSolidMesh");
+        requirePositiveThreadSurfaceRadius(radius, resolved, "threadSolidMesh");
         if (previousRadius !== undefined &&
             previousZ !== undefined &&
             Math.abs(sample.z - previousZ) <= resolved.tolerance.linear &&