@metamesh/modeling 0.17.0 → 0.19.0

package/dist/export/glb.js

@@ -0,0 +1,209 @@
+import { GeometryError } from "../geometry/errors.js";
+import { renderMesh } from "../geometry/mesh/mesh-render.js";
+import { captureExport } from "./capture.js";
+import { collectExport, createExportWriter } from "./writer.js";
+const alignedLength = (length) => Math.ceil(length / 4) * 4;
+const linearChannel = (value) => value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+function baseColor(color) {
+    return [
+        linearChannel(Number.parseInt(color.slice(1, 3), 16) / 255),
+        linearChannel(Number.parseInt(color.slice(3, 5), 16) / 255),
+        linearChannel(Number.parseInt(color.slice(5, 7), 16) / 255),
+        1,
+    ];
+}
+/**
+ * Serializes captured local meshes as uncompressed glTF 2.0 binary, in metres and Y-up.
+ * Preserves named parts, placement, shared geometry and display appearance. Authored normals take
+ * precedence over crease-aware shading; no engine, renderer or optional compression codec is loaded.
+ */
+export function exportGlb(parts, options = {}) {
+    return collectExport((sink) => writeGlb(parts, sink, options));
+}
+/**
+ * Writes owned GLB chunks with backpressure, cancellation and explicit output limits.
+ * Plans accessor and container lengths before writing, then emits bounded binary chunks.
+ * Hosts own sink completion, scheduling and recovery after a partially written failure.
+ */
+export async function writeGlb(parts, sink, options = {}) {
+    const captured = captureExport(parts, options, "glb");
+    const creaseAngle = options.creaseAngle ?? 20;
+    if (!Number.isFinite(creaseAngle) || creaseAngle < 0 || creaseAngle > 180)
+        throw new GeometryError("INVALID_ARGUMENT", "Crease angle must be from 0 through 180 degrees.", {
+            operation: "exportGlb",
+        });
+    const writer = createExportWriter(captured, sink, "glb");
+    const accessors = [];
+    const bufferViews = [];
+    const attributes = [];
+    const materials = [];
+    const meshes = [];
+    const nodes = [];
+    const geometryAccessors = new Map();
+    const materialIndices = new Map();
+    const meshIndices = new Map();
+    let binaryLength = 0;
+    let lastYield = performance.now();
+    const addAttribute = (data, componentType, type, bounds) => {
+        const byteLength = data.length * (componentType === 5123 ? 2 : 4);
+        const bufferView = bufferViews.length;
+        bufferViews.push({
+            buffer: 0,
+            byteOffset: binaryLength,
+            byteLength,
+            target: type === "SCALAR" ? 34963 : 34962,
+        });
+        binaryLength += alignedLength(byteLength);
+        if (binaryLength > captured.limits.maxOutputBytes || binaryLength >= 0x1_0000_0000)
+            throw new GeometryError("COMPLEXITY_LIMIT", "GLB binary data exceeds the output limits.", {
+                operation: "exportGlb",
+            });
+        attributes.push({ data, componentType, byteLength });
+        const accessor = accessors.length;
+        accessors.push({
+            bufferView,
+            componentType,
+            count: data.length / (type === "VEC3" ? 3 : 1),
+            type,
+            ...bounds,
+        });
+        return accessor;
+    };
+    for (const part of captured.parts) {
+        captured.signal?.throwIfAborted();
+        let geometry = geometryAccessors.get(part.geometry);
+        if (geometry === undefined) {
+            const rendered = part.geometry.normals === undefined
+                ? renderMesh(part.geometry, { creaseAngle })
+                : { ...part.geometry, normals: part.geometry.normals };
+            const min = [Infinity, Infinity, Infinity];
+            const max = [-Infinity, -Infinity, -Infinity];
+            for (let index = 0; index < rendered.positions.length; index += 3)
+                for (let axis = 0; axis < 3; axis += 1) {
+                    min[axis] = Math.min(min[axis], rendered.positions[index + axis]);
+                    max[axis] = Math.max(max[axis], rendered.positions[index + axis]);
+                }
+            const position = addAttribute(rendered.positions, 5126, "VEC3", { min, max });
+            const normal = addAttribute(rendered.normals, 5126, "VEC3");
+            let maximumIndex = 0;
+            for (const index of rendered.indices)
+                maximumIndex = Math.max(maximumIndex, index);
+            // glTF reserves the component type's largest integer for primitive restart.
+            const indices = addAttribute(rendered.indices, maximumIndex < 65_535 ? 5123 : 5125, "SCALAR");
+            geometry = { position, normal, indices };
+            geometryAccessors.set(part.geometry, geometry);
+        }
+        const color = part.color ?? "#ffffff";
+        const materialKey = `${part.materialId ?? ""}:${color.toLowerCase()}`;
+        let material = materialIndices.get(materialKey);
+        if (material === undefined) {
+            material = materials.length;
+            materials.push({
+                ...(part.materialId === undefined
+                    ? {}
+                    : { name: part.materialId, extras: { materialId: part.materialId } }),
+                pbrMetallicRoughness: {
+                    baseColorFactor: baseColor(color),
+                    metallicFactor: 0,
+                    roughnessFactor: 1,
+                },
+            });
+            materialIndices.set(materialKey, material);
+        }
+        const meshKey = `${geometry.position}:${material}`;
+        let mesh = meshIndices.get(meshKey);
+        if (mesh === undefined) {
+            mesh = meshes.length;
+            meshes.push({
+                primitives: [
+                    {
+                        attributes: { POSITION: geometry.position, NORMAL: geometry.normal },
+                        indices: geometry.indices,
+                        material,
+                    },
+                ],
+            });
+            meshIndices.set(meshKey, mesh);
+        }
+        const transform = part.transform;
+        const matrix = Array.from({ length: 16 }, (_, index) => transform[(index % 4) * 4 + Math.floor(index / 4)]);
+        nodes.push({ name: part.id, mesh, matrix });
+        if (performance.now() - lastYield >= 16) {
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            lastYield = performance.now();
+        }
+    }
+    captured.signal?.throwIfAborted();
+    const rootNode = nodes.length;
+    nodes.push({
+        name: captured.name,
+        // Column-major matrix: x'=x/1000, y'=z/1000, z'=-y/1000.
+        matrix: [0.001, 0, 0, 0, 0, 0, -0.001, 0, 0, 0.001, 0, 0, 0, 0, 0, 1],
+        children: Array.from({ length: rootNode }, (_, index) => index),
+    });
+    const json = new TextEncoder().encode(JSON.stringify({
+        asset: { version: "2.0", generator: "MetaMesh" },
+        scene: 0,
+        scenes: [{ name: captured.name, nodes: [rootNode] }],
+        nodes,
+        meshes,
+        materials,
+        accessors,
+        bufferViews,
+        buffers: [{ byteLength: binaryLength }],
+    }));
+    const paddedJsonLength = alignedLength(json.byteLength);
+    const fileLength = 12 + 8 + paddedJsonLength + 8 + binaryLength;
+    if (fileLength >= 0x1_0000_0000 || fileLength > captured.limits.maxOutputBytes)
+        throw new GeometryError("COMPLEXITY_LIMIT", "GLB container exceeds the output limits.", {
+            operation: "exportGlb",
+        });
+    const header = new Uint8Array(20);
+    const headerView = new DataView(header.buffer);
+    headerView.setUint32(0, 0x46546c67, true);
+    headerView.setUint32(4, 2, true);
+    headerView.setUint32(8, fileLength, true);
+    headerView.setUint32(12, paddedJsonLength, true);
+    headerView.setUint32(16, 0x4e4f534a, true);
+    await writer.write(header);
+    const paddedJson = new Uint8Array(paddedJsonLength).fill(0x20);
+    paddedJson.set(json);
+    for (let start = 0; start < paddedJson.length; start += 65_536)
+        await writer.write(paddedJson.slice(start, start + 65_536));
+    const binaryHeader = new Uint8Array(8);
+    const binaryHeaderView = new DataView(binaryHeader.buffer);
+    binaryHeaderView.setUint32(0, binaryLength, true);
+    binaryHeaderView.setUint32(4, 0x004e4942, true);
+    await writer.write(binaryHeader);
+    for (const attribute of attributes) {
+        const width = attribute.componentType === 5123 ? 2 : 4;
+        const elementsPerChunk = 65_536 / width;
+        for (let start = 0; start < attribute.data.length; start += elementsPerChunk) {
+            const count = Math.min(elementsPerChunk, attribute.data.length - start);
+            const chunk = new Uint8Array(count * width);
+            const view = new DataView(chunk.buffer);
+            for (let index = 0; index < count; index += 1) {
+                const value = attribute.data[start + index];
+                if (attribute.componentType === 5126)
+                    view.setFloat32(index * width, value, true);
+                else if (attribute.componentType === 5123)
+                    view.setUint16(index * width, value, true);
+                else
+                    view.setUint32(index * width, value, true);
+            }
+            await writer.write(chunk);
+        }
+        const padding = alignedLength(attribute.byteLength) - attribute.byteLength;
+        if (padding > 0)
+            await writer.write(new Uint8Array(padding));
+    }
+    const diagnostics = [];
+    const assigned = captured.parts.filter((part) => part.materialId !== undefined);
+    if (assigned.length > 0)
+        diagnostics.push({
+            code: "MATERIAL_ASSIGNMENTS_DROPPED",
+            message: "GLB preserves material identities as metadata and appearance, without print material assignment semantics.",
+            partIds: assigned.map((part) => part.id),
+        });
+    return writer.report(diagnostics);
+}

