@metamesh/modeling 0.6.0 → 0.8.0

package/dist/api/text.d.ts

@@ -1,16 +1,28 @@
 /** Limits apply before parsing or shaping untrusted font data. */
 export declare const MAX_VECTOR_FONT_BYTES: number;
 
-/** Parses bounded font bytes using optional fontkit and WOFF2 peers; no font fetching occurs here. */
+/**
+ * Parses bounded font bytes using optional fontkit and WOFF2 peers; no font fetching occurs here.
+ *
+ * @example Prepare a label before building geometry
+ * ```ts
+ * async function prepareLabel(fontBytes: Uint8Array) {
+ *   const font = await prepareVectorFont(fontBytes);
+ *   return font.layout("MetaMesh", { fontSize: 8 });
+ * }
+ * ```
+ */
 export declare function prepareVectorFont(bytes: Uint8Array, options?: VectorFontOptions): Promise<VectorFont>;
 
-/** A prepared font owns its parsed bytes; keep handles local to their Worker or invocation. */
+/**
+ * A prepared font owns its parsed bytes; keep handles local to their Worker or invocation.
+ */
 export declare interface VectorFont {
-    /** Shape and position up to 512 UTF-16 units and 16 lines; supports empty or whitespace text. */
+    /** Shape horizontal lines or one circular line; bounded to 512 UTF-16 units and supports blank text. */
     readonly layout: (text: string, options: VectorTextLayoutOptions) => VectorTextLayout;
     /** Measure the same cached vector layout; all returned lengths are in millimetres. */
     readonly measure: (text: string, options: VectorTextLayoutOptions) => VectorTextMetrics;
-    /** Serialize visible multiline outlines as bounded path-only SVG in physical millimetres. */
+    /** Serialize visible horizontal or circular outlines as bounded path-only SVG in physical millimetres. */
     readonly toSvg: (text: string, options: VectorTextLayoutOptions) => string;
 }
 
@@ -20,6 +32,18 @@ export declare interface VectorFontOptions {
     readonly staticWeight?: number;
 }
 
