fluidcad 0.0.38 → 0.0.39

package/lib/dist/math/bspline-interpolation.js

@@ -1,16 +1,18 @@
 /**
- * Global B-spline interpolation of planar points (The NURBS Book, §9.2.1):
- * chord-length parameters, knots by averaging, and a banded linear system
- * solved densely. The resulting curve passes through every input point and
- * is C2 (for the cubic case).
+ * Global B-spline interpolation (The NURBS Book, §9.2.1–9.2.2): chord-length
+ * or caller-supplied parameters, knots by averaging, and a banded linear
+ * system solved densely. The resulting curve passes through every input
+ * point and is C2 (for the cubic case). Optional end-derivative constraints
+ * (§9.2.2) pin the takeoff/arrival tangent vectors exactly — used by the
+ * loft end conditions to control how a skinned surface leaves its profiles.
  *
  * Exists because fluidcad-ocjs currently miscompiles the `Geom2dAPI` fitting
  * classes (both their constructors and `Init` produce corrupted curves);
- * `Geom2d_BSplineCurve`'s array constructor is unaffected, so we compute the
- * poles/knots ourselves and hand them over.
+ * the `Geom_BSplineCurve`/`Geom2d_BSplineCurve` array constructors are
+ * unaffected, so we compute the poles/knots ourselves and hand them over.
  */
 /** Largest knot span index whose half-open interval contains t. */
