@metamesh/modeling 0.14.0 → 0.15.0

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

@@ -36,9 +36,9 @@ function validationWork(mesh, options) {
             operation: "validateSolidMesh",
         });
     const count = mesh.indices.length / 3;
-    const maximumTests = options.maximumTests ?? MAXIMUM_TESTS;
-    if (!Number.isSafeInteger(maximumTests) || maximumTests < 1 || maximumTests > MAXIMUM_TESTS)
-        throw new GeometryError("INVALID_ARGUMENT", "Solid validation maximumTests must be an integer from 1 through 2,000,000.", { operation: "validateSolidMesh" });
+    const maxTests = options.maxTests ?? MAXIMUM_TESTS;
+    if (!Number.isSafeInteger(maxTests) || maxTests < 1 || maxTests > MAXIMUM_TESTS)
+        throw new GeometryError("INVALID_ARGUMENT", "Solid validation maxTests must be an integer from 1 through 2,000,000.", { operation: "validateSolidMesh" });
     if (count > MAXIMUM_TRIANGLES)
         throw new GeometryError("COMPLEXITY_LIMIT", "Solid validation exceeds its triangle ceiling.", {
             operation: "validateSolidMesh",
@@ -46,7 +46,7 @@ function validationWork(mesh, options) {
         });
     if (mesh.positions.length / 3 > mesh.indices.length)
         throw new GeometryError("INVALID_MESH", "Solid validation requires every position-buffer vertex to be referenced.", { operation: "validateSolidMesh" });
-    return { count, maximumTests };
+    return { count, maxTests };
 }
 /** @internal Fresh measurements precede one adjacency traversal for closure, fans, and shells. */
 export function analyzeSolidMesh(mesh, options = {}) {
@@ -71,14 +71,14 @@ export function validateAnalyzedSolidMesh(mesh, measurements, options = {}) {
         : mesh;
     checkSolidGeometry(source, measurements, options, validationWork(source, options));
 }
-function checkSolidGeometry(mesh, facts, options, { count, maximumTests }) {
+function checkSolidGeometry(mesh, facts, options, { count, maxTests }) {
     const epsilon = resolveGeometryTolerance(Math.hypot(...facts.bounds.max.map((value, axis) => value - facts.bounds.min[axis])), options.tolerance).linear;
     let tests = 0;
     const spend = () => {
-        if (++tests > maximumTests)
+        if (++tests > maxTests)
             throw new GeometryError("COMPLEXITY_LIMIT", "Solid validation exhausted its work ceiling.", {
                 operation: "validateSolidMesh",
-                details: { required: tests, allowed: maximumTests },
+                details: { required: tests, allowed: maxTests },
             });
     };
     const vertex = (index) => [

package/dist/geometry/mesh/mesh.js

@@ -1,6 +1,7 @@
 import { GeometryError } from "../errors.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) {
@@ -184,19 +185,6 @@ export function validateTriangleMesh(mesh, options = {}) {
 export const meshBounds = (mesh) => {
     return inspectTriangleMesh(mesh, {}, "bounds");
 };
-/**
- * Measures bounds, surface area, and signed volume without changing the mesh.
- *
- * Signed volume is meaningful for a consistently wound closed mesh. Set
- * `requireClosed` when measurements will be used as manufacturing assertions.
- *
- * @param mesh - Mesh to validate and measure.
- * @param options - Validation policy applied before measurement.
- * @returns Immutable deterministic scalar and bounds measurements.
- */
-export function measureTriangleMesh(mesh, options = {}) {
-    return inspectTriangleMesh(mesh, options, "measure");
-}
 /**
  * Concatenates meshes into one indexed mesh without welding coincident vertices.
  *
@@ -257,12 +245,13 @@ export function reverseTriangleMesh(mesh) {
  * automatically reverses every triangle. Singular transforms are rejected.
  *
  * @param mesh - Mesh to transform without mutation.
- * @param transform - Row-major affine transform.
+ * @param placement - Immutable spatial placement or canonical row-major affine matrix.
  * @returns A mesh with fresh transformed positions and copied or reversed indices.
  */
-export function transformTriangleMesh(mesh, transform) {
+export function transformTriangleMesh(mesh, placement) {
     const source = { positions: mesh.positions, indices: mesh.indices };
     validateTriangleMesh(source);
+    const transform = readTransformMatrix(placement, 3);
     validateTransform3(transform);
     const positions = new Float32Array(source.positions.length);
     for (let offset = 0; offset < source.positions.length; offset += 3) {

package/dist/geometry/paths/closest-point.js

@@ -1,37 +1,26 @@
 import { GeometryError } from "../errors.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
-export function closestPointOnPath(path, point, options = {}) {
+/** Internal scalar scan. Immutable paths validate their coordinates and ceiling once at construction. */
+export function closestPointOnValidatedPath(path, point, closed) {
     const fail = (message, code = "INVALID_ARGUMENT") => {
-        throw new GeometryError(code, message, { operation: "closestPointOnPath" });
+        throw new GeometryError(code, message, { operation: "path.closestPoint" });
     };
     const dimensions = point.length;
-    const closed = options.closed ?? false;
-    if (typeof closed !== "boolean" || (dimensions !== 2 && dimensions !== 3))
-        fail("Use a 2D or 3D point and a boolean closed option.");
-    assertSamplingCount(path.length, "closestPointOnPath", resolveGeometrySamplingLimits(options.limits).maxPathPoints);
     if (path.length < (closed ? 3 : 2))
         fail("Open paths need two points; closed paths need three.");
-    const validate = (value) => {
-        if (value.length !== dimensions)
-            fail("Path and query points must have the same dimension.");
-        if (!Number.isFinite(value[0]) ||
-            !Number.isFinite(value[1]) ||
-            (dimensions === 3 && !Number.isFinite(value[2])))
-            fail("Path and query coordinates must be finite.", "NON_FINITE_VALUE");
-    };
-    validate(point);
-    validate(path[0]);
+    if (!Number.isFinite(point[0]) ||
+        !Number.isFinite(point[1]) ||
+        (dimensions === 3 && !Number.isFinite(point[2])))
+        fail("Query coordinates must be finite.", "NON_FINITE_VALUE");
     let bestDistance = Infinity, bestSquared = Infinity, edgeIndex = 0, fraction = 0;
     let bestX = 0, bestY = 0, bestZ = 0;
     const count = closed ? path.length : path.length - 1;
     for (let i = 0; i < count; i++) {
         const a = path[i], b = path[(i + 1) % path.length];
-        validate(b);
         const dx = b[0] - a[0], dy = b[1] - a[1], dz = (b[2] ?? 0) - (a[2] ?? 0);
         const px = point[0] - a[0], py = point[1] - a[1], pz = (point[2] ?? 0) - (a[2] ?? 0);
         const lengthSquared = dx * dx + dy * dy + dz * dz;
         let projection = (px * dx + py * dy + pz * dz) / lengthSquared;
-        if (!Number.isFinite(projection)) {
+        if (!Number.isFinite(lengthSquared) || !Number.isFinite(projection)) {
             // Normalize only extreme extents; ordinary boundary scans use scalar squared arithmetic.
             const scale = Math.max(Math.abs(dx), Math.abs(dy), Math.abs(dz));
             if (!Number.isFinite(scale))

package/dist/geometry/paths/frames.js

@@ -1,5 +1,15 @@
+import { GeometryError } from "../errors.js";
+import { vector3Data } from "../math/vector-value.js";
 import { cross3, dot3, length3, normalize3, projectOntoPlane3, rotateAroundAxis3Radians, scale3, subtract3, } from "../math/vector3.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+import { path3InputData } from "./path-value.js";
+const guideData = (input, operation) => {
+    const coordinates = vector3Data(input);
+    if (!coordinates.every(Number.isFinite))
+        throw new GeometryError("NON_FINITE_VALUE", "Path frame guides must have finite coordinates.", {
+            operation,
+        });
+    return coordinates;
+};
 const tangentAt = (path, index) => {
     if (index === 0) {
         return normalize3(subtract3(path[1], path[0]));
@@ -23,7 +33,9 @@ const chooseInitialNormal = (tangent, preferred) => {
             return normalize3(projected);
         }
     }
-    throw new Error("Unable to choose an initial path normal.");
+    throw new GeometryError("DEGENERATE_GEOMETRY", "Unable to choose an initial path normal.", {
+        operation: "computeParallelTransportFrames",
+    });
 };
 const transportNormal = (normal, previousTangent, tangent) => {
     const rotationAxis = cross3(previousTangent, tangent);
@@ -40,15 +52,20 @@ const transportNormal = (normal, previousTangent, tangent) => {
  * Builds rotation-minimizing frames by parallel-transporting the previous normal.
  * This avoids the sudden profile flips produced by picking a fresh up-vector per ring.
  * Paths exceeding maxPathPoints (default 100000) reject before frame allocation or guide evaluation.
+ * Requires open path values; raw tuples are interpreted as an open path. Invalid paths throw GeometryError.
+ * Nonfinite normals and guide results reject. A finite initial guide parallel to the tangent selects a canonical fallback.
  */
-export const computeParallelTransportFrames = (path, initialNormal, normalGuide, limits = {}) => {
+export const computeParallelTransportFrames = (input, initialNormal, normalGuide, limits = {}) => {
+    const { points: path } = path3InputData(input, false, limits);
     if (path.length < 2) {
-        throw new Error("A framed path needs at least two points.");
+        throw new GeometryError("INVALID_ARGUMENT", "A framed path needs at least two points.", {
+            operation: "computeParallelTransportFrames",
+        });
     }
-    assertSamplingCount(path.length, "computeParallelTransportFrames", resolveGeometrySamplingLimits(limits).maxPathPoints);
     const tangents = path.map((_, index) => tangentAt(path, index));
     const firstTangent = tangents[0];
-    let normal = chooseInitialNormal(firstTangent, normalGuide?.(path[0], 0) ?? initialNormal);
+    const firstGuide = normalGuide?.(path[0], 0) ?? initialNormal;
+    let normal = chooseInitialNormal(firstTangent, firstGuide === undefined ? undefined : guideData(firstGuide, "computeParallelTransportFrames"));
     const frames = [
         {
             tangent: firstTangent,
@@ -64,7 +81,7 @@ export const computeParallelTransportFrames = (path, initialNormal, normalGuide,
             normal = transportNormal(normal, previousTangent, tangent);
         }
         else {
-            const guided = normalize3(projectOntoPlane3(guide, tangent));
+            const guided = normalize3(projectOntoPlane3(guideData(guide, "computeParallelTransportFrames"), tangent));
             // A guide describes an unoriented plane direction. Preserve the prior
             // sign so noisy guide inputs cannot create a 180-degree seam flip.
             normal = dot3(guided, normal) < 0 ? scale3(guided, -1) : guided;
@@ -92,14 +109,27 @@ const signedAngleAround = (from, to, axis) => Math.atan2(dot3(axis, cross3(from,
  * normal back to the first tangent measures seam holonomy; distributing that residual rotation
  * uniformly over all path intervals avoids a visible seam or accumulated frame flip.
  * The maxPathPoints ceiling (default 100000) bounds path points and frames.
+ * Requires closed path values; raw tuples are interpreted as closed and must omit their seam point.
+ * Invalid paths throw GeometryError.
+ * Nonfinite initial normals reject; finite parallel preferences select a canonical fallback.
  */
-export const computeClosedParallelTransportFrames = (path, initialNormal, limits = {}) => {
+export const computeClosedParallelTransportFrames = (input, initialNormal, limits = {}) => {
+    const { points: path } = path3InputData(input, true, limits);
     if (path.length < 3) {
-        throw new Error("A closed framed path needs at least three points.");
+        throw new GeometryError("INVALID_ARGUMENT", "A closed framed path needs at least three points.", {
+            operation: "computeClosedParallelTransportFrames",
+        });
     }
-    assertSamplingCount(path.length, "computeClosedParallelTransportFrames", resolveGeometrySamplingLimits(limits).maxPathPoints);
+    if (path[0].every((coordinate, axis) => coordinate === path.at(-1)[axis]))
+        throw new GeometryError("INVALID_ARGUMENT", "Closed framed paths omit their repeated seam point.", {
+            operation: "computeClosedParallelTransportFrames",
+        });
     const tangents = path.map((_, index) => closedTangentAt(path, index));
-    const transportedNormals = [chooseInitialNormal(tangents[0], initialNormal)];
+    const transportedNormals = [
+        chooseInitialNormal(tangents[0], initialNormal === undefined
+            ? undefined
+            : guideData(initialNormal, "computeClosedParallelTransportFrames")),
+    ];
     for (let index = 1; index < tangents.length; index += 1) {
         transportedNormals.push(transportNormal(transportedNormals[index - 1], tangents[index - 1], tangents[index]));
     }

package/dist/geometry/paths/helix.js

@@ -1,31 +1,39 @@
+import { GeometryError } from "../errors.js";
 import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
 /**
  * Creates `segments + 1` points including exact helix endpoints from finite positive dimensions.
  * Integrated weights must remain finite. The maxPathPoints ceiling defaults to 100000; excessive
  * exact counts reject before evaluating axial weights or allocating sample arrays.
+ * Invalid inputs use GeometryError; exceptions thrown by axialWeight propagate unchanged.
  */
 export const sampleHelix = ({ turns, radius, height, segments, limits, axialWeight = () => 1, }) => {
     if (![turns, radius, height].every(Number.isFinite) || !(turns > 0 && radius > 0 && height > 0)) {
-        throw new Error("Helix turns, radius, and height must be finite and positive.");
+        throw new GeometryError([turns, radius, height].every(Number.isFinite) ? "INVALID_ARGUMENT" : "NON_FINITE_VALUE", "Helix turns, radius, and height must be finite and positive.", { operation: "sampleHelix" });
     }
     if (!Number.isInteger(segments) || segments < 3) {
-        throw new Error("A helix needs at least three segments.");
+        throw new GeometryError("INVALID_ARGUMENT", "A helix needs at least three segments.", {
+            operation: "sampleHelix",
+        });
     }
     assertSamplingCount(segments + 1, "sampleHelix", resolveGeometrySamplingLimits(limits).maxPathPoints);
     const angleRange = Math.PI * 2 * turns;
     if (!Number.isFinite(angleRange)) {
-        throw new Error("Helix angle range must be finite.");
+        throw new GeometryError("NON_FINITE_VALUE", "Helix angle range must be finite.", {
+            operation: "sampleHelix",
+        });
     }
     const weights = Array.from({ length: segments }, (_, index) => {
         const value = axialWeight((index + 0.5) / segments);
         if (!Number.isFinite(value) || value <= 0) {
-            throw new Error("Helix axial weights must be finite and positive.");
+            throw new GeometryError(Number.isFinite(value) ? "INVALID_ARGUMENT" : "NON_FINITE_VALUE", "Helix axial weights must be finite and positive.", { operation: "sampleHelix" });
         }
         return value;
     });
     const totalWeight = weights.reduce((sum, weight) => sum + weight, 0);
     if (!Number.isFinite(totalWeight)) {
-        throw new Error("Helix integrated axial weight must be finite.");
+        throw new GeometryError("NON_FINITE_VALUE", "Helix integrated axial weight must be finite.", {
+            operation: "sampleHelix",
+        });
     }
     let accumulatedWeight = 0;
     const result = [];
@@ -41,7 +49,9 @@ export const sampleHelix = ({ turns, radius, height, segments, limits, axialWeig
             height * (accumulatedWeight / totalWeight),
         ];
         if (!point.every(Number.isFinite)) {
-            throw new Error("Helix sampled coordinates must be finite.");
+            throw new GeometryError("NON_FINITE_VALUE", "Helix sampled coordinates must be finite.", {
+                operation: "sampleHelix",
+            });
         }
         result.push(point);
     }

package/dist/geometry/paths/path-value.js

@@ -0,0 +1,252 @@
+import { GeometryError } from "../errors.js";
+import { immutableMathClass } from "../math/immutable-value.js";
+import { vector2, vector2Data, vector3, vector3Data, } from "../math/vector-value.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+import { transformPath2, transformPath3 } from "../transform-geometry.js";
+import { closestPointOnValidatedPath } from "./closest-point.js";
+import { resamplePath2Data, resamplePath3Data } from "./resampling.js";
+const fail = (message, code = "INVALID_ARGUMENT") => {
+    throw new GeometryError(code, message, { operation: "path" });
+};
+// Ordinary tuples keep numerical loops fast. Never expose this owned storage to callers or guides;
+// the deeply frozen interchange snapshot is created only when a consumer actually needs it.
+const pathStates = new WeakMap();
+const stateOf = (owner) => pathStates.get(owner);
+const points2 = (owner) => stateOf(owner).points;
+const points3 = (owner) => stateOf(owner).points;
+function freezePoints(points) {
+    for (const point of points)
+        Object.freeze(point);
+    return Object.freeze(points);
+}
+function frozenArray(owner) {
+    const state = stateOf(owner);
+    return (state.array ??= freezePoints(state.points.map((point) => [...point])));
+}
+function closedOption(closed) {
+    if (closed !== undefined && typeof closed !== "boolean")
+        fail("Path closed must be a boolean.");
+    return closed ?? false;
+}
+function snapshot(input, dimension, limits) {
+    if (!Array.isArray(input))
+        fail("Path points must be an array of coordinate tuples or vectors.");
+    const count = input.length;
+    assertSamplingCount(count, "path", limits.maxPathPoints);
+    const points = [];
+    for (let index = 0; index < count; index++) {
+        const values = dimension === 2
+            ? vector2Data(input[index])
+            : vector3Data(input[index]);
+        // Read exactly the required coordinates once; user accessors and array iterators cannot
+        // change an already validated snapshot or grow its allocation beyond the initial ceiling.
+        const copied = dimension === 2 ? [values[0], values[1]] : [values[0], values[1], values[2]];
+        for (const coordinate of copied)
+            if (!Number.isFinite(coordinate))
+                fail("Path coordinates must be finite.", "NON_FINITE_VALUE");
+        points.push(copied);
+    }
+    return points;
+}
+function validateClosure(points, closed) {
+    if (!closed)
+        return;
+    if (points.length < 3)
+        fail("Closed paths need at least three vertices.");
+    const first = points[0], last = points.at(-1);
+    if (first.every((coordinate, index) => coordinate === last[index]))
+        fail("Closed paths omit the repeated closing vertex.");
+}
+function pathSource(input, closed, dimension) {
+    if (Array.isArray(input))
+        return { points: input, closed: closedOption(closed) };
+    if (typeof input !== "object" ||
+        input === null ||
+        !("toArray" in input) ||
+        typeof input.toArray !== "function" ||
+        !("closed" in input) ||
+        !("dimension" in input) ||
+        input.dimension !== dimension)
+        return fail("Expected a path or an array of coordinate tuples or vectors.");
+    if (typeof input.closed !== "boolean")
+        fail("Path closure metadata must be a boolean.");
+    const sourceClosed = input.closed;
+    if (closed !== undefined && closedOption(closed) !== sourceClosed)
+        fail("The closed option conflicts with the path's closure.");
+    const points = pathStates.get(input)?.points ?? input.toArray();
+    if (!Array.isArray(points))
+        fail("Path points must be an array of coordinate tuples or vectors.");
+    return { points, closed: sourceClosed };
+}
+function measuredLength(owner) {
+    const state = stateOf(owner);
+    const cached = state.length;
+    if (cached !== undefined)
+        return cached;
+    const points = state.points;
+    let total = 0;
+    const count = owner.closed ? points.length : Math.max(0, points.length - 1);
+    for (let index = 0; index < count; index++) {
+        const a = points[index], b = points[(index + 1) % points.length];
+        total += Math.hypot(b[0] - a[0], b[1] - a[1], (b[2] ?? 0) - (a[2] ?? 0));
+        if (!Number.isFinite(total))
+            fail("Path length exceeds finite arithmetic.", "NON_FINITE_VALUE");
+    }
+    state.length = total;
+    return total;
+}
+function measuredBounds(points) {
+    if (points.length === 0)
+        return undefined;
+    const min = [...points[0]], max = [...points[0]];
+    for (let index = 1; index < points.length; index++) {
+        const point = points[index];
+        for (let axis = 0; axis < point.length; axis++) {
+            min[axis] = Math.min(min[axis], point[axis]);
+            max[axis] = Math.max(max[axis], point[axis]);
+        }
+    }
+    return Object.freeze({ min: Object.freeze(min), max: Object.freeze(max) });
+}
+function samplingOptions(options, closed) {
+    if (typeof options !== "object" || options === null || Array.isArray(options))
+        fail("Path resampling options must be an object.");
+    if ("closed" in options)
+        fail("Path resampling preserves its existing closure.");
+    return { ...options, closed };
+}
+const PlanarPath = /* @__PURE__ */ immutableMathClass(class PlanarPath {
+    closed;
+    dimension = 2;
+    constructor(points, closed) {
+        this.closed = closed;
+        pathStates.set(this, { points });
+        Object.freeze(this);
+    }
+    toArray() {
+        return frozenArray(this);
+    }
+    length() {
+        return measuredLength(this);
+    }
+    bounds() {
+        return measuredBounds(points2(this));
+    }
+    closestPoint(point) {
+        const location = closestPointOnValidatedPath(points2(this), vector2Data(point), this.closed);
+        return Object.freeze({ ...location, point: vector2(location.point) });
+    }
+    transform(placement) {
+        return new PlanarPath(transformPath2(points2(this), placement), this.closed);
+    }
+    reverse() {
+        return new PlanarPath([...points2(this)].reverse(), this.closed);
+    }
+    resample(options = {}) {
+        const policy = samplingOptions(options, this.closed);
+        return new PlanarPath(resamplePath2Data(points2(this), policy), this.closed);
+    }
+});
+const SpatialPath = /* @__PURE__ */ immutableMathClass(class SpatialPath {
+    closed;
+    dimension = 3;
+    constructor(points, closed) {
+        this.closed = closed;
+        pathStates.set(this, { points });
+        Object.freeze(this);
+    }
+    toArray() {
+        return frozenArray(this);
+    }
+    length() {
+        return measuredLength(this);
+    }
+    bounds() {
+        return measuredBounds(points3(this));
+    }
+    closestPoint(point) {
+        const location = closestPointOnValidatedPath(points3(this), vector3Data(point), this.closed);
+        return Object.freeze({ ...location, point: vector3(location.point) });
+    }
+    transform(placement) {
+        return new SpatialPath(transformPath3(points3(this), placement), this.closed);
+    }
+    reverse() {
+        return new SpatialPath([...points3(this)].reverse(), this.closed);
+    }
+    resample(options = {}) {
+        const policy = samplingOptions(options, this.closed);
+        return new SpatialPath(resamplePath3Data(points3(this), policy), this.closed);
+    }
+});
+/**
+ * Snapshots finite XY coordinates as an immutable sampled path, independent of engine initialization.
+ * Open paths may be empty or have one point; closed paths need three vertices and omit a duplicated
+ * seam. Repeated adjacent vertices are retained. No winding normalization or filling is performed.
+ * Malformed dimensions or topology throw INVALID_ARGUMENT; nonfinite coordinates or measurement
+ * overflow throw NON_FINITE_VALUE; exhausted allocation ceilings throw COMPLEXITY_LIMIT GeometryError.
+ * A path input retains its closure. Limits bound construction only; resampling takes its own limits.
+ */
+export function path2(input, options = {}) {
+    validateOptions(options);
+    const limits = resolveGeometrySamplingLimits(options.limits);
+    const source = pathSource(input, options.closed, 2);
+    const points = snapshot(source.points, 2, limits);
+    validateClosure(points, source.closed);
+    return new PlanarPath(points, source.closed);
+}
+/**
+ * Snapshots finite XYZ coordinates as an immutable sampled path with the same closure, seam,
+ * allocation and error rules as path2. Analytic curves must be sampled explicitly first.
+ */
+export function path3(input, options = {}) {
+    validateOptions(options);
+    const limits = resolveGeometrySamplingLimits(options.limits);
+    const source = pathSource(input, options.closed, 3);
+    const points = snapshot(source.points, 3, limits);
+    validateClosure(points, source.closed);
+    return new SpatialPath(points, source.closed);
+}
+function validateOptions(options) {
+    if (typeof options !== "object" || options === null || Array.isArray(options))
+        fail("Path options must be an object.");
+}
+/** Internal aggregate preflight without coordinate reads or copies. */
+export function path2InputPointCount(input, closed) {
+    const source = pathSource(input, closed, 2);
+    if (!Array.isArray(source.points))
+        fail("Path points must be an array of coordinate tuples or vectors.");
+    return source.points.length;
+}
+/** Internal source capture for aggregate preflight followed by normalization, reading foreign data once. */
+export function capturePath2Input(input, closed) {
+    const source = pathSource(input, closed, 2);
+    return {
+        input: input instanceof PlanarPath ? input : source.points,
+        count: source.points.length,
+    };
+}
+/** Internal boundary normalization; raw interchange retains the consuming operation's topology rules. */
+export function path2InputData(input, closed, limits) {
+    const source = pathSource(input, closed, 2);
+    const policy = resolveGeometrySamplingLimits(limits);
+    assertSamplingCount(source.points.length, "path", policy.maxPathPoints);
+    return {
+        points: input instanceof PlanarPath
+            ? input.toArray()
+            : freezePoints(snapshot(source.points, 2, policy)),
+        closed: source.closed,
+    };
+}
+/** Internal boundary normalization; immutable path coordinates can be shared without copying. */
+export function path3InputData(input, closed, limits) {
+    const source = pathSource(input, closed, 3);
+    const policy = resolveGeometrySamplingLimits(limits);
+    assertSamplingCount(source.points.length, "path", policy.maxPathPoints);
+    return {
+        points: input instanceof SpatialPath
+            ? input.toArray()
+            : freezePoints(snapshot(source.points, 3, policy)),
+        closed: source.closed,
+    };
+}

package/dist/geometry/paths/planar.js

@@ -1,6 +1,10 @@
 import { GeometryError } from "../errors.js";
 import { length3, normalize3, subtract3 } from "../math/vector3.js";
 import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+import { path3InputData } from "./path-value.js";
+const invalidPath = (message, operation) => {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation });
+};
 const requireFinitePathValues = (values, operation) => {
     if (!values.every(Number.isFinite)) {
         throw new GeometryError("NON_FINITE_VALUE", "Path dimensions and coordinates must be finite.", {
@@ -22,25 +26,29 @@ const segmentLengths = (path, closed) => path.map((point, index) => {
  * open paths include both endpoints when `count` is greater than one.
  * Coordinates and total length must be finite. Input points and output placements are each
  * limited by maxPathPoints (default 100000); exact counts exceeding that ceiling reject before length calculation.
+ * Closure defaults to the path value's metadata, or false for tuples. An explicit conflicting closure rejects.
+ * Invalid arguments and degenerate paths throw GeometryError.
  */
-export const distributeAlongPath = (path, count, closed, limits = {}) => {
-    if (path.length < (closed ? 3 : 2)) {
-        throw new Error(`${closed ? "Closed" : "Open"} distribution paths need more points.`);
-    }
+export const distributeAlongPath = (input, count, closed, limits = {}) => {
     if (!Number.isInteger(count) || count < 1) {
-        throw new Error("Path distribution count must be a positive integer.");
+        invalidPath("Path distribution count must be a positive integer.", "distributeAlongPath");
     }
     const maximum = resolveGeometrySamplingLimits(limits).maxPathPoints;
     assertSamplingCount(count, "distributeAlongPath", maximum);
-    assertSamplingCount(path.length, "distributeAlongPath", maximum);
-    for (const point of path)
-        requireFinitePathValues(point, "distributeAlongPath");
-    const lengths = segmentLengths(path, closed);
+    const { points: path, closed: closePath } = path3InputData(input, closed, limits);
+    if (path.length < (closePath ? 3 : 2)) {
+        invalidPath(`${closePath ? "Closed" : "Open"} distribution paths need more points.`, "distributeAlongPath");
+    }
+    if (closePath && path[0].every((coordinate, axis) => coordinate === path.at(-1)[axis]))
+        invalidPath("Closed distribution paths omit their repeated seam point.", "distributeAlongPath");
+    const lengths = segmentLengths(path, closePath);
     const total = lengths.reduce((sum, length) => sum + length, 0);
     requireFinitePathValues([total], "distributeAlongPath");
     if (!(total > 0))
-        throw new Error("Cannot distribute along a zero-length path.");
-    const denominator = closed ? count : Math.max(1, count - 1);
+        throw new GeometryError("DEGENERATE_GEOMETRY", "Cannot distribute along a zero-length path.", {
+            operation: "distributeAlongPath",
+        });
+    const denominator = closePath ? count : Math.max(1, count - 1);
     let traversed = 0;
     let segment = 0;
     return Array.from({ length: count }, (_, itemIndex) => {
@@ -64,7 +72,7 @@ export const distributeAlongPath = (path, count, closed, limits = {}) => {
             }
             traversed += length;
         }
-        throw new Error("Path distribution invariant failed.");
+        return invalidPath("Path distribution invariant failed.", "distributeAlongPath");
     });
 };
 /**
@@ -75,21 +83,26 @@ export const distributeAlongPath = (path, count, closed, limits = {}) => {
  * 45% of adjacent segment lengths to prevent neighboring corners from crossing.
  * The returned path does not duplicate its closing point.
  * Coordinates and radius must be finite; input and output are each limited by maxPathPoints (default 100000).
+ * Requires a closed path value; raw tuples are interpreted as closed. Invalid inputs throw GeometryError.
  */
-export const roundClosedPolylinePath = (points, radius, segmentsPerCorner, limits = {}) => {
-    if (points.length < 3)
-        throw new Error("Closed polylines need at least three points.");
+export const roundClosedPolylinePath = (input, radius, segmentsPerCorner, limits = {}) => {
     const maximum = resolveGeometrySamplingLimits(limits).maxPathPoints;
-    assertSamplingCount(points.length, "roundClosedPolylinePath", maximum);
     requireFinitePathValues([radius], "roundClosedPolylinePath");
     if (!(radius > 0))
-        throw new Error("Corner radius must be positive.");
+        invalidPath("Corner radius must be positive.", "roundClosedPolylinePath");
     if (!Number.isInteger(segmentsPerCorner) || segmentsPerCorner < 1) {
-        throw new Error("Rounded corners need at least one segment.");
+        invalidPath("Rounded corners need at least one segment.", "roundClosedPolylinePath");
     }
-    assertSamplingCount(points.length * (segmentsPerCorner + 1), "roundClosedPolylinePath", maximum);
-    for (const point of points)
-        requireFinitePathValues(point, "roundClosedPolylinePath");
+    // Reject exact output budgets before snapshotting tuple input or calculating any corner.
+    if (Array.isArray(input))
+        assertSamplingCount(input.length * (segmentsPerCorner + 1), "roundClosedPolylinePath", maximum);
+    const { points } = path3InputData(input, true, limits);
+    if (!Array.isArray(input))
+        assertSamplingCount(points.length * (segmentsPerCorner + 1), "roundClosedPolylinePath", maximum);
+    if (points.length < 3)
+        invalidPath("Closed polylines need at least three points.", "roundClosedPolylinePath");
+    if (points[0].every((coordinate, axis) => coordinate === points.at(-1)[axis]))
+        invalidPath("Closed polylines omit their repeated seam point.", "roundClosedPolylinePath");
     return points.flatMap((point, index) => {
         const previous = points[(index - 1 + points.length) % points.length];
         const next = points[(index + 1) % points.length];
@@ -99,14 +112,14 @@ export const roundClosedPolylinePath = (points, radius, segmentsPerCorner, limit
         const outgoingLength = length3(outgoingDelta);
         requireFinitePathValues([incomingLength, outgoingLength], "roundClosedPolylinePath");
         if (!(incomingLength > 0) || !(outgoingLength > 0)) {
-            throw new Error("Closed polylines cannot contain duplicate adjacent points.");
+            invalidPath("Closed polylines cannot contain duplicate adjacent points.", "roundClosedPolylinePath");
         }
         const incoming = normalize3(incomingDelta);
         const outgoing = normalize3(outgoingDelta);
         const cornerCosine = Math.max(-1, Math.min(1, -(incoming[0] * outgoing[0] + incoming[1] * outgoing[1] + incoming[2] * outgoing[2])));
         const cornerAngle = Math.acos(cornerCosine);
         if (cornerAngle < 1e-6 || Math.abs(Math.PI - cornerAngle) < 1e-6) {
-            throw new Error("Rounded polyline corners must change direction.");
+            invalidPath("Rounded polyline corners must change direction.", "roundClosedPolylinePath");
         }
         const tangentDistance = Math.min(radius / Math.tan(cornerAngle / 2), incomingLength * 0.45, outgoingLength * 0.45);
         const entry = [