bireactive 0.2.0 → 0.2.2

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

@@ -1,5 +1,7 @@
-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 ArgminOpts, type ArgminVecOpts, argminNum, argminVec, clampToDisc, } from "./aggregates.js";
+export { bestFitCircle, bestFitLine, pca, rigidTranslate, rotateAbout, scaleAbout, scaleAboutXY, total, } from "./closed-form-policies.js";
+export { bbox, meanDiff, procrustes } from "./decompositions.js";
+export { bezierGestalt, crossfade, mean, meanSpread, mix, select, spread, timeSeries, } from "./domain-aggregates.js";
+export { angle, clampedMean, diff, distance, pulleySum, reflection, vecLerp } from "./geometry.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";
+export { bundle, type FactorOpts, type FactorResult, factor, factorTuple, type OutputSpec, type PackedInput, } from "./typed-factor.js";

package/dist/core/lenses/index.js

@@ -1,16 +1,7 @@
-// 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 { argminNum, argminVec, clampToDisc, } from "./aggregates.js";
+export { bestFitCircle, bestFitLine, pca, rigidTranslate, rotateAbout, scaleAbout, scaleAboutXY, total, } from "./closed-form-policies.js";
+export { bbox, meanDiff, procrustes } from "./decompositions.js";
+export { bezierGestalt, crossfade, mean, meanSpread, mix, select, spread, timeSeries, } from "./domain-aggregates.js";
+export { angle, clampedMean, diff, distance, pulleySum, reflection, vecLerp } from "./geometry.js";
 export { continuous, remember, } from "./memory.js";
-export { bundle, factor, factorTuple, procrustesTyped, } from "./typed-factor.js";
+export { bundle, factor, factorTuple, } from "./typed-factor.js";

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

@@ -1,4 +1,4 @@
-import { type Cell, type Inner, Num, type Read, type Traits, Vec, type Writable } from "../index.js";
+import type { Cell, Inner, Read, Traits, 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">>;
@@ -38,8 +38,3 @@ export declare function factorTuple<T extends readonly OutputSpec<any>[]>(inputs
     [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>;
-};

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

@@ -1,10 +1,10 @@
-// typed-factor.ts — heterogeneous-output factor lens.
+// typed-factor.ts — generic heterogeneous-output factor lens.
 //
-// Generalises `factorLens` (scalar-only) to 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
+// 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 `procrustesLens` for exactness.
+// 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 => … },
@@ -14,7 +14,7 @@
 //   centroid.value = { x: 100, y: 50 };  // typed
 //
 // `bundle()` is the 1→M case: `factor()` over a single typed source.
-import { Num, Vec, } from "../index.js";
+import { solveSPD } from "../linalg.js";
 function getPack(cell) {
     const ctor = cell.constructor;
     const p = ctor.traits?.pack;
@@ -87,9 +87,9 @@ export function factor(inputs, outputs, opts = {}) {
     const flatOutPerturbed = new Float64Array(M);
     const J = new Float64Array(M * N);
     const A = new Float64Array(M * M);
-    const Ainv = new Float64Array(M * M);
+    // `dy` carries the sparse residual in, then the solve overwrites it
+    // with `k` in place (SPD LDLᵀ destroys A and writes the solution here).
     const dy = new Float64Array(M);
-    const kvec = new Float64Array(M);
     // Per-write driver, shared by all M cells.
     const computeBwd = (channelIdx, // which named output is being written
     target, vals) => {
@@ -151,7 +151,7 @@ export function factor(inputs, outputs, opts = {}) {
                 typedScratch[k] = inputPacks[k].write(flatIn, inputOffsets[k]);
             }
         }
-        // 5. A = J W J^T + λI
+        // 5. A = J W J^T + λI  (SPD by construction: W ≥ 0, λ > 0).
         for (let r = 0; r < M; r++) {
             for (let c = 0; c < M; c++) {
                 let s = 0;
@@ -161,16 +161,10 @@ export function factor(inputs, outputs, opts = {}) {
                 A[r * M + c] = s + (r === c ? lambda : 0);
             }
         }
-        // 6. Solve A · k = δy
-        if (!invertMatrix(A, M, Ainv)) {
+        // 6. Solve A · k = δy in place (LDLᵀ; `dy` is overwritten with k).
+        if (!solveSPD(A, dy, M)) {
             return vals.map(() => undefined);
         }
-        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;
-        }
         // 7. δx = W J^T k, applied to flatIn → produces new flat input vector.
         //    Then unpack per-input to typed updates.
         const updates = new Array(inputCount);
@@ -185,7 +179,7 @@ export function factor(inputs, outputs, opts = {}) {
                     continue;
                 let dxi = 0;
                 for (let r = 0; r < M; r++)
-                    dxi += J[r * N + flatIdx] * kvec[r];
+                    dxi += J[r * N + flatIdx] * dy[r];
                 const newVal = flatIn[flatIdx] + w * dxi;
                 if (newVal !== flatIn[flatIdx])
                     anyChange = true;
@@ -278,99 +272,3 @@ export function bundle(source, views, opts = {}) {
 }
 // For field-style bundles, `field()` already covers the independent case;
 // use `bundle()` when you want coupled writes through the Jacobian solve.
-// Matrix inverse (Gauss-Jordan with partial pivoting).
-function invertMatrix(A, M, out) {
-    const W = 2 * M;
-    const aug = new Float64Array(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] *= 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] -= 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;
-}
-// Sugar: closed-form Procrustes via factor() typed API.
-//
-// Procrustes with typed outputs (centroid is a real Vec) but a
-// Jacobian-LSQ bwd — a showcase for the typed ergonomics. The
-// closed-form `procrustesLens` is faster and exact.
-export function procrustesTyped(points) {
-    const K = points.length;
-    return factor(points, {
-        centroid: {
-            Cls: Vec,
-            fwd: (pts) => {
-                let sx = 0;
-                let sy = 0;
-                for (let i = 0; i < K; i++) {
-                    sx += pts[i].x;
-                    sy += pts[i].y;
-                }
-                return { x: sx / K, y: sy / K };
-            },
-        },
-        rotation: {
-            Cls: Num,
-            fwd: (pts) => {
-                let sx = 0;
-                let sy = 0;
-                for (let i = 0; i < K; i++) {
-                    sx += pts[i].x;
-                    sy += pts[i].y;
-                }
-                return Math.atan2(pts[0].y - sy / K, pts[0].x - sx / K);
-            },
-        },
-        scale: {
-            Cls: Num,
-            fwd: (pts) => {
-                let sx = 0;
-                let sy = 0;
-                for (let i = 0; i < K; i++) {
-                    sx += pts[i].x;
-                    sy += pts[i].y;
-                }
-                return Math.hypot(pts[0].x - sx / K, pts[0].y - sy / K);
-            },
-        },
-        // Damping bumped up — atan2/hypot are non-linear; without damping the
-        // first-Newton-step error compounds at the boundary of well-conditioned.
-    }, { damping: 1e-3 });
-}

package/dist/core/{network-utils.d.ts → lifecycle.d.ts}

@@ -1,4 +1,4 @@
-import { type Read } from "./signal.js";
+import { type Read } from "./cell.js";
 /** Disposable handle. */
 export interface Lifecycle {
     dispose(): void;

package/dist/core/{network-utils.js → lifecycle.js}

@@ -1,10 +1,10 @@
-// network-utils.ts — reactive-collection lifecycle helpers over the
+// lifecycle.ts — reactive-collection lifecycle helpers over the
 // `network` model. Implemented purely via `effect`:
 //
 //   `each(source, body)` — body runs per element (keyed by reference
 //                          identity); cleanup on removal.
 //   `when(source, body)` — body runs while truthy; cleanup on falsy.
-import { effect } from "./signal.js";
+import { effect } from "./cell.js";
 /** Run `body(item)` per element on first sight (storing its cleanup) and
  *  run that cleanup when the element leaves. Identity is element
  *  reference — keep stable refs across mutations, don't re-create

package/dist/core/linalg.d.ts

@@ -0,0 +1,10 @@
+/** Dense vector/matrix backing: a typed buffer or a plain array. */
+export type Floats = Float64Array | number[];
+/** Solve an SPD (or semi-definite) system `A·x = b` in place via LDLᵀ.
+ *  `A` is destroyed, the solution is written into `b`. Returns `false`
+ *  if too singular to solve safely (callers typically leave state put). */
+export declare function solveSPD(A: Floats, b: Floats, n: number): boolean;
+/** 2×2 SPD direct solve (uses symmetry: `A[1] === A[2]`). */
+export declare function solve2(A: Floats, b: Floats): boolean;
+/** 3×3 SPD direct solve via cofactor expansion. */
+export declare function solve3(A: Floats, b: Floats): boolean;

package/dist/core/linalg.js

@@ -0,0 +1,109 @@
+// linalg.ts — small dense linear algebra for the numerical backward
+// directions. Two callers, one kernel:
+//   - lenses: the factor/argmin pseudoinverse solves `A k = δy` where
+//     `A = J W Jᵀ + λI` is SPD by construction.
+//   - constraints: AVBD's per-cell local Newton solve, `n = cell DOF`.
+//
+// Systems are tiny (n ≤ ~12), so unrolled direct solves (n = 2, 3) and
+// in-place LDLᵀ beat anything general-purpose AND allocate nothing — the
+// matrix is destroyed, the solution is written into `b`. This replaces the
+// old full-inverse-then-multiply path (1.9–5.3× slower; allocated an
+// `n×2n` augmented buffer per write).
+//
+// Convention: matrices are row-major, length `n*n`.
+const TINY = 1e-14;
+/** Solve an SPD (or semi-definite) system `A·x = b` in place via LDLᵀ.
+ *  `A` is destroyed, the solution is written into `b`. Returns `false`
+ *  if too singular to solve safely (callers typically leave state put). */
+export function solveSPD(A, b, n) {
+    if (n === 1) {
+        const a = A[0];
+        if (Math.abs(a) < TINY)
+            return false;
+        b[0] = b[0] / a;
+        return true;
+    }
+    if (n === 2)
+        return solve2(A, b);
+    if (n === 3)
+        return solve3(A, b);
+    return ldltGeneric(A, b, n);
+}
+/** 2×2 SPD direct solve (uses symmetry: `A[1] === A[2]`). */
+export function solve2(A, b) {
+    const a = A[0];
+    const c = A[1];
+    const d = A[3];
+    const det = a * d - c * c;
+    if (Math.abs(det) < TINY)
+        return false;
+    const inv = 1 / det;
+    const x0 = (d * b[0] - c * b[1]) * inv;
+    const x1 = (-c * b[0] + a * b[1]) * inv;
+    b[0] = x0;
+    b[1] = x1;
+    return true;
+}
+/** 3×3 SPD direct solve via cofactor expansion. */
+export function solve3(A, b) {
+    const a00 = A[0], a01 = A[1], a02 = A[2];
+    const a10 = A[3], a11 = A[4], a12 = A[5];
+    const a20 = A[6], a21 = A[7], a22 = A[8];
+    const c00 = a11 * a22 - a12 * a21;
+    const c01 = -(a10 * a22 - a12 * a20);
+    const c02 = a10 * a21 - a11 * a20;
+    const det = a00 * c00 + a01 * c01 + a02 * c02;
+    if (Math.abs(det) < TINY)
+        return false;
+    const c10 = -(a01 * a22 - a02 * a21);
+    const c11 = a00 * a22 - a02 * a20;
+    const c12 = -(a00 * a21 - a01 * a20);
+    const c20 = a01 * a12 - a02 * a11;
+    const c21 = -(a00 * a12 - a02 * a10);
+    const c22 = a00 * a11 - a01 * a10;
+    const inv = 1 / det;
+    const b0 = b[0], b1 = b[1], b2 = b[2];
+    b[0] = (c00 * b0 + c10 * b1 + c20 * b2) * inv;
+    b[1] = (c01 * b0 + c11 * b1 + c21 * b2) * inv;
+    b[2] = (c02 * b0 + c12 * b1 + c22 * b2) * inv;
+    return true;
+}
+/** General LDLᵀ for `n ≥ 4`. In-place: `A` is overwritten with the
+ *  factor, `b` with the solution. */
+function ldltGeneric(A, b, n) {
+    for (let j = 0; j < n; j++) {
+        let djj = A[j * n + j];
+        for (let k = 0; k < j; k++) {
+            const ljk = A[j * n + k];
+            djj -= ljk * ljk * A[k * n + k];
+        }
+        if (Math.abs(djj) < TINY)
+            return false;
+        A[j * n + j] = djj;
+        for (let i = j + 1; i < n; i++) {
+            let lij = A[i * n + j];
+            for (let k = 0; k < j; k++) {
+                lij -= A[i * n + k] * A[j * n + k] * A[k * n + k];
+            }
+            A[i * n + j] = lij / djj;
+        }
+    }
+    // Forward solve L y = b → y in b.
+    for (let i = 0; i < n; i++) {
+        let yi = b[i];
+        for (let k = 0; k < i; k++)
+            yi -= A[i * n + k] * b[k];
+        b[i] = yi;
+    }
+    // D solve.
+    for (let i = 0; i < n; i++)
+        b[i] = b[i] / A[i * n + i];
+    // Backward solve Lᵀ x = y → x in b.
+    for (let i = n - 1; i >= 0; i--) {
+        let xi = b[i];
+        for (let k = i + 1; k < n; k++)
+            xi -= A[k * n + i] * b[k];
+        b[i] = xi;
+    }
+    return true;
+}

package/dist/core/values/anchor.d.ts

@@ -1,4 +1,4 @@
-import type { Inner } from "../signal.js";
+import type { Inner } from "../cell.js";
 import type { Vec } from "./vec.js";
 type V = Inner<Vec>;
 /** Anchor points on the unit box (`Center = {0.5, 0.5}`). */

package/dist/core/values/audio.d.ts

@@ -1,4 +1,4 @@
-import { Cell, type Init, type Val, type Writable } from "../signal.js";
+import { Cell, type Init, type Val, type Writable } from "../cell.js";
 import { Num } from "./num.js";
 /** Clip header. The graph compares `epoch`; `pcm` is one channel buffer each. */
 export interface AudioClip {

package/dist/core/values/audio.js

@@ -13,7 +13,7 @@
 //     complement (the original peak) recovered on write-back, the audio analog of
 //     str.lowercase()/canvas.grayscale().
 //   - cross-type lens (`rms` → Num).
-import { Cell, reader } from "../signal.js";
+import { Cell, reader } from "../cell.js";
 import { Num } from "./num.js";
 let EPOCH = 0;
 /** Stamp channel buffers with a fresh epoch — the only way to mint a value. */

package/dist/core/values/bool.d.ts

@@ -1,4 +1,4 @@
-import { Cell, type Init, type Val, type Writable } from "../signal.js";
+import { Cell, type Init, type Val, type Writable } from "../cell.js";
 import type { Linear } from "../traits.js";
 type V = boolean;
 export declare const not: (a: V) => V;

package/dist/core/values/bool.js

@@ -7,7 +7,7 @@
 // `and` / `or` / `implies` / `eq` / `nand` / `nor` return bare RO `Bool`
 // — lossy fan-ins whose write-back is ambiguous. Lift to writable via
 // `Bool.lens([a, b], fwd, bwd)` with an explicit policy.
-import { Cell, reader } from "../signal.js";
+import { Cell, reader } from "../cell.js";
 export const not = (a) => !a;
 export const and = (a, b) => a && b;
 export const or = (a, b) => a || b;

package/dist/core/values/box.d.ts

@@ -1,6 +1,5 @@
-import type { Easing } from "../../animation/index.js";
-import { type Tween } from "../anim.js";
-import { Cell, type Init, type Inner, type Val, type Writable, type WritableBrand } from "../signal.js";
+import { type Easing, type Tween } from "../../animation/index.js";
+import { Cell, type Init, type Inner, type Val, type Writable, type WritableBrand } from "../cell.js";
 import type { Linear, Pack } from "../traits.js";
 import { Bool } from "./bool.js";
 import { Num } from "./num.js";

package/dist/core/values/box.js

@@ -2,9 +2,8 @@
 //
 // Invertibles (`add`, `sub`, `scale`, `expand`) return `: this` and ride
 // on `Cell#lens(fwd, bwd)`. Chained calls compose into a lens chain.
-import { tween } from "../anim.js";
-import { Cell, isComputed, lazy, reader, readNow, } from "../signal.js";
-import { derived, field } from "../writable.js";
+import { tween } from "../../animation/index.js";
+import { Cell, cachedDerive, field, isReadonly, lazy, reader, readNow, } from "../cell.js";
 import { Bool } from "./bool.js";
 import { Num, num } from "./num.js";
 import { Vec } from "./vec.js";
@@ -129,9 +128,9 @@ export class Box extends Cell {
      *  nearest edge by `eps`. Literal / RO inputs yield a bare RO `Bool`. */
     contains(p) {
         if (p instanceof Vec) {
-            // A computed Vec has no backward path → RO branch; sources and
+            // A read-only Vec has no backward path → RO branch; sources and
             // writable lenses accept write-back.
-            if (!isComputed(p)) {
+            if (!isReadonly(p)) {
                 // `.bind(Bool)` + cast steps past the generic overloads, whose
                 // mapped-tuple inference over the full class types otherwise blows
                 // the instantiation depth.
@@ -159,7 +158,7 @@ export class Box extends Cell {
         return field(this, "h", Num);
     }
     get area() {
-        return derived(this, "area", Num, b => b.w * b.h);
+        return cachedDerive(this, "area", Num, b => b.w * b.h);
     }
     /** Vec at parametric (u, v) within `[0,1]²`. Not memoised (arbitrary
      *  pairs would leak a cache entry each) — use the named edge getters

package/dist/core/values/canvas.d.ts

@@ -1,4 +1,4 @@
-import { Cell, type Val, type Writable } from "../signal.js";
+import { Cell, type Val, type Writable } from "../cell.js";
 import { Bool } from "./bool.js";
 import { Color } from "./color.js";
 import { Spring, type SpringOpts } from "./gpu.js";

package/dist/core/values/canvas.js

@@ -20,8 +20,7 @@
 // A backward pass that produces a ROOT cell's next value reads that root and
 // writes a result that becomes its value, so it uses `scratch2` (a feedback-
 // safe pair) to avoid reading and writing the same texture.
-import { Cell, reader } from "../signal.js";
-import { derived } from "../writable.js";
+import { Cell, cachedDerive, reader } from "../cell.js";
 import { Bool } from "./bool.js";
 import { Color } from "./color.js";
 import { copy, newTex, pass, reduceMean, Spring, scratch, scratch2, } from "./gpu.js";
@@ -464,7 +463,7 @@ export class Canvas extends Cell {
     }
     /** Dimensions `(w, h)` as a read-only `Vec`. */
     get dimensions() {
-        return derived(this, "dimensions", Vec, v => ({ x: v.w, y: v.h }));
+        return cachedDerive(this, "dimensions", Vec, v => ({ x: v.w, y: v.h }));
     }
     /** A GPU per-pixel spring driver seeded from this value's texture. The
      *  host steps it and writes `current()` back into a root cell each frame;

package/dist/core/values/color.d.ts

@@ -1,6 +1,5 @@
-import type { Easing } from "../../animation/index.js";
-import { type Tween } from "../anim.js";
-import { Cell, type Init, type Val, type Writable } from "../signal.js";
+import { type Easing, type Tween } from "../../animation/index.js";
+import { Cell, type Init, type Val, type Writable } from "../cell.js";
 import type { Linear, Pack } from "../traits.js";
 import { Num } from "./num.js";
 type V = {

package/dist/core/values/color.js

@@ -2,9 +2,8 @@
 //
 // Invertibles (`add`, `sub`, `scale`) return `: this` and ride on
 // `Cell#lens(fwd, bwd)`. Chained calls compose into a lens chain.
-import { tween } from "../anim.js";
-import { Cell, derive, lazy, reader, readNow } from "../signal.js";
-import { derived, field } from "../writable.js";
+import { tween } from "../../animation/index.js";
+import { Cell, cachedDerive, derive, field, lazy, reader, readNow, } from "../cell.js";
 import { Num, num } from "./num.js";
 export const add = (a, b) => ({ r: a.r + b.r, g: a.g + b.g, b: a.b + b.b, a: a.a + b.a });
 export const sub = (a, b) => ({ r: a.r - b.r, g: a.g - b.g, b: a.b - b.b, a: a.a - b.a });
@@ -68,7 +67,7 @@ export class Color extends Cell {
         return field(this, "a", Num);
     }
     get luminance() {
-        return derived(this, "luminance", Num, c => 0.299 * c.r + 0.587 * c.g + 0.114 * c.b);
+        return cachedDerive(this, "luminance", Num, c => 0.299 * c.r + 0.587 * c.g + 0.114 * c.b);
     }
     get css() {
         return lazy(this, "css", () => derive(() => {

package/dist/core/values/flags.d.ts

@@ -1,4 +1,4 @@
-import { Cell, type Writable } from "../signal.js";
+import { Cell, type Writable } from "../cell.js";
 import { Bool } from "./bool.js";
 export declare class Flags<K extends string> extends Cell<number> {
     #private;

package/dist/core/values/flags.js

@@ -13,7 +13,7 @@
 // flag named "value"/"flag" shadowing the class. Since each flag is a
 // writable Bool, `Tri.allOf([f.flag(a), f.flag(b)])` gives all/none/mixed
 // group toggles for free.
-import { Cell } from "../signal.js";
+import { Cell } from "../cell.js";
 import { Bool } from "./bool.js";
 const equals = (a, b) => a === b;
 export class Flags extends Cell {

package/dist/core/values/matrix.d.ts

@@ -1,4 +1,4 @@
-import { Cell, type Init, type Inner, type Val, type Writable } from "../signal.js";
+import { Cell, type Init, type Inner, type Val, type Writable } from "../cell.js";
 import { Num } from "./num.js";
 import type { Vec } from "./vec.js";
 type V = {

package/dist/core/values/matrix.js

@@ -5,8 +5,7 @@
 // compile time. Two invertibles, both `: this` via `Cell#lens`:
 //   - `multiply(b)` — inverse multiplies by `invert(b)`
 //   - `invert()`    — its own inverse
-import { Cell, reader } from "../signal.js";
-import { derived, field } from "../writable.js";
+import { Cell, cachedDerive, field, reader, } from "../cell.js";
 import { Num, num } from "./num.js";
 export const identity = () => ({ a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
 export const fromTranslate = (x, y) => ({ a: 1, b: 0, c: 0, d: 1, e: x, f: y });
@@ -112,7 +111,7 @@ export class Matrix extends Cell {
         return field(this, "f", Num);
     }
     get determinant() {
-        return derived(this, "determinant", Num, determinant);
+        return cachedDerive(this, "determinant", Num, determinant);
     }
 }
 /** Writable `Matrix` with entries `(a, b, c, d, e, f)` (SVG/Canvas order).

package/dist/core/values/num.d.ts

@@ -1,6 +1,5 @@
-import type { Easing } from "../../animation/index.js";
-import { type Tween } from "../anim.js";
-import { Cell, type Init, type Val, type Writable, type WritableBrand } from "../signal.js";
+import { type Easing, type Tween } from "../../animation/index.js";
+import { Cell, type Init, type Val, type Writable, type WritableBrand } from "../cell.js";
 import type { Linear, Pack } from "../traits.js";
 import { Bool } from "./bool.js";
 type V = number;
@@ -26,6 +25,12 @@ export declare class Num extends Cell<V> {
     /** Affine `v ↦ k·v + off`. Invertible iff k ≠ 0; readability alias
      *  for `.scale(k).add(off)`. */
     affine(k: Val<number>, off: Val<number>): this;
+    /** `sin(this)` (radians). Forward lands in [−1, 1]; the inverse is
+     *  multi-valued, so a write clamps to that domain and returns the
+     *  pre-image nearest the current source — the drag stays on its branch. */
+    sin(): this;
+    /** `exp(this)` — bijection on the reals; inverse is the natural log. */
+    exp(): this;
     /** Lossy clamping lens to `[lo, hi]`. PutGet only (a write outside
      *  the range reads back clamped, not as written). */
     clamp(lo: Val<V>, hi: Val<V>): this;

package/dist/core/values/num.js

@@ -2,8 +2,8 @@
 //
 // Invertibles return `: this` and ride on `Cell#lens(fwd, bwd)`;
 // chained calls compose into a lens chain.
-import { tween } from "../anim.js";
-import { Cell, lazy, reader, } from "../signal.js";
+import { tween } from "../../animation/index.js";
+import { Cell, lazy, reader, } from "../cell.js";
 import { Bool } from "./bool.js";
 export const add = (a, b) => a + b;
 export const sub = (a, b) => a - b;
@@ -11,6 +11,11 @@ export const scale = (a, k) => a * k;
 export const lerp = (a, b, t) => a + (b - a) * t;
 export const metric = (a, b) => Math.abs(a - b);
 export const equals = (a, b) => a === b;
+const TAU = 2 * Math.PI;
+/** Representative of `x + 2πk` nearest `s` (shortest-arc branch pick). */
+const nearestTo = (s, x) => x + TAU * Math.round((s - x) / TAU);
+/** Clamp to the sin/cos domain `[-1, 1]`. */
+const unit = (t) => (t < -1 ? -1 : t > 1 ? 1 : t);
 const linearImpl = { add, sub, scale };
 const packImpl = {
     dim: 1,
@@ -49,6 +54,21 @@ export class Num extends Cell {
         const of = reader(off);
         return this.lens(v => v * kf() + of(), n => (n - of()) / kf());
     }
+    /** `sin(this)` (radians). Forward lands in [−1, 1]; the inverse is
+     *  multi-valued, so a write clamps to that domain and returns the
+     *  pre-image nearest the current source — the drag stays on its branch. */
+    sin() {
+        return this.lens(v => Math.sin(v), (target, s) => {
+            const p = Math.asin(unit(target));
+            const a = nearestTo(s, p);
+            const b = nearestTo(s, Math.PI - p);
+            return Math.abs(a - s) <= Math.abs(b - s) ? a : b;
+        });
+    }
+    /** `exp(this)` — bijection on the reals; inverse is the natural log. */
+    exp() {
+        return this.lens(v => Math.exp(v), n => Math.log(n));
+    }
     /** Lossy clamping lens to `[lo, hi]`. PutGet only (a write outside
      *  the range reads back clamped, not as written). */
     clamp(lo, hi) {

package/dist/core/values/pose.d.ts

@@ -1,5 +1,6 @@
-import { Cell, type Init, type Writable } from "../signal.js";
+import { Cell, type Init, type Writable } from "../cell.js";
 import type { Linear, Pack, Pivotal } from "../traits.js";
+import { Num } from "./num.js";
 type V = {
     x: number;
     y: number;
@@ -22,6 +23,9 @@ export declare class Pose extends Cell<V> {
     };
     readonly _t: typeof Pose.traits;
     constructor(v?: V);
+    get x(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
+    get y(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
+    get theta(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
 }
 /** Writable `Pose`. Literal seeds a fresh cell; existing `Pose` passes
  *  through by identity. RO sources are rejected at the type level — use