package/dist/export/index.js

@@ -0,0 +1,5 @@
+/** Runtime-independent completed-mesh export. All input coordinates are millimetres, right-handed, and Z-up. @packageDocumentation */
+export { export3mf, write3mf } from "./3mf.js";
+export { exportStl, writeStl } from "./stl.js";
+export { exportGlb, writeGlb } from "./glb.js";
+export { defaultExportLimits } from "./limits.js";

package/dist/export/limits.js

@@ -0,0 +1,18 @@
+import { GeometryError } from "../geometry/errors.js";
+/** Default standalone export policy: 64 parts, one million vertices, two million triangles, 96 MiB input, 512 MiB output. */
+export const defaultExportLimits = Object.freeze({
+    maxParts: 64,
+    maxVertices: 1_000_000,
+    maxTriangles: 2_000_000,
+    maxBytes: 96 * 1024 * 1024,
+    maxOutputBytes: 512 * 1024 * 1024,
+});
+export function resolveExportLimits(overrides = {}) {
+    if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides))
+        throw new GeometryError("INVALID_ARGUMENT", "Export limits must be an object.");
+    const limits = { ...defaultExportLimits, ...overrides };
+    for (const key of Object.keys(defaultExportLimits))
+        if (!Number.isSafeInteger(limits[key]) || limits[key] < 1)
+            throw new GeometryError("INVALID_ARGUMENT", `${key} must be a positive safe integer.`);
+    return Object.freeze(limits);
+}