-function findSpan(poleCount, degree, t, flatKnots) {
+export function findSpan(poleCount, degree, t, flatKnots) {
     const n = poleCount - 1;
     if (t >= flatKnots[n + 1]) {
         return n;
@@ -30,7 +32,7 @@ function findSpan(poleCount, degree, t, flatKnots) {
     return mid;
 }
 /** Nonzero basis function values N[span-degree .. span] at t (Cox–de Boor). */
-function basisFunctions(span, t, degree, flatKnots) {
+export function basisFunctions(span, t, degree, flatKnots) {
     const values = [1];
     const left = [];
     const right = [];
@@ -47,49 +49,73 @@ function basisFunctions(span, t, degree, flatKnots) {
     }
     return values;
 }
-/** Gaussian elimination with partial pivoting; solves A·x = b for both RHS columns. */
-function solveDense(matrix, rhsX, rhsY) {
+/**
+ * Gaussian elimination restricted to the matrix band; solves A·x = b for
+ * every RHS column at once. Mutates its inputs.
+ *
+ * B-spline collocation matrices are banded (bandwidth ≤ degree) and totally
+ * positive, so elimination without pivoting is stable (de Boor) — and the
+ * band restriction turns the O(n³) dense solve into O(n·b²), which is what
+ * makes dense-sample curve approximation affordable.
+ */
+function solveBanded(matrix, rhsColumns) {
     const n = matrix.length;
-    for (let col = 0; col < n; col++) {
-        let pivot = col;
-        for (let row = col + 1; row < n; row++) {
-            if (Math.abs(matrix[row][col]) > Math.abs(matrix[pivot][col])) {
-                pivot = row;
+    let lowerBandwidth = 0;
+    let upperBandwidth = 0;
+    for (let row = 0; row < n; row++) {
+        for (let col = 0; col < n; col++) {
+            if (matrix[row][col] !== 0) {
+                lowerBandwidth = Math.max(lowerBandwidth, row - col);
+                upperBandwidth = Math.max(upperBandwidth, col - row);
             }
         }
-        if (Math.abs(matrix[pivot][col]) < 1e-14) {
+    }
+    for (let col = 0; col < n; col++) {
+        if (Math.abs(matrix[col][col]) < 1e-14) {
             throw new Error("B-spline interpolation: singular system (degenerate or duplicate points)");
         }
-        if (pivot !== col) {
-            [matrix[pivot], matrix[col]] = [matrix[col], matrix[pivot]];
-            [rhsX[pivot], rhsX[col]] = [rhsX[col], rhsX[pivot]];
-            [rhsY[pivot], rhsY[col]] = [rhsY[col], rhsY[pivot]];
-        }
-        for (let row = col + 1; row < n; row++) {
+        const lastRow = Math.min(n - 1, col + lowerBandwidth);
+        const lastCol = Math.min(n - 1, col + upperBandwidth);
+        for (let row = col + 1; row <= lastRow; row++) {
             const factor = matrix[row][col] / matrix[col][col];
             if (factor === 0) {
                 continue;
             }
-            for (let k = col; k < n; k++) {
+            for (let k = col; k <= lastCol; k++) {
                 matrix[row][k] -= factor * matrix[col][k];
             }
-            rhsX[row] -= factor * rhsX[col];
-            rhsY[row] -= factor * rhsY[col];
+            for (const rhs of rhsColumns) {
+                rhs[row] -= factor * rhs[col];
+            }
         }
     }
-    const x = new Array(n);
-    const y = new Array(n);
+    const solutions = rhsColumns.map(() => new Array(n));
     for (let row = n - 1; row >= 0; row--) {
-        let sumX = rhsX[row];
-        let sumY = rhsY[row];
-        for (let k = row + 1; k < n; k++) {
-            sumX -= matrix[row][k] * x[k];
-            sumY -= matrix[row][k] * y[k];
+        const lastCol = Math.min(n - 1, row + upperBandwidth);
+        for (let d = 0; d < rhsColumns.length; d++) {
+            let sum = rhsColumns[d][row];
+            for (let k = row + 1; k <= lastCol; k++) {
+                sum -= matrix[row][k] * solutions[d][k];
+            }
+            solutions[d][row] = sum / matrix[row][row];
+        }
+    }
+    return solutions;
+}
+/** Converts a flat knot vector to OCC's distinct-knots + multiplicities. */
+function toDistinctKnots(flatKnots) {
+    const knots = [];
+    const multiplicities = [];
+    for (const knot of flatKnots) {
+        if (knots.length > 0 && knot === knots[knots.length - 1]) {
+            multiplicities[multiplicities.length - 1]++;
+        }
+        else {
+            knots.push(knot);
+            multiplicities.push(1);
         }
-        x[row] = sumX / matrix[row][row];
-        y[row] = sumY / matrix[row][row];
     }
-    return { x, y };
+    return { knots, multiplicities };
 }
 /** Drops consecutive points closer than a millionth of the total chord. */
 function dedupe(points) {
@@ -118,6 +144,127 @@ function dedupe(points) {
     }
     return result;
 }
+/**
+ * Interpolates points (of any dimension) with a B-spline of degree up to 3,
+ * passing exactly through every point at the given parameters. Optional end
+ * derivatives constrain the curve's takeoff / arrival vectors (with respect
+ * to the same parameterization as `params`), adding one pole per constraint
+ * (The NURBS Book §9.2.2).
+ *
+ * With an end derivative D at a clamped end, the neighbouring pole is pinned
+ * directly (P1 = P0 + D·Δu/p and its mirror), so the constraint is exact and
+ * the linear system only solves for the remaining interior poles.
+ */
+export function interpolateWithDerivatives(points, params, startDerivative, endDerivative) {
+    const pointCount = points.length;
+    if (pointCount < 2) {
+        throw new Error("B-spline interpolation needs at least two points");
+    }
+    if (params.length !== pointCount) {
+        throw new Error("B-spline interpolation: params must match points in length");
+    }
+    for (let i = 1; i < pointCount; i++) {
+        if (!(params[i] > params[i - 1])) {
+            throw new Error("B-spline interpolation: params must be strictly increasing");
+        }
+    }
+    const dimension = points[0].length;
+    for (const derivative of [startDerivative, endDerivative]) {
+        if (derivative && derivative.length !== dimension) {
+            throw new Error("B-spline interpolation: derivative dimension must match points");
+        }
+    }
+    const constraintCount = (startDerivative ? 1 : 0) + (endDerivative ? 1 : 0);
+    const poleCount = pointCount + constraintCount;
+    const degree = Math.min(3, poleCount - 1);
+    // Knots by averaging (NURBS book eq. 9.8) over a parameter list padded with
+    // one extra copy of the first/last parameter per derivative constraint —
+    // this reduces to eq. 9.8 unconstrained and to eq. 9.11 with both ends
+    // constrained, and keeps the collocation matrix nonsingular in between.
+    const padded = [params[0]];
+    if (startDerivative) {
+        padded.push(params[0]);
+    }
+    for (let i = 1; i < pointCount - 1; i++) {
+        padded.push(params[i]);
+    }
+    if (endDerivative) {
+        padded.push(params[pointCount - 1]);
+    }
+    padded.push(params[pointCount - 1]);
+    const flatKnots = [];
+    for (let i = 0; i <= degree; i++) {
+        flatKnots.push(params[0]);
+    }
+    for (let j = 1; j <= poleCount - 1 - degree; j++) {
+        let sum = 0;
+        for (let i = j; i <= j + degree - 1; i++) {
+            sum += padded[i];
+        }
+        flatKnots.push(sum / degree);
+    }
+    for (let i = 0; i <= degree; i++) {
+        flatKnots.push(params[pointCount - 1]);
+    }
+    // Pinned poles: clamped endpoints, plus the derivative neighbours.
+    const poles = new Array(poleCount).fill(null);
+    poles[0] = [...points[0]];
+    poles[poleCount - 1] = [...points[pointCount - 1]];
+    if (startDerivative) {
+        const span = (flatKnots[degree + 1] - params[0]) / degree;
+        poles[1] = points[0].map((v, d) => v + startDerivative[d] * span);
+    }
+    if (endDerivative) {
+        const span = (params[pointCount - 1] - flatKnots[poleCount - 1]) / degree;
+        poles[poleCount - 2] = points[pointCount - 1].map((v, d) => v - endDerivative[d] * span);
+    }
+    const unknownIndices = [];
+    for (let i = 0; i < poleCount; i++) {
+        if (poles[i] === null) {
+            unknownIndices.push(i);
+        }
+    }
+    if (unknownIndices.length > 0) {
+        const columnOfPole = new Map();
+        unknownIndices.forEach((poleIndex, column) => columnOfPole.set(poleIndex, column));
+        // One collocation row per interior point; pinned poles move to the RHS.
+        const matrix = [];
+        const rhsColumns = Array.from({ length: dimension }, () => []);
+        for (let k = 1; k <= pointCount - 2; k++) {
+            const row = new Array(unknownIndices.length).fill(0);
+            const rhs = [...points[k]];
+            const span = findSpan(poleCount, degree, params[k], flatKnots);
+            const values = basisFunctions(span, params[k], degree, flatKnots);
+            for (let j = 0; j <= degree; j++) {
+                const poleIndex = span - degree + j;
+                const pinned = poles[poleIndex];
+                if (pinned) {
+                    for (let d = 0; d < dimension; d++) {
+                        rhs[d] -= values[j] * pinned[d];
+                    }
+                }
+                else {
+                    row[columnOfPole.get(poleIndex)] = values[j];
+                }
+            }
+            matrix.push(row);
+            for (let d = 0; d < dimension; d++) {
+                rhsColumns[d].push(rhs[d]);
+            }
+        }
+        const solved = solveBanded(matrix, rhsColumns);
+        unknownIndices.forEach((poleIndex, column) => {
+            poles[poleIndex] = solved.map(solution => solution[column]);
+        });
+    }
+    const { knots, multiplicities } = toDistinctKnots(flatKnots);
+    return {
+        poles: poles,
+        knots,
+        multiplicities,
+        degree,
+    };
+}
 /**
  * Interpolates the given planar points with a B-spline of degree up to 3
  * (lower for 2 or 3 points). The curve passes exactly through every point,
@@ -129,7 +276,6 @@ export function interpolateBSpline2d(rawPoints) {
         throw new Error("B-spline interpolation needs at least two distinct points");
     }
     const n = points.length - 1;
-    const degree = Math.min(3, n);
     // Chord-length parameters, normalized to [0, 1].
     const params = new Array(points.length);
     params[0] = 0;
@@ -141,54 +287,11 @@ export function interpolateBSpline2d(rawPoints) {
         params[i] /= total;
     }
     params[n] = 1;
-    // Knots by averaging (NURBS book eq. 9.8): clamped ends, one internal knot
-    // per unconstrained pole.
-    const flatKnots = [];
-    for (let i = 0; i <= degree; i++) {
-        flatKnots.push(0);
-    }
-    for (let j = 1; j <= n - degree; j++) {
-        let sum = 0;
-        for (let i = j; i <= j + degree - 1; i++) {
-            sum += params[i];
-        }
-        flatKnots.push(sum / degree);
-    }
-    for (let i = 0; i <= degree; i++) {
-        flatKnots.push(1);
-    }
-    // Interpolation system: one basis row per parameter.
-    const matrix = [];
-    const rhsX = [];
-    const rhsY = [];
-    for (let k = 0; k <= n; k++) {
-        const row = new Array(n + 1).fill(0);
-        const span = findSpan(n + 1, degree, params[k], flatKnots);
-        const values = basisFunctions(span, params[k], degree, flatKnots);
-        for (let j = 0; j <= degree; j++) {
-            row[span - degree + j] = values[j];
-        }
-        matrix.push(row);
-        rhsX.push(points[k].x);
-        rhsY.push(points[k].y);
-    }
-    const solved = solveDense(matrix, rhsX, rhsY);
-    // Convert the flat knot vector to OCC's distinct-knots + multiplicities.
-    const knots = [];
-    const multiplicities = [];
-    for (const knot of flatKnots) {
-        if (knots.length > 0 && knot === knots[knots.length - 1]) {
-            multiplicities[multiplicities.length - 1]++;
-        }
-        else {
-            knots.push(knot);
-            multiplicities.push(1);
-        }
-    }
+    const data = interpolateWithDerivatives(points.map(p => [p.x, p.y]), params);
     return {
-        poles: solved.x.map((x, i) => ({ x, y: solved.y[i] })),
-        knots,
-        multiplicities,
-        degree,
+        poles: data.poles.map(p => ({ x: p[0], y: p[1] })),
+        knots: data.knots,
+        multiplicities: data.multiplicities,
+        degree: data.degree,
     };
 }

package/lib/dist/oc/loft/constrained-loft.d.ts

@@ -0,0 +1,32 @@
+import { Wire } from "../../common/wire.js";
+import { Solid } from "../../common/solid.js";
+import { LoftEndCondition } from "./skinning.js";
+export type { LoftConditionKind, LoftEndCondition } from "./skinning.js";
+/**
+ * Loft with start/end conditions. OCC's `BRepOffsetAPI_ThruSections` cannot
+ * constrain end tangency, so this path skins the surface itself: profiles
+ * become compatible B-spline sections (`SectionCompatibility`), matching pole
+ * columns are interpolated along the loft with the end derivatives pinned,
+ * and the resulting surface is capped and sewn into a solid (`Skinning`).
+ *
+ * Conditions:
+ * - `normal`: the surface leaves the profile along the profile's plane
+ *   normal — a perpendicular takeoff.
+ * - `tangent`: the surface leaves the profile inside the profile's plane,
+ *   directed outward — profiles become tangency planes (e.g. a barrel from
+ *   two stacked circles). Negative magnitudes direct it inward.
+ */
+export declare class ConstrainedLoft {
+    static build(wires: Wire[], startCondition: LoftEndCondition | undefined, endCondition: LoftEndCondition | undefined): Solid[];
+    /**
+     * Thin-walled conditioned loft, assembled directly: outer wall, inner
+     * wall, and two planar ring caps sewn into one solid. Cutting the inner
+     * loft out of the outer with a boolean instead takes OCC seconds — two
+     * nearly-parallel B-spline shells are the pave-filler's worst case — and
+     * the walls are already exact offsets, so no boolean is needed.
+     */
+    static buildThin(outerWires: Wire[], innerWires: Wire[], startCondition: LoftEndCondition | undefined, endCondition: LoftEndCondition | undefined): Solid[];
+    private static skinWires;
+    /** Planar ring between the outer and inner wall boundaries at one end. */
+    private static ringCap;
+}

package/lib/dist/oc/loft/constrained-loft.js

@@ -0,0 +1,61 @@
+import { Wire } from "../../common/wire.js";
+import { FaceOps } from "../face-ops.js";
+import { SectionCompatibility } from "./section-compatibility.js";
+import { Skinning } from "./skinning.js";
+/**
+ * Loft with start/end conditions. OCC's `BRepOffsetAPI_ThruSections` cannot
+ * constrain end tangency, so this path skins the surface itself: profiles
+ * become compatible B-spline sections (`SectionCompatibility`), matching pole
+ * columns are interpolated along the loft with the end derivatives pinned,
+ * and the resulting surface is capped and sewn into a solid (`Skinning`).
+ *
+ * Conditions:
+ * - `normal`: the surface leaves the profile along the profile's plane
+ *   normal — a perpendicular takeoff.
+ * - `tangent`: the surface leaves the profile inside the profile's plane,
+ *   directed outward — profiles become tangency planes (e.g. a barrel from
+ *   two stacked circles). Negative magnitudes direct it inward.
+ */
+export class ConstrainedLoft {
+    static build(wires, startCondition, endCondition) {
+        const compatible = ConstrainedLoft.skinWires(wires);
+        const skinned = Skinning.skinSections(compatible, startCondition, endCondition);
+        return [Skinning.buildLoftSolid(compatible, skinned.grid, skinned.vBasis)];
+    }
+    /**
+     * Thin-walled conditioned loft, assembled directly: outer wall, inner
+     * wall, and two planar ring caps sewn into one solid. Cutting the inner
+     * loft out of the outer with a boolean instead takes OCC seconds — two
+     * nearly-parallel B-spline shells are the pave-filler's worst case — and
+     * the walls are already exact offsets, so no boolean is needed.
+     */
+    static buildThin(outerWires, innerWires, startCondition, endCondition) {
+        const outer = ConstrainedLoft.skinWires(outerWires);
+        const inner = ConstrainedLoft.skinWires(innerWires);
+        const outerSkin = Skinning.skinSections(outer, startCondition, endCondition);
+        const innerSkin = Skinning.skinSections(inner, startCondition, endCondition);
+        const faces = [
+            ...Skinning.sideFaces(outer, outerSkin.grid, outerSkin.vBasis),
+            ...Skinning.sideFaces(inner, innerSkin.grid, innerSkin.vBasis),
+            ConstrainedLoft.ringCap(outer, outerSkin, inner, innerSkin, false),
+            ConstrainedLoft.ringCap(outer, outerSkin, inner, innerSkin, true),
+        ];
+        return [Skinning.sewSolid(faces)];
+    }
+    static skinWires(wires) {
+        for (const wire of wires) {
+            if (!wire.isClosed()) {
+                throw new Error("Loft with start/end conditions requires closed profiles.");
+            }
+        }
+        return SectionCompatibility.build(wires.map(w => w.getShape()));
+    }
+    /** Planar ring between the outer and inner wall boundaries at one end. */
+    static ringCap(outer, outerSkin, inner, innerSkin, isEnd) {
+        const column = (grid) => grid.map(row => row[isEnd ? row.length - 1 : 0]);
+        const outerWire = new Wire(Skinning.capWire(outer, column(outerSkin.grid)));
+        const innerWire = new Wire(Skinning.capWire(inner, column(innerSkin.grid)));
+        const ring = FaceOps.makeFaceWithHoles(outerWire, [innerWire]);
+        return FaceOps.fixFaceOrientation(ring).getShape();
+    }
+}

package/lib/dist/oc/loft/curve-data.d.ts

@@ -0,0 +1,18 @@
+import type { Geom_BSplineCurve } from "ocjs-fluidcad";
+import type { BSplineCurveData } from "../../math/bspline-interpolation.js";
+/**
+ * Plain-JS mirror of a `Geom_BSplineCurve`. `weights` is null for polynomial
+ * curves; when present it holds one weight per pole (rational curve).
+ */
+export interface RationalBSplineData extends BSplineCurveData {
+    weights: number[] | null;
+}
+/**
+ * Moves B-spline curves between OCC handles and plain data, so the knot/pole
+ * bookkeeping of the loft pipeline (concatenation, unification, skinning) can
+ * run on ordinary arrays instead of chains of native calls.
+ */
+export declare class CurveData {
+    static read(curve: Geom_BSplineCurve): RationalBSplineData;
+    static build(data: RationalBSplineData): Geom_BSplineCurve;
+}

package/lib/dist/oc/loft/curve-data.js

@@ -0,0 +1,54 @@
+import { getOC } from "../init.js";
+import { NCollections } from "../ncollection.js";
+/**
+ * Moves B-spline curves between OCC handles and plain data, so the knot/pole
+ * bookkeeping of the loft pipeline (concatenation, unification, skinning) can
+ * run on ordinary arrays instead of chains of native calls.
+ */
+export class CurveData {
+    static read(curve) {
+        const poles = [];
+        for (let i = 1; i <= curve.NbPoles(); i++) {
+            const pole = curve.Pole(i);
+            poles.push([pole.X(), pole.Y(), pole.Z()]);
+            pole.delete();
+        }
+        const knots = [];
+        const multiplicities = [];
+        for (let i = 1; i <= curve.NbKnots(); i++) {
+            knots.push(curve.Knot(i));
+            multiplicities.push(curve.Multiplicity(i));
+        }
+        let weights = null;
+        if (curve.IsRational()) {
+            weights = [];
+            for (let i = 1; i <= curve.NbPoles(); i++) {
+                weights.push(curve.Weight(i));
+            }
+        }
+        return { poles, weights, knots, multiplicities, degree: curve.Degree() };
+    }
+    static build(data) {
+        const oc = getOC();
+        const [poles, disposePoles] = NCollections.toArray1Pnt(data.poles);
+        const [knots, disposeKnots] = NCollections.toArray1Double(data.knots);
+        const [multiplicities, disposeMultiplicities] = NCollections.toArray1Int(data.multiplicities);
+        try {
+            if (data.weights) {
+                const [weights, disposeWeights] = NCollections.toArray1Double(data.weights);
+                try {
+                    return new oc.Geom_BSplineCurve(poles, weights, knots, multiplicities, data.degree, false, false);
+                }
+                finally {
+                    disposeWeights();
+                }
+            }
+            return new oc.Geom_BSplineCurve(poles, knots, multiplicities, data.degree, false);
+        }
+        finally {
+            disposePoles();
+            disposeKnots();
+            disposeMultiplicities();
+        }
+    }
+}

package/lib/dist/oc/loft/curve-eval.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Plain-data B-spline evaluation for the loft pipeline. Sections and guides
+ * live as pole/knot arrays between pipeline stages (see `CurveData`), and
+ * evaluating them directly in JS avoids rebuilding native curves just to
+ * sample a few points.
+ */
+/** Expands distinct knots + multiplicities into the flat knot sequence. */
+export declare function flattenKnots(knots: ReadonlyArray<number>, multiplicities: ReadonlyArray<number>): number[];
+export interface EvaluableBSpline {
+    degree: number;
+    knots: number[];
+    multiplicities: number[];
+    poles: number[][];
+    weights?: number[] | null;
+}
+/** Point on a (possibly rational) B-spline at parameter t. */
+export declare function evaluateBSplinePoint(curve: EvaluableBSpline, t: number): number[];
+/**
+ * Parameter in [low, high] whose evaluated point lies closest to `target`:
+ * dense sampling to bracket the minimum, then golden-section refinement.
+ * Works for any point-valued curve evaluation (plain-data or native).
+ */
+export declare function closestCurveParameter(evaluate: (t: number) => number[], target: ReadonlyArray<number>, low?: number, high?: number, samples?: number): number;

package/lib/dist/oc/loft/curve-eval.js

@@ -0,0 +1,84 @@
+import { findSpan, basisFunctions } from "../../math/bspline-interpolation.js";
+/**
+ * Plain-data B-spline evaluation for the loft pipeline. Sections and guides
+ * live as pole/knot arrays between pipeline stages (see `CurveData`), and
+ * evaluating them directly in JS avoids rebuilding native curves just to
+ * sample a few points.
+ */
+/** Expands distinct knots + multiplicities into the flat knot sequence. */
+export function flattenKnots(knots, multiplicities) {
+    const flat = [];
+    for (let i = 0; i < knots.length; i++) {
+        for (let m = 0; m < multiplicities[i]; m++) {
+            flat.push(knots[i]);
+        }
+    }
+    return flat;
+}
+/** Point on a (possibly rational) B-spline at parameter t. */
+export function evaluateBSplinePoint(curve, t) {
+    const flat = flattenKnots(curve.knots, curve.multiplicities);
+    const span = findSpan(curve.poles.length, curve.degree, t, flat);
+    const values = basisFunctions(span, t, curve.degree, flat);
+    const dimension = curve.poles[0].length;
+    const numerator = new Array(dimension).fill(0);
+    let denominator = 0;
+    for (let j = 0; j <= curve.degree; j++) {
+        const poleIndex = span - curve.degree + j;
+        const weight = curve.weights ? curve.weights[poleIndex] : 1;
+        const blend = values[j] * weight;
+        denominator += blend;
+        for (let d = 0; d < dimension; d++) {
+            numerator[d] += blend * curve.poles[poleIndex][d];
+        }
+    }
+    return numerator.map(v => v / denominator);
+}
+/**
+ * Parameter in [low, high] whose evaluated point lies closest to `target`:
+ * dense sampling to bracket the minimum, then golden-section refinement.
+ * Works for any point-valued curve evaluation (plain-data or native).
+ */
+export function closestCurveParameter(evaluate, target, low = 0, high = 1, samples = 512) {
+    const distanceAt = (t) => {
+        const p = evaluate(t);
+        let sum = 0;
+        for (let d = 0; d < target.length; d++) {
+            sum += (p[d] - target[d]) * (p[d] - target[d]);
+        }
+        return sum;
+    };
+    let bestIndex = 0;
+    let bestDistance = Infinity;
+    for (let i = 0; i <= samples; i++) {
+        const d = distanceAt(low + ((high - low) * i) / samples);
+        if (d < bestDistance) {
+            bestDistance = d;
+            bestIndex = i;
+        }
+    }
+    let a = low + ((high - low) * Math.max(0, bestIndex - 1)) / samples;
+    let b = low + ((high - low) * Math.min(samples, bestIndex + 1)) / samples;
+    const phi = (Math.sqrt(5) - 1) / 2;
+    let mid1 = b - phi * (b - a);
+    let mid2 = a + phi * (b - a);
+    let d1 = distanceAt(mid1);
+    let d2 = distanceAt(mid2);
+    for (let iteration = 0; iteration < 40; iteration++) {
+        if (d1 <= d2) {
+            b = mid2;
+            mid2 = mid1;
+            d2 = d1;
+            mid1 = b - phi * (b - a);
+            d1 = distanceAt(mid1);
+        }
+        else {
+            a = mid1;
+            mid1 = mid2;
+            d1 = d2;
+            mid2 = a + phi * (b - a);
+            d2 = distanceAt(mid2);
+        }
+    }
+    return (a + b) / 2;
+}