@metamesh/modeling 0.0.0-stage → 0.7.0

package/dist/geometry/mesh.js

@@ -0,0 +1,283 @@
+import { GeometryError } from "./errors.js";
+import { IndexedMeshEdgeTable } from "./mesh-edge-table.js";
+import { writeMeshVertex } from "./numeric.js";
+import { resolveGeometryTolerance } from "./tolerance.js";
+import { transformDeterminant3, validateTransform3 } from "./transform3.js";
+function inspectTriangleMesh(mesh, options = {}, mode = "validate", topology = false) {
+    const measurements = mode === "measure";
+    if (!(mesh.positions instanceof Float32Array) || !(mesh.indices instanceof Uint32Array)) {
+        throw new GeometryError("INVALID_MESH", "Triangle meshes require Float32Array positions and Uint32Array indices.");
+    }
+    if (mesh.positions.length % 3 !== 0) {
+        throw new GeometryError("INVALID_MESH", "Mesh positions must contain complete XYZ vertices.");
+    }
+    if (mesh.indices.length % 3 !== 0) {
+        throw new GeometryError("INVALID_MESH", "Mesh indices must contain complete triangles.");
+    }
+    const vertexCount = mesh.positions.length / 3;
+    if ((vertexCount === 0 || mesh.indices.length === 0) &&
+        !(options.allowEmpty && vertexCount === 0 && mesh.indices.length === 0)) {
+        throw new GeometryError("INVALID_MESH", "A triangle mesh must contain vertices and faces.");
+    }
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    for (let offset = 0; offset < mesh.positions.length; offset += 3) {
+        for (let axis = 0; axis < 3; axis += 1) {
+            const coordinate = mesh.positions[offset + axis];
+            if (!Number.isFinite(coordinate)) {
+                throw new GeometryError("NON_FINITE_VALUE", `Mesh position ${offset + axis} must be finite.`);
+            }
+            min[axis] = Math.min(min[axis], coordinate);
+            max[axis] = Math.max(max[axis], coordinate);
+        }
+    }
+    const extent = vertexCount === 0 ? 0 : Math.max(max[0] - min[0], max[1] - min[1], max[2] - min[2]);
+    const minimumDoubleArea = resolveGeometryTolerance(extent, options.tolerance).area;
+    const edges = options.requireClosed || topology
+        ? new IndexedMeshEdgeTable(mesh.indices.length, topology)
+        : null;
+    const triangleCount = mesh.indices.length / 3;
+    const parents = topology ? new Int32Array(triangleCount) : null;
+    const ranks = topology ? new Uint8Array(triangleCount) : null;
+    const referenced = topology ? new Uint8Array(vertexCount) : null;
+    let connectedComponentCount = 0;
+    const root = (triangle) => {
+        let current = triangle;
+        while (parents[current] !== current)
+            current = parents[current];
+        while (parents[triangle] !== triangle) {
+            const next = parents[triangle];
+            parents[triangle] = current;
+            triangle = next;
+        }
+        return current;
+    };
+    const connect = (a, b) => {
+        let left = root(a), right = root(b);
+        if (left === right)
+            return;
+        if (ranks[left] < ranks[right])
+            [left, right] = [right, left];
+        parents[right] = left;
+        if (ranks[left] === ranks[right])
+            ranks[left] = ranks[left] + 1;
+        connectedComponentCount -= 1;
+    };
+    let edgeCount = 0;
+    const addEdge = (a, b, triangle) => {
+        const firstTriangle = edges.touch(a, b, triangle);
+        if (firstTriangle === -1)
+            edgeCount += 1;
+        else if (topology)
+            connect(firstTriangle, triangle);
+    };
+    // Keep the two hot-loop accumulators independent and local: no mutable numeric objects escape.
+    let surfaceArea = 0, areaCorrection = 0, signedVolume = 0, volumeCorrection = 0;
+    const originX = mesh.positions[0] ?? 0, originY = mesh.positions[1] ?? 0, originZ = mesh.positions[2] ?? 0;
+    for (let offset = 0; offset < mesh.indices.length; offset += 3) {
+        const a = mesh.indices[offset], b = mesh.indices[offset + 1], c = mesh.indices[offset + 2];
+        if (a >= vertexCount || b >= vertexCount || c >= vertexCount) {
+            throw new GeometryError("INVALID_MESH", `Triangle ${offset / 3} references a missing vertex.`);
+        }
+        if (a === b || b === c || c === a) {
+            throw new GeometryError("DEGENERATE_GEOMETRY", `Triangle ${offset / 3} repeats a vertex.`);
+        }
+        const ax = mesh.positions[a * 3], ay = mesh.positions[a * 3 + 1], az = mesh.positions[a * 3 + 2];
+        const abx = mesh.positions[b * 3] - ax, aby = mesh.positions[b * 3 + 1] - ay, abz = mesh.positions[b * 3 + 2] - az;
+        const acx = mesh.positions[c * 3] - ax, acy = mesh.positions[c * 3 + 1] - ay, acz = mesh.positions[c * 3 + 2] - az;
+        const crossX = aby * acz - abz * acy, crossY = abz * acx - abx * acz, crossZ = abx * acy - aby * acx;
+        const doubleArea = Math.hypot(crossX, crossY, crossZ);
+        if (doubleArea <= minimumDoubleArea) {
+            throw new GeometryError("DEGENERATE_GEOMETRY", `Triangle ${offset / 3} has zero area.`);
+        }
+        if (measurements) {
+            const area = doubleArea / 2;
+            const nextArea = surfaceArea + area;
+            areaCorrection +=
+                Math.abs(surfaceArea) >= Math.abs(area)
+                    ? surfaceArea - nextArea + area
+                    : area - nextArea + surfaceArea;
+            surfaceArea = nextArea;
+            const volume = ((ax - originX) * crossX + (ay - originY) * crossY + (az - originZ) * crossZ) / 6;
+            const nextVolume = signedVolume + volume;
+            volumeCorrection +=
+                Math.abs(signedVolume) >= Math.abs(volume)
+                    ? signedVolume - nextVolume + volume
+                    : volume - nextVolume + signedVolume;
+            signedVolume = nextVolume;
+        }
+        if (parents !== null) {
+            const triangle = offset / 3;
+            parents[triangle] = triangle;
+            referenced[a] = referenced[b] = referenced[c] = 1;
+            connectedComponentCount += 1;
+        }
+        if (edges !== null) {
+            addEdge(a, b, offset / 3);
+            addEdge(b, c, offset / 3);
+            addEdge(c, a, offset / 3);
+        }
+    }
+    if (options.requireClosed && edges !== null && !edges.isClosed())
+        throw new GeometryError("INVALID_MESH", "Closed meshes require exactly two oppositely wound faces at every edge.");
+    if (referenced !== null) {
+        for (let vertex = 0; vertex < vertexCount; vertex += 1) {
+            if (referenced[vertex] === 0) {
+                throw new GeometryError("INVALID_MESH", "Mesh signatures require every position-buffer vertex to be referenced by a triangle.");
+            }
+        }
+    }
+    // Validation-only calls produce no unused zero-valued metric record. Completed measurements
+    // are immutable snapshots with independent storage, including their nested bounds tuples.
+    if (mode === "validate")
+        return;
+    const bounds = Object.freeze({ min: Object.freeze(min), max: Object.freeze(max) });
+    if (mode === "bounds")
+        return bounds;
+    return Object.freeze({
+        bounds,
+        signedVolume: signedVolume + volumeCorrection,
+        surfaceArea: surfaceArea + areaCorrection,
+        triangleCount,
+        vertexCount,
+        ...(topology ? { connectedComponentCount, edgeCount } : {}),
+    });
+}
+/**
+ * Validates and measures a mesh in one position and one triangle traversal.
+ *
+ * Bounds, area in square model units and signed volume in cubic model units are computed without
+ * copying or changing the input buffers. Volume is meaningful for consistently wound closed
+ * geometry; `requireClosed` checks oriented edge closure. Optional indexed topology counts require
+ * every position vertex to be referenced and do not establish freedom from self-intersections.
+ * Results and nested bounds are immutable snapshots. Caller-owned mutable meshes are freshly
+ * inspected on every call, never cached.
+ */
+export function analyzeTriangleMesh(mesh, options = {}) {
+    return inspectTriangleMesh(mesh, options, "measure", options.includeTopology ?? false);
+}
+/**
+ * Validates mesh buffers, indices, triangle area, and optionally closed topology.
+ *
+ * Closed validation requires each edge to occur exactly twice with opposite
+ * directions, rejecting boundary and non-manifold edges. Validation does not
+ * mutate or copy the mesh. This establishes edge connectivity, not the absence
+ * of geometric self-intersections between faces.
+ *
+ * @param mesh - Mesh to inspect.
+ * @param options - Empty-mesh, topology, and tolerance policy.
+ * @returns The original mesh after successful validation.
+ * @throws {@link GeometryError} When any requested invariant fails.
+ */
+export function validateTriangleMesh(mesh, options = {}) {
+    inspectTriangleMesh(mesh, options);
+    return mesh;
+}
+/**
+ * Computes axis-aligned bounds for a non-empty mesh.
+ *
+ * @param mesh - Mesh whose finite complete vertices will be measured.
+ * @returns Fresh immutable minimum and maximum XYZ tuples.
+ * @throws {@link GeometryError} When the mesh is structurally invalid.
+ */
+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.
+ *
+ * Inputs are validated and never mutated. Face order and winding remain stable.
+ *
+ * @param meshes - One or more meshes to concatenate.
+ * @returns Fresh typed arrays with indices offset to their source vertex ranges.
+ * @throws {@link GeometryError} When no mesh is supplied or an input is invalid.
+ */
+export function joinTriangleMeshes(meshes) {
+    if (meshes.length === 0) {
+        throw new GeometryError("INVALID_ARGUMENT", "Joining meshes requires at least one mesh.");
+    }
+    meshes.forEach((mesh) => validateTriangleMesh(mesh));
+    const positionLength = meshes.reduce((sum, mesh) => sum + mesh.positions.length, 0);
+    const indexLength = meshes.reduce((sum, mesh) => sum + mesh.indices.length, 0);
+    if (positionLength / 3 > 0xffff_ffff) {
+        throw new GeometryError("INVALID_MESH", "Joined mesh exceeds the Uint32 vertex index range.");
+    }
+    const positions = new Float32Array(positionLength);
+    const indices = new Uint32Array(indexLength);
+    let positionOffset = 0;
+    let indexOffset = 0;
+    let vertexOffset = 0;
+    for (const mesh of meshes) {
+        positions.set(mesh.positions, positionOffset);
+        for (let index = 0; index < mesh.indices.length; index += 1) {
+            indices[indexOffset + index] = mesh.indices[index] + vertexOffset;
+        }
+        positionOffset += mesh.positions.length;
+        indexOffset += mesh.indices.length;
+        vertexOffset += mesh.positions.length / 3;
+    }
+    return { indices, positions };
+}
+/**
+ * Returns a copy of a mesh with every triangle winding reversed.
+ *
+ * @param mesh - Mesh to copy and reverse.
+ * @returns Fresh position and index buffers; the input remains unchanged.
+ */
+export function reverseTriangleMesh(mesh) {
+    validateTriangleMesh(mesh);
+    const indices = new Uint32Array(mesh.indices);
+    for (let offset = 0; offset < indices.length; offset += 3) {
+        const second = indices[offset + 1];
+        indices[offset + 1] = indices[offset + 2];
+        indices[offset + 2] = second;
+    }
+    return { indices, positions: new Float32Array(mesh.positions) };
+}
+/**
+ * Applies an affine transform to a mesh and preserves outward face orientation.
+ *
+ * A transform with a negative linear determinant reflects space, so this helper
+ * automatically reverses every triangle. Singular transforms are rejected.
+ *
+ * @param mesh - Mesh to transform without mutation.
+ * @param transform - Row-major affine transform.
+ * @returns A mesh with fresh transformed positions and copied or reversed indices.
+ */
+export function transformTriangleMesh(mesh, transform) {
+    validateTriangleMesh(mesh);
+    validateTransform3(transform);
+    const positions = new Float32Array(mesh.positions.length);
+    for (let offset = 0; offset < mesh.positions.length; offset += 3) {
+        const x = mesh.positions[offset];
+        const y = mesh.positions[offset + 1];
+        const z = mesh.positions[offset + 2];
+        writeMeshVertex(positions, offset, [
+            transform[0] * x + transform[1] * y + transform[2] * z + transform[3],
+            transform[4] * x + transform[5] * y + transform[6] * z + transform[7],
+            transform[8] * x + transform[9] * y + transform[10] * z + transform[11],
+        ], "transformTriangleMesh");
+    }
+    const indices = new Uint32Array(mesh.indices);
+    if (transformDeterminant3(transform) < 0) {
+        for (let offset = 0; offset < indices.length; offset += 3) {
+            const second = indices[offset + 1];
+            indices[offset + 1] = indices[offset + 2];
+            indices[offset + 2] = second;
+        }
+    }
+    return validateTriangleMesh({ indices, positions });
+}

