bireactive 0.2.0

package/dist/core/lenses/factor-lens.js

@@ -0,0 +1,419 @@
+// factor-lens.ts — N→M lens prototypes (Vec-specific monoliths).
+//
+// N inputs → M coupled writable outputs, where writing one output
+// preserves the readings of the other M−1 (cross-channel invariance).
+// Two regimes:
+//
+//   1. Numerical (Jacobian-LSQ): `factorLens` builds an M×N Jacobian by
+//      finite differences and solves `(J W Jᵀ + λI) k = δy` for `k`,
+//      then writes `δx = W Jᵀ k`. δy is sparse (only the written
+//      channel), so the solve leaves other channels near-stationary.
+//      Invariance is approximate, set by the local condition number.
+//
+//   2. Closed-form (geometric): `procrustesLens`, `bboxLens`,
+//      `meanDiffLens` — hand-rolled bwd via the right group action, so
+//      cross-channel invariance is EXACT. Cost: crafted per topology.
+//
+// `bundleLens` sketches the 1→M dual (single source → M coupled views).
+import { Num, Vec } from "../index.js";
+export function factorLens(inputs, forwards, opts = {}) {
+    const N = inputs.length;
+    const M = forwards.length;
+    if (M === 0)
+        return [];
+    const w = opts.inputWeights ?? new Array(N).fill(1);
+    const eps = opts.eps ?? 1e-5;
+    const lambda = opts.damping ?? 1e-6;
+    // Per-call (NOT per-cell) scratch; safe because writes execute
+    // synchronously inside `_setWithExclusion`.
+    const J = new Array(M * N);
+    const A = new Array(M * M);
+    const Ainv = new Array(M * M);
+    const ys = new Array(M);
+    const dy = new Array(M);
+    const kvec = new Array(M);
+    const outputs = [];
+    for (let outIdx = 0; outIdx < M; outIdx++) {
+        const idx = outIdx;
+        const out = new Array(N);
+        const cell = Num.lens(inputs, (vals) => forwards[idx](vals), (target, valsReadonly) => {
+            // Snapshot inputs into a mutable scratch so FD perturbations
+            // don't leak into upstream cell state.
+            const xs = valsReadonly;
+            const xsm = xs.slice();
+            for (let j = 0; j < M; j++)
+                ys[j] = forwards[j](xsm);
+            for (let j = 0; j < M; j++)
+                dy[j] = 0;
+            dy[idx] = target - ys[idx];
+            // Build Jacobian column-by-column.
+            for (let i = 0; i < N; i++) {
+                const saved = xsm[i];
+                xsm[i] = saved + eps;
+                for (let j = 0; j < M; j++) {
+                    J[j * N + i] = (forwards[j](xsm) - ys[j]) / eps;
+                }
+                xsm[i] = saved;
+            }
+            // A = J W Jᵀ + λI
+            for (let r = 0; r < M; r++) {
+                for (let c = 0; c < M; c++) {
+                    let s = 0;
+                    for (let i = 0; i < N; i++)
+                        s += J[r * N + i] * w[i] * J[c * N + i];
+                    A[r * M + c] = s + (r === c ? lambda : 0);
+                }
+            }
+            if (!invertMatrix(A, M, Ainv)) {
+                // Singular — leave inputs unchanged.
+                for (let i = 0; i < N; i++)
+                    out[i] = undefined;
+                return out;
+            }
+            for (let r = 0; r < M; r++) {
+                let s = 0;
+                for (let c = 0; c < M; c++)
+                    s += Ainv[r * M + c] * dy[c];
+                kvec[r] = s;
+            }
+            for (let i = 0; i < N; i++) {
+                let dxi = 0;
+                for (let r = 0; r < M; r++)
+                    dxi += J[r * N + i] * kvec[r];
+                out[i] = xsm[i] + w[i] * dxi;
+            }
+            return out;
+        });
+        outputs.push(cell);
+    }
+    return outputs;
+}
+/** Gauss-Jordan inverse of a row-major M×M matrix. Returns false if
+ *  singular (pivot below 1e-14). Allocates one 2M-wide row buffer.
+ *  For M ≤ ~10 this is competitive with LAPACK and avoids the dep. */
+function invertMatrix(A, M, out) {
+    const W = 2 * M;
+    const aug = new Array(M * W);
+    for (let r = 0; r < M; r++) {
+        for (let c = 0; c < M; c++)
+            aug[r * W + c] = A[r * M + c];
+        for (let c = 0; c < M; c++)
+            aug[r * W + M + c] = r === c ? 1 : 0;
+    }
+    for (let i = 0; i < M; i++) {
+        let p = i;
+        let pv = Math.abs(aug[i * W + i]);
+        for (let r = i + 1; r < M; r++) {
+            const v = Math.abs(aug[r * W + i]);
+            if (v > pv) {
+                pv = v;
+                p = r;
+            }
+        }
+        if (pv < 1e-14)
+            return false;
+        if (p !== i) {
+            for (let c = 0; c < W; c++) {
+                const t = aug[i * W + c];
+                aug[i * W + c] = aug[p * W + c];
+                aug[p * W + c] = t;
+            }
+        }
+        const inv = 1 / aug[i * W + i];
+        for (let c = 0; c < W; c++)
+            aug[i * W + c] = aug[i * W + c] * inv;
+        for (let r = 0; r < M; r++) {
+            if (r === i)
+                continue;
+            const f = aug[r * W + i];
+            if (f === 0)
+                continue;
+            for (let c = 0; c < W; c++)
+                aug[r * W + c] = aug[r * W + c] - f * aug[i * W + c];
+        }
+    }
+    for (let r = 0; r < M; r++) {
+        for (let c = 0; c < M; c++)
+            out[r * M + c] = aug[r * W + M + c];
+    }
+    return true;
+}
+// meanDiffLens — M=2 isomorphism baseline.
+//
+// (a, b) → ((a+b)/2, a−b). Square full-rank linear lens; bwd is the
+// inverse change of basis — exact, cross-channel invariant. Sanity
+// baseline for the property tests.
+export function meanDiffLens(a, b) {
+    const mean = Num.lens([a, b], vals => (vals[0] + vals[1]) / 2, (target, vals) => {
+        const d = vals[0] - vals[1];
+        return [target + d / 2, target - d / 2];
+    });
+    const diff = Num.lens([a, b], vals => vals[0] - vals[1], (target, vals) => {
+        const m = (vals[0] + vals[1]) / 2;
+        return [m + target / 2, m - target / 2];
+    });
+    return { mean, diff };
+}
+// procrustesLens — closed-form similarity (the showcase).
+//
+// K writable Vecs → {centroid, rotation (angle of point[0] about
+// centroid), scale (its distance from centroid)}. Each bwd is a
+// closed-form transform about the centroid:
+//   write centroid → translate every point by (c − old c)
+//   write rotation → rotate every point about centroid by (θ − old θ)
+//   write scale    → scale every point about centroid by (s / old s)
+// These commute on the cluster's similarity orbit, so the three outputs
+// have EXACT cross-channel invariance (cf. `procrustesJacobianLens`'s
+// approximate version). Degenerate: K < 2 leaves rotation/scale
+// undefined; a collapsed cluster (scale → 0) makes rotation singular and
+// scale writes no-ops; target scale = 0 collapses to the centroid.
+export function procrustesLens(points) {
+    const K = points.length;
+    if (K < 2)
+        throw new Error("procrustesLens: need ≥ 2 points");
+    const centroid = Vec.lens(points, (vals) => {
+        let sx = 0;
+        let sy = 0;
+        for (let i = 0; i < K; i++) {
+            sx += vals[i].x;
+            sy += vals[i].y;
+        }
+        return { x: sx / K, y: sy / K };
+    }, (target, vals) => {
+        let sx = 0;
+        let sy = 0;
+        for (let i = 0; i < K; i++) {
+            sx += vals[i].x;
+            sy += vals[i].y;
+        }
+        const dx = target.x - sx / K;
+        const dy = target.y - sy / K;
+        const out = new Array(K);
+        for (let i = 0; i < K; i++)
+            out[i] = { x: vals[i].x + dx, y: vals[i].y + dy };
+        return out;
+    });
+    const rotation = Num.lens(points, (vals) => {
+        let sx = 0;
+        let sy = 0;
+        for (let i = 0; i < K; i++) {
+            sx += vals[i].x;
+            sy += vals[i].y;
+        }
+        const cx = sx / K;
+        const cy = sy / K;
+        return Math.atan2(vals[0].y - cy, vals[0].x - cx);
+    }, (target, vals) => {
+        let sx = 0;
+        let sy = 0;
+        for (let i = 0; i < K; i++) {
+            sx += vals[i].x;
+            sy += vals[i].y;
+        }
+        const cx = sx / K;
+        const cy = sy / K;
+        const rx0 = vals[0].x - cx;
+        const ry0 = vals[0].y - cy;
+        if (rx0 * rx0 + ry0 * ry0 < 1e-24) {
+            // Collapsed cluster; no angle to rotate from.
+            return vals.map(() => undefined);
+        }
+        const oldθ = Math.atan2(ry0, rx0);
+        const dθ = target - oldθ;
+        const cos = Math.cos(dθ);
+        const sin = Math.sin(dθ);
+        const out = new Array(K);
+        for (let i = 0; i < K; i++) {
+            const rx = vals[i].x - cx;
+            const ry = vals[i].y - cy;
+            out[i] = { x: cx + cos * rx - sin * ry, y: cy + sin * rx + cos * ry };
+        }
+        return out;
+    });
+    const centroidOf = (vals) => {
+        let sx = 0;
+        let sy = 0;
+        for (let i = 0; i < K; i++) {
+            sx += vals[i].x;
+            sy += vals[i].y;
+        }
+        return { x: sx / K, y: sy / K };
+    };
+    const refreshDevs = (devs, vals) => {
+        const c = centroidOf(vals);
+        return devs.map((d, i) => {
+            const dx = vals[i].x - c.x;
+            const dy = vals[i].y - c.y;
+            return dx * dx + dy * dy > 1e-18 ? { x: dx, y: dy } : d;
+        });
+    };
+    const scale = Num.lens(points, {
+        init: (vals) => {
+            const c = centroidOf(vals);
+            return { devs: vals.map(v => ({ x: v.x - c.x, y: v.y - c.y })) };
+        },
+        step: (vals, c) => ({ devs: refreshDevs(c.devs, vals) }),
+        fwd: (vals) => {
+            const c = centroidOf(vals);
+            return Math.hypot(vals[0].x - c.x, vals[0].y - c.y);
+        },
+        bwd: (target, vals, c) => {
+            const cen = centroidOf(vals);
+            const d0 = c.devs[0];
+            const r0 = Math.hypot(d0.x, d0.y);
+            if (r0 < 1e-12)
+                return { updates: vals.map(() => undefined), complement: c };
+            const k = target / r0;
+            const out = c.devs.map(d => ({ x: cen.x + k * d.x, y: cen.y + k * d.y }));
+            return { updates: out, complement: c };
+        },
+    });
+    return { centroid, rotation, scale };
+}
+// bboxLens — closed-form axis-aligned bounding box.
+//
+// K Vecs → {center, size}. Forward is min/max (piecewise-constant
+// Jacobian — fatal for FD), but the closed-form bwd is exact:
+//   write center → translate all points by (c − old c)
+//   write size   → scale all about center by component-wise ratio
+// Center↔size invariance is exact. Degenerate axes (size = 0) write
+// as no-ops; negative size reflects (kept permissive).
+export function bboxLens(points) {
+    const K = points.length;
+    if (K < 1)
+        throw new Error("bboxLens: need ≥ 1 point");
+    const computeBox = (vals) => {
+        let minX = Number.POSITIVE_INFINITY;
+        let minY = Number.POSITIVE_INFINITY;
+        let maxX = Number.NEGATIVE_INFINITY;
+        let maxY = Number.NEGATIVE_INFINITY;
+        for (let i = 0; i < K; i++) {
+            const x = vals[i].x;
+            const y = vals[i].y;
+            if (x < minX)
+                minX = x;
+            if (x > maxX)
+                maxX = x;
+            if (y < minY)
+                minY = y;
+            if (y > maxY)
+                maxY = y;
+        }
+        return {
+            cx: (minX + maxX) / 2,
+            cy: (minY + maxY) / 2,
+            sx: maxX - minX,
+            sy: maxY - minY,
+        };
+    };
+    const center = Vec.lens(points, (vals) => {
+        const b = computeBox(vals);
+        return { x: b.cx, y: b.cy };
+    }, (target, vals) => {
+        const b = computeBox(vals);
+        const dx = target.x - b.cx;
+        const dy = target.y - b.cy;
+        const out = new Array(K);
+        for (let i = 0; i < K; i++)
+            out[i] = { x: vals[i].x + dx, y: vals[i].y + dy };
+        return out;
+    });
+    const refreshFracs = (fracs, vals) => {
+        const b = computeBox(vals);
+        const hx = b.sx > 1e-12 ? b.sx / 2 : 0;
+        const hy = b.sy > 1e-12 ? b.sy / 2 : 0;
+        return fracs.map((f, i) => ({
+            x: hx > 0 ? (vals[i].x - b.cx) / hx : f.x,
+            y: hy > 0 ? (vals[i].y - b.cy) / hy : f.y,
+        }));
+    };
+    const size = Vec.lens(points, {
+        init: (vals) => {
+            const b = computeBox(vals);
+            const halfX0 = b.sx > 1e-12 ? b.sx / 2 : 1;
+            const halfY0 = b.sy > 1e-12 ? b.sy / 2 : 1;
+            return {
+                fracs: vals.map(v => ({
+                    x: b.sx > 1e-12 ? (v.x - b.cx) / halfX0 : 0,
+                    y: b.sy > 1e-12 ? (v.y - b.cy) / halfY0 : 0,
+                })),
+            };
+        },
+        step: (vals, c) => ({ fracs: refreshFracs(c.fracs, vals) }),
+        fwd: (vals) => {
+            const b = computeBox(vals);
+            return { x: b.sx, y: b.sy };
+        },
+        bwd: (target, vals, c) => {
+            const b = computeBox(vals);
+            const halfTx = target.x / 2;
+            const halfTy = target.y / 2;
+            const out = c.fracs.map(f => ({ x: b.cx + f.x * halfTx, y: b.cy + f.y * halfTy }));
+            return { updates: out, complement: c };
+        },
+    });
+    return { center, size };
+}
+// procrustesJacobianLens — comparison point.
+//
+// Same forward map as `procrustesLens` but with the generic Jacobian-LSQ
+// bwd, to quantify the numerical path vs. the closed-form one.
+export function procrustesJacobianLens(points) {
+    const K = points.length;
+    if (K < 2)
+        throw new Error("procrustesJacobianLens: need ≥ 2 points");
+    // Flatten K Vecs into 2K scalar field lenses.
+    const xs = [];
+    const ys = [];
+    for (const p of points) {
+        xs.push(Num.lens([p], v => v[0].x, (t, v) => [{ x: t, y: v[0].y }]));
+        ys.push(Num.lens([p], v => v[0].y, (t, v) => [{ x: v[0].x, y: t }]));
+    }
+    // factorLens wants a flat input array.
+    const flat = [];
+    for (let i = 0; i < K; i++) {
+        flat.push(xs[i], ys[i]);
+    }
+    // Indexing helpers
+    const xAt = (a, i) => a[2 * i];
+    const yAt = (a, i) => a[2 * i + 1];
+    const fwdCx = (a) => {
+        let s = 0;
+        for (let i = 0; i < K; i++)
+            s += xAt(a, i);
+        return s / K;
+    };
+    const fwdCy = (a) => {
+        let s = 0;
+        for (let i = 0; i < K; i++)
+            s += yAt(a, i);
+        return s / K;
+    };
+    const fwdRot = (a) => {
+        return Math.atan2(yAt(a, 0) - fwdCy(a), xAt(a, 0) - fwdCx(a));
+    };
+    const fwdScale = (a) => {
+        return Math.hypot(xAt(a, 0) - fwdCx(a), yAt(a, 0) - fwdCy(a));
+    };
+    const [centroidX, centroidY, rotation, scale] = factorLens(flat, [fwdCx, fwdCy, fwdRot, fwdScale], { damping: 1e-4 });
+    return { centroidX, centroidY, rotation, scale };
+}
+export function bundleLens(pose, rotateAbout) {
+    const position = Vec.lens([pose], (v) => ({ x: v[0].x, y: v[0].y }), (target, v) => [{ ...v[0], x: target.x, y: target.y }]);
+    const rotation = Num.lens([pose], (v) => v[0].theta, (target, v) => {
+        const cur = v[0];
+        const dθ = target - cur.theta;
+        const cos = Math.cos(dθ);
+        const sin = Math.sin(dθ);
+        const rx = cur.x - rotateAbout.x;
+        const ry = cur.y - rotateAbout.y;
+        return [
+            {
+                x: rotateAbout.x + cos * rx - sin * ry,
+                y: rotateAbout.y + sin * rx + cos * ry,
+                theta: target,
+            },
+        ];
+    });
+    return { position, rotation };
+}

