bireactive 0.3.1 → 0.3.3

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) => {
@@ -414,17 +375,11 @@ export function pca(points) {
     };
     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)
@@ -441,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

@@ -8,7 +8,7 @@ type V = {
 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. */
+     *  nearer by more than this. Default 0. */
     sticky?: number;
 }
 /** Index of the candidate nearest `pointer`, with hysteresis. Read-only

package/dist/core/lenses/snap.js

@@ -1,13 +1,6 @@
-// snap.ts — the pointer math the `d` drag algebra (shapes/drag-spec.ts) and the
-// demos build on. Candidate positions are live layout cells, so there's no
-// speculative re-render to recover them:
-//
-//   • hullWeights — barycentric weights of a point in the convex hull of K
-//     targets (closed form for K ≤ 3, Frank–Wolfe for K > 3). Powers
-//     `d.between`'s blend and any pointer-in-hull interpolation.
-//   • nearestIndex — the candidate nearest the pointer, with hysteresis. The
-//     "stickiness" lives in the lens complement (the sanctioned home for
-//     path-dependence), so reads stay pure.
+// 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;

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

package/dist/core/lenses/text.js

@@ -0,0 +1,202 @@
+import { Str } from "../values/str.js";
+// ── word parsing ─────────────────────────────────────────────────────
+/** A "word" character: letters, digits, underscore, apostrophe, hyphen
+ *  (handles "don't", "co-op"). Everything else is a separator. */
+const WORD_CHAR = /[\p{L}\p{N}_'-]/u;
+/** 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 function parseWords(s) {
+    const words = [];
+    const seps = [];
+    let cur = "";
+    let inWord = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (WORD_CHAR.test(c)) {
+            if (!inWord) {
+                seps.push(cur);
+                cur = "";
+                inWord = true;
+            }
+            cur += c;
+        }
+        else {
+            if (inWord) {
+                words.push(cur);
+                cur = "";
+                inWord = false;
+            }
+            cur += c;
+        }
+    }
+    if (inWord) {
+        words.push(cur);
+        seps.push("");
+    }
+    else {
+        seps.push(cur);
+    }
+    return { words, seps };
+}
+/** 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 function rebuildWords(words, seps) {
+    const n = words.length;
+    if (n === 0)
+        return seps[0] ?? "";
+    const lead = seps[0] ?? "";
+    const trail = seps.length > 1 ? (seps[seps.length - 1] ?? "") : "";
+    let out = lead;
+    for (let i = 0; i < n; i++) {
+        out += words[i];
+        if (i < n - 1) {
+            const idx = i + 1;
+            // Interior separators only; the final `seps` entry is the trail.
+            const sep = idx < seps.length - 1 ? seps[idx] : undefined;
+            out += sep !== undefined ? sep : " ";
+        }
+        else {
+            out += trail;
+        }
+    }
+    return out;
+}
+// ── case masks ───────────────────────────────────────────────────────
+/** Per-character case mask: `U` upper letter, `L` lower letter,
+ *  `" "` non-letter. Length matches the source. */
+export function caseMaskOf(s) {
+    let mask = "";
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (c >= "A" && c <= "Z")
+            mask += "U";
+        else if (c >= "a" && c <= "z")
+            mask += "L";
+        else
+            mask += " ";
+    }
+    return mask;
+}
+/** 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 function applyCaseMask(target, mask) {
+    let out = "";
+    for (let i = 0; i < target.length; i++) {
+        const c = target[i];
+        const m = i < mask.length ? mask[i] : " ";
+        if (m === "U")
+            out += c.toUpperCase();
+        else if (m === "L")
+            out += c.toLowerCase();
+        else
+            out += c;
+    }
+    return out;
+}
+const ASCII_LETTER = (c) => (c >= "a" && c <= "z") || (c >= "A" && c <= "Z");
+/** 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 function applyCasePattern(target, mask) {
+    if (target.length === 0 || mask.length === 0)
+        return target;
+    const letters = [...mask].filter(c => c === "U" || c === "L");
+    if (letters.length === 0)
+        return target;
+    if (letters.every(c => c === "U"))
+        return target.toUpperCase();
+    if (letters.every(c => c === "L"))
+        return target.toLowerCase();
+    if (letters[0] === "U" && letters.slice(1).every(c => c === "L")) {
+        // Title case: uppercase the first letter (skipping leading
+        // non-letters), lowercase the rest, pass non-letters through.
+        let out = "";
+        let firstLetterDone = false;
+        for (let i = 0; i < target.length; i++) {
+            const c = target[i];
+            if (ASCII_LETTER(c)) {
+                out += firstLetterDone ? c.toLowerCase() : c.toUpperCase();
+                firstLetterDone = true;
+            }
+            else {
+                out += c;
+            }
+        }
+        return out;
+    }
+    return applyCaseMask(target, mask);
+}
+/** (Re)build the case complement: positional `wordMasks` and content-keyed
+ *  `byContent` in one pass. `byContent` lists stay in source order for FIFO
+ *  consumption on write-back. */
+function refreshCaseComplement(s, c) {
+    const { words } = parseWords(s);
+    const wordMasks = words.map(caseMaskOf);
+    const byContent = new Map();
+    for (let i = 0; i < words.length; i++) {
+        const key = words[i].toLowerCase();
+        let list = byContent.get(key);
+        if (list === undefined) {
+            list = [];
+            byContent.set(key, list);
+        }
+        list.push(wordMasks[i]);
+    }
+    c.wordMasks = wordMasks;
+    c.byContent = byContent;
+}
+/** Apply the case complement to a target string and rebuild. Each
+ *  target word goes through three lookup tiers — content match
+ *  (FIFO-consumed from a per-call clone), positional fallback, then
+ *  native pass-through. */
+function applyCaseComplement(target, c) {
+    const { words, seps } = parseWords(target);
+    // Per-call clone: consume FIFO without mutating the stored map, so
+    // repeated writes start from the same state.
+    const remaining = new Map();
+    for (const [k, list] of c.byContent)
+        remaining.set(k, list.slice());
+    const cased = words.map((w, i) => {
+        const key = w.toLowerCase();
+        const matches = remaining.get(key);
+        if (matches !== undefined && matches.length > 0) {
+            return applyCasePattern(w, matches.shift());
+        }
+        const mask = i < c.wordMasks.length ? c.wordMasks[i] : "";
+        return mask.length === 0 ? w : applyCasePattern(w, mask);
+    });
+    return rebuildWords(cased, seps);
+}
+function buildCaseComplement(s) {
+    const c = { wordMasks: [], byContent: new Map() };
+    refreshCaseComplement(s, c);
+    return c;
+}
+// ── caseFold ─────────────────────────────────────────────────────────
+/** 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 function caseFold(parent, to = "lower") {
+    const fold = to === "upper" ? (s) => s.toUpperCase() : (s) => s.toLowerCase();
+    return Str.lens(parent, {
+        init: (s) => buildCaseComplement(s),
+        fwd: (s) => fold(s),
+        bwd: (target, _s, c) => ({
+            update: applyCaseComplement(target, c),
+            complement: c,
+        }),
+    });
+}

package/dist/core/lifecycle.js

@@ -1,9 +1,6 @@
-// lifecycle.ts — reactive-collection lifecycle helpers over the
-// `network` model. Implemented purely via `effect`:
-//
-//   `each(source, body)` — body runs per element (keyed by reference
-//                          identity); cleanup on removal.
-//   `when(source, body)` — body runs while truthy; cleanup on falsy.
+// Reactive-collection lifecycle helpers, implemented via `effect`: `each` runs a
+// body per element (keyed by reference identity) with cleanup on removal; `when`
+// runs a body while truthy with cleanup on falsy.
 import { effect } from "./cell.js";
 /** Run `body(item)` per element on first sight (storing its cleanup) and
  *  run that cleanup when the element leaves. Identity is element