@metamesh/modeling 0.17.0 → 0.18.0

package/dist/geometry/mesh/mesh-signature.js

@@ -1,4 +1,5 @@
 import { GeometryError } from "../errors.js";
+import { immutableMeshView } from "../immutable-buffer.js";
 import { analyzeTriangleMesh, validateTriangleMesh } from "./mesh.js";
 const DEFAULT_POSITION_TOLERANCE = 1e-5;
 const DEFAULT_VOLUME_TOLERANCE = 1e-4;
@@ -68,10 +69,10 @@ const hashCanonicalKeys = (header, groups) => {
  * @param mesh - Closed oriented mesh to measure without mutation.
  * @param options - Absolute quantization and complexity limits.
  * @returns Compact counts, bounds, volume, topology, tolerances, and canonical fingerprint.
- * @throws {@link GeometryError} When validation, topology, tolerance, or complexity checks fail.
+ * @throws `GeometryError` When validation, topology, tolerance, or complexity checks fail.
  */
 export function computeTriangleMeshSignature(mesh, options = {}) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const source = immutableMeshView(mesh);
     const maxTriangles = options.maxTriangles ?? DEFAULT_MAXIMUM_TRIANGLE_COUNT;
     if (!Number.isSafeInteger(maxTriangles) || maxTriangles <= 0) {
         throw new GeometryError("INVALID_ARGUMENT", "maxTriangles must be a positive safe integer.", {
@@ -92,14 +93,14 @@ export function computeTriangleMeshSignature(mesh, options = {}) {
     const positionTolerance = validatePositiveTolerance(options.positionTolerance ?? DEFAULT_POSITION_TOLERANCE, "positionTolerance");
     const volumeTolerance = validatePositiveTolerance(options.volumeTolerance ?? DEFAULT_VOLUME_TOLERANCE, "volumeTolerance");
     const measured = analyzeTriangleMesh(source, { requireClosed: true, includeTopology: true });
-    const connectedComponentCount = measured.connectedComponentCount;
+    const shellCount = measured.shellCount;
     const edgeCount = measured.edgeCount;
     const eulerCharacteristic = measured.vertexCount - edgeCount + measured.triangleCount;
-    const twiceGenus = connectedComponentCount * 2 - eulerCharacteristic;
+    const twiceGenus = shellCount * 2 - eulerCharacteristic;
     if (twiceGenus < 0 || twiceGenus % 2 !== 0) {
         throw new GeometryError("INVALID_TOPOLOGY", "Closed mesh topology does not describe orientable vertex-manifold components.", {
             operation: "computeTriangleMeshSignature",
-            details: { connectedComponentCount, edgeCount, eulerCharacteristic },
+            details: { shellCount, edgeCount, eulerCharacteristic },
         });
     }
     const coordinateKeys = Array.from({ length: measured.vertexCount }, (_, vertex) => coordinateKey(source.positions, vertex, positionTolerance));
@@ -127,7 +128,7 @@ export function computeTriangleMeshSignature(mesh, options = {}) {
     });
     return Object.freeze({
         bounds: quantizeBounds(measured.bounds),
-        connectedComponentCount,
+        shellCount,
         fingerprint: hashCanonicalKeys(`${measured.vertexCount}|${measured.triangleCount}|${positionTolerance}`, [vertexKeys, triangleKeys]),
         genus: twiceGenus / 2,
         signedVolume: quantizedScalar(measured.signedVolume, volumeTolerance, "Signed volume"),

package/dist/geometry/mesh/mesh-solid.js

@@ -1,4 +1,5 @@
 import { GeometryError } from "../errors.js";
+import { immutableMeshView } from "../immutable-buffer.js";
 import { resolveGeometryTolerance } from "../tolerance.js";
 import { IndexedMeshEdgeTable } from "./mesh-edge-table.js";
 import { prepareSolidTriangle, trianglesIntersectBeyondSharedBoundary, triangleSolidAngle, } from "./mesh-solid-intersections.js";
@@ -51,9 +52,7 @@ function validationWork(mesh, options) {
 }
 /** @internal Fresh measurements precede one adjacency traversal for closure, fans, and shells. */
 export function analyzeSolidMesh(mesh, options = {}) {
-    const source = typeof mesh === "object" && mesh !== null
-        ? { positions: mesh.positions, indices: mesh.indices }
-        : mesh;
+    const source = typeof mesh === "object" && mesh !== null ? immutableMeshView(mesh) : mesh;
     const work = validationWork(source, options);
     const measurements = analyzeTriangleMesh(source, {
         ...(options.tolerance === undefined ? {} : { tolerance: options.tolerance }),

package/dist/geometry/mesh/mesh-types.js

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

package/dist/geometry/mesh/mesh.js

@@ -1,12 +1,13 @@
 import { GeometryError } from "../errors.js";
+import { immutableMeshView } from "../immutable-buffer.js";
 import { writeMeshVertex } from "../numeric.js";
 import { resolveGeometryTolerance } from "../tolerance.js";
 import { readTransformMatrix } from "../transform-matrix.js";
 import { transformDeterminant3, validateTransform3 } from "../transform3.js";
 import { IndexedMeshEdgeTable } from "./mesh-edge-table.js";
 function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = false) {
-    // Snapshot meshes can expose owned-copy accessors. Read each buffer once before traversal.
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    // Normalize immutable storage and read raw input accessors once before traversal.
+    const source = immutableMeshView(mesh);
     const measurements = mode === "measure";
     if (!(source.positions instanceof Float32Array) || !(source.indices instanceof Uint32Array)) {
         throw new GeometryError("INVALID_MESH", "Triangle meshes require Float32Array positions and Uint32Array indices.");
@@ -43,7 +44,7 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
     const parents = topology ? new Int32Array(triangleCount) : null;
     const ranks = topology ? new Uint8Array(triangleCount) : null;
     const referenced = topology ? new Uint8Array(vertexCount) : null;
-    let connectedComponentCount = 0;
+    let shellCount = 0;
     const root = (triangle) => {
         let current = triangle;
         while (parents[current] !== current)
@@ -64,7 +65,7 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
         parents[right] = left;
         if (ranks[left] === ranks[right])
             ranks[left] = ranks[left] + 1;
-        connectedComponentCount -= 1;
+        shellCount -= 1;
     };
     let edgeCount = 0;
     const addEdge = (a, b, triangle) => {
@@ -113,7 +114,7 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
             const triangle = offset / 3;
             parents[triangle] = triangle;
             referenced[a] = referenced[b] = referenced[c] = 1;
-            connectedComponentCount += 1;
+            shellCount += 1;
         }
         if (edges !== null) {
             addEdge(a, b, offset / 3);
@@ -143,19 +144,9 @@ function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = f
         surfaceArea: surfaceArea + areaCorrection,
         triangleCount,
         vertexCount,
-        ...(topology ? { connectedComponentCount, edgeCount } : {}),
+        ...(topology ? { shellCount, edgeCount } : {}),
     });
 }
-/**
- * Validates and measures a mesh in one position and one triangle traversal.
- *
- * Bounds, area in square model units and signed volume in cubic model units are computed without
- * copying or changing the input buffers. Volume is meaningful for consistently wound closed
- * geometry; `requireClosed` checks oriented edge closure. Optional indexed topology counts require
- * every position vertex to be referenced and do not establish freedom from self-intersections.
- * Results and nested bounds are immutable snapshots. Caller-owned mutable meshes are freshly
- * inspected on every call, never cached.
- */
 export function analyzeTriangleMesh(mesh, options = {}) {
     return inspectTriangleMesh(mesh, options, "measure", options.includeTopology ?? false);
 }
@@ -169,7 +160,7 @@ export function analyzeTriangleMesh(mesh, options = {}) {
  * @param mesh - Mesh to inspect.
  * @param options - Empty-mesh, topology, and tolerance policy.
  * @returns The original mesh after successful validation.
- * @throws {@link GeometryError} When any requested invariant fails.
+ * @throws `GeometryError` When any requested invariant fails.
  */
 export function validateTriangleMesh(mesh, options = {}) {
     inspectTriangleMesh(mesh, options);
@@ -180,7 +171,7 @@ export function validateTriangleMesh(mesh, options = {}) {
  *
  * @param mesh - Mesh whose finite complete vertices will be measured.
  * @returns Fresh immutable minimum and maximum XYZ tuples.
- * @throws {@link GeometryError} When the mesh is structurally invalid.
+ * @throws `GeometryError` When the mesh is structurally invalid.
  */
 export const meshBounds = (mesh) => {
     return inspectTriangleMesh(mesh, {}, "bounds");
@@ -192,10 +183,10 @@ export const meshBounds = (mesh) => {
  *
  * @param meshes - One or more meshes to concatenate.
  * @returns Fresh typed arrays with indices offset to their source vertex ranges.
- * @throws {@link GeometryError} When no mesh is supplied or an input is invalid.
+ * @throws `GeometryError` When no mesh is supplied or an input is invalid.
  */
 export function joinTriangleMeshes(meshes) {
-    const sources = meshes.map(({ positions, indices }) => ({ positions, indices }));
+    const sources = meshes.map((mesh) => immutableMeshView(mesh));
     if (sources.length === 0) {
         throw new GeometryError("INVALID_ARGUMENT", "Joining meshes requires at least one mesh.");
     }
@@ -228,7 +219,7 @@ export function joinTriangleMeshes(meshes) {
  * @returns Fresh position and index buffers; the input remains unchanged.
  */
 export function reverseTriangleMesh(mesh) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const source = immutableMeshView(mesh);
     validateTriangleMesh(source);
     const indices = new Uint32Array(source.indices);
     for (let offset = 0; offset < indices.length; offset += 3) {
@@ -249,7 +240,7 @@ export function reverseTriangleMesh(mesh) {
  * @returns A mesh with fresh transformed positions and copied or reversed indices.
  */
 export function transformTriangleMesh(mesh, placement) {
-    const source = { positions: mesh.positions, indices: mesh.indices };
+    const source = immutableMeshView(mesh);
     validateTriangleMesh(source);
     const transform = readTransformMatrix(placement, 3);
     validateTransform3(transform);

package/dist/geometry/mesh-api.js

@@ -0,0 +1,14 @@
+/** Pure triangle mesh construction, processing, and inspection without a host engine. */
+export { extrudeMesh as extrude, loftMesh as loft } from "./loft/loft.js";
+export { revolveMesh as revolve } from "./revolve/revolve-mesh.js";
+export { sweepMesh as sweep } from "./sweeps/sweep-mesh.js";
+export { heightfieldMesh as heightfield, preflightHeightfield } from "./heightfield.js";
+export { threadRidgeMesh as threadRidge, threadSolidMesh as threadSolid, } from "./mechanical/threads/mesh.js";
+export { preflightThreadSolidMesh as preflightThreadSolid } from "./mechanical/threads/mesh-plan.js";
+export { transformTriangleMesh as transform, joinTriangleMeshes as join, reverseTriangleMesh as reverse, meshBounds as bounds, analyzeTriangleMesh as analyze, validateTriangleMesh as validate, } from "./mesh/mesh.js";
+export { computeTriangleMeshCentroid as centroid } from "./mesh/mesh-centroid.js";
+export { analyzeTriangleMeshQuality as analyzeQuality } from "./mesh/mesh-quality.js";
+export { computeTriangleMeshSignature as signature } from "./mesh/mesh-signature.js";
+export { validateSolidMesh as validateSolid } from "./mesh/mesh-solid.js";
+export { optimizePlanarPatches } from "./mesh/mesh-planar.js";
+export { immutableMesh as immutable } from "./immutable-buffer.js";

package/dist/geometry/primitive-resolvers.js

@@ -1,5 +1,6 @@
 import { edgeTreatmentPointCount, edgeTreatmentSetbacks, sampleEdgeTreatment, } from "./edge-finishing.js";
 import { GeometryError } from "./errors.js";
+import { vector3Data } from "./math/vector-value.js";
 import { assertMeshAllocationWithinLimits, resolveModelingLimits } from "./model-limits.js";
 import { resolveCircularPrimitiveSegments } from "./primitive-resolution.js";
 /** @internal Face pairs define the twelve nominal box edges in deterministic order. */
@@ -87,13 +88,9 @@ export function resolveBoxPrimitive(options) {
             operation,
         });
     }
-    if (typeof options.size !== "number" &&
-        (!Array.isArray(options.size) || options.size.length !== 3)) {
-        throw new GeometryError("INVALID_ARGUMENT", "size must be a number or an exact XYZ tuple.", {
-            operation,
-        });
-    }
-    const dimensions = typeof options.size === "number" ? [options.size, options.size, options.size] : options.size;
+    const dimensions = typeof options.size === "number"
+        ? [options.size, options.size, options.size]
+        : vector3Data(options.size);
     for (let axis = 0; axis < 3; axis += 1) {
         assertPositivePrimitive(dimensions[axis], `size[${axis}]`, operation);
     }
@@ -193,17 +190,48 @@ export function resolveBoxPrimitive(options) {
             },
         };
 }
-/** @internal Validates tube dimensions shared by both adapters before allocating cylinders. */
-export function resolveTubePrimitive(options) {
+/** @internal Resolves one complete radius or diameter pair before applying faceting compensation. */
+export function resolveTubeRadii(options) {
     assertPrimitiveOptions(options, "tube");
-    assertPositivePrimitive(options.innerRadius, "innerRadius", "tube");
-    assertPositivePrimitive(options.outerRadius, "outerRadius", "tube");
+    const radii = options.innerRadius !== undefined || options.outerRadius !== undefined;
+    const diameters = options.innerDiameter !== undefined || options.outerDiameter !== undefined;
+    if (radii === diameters)
+        throw new GeometryError("INVALID_ARGUMENT", "Supply one complete radius or diameter pair.", {
+            operation: "tube",
+        });
+    const innerRadius = radii ? options.innerRadius : options.innerDiameter / 2;
+    const outerRadius = radii ? options.outerRadius : options.outerDiameter / 2;
+    assertPositivePrimitive(innerRadius, "innerRadius", "tube");
+    assertPositivePrimitive(outerRadius, "outerRadius", "tube");
+    if (!(outerRadius > innerRadius))
+        throw new GeometryError("INVALID_ARGUMENT", "Outer size must be larger than inner size.", {
+            operation: "tube",
+        });
+    return { innerRadius, outerRadius };
+}
+/** @internal Resolves shared faceting so compensated inner and outer rings retain a positive wall. */
+export function resolveTubePrimitive(options) {
+    const { innerRadius, outerRadius } = resolveTubeRadii(options);
     assertPositivePrimitive(options.height, "height", "tube");
-    if (!(options.outerRadius > options.innerRadius)) {
-        throw new GeometryError("INVALID_ARGUMENT", "outerRadius must be larger than innerRadius.", {
+    if (options.center !== undefined && typeof options.center !== "boolean")
+        throw new GeometryError("INVALID_ARGUMENT", "center must be boolean when supplied.", {
             operation: "tube",
         });
-    }
+    const sizing = (value) => {
+        if (value !== undefined && value !== "vertex" && value !== "face")
+            throw new GeometryError("INVALID_ARGUMENT", "Tube sizing must be vertex or face.", {
+                operation: "tube",
+            });
+        return value ?? "vertex";
+    };
+    const innerSizing = sizing(options.innerSizing), outerSizing = sizing(options.outerSizing);
+    const segments = Math.max(resolveCircularPrimitiveSegments(innerRadius, { ...options, sizing: innerSizing }, "tube"), resolveCircularPrimitiveSegments(outerRadius, { ...options, sizing: outerSizing }, "tube"));
+    const cosine = Math.cos(Math.PI / segments);
+    const innerVertexRadius = innerSizing === "face" ? innerRadius / cosine : innerRadius;
+    const outerVertexRadius = outerSizing === "face" ? outerRadius / cosine : outerRadius;
+    if (!Number.isFinite(outerVertexRadius) || !(outerVertexRadius > innerVertexRadius))
+        throw new GeometryError("INVALID_ARGUMENT", "Tube sizing and sampling must leave a finite positive wall.", { operation: "tube" });
+    return { innerVertexRadius, outerVertexRadius, segments };
 }
 /** @internal Resolves sphere sampling shared by compiled and authored adapters. */
 export function resolveSpherePrimitive(options) {

package/dist/geometry/profiles/primitives/circle.js

@@ -0,0 +1,19 @@
+import { resolveCircularSampling } from "../../circular-sampling.js";
+import { requireProfileVertexCount } from "../validation.js";
+/**
+ * Creates an immutable centered CCW circle with +X seam and vertex or face radial sizing.
+ *
+ * @example Explicit circular point data
+ * ```ts
+ * circleContour({ diameter: 20, segments: 32 });
+ * ```
+ */
+export const circleContour = (options) => {
+    const operation = "circleContour";
+    const { segments, vertexRadius } = resolveCircularSampling(options);
+    requireProfileVertexCount(segments, 3, operation, options.limits);
+    return Object.freeze(Array.from({ length: segments }, (_, index) => {
+        const angle = (Math.PI * 2 * index) / segments;
+        return Object.freeze([vertexRadius * Math.cos(angle), vertexRadius * Math.sin(angle)]);
+    }));
+};

package/dist/geometry/profiles/{shapes.js → primitives/ellipse.js}

@@ -1,7 +1,8 @@
-import { GeometryError } from "../errors.js";
-import { resolveCircularPrimitiveSegments } from "../primitive-resolution.js";
-import { assertPrimitiveOptions } from "../primitive-resolvers.js";
-import { requireFiniteProfileValues, requireProfileVertexCount } from "./validation.js";
+import { GeometryError } from "../../errors.js";
+import { vector2Data } from "../../math/vector-value.js";
+import { resolveCircularPrimitiveSegments } from "../../primitive-resolution.js";
+import { assertPrimitiveOptions } from "../../primitive-resolvers.js";
+import { requireFiniteProfileValues, requireProfileVertexCount } from "../validation.js";
 /**
  * Creates an immutable centered CCW ellipse with +X seam within the selected sampling ceiling.
  *
@@ -17,12 +18,7 @@ export function ellipseContour(options) {
             operation: "ellipseContour",
         });
     }
-    const dimensions = options.radius ?? options.size;
-    if (!Array.isArray(dimensions) || dimensions.length !== 2) {
-        throw new GeometryError("INVALID_ARGUMENT", "Ellipse dimensions must be an exact XY tuple.", {
-            operation: "ellipseContour",
-        });
-    }
+    const dimensions = vector2Data(options.radius ?? options.size);
     const factor = options.radius === undefined ? 0.5 : 1;
     const radiusX = dimensions[0] * factor;
     const radiusY = dimensions[1] * factor;

package/dist/geometry/profiles/{rectangle.js → primitives/rectangle.js}

@@ -1,22 +1,20 @@
-import { edgeTreatmentPointCount, edgeTreatmentSetbacks, sampleEdgeTreatment, } from "../edge-finishing.js";
-import { GeometryError } from "../errors.js";
-import { resolveModelingLimits } from "../model-limits.js";
-import { assertPrimitiveOptions } from "../primitive-resolvers.js";
-import { resolveAlignedCircularSegments } from "../resolution.js";
-import { assertSamplingCount } from "../sampling-limits.js";
-import { requireFiniteProfileValues, requireProfileVertexCount } from "./validation.js";
+import { edgeTreatmentPointCount, edgeTreatmentSetbacks, sampleEdgeTreatment, } from "../../edge-finishing.js";
+import { GeometryError } from "../../errors.js";
+import { vector2Data } from "../../math/vector-value.js";
+import { resolveModelingLimits } from "../../model-limits.js";
+import { assertPrimitiveOptions } from "../../primitive-resolvers.js";
+import { resolveAlignedCircularSegments } from "../../resolution.js";
+import { assertSamplingCount } from "../../sampling-limits.js";
+import { requireFiniteProfileValues, requireProfileVertexCount } from "../validation.js";
 const fail = (operation, message) => {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation });
 };
 /** @internal Validates the shared rectangle family before native or pure allocation. */
 export function resolveRectangle(options, operation) {
     assertPrimitiveOptions(options, operation);
-    if (typeof options.size !== "number" &&
-        (!Array.isArray(options.size) || options.size.length !== 2))
-        fail(operation, "size must be a number or an exact XY tuple.");
     if (options.center !== undefined && typeof options.center !== "boolean")
         fail(operation, "center must be boolean.");
-    const [width, height] = typeof options.size === "number" ? [options.size, options.size] : options.size;
+    const [width, height] = typeof options.size === "number" ? [options.size, options.size] : vector2Data(options.size);
     requireFiniteProfileValues([width, height], operation);
     if (!(width > 0) || !(height > 0))
         fail(operation, "Rectangle dimensions must be positive.");
@@ -79,7 +77,11 @@ export function rectangleCornerSegments(corner, limits) {
     }) / 4);
 }
 /**
- * Creates an immutable sampled CCW rectangle boundary. Round radius zero is square; tangent saturated endpoints occur once.
+ * Creates an immutable sampled CCW rectangle boundary.
+ *
+ * @remarks
+ * A zero round radius leaves square corners. When rounded corners meet, their shared endpoints
+ * appear once.
  *
  * Use [rectangle](/docs/reference/model/rectangle) for a filled Section.
  *

package/dist/geometry/profiles/primitives/regular-polygon.js

@@ -0,0 +1,33 @@
+import { GeometryError } from "../../errors.js";
+import { requireFiniteProfileValues, requireProfileVertexCount } from "../validation.js";
+/**
+ * Creates an immutable centered CCW point loop with vertex or face radial sizing and an implicit seam.
+ *
+ * @example Hexagon sized to its faces
+ * ```ts
+ * regularPolygonContour({ radius: 10, sides: 6, sizing: "face" });
+ * ```
+ */
+export const regularPolygonContour = (options) => {
+    const operation = "regularPolygonContour";
+    const { radius, sides, rotation = 0, sizing = "vertex" } = options;
+    requireFiniteProfileValues([radius, rotation], operation);
+    if (!(radius > 0)) {
+        throw new GeometryError("INVALID_ARGUMENT", "Polygon radius must be positive.", { operation });
+    }
+    requireProfileVertexCount(sides, 3, operation, options.limits);
+    if (sizing !== "vertex" && sizing !== "face")
+        throw new GeometryError("INVALID_ARGUMENT", "Polygon sizing must be vertex or face.", {
+            operation,
+        });
+    const sampledRadius = sizing === "face" ? radius / Math.cos(Math.PI / sides) : radius;
+    requireFiniteProfileValues([sampledRadius], operation);
+    const rotationRadians = ((rotation % 360) * Math.PI) / 180;
+    return Object.freeze(Array.from({ length: sides }, (_, index) => {
+        const angle = rotationRadians + (Math.PI * 2 * index) / sides;
+        return Object.freeze([
+            sampledRadius * Math.cos(angle),
+            sampledRadius * Math.sin(angle),
+        ]);
+    }));
+};

package/dist/geometry/profiles/primitives/star.js

@@ -0,0 +1,28 @@
+import { GeometryError } from "../../errors.js";
+import { assertPrimitiveOptions } from "../../primitive-resolvers.js";
+import { requireFiniteProfileValues, requireProfileVertexCount } from "../validation.js";
+/**
+ * Creates an immutable centered CCW alternating-radius star within the selected profile sampling ceiling.
+ *
+ * @example Five-point outline
+ * ```ts
+ * starContour({ outerRadius: 12, innerRadius: 6, points: 5 });
+ * ```
+ */
+export const starContour = (options) => {
+    const operation = "starContour";
+    assertPrimitiveOptions(options, operation);
+    const { outerRadius, innerRadius, points, rotation = 0, limits } = options;
+    requireFiniteProfileValues([outerRadius, innerRadius, rotation], operation);
+    if (!(outerRadius > 0) || !(innerRadius > 0) || innerRadius >= outerRadius) {
+        throw new GeometryError("INVALID_ARGUMENT", "Star radii must be positive, with the inner radius smaller than the outer.", { operation });
+    }
+    requireProfileVertexCount(points, 3, operation, limits);
+    requireProfileVertexCount(points * 2, 6, operation, limits);
+    const rotationRadians = ((rotation % 360) * Math.PI) / 180;
+    return Object.freeze(Array.from({ length: points * 2 }, (_, index) => {
+        const radius = index % 2 === 0 ? outerRadius : innerRadius;
+        const angle = (Math.PI * index) / points + rotationRadians;
+        return Object.freeze([radius * Math.cos(angle), radius * Math.sin(angle)]);
+    }));
+};

package/dist/geometry/revolve/revolve-mesh.js

@@ -26,7 +26,7 @@ const AXIS_EPSILON = 1e-10;
  * @example Partial revolution with end caps
  * ```ts
  * // Each point is [radius, Z]; the profile seam is implicit.
- * revolveMesh([[0, 0], [12, 0], [8, 20], [0, 20]], { degrees: 270 });
+ * mesh.revolve([[0, 0], [12, 0], [8, 20], [0, 20]], { degrees: 270 });
  * ```
  */
 export const revolveMesh = (input, options = {}) => {

package/dist/geometry/{svg-import.js → svg/import.js}

@@ -1,15 +1,15 @@
 import { SaxesParser } from "saxes";
 import { SVGPathData } from "svg-pathdata";
-import { bounds2 } from "./bounds-value.js";
-import { fitBounds } from "./bounds.js";
-import { GeometryError } from "./errors.js";
-import { regionArea, signedContourArea } from "./regions.js";
-import { resolveCircularSegments, resolveGeometryResolution, } from "./resolution.js";
-import { resolveGeometrySamplingLimits } from "./sampling-limits.js";
-import { strokePathMultiPolygon } from "./stroke-path.js";
-import { createBoundedSvgClipping } from "./svg/fill.js";
-import { inverseMatrix, multiplyMatrices as multiply, transformPoint } from "./svg/matrix.js";
-import { flattenSvgSubpaths, SvgVertexBudget } from "./svg/path.js";
+import { bounds2 } from "../bounds-value.js";
+import { fitBounds } from "../bounds.js";
+import { GeometryError } from "../errors.js";
+import { regionArea, signedContourArea } from "../regions.js";
+import { resolveCircularSegments, resolveGeometryResolution, } from "../resolution.js";
+import { resolveGeometrySamplingLimits } from "../sampling-limits.js";
+import { strokePathMultiPolygon } from "../stroke-path.js";
+import { createBoundedSvgClipping } from "./fill.js";
+import { inverseMatrix, multiplyMatrices as multiply, transformPoint } from "./matrix.js";
+import { flattenSvgSubpaths, SvgVertexBudget } from "./path.js";
 const MAX_SVG_BYTES = 256 * 1024;
 const MAX_SVG_ELEMENTS = 500;
 const MAX_SVG_NESTING_DEPTH = 64;

package/dist/geometry/sweeps/sweep-mesh.js

@@ -10,7 +10,7 @@ import { buildOpenSweepMesh } from "./sweep-open.js";
  * @example Sweep point data along a bent path
  * ```ts
  * const profile = rectangleContour({ size: [6, 3] });
- * sweepMesh(profile, [[0, 0, 0], [0, 0, 15], [10, 0, 25]], {
+ * mesh.sweep(profile, [[0, 0, 0], [0, 0, 15], [10, 0, 25]], {
  *   orientation: { kind: "transport", initialNormal: [0, 1, 0] },
  * });
  * ```

package/dist/geometry/transform3.js

@@ -59,6 +59,35 @@ export function validateTransform3(transform, tolerance = {}) {
     }
     return transform;
 }
+/**
+ * Validates a proper rigid transform: finite translation and a right-handed orthonormal rotation.
+ * Scale, shear, reflection, and perspective are rejected within the default angular tolerance.
+ * Returns the original row-major 4x4 matrix without copying or normalizing it.
+ *
+ * @throws {@link GeometryError} For a malformed, non-finite, or non-rigid matrix.
+ */
+export function validateRigidTransform3(transform) {
+    if (!Array.isArray(transform) || transform.length !== 16)
+        throw new GeometryError("INVALID_ARGUMENT", "Rigid transforms require sixteen matrix entries.");
+    for (let index = 0; index < 16; index++) {
+        if (!Object.hasOwn(transform, index) || !Number.isFinite(transform[index]))
+            throw new GeometryError("NON_FINITE_VALUE", "Rigid transforms require sixteen finite values.");
+    }
+    validateTransform3(transform);
+    const tolerance = resolveGeometryTolerance().angular;
+    for (let row = 0; row < 3; row++) {
+        for (let other = row; other < 3; other++) {
+            let product = 0;
+            for (let column = 0; column < 3; column++)
+                product += transform[row * 4 + column] * transform[other * 4 + column];
+            if (Math.abs(product - (row === other ? 1 : 0)) > tolerance)
+                throw new GeometryError("INVALID_ARGUMENT", "Rigid placement permits only translation and rotation; scale and shear are not supported.");
+        }
+    }
+    if (Math.abs(transformDeterminant3(transform) - 1) > tolerance)
+        throw new GeometryError("INVALID_ARGUMENT", "Rigid placement does not support reflection.");
+    return transform;
+}
 /**
  * Creates an immutable translation transform.
  *

package/dist/index.js

@@ -1,8 +1,9 @@
 /** Immutable modeling recipes and math values; the host owns geometry evaluation. @packageDocumentation */
+export { GeometryError, isGeometryError, } from "./geometry/errors.js";
 export { bounds2, bounds3, } from "./geometry/bounds-value.js";
 export { transform2, transform3, } from "./geometry/transform-value.js";
 export { vector2, vector3, } from "./geometry/math/vector-value.js";
 export { path2, path3, } from "./geometry/paths/path-value.js";
 export * from "./model/operations.js";
 export * from "./model/generation.js";
-export { immutableBuffer, immutableMesh } from "./model/immutable-buffer.js";
+export { immutableBuffer } from "./geometry/immutable-buffer.js";

package/dist/model/diagnostic-path.js

@@ -0,0 +1,26 @@
+/** Captures a bounded relative field location without reading array accessors. */
+export function captureDiagnosticPath(path) {
+    if (path === undefined)
+        return undefined;
+    const invalid = () => {
+        throw new TypeError("Diagnostic path must contain at most 32 field names or nonnegative safe indices; field names need 1–120 characters.");
+    };
+    if (!Array.isArray(path) || path.length > 32 || Reflect.ownKeys(path).length !== path.length + 1)
+        invalid();
+    const captured = [];
+    for (let index = 0; index < path.length; index++) {
+        const field = Object.getOwnPropertyDescriptor(path, String(index));
+        if (field === undefined || !("value" in field))
+            return invalid();
+        const segment = field.value;
+        if (typeof segment === "string"
+            ? segment.length === 0 || segment.length > 120
+            : typeof segment !== "number" ||
+                !Number.isSafeInteger(segment) ||
+                segment < 0 ||
+                Object.is(segment, -0))
+            invalid();
+        captured.push(segment);
+    }
+    return Object.freeze(captured);
+}

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/9");
+const executionKey = Symbol.for("@metamesh/modeling/execution/11");
 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: 7, context };
+    bindings[executionKey] = { version: 11, context };
     try {
         return build();
     }
@@ -31,5 +31,5 @@ export function currentModelContext(operation) {
 /** Reads an optional binding without initializing an engine or creating ambient authoring state. */
 export function activeModelContext() {
     const binding = bindings[executionKey];
-    return binding?.version === 7 ? binding.context : undefined;
+    return binding?.version === 11 ? binding.context : undefined;
 }

package/dist/model/generation.js

@@ -1,3 +1,4 @@
+import { captureDiagnosticPath } from "./diagnostic-path.js";
 /** 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. */
@@ -6,11 +7,16 @@ export class GenerationError extends Error {
     constructor(diagnostics) {
         super(diagnostics.at(-1)?.message ?? "Generation failed.");
         this.name = "GenerationError";
-        this.diagnostics = Object.freeze(diagnostics.map((issue) => Object.freeze({ ...issue })));
+        this.diagnostics = Object.freeze(diagnostics.map((issue) => Object.freeze({
+            ...issue,
+            ...(issue.path === undefined ? {} : { path: captureDiagnosticPath(issue.path) }),
+        })));
     }
 }
 /**
- * Defines a typed model without executing it. Use `computed` only for work worth reusing.
+ * Defines a typed model without executing it. Parameters are an object map of capturable data;
+ * runtime capture rejects arrays at the root, ordinary class instances, mutable buffers, and functions.
+ * Supply live capabilities through services. Use `computed` only for work worth reusing.
  *
  * @example A simple model
  * ```ts

package/dist/model/geometry-recipes.js

@@ -1,7 +1,7 @@
 import { createSectionHandle, createSolidHandle } from "./shape-handles.js";
 // One realm protocol lets bundled authoring code declare recipes before a host is initialized.
 // The payload contains no native handles and the engine remains responsible for realization.
-const recipeKey = Symbol.for("@metamesh/modeling/recipe/9");
+const recipeKey = Symbol.for("@metamesh/modeling/recipe/10");
 /** Reads private recipe metadata without requiring an execution context. */
 export const geometryRecipe = (value) => Object.getOwnPropertyDescriptor(value, recipeKey)?.value;
 /** Recognizes only opaque recipe handles issued by this engine. */