bireactive 0.3.0 → 0.3.2

package/dist/core/lenses/{closed-form-policies.js → point-cloud.js}

@@ -1,16 +1,9 @@
-// closed-form-policies.ts — exact group-action lenses for point clouds.
-//
-// When an aggregate lens has a closed-form inverse, its bwd applies a
-// GROUP ELEMENT to the source set. Translation, rotation-about-pivot,
-// and scale-about-pivot are the building blocks; Procrustes, best-fit
-// line/circle, and PCA decompose into combinations of them.
-//
-// Layout: building-block actions (rigidTranslate, rotateAbout,
-// scaleAbout, scaleAboutXY), then closed-form decompositions
-// (bestFitLine, bestFitCircle, pca, total). All exact, idempotent,
-// cross-channel invariant by construction, on the same `Cls.lens`
-// machinery — no engine changes.
-import { mean, Num, SKIP, Vec, } from "../index.js";
+// Exact group-action lenses for point clouds. The backward pass applies a
+// group element (translate / rotate / scale about a pivot) to the whole
+// source set, so the fits below (bestFitLine, bestFitCircle, pca, procrustes)
+// are exact and cross-channel invariant.
+import { Num, SKIP, Vec, } from "../index.js";
+import { mean } from "./aggregates.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
@@ -20,23 +13,14 @@ function pivotalOf(input) {
     const p = Cls.traits?.pivotal;
     if (!p) {
         const name = Cls.name ?? "?";
-        throw new Error(`closed-form-policies: ${name} has no traits.pivotal`);
+        throw new Error(`point-cloud: ${name} has no traits.pivotal`);
     }
     return p;
 }
-/** Writable centroid; on write, translates every point by the delta.
- *  The Vec-specific group-action reading of `mean`. */
-export function rigidTranslate(points) {
-    return mean(points);
-}
 /** Writable angle from `pivot` to `points[0]`; write rotates every input
- *  about `pivot` by (target − current) via its `Pivotal` trait.
- *
- *  Trait-generic: Vec rotates position; Pose rotates position AND
- *  orientation. Rotation-about-pivot fixes the pivot and preserves radial
- *  distances, so scale-about-pivot reads unchanged. `pivot` is reactive
- *  (re-read per write); pass `rigidTranslate(points)` for rotation about
- *  the cluster's own centroid. */
+ *  about `pivot` by (target − current) via its `Pivotal` trait (Vec rotates
+ *  position, Pose also rotates orientation). `pivot` is reactive; pass
+ *  `mean(points)` to rotate about the cluster's own centroid. */
 export function rotateAbout(points, pivot) {
     const K = points.length;
     if (K < 1)
@@ -61,13 +45,9 @@ export function rotateAbout(points, pivot) {
     });
 }
 /** Writable radial distance from pivot to `points[0]`; write scales every
- *  input radially about `pivot` (negative target reflects). Exact
- *  cross-channel invariance with `rotateAbout`.
- *
- *  Complement carries per-point offsets from the pivot at the last
- *  non-degenerate state, so a collapse onto the pivot (radius ≈ 0)
- *  reinflates from the stored shape. Pose `theta` survives the round-trip
- *  (only spatial offset is stored). */
+ *  input radially about `pivot` (negative target reflects). The complement
+ *  carries per-point offsets from the pivot, so a collapse onto it (radius
+ *  ≈ 0) reinflates from the stored shape. Pose `theta` survives. */
 export function scaleAbout(points, pivot) {
     const K = points.length;
     if (K < 1)
@@ -111,10 +91,9 @@ export function scaleAbout(points, pivot) {
         },
     });
 }
-/** Per-axis scale about a pivot. Vec-specific (Pivotal has no per-axis
- *  method yet). Complement carries per-point per-axis fractions of
- *  point 0's offset, so a per-axis collapse is recoverable (cf.
- *  `bboxLens.size`). */
+/** Per-axis scale about a pivot (Vec-specific). The complement carries
+ *  per-point per-axis fractions of point 0's offset, so a per-axis collapse
+ *  is recoverable. */
 export function scaleAboutXY(points, pivot) {
     const K = points.length;
     if (K < 1)
@@ -153,13 +132,6 @@ export function scaleAboutXY(points, pivot) {
         },
     });
 }
