@metamesh/modeling 0.9.0 → 0.11.0

package/dist/geometry/svg-import.js

@@ -5,6 +5,7 @@ import { resolveCircularSegments, resolveGeometryResolution, } from "./resolutio
 import { resolveGeometrySamplingLimits } from "./sampling-limits.js";
 import { strokePathMultiPolygon } from "./stroke-path.js";
 import { createBoundedSvgClipping } from "./svg/fill.js";
+import { multiplyMatrices as multiply, transformPoint } from "./svg/matrix.js";
 import { flattenSvgSubpaths, SvgVertexBudget } from "./svg/path.js";
 const MAX_SVG_BYTES = 256 * 1024;
 const MAX_SVG_ELEMENTS = 500;
@@ -89,22 +90,6 @@ function finite(value, fallback) {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : fail(`Invalid SVG number “${value}”.`);
 }
-function multiply(left, right) {
-    return [
-        left[0] * right[0] + left[2] * right[1],
-        left[1] * right[0] + left[3] * right[1],
-        left[0] * right[2] + left[2] * right[3],
-        left[1] * right[2] + left[3] * right[3],
-        left[0] * right[4] + left[2] * right[5] + left[4],
-        left[1] * right[4] + left[3] * right[5] + left[5],
-    ];
-}
-function transformPoint(matrix, point) {
-    return [
-        matrix[0] * point[0] + matrix[2] * point[1] + matrix[4],
-        matrix[1] * point[0] + matrix[3] * point[1] + matrix[5],
-    ];
-}
 function parseTransform(value) {
     if (value === undefined || value.trim() === "")
         return [1, 0, 0, 1, 0, 0];

package/dist/index.js

@@ -1 +1,3 @@
 export * from "./model/operations.js";
+export * from "./model/generation.js";
+export { immutableBuffer, immutableMesh } from "./model/immutable-buffer.js";

package/dist/model/execution-binding.js

@@ -1,7 +1,7 @@
 import { GeometryError } from "../geometry/errors.js";
 // One protocol key lets locally bundled operation wrappers resolve the host's execution
 // without depending on package instances, class identity, or initializing a native runtime.
-const executionKey = Symbol.for("@metamesh/modeling/execution/2");
+const executionKey = Symbol.for("@metamesh/modeling/execution/4");
 const bindings = globalThis;
 /** Internal host binding. Executable callbacks are synchronous and may not nest executions. */
 export function bindModelContext(context, build) {
@@ -10,7 +10,7 @@ export function bindModelContext(context, build) {
             operation: "build",
         });
     }
-    bindings[executionKey] = { version: 2, context };
+    bindings[executionKey] = { version: 4, context };
     try {
         return build();
     }
@@ -18,11 +18,11 @@ export function bindModelContext(context, build) {
         delete bindings[executionKey];
     }
 }