package/dist/core/lenses/index.d.ts

@@ -0,0 +1,5 @@
+export { bestFitCircleLens, bestFitLineLens, pcaLens, procrustesViaBuildingBlocks, rigidTranslate, rotateAbout, scaleAbout, scaleAboutXY, totalLens, } from "./closed-form-policies.js";
+export { bezierGestaltLens, crossfade, meanColor, meanOf, mix, paletteLens, rigidTranslateOf, select, spreadOf, timeSeriesLens, } from "./domain-aggregates.js";
+export { bboxLens, bundleLens, type FactorLensOpts, factorLens, meanDiffLens, procrustesJacobianLens, procrustesLens, } from "./factor-lens.js";
+export { type ContinuousOpts, continuous, type RememberOpts, remember, } from "./memory.js";
+export { bundle, type FactorOpts, type FactorResult, factor, factorTuple, type OutputSpec, type PackedInput, procrustesTyped, } from "./typed-factor.js";

package/dist/core/lenses/index.js

@@ -0,0 +1,16 @@
+// core/lenses/index.ts — N→M and 1→M bidirectional lens primitives.
+//
+// Three layers:
+//   1. NUMERICAL — `factor`, `factorTuple`, `bundle`: generic
+//      Jacobian-LSQ, the escape hatch when no closed-form policy fits.
+//   2. CLOSED-FORM POLICIES — `rigidTranslate`, `rotateAbout`,
+//      `scaleAbout`, `scaleAboutXY`: exact group-action primitives.
+//   3. DECOMPOSITIONS — `procrustesLens`, `bboxLens`, `bestFitLine`,
+//      etc.: composed M-output views over the policies and aggregates.
+//
+// See BIDIRECTIONAL-LENSES.md for the engine substrate.
+export { bestFitCircleLens, bestFitLineLens, pcaLens, procrustesViaBuildingBlocks, rigidTranslate, rotateAbout, scaleAbout, scaleAboutXY, totalLens, } from "./closed-form-policies.js";
+export { bezierGestaltLens, crossfade, meanColor, meanOf, mix, paletteLens, rigidTranslateOf, select, spreadOf, timeSeriesLens, } from "./domain-aggregates.js";
+export { bboxLens, bundleLens, factorLens, meanDiffLens, procrustesJacobianLens, procrustesLens, } from "./factor-lens.js";
+export { continuous, remember, } from "./memory.js";
+export { bundle, factor, factorTuple, procrustesTyped, } from "./typed-factor.js";

