@metamesh/modeling 0.16.0 → 0.18.0

package/dist/engine/recipe-realization.js

@@ -1,7 +1,7 @@
 import { GeometryError } from "../geometry/errors.js";
+import { immutableBufferView, isImmutableBuffer } from "../geometry/immutable-buffer.js";
 import { isImmutableMathValue } from "../geometry/math/immutable-value.js";
 import { geometryRecipe, isGeometryRecipe } from "../model/geometry-recipes.js";
-import { immutableBufferView, isImmutableBuffer } from "../model/immutable-buffer.js";
 import { generationDataMetadata } from "../model/immutable-generation-data.js";
 /**
  * Evaluates immutable recipes within one host revision. These maps memoize borrowed native handles;

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

@@ -0,0 +1,116 @@
+import { Zip, ZipDeflate } from "fflate";
+import { GeometryError } from "../geometry/errors.js";
+import { analyzeSolidMesh } from "../geometry/mesh/mesh-solid.js";
+import { analyzeTriangleMesh, } from "../geometry/mesh/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 ||
+        name.length > 1024 ||
+        // 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) {
+        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;
+    const zip = new Zip((error, data, final) => {
+        if (error !== null)
+            throw error;
+        bytes += data.byteLength;
+        if (bytes >= 0xffffffff)
+            throw new GeometryError("COMPLEXITY_LIMIT", "3MF ZIP output exceeds its 32-bit container limit.", { operation: "export3mf" });
+        chunks.push(data);
+        complete = final;
+    });
+    const add = (path) => {
+        const file = new ZipDeflate(path, { level: 6 });
+        file.mtime = new Date(1980, 0, 1);
+        zip.add(file);
+        return file;
+    };
+    const addText = (path, contents) => add(path).push(encoder.encode(contents), true);
+    try {
+        addText("[Content_Types].xml", `${declaration}<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="model" ContentType="application/vnd.ms-package.3dmanufacturing-3dmodel+xml"/></Types>`);
+        addText("_rels/.rels", `${declaration}<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Target="/3D/3dmodel.model" Id="model" Type="http://schemas.microsoft.com/3dmanufacturing/2013/01/3dmodel"/></Relationships>`);
+        const model = add("3D/3dmodel.model");
+        let xml = "", xmlBytes = 0;
+        const flush = (final = false) => {
+            const data = encoder.encode(xml);
+            xmlBytes += data.byteLength;
+            if (xmlBytes >= 0xffffffff)
+                throw new GeometryError("COMPLEXITY_LIMIT", "3MF model XML exceeds its 32-bit ZIP entry limit.", { operation: "export3mf" });
+            model.push(data, final);
+            xml = "";
+        };
+        const append = (value) => {
+            xml += value;
+            if (xml.length >= 32_768)
+                flush();
+        };
+        append(`${declaration}<model unit="millimeter" xml:lang="en-US" xmlns="${namespace}"><metadata name="Application">MetaMesh Modeling</metadata><metadata name="Title">${escapeXml(name)}</metadata><resources>`);
+        const colors = new Map();
+        for (const part of parts)
+            if (part.color !== undefined && !colors.has(part.color.toLowerCase()))
+                colors.set(part.color.toLowerCase(), colors.size);
+        const materialId = parts.length + 1;
+        if (colors.size) {
+            append(`<basematerials id="${materialId}">`);
+            for (const color of colors.keys())
+                append(`<base name="Color ${color.slice(1)}" displaycolor="${color.toUpperCase()}FF"/>`);
+            append("</basematerials>");
+        }
+        parts.forEach((part, index) => {
+            const material = part.color === undefined
+                ? ""
+                : ` pid="${materialId}" pindex="${colors.get(part.color.toLowerCase())}"`;
+            append(`<object id="${index + 1}" name="${escapeXml(part.id)}" partnumber="${escapeXml(part.id)}" type="model"${material}><mesh><vertices>`);
+            for (let offset = 0; offset < part.positions.length; offset += 3)
+                append(`<vertex x="${part.positions[offset]}" y="${part.positions[offset + 1]}" z="${part.positions[offset + 2]}"/>`);
+            append("</vertices><triangles>");
+            for (let offset = 0; offset < part.indices.length; offset += 3)
+                append(`<triangle v1="${part.indices[offset]}" v2="${part.indices[offset + 1]}" v3="${part.indices[offset + 2]}"/>`);
+            append("</triangles></mesh></object>");
+        });
+        append("</resources><build>");
+        parts.forEach((_, index) => append(`<item objectid="${index + 1}"/>`));
+        append("</build></model>");
+        flush(true);
+        zip.end();
+        if (!complete)
+            throw new Error("The synchronous 3MF compressor did not complete.");
+        const result = new Uint8Array(bytes);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return result.buffer;
+    }
+    finally {
+        zip.terminate();
+    }
+}

package/dist/engine/{deferred-context.js → session/deferred-context.js}

@@ -1,7 +1,7 @@
-import { geometryRecipe, isGeometryRecipe } from "../model/geometry-recipes.js";
-import { dispatchModelOperation } from "../model/operation-dispatch.js";
-import { createRecipeContext } from "../model/recipe-declaration.js";
-import { RecipeRealization } from "./recipe-realization.js";
+import { geometryRecipe, isGeometryRecipe } from "../../model/geometry-recipes.js";
+import { dispatchModelOperation } from "../../model/operation-dispatch.js";
+import { createRecipeContext } from "../../model/recipe-declaration.js";
+import { RecipeRealization } from "../recipe-realization.js";
 /** Supplies active observations and limits without capturing the host's implicit sampling policy. */
 export function createDeferredContext(owner, native, limits, duringNative, assertActive, restoreNative = () => undefined) {
     const realization = new RecipeRealization(owner, native, duringNative, restoreNative);

package/dist/engine/{model-dependencies.js → session/dependencies.js}

@@ -32,7 +32,7 @@ export function createModelDependencies(output, modelParameters, entries, reader
             computations: Object.freeze([...(entry?.dependencies.keys() ?? [])].sort()),
         }))),
         parts: Object.freeze(output.map((part) => {
-            const roots = [part.geometry, part.position, part.rotation].flatMap((value) => {
+            const roots = [part.geometry, part.transform].flatMap((value) => {
                 const id = typeof value === "function" ? readerIds.get(value) : undefined;
                 return id === undefined ? [] : [id];
             });

package/dist/engine/{session-graph.js → session/graph.js}

@@ -1,8 +1,9 @@
-import { GeometryError } from "../geometry/errors.js";
-import { GenerationError, } from "../model/generation.js";
-import { captureGenerationDependencies, captureGenerationValue, compareGenerationValues, generationDataEntries, } from "../model/immutable-generation-data.js";
-import { createModelDependencies } from "./model-dependencies.js";
-import { assertSynchronousScopeResult } from "./native/ownership.js";
+import { GeometryError } from "../../geometry/errors.js";
+import { captureDiagnosticPath } from "../../model/diagnostic-path.js";
+import { GenerationError, } from "../../model/generation.js";
+import { captureGenerationDependencies, captureGenerationValue, compareGenerationValues, generationDataEntries, isImmutableGenerationValue, } from "../../model/immutable-generation-data.js";
+import { assertSynchronousScopeResult } from "../native/ownership.js";
+import { createModelDependencies } from "./dependencies.js";
 function reusableEntry(node) {
     if (node.state.kind === "ready")
         return node.state.entry;
@@ -28,7 +29,9 @@ function evaluateComputed(callback) {
 /** Reuse immutable captures only when the host supplies the same input value. */
 function captureParameters(input, previousInput, previousSnapshot) {
     return Object.freeze(Object.fromEntries(Array.from(generationDataEntries(input), ([key, value]) => {
-        if (Object.is(value, previousInput[key]) && Object.hasOwn(previousSnapshot, key))
+        if (Object.is(value, previousInput[key]) &&
+            Object.hasOwn(previousSnapshot, key) &&
+            isImmutableGenerationValue(value))
             return [key, previousSnapshot[key]];
         return [key, captureGenerationValue(value)];
     })));
@@ -329,6 +332,7 @@ export function createGenerationGraph(options, maxParts) {
                     severity,
                     message,
                     ...(metadata?.parameterId === undefined ? {} : { parameterId: metadata.parameterId }),
+                    ...(metadata?.path === undefined ? {} : { path: captureDiagnosticPath(metadata.path) }),
                 }));
                 if (severity === "error") {
                     assertionFailure ??= new GenerationError(diagnostics);
@@ -345,11 +349,9 @@ export function createGenerationGraph(options, maxParts) {
                 const configuration = typeof value === "object" && value !== null && "geometry" in value
                     ? value
                     : { geometry: value };
-                for (const value of [
-                    configuration.geometry,
-                    configuration.position,
-                    configuration.rotation,
-                ])
+                if ("position" in configuration || "rotation" in configuration)
+                    invalid("Part placement uses transform; position and rotation are not supported.");
+                for (const value of [configuration.geometry, configuration.transform])
                     if (typeof value === "function" && !readerIds.has(value))
                         invalid("Part readers must belong to this model session.");
                 const descriptor = Object.freeze({ ...configuration, id });

package/dist/engine/{session-native.js → session/native-cache.js}

@@ -1,4 +1,4 @@
-import { generationValueBytes } from "../model/immutable-generation-data.js";
+import { generationValueBytes } from "../../model/immutable-generation-data.js";
 function disposeValues(values) {
     const errors = [];
     for (const value of new Set(values)) {

package/dist/engine/{session.js → session/session.js}

@@ -1,15 +1,16 @@
-import { GeometryError } from "../geometry/errors.js";
-import { resolveModelingLimits } from "../geometry/model-limits.js";
-import { bindModelContext } from "../model/execution-binding.js";
-import { captureGenerationValue, generationValueBytes, } from "../model/immutable-generation-data.js";
+import { GeometryError } from "../../geometry/errors.js";
+import { resolveModelingLimits } from "../../geometry/model-limits.js";
+import { bindModelContext } from "../../model/execution-binding.js";
+import { GenerationError } from "../../model/generation.js";
+import { captureGenerationValue, generationValueBytes, } from "../../model/immutable-generation-data.js";
 import { createDeferredContext } from "./deferred-context.js";
-import { createGenerationGraph } from "./session-graph.js";
-import { createNativeGeometryCache } from "./session-native.js";
-import { createSnapshotCache } from "./session-snapshot.js";
+import { createGenerationGraph } from "./graph.js";
+import { createNativeGeometryCache } from "./native-cache.js";
+import { createSnapshotCache } from "./snapshot-cache.js";
 function invalid(message) {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: "generate" });
 }
-/** Coordinates native transactions and bounded atomic cache commits; snapshots own their lifetime. */
+/** Coordinates native transactions and bounded atomic cache commits; results remain durable after cache cleanup. */
 export function createSession(program, suppliedOptions, engineLimits, transaction) {
     const options = Object.freeze({
         ...suppliedOptions,
@@ -58,6 +59,11 @@ export function createSession(program, suppliedOptions, engineLimits, transactio
             // Nothing becomes reusable until geometry validation AND native cleanup have succeeded.
             revision.commit();
         }
+        catch (error) {
+            if (mode === "validate" && error instanceof GenerationError)
+                return error.diagnostics;
+            throw error;
+        }
         finally {
             try {
                 revision.dispose();
@@ -69,8 +75,8 @@ export function createSession(program, suppliedOptions, engineLimits, transactio
         return completed.capture.snapshot;
     }
     return Object.freeze({
-        run: (params) => execute(params, "run"),
-        validate: (params) => execute(params, "validate"),
+        run: (params) => execute(params === undefined ? {} : params, "run"),
+        check: (params) => execute(params === undefined ? {} : params, "validate"),
         clearCache() {
             if (running)
                 invalid("Cannot clear a running session.");

package/dist/engine/{session-snapshot.js → session/snapshot-cache.js}

@@ -1,26 +1,22 @@
-import { GeometryError } from "../geometry/errors.js";
-import { vector3Data } from "../geometry/math/vector-value.js";
-import { isImmutableBuffer } from "../model/immutable-buffer.js";
-import { createGeometryFinalizer, rememberSnapshotPart, } from "./finalization.js";
-import { createModelSummary } from "./model-summary.js";
-import { placeFinalizedGeometry } from "./placement.js";
+import { GeometryError } from "../../geometry/errors.js";
+import { isImmutableBuffer, ownImmutableBuffer } from "../../geometry/immutable-buffer.js";
+import { transform3 } from "../../geometry/transform-value.js";
+import { validateRigidTransform3 } from "../../geometry/transform3.js";
+import { createGeometryFinalizer } from "../finalization.js";
+import { requireModelPart } from "../model-parts.js";
+import { createModelSummary } from "../model-summary.js";
+import { placeFinalizedGeometry } from "../placement.js";
 let nextSession = 0;
 function invalid(message) {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: "generate" });
 }
-const vector = (value) => {
-    const result = value === undefined ? [0, 0, 0] : vector3Data(value);
-    if (!result.every(Number.isFinite))
-        invalid("Part placement requires three finite coordinates.");
-    return Object.freeze([...result]);
-};
 /** Only fixed buffer fields can establish immutable mesh identity across revisions. */
 function isImmutableMesh(value) {
     return (Object.isFrozen(value) &&
         isImmutableBuffer(Object.getOwnPropertyDescriptor(value, "positions")?.value) &&
         isImmutableBuffer(Object.getOwnPropertyDescriptor(value, "indices")?.value));
 }
-/** Publishes copied views while retaining the authoritative local buffers privately. */
+/** Publishes immutable views over already-owned local buffers. */
 function createResource(id, geometry, reusable) {
     return {
         geometry,
@@ -29,66 +25,44 @@ function createResource(id, geometry, reusable) {
             id,
             revision: 1,
             measurements: geometry.measurements,
-            get positions() {
-                return new Float32Array(geometry.positions);
-            },
-            get indices() {
-                return new Uint32Array(geometry.indices);
-            },
+            positions: ownImmutableBuffer(geometry.positions),
+            indices: ownImmutableBuffer(geometry.indices),
         }),
     };
 }
 /** Captures authoritative placement and appearance before consulting world-geometry reuse. */
 function capturePlacement(descriptor) {
-    const position = vector(typeof descriptor.position === "function" ? descriptor.position() : descriptor.position);
-    const rotation = vector(typeof descriptor.rotation === "function" ? descriptor.rotation() : descriptor.rotation);
+    const transform = validateRigidTransform3(transform3(typeof descriptor.transform === "function" ? descriptor.transform() : descriptor.transform).toData());
     const color = descriptor.color;
     if (color !== undefined && (typeof color !== "string" || !/^#[\da-f]{6}$/i.test(color)))
         invalid("Part colors must be six-digit hex strings.");
-    return { position, rotation, ...(color === undefined ? {} : { color: color.toLowerCase() }) };
+    return { transform, ...(color === undefined ? {} : { color: color.toLowerCase() }) };
 }
-/** Snapshot accessors own their copies; export can still use the trusted private world buffers. */
+/** Captures stable immutable world geometry without duplicating owned buffers. */
 function capturePart(id, geometry, placement, worldGeometry) {
     const part = Object.freeze({
         id,
         geometry,
         ...placement,
         measurements: worldGeometry.measurements,
-        get positions() {
-            return new Float32Array(worldGeometry.positions);
-        },
-        get indices() {
-            return new Uint32Array(worldGeometry.indices);
-        },
+        positions: ownImmutableBuffer(worldGeometry.positions),
+        indices: ownImmutableBuffer(worldGeometry.indices),
     });
-    rememberSnapshotPart(part, worldGeometry);
     return part;
 }
-/** Isolates a snapshot's lifetime from the cache transaction that produced it. */
-function createSnapshot(parts, { bounds, stats }, diagnostics, dependencies, generationStartedAt) {
-    const completedStats = Object.freeze({
-        ...stats,
-        generationMs: performance.now() - generationStartedAt,
-    });
-    let ownedParts = Object.freeze(parts);
-    const requireParts = () => ownedParts ?? invalid("This model snapshot has been disposed.");
+/** Publishes finalized data independently of the cache transaction that produced it. */
+function createResult(parts, { bounds, stats }, diagnostics, dependencies, generationStartedAt) {
+    const capturedParts = Object.freeze(parts);
     return Object.freeze({
-        get parts() {
-            return requireParts();
-        },
-        get bounds() {
-            requireParts();
-            return bounds;
-        },
-        get stats() {
-            requireParts();
-            return completedStats;
-        },
+        parts: capturedParts,
+        part: (id) => requireModelPart(capturedParts, id),
+        bounds,
+        stats: Object.freeze({
+            ...stats,
+            generateMs: performance.now() - generationStartedAt,
+        }),
         diagnostics: Object.freeze([...diagnostics]),
         dependencies,
-        dispose() {
-            ownedParts = undefined;
-        },
     });
 }
 /**
@@ -123,14 +97,10 @@ export function createSnapshotCache(options, limits) {
                 nextResources.set(geometry, resource);
                 const placement = capturePlacement(descriptor);
                 // World buffers belong to geometry and placement, independently of semantic part identity.
-                const placementKey = JSON.stringify([
-                    resource.public.id,
-                    placement.position,
-                    placement.rotation,
-                ]);
+                const placementKey = JSON.stringify([resource.public.id, placement.transform]);
                 const placed = nextPlaced.get(placementKey) ??
                     placedCache.get(placementKey) ??
-                    placeFinalizedGeometry(resource.geometry, placement.position, placement.rotation, options.meshValidation);
+                    placeFinalizedGeometry(resource.geometry, placement.transform, options.meshValidation);
                 nextPlaced.set(placementKey, placed);
                 summary.add(placed);
                 worldParts.push(capturePart(descriptor.id, resource.public, placement, placed));
@@ -141,7 +111,7 @@ export function createSnapshotCache(options, limits) {
             return {
                 // Publish only after retention, native cleanup and cache commit have succeeded.
                 get snapshot() {
-                    return (snapshot ??= createSnapshot(worldParts, model, diagnostics, dependencies, generationStartedAt));
+                    return (snapshot ??= createResult(worldParts, model, diagnostics, dependencies, generationStartedAt));
                 },
                 retainedValues: [
                     ...nextResources.keys(),

package/dist/geometry/anchors.js

@@ -32,11 +32,7 @@ const boxFaces = {
 const primitiveAnchorOrigin = (options, operation) => {
     if (options.center !== undefined && typeof options.center !== "boolean")
         throw new GeometryError("INVALID_ARGUMENT", "center must be boolean.", { operation });
-    const origin = options.origin === undefined ? [0, 0, 0] : options.origin;
-    if (!Array.isArray(origin) || origin.length !== 3)
-        throw new GeometryError("INVALID_ARGUMENT", "origin must be an exact XYZ tuple.", {
-            operation,
-        });
+    const origin = options.origin === undefined ? [0, 0, 0] : vector3Data(options.origin);
     for (let axis = 0; axis < 3; axis++)
         if (!Number.isFinite(origin[axis]))
             throw new GeometryError("NON_FINITE_VALUE", "Anchor origin must be finite.", { operation });
@@ -54,12 +50,9 @@ export function boxAnchor3(options) {
     const operation = "boxAnchor3";
     assertAnchorOptions(options, operation);
     const origin = primitiveAnchorOrigin(options, operation);
-    if (typeof options.size !== "number" &&
-        (!Array.isArray(options.size) || options.size.length !== 3))
-        throw new GeometryError("INVALID_ARGUMENT", "Box anchor size must be a number or XYZ tuple.", {
-            operation,
-        });
-    const size = typeof options.size === "number" ? [options.size, options.size, options.size] : options.size;
+    const size = typeof options.size === "number"
+        ? [options.size, options.size, options.size]
+        : vector3Data(options.size);
     for (let axis = 0; axis < 3; axis++)
         if (!Number.isFinite(size[axis]) || size[axis] <= 0)
             throw new GeometryError("INVALID_ARGUMENT", "Box anchor dimensions must be positive.", {

package/dist/geometry/bounds-value.js

@@ -1,25 +1,61 @@
 import { boundsCenter, boundsSize, containsBounds, validateBounds } from "./bounds.js";
-import { GeometryError } from "./errors.js";
+import { GeometryError, isGeometryError } from "./errors.js";
 import { immutableMathClass } from "./math/immutable-value.js";
-import { vector2, vector3 } from "./math/vector-value.js";
+import { vector2, vector2Data, vector3, vector3Data, } from "./math/vector-value.js";
 function fail(dimension, message) {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation: `bounds${dimension}` });
 }
 function snapshot(input, dimension) {
-    if (typeof input !== "object" || input === null)
-        fail(dimension, "Bounds require minimum and maximum coordinate tuples.");
-    const { min, max } = input;
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        fail(dimension, "Bounds require extrema or size.");
+    const { size, center } = input;
+    const coordinates = (value) => {
+        try {
+            return dimension === 2
+                ? vector2Data(value)
+                : vector3Data(value);
+        }
+        catch (error) {
+            if (isGeometryError(error) && error.code === "INVALID_ARGUMENT")
+                fail(dimension, `Bounds require matching ${dimension}D vectors or coordinate tuples.`);
+            throw error;
+        }
+    };
+    let min, max;
+    // Existing immutable bounds expose size()/center(); only a size value selects construction.
+    if ("size" in input && typeof size !== "function") {
+        if ("min" in input || "max" in input)
+            fail(dimension, "Supply size or min/max, never both.");
+        if (center !== undefined && typeof center !== "boolean")
+            fail(dimension, "center must be boolean.");
+        const sizeCoordinates = coordinates(size);
+        const dimensions = Array.from({ length: dimension }, (_, axis) => {
+            const value = sizeCoordinates[axis];
+            if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+                fail(dimension, "Size must be finite and nonnegative.");
+            return value;
+        });
+        const centered = center ?? true;
+        min = dimensions.map((value) => (centered ? -value / 2 : 0));
+        max = dimensions.map((value) => (centered ? value / 2 : value));
+    }
+    else {
+        if (center !== undefined && typeof center !== "function")
+            fail(dimension, "center requires size construction.");
+        const extrema = input;
+        min = coordinates(extrema.min);
+        max = coordinates(extrema.max);
+    }
     if (!Array.isArray(min) ||
         !Array.isArray(max) ||
         min.length !== dimension ||
         max.length !== dimension)
         fail(dimension, `Bounds require matching ${dimension}D minimum and maximum tuples.`);
-    const minimum = min, maximum = max;
     const copy = (source) => Object.freeze(Array.from({ length: dimension }, (_, axis) => {
         const value = source[axis];
         return value === 0 ? 0 : value;
     }));
-    const data = Object.freeze({ min: copy(minimum), max: copy(maximum) });
+    const data = Object.freeze({ min: copy(min), max: copy(max) });
     validateBounds(data, `bounds${dimension}`);
     return data;
 }
@@ -70,23 +106,25 @@ const SpatialBounds = /* @__PURE__ */ immutableMathClass(class SpatialBounds {
     }
 });
 /**
- * Snapshots finite ordered XY bounds in millimetres as an immutable fluent value.
+ * Constructs immutable finite XY bounds from ordered extrema or nonnegative size in millimetres.
  *
  * Zero extents are valid. Invalid dimensions, nonfinite coordinates, reversed bounds and
  * overflowing extents throw `INVALID_ARGUMENT` GeometryError. Use `toData()` for plain records.
+ * Size construction centers on the origin unless `center` is false. Size and extrema are exclusive.
  * Compiled Generator packages passing these values to host recipes or computed data require
- * runtime 8.0.0 or newer in major 8.
+ * runtime 10.0.0 or newer in major 10.
  */
 export function bounds2(input) {
     return new PlanarBounds(snapshot(input, 2));
 }
 /**
- * Snapshots finite ordered XYZ bounds in millimetres as an immutable fluent value.
+ * Constructs immutable finite XYZ bounds from ordered extrema or nonnegative size in millimetres.
  *
  * Zero extents are valid. Invalid dimensions, nonfinite coordinates, reversed bounds and
  * overflowing extents throw `INVALID_ARGUMENT` GeometryError. Use `toData()` for plain records.
+ * Size construction centers on the origin unless `center` is false. Size and extrema are exclusive.
  * Compiled Generator packages passing these values to host recipes or computed data require
- * runtime 8.0.0 or newer in major 8.
+ * runtime 10.0.0 or newer in major 10.
  */
 export function bounds3(input) {
     return new SpatialBounds(snapshot(input, 3));

package/dist/geometry/bounds.js

@@ -37,23 +37,6 @@ function size(bounds) {
 function center(bounds) {
     return bounds.min.map((value, axis) => value / 2 + bounds.max[axis] / 2);
 }
-export function boundsFromSize(dimensions, options = {}) {
-    const operation = "boundsFromSize";
-    if (!isArray(dimensions) ||
-        (dimensions.length !== 2 && dimensions.length !== 3) ||
-        Array.from(dimensions).some((value) => !Number.isFinite(value) || value < 0))
-        fail(operation, "Bounds dimensions require two or three finite nonnegative values.");
-    if (typeof options !== "object" ||
-        options === null ||
-        isArray(options) ||
-        (options.center !== undefined && typeof options.center !== "boolean"))
-        fail(operation, "Bounds placement requires an optional boolean center value.");
-    const centered = options.center ?? true;
-    return Object.freeze({
-        min: vector(dimensions.map((value) => (centered ? -value / 2 : 0)), operation),
-        max: vector(dimensions.map((value) => (centered ? value / 2 : value)), operation),
-    });
-}
 export function boundsSize(bounds) {
     validateBounds(bounds, "boundsSize");
     return vector(size(bounds), "boundsSize");

package/dist/geometry/circular-sampling.js

@@ -0,0 +1,45 @@
+import { GeometryError } from "./errors.js";
+import { resolveCircularPrimitiveSegments } from "./primitive-resolution.js";
+import { assertPrimitiveOptions } from "./primitive-resolvers.js";
+function fail(message, nonfinite = false) {
+    throw new GeometryError(nonfinite ? "NON_FINITE_VALUE" : "INVALID_ARGUMENT", message, {
+        operation: "resolveCircularSampling",
+    });
+}
+/**
+ * Resolves circular sampling and its actual radial envelopes without allocating boundary points.
+ *
+ * Vertex sizing retains the nominal vertex radius; face sizing retains the nominal face radius.
+ * Exact `segments` override resolution, while allocation ceilings still apply. Adaptive sampling
+ * uses the same count calculation as `resolveCircularSegments` and `circleContour` and rejects
+ * exhausted limits rather than coarsening. The returned record is immutable and needs no engine.
+ *
+ * @example Check a nominal 8 mm face-sized bore
+ * ```ts
+ * const bore = resolveCircularSampling({ diameter: 8, segments: 64, sizing: "face" });
+ * bore.faceRadius; // 4 mm
+ * bore.vertexRadius; // slightly larger than 4 mm
+ * ```
+ */
+export function resolveCircularSampling(options) {
+    const operation = "resolveCircularSampling";
+    assertPrimitiveOptions(options, operation);
+    if ((options.radius === undefined) === (options.diameter === undefined)) {
+        fail("Specify exactly one radius or diameter.");
+    }
+    const radius = options.radius ?? options.diameter / 2;
+    const finite = Number.isFinite(radius);
+    if (!finite || radius <= 0)
+        fail("Circle radius must be finite and positive.", !finite);
+    const sizing = options.sizing ?? "vertex";
+    if (sizing !== "vertex" && sizing !== "face") {
+        fail("sizing must be vertex or face.");
+    }
+    const segments = resolveCircularPrimitiveSegments(radius, options, operation);
+    const cosine = Math.cos(Math.PI / segments);
+    const vertexRadius = sizing === "face" ? radius / cosine : radius;
+    const faceRadius = sizing === "face" ? radius : radius * cosine;
+    if (!Number.isFinite(vertexRadius))
+        fail("Sampled radii must remain finite.", true);
+    return Object.freeze({ segments, vertexRadius, faceRadius });
+}