bireactive 0.2.4 → 0.3.1

package/dist/learn/lens-net.js

@@ -0,0 +1,219 @@
+// lens-net.ts — the MLP of `mlp.ts`, but wired as an actual lens DAG so that
+// *training is a backward write*.
+//
+// Each dense layer is a multi-parent stateful lens over `[paramsCell, inputCell]`:
+//   fwd  computes the activation `act(W·x + b)`,
+//   bwd  receives the cotangent dL/da, deposits an SGD step on the weight cell,
+//        and passes dL/dx up to the previous layer.
+// Composing the layers composes their backward passes in reverse, so writing
+// the output cotangent to the `logits` cell makes the engine run reverse-mode
+// backprop down the whole chain and land an update on every weight source.
+// There is no optimizer object and no training loop inside the net: the
+// statement `logits.value = cotangent` *is* one gradient step.
+//
+// The very same lens, run with the weights frozen (`cfg.frozen`), inverts
+// instead of fits — the cotangent still flows to the input, so the input cell
+// receives dL/dx. That is the gradient the "dream" ascends to paint a class
+// prototype: inference-time inversion is just the backward leg with the
+// parameters held fixed.
+//
+// `mlp.ts` stays the flat, fast reference (and the offline ground truth); this
+// is the reactive realization the demos drive.
+import { cell, lens, SKIP } from "../core/index.js";
+import { actGrad, applyAct, gaussian, rng, softmax } from "./mlp.js";
+const toF64 = (x) => x instanceof Float64Array ? x : Float64Array.from(x);
+// Forward of one dense layer (the lens `fwd`).
+function denseForward(p, inDim, outDim, act, x) {
+    const y = new Float64Array(outDim);
+    for (let o = 0; o < outDim; o++) {
+        let z = p.b[o];
+        const base = o * inDim;
+        for (let i = 0; i < inDim; i++)
+            z += p.W[base + i] * x[i];
+        y[o] = applyAct(act, z);
+    }
+    return y;
+}
+// Backward of one dense layer (the lens `bwd` math): given dL/da, return the
+// input cotangent dL/dx and the parameter gradients gW/gb. Shared by the
+// engine-routed training step and the frozen inversion pass so they can't drift.
+function denseBackward(p, inDim, outDim, act, x, dOut) {
+    const dIn = new Float64Array(inDim);
+    const gW = new Float64Array(outDim * inDim);
+    const gb = new Float64Array(outDim);
+    for (let o = 0; o < outDim; o++) {
+        let z = p.b[o];
+        const base = o * inDim;
+        for (let i = 0; i < inDim; i++)
+            z += p.W[base + i] * x[i];
+        const dz = dOut[o] * actGrad(act, applyAct(act, z));
+        gb[o] = dz;
+        for (let i = 0; i < inDim; i++) {
+            gW[base + i] = dz * x[i];
+            dIn[i] = dIn[i] + p.W[base + i] * dz;
+        }
+    }
+    return { dIn, gW, gb };
+}
+// Build one dense layer-lens over its weight source and input cell. Forward is
+// the activation; backward steps the weights (unless frozen) and always returns
+// dL/dx for the input parent — for a hidden layer that propagates the gradient
+// up the chain; for the first layer it lands on the input cell (where the
+// inversion pass reads it).
+function denseLens(params, input, inDim, outDim, act, cfg) {
+    const parents = [params, input];
+    return lens(parents, {
+        init: () => null,
+        step: (_s, c) => c,
+        fwd: (s) => denseForward(s[0], inDim, outDim, act, s[1]),
+        bwd: (cot, s, c) => {
+            const { dIn, gW, gb } = denseBackward(s[0], inDim, outDim, act, s[1], cot);
+            let pUpd;
+            if (cfg.frozen) {
+                pUpd = SKIP;
+            }
+            else {
+                const W = new Float64Array(s[0].W);
+                const b = new Float64Array(s[0].b);
+                const lr = cfg.lr;
+                for (let k = 0; k < W.length; k++)
+                    W[k] = W[k] - lr * gW[k];
+                for (let o = 0; o < b.length; o++)
+                    b[o] = b[o] - lr * gb[o];
+                pUpd = { W, b };
+            }
+            return { updates: [pUpd, dIn], complement: c };
+        },
+    });
+}
+/** Build a net as a lens DAG. `dims` is `[in, h1, …, out]`; hidden layers use
+ *  `hidden` activation, the output is `linear` (the squash folds into the loss). */
+export function lensNet(dims, opts = {}) {
+    const hidden = opts.hidden ?? "tanh";
+    const r = rng(opts.seed ?? 1);
+    const cfg = { lr: opts.lr ?? 0.05, frozen: false };
+    const input = cell(new Float64Array(dims[0]));
+    const layers = [];
+    let x = input;
+    for (let i = 0; i + 1 < dims.length; i++) {
+        const inDim = dims[i];
+        const outDim = dims[i + 1];
+        const act = i + 2 < dims.length ? hidden : "linear";
+        const scale = act === "relu" ? Math.sqrt(2 / inDim) : Math.sqrt(1 / inDim);
+        const W = new Float64Array(outDim * inDim);
+        for (let k = 0; k < W.length; k++)
+            W[k] = gaussian(r) * scale;
+        const params = cell({ W, b: new Float64Array(outDim) });
+        const out = denseLens(params, x, inDim, outDim, act, cfg);
+        layers.push({ inDim, outDim, act, params, out });
+        x = out;
+    }
+    return { input, layers, logits: x, cfg, dims };
+}
+/** Logits for `x`, reading the current weight cells (no training, untracked).
+ *  Applies any pending backward write first, so it always sees fresh weights. */
+export function logitsOf(net, x) {
+    let a = toF64(x);
+    for (const L of net.layers)
+        a = denseForward(L.params.peek(), L.inDim, L.outDim, L.act, a);
+    return a;
+}
+/** Class probabilities: sigmoid for a 1-logit (binary) net, else softmax. */
+export function probsOf(net, x) {
+    const z = logitsOf(net, x);
+    return z.length === 1 ? Float64Array.of(1 / (1 + Math.exp(-z[0]))) : softmax(z);
+}
+/** Argmax class for a multi-logit net, or `P ≥ 0.5` for a binary net. */
+export function classifyOf(net, x) {
+    const p = probsOf(net, x);
+    if (p.length === 1)
+        return p[0] >= 0.5 ? 1 : 0;
+    let best = 0;
+    for (let i = 1; i < p.length; i++)
+        if (p[i] > p[best])
+            best = i;
+    return best;
+}
+/** Fraction of `data` classified correctly. */
+export function accuracyOf(net, data) {
+    let ok = 0;
+    for (const s of data)
+        if (classifyOf(net, s.x) === s.y)
+            ok++;
+    return ok / Math.max(1, data.length);
+}
+// Cross-entropy loss + the cotangent dL/dlogits (the seed of the backward
+// pass). Binary: BCE-with-logits, dz = σ(z) − y. Multi: softmax CE, dz = p − e_y.
+function lossCotangent(z, y) {
+    if (z.length === 1) {
+        const p = 1 / (1 + Math.exp(-z[0]));
+        const eps = 1e-12;
+        return {
+            loss: -(y * Math.log(p + eps) + (1 - y) * Math.log(1 - p + eps)),
+            cot: Float64Array.of(p - y),
+        };
+    }
+    const p = softmax(z);
+    const cot = new Float64Array(z.length);
+    for (let k = 0; k < z.length; k++)
+        cot[k] = p[k] - (k === y ? 1 : 0);
+    return { loss: -Math.log(p[y] + 1e-12), cot };
+}
+/** Mean cross-entropy over a dataset (no update) — for monitoring/tests. */
+export function meanLossOf(net, data) {
+    let total = 0;
+    for (const s of data)
+        total += lossCotangent(logitsOf(net, s.x), s.y).loss;
+    return total / Math.max(1, data.length);
+}
+/** Train one example with a single backward write: pin the input, read the
+ *  prediction (the forward pull), then write the output cotangent to `logits`.
+ *  The engine backpropagates and lands an SGD step on every weight cell. The
+ *  step is forced before returning (while the input still holds this example),
+ *  so callers may move on immediately. Returns the loss before the step. */
+export function trainExample(net, x, y) {
+    net.cfg.frozen = false;
+    net.input.value = toF64(x);
+    const { loss, cot } = lossCotangent(net.logits.value, y);
+    net.logits.value = cot;
+    void net.logits.peek(); // force the backward now, while input === this example
+    return loss;
+}
+// Fisher–Yates over [0, n) using the provided uniform source.
+function shuffled(n, r) {
+    const a = Array.from({ length: n }, (_, i) => i);
+    for (let i = n - 1; i > 0; i--) {
+        const j = Math.floor(r() * (i + 1));
+        const t = a[i];
+        a[i] = a[j];
+        a[j] = t;
+    }
+    return a;
+}
+/** Train one shuffled pass — one backward write per example (online SGD).
+ *  Returns the mean loss over the epoch. */
+export function trainEpoch(net, data, r) {
+    if (data.length === 0)
+        return 0;
+    let total = 0;
+    for (const idx of shuffled(data.length, r)) {
+        const s = data[idx];
+        total += trainExample(net, s.x, s.y);
+    }
+    return total / data.length;
+}
+/** Input-space gradient toward raising logit `cls`, by one frozen-weight
+ *  backward write: with the weights held fixed the cotangent flows past them to
+ *  the input cell, which then holds dL/dInput. Drives the "dream" / saliency. */
+export function inputGradient(net, x, cls = 0) {
+    net.cfg.frozen = true;
+    net.input.value = toF64(x);
+    const z = net.logits.value; // forward
+    const seed = new Float64Array(z.length);
+    seed[Math.min(cls, z.length - 1)] = 1;
+    net.logits.value = seed;
+    void net.logits.peek(); // force the backward; the gradient lands on `input`
+    const g = net.input.peek();
+    net.cfg.frozen = false;
+    return g;
+}

package/dist/learn/mlp.d.ts

@@ -0,0 +1,77 @@
+/** Hidden/output nonlinearity. The output layer is `linear`; its squashing
+ *  (sigmoid/softmax) is folded into the loss for numerically-stable grads. */
+export type Activation = "tanh" | "relu" | "sigmoid" | "linear";
+/** Deterministic PRNG (mulberry32) so init and data are reproducible. */
+export declare function rng(seed: number): () => number;
+/** Standard normal via Box–Muller, driven by a uniform source. */
+export declare function gaussian(r: () => number): number;
+interface Layer {
+    inDim: number;
+    outDim: number;
+    act: Activation;
+    W: Float64Array;
+    b: Float64Array;
+    gW: Float64Array;
+    gb: Float64Array;
+    mW: Float64Array;
+    vW: Float64Array;
+    mb: Float64Array;
+    vb: Float64Array;
+    inBuf: Float64Array;
+    preBuf: Float64Array;
+    outBuf: Float64Array;
+}
+/** A multilayer perceptron: a `pipe` of dense layers plus an Adam step clock. */
+export interface MLP {
+    layers: Layer[];
+    /** Adam timestep (for bias correction). */
+    t: number;
+    lr: number;
+    beta1: number;
+    beta2: number;
+    l2: number;
+}
+/** Build an MLP. `dims` is `[in, h1, …, out]`; hidden layers use `hidden`
+ *  activation, the output layer is `linear` (loss folds in the squashing). */
+export declare function mlp(dims: readonly number[], opts?: {
+    seed?: number;
+    hidden?: Activation;
+    lr?: number;
+    l2?: number;
+}): MLP;
+/** Pointwise activation `a = σ(z)`. */
+export declare function applyAct(act: Activation, z: number): number;
+/** Activation derivative `σ'`, given the *output* `a` (cheap for tanh/sigmoid). */
+export declare function actGrad(act: Activation, a: number): number;
+/** Forward pass: logits (pre-squash output) for one input vector. */
+export declare function forward(net: MLP, x: Float64Array | number[]): Float64Array;
+/** Softmax of a logit vector (numerically stabilised). */
+export declare function softmax(logits: Float64Array): Float64Array;
+/** Class probabilities: sigmoid for a 1-logit (binary) net, else softmax.
+ *  A binary net returns `[P(class 1)]`. */
+export declare function predict(net: MLP, x: Float64Array | number[]): Float64Array;
+/** Argmax class for a multi-logit net, or `prob ≥ 0.5` for a binary net. */
+export declare function classify(net: MLP, x: Float64Array | number[]): number;
+/** A labelled example: input vector + integer class. */
+export interface Sample {
+    x: Float64Array | number[];
+    y: number;
+}
+/** One full-batch gradient step over `batch`. Returns the mean loss before
+ *  the update. This is the dynamical step on the weights — call it from a
+ *  clock to train. */
+export declare function trainStep(net: MLP, batch: readonly Sample[]): number;
+/** Mean cross-entropy over a dataset (no update) — for monitoring/tests. */
+export declare function meanLoss(net: MLP, data: readonly Sample[]): number;
+/** Fraction of `data` classified correctly. */
+export declare function accuracy(net: MLP, data: readonly Sample[]): number;
+/** Flattened parameter buffers `[W0, b0, W1, b1, …]` (live views). */
+export declare function parameters(net: MLP): Float64Array[];
+/** Mean-loss gradients over `batch` with no update and no weight decay,
+ *  aligned with `parameters(net)`. For gradient checking / inspection. */
+export declare function gradients(net: MLP, batch: readonly Sample[]): Float64Array[];
+/** Input-space gradient of a chosen logit, by one backward pass with a unit
+ *  seed. Drives the "dream" view (ascend pixels toward a class) and saliency.
+ *  Leaves parameter-gradient accumulators dirty; not for use mid-train-step. */
+export declare function inputGradient(net: MLP, x: Float64Array | number[], cls?: number): Float64Array;
+export {};

package/dist/learn/mlp.js

@@ -0,0 +1,292 @@
+// mlp.ts — a tiny dense neural net, written as a stack of parametric lenses.
+//
+// Backprop is the lens pattern: each layer is a forward map (compute the
+// activation) paired with a backward map (pull a gradient back to the input
+// and deposit gradients on the parameters). Composing layers composes their
+// backward passes in reverse — reverse-mode autodiff *is* lens composition,
+// exactly the `pipe` of the schema kit but over differentiable maps. The
+// "complement" a layer needs for its backward pass is the cached forward
+// activation, stashed on the layer during `forward`.
+//
+// Deliberately coarse-grained: one layer = one matmul over Float64Arrays, not
+// a cell per scalar. The reactive/bidirectional payoff lives in the demos
+// (live data, watch-it-learn); this core stays plain and fast so it is cheap
+// to run and easy to test offline.
+/** Deterministic PRNG (mulberry32) so init and data are reproducible. */
+export function rng(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t ^= t + Math.imul(t ^ (t >>> 7), 61 | t);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** Standard normal via Box–Muller, driven by a uniform source. */
+export function gaussian(r) {
+    let u = 0;
+    let v = 0;
+    while (u === 0)
+        u = r();
+    while (v === 0)
+        v = r();
+    return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
+}
+/** Build an MLP. `dims` is `[in, h1, …, out]`; hidden layers use `hidden`
+ *  activation, the output layer is `linear` (loss folds in the squashing). */
+export function mlp(dims, opts = {}) {
+    const hidden = opts.hidden ?? "tanh";
+    const r = rng(opts.seed ?? 1);
+    const layers = [];
+    for (let i = 0; i + 1 < dims.length; i++) {
+        const inDim = dims[i];
+        const outDim = dims[i + 1];
+        const act = i + 2 < dims.length ? hidden : "linear";
+        // He for relu, Xavier otherwise — keeps early activations well-scaled.
+        const scale = act === "relu" ? Math.sqrt(2 / inDim) : Math.sqrt(1 / inDim);
+        const W = new Float64Array(outDim * inDim);
+        for (let k = 0; k < W.length; k++)
+            W[k] = gaussian(r) * scale;
+        layers.push({
+            inDim,
+            outDim,
+            act,
+            W,
+            b: new Float64Array(outDim),
+            gW: new Float64Array(outDim * inDim),
+            gb: new Float64Array(outDim),
+            mW: new Float64Array(outDim * inDim),
+            vW: new Float64Array(outDim * inDim),
+            mb: new Float64Array(outDim),
+            vb: new Float64Array(outDim),
+            inBuf: new Float64Array(inDim),
+            preBuf: new Float64Array(outDim),
+            outBuf: new Float64Array(outDim),
+        });
+    }
+    return {
+        layers,
+        t: 0,
+        lr: opts.lr ?? 0.02,
+        beta1: 0.9,
+        beta2: 0.999,
+        l2: opts.l2 ?? 0,
+    };
+}
+/** Pointwise activation `a = σ(z)`. */
+export function applyAct(act, z) {
+    switch (act) {
+        case "tanh":
+            return Math.tanh(z);
+        case "relu":
+            return z > 0 ? z : 0;
+        case "sigmoid":
+            return 1 / (1 + Math.exp(-z));
+        default:
+            return z;
+    }
+}
+/** Activation derivative `σ'`, given the *output* `a` (cheap for tanh/sigmoid). */
+export function actGrad(act, a) {
+    switch (act) {
+        case "tanh":
+            return 1 - a * a;
+        case "relu":
+            return a > 0 ? 1 : 0;
+        case "sigmoid":
+            return a * (1 - a);
+        default:
+            return 1;
+    }
+}
+// Forward through one layer (the lens `fwd`): caches input + output as the
+// complement, returns the activation buffer (reused — copy if you must keep).
+function forwardLayer(L, x) {
+    L.inBuf.set(x);
+    for (let o = 0; o < L.outDim; o++) {
+        let z = L.b[o];
+        const base = o * L.inDim;
+        for (let i = 0; i < L.inDim; i++)
+            z += L.W[base + i] * x[i];
+        L.preBuf[o] = z;
+        L.outBuf[o] = applyAct(L.act, z);
+    }
+    return L.outBuf;
+}
+// Backward through one layer (the lens `bwd`): given dL/da, accumulate the
+// parameter gradients and return dL/dx for the previous layer.
+function backwardLayer(L, dOut) {
+    const dIn = new Float64Array(L.inDim);
+    for (let o = 0; o < L.outDim; o++) {
+        const dz = dOut[o] * actGrad(L.act, L.outBuf[o]);
+        L.gb[o] = L.gb[o] + dz;
+        const base = o * L.inDim;
+        for (let i = 0; i < L.inDim; i++) {
+            L.gW[base + i] = L.gW[base + i] + dz * L.inBuf[i];
+            dIn[i] = dIn[i] + L.W[base + i] * dz;
+        }
+    }
+    return dIn;
+}
+/** Forward pass: logits (pre-squash output) for one input vector. */
+export function forward(net, x) {
+    let a = x instanceof Float64Array ? x : Float64Array.from(x);
+    for (const L of net.layers)
+        a = forwardLayer(L, a);
+    return a;
+}
+/** Softmax of a logit vector (numerically stabilised). */
+export function softmax(logits) {
+    let max = Number.NEGATIVE_INFINITY;
+    for (const z of logits)
+        if (z > max)
+            max = z;
+    const out = new Float64Array(logits.length);
+    let sum = 0;
+    for (let i = 0; i < logits.length; i++) {
+        const e = Math.exp(logits[i] - max);
+        out[i] = e;
+        sum += e;
+    }
+    for (let i = 0; i < out.length; i++)
+        out[i] = out[i] / sum;
+    return out;
+}
+/** Class probabilities: sigmoid for a 1-logit (binary) net, else softmax.
+ *  A binary net returns `[P(class 1)]`. */
+export function predict(net, x) {
+    const logits = forward(net, x);
+    if (logits.length === 1)
+        return Float64Array.of(1 / (1 + Math.exp(-logits[0])));
+    return softmax(logits);
+}
+/** Argmax class for a multi-logit net, or `prob ≥ 0.5` for a binary net. */
+export function classify(net, x) {
+    const p = predict(net, x);
+    if (p.length === 1)
+        return p[0] >= 0.5 ? 1 : 0;
+    let best = 0;
+    for (let i = 1; i < p.length; i++)
+        if (p[i] > p[best])
+            best = i;
+    return best;
+}
+// Cross-entropy loss + the gradient on the logits, written into `dLogit`.
+// Binary (1 logit): BCE-with-logits, dz = sigmoid(z) − y.
+// Multi (K logits): softmax CE, dz = softmax(z) − onehot(y).
+function lossAndGrad(logits, y, dLogit) {
+    if (logits.length === 1) {
+        const z = logits[0];
+        const p = 1 / (1 + Math.exp(-z));
+        dLogit[0] = p - y;
+        const eps = 1e-12;
+        return -(y * Math.log(p + eps) + (1 - y) * Math.log(1 - p + eps));
+    }
+    const p = softmax(logits);
+    for (let k = 0; k < logits.length; k++)
+        dLogit[k] = p[k] - (k === y ? 1 : 0);
+    return -Math.log(p[y] + 1e-12);
+}
+function adamStep(net, param, g, m, v) {
+    const { lr, beta1, beta2, t } = net;
+    const bc1 = 1 - beta1 ** t;
+    const bc2 = 1 - beta2 ** t;
+    for (let i = 0; i < param.length; i++) {
+        const gi = g[i];
+        const mi = (m[i] = beta1 * m[i] + (1 - beta1) * gi);
+        const vi = (v[i] = beta2 * v[i] + (1 - beta2) * gi * gi);
+        param[i] = param[i] - (lr * (mi / bc1)) / (Math.sqrt(vi / bc2) + 1e-8);
+    }
+}
+/** One full-batch gradient step over `batch`. Returns the mean loss before
+ *  the update. This is the dynamical step on the weights — call it from a
+ *  clock to train. */
+export function trainStep(net, batch) {
+    for (const L of net.layers) {
+        L.gW.fill(0);
+        L.gb.fill(0);
+    }
+    const outDim = net.layers[net.layers.length - 1].outDim;
+    const dLogit = new Float64Array(outDim);
+    let total = 0;
+    for (const s of batch) {
+        const logits = forward(net, s.x);
+        total += lossAndGrad(logits, s.y, dLogit);
+        let g = dLogit;
+        for (let li = net.layers.length - 1; li >= 0; li--)
+            g = backwardLayer(net.layers[li], g);
+    }
+    const inv = 1 / Math.max(1, batch.length);
+    net.t += 1;
+    for (const L of net.layers) {
+        for (let i = 0; i < L.gW.length; i++)
+            L.gW[i] = L.gW[i] * inv + net.l2 * L.W[i];
+        for (let i = 0; i < L.gb.length; i++)
+            L.gb[i] = L.gb[i] * inv;
+        adamStep(net, L.W, L.gW, L.mW, L.vW);
+        adamStep(net, L.b, L.gb, L.mb, L.vb);
+    }
+    return total * inv;
+}
+/** Mean cross-entropy over a dataset (no update) — for monitoring/tests. */
+export function meanLoss(net, data) {
+    const outDim = net.layers[net.layers.length - 1].outDim;
+    const dLogit = new Float64Array(outDim);
+    let total = 0;
+    for (const s of data)
+        total += lossAndGrad(forward(net, s.x), s.y, dLogit);
+    return total / Math.max(1, data.length);
+}
+/** Fraction of `data` classified correctly. */
+export function accuracy(net, data) {
+    let ok = 0;
+    for (const s of data)
+        if (classify(net, s.x) === s.y)
+            ok++;
+    return ok / Math.max(1, data.length);
+}
+/** Flattened parameter buffers `[W0, b0, W1, b1, …]` (live views). */
+export function parameters(net) {
+    const out = [];
+    for (const L of net.layers) {
+        out.push(L.W);
+        out.push(L.b);
+    }
+    return out;
+}
+/** Mean-loss gradients over `batch` with no update and no weight decay,
+ *  aligned with `parameters(net)`. For gradient checking / inspection. */
+export function gradients(net, batch) {
+    for (const L of net.layers) {
+        L.gW.fill(0);
+        L.gb.fill(0);
+    }
+    const outDim = net.layers[net.layers.length - 1].outDim;
+    const dLogit = new Float64Array(outDim);
+    for (const s of batch) {
+        lossAndGrad(forward(net, s.x), s.y, dLogit);
+        let g = dLogit;
+        for (let li = net.layers.length - 1; li >= 0; li--)
+            g = backwardLayer(net.layers[li], g);
+    }
+    const inv = 1 / Math.max(1, batch.length);
+    const out = [];
+    for (const L of net.layers) {
+        out.push(L.gW.map(v => v * inv));
+        out.push(L.gb.map(v => v * inv));
+    }
+    return out;
+}
+/** Input-space gradient of a chosen logit, by one backward pass with a unit
+ *  seed. Drives the "dream" view (ascend pixels toward a class) and saliency.
+ *  Leaves parameter-gradient accumulators dirty; not for use mid-train-step. */
+export function inputGradient(net, x, cls = 0) {
+    forward(net, x);
+    const outDim = net.layers[net.layers.length - 1].outDim;
+    const seed = new Float64Array(outDim);
+    seed[Math.min(cls, outDim - 1)] = 1;
+    let g = seed;
+    for (let li = net.layers.length - 1; li >= 0; li--)
+        g = backwardLayer(net.layers[li], g);
+    return g;
+}

package/dist/propagators/csp.d.ts

@@ -0,0 +1,13 @@
+import { type LatticeCell } from "./lattice.js";
+import { type Propagator } from "./solver.js";
+type S<E> = LatticeCell<ReadonlySet<E>>;
+/** "These cells hold DIFFERENT values." When one collapses to a
+ *  singleton `{v}`, eliminate `v` from the others (naked-single
+ *  propagation). N(N−1) narrowers. */
+export declare function allDifferent<E>(...cells: S<E>[]): Propagator[];
+/** `a` and `b` hold the same value: intersect both candidate sets.
+ *  Unification, lifted to sets. */
+export declare function same<E>(a: S<E>, b: S<E>): Propagator[];
+/** Restrict `cell` to `allowed` (intersect). Self-applying. */
+export declare function restrict<E>(cell: S<E>, allowed: Iterable<E>): Propagator;
+export {};

package/dist/propagators/csp.js

@@ -0,0 +1,52 @@
+// csp.ts — set-narrowing relations over candidate-set cells.
+//
+// The discrete sibling of `numeric.ts`: same monotone-narrowing model,
+// finite-set lattice. Height is bounded by the universe size, so these
+// terminate structurally — sudoku, map colouring, type unification.
+import { merge } from "./lattice.js";
+import { propagator } from "./solver.js";
+/** "These cells hold DIFFERENT values." When one collapses to a
+ *  singleton `{v}`, eliminate `v` from the others (naked-single
+ *  propagation). N(N−1) narrowers. */
+export function allDifferent(...cells) {
+    const props = [];
+    for (let i = 0; i < cells.length; i++) {
+        for (let j = 0; j < cells.length; j++) {
+            if (i === j)
+                continue;
+            const src = cells[i];
+            const dst = cells[j];
+            props.push(propagator([src], [dst], () => {
+                const sv = src.value;
+                if (sv.size !== 1)
+                    return;
+                const [only] = sv;
+                if (!dst.value.has(only))
+                    return;
+                const next = new Set(dst.value);
+                next.delete(only);
+                merge(dst, next);
+            }));
+        }
+    }
+    return props;
+}
+/** `a` and `b` hold the same value: intersect both candidate sets.
+ *  Unification, lifted to sets. */
+export function same(a, b) {
+    return [
+        propagator([a], [b], () => {
+            merge(b, a.value);
+        }),
+        propagator([b], [a], () => {
+            merge(a, b.value);
+        }),
+    ];
+}
+/** Restrict `cell` to `allowed` (intersect). Self-applying. */
+export function restrict(cell, allowed) {
+    const allow = new Set(allowed);
+    return propagator([cell], [cell], () => {
+        merge(cell, allow);
+    });
+}

package/dist/propagators/flex.d.ts

@@ -0,0 +1,31 @@
+import { type Box, type Num as NumClass, type Read, type Writable } from "../core/index.js";
+import { type Propagator } from "./solver.js";
+type ValOrSig = number | Read<number>;
+/** A flex child. A bare `Box` takes defaults (grow 1, shrink 1, no
+ *  bounds); tag it to set per-item flex. `basis` seeds the size the
+ *  distribution grows/shrinks from (defaults to the box's current main
+ *  size). */
+export type Item = Box | {
+    box: Box;
+    grow?: number;
+    shrink?: number;
+    min?: number;
+    max?: number;
+    basis?: number;
+};
+export interface FlexOpts {
+    /** Space between adjacent items. Default 0. */
+    gap?: ValOrSig;
+    /** Padding inside the container on every side. Default 0. */
+    padding?: ValOrSig;
+    /** Cross-axis placement. Default "stretch". */
+    align?: "start" | "center" | "end" | "stretch";
+    /** Set to `true` on the frame(s) where the content can't fit (Σmin >
+     *  content). Drives "this layout is impossible" UI. */
+    report?: Writable<NumClass> | ((infeasible: boolean) => void);
+}
+/** Horizontal flex line over plain `Box` cells. */
+export declare function row(c: Box, items: readonly Item[], opts?: FlexOpts): Propagator;
+/** Vertical flex line over plain `Box` cells. */
+export declare function col(c: Box, items: readonly Item[], opts?: FlexOpts): Propagator;
+export {};