package/dist/geometry/model-limits.js

@@ -0,0 +1,50 @@
+import { GeometryError } from "./errors.js";
+import { defaultGeometrySamplingLimits } from "./sampling-limits.js";
+/** Default engine ceilings, shared with predictable pure mesh constructor preflights. */
+export const defaultModelingLimits = Object.freeze({
+    ...defaultGeometrySamplingLimits,
+    maxParts: 64,
+    maxVertices: 1_000_000,
+    maxTriangles: 2_000_000,
+    maxBytes: 96 * 1024 * 1024,
+});
+/** @internal Resolves trusted pure/engine policy; a host ceiling restricts local overrides. */
+export function resolveModelingLimits(overrides = {}, ceilings) {
+    if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides))
+        throw new GeometryError("INVALID_ARGUMENT", "Modeling limits must be an object.", {
+            operation: "modelingLimits",
+        });
+    const result = { ...(ceilings ?? defaultModelingLimits), ...overrides };
+    for (const key of Object.keys(defaultModelingLimits)) {
+        if (!Number.isSafeInteger(result[key]) ||
+            result[key] < (key === "maxCircularSegments" ? 3 : 1) ||
+            (ceilings !== undefined && result[key] > ceilings[key]))
+            throw new GeometryError("INVALID_ARGUMENT", `${key} must be a positive safe integer${key === "maxCircularSegments" ? " of at least three" : ""}${ceilings === undefined ? "" : " no larger than the configured engine ceiling"}.`, { operation: "modelingLimits" });
+    }
+    return Object.freeze(result);
+}
+/** @internal Checks predictable typed mesh storage before constructing it. */
+export function assertMeshAllocationWithinLimits(vertices, triangles, bytes, operation, limits) {
+    if (!Number.isSafeInteger(vertices) ||
+        !Number.isSafeInteger(triangles) ||
+        !Number.isSafeInteger(bytes) ||
+        vertices < 0 ||
+        triangles < 0 ||
+        bytes < 0 ||
+        vertices * 3 > 0xffff_ffff ||
+        triangles * 3 > 0xffff_ffff ||
+        vertices > limits.maxVertices ||
+        triangles > limits.maxTriangles ||
+        bytes > limits.maxBytes)
+        throw new GeometryError("COMPLEXITY_LIMIT", `Mesh allocation requires ${vertices} vertices, ${triangles} triangles and ${bytes} bytes; the host execution limits permit ${limits.maxVertices} vertices, ${limits.maxTriangles} triangles and ${limits.maxBytes} bytes, within typed-array capacity.`, {
+            operation,
+            details: {
+                requiredVertices: vertices,
+                allowedVertices: limits.maxVertices,
+                requiredTriangles: triangles,
+                allowedTriangles: limits.maxTriangles,
+                requiredBytes: bytes,
+                allowedBytes: limits.maxBytes,
+            },
+        });
+}

