@metamesh/modeling 0.19.0 → 0.20.0

package/dist/geometry/mesh/{mesh-quality.js → quality.js}

@@ -1,6 +1,7 @@
 import { GeometryError } from "../errors.js";
 import { immutableMeshView } from "../immutable-buffer.js";
 import { resolveGeometryTolerance, } from "../tolerance.js";
+import { triangleQuality } from "./triangle-quality.js";
 const DEFAULT_MAXIMUM_TRIANGLE_COUNT = 200_000;
 const FLOAT32_EPSILON = 2 ** -23;
 const MINIMUM_PLANAR_ANGULAR_TOLERANCE = 1e-5;
@@ -10,18 +11,9 @@ const pointAt = (positions, vertex) => [
     positions[vertex * 3 + 1],
     positions[vertex * 3 + 2],
 ];
-const subtract = (left, right) => [
-    left[0] - right[0],
-    left[1] - right[1],
-    left[2] - right[2],
-];
+// Keep these kernels local to isolate V8's array-type feedback from other modeling operations.
+// Shared helpers see more array representations, which can slow hot loops even when inlined.
 const dot = (left, right) => left[0] * right[0] + left[1] * right[1] + left[2] * right[2];
-const cross = (left, right) => [
-    left[1] * right[2] - left[2] * right[1],
-    left[2] * right[0] - left[0] * right[2],
-    left[0] * right[1] - left[1] * right[0],
-];
-const length = (vector) => Math.hypot(vector[0], vector[1], vector[2]);
 const maximumUint32 = (values) => {
     let maximum = 0;
     for (const value of values)
@@ -80,46 +72,22 @@ const meshBoundsAndExtent = (positions) => {
         extent: Math.max(maximum[0] - minimum[0], maximum[1] - minimum[1], maximum[2] - minimum[2]),
     };
 };
-const triangleAngles = (first, second, third) => {
-    const firstSecond = subtract(second, first);
-    const firstThird = subtract(third, first);
-    const secondThird = subtract(third, second);
-    const lengthFirstSecond = length(firstSecond);
-    const lengthFirstThird = length(firstThird);
-    const lengthSecondThird = length(secondThird);
-    if (lengthFirstSecond === 0 || lengthFirstThird === 0 || lengthSecondThird === 0) {
-        return [0, 0, 0];
-    }
-    const thirdFirst = subtract(first, third);
-    const secondFirst = [-firstSecond[0], -firstSecond[1], -firstSecond[2]];
-    const thirdSecond = [-secondThird[0], -secondThird[1], -secondThird[2]];
-    return [
-        Math.atan2(length(cross(firstSecond, firstThird)), dot(firstSecond, firstThird)),
-        Math.atan2(length(cross(secondThird, secondFirst)), dot(secondThird, secondFirst)),
-        Math.atan2(length(cross(thirdFirst, thirdSecond)), dot(thirdFirst, thirdSecond)),
-    ];
-};
 const faceAnalysis = (positions, vertices, index) => {
     const first = pointAt(positions, vertices[0]);
     const second = pointAt(positions, vertices[1]);
     const third = pointAt(positions, vertices[2]);
-    const firstSecond = subtract(second, first);
-    const firstThird = subtract(third, first);
-    const secondThird = subtract(third, second);
-    const product = cross(firstSecond, firstThird);
-    const doubleArea = length(product);
+    const quality = triangleQuality(first, second, third, "hypot");
+    const { doubleArea } = quality;
     const area = doubleArea / 2;
-    const longestEdge = Math.max(length(firstSecond), length(firstThird), length(secondThird));
     const normal = doubleArea === 0
         ? undefined
-        : [product[0] / doubleArea, product[1] / doubleArea, product[2] / doubleArea];
-    const angles = triangleAngles(first, second, third);
+        : [quality.crossX / doubleArea, quality.crossY / doubleArea, quality.crossZ / doubleArea];
     return {
         area,
-        aspectRatio: area === 0 ? Number.POSITIVE_INFINITY : (Math.sqrt(3) * longestEdge ** 2) / (4 * area),
+        aspectRatio: quality.aspectRatio,
         doubleArea,
         index,
-        minimumAngleRadians: Math.min(...angles),
+        minimumAngleRadians: Math.min(...quality.angles),
         normal,
         planeOffset: normal === undefined ? undefined : dot(normal, first),
         vertices,
@@ -234,7 +202,7 @@ const buildPatchAnalysis = (faces, edges, faceIndices, id) => {
         },
     };
 };