-/** Resolves only the current live build; imported functions carry no native state themselves. */
+/** Resolves the private realm protocol; imported functions carry no native state themselves. */
 export function currentModelContext(operation) {
     const binding = bindings[executionKey];
-    if (binding?.version !== 2) {
-        throw new GeometryError("INVALID_ARGUMENT", "Modeling functions can only run inside build().", {
+    if (binding?.version !== 4) {
+        throw new GeometryError("INVALID_ARGUMENT", "Modeling functions can only run inside generate().", {
             operation,
         });
     }

package/dist/model/generation.js

@@ -0,0 +1,27 @@
+/** A user-correctable assertion failure. Successful computation caches never retain failures. */
+export class GenerationError extends Error {
+    /** Issues reached in normal JavaScript order, ending with the first failed assertion. */
+    diagnostics;
+    /** Captures immutable diagnostics; unexpected author errors retain their original type. */
+    constructor(diagnostics) {
+        super(diagnostics.at(-1)?.message ?? "Generation failed.");
+        this.name = "GenerationError";
+        this.diagnostics = Object.freeze(diagnostics.map((issue) => Object.freeze({ ...issue })));
+    }
+}
+/**
+ * Defines a typed model without executing it. Use `computed` only for work worth reusing.
+ *
+ * @example A simple model
+ * ```ts
+ * const model = generate<{ height: number }>(({ params, part, assert }) => {
+ *   assert(params.height > 0, "Height must be positive.");
+ *   return [part("body", box({ size: [10, 10, params.height] }))];
+ * });
+ * ```
+ */
+export function generate(callback) {
+    if (typeof callback !== "function")
+        throw new TypeError("generate requires a callback.");
+    return Object.freeze({ kind: "metamesh-model", generate: callback });
+}

package/dist/model/immutable-buffer.js

@@ -0,0 +1,111 @@
+const constructors = { Float32Array, Float64Array, Uint32Array, Uint8Array, Int32Array };
+const protocol = Symbol.for("@metamesh/modeling/immutable-buffer/1");
+const storage = new WeakMap();
+const adopted = new WeakMap();
+/**
+ * Copies numeric data once into private storage. This pure helper needs no active generation.
+ * @example
+ * ```ts
+ * import { immutableBuffer } from "@metamesh/modeling";
+ * const heights = immutableBuffer(new Float32Array([2, 4, 6]));
+ * const count = heights.length;
+ * const first = heights.at(0);
+ * const editable = heights.copy();
+ * editable[0] = 8; // heights still contains 2, 4, 6.
+ * ```
+ */
+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 owned = new constructor(source);
+    const length = owned.length;
+    const result = Object.freeze({
+        [protocol]: kind,
+        length,
+        at: (index) => {
+            const offset = index < 0 ? length + index : index;
+            return Number.isInteger(offset) && offset >= 0 && offset < length ? owned[offset] : undefined;
+        },
+        copy: () => new constructor(owned),
+    });
+    storage.set(result, owned);
+    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)];
+ * });
+ * ```
+ */
+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.");
+    return Object.freeze({
+        positions: immutableBuffer(positions),
+        indices: immutableBuffer(indices),
+    });
+}
+/** Recognizes the versioned cross-bundle protocol without invoking foreign callbacks. */
+export function isImmutableBuffer(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (storage.has(value))
+        return true;
+    if (!Object.isFrozen(value))
+        return false;
+    const field = (key) => {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        return descriptor !== undefined && "value" in descriptor ? descriptor.value : undefined;
+    };
+    const kind = field(protocol), length = field("length");
+    return (typeof kind === "string" &&
+        Object.hasOwn(constructors, kind) &&
+        typeof length === "number" &&
+        Number.isSafeInteger(length) &&
+        length >= 0 &&
+        typeof field("at") === "function" &&
+        typeof field("copy") === "function");
+}
+/** Adopts separately bundled factories once, copying before trusting their storage or methods. */
+export function adoptImmutableBuffer(buffer) {
+    if (storage.has(buffer))
+        return buffer;
+    const previous = adopted.get(buffer);
+    if (previous !== undefined)
+        return previous;
+    if (!isImmutableBuffer(buffer))
+        throw new TypeError("Expected an immutableBuffer() value.");
+    const source = buffer.copy();
+    const kind = Object.getOwnPropertyDescriptor(buffer, protocol)
+        .value;
+    if (!(source instanceof constructors[kind]))
+        throw new TypeError("An immutable buffer copy must retain its numeric type and length.");
+    const captured = immutableBuffer(source);
+    if (captured.length !== buffer.length)
+        throw new TypeError("An immutable buffer copy must retain its numeric type and length.");
+    adopted.set(buffer, captured);
+    return captured;
+}
+/** Trusted internal read only: never mutate or expose this view or its backing buffer. */
+export function immutableBufferView(buffer) {
+    return storage.get(adoptImmutableBuffer(buffer));
+}
+/** Normalizes trusted modeling/finalization inputs without copying or exposing storage publicly. */
+export function immutableMeshView(mesh) {
+    const { positions, indices } = mesh;
+    return {
+        positions: isImmutableBuffer(positions) ? immutableBufferView(positions) : positions,
+        indices: isImmutableBuffer(indices) ? immutableBufferView(indices) : indices,
+    };
+}

package/dist/model/modeling-context.js

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