bireactive 0.3.1 → 0.3.2

package/README.md

@@ -1,6 +1,6 @@
 # bi-reactive
 
-[npm](https://www.npmjs.com/package/bireactive) · [GitHub](https://github.com/OrionReed/bireactive) · [site](https://orionreed.github.io/bireactive/) · [API](https://orionreed.github.io/bireactive/api/)
+[NPM](https://www.npmjs.com/package/bireactive) · [GitHub](https://github.com/OrionReed/bireactive) · [Demos](https://orionreed.github.io/bireactive/) · [API](https://orionreed.github.io/bireactive/api/)
 
 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.
 
@@ -10,9 +10,9 @@ A signals-like bidirectional reactive programming system where edges can go both
 npm install bireactive
 ```
 
-Runtime dependencies [`temml`](https://temml.org) (for `tex`) and
+Runtime dependencies [`temml`](https://temml.org) (for `tex`), [`Automerge`](https://automerge.org) and
 [`prism-esm`](https://github.com/orionhealthotago/prism-esm) (for `code`) are
-installed automatically. They may be split into separate packages later so the
+installed automatically. These will be split into separate packages later so the
 core stays dependency-free.
 
 ## Sketch
@@ -61,20 +61,27 @@ inside.value = true; // assert membership…
 q.value; // { x: 100, y: 50 } — q snaps to the nearest in-box point
 ```
 
+## Documentation
+
+- **Guide** — start with the [Overview](guide/overview.md) (a map of every
+  capability) and [Getting Started](guide/getting-started.md).
+- **[API reference](https://orionreed.github.io/bireactive/api/)** — every
+  export, grouped by domain; the guide lives in its sidebar too.
+- **[Demos](https://orionreed.github.io/bireactive/)** — live, interactive examples.
+
 ## Develop
 
 ```sh
 npm run dev        # serve the landing page at :5555
-npm run site       # build the static site into dist-web/
+npm run site       # build the static site + API docs into dist-web/
+npm run docs       # build just the API reference + guide into dist-web/api/
 npm run build      # compile the library into dist/
 npm test           # run the test suite
 ```
 
 ## Status
 
-`0.x` — APIs are still moving. The package is a single bundle today;
-sub-packages (`@bireactive/core`, `@bireactive/animation`, `@bireactive/shapes`, …) are used
-internally as path aliases and will be split out once the surface settles.
+`0.x` — APIs are still moving frequently. The package is a single bundle today; sub-packages will be split out once the surface settles.
 
 ## License
 

package/dist/core/_counts.js

@@ -1,15 +1,8 @@
-// Counts-first instrumentation — measurement scaffolding, not a public surface.
-//
-// The methodology (per the redesign brief): judge engine work by *counts*, not
-// timings. Every metric here is a discrete, predictable event — a user callback
-// invoked, a codepath entered, a node visited, a reverse edge spliced — so a
-// correct minimal engine has a *calculable* target and any work above it is
-// provably wasted. This is the gate for the unification: a change must not raise
-// the forward counts and must hold the backward counts at their minimum.
-//
-// Off by default. `COUNTS` is one module-level gate; each instrumented site reads
-// `if (COUNTS) counts.x++`, so a downstream minifier sees `if (false)` and drops
-// it, and when on the cost is a single predictable branch. Flip via `withCounts`.
+// Counts-first instrumentation: judge engine work by discrete event *counts*
+// (callbacks invoked, codepaths entered, nodes visited, edges spliced), not
+// timings, so a minimal engine has a calculable target. Off by default — each
+// site reads `if (COUNTS) counts.x++`, so a minifier drops it when off and it
+// costs one branch when on. Flip via `withCounts`.
 function fresh() {
     return {
         recompute: 0,

package/dist/core/cell.d.ts

@@ -209,8 +209,8 @@ export declare class Cell<T = unknown> implements ReactiveNode {
     through<B>(this: Cell<T>, o: Optic<T, B>): Writable<Cell<B>>;
     through<B, C>(this: Cell<T>, o1: Optic<T, B>, o2: Optic<B, C>): Writable<Cell<C>>;
     through<B, C, D>(this: Cell<T>, o1: Optic<T, B>, o2: Optic<B, C>, o3: Optic<C, D>): Writable<Cell<D>>;
-    /** Backward fan-in: forward the identity view of its parent, backward the point
-     *  where N contributors fold into one value. `fold` defaults to last-writer-wins. */
+    /** Backward fan-in: forwards its parent's value unchanged; on write, folds N
+     *  contributors into one value. `fold` defaults to last-writer-wins. */
     merge(this: Cell<T>, fold?: MergeFold<T>): Cell<T>;
     /** Read-only typed view. `Cls.derive(parent, fn)` (1-input),
      *  `Cls.derive(parents, fn)` (N-input), or `Cls.derive(fn)` (closure).
@@ -324,7 +324,7 @@ export declare function network(deps: readonly Cell<any>[], body: NetworkBody, o
  *      get x() { return fieldLens(this, "x", Num); } */
 export declare function fieldLens<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). The cache is the point.
+ *  (instance, key).
  *
  *      get magnitude() {
  *        return cachedDerive(this, "magnitude", Num, v => Math.hypot(v.x, v.y));

package/dist/core/cell.js

@@ -754,8 +754,8 @@ export class Cell {
             : (target) => o.put(target, undefined);
         return lens(this, o.get, bwd);
     }
-    /** Backward fan-in: forward the identity view of its parent, backward the point
-     *  where N contributors fold into one value. `fold` defaults to last-writer-wins. */
+    /** Backward fan-in: forwards its parent's value unchanged; on write, folds N
+     *  contributors into one value. `fold` defaults to last-writer-wins. */
     merge(fold) {
         if (this.getter !== undefined && this._bwd === undefined) {
             throw new TypeError("merge: receiver is read-only");
@@ -1159,8 +1159,8 @@ function markDown(start) {
  *  `writeBack`ing each. Source-centric — a source reflects all its writers, so a
  *  call on it resolves every co-writer together and commits once.
  *
- *  Iterative post-order over the back-cone (was a recursion bounded by lens-nesting
- *  depth), via an explicit frame stack of {node, next-child cursor}. On entering a
+ *  Iterative post-order over the back-cone, via an explicit frame stack of
+ *  {node, next-child cursor}. On entering a
  *  node (pre): clear a merge's contributions, then `writeBack` if it holds an armed
  *  target. After its children drain (post): clear `BF.Pending`, then fold a merge.
  *  Children are walked in forward `childEdges` order (so a co-writer's last write
@@ -1295,8 +1295,7 @@ function resolveBackDeps(node) {
  *
  *  Iterative depth-first, left-to-right (children pushed in reverse onto the
  *  pooled `wbNode`/`wbTarget` stack), so a sibling read sees a prior sibling's
- *  staged write exactly as the old recursion did — bounded by stack memory, not
- *  the call stack. */
+ *  staged write — bounded by pooled stack memory, not the call stack. */
 function writeBack(node, target) {
     wbNode[0] = node;
     wbTarget[0] = target;
@@ -1815,7 +1814,7 @@ export function fieldLens(parent, key, Cls) {
     return lazy(parent, key, () => fieldOf(parent, key, Cls));
 }
 /** Read-only derived view via `Cls.derive(parent, fn)`, memoized per
- *  (instance, key). The cache is the point.
+ *  (instance, key).
  *
  *      get magnitude() {
  *        return cachedDerive(this, "magnitude", Num, v => Math.hypot(v.x, v.y));

package/dist/core/derived-geometry.js

@@ -1,10 +1,7 @@
-// derived-geometry.ts — read-only geometric readouts over `Cls.derive`.
-//
-// One-way derives whose inverse is genuinely under-determined (a point
-// sampled at parameter `t` constrains the curve at one point, but the
-// control points have many DOF). They live here, off the lens surface,
-// to keep `lenses/` exclusively bidirectional. For the writable bezier
-// shape decomposition see `bezierGestalt` in `lenses/domain-aggregates`.
+// Read-only geometric readouts over `Cls.derive`: one-way derives whose inverse
+// is under-determined (a point at parameter `t` pins the curve at one point, but
+// the control points keep many DOF). For the writable bezier decomposition see
+// `bezierGestalt` in `lenses/geometry`.
 import { Vec } from "./values/vec.js";
 /** Quadratic Bézier point at parameter `t`. RO. */
 export function bezier2(p0, p1, p2, t) {

package/dist/core/index.d.ts

@@ -9,6 +9,7 @@ export { at, fields } from "./optics.js";
 export { type Store, store } from "./store.js";
 export { type Equals, type Lerp, type Linear, type Metric, type Pack, type Pivotal, requireEquals, requireLerp, requireLinear, requireMetric, requirePack, requirePivotal, type TraitDict, type Traits, } from "./traits.js";
 export { Anchor, Dir } from "./values/anchor.js";
+export { Arr, allPass, arr, type CellPred, type Group, GroupArr, is, } from "./values/arr.js";
 export { Audio, type AudioClip, audio, stamp as audioStamp } from "./values/audio.js";
 export { Bool, bool } from "./values/bool.js";
 export { Box, box, edgeFrom as boxEdgeFrom, expand as boxExpand, union as boxUnion, } from "./values/box.js";
@@ -21,8 +22,9 @@ export { compose as matrixCompose, Matrix, matrix, toMatrixString, transformBox,
 export { Num, num } from "./values/num.js";
 export { Pose, pose } from "./values/pose.js";
 export { Range, range, span } from "./values/range.js";
+export { type AltVal, type BindOpts, type Handle, type HandleKind, type HandleOf, Reg, type RegVal, type Silent, type StarVal, } from "./values/reg.js";
 export { Str, str } from "./values/str.js";
 export { type Codec, enumCodec, numCodec, route, type Slot, slot, strCodec, template, tpl, } from "./values/template.js";
 export { Transform, type TransformInit, transform } from "./values/transform.js";
 export { Tri, tri } from "./values/tri.js";
-export { type PolarPolicy, polar, tangentPoint, Vec, vec } from "./values/vec.js";
+export { tangentPoint, Vec, vec } from "./values/vec.js";

package/dist/core/index.js

@@ -9,6 +9,7 @@ export { at, fields } from "./optics.js";
 export { store } from "./store.js";
 export { requireEquals, requireLerp, requireLinear, requireMetric, requirePack, requirePivotal, } from "./traits.js";
 export { Anchor, Dir } from "./values/anchor.js";
+export { Arr, allPass, arr, GroupArr, is, } from "./values/arr.js";
 export { Audio, audio, stamp as audioStamp } from "./values/audio.js";
 export { Bool, bool } from "./values/bool.js";
 export { Box, box, edgeFrom as boxEdgeFrom, expand as boxExpand, union as boxUnion, } from "./values/box.js";
@@ -21,8 +22,9 @@ export { compose as matrixCompose, Matrix, matrix, toMatrixString, transformBox,
 export { Num, num } from "./values/num.js";
 export { Pose, pose } from "./values/pose.js";
 export { Range, range, span } from "./values/range.js";
+export { Reg, } from "./values/reg.js";
 export { Str, str } from "./values/str.js";
 export { enumCodec, numCodec, route, slot, strCodec, template, tpl, } from "./values/template.js";
 export { Transform, transform } from "./values/transform.js";
 export { Tri, tri } from "./values/tri.js";
-export { polar, tangentPoint, Vec, vec } from "./values/vec.js";
+export { tangentPoint, Vec, vec } from "./values/vec.js";

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

@@ -1,53 +1,43 @@
-import { type Writable } from "../cell.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;
+import { type Cell, Num, type Read, type Traits, type Val, type Writable } from "../index.js";
+/** 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: reads the normalized
+ *  weighted sum `Σ wᵢ·aᵢ`, writes the minimum-norm delta back into the
+ *  branches (zero-weight branches untouched). Weights are read-only reactive
+ *  controls — a one-hot is `select`, a `(1−t, t)` edge is `crossfade`. */
+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
+ *  flow entirely to it, the other is left put. Flipping `cond` snaps the
+ *  output to the other branch's stored value. */
+export declare function select<S extends Traits<any, "linear">>(cond: Read<boolean>, whenFalse: Writable<S>, whenTrue: Writable<S>): Writable<S>;
+/** 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>;
+/** Mean distance from the centroid (needs `Linear` + `Metric`); write scales
+ *  the cluster's deviations so the new mean matches. The complement carries
+ *  normalized deviations, so a collapse (spread → 0) reinflates the shape. */
+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>;
+};
+/** (a, b) → {mean: (a+b)/2, diff: a−b}. Square linear iso; each write is the
+ *  inverse change of basis, so mean and diff are cross-channel invariant. */
+export declare function meanDiff(a: Num, b: Num): {
+    mean: Writable<Num>;
+    diff: 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>;
+/** Num values as (i, valueᵢ) samples → {mean, slope}. Writing `mean` shifts
+ *  all values; writing `slope` (least-squares) tilts them about the mean.
+ *  Each preserves the other's reading. */
+export declare function timeSeries(values: readonly Writable<Num>[]): {
+    mean: Writable<Num>;
+    slope: Writable<Num>;
 };
-/** 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>;