package/dist/geometry/numeric.js

@@ -0,0 +1,11 @@
+import { GeometryError } from "./errors.js";
+/** @internal Writes one finite, representable manufacturing vertex before checking mesh topology. */
+export function writeMeshVertex(positions, offset, point, operation) {
+    for (let axis = 0; axis < 3; axis += 1) {
+        const coordinate = Math.fround(point[axis]);
+        if (!Number.isFinite(coordinate)) {
+            throw new GeometryError("NON_FINITE_VALUE", "Mesh coordinates exceed finite Float32 storage.", { operation, details: { axis, coordinate: point[axis] } });
+        }
+        positions[offset + axis] = coordinate;
+    }
+}

package/dist/geometry/paths/frames.js

@@ -0,0 +1,118 @@
+import { cross3, dot3, length3, normalize3, projectOntoPlane3, rotateAroundAxis3, scale3, subtract3, } from "../math/vector3.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+const tangentAt = (path, index) => {
+    if (index === 0) {
+        return normalize3(subtract3(path[1], path[0]));
+    }
+    if (index === path.length - 1) {
+        return normalize3(subtract3(path[index], path[index - 1]));
+    }
+    return normalize3(subtract3(path[index + 1], path[index - 1]));
+};
+const chooseInitialNormal = (tangent, preferred) => {
+    const candidates = preferred
+        ? [preferred, [1, 0, 0], [0, 1, 0], [0, 0, 1]]
+        : [
+            [1, 0, 0],
+            [0, 1, 0],
+            [0, 0, 1],
+        ];
+    for (const candidate of candidates) {
+        const projected = projectOntoPlane3(candidate, tangent);
+        if (length3(projected) > 1e-8) {
+            return normalize3(projected);
+        }
+    }
+    throw new Error("Unable to choose an initial path normal.");
+};
+const transportNormal = (normal, previousTangent, tangent) => {
+    const rotationAxis = cross3(previousTangent, tangent);
+    const sine = length3(rotationAxis);
+    let transported = normal;
+    if (sine > 1e-10) {
+        const axis = scale3(rotationAxis, 1 / sine);
+        const cosine = Math.max(-1, Math.min(1, dot3(previousTangent, tangent)));
+        transported = rotateAroundAxis3(normal, axis, Math.atan2(sine, cosine));
+    }
+    return normalize3(projectOntoPlane3(transported, 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.
+ */
+export const computeParallelTransportFrames = (path, initialNormal, normalGuide, limits = {}) => {
+    if (path.length < 2) {
+        throw new Error("A framed path needs at least two points.");
+    }
+    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 frames = [
+        {
+            tangent: firstTangent,
+            normal,
+            binormal: normalize3(cross3(firstTangent, normal)),
+        },
+    ];
+    for (let index = 1; index < tangents.length; index += 1) {
+        const previousTangent = tangents[index - 1];
+        const tangent = tangents[index];
+        const guide = normalGuide?.(path[index], index);
+        if (guide === undefined) {
+            normal = transportNormal(normal, previousTangent, tangent);
+        }
+        else {
+            const guided = normalize3(projectOntoPlane3(guide, 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;
+        }
+        // Reprojection removes accumulated floating-point drift.
+        normal = normalize3(projectOntoPlane3(normal, tangent));
+        frames.push({
+            tangent,
+            normal,
+            binormal: normalize3(cross3(tangent, normal)),
+        });
+    }
+    return frames;
+};
+const closedTangentAt = (path, index) => {
+    const previous = path[(index - 1 + path.length) % path.length];
+    const next = path[(index + 1) % path.length];
+    return normalize3(subtract3(next, previous));
+};
+const signedAngleAround = (from, to, axis) => Math.atan2(dot3(axis, cross3(from, to)), Math.max(-1, Math.min(1, dot3(from, to))));
+/**
+ * Builds rotation-minimizing frames for a non-duplicated closed path.
+ *
+ * Centered cyclic tangents are parallel-transported around the loop. The seam
+ * holonomy is measured by transporting the last normal back to the first
+ * tangent, then its residual rotation is distributed uniformly over all path
+ * intervals. This avoids a single visible seam or an accumulated frame flip.
+ * The maxPathPoints ceiling (default100000) bounds path points and frames.
+ */
+export const computeClosedParallelTransportFrames = (path, initialNormal, limits = {}) => {
+    if (path.length < 3) {
+        throw new Error("A closed framed path needs at least three points.");
+    }
+    assertSamplingCount(path.length, "computeClosedParallelTransportFrames", resolveGeometrySamplingLimits(limits).maxPathPoints);
+    const tangents = path.map((_, index) => closedTangentAt(path, index));
+    const transportedNormals = [chooseInitialNormal(tangents[0], initialNormal)];
+    for (let index = 1; index < tangents.length; index += 1) {
+        transportedNormals.push(transportNormal(transportedNormals[index - 1], tangents[index - 1], tangents[index]));
+    }
+    const seamNormal = transportNormal(transportedNormals.at(-1), tangents.at(-1), tangents[0]);
+    const seamCorrection = signedAngleAround(seamNormal, transportedNormals[0], tangents[0]);
+    return tangents.map((tangent, index) => {
+        const correction = (seamCorrection * index) / path.length;
+        const normal = normalize3(projectOntoPlane3(rotateAroundAxis3(transportedNormals[index], tangent, correction), tangent));
+        return {
+            tangent,
+            normal,
+            binormal: normalize3(cross3(tangent, normal)),
+        };
+    });
+};

package/dist/geometry/paths/helix.js

@@ -0,0 +1,49 @@
+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.
+ */
+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.");
+    }
+    if (!Number.isInteger(segments) || segments < 3) {
+        throw new Error("A helix needs at least three segments.");
+    }
+    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.");
+    }
+    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.");
+        }
+        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.");
+    }
+    let accumulatedWeight = 0;
+    const result = [];
+    for (let index = 0; index <= segments; index += 1) {
+        if (index > 0) {
+            accumulatedWeight += weights[index - 1];
+        }
+        const t = index / segments;
+        const angle = angleRange * t;
+        const point = [
+            radius * Math.cos(angle),
+            radius * Math.sin(angle),
+            height * (accumulatedWeight / totalWeight),
+        ];
+        if (!point.every(Number.isFinite)) {
+            throw new Error("Helix sampled coordinates must be finite.");
+        }
+        result.push(point);
+    }
+    return result;
+};