-/** @internal */
+/** @internal Builds fresh bounded geometry and topology facts without mutating source buffers. */
 export function buildTriangleMeshQualityAnalysis(mesh, options = {}) {
     const source = immutableMeshView(mesh);
     const maxTriangles = positiveInteger(options.maxTriangles ?? DEFAULT_MAXIMUM_TRIANGLE_COUNT, "Maximum analyzed triangle count");
@@ -389,7 +357,7 @@ export function buildTriangleMeshQualityAnalysis(mesh, options = {}) {
  * Degenerate triangles are reported rather than rejected, while malformed buffers, non-finite
  * positions, missing vertex references, and the configured complexity limit throw.
  *
- * @param mesh - Indexed triangle mesh in arbitrary consistent model units.
+ * @param mesh - Indexed triangle mesh in consistent units.
  * @param options - Scale-aware tolerance and analysis budget.
  * @returns A deterministic report without mutating or copying the mesh.
  */

package/dist/geometry/mesh/{mesh-render.js → render-buffers.js}

@@ -1,7 +1,13 @@
 import { GeometryError } from "../errors.js";
 import { immutableMeshView } from "../immutable-buffer.js";
-import { validateTriangleMesh } from "./mesh.js";
+import { validateTriangleMesh } from "./operations.js";
 const MAX_NORMAL_COMPARISONS = 50_000_000;
+// Float32 integer coordinates share low zero bits. Mix high bits before masking a table slot.
+function mixHash(value) {
+    value = Math.imul(value ^ (value >>> 16), 0x7feb352d);
+    value = Math.imul(value ^ (value >>> 15), 0x846ca68b);
+    return value ^ (value >>> 16);
+}
 function tableCapacity(count) {
     let capacity = 16;
     while (capacity < count * 2)
@@ -16,6 +22,8 @@ function tableCapacity(count) {
  * Returns owned buffers; every triangle retains its coordinates, order and winding.
  * Pathological vertex fans exceeding 50 million normal comparisons reject with a complexity error.
  *
+ * @param input - Indexed mesh to copy; source buffers remain unchanged.
+ *
  * @example
  * ```ts
  * import * as mesh from "@metamesh/modeling/geometry/mesh";
@@ -30,8 +38,15 @@ export function renderMesh(input, options = {}) {
         throw new GeometryError("INVALID_ARGUMENT", "Crease angle must be from 0 through 180 degrees.", {
             operation: "renderMesh",
         });
-    validateTriangleMesh(input);
-    const { positions, indices } = immutableMeshView(input);
+    const mesh = immutableMeshView(input);
+    validateTriangleMesh(mesh);
+    return renderValidatedMesh(mesh, angle);
+}
+/**
+ * @internal Renders exact privately captured buffer ranges already validated with the default
+ * mesh tolerance. The buffers must remain unchanged, and angle must be validated in [0, 180].
+ */
+export function renderValidatedMesh({ positions, indices }, angle) {
     const vertexCount = positions.length / 3;
     const cornerCount = indices.length;
     const faceCount = cornerCount / 3;
@@ -67,7 +82,7 @@ export function renderMesh(input, options = {}) {
         Math.imul(positions[offset + 2] === 0 ? 0 : positionBits[offset + 2], 83_492_791);
     for (let vertex = 0; vertex < vertexCount; vertex += 1) {
         const offset = vertex * 3;
-        let slot = positionHash(offset) & positionMask;
+        let slot = mixHash(positionHash(offset)) & positionMask;
         while (positionTable[slot] !== 0) {
             const id = positionTable[slot] - 1;
             const other = representatives[id] * 3;
@@ -153,7 +168,7 @@ export function renderMesh(input, options = {}) {
             Math.imul(candidateNormal[0] === 0 ? 0 : normalBits[0], 49_979_687) ^
             Math.imul(candidateNormal[1] === 0 ? 0 : normalBits[1], 67_867_967) ^
             Math.imul(candidateNormal[2] === 0 ? 0 : normalBits[2], 86_028_121);
-        let slot = hash & renderMask;
+        let slot = mixHash(hash) & renderMask;
         while (renderTable[slot] !== 0) {
             const offset = (renderTable[slot] - 1) * 3;
             if (renderPositions[offset] === positions[positionOffset] &&
@@ -179,12 +194,12 @@ export function renderMesh(input, options = {}) {
                 renderTable = new Uint32Array(tableCapacity(capacity));
                 renderMask = renderTable.length - 1;
                 for (let index = 0; index < renderedCount; index += 1) {
-                    let target = renderHash(index * 3) & renderMask;
+                    let target = mixHash(renderHash(index * 3)) & renderMask;
                     while (renderTable[target] !== 0)
                         target = (target + 1) & renderMask;
                     renderTable[target] = index + 1;
                 }
-                slot = hash & renderMask;
+                slot = mixHash(hash) & renderMask;
                 while (renderTable[slot] !== 0)
                     slot = (slot + 1) & renderMask;
             }

package/dist/geometry/mesh/{mesh-signature.js → signature.js}

@@ -1,6 +1,6 @@
 import { GeometryError } from "../errors.js";
 import { immutableMeshView } from "../immutable-buffer.js";
-import { analyzeTriangleMesh, validateTriangleMesh } from "./mesh.js";
+import { analyzeTriangleMesh, validateTriangleMesh } from "./operations.js";
 const DEFAULT_POSITION_TOLERANCE = 1e-5;
 const DEFAULT_VOLUME_TOLERANCE = 1e-4;
 const DEFAULT_MAXIMUM_TRIANGLE_COUNT = 200_000;

package/dist/geometry/mesh/{mesh-solid-intersections.js → solid-intersections.js}

@@ -1,3 +1,5 @@
+// Keep these kernels local to isolate V8's array-type feedback from other modeling operations.
+// Shared helpers see more array representations, which can slow hot loops even when inlined.
 const subtract = (a, b) => [
     a[0] - b[0],
     a[1] - b[1],

package/dist/geometry/mesh/{mesh-solid.js → solid.js}

@@ -1,9 +1,9 @@
 import { GeometryError } from "../errors.js";
 import { immutableMeshView } from "../immutable-buffer.js";
 import { resolveGeometryTolerance } from "../tolerance.js";
-import { IndexedMeshEdgeTable } from "./mesh-edge-table.js";
-import { prepareSolidTriangle, trianglesIntersectBeyondSharedBoundary, triangleSolidAngle, } from "./mesh-solid-intersections.js";
-import { analyzeTriangleMesh } from "./mesh.js";
+import { IndexedMeshEdgeTable } from "./edge-table.js";
+import { analyzeTriangleMesh, } from "./operations.js";
+import { prepareSolidTriangle, trianglesIntersectBeyondSharedBoundary, triangleSolidAngle, } from "./solid-intersections.js";
 const MAXIMUM_TRIANGLES = 200_000;
 const MAXIMUM_TESTS = 2_000_000;
 /**
@@ -18,7 +18,7 @@ const MAXIMUM_TESTS = 2_000_000;
  * Input buffers are freshly inspected and never modified; units are millimetres.
  *
  * @param mesh - Closed triangle mesh to inspect.
- * @param options - Optional lower work ceiling and numeric comparison policy.
+ * @param options - Lower work limit and tolerance for numeric comparisons.
  * @returns The original mesh after every requested check succeeds.
  */
 export function validateSolidMesh(mesh, options = {}) {

package/dist/geometry/mesh/triangle-quality.js

@@ -0,0 +1,42 @@
+const magnitude = (x, y, z, calculation) => calculation === "hypot" ? Math.hypot(x, y, z) : Math.sqrt(x * x + y * y + z * z);
+const cornerAngle = (ux, uy, uz, vx, vy, vz, calculation) => Math.atan2(magnitude(uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx, calculation), ux * vx + uy * vy + uz * vz);
+/** @internal Shape measurements using the caller's selected length arithmetic and tolerances. */
+export function triangleQuality(first, second, third, calculation) {
+    const abx = second[0] - first[0], aby = second[1] - first[1], abz = second[2] - first[2];
+    const acx = third[0] - first[0], acy = third[1] - first[1], acz = third[2] - first[2];
+    const bcx = third[0] - second[0], bcy = third[1] - second[1], bcz = third[2] - second[2];
+    const cax = first[0] - third[0], cay = first[1] - third[1], caz = first[2] - third[2];
+    const crossX = aby * acz - abz * acy, crossY = abz * acx - abx * acz, crossZ = abx * acy - aby * acx;
+    const doubleArea = magnitude(crossX, crossY, crossZ, calculation);
+    let longestEdgeSquared;
+    let collapsed = false;
+    if (calculation === "hypot") {
+        const ab = Math.hypot(abx, aby, abz), ac = Math.hypot(acx, acy, acz), bc = Math.hypot(bcx, bcy, bcz);
+        longestEdgeSquared = Math.max(ab, ac, bc) ** 2;
+        collapsed = ab === 0 || ac === 0 || bc === 0;
+    }
+    else {
+        longestEdgeSquared = Math.max(abx * abx + aby * aby + abz * abz, bcx * bcx + bcy * bcy + bcz * bcz, cax * cax + cay * cay + caz * caz);
+    }
+    // Quality reporting negates these edges; flip comparison subtracts them directly.
+    // Preserve both evaluation paths, including signed zero, for deterministic quality ordering.
+    const bax = calculation === "hypot" ? -abx : first[0] - second[0], bay = calculation === "hypot" ? -aby : first[1] - second[1], baz = calculation === "hypot" ? -abz : first[2] - second[2];
+    const cbx = calculation === "hypot" ? -bcx : second[0] - third[0], cby = calculation === "hypot" ? -bcy : second[1] - third[1], cbz = calculation === "hypot" ? -bcz : second[2] - third[2];
+    const angles = collapsed
+        ? [0, 0, 0]
+        : [
+            Math.atan2(doubleArea, abx * acx + aby * acy + abz * acz),
+            cornerAngle(bcx, bcy, bcz, bax, bay, baz, calculation),
+            cornerAngle(cax, cay, caz, cbx, cby, cbz, calculation),
+        ];
+    return {
+        angles,
+        aspectRatio: doubleArea === 0
+            ? Number.POSITIVE_INFINITY
+            : (Math.sqrt(3) * longestEdgeSquared) / (2 * doubleArea),
+        crossX,
+        crossY,
+        crossZ,
+        doubleArea,
+    };
+}

package/dist/geometry/mesh/winding.js

@@ -0,0 +1,11 @@
+/**
+ * @internal Reverses validated, exclusively owned triangle indices in place.
+ * Global reversal preserves areas and closed topology; caller-owned public meshes need copies.
+ */
+export function reverseOwnedTriangleWinding(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;
+    }
+}

package/dist/geometry/{numeric.js → mesh/write-vertex.js}

@@ -1,4 +1,4 @@
-import { GeometryError } from "./errors.js";
+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) {

package/dist/geometry/mesh-api.js

@@ -1,15 +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 { renderMesh as render } from "./mesh/mesh-render.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.
  *