@metamesh/modeling 0.6.0 → 0.8.0

package/dist/engine/native/distance.js

@@ -0,0 +1,42 @@
+import { GeometryError } from "../../geometry/errors.js";
+import { assertNativeSolidStatus } from "./status.js";
+/** Internal minimum separation query; never exposes the kernel's capped search result. */
+export function measureSolidDistance(left, right) {
+    assertNativeSolidStatus(left, "distance");
+    assertNativeSolidStatus(right, "distance");
+    if (left.isEmpty() || right.isEmpty())
+        throw new GeometryError("DEGENERATE_GEOMETRY", "Distance requires nonempty solids.", {
+            operation: "distance",
+        });
+    const a = left.boundingBox(), b = right.boundingBox();
+    const axes = [0, 1, 2];
+    const lower = Math.hypot(...axes.map((i) => Math.max(0, a.min[i] - b.max[i], b.min[i] - a.max[i])));
+    const upper = Math.hypot(...axes.map((i) => Math.max(Math.abs(a.min[i] - b.max[i]), Math.abs(a.max[i] - b.min[i]))));
+    const diagonal = Math.max(Math.hypot(...axes.map((i) => a.max[i] - a.min[i])), Math.hypot(...axes.map((i) => b.max[i] - b.min[i])));
+    const scale = Math.max(upper, ...[...a.min, ...a.max, ...b.min, ...b.max].map(Math.abs));
+    const padding = Math.max(Math.sqrt(Number.MIN_VALUE) * 2, scale * Number.EPSILON * 8);
+    const maximum = upper + padding;
+    if (!Number.isFinite(maximum * maximum) || maximum <= 0)
+        throw new GeometryError("NON_FINITE_VALUE", "Distance exceeds the kernel's numeric range.", {
+            operation: "distance",
+        });
+    // A modest extent-based seed avoids many tiny searches for very unequal shapes.
+    // A full bounding-box diagonal would make the kernel visit unnecessary triangle pairs.
+    let radius = Math.min(maximum, Math.max(lower + padding, diagonal / 32, padding));
+    for (;;) {
+        const value = left.minGap(right, radius);
+        // The kernel takes sqrt(radius²) when capped; that can round below radius.
+        const capSlack = Math.max(Math.sqrt(Number.MIN_VALUE), radius * Number.EPSILON * 4);
+        if (!Number.isFinite(value) || value < 0 || value > radius + capSlack)
+            throw new GeometryError("NON_FINITE_VALUE", "The kernel returned an invalid distance.", {
+                operation: "distance",
+            });
+        if (value < radius - capSlack)
+            return value;
+        if (radius === maximum)
+            throw new GeometryError("INVALID_MESH", "The kernel could not resolve the minimum distance.", {
+                operation: "distance",
+            });
+        radius = Math.min(maximum, radius * 2);
+    }
+}

package/dist/engine/native/status.js

@@ -0,0 +1,16 @@
+import { GeometryError } from "../../geometry/errors.js";
+/** Checks an already required native evaluation without exposing upstream status types publicly. */
+export function assertNativeSolidStatus(native, operation) {
+    const status = native.status();
+    if (status === "NoError")
+        return;
+    const code = status === "NonFiniteVertex"
+        ? "NON_FINITE_VALUE"
+        : status === "ResultTooLarge"
+            ? "COMPLEXITY_LIMIT"
+            : "INVALID_TOPOLOGY";
+    throw new GeometryError(code, `The geometry kernel rejected the solid: ${status}.`, {
+        operation,
+        details: { nativeStatus: status },
+    });
+}

package/dist/engine/operation-environment.js