package/dist/geometry/paths/path.js

@@ -0,0 +1,32 @@
+import { length3, subtract3 } from "../math/vector3.js";
+import { assertSamplingCount, resolveGeometrySamplingLimits, } from "../sampling-limits.js";
+/** Returns cumulative arc length for finite points under maxPathPoints (default 100000); rejects overflowing length. */
+export const cumulativePathLengths = (path, limits = {}) => {
+    assertSamplingCount(path.length, "cumulativePathLengths", resolveGeometrySamplingLimits(limits).maxPathPoints);
+    if (path.length === 0) {
+        return [];
+    }
+    for (const point of path) {
+        if (!point.every(Number.isFinite)) {
+            throw new Error("Path coordinates must be finite.");
+        }
+    }
+    const cumulative = [0];
+    for (let index = 1; index < path.length; index += 1) {
+        const previous = path[index - 1];
+        const point = path[index];
+        if (previous === undefined || point === undefined) {
+            throw new Error("Path indexing invariant failed.");
+        }
+        const distance = cumulative[index - 1] + length3(subtract3(point, previous));
+        if (!Number.isFinite(distance)) {
+            throw new Error("Path cumulative length must be finite.");
+        }
+        cumulative.push(distance);
+    }
+    return cumulative;
+};
+/**
+ * Returns total sampled 3D path length, or zero for an empty path.
+ */
+export const pathLength = (path, limits = {}) => cumulativePathLengths(path, limits).at(-1) ?? 0;