@metamesh/modeling 0.9.0 → 0.11.0

package/dist/engine/construction-operations.js

@@ -7,6 +7,7 @@ import { matchProfiles } from "../geometry/profiles/matched.js";
 import { resolveGeometryResolution } from "../geometry/resolution.js";
 import { assertSamplingCount } from "../geometry/sampling-limits.js";
 import { sweepMesh } from "../geometry/sweeps/sweep-mesh.js";
+import { immutableMeshView } from "../model/immutable-buffer.js";
 import { buildFinishedExtrusion } from "./extrusion-finishing.js";
 import { createLoftOperation } from "./loft-operations.js";
 import { triangleMeshToManifold } from "./native/adapter.js";
@@ -91,8 +92,9 @@ export function createConstructionOperations(environment, sections) {
                 ...cutters.map((cutter) => nativeSection(cutter)),
             ]));
     });
-    const solidFromMesh = (mesh) => {
+    const solidFromMesh = (input) => {
         assertActive();
+        const mesh = immutableMeshView(input);
         assertMeshAllocation(mesh.positions.length / 3, mesh.indices.length / 3, mesh.positions.byteLength + mesh.indices.byteLength, "solidFromMesh");
         return wrapSolid(trackScopedManifoldValue(scope, triangleMeshToManifold(module, mesh, scopedManifoldScope(scope))));
     };

package/dist/engine/deferred-context.js

@@ -0,0 +1,182 @@
+import { GeometryError } from "../geometry/errors.js";
+import { geometryRecipe, isGeometryRecipe, recordGeometryRecipe, } from "./geometry-recipes.js";
+import { captureRecipeInputs } from "./immutable-generation-data.js";
+import { gridPatternPlan, linearPatternPlan, pathPatternPlan, radialPatternPlan, } from "./pattern-placements.js";
+import { RecipeRealization } from "./recipe-realization.js";
+// Every public operation must explicitly choose its realization and result behavior.
+const operationBehaviors = {
+    withResolution: "resolution",
+    box: "solid",
+    cylinder: "solid",
+    tube: "solid",
+    sphere: "solid",
+    torus: "solid",
+    heightfield: "solid",
+    implicit: "solid",
+    extrude: "solid",
+    revolve: "solid",
+    loft: "solid",
+    sweep: "solid",
+    compose: "solid",
+    minkowskiSum: "solid",
+    solidFromMesh: "solid",
+    setTolerance: "solid",
+    threadRidge: "solid",
+    threadedRod: "solid",
+    threadedNut: "solid",
+    internalThreadCutter: "solid",
+    sectionFromContours: "section",
+    fromRegion: "section",
+    rectangle: "section",
+    circle: "section",
+    ellipse: "section",
+    regularPolygon: "section",
+    star: "section",
+    projectSection: "section",
+    sliceSection: "section",
+    textSection: "section",
+    svgSection: "section",
+    svgPathSection: "section",
+    translate: "preserve",
+    rotate: "preserve",
+    scale: "preserve",
+    mirror: "preserve",
+    transform: "preserve",
+    offset: "preserve",
+    simplify: "preserve",
+    withAnchors: "preserve",
+    attach: "preserve",
+    union: "preserve",
+    intersect: "preserve",
+    subtract: "preserve",
+    hull: "preserve",
+    toTriangleMesh: "observation",
+    toRegion: "observation",
+    inspectSection: "observation",
+    inspectSolid: "observation",
+    isEmpty: "observation",
+    distance: "observation",
+    rayCast: "observation",
+    anchor: "observation",
+    matchProfiles: "observation",
+    preflightThreadedRod: "observation",
+    preflightInternalThreadCutter: "observation",
+    preflightThreadedNut: "observation",
+    split: "split",
+    splitByPlane: "split",
+    components: "components",
+    linearPattern: "pattern",
+    radialPattern: "pattern",
+    gridPattern: "pattern",
+    pathPattern: "pattern",
+};
+/**
+ * Binds declaration to one active revision. Recipe handles retain only immutable session identity
+ * and captured inputs; native results remain private to the revision's realization owner.
+ */
+export function createDeferredContext(owner, native, limits, initialResolution, duringNative, assertActive, restoreNative = () => undefined) {
+    const realization = new RecipeRealization(owner, native, duringNative, restoreNative);
+    const declaration = { owner, limits, realization, assertActive };
+    return {
+        context: createModelingContext(initialResolution, declaration),
+        resolve: (shape) => realization.resolve(shape),
+        isRecipe: isGeometryRecipe,
+        realizedShape: (shape) => realization.realizedShape(shape),
+        retentionCandidates: (values) => realization.retentionCandidates(values),
+        isSolid: (shape) => isGeometryRecipe(shape) && geometryRecipe(shape)?.kind === "solid",
+    };
+}
+function createModelingContext(resolution, declaration) {
+    return Object.freeze(Object.fromEntries(Object.keys(operationBehaviors).map((key) => [
+        key,
+        (...supplied) => declareOperation(key, resolution, supplied, declaration),
+    ])));
+}
+/** Captures and validates inputs before deciding whether an operation needs native geometry now. */
+function declareOperation(operation, resolution, supplied, declaration) {
+    declaration.assertActive();
+    const behavior = operationBehaviors[operation];
+    if (behavior === "resolution") {
+        const nextResolution = Object.freeze({ ...resolution, ...supplied[0] });
+        return createModelingContext(nextResolution, declaration);
+    }
+    if (behavior === "pattern")
+        return declarePattern(operation, resolution, supplied, declaration);
+    const args = captureRecipeInputs(supplied);
+    declaration.realization.assertOwned(args);
+    const call = { method: operation, args, resolution };
+    if (behavior === "observation")
+        return declaration.realization.invoke(call);
+    const recipe = {
+        owner: declaration.owner,
+        kind: resultKind(behavior, args[0]),
+        call,
+    };
+    if (behavior === "split")
+        return Object.freeze([
+            recordGeometryRecipe({ ...recipe, index: 0 }),
+            recordGeometryRecipe({ ...recipe, index: 1 }),
+        ]);
+    if (behavior === "components") {
+        // Cardinality requires realization now; projected handles reuse that same call result later.
+        const values = declaration.realization.evaluate(call);
+        return Object.freeze(values.map((_value, index) => recordGeometryRecipe({ ...recipe, index })));
+    }
+    return recordGeometryRecipe(recipe);
+}
+function resultKind(behavior, input) {
+    if (behavior === "section")
+        return "section";
+    if (behavior === "preserve" || behavior === "components")
+        return inputKind(input);
+    return "solid";
+}
+function inputKind(value) {
+    if (Array.isArray(value))
+        return inputKind(value[0]);
+    if (typeof value !== "object" || value === null)
+        return "solid";
+    const recipe = geometryRecipe(value);
+    if (recipe !== undefined)
+        return recipe.kind;
+    if ("sections" in value)
+        return "section";
+    if ("points" in value &&
+        Array.isArray(value.points) &&
+        Array.isArray(value.points[0]) &&
+        value.points[0].length === 2)
+        return "section";
+    return "solid";
+}
+/** Runs every factory during declaration; each placed copy stays deferred until it is used. */
+function declarePattern(operation, resolution, supplied, declaration) {
+    const plan = patternPlan(operation, supplied, declaration.limits);
+    if (plan.count > declaration.limits.maxVertices)
+        throw new GeometryError("COMPLEXITY_LIMIT", "Pattern declaration exceeds execution limits.", {
+            operation,
+        });
+    const source = supplied[0];
+    const copies = [];
+    for (let index = 0; index < plan.count; index++) {
+        const shape = typeof source === "function"
+            ? source(index)
+            : source;
+        copies.push(declareOperation("transform", resolution, [shape, plan.transformAt(index)], declaration));
+    }
+    return Object.freeze(copies);
+}
+function patternPlan(operation, supplied, limits) {
+    const options = supplied[1];
+    switch (operation) {
+        case "linearPattern":
+            return linearPatternPlan(options);
+        case "radialPattern":
+            return radialPatternPlan(options);
+        case "gridPattern":
+            return gridPatternPlan(options);
+        case "pathPattern":
+            return pathPatternPlan(options, supplied[2], limits);
+        default:
+            throw new Error(`Operation ${operation} does not declare a pattern.`);
+    }
+}

package/dist/engine/execution.js

@@ -1,10 +1,10 @@
 import { GeometryError } from "../geometry/errors.js";
 import { analyzeTriangleMesh, } from "../geometry/mesh.js";
 import { assertMeshAllocationWithinLimits } from "../geometry/model-limits.js";
-import {} from "../geometry/resolution.js";
 import { assertSamplingCount } from "../geometry/sampling-limits.js";
+import { createSectionHandle, createSolidHandle } from "../model/shape-handles.js";
 import { createModelingContext } from "./modeling-context.js";
-import { ownScopedManifoldValue } from "./native/context.js";
+import { ownScopedManifoldValue, scopedManifoldScope, trackScopedManifoldValue, } from "./native/context.js";
 import { copiedFloat32Array, copiedUint32Array } from "./native/copied-views.js";
 import * as kernel from "./native/index.js";
 import { assertNativeSolidStatus } from "./native/status.js";
@@ -47,14 +47,14 @@ export function createExecutionContext(module, scope, limits, initialResolution
     };
     const wrapSolid = (value) => {
         assertActive();
-        const handle = Object.freeze({});
+        const handle = createSolidHandle();
         handles.set(handle, { kind: "solid", value });
         return handle;
     };
     const wrapSection = (value) => {
         assertActive();
         assertSamplingCount(value.numVert(), "section", limits.maxProfilePoints);
-        const handle = Object.freeze({});
+        const handle = createSectionHandle();
         handles.set(handle, { kind: "section", value });
         return handle;
     };
@@ -254,6 +254,40 @@ export function createExecutionContext(module, scope, limits, initialResolution
     };
     return {
         context: createModelingContext(owner, initialResolution),
+        captureNative(shape) {
+            const native = resolveHandle(shape);
+            // The kernel does not expose allocation sizes. Charge topology conservatively, including
+            // fixed object overhead, and force any lazy geometry while the run still owns it.
+            const bytes = native.kind === "solid"
+                ? 4096 +
+                    native.value.numVert() * 64 +
+                    native.value.numTri() * 96 +
+                    native.value.numPropVert() * native.value.numProp() * 8
+                : 1024 + native.value.numVert() * 64 + native.value.numContour() * 128;
+            return {
+                native,
+                bytes,
+                anchors: shapeAnchors.read(shape),
+                profile: primitiveSectionProfiles.get(shape),
+            };
+        },
+        /** Transfers cleanup to the session cache without deleting the realized geometry. */
+        detachNative(geometry) {
+            assertActive();
+            scopedManifoldScope(scope).release(geometry.native.value);
+        },
+        restoreNative(geometry) {
+            assertActive();
+            trackScopedManifoldValue(scope, geometry.native.value);
+            const shape = geometry.native.kind === "solid"
+                ? wrapSolid(geometry.native.value)
+                : wrapSection(geometry.native.value);
+            if (geometry.anchors !== undefined)
+                shapeAnchors.remember(shape, geometry.anchors);
+            if (geometry.profile !== undefined)
+                primitiveSectionProfiles.set(shape, geometry.profile);
+            return shape;
+        },
         analyzedMeshFor,
         isSolid: (value) => typeof value === "object" && value !== null && handles.get(value)?.kind === "solid",
         validateMesh: (mesh) => {

package/dist/engine/finalization.js

@@ -2,172 +2,90 @@ import { GeometryError } from "../geometry/errors.js";
 import { optimizePlanarPatches } from "../geometry/mesh-planar.js";
 import { validateAnalyzedSolidMesh } from "../geometry/mesh-solid.js";
 import { analyzeTriangleMesh, } from "../geometry/mesh.js";
+import { immutableMeshView } from "../model/immutable-buffer.js";
 import { MeshViewCache } from "./mesh-view-cache.js";
 import { copiedMeshViews, copiedUint32Array } from "./native/copied-views.js";
 const isArray = (value) => Array.isArray(value);
-function finalPartTotals(parts) {
-    const buffers = new Set();
-    let vertices = 0, triangles = 0, bytes = 0, volumeMm3 = 0;
-    for (const part of parts) {
-        vertices += part.measurements.vertexCount;
-        triangles += part.measurements.triangleCount;
-        volumeMm3 += part.measurements.signedVolume;
-        for (const buffer of [part.positions.buffer, part.indices.buffer]) {
-            if (!buffers.has(buffer)) {
-                buffers.add(buffer);
-                bytes += buffer.byteLength;
-            }
-        }
-    }
-    return { vertices, triangles, bytes, volumeMm3 };
+const snapshotMeshes = new WeakMap();
+/** Registers trusted snapshot storage without exposing its shared backing arrays publicly. */
+export function rememberSnapshotPart(part, mesh) {
+    snapshotMeshes.set(part, mesh);
 }
-function fitsLimits(totals, limits) {
-    return (totals.vertices <= limits.maxVertices &&
-        totals.triangles <= limits.maxTriangles &&
-        totals.bytes <= limits.maxBytes);
+function fitsGeometryLimits(mesh, limits) {
+    const buffers = new Set([mesh.positions.buffer, mesh.indices.buffer]);
+    let bytes = 0;
+    for (const buffer of buffers)
+        bytes += buffer.byteLength;
+    return (mesh.positions.length / 3 <= limits.maxVertices &&
+        mesh.indices.length / 3 <= limits.maxTriangles &&
+        bytes <= limits.maxBytes);
 }
-/** Finalizes one complete build under the selected limits, preserving usable originals when optional cleanup fails. */
-export function finalizeModel(execution, output, limits, options, startedAt, builtAt) {
+/** Copies, validates and optionally simplifies local geometry, sharing equal views within one transaction. */
+export function createGeometryFinalizer(execution, limits, options) {
     if (options.meshValidation !== undefined &&
         options.meshValidation !== "topology" &&
         options.meshValidation !== "solid")
         throw new GeometryError("INVALID_ARGUMENT", "Unsupported mesh validation mode.", {
             operation: "finalize",
         });
-    const descriptors = execution.isSolid(output) ? [{ id: "model", solid: output }] : output;
-    if (!isArray(descriptors) || descriptors.length === 0)
-        throw new GeometryError("INVALID_ARGUMENT", "Build must return a solid or at least one named part.", { operation: "finalize" });
-    if (descriptors.length > limits.maxParts)
-        throw new GeometryError("COMPLEXITY_LIMIT", `Output exceeds ${limits.maxParts} parts.`, {
-            operation: "finalize",
-        });
-    const ids = new Set();
-    const backingBuffers = new Set();
     const meshCopies = new Map();
-    const directMeasurements = new MeshViewCache();
-    const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
-    let vertices = 0, triangles = 0, bytes = 0;
-    let parts = descriptors.map((descriptor) => {
-        if (typeof descriptor !== "object" ||
-            descriptor === null ||
-            typeof descriptor.id !== "string" ||
-            !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(descriptor.id) ||
-            descriptor.id.length > 64 ||
-            ids.has(descriptor.id))
-            throw new GeometryError("INVALID_ARGUMENT", "Part IDs must be unique canonical lowercase identifiers of at most 64 characters.", { operation: "finalize" });
-        ids.add(descriptor.id);
-        if (descriptor.color !== undefined &&
-            (typeof descriptor.color !== "string" || !/^#[\da-f]{6}$/i.test(descriptor.color)))
-            throw new GeometryError("INVALID_ARGUMENT", "Part colors must be six-digit hex strings.", {
-                operation: "finalize",
-            });
-        if ((descriptor.solid === undefined) === (descriptor.mesh === undefined))
-            throw new GeometryError("INVALID_ARGUMENT", "Each part must contain exactly one solid or mesh.", { operation: "finalize" });
-        const nativeAnalysis = descriptor.solid === undefined ? undefined : execution.analyzedMeshFor(descriptor.solid);
-        const source = descriptor.solid === undefined ? descriptor.mesh : nativeAnalysis.mesh;
+    const finalized = new MeshViewCache();
+    return function finalizeGeometry(geometry) {
+        const nativeAnalysis = execution.isSolid(geometry)
+            ? execution.analyzedMeshFor(geometry)
+            : undefined;
+        const input = nativeAnalysis?.mesh ?? geometry;
+        // Immutable generation buffers expose owned copies publicly. Unwrap only at this trusted
+        // copy boundary, so the captured mesh retains shared backing storage without repeated copies.
+        const source = immutableMeshView(input);
         if (!(source.positions instanceof Float32Array) ||
             !(source.indices instanceof Uint32Array) ||
             !(source.positions.buffer instanceof ArrayBuffer) ||
             !(source.indices.buffer instanceof ArrayBuffer))
             throw new GeometryError("INVALID_MESH", "Parts require transferable Float32 positions and Uint32 indices.", { operation: "finalize" });
-        const sourceVertices = source.positions.length / 3, sourceTriangles = source.indices.length / 3;
-        let sourceBytes = 0;
-        for (const buffer of [source.positions.buffer, source.indices.buffer]) {
-            if (!backingBuffers.has(buffer)) {
-                backingBuffers.add(buffer);
-                sourceBytes += buffer.byteLength;
-            }
-        }
-        vertices += sourceVertices;
-        triangles += sourceTriangles;
-        bytes += sourceBytes;
-        if (vertices > limits.maxVertices || triangles > limits.maxTriangles || bytes > limits.maxBytes)
+        if (!fitsGeometryLimits(source, limits))
             throw new GeometryError("COMPLEXITY_LIMIT", "Aggregate output exceeds the execution limits.", { operation: "finalize" });
+        const cached = finalized.get(source);
+        if (cached !== undefined)
+            return cached;
         // Direct meshes are copied before analysis so later caller mutation cannot invalidate facts.
-        const mesh = descriptor.mesh === undefined ? source : copiedMeshViews(source, meshCopies);
-        let measurements = nativeAnalysis?.measurements ?? directMeasurements.get(mesh);
+        const mesh = nativeAnalysis === undefined ? copiedMeshViews(source, meshCopies) : source;
+        let measurements = nativeAnalysis?.measurements;
         if (measurements === undefined) {
             measurements = analyzeTriangleMesh(mesh, { requireClosed: true, includeTopology: true });
             execution.validateMesh(mesh);
-            directMeasurements.set(mesh, measurements);
         }
         if (!(measurements.signedVolume > 0))
             throw new GeometryError("INVALID_TOPOLOGY", "Manufacturing parts must enclose positive oriented volume.", { operation: "finalize" });
-        for (let axis = 0; axis < 3; axis += 1) {
-            min[axis] = Math.min(min[axis], measurements.bounds.min[axis]);
-            max[axis] = Math.max(max[axis], measurements.bounds.max[axis]);
-        }
-        return Object.freeze({
-            id: descriptor.id,
-            ...mesh,
-            ...(descriptor.color === undefined ? {} : { color: descriptor.color.toLowerCase() }),
-            measurements,
-        });
-    });
-    const originalParts = parts;
-    if (options.meshTopologyMode === "optimized" && triangles <= 200_000) {
-        const candidates = new MeshViewCache();
-        parts = parts.map((part) => {
-            const cached = candidates.get(part);
-            if (cached !== undefined)
-                return Object.freeze({ ...part, ...cached });
-            let selected = {
-                positions: part.positions,
-                indices: part.indices,
-                measurements: part.measurements,
-            };
+        let selected = { ...mesh, measurements };
+        if (options.meshTopologyMode === "optimized" && measurements.triangleCount <= 200_000) {
             try {
-                const optimized = optimizePlanarPatches(part);
+                const optimized = optimizePlanarPatches(mesh);
                 if (optimized.changed) {
-                    const mesh = {
-                        positions: part.positions,
+                    const candidate = {
+                        positions: mesh.positions,
                         indices: copiedUint32Array(optimized.mesh.indices),
                     };
-                    const measurements = analyzeTriangleMesh(mesh, {
-                        requireClosed: true,
-                        includeTopology: true,
-                    });
-                    execution.validateMesh(mesh);
-                    selected = { ...mesh, measurements };
+                    if (fitsGeometryLimits(candidate, limits)) {
+                        const facts = analyzeTriangleMesh(candidate, {
+                            requireClosed: true,
+                            includeTopology: true,
+                        });
+                        execution.validateMesh(candidate);
+                        selected = { ...candidate, measurements: facts };
+                    }
                 }
             }
             catch {
                 // Optional optimization preserves the usable original on unsupported geometry.
             }
-            candidates.set(part, selected);
-            return Object.freeze({ ...part, ...selected });
-        });
-    }
-    // Statistics describe the exact selected buffers after optional finalization.
-    let totals = finalPartTotals(parts);
-    if (!fitsLimits(totals, limits) && parts !== originalParts) {
-        parts = originalParts;
-        totals = finalPartTotals(parts);
-    }
-    if (!fitsLimits(totals, limits))
-        throw new GeometryError("COMPLEXITY_LIMIT", "Selected output exceeds the execution limits.", {
-            operation: "finalize",
-        });
-    if (options.meshValidation === "solid") {
-        const checked = new MeshViewCache();
-        for (const part of parts) {
-            if (checked.get(part) !== undefined)
-                continue;
-            validateAnalyzedSolidMesh(part, part.measurements);
-            checked.set(part, true);
         }
-    }
-    const finalizedAt = performance.now();
-    return Object.freeze({
-        parts: Object.freeze(parts),
-        bounds: Object.freeze({ min: Object.freeze(min), max: Object.freeze(max) }),
-        stats: Object.freeze({
-            ...totals,
-            buildMs: builtAt - startedAt,
-            finalizationMs: finalizedAt - builtAt,
-            generationMs: finalizedAt - startedAt,
-        }),
-    });
+        if (options.meshValidation === "solid")
+            validateAnalyzedSolidMesh(selected, selected.measurements);
+        const result = Object.freeze(selected);
+        finalized.set(source, result);
+        return result;
+    };
 }
 /** Captures mutable external buffers once before an asynchronous snapshot export begins. */
 export function captureExportParts(parts, limits) {
@@ -175,10 +93,24 @@ export function captureExportParts(parts, limits) {
         throw new GeometryError("COMPLEXITY_LIMIT", `Export requires one through ${limits.maxParts} parts.`, {
             operation: "export3mf",
         });
+    const captured = parts.map((part) => {
+        if (typeof part !== "object" || part === null)
+            throw new GeometryError("INVALID_ARGUMENT", "Export part IDs must be unique canonical identifiers.", { operation: "export3mf" });
+        // Access public owned-copy getters exactly once, or retain trusted private sharing for a
+        // snapshot created by this engine. Capture still copies before the asynchronous boundary.
+        const mesh = snapshotMeshes.get(part) ?? { positions: part.positions, indices: part.indices };
+        const id = part.id, color = part.color;
+        return {
+            id,
+            positions: mesh.positions,
+            indices: mesh.indices,
+            ...(color === undefined ? {} : { color }),
+        };
+    });
     const identifiers = new Set();
     const buffers = new Set();
     let vertexCount = 0, triangleCount = 0, byteCount = 0;
-    for (const part of parts) {
+    for (const part of captured) {
         if (typeof part !== "object" ||
             part === null ||
             typeof part.id !== "string" ||
@@ -215,7 +147,7 @@ export function captureExportParts(parts, limits) {
             });
     }
     const copiedBuffers = new Map();
-    return parts.map((part) => ({
+    return captured.map((part) => ({
         id: part.id,
         ...copiedMeshViews(part, copiedBuffers),
         ...(part.color === undefined ? {} : { color: part.color }),

package/dist/engine/geometry-recipes.js

@@ -0,0 +1,12 @@
+import { createSectionHandle, createSolidHandle } from "../model/shape-handles.js";
+const recipes = new WeakMap();
+/** Reads private recipe metadata without requiring an execution context. */
+export const geometryRecipe = (value) => recipes.get(value);
+/** Recognizes only opaque recipe handles issued by this engine. */
+export const isGeometryRecipe = (value) => typeof value === "object" && value !== null && recipes.has(value);
+/** Creates an immutable opaque handle for a recorded operation. */
+export function recordGeometryRecipe(recipe) {
+    const handle = recipe.kind === "solid" ? createSolidHandle() : createSectionHandle();
+    recipes.set(handle, recipe);
+    return handle;
+}