package/dist/export/stl.js

@@ -0,0 +1,105 @@
+import { GeometryError } from "../geometry/errors.js";
+import { captureExport } from "./capture.js";
+import { collectExport, createExportWriter } from "./writer.js";
+const TRIANGLES_PER_CHUNK = 1_024;
+/**
+ * Serializes a captured model as binary STL in millimetres and Z-up coordinates.
+ * Placement is baked into triangles. Diagnostics describe dropped names, appearance and materials.
+ * Mutable input is captured before the first await; no engine or renderer is needed.
+ */
+export function exportStl(parts, options = {}) {
+    return collectExport((sink) => writeStl(parts, sink, options));
+}
+/**
+ * Writes owned binary STL chunks to a sink, awaiting backpressure after each bounded chunk.
+ * The host owns sink completion and recovery after failure. Honors cancellation and output limits.
+ */
+export async function writeStl(parts, sink, options = {}) {
+    const captured = captureExport(parts, options, "stl");
+    const writer = createExportWriter(captured, sink, "stl");
+    const triangleCount = captured.parts.reduce((total, part) => total + part.geometry.indices.length / 3, 0);
+    const byteLength = 84 + triangleCount * 50;
+    if (triangleCount >= 0x1_0000_0000 || byteLength > captured.limits.maxOutputBytes)
+        throw new GeometryError("COMPLEXITY_LIMIT", "Binary STL exceeds the output limits.", {
+            operation: "exportStl",
+        });
+    const header = new Uint8Array(84);
+    header.set(new TextEncoder().encode(`MetaMesh ${captured.name}`).subarray(0, 80));
+    new DataView(header.buffer).setUint32(80, triangleCount, true);
+    await writer.write(header);
+    let chunk = new Uint8Array(Math.min(TRIANGLES_PER_CHUNK, triangleCount) * 50);
+    let view = new DataView(chunk.buffer);
+    let writtenTriangles = 0;
+    let chunkTriangles = 0;
+    const triangle = new Float32Array(9);
+    for (const part of captured.parts) {
+        const { positions, indices } = part.geometry;
+        const matrix = part.transform;
+        for (let offset = 0; offset < indices.length; offset += 3) {
+            for (let corner = 0; corner < 3; corner += 1) {
+                const index = indices[offset + corner] * 3;
+                const x = positions[index];
+                const y = positions[index + 1];
+                const z = positions[index + 2];
+                for (let axis = 0; axis < 3; axis += 1) {
+                    const row = axis * 4;
+                    const value = Math.fround(matrix[row] * x + matrix[row + 1] * y + matrix[row + 2] * z + matrix[row + 3]);
+                    if (!Number.isFinite(value))
+                        throw new GeometryError("NON_FINITE_VALUE", "Placed STL positions must fit finite Float32 coordinates.", { operation: "exportStl" });
+                    triangle[corner * 3 + axis] = value;
+                }
+            }
+            const ux = triangle[3] - triangle[0];
+            const uy = triangle[4] - triangle[1];
+            const uz = triangle[5] - triangle[2];
+            const vx = triangle[6] - triangle[0];
+            const vy = triangle[7] - triangle[1];
+            const vz = triangle[8] - triangle[2];
+            const nx = uy * vz - uz * vy;
+            const ny = uz * vx - ux * vz;
+            const nz = ux * vy - uy * vx;
+            const length = Math.hypot(nx, ny, nz);
+            if (length === 0)
+                throw new GeometryError("DEGENERATE_GEOMETRY", "Placed STL triangles must retain nonzero area in Float32 coordinates.", { operation: "exportStl" });
+            const target = chunkTriangles * 50;
+            view.setFloat32(target, nx === 0 ? 0 : nx / length, true);
+            view.setFloat32(target + 4, ny === 0 ? 0 : ny / length, true);
+            view.setFloat32(target + 8, nz === 0 ? 0 : nz / length, true);
+            for (let index = 0; index < 9; index += 1)
+                view.setFloat32(target + 12 + index * 4, triangle[index], true);
+            view.setUint16(target + 48, 0, true);
+            chunkTriangles += 1;
+            writtenTriangles += 1;
+            if (chunkTriangles * 50 === chunk.byteLength) {
+                await writer.write(chunk);
+                chunkTriangles = 0;
+                if (writtenTriangles < triangleCount) {
+                    chunk = new Uint8Array(Math.min(TRIANGLES_PER_CHUNK, triangleCount - writtenTriangles) * 50);
+                    view = new DataView(chunk.buffer);
+                }
+            }
+        }
+    }
+    const diagnostics = [
+        {
+            code: "PART_NAMES_DROPPED",
+            message: "Binary STL stores triangles without semantic part names.",
+            partIds: captured.parts.map((part) => part.id),
+        },
+    ];
+    const colored = captured.parts.filter((part) => part.color !== undefined);
+    if (colored.length > 0)
+        diagnostics.push({
+            code: "APPEARANCE_DROPPED",
+            message: "Portable binary STL does not preserve display colors.",
+            partIds: colored.map((part) => part.id),
+        });
+    const assigned = captured.parts.filter((part) => part.materialId !== undefined);
+    if (assigned.length > 0)
+        diagnostics.push({
+            code: "MATERIAL_ASSIGNMENTS_DROPPED",
+            message: "Binary STL does not preserve print material assignments.",
+            partIds: assigned.map((part) => part.id),
+        });
+    return writer.report(diagnostics);
+}