-// Best-fit line.
-//
-// K points → {point: centroid, direction: principal-axis angle}.
-//   write point     → rigidTranslate
-//   write direction → rotate all about centroid to set principal axis
-// Invariance: principal axis is translation-invariant; centroid is
-// invariant under rotation-about-itself.
 /** Angle of the dominant eigenvector of symmetric 2×2 [[cxx,cxy],[cxy,cyy]]. */
 function dominantAxisAngle(cxx, cxy, cyy) {
     return 0.5 * Math.atan2(2 * cxy, cxx - cyy);
@@ -178,16 +150,16 @@ function covariance(points, cx, cy) {
     }
     return { cxx: cxx / K, cxy: cxy / K, cyy: cyy / K };
 }
+/** K points → {point: centroid, direction: principal-axis angle}. Writing
+ *  `point` translates; writing `direction` rotates all about the centroid. */
 export function bestFitLine(points) {
     const K = points.length;
     if (K < 2)
         throw new Error("bestFitLine: need ≥ 2 points");
-    const point = rigidTranslate(points);
-    // The principal axis is an eigenvector — defined only up to sign, so the
-    // raw atan2 jumps by π as the cloud rotates. `continuous` lifts it to its
-    // universal cover (period π, since axis ≡ axis + π), tracking the last
-    // emitted angle so the direction stays continuous; a collapsed cloud has
-    // no axis (`defined: false`), so it freezes and stashes the target.
+    const point = mean(points);
+    // Axis angle is an eigenvector direction (defined up to sign), so the raw
+    // atan2 jumps by π as the cloud rotates; `continuous` (period π) tracks the
+    // last emitted angle to stay continuous, freezing on a collapsed cloud.
     // Centroid + dominant-axis raw angle; `degenerate` when covariance vanishes.
     const axisOf = (vals) => {
         let sx = 0;
@@ -225,18 +197,13 @@ export function bestFitLine(points) {
     });
     return { point, direction };
 }
-// Best-fit circle.
-//
-// K points → {center: centroid, radius: mean distance from center}.
-//   write center → rigidTranslate
-//   write radius → scale all about center by target/current
-// Simplest closed-form fit (mean center). Invariance: translation
-// preserves radii; uniform scale-about-center preserves the center.
+/** K points → {center: centroid, radius: mean distance from center}. Writing
+ *  `center` translates; writing `radius` scales all about the center. */
 export function bestFitCircle(points) {
     const K = points.length;
     if (K < 1)
         throw new Error("bestFitCircle: need ≥ 1 point");
-    const center = rigidTranslate(points);
+    const center = mean(points);
     // Radius = mean distance from the centroid; writing it scales the cluster
     // about the centroid, and a collapse (mean → 0) reinflates the remembered
     // shape — exactly `remember`'s magnitude view, anchored at the centroid.
@@ -261,20 +228,14 @@ export function bestFitCircle(points) {
     });
     return { center, radius };
 }
-// PCA / affine similarity decomposition.
-//
-// K points → {mean: centroid, rotation: dominant-eigenvector angle,
-//   majorLength: √λ_major, minorLength: √λ_minor (per-axis std-devs)}.
-//   write mean        → rigidTranslate
-//   write rotation    → rotate all about mean to set principal axis
-//   write major/minor → scale along that axis by target/current
-// Each write is a single group action; cross-channel invariance holds
-// for all pairs.
+/** K points → {mean: centroid, rotation: dominant-eigenvector angle,
+ *  majorLength/minorLength: per-axis std-devs (√λ)}. Each write is a single
+ *  group action about the mean, so all pairs are cross-channel invariant. */
 export function pca(points) {
     const K = points.length;
     if (K < 2)
         throw new Error("pca: need ≥ 2 points");
-    const mean = rigidTranslate(points);
+    const meanCell = mean(points);
     // 2×2 symmetric eigendecomp → {θ, λ_major, λ_minor}; null when fully
     // collapsed (λ_major ≈ 0).
     const decompose = (vals) => {
@@ -383,9 +344,14 @@ export function pca(points) {
                     // the current axis length and is absorbed (cluster left put).
                     if (Math.abs(target) === c.lenThis)
                         return { updates: vals.map(() => SKIP), complement: c };
-                    // Non-degenerate fast path: scale current cluster along axis.
+                    // 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,23 +369,17 @@ 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) } };
             },
         });
     };
     const majorLength = buildAxisLens("major");
     const minorLength = buildAxisLens("minor");