@@ -3,7 +3,8 @@ import { resolveCircularPrimitiveSegments } from "../geometry/primitive-resoluti
 /** Applies explicit resolution inheritance once for this bound context. */
 export function createOperationEnvironment(owner, resolution) {
     const withResolutionDefaults = (value) => {
-        const limits = resolveModelingLimits(value.limits, owner.limits);
+        const overrides = value.limits;
+        const limits = overrides === undefined ? owner.limits : resolveModelingLimits(overrides, owner.limits);
         return {
             ...value,
             resolution: {

package/dist/engine/section-operations.js

@@ -5,7 +5,7 @@ import { sampleTextContours } from "../geometry/text-contours.js";
 import * as kernel from "./native/index.js";
 /** Internal host-bound section operations. */
 export function createSectionOperations(environment, transforms) {
-    const { module, limits, scope, assertActive, throwGeometryError, nativeSolid, nativeSection, wrapSection, ownSection, validateFiniteNumber, requirePositiveNumber, validateCoordinates, assertOperandCount, withResolutionDefaults, resolveCircularSegments, } = environment;
+    const { module, limits, scope, assertActive, throwGeometryError, nativeSolid, nativeSection, wrapSection, ownSection, validateFiniteNumber, validateCoordinates, assertOperandCount, withResolutionDefaults, resolveCircularSegments, } = environment;
     const { translate } = transforms.operations;
     const fromContours = (contours, value = {}) => {
         assertActive();
@@ -51,8 +51,8 @@ export function createSectionOperations(environment, transforms) {
             const join = value.join ?? "round";
             if (!["round", "miter", "square"].includes(join))
                 throwGeometryError("INVALID_ARGUMENT", "offset", "Unsupported offset join.");
-            if (value.miterLimit !== undefined)
-                requirePositiveNumber(value.miterLimit, "offset");
+            if (value.miterLimit !== undefined && validateFiniteNumber(value.miterLimit, "offset") < 2)
+                throwGeometryError("INVALID_ARGUMENT", "offset", "miterLimit must be at least two.");
             return ownSection(native.offset(distance, join === "round" ? "Round" : join === "miter" ? "Miter" : "Square", value.miterLimit, resolveCircularSegments(Math.max(Math.abs(distance), 0.001), {
                 ...(value.circularSegments === undefined ? {} : { segments: value.circularSegments }),
                 ...(value.resolution === undefined ? {} : { resolution: value.resolution }),

package/dist/geometry/curves/sampling.js

@@ -224,7 +224,8 @@ function sampleCurve(curve, options, createWriter) {
             return curveFailure("INVALID_ARGUMENT", "Unsupported curve kind.");
     }
 }
-/** Samples a spatial curve, preserving endpoints and directed unit tangents.
+/**
+ * Samples a spatial curve, preserving endpoints and directed unit tangents.
  * @remarks Exact counts use uniform curve parameters, not equal physical distances. Adaptive cubics
  * bound the full control hull. Full-circle arcs repeat their endpoint; closed polylines do not.
  * @example

package/dist/geometry/heightfield.js

@@ -1,57 +1,108 @@
 import { GeometryError } from "./errors.js";
 import { validateTriangleMesh } from "./mesh.js";
-import { defaultModelingLimits } from "./model-limits.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "./model-limits.js";
 import { writeMeshVertex } from "./numeric.js";
-const isArray = (value) => Array.isArray(value);
-/** Checks regular-grid dimensions and bounds allocation before evaluating any height samples. */
-export function preflightHeightfield(options, limits = {}) {
+function planHeightfield(options, limits) {
     const operation = "preflightHeightfield";
     if (typeof options !== "object" ||
         options === null ||
-        !isArray(options.size) ||
-        options.size.length !== 2 ||
-        !options.size.every((value) => Number.isFinite(value) && value > 0) ||
-        !isArray(options.segments) ||
-        options.segments.length !== 2 ||
-        !options.segments.every((value) => Number.isSafeInteger(value) && value > 0) ||
         typeof options.height !== "function" ||
         !Number.isFinite(options.baseZ ?? 0) ||
-        (options.origin !== undefined &&
-            (!isArray(options.origin) ||
-                options.origin.length !== 2 ||
-                !options.origin.every(Number.isFinite)))) {
-        throw new GeometryError("INVALID_ARGUMENT", "Heightfields need a finite positive footprint, integer intervals, finite base, and a height callback.", { operation });
+        (options.triangulation !== undefined &&
+            !["fixed", "min-edge", "center-error"].includes(options.triangulation))) {
+        throw new GeometryError("INVALID_ARGUMENT", "Heightfields need a finite base, height callback, and supported triangulation policy.", { operation });
+    }
+    let x, y;
+    let xAt, yAt;
+    if (options.coordinates !== undefined) {
+        const coordinates = options.coordinates;
+        if (typeof coordinates !== "object" ||
+            coordinates === null ||
+            !Array.isArray(coordinates.x) ||
+            !Array.isArray(coordinates.y) ||
+            coordinates.x.length < 2 ||
+            coordinates.y.length < 2 ||
+            options.size !== undefined ||
+            options.segments !== undefined ||
+            options.origin !== undefined) {
+            throw new GeometryError("INVALID_ARGUMENT", "Explicit heightfield coordinates need two or more samples per axis and cannot include size, segments, or origin.", { operation });
+        }
+        x = coordinates.x.length - 1;
+        y = coordinates.y.length - 1;
+        xAt = (index) => coordinates.x[index];
+        yAt = (index) => coordinates.y[index];
+    }
+    else {
+        if (!Array.isArray(options.size) ||
+            options.size.length !== 2 ||
+            !options.size.every((value) => Number.isFinite(value) && value > 0) ||
+            !Array.isArray(options.segments) ||
+            options.segments.length !== 2 ||
+            !options.segments.every((value) => Number.isSafeInteger(value) && value > 0) ||
+            (options.origin !== undefined &&
+                (!Array.isArray(options.origin) ||
+                    options.origin.length !== 2 ||
+                    !options.origin.every(Number.isFinite)))) {
+            throw new GeometryError("INVALID_ARGUMENT", "Uniform heightfields need a finite positive footprint, integer intervals, and finite origin.", { operation });
+        }
+        [x, y] = options.segments;
+        const [width, depth] = options.size;
+        const [originX, originY] = options.origin ?? [-width / 2, -depth / 2];
+        xAt = (index) => originX + (width * index) / x;
+        yAt = (index) => originY + (depth * index) / y;
     }
-    const [x, y] = options.segments;
     const sampleCount = (x + 1) * (y + 1);
     const perimeter = 2 * (x + y);
     const vertexCount = sampleCount + perimeter + 1;
     const triangleCount = 2 * x * y + 3 * perimeter;
     const byteCount = 12 * (vertexCount + triangleCount);
-    const policy = { ...defaultModelingLimits, ...limits };
-    if (![policy.maxVertices, policy.maxTriangles, policy.maxBytes].every((value) => Number.isSafeInteger(value) && value > 0))
-        throw new GeometryError("INVALID_ARGUMENT", "Heightfield ceilings must be positive safe integers.", { operation });
-    if (!Number.isSafeInteger(byteCount) ||
-        vertexCount > 0xffff_ffff ||
-        triangleCount * 3 > 0xffff_ffff ||
-        vertexCount > policy.maxVertices ||
-        triangleCount > policy.maxTriangles ||
-        byteCount > policy.maxBytes) {
-        throw new GeometryError("COMPLEXITY_LIMIT", "Heightfield grid exceeds the configured output limits or numeric index ceiling.", { operation });
+    assertMeshAllocationWithinLimits(vertexCount, triangleCount, byteCount, operation, resolveModelingLimits(limits));
+    for (const [axis, count, at] of [
+        ["x", x, xAt],
+        ["y", y, yAt],
+    ]) {
+        let previous = -Infinity;
+        for (let index = 0; index <= count; index += 1) {
+            const coordinate = Math.fround(at(index));
+            if (!Number.isFinite(coordinate) || !(coordinate > previous))
+                throw new GeometryError("INVALID_ARGUMENT", "Heightfield axes must be finite, strictly increasing, and distinct in Float32 storage.", { operation, details: { axis, index } });
+            previous = coordinate;
+        }
     }
-    return Object.freeze({ sampleCount, vertexCount, triangleCount, byteCount });
+    return {
+        x,
+        y,
+        xAt,
+        yAt,
+        facts: Object.freeze({ sampleCount, vertexCount, triangleCount, byteCount }),
+    };
+}
+/** Checks grid dimensions, coordinate precision, and allocation bounds before evaluating heights. */
+export function preflightHeightfield(options, limits = {}) {
+    return planHeightfield(options, limits).facts;
 }
 /**
- * Builds a closed indexed solid from a regularly sampled top, matched boundary walls, and flat base.
- * Heights are evaluated once per grid point after allocation preflight. Physical XY sizes and all
- * output coordinates must fit Float32 storage. Shared wall vertices prevent cracks at the base.
+ * Builds a closed indexed mesh from a rectilinear top, matched boundary walls, and flat base.
+ * Heights run once per grid point after preflight; center-error adds one evaluation per cell.
+ * Top winding is +Z, the base is -Z, and sides face outward. Coordinates and heights must fit
+ * Float32 storage. Explicit axes are captured before sampling; shared wall vertices prevent cracks.
+ *
+ * @example Sample a closed wavy mesh
+ * ```ts
+ * heightfieldMesh({
+ *   size: [30, 20], segments: [24, 16],
+ *   height: ([x, y]) => 3 + Math.cos(x / 5) * Math.cos(y / 5),
+ * });
+ * ```
  */
 export function heightfieldMesh(options, limits = {}) {
-    const facts = preflightHeightfield(options, limits);
+    const plan = planHeightfield(options, limits);
+    const { facts, x: nx, y: ny } = plan;
     const operation = "heightfieldMesh";
-    const [nx, ny] = options.segments;
-    const [width, depth] = options.size;
-    const [originX, originY] = options.origin ?? [-width / 2, -depth / 2];
+    const xs = Array.from({ length: nx + 1 }, (_, index) => plan.xAt(index));
+    const ys = Array.from({ length: ny + 1 }, (_, index) => plan.yAt(index));
+    const triangulation = options.triangulation ?? "fixed";
+    const heightAt = options.height;
     const baseZ = Math.fround(options.baseZ ?? 0);
     if (!Number.isFinite(baseZ))
         throw new GeometryError("NON_FINITE_VALUE", "Heightfield base must fit Float32 storage.", {
@@ -60,13 +111,16 @@ export function heightfieldMesh(options, limits = {}) {
     const positions = new Float32Array(facts.vertexCount * 3);
     const indices = new Uint32Array(facts.triangleCount * 3);
     const grid = (x, y) => y * (nx + 1) + x;
+    const sampleHeight = (point) => {
+        const height = Math.fround(heightAt(point));
+        if (!Number.isFinite(height) || !(height > baseZ))
+            throw new GeometryError("INVALID_ARGUMENT", "Every finite Float32 height must be strictly above the Float32 base.", { operation, details: { x: point[0], y: point[1] } });
+        return height;
+    };
     for (let y = 0; y <= ny; y += 1) {
         for (let x = 0; x <= nx; x += 1) {
-            const point = [originX + (width * x) / nx, originY + (depth * y) / ny];
-            const height = Math.fround(options.height(point));
-            if (!Number.isFinite(height) || !(height > baseZ)) {
-                throw new GeometryError("INVALID_ARGUMENT", "Every finite Float32 height must be strictly above the Float32 base.", { operation, details: { x, y } });
-            }
+            const point = [xs[x], ys[y]];
+            const height = sampleHeight(point);
             writeMeshVertex(positions, grid(x, y) * 3, [point[0], point[1], height], operation);
         }
     }
@@ -79,8 +133,21 @@ export function heightfieldMesh(options, limits = {}) {
     for (let y = 0; y < ny; y += 1) {
         for (let x = 0; x < nx; x += 1) {
             const a = grid(x, y), b = grid(x + 1, y), c = grid(x + 1, y + 1), d = grid(x, y + 1);
-            triangle(a, b, c);
-            triangle(a, c, d);
+            const za = positions[a * 3 + 2], zb = positions[b * 3 + 2], zc = positions[c * 3 + 2], zd = positions[d * 3 + 2];
+            // Rectangular XY cells have equal XY diagonal lengths, so only Z differs.
+            let alternate = triangulation === "min-edge" && Math.abs(zb - zd) < Math.abs(za - zc);
+            if (triangulation === "center-error") {
+                const centre = sampleHeight([(xs[x] + xs[x + 1]) / 2, (ys[y] + ys[y + 1]) / 2]);
+                alternate = Math.abs((zb + zd) / 2 - centre) < Math.abs((za + zc) / 2 - centre);
+            }
+            if (alternate) {
+                triangle(a, b, d);
+                triangle(b, c, d);
+            }
+            else {
+                triangle(a, b, c);
+                triangle(a, c, d);
+            }
         }
     }
     const boundary = [];
@@ -94,7 +161,7 @@ export function heightfieldMesh(options, limits = {}) {
         boundary.push(grid(0, y));
     const baseStart = facts.sampleCount;
     const baseCenter = facts.vertexCount - 1;
-    writeMeshVertex(positions, baseCenter * 3, [originX + width / 2, originY + depth / 2, baseZ], operation);
+    writeMeshVertex(positions, baseCenter * 3, [(xs[0] + xs[nx]) / 2, (ys[0] + ys[ny]) / 2, baseZ], operation);
     for (let offset = 0; offset < boundary.length; offset += 1) {
         const top = boundary[offset];
         writeMeshVertex(positions, (baseStart + offset) * 3, [positions[top * 3], positions[top * 3 + 1], baseZ], operation);

package/dist/geometry/index.js

@@ -1,4 +1,6 @@
 /** Pure geometry foundations without host initialization. @packageDocumentation */
+export { validateSolidMesh } from "./mesh-solid.js";
+export { computeTriangleMeshCentroid } from "./mesh-centroid.js";
 export { matchProfiles, } from "./profiles/matched.js";
 export { heightfieldMesh, preflightHeightfield, } from "./heightfield.js";
 export { preflightThreadedRodSolid as preflightThreadedRod, preflightInternalThreadCutterSolid as preflightInternalThreadCutter, preflightThreadedNutSolid as preflightThreadedNut, } from "./mechanical/thread-solids.js";

package/dist/geometry/loft-simple-mesh.js

@@ -1,15 +1,14 @@
 import { GeometryError } from "./errors.js";
 import { triangulateLoop2 } from "./loft-triangulation.js";
 import { measureTriangleMesh, validateTriangleMesh } from "./mesh.js";
-import { assertMeshAllocationWithinLimits, } from "./model-limits.js";
+import { assertMeshAllocationWithinLimits } from "./model-limits.js";
 import { writeMeshVertex } from "./numeric.js";
 /** @internal Pure closed simple-contour strips, retaining repeated correspondence slots as shared physical vertices. */
-export function simpleLoftMesh(geometry, limits, allocationGuard) {
+export function simpleLoftMesh(geometry, limits) {
     const count = geometry.world[0][0].length, rowCount = geometry.world.length;
     const maximumVertices = count * rowCount, maximumTriangles = 2 * count * (rowCount - 1) + 2 * (count - 2);
     const bytes = 12 * (maximumVertices + maximumTriangles);
     assertMeshAllocationWithinLimits(maximumVertices, maximumTriangles, bytes, "loftMesh", limits);
-    allocationGuard?.(maximumVertices, maximumTriangles, bytes, "loftMesh");
     const positions = new Float32Array(maximumVertices * 3), indices = new Uint32Array(maximumTriangles * 3);
     let vertexCount = 0, cursor = 0;
     const rows = geometry.world.map((contours, row) => {

package/dist/geometry/loft-triangulation.js

@@ -11,6 +11,16 @@ const pointInTriangle = (point, a, b, c, epsilon) => {
 /** Ear-clips one normalized simple CCW loop into stable local vertex indices. */
 export function triangulateLoop2(loop) {
     const normalized = normalizeLoop2(loop, true);
+    const assertComparisonLimit = (requiredCount) => {
+        if (requiredCount > maximumComparisons)
+            throw new GeometryError("COMPLEXITY_LIMIT", "Profile cap triangulation exceeds its eight-million-comparison work limit.", {
+                operation: "triangulateLoop2",
+                details: { requiredCount, allowedCount: maximumComparisons },
+            });
+    };
+    // Every accepted ear scans all remaining vertices plus its outer-loop comparison.
+    // Reject impossible workloads before clipping; unsuccessful ears still spend the live budget.
+    assertComparisonLimit(((normalized.length - 3) * (normalized.length + 6)) / 2);
     // Subdividing a straight edge introduces roundoff-sized turns. Treat them consistently
     // in both ear convexity and containment so they cannot consume a false ear or block the cap.
     let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
@@ -25,24 +35,17 @@ export function triangulateLoop2(loop) {
     const remaining = normalized.map((_, index) => index);
     const triangles = [];
     let comparisons = 0;
-    const consume = () => {
-        if (++comparisons > maximumComparisons)
-            throw new GeometryError("COMPLEXITY_LIMIT", "Profile cap triangulation exceeds its eight-million-comparison work limit.", {
-                operation: "triangulateLoop2",
-                details: { requiredCount: comparisons, allowedCount: maximumComparisons },
-            });
-    };
     while (remaining.length > 3) {
         let clipped = false;
         for (let offset = 0; offset < remaining.length; offset += 1) {
-            consume();
+            assertComparisonLimit(++comparisons);
             const previous = remaining[(offset - 1 + remaining.length) % remaining.length];
             const current = remaining[offset];
             const next = remaining[(offset + 1) % remaining.length];
             if (cross(normalized[previous], normalized[current], normalized[next]) <= epsilon)
                 continue;
             if (remaining.some((candidate) => {
-                consume();
+                assertComparisonLimit(++comparisons);
                 return (candidate !== previous &&
                     candidate !== current &&
                     candidate !== next &&

package/dist/geometry/loft.js

@@ -3,7 +3,7 @@ import { resolveExtrusionControls, resolveExtrusionDivisions, } from "./extrusio
 import { pointLoftProfile, prepareLoftGeometry } from "./loft-geometry.js";
 import {} from "./loft-options.js";
 import { simpleLoftMesh } from "./loft-simple-mesh.js";
-import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "./model-limits.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits } from "./model-limits.js";
 import { assertSamplingCount } from "./sampling-limits.js";
 export { triangulateLoop2 } from "./loft-triangulation.js";
 /**
@@ -14,12 +14,15 @@ export { triangulateLoop2 } from "./loft-triangulation.js";
  * Both ends use ear-clipped caps, supporting concave profiles without center fans.
  * Intermediate slices interpolate placed world vertices, never frame axes.
  * Transformed coordinates must fit finite Float32 mesh storage.
+ *
+ * @example Loft with explicit point correspondence
+ * ```ts
+ * const bottom = rectangleLoop({ size: [20, 12] });
+ * const top = rectangleLoop({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+ * loftMesh([{ profile: bottom, z: 0 }, { profile: top, z: 30 }], { correspondence: "reindex" });
+ * ```
  */
 export function loftMesh(stations, options) {
-    return buildLoftMesh(stations, options);
-}
-/** @internal Shared pure loft with host allocation preflight. */
-export function buildLoftMesh(stations, options, allocationGuard) {
     if (options?.correspondence === undefined)
         throw new GeometryError("INVALID_ARGUMENT", "Point-loop lofts require an explicit correspondence method.", { operation: "loftMesh" });
     const limits = resolveModelingLimits(options.limits);
@@ -38,9 +41,17 @@ export function buildLoftMesh(stations, options, allocationGuard) {
         ...station,
         profile: pointLoftProfile(station.profile),
     }));
-    return simpleLoftMesh(prepareLoftGeometry(profiles, options, limits, false), limits, allocationGuard);
+    return simpleLoftMesh(prepareLoftGeometry(profiles, options, limits, false), limits);
 }
-/** Linearly extrudes one simple profile along +Z with robust ear-clipped caps. */
+/**
+ * Linearly extrudes one simple profile along +Z with robust ear-clipped caps.
+ *
+ * @example Extrude point data without an engine
+ * ```ts
+ * const outline = rectangleLoop({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+ * extrudeMesh(outline, { height: 8 });
+ * ```
+ */
 export function extrudeMesh(profile, options) {
     const { height } = options;
     const { center, scales, twistDegrees } = resolveExtrusionControls(height, options, "extrudeMesh");

package/dist/geometry/math/vector3.js

@@ -1,16 +1,46 @@
-/** Adds two finite XYZ vectors component-wise. @example `add3([1, 2, 3], [4, 5, 6])` */
+/**
+ * Adds two finite XYZ vectors component-wise.
+ * @example
+ * ```ts
+ * add3([1, 2, 3], [4, 5, 6]); // [5, 7, 9]
+ * ```
+ */
 export const add3 = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
-/** Subtracts `b` from `a`. @example `subtract3([4, 5, 6], [1, 2, 3])` */
+/**
+ * Subtracts `b` from `a`.
+ * @example
+ * ```ts
+ * subtract3([4, 5, 6], [1, 2, 3]); // [3, 3, 3]
+ * ```
+ */
 export const subtract3 = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
-/** Multiplies a vector by a dimensionless scalar. @example `scale3([1, 2, 3], 2)` */
+/**
+ * Multiplies a vector by a dimensionless scalar.
+ * @example
+ * ```ts
+ * scale3([1, 2, 3], 2); // [2, 4, 6]
+ * ```
+ */
 export const scale3 = (vector, scale) => [
     vector[0] * scale,
     vector[1] * scale,
     vector[2] * scale,
 ];
-/** Returns the scalar dot product. @example `dot3([1, 0, 0], [0, 1, 0])` */
+/**
+ * Returns the scalar dot product.
+ * @example
+ * ```ts
+ * dot3([1, 0, 0], [0, 1, 0]); // 0
+ * ```
+ */
 export const dot3 = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
-/** Returns the right-handed cross product. @example `cross3([1, 0, 0], [0, 1, 0])` */
+/**
+ * Returns the right-handed cross product.
+ * @example
+ * ```ts
+ * cross3([1, 0, 0], [0, 1, 0]); // [0, 0, 1]
+ * ```
+ */
 export const cross3 = (a, b) => [
     a[1] * b[2] - a[2] * b[1],
     a[2] * b[0] - a[0] * b[2],

package/dist/geometry/mechanical/standards.js

@@ -44,11 +44,10 @@ export const METRIC_FASTENER_STANDARDS = Object.freeze({
 });
 /** Returns the immutable standards record for one supported metric size. */
 export function getMetricFastenerStandard(size) {
-    const value = METRIC_FASTENER_STANDARDS[size];
-    if (value === undefined) {
+    if (!Object.hasOwn(METRIC_FASTENER_STANDARDS, size)) {
         throw new GeometryError("INVALID_ARGUMENT", `Unsupported metric fastener size: ${size}.`);
     }
-    return value;
+    return METRIC_FASTENER_STANDARDS[size];
 }
 /** Returns one recommended metric clearance-hole diameter in millimetres. */
 export function getMetricClearanceHole(size, fit = "normal") {

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

@@ -234,6 +234,11 @@ const standardProfile = (kind, pitch, depth, root, crest, leftRun, rightRun) =>
  * The open path spans one pitch. Radial zero is the major envelope; negative
  * values point toward the shaft. Custom paths must be finite, axially
  * non-decreasing, periodic at their endpoints, and reach radial zero.
+ *
+ * @example Printable triangular thread profile
+ * ```ts
+ * createThreadProfile({ kind: "triangular", pitch: 1.75 });
+ * ```
  */
 export function createThreadProfile(spec) {
     const operation = "createThreadProfile";

package/dist/geometry/mechanical/threads.js

@@ -36,11 +36,10 @@ const validateFitPolicy = (policy) => {
 export function resolvePrintableThreadFitPolicy(fit = "normal") {
     if (typeof fit !== "string")
         return validateFitPolicy(fit);
-    const policy = PRINTABLE_THREAD_FIT_POLICIES[fit];
-    if (policy === undefined) {
+    if (!Object.hasOwn(PRINTABLE_THREAD_FIT_POLICIES, fit)) {
         throw new GeometryError("INVALID_ARGUMENT", `Unsupported printable thread fit: ${fit}.`);
     }
-    return policy;
+    return PRINTABLE_THREAD_FIT_POLICIES[fit];
 }
 /**
  * Applies role-specific radial compensation while preserving thread depth.

package/dist/geometry/mesh-centroid.js

@@ -0,0 +1,36 @@
+import { GeometryError } from "./errors.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.
+ * 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 facts = analyzeTriangleMesh(mesh, { requireClosed: true });
+    if (!(facts.signedVolume > 0))
+        throw new GeometryError("INVALID_TOPOLOGY", "A volume centroid requires positive oriented volume.", { operation: "computeTriangleMeshCentroid" });
+    const origin = facts.bounds.min;
+    const totals = [0, 0, 0], corrections = [0, 0, 0];
+    for (let offset = 0; offset < mesh.indices.length; offset += 3) {
+        const a = mesh.indices[offset] * 3, b = mesh.indices[offset + 1] * 3, c = mesh.indices[offset + 2] * 3;
+        const ax = mesh.positions[a] - origin[0], ay = mesh.positions[a + 1] - origin[1], az = mesh.positions[a + 2] - origin[2];
+        const bx = mesh.positions[b] - origin[0], by = mesh.positions[b + 1] - origin[1], bz = mesh.positions[b + 2] - origin[2];
+        const cx = mesh.positions[c] - origin[0], cy = mesh.positions[c + 1] - origin[1], cz = mesh.positions[c + 2] - origin[2];
+        const volume = (ax * (by * cz - bz * cy) + ay * (bz * cx - bx * cz) + az * (bx * cy - by * cx)) / 6;
+        const coordinates = [(ax + bx + cx) / 4, (ay + by + cy) / 4, (az + bz + cz) / 4];
+        for (let axis = 0; axis < 3; axis++) {
+            const value = volume * coordinates[axis], next = totals[axis] + value;
+            corrections[axis] +=
+                Math.abs(totals[axis]) >= Math.abs(value)
+                    ? totals[axis] - next + value
+                    : value - next + totals[axis];
+            totals[axis] = next;
+        }
+    }
+    const coordinate = (axis) => origin[axis] + (totals[axis] + corrections[axis]) / facts.signedVolume;
+    return Object.freeze([coordinate(0), coordinate(1), coordinate(2)]);
+}