package/dist/export/types.js

@@ -0,0 +1 @@
+export {};

package/dist/export/writer.js

@@ -0,0 +1,54 @@
+import { GeometryError } from "../geometry/errors.js";
+const mediaTypes = {
+    "3mf": "model/3mf",
+    stl: "model/stl",
+    glb: "model/gltf-binary",
+};
+/** Shared output accounting and backpressure. Input resources are never passed to the host sink. */
+export function createExportWriter(captured, sink, format) {
+    if (typeof sink !== "function")
+        throw new TypeError("An export sink must be a function.");
+    let byteLength = 0;
+    let lastYield = performance.now();
+    return {
+        async write(chunk) {
+            captured.signal?.throwIfAborted();
+            const chunkLength = chunk.byteLength;
+            if (byteLength + chunkLength > captured.limits.maxOutputBytes)
+                throw new GeometryError("COMPLEXITY_LIMIT", "Encoded export exceeds maxOutputBytes.", {
+                    operation: `export${format}`,
+                });
+            await sink(chunk);
+            // The sink owns this chunk and may transfer/detach its buffer before resolving.
+            byteLength += chunkLength;
+            // Yield to the host's task queue so a Worker can receive cancellation while writing.
+            if (performance.now() - lastYield >= 16) {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+                lastYield = performance.now();
+            }
+            captured.signal?.throwIfAborted();
+        },
+        report(diagnostics = []) {
+            return Object.freeze({
+                mediaType: mediaTypes[format],
+                extension: format,
+                byteLength,
+                diagnostics: Object.freeze([...diagnostics]),
+            });
+        },
+    };
+}
+/** Buffered convenience over the same streaming implementation; allocation is bounded by the writer's output ceiling. */
+export async function collectExport(write) {
+    const chunks = [];
+    const report = await write((chunk) => {
+        chunks.push(chunk);
+    });
+    const bytes = new Uint8Array(report.byteLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return Object.freeze({ ...report, bytes });
+}

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,7 +1,7 @@
 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}` });
 }
@@ -9,18 +9,28 @@ function snapshot(input, dimension) {
     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 (!Array.isArray(size) || size.length !== dimension)
-            fail(dimension, `Size requires ${dimension}D coordinates.`);
         if (center !== undefined && typeof center !== "boolean")
             fail(dimension, "center must be boolean.");
-        const coordinates = size;
+        const sizeCoordinates = coordinates(size);
         const dimensions = Array.from({ length: dimension }, (_, axis) => {
-            const value = coordinates[axis];
+            const value = sizeCoordinates[axis];
             if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
                 fail(dimension, "Size must be finite and nonnegative.");
             return value;
@@ -33,8 +43,8 @@ function snapshot(input, dimension) {
         if (center !== undefined && typeof center !== "function")
             fail(dimension, "center requires size construction.");
         const extrema = input;
-        min = extrema.min;
-        max = extrema.max;
+        min = coordinates(extrema.min);
+        max = coordinates(extrema.max);
     }
     if (!Array.isArray(min) ||
         !Array.isArray(max) ||
@@ -101,8 +111,8 @@ const SpatialBounds = /* @__PURE__ */ immutableMathClass(class SpatialBounds {
  * 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 9.0.0 or newer in major 9.
+ * Compiled Generator packages passing these values to host recipes or memo data require
+ * the current Modeling runtime.
  */
 export function bounds2(input) {
     return new PlanarBounds(snapshot(input, 2));
@@ -113,8 +123,8 @@ export function bounds2(input) {
  * 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 9.0.0 or newer in major 9.
+ * Compiled Generator packages passing these values to host recipes or memo data require
+ * the current Modeling runtime.
  */
 export function bounds3(input) {
     return new SpatialBounds(snapshot(input, 3));

package/dist/geometry/heightfield.js

@@ -1,4 +1,5 @@
 import { GeometryError } from "./errors.js";
+import { vector2Data } from "./math/vector-value.js";
 import { validateTriangleMesh } from "./mesh/mesh.js";
 import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "./model-limits.js";
 import { writeMeshVertex } from "./numeric.js";
@@ -33,21 +34,18 @@ function planHeightfield(options, limits) {
         yAt = (index) => coordinates.y[index];
     }
     else {
-        if (!Array.isArray(options.size) ||
-            options.size.length !== 2 ||
-            !options.size.every((value) => Number.isFinite(value) && value > 0) ||
+        const size = vector2Data(options.size);
+        const origin = options.origin === undefined ? undefined : vector2Data(options.origin);
+        if (!size.every((value) => Number.isFinite(value) && value > 0) ||
             !Array.isArray(options.segments) ||
             options.segments.length !== 2 ||
             !options.segments.every((value) => Number.isSafeInteger(value) && value > 0) ||
-            (options.origin !== undefined &&
-                (!Array.isArray(options.origin) ||
-                    options.origin.length !== 2 ||
-                    !options.origin.every(Number.isFinite)))) {
+            (origin !== undefined && !origin.every(Number.isFinite))) {
             throw new GeometryError("INVALID_ARGUMENT", "Uniform heightfields need a finite positive footprint, integer intervals, and finite origin.", { operation });
         }
         [x, y] = options.segments;
-        const [width, depth] = options.size;
-        const [originX, originY] = options.origin ?? [-width / 2, -depth / 2];
+        const [width, depth] = size;
+        const [originX, originY] = origin ?? [-width / 2, -depth / 2];
         xAt = (index) => originX + (width * index) / x;
         yAt = (index) => originY + (depth * index) / y;
     }
@@ -84,7 +82,7 @@ function planHeightfield(options, limits) {
  * Successful preflight leaves height values, Float32 base storage, and generated mesh validity to
  * construction. `byteCount` covers position and index buffers, not total working memory.
  *
- * @see {@link heightfieldMesh}
+ * @see `mesh.heightfield`
  */
 export function preflightHeightfield(options, limits = {}) {
     return planHeightfield(options, limits).facts;
@@ -96,11 +94,11 @@ export function preflightHeightfield(options, limits = {}) {
  * Top winding is +Z, the base is -Z, and sides face outward. Coordinates and heights must fit
  * Float32 storage. Explicit axes are captured before sampling; shared wall vertices prevent cracks.
  *
- * @see {@link preflightHeightfield}
+ * @see `mesh.preflightHeightfield`
  *
  * @example Sample a closed wavy mesh
  * ```ts
