@metamesh/modeling 0.16.0 → 0.18.0

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);

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

@@ -1,4 +1,5 @@
 import { GeometryError } from "../errors.js";
+import { immutableMeshView } from "../immutable-buffer.js";
 import { analyzeTriangleMesh, validateTriangleMesh } from "./mesh.js";
 const DEFAULT_POSITION_TOLERANCE = 1e-5;
 const DEFAULT_VOLUME_TOLERANCE = 1e-4;
@@ -68,10 +69,10 @@ const hashCanonicalKeys = (header, groups) => {
  * @param mesh - Closed oriented mesh to measure without mutation.
  * @param options - Absolute quantization and complexity limits.
  * @returns Compact counts, bounds, volume, topology, tolerances, and canonical fingerprint.
- * @throws {@link GeometryError} When validation, topology, tolerance, or complexity checks fail.
+ * @throws `GeometryError` When validation, topology, tolerance, or complexity checks fail.
  */
 export function computeTriangleMeshSignature(mesh, options = {}) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const source = immutableMeshView(mesh);
     const maxTriangles = options.maxTriangles ?? DEFAULT_MAXIMUM_TRIANGLE_COUNT;
     if (!Number.isSafeInteger(maxTriangles) || maxTriangles <= 0) {
         throw new GeometryError("INVALID_ARGUMENT", "maxTriangles must be a positive safe integer.", {
@@ -92,14 +93,14 @@ export function computeTriangleMeshSignature(mesh, options = {}) {
     const positionTolerance = validatePositiveTolerance(options.positionTolerance ?? DEFAULT_POSITION_TOLERANCE, "positionTolerance");
     const volumeTolerance = validatePositiveTolerance(options.volumeTolerance ?? DEFAULT_VOLUME_TOLERANCE, "volumeTolerance");
     const measured = analyzeTriangleMesh(source, { requireClosed: true, includeTopology: true });
-    const connectedComponentCount = measured.connectedComponentCount;
+    const shellCount = measured.shellCount;
     const edgeCount = measured.edgeCount;
     const eulerCharacteristic = measured.vertexCount - edgeCount + measured.triangleCount;
-    const twiceGenus = connectedComponentCount * 2 - eulerCharacteristic;
+    const twiceGenus = shellCount * 2 - eulerCharacteristic;
     if (twiceGenus < 0 || twiceGenus % 2 !== 0) {
         throw new GeometryError("INVALID_TOPOLOGY", "Closed mesh topology does not describe orientable vertex-manifold components.", {
             operation: "computeTriangleMeshSignature",
-            details: { connectedComponentCount, edgeCount, eulerCharacteristic },
+            details: { shellCount, edgeCount, eulerCharacteristic },
         });
     }
     const coordinateKeys = Array.from({ length: measured.vertexCount }, (_, vertex) => coordinateKey(source.positions, vertex, positionTolerance));
@@ -127,7 +128,7 @@ export function computeTriangleMeshSignature(mesh, options = {}) {
     });
     return Object.freeze({
         bounds: quantizeBounds(measured.bounds),
-        connectedComponentCount,
+        shellCount,
         fingerprint: hashCanonicalKeys(`${measured.vertexCount}|${measured.triangleCount}|${positionTolerance}`, [vertexKeys, triangleKeys]),
         genus: twiceGenus / 2,
         signedVolume: quantizedScalar(measured.signedVolume, volumeTolerance, "Signed volume"),

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

@@ -1,4 +1,5 @@
 import { GeometryError } from "../errors.js";
+import { immutableMeshView } from "../immutable-buffer.js";
 import { resolveGeometryTolerance } from "../tolerance.js";
 import { IndexedMeshEdgeTable } from "./mesh-edge-table.js";
 import { prepareSolidTriangle, trianglesIntersectBeyondSharedBoundary, triangleSolidAngle, } from "./mesh-solid-intersections.js";
@@ -51,9 +52,7 @@ function validationWork(mesh, options) {
 }
 /** @internal Fresh measurements precede one adjacency traversal for closure, fans, and shells. */
 export function analyzeSolidMesh(mesh, options = {}) {
-    const source = typeof mesh === "object" && mesh !== null
-        ? { positions: mesh.positions, indices: mesh.indices }
-        : mesh;
+    const source = typeof mesh === "object" && mesh !== null ? immutableMeshView(mesh) : mesh;
     const work = validationWork(source, options);
     const measurements = analyzeTriangleMesh(source, {
         ...(options.tolerance === undefined ? {} : { tolerance: options.tolerance }),

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

@@ -0,0 +1 @@
+export {};

package/dist/geometry/mesh/mesh.js

@@ -1,12 +1,13 @@
 import { GeometryError } from "../errors.js";
+import { immutableMeshView } from "../immutable-buffer.js";
 import { writeMeshVertex } from "../numeric.js";
 import { resolveGeometryTolerance } from "../tolerance.js";
 import { readTransformMatrix } from "../transform-matrix.js";
 import { transformDeterminant3, validateTransform3 } from "../transform3.js";
 import { IndexedMeshEdgeTable } from "./mesh-edge-table.js";
 function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = false) {
-    // Snapshot meshes can expose owned-copy accessors. Read each buffer once before traversal.
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    // Normalize immutable storage and read raw input accessors once before traversal.
+    const source = immutableMeshView(mesh);
     const measurements = mode === "measure";
     if (!(source.positions instanceof Float32Array) || !(source.indices instanceof Uint32Array)) {
         throw new GeometryError("INVALID_MESH", "Triangle meshes require Float32Array positions and Uint32Array indices.");
@@ -43,7 +44,7 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
     const parents = topology ? new Int32Array(triangleCount) : null;
     const ranks = topology ? new Uint8Array(triangleCount) : null;
     const referenced = topology ? new Uint8Array(vertexCount) : null;
-    let connectedComponentCount = 0;
+    let shellCount = 0;
     const root = (triangle) => {
         let current = triangle;
         while (parents[current] !== current)
@@ -64,7 +65,7 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
         parents[right] = left;
         if (ranks[left] === ranks[right])
             ranks[left] = ranks[left] + 1;
-        connectedComponentCount -= 1;
+        shellCount -= 1;
     };
     let edgeCount = 0;
     const addEdge = (a, b, triangle) => {
@@ -113,7 +114,7 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
             const triangle = offset / 3;
             parents[triangle] = triangle;
             referenced[a] = referenced[b] = referenced[c] = 1;
-            connectedComponentCount += 1;
+            shellCount += 1;
         }
         if (edges !== null) {
             addEdge(a, b, offset / 3);
@@ -143,19 +144,9 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
         surfaceArea: surfaceArea + areaCorrection,
         triangleCount,
         vertexCount,
-        ...(topology ? { connectedComponentCount, edgeCount } : {}),
+        ...(topology ? { shellCount, edgeCount } : {}),
     });
 }
-/**
- * Validates and measures a mesh in one position and one triangle traversal.
- *
- * Bounds, area in square model units and signed volume in cubic model units are computed without
- * copying or changing the input buffers. Volume is meaningful for consistently wound closed
- * geometry; `requireClosed` checks oriented edge closure. Optional indexed topology counts require
- * every position vertex to be referenced and do not establish freedom from self-intersections.
- * Results and nested bounds are immutable snapshots. Caller-owned mutable meshes are freshly
- * inspected on every call, never cached.
- */
 export function analyzeTriangleMesh(mesh, options = {}) {
     return inspectTriangleMesh(mesh, options, "measure", options.includeTopology ?? false);
 }
@@ -169,7 +160,7 @@ export function analyzeTriangleMesh(mesh, options = {}) {
  * @param mesh - Mesh to inspect.
  * @param options - Empty-mesh, topology, and tolerance policy.
  * @returns The original mesh after successful validation.
- * @throws {@link GeometryError} When any requested invariant fails.
+ * @throws `GeometryError` When any requested invariant fails.
  */
 export function validateTriangleMesh(mesh, options = {}) {
     inspectTriangleMesh(mesh, options);
@@ -180,7 +171,7 @@ export function validateTriangleMesh(mesh, options = {}) {
  *
  * @param mesh - Mesh whose finite complete vertices will be measured.
  * @returns Fresh immutable minimum and maximum XYZ tuples.
- * @throws {@link GeometryError} When the mesh is structurally invalid.
+ * @throws `GeometryError` When the mesh is structurally invalid.
  */
 export const meshBounds = (mesh) => {
     return inspectTriangleMesh(mesh, {}, "bounds");
@@ -192,10 +183,10 @@ export const meshBounds = (mesh) => {
  *
  * @param meshes - One or more meshes to concatenate.
  * @returns Fresh typed arrays with indices offset to their source vertex ranges.
- * @throws {@link GeometryError} When no mesh is supplied or an input is invalid.
+ * @throws `GeometryError` When no mesh is supplied or an input is invalid.
  */
 export function joinTriangleMeshes(meshes) {
-    const sources = meshes.map(({ positions, indices }) => ({ positions, indices }));
+    const sources = meshes.map((mesh) => immutableMeshView(mesh));
     if (sources.length === 0) {
         throw new GeometryError("INVALID_ARGUMENT", "Joining meshes requires at least one mesh.");
     }
@@ -228,7 +219,7 @@ export function joinTriangleMeshes(meshes) {
  * @returns Fresh position and index buffers; the input remains unchanged.
  */
 export function reverseTriangleMesh(mesh) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const source = immutableMeshView(mesh);
     validateTriangleMesh(source);
     const indices = new Uint32Array(source.indices);
     for (let offset = 0; offset < indices.length; offset += 3) {
@@ -249,7 +240,7 @@ export function reverseTriangleMesh(mesh) {
  * @returns A mesh with fresh transformed positions and copied or reversed indices.
  */
 export function transformTriangleMesh(mesh, placement) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const source = immutableMeshView(mesh);
     validateTriangleMesh(source);
     const transform = readTransformMatrix(placement, 3);
     validateTransform3(transform);

package/dist/geometry/mesh-api.js

@@ -0,0 +1,14 @@
+/** Pure triangle mesh construction, processing, and inspection without a host engine. */
+export { extrudeMesh as extrude, loftMesh as loft } from "./loft/loft.js";
+export { revolveMesh as revolve } from "./revolve/revolve-mesh.js";
+export { sweepMesh as sweep } from "./sweeps/sweep-mesh.js";
+export { heightfieldMesh as heightfield, preflightHeightfield } from "./heightfield.js";
+export { threadRidgeMesh as threadRidge, threadSolidMesh as threadSolid, } from "./mechanical/threads/mesh.js";
+export { preflightThreadSolidMesh as preflightThreadSolid } from "./mechanical/threads/mesh-plan.js";
+export { transformTriangleMesh as transform, joinTriangleMeshes as join, reverseTriangleMesh as reverse, meshBounds as bounds, analyzeTriangleMesh as analyze, validateTriangleMesh as validate, } from "./mesh/mesh.js";
+export { computeTriangleMeshCentroid as centroid } from "./mesh/mesh-centroid.js";
+export { analyzeTriangleMeshQuality as analyzeQuality } from "./mesh/mesh-quality.js";
+export { computeTriangleMeshSignature as signature } from "./mesh/mesh-signature.js";
+export { validateSolidMesh as validateSolid } from "./mesh/mesh-solid.js";
+export { optimizePlanarPatches } from "./mesh/mesh-planar.js";
+export { immutableMesh as immutable } from "./immutable-buffer.js";