bireactive 0.2.0 → 0.2.2

package/README.md

@@ -1,8 +1,8 @@
-# bireactive
+# bi-reactive
 
-Reactive programming where edges can go both ways. Write to an input and
-everything derived from it updates; write the *derived* value and the input
-adjusts to match. Forward and backward propagation are handled by the engine, with the same set of caveats as regular reactive programming.
+[npm](https://www.npmjs.com/package/bireactive) · [GitHub](https://github.com/OrionReed/bireactive) · [site](https://orionreed.github.io/bireactive/)
+
+A signals-like bidirectional reactive programming system where edges can go both ways. Forward and backward propagation are handled by the engine, with the same set of caveats as regular reactive programming.
 
 ## Install
 
@@ -36,12 +36,12 @@ Values also come as small classes (`Num`, `Vec`, `Box`, `Color`, ...) with field
 lenses and bidirectional operators.
 
 ```ts
-import { vec, box, midpointLens } from "bireactive";
+import { vec, box, mean } from "bireactive";
 
-// Free-function lens: the midpoint of two points, writable.
+// Free-function lens: the mean (midpoint) of two points, writable.
 const a = vec(0, 0);
 const b = vec(10, 0);
-const mid = midpointLens(a, b);
+const mid = mean([a, b]);
 mid.value = { x: 5, y: 10 }; // drag it up…
 a.value; // { x: 0, y: 10 } — both ends translate to keep it the midpoint
 

package/dist/{core/anim.d.ts → animation/animators.d.ts}

@@ -1,6 +1,8 @@
-import { type Animator, type Easing, type Tick, type Yieldable } from "../animation/index.js";
-import { Cell, type Read, type Val, type Writable } from "./signal.js";
-import { type TraitKey, type Traits } from "./traits.js";
+import { Cell, type Read, type Val, type Writable } from "../core/cell.js";
+import { type TraitKey, type Traits } from "../core/traits.js";
+import type { Yieldable } from "./anim.js";
+import { type Animator, type Tick } from "./anim.js";
+import { type Easing } from "./easings.js";
 /** Animator-style constraint: a writable reactive carrying `T` whose
  *  class declares the listed traits. Reads as a sentence:
  *

package/dist/{core/anim.js → animation/animators.js}

@@ -1,12 +1,15 @@
-// anim.ts — animator primitives over `Animatable<T, K>` (writable +
-// nominal trait constraint), plus the signals↔generators bridge.
+// animators.ts — animator primitives over `Animatable<T, K>` (writable +
+// nominal trait constraint): the signals↔generators bridge. Lives with the
+// generator runtime; depends on core for the reactive substrate.
 //
 // Signatures read as a sentence ("spring takes a writable carrying T
 // with linear+metric"), so misuse is a compile error: `spring(box, …)`
 // (no metric), `spring(roVec, …)` (not writable).
-import { drive, easeOut, isGenerator, race, suspend, } from "../animation/index.js";
-import { Cell, derive, effect, reader } from "./signal.js";
-import { requireLerp, requireLinear, requireMetric } from "./traits.js";
+import { Cell, derive, effect, reader } from "../core/cell.js";
+import { requireLerp, requireLinear, requireMetric, } from "../core/traits.js";
+import { isGenerator } from "./anim.js";
+import { drive, race, suspend } from "./combinators.js";
+import { easeOut } from "./easings.js";
 const defaultEase = easeOut;
 /** Chainable Animator over a writable cell: `.to(...).to(...).from(start)`
  *  reads naturally. `.to`/`.from` are pure data — segments accumulate at

package/dist/animation/index.d.ts

@@ -1,3 +1,4 @@
 export { Anim, type Animator, type Cut, cut, isGenerator, type Resume, type Suspend, type Tick, type Yieldable, } from "./anim.js";
+export { type Animatable, attract, driven, every, loop, not, type Play, play, type SpringOpts, spring, Tween, toward, tween, untilChange, wave, when, } from "./animators.js";
 export { all, allSettled, anySuccess, commit, detach, drive, firstMatching, firstN, race, rand, type Settled, suspend, untilEvent, untilPromise, } from "./combinators.js";
 export { type Easing, easeIn, easeInOut, easeOut, linear } from "./easings.js";

package/dist/animation/index.js

@@ -1,3 +1,4 @@
 export { Anim, cut, isGenerator, } from "./anim.js";
+export { attract, driven, every, loop, not, play, spring, Tween, toward, tween, untilChange, wave, when, } from "./animators.js";
 export { all, allSettled, anySuccess, commit, detach, drive, firstMatching, firstN, race, rand, suspend, untilEvent, untilPromise, } from "./combinators.js";
 export { easeIn, easeInOut, easeOut, linear } from "./easings.js";

package/dist/constraints/cluster.js

@@ -14,7 +14,7 @@
 // returns a disposer. `c.add(rel)` calls `bind`; `c.remove(rel)`
 // calls the disposer.
 import { cell, network, requirePack, } from "../core/index.js";
-import { when } from "../core/network-utils.js";
+import { when } from "../core/lifecycle.js";
 import { reactivePipeline } from "./phases.js";
 import { Solver } from "./solver.js";
 export class Constraints {

package/dist/constraints/expose.d.ts

@@ -0,0 +1,17 @@
+import { Vec, type Writable } from "../core/index.js";
+import type { Constraints } from "./cluster.js";
+export interface ExposeOpts {
+    /** Solver sweeps per write (each `step` runs `cluster.iterations`
+     *  inner iterations, warm-started from the previous sweep). Default 4
+     *  — enough to land on a reachable target in one write; the cluster
+     *  also warm-starts across writes, so a spring/drag refines per frame. */
+    iters?: number;
+    /** Stiffness of the soft pull toward the written target. High → the
+     *  handle lands on the target; lower → it lags onto the manifold like
+     *  a dragged-through-load anchor. Default 1e5. */
+    stiffness?: number;
+}
+/** Expose one cell of a `Vec` constraint cluster as a writable lens over
+ *  the cluster's solution manifold. `free` is the set whose solved
+ *  positions are read back (`handle` must be among them). See module note. */
+export declare function exposeVec(c: Constraints, free: readonly Writable<Vec>[], handle: Writable<Vec>, opts?: ExposeOpts): Writable<Vec>;

package/dist/constraints/expose.js

@@ -0,0 +1,61 @@
+// expose.ts — a constraint cluster, oriented as a writable lens.
+//
+// A constraint network is an *unoriented* relation: it has no inputs or
+// outputs, just cells that must agree. A lens is an *oriented* relation —
+// one end you write, the rest follow. `exposeVec` picks the orientation:
+// it names one bound cell the handle and hands back a single
+// `Writable<Vec>` whose backward direction relaxes the cluster.
+//
+// Writing the handle re-aims a strong soft pull at the target, steps the
+// (manually-driven) solver, and reads the settled positions of `free`
+// straight out of the solver buffers — so the whole mechanism collapses
+// to one composable value. `spring`, `handle`, `crossfade`, `mean` — any
+// lens or animator that takes a `Writable<Vec>` now drives the network.
+//
+// Ownership: `exposeVec` disposes the cluster's reactive driver and takes
+// over stepping (the lens body is the only thing that calls `step`), so
+// there's no auto-resolve racing the backward pass. Drive the network
+// through the returned handle(s), not by writing the bound cells directly.
+//
+// One cluster, many handles: call `exposeVec` again with a different cell
+// to expose another section of the same relation (each write relaxes the
+// shared solver). The writeback phase is dropped, so the handles never
+// fight over committing the bound signals — each backward pass reads the
+// freshly solved positions and returns them as its own updates.
+import { Vec } from "../core/index.js";
+import { prepare, solve } from "./phases.js";
+import { SoftTargetTerm } from "./terms.js";
+/** Expose one cell of a `Vec` constraint cluster as a writable lens over
+ *  the cluster's solution manifold. `free` is the set whose solved
+ *  positions are read back (`handle` must be among them). See module note. */
+export function exposeVec(c, free, handle, opts = {}) {
+    const iters = opts.iters ?? 4;
+    const stiffness = opts.stiffness ?? 1e5;
+    const hidx = free.indexOf(handle);
+    if (hidx < 0)
+        throw new Error("exposeVec: handle must be one of `free`");
+    // Take over the time loop: the backward pass is the only `step` caller.
+    c.dispose();
+    // Drop BOTH snapshot and writeback: the solver's own `positions` are the
+    // state. `_bind` seeded them from the cells; each write iterates `solve`
+    // in place (warm-started), then we read the settled positions back as
+    // the lens's updates — committed once by the engine. No re-snapshot means
+    // repeated sweeps actually converge, and state persists across writes.
+    c.pipeline = [prepare, solve];
+    // A re-aimable soft pull standing in for "the value you wrote".
+    const seed = handle.peek();
+    const drive = new SoftTargetTerm(c.solver, c._bind(handle), [seed.x, seed.y], stiffness);
+    c.solver.addTerm(drive);
+    const offsets = free.map(f => c.solver.offsets[c._bind(f)]);
+    const readSolved = (i) => {
+        const off = offsets[i];
+        return { x: c.solver.positions[off], y: c.solver.positions[off + 1] };
+    };
+    return Vec.lens(free, (vals) => vals[hidx], (target) => {
+        drive.target[0] = target.x;
+        drive.target[1] = target.y;
+        for (let i = 0; i < iters; i++)
+            c.step();
+        return free.map((_, i) => readSolved(i));
+    });
+}

package/dist/constraints/index.d.ts

@@ -1,5 +1,6 @@
 export { Constraints, constraints, type Relation } from "./cluster.js";
 export { animate, dilated, fixedStep, } from "./drivers.js";
+export { type ExposeOpts, exposeVec } from "./expose.js";
 export { angle, bend, clamp, collinear, distance, eq, equalDist, gap, generic, geq, inside, lensNum, leq, midpoint, onCircle, parallel, perpendicular, pin, repel, rightAngle, softTarget, spring, } from "./factories.js";
 export { dragBody, dragBodyAnchored } from "./interaction.js";
 export { type Phase, prepare, snapshot, solve, writeback } from "./phases.js";

package/dist/constraints/index.js

@@ -28,6 +28,7 @@
 // https://github.com/savant117/avbd-demo2d.
 export { Constraints, constraints } from "./cluster.js";
 export { animate, dilated, fixedStep, } from "./drivers.js";
+export { exposeVec } from "./expose.js";
 export { angle, bend, clamp, collinear, distance, eq, equalDist, gap, generic, geq, inside, lensNum, leq, midpoint, onCircle, parallel, perpendicular, pin, repel, rightAngle, softTarget, spring, } from "./factories.js";
 export { dragBody, dragBodyAnchored } from "./interaction.js";
 export { prepare, snapshot, solve, writeback } from "./phases.js";

package/dist/constraints/linalg.d.ts

@@ -1,11 +1,4 @@
-/** Solve an SPD (or semi-definite) system `A·x = b` in place via
- *  LDLᵀ. Returns `false` if too singular to solve safely (leaving
- *  `b` undefined — callers typically leave the cell unchanged). */
-export declare function solveSPD(A: Float64Array, b: Float64Array, n: number): boolean;
-/** 2×2 SPD direct solve. A is row-major; we use the symmetry. */
-export declare function solve2(A: Float64Array, b: Float64Array): boolean;
-/** 3×3 SPD direct solve via cofactor expansion. */
-export declare function solve3(A: Float64Array, b: Float64Array): boolean;
+export { solve2, solve3, solveSPD } from "../core/linalg.js";
 /** Add `α · v · vᵀ` to a square matrix `A` in row-major form.
  *  Used to accumulate Jᵀ J terms in the local Newton system. */
 export declare function addOuterProduct(A: Float64Array, v: Float64Array, alpha: number, n: number): void;

package/dist/constraints/linalg.js

@@ -1,113 +1,10 @@
-// linalg.ts — small dense linear algebra for AVBD's per-cell local
-// Newton solves. Systems are `n × n` with n = cell DOF (small, ≤ 6),
-// where unrolled direct solves / LDLᵀ beat anything general-purpose.
+// linalg.ts — constraint-specific dense matrix helpers for AVBD's
+// per-cell local Newton system. The SPD solve itself is shared with the
+// numerical lenses (`solveSPD` lives in core); this module re-exports it
+// and adds the accumulation helpers the solver assembles its LHS with.
 //
 // Convention: matrices are row-major Float64Array of length n*n.
-// Solves are in place: `A` is destroyed, `x` is written into `b`.
-const TINY = 1e-14;
-/** Solve an SPD (or semi-definite) system `A·x = b` in place via
- *  LDLᵀ. Returns `false` if too singular to solve safely (leaving
- *  `b` undefined — callers typically leave the cell unchanged). */
-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);
-    // General LDLᵀ.
-    return ldltGeneric(A, b, n);
-}
-/** 2×2 SPD direct solve. A is row-major; we use the symmetry. */
-export function solve2(A, b) {
-    const a = A[0];
-    const c = A[1]; // = A[2] by symmetry
-    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];
-    // Inverse is transpose of cofactor / det. For SPD it equals the
-    // adjugate / det. We multiply by b directly.
-    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` is overwritten with the solution. */
-function ldltGeneric(A, b, n) {
-    // Factor: A = L D Lᵀ where L is unit lower-triangular and D is
-    // diagonal. We store L in the strictly-lower part of A and D on
-    // the diagonal.
-    for (let j = 0; j < n; j++) {
-        // D[j] = A[j,j] - Σ_{k<j} L[j,k]² · D[k]
-        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;
-        // L[i,j] = (A[i,j] - Σ_{k<j} L[i,k] L[j,k] D[k]) / D[j]
-        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: y_i ← y_i / D[i].
-    for (let i = 0; i < n; 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;
-}
+export { solve2, solve3, solveSPD } from "../core/linalg.js";
 /** Add `α · v · vᵀ` to a square matrix `A` in row-major form.
  *  Used to accumulate Jᵀ J terms in the local Newton system. */
 export function addOuterProduct(A, v, alpha, n) {

package/dist/core/{signal.d.ts → cell.d.ts}

@@ -18,7 +18,7 @@ interface Link {
     nextDep: Link | undefined;
 }
 /** Install a hook fired on every source value-change; returns a restore fn. */
-export declare function setCellWriteHook(fn: ((sig: Cell<unknown>) => void) | undefined): () => void;
+export declare function setCellWriteHook(fn: ((cell: Cell<unknown>) => void) | undefined): () => void;
 export interface MergePolicy<T> {
     readonly identity: T;
     combine(acc: T, x: T): T;
@@ -99,8 +99,8 @@ export declare function lazy<R>(self: object, key: string | symbol, make: () =>
 export declare const isCell: (v: unknown) => v is Cell<unknown>;
 /** Lens mode: a derived cell that can be written back (has a backward sidecar). */
 export declare const isLens: (v: unknown) => v is Cell<unknown>;
-/** Computed mode: derived + read-only (no backward path). */
-export declare const isComputed: (v: unknown) => v is Cell<unknown>;
+/** Read-only mode: derived with no backward path. */
+export declare const isReadonly: (v: unknown) => v is Cell<unknown>;
 export interface CellOptions<T = unknown> {
     /** First subscriber attached; fired from `link`. */
     watched?: () => void;
@@ -149,6 +149,9 @@ export declare class Cell<T = unknown> implements ReactiveNode {
     /** Endomorphic lens. A 2-arg `bwd(view, current)` consults the current
      *  source; a 1-arg `bwd(view)` reconstructs it from the view alone. */
     lens(this: Cell<T>, fwd: (v: T) => T, bwd: (target: T, current: T) => T): this;
+    /** Read-only same-type view: the RO dual of the endo `.lens`. For a cross-type view use the typed static
+     *  `Target.derive(src, fn)`. */
+    derive(this: Cell<T>, fn: (v: T) => T): this;
     /** Backward-aggregating node — bwd dual of computed. Forward, the
      *  identity view of its parent; backward, folds contributions from
      *  upstream lenses (slot-keyed) and direct writes (DIRECT_SLOT). */
@@ -205,7 +208,6 @@ export interface StatefulLensSpec<S extends readonly unknown[], V, C> {
 }
 /** Writable source; passes an existing `Writable` through (idempotent). */
 export declare function cell<T>(initial: T | Writable<Cell<T>>, opts?: CellOptions<T>): Writable<Cell<T>>;
-export declare function computed<T>(fn: () => T): Cell<T>;
 /** Untyped read-only view: `derive(parent, fn)`, `derive(parents, fn)`,
  *  or `derive(fn)` (closure). */
 export declare function derive<P, R>(parent: Read<P>, fn: (v: P) => R): Cell<R>;
@@ -238,9 +240,9 @@ export interface Network {
     /** Run the body now (manual mode's only advance; no-op if unchanged). */
     flush(): void;
     /** Add cells to the topology (idempotent; does NOT fire the body). */
-    subscribe(...sigs: Cell<any>[]): void;
+    subscribe(...cells: Cell<any>[]): void;
     /** Remove cells from the topology (idempotent; does NOT fire). */
-    unsubscribe(...sigs: Cell<any>[]): void;
+    unsubscribe(...cells: Cell<any>[]): void;
 }
 /** Build a reactive sub-DAG node with explicit topology. The body fires
  *  when any subscribed dep changes (`dirty` = the changed subset), runs
@@ -251,4 +253,25 @@ export interface Network {
 export declare function network(deps: readonly Cell<any>[], body: (dirty: ReadonlySet<Cell<unknown>>, handle: Network) => void, opts?: {
     manual?: boolean;
 }): Network;
+/** Bidirectional field lens onto `parent.value[key]`; write spread-
+ *  replaces the composite. Cached per (instance, key). Return type is
+ *  conditional: `Writable<Cls>` on a writable parent, bare `Cls` on RO.
+ *
+ *      get x() { return field(this, "x", Num); } */
+export declare function field<S extends Cell<any>, K extends keyof Inner<S>, C extends new (...args: never[]) => Cell<Inner<S>[K]>>(parent: S, key: K, Cls: C): S extends WritableBrand ? Writable<InstanceType<C>> : InstanceType<C>;
+/** Read-only derived view via `Cls.derive(parent, fn)`, memoized per
+ *  (instance, key); always bare `Cls` (RO). The cache is the point — the
+ *  getter form, not a new kind of cell.
+ *
+ *      get magnitude() {
+ *        return cachedDerive(this, "magnitude", Num, v => Math.hypot(v.x, v.y));
+ *      } */
+export declare function cachedDerive<S extends Cell<any>, C extends new (...args: never[]) => Cell<any>>(parent: S, key: string | symbol, Cls: C, fn: (v: Inner<S>) => Inner<InstanceType<C>>): InstanceType<C>;
+/** Every cell `s` transitively depends on, including itself. Raw cells
+ *  return `{s}`; lens chains return the chain plus all parents. BFS,
+ *  peeking each Computed to populate deps; the `seen` set breaks cycles.
+ *  Used by `Propagators` to expand declared reads into their transitive
+ *  parent set. Inspection is safe: it only reads engine state and peeks
+ *  `.value` (idempotent for lazy Computeds). */
+export declare function transitiveDeps(s: Cell<unknown>): Set<Cell<unknown>>;
 export {};