@metamesh/modeling 0.14.0 → 0.16.0

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

@@ -0,0 +1,268 @@
+import { bounds2, bounds3 } from "../bounds-value.js";
+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 { resamplePath2Points, resamplePath3Points } 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 frozenData(owner) {
+    const state = stateOf(owner);
+    return (state.data ??= Object.freeze({
+        dimension: owner.dimension,
+        closed: owner.closed,
+        points: 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)
+        return fail("Expected a path value, path data, or an array of vectors.");
+    const own = pathStates.get(input);
+    const method = Reflect.get(input, "toData");
+    const data = own !== undefined
+        ? input
+        : typeof method === "function"
+            ? Reflect.apply(method, input, [])
+            : input;
+    if (typeof data !== "object" || data === null)
+        return fail("Expected complete path data.");
+    const sourceDimension = Reflect.get(data, "dimension");
+    const sourceClosed = Reflect.get(data, "closed");
+    const points = own?.points ?? Reflect.get(data, "points");
+    if (sourceDimension !== dimension || typeof sourceClosed !== "boolean" || !Array.isArray(points))
+        return fail("Path data requires matching dimension, boolean closure, and an array of vectors.");
+    if (closed !== undefined && closedOption(closed) !== sourceClosed)
+        fail("The closed option conflicts with the path's closure.");
+    return { points: 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 min.length === 2
+        ? bounds2({ min: [min[0], min[1]], max: [max[0], max[1]] })
+        : bounds3({ min: [min[0], min[1], min[2]], max: [max[0], max[1], max[2]] });
+}
+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);
+    }
+    toData() {
+        return frozenData(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(resamplePath2Points(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);
+    }
+    toData() {
+        return frozenData(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(resamplePath3Points(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.
+ *
+ * Use `toData()` for a frozen record that restores coordinates, closure, and dimension together.
+ */
+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.
+ *
+ * Use `toData()` for a frozen record that restores coordinates, closure, and dimension together.
+ *
+ * @see {@link path2} for shared construction rules.
+ */
+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.toData().points
+            : 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.toData().points
+            : 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 = [

package/dist/geometry/paths/resampling.js

@@ -9,7 +9,7 @@ const distance = (a, b) => {
         curveFailure("NON_FINITE_VALUE", "Curve extent exceeds finite arithmetic.");
     return value;
 };
-function resamplePolyline(path, dimensions, options, createWriter) {
+function resamplePolyline(path, dimensions, options, createWriter, includeTangents = true) {
     const maximum = resolveSamplingBudget(options);
     if (options.closed !== undefined && typeof options.closed !== "boolean")
         curveFailure("INVALID_ARGUMENT", "closed must be a boolean.");
@@ -91,10 +91,12 @@ function resamplePolyline(path, dimensions, options, createWriter) {
             point[2] = z(a) + (z(b) - z(a)) * t;
         }
         validateCurvePoint3(point);
-        tangent[0] = b[0] - a[0];
-        tangent[1] = b[1] - a[1];
-        tangent[2] = z(b) - z(a);
-        normalizeCurveDirection(tangent, tangent);
+        if (includeTangents) {
+            tangent[0] = b[0] - a[0];
+            tangent[1] = b[1] - a[1];
+            tangent[2] = z(b) - z(a);
+            normalizeCurveDirection(tangent, tangent);
+        }
         writer.append(point, tangent);
     }
     return writer.finish();
@@ -123,3 +125,23 @@ export function resamplePolyline3(path, options = {}) {
 export function resamplePolyline2(path, options = {}) {
     return resamplePolyline(path, 2, options, createPlanarSampleWriter);
 }
+/** Internal points-only writer; Path2 owns these mutable coordinates and freezes public interchange. */
+export function resamplePath2Points(path, options) {
+    const points = [];
+    return resamplePolyline(path, 2, options, () => ({
+        append: (point) => {
+            points.push([point[0], point[1]]);
+        },
+        finish: () => points,
+    }), false);
+}
+/** Internal points-only writer; avoids calculating and allocating tangents discarded by Path3. */
+export function resamplePath3Points(path, options) {
+    const points = [];
+    return resamplePolyline(path, 3, options, () => ({
+        append: (point) => {
+            points.push([point[0], point[1], point[2]]);
+        },
+        finish: () => points,
+    }), false);
+}

package/dist/geometry/patterns/placements.js

@@ -1,7 +1,9 @@
 import { GeometryError } from "../errors.js";
+import { vector3Data } from "../math/vector-value.js";
 import { cross3, dot3, scale3 } from "../math/vector3.js";
+import { path2InputData, path3InputData, } from "../paths/path-value.js";
 import { distributeAlongPath } from "../paths/planar.js";
-import { normalizeSweepPath } from "../sweeps/validation.js";
+import { restrictTransform3 } from "../transform2.js";
 import { composeTransform3, frameTransform3, IDENTITY_TRANSFORM3, rotationTransform3, translationTransform3, } from "../transform3.js";
 const fail = (operation, message) => {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation });
@@ -23,13 +25,35 @@ const finite = (value, operation) => {
         });
     return value;
 };
-const vector = (value, operation) => {
-    if (!Array.isArray(value) || value.length !== 3 || !Array.from(value).every(Number.isFinite))
-        fail(operation, "Pattern vectors require three finite coordinates.");
-    return value;
+const coordinates = (input, operation) => {
+    const value = typeof input === "object" &&
+        input !== null &&
+        "toData" in input &&
+        typeof input.toData === "function"
+        ? input.toData()
+        : input;
+    if (!Array.isArray(value) || (value.length !== 2 && value.length !== 3))
+        fail(operation, "Pattern vectors require exact XY or XYZ coordinates.");
+    const source = value;
+    const copied = source.length === 2 ? [source[0], source[1]] : [source[0], source[1], source[2]];
+    if (copied.some((coordinate) => typeof coordinate !== "number"))
+        fail(operation, "Pattern vectors require numeric coordinates.");
+    copied.forEach((coordinate) => finite(coordinate, operation));
+    return copied;
+};
+const vector = (input, operation) => {
+    const value = coordinates(input, operation);
+    if (value.length !== 3)
+        fail(operation, "Spatial pattern vectors require XYZ coordinates.");
+    return vector3Data(value);
 };
-const direction = (value, operation) => {
-    vector(value, operation);
+const lift = (value) => [value[0], value[1], value[2] ?? 0];
+const requireDimension = (actual, expected, operation) => {
+    if (actual !== expected)
+        fail(operation, "Pattern coordinates must match the shape dimension.");
+};
+const direction = (input, operation) => {
+    const value = vector(input, operation);
     const maximum = Math.max(...value.map(Math.abs));
     if (maximum === 0)
         fail(operation, "Pattern direction must be nonzero.");
@@ -77,27 +101,46 @@ export function linearPatternPlan(options) {
             fail(operation, "Length must be a nonnegative whole multiple of the signed spacing.");
         count = patternCount(Math.round(intervals) + 1, operation);
     }
-    const axis = direction(options.direction ?? [1, 0, 0], operation);
+    const input = options.direction === undefined ? undefined : coordinates(options.direction, operation);
+    const axis = direction(input === undefined ? [1, 0, 0] : lift(input), operation);
     finite(spacing * (count - 1), operation);
-    return { count, transformAt: (index) => translationTransform3(scale3(axis, spacing * index)) };
+    return {
+        count,
+        transformAt: (index, dimension = 3) => {
+            if (input !== undefined)
+                requireDimension(input.length, dimension, operation);
+            return translationTransform3(scale3(axis, spacing * index));
+        },
+    };
 }
 export function radialPatternPlan(options) {
     const operation = "radialPattern";
     optionsObject(options, operation);
     const count = patternCount(options.count, operation);
-    const axis = direction(options.axis, operation);
-    const angle = finite((options.angleDegrees / 180) * Math.PI, operation);
-    if (angle === 0)
-        fail(operation, "Pattern angleDegrees must be nonzero.");
-    finite(angle * (count - 1), operation);
-    const center = vector(options.center ?? [0, 0, 0], operation);
-    const before = translationTransform3(scale3(center, -1));
-    const after = translationTransform3(center);
+    if ("center" in options)
+        fail(operation, "Use pivot for a radial pattern's rotation reference.");
+    const hasAxis = options.axis !== undefined;
+    const axis = direction(options.axis ?? [0, 0, 1], operation);
+    const angleRadians = finite((options.angle / 180) * Math.PI, operation);
+    if (angleRadians === 0)
+        fail(operation, "Pattern angle must be nonzero.");
+    finite(angleRadians * (count - 1), operation);
+    const pivot = options.pivot === undefined ? undefined : coordinates(options.pivot, operation);
+    const before = translationTransform3(scale3(pivot === undefined ? [0, 0, 0] : lift(pivot), -1));
+    const after = translationTransform3(pivot === undefined ? [0, 0, 0] : lift(pivot));
     return {
         count,
-        transformAt: (index) => index === 0
-            ? IDENTITY_TRANSFORM3
-            : composeTransform3(after, composeTransform3(rotationTransform3(axis, { radians: angle * index }), before)),
+        transformAt: (index, dimension = 3) => {
+            if (dimension === 2 && hasAxis)
+                fail(operation, "XY radial patterns use the implicit +Z axis.");
+            if (dimension === 3 && !hasAxis)
+                fail(operation, "Spatial radial patterns require an explicit axis.");
+            if (pivot !== undefined)
+                requireDimension(pivot.length, dimension, operation);
+            return index === 0
+                ? IDENTITY_TRANSFORM3
+                : composeTransform3(after, composeTransform3(rotationTransform3(axis, { radians: angleRadians * index }), before));
+        },
     };
 }
 export function gridPatternPlan(options) {
@@ -111,6 +154,7 @@ export function gridPatternPlan(options) {
         fail(operation, "Grid count and spacing require matching XY or XYZ tuples.");
     if (options.center !== undefined && typeof options.center !== "boolean")
         fail(operation, "Grid center must be a boolean.");
+    const centered = options.center === true;
     const counts = [options.count[0], options.count[1], dimensions === 3 ? options.count[2] : 1];
     counts.forEach((count) => patternCount(count, operation));
     const count = patternCount(counts[0] * counts[1] * counts[2], operation);
@@ -138,13 +182,17 @@ export function gridPatternPlan(options) {
     const frame = options.frame === undefined ? IDENTITY_TRANSFORM3 : frameTransform3(options.frame);
     return {
         count,
-        transformAt: (index) => {
+        transformAt: (index, dimension = 3) => {
+            if (dimension === 2) {
+                requireDimension(dimensions, dimension, operation);
+                restrictTransform3(frame);
+            }
             const coordinates = [
                 index % counts[0],
                 Math.floor(index / counts[0]) % counts[1],
                 Math.floor(index / (counts[0] * counts[1])),
             ];
-            const offset = coordinates.map((value, axis) => value * spacing[axis] - (options.center === true ? extent[axis] / 2 : 0));
+            const offset = coordinates.map((value, axis) => value * spacing[axis] - (centered ? extent[axis] / 2 : 0));
             return composeTransform3(frame, translationTransform3(offset));
         },
     };
@@ -164,18 +212,43 @@ export function pathPatternPlan(input, options, limits) {
         options.orientation !== "fixed" &&
         options.orientation !== "tangent")
         fail(operation, "Path orientation must be fixed or tangent.");
-    const path = normalizeSweepPath(input, options.closed ?? false, operation, limits);
+    const tangentOrientation = options.orientation === "tangent";
+    if (typeof input !== "object" || input === null)
+        fail(operation, "Path patterns require sampled XY or XYZ coordinates.");
+    const first = Array.isArray(input) ? input[0] : undefined;
+    const suppliedDimension = Array.isArray(input)
+        ? Array.isArray(first)
+            ? first.length
+            : typeof first === "object" && first !== null && "z" in first
+                ? 3
+                : 2
+        : Reflect.get(input, "dimension");
+    if (suppliedDimension !== 2 && suppliedDimension !== 3)
+        fail(operation, "Path patterns require sampled XY or XYZ coordinates.");
+    const dimension = suppliedDimension === 2 ? 2 : 3;
+    const data = dimension === 2
+        ? path2InputData(input, options.closed, limits)
+        : path3InputData(input, options.closed, limits);
+    const path = dimension === 2 ? data.points.map(lift) : data.points;
+    // Distribution permits reversals, zero-length edges, and open paths returning to their start.
+    // Validate the traversal before factories without allocating the complete placement collection.
+    const firstPlacement = distributeAlongPath(path, 1, data.closed, limits);
     // Defer the output placement array until the operation has checked the source copy budget.
-    let placements;
+    let placements = count === 1 ? firstPlacement : undefined;
     return {
         count,
-        transformAt: (index) => {
-            placements ??= distributeAlongPath(path, count, options.closed ?? false, limits);
+        transformAt: (index, shapeDimension = 3) => {
+            requireDimension(dimension, shapeDimension, operation);
+            placements ??= distributeAlongPath(path, count, data.closed, limits);
             const placement = placements[index];
             const translation = translationTransform3(placement.position);
-            if (options.orientation !== "tangent")
+            if (!tangentOrientation)
                 return translation;
             const tangent = placement.tangent;
+            if (dimension === 2)
+                return composeTransform3(translation, rotationTransform3([0, 0, 1], {
+                    radians: Math.atan2(tangent[1], tangent[0]),
+                }));
             const cosine = Math.max(-1, Math.min(1, dot3([0, 0, 1], tangent)));
             const axis = cross3([0, 0, 1], tangent);
             const sine = Math.hypot(...axis);

package/dist/geometry/patterns.js

@@ -3,7 +3,7 @@ import { resolveGeometrySamplingLimits } from "./sampling-limits.js";
 function transforms(plan) {
     return Object.freeze(Array.from({ length: plan.count }, (_, index) => Object.freeze(plan.transformAt(index))));
 }
-/** Equal linear placements in millimetres, including the original at the origin. */
+/** Spatial XYZ matrix placements in millimetres, including the original at the origin. */
 export function linearPatternTransforms(options) {
     return transforms(linearPatternPlan(options));
 }
@@ -11,12 +11,14 @@ export function linearPatternTransforms(options) {
 export function radialPatternTransforms(options) {
     return transforms(radialPatternPlan(options));
 }
-/** XY or XYZ grid placements in millimetres, in X-fastest order. */
+/** Spatial XYZ matrices for an XY or XYZ grid, in X-fastest order. */
 export function gridPatternTransforms(options) {
     return transforms(gridPatternPlan(options));
 }
 /**
- * Equal physical arc-length placements along a sampled XYZ path. Tangent orientation maps +Z
+ * Equal physical arc-length placements along a sampled XYZ path.
+ *
+ * Tangent orientation maps +Z
  * onto the local path tangent; fixed orientation only translates. Closed paths omit a repeated seam.
  * Explicit sampling ceilings bound both input points and output placements.
  */