- * heightfieldMesh({
+ * mesh.heightfield({
  *   size: [30, 20], segments: [24, 16],
  *   height: ([x, y]) => 3 + Math.cos(x / 5) * Math.cos(y / 5),
  * });

package/dist/{model → geometry}/immutable-buffer.js

@@ -1,6 +1,7 @@
 const constructors = { Float32Array, Float64Array, Uint32Array, Uint8Array, Int32Array };
-const protocol = Symbol.for("@metamesh/modeling/immutable-buffer/1");
+const protocol = Symbol.for("@metamesh/modeling/immutable-buffer/2");
 const storage = new WeakMap();
+const ownedBuffers = new WeakMap();
 const adopted = new WeakMap();
 /**
  * Copies numeric data once into private storage. This pure helper needs no active generation.
@@ -10,6 +11,7 @@ const adopted = new WeakMap();
  * const heights = immutableBuffer(new Float32Array([2, 4, 6]));
  * const count = heights.length;
  * const first = heights.at(0);
+ * const doubled = Array.from(heights, (height) => height * 2);
  * const editable = heights.copy();
  * editable[0] = 8; // heights still contains 2, 4, 6.
  * ```
@@ -18,8 +20,19 @@ export function immutableBuffer(source) {
     const entry = Object.entries(constructors).find(([, constructor]) => source instanceof constructor);
     if (entry === undefined)
         throw new TypeError("immutableBuffer requires a supported numeric typed array.");
-    const [kind, constructor] = entry;
+    const constructor = entry[1];
     const owned = new constructor(source);
+    return ownImmutableBuffer(owned);
+}
+/** Wraps storage whose exclusive mutable ownership has already been captured by the host. */
+export function ownImmutableBuffer(owned) {
+    const previous = ownedBuffers.get(owned);
+    if (previous !== undefined)
+        return previous;
+    const entry = Object.entries(constructors).find(([, constructor]) => owned instanceof constructor);
+    if (entry === undefined)
+        throw new TypeError("Unsupported owned numeric storage.");
+    const [kind, constructor] = entry;
     const length = owned.length;
     const result = Object.freeze({
         [protocol]: kind,
@@ -29,28 +42,28 @@ export function immutableBuffer(source) {
             return Number.isInteger(offset) && offset >= 0 && offset < length ? owned[offset] : undefined;
         },
         copy: () => new constructor(owned),
+        [Symbol.iterator]: () => owned.values(),
     });
     storage.set(result, owned);
+    ownedBuffers.set(owned, result);
     return result;
 }
 /**
  * Copies mesh buffers into immutable data; geometric validation still occurs when modeling or finalizing.
  * @example
  * ```ts
- * import { generate, immutableMesh } from "@metamesh/modeling";
- * import { heightfieldMesh } from "@metamesh/modeling/geometry";
- * const model = generate(({ computed, part }) => {
- *   const surface = computed("surface", () => immutableMesh(heightfieldMesh({
- *     size: [10, 10], segments: [8, 8], height: () => 2,
- *   })));
- *   return [part("surface", surface)];
- * });
+ * import { generate } from "@metamesh/modeling";
+ * import * as mesh from "@metamesh/modeling/geometry/mesh";
+ * const buildSurface = () => mesh.immutable(mesh.heightfield({
+ *   size: [10, 10], segments: [8, 8], height: () => 2,
+ * }));
+ * const model = generate(({ memo, part }) => part("surface", memo(buildSurface)));
  * ```
  */
 export function immutableMesh(mesh) {
     const { positions, indices } = mesh;
     if (!(positions instanceof Float32Array) || !(indices instanceof Uint32Array))
-        throw new TypeError("immutableMesh requires Float32 positions and Uint32 indices.");
+        throw new TypeError("mesh.immutable requires Float32 positions and Uint32 indices.");
     return Object.freeze({
         positions: immutableBuffer(positions),
         indices: immutableBuffer(indices),
@@ -75,7 +88,8 @@ export function isImmutableBuffer(value) {
         Number.isSafeInteger(length) &&
         length >= 0 &&
         typeof field("at") === "function" &&
-        typeof field("copy") === "function");
+        typeof field("copy") === "function" &&
+        typeof field(Symbol.iterator) === "function");
 }
 /** Adopts separately bundled factories once, copying before trusting their storage or methods. */
 export function adoptImmutableBuffer(buffer) {
@@ -104,6 +118,11 @@ export function immutableBufferView(buffer) {
 /** Normalizes trusted modeling/finalization inputs without copying or exposing storage publicly. */
 export function immutableMeshView(mesh) {
     const { positions, indices } = mesh;
+    if (positions instanceof Float32Array &&
+        indices instanceof Uint32Array &&
+        Object.getOwnPropertyDescriptor(mesh, "positions")?.value === positions &&
+        Object.getOwnPropertyDescriptor(mesh, "indices")?.value === indices)
+        return mesh;
     return {
         positions: isImmutableBuffer(positions) ? immutableBufferView(positions) : positions,
         indices: isImmutableBuffer(indices) ? immutableBufferView(indices) : indices,