@metamesh/modeling 0.14.0 → 0.15.0

package/dist/engine/execution.js

@@ -7,6 +7,7 @@ import { createModelingContext } from "./modeling-context.js";
 import { ownScopedManifoldValue, scopedManifoldScope, trackScopedManifoldValue, } from "./native/context.js";
 import { copiedFloat32Array, copiedUint32Array } from "./native/copied-views.js";
 import * as kernel from "./native/index.js";
+import { solidMaterialComponents } from "./native/material-components.js";
 import { assertNativeSolidStatus } from "./native/status.js";
 import { createShapeAnchorOwner } from "./shape-anchors.js";
 /** Internal execution owner; no native value or constructor crosses the public facade. */
@@ -18,6 +19,8 @@ export function createExecutionContext(module, scope, limits, initialResolution
     const canonicalSectionProfiles = new Map();
     let solidInspections;
     let sectionInspections;
+    let solidComponents;
+    let sectionComponents;
     const primitiveSectionProfiles = new Map();
     let active = true;
     const throwGeometryError = (code, operation, message) => {
@@ -63,6 +66,30 @@ export function createExecutionContext(module, scope, limits, initialResolution
         const owned = ownScopedManifoldValue(scope, value);
         return wrapSection(owned);
     };
+    const solidComponentsFor = (handle) => {
+        const native = nativeSolid(handle);
+        const cached = solidComponents?.get(native);
+        if (cached !== undefined)
+            return cached;
+        const components = solidMaterialComponents(scope, native, limits);
+        const cache = (solidComponents ??= new Map());
+        cache.set(native, components);
+        for (const component of components)
+            cache.set(component, Object.freeze([component]));
+        return components;
+    };
+    const sectionComponentsFor = (handle) => {
+        const native = nativeSection(handle);
+        const cached = sectionComponents?.get(native);
+        if (cached !== undefined)
+            return cached;
+        const components = Object.freeze(native.isEmpty() ? [] : native.decompose().map((part) => ownScopedManifoldValue(scope, part)));
+        const cache = (sectionComponents ??= new Map());
+        cache.set(native, components);
+        for (const component of components)
+            cache.set(component, Object.freeze([component]));
+        return components;
+    };
     // Geometry is immutable for a native value. Validate build ownership before every cache hit,
     // and retain only frozen plain facts so callers cannot corrupt later inspections.
     const solidInspectionFor = (handle) => {
@@ -72,12 +99,12 @@ export function createExecutionContext(module, scope, limits, initialResolution
             return cached;
         assertNativeSolidStatus(native, "inspectSolid");
         const bounds = native.boundingBox();
-        const parts = native.decompose().map((part) => ownScopedManifoldValue(scope, part));
+        const components = solidComponentsFor(handle);
         const facts = Object.freeze({
             min: Object.freeze([...bounds.min]),
             max: Object.freeze([...bounds.max]),
             isEmpty: native.isEmpty(),
-            parts: parts.length,
+            componentCount: components.length,
             volume: native.volume(),
             surfaceArea: native.surfaceArea(),
             tolerance: native.tolerance(),
@@ -92,17 +119,15 @@ export function createExecutionContext(module, scope, limits, initialResolution
             return cached;
         const bounds = native.bounds();
         const empty = native.isEmpty();
-        const parts = empty
-            ? []
-            : native.decompose().map((part) => ownScopedManifoldValue(scope, part));
+        const components = sectionComponentsFor(handle);
         const facts = Object.freeze({
             min: Object.freeze([...bounds.min]),
             max: Object.freeze([...bounds.max]),
             isEmpty: empty,
             area: native.area(),
-            contours: native.numContour(),
-            parts: parts.length,
-            vertices: native.numVert(),
+            contourCount: native.numContour(),
+            componentCount: components.length,
+            vertexCount: native.numVert(),
         });
         (sectionInspections ??= new Map()).set(native, facts);
         return facts;
@@ -244,6 +269,8 @@ export function createExecutionContext(module, scope, limits, initialResolution
         analyzedMeshFor,
         solidInspectionFor,
         sectionInspectionFor,
+        solidComponentsFor,
+        sectionComponentsFor,
         sectionProfileFor,
         primitiveProfileFor,
         rememberPrimitiveProfile,
@@ -305,8 +332,12 @@ export function createExecutionContext(module, scope, limits, initialResolution
             canonicalSectionProfiles.clear();
             solidInspections?.clear();
             sectionInspections?.clear();
+            solidComponents?.clear();
+            sectionComponents?.clear();
             solidInspections = undefined;
             sectionInspections = undefined;
+            solidComponents = undefined;
+            sectionComponents = undefined;
             primitiveSectionProfiles.clear();
             shapeAnchors.dispose();
         },

package/dist/engine/extrusion-finishing.js

@@ -10,7 +10,7 @@ const fail = (message) => {
 /** Finishes inward convex extrusion rims with exact parallel-edge offsets and retained correspondence. */
 export function buildFinishedExtrusion(module, profile, options) {
     const controls = resolveExtrusionControls(options.height, options, "extrude");
-    if (controls.twistDegrees !== 0 ||
+    if (controls.twist !== 0 ||
         controls.scales.some((scale) => scale !== 1) ||
         options.divisions !== undefined)
         fail("End treatments require a straight extrusion without twist, top scaling or divisions.");

package/dist/engine/index.js

@@ -97,8 +97,13 @@ function engineFromModule(module, engineLimits) {
  */
 export async function createModelEngine(options = {}) {
     const limits = resolveModelingLimits(options.limits);
+    const wasmUrl = options.wasmUrl === undefined ? modelingWasmUrl : options.wasmUrl;
+    if (typeof wasmUrl !== "string" || wasmUrl.trim().length === 0)
+        throw new GeometryError("INVALID_ARGUMENT", "wasmUrl must be a non-empty asset URL string.", {
+            operation: "createModelEngine",
+        });
     const module = await createManifoldModule({
-        locateFile: options.locateFile ?? (() => modelingWasmUrl),
+        locateFile: () => wasmUrl,
     });
     module.setup();
     return engineFromModule(module, limits);

package/dist/engine/inspection-operations.js

@@ -1,10 +1,11 @@
+import { vector3Data } from "../geometry/math/vector-value.js";
 import { ownScopedManifoldValue } from "./native/context.js";
 import { copiedMeshViews } from "./native/copied-views.js";
 import { measureSolidDistance } from "./native/distance.js";
 import { assertNativeSolidStatus } from "./native/status.js";
 /** Internal host-bound inspection operations. */
 export function createInspectionOperations(environment) {
-    const { scope, throwGeometryError, nativeSolid, resolveHandle, ownSolid, ownSection, validateFiniteNumber, requirePositiveNumber, validateCoordinates, analyzedMeshFor, solidInspectionFor, sectionInspectionFor, } = environment;
+    const { scope, throwGeometryError, nativeSolid, resolveHandle, ownSolid, ownSection, wrapSolid, wrapSection, validateFiniteNumber, requirePositiveNumber, validateCoordinates, analyzedMeshFor, solidInspectionFor, sectionInspectionFor, solidComponentsFor, sectionComponentsFor, } = environment;
     const operations = {
         toTriangleMesh: (value) => copiedMeshViews(analyzedMeshFor(value).mesh, new Map()),
         inspectSection: sectionInspectionFor,
@@ -16,12 +17,14 @@ export function createInspectionOperations(environment) {
             return native.value.isEmpty();
         },
         distance: (handle, other) => measureSolidDistance(nativeSolid(handle), nativeSolid(other)),
-        rayCast: (handle, origin, endpoint) => {
-            validateCoordinates(origin, 3, "rayCast");
-            validateCoordinates(endpoint, 3, "rayCast");
+        castSegment: (handle, inputOrigin, inputEndpoint) => {
+            const origin = vector3Data(inputOrigin);
+            const endpoint = vector3Data(inputEndpoint);
+            validateCoordinates(origin, 3, "castSegment");
+            validateCoordinates(endpoint, 3, "castSegment");
             const segmentLength = Math.hypot(...origin.map((value, axis) => value - endpoint[axis]));
             if (!Number.isFinite(segmentLength) || segmentLength === 0)
-                throwGeometryError("DEGENERATE_GEOMETRY", "rayCast", "Ray segment endpoints must differ.");
+                throwGeometryError("DEGENERATE_GEOMETRY", "castSegment", "Segment endpoints must differ.");
             return Object.freeze(nativeSolid(handle)
                 .rayCast([...origin], [...endpoint])
                 .map((hit) => Object.freeze({
@@ -34,9 +37,8 @@ export function createInspectionOperations(environment) {
         components: ((handle) => {
             const native = resolveHandle(handle);
             if (native.kind === "section")
-                return Object.freeze(native.value.isEmpty() ? [] : native.value.decompose().map(ownSection));
-            assertNativeSolidStatus(native.value, "components");
-            return Object.freeze(native.value.decompose().map(ownSolid));
+                return Object.freeze(sectionComponentsFor(handle).map(wrapSection));
+            return Object.freeze(solidComponentsFor(handle).map(wrapSolid));
         }),
         simplify: ((handle, tolerance) => {
             const native = resolveHandle(handle);
@@ -46,9 +48,9 @@ export function createInspectionOperations(environment) {
             const original = ownScopedManifoldValue(scope, native.value.asOriginal());
             return ownSolid(original.simplify(distance));
         }),
-        setTolerance: (handle, tolerance) => {
-            if (validateFiniteNumber(tolerance, "setTolerance") < 0)
-                throwGeometryError("INVALID_ARGUMENT", "setTolerance", "Tolerance must be nonnegative millimetres.");
+        withTolerance: (handle, tolerance) => {
+            if (validateFiniteNumber(tolerance, "withTolerance") < 0)
+                throwGeometryError("INVALID_ARGUMENT", "withTolerance", "Tolerance must be nonnegative millimetres.");
             return ownSolid(nativeSolid(handle).setTolerance(tolerance));
         },
     };

package/dist/engine/loft-operations.js

@@ -2,11 +2,13 @@ import { GeometryError } from "../geometry/errors.js";
 import { loftProfilePointCount, pointLoftProfile, prepareLoftGeometry, } from "../geometry/loft/loft-geometry.js";
 import { loftFrame, resolveLoftControls } from "../geometry/loft/loft-options.js";
 import { simpleLoftMesh } from "../geometry/loft/loft-simple-mesh.js";
-import { measureTriangleMesh } from "../geometry/mesh/mesh.js";
+import { analyzeTriangleMesh } from "../geometry/mesh/mesh.js";
+import { capturePath2Input, path2InputData, } from "../geometry/paths/path-value.js";
 import { assertSamplingCount } from "../geometry/sampling-limits.js";
 import { correspondingPrimitiveProfiles, rectangularPrimitiveFamily, } from "./primitive-profiles.js";
 import { buildProfileLoftMesh } from "./profile-mesh.js";
 const explicitProfile = (value) => typeof value === "object" && value !== null && "components" in value;
+const pointProfile = (value) => Array.isArray(value) || (typeof value === "object" && value !== null && "toArray" in value);
 const fail = (message) => {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: "loft" });
 };
@@ -63,21 +65,40 @@ function primitivePolygon(profile) {
 }
 /** Private host adapter: known authored identity or explicitly requested geometric correspondence. */
 export function createLoftOperation(environment, solidFromMesh) {
-    return (stations, value = {}) => {
+    return (inputStations, value = {}) => {
         environment.assertActive();
-        if (!Array.isArray(stations) || stations.length < 2)
+        if (!Array.isArray(inputStations) || inputStations.length < 2)
             fail("Loft requires at least two stations.");
-        assertSamplingCount(stations.length, "loft", environment.limits.maxPathPoints);
-        stations.forEach((station) => loftFrame(station));
-        resolveLoftControls(value, stations.length);
-        const rawPoints = stations.reduce((sum, station) => sum +
-            (explicitProfile(station.profile)
-                ? loftProfilePointCount(station.profile)
-                : Array.isArray(station.profile)
-                    ? station.profile.length
-                    : environment.nativeSection(station.profile).numVert()), 0);
-        assertSamplingCount(rawPoints, "loft", 1_000_000);
+        assertSamplingCount(inputStations.length, "loft", environment.limits.maxPathPoints);
+        inputStations.forEach((station) => loftFrame(station));
         let selected = environment.withResolutionDefaults(value);
+        resolveLoftControls(value, inputStations.length);
+        const captured = inputStations.map(({ profile, ...placement }) => {
+            const source = pointProfile(profile) ? capturePath2Input(profile, true) : undefined;
+            return { placement, profile: source?.input ?? profile, count: source?.count };
+        });
+        let rawPoints = 0, fixedPoints = 0;
+        for (const { profile, count } of captured) {
+            const fixed = count === undefined
+                ? explicitProfile(profile)
+                    ? loftProfilePointCount(profile)
+                    : environment.nativeSection(profile).numVert()
+                : 0;
+            fixedPoints += fixed;
+            rawPoints += count ?? fixed;
+            assertSamplingCount(rawPoints, "loft", 1_000_000);
+        }
+        let remaining = 1_000_000 - fixedPoints;
+        const stations = captured.map(({ placement, profile, count }) => {
+            if (count === undefined)
+                return { ...placement, profile };
+            const points = path2InputData(profile, true, {
+                maxPathPoints: Math.max(1, Math.min(selected.limits.maxProfilePoints, remaining)),
+            }).points;
+            assertSamplingCount(points.length, "loft", remaining);
+            remaining -= points.length;
+            return { ...placement, profile: points };
+        });
         const controls = resolveLoftControls(selected, stations.length);
         const explicit = stations.some((station) => explicitProfile(station.profile));
         let profiles, authoritative = false;
@@ -145,7 +166,7 @@ export function createLoftOperation(environment, solidFromMesh) {
             station.profile.components[0].holes.length === 0))
             return solidFromMesh(simpleLoftMesh(geometry, selected.limits));
         const mesh = buildProfileLoftMesh(environment.module, geometry.stations, selected.limits, false, 0, (station, contour, slot) => geometry.world[station][contour][slot]);
-        if (measureTriangleMesh(mesh).signedVolume < 0)
+        if (analyzeTriangleMesh(mesh).signedVolume < 0)
             for (let index = 0; index < mesh.indices.length; index += 3) {
                 const b = mesh.indices[index + 1];
                 mesh.indices[index + 1] = mesh.indices[index + 2];

package/dist/engine/model-summary.js

@@ -1,11 +1,12 @@
 import { GeometryError } from "../geometry/errors.js";
 /** Counts manufacturing instances while charging shared backing storage only once. */
 export function createModelSummary(limits) {
-    let vertices = 0, triangles = 0, bytes = 0, volumeMm3 = 0;
+    let vertices = 0, triangles = 0, bytes = 0, partCount = 0, volumeMm3 = 0;
     const storage = new Set();
     const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
     return {
         add(geometry) {
+            partCount++;
             const measurements = geometry.measurements;
             vertices += measurements.vertexCount;
             triangles += measurements.triangleCount;
@@ -15,7 +16,8 @@ export function createModelSummary(limits) {
                     storage.add(buffer);
                     bytes += buffer.byteLength;
                 }
-            if (vertices > limits.maxVertices ||
+            if (partCount > limits.maxParts ||
+                vertices > limits.maxVertices ||
                 triangles > limits.maxTriangles ||
                 bytes > limits.maxBytes)
                 throw new GeometryError("COMPLEXITY_LIMIT", "Aggregate output exceeds the execution limits.", { operation: "generate" });
@@ -29,9 +31,10 @@ export function createModelSummary(limits) {
             return {
                 bounds: Object.freeze({ min: Object.freeze(min), max: Object.freeze(max) }),
                 stats: Object.freeze({
-                    vertices,
-                    triangles,
-                    bytes,
+                    partCount,
+                    vertexCount: vertices,
+                    triangleCount: triangles,
+                    byteCount: bytes,
                     volumeMm3,
                     buildMs: builtAt - startedAt,
                     finalizationMs: endedAt - builtAt,

package/dist/engine/native/material-components.js

@@ -0,0 +1,305 @@
+import { GeometryError } from "../../geometry/errors.js";
+import { triangleSolidAngle } from "../../geometry/mesh/mesh-solid-intersections.js";
+import { assertMeshAllocationWithinLimits, } from "../../geometry/model-limits.js";
+import { ownScopedManifoldValue, scopedManifoldModule, } from "./context.js";
+import { assertNativeSolidStatus } from "./status.js";
+const MAXIMUM_CONTAINMENT_TESTS = 2_000_000;
+/** Certifies the native sign only when its floating-point error cannot reach zero. */
+function certifiedNativeOrientation(volume, bounds, triangles) {
+    const magnitudes = bounds.min.map((value, axis) => Math.max(Math.abs(value), Math.abs(bounds.max[axis])));
+    const ranges = bounds.min.map((value, axis) => bounds.max[axis] - value);
+    const magnitude = Math.max(...magnitudes);
+    // Pinned Manifold 3.5.4 src/properties.cpp:245-270 computes edge-cross/dot/6
+    // terms q followed by s'=fl(s+q), c+=fl(fl(s-s')+q). In exact algebra the
+    // compensation cancels the running-sum errors. For u=2^-53 and n*u<1/4,
+    // remaining summation error is <=(6u+7n^2*u^2)*sum(abs(q)). For
+    // P=sum(Mi*Rj*Rk), each triangle's absolute product sum is <=P/3 and its
+    // arithmetic error is <=64uP. Their total is <80*u*n*P*(1+n^2*u);
+    // 512 also covers rounding of ranges/P. This selects arithmetic, never size.
+    // These windows keep the bound finite/normal and absolute subnormal errors
+    // below its spare margin; coordinates outside them use exact arithmetic.
+    if (!Number.isFinite(volume) ||
+        triangles < 4 ||
+        triangles >= 2 ** 31 ||
+        magnitude < 2 ** -300 ||
+        magnitude > 2 ** 300 ||
+        ranges.some((range) => range < 2 ** -300 || range > 2 ** 300))
+        return undefined;
+    const productSum = magnitudes[0] * ranges[1] * ranges[2] +
+        magnitudes[1] * ranges[0] * ranges[2] +
+        magnitudes[2] * ranges[0] * ranges[1];
+    const unitRoundoff = Number.EPSILON / 2;
+    const error = 512 * unitRoundoff * triangles * productSum * (1 + triangles * triangles * unitRoundoff);
+    if (!Number.isFinite(error))
+        return undefined;
+    return Math.abs(volume) > error ? (volume < 0 ? -1 : 1) : undefined;
+}
+/** Observes native coordinates and topology without converting geometry to Float32. */
+function nativeShellMesh(scope, shell, limits) {
+    const vertices = shell.numVert();
+    const properties = shell.numPropVert();
+    const triangles = shell.numTri();
+    // Both native observation work and copied topology stay within the host's mesh limits.
+    // Charge the Float64 coordinates, Float32 property mesh, index map and triangle indices.
+    assertMeshAllocationWithinLimits(Math.max(vertices, properties), triangles, vertices * 24 + properties * (shell.numProp() + 4) * 4 + triangles * 12, "components", limits);
+    const coordinates = new Float64Array(vertices * 3);
+    const encoded = ownScopedManifoldValue(scope, shell.warpBatch((positions, count) => {
+        coordinates.set(positions);
+        for (let vertex = 0; vertex < count; vertex++) {
+            // Exact Float32-safe IDs recover native indices even when property vertices
+            // are duplicated or reordered by getMesh(). The original coordinates stay Float64.
+            positions[vertex * 3] = vertex % 65536;
+            positions[vertex * 3 + 1] = Math.floor(vertex / 65536);
+            positions[vertex * 3 + 2] = 0;
+        }
+    }));
+    assertNativeSolidStatus(encoded, "components");
+    if (encoded.numVert() !== vertices || encoded.numTri() !== triangles)
+        throw new GeometryError("INVALID_TOPOLOGY", "Native observation changed shell topology.", {
+            operation: "components",
+        });
+    const mesh = encoded.getMesh();
+    if (mesh.numVert !== properties || mesh.numTri !== triangles)
+        throw new GeometryError("INVALID_TOPOLOGY", "Native observation changed property topology.", {
+            operation: "components",
+        });
+    const indices = new Uint32Array(properties);
+    for (let vertex = 0; vertex < properties; vertex++) {
+        const offset = vertex * mesh.numProp;
+        const low = mesh.vertProperties[offset];
+        const high = mesh.vertProperties[offset + 1];
+        const index = low + high * 65536;
+        if (!Number.isInteger(low) ||
+            low < 0 ||
+            low >= 65536 ||
+            !Number.isInteger(high) ||
+            high < 0 ||
+            !Number.isSafeInteger(index) ||
+            index >= vertices ||
+            mesh.vertProperties[offset + 2] !== 0)
+            throw new GeometryError("INVALID_TOPOLOGY", "Native observation lost a vertex identity.", {
+                operation: "components",
+            });
+        indices[vertex] = index;
+    }
+    return { coordinates, vertexIndices: indices, triangles: mesh.triVerts };
+}
+/** Computes signed enclosed volume without rounding, including folded contact boundaries. */
+function nativeShellOrientation(mesh) {
+    const { coordinates, vertexIndices, triangles } = mesh;
+    const bits = new DataView(new ArrayBuffer(8));
+    const fractionMask = (1n << 52n) - 1n;
+    const representation = (value) => {
+        bits.setFloat64(0, value);
+        return bits.getBigUint64(0);
+    };
+    let minimumExponent = 2047;
+    for (const value of coordinates) {
+        if (!Number.isFinite(value))
+            throw new GeometryError("NON_FINITE_VALUE", "Native coordinates must be finite.", {
+                operation: "components",
+            });
+        if (value !== 0)
+            minimumExponent = Math.min(minimumExponent, Number((representation(value) >> 52n) & 2047n) || 1);
+    }
+    // One common binary scale makes each coefficient exact while avoiding thousands
+    // of unnecessary zero bits for ordinary millimetre coordinates.
+    const integer = (value) => {
+        if (value === 0)
+            return 0n;
+        const encodedValue = representation(value);
+        const exponent = Number((encodedValue >> 52n) & 2047n);
+        const significand = (encodedValue & fractionMask) | (exponent === 0 ? 0n : 1n << 52n);
+        const magnitude = significand << BigInt((exponent || 1) - minimumExponent);
+        return encodedValue >> 63n === 0n ? magnitude : -magnitude;
+    };
+    const origin = [integer(coordinates[0]), integer(coordinates[1]), integer(coordinates[2])];
+    const pointAt = (propertyVertex) => {
+        const offset = vertexIndices[propertyVertex] * 3;
+        return [
+            integer(coordinates[offset]) - origin[0],
+            integer(coordinates[offset + 1]) - origin[1],
+            integer(coordinates[offset + 2]) - origin[2],
+        ];
+    };
+    let volume = 0n;
+    for (let triangle = 0; triangle < triangles.length; triangle += 3) {
+        const a = pointAt(triangles[triangle]);
+        const b = pointAt(triangles[triangle + 1]);
+        const c = pointAt(triangles[triangle + 2]);
+        volume +=
+            a[0] * (b[1] * c[2] - b[2] * c[1]) +
+                a[1] * (b[2] * c[0] - b[0] * c[2]) +
+                a[2] * (b[0] * c[1] - b[1] * c[0]);
+    }
+    return volume < 0n ? -1 : volume > 0n ? 1 : 0;
+}
+/** Internal material decomposition; inward boundary shells stay with their enclosing exterior. */
+export function solidMaterialComponents(scope, solid, limits) {
+    assertNativeSolidStatus(solid, "components");
+    assertMeshAllocationWithinLimits(Math.max(solid.numVert(), solid.numPropVert()), solid.numTri(), solid.numPropVert() * (solid.numProp() + 3) * 4 + solid.numTri() * 12, "components", limits);
+    const shells = solid.decompose().map((shell) => ownScopedManifoldValue(scope, shell));
+    const boundaries = shells
+        .map((shell) => ({ shell, volume: shell.volume(), bounds: shell.boundingBox() }))
+        .filter(({ bounds }) => {
+        // Coplanar Boolean contact can leave native boundary shells without any material.
+        // Exact collapsed native bounds identify axis-aligned contacts cheaply. Do not
+        // use volume, an epsilon or Float32 mesh tests: any of them could
+        // discard a thin positive piece or an inward shell enclosing a real cavity.
+        return bounds.min.every((value, axis) => value !== bounds.max[axis]);
+    })
+        .map((entry) => ({
+        ...entry,
+        orientation: certifiedNativeOrientation(entry.volume, entry.bounds, entry.shell.numTri()),
+    }));
+    const uncertain = boundaries.filter(({ orientation }) => orientation === undefined);
+    if (uncertain.length > 0) {
+        let vertices = 0;
+        let properties = 0;
+        let triangles = 0;
+        let bytes = 0;
+        for (const { shell } of uncertain) {
+            vertices += shell.numVert();
+            properties += shell.numPropVert();
+            triangles += shell.numTri();
+            bytes +=
+                shell.numVert() * 24 +
+                    shell.numPropVert() * (shell.numProp() + 4) * 4 +
+                    shell.numTri() * 12;
+        }
+        assertMeshAllocationWithinLimits(Math.max(vertices, properties), triangles, bytes, "components", limits);
+    }
+    const meshes = new Map();
+    let observedVertices = 0;
+    let observedProperties = 0;
+    let observedTriangles = 0;
+    let observedBytes = 0;
+    const meshFor = (shell) => {
+        const cached = meshes.get(shell);
+        if (cached !== undefined)
+            return cached;
+        const vertices = observedVertices + shell.numVert();
+        const properties = observedProperties + shell.numPropVert();
+        const triangles = observedTriangles + shell.numTri();
+        const bytes = observedBytes +
+            shell.numVert() * 24 +
+            shell.numPropVert() * (shell.numProp() + 4) * 4 +
+            shell.numTri() * 12;
+        assertMeshAllocationWithinLimits(Math.max(vertices, properties), triangles, bytes, "components", limits);
+        const mesh = nativeShellMesh(scope, shell, limits);
+        meshes.set(shell, mesh);
+        observedVertices = vertices;
+        observedProperties = properties;
+        observedTriangles = triangles;
+        observedBytes = bytes;
+        return mesh;
+    };
+    const entries = boundaries
+        .map((entry) => ({
+        ...entry,
+        orientation: entry.orientation ?? nativeShellOrientation(meshFor(entry.shell)),
+    }))
+        .filter(({ orientation }) => orientation !== 0);
+    let tests = 0;
+    const spend = (count = 1) => {
+        tests += count;
+        if (tests > MAXIMUM_CONTAINMENT_TESTS)
+            throw new GeometryError("COMPLEXITY_LIMIT", "Material component containment exceeds its work ceiling.", {
+                operation: "components",
+                details: { required: tests, allowed: MAXIMUM_CONTAINMENT_TESTS },
+            });
+    };
+    const exteriors = entries.filter(({ orientation }) => orientation > 0);
+    const cavities = entries.filter(({ orientation }) => orientation < 0);
+    if (exteriors.length === 0)
+        return Object.freeze([]);
+    if (cavities.length === 0)
+        return Object.freeze(exteriors.map(({ shell }) => shell));
+    const pointAt = (mesh, index) => {
+        const offset = mesh.vertexIndices[index] * 3;
+        return [
+            mesh.coordinates[offset],
+            mesh.coordinates[offset + 1],
+            mesh.coordinates[offset + 2],
+        ];
+    };
+    const candidates = [...exteriors].sort((left, right) => Math.abs(left.volume) - Math.abs(right.volume));
+    const enclosingExterior = (entry) => {
+        return candidates.find((candidate) => {
+            spend();
+            if (candidate === entry ||
+                entry.bounds.min.some((value, axis) => value < candidate.bounds.min[axis]) ||
+                entry.bounds.max.some((value, axis) => value > candidate.bounds.max[axis]))
+                return false;
+            const childMesh = meshFor(entry.shell);
+            const point = pointAt(childMesh, childMesh.triangles[0]);
+            const mesh = meshFor(candidate.shell);
+            let angle = 0;
+            for (let triangle = 0; triangle < mesh.triangles.length; triangle += 3) {
+                spend();
+                angle += triangleSolidAngle(point, [
+                    pointAt(mesh, mesh.triangles[triangle]),
+                    pointAt(mesh, mesh.triangles[triangle + 1]),
+                    pointAt(mesh, mesh.triangles[triangle + 2]),
+                ]);
+            }
+            return Math.abs(angle) > 2 * Math.PI;
+        });
+    };
+    const module = scopedManifoldModule(scope);
+    const enclosedCavities = cavities.map((cavity) => ({
+        cavity,
+        parent: enclosingExterior(cavity),
+    }));
+    const orphanedCavity = enclosedCavities.some(({ parent }) => parent === undefined);
+    if (exteriors.length === 1 && entries.length === shells.length && !orphanedCavity)
+        return Object.freeze([solid]);
+    if (entries.length !== shells.length || orphanedCavity) {
+        // Selecting from the original would retain contact sheets inside a sealed cavity.
+        // Rebuild only this exceptional case from its material boundaries. The JS kernel's
+        // compose aliases union, so turn inward shells into positive native cutters instead.
+        const cutters = new Map(exteriors.map(({ shell }) => [shell, []]));
+        for (const { cavity, parent } of enclosedCavities) {
+            // An inward shell removes positive occupancy only inside an exterior. A lone
+            // inward contact remnant cannot define a bounded piece of material.
+            if (parent === undefined)
+                continue;
+            // Warp preserves winding while native mirror reverses it. The two exact X sign
+            // changes restore all Float64 coordinates without a mesh round-trip or tolerance.
+            spend(cavity.shell.numVert());
+            const reflected = ownScopedManifoldValue(scope, cavity.shell.warpBatch((vertices, count) => {
+                for (let vertex = 0; vertex < count; vertex++) {
+                    vertices[vertex * 3] = -vertices[vertex * 3];
+                }
+            }));
+            const cutter = ownScopedManifoldValue(scope, reflected.mirror([1, 0, 0]));
+            assertNativeSolidStatus(cutter, "components");
+            cutters.get(parent.shell).push(cutter);
+        }
+        return Object.freeze(exteriors.map(({ shell }) => {
+            const holes = cutters.get(shell);
+            const component = holes.length === 0
+                ? shell
+                : ownScopedManifoldValue(scope, module.Manifold.difference([shell, ...holes]));
+            assertNativeSolidStatus(component, "components");
+            return component;
+        }));
+    }
+    const children = new Map(exteriors.map(({ shell }) => [shell, []]));
+    for (const exterior of exteriors) {
+        const parent = enclosingExterior(exterior);
+        if (parent !== undefined)
+            children.get(parent.shell).push(exterior.shell);
+    }
+    // The JS kernel aliases compose to union, which fills independently supplied inward shells.
+    // Select from the original material instead, retaining its native precision and cavity winding.
+    return Object.freeze(exteriors.map(({ shell }) => {
+        const selected = ownScopedManifoldValue(scope, solid.intersect(shell));
+        const nested = children.get(shell);
+        const component = nested.length === 0
+            ? selected
+            : ownScopedManifoldValue(scope, module.Manifold.difference([selected, ...nested]));
+        assertNativeSolidStatus(component, "components");
+        return component;
+    }));
+}

package/dist/engine/native/regions.js

@@ -2,7 +2,8 @@ import { GeometryError } from "../../geometry/errors.js";
 import { contourContainsPoint, normalizeContour, normalizeRegion, signedContourArea, } from "../../geometry/regions.js";
 import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../../geometry/sampling-limits.js";
 import { assertScopedManifoldValue, ownScopedManifoldValue, scopedManifoldModule, } from "./context.js";
-const MAX_AGGREGATE_CONTOURS = 25_000;
+/** @internal One contour ceiling shared with authored input normalization preflights. */
+export const MAX_AGGREGATE_CONTOURS = 25_000;
 const assertRegionBounds = (regions, operation, limits = {}) => {
     const hasArrayShape = Array.isArray(regions);
     if (!hasArrayShape) {

package/dist/engine/native/threads.js

@@ -1,10 +1,10 @@
-import { buildHelicalThreadRidgeMesh, buildHelicalThreadSolidMesh, } from "../../geometry/mechanical/index.js";
+import { helicalThreadRidgeMesh, helicalThreadSolidMesh } from "../../geometry/mechanical/index.js";
 import { resolveCompensatedThreadSolidMesh, resolveThreadedNutSolid, } from "../../geometry/mechanical/thread-solids.js";
 import { triangleMeshToManifold } from "./adapter.js";
 export { preflightThreadedRodSolid, preflightInternalThreadCutterSolid, preflightThreadedNutSolid, } from "../../geometry/mechanical/thread-solids.js";
 /** Converts the runtime-neutral ridge mesh into a scope-owned Manifold solid. */
 export function threadRidgeSolid(module, options, scope) {
-    return triangleMeshToManifold(module, buildHelicalThreadRidgeMesh(options), scope);
+    return triangleMeshToManifold(module, helicalThreadRidgeMesh(options), scope);
 }
 const compensatedThreadSolid = (module, options, role, scope) => {
     const resolved = resolveCompensatedThreadSolidMesh(options, role);
@@ -12,7 +12,7 @@ const compensatedThreadSolid = (module, options, role, scope) => {
 };
 const compensatedThreadSolidFromResolved = (module, resolved, scope) => {
     const { axialExtension, meshOptions } = resolved;
-    const combined = triangleMeshToManifold(module, buildHelicalThreadSolidMesh(meshOptions), scope);
+    const combined = triangleMeshToManifold(module, helicalThreadSolidMesh(meshOptions), scope);
     return axialExtension === 0 ? combined : scope.own(combined.translate([0, 0, -axialExtension]));
 };
 /** Creates a compensated, scope-owned external threaded rod along +Z. */