bireactive 0.3.0 → 0.3.2

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

@@ -0,0 +1,100 @@
+import { type Cell, type Inner, type Read, type Writable } from "../cell.js";
+import type { Traits } from "../traits.js";
+import { Num } from "../values/num.js";
+import { Vec } from "../values/vec.js";
+export interface ArgminOpts {
+    /** Finite-difference epsilon for the Jacobian. Default 1e-4. */
+    eps?: number;
+    /** Levenberg-Marquardt damping. Default `1e-6` for `argminNum`
+     *  (Jacobian is always well-conditioned for linear constraints) and
+     *  `1e-3` for `argminVec` (IK chains hit rank-deficient regimes at
+     *  full extension). Larger → smaller, more stable updates; smaller
+     *  → closer to pure pseudoinverse. */
+    damping?: number;
+}
+/** Target-shaping for `argminVec`: project a write into the reachable
+ *  workspace before the Jacobian step, sidestepping the rank-deficient
+ *  swings at the boundary. For an N-link chain rooted at `R` with reach
+ *  `L`, pass `clampToDisc(R, L)`. */
+export interface ArgminVecOpts extends ArgminOpts {
+    /** Pre-write hook: transform the requested target into one that's
+     *  guaranteed solvable. Most useful as a workspace clamp. */
+    clampTarget?: (target: {
+        x: number;
+        y: number;
+    }, currentInputs: readonly number[]) => {
+        x: number;
+        y: number;
+    };
+}
+/** Project `p` into the closed disc of radius `r` centred on `c` (points
+ *  inside pass through). Use as `argminVec`'s `clampTarget` to fix IK
+ *  explosion at maximum reach. */
+export declare function clampToDisc(c: {
+    x: number;
+    y: number;
+}, r: number): (p: {
+    x: number;
+    y: number;
+}) => {
+    x: number;
+    y: number;
+};
+/** Scalar-output argmin lens: write does one Newton step against the FD
+ *  Jacobian, distributing the residual by `weights`. For typed/multi-
+ *  output cases use `factor()`; this M=1 path is kept for its hand-rolled
+ *  inner loop. */
+export declare function argminNum(inputs: readonly Num[], forward: (xs: readonly number[]) => number, weights: readonly number[], opts?: ArgminOpts): Writable<Num>;
+/** 2D-output argmin lens (scalar Num inputs, `{x, y}` forward). For IK
+ *  arms, draggable points, handle projection. Kept for its hand-rolled
+ *  2×2 inverse + `clampTarget` hook; see `factor()` for other M. */
+export declare function argminVec(inputs: readonly Num[], forward: (xs: readonly number[]) => {
+    x: number;
+    y: number;
+}, weights: readonly number[], opts?: ArgminVecOpts): Writable<Vec>;
+/** 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 Euclidean). Default 1e-4. */
+    tol?: number;
+}
+/** Factor packed inputs into a named record of coupled writable outputs.
+ *  Each output is `{ Cls, fwd }`; writing one solves the Jacobian LSQ for the
+ *  input deltas. See `bundle` for the 1→M case, `factorTuple` for positional. */
+export declare function factor<O extends Record<string, OutputSpec<any>>>(inputs: readonly PackedInput[], outputs: O, opts?: FactorOpts): FactorResult<O>;
+/** Positional `factor`: outputs are a tuple of specs, result a tuple of
+ *  writables. Terser to destructure but order-sensitive. */
+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"]>>;
+};
+/** A single typed source factored into M coupled views: `factor` with one
+ *  input. Writing a view solves the (small) Jacobian over the source's pack. */
+export declare function bundle<T, O extends Record<string, OutputSpec<any>>>(source: Writable<Read<T> & Traits<T, "pack">>, views: O, opts?: FactorOpts): FactorResult<O>;

package/dist/core/lenses/{typed-factor.js → numerical.js}

@@ -1,27 +1,134 @@
-// typed-factor.ts — generic heterogeneous-output factor lens.
-//
-// The numerical N→M escape hatch: typed inputs/outputs via the `Pack`
-// trait. Inputs and outputs are flat-packed; the Jacobian is the full
-// M×N matrix; writing one channel sends a sparse δy through the LSQ
-// pseudoinverse. Invariance is approximate (the Jacobian path) — use
-// closed-form lenses like `procrustes` when an exact one exists.
-//
-//   const { centroid, rotation, scale } = factor([v1, v2, v3] as const, {
-//     centroid: { Cls: Vec, fwd: pts => … },
-//     rotation: { Cls: Num, fwd: pts => atan2(…) },
-//     scale:    { Cls: Num, fwd: pts => hypot(…) },
-//   });
-//   centroid.value = { x: 100, y: 50 };  // typed
-//
-// `bundle()` is the 1→M case: `factor()` over a single typed source.
-import { SKIP } from "../index.js";
+// Numerical lenses: writes solve a finite-differenced Jacobian (one Newton
+// step, Levenberg-Marquardt damped) rather than a closed form, so invariance
+// is approximate — prefer the exact lenses (point-cloud.ts, aggregates.ts)
+// when one fits. `argminNum`/`argminVec` are hand-rolled M=1/M=2 forms;
+// `factor` is the typed N→M generalization over the `Pack` trait.
+import { SKIP } from "../cell.js";
 import { solveSPD } from "../linalg.js";
+import { Num } from "../values/num.js";
+import { Vec } from "../values/vec.js";
+/** Project `p` into the closed disc of radius `r` centred on `c` (points
+ *  inside pass through). Use as `argminVec`'s `clampTarget` to fix IK
+ *  explosion at maximum reach. */
+export function clampToDisc(c, r) {
+    return p => {
+        const dx = p.x - c.x;
+        const dy = p.y - c.y;
+        const d = Math.hypot(dx, dy);
+        if (d <= r)
+            return p;
+        const k = r / d;
+        return { x: c.x + dx * k, y: c.y + dy * k };
+    };
+}
+/** Scalar-output argmin lens: write does one Newton step against the FD
+ *  Jacobian, distributing the residual by `weights`. For typed/multi-
+ *  output cases use `factor()`; this M=1 path is kept for its hand-rolled
+ *  inner loop. */
+export function argminNum(inputs, forward, weights, opts = {}) {
+    if (weights.length !== inputs.length) {
+        throw new Error("argminNum: weights/inputs length mismatch");
+    }
+    const eps = opts.eps ?? 1e-4;
+    const damping = opts.damping ?? 1e-6;
+    const n = inputs.length;
+    // Pre-allocated to avoid per-write allocations.
+    const J = new Array(n);
+    const out = new Array(n);
+    return Num.lens(inputs, vals => forward(vals), (target, vals) => {
+        const xs = vals;
+        const y0 = forward(xs);
+        const dy = target - y0;
+        for (let i = 0; i < n; i++) {
+            const saved = xs[i];
+            xs[i] = saved + eps;
+            J[i] = (forward(xs) - y0) / eps;
+            xs[i] = saved;
+        }
+        let denom = damping;
+        for (let i = 0; i < n; i++)
+            denom += weights[i] * J[i] * J[i];
+        const k = dy / denom;
+        for (let i = 0; i < n; i++) {
+            if (weights[i] === 0) {
+                out[i] = SKIP;
+            }
+            else {
+                out[i] = xs[i] + weights[i] * J[i] * k;
+            }
+        }
+        return out;
+    });
+}
+/** 2D-output argmin lens (scalar Num inputs, `{x, y}` forward). For IK
+ *  arms, draggable points, handle projection. Kept for its hand-rolled
+ *  2×2 inverse + `clampTarget` hook; see `factor()` for other M. */
+export function argminVec(inputs, forward, weights, opts = {}) {
+    if (weights.length !== inputs.length) {
+        throw new Error("argminVec: weights/inputs length mismatch");
+    }
+    const eps = opts.eps ?? 1e-4;
+    const damping = opts.damping ?? 1e-3;
+    const clamp = opts.clampTarget;
+    const n = inputs.length;
+    // Pre-allocated to avoid per-write allocations.
+    const Jx = new Array(n);
+    const Jy = new Array(n);
+    const out = new Array(n);
+    return Vec.lens(inputs, vals => forward(vals), (rawTarget, vals) => {
+        const xs = vals;
+        const target = clamp ? clamp(rawTarget, xs) : rawTarget;
+        const y0 = forward(xs);
+        const dx = target.x - y0.x;
+        const dy = target.y - y0.y;
+        for (let i = 0; i < n; i++) {
+            const saved = xs[i];
+            xs[i] = saved + eps;
+            const ye = forward(xs);
+            xs[i] = saved;
+            Jx[i] = (ye.x - y0.x) / eps;
+            Jy[i] = (ye.y - y0.y) / eps;
+        }
+        // J·W·Jᵀ is the 2×2 [a b; b c]. Add damping to the diagonal, invert.
+        let a = damping;
+        let b = 0;
+        let c = damping;
+        for (let i = 0; i < n; i++) {
+            const w = weights[i];
+            a += w * Jx[i] * Jx[i];
+            b += w * Jx[i] * Jy[i];
+            c += w * Jy[i] * Jy[i];
+        }
+        const det = a * c - b * b;
+        if (Math.abs(det) < 1e-14) {
+            // Singular; leave inputs unchanged.
+            for (let i = 0; i < n; i++)
+                out[i] = SKIP;
+            return out;
+        }
+        const invA = c / det;
+        const invB = -b / det;
+        const invC = a / det;
+        const kx = invA * dx + invB * dy;
+        const ky = invB * dx + invC * dy;
+        for (let i = 0; i < n; i++) {
+            const w = weights[i];
+            if (w === 0) {
+                out[i] = SKIP;
+            }
+            else {
+                out[i] = xs[i] + w * (Jx[i] * kx + Jy[i] * ky);
+            }
+        }
+        return out;
+    });
+}
 function getPack(cell) {
     const ctor = cell.constructor;
     const p = ctor.traits?.pack;
     if (!p) {
         const name = ctor.name ?? "?";
-        throw new Error(`typed-factor: ${name} has no traits.pack`);
+        throw new Error(`numerical: ${name} has no traits.pack`);
     }
     return p;
 }
@@ -29,7 +136,7 @@ function getPackFromCls(Cls) {
     const p = Cls.traits?.pack;
     if (!p) {
         const name = Cls.name ?? "?";
-        throw new Error(`typed-factor: ${name} has no traits.pack`);
+        throw new Error(`numerical: ${name} has no traits.pack`);
     }
     return p;
 }
@@ -42,10 +149,13 @@ function cumOffsets(dims) {
     }
     return out;
 }
+/** Factor packed inputs into a named record of coupled writable outputs.
+ *  Each output is `{ Cls, fwd }`; writing one solves the Jacobian LSQ for the
+ *  input deltas. See `bundle` for the 1→M case, `factorTuple` for positional. */
 export function factor(inputs, outputs, opts = {}) {
     const inputCount = inputs.length;
     if (inputCount === 0) {
-        throw new Error("typed-factor: need ≥ 1 input");
+        throw new Error("numerical: need ≥ 1 input");
     }
     const inputPacks = inputs.map(s => getPack(s));
     const inputDims = inputPacks.map(p => p.dim);
@@ -62,7 +172,7 @@ export function factor(inputs, outputs, opts = {}) {
     const outputKeys = Object.keys(outputs);
     const outputCount = outputKeys.length;
     if (outputCount === 0) {
-        throw new Error("typed-factor: need ≥ 1 output");
+        throw new Error("numerical: need ≥ 1 output");
     }
     const outputSpecs = outputKeys.map(k => outputs[k]);
     const outputPacks = outputSpecs.map(s => getPackFromCls(s.Cls));
@@ -71,7 +181,7 @@ export function factor(inputs, outputs, opts = {}) {
     const M = outputDims.reduce((s, d) => s + d, 0);
     const weights = opts.inputWeights ?? Array.from({ length: N }, () => 1);
     if (weights.length !== N) {
-        throw new Error(`typed-factor: inputWeights length ${weights.length} ≠ flat input dim ${N}`);
+        throw new Error(`numerical: inputWeights length ${weights.length} ≠ flat input dim ${N}`);
     }
     const eps = opts.eps ?? 1e-5;
     const lambda = opts.damping ?? 1e-6;
@@ -233,11 +343,8 @@ export function factor(inputs, outputs, opts = {}) {
     }
     return result;
 }
-// factorTuple — positional API.
-//
-// Same engine, no names. Outputs are a tuple of specs; the result is a
-// tuple of writables. Terser to destructure, but order-sensitive and
-// loses self-documenting names.
+/** Positional `factor`: outputs are a tuple of specs, result a tuple of
+ *  writables. Terser to destructure but order-sensitive. */
 export function factorTuple(inputs, outputs, opts = {}) {
     // Wrap to named, call factor, unwrap (one-time setup; hot path identical).
     // biome-ignore lint/suspicious/noExplicitAny: variance escape
@@ -247,11 +354,8 @@ export function factorTuple(inputs, outputs, opts = {}) {
     const result = factor(inputs, named, opts);
     return outputs.map((_, i) => result[String(i)]);
 }
-// bundle — 1→M dual, sugar over factor() with one input.
-//
-// A single typed source factored into M coupled views — `factor()` with
-// a length-1 input array. Writing a view sends a sparse δy through the
-// Jacobian solve (small, since N = the source's pack dim).
+/** A single typed source factored into M coupled views: `factor` with one
+ *  input. Writing a view solves the (small) Jacobian over the source's pack. */
 export function bundle(source, views, opts = {}) {
     // factor() takes an input array, so pass [source] and wrap each view's
     // fwd to receive the single-element array form.
@@ -271,5 +375,3 @@ export function bundle(source, views, opts = {}) {
     }
     return factor([source], wrapped, opts);
 }
-// For field-style bundles, `field()` already covers the independent case;
-// use `bundle()` when you want coupled writes through the Jacobian solve.

package/dist/core/lenses/point-cloud.d.ts

@@ -0,0 +1,67 @@
+import { type Cell, Num, type Read, type Traits, Vec, type Writable } from "../index.js";
+type V = {
+    x: number;
+    y: number;
+};
+/** Writable angle from `pivot` to `points[0]`; write rotates every input
+ *  about `pivot` by (target − current) via its `Pivotal` trait (Vec rotates
+ *  position, Pose also rotates orientation). `pivot` is reactive; pass
+ *  `mean(points)` to rotate about the cluster's own centroid. */
+export declare function rotateAbout<T extends {
+    x: number;
+    y: number;
+}>(points: readonly Writable<Traits<T, "pivotal"> & Cell<T>>[], pivot: Read<V>): Writable<Num>;
+/** Writable radial distance from pivot to `points[0]`; write scales every
+ *  input radially about `pivot` (negative target reflects). The complement
+ *  carries per-point offsets from the pivot, so a collapse onto it (radius
+ *  ≈ 0) reinflates from the stored shape. Pose `theta` survives. */
+export declare function scaleAbout<T extends {
+    x: number;
+    y: number;
+}>(points: readonly Writable<Traits<T, "pivotal"> & Cell<T>>[], pivot: Read<V>): Writable<Num>;
+/** Per-axis scale about a pivot (Vec-specific). The complement carries
+ *  per-point per-axis fractions of point 0's offset, so a per-axis collapse
+ *  is recoverable. */
+export declare function scaleAboutXY(points: readonly Writable<Vec>[], pivot: Read<V>): Writable<Vec>;
+/** K points → {point: centroid, direction: principal-axis angle}. Writing
+ *  `point` translates; writing `direction` rotates all about the centroid. */
+export declare function bestFitLine(points: readonly Writable<Vec>[]): {
+    point: Writable<Vec>;
+    direction: Writable<Num>;
+};
+/** K points → {center: centroid, radius: mean distance from center}. Writing
+ *  `center` translates; writing `radius` scales all about the center. */
+export declare function bestFitCircle(points: readonly Writable<Vec>[]): {
+    center: Writable<Vec>;
+    radius: Writable<Num>;
+};
+/** K points → {mean: centroid, rotation: dominant-eigenvector angle,
+ *  majorLength/minorLength: per-axis std-devs (√λ)}. Each write is a single
+ *  group action about the mean, so all pairs are cross-channel invariant. */
+export declare function pca(points: readonly Writable<Vec>[]): {
+    mean: Writable<Vec>;
+    rotation: Writable<Num>;
+    majorLength: Writable<Num>;
+    minorLength: Writable<Num>;
+};
+/** Writable total over K parts; write scales all parts proportionally,
+ *  preserving their ratios. A collapse to zero reinflates the stored ratios,
+ *  seeded uniform so an all-zero start splits evenly. */
+export declare function total(parts: readonly Writable<Num>[]): Writable<Num>;
+/** K Vecs → {centroid, rotation (angle of point[0] about centroid), scale
+ *  (its distance from centroid)}. Each write is a closed-form transform about
+ *  the centroid (translate / rotate / scale), so the three are cross-channel
+ *  invariant. A collapsed cluster makes rotation singular and scale a no-op. */
+export declare function procrustes(points: readonly Writable<Vec>[]): {
+    centroid: Writable<Vec>;
+    rotation: Writable<Num>;
+    scale: Writable<Num>;
+};
+/** K Vecs → {center, size} of the axis-aligned bounding box. Writing `center`
+ *  translates; writing `size` scales all about the center per-axis. Degenerate
+ *  axes (size = 0) write as no-ops; negative size reflects. */
+export declare function bbox(points: readonly Writable<Vec>[]): {
+    center: Writable<Vec>;
+    size: Writable<Vec>;
+};
+export {};