+/** A circular baseline centered at the XY origin, with rigid shaped glyph groups. */
+export declare interface VectorTextArcBaseline {
+    /** Selects a circular baseline; glyph outlines rotate without bending or stretching. */
+    readonly kind: "arc";
+    /** Baseline radius in millimetres, greater than zero and at most 10000. */
+    readonly radius: number;
+    /** Alignment datum in degrees counterclockwise from +X; defaults to 90. */
+    readonly centerAngleDegrees?: number;
+    /** Reading direction around the circle; defaults to clockwise. */
+    readonly direction?: "clockwise" | "counterclockwise";
+}
+
 /** Exact curve bounds in millimetres; positive Y points upward. */
 export declare interface VectorTextBounds {
     /** Minimum X and Y of visible outlines, including accents, descenders, and overhangs. */
@@ -28,7 +52,9 @@ export declare interface VectorTextBounds {
     readonly max: readonly [number, number];
 }
 
-/** Immutable vector layout with no browser, font parser, or kernel ownership. */
+/**
+ * Immutable vector layout with no browser, font parser, or kernel ownership.
+ */
 export declare interface VectorTextLayout {
     /** Nonzero-filled path data in millimetres, positive Y upward; empty for text with no ink. */
     readonly paths: readonly string[];
@@ -36,13 +62,17 @@ export declare interface VectorTextLayout {
     readonly metrics: VectorTextMetrics;
 }
 
-/** Horizontal multiline text, bounded to 512 UTF-16 units and 16 lines without wrapping. */
+/**
+ * Text bounded to 512 UTF-16 units: horizontal lines or one circular line without wrapping.
+ */
 export declare interface VectorTextLayoutOptions extends VectorTextOptions {
-    /** Place each line's advance at the origin; defaults to left. Ink overhang is preserved. */
+    /** Place the advance's start, midpoint or end at the datum; defaults to center on arcs, otherwise left. */
     readonly align?: "left" | "center" | "right";
+    /** Omitted uses horizontal lines. Arcs require one line and baseline vertical alignment. */
+    readonly baseline?: VectorTextArcBaseline;
     /** Baseline spacing in ems, 0.5–5; omitted uses the selected face's natural vertical metrics. */
     readonly lineHeight?: number;
-    /** Place the first baseline or the complete ink bounds at Y=0; defaults to baseline. */
+    /** Place the first baseline or complete ink bounds at Y=0; arcs only accept baseline. */
     readonly verticalAlign?: "baseline" | "top" | "center" | "bottom";
 }
 
@@ -50,9 +80,9 @@ export declare interface VectorTextLayoutOptions extends VectorTextOptions {
 export declare interface VectorTextMetrics {
     /** Visible curve bounds after alignment, or null when the text has no ink. */
     readonly bounds: VectorTextBounds | null;
-    /** Unaligned pen displacement: final line advance and negative baseline displacement, in mm. */
+    /** Unaligned logical advance and negative baseline displacement in mm; arcs retain [arc length, 0]. */
     readonly advance: readonly [number, number];
-    /** Maximum line advance in millimetres, including spaces; distinct from visible ink width. */
+    /** Maximum logical line advance in millimetres, including spaces; arc length on circular baselines. */
     readonly logicalWidth: number;
     /** Selected font's ascender distance above a baseline in millimetres, independent of the text. */
     readonly ascent: number;

package/dist/engine/construction-operations.js

@@ -1,12 +1,12 @@
 import { GeometryError } from "../geometry/errors.js";
 import { resolveExtrusionContourDivisions, resolveExtrusionControls, } from "../geometry/extrusion.js";
-import { heightfieldMesh, preflightHeightfield } from "../geometry/heightfield.js";
+import { heightfieldMesh } from "../geometry/heightfield.js";
 import { assertMeshAllocationWithinLimits } from "../geometry/model-limits.js";
 import { assertPrimitiveOptions } from "../geometry/primitive-resolvers.js";
 import { matchProfiles } from "../geometry/profiles/matched.js";
 import { resolveGeometryResolution } from "../geometry/resolution.js";
 import { assertSamplingCount } from "../geometry/sampling-limits.js";
-import { buildSweepMesh } from "../geometry/sweeps/sweep-mesh.js";
+import { sweepMesh } from "../geometry/sweeps/sweep-mesh.js";
 import { buildFinishedExtrusion } from "./extrusion-finishing.js";
 import { createLoftOperation } from "./loft-operations.js";
 import { triangleMeshToManifold } from "./native/adapter.js";
@@ -15,7 +15,18 @@ import * as kernel from "./native/index.js";
 import { buildProfileSweepMesh } from "./profile-mesh.js";
 /** Internal host-bound construction operations. */
 export function createConstructionOperations(environment, sections) {
-    const { module, scope, limits, assertActive, throwGeometryError, resolveHandle, nativeSolid, nativeSection, wrapSolid, ownSolid, ownSection, validateFiniteNumber, requirePositiveNumber, validateCoordinates, assertOperandCount, assertMeshAllocation, withResolutionDefaults, resolveCircularSegments, } = environment;
+    const { module, scope, limits, assertActive, throwGeometryError, resolveHandle, nativeSolid, nativeSection, wrapSolid, wrapSection, ownSolid, ownSection, validateFiniteNumber, requirePositiveNumber, validateCoordinates, assertOperandCount, assertMeshAllocation, withResolutionDefaults, resolveCircularSegments, } = environment;
+    const cuttingPlane = (value, operation) => {
+        assertPrimitiveOptions(value, operation);
+        validateCoordinates(value.normal, 3, operation);
+        const magnitude = Math.max(...value.normal.map(Math.abs));
+        if (magnitude === 0)
+            throwGeometryError("DEGENERATE_GEOMETRY", operation, "Plane normals must be nonzero.");
+        const scaled = value.normal.map((coordinate) => coordinate / magnitude);
+        const length = Math.hypot(...scaled);
+        const normal = [scaled[0] / length, scaled[1] / length, scaled[2] / length];
+        return { normal, offset: validateFiniteNumber(value.offset ?? 0, operation) };
+    };
     const fromContours = sections.sectionFromContours;
     const corresponding = (value) => typeof value === "object" && value !== null && "components" in value;
     const shapeSection = (shape) => corresponding(shape)
@@ -50,7 +61,6 @@ export function createConstructionOperations(environment, sections) {
         // a hole also bounds disconnected Sections, without extracting native point data.
         triangles = Math.max(0, vertices * 2 + 4 * native.numContour() - 8);
         assertMeshAllocationWithinLimits(vertices, triangles, vertices * 12 + triangles * 12, "extrude", resolved.limits);
-        assertMeshAllocation(vertices, triangles, vertices * 12 + triangles * 12, "extrude");
         return ownSolid(native.extrude(value.height, divisions, controls.twistDegrees, controls.scales, controls.center));
     };
     const boolean = (values, operation) => {
@@ -90,13 +100,47 @@ export function createConstructionOperations(environment, sections) {
         union: ((values) => boolean(values, "union")),
         subtract,
         intersect: ((values) => boolean(values, "intersect")),
+        split: (solid, cutter) => {
+            const results = nativeSolid(solid).split(nativeSolid(cutter));
+            return Object.freeze([ownSolid(results[0]), ownSolid(results[1])]);
+        },
+        splitByPlane: (solid, value) => {
+            const native = nativeSolid(solid);
+            const plane = cuttingPlane(value, "splitByPlane");
+            const results = native.splitByPlane(plane.normal, plane.offset);
+            return Object.freeze([ownSolid(results[0]), ownSolid(results[1])]);
+        },
         compose: (values) => wrapSolid(kernel.compose(scope, values.map(nativeSolid))),
-        hull: (value) => {
+        hull: ((value) => {
             assertActive();
-            return wrapSolid(kernel.hull(scope, value.solids === undefined
+            assertPrimitiveOptions(value, "hull");
+            const hasSolids = "solids" in value && value.solids !== undefined;
+            const hasSections = "sections" in value && value.sections !== undefined;
+            if (Number(value.points !== undefined) + Number(hasSolids) + Number(hasSections) !== 1)
+                throwGeometryError("INVALID_ARGUMENT", "hull", "Supply exactly one hull input family.");
+            if (hasSections) {
+                assertOperandCount(value.sections, "hull");
+                return ownSection(module.CrossSection.hull(value.sections.map(nativeSection)));
+            }
+            if (value.points !== undefined && value.points[0]?.length === 2) {
+                const points = value.points;
+                const pointInputs = points;
+                if (!Array.isArray(points) || points.length < 3)
+                    throwGeometryError("INVALID_ARGUMENT", "hull", "A planar hull needs at least three points.");
+                assertSamplingCount(points.length, "hull", Math.min(100_000, limits.maxProfilePoints));
+                const copied = pointInputs.map((point) => {
+                    validateCoordinates(point, 2, "hull");
+                    return [point[0], point[1]];
+                });
+                const native = ownScopedManifoldValue(scope, module.CrossSection.hull([copied]));
+                if (!(native.area() > 0))
+                    throwGeometryError("DEGENERATE_GEOMETRY", "hull", "Hull points must span positive area.");
+                return wrapSection(native);
+            }
+            return wrapSolid(kernel.hull(scope, !hasSolids
                 ? { points: value.points }
                 : { solids: value.solids.map(nativeSolid) }));
-        },
+        }),
         minkowskiSum: (a, b) => wrapSolid(kernel.minkowskiSum(scope, nativeSolid(a), nativeSolid(b))),
         solidFromMesh,
         extrude,
@@ -147,13 +191,11 @@ export function createConstructionOperations(environment, sections) {
             const singleComponent = profile.components.length === 1 ? profile.components[0] : undefined;
             const contours = singleComponent?.holes.length === 0 ? [singleComponent.outer.points] : [];
             if (contours.length === 1)
-                return solidFromMesh(buildSweepMesh(contours[0], path, selected, assertMeshAllocation));
+                return solidFromMesh(sweepMesh(contours[0], path, selected));
             return solidFromMesh(buildProfileSweepMesh(module, profile, path, selected, selected.limits));
         },
         heightfield: (value) => {
             assertActive();
-            const facts = preflightHeightfield(value, limits);
-            assertMeshAllocation(facts.vertexCount, facts.triangleCount, facts.byteCount, "heightfield");
             return solidFromMesh(heightfieldMesh(value, limits));
         },
         implicit: (value) => {

package/dist/engine/execution.js

@@ -7,6 +7,7 @@ import { createModelingContext } from "./modeling-context.js";
 import { ownScopedManifoldValue } from "./native/context.js";
 import { copiedFloat32Array, copiedUint32Array } from "./native/copied-views.js";
 import * as kernel from "./native/index.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. */
 export function createExecutionContext(module, scope, limits, initialResolution = {}) {
@@ -15,6 +16,8 @@ export function createExecutionContext(module, scope, limits, initialResolution
     // mesh inspection receives independent copies, and this run-owned cache is cleared on exit.
     const canonicalSolidMeshes = new Map();
     const canonicalSectionProfiles = new Map();
+    let solidInspections;
+    let sectionInspections;
     const primitiveSectionProfiles = new Map();
     let active = true;
     const throwGeometryError = (code, operation, message) => {
@@ -60,6 +63,50 @@ export function createExecutionContext(module, scope, limits, initialResolution
         const owned = ownScopedManifoldValue(scope, value);
         return wrapSection(owned);
     };
+    // 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) => {
+        const native = nativeSolid(handle);
+        const cached = solidInspections?.get(native);
+        if (cached !== undefined)
+            return cached;
+        assertNativeSolidStatus(native, "inspectSolid");
+        const bounds = native.boundingBox();
+        const parts = native.decompose().map((part) => ownScopedManifoldValue(scope, part));
+        const facts = Object.freeze({
+            min: Object.freeze([...bounds.min]),
+            max: Object.freeze([...bounds.max]),
+            isEmpty: native.isEmpty(),
+            parts: parts.length,
+            volume: native.volume(),
+            surfaceArea: native.surfaceArea(),
+            tolerance: native.tolerance(),
+        });
+        (solidInspections ??= new Map()).set(native, facts);
+        return facts;
+    };
+    const sectionInspectionFor = (handle) => {
+        const native = nativeSection(handle);
+        const cached = sectionInspections?.get(native);
+        if (cached !== undefined)
+            return cached;
+        const bounds = native.bounds();
+        const empty = native.isEmpty();
+        const parts = empty
+            ? []
+            : native.decompose().map((part) => ownScopedManifoldValue(scope, part));
+        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(),
+        });
+        (sectionInspections ??= new Map()).set(native, facts);
+        return facts;
+    };
     const shapeAnchors = createShapeAnchorOwner((shape) => {
         resolveHandle(shape);
     }, (shape) => {
@@ -94,6 +141,7 @@ export function createExecutionContext(module, scope, limits, initialResolution
         assertMeshAllocationWithinLimits(vertices, triangles, bytes, operation, limits);
     };
     const copyNativeMesh = (native) => {
+        assertNativeSolidStatus(native, "toTriangleMesh");
         const raw = native.getMesh();
         assertMeshAllocation(raw.numVert, raw.numTri, (raw.numVert + raw.numTri) * 12, "copyMesh");
         const positions = copiedFloat32Array(raw.numVert * 3);
@@ -194,6 +242,8 @@ export function createExecutionContext(module, scope, limits, initialResolution
         assertOperandCount,
         assertMeshAllocation,
         analyzedMeshFor,
+        solidInspectionFor,
+        sectionInspectionFor,
         sectionProfileFor,
         primitiveProfileFor,
         rememberPrimitiveProfile,
@@ -213,13 +263,16 @@ export function createExecutionContext(module, scope, limits, initialResolution
                 triVerts: mesh.indices,
             });
             const native = ownScopedManifoldValue(scope, new module.Manifold(input));
-            if (native.status() !== "NoError")
-                throwGeometryError("INVALID_TOPOLOGY", "finalize", "The geometry kernel rejected the finalized manufacturing mesh.");
+            assertNativeSolidStatus(native, "finalize");
         },
         dispose: () => {
             active = false;
             canonicalSolidMeshes.clear();
             canonicalSectionProfiles.clear();
+            solidInspections?.clear();
+            sectionInspections?.clear();
+            solidInspections = undefined;
+            sectionInspections = undefined;
             primitiveSectionProfiles.clear();
             shapeAnchors.dispose();
         },

package/dist/engine/export-3mf.js

@@ -1,12 +1,20 @@
 import { Zip, ZipDeflate } from "fflate";
 import { GeometryError } from "../geometry/errors.js";
+import { analyzeSolidMesh } from "../geometry/mesh-solid.js";
 import { analyzeTriangleMesh } from "../geometry/mesh.js";
+import { MeshViewCache } from "./mesh-view-cache.js";
 const namespace = "http://schemas.microsoft.com/3dmanufacturing/core/2015/02";
 const declaration = '<?xml version="1.0" encoding="UTF-8"?>';
 const encoder = new TextEncoder();
 const escapeXml = (value) => value.replace(/[&<>"']/g, (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" })[character]);
 /** Private core 3MF serializer. It preserves the selected buffers and streams bounded XML chunks. */
 export function meshesTo3mf(parts, options) {
+    if (options.meshValidation !== undefined &&
+        options.meshValidation !== "topology" &&
+        options.meshValidation !== "solid")
+        throw new GeometryError("INVALID_ARGUMENT", "Unsupported mesh validation mode.", {
+            operation: "export3mf",
+        });
     const name = options.name ?? "MetaMesh model";
     if (typeof name !== "string" ||
         name.length === 0 ||
@@ -14,10 +22,18 @@ export function meshesTo3mf(parts, options) {
         // eslint-disable-next-line no-control-regex -- XML 1.0 disallows these control characters.
         /[\u0000-\u0008\u000b\u000c\u000e-\u001f\ud800-\udfff\ufffe\uffff]/u.test(name))
         throw new GeometryError("INVALID_ARGUMENT", "3MF names require one through 1024 valid XML characters.", { operation: "export3mf" });
+    const analyzed = new MeshViewCache();
     for (const part of parts) {
-        const facts = analyzeTriangleMesh(part, { requireClosed: true, includeTopology: true });
+        let facts = analyzed.get(part);
+        if (facts !== undefined)
+            continue;
+        facts =
+            options.meshValidation === "solid"
+                ? analyzeSolidMesh(part)
+                : analyzeTriangleMesh(part, { requireClosed: true, includeTopology: true });
         if (!(facts.signedVolume > 0) || facts.vertexCount >= 2 ** 31 || facts.triangleCount >= 2 ** 31)
             throw new GeometryError("INVALID_TOPOLOGY", "3MF parts require positive oriented volume and valid core resource counts.", { operation: "export3mf" });
+        analyzed.set(part, facts);
     }
     const chunks = [];
     let bytes = 0, complete = false;

package/dist/engine/finalization.js

@@ -1,6 +1,8 @@
 import { GeometryError } from "../geometry/errors.js";
 import { optimizePlanarPatches } from "../geometry/mesh-planar.js";
-import { analyzeTriangleMesh } from "../geometry/mesh.js";
+import { validateAnalyzedSolidMesh } from "../geometry/mesh-solid.js";
+import { analyzeTriangleMesh, } from "../geometry/mesh.js";
+import { MeshViewCache } from "./mesh-view-cache.js";
 import { copiedMeshViews, copiedUint32Array } from "./native/copied-views.js";
 const isArray = (value) => Array.isArray(value);
 function finalPartTotals(parts) {
@@ -26,6 +28,12 @@ function fitsLimits(totals, limits) {
 }
 /** Finalizes one complete build under the selected limits, preserving usable originals when optional cleanup fails. */
 export function finalizeModel(execution, output, limits, options, startedAt, builtAt) {
+    if (options.meshValidation !== undefined &&
+        options.meshValidation !== "topology" &&
+        options.meshValidation !== "solid")
+        throw new GeometryError("INVALID_ARGUMENT", "Unsupported mesh validation mode.", {
+            operation: "finalize",
+        });
     const descriptors = execution.isSolid(output) ? [{ id: "model", solid: output }] : output;
     if (!isArray(descriptors) || descriptors.length === 0)
         throw new GeometryError("INVALID_ARGUMENT", "Build must return a solid or at least one named part.", { operation: "finalize" });
@@ -36,6 +44,7 @@ export function finalizeModel(execution, output, limits, options, startedAt, bui
     const ids = new Set();
     const backingBuffers = new Set();
     const meshCopies = new Map();
+    const directMeasurements = new MeshViewCache();
     const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
     let vertices = 0, triangles = 0, bytes = 0;
     let parts = descriptors.map((descriptor) => {
@@ -76,10 +85,12 @@ export function finalizeModel(execution, output, limits, options, startedAt, bui
             throw new GeometryError("COMPLEXITY_LIMIT", "Aggregate output exceeds the execution limits.", { operation: "finalize" });
         // Direct meshes are copied before analysis so later caller mutation cannot invalidate facts.
         const mesh = descriptor.mesh === undefined ? source : copiedMeshViews(source, meshCopies);
-        const measurements = nativeAnalysis?.measurements ??
-            analyzeTriangleMesh(mesh, { requireClosed: true, includeTopology: true });
-        if (descriptor.mesh !== undefined)
+        let measurements = nativeAnalysis?.measurements ?? directMeasurements.get(mesh);
+        if (measurements === undefined) {
+            measurements = analyzeTriangleMesh(mesh, { requireClosed: true, includeTopology: true });
             execution.validateMesh(mesh);
+            directMeasurements.set(mesh, measurements);
+        }
         if (!(measurements.signedVolume > 0))
             throw new GeometryError("INVALID_TOPOLOGY", "Manufacturing parts must enclose positive oriented volume.", { operation: "finalize" });
         for (let axis = 0; axis < 3; axis += 1) {
@@ -95,20 +106,9 @@ export function finalizeModel(execution, output, limits, options, startedAt, bui
     });
     const originalParts = parts;
     if (options.meshTopologyMode === "optimized" && triangles <= 200_000) {
-        const candidates = new Map();
+        const candidates = new MeshViewCache();
         parts = parts.map((part) => {
-            let indexBuffers = candidates.get(part.positions.buffer);
-            if (indexBuffers === undefined) {
-                indexBuffers = new Map();
-                candidates.set(part.positions.buffer, indexBuffers);
-            }
-            let views = indexBuffers.get(part.indices.buffer);
-            if (views === undefined) {
-                views = new Map();
-                indexBuffers.set(part.indices.buffer, views);
-            }
-            const key = `${part.positions.byteOffset}:${part.positions.length}:${part.indices.byteOffset}:${part.indices.length}`;
-            const cached = views.get(key);
+            const cached = candidates.get(part);
             if (cached !== undefined)
                 return Object.freeze({ ...part, ...cached });
             let selected = {
@@ -134,7 +134,7 @@ export function finalizeModel(execution, output, limits, options, startedAt, bui
             catch {
                 // Optional optimization preserves the usable original on unsupported geometry.
             }
-            views.set(key, selected);
+            candidates.set(part, selected);
             return Object.freeze({ ...part, ...selected });
         });
     }
@@ -148,6 +148,15 @@ export function finalizeModel(execution, output, limits, options, startedAt, bui
         throw new GeometryError("COMPLEXITY_LIMIT", "Selected output exceeds the execution limits.", {
             operation: "finalize",
         });
+    if (options.meshValidation === "solid") {
+        const checked = new MeshViewCache();
+        for (const part of parts) {
+            if (checked.get(part) !== undefined)
+                continue;
+            validateAnalyzedSolidMesh(part, part.measurements);
+            checked.set(part, true);
+        }
+    }
     const finalizedAt = performance.now();
     return Object.freeze({
         parts: Object.freeze(parts),

package/dist/engine/index.js

@@ -61,7 +61,18 @@ function engineFromModule(module, engineLimits) {
         },
     });
 }
-/** Initializes one host kernel and returns a lifecycle-safe engine. No generator initializes WASM. */
+/**
+ * Initializes one host kernel and returns a lifecycle-safe engine. No generator initializes WASM.
+ *
+ * @example Build a box in a host application
+ * ```ts
+ * import { box } from "@metamesh/modeling";
+ * import { createModelEngine } from "@metamesh/modeling/engine";
+ *
+ * const engine = await createModelEngine();
+ * const snapshot = engine.build(() => box({ size: [30, 20, 8] }));
+ * ```
+ */
 export async function createModelEngine(options = {}) {
     const limits = resolveModelingLimits(options.limits);
     const module = await createManifoldModule({

package/dist/engine/inspection-operations.js

@@ -1,26 +1,21 @@
 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, nativeSection, ownSolid, validateFiniteNumber, requirePositiveNumber, validateCoordinates, analyzedMeshFor, } = environment;
+    const { scope, throwGeometryError, nativeSolid, resolveHandle, ownSolid, ownSection, validateFiniteNumber, requirePositiveNumber, validateCoordinates, analyzedMeshFor, solidInspectionFor, sectionInspectionFor, } = environment;
     const operations = {
         toTriangleMesh: (value) => copiedMeshViews(analyzedMeshFor(value).mesh, new Map()),
-        inspectSection: (handle) => {
-            const native = nativeSection(handle), bounds = native.bounds();
-            const parts = native.decompose().map((part) => ownScopedManifoldValue(scope, part));
-            return {
-                ...bounds,
-                area: native.area(),
-                contours: native.toPolygons().length,
-                parts: parts.length,
-                vertices: native.numVert(),
-            };
-        },
-        inspectSolid: (handle) => {
-            const native = nativeSolid(handle), bounds = native.boundingBox();
-            const parts = native.decompose().map((part) => ownScopedManifoldValue(scope, part));
-            return { ...bounds, parts: parts.length, volume: native.volume() };
+        inspectSection: sectionInspectionFor,
+        inspectSolid: solidInspectionFor,
+        isEmpty: (handle) => {
+            const native = resolveHandle(handle);
+            if (native.kind === "solid")
+                assertNativeSolidStatus(native.value, "isEmpty");
+            return native.value.isEmpty();
         },
+        distance: (handle, other) => measureSolidDistance(nativeSolid(handle), nativeSolid(other)),
         rayCast: (handle, origin, endpoint) => {
             validateCoordinates(origin, 3, "rayCast");
             validateCoordinates(endpoint, 3, "rayCast");
@@ -36,12 +31,21 @@ export function createInspectionOperations(environment) {
                 normal: Object.freeze([...hit.normal]),
             })));
         },
-        components: (handle) => nativeSolid(handle).decompose().map(ownSolid),
-        simplify: (handle, tolerance) => {
-            const native = nativeSolid(handle);
-            const original = ownScopedManifoldValue(scope, native.asOriginal());
-            return ownSolid(original.simplify(requirePositiveNumber(tolerance, "simplify")));
-        },
+        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));
+        }),
+        simplify: ((handle, tolerance) => {
+            const native = resolveHandle(handle);
+            const distance = requirePositiveNumber(tolerance, "simplify");
+            if (native.kind === "section")
+                return ownSection(native.value.simplify(distance));
+            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.");

package/dist/engine/loft-operations.js

@@ -143,7 +143,7 @@ export function createLoftOperation(environment, solidFromMesh) {
         const geometry = prepareLoftGeometry(input, selected, selected.limits, authoritative, recipeSampled);
         if (geometry.stations.every((station) => station.profile.components.length === 1 &&
             station.profile.components[0].holes.length === 0))
-            return solidFromMesh(simpleLoftMesh(geometry, selected.limits, environment.assertMeshAllocation));
+            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)
             for (let index = 0; index < mesh.indices.length; index += 3) {

package/dist/engine/mechanical-operations.js

@@ -2,15 +2,12 @@ import * as kernel from "./native/index.js";
 /** Internal host-bound mechanical operations. */
 export function createMechanicalOperations(environment) {
     const { resolution } = environment;
-    const { scope, assertActive, wrapSolid, assertMeshAllocation, withResolutionDefaults } = environment;
+    const { scope, assertActive, wrapSolid, withResolutionDefaults } = environment;
     const nutOptions = (value) => ({
         ...withResolutionDefaults(value),
         bodyResolution: { ...resolution, ...value.bodyResolution },
     });
-    const threadBudget = (preflight, operation) => {
-        const vertices = (preflight.estimatedRows + 2) * preflight.circularSegments;
-        assertMeshAllocation(vertices, preflight.estimatedTriangles, (vertices + preflight.estimatedTriangles) * 12, operation);
-    };
+    // Explicit preflight preserves the stable error operation names exposed by these constructors.
     const operations = {
         threadRidge: (value) => {
             assertActive();
@@ -19,19 +16,19 @@ export function createMechanicalOperations(environment) {
         threadedRod: (value) => {
             assertActive();
             const resolved = withResolutionDefaults(value);
-            threadBudget(kernel.preflightThreadedRod(resolved), "threadedRod");
+            kernel.preflightThreadedRod(resolved);
             return wrapSolid(kernel.threadedRod(scope, resolved));
         },
         internalThreadCutter: (value) => {
             assertActive();
             const resolved = withResolutionDefaults(value);
-            threadBudget(kernel.preflightInternalThreadCutter(resolved), "internalThreadCutter");
+            kernel.preflightInternalThreadCutter(resolved);
             return wrapSolid(kernel.internalThreadCutter(scope, resolved));
         },
         threadedNut: (value) => {
             assertActive();
             const resolved = nutOptions(value);
-            threadBudget(kernel.preflightThreadedNut(resolved).thread, "threadedNut");
+            kernel.preflightThreadedNut(resolved);
             return wrapSolid(kernel.threadedNut(scope, resolved));
         },
         preflightThreadedRod: (value) => {

package/dist/engine/mesh-view-cache.js

@@ -0,0 +1,23 @@
+/** @internal Operation-local facts for identical privately owned mesh buffer ranges. */
+export class MeshViewCache {
+    positions = new Map();
+    key(mesh) {
+        return `${mesh.positions.byteOffset}:${mesh.positions.length}:${mesh.indices.byteOffset}:${mesh.indices.length}`;
+    }
+    get(mesh) {
+        return this.positions.get(mesh.positions.buffer)?.get(mesh.indices.buffer)?.get(this.key(mesh));
+    }
+    set(mesh, value) {
+        let indices = this.positions.get(mesh.positions.buffer);
+        if (indices === undefined) {
+            indices = new Map();
+            this.positions.set(mesh.positions.buffer, indices);
+        }
+        let ranges = indices.get(mesh.indices.buffer);
+        if (ranges === undefined) {
+            ranges = new Map();
+            indices.set(mesh.indices.buffer, ranges);
+        }
+        ranges.set(this.key(mesh), value);
+    }
+}

package/dist/engine/native/adapter.js

@@ -1,4 +1,5 @@
 import { validateTriangleMesh } from "../../geometry/mesh.js";
+import { assertNativeSolidStatus } from "./status.js";
 /**
  * Constructs a live Manifold solid from a copied indexed triangle mesh.
  *
@@ -12,9 +13,6 @@ export const triangleMeshToManifold = (module, mesh, scope) => {
         triVerts: mesh.indices,
     });
     const manifold = scope.own(new module.Manifold(manifoldMesh));
-    const status = manifold.status();
-    if (status !== "NoError") {
-        throw new Error(`Manifold rejected generated mesh: ${status}.`);
-    }
+    assertNativeSolidStatus(manifold, "solidFromMesh");
     return manifold;
 };