package/dist/core/lenses/memory.d.ts

@@ -0,0 +1,47 @@
+import { type Cell, Num, type Traits, type Writable } from "../index.js";
+/** Options for {@link remember}. `anchor` is the fixed point sources scale
+ *  about (a pivot, or the live centroid); `feature` is the writable scalar
+ *  (a radius, mean distance, or sum). */
+export interface RememberOpts<T> {
+    /** Point sources scale about — a constant pivot or a derived centroid. */
+    anchor: (vals: readonly T[]) => T;
+    /** The scalar view (the forward): radius, mean radius, spread, sum, … */
+    feature: (vals: readonly T[], anchor: T) => number;
+    /** Feature is non-negative ⇒ a same-magnitude write (e.g. `-r`) is a
+     *  no-op (PutGet on a magnitude). Default `true`; set `false` for a
+     *  signed total. */
+    magnitude?: boolean;
+    /** Degeneracy threshold; below it the cluster is "collapsed" and the
+     *  stored shape drives reinflation. Default `1e-9`. */
+    eps?: number;
+    /** Normalized shape to seed when the feature is degenerate at init and
+     *  no prior good shape exists. Default: zero deviations (stays
+     *  collapsed). `totalLens` passes uniform `1/K` for an even split. */
+    seed?: (vals: readonly T[]) => T[];
+}
+/** Scalar shape-memory lens. Reads `feature(sources)`; writing it scales
+ *  the cluster about `anchor` so the new feature matches, reinflating the
+ *  remembered shape when the cluster has collapsed onto the anchor. The
+ *  complement is the per-source deviation normalized by the feature. */
+export declare function remember<T, S extends Cell<T> & Traits<T, "linear">>(sources: readonly Writable<S>[], opts: RememberOpts<T>): Writable<Num>;
+/** Options for {@link continuous}. `raw` reads the cyclic value (mod
+ *  `period`) and whether it's defined; `apply` realizes an unwrapped
+ *  target back onto the sources given the current unwrapped reading. */
+export interface ContinuousOpts<T> {
+    /** Cycle length: `2π` for a full angle, `π` for an axis (sign-free). */
+    period: number;
+    /** Raw cyclic reading. `defined: false` (e.g. a collapsed cloud has no
+     *  axis) holds the last emitted value and freezes the sources. */
+    raw: (vals: readonly T[]) => {
+        value: number;
+        defined: boolean;
+    };
+    /** Realize `target` (already unwrapped, absolute) onto the sources,
+     *  given the `current` unwrapped reading (for a delta). */
+    apply: (target: number, vals: readonly T[], current: number) => readonly (T | undefined)[];
+}
+/** Continuous (winding-aware) lens over a cyclic reading. The complement
+ *  tracks the last emitted value and unwraps each raw reading to the
+ *  nearest representative modulo `period`, so the view follows the source
+ *  across branch cuts instead of jumping a full period. */
+export declare function continuous<T>(sources: readonly Writable<Cell<T>>[], opts: ContinuousOpts<T>): Writable<Num>;

