@metamesh/modeling 0.18.0 → 0.20.0

package/dist/geometry/mesh-api.js

@@ -1,14 +1,16 @@
 /** 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 { extrudeMesh as extrude } from "./extrusion/mesh.js";
+export { loftMesh as loft } from "./loft/mesh.js";
+export { revolveMesh as revolve } from "./revolve/mesh.js";
+export { sweepMesh as sweep } from "./sweep/mesh.js";
+export { heightfieldMesh as heightfield, preflightHeightfield } from "./mesh/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 { transformTriangleMesh as transform, joinTriangleMeshes as join, reverseTriangleMesh as reverse, meshBounds as bounds, analyzeTriangleMesh as analyze, validateTriangleMesh as validate, } from "./mesh/operations.js";
+export { computeTriangleMeshCentroid as centroid } from "./mesh/centroid.js";
+export { analyzeTriangleMeshQuality as analyzeQuality } from "./mesh/quality.js";
+export { computeTriangleMeshSignature as signature } from "./mesh/signature.js";
+export { validateSolidMesh as validateSolid } from "./mesh/solid.js";
+export { renderMesh as render } from "./mesh/render-buffers.js";
+export { optimizePlanarPatches } from "./mesh/planar.js";
 export { immutableMesh as immutable } from "./immutable-buffer.js";

package/dist/geometry/paths/distribution.js

@@ -0,0 +1,43 @@
+import { GeometryError } from "../errors.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling/limits.js";
+import { createPathTraversal, locatePathDistance, writePathPoint, writePathTangent, } from "./traversal.js";
+import { path3InputData } from "./value.js";
+/**
+ * Places an exact item count at equal arc-length intervals along a sampled XYZ path.
+ *
+ * Open paths retain both endpoints when count exceeds one; closed paths omit the seam endpoint.
+ * Zero-length edges are skipped. Invalid counts, repeated closed seams, nonfinite lengths,
+ * zero-length paths, and exhausted budgets throw GeometryError.
+ *
+ * @param input - XYZ path or points in millimetres.
+ * @param count - Positive placement count; one selects the path start.
+ * @param closed - Raw-point closure, false by default; must match a path value.
+ * @param limits - Limits on input points and output placements.
+ */
+export function distributeAlongPath(input, count, closed, limits = {}) {
+    if (!Number.isSafeInteger(count) || count < 1)
+        throw new GeometryError("INVALID_ARGUMENT", "Path distribution count must be a positive integer.", { operation: "distributeAlongPath" });
+    assertSamplingCount(count, "distributeAlongPath", resolveGeometrySamplingLimits(limits).maxPathPoints);
+    const data = path3InputData(input, closed, limits);
+    const path = data.points;
+    if (path.length < (data.closed ? 3 : 2))
+        throw new GeometryError("INVALID_ARGUMENT", `${data.closed ? "Closed" : "Open"} distribution paths need more points.`, { operation: "distributeAlongPath" });
+    if (data.closed && path[0].every((coordinate, axis) => coordinate === path.at(-1)[axis]))
+        throw new GeometryError("INVALID_ARGUMENT", "Closed distribution paths omit their repeated seam point.", { operation: "distributeAlongPath" });
+    const traversal = createPathTraversal(path, data.closed);
+    if (traversal.length === 0)
+        throw new GeometryError("DEGENERATE_GEOMETRY", "Cannot distribute along a zero-length path.", {
+            operation: "distributeAlongPath",
+        });
+    const denominator = data.closed ? count : Math.max(1, count - 1);
+    let cursor = 0;
+    return Array.from({ length: count }, (_, index) => {
+        const location = locatePathDistance(traversal, traversal.length * (index / denominator), cursor);
+        cursor = location.edgeIndex;
+        const position = [0, 0, 0];
+        const tangent = [0, 0, 0];
+        writePathPoint(traversal, location, position);
+        writePathTangent(traversal, location, tangent);
+        return { position, tangent };
+    });
+}

package/dist/geometry/paths/editing.js

