@metamesh/modeling 0.7.0 → 0.8.0

package/dist/api/index.d.ts

@@ -225,6 +225,9 @@ export declare type CylinderOptions = CircularPrimitiveOptions & RadialSizingOpt
     readonly radius?: never;
 });
 
+/** Measures the minimum separation between two nonempty solids in millimetres. */
+export declare const distance: ModelingContext["distance"];
+
 /**
  * Uniform finishing vocabulary shared by applicable solid edges and profile corners.
  */
@@ -403,22 +406,57 @@ export declare type GridPatternOptions = {
     readonly spacing: Vec3;
 });
 
-/** Constructs a closed regularly sampled heightfield during the active synchronous build. */
+/** Constructs a closed rectilinear heightfield during the active synchronous build. */
 export declare const heightfield: ModelingContext["heightfield"];
 
-/** A regularly sampled, closed heightfield above a flat base, in millimetres. */
-export declare interface HeightfieldOptions {
-    /** Positive XY footprint. */
-    readonly size: Vec2;
-    /** Exact positive integer X/Y interval counts. */
-    readonly segments: readonly [x: number, y: number];
+/**
+ * A closed rectilinear heightfield above a flat base, with uniform or explicit XY samples in millimetres.
+ *
+ * Uniform sampling requires positive `size: [width, depth]` and positive integer `segments: [x, y]`.
+ * Optional `origin` sets the lower-left XY corner; omitting it centres the footprint on XY.
+ * Alternatively, supply `coordinates: { x, y }` with at least two strictly increasing finite
+ * absolute samples per axis, distinct in Float32. This infers the footprint and interval counts;
+ * `size`, `segments`, and `origin` cannot be combined with explicit coordinates.
+ */
+export declare type HeightfieldOptions = {
     /** Absolute top Z at the supplied XY point. Every sample must be above baseZ. */
     readonly height: (point: Vec2) => number;
     /** Flat bottom Z. Defaults to zero. */
     readonly baseZ?: number;
+    /**
+     * Top-cell diagonal policy. Defaults to fixed (lower-left to upper-right).
+     * min-edge selects the shorter 3D diagonal; center-error selects the diagonal whose endpoint
+     * average is closest to one extra height sample at the physical cell centre. Ties use fixed.
+     * All policies retain two triangles per cell; neither estimates error elsewhere in the cell.
+     */
+    readonly triangulation?: "fixed" | "min-edge" | "center-error";
+} & ({
+    /** Positive XY footprint for uniform sampling. */
+    readonly size: Vec2;
+    /** Exact positive integer X/Y interval counts. */
+    readonly segments: readonly [x: number, y: number];
     /** Lower-left footprint XY. Omitted centers the footprint on XY. */
     readonly origin?: Vec2;
-}
+    /** Explicit coordinates cannot be combined with uniform sampling. */
+    readonly coordinates?: never;
+} | {
+    /**
+     * Absolute XY coordinates, each with at least two strictly increasing finite values that
+     * remain distinct in Float32. Uneven spacing permits caller-owned local refinement.
+     */
+    readonly coordinates: {
+        /** Absolute X samples in ascending order. */
+        readonly x: readonly number[];
+        /** Absolute Y samples in ascending order. */
+        readonly y: readonly number[];
+    };
+    /** The footprint is inferred from explicit coordinates. */
+    readonly size?: never;
+    /** Interval counts are inferred from explicit coordinates. */
+    readonly segments?: never;
+    /** Explicit coordinates already include their origin. */
+    readonly origin?: never;
+});
 
 /** Runtime-neutral options for the dedicated helical ridge mesher. */
 export declare interface HelicalThreadRidgeMeshOptions {
@@ -488,7 +526,7 @@ export declare interface ImplicitOptions {
     readonly edgeLength: number;
     /** Field isosurface value; defaults to zero. */
     readonly level?: number;
-    /** Explicit nonnegative native geometric tolerance in millimetres. */
+    /** Positive native geometric tolerance in millimetres; omitted uses interpolated grid crossings. */
     readonly tolerance?: number;
 }
 
@@ -512,6 +550,9 @@ export declare interface InternalThreadCutterOptions extends Omit<HelicalThreadR
 /** Host-bound intersect operation. Valid only during a synchronous build. */
 export declare const intersect: ModelingContext["intersect"];
 
+/** Tests a solid or filled section in the active build, including expected empty Boolean results. */
+export declare const isEmpty: ModelingContext["isEmpty"];
+
 /** Host-bound linearPattern operation. Valid only during a synchronous build. */
 export declare const linearPattern: ModelingContext["linearPattern"];
 
@@ -733,6 +774,44 @@ export declare interface ModelingContext {
     intersect(this: void, solids: readonly Solid[]): Solid;
     /** Native filled section intersection; dimensions cannot be mixed. */
     intersect(this: void, sections: readonly Section[]): Section;
+    /**
+     * Splits a solid into [inside the cutter, outside the cutter].
+     *
+     * The first result is the intersection; the second is the subtraction. The cutter itself
+     * is not returned. Either result may be empty or contain multiple disconnected components.
+     *
+     * @example Keep the plug and the surrounding body
+     * ```ts
+     * const body = box({ size: [30, 20, 8] });
+     * const cutter = cylinder({ height: 10, diameter: 8 });
+     * const [plug, remainder] = split(body, cutter);
+     * // Move the plug beside the body to show both results.
+     * union([translate(plug, [0, -20, 0]), remainder]);
+     * ```
+     */
+    split(this: void, solid: Solid, cutter: Solid): readonly [Solid, Solid];
+    /**
+     * Splits a solid into [positive-normal side, negative side] at a world-space plane.
+     *
+     * The nonzero normal is normalized; offset is the signed distance from the origin in
+     * millimetres, defaulting to zero. Both cut faces are closed. Select either tuple result
+     * to retain one side; either result may be empty.
+     *
+     * @example Separate two halves at X = 0
+     * ```ts
+     * const body = box({ size: [30, 20, 8] });
+     * const [right, left] = splitByPlane(body, { normal: [1, 0, 0] });
+     * // The gap is only for display; the cut itself removes no material.
+     * union([translate(right, [4, 0, 0]), translate(left, [-4, 0, 0])]);
+     * ```
+     *
+     * @example Keep only the positive half
+     * ```ts
+     * const [right] = splitByPlane(box({ size: [30, 20, 8] }), { normal: [1, 0, 0] });
+     * right;
+     * ```
+     */
+    splitByPlane(this: void, solid: Solid, plane: PlaneOptions): readonly [Solid, Solid];
     /** Combines disjoint components without resolving overlap. */
     compose(this: void, solids: readonly Solid[]): Solid;
     /**
@@ -746,6 +825,8 @@ export declare interface ModelingContext {
      * ```
      */
     hull(this: void, options: HullOptions): Solid;
+    /** Convex filled XY hull of finite points or same-build sections. */
+    hull(this: void, options: SectionHullOptions): Section;
     /** Three-dimensional Minkowski sum. */
     minkowskiSum(this: void, a: Solid, b: Solid): Solid;
     /**
@@ -966,7 +1047,7 @@ export declare interface ModelingContext {
      */
     inspectSection(this: void, section: Section): SectionInspection;
     /**
-     * Copies solid bounds and volume; temporary components are owned by the build.
+     * Reads immutable native facts once per solid; temporary components are owned by the build.
      *
      * @example Check dimensions and volume
      * ```ts
@@ -975,18 +1056,85 @@ export declare interface ModelingContext {
      * ```
      */
     inspectSolid(this: void, solid: Solid): SolidInspection;
+    /**
+     * Checks whether a same-build solid or filled section contains no geometry.
+     *
+     * Accepts a 3D Solid or 2D Section handle, not a finalized model or raw triangle mesh.
+     * Useful after a Boolean operation whose inputs may not overlap; no mesh is extracted.
+     *
+     * @example Check a missed intersection
+     * ```ts
+     * const body = box({ size: 10 });
+     * const distant = translate(box({ size: 10 }), [30, 0, 0]);
+     * const empty = intersect([body, distant]);
+     * const missed = isEmpty(empty); // true
+     * ```
+     */
+    isEmpty(this: void, shape: Solid | Section): boolean;
+    /**
+     * Measures the minimum separation between two nonempty solids in millimetres.
+     *
+     * Uses actual geometry, not bounding-box separation or distance between object origins.
+     * Contact or overlapping material returns zero, including one solid inside another.
+     * The kernel's search range is managed internally; the result is not capped at a caller limit.
+     * Empty, expired or foreign-build handles reject. Results follow native numeric precision.
+     *
+     * @example Measure the gap between two blocks
+     * ```ts
+     * const left = box({ size: 10 });
+     * const right = translate(box({ size: 10 }), [13, 0, 0]);
+     * const gap = distance(left, right); // 3 mm
+     * ```
+     */
+    distance(this: void, solid: Solid, other: Solid): number;
     /** Copies intersections along the finite directed origin-to-endpoint segment. */
     rayCast(this: void, solid: Solid, origin: Vec3, endpoint: Vec3): readonly SolidRayHit[];
-    /** Returns same-build disconnected solid handles. */
+    /**
+     * Separates a solid's disconnected surface shells into same-build solid handles.
+     *
+     * For solids without enclosed cavities, these shells are the disconnected material islands.
+     * Enclosed cavities produce separate inward shells with negative signed volume; these cannot
+     * be finalized alone as manufacturing parts. This does not cut connected geometry.
+     *
+     * @example Move disconnected pieces independently
+     * ```ts
+     * const islands = union([box({ size: 8 }), translate(box({ size: 8 }), [12, 0, 0])]);
+     * const pieces = components(islands);
+     * // Component order is unspecified; the index only sets a display height here.
+     * union(pieces.map((piece, index) => translate(piece, [0, 0, index * 6])));
+     * ```
+     */
     components(this: void, solid: Solid): readonly Solid[];
-    /** Removes features within the explicit millimetre tolerance. */
+    /** Separates filled 2D islands into sections, retaining each island's holes; empty gives []. */
+    components(this: void, section: Section): readonly Section[];
+    /**
+     * Simplifies a solid using an explicit positive millimetre tolerance.
+     *
+     * Removes redundant vertices while keeping surfaces within the greater of this tolerance
+     * and the solid's existing native tolerance. Choose it from the detail you can afford to lose.
+     */
     simplify(this: void, solid: Solid, tolerance: number): Solid;
+    /**
+     * Simplifies filled 2D contours using an explicit positive millimetre tolerance.
+     *
+     * Useful for dense imported outlines before extrusion. This changes the outline rather
+     * than selecting a lower rendering quality; fine features may be removed.
+     *
+     * @example Clean a dense outline before extrusion
+     * ```ts
+     * const outline = circle({ diameter: 20, segments: 256 });
+     * const cleaned = simplify(outline, 0.05); // 0.05 mm cleanup tolerance
+     * const body = extrude(cleaned, { height: 3 });
+     * ```
+     */
+    simplify(this: void, section: Section, tolerance: number): Section;
     /** Bounded positive-inside implicit field constructor. */
     implicit(this: void, options: ImplicitOptions): Solid;
     /** Replaces native tolerance on an immutable copy; zero selects the kernel minimum. */
     setTolerance(this: void, solid: Solid, tolerance: number): Solid;
     /**
-     * Closed regular-grid top above a flat base; every height is sampled once.
+     * Closed rectilinear top above a flat base, with uniform or explicit XY coordinates.
+     * Samples each grid height once; center-error triangulation also samples each cell centre.
      *
      * @example Heightfield
      * ```ts
@@ -1171,6 +1319,14 @@ export declare interface PathPatternOptions {
  */
 export declare type PatternSource = Solid | ((index: number) => Solid);
 
+/** A world-space cutting plane, retaining the half-space in the normal's direction. */
+export declare interface PlaneOptions {
+    /** Finite nonzero plane normal; magnitude does not affect the plane. */
+    readonly normal: Vec3;
+    /** Signed millimetre distance from the origin along the unit normal. Defaults to zero. */
+    readonly offset?: number;
+}
+
 /**
  * One bounded two-dimensional polygon.
  *
@@ -1473,10 +1629,26 @@ export declare interface SectionFromContoursOptions {
     readonly fillRule?: "nonzero" | "evenodd";
 }
 
+/** Planar convex hull inputs are finite XY points or same-build filled sections. */
+export declare type SectionHullOptions = {
+    /** At least three finite millimetre XY points spanning positive area. */
+    readonly points: readonly Vec2[];
+    /** Point input excludes section input. */
+    readonly sections?: never;
+} | {
+    /** One through 1000 same-build sections to include in the convex hull. */
+    readonly sections: readonly Section[];
+    /** Section input excludes point input. */
+    readonly points?: never;
+};
+
 /**
- * Copied native filled section facts in millimetres and square millimetres.
+ * Immutable native filled section facts in millimetres and square millimetres.
+ * Repeated inspections of the same native shape share these facts within one build.
  */
 export declare interface SectionInspection {
+    /** Whether this filled section has no area or boundary. */
+    readonly isEmpty: boolean;
     /** Filled section area in square millimetres. */
     readonly area: number;
     /** Number of extracted outer and hole contours. */
@@ -1526,17 +1698,24 @@ declare const solidBrand: unique symbol;
 export declare const solidFromMesh: ModelingContext["solidFromMesh"];
 
 /**
- * Copied solid bounds, connected component count, and cubic millimetre volume.
+ * Immutable solid bounds, emptiness, component count, volume, surface area and native tolerance.
+ * Repeated inspections of the same native shape share these facts within one build.
  */
 export declare interface SolidInspection {
+    /** Whether this native solid contains no material. */
+    readonly isEmpty: boolean;
     /** Inclusive maximum coordinates in millimetres. */
     readonly max: Vec3;
     /** Inclusive minimum coordinates in millimetres. */
     readonly min: Vec3;
-    /** Number of connected native solid components. */
+    /** Number of connected surface shells; inward cavity shells count separately. */
     readonly parts: number;
     /** Enclosed native solid volume in cubic millimetres. */
     readonly volume: number;
+    /** Total native surface area in square millimetres. */
+    readonly surfaceArea: number;
+    /** Effective native geometric tolerance in millimetres. */
+    readonly tolerance: number;
 }
 
 /** Named same-build solid manufacturing part. */
@@ -1581,6 +1760,12 @@ export declare type SphereOptions = CircularPrimitiveOptions & PrimitivePlacemen
     readonly radius?: never;
 });
 
+/** Returns intersection and difference with a same-build cutter, including empty results. */
+export declare const split: ModelingContext["split"];
+
+/** Splits a solid into the normal-side and opposite-side halves of a world-space plane. */
+export declare const splitByPlane: ModelingContext["splitByPlane"];
+
 /** Square profile with equal crest and root widths. */
 declare interface SquareThreadProfileSpec extends ThreadProfileBaseSpec {
     /** Selects the square profile family. */
@@ -2067,9 +2252,9 @@ export declare interface VectorTextLayout {
 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/api/text.d.ts

@@ -18,11 +18,11 @@ export declare function prepareVectorFont(bytes: Uint8Array, options?: VectorFon
  * 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;
 }
 
@@ -32,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. */
@@ -51,14 +63,16 @@ export declare interface VectorTextLayout {
 }
 
 /**
- * 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";
 }
 
@@ -66,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;