package/dist/core/lenses/memory.js

@@ -0,0 +1,102 @@
+// memory.ts — path-dependent (stateful-complement) lens combinators.
+//
+// Two backward directions are not functions of the current source alone;
+// they depend on where the value has BEEN. Both were hand-rolled per site
+// across the closed-form-policy and aggregate lenses, each with its own
+// degeneracy threshold. They factor into two combinators:
+//
+//   remember   — a magnitude/total view of a cluster: sources live at
+//                `anchorᵢ + shapeᵢ · scale`, `scale` is the writable
+//                scalar. The complement holds the normalized shape so a
+//                collapse to the anchor (scale → 0) reinflates it. Covers
+//                scaleAbout, bestFitCircle.radius, spreadOf, totalLens.
+//   continuous — a cyclic (mod-`period`) view lifted to its universal
+//                cover: the complement tracks the last emitted value and
+//                unwraps the raw reading to the nearest sheet, so the
+//                view never tears at a branch cut. Covers the eigenvector
+//                angle of bestFitLine; the primitive behind winding.
+import { Num } from "../index.js";
+/** Scalar shape-memory lens. Reads `feature(sources)`; writing it scales
+ *  the cluster about `anchor` so the new feature matches, reinflating the
+ *  remembered shape when the cluster has collapsed onto the anchor. The
+ *  complement is the per-source deviation normalized by the feature. */
+export function remember(sources, opts) {
+    const K = sources.length;
+    if (K < 1)
+        throw new Error("remember: need ≥ 1 source");
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic class/trait lookup
+    const Cls = sources[0].constructor;
+    const lin = Cls.traits?.linear;
+    if (!lin)
+        throw new Error(`remember: ${Cls.name ?? "?"} has no traits.linear`);
+    const { anchor, feature, seed } = opts;
+    const magnitude = opts.magnitude ?? true;
+    const eps = opts.eps ?? 1e-9;
+    const zero = (vals, a) => vals.map(v => lin.scale(lin.sub(v, a), 0));
+    // Normalized deviations `(vᵢ − anchor) / feature`, refreshed whole while
+    // the feature is non-degenerate; below `eps` the prior shape (or the
+    // seed) is held so a collapse reinflates it.
+    const shapeOf = (vals, a, f, prev) => {
+        if (f <= eps)
+            return prev ?? seed?.(vals) ?? zero(vals, a);
+        const inv = 1 / f;
+        return vals.map(v => lin.scale(lin.sub(v, a), inv));
+    };
+    // biome-ignore lint/suspicious/noExplicitAny: spec is checked structurally
+    return Num.lens(sources, {
+        init: (vals) => {
+            const a = anchor(vals);
+            return { shape: shapeOf(vals, a, feature(vals, a), null) };
+        },
+        step: (vals, c) => {
+            const a = anchor(vals);
+            return { shape: shapeOf(vals, a, feature(vals, a), c.shape) };
+        },
+        fwd: (vals) => feature(vals, anchor(vals)),
+        bwd: (target, vals, c) => {
+            const a = anchor(vals);
+            const f = feature(vals, a);
+            // Magnitude is lossy (|−f| = f): a same-magnitude target re-projects
+            // to the current feature, so the cluster is left put.
+            if (magnitude && Math.abs(target) === f) {
+                return { updates: vals.map(() => undefined), complement: c };
+            }
+            if (f > eps) {
+                const k = target / f;
+                return { updates: vals.map(v => lin.add(a, lin.scale(lin.sub(v, a), k))), complement: c };
+            }
+            return { updates: c.shape.map(s => lin.add(a, lin.scale(s, target))), complement: c };
+        },
+    });
+}
+/** Continuous (winding-aware) lens over a cyclic reading. The complement
+ *  tracks the last emitted value and unwraps each raw reading to the
+ *  nearest representative modulo `period`, so the view follows the source
+ *  across branch cuts instead of jumping a full period. */
+export function continuous(sources, opts) {
+    const { period, raw, apply } = opts;
+    const wrap = (x) => x - period * Math.round(x / period);
+    const unwrap = (rawv, prev) => prev + wrap(rawv - prev);
+    // biome-ignore lint/suspicious/noExplicitAny: spec is checked structurally
+    return Num.lens(sources, {
+        init: (vals) => {
+            const r = raw(vals);
+            return { prev: r.defined ? r.value : 0 };
+        },
+        step: (vals, c) => {
+            const r = raw(vals);
+            return r.defined ? { prev: unwrap(r.value, c.prev) } : c;
+        },
+        fwd: (vals, c) => {
+            const r = raw(vals);
+            return r.defined ? unwrap(r.value, c.prev) : c.prev;
+        },
+        bwd: (target, vals, c) => {
+            const r = raw(vals);
+            if (!r.defined)
+                return { updates: vals.map(() => undefined), complement: { prev: target } };
+            const current = unwrap(r.value, c.prev);
+            return { updates: apply(target, vals, current), complement: { prev: target } };
+        },
+    });
+}

package/dist/core/lenses/typed-factor.d.ts

@@ -0,0 +1,45 @@
+import { type Cell, type Inner, Num, type Read, type Traits, Vec, type Writable } from "../index.js";
+/** Input cell: writable cell whose value class declares the `pack`
+ *  trait. Vec, Num, Pose, Box, Color, Range all satisfy this. */
+export type PackedInput<T = any> = Writable<Read<T> & Traits<T, "pack">>;
+/** Output specification: a target class + a fwd from typed inputs to
+ *  the value the class wraps. Optional analytical Jacobian skips FD. */
+export interface OutputSpec<C extends new (...args: never[]) => Cell<any>> {
+    Cls: C;
+    fwd: (inputs: ReadonlyArray<any>) => Inner<InstanceType<C>>;
+    /** Optional analytical Jacobian. Returns dim(Cls) rows, each of
+     *  length `sum(input pack dims)`. If supplied for ALL outputs, FD
+     *  is skipped entirely → faster AND exact (no eps drift). */
+    jacobian?: (inputs: ReadonlyArray<any>) => readonly (readonly number[])[];
+}
+/** Result type: writable cell per output key, typed by the spec's Cls. */
+export type FactorResult<O extends Record<string, OutputSpec<any>>> = {
+    [K in keyof O]: Writable<InstanceType<O[K]["Cls"]>>;
+};
+export interface FactorOpts {
+    /** Per-input mobility weights. 0 = pinned. Defaults to 1 for all. */
+    inputWeights?: readonly number[];
+    /** Levenberg-Marquardt damping. Default 1e-6. */
+    damping?: number;
+    /** Finite-difference epsilon. Default 1e-5. */
+    eps?: number;
+    /** Auto-iterate the bwd until the written channel's reading is
+     *  within `tol` of target (or `maxIters` exhausted). Cheap when
+     *  forwards are linear (1 iter); needed for non-linear forwards
+     *  to land exactly without user-side loops. Default `false`. */
+    converge?: boolean;
+    /** Max iters when `converge: true`. Default 10. */
+    maxIters?: number;
+    /** Convergence tolerance (per-channel L2). Default 1e-4. */
+    tol?: number;
+}
+export declare function factor<O extends Record<string, OutputSpec<any>>>(inputs: readonly PackedInput[], outputs: O, opts?: FactorOpts): FactorResult<O>;
+export declare function factorTuple<T extends readonly OutputSpec<any>[]>(inputs: readonly PackedInput[], outputs: readonly [...T], opts?: FactorOpts): {
+    [K in keyof T]: Writable<InstanceType<T[K]["Cls"]>>;
+};
+export declare function bundle<T, O extends Record<string, OutputSpec<any>>>(source: Writable<Read<T> & Traits<T, "pack">>, views: O, opts?: FactorOpts): FactorResult<O>;
+export declare function procrustesTyped(points: readonly PackedInput<Inner<Vec>>[]): {
+    centroid: Writable<Vec>;
+    rotation: Writable<Num>;
+    scale: Writable<Num>;
+};