-    return { mean, rotation, majorLength, minorLength };
+    return { mean: meanCell, rotation, majorLength, minorLength };
 }
-// Partition / simplex lens.
-//
-// K parts → {total}: writing total scales all parts proportionally.
-// (A {total, ratios} form is possible but ratios on a K-simplex have
-// K−1 DOF, so it's left out of this prototype.)
 /** Writable total over K parts; write scales all parts proportionally,
- *  preserving their ratios. A `remember` anchored at zero with a signed
- *  sum feature: a collapse to zero reinflates the stored ratios, seeded
- *  uniform so an all-zero start splits evenly. */
+ *  preserving their ratios. A collapse to zero reinflates the stored ratios,
+ *  seeded uniform so an all-zero start splits evenly. */
 export function total(parts) {
     const K = parts.length;
     if (K < 1)
@@ -436,7 +396,189 @@ export function total(parts) {
         seed: () => parts.map(() => 1 / K),
     });
 }
-// Every lens here is a group action about a pivot (translate, rotateAbout,
-// scaleAbout, scaleAboutXY, scaleAlongAxis) or a `remember`/`continuous`
-// shape-memory; the decompositions combine them, each measured against a
-// derived feature (centroid, principal axis, mean radius).
+/** K Vecs → {centroid, rotation (angle of point[0] about centroid), scale
+ *  (its distance from centroid)}. Each write is a closed-form transform about
+ *  the centroid (translate / rotate / scale), so the three are cross-channel
+ *  invariant. A collapsed cluster makes rotation singular and scale a no-op. */
+export function procrustes(points) {
+    const K = points.length;
+    if (K < 2)
+        throw new Error("procrustes: need ≥ 2 points");
+    const centroid = Vec.lens(points, (vals) => {
+        let sx = 0;
+        let sy = 0;
+        for (let i = 0; i < K; i++) {
+            sx += vals[i].x;
+            sy += vals[i].y;
+        }
+        return { x: sx / K, y: sy / K };
+    }, (target, vals) => {
+        let sx = 0;
+        let sy = 0;
+        for (let i = 0; i < K; i++) {
+            sx += vals[i].x;
+            sy += vals[i].y;
+        }
+        const dx = target.x - sx / K;
+        const dy = target.y - sy / K;
+        const out = new Array(K);
+        for (let i = 0; i < K; i++)
+            out[i] = { x: vals[i].x + dx, y: vals[i].y + dy };
+        return out;
+    });
+    const rotation = Num.lens(points, (vals) => {
+        let sx = 0;
+        let sy = 0;
+        for (let i = 0; i < K; i++) {
+            sx += vals[i].x;
+            sy += vals[i].y;
+        }
+        const cx = sx / K;
+        const cy = sy / K;
+        return Math.atan2(vals[0].y - cy, vals[0].x - cx);
+    }, (target, vals) => {
+        let sx = 0;
+        let sy = 0;
+        for (let i = 0; i < K; i++) {
+            sx += vals[i].x;
+            sy += vals[i].y;
+        }
+        const cx = sx / K;
+        const cy = sy / K;
+        const rx0 = vals[0].x - cx;
+        const ry0 = vals[0].y - cy;
+        if (rx0 * rx0 + ry0 * ry0 < 1e-24) {
+            // Collapsed cluster; no angle to rotate from.
+            return vals.map(() => SKIP);
+        }
+        const oldθ = Math.atan2(ry0, rx0);
+        const dθ = target - oldθ;
+        const cos = Math.cos(dθ);
+        const sin = Math.sin(dθ);
+        const out = new Array(K);
+        for (let i = 0; i < K; i++) {
+            const rx = vals[i].x - cx;
+            const ry = vals[i].y - cy;
+            out[i] = { x: cx + cos * rx - sin * ry, y: cy + sin * rx + cos * ry };
+        }
+        return out;
+    });
+    const centroidOf = (vals) => {
+        let sx = 0;
+        let sy = 0;
+        for (let i = 0; i < K; i++) {
+            sx += vals[i].x;
+            sy += vals[i].y;
+        }
+        return { x: sx / K, y: sy / K };
+    };
+    const refreshDevs = (devs, vals) => {
+        const c = centroidOf(vals);
+        return devs.map((d, i) => {
+            const dx = vals[i].x - c.x;
+            const dy = vals[i].y - c.y;
+            return dx * dx + dy * dy > 1e-18 ? { x: dx, y: dy } : d;
+        });
+    };
+    const scale = Num.lens(points, {
+        init: (vals) => {
+            const c = centroidOf(vals);
+            return { devs: vals.map(v => ({ x: v.x - c.x, y: v.y - c.y })) };
+        },
+        step: (vals, c) => ({ devs: refreshDevs(c.devs, vals) }),
+        fwd: (vals) => {
+            const c = centroidOf(vals);
+            return Math.hypot(vals[0].x - c.x, vals[0].y - c.y);
+        },
+        bwd: (target, vals, c) => {
+            const cen = centroidOf(vals);
+            const d0 = c.devs[0];
+            const r0 = Math.hypot(d0.x, d0.y);
+            if (r0 < 1e-12)
+                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 };
+        },
+    });
+    return { centroid, rotation, scale };
+}
+/** K Vecs → {center, size} of the axis-aligned bounding box. Writing `center`
+ *  translates; writing `size` scales all about the center per-axis. Degenerate
+ *  axes (size = 0) write as no-ops; negative size reflects. */
+export function bbox(points) {
+    const K = points.length;
+    if (K < 1)
+        throw new Error("bbox: need ≥ 1 point");
+    const computeBox = (vals) => {
+        let minX = Number.POSITIVE_INFINITY;
+        let minY = Number.POSITIVE_INFINITY;
+        let maxX = Number.NEGATIVE_INFINITY;
+        let maxY = Number.NEGATIVE_INFINITY;
+        for (let i = 0; i < K; i++) {
+            const x = vals[i].x;
+            const y = vals[i].y;
+            if (x < minX)
+                minX = x;
+            if (x > maxX)
+                maxX = x;
+            if (y < minY)
+                minY = y;
+            if (y > maxY)
+                maxY = y;
+        }
+        return {
+            cx: (minX + maxX) / 2,
+            cy: (minY + maxY) / 2,
+            sx: maxX - minX,
+            sy: maxY - minY,
+        };
+    };
+    const center = Vec.lens(points, (vals) => {
+        const b = computeBox(vals);
+        return { x: b.cx, y: b.cy };
+    }, (target, vals) => {
+        const b = computeBox(vals);
+        const dx = target.x - b.cx;
+        const dy = target.y - b.cy;
+        const out = new Array(K);
+        for (let i = 0; i < K; i++)
+            out[i] = { x: vals[i].x + dx, y: vals[i].y + dy };
+        return out;
+    });
+    const refreshFracs = (fracs, vals) => {
+        const b = computeBox(vals);
+        const hx = b.sx > 1e-12 ? b.sx / 2 : 0;
+        const hy = b.sy > 1e-12 ? b.sy / 2 : 0;
+        return fracs.map((f, i) => ({
+            x: hx > 0 ? (vals[i].x - b.cx) / hx : f.x,
+            y: hy > 0 ? (vals[i].y - b.cy) / hy : f.y,
+        }));
+    };
+    const size = Vec.lens(points, {
+        init: (vals) => {
+            const b = computeBox(vals);
+            const halfX0 = b.sx > 1e-12 ? b.sx / 2 : 1;
+            const halfY0 = b.sy > 1e-12 ? b.sy / 2 : 1;
+            return {
+                fracs: vals.map(v => ({
+                    x: b.sx > 1e-12 ? (v.x - b.cx) / halfX0 : 0,
+                    y: b.sy > 1e-12 ? (v.y - b.cy) / halfY0 : 0,
+                })),
+            };
+        },
+        step: (vals, c) => ({ fracs: refreshFracs(c.fracs, vals) }),
+        fwd: (vals) => {
+            const b = computeBox(vals);
+            return { x: b.sx, y: b.sy };
+        },
+        bwd: (target, vals, c) => {
+            const b = computeBox(vals);
+            const halfTx = target.x / 2;
+            const halfTy = target.y / 2;
+            const out = c.fracs.map(f => ({ x: b.cx + f.x * halfTx, y: b.cy + f.y * halfTy }));
+            return { updates: out, complement: c };
+        },
+    });
+    return { center, size };
+}

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. 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 {};