@@ -0,0 +1,76 @@
+import { GeometryError } from "../errors.js";
+import { assertSamplingCount } from "../sampling/limits.js";
+import { locatePathDistance, pathEdgeLength, validatePathDistance, writePathPoint, } from "./traversal.js";
+const invalid = (message) => {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation: "path" });
+};
+function pointAt(traversal, distance) {
+    const point = [];
+    writePathPoint(traversal, locatePathDistance(traversal, distance), point);
+    point.length = traversal.points[0].length;
+    return point;
+}
+/** Internal directed extraction; only cut endpoints are interpolated, and original interior vertices survive. */
+export function trimPathPoints(traversal, start, end, maximum) {
+    validatePathDistance(start, traversal.length);
+    validatePathDistance(end, traversal.length);
+    if (start >= end)
+        invalid("Trim distances must be strictly increasing.");
+    const first = start === 0 ? 1 : locatePathDistance(traversal, start).edgeIndex + 1;
+    let after = first;
+    if (end === traversal.length) {
+        // Preserve authored terminal corners even when a small edge was rounded out of the total.
+        after = traversal.points.length - (traversal.closed ? 0 : 1);
+    }
+    else {
+        while (after < traversal.points.length && traversal.cumulative[after] < end)
+            after++;
+    }
+    assertSamplingCount(2 + after - first, "path.trim", maximum);
+    const points = [pointAt(traversal, start)];
+    for (let vertex = first; vertex < after; vertex++)
+        points.push(traversal.points[vertex]);
+    points.push(pointAt(traversal, end));
+    return points;
+}
+/** Internal split of one directed traversal into two open paths, with one shared cut position. */
+export function splitPathPoints(traversal, distance, maximum) {
+    validatePathDistance(distance, traversal.length);
+    if (distance === 0 || distance === traversal.length)
+        invalid("Split distance must lie strictly inside the path.");
+    return [
+        trimPathPoints(traversal, 0, distance, maximum),
+        trimPathPoints(traversal, distance, traversal.length, maximum),
+    ];
+}
+/** Internal edge subdivision; exact original vertices and closure survive, including repeated adjacent vertices. */
+export function subdividePathPoints(traversal, maxSegmentLength, maximum) {
+    if (!Number.isFinite(maxSegmentLength) || maxSegmentLength <= 0)
+        invalid("maxSegmentLength must be finite and positive.");
+    const { points, closed } = traversal;
+    const count = closed ? points.length : Math.max(0, points.length - 1);
+    const divisions = [];
+    let required = closed ? 0 : Math.min(1, points.length);
+    for (let edge = 0; edge < count; edge++) {
+        const intervals = Math.max(1, Math.ceil(pathEdgeLength(points[edge], points[(edge + 1) % points.length]) / maxSegmentLength));
+        required += intervals;
+        assertSamplingCount(required, "path.subdivide", maximum);
+        divisions.push(intervals);
+    }
+    const result = points.length === 0 ? [] : [points[0]];
+    const scratch = [];
+    for (let edge = 0; edge < count; edge++) {
+        const intervals = divisions[edge];
+        for (let step = 1; step <= intervals; step++) {
+            if (closed && edge === count - 1 && step === intervals)
+                break;
+            if (step === intervals)
+                result.push(points[edge + 1]);
+            else {
+                writePathPoint(traversal, { edgeIndex: edge, fraction: step / intervals }, scratch);
+                result.push(scratch.slice(0, points[0].length));
+            }
+        }
+    }
+    return result;
+}

package/dist/geometry/paths/frames.js

@@ -1,7 +1,7 @@
 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 { path3InputData } from "./path-value.js";
