bireactive 0.2.0 → 0.2.1

package/dist/core/lenses/closed-form-policies.js

@@ -6,11 +6,11 @@
 // line/circle, and PCA decompose into combinations of them.
 //
 // Layout: building-block actions (rigidTranslate, rotateAbout,
-// scaleAbout, scaleAboutXY), Procrustes re-expressed via them, then
-// closed-form decompositions (bestFitLine, bestFitCircle, pcaLens,
-// totalLens). All exact, idempotent, cross-channel invariant by
-// construction, on the same `Cls.lens` machinery — no engine changes.
-import { centroidLens, Num, Vec, } from "../index.js";
+// scaleAbout, scaleAboutXY), then closed-form decompositions
+// (bestFitLine, bestFitCircle, pca, total). All exact, idempotent,
+// cross-channel invariant by construction, on the same `Cls.lens`
+// machinery — no engine changes.
+import { mean, Num, Vec, } from "../index.js";
 import { continuous, remember } from "./memory.js";
 // Pivotal trait lookup via the value class's `static traits.pivotal` slot.
 // biome-ignore lint/suspicious/noExplicitAny: dynamic trait lookup
@@ -25,9 +25,9 @@ function pivotalOf(input) {
     return p;
 }
 /** Writable centroid; on write, translates every point by the delta.
- *  Alias of `centroidLens` under the "policy" naming. */
+ *  The Vec-specific group-action reading of `mean`. */
 export function rigidTranslate(points) {
-    return centroidLens(points);
+    return mean(points);
 }
 /** Writable angle from `pivot` to `points[0]`; write rotates every input
  *  about `pivot` by (target − current) via its `Pivotal` trait.
@@ -35,7 +35,7 @@ export function rigidTranslate(points) {
  *  Trait-generic: Vec rotates position; Pose rotates position AND
  *  orientation. Rotation-about-pivot fixes the pivot and preserves radial
  *  distances, so scale-about-pivot reads unchanged. `pivot` is reactive
- *  (re-read per write); pass `centroidLens(points)` for rotation about
+ *  (re-read per write); pass `rigidTranslate(points)` for rotation about
  *  the cluster's own centroid. */
 export function rotateAbout(points, pivot) {
     const K = points.length;
@@ -153,16 +153,6 @@ export function scaleAboutXY(points, pivot) {
         },
     });
 }
-/** Same semantics as `factor-lens.ts`'s `procrustesLens`, decomposed
- *  into three building-block lenses sharing a centroid. */
-export function procrustesViaBuildingBlocks(points) {
-    if (points.length < 2)
-        throw new Error("procrustes: need ≥ 2 points");
-    const centroid = rigidTranslate(points);
-    const rotation = rotateAbout(points, centroid);
-    const scale = scaleAbout(points, centroid);
-    return { centroid, rotation, scale };
-}
 // Best-fit line.
 //
 // K points → {point: centroid, direction: principal-axis angle}.
@@ -188,7 +178,7 @@ function covariance(points, cx, cy) {
     }
     return { cxx: cxx / K, cxy: cxy / K, cyy: cyy / K };
 }
-export function bestFitLineLens(points) {
+export function bestFitLine(points) {
     const K = points.length;
     if (K < 2)
         throw new Error("bestFitLine: need ≥ 2 points");
@@ -242,7 +232,7 @@ export function bestFitLineLens(points) {
 //   write radius → scale all about center by target/current
 // Simplest closed-form fit (mean center). Invariance: translation
 // preserves radii; uniform scale-about-center preserves the center.
-export function bestFitCircleLens(points) {
+export function bestFitCircle(points) {
     const K = points.length;
     if (K < 1)
         throw new Error("bestFitCircle: need ≥ 1 point");
@@ -280,10 +270,10 @@ export function bestFitCircleLens(points) {
 //   write major/minor → scale along that axis by target/current
 // Each write is a single group action; cross-channel invariance holds
 // for all pairs.
-export function pcaLens(points) {
+export function pca(points) {
     const K = points.length;
     if (K < 2)
-        throw new Error("pcaLens: need ≥ 2 points");
+        throw new Error("pca: need ≥ 2 points");
     const mean = rigidTranslate(points);
     // 2×2 symmetric eigendecomp → {θ, λ_major, λ_minor}; null when fully
     // collapsed (λ_major ≈ 0).
@@ -430,10 +420,10 @@ export function pcaLens(points) {
  *  preserving their ratios. A `remember` anchored at zero with a signed
  *  sum feature: a collapse to zero reinflates the stored ratios, seeded
  *  uniform so an all-zero start splits evenly. */
-export function totalLens(parts) {
+export function total(parts) {
     const K = parts.length;
     if (K < 1)
-        throw new Error("totalLens: need ≥ 1 part");
+        throw new Error("total: need ≥ 1 part");
     return remember(parts, {
         anchor: () => 0,
         feature: (vals) => {

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

@@ -0,0 +1,14 @@
+import { Num, Vec, type Writable } from "../index.js";
+export declare function meanDiff(a: Num, b: Num): {
+    mean: Writable<Num>;
+    diff: Writable<Num>;
+};
+export declare function procrustes(points: readonly Writable<Vec>[]): {
+    centroid: Writable<Vec>;
+    rotation: Writable<Num>;
+    scale: Writable<Num>;
+};
+export declare function bbox(points: readonly Writable<Vec>[]): {
+    center: Writable<Vec>;
+    size: Writable<Vec>;
+};

package/dist/core/lenses/decompositions.js

@@ -0,0 +1,224 @@
+// decompositions.ts — closed-form N→M lens decompositions (Vec/Num).
+//
+// N inputs → M coupled writable outputs, where writing one output
+// preserves the readings of the other M−1 (cross-channel invariance).
+// Each bwd is a hand-rolled group action (translate / rotate / scale
+// about the centroid), so cross-channel invariance is EXACT and one
+// write lands in O(K). For the generic numerical N→M escape hatch (when
+// no closed form fits) see `factor` in `typed-factor.ts`.
+import { Num, Vec } from "../index.js";
+// meanDiff — 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.
+export function meanDiff(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 };
+}
+// procrustes — 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. 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 procrustes(points) {
+    const K = points.length;
+    if (K < 2)
+        throw new Error("procrustes: 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 };
+}
+// bbox — 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 bbox(points) {
+    const K = points.length;
+    if (K < 1)
+        throw new Error("bbox: 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 };
+}

package/dist/core/lenses/domain-aggregates.d.ts

@@ -1,9 +1,7 @@
 import { type Cell, Num, type Read, type Traits, type Val, Vec, type Writable } from "../index.js";
-/** Class-inferring mean (writable of `inputs[0]`'s class). Needs `linear`. */
-export declare function meanOf<S extends Traits<any, "linear">>(inputs: readonly Writable<S>[]): Writable<S>;
-/** Rigid-translate aggregate over any Linear type. Alias of `meanOf`,
- *  named for the geometric intent. */
-export declare function rigidTranslateOf<S extends Traits<any, "linear">>(inputs: readonly Writable<S>[]): Writable<S>;
+/** Equal-weight mean (writable of `inputs[0]`'s class); writes distribute
+ *  the delta evenly. Class inferred from the first input; needs `linear`. */
+export declare function mean<S extends Traits<any, "linear">>(inputs: readonly Writable<S>[]): Writable<S>;
 /** Weighted blend of K branches over any `Linear` type. See module note. */
 export declare function mix<S extends Traits<any, "linear">>(weights: readonly Val<number>[], branches: readonly Writable<S>[]): Writable<S>;
 /** Two-branch router (mix simplex *vertex*): reads the live branch, writes
@@ -13,15 +11,6 @@ export declare function select<S extends Traits<any, "linear">>(cond: Read<boole
 /** Two-branch crossfade (mix simplex *edge*): `lerp(a, b, t)`. Writing
  *  keeps `t` fixed and splits the delta by influence. */
 export declare function crossfade<S extends Traits<any, "linear">>(t: Read<number>, a: Writable<S>, b: Writable<S>): Writable<S>;
-type ColorV = {
-    r: number;
-    g: number;
-    b: number;
-    a: number;
-};
-/** Mean color of a palette; write shifts every color by the delta
- *  (rigid translate in RGBA). Via `meanOf`. */
-export declare function meanColor(colors: readonly Writable<Traits<ColorV, "linear">>[]): Writable<Traits<ColorV, "linear">>;
 /** Mean radial distance from the centroid; write scales the cluster's
  *  deviations so the new mean matches the target. Trait-driven via
  *  `Linear` + `Metric`, so it works for any class declaring both (Vec,
@@ -32,23 +21,22 @@ export declare function meanColor(colors: readonly Writable<Traits<ColorV, "line
  *  and a collapse (spread → 0) reinflates the original SHAPE. Centroid is
  *  recomputed every read/write, so an intervening mean translate is not
  *  stale. */
-export declare function spreadOf<T extends NonNullable<unknown>, S extends Cell<T> & Traits<T, "linear" | "metric">>(inputs: readonly Writable<S>[]): Writable<Num>;
-/** Palette decomposition: K values → {mean, spread}, i.e. centroid +
- *  uniform scale about it. `meanOf` ∘ `spreadOf`; works for any
- *  Linear + Metric class. */
-export declare function paletteLens<T extends NonNullable<unknown>, S extends Cell<T> & Traits<T, "linear" | "metric">>(colors: readonly Writable<S>[]): {
+export declare function spread<T extends NonNullable<unknown>, S extends Cell<T> & Traits<T, "linear" | "metric">>(inputs: readonly Writable<S>[]): Writable<Num>;
+/** Mean/spread decomposition: K values → {mean, spread}, i.e. centroid +
+ *  uniform scale about it. `mean` ∘ `spread`; works for any
+ *  Linear + Metric class (palettes, point clouds, poses, …). */
+export declare function meanSpread<T extends NonNullable<unknown>, S extends Cell<T> & Traits<T, "linear" | "metric">>(colors: readonly Writable<S>[]): {
     mean: Writable<S>;
     spread: Writable<Num>;
 };
-export declare function bezierGestaltLens(p0: Writable<Vec>, p1: Writable<Vec>, p2: Writable<Vec>, p3: Writable<Vec>): {
+export declare function bezierGestalt(p0: Writable<Vec>, p1: Writable<Vec>, p2: Writable<Vec>, p3: Writable<Vec>): {
     start: Writable<Vec>;
     end: Writable<Vec>;
     startTangent: Writable<Vec>;
     endTangent: Writable<Vec>;
 };
 /** Time-series scalar aggregate over Num values as (i, value_i) samples. */
-export declare function timeSeriesLens(values: readonly Writable<Num>[]): {
+export declare function timeSeries(values: readonly Writable<Num>[]): {
     mean: Writable<Num>;
     slope: Writable<Num>;
 };
-export {};

package/dist/core/lenses/domain-aggregates.js

@@ -1,30 +1,30 @@
 // domain-aggregates.ts — closed-form lenses beyond point clouds.
 //
 // The group-action patterns from `closed-form-policies.ts`, applied to:
-//   (1) Generic Linear/Metric-trait aggregates — `meanOf`, `spreadOf`,
-//       `paletteLens` work for colors, poses, ranges, boxes for free.
-//   (2) Color aggregates — `meanColor`.
-//   (3) Bezier gestalt handles ({start, end, startTangent, endTangent}).
-//   (4) Time-series ({mean, slope}) over (i, value) samples.
+//   (1) Generic Linear/Metric-trait aggregates — `mean`, `spread`,
+//       `palette` work for colors, poses, ranges, boxes for free.
+//   (2) Bezier gestalt handles ({start, end, startTangent, endTangent}).
+//   (3) Time-series ({mean, slope}) over (i, value) samples.
 // All exact, idempotent, cross-channel invariant by construction.
 import { Num, reader, Vec, } from "../index.js";
 import { remember } from "./memory.js";
 // Generic Linear-trait aggregates.
 //
-// Ergonomic entry points over `meanLens` / `scaleAbout` that infer the
-// value class from the first input (`meanOf(colors)` vs
-// `meanLens(Color, colors)`). Same engine, no new infrastructure.
-/** Class-inferring mean (writable of `inputs[0]`'s class). Needs `linear`. */
+// Ergonomic entry points that infer the value class from the first input
+// (`mean(colors)` works for any `linear` class). Same engine, no new
+// infrastructure.
+/** Equal-weight mean (writable of `inputs[0]`'s class); writes distribute
+ *  the delta evenly. Class inferred from the first input; needs `linear`. */
 // biome-ignore lint/suspicious/noExplicitAny: variance escape
-export function meanOf(inputs) {
+export function mean(inputs) {
     if (inputs.length === 0)
-        throw new Error("meanOf: need ≥ 1 input");
+        throw new Error("mean: need ≥ 1 input");
     // biome-ignore lint/suspicious/noExplicitAny: dynamic class lookup
     const Cls = inputs[0].constructor;
     // biome-ignore lint/suspicious/noExplicitAny: dynamic trait lookup
     const lin = Cls.traits?.linear;
     if (!lin)
-        throw new Error(`meanOf: ${Cls.name ?? "?"} has no traits.linear`);
+        throw new Error(`mean: ${Cls.name ?? "?"} has no traits.linear`);
     const n = inputs.length;
     const inv = 1 / n;
     // biome-ignore lint/suspicious/noExplicitAny: variance escape on Cls.lens
@@ -49,15 +49,9 @@ export function meanOf(inputs) {
         return out;
     });
 }
-/** Rigid-translate aggregate over any Linear type. Alias of `meanOf`,
- *  named for the geometric intent. */
-// biome-ignore lint/suspicious/noExplicitAny: variance escape
-export function rigidTranslateOf(inputs) {
-    return meanOf(inputs);
-}
 // Weighted blend (the mix simplex).
 //
-// `mix` is `meanOf` with the uniform-weight assumption lifted: the read
+// `mix` is `mean` with the uniform-weight assumption lifted: the read
 // is the normalized weighted sum `Σ wᵢ·aᵢ`, the write is the minimum-norm
 // delta `daᵢ = wᵢ·δ / Σwⱼ²` (the pseudoinverse of `wᵀ·da = δ`), so a
 // zero-weight branch is left untouched. Weights are read-only controls —
@@ -66,7 +60,7 @@ export function rigidTranslateOf(inputs) {
 //
 // The control lives on the K-simplex: a one-hot vertex is `select`
 // (the live branch absorbs everything), a `(1−t, t)` edge is `crossfade`,
-// uniform weights recover `meanOf`. Reactive weights are dynamically
+// uniform weights recover `mean`. Reactive weights are dynamically
 // tracked (read via `.value` inside fwd), so flipping a Bool or sliding a
 // Num re-reads with no extra wiring.
 /** Weighted blend of K branches over any `Linear` type. See module note. */
@@ -131,11 +125,6 @@ export function select(cond, whenFalse, whenTrue) {
 export function crossfade(t, a, b) {
     return mix([Num.derive(() => 1 - t.value), Num.derive(() => t.value)], [a, b]);
 }
-/** Mean color of a palette; write shifts every color by the delta
- *  (rigid translate in RGBA). Via `meanOf`. */
-export function meanColor(colors) {
-    return meanOf(colors);
-}
 /** Mean radial distance from the centroid; write scales the cluster's
  *  deviations so the new mean matches the target. Trait-driven via
  *  `Linear` + `Metric`, so it works for any class declaring both (Vec,
@@ -146,16 +135,16 @@ export function meanColor(colors) {
  *  and a collapse (spread → 0) reinflates the original SHAPE. Centroid is
  *  recomputed every read/write, so an intervening mean translate is not
  *  stale. */
-export function spreadOf(inputs) {
+export function spread(inputs) {
     const K = inputs.length;
     if (K < 1)
-        throw new Error("spreadOf: need ≥ 1 input");
+        throw new Error("spread: need ≥ 1 input");
     // biome-ignore lint/suspicious/noExplicitAny: dynamic class lookup
     const Cls = inputs[0].constructor;
     const lin = Cls.traits?.linear;
     const met = Cls.traits?.metric;
     if (!lin || !met) {
-        throw new Error(`spreadOf: ${Cls.name ?? "?"} needs Linear + Metric`);
+        throw new Error(`spread: ${Cls.name ?? "?"} needs Linear + Metric`);
     }
     const inv = 1 / K;
     const centroid = (vals) => {
@@ -178,16 +167,16 @@ export function spreadOf(inputs) {
         feature: (vals, ctr) => meanSpread(vals, ctr),
     });
 }
-/** Palette decomposition: K values → {mean, spread}, i.e. centroid +
- *  uniform scale about it. `meanOf` ∘ `spreadOf`; works for any
- *  Linear + Metric class. */
-export function paletteLens(colors) {
+/** Mean/spread decomposition: K values → {mean, spread}, i.e. centroid +
+ *  uniform scale about it. `mean` ∘ `spread`; works for any
+ *  Linear + Metric class (palettes, point clouds, poses, …). */
+export function meanSpread(colors) {
     return {
-        mean: meanOf(colors),
-        spread: spreadOf(colors),
+        mean: mean(colors),
+        spread: spread(colors),
     };
 }
-export function bezierGestaltLens(p0, p1, p2, p3) {
+export function bezierGestalt(p0, p1, p2, p3) {
     const start = Vec.lens([p0, p1], (vals) => vals[0], (target, vals) => {
         const dx = target.x - vals[0].x;
         const dy = target.y - vals[0].y;
@@ -210,7 +199,7 @@ export function bezierGestaltLens(p0, p1, p2, p3) {
 // mean and slope are invariant under each other (a y-shift preserves
 // slope; tilting about the mean preserves the mean).
 /** Time-series scalar aggregate over Num values as (i, value_i) samples. */
-export function timeSeriesLens(values) {
+export function timeSeries(values) {
     const N = values.length;
     if (N < 2)
         throw new Error("timeSeries: need ≥ 2 values");
@@ -254,6 +243,3 @@ export function timeSeriesLens(values) {
     });
     return { mean, slope };
 }
-// `meanOf` / `rigidTranslateOf` / `spreadOf` are fully trait-driven
-// (Linear, Metric); `bezierGestalt` and `timeSeries` stay value-specific
-// (Vec / Num) since their operations don't benefit from the trait layer.

package/dist/core/{new-primitives.d.ts → lenses/geometry.d.ts}

@@ -1,19 +1,20 @@
-import type { Cell, Writable } from "./signal.js";
-import { Num } from "./values/num.js";
-import { Vec } from "./values/vec.js";
+import type { Cell, Read, Writable } from "../cell.js";
+import { Num } from "../values/num.js";
+import { Vec } from "../values/vec.js";
 type V = {
     x: number;
     y: number;
 };
-/** Distance between two Vecs. RO — the inverse isn't unique. For a
- *  writable variant see `radialLens`. */
-export declare function distanceLens(a: Cell<V>, b: Cell<V>): Num;
-/** Angle from `a` to `b`, in radians. RO. */
-export declare function angleLens(a: Cell<V>, b: Cell<V>): Num;
+/** Distance between two Vecs; writing scales them symmetrically about
+ *  their midpoint (collapse to 0 reinflates the last direction). */
+export declare function distance(a: Writable<Vec>, b: Writable<Vec>): Writable<Num>;
+/** Angle from `a` to `b`, in radians; writing rotates `b` about `a`
+ *  (a fixed, separation preserved). */
+export declare function angle(a: Read<V>, b: Writable<Vec>): Writable<Num>;
 /** Reflect `point` across the line through `axisStart`/`axisEnd`. Writes
  *  the reflected position back to `point` (axis unchanged); reflection is
  *  involutive, so the same formula reads and writes. */
-export declare function reflectionLens(point: Cell<V>, axisStart: Cell<V>, axisEnd: Cell<V>): Writable<Vec>;
+export declare function reflection(point: Cell<V>, axisStart: Cell<V>, axisEnd: Cell<V>): Writable<Vec>;
 /** Lerp between two Vecs at parameter `t`. Writing the interpolated point
  *  shifts both endpoints rigidly (preserving t). */
 export declare function vecLerp(a: Cell<V>, b: Cell<V>, t: Cell<number>): Writable<Vec>;
@@ -22,12 +23,8 @@ export declare function vecLerp(a: Cell<V>, b: Cell<V>, t: Cell<number>): Writab
 export declare function pulleySum(a: Num, b: Num): Writable<Num>;
 /** Difference of two nums: `a - b`. Writing the difference shifts
  *  both inputs symmetrically by ±half-delta. */
-export declare function diffLens(a: Num, b: Num): Writable<Num>;
+export declare function diff(a: Num, b: Num): Writable<Num>;
 /** Mean of N nums, clamped to `[lo, hi]` on read and write (writes are
  *  clamped before the delta is distributed). */
 export declare function clampedMean(parents: readonly Num[], lo: number, hi: number): Writable<Num>;
-/** Quadratic Bézier point at parameter `t`. RO. */
-export declare function bezier2(p0: Cell<V>, p1: Cell<V>, p2: Cell<V>, t: Cell<number>): Vec;
-/** Cubic Bézier point at parameter `t`. RO. */
-export declare function bezier3(p0: Cell<V>, p1: Cell<V>, p2: Cell<V>, p3: Cell<V>, t: Cell<number>): Vec;
 export {};

package/dist/core/{new-primitives.js → lenses/geometry.js}

@@ -1,20 +1,30 @@
-// new-primitives.ts — building blocks over the N-input `Cls.lens` /
-// `Cls.derive` forms. All are a few lines on top of the engine.
-import { Num } from "./values/num.js";
-import { Vec } from "./values/vec.js";
-/** Distance between two Vecs. RO — the inverse isn't unique. For a
- *  writable variant see `radialLens`. */
-export function distanceLens(a, b) {
-    return Num.derive([a, b], vals => Math.hypot(vals[0].x - vals[1].x, vals[0].y - vals[1].y));
+// geometry.ts — geometric lens building blocks over the N-input
+// `Cls.lens` / `Cls.derive` forms. All are a few lines on top of the engine.
+import { Num } from "../values/num.js";
+import { Vec } from "../values/vec.js";
+import { rotateAbout } from "./closed-form-policies.js";
+import { remember } from "./memory.js";
+/** Distance between two Vecs; writing scales them symmetrically about
+ *  their midpoint (collapse to 0 reinflates the last direction). */
+export function distance(a, b) {
+    const points = [a, b];
+    return remember(points, {
+        anchor: (vals) => ({
+            x: (vals[0].x + vals[1].x) / 2,
+            y: (vals[0].y + vals[1].y) / 2,
+        }),
+        feature: (vals) => Math.hypot(vals[0].x - vals[1].x, vals[0].y - vals[1].y),
+    });
 }
-/** Angle from `a` to `b`, in radians. RO. */
-export function angleLens(a, b) {
-    return Num.derive([a, b], vals => Math.atan2(vals[1].y - vals[0].y, vals[1].x - vals[0].x));
+/** Angle from `a` to `b`, in radians; writing rotates `b` about `a`
+ *  (a fixed, separation preserved). */
+export function angle(a, b) {
+    return rotateAbout([b], a);
 }
 /** Reflect `point` across the line through `axisStart`/`axisEnd`. Writes
  *  the reflected position back to `point` (axis unchanged); reflection is
  *  involutive, so the same formula reads and writes. */
-export function reflectionLens(point, axisStart, axisEnd) {
+export function reflection(point, axisStart, axisEnd) {
     const reflect = (p, a, b) => {
         const dx = b.x - a.x;
         const dy = b.y - a.y;
@@ -53,7 +63,7 @@ export function pulleySum(a, b) {
 }
 /** Difference of two nums: `a - b`. Writing the difference shifts
  *  both inputs symmetrically by ±half-delta. */
-export function diffLens(a, b) {
+export function diff(a, b) {
     return Num.lens([a, b], vals => vals[0] - vals[1], (target, vals) => {
         const [av, bv] = vals;
         const cur = av - bv;
@@ -87,27 +97,3 @@ export function clampedMean(parents, lo, hi) {
         return out;
     });
 }
-/** Quadratic Bézier point at parameter `t`. RO. */
-export function bezier2(p0, p1, p2, t) {
-    return Vec.derive([p0, p1, p2, t], vals => {
-        const [a, b, c, tv] = vals;
-        const u = 1 - tv;
-        return {
-            x: u * u * a.x + 2 * u * tv * b.x + tv * tv * c.x,
-            y: u * u * a.y + 2 * u * tv * b.y + tv * tv * c.y,
-        };
-    });
-}
-/** Cubic Bézier point at parameter `t`. RO. */
-export function bezier3(p0, p1, p2, p3, t) {
-    return Vec.derive([p0, p1, p2, p3, t], vals => {
-        const [a, b, c, d, tv] = vals;
-        const u = 1 - tv;
-        const u2 = u * u;
-        const t2 = tv * tv;
-        return {
-            x: u2 * u * a.x + 3 * u2 * tv * b.x + 3 * u * t2 * c.x + t2 * tv * d.x,
-            y: u2 * u * a.y + 3 * u2 * tv * b.y + 3 * u * t2 * c.y + t2 * tv * d.y,
-        };
-    });
-}