package/dist/core/lenses/snap.js

@@ -0,0 +1,138 @@
+// Pointer math for the drag algebra: `hullWeights` (barycentric weights of a
+// point in a convex hull) and `nearestIndex` (nearest candidate, with sticky
+// hysteresis carried in the lens complement).
+import { lens, SKIP } from "../cell.js";
+const sub = (a, b) => ({ x: a.x - b.x, y: a.y - b.y });
+const dot = (a, b) => a.x * b.x + a.y * b.y;
+const dist2 = (a, b) => {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    return dx * dx + dy * dy;
+};
+// ── convex-hull barycentric weights ─────────────────────────────────
+/** Project `q` onto segment p0→p1; weights `[1−t, t]`, t clamped to [0,1]. */
+function segmentWeights(q, p0, p1) {
+    const d = sub(p1, p0);
+    const len2 = dot(d, d);
+    if (len2 < 1e-18)
+        return [0.5, 0.5];
+    const t = Math.max(0, Math.min(1, dot(sub(q, p0), d) / len2));
+    return [1 - t, t];
+}
+/** Barycentric weights of `q` in triangle (p0,p1,p2), CLAMPED to the
+ *  triangle: inside → the true coords; outside → the nearest point on the
+ *  hull (an edge projection or a vertex), so the blend never extrapolates. */
+function triangleWeights(q, p0, p1, p2) {
+    const v0 = sub(p1, p0);
+    const v1 = sub(p2, p0);
+    const v2 = sub(q, p0);
+    const d00 = dot(v0, v0);
+    const d01 = dot(v0, v1);
+    const d11 = dot(v1, v1);
+    const d20 = dot(v2, v0);
+    const d21 = dot(v2, v1);
+    const denom = d00 * d11 - d01 * d01;
+    if (Math.abs(denom) > 1e-18) {
+        const b1 = (d11 * d20 - d01 * d21) / denom;
+        const b2 = (d00 * d21 - d01 * d20) / denom;
+        const b0 = 1 - b1 - b2;
+        if (b0 >= -1e-9 && b1 >= -1e-9 && b2 >= -1e-9) {
+            const s = b0 + b1 + b2;
+            return [b0 / s, b1 / s, b2 / s];
+        }
+    }
+    // Outside (or degenerate): nearest point on the three edges.
+    const e01 = segmentWeights(q, p0, p1);
+    const e12 = segmentWeights(q, p1, p2);
+    const e20 = segmentWeights(q, p2, p0);
+    const at01 = { x: p0.x * e01[0] + p1.x * e01[1], y: p0.y * e01[0] + p1.y * e01[1] };
+    const at12 = { x: p1.x * e12[0] + p2.x * e12[1], y: p1.y * e12[0] + p2.y * e12[1] };
+    const at20 = { x: p2.x * e20[0] + p0.x * e20[1], y: p2.y * e20[0] + p0.y * e20[1] };
+    const c = [
+        [dist2(q, at01), [e01[0], e01[1], 0]],
+        [dist2(q, at12), [0, e12[0], e12[1]]],
+        [dist2(q, at20), [e20[1], 0, e20[0]]],
+    ];
+    c.sort((a, b) => a[0] - b[0]);
+    return c[0][1];
+}
+/** Frank–Wolfe projection of `q` onto the convex hull of `pts` in
+ *  barycentric coordinates (used for K > 3). Minimises |Σ wᵢ·pᵢ − q|² over
+ *  the simplex; O(K·iters), plenty fast for the handful of targets a drag
+ *  ever offers. */
+function hullProjectWeights(q, pts, iters = 60) {
+    const K = pts.length;
+    const w = new Array(K).fill(1 / K);
+    for (let t = 0; t < iters; t++) {
+        let cx = 0;
+        let cy = 0;
+        for (let i = 0; i < K; i++) {
+            cx += w[i] * pts[i].x;
+            cy += w[i] * pts[i].y;
+        }
+        const rx = cx - q.x;
+        const ry = cy - q.y;
+        let best = 0;
+        let bestG = Number.POSITIVE_INFINITY;
+        for (let i = 0; i < K; i++) {
+            const g = rx * pts[i].x + ry * pts[i].y;
+            if (g < bestG) {
+                bestG = g;
+                best = i;
+            }
+        }
+        const gamma = 2 / (t + 2);
+        for (let i = 0; i < K; i++)
+            w[i] = w[i] * (1 - gamma);
+        w[best] = w[best] + gamma;
+    }
+    return w;
+}
+/** 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 function hullWeights(q, pts) {
+    const K = pts.length;
+    if (K === 0)
+        return [];
+    if (K === 1)
+        return [1];
+    if (K === 2)
+        return segmentWeights(q, pts[0], pts[1]);
+    if (K === 3)
+        return triangleWeights(q, pts[0], pts[1], pts[2]);
+    return hullProjectWeights(q, pts);
+}
+function pick(sources, prev, sticky) {
+    const p = sources[0];
+    let best = -1;
+    let bestD = Number.POSITIVE_INFINITY;
+    for (let i = 1; i < sources.length; i++) {
+        const d = dist2(sources[i], p);
+        if (d < bestD) {
+            bestD = d;
+            best = i - 1;
+        }
+    }
+    if (sticky > 0 && prev >= 0 && prev + 1 < sources.length) {
+        const prevD = Math.sqrt(dist2(sources[prev + 1], p));
+        if (prevD - Math.sqrt(bestD) < sticky)
+            return prev;
+    }
+    return best;
+}
+/** 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 function nearestIndex(pointer, candidates, opts = {}) {
+    const sticky = opts.sticky ?? 0;
+    const parents = [pointer, ...candidates];
+    return lens(parents, {
+        init: (sources) => ({ index: pick(sources, -1, 0) }),
+        step: (sources, c) => ({ index: pick(sources, c.index, sticky) }),
+        fwd: (_sources, c) => c.index,
+        bwd: (_t, sources, c) => ({
+            updates: sources.map(() => SKIP),
+            complement: c,
+        }),
+    });
+}

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

@@ -0,0 +1,40 @@
+import type { Cell, Writable } from "../cell.js";
+import { Str } from "../values/str.js";
+type V = string;
+/** Split `s` into words and separators. Returns:
+ *
+ *    words[i] — the i-th run of word characters
+ *    seps[0]  — leading non-word characters (possibly empty)
+ *    seps[i]  — for 1 ≤ i ≤ words.length-1, the separator BETWEEN
+ *               `words[i-1]` and `words[i]`
+ *    seps[words.length] — trailing non-word characters
+ *
+ *  Always satisfies `seps.length === words.length + 1`. */
+export declare function parseWords(s: V): {
+    words: V[];
+    seps: V[];
+};
+/** Inverse of `parseWords`. Interleaves words with `seps`; added words
+ *  get `" "` gaps, removed words keep the original trailing separator.
+ *  A zero-word original (`seps.length === 1`) treats its one entry as
+ *  lead only, so words append after it without double-counting as trail. */
+export declare function rebuildWords(words: V[], seps: V[]): V;
+/** Per-character case mask: `U` upper letter, `L` lower letter,
+ *  `" "` non-letter. Length matches the source. */
+export declare function caseMaskOf(s: V): string;
+/** Apply a case mask to `target`, position by position. Mask positions
+ *  beyond `target.length` are ignored; target positions beyond the
+ *  mask keep their native case (e.g. user appended a longer word). */
+export declare function applyCaseMask(target: V, mask: string): V;
+/** Apply the case pattern of a source word to a target word. Detects
+ *  all-upper / all-lower / title case, else falls back to position-wise
+ *  `applyCaseMask`. Non-letter target chars always pass through unchanged
+ *  (title-casing "-gng" → "-Gng"). */
+export declare function applyCasePattern(target: V, mask: string): V;
+/** Case-folded view of a string cell with word-aware case recovery on
+ *  write. Read folds to lower (default) or upper; write recovers the
+ *  source's per-word case — lookup priority: (1) content match (FIFO
+ *  across duplicates); (2) per-position fallback for new content; (3)
+ *  native for content beyond the source structure. */
+export declare function caseFold(parent: Cell<V>, to?: "lower" | "upper"): Writable<Str>;
+export {};