+import { path3InputData } from "./value.js";
 const guideData = (input, operation) => {
     const coordinates = vector3Data(input);
     if (!coordinates.every(Number.isFinite))
@@ -52,9 +52,13 @@ 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.
+ * Nonfinite guides and unusable path tangents throw GeometryError. A finite initial guide
+ * parallel to the tangent selects a canonical fallback.
+ *
+ * @param input - Open XYZ path or points in millimetres; at least two points.
+ * @param initialNormal - Preferred starting X direction; the first normalGuide result wins.
+ * @param normalGuide - Profile X guide at each point; its sign follows the transported normal.
+ * @param limits - Point limits, checked before creating frames or calling guides.
  */
 export const computeParallelTransportFrames = (input, initialNormal, normalGuide, limits = {}) => {
     const { points: path } = path3InputData(input, false, limits);
@@ -77,15 +81,15 @@ export const computeParallelTransportFrames = (input, initialNormal, normalGuide
     for (let index = 1; index < tangents.length; index += 1) {
         const previousTangent = tangents[index - 1];
         const tangent = tangents[index];
+        const transported = transportNormal(normal, previousTangent, tangent);
         const guide = normalGuide?.(path[index], index);
         if (guide === undefined) {
-            normal = transportNormal(normal, previousTangent, tangent);
+            normal = transported;
         }
         else {
             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;
+            // Compare in the new tangent plane so a bend cannot reverse the profile's orientation.
+            normal = dot3(guided, transported) < 0 ? scale3(guided, -1) : guided;
         }
         // Reprojection removes accumulated floating-point drift.
         normal = normalize3(projectOntoPlane3(normal, tangent));
@@ -109,10 +113,11 @@ const signedAngleAround = (from, to, axis) => Math.atan2(dot3(axis, cross3(from,
  * Centered cyclic tangents are parallel-transported around the loop. Transporting the last
  * 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.
+ *
+ * @param input - Closed XYZ path or points in millimetres, with no repeated seam.
+ * @param initialNormal - Preferred profile X direction at the seam.
+ * @param limits - Limits on input points and output frames.
  */
 export const computeClosedParallelTransportFrames = (input, initialNormal, limits = {}) => {
     const { points: path } = path3InputData(input, true, limits);

package/dist/geometry/paths/helix.js

@@ -1,5 +1,5 @@
 import { GeometryError } from "../errors.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling/limits.js";
 /**
  * Creates `segments + 1` points including exact helix endpoints from finite positive dimensions.
  *

package/dist/geometry/paths/resampling.js

@@ -1,16 +1,13 @@
-import { curveFailure, normalizeCurveDirection, validateCurvePoint3, } from "../curves/evaluation.js";
+import { curveFailure, validateCurvePoint3 } from "../curves/evaluation.js";
 import { assertSampleVertexCount, createPlanarSampleWriter, createSpatialSampleWriter, resolveSamplingBudget, } from "../curves/sampling.js";
-import { resolveGeometryResolution } from "../resolution.js";
-import { assertSamplingCount, resolveGeometrySamplingLimits } from "../sampling-limits.js";
-const z = (point) => point[2] ?? 0;
-const distance = (a, b) => {
-    const value = Math.hypot(b[0] - a[0], b[1] - a[1], z(b) - z(a));
-    if (!Number.isFinite(value))
-        curveFailure("NON_FINITE_VALUE", "Curve extent exceeds finite arithmetic.");
-    return value;
-};
-function resamplePolyline(path, dimensions, options, createWriter, includeTangents = true) {
+import { assertSamplingCount, resolveGeometrySamplingLimits } from "../sampling/limits.js";
+import { resolveGeometryResolution } from "../sampling/resolution.js";
+import { createPathTraversal, locatePathDistance, pathEdgeLength, writePathPoint, writePathTangent, } from "./traversal.js";
+const isArray = (value) => Array.isArray(value);
+function resamplePolyline(path, dimensions, options, createWriter, output = {}) {
     const maximum = resolveSamplingBudget(options);
+    if (!isArray(path))
+        curveFailure("INVALID_ARGUMENT", "Polyline points must be an array.");
     if (options.closed !== undefined && typeof options.closed !== "boolean")
         curveFailure("INVALID_ARGUMENT", "closed must be a boolean.");
     const closed = options.closed ?? false;
@@ -19,42 +16,35 @@ function resamplePolyline(path, dimensions, options, createWriter, includeTangen
     assertSamplingCount(path.length, "sampleCurve", resolveGeometrySamplingLimits(options.limits).maxPathPoints, "Polyline input exceeds the configured path point ceiling.");
     if (options.segments !== undefined)
         assertSampleVertexCount(options.segments + (closed ? 0 : 1), maximum);
-    // Keep caller point references only within this synchronous operation. Unlike 2D promotion,
-    // normalization needs no extra 3D vector for every input point.
     const points = [];
-    const lengths = [];
-    let total = 0;
-    for (const input of path) {
-        if (input.length !== dimensions)
+    const count = path.length;
+    for (let index = 0; index < count; index++) {
+        const input = path[index];
+        if (!isArray(input) || input.length !== dimensions)
             curveFailure(dimensions === 2 ? "INVALID_ARGUMENT" : "NON_FINITE_VALUE", dimensions === 2
                 ? "Planar curve points must have two coordinates."
                 : "Curve coordinates must be finite three-dimensional points.");
-        if (!input.every(Number.isFinite))
+        const point = output.ownedInput
+            ? input
+            : dimensions === 2
+                ? [input[0], input[1]]
+                : [input[0], input[1], input[2]];
+        if (!output.ownedInput && !point.every(Number.isFinite))
             curveFailure("NON_FINITE_VALUE", "Curve coordinates must be finite three-dimensional points.");
         const previous = points.at(-1);
-        const length = previous === undefined ? 0 : distance(previous, input);
-        if (previous !== undefined && length === 0)
+        if (previous !== undefined && pathEdgeLength(previous, point) === 0)
             continue;
-        total += length;
-        if (!Number.isFinite(total))
-            curveFailure("NON_FINITE_VALUE", "Polyline length exceeds finite arithmetic.");
-        points.push(input);
-        lengths.push(total);
+        points.push(point);
     }
     if (closed) {
-        if (points.length > 1 && distance(points[0], points.at(-1)) === 0) {
+        if (points.length > 1 && pathEdgeLength(points[0], points.at(-1)) === 0) {
             points.pop();
-            lengths.pop();
-            total = lengths.at(-1) ?? 0;
         }
         if (points.length < 3)
             curveFailure("DEGENERATE_GEOMETRY", "A closed polyline needs at least three distinct consecutive points.");
-        total += distance(points.at(-1), points[0]);
-        if (!Number.isFinite(total))
-            curveFailure("NON_FINITE_VALUE", "Polyline length exceeds finite arithmetic.");
-        points.push(points[0]);
-        lengths.push(total);
     }
+    const traversal = createPathTraversal(points, closed);
+    const total = traversal.length;
     if (total === 0)
         curveFailure("DEGENERATE_GEOMETRY", "A zero-length polyline cannot be resampled.");
     const policy = options.segments === undefined
@@ -62,7 +52,7 @@ function resamplePolyline(path, dimensions, options, createWriter, includeTangen
         : undefined;
     const segments = options.segments ??
         (policy?.maxSegmentLength === undefined
-            ? points.length - 1
+            ? points.length - (closed ? 0 : 1)
             : Math.max(closed ? 3 : 1, Math.ceil(total / policy.maxSegmentLength)));
     if (closed && segments < 3)
         curveFailure("INVALID_ARGUMENT", "Closed polyline sampling needs at least three segments.");
@@ -70,39 +60,29 @@ function resamplePolyline(path, dimensions, options, createWriter, includeTangen
     assertSampleVertexCount(vertexCount, maximum);
     const writer = createWriter();
     const point = [0, 0, 0], tangent = [0, 0, 0];
-    let source = 1;
+    let source = 0;
     for (let i = 0; i < vertexCount; i++) {
         const at = total * (i / segments);
-        // At an exact source vertex choose its outgoing edge; the last open endpoint uses its incoming edge.
-        while (source < points.length - 1 && lengths[source] <= at)
-            source++;
-        const a = points[source - 1], b = points[source];
-        if (i === 0 || i === segments) {
-            const endpoint = i === 0 ? points[0] : points.at(-1);
-            point[0] = endpoint[0];
-            point[1] = endpoint[1];
-            point[2] = z(endpoint);
-        }
-        else {
-            const t = (at - lengths[source - 1]) / (lengths[source] - lengths[source - 1]);
-            // Preserve the original direct interpolation order used by existing mechanical paths.
-            point[0] = a[0] + (b[0] - a[0]) * t;
-            point[1] = a[1] + (b[1] - a[1]) * t;
-            point[2] = z(a) + (z(b) - z(a)) * t;
-        }
+        const location = locatePathDistance(traversal, at, source);
+        source = location.edgeIndex;
+        writePathPoint(traversal, location, point);
         validateCurvePoint3(point);
-        if (includeTangents) {
-            tangent[0] = b[0] - a[0];
-            tangent[1] = b[1] - a[1];
-            tangent[2] = z(b) - z(a);
-            normalizeCurveDirection(tangent, tangent);
-        }
+        if (closed &&
+            i === vertexCount - 1 &&
+            point.every((coordinate, axis) => coordinate === (points[0][axis] ?? 0)))
+            curveFailure("DEGENERATE_GEOMETRY", "Closed resampling must not repeat its seam point; select a different segment count.");
+        if (output.tangents !== false)
+            writePathTangent(traversal, location, tangent);
         writer.append(point, tangent);
     }
     return writer.finish();
 }
 /**
  * Resamples a spatial polyline at equal arc lengths with directed outgoing tangents.
+ *
+ * @param path - XYZ points in millimetres; duplicate neighbors are removed.
+ * @param options - Closure and exact intervals or physical edge spacing.
+ *
  * @remarks Open paths retain both endpoints; closed paths include the closing edge and omit the
  * repeated seam. Repeated adjacent inputs and explicit closing duplicates are removed. Physical
  * maxSegmentLength bounds arc-length intervals; exact counts override that policy. Output edges
@@ -115,7 +95,12 @@ function resamplePolyline(path, dimensions, options, createWriter, includeTangen
 export function resamplePolyline3(path, options = {}) {
     return resamplePolyline(path, 3, options, createSpatialSampleWriter);
 }
-/** Resamples a planar polyline with the same point, tangent, seam and budget guarantees as 3D.
+/**
+ * Resamples a planar polyline with the same point, tangent, seam and budget guarantees as 3D.
+ *
+ * @param path - XY points in millimetres; duplicate neighbors are removed.
+ * @param options - Closure and exact intervals or physical edge spacing.
+ *
  * @remarks Only final 2D output vectors are copied and frozen. No immutable 3D intermediate is built.
  * @example
  * ```ts
@@ -133,7 +118,7 @@ export function resamplePath2Points(path, options) {
             points.push([point[0], point[1]]);
         },
         finish: () => points,
-    }), false);
+    }), { tangents: false, ownedInput: true });
 }
 /** Internal points-only writer; avoids calculating and allocating tangents discarded by Path3. */
 export function resamplePath3Points(path, options) {
@@ -143,5 +128,5 @@ export function resamplePath3Points(path, options) {
             points.push([point[0], point[1], point[2]]);
         },
         finish: () => points,
-    }), false);
+    }), { tangents: false, ownedInput: true });
 }

package/dist/geometry/paths/{planar.js → rounding.js}

@@ -1,7 +1,7 @@
 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";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling/limits.js";
+import { path3InputData } from "./value.js";
 const invalidPath = (message, operation) => {
     throw new GeometryError("INVALID_ARGUMENT", message, { operation });
 };
@@ -12,69 +12,6 @@ const requireFinitePathValues = (values, operation) => {
         });
     }
 };
-const segmentLengths = (path, closed) => path.map((point, index) => {
-    if (!closed && index === path.length - 1)
-        return 0;
-    const next = path[(index + 1) % path.length];
-    const delta = subtract3(next, point);
-    return Math.hypot(delta[0], delta[1], delta[2]);
-});
-/**
- * Places an exact item count at equal arc-length intervals along a sampled path.
- *
- * Coordinates are unit-agnostic. Closed paths must omit their duplicated seam;
- * 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 = (input, count, closed, limits = {}) => {
-    if (!Number.isInteger(count) || count < 1) {
-        invalidPath("Path distribution count must be a positive integer.", "distributeAlongPath");
-    }
-    const maximum = resolveGeometrySamplingLimits(limits).maxPathPoints;
-    assertSamplingCount(count, "distributeAlongPath", maximum);
-    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 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) => {
-        const target = total * (itemIndex / denominator);
-        for (; segment < lengths.length; segment += 1) {
-            const length = lengths[segment];
-            if (length === 0)
-                continue;
-            if (target <= traversed + length || segment === lengths.length - 1) {
-                const start = path[segment];
-                const end = path[(segment + 1) % path.length];
-                const amount = Math.min(1, Math.max(0, (target - traversed) / length));
-                return {
-                    position: [
-                        start[0] + (end[0] - start[0]) * amount,
-                        start[1] + (end[1] - start[1]) * amount,
-                        start[2] + (end[2] - start[2]) * amount,
-                    ],
-                    tangent: normalize3(subtract3(end, start)),
-                };
-            }
-            traversed += length;
-        }
-        return invalidPath("Path distribution invariant failed.", "distributeAlongPath");
-    });
-};
 /**
  * Replaces each vertex of a non-duplicated closed polyline with a sampled
  * quadratic corner in the same coordinate system as the input.
@@ -82,8 +19,12 @@ export const distributeAlongPath = (input, count, closed, limits = {}) => {
  * `radius` is the desired tangent distance for a right angle and is capped to
  * 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.
+ * Invalid coordinates, topology, dimensions, or exhausted budgets throw GeometryError.
+ *
+ * @param input - Closed XYZ path or points in millimetres, without a repeated seam.
+ * @param radius - Positive right-angle tangent distance in millimetres.
+ * @param segmentsPerCorner - Quadratic intervals per corner; a positive integer.
+ * @param limits - Limits on input and rounded path points.
  */
 export const roundClosedPolylinePath = (input, radius, segmentsPerCorner, limits = {}) => {
     const maximum = resolveGeometrySamplingLimits(limits).maxPathPoints;

package/dist/geometry/paths/spline.js

@@ -0,0 +1,116 @@
+import { sampleCubicControlPoints } from "../curves/sampling.js";
+import { GeometryError } from "../errors.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling/limits.js";
+import { pathEdgeLength } from "./traversal.js";
+import { path2, path2InputData, path3, path3InputData, } from "./value.js";
+const fail = (message) => {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation: "spline" });
+};
+function optionsPolicy(options, input) {
+    if (typeof options !== "object" || options === null || Array.isArray(options))
+        fail("Spline options must be an object.");
+    if (options.closed !== undefined && typeof options.closed !== "boolean")
+        fail("Spline closed must be a boolean.");
+    if (options.segmentsPerSpan !== undefined &&
+        (!Number.isSafeInteger(options.segmentsPerSpan) || options.segmentsPerSpan < 1))
+        fail("segmentsPerSpan must be a positive safe integer.");
+    const maximum = resolveGeometrySamplingLimits(options.limits).maxPathPoints;
+    if (Array.isArray(input) && options.segmentsPerSpan !== undefined)
+        assertSamplingCount((input.length - (options.closed ? 0 : 1)) * options.segmentsPerSpan +
+            (options.closed ? 0 : 1), "spline", maximum);
+    return maximum;
+}
+/** Converts one centripetal Catmull–Rom span into equivalent cubic Bézier controls. */
+function controls(points, edge, closed) {
+    const count = points.length;
+    const start = points[edge], end = points[(edge + 1) % count];
+    const before = points[(edge - 1 + count) % count], after = points[(edge + 2) % count];
+    // Square-root chord lengths define the knots; one-sided secants avoid extrapolated endpoints.
+    const span = Math.sqrt(pathEdgeLength(start, end));
+    const previous = !closed && edge === 0 ? span : Math.sqrt(pathEdgeLength(before, start));
+    const next = !closed && edge === count - 2 ? span : Math.sqrt(pathEdgeLength(end, after));
+    const first = [], second = [];
+    for (let axis = 0; axis < 3; axis++) {
+        const a = start[axis] ?? 0, b = end[axis] ?? 0;
+        const delta = b - a;
+        const incoming = !closed && edge === 0 ? delta : a - (before[axis] ?? 0);
+        const outgoing = !closed && edge === count - 2 ? delta : (after[axis] ?? 0) - b;
+        // Unit-span derivatives become Bézier controls at one third of each endpoint tangent.
+        const firstTangent = (incoming / previous) * span * (span / (previous + span)) +
+            delta * (previous / (previous + span));
+        const secondTangent = delta * (next / (span + next)) + (outgoing / next) * span * (span / (span + next));
+        first.push(a + firstTangent / 3);
+        second.push(b - secondTangent / 3);
+    }
+    return [
+        [start[0], start[1], start[2] ?? 0],
+        first,
+        second,
+        [end[0], end[1], end[2] ?? 0],
+    ];
+}
+function splinePoints(points, closed, options, maximum) {
+    if (points.length < (closed ? 3 : 2))
+        fail("Open splines need two waypoints; closed splines need three.");
+    const spans = points.length - (closed ? 0 : 1);
+    // Every span needs an output edge, even before adaptive physical refinement.
+    assertSamplingCount(spans * (options.segmentsPerSpan ?? 1) + (closed ? 0 : 1), "spline", maximum);
+    for (let edge = 0; edge < spans; edge++)
+        if (pathEdgeLength(points[edge], points[(edge + 1) % points.length]) === 0)
+            fail("Spline waypoints must not contain adjacent duplicates or a repeated closed seam.");
+    const result = [points[0]];
+    for (let edge = 0; edge < spans; edge++) {
+        const omitSeam = closed && edge === spans - 1;
+        // Reserve one endpoint for each later span; the final closed endpoint is not retained.
+        const reserved = spans - edge - 1 - (closed ? 1 : 0);
+        const budget = maximum - result.length - reserved + 1;
+        sampleCubicControlPoints(controls(points, edge, closed), {
+            ...(options.segmentsPerSpan === undefined ? {} : { segments: options.segmentsPerSpan }),
+            ...(options.resolution === undefined ? {} : { resolution: options.resolution }),
+            limits: options.limits ?? {},
+            maxVertices: budget,
+        }, (sample, endpoint) => {
+            if (omitSeam && endpoint)
+                return;
+            result.push((points[0].length === 2
+                ? [sample[0], sample[1]]
+                : [sample[0], sample[1], sample[2]]));
+        });
+    }
+    return result;
+}
+/**
+ * Samples an immutable XY centripetal Catmull–Rom path through every waypoint in traversal order.
+ * Open endpoints use one-sided secants; closed paths are periodic and omit their repeated seam.
+ * Adjacent duplicate waypoints reject. The default physical policy bounds each cubic control hull;
+ * segmentsPerSpan instead selects exact uniform parameters per span. Sampling never coarsens to fit
+ * maxPathPoints. Invalid topology, nonfinite arithmetic, and exhausted budgets throw GeometryError.
+ *
+ * @param input - XY waypoints in millimetres; path values retain closure.
+ *
+ * @example
+ * ```ts
+ * const route = spline2([[0, 0], [10, 8], [25, 0]], { resolution: { maxChordError: 0.02 } });
+ * ```
+ */
+export function spline2(input, options = {}) {
+    const maximum = optionsPolicy(options, input);
+    const data = path2InputData(input, options.closed, options.limits);
+    return path2(splinePoints(data.points, data.closed, options, maximum), {
+        closed: data.closed,
+        limits: options.limits ?? {},
+    });
+}
+/**
+ * Samples an immutable XYZ centripetal Catmull–Rom path with the same interpolation, seam, sampling, and ceiling rules as spline2.
+ *
+ * @param input - XYZ waypoints in millimetres; path values retain closure.
+ */
+export function spline3(input, options = {}) {
+    const maximum = optionsPolicy(options, input);
+    const data = path3InputData(input, options.closed, options.limits);
+    return path3(splinePoints(data.points, data.closed, options, maximum), {
+        closed: data.closed,
+        limits: options.limits ?? {},
+    });
+}