bireactive 0.3.1 → 0.3.3

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/automerge/doc-cell.d.ts

@@ -1,20 +1,33 @@
 import type { DocHandle } from "@automerge/automerge-repo";
 import { type Cell, type Writable } from "../core/cell.js";
 import { type Store } from "../core/store.js";
-/** Two-way bridge between an Automerge doc and the reactive graph. */
-export interface DocBridge<T> {
-    /** Source cell mirroring the doc; writes (direct or via a lens) flow back to the CRDT. */
-    cell: Writable<Cell<T>>;
-    /** Deep `store` view over `cell` — `bridge.store.a.b.value = x` commits to the doc. */
-    store: Store<T>;
+import { type By } from "./reconcile.js";
+/** Bridge options shared by every `connect*` entry. */
+export interface DocOptions {
+    /** Identity key for list elements, enabling keyed reconciliation (see `reconcile`). */
+    by?: By;
+}
+/** Lifecycle shared by every bridge: retarget the doc, detach both directions. */
+export interface DocLifecycle<T> {
     /** Point the same cell at a different doc, keeping every bound lens/view alive. */
     retarget: (handle: DocHandle<T>) => void;
     /** Detach both directions (call from `disconnectedCallback`). */
     dispose: () => void;
 }
+/** Doc bridged to a writable cell; writes (direct or via a lens) flow to the CRDT. */
+export interface CellBridge<T> extends DocLifecycle<T> {
+    cell: Writable<Cell<T>>;
+}
+/** Doc bridged to a deep `store` — `bridge.store.a.b.value = x` commits to the doc. */
+export interface StoreBridge<T> extends DocLifecycle<T> {
+    store: Store<T>;
+}
+/** Doc bridged to both a cell and a deep store. */
+export interface DocBridge<T> extends CellBridge<T>, StoreBridge<T> {
+}
+/** Connect a `DocHandle` to a reactive cell, syncing both ways. */
+export declare function connectCell<T extends object>(handle: DocHandle<T>, opts?: DocOptions): CellBridge<T>;
+/** Connect a `DocHandle` to a deep `store`, syncing both ways. */
+export declare function connectStore<T extends object>(handle: DocHandle<T>, opts?: DocOptions): StoreBridge<T>;
 /** Connect a `DocHandle` to a reactive cell + store, syncing both ways. */
-export declare function connectDoc<T extends object>(handle: DocHandle<T>): DocBridge<T>;
-/** Doc as a writable cell (page-lifetime; use {@link connectDoc} when you need disposal). */
-export declare function docCell<T extends object>(handle: DocHandle<T>): Writable<Cell<T>>;
-/** Doc as a deep store (page-lifetime; use {@link connectDoc} when you need disposal). */
-export declare function docStore<T extends object>(handle: DocHandle<T>): Store<T>;
+export declare function connectDoc<T extends object>(handle: DocHandle<T>, opts?: DocOptions): DocBridge<T>;

package/dist/automerge/doc-cell.js

@@ -39,42 +39,48 @@ function deepEqual(a, b) {
     return true;
 }
 /** Wire an existing cell to a handle in both directions; returns an unbind. */
-function bind(c, handle) {
+function bind(c, handle, by) {
     const onChange = () => {
         c.value = structuredClone(handle.doc());
     };
     handle.on("change", onChange);
     const stop = effect(() => {
         const next = c.value;
-        handle.change((d) => reconcile(d, next));
+        handle.change((d) => reconcile(d, next, by));
     });
     return () => {
         stop();
         handle.off("change", onChange);
     };
 }
-/** Connect a `DocHandle` to a reactive cell + store, syncing both ways. */
-export function connectDoc(handle) {
+/** Core: a doc-backed cell plus lifecycle. The cell projections layer on top. */
+function connect(handle, opts) {
+    const by = opts?.by;
     const c = cell(structuredClone(handle.doc()), { equals: deepEqual, name: "doc" });
-    let unbind = bind(c, handle);
+    let unbind = bind(c, handle, by);
     return {
         cell: c,
-        store: store(c),
         retarget: next => {
             unbind();
             // Seed the cell from the new doc *before* re-binding, so the cell→doc
             // effect doesn't push the old value into the freshly targeted doc.
             c.value = structuredClone(next.doc());
-            unbind = bind(c, next);
+            unbind = bind(c, next, by);
         },
         dispose: () => unbind(),
     };
 }
-/** Doc as a writable cell (page-lifetime; use {@link connectDoc} when you need disposal). */
-export function docCell(handle) {
-    return connectDoc(handle).cell;
+/** Connect a `DocHandle` to a reactive cell, syncing both ways. */
+export function connectCell(handle, opts) {
+    return connect(handle, opts);
+}
+/** Connect a `DocHandle` to a deep `store`, syncing both ways. */
+export function connectStore(handle, opts) {
+    const { cell: c, retarget, dispose } = connect(handle, opts);
+    return { store: store(c), retarget, dispose };
 }
-/** Doc as a deep store (page-lifetime; use {@link connectDoc} when you need disposal). */
-export function docStore(handle) {
-    return connectDoc(handle).store;
+/** Connect a `DocHandle` to a reactive cell + store, syncing both ways. */
+export function connectDoc(handle, opts) {
+    const b = connect(handle, opts);
+    return { ...b, store: store(b.cell) };
 }

package/dist/automerge/index.d.ts

@@ -1,3 +1,4 @@
-export type { DocBridge } from "./doc-cell.js";
-export { connectDoc, docCell, docStore } from "./doc-cell.js";
+export type { CellBridge, DocBridge, DocLifecycle, DocOptions, StoreBridge } from "./doc-cell.js";
+export { connectCell, connectDoc, connectStore } from "./doc-cell.js";
+export type { By } from "./reconcile.js";
 export { reconcile } from "./reconcile.js";

package/dist/automerge/index.js

@@ -1,12 +1,13 @@
 // @bireactive/automerge — view an Automerge CRDT through the reactive graph.
 //
 // `connectDoc(handle)` turns a `DocHandle` into a `Writable<Cell<T>>` plus a deep
-// `store`, synced both ways. Lens/`store` projections off that one cell give you
-// many schemas over a single shared doc with no privileged "primary" — the CRDT
-// is the apex, every view is a leg. `reconcile` is the doc-side diff that keeps
-// writes merge-friendly; it's exported for custom bridges.
+// `store`, synced both ways; `connectCell`/`connectStore` give just one projection.
+// Lens/`store` views off that one cell give you many schemas over a single shared
+// doc with no privileged "primary" — the CRDT is the apex, every view is a leg.
+// `reconcile` is the doc-side diff that keeps writes merge-friendly; it's exported
+// for custom bridges.
 //
 // Automerge is an optional peer dependency: import this entry only when you've
 // installed `@automerge/automerge-repo`.
-export { connectDoc, docCell, docStore } from "./doc-cell.js";
+export { connectCell, connectDoc, connectStore } from "./doc-cell.js";
 export { reconcile } from "./reconcile.js";

package/dist/automerge/reconcile.d.ts

@@ -1,5 +1,8 @@
 type Any = any;
+/** Stable identity key for a list element; return a primitive. `undefined` (or a
+ *  collision) on any element makes that list fall back to positional. */
+export type By = (element: unknown) => unknown;
 /** Minimally mutate the Automerge node `target` (inside `handle.change`) to equal
- *  the plain value `next`. */
-export declare function reconcile(target: Any, next: Any): void;
+ *  the plain value `next`. Pass `by` for identity-keyed list reconciliation. */
+export declare function reconcile(target: Any, next: Any, by?: By): void;
 export {};

package/dist/automerge/reconcile.js

@@ -9,38 +9,96 @@
 // `updateText` for strings (char-level), in-place splices for lists, recursive
 // descent for objects, scalar sets for the rest.
 //
-// List handling is intentionally simple for now: element-wise in place, with a
-// tail push/truncate. Correct for edits/appends/truncations; a reorder or mid
-// insert produces more ops than ideal. Identity-keyed list reconciliation is the
-// obvious upgrade (mirror the `eachBy` lens's `by`).
+// List handling is positional by default: element-wise in place, with a tail
+// push/truncate. Correct for edits/appends/truncations, but a reorder or mid
+// insert rewrites every shifted slot's scalars — merge-hostile. Pass `by` for
+// identity-keyed reconciliation (mirrors the `eachBy` lens's `by`): a longest
+// common subsequence keeps shared elements in place and emits minimal keyed
+// splices/inserts for the rest, so reorders and mid-inserts merge cleanly.
 import { updateText } from "@automerge/automerge-repo";
 const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 /** Minimally mutate the Automerge node `target` (inside `handle.change`) to equal
- *  the plain value `next`. */
-export function reconcile(target, next) {
+ *  the plain value `next`. Pass `by` for identity-keyed list reconciliation. */
+export function reconcile(target, next, by) {
     if (Array.isArray(next) && Array.isArray(target))
-        reconcileList(target, next);
+        reconcileList(target, next, by);
     else
-        reconcileObject(target, next);
+        reconcileObject(target, next, by);
 }
-function reconcileObject(target, next) {
+function reconcileObject(target, next, by) {
     for (const k of Object.keys(target))
         if (!(k in next))
             delete target[k];
     for (const k of Object.keys(next))
-        setKey(target, k, target[k], next[k], false);
+        setKey(target, k, target[k], next[k], false, by);
 }
-function reconcileList(target, next) {
+function reconcileList(target, next, by) {
+    if (by !== undefined && reconcileKeyed(target, next, by))
+        return;
     const shared = Math.min(target.length, next.length);
     for (let i = 0; i < shared; i++)
-        setKey(target, i, target[i], next[i], true);
+        setKey(target, i, target[i], next[i], true, by);
     if (next.length < target.length)
         target.splice(next.length);
     else
         for (let i = target.length; i < next.length; i++)
             target.push(next[i]);
 }
-function setKey(parent, key, a, b, inList) {
+/** Keyed list reconcile via LCS. Returns false (→ positional fallback) when keys
+ *  aren't total + unique on either side. */
+function reconcileKeyed(target, next, by) {
+    const tKeys = target.map(by);
+    const nKeys = next.map(by);
+    if (!totalUnique(tKeys) || !totalUnique(nKeys))
+        return false;
+    const keep = lcs(tKeys, nKeys);
+    let i = 0; // cursor into `target`, which mutates as we splice
+    for (let n = 0; n < next.length; n++) {
+        if (keep.has(nKeys[n])) {
+            while (i < target.length && !keep.has(by(target[i])))
+                target.splice(i, 1);
+            setKey(target, i, target[i], next[n], true, by); // same identity → merge edits
+            i++;
+        }
+        else {
+            target.splice(i, 0, next[n]); // insert (new key, or a moved element re-placed)
+            i++;
+        }
+    }
+    if (i < target.length)
+        target.splice(i);
+    return true;
+}
+function totalUnique(keys) {
+    if (keys.some(k => k === undefined))
+        return false;
+    return new Set(keys).size === keys.length;
+}
+/** Keys of the longest common subsequence of `a` and `b` (`===` on keys). */
+function lcs(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--)
+        for (let j = m - 1; j >= 0; j--)
+            dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    const keep = new Set();
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            keep.add(a[i]);
+            i++;
+            j++;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1])
+            i++;
+        else
+            j++;
+    }
+    return keep;
+}
+function setKey(parent, key, a, b, inList, by) {
     if (typeof b === "string" && typeof a === "string") {
         // Char-level merge for object text fields; list string elements just assign
         // (path-relative updateText targets a keyed field, not an array slot).
@@ -52,10 +110,10 @@ function setKey(parent, key, a, b, inList) {
         }
     }
     else if (Array.isArray(b) && Array.isArray(a)) {
-        reconcileList(a, b);
+        reconcileList(a, b, by);
     }
     else if (isPlainObject(b) && isPlainObject(a)) {
-        reconcileObject(a, b);
+        reconcileObject(a, b, by);
     }
     else if (a !== b) {
         parent[key] = b;

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>;