@metamesh/modeling 0.17.0 → 0.18.0

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 &&

package/dist/geometry/mesh/mesh-centroid.js

@@ -1,17 +1,18 @@
 import { GeometryError } from "../errors.js";
+import { immutableMeshView } from "../immutable-buffer.js";
 import { analyzeTriangleMesh } from "./mesh.js";
 /**
  * Computes the uniform-density volume centroid of an oriented closed solid, including cavity shells.
  *
  * Coordinates are millimetres. Indexed closure and positive aggregate volume are required; callers
- * may use validateSolidMesh first when geometric intersections and shell orientation are untrusted.
+ * may use mesh.validateSolid first when geometric intersections and shell orientation are untrusted.
  * Fresh mutable input is inspected on every call, and buffers are never changed.
  *
  * @param mesh - Consistently oriented closed mesh with positive enclosed volume.
  * @returns A fresh immutable XYZ volume centroid.
  */
 export function computeTriangleMeshCentroid(mesh) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const source = immutableMeshView(mesh);
     const facts = analyzeTriangleMesh(source, { requireClosed: true });
     if (!(facts.signedVolume > 0))
         throw new GeometryError("INVALID_TOPOLOGY", "A volume centroid requires positive oriented volume.", { operation: "computeTriangleMeshCentroid" });

package/dist/geometry/mesh/mesh-planar.js

@@ -1,4 +1,5 @@
 import { GeometryError } from "../errors.js";
+import { immutableMeshView, isImmutableBuffer } from "../immutable-buffer.js";
 import { buildTriangleMeshQualityAnalysis, } from "./mesh-quality.js";
 const DEFAULT_MAXIMUM_FLIP_ATTEMPTS = 1_000_000;
 const DEFAULT_MAXIMUM_PATCH_TRIANGLE_COUNT = 50_000;
@@ -165,19 +166,37 @@ const fallbackReasonForCandidate = (before, after, boundaryEdgeKeys) => {
  * The operation changes indices only: it never moves, adds, welds, or removes vertices; never
  * crosses a coplanar-patch boundary; and never changes the face count. Each accepted flip improves
  * a deterministic ordering of triangle angles, aspect ratio, diagonal locality, and local
- * incidence/valence concentration. Unsupported input or a failed final integrity check returns the
- * exact original mesh object. Malformed buffers and the configured analysis complexity limit throw.
+ * incidence/valence concentration. Unsupported input or a failed final integrity check preserves the
+ * original raw mesh object. Immutable inputs produce owned raw output buffers, including unchanged
+ * results. Malformed buffers and the configured analysis complexity limit throw.
  *
  * @param mesh - Closed, consistently wound indexed triangle mesh in arbitrary consistent units.
  * @param options - Patch eligibility, numeric tolerance, and deterministic work bounds.
  * @returns Optimized connectivity and before/after diagnostics, or an unchanged safe fallback.
  */
 export function optimizePlanarPatches(mesh, options = {}) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const { positions, indices } = mesh;
+    const immutable = isImmutableBuffer(positions) || isImmutableBuffer(indices);
+    const source = immutableMeshView({ positions, indices });
+    const result = optimizePlanarMesh(source, options);
+    // Raw numerical outputs may alias caller-owned raw inputs, never immutable private storage.
+    return !immutable
+        ? result.changed
+            ? result
+            : { ...result, mesh: mesh }
+        : {
+            ...result,
+            mesh: {
+                positions: new Float32Array(result.mesh.positions),
+                indices: new Uint32Array(result.mesh.indices),
+            },
+        };
+}
+function optimizePlanarMesh(source, options) {
     const resolved = resolveOptions(options);
     const before = buildTriangleMeshQualityAnalysis(source, options);
     if (!before.report.isClosedOrientedManifold) {
-        return unchangedResult(mesh, before.report, 0, false, "input-not-closed-oriented-manifold");
+        return unchangedResult(source, before.report, 0, false, "input-not-closed-oriented-manifold");
     }
     const selectedPatchIds = new Set();
     const boundaryEdgeKeys = new Set();
@@ -199,7 +218,7 @@ export function optimizePlanarPatches(mesh, options = {}) {
             boundaryEdgeKeys.add(key);
     }
     if (selectedPatchIds.size === 0) {
-        return unchangedResult(mesh, before.report, skippedPatchCount, budgetExhausted);
+        return unchangedResult(source, before.report, skippedPatchCount, budgetExhausted);
     }
     const triangles = before.faces.map(({ vertices }) => [...vertices]);
     const edges = new Map();
@@ -226,7 +245,7 @@ export function optimizePlanarPatches(mesh, options = {}) {
     const maxFlipAttempts = resolved.maxFlipAttempts ??
         Math.min(DEFAULT_MAXIMUM_FLIP_ATTEMPTS, initialEdges.length * ATTEMPTS_PER_INITIAL_EDGE);
     if (maxFlipAttempts === 0) {
-        return unchangedResult(mesh, before.report, skippedPatchCount, budgetExhausted);
+        return unchangedResult(source, before.report, skippedPatchCount, budgetExhausted);
     }
     const queue = initialEdges.map(({ key }) => key);
     const queued = new Set(queue);
@@ -382,7 +401,7 @@ export function optimizePlanarPatches(mesh, options = {}) {
     if (queueOffset < queue.length)
         budgetExhausted = true;
     if (flipCount === 0) {
-        return unchangedResult(mesh, before.report, skippedPatchCount, budgetExhausted);
+        return unchangedResult(source, before.report, skippedPatchCount, budgetExhausted);
     }
     const indices = new Uint32Array(source.indices.length);
     for (let faceIndex = 0; faceIndex < triangles.length; faceIndex += 1) {
@@ -392,7 +411,7 @@ export function optimizePlanarPatches(mesh, options = {}) {
     const after = buildTriangleMeshQualityAnalysis(candidate, options);
     const fallbackReason = fallbackReasonForCandidate(before, after, boundaryEdgeKeys);
     if (fallbackReason !== undefined) {
-        return unchangedResult(mesh, before.report, skippedPatchCount, budgetExhausted, fallbackReason);
+        return unchangedResult(source, before.report, skippedPatchCount, budgetExhausted, fallbackReason);
     }
     return {
         after: after.report,

package/dist/geometry/mesh/mesh-quality.js

@@ -1,4 +1,5 @@
 import { GeometryError } from "../errors.js";
+import { immutableMeshView } from "../immutable-buffer.js";
 import { resolveGeometryTolerance, } from "../tolerance.js";
 const DEFAULT_MAXIMUM_TRIANGLE_COUNT = 200_000;
 const FLOAT32_EPSILON = 2 ** -23;
@@ -235,7 +236,7 @@ const buildPatchAnalysis = (faces, edges, faceIndices, id) => {
 };
 /** @internal */
 export function buildTriangleMeshQualityAnalysis(mesh, options = {}) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const source = immutableMeshView(mesh);
     const maxTriangles = positiveInteger(options.maxTriangles ?? DEFAULT_MAXIMUM_TRIANGLE_COUNT, "Maximum analyzed triangle count");
     structurallyValidateMesh(source, maxTriangles);
     const { bounds, extent } = meshBoundsAndExtent(source.positions);