bireactive 0.2.4 → 0.3.1

package/dist/core/debug.d.ts

@@ -0,0 +1,25 @@
+import { Cell } from "./cell.js";
+type SomeCell = Cell<any>;
+/** Short, stable display name: the cell's `name`, else `Ctor#n`. */
+export declare function label(c: SomeCell): string;
+/** `source` (no getter), `lens` (writable derived), or `computed` (read-only derived). */
+export declare function kind(c: SomeCell): "source" | "lens" | "computed";
+/** Upstream cells: eager lens parents unioned with dynamic forward deps. */
+export declare function upstream(c: SomeCell): Cell<unknown>[];
+/** One-line summary: `name = value  [kind]` plus upstream labels, if any. */
+export declare function explain(c: SomeCell): string;
+export interface DumpOpts {
+    /** Max upstream depth to descend. Default `Infinity`. */
+    depth?: number;
+    /** Include `= value` in each line. Default `true`. */
+    values?: boolean;
+}
+/** Render the upstream graph of `root` as an indented tree (cycle-safe). */
+export declare function dumpGraph(root: SomeCell, opts?: DumpOpts): string;
+/** Run `fn` and collect the source cells written during it (back-writes included,
+ *  since a view write commits through its sources' `_writeSource`). */
+export declare function traceWrites<T>(fn: () => T): {
+    result: T;
+    writes: Cell<unknown>[];
+};
+export {};

package/dist/core/debug.js

@@ -0,0 +1,121 @@
+// debug.ts — read-only inspection of the cell graph (dev-time, no hot-path cost).
+//
+// Three small tools: `explain` (one line about a cell), `dumpGraph` (the upstream
+// dependency tree), and `traceWrites` (which sources a block of work actually
+// wrote). All walk the same edges the engine maintains — lens parents
+// (`parentEdges`, eager) unioned with dynamic forward deps (`deps`, post-read) —
+// and label cells by their optional `name` (falling back to `Ctor#n`). Nothing
+// here mutates graph state; reads go through `peek` so they don't track.
+import { Cell, isLens, isReadonly, setCellWriteHook } from "./cell.js";
+const edges = (c) => c;
+const erase = (c) => c;
+const ids = new WeakMap();
+let nextId = 1;
+function idOf(c) {
+    let i = ids.get(c);
+    if (i === undefined) {
+        i = nextId++;
+        ids.set(c, i);
+    }
+    return i;
+}
+/** Short, stable display name: the cell's `name`, else `Ctor#n`. */
+export function label(c) {
+    return c.name ?? `${c.constructor.name}#${idOf(erase(c))}`;
+}
+/** `source` (no getter), `lens` (writable derived), or `computed` (read-only derived). */
+export function kind(c) {
+    return isLens(c) ? "lens" : isReadonly(c) ? "computed" : "source";
+}
+function short(v) {
+    try {
+        if (typeof v === "string")
+            return JSON.stringify(v);
+        if (v === null || v === undefined || typeof v !== "object")
+            return String(v);
+        const s = JSON.stringify(v);
+        if (s === undefined)
+            return Object.prototype.toString.call(v);
+        return s.length > 48 ? `${s.slice(0, 47)}…` : s;
+    }
+    catch {
+        return "?";
+    }
+}
+/** Upstream cells: eager lens parents unioned with dynamic forward deps. */
+export function upstream(c) {
+    const out = [];
+    const seen = new Set();
+    const push = (n) => {
+        if (n instanceof Cell && !seen.has(n)) {
+            seen.add(n);
+            out.push(n);
+        }
+    };
+    for (let e = edges(erase(c)).parentEdges; e !== undefined; e = e.nextParent)
+        push(e.parent);
+    for (let l = edges(erase(c)).deps; l !== undefined; l = l.nextDep)
+        push(l.dep);
+    return out;
+}
+/** One-line summary: `name = value  [kind]` plus upstream labels, if any. */
+export function explain(c) {
+    let v;
+    try {
+        v = c.peek();
+    }
+    catch {
+        v = "?";
+    }
+    const ups = upstream(c);
+    const tail = ups.length > 0 ? `  ← ${ups.map(label).join(", ")}` : "";
+    return `${label(c)} = ${short(v)}  [${kind(c)}]${tail}`;
+}
+/** Render the upstream graph of `root` as an indented tree (cycle-safe). */
+export function dumpGraph(root, opts = {}) {
+    const maxDepth = opts.depth ?? Number.POSITIVE_INFINITY;
+    const withValues = opts.values ?? true;
+    const lines = [];
+    const path = new Set();
+    const line = (c, indent) => {
+        if (!withValues)
+            return `${indent}${label(c)}  [${kind(c)}]`;
+        let v;
+        try {
+            v = c.peek();
+        }
+        catch {
+            v = "?";
+        }
+        return `${indent}${label(c)} = ${short(v)}  [${kind(c)}]`;
+    };
+    const walk = (c, indent, depth) => {
+        if (path.has(c)) {
+            lines.push(`${indent}${label(c)} ↺`); // back-edge into the current path
+            return;
+        }
+        lines.push(line(c, indent));
+        if (depth >= maxDepth)
+            return;
+        path.add(c);
+        for (const u of upstream(c))
+            walk(u, `${indent}  `, depth + 1);
+        path.delete(c);
+    };
+    walk(root, "", 0);
+    return lines.join("\n");
+}
+/** Run `fn` and collect the source cells written during it (back-writes included,
+ *  since a view write commits through its sources' `_writeSource`). */
+export function traceWrites(fn) {
+    const writes = [];
+    const restore = setCellWriteHook(c => {
+        writes.push(c);
+    });
+    try {
+        return { result: fn(), writes };
+    }
+    finally {
+        restore();
+    }
+}

package/dist/core/index.d.ts

@@ -1,33 +1,28 @@
-export { batch, Cell, type CellOptions, cachedDerive, cell, derive, effect, field, type Init, type Inner, isCell, isLens, isReadonly, lazy, lens, type Network, network, type Read, reader, readNow, type StatefulBwd, type StatefulLensSpec, setCellWriteHook, transitiveDeps, untracked, type Val, type Writable, type WritableBrand, } from "./cell.js";
+export { type Counts, counts, resetCounts, snapshotCounts, withCounts } from "./_counts.js";
+export { batch, Cell, type CellOptions, cachedDerive, cell, derive, effect, fieldLens, fieldOf, type Init, type Inner, isCell, isLens, isReadonly, lazy, lens, type Network, network, type Optic, type Read, reader, readNow, SKIP, type Skip, type StatefulBwd, type StatefulBwd1, type StatefulLensSpec, type StatefulLensSpec1, setCellWriteHook, settle, transitiveDeps, untracked, type Val, type Writable, type WritableBrand, } from "./cell.js";
+export { type DumpOpts, dumpGraph, explain, kind as cellKind, label as cellLabel, traceWrites, upstream, } from "./debug.js";
 export { bezier2, bezier3 } from "./derived-geometry.js";
 export * from "./lenses/index.js";
 export { each, type Lifecycle } from "./lifecycle.js";
+export { atKey, compose, iso, optic } from "./optic.js";
+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 { Audio, type AudioClip, audio, stamp as audioStamp } from "./values/audio.js";
-export * as BoolMath from "./values/bool.js";
 export { Bool, bool } from "./values/bool.js";
-export * as BoxMath from "./values/box.js";
-export { Box, box } from "./values/box.js";
+export { Box, box, edgeFrom as boxEdgeFrom, expand as boxExpand, union as boxUnion, } from "./values/box.js";
 export { Canvas, canvas, type Raster, stamp as canvasStamp } from "./values/canvas.js";
-export * as ColorMath from "./values/color.js";
 export { Color, rgb, rgba } from "./values/color.js";
+export { type ColorStop, Colour, Field, type FieldVal, field, type Kind as FieldKind, Scalar, Vector, } from "./values/field.js";
 export { Flags, flags } from "./values/flags.js";
 export { blit as gpuBlit, brush as gpuBrush, copy as gpuCopy, newTex as gpuNewTex, Spring, scratch2 as gpuScratch2, type Tex, } from "./values/gpu.js";
-export * as MatrixMath from "./values/matrix.js";
-export { Matrix, matrix, transformBox, transformPoint } from "./values/matrix.js";
-export * as NumMath from "./values/num.js";
+export { compose as matrixCompose, Matrix, matrix, toMatrixString, transformBox, transformPoint, } from "./values/matrix.js";
 export { Num, num } from "./values/num.js";
-export * as PoseMath from "./values/pose.js";
 export { Pose, pose } from "./values/pose.js";
-export * as RangeMath from "./values/range.js";
 export { Range, range, span } from "./values/range.js";
-export * as StrMath from "./values/str.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 * as TransformMath from "./values/transform.js";
 export { Transform, type TransformInit, transform } from "./values/transform.js";
-export * as TriMath from "./values/tri.js";
 export { Tri, tri } from "./values/tri.js";
-export * as VecMath from "./values/vec.js";
 export { type PolarPolicy, polar, tangentPoint, Vec, vec } from "./values/vec.js";

package/dist/core/index.js

@@ -1,33 +1,28 @@
-export { batch, Cell, cachedDerive, cell, derive, effect, field, isCell, isLens, isReadonly, lazy, lens, network, reader, readNow, setCellWriteHook, transitiveDeps, untracked, } from "./cell.js";
+export { counts, resetCounts, snapshotCounts, withCounts } from "./_counts.js";
+export { batch, Cell, cachedDerive, cell, derive, effect, fieldLens, fieldOf, isCell, isLens, isReadonly, lazy, lens, network, reader, readNow, SKIP, setCellWriteHook, settle, transitiveDeps, untracked, } from "./cell.js";
+export { dumpGraph, explain, kind as cellKind, label as cellLabel, traceWrites, upstream, } from "./debug.js";
 export { bezier2, bezier3 } from "./derived-geometry.js";
 export * from "./lenses/index.js";
 export { each } from "./lifecycle.js";
+export { atKey, compose, iso, optic } from "./optic.js";
+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 { Audio, audio, stamp as audioStamp } from "./values/audio.js";
-export * as BoolMath from "./values/bool.js";
 export { Bool, bool } from "./values/bool.js";
-export * as BoxMath from "./values/box.js";
-export { Box, box } from "./values/box.js";
+export { Box, box, edgeFrom as boxEdgeFrom, expand as boxExpand, union as boxUnion, } from "./values/box.js";
 export { Canvas, canvas, stamp as canvasStamp } from "./values/canvas.js";
-export * as ColorMath from "./values/color.js";
 export { Color, rgb, rgba } from "./values/color.js";
+export { Colour, Field, field, Scalar, Vector, } from "./values/field.js";
 export { Flags, flags } from "./values/flags.js";
 export { blit as gpuBlit, brush as gpuBrush, copy as gpuCopy, newTex as gpuNewTex, Spring, scratch2 as gpuScratch2, } from "./values/gpu.js";
-export * as MatrixMath from "./values/matrix.js";
-export { Matrix, matrix, transformBox, transformPoint } from "./values/matrix.js";
-export * as NumMath from "./values/num.js";
+export { compose as matrixCompose, Matrix, matrix, toMatrixString, transformBox, transformPoint, } from "./values/matrix.js";
 export { Num, num } from "./values/num.js";
-export * as PoseMath from "./values/pose.js";
 export { Pose, pose } from "./values/pose.js";
-export * as RangeMath from "./values/range.js";
 export { Range, range, span } from "./values/range.js";
-export * as StrMath from "./values/str.js";
 export { Str, str } from "./values/str.js";
 export { enumCodec, numCodec, route, slot, strCodec, template, tpl, } from "./values/template.js";
-export * as TransformMath from "./values/transform.js";
 export { Transform, transform } from "./values/transform.js";
-export * as TriMath from "./values/tri.js";
 export { Tri, tri } from "./values/tri.js";
-export * as VecMath from "./values/vec.js";
 export { polar, tangentPoint, Vec, vec } from "./values/vec.js";

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

@@ -1,4 +1,4 @@
-import type { Writable } from "../cell.js";
+import { type Writable } from "../cell.js";
 import { Num } from "../values/num.js";
 import { Vec } from "../values/vec.js";
 export interface ArgminOpts {

package/dist/core/lenses/aggregates.js

@@ -5,6 +5,7 @@
 // All route through the engine's N-input lens path. Stateless-bwd
 // (`(target) => updates`) skips the peek loop on the hot path;
 // stateful-bwd (`(target, vals) => updates`) reads the scratch.
+import { SKIP } from "../cell.js";
 import { Num } from "../values/num.js";
 import { Vec } from "../values/vec.js";
 /** Project `p` into the closed disc of radius `r` centred on `c` (points
@@ -51,7 +52,7 @@ export function argminNum(inputs, forward, weights, opts = {}) {
         const k = dy / denom;
         for (let i = 0; i < n; i++) {
             if (weights[i] === 0) {
-                out[i] = undefined;
+                out[i] = SKIP;
             }
             else {
                 out[i] = xs[i] + weights[i] * J[i] * k;
@@ -103,7 +104,7 @@ export function argminVec(inputs, forward, weights, opts = {}) {
         if (Math.abs(det) < 1e-14) {
             // Singular; leave inputs unchanged.
             for (let i = 0; i < n; i++)
-                out[i] = undefined;
+                out[i] = SKIP;
             return out;
         }
         const invA = c / det;
@@ -114,7 +115,7 @@ export function argminVec(inputs, forward, weights, opts = {}) {
         for (let i = 0; i < n; i++) {
             const w = weights[i];
             if (w === 0) {
-                out[i] = undefined;
+                out[i] = SKIP;
             }
             else {
                 out[i] = xs[i] + w * (Jx[i] * kx + Jy[i] * ky);

package/dist/core/lenses/closed-form-policies.js

@@ -10,7 +10,7 @@
 // (bestFitLine, bestFitCircle, pca, total). All exact, idempotent,
 // cross-channel invariant by construction, on the same `Cls.lens`
 // machinery — no engine changes.
-import { mean, Num, Vec, } from "../index.js";
+import { mean, Num, SKIP, Vec, } from "../index.js";
 import { continuous, remember } from "./memory.js";
 // Pivotal trait lookup via the value class's `static traits.pivotal` slot.
 // biome-ignore lint/suspicious/noExplicitAny: dynamic trait lookup
@@ -50,7 +50,7 @@ export function rotateAbout(points, pivot) {
         const rx0 = vals[0].x - p.x;
         const ry0 = vals[0].y - p.y;
         if (rx0 * rx0 + ry0 * ry0 < 1e-24) {
-            return vals.map(() => undefined);
+            return vals.map(() => SKIP);
         }
         const oldθ = Math.atan2(ry0, rx0);
         const dθ = target - oldθ;
@@ -96,11 +96,11 @@ export function scaleAbout(points, pivot) {
             // re-projects to the current radius and is absorbed (sources put).
             const rNow = Math.hypot(vals[0].x - p.x, vals[0].y - p.y);
             if (Math.abs(target) === rNow)
-                return { updates: vals.map(() => undefined), complement: c };
+                return { updates: vals.map(() => SKIP), complement: c };
             const d0 = c.devs[0];
             const r0 = Math.hypot(d0.x, d0.y);
             if (r0 < 1e-12)
-                return { updates: vals.map(() => undefined), complement: c };
+                return { updates: vals.map(() => SKIP), complement: c };
             const k = target / r0;
             const out = vals.map((v, i) => ({
                 ...v,
@@ -299,7 +299,7 @@ export function pca(points) {
     const rotation = Num.lens(points, (vals) => decompose(vals)?.θ ?? 0, (target, vals) => {
         const d = decompose(vals);
         if (!d)
-            return vals.map(() => undefined);
+            return vals.map(() => SKIP);
         const dθ = target - d.θ;
         const cos = Math.cos(dθ);
         const sin = Math.sin(dθ);
@@ -382,10 +382,15 @@ export function pca(points) {
                     // Lossy magnitude view: a same-magnitude target re-projects to
                     // the current axis length and is absorbed (cluster left put).
                     if (Math.abs(target) === c.lenThis)
-                        return { updates: vals.map(() => undefined), complement: c };
-                    // Non-degenerate fast path: scale current cluster along axis.
+                        return { updates: vals.map(() => SKIP), complement: c };
+                    // Non-degenerate fast path: scale current cluster along axis. The scale
+                    // sets the axis length to |target|, so the complement is consistent
+                    // without a post-write `step` (the engine no longer re-steps own writes).
                     const k = target / c.lenThis;
-                    return { updates: scaleAlongAxis(vals, d.cx, d.cy, c.uX, c.uY, k), complement: c };
+                    return {
+                        updates: scaleAlongAxis(vals, d.cx, d.cy, c.uX, c.uY, k),
+                        complement: { ...c, lenThis: Math.abs(target) },
+                    };
                 }
                 // Degenerate: reconstruct from complement. Centroid still
                 // derivable from current source (mean translates always work).
@@ -403,7 +408,7 @@ export function pca(points) {
                     const b = c.projOther[i] * c.lenOther;
                     out[i] = { x: cx + a * c.uX + b * c.vX, y: cy + a * c.uY + b * c.vY };
                 }
-                return { updates: out, complement: c };
+                return { updates: out, complement: { ...c, lenThis: Math.abs(target) } };
             },
         });
     };

package/dist/core/lenses/decompositions.js

@@ -6,7 +6,7 @@
 // about the centroid), so cross-channel invariance is EXACT and one
 // write lands in O(K). For the generic numerical N→M escape hatch (when
 // no closed form fits) see `factor` in `typed-factor.ts`.
-import { Num, Vec } from "../index.js";
+import { Num, SKIP, Vec } from "../index.js";
 // meanDiff — M=2 isomorphism baseline.
 //
 // (a, b) → ((a+b)/2, a−b). Square full-rank linear lens; bwd is the
@@ -84,7 +84,7 @@ export function procrustes(points) {
         const ry0 = vals[0].y - cy;
         if (rx0 * rx0 + ry0 * ry0 < 1e-24) {
             // Collapsed cluster; no angle to rotate from.
-            return vals.map(() => undefined);
+            return vals.map(() => SKIP);
         }
         const oldθ = Math.atan2(ry0, rx0);
         const dθ = target - oldθ;
@@ -130,7 +130,7 @@ export function procrustes(points) {
             const d0 = c.devs[0];
             const r0 = Math.hypot(d0.x, d0.y);
             if (r0 < 1e-12)
-                return { updates: vals.map(() => undefined), complement: c };
+                return { updates: vals.map(() => SKIP), complement: c };
             const k = target / r0;
             const out = c.devs.map(d => ({ x: cen.x + k * d.x, y: cen.y + k * d.y }));
             return { updates: out, complement: c };

package/dist/core/lenses/domain-aggregates.js

@@ -6,7 +6,7 @@
 //   (2) Bezier gestalt handles ({start, end, startTangent, endTangent}).
 //   (3) Time-series ({mean, slope}) over (i, value) samples.
 // All exact, idempotent, cross-channel invariant by construction.
-import { Num, reader, Vec, } from "../index.js";
+import { Num, reader, SKIP, Vec, } from "../index.js";
 import { remember } from "./memory.js";
 // Generic Linear-trait aggregates.
 //
@@ -107,9 +107,9 @@ export function mix(weights, branches) {
         const { w, sumSq } = readW();
         const delta = lin.sub(target, combine(vals, w));
         if (sumSq < 1e-12)
-            return vals.map(() => undefined);
+            return vals.map(() => SKIP);
         const inv = 1 / sumSq;
-        return vals.map((v, i) => w[i] === 0 ? undefined : lin.add(v, lin.scale(delta, w[i] * inv)));
+        return vals.map((v, i) => w[i] === 0 ? SKIP : lin.add(v, lin.scale(delta, w[i] * inv)));
     });
 }
 /** Two-branch router (mix simplex *vertex*): reads the live branch, writes
@@ -187,8 +187,8 @@ export function bezierGestalt(p0, p1, p2, p3) {
         const dy = target.y - vals[1].y;
         return [{ x: vals[0].x + dx, y: vals[0].y + dy }, target];
     });
-    const startTangent = Vec.lens([p0, p1], (vals) => ({ x: vals[1].x - vals[0].x, y: vals[1].y - vals[0].y }), (target, vals) => [undefined, { x: vals[0].x + target.x, y: vals[0].y + target.y }]);
-    const endTangent = Vec.lens([p2, p3], (vals) => ({ x: vals[1].x - vals[0].x, y: vals[1].y - vals[0].y }), (target, vals) => [{ x: vals[1].x - target.x, y: vals[1].y - target.y }, undefined]);
+    const startTangent = Vec.lens([p0, p1], (vals) => ({ x: vals[1].x - vals[0].x, y: vals[1].y - vals[0].y }), (target, vals) => [SKIP, { x: vals[0].x + target.x, y: vals[0].y + target.y }]);
+    const endTangent = Vec.lens([p2, p3], (vals) => ({ x: vals[1].x - vals[0].x, y: vals[1].y - vals[0].y }), (target, vals) => [{ x: vals[1].x - target.x, y: vals[1].y - target.y }, SKIP]);
     return { start, end, startTangent, endTangent };
 }
 // Time-series aggregates.

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

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

package/dist/core/lenses/geometry.js

@@ -1,5 +1,6 @@
 // geometry.ts — geometric lens building blocks over the N-input
 // `Cls.lens` / `Cls.derive` forms. All are a few lines on top of the engine.
+import { SKIP } from "../cell.js";
 import { Num } from "../values/num.js";
 import { Vec } from "../values/vec.js";
 import { rotateAbout } from "./closed-form-policies.js";
@@ -36,7 +37,7 @@ export function reflection(point, axisStart, axisEnd) {
         const projY = a.y + t * dy;
         return { x: 2 * projX - p.x, y: 2 * projY - p.y };
     };
-    return Vec.lens([point, axisStart, axisEnd], vals => reflect(vals[0], vals[1], vals[2]), (target, vals) => [reflect(target, vals[1], vals[2]), undefined, undefined]);
+    return Vec.lens([point, axisStart, axisEnd], vals => reflect(vals[0], vals[1], vals[2]), (target, vals) => [reflect(target, vals[1], vals[2]), SKIP, SKIP]);
 }
 /** Lerp between two Vecs at parameter `t`. Writing the interpolated point
  *  shifts both endpoints rigidly (preserving t). */
@@ -48,7 +49,7 @@ export function vecLerp(a, b, t) {
         const [av, bv, tv] = vals;
         const dx = target.x - (av.x + (bv.x - av.x) * tv);
         const dy = target.y - (av.y + (bv.y - av.y) * tv);
-        return [{ x: av.x + dx, y: av.y + dy }, { x: bv.x + dx, y: bv.y + dy }, undefined];
+        return [{ x: av.x + dx, y: av.y + dy }, { x: bv.x + dx, y: bv.y + dy }, SKIP];
     });
 }
 /** Sum of two nums; writing the sum splits the delta equally between
@@ -77,23 +78,21 @@ export function clampedMean(parents, lo, hi) {
     const n = parents.length;
     const inv = 1 / n;
     return Num.lens(parents, vals => {
-        const arr = vals;
         let s = 0;
         for (let i = 0; i < n; i++)
-            s += arr[i];
+            s += vals[i];
         const m = s * inv;
         return m < lo ? lo : m > hi ? hi : m;
     }, (target, vals) => {
-        const arr = vals;
         const clamped = target < lo ? lo : target > hi ? hi : target;
         let s = 0;
         for (let i = 0; i < n; i++)
-            s += arr[i];
+            s += vals[i];
         const cur = s * inv;
         const delta = clamped - cur;
         const out = new Array(n);
         for (let i = 0; i < n; i++)
-            out[i] = arr[i] + delta;
+            out[i] = vals[i] + delta;
         return out;
     });
 }

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

@@ -4,4 +4,5 @@ export { bbox, meanDiff, procrustes } from "./decompositions.js";
 export { bezierGestalt, crossfade, mean, meanSpread, mix, select, spread, timeSeries, } from "./domain-aggregates.js";
 export { angle, clampedMean, diff, distance, pulleySum, reflection, vecLerp } from "./geometry.js";
 export { type ContinuousOpts, continuous, type RememberOpts, remember, } from "./memory.js";
+export { type ClosestOpts, hullWeights, nearestIndex } from "./snap.js";
 export { bundle, type FactorOpts, type FactorResult, factor, factorTuple, type OutputSpec, type PackedInput, } from "./typed-factor.js";

package/dist/core/lenses/index.js

@@ -4,4 +4,5 @@ export { bbox, meanDiff, procrustes } from "./decompositions.js";
 export { bezierGestalt, crossfade, mean, meanSpread, mix, select, spread, timeSeries, } from "./domain-aggregates.js";
 export { angle, clampedMean, diff, distance, pulleySum, reflection, vecLerp } from "./geometry.js";
 export { continuous, remember, } from "./memory.js";
+export { hullWeights, nearestIndex } from "./snap.js";
 export { bundle, factor, factorTuple, } from "./typed-factor.js";

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

@@ -1,4 +1,4 @@
-import { type Cell, Num, type Traits, type Writable } from "../index.js";
+import { type Cell, Num, type Skip, type Traits, type Writable } from "../index.js";
 /** Options for {@link remember}. `anchor` is the fixed point sources scale
  *  about (a pivot, or the live centroid); `feature` is the writable scalar
  *  (a radius, mean distance, or sum). */
@@ -38,7 +38,7 @@ export interface ContinuousOpts<T> {
     };
     /** Realize `target` (already unwrapped, absolute) onto the sources,
      *  given the `current` unwrapped reading (for a delta). */
-    apply: (target: number, vals: readonly T[], current: number) => readonly (T | undefined)[];
+    apply: (target: number, vals: readonly T[], current: number) => readonly (T | Skip)[];
 }
 /** Continuous (winding-aware) lens over a cyclic reading. The complement
  *  tracks the last emitted value and unwraps each raw reading to the

package/dist/core/lenses/memory.js

@@ -15,7 +15,7 @@
 //                unwraps the raw reading to the nearest sheet, so the
 //                view never tears at a branch cut. Covers the eigenvector
 //                angle of bestFitLine; the primitive behind winding.
-import { Num } from "../index.js";
+import { Num, SKIP } from "../index.js";
 /** Scalar shape-memory lens. Reads `feature(sources)`; writing it scales
  *  the cluster about `anchor` so the new feature matches, reinflating the
  *  remembered shape when the cluster has collapsed onto the anchor. The
@@ -59,7 +59,7 @@ export function remember(sources, opts) {
             // Magnitude is lossy (|−f| = f): a same-magnitude target re-projects
             // to the current feature, so the cluster is left put.
             if (magnitude && Math.abs(target) === f) {
-                return { updates: vals.map(() => undefined), complement: c };
+                return { updates: vals.map(() => SKIP), complement: c };
             }
             if (f > eps) {
                 const k = target / f;
@@ -94,7 +94,7 @@ export function continuous(sources, opts) {
         bwd: (target, vals, c) => {
             const r = raw(vals);
             if (!r.defined)
-                return { updates: vals.map(() => undefined), complement: { prev: target } };
+                return { updates: vals.map(() => SKIP), complement: { prev: target } };
             const current = unwrap(r.value, c.prev);
             return { updates: apply(target, vals, current), complement: { prev: target } };
         },

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

@@ -0,0 +1,18 @@
+import { type Cell, type Read } from "../cell.js";
+type V = {
+    x: number;
+    y: number;
+};
+/** Convex-hull barycentric weights of `q` over `pts` (Σ = 1, all ≥ 0,
+ *  clamped to the hull). Closed form for K ≤ 3; Frank–Wolfe for K > 3. */
+export declare function hullWeights(q: V, pts: readonly V[]): number[];
+export interface ClosestOpts {
+    /** Hysteresis margin (px): the current pick is kept until a rival is
+     *  nearer by more than this. Dragology's stickiness. Default 0. */
+    sticky?: number;
+}
+/** Index of the candidate nearest `pointer`, with hysteresis. Read-only
+ *  selection: the stickiness state lives in the lens complement (the
+ *  sanctioned place for path-dependence), so reads stay pure. */
+export declare function nearestIndex(pointer: Read<V>, candidates: readonly Read<V>[], opts?: ClosestOpts): Cell<number>;
+export {};