bireactive 0.2.0

package/dist/core/values/range.js

@@ -0,0 +1,167 @@
+// range.ts — reactive numeric interval `[lo, hi]`.
+//
+// Home for sliders, scrollbars, and timeline clip spans. Field lenses
+// give start-knob (`.lo`) and end-knob (`.hi`) drag; `.start` is the
+// body-drag (shifts both, preserving width); `.slider(t)` is the
+// bidirectional `t ↔ lo + t·(hi - lo)` iso. Traits: `linear`, `lerp`,
+// `equals`, `pack` (scalar-only).
+import { tween } from "../anim.js";
+import { Cell, isComputed, reader, readNow, } from "../signal.js";
+import { derived, field } from "../writable.js";
+import { Bool } from "./bool.js";
+import { Num, num } from "./num.js";
+export const add = (a, b) => ({ lo: a.lo + b.lo, hi: a.hi + b.hi });
+export const sub = (a, b) => ({ lo: a.lo - b.lo, hi: a.hi - b.hi });
+export const scale = (a, k) => ({ lo: a.lo * k, hi: a.hi * k });
+export const lerp = (a, b, t) => ({
+    lo: a.lo + (b.lo - a.lo) * t,
+    hi: a.hi + (b.hi - a.hi) * t,
+});
+export const equals = (a, b) => a === b || (a.lo === b.lo && a.hi === b.hi);
+/** L2 distance over (lo, hi). Treats a range as a point in 2-space. */
+export const metric = (a, b) => Math.hypot(a.lo - b.lo, a.hi - b.hi);
+export const width = (r) => r.hi - r.lo;
+export const center = (r) => (r.lo + r.hi) / 2;
+export const contains = (r, v) => v >= r.lo && v <= r.hi;
+export const clamp = (r, v) => (v < r.lo ? r.lo : v > r.hi ? r.hi : v);
+/** Closest value STRICTLY outside `[lo, hi]`, displaced past the
+ *  nearest endpoint by `eps`. Used by `Range#contains` as the bwd's
+ *  false-side policy. */
+export const eject = (r, v, eps = 1e-6) => {
+    if (!contains(r, v))
+        return v;
+    return v - r.lo <= r.hi - v ? r.lo - eps : r.hi + eps;
+};
+/** Sample at parameter `t`: `lo + t·(hi - lo)`. `t ∈ [0, 1]` stays
+ *  inside the range; values outside extrapolate linearly. */
+export const sample = (r, t) => r.lo + t * (r.hi - r.lo);
+/** Inverse of `sample`: given a value, recover the `t` that would
+ *  produce it. Degenerate (zero-width) ranges return 0. */
+export const paramOf = (r, v) => {
+    const w = r.hi - r.lo;
+    return w === 0 ? 0 : (v - r.lo) / w;
+};
+const linearImpl = { add, sub, scale };
+const packImpl = {
+    dim: 2,
+    read: (v, a, o) => {
+        a[o] = v.lo;
+        a[o + 1] = v.hi;
+    },
+    write: (a, o) => ({ lo: a[o], hi: a[o + 1] }),
+};
+export class Range extends Cell {
+    static traits = {
+        linear: linearImpl,
+        lerp,
+        metric,
+        equals,
+        pack: packImpl,
+    };
+    constructor(v = { lo: 0, hi: 1 }) {
+        super(v, { equals });
+    }
+    /** Start endpoint. Writes preserve `hi` (start-knob semantics). */
+    get lo() {
+        return field(this, "lo", Num);
+    }
+    /** End endpoint. Writes preserve `lo` (end-knob semantics). */
+    get hi() {
+        return field(this, "hi", Num);
+    }
+    get width() {
+        return derived(this, "width", Num, width);
+    }
+    get center() {
+        return derived(this, "center", Num, center);
+    }
+    /** Translate by `by`. Reads shift the interval; writes shift back. */
+    shift(by) {
+        const f = reader(by);
+        return this.lens(v => ({ lo: v.lo + f(), hi: v.hi + f() }), n => ({ lo: n.lo - f(), hi: n.hi - f() }));
+    }
+    /** Scale uniformly about the origin. Iso for `k ≠ 0`. */
+    scale(k) {
+        const kf = reader(k);
+        return this.lens(v => {
+            const k = kf();
+            return { lo: v.lo * k, hi: v.hi * k };
+        }, n => {
+            const k = kf();
+            return { lo: n.lo / k, hi: n.hi / k };
+        });
+    }
+    /** Body-drag handle: read returns `lo`; write shifts the range so `lo`
+     *  matches (width preserved). For start-knob editing use `.lo`. */
+    get start() {
+        return Num.lens(this, v => v.lo, (newLo, src) => ({ lo: newLo, hi: newLo + (src.hi - src.lo) }));
+    }
+    /** RO sample at `t`. `t ∈ [0, 1]` stays inside; outside extrapolates. */
+    sample(t) {
+        return Num.derive(() => sample(this.value, readNow(t)));
+    }
+    /** Bidirectional `t ↔ value` slider. Read `lo + t·(hi - lo)`; write
+     *  solves for `t` and updates `t` only, leaving `lo` / `hi` put. */
+    slider(t) {
+        // `this as Range` pins the tuple element type (polymorphic `this`
+        // defeats the mapped-tuple inference on `[this, t]`).
+        return Num.lens([this, t], ([r, tv]) => sample(r, tv), (v, [r]) => {
+            const w = r.hi - r.lo;
+            return [undefined, w === 0 ? 0 : (v - r.lo) / w];
+        });
+    }
+    /** Membership predicate. Conditional return type: a writable `Num`
+     *  yields `Writable<Bool>` and flipping the view bumps the source
+     *  (`true` clamps into `[lo, hi]`, `false` ejects past the nearest
+     *  endpoint by `eps`). Literal / RO inputs yield a bare RO `Bool`. */
+    contains(v) {
+        if (v instanceof Num) {
+            // RO computed Num has no backward path → RO branch. Sources and
+            // writable lenses both accept write-back.
+            if (!isComputed(v)) {
+                return Bool.lens([this, v], (vals) => contains(vals[0], vals[1]), (target, vals) => {
+                    const [r, n] = vals;
+                    if (contains(r, n) === target)
+                        return [undefined, undefined];
+                    return [undefined, target ? clamp(r, n) : eject(r, n)];
+                });
+            }
+        }
+        return Bool.derive(() => contains(this.value, readNow(v)));
+    }
+    /** RO clamp: read `v` into `[lo, hi]`. For a writable clamping lens
+     *  on a single Num, see `Num#clamp(lo, hi)`. */
+    clampedRead(v) {
+        return Num.derive(() => clamp(this.value, readNow(v)));
+    }
+    /** Inverse of `sample`: derive the `t` that would produce `v`. */
+    paramOf(v) {
+        return Num.derive(() => paramOf(this.value, readNow(v)));
+    }
+    /** Tween-builder; animates `{lo, hi}` jointly. */
+    to(target, dur, ease) {
+        return tween(this, target, dur, ease);
+    }
+}
+/** @internal — 2-input lens over two writable `Num`s; `range()` delegates
+ *  here after lifting literals. */
+function ends(lo, hi) {
+    return Range.lens([lo, hi], (vals) => ({ lo: vals[0], hi: vals[1] }), (target) => [target.lo, target.hi]);
+}
+/** Range over `[at, at + dur]`, parameterised by start + duration. The
+ *  timeline-clip shape: `.lo` slides the start, `.hi` the end, `.start`
+ *  body-drags (preserving width). Backed by the live `at` / `dur` Nums. */
+export function span(at, dur) {
+    return Range.lens([at, dur], (vals) => ({ lo: vals[0], hi: vals[0] + vals[1] }), (target) => [target.lo, target.hi - target.lo]);
+}
+/** Writable `Range` over `[lo, hi]`. Each endpoint is a literal `number`
+ *  (lifted to a fresh seed) or an existing `Writable<Num>` (identity
+ *  passthrough). RO sources are rejected at the type level — use
+ *  `Range.derive(...)` for reactive RO tracking, or `cell.value` to
+ *  snapshot. Lock an endpoint with `Num.pin(c)`. */
+export function range(lo = 0, hi = 1) {
+    if (typeof lo === "number" && typeof hi === "number") {
+        return new Range({ lo, hi });
+    }
+    return ends(num(lo), num(hi));
+}

package/dist/core/values/str.d.ts

@@ -0,0 +1,76 @@
+import { Cell, type Init, type Writable } from "../signal.js";
+type V = string;
+export declare const equals: (a: V, b: V) => boolean;
+/** Reverse a string by Unicode code points. */
+export declare const reverseStr: (s: V) => V;
+/** ROT13 cipher. Involutive: `rot13(rot13(s)) === s`. */
+export declare const rot13Str: (s: 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"); this letter-awareness is what makes
+ *  GetPut hold when source words contain non-letters. */
+export declare function applyCasePattern(target: V, mask: string): V;
+/** 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;
+export declare class Str extends Cell<V> {
+    static traits: {
+        equals: (a: V, b: V) => boolean;
+    };
+    readonly _t: typeof Str.traits;
+    constructor(v?: V);
+    /** Reverse. Involution. */
+    reverse(): this;
+    /** ROT13. Involution. */
+    rot13(): this;
+    /** Trim edge whitespace; the complement restores the original padding
+     *  on write. Edge whitespace in a write is stripped first (the view's
+     *  contract is "no edge whitespace", else the complement grows). */
+    trim(): Writable<Str>;
+    /** Lowercase view with word-aware case recovery on write. Lookup
+     *  priority: (1) content match — recover the source mask by word
+     *  (FIFO across duplicates); (2) per-position fallback for new content;
+     *  (3) native for content beyond the source structure. */
+    lowercase(): Writable<Str>;
+    /** Uppercase view. Dual of `lowercase`; same per-word case recovery. */
+    uppercase(): Writable<Str>;
+    /** Words view, one word per line. Read splits on non-word chars; the
+     *  complement is the separator layout, restored on write (added words
+     *  get single spaces). Non-word chars typed into a line are stripped —
+     *  edit `Trimmed` / `Lowercased` / `Source` to add punctuation. */
+    words(): Writable<Str>;
+    /** Sorted, case-insensitively-unique words, one per line. The
+     *  complement records each entry's source positions and original case,
+     *  so editing one line broadcasts to every occurrence in the source —
+     *  each rebuilt with its own original casing. */
+    sortedUnique(): Writable<Str>;
+}
+/** Writable `Str`. Strict factory: literal seeds a fresh cell;
+ *  existing `Writable<Str>` passes through by identity. RO sources
+ *  are rejected at the type level — use `Str.derive(...)` for
+ *  reactive RO tracking, or `cell.value` to snapshot. */
+export declare function str(v?: Init<Str>): Writable<Str>;
+export {};

package/dist/core/values/str.js

@@ -0,0 +1,346 @@
+// str.ts — reactive string with a symmetric lens chain.
+//
+// String projections are the canonical use of the engine's stateful-lens
+// primitive (`statefulLens`). Every useful view loses information the
+// engine recovers on write via a per-cell `complement`, so editing through
+// ANY view round-trips with case, whitespace, separators, and duplicate
+// positions preserved (the Foster/Pierce case-preserving find-and-replace
+// demo).
+//
+// `reverse()` and `rot13()` are involutions on the plain endo
+// `.lens(fwd, bwd)` — no complement; they chain like any endo lens.
+// Everything else is `Str.lens(parent, spec)` with a complement:
+//
+//   trim         — leading + trailing whitespace
+//   lowercase    — per-character case mask of the source
+//   uppercase    — dual of lowercase
+//   words        — separator pattern between words
+//   sortedUnique — source positions + original case per unique word
+import { Cell } from "../signal.js";
+// Complement-carrying endo lens.
+//
+// The complement is state recorded forward from the source and consumed
+// on write-back. It persists across the lens's own writes (so `trim`
+// keeps its padding even when the view is emptied) and refreshes on
+// external source changes — the engine's `external` flag drives `step`.
+/** Endo lens backed by a complement recorded from the source. `record`
+ *  rebuilds the complement (kept on the lens's own writes), `project`
+ *  is the forward view, `reconstruct` is the backward source. */
+function complementLens(parent, record, project, reconstruct) {
+    return Str.lens([parent], {
+        init: ([s]) => record(s),
+        step: ([s], c, external) => (external ? record(s) : c),
+        fwd: ([s]) => project(s),
+        bwd: (target, _s, c) => ({ updates: [reconstruct(target, c)], complement: c }),
+    });
+}
+export const equals = (a, b) => a === b;
+/** Reverse a string by Unicode code points. */
+export const reverseStr = (s) => [...s].reverse().join("");
+/** ROT13 cipher. Involutive: `rot13(rot13(s)) === s`. */
+export const rot13Str = (s) => s.replace(/[a-zA-Z]/g, c => {
+    const code = c.charCodeAt(0);
+    const base = code >= 97 ? 97 : 65;
+    return String.fromCharCode(((code - base + 13) % 26) + base);
+});
+/** 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"); this letter-awareness is what makes
+ *  GetPut hold when source words contain non-letters. */
+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);
+}
+/** 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;
+/** Strip every non-word character. Keeps user-typed punctuation in the
+ *  `words` / `sortedUnique` views from leaking into the source via the
+ *  separator complement (where it would accumulate across edits). */
+const stripNonWord = (s) => s.replace(/[^\p{L}\p{N}_'-]/gu, "");
+/** 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;
+}
+/** (Re)build the case complement: positional `wordMasks` and content-keyed
+ *  `byContent` in one pass. `byContent` lists stay in source order for FIFO
+ *  consumption in `putl`. */
+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 arr = byContent.get(key);
+        if (arr === undefined) {
+            arr = [];
+            byContent.set(key, arr);
+        }
+        arr.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 `putl` calls start from the same state.
+    const remaining = new Map();
+    for (const [k, arr] of c.byContent)
+        remaining.set(k, arr.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);
+}
+/** Build a fresh case complement from a source string. */
+function buildCaseComplement(s) {
+    const c = { wordMasks: [], byContent: new Map() };
+    refreshCaseComplement(s, c);
+    return c;
+}
+export class Str extends Cell {
+    static traits = { equals };
+    constructor(v = "") {
+        super(v, { equals });
+    }
+    /** Reverse. Involution. */
+    reverse() {
+        return this.lens(reverseStr, reverseStr);
+    }
+    /** ROT13. Involution. */
+    rot13() {
+        return this.lens(rot13Str, rot13Str);
+    }
+    /** Trim edge whitespace; the complement restores the original padding
+     *  on write. Edge whitespace in a write is stripped first (the view's
+     *  contract is "no edge whitespace", else the complement grows). */
+    trim() {
+        return complementLens(this, s => {
+            const lead = /^\s*/.exec(s)?.[0] ?? "";
+            // Slice lead off first so trail can't overlap it on all-whitespace.
+            const remain = s.slice(lead.length);
+            const trail = /\s*$/.exec(remain)?.[0] ?? "";
+            return { lead, trail };
+        }, s => {
+            const lead = /^\s*/.exec(s)?.[0] ?? "";
+            const remain = s.slice(lead.length);
+            const trail = /\s*$/.exec(remain)?.[0] ?? "";
+            return remain.slice(0, remain.length - trail.length);
+        }, 
+        // Edge whitespace in the write is dropped; complement restores pad.
+        (target, c) => c.lead + target.replace(/^\s+/, "").replace(/\s+$/, "") + c.trail);
+    }
+    /** Lowercase view with word-aware case recovery on write. Lookup
+     *  priority: (1) content match — recover the source mask by word
+     *  (FIFO across duplicates); (2) per-position fallback for new content;
+     *  (3) native for content beyond the source structure. */
+    lowercase() {
+        return complementLens(this, s => buildCaseComplement(s), s => s.toLowerCase(), (target, c) => applyCaseComplement(target, c));
+    }
+    /** Uppercase view. Dual of `lowercase`; same per-word case recovery. */
+    uppercase() {
+        return complementLens(this, s => buildCaseComplement(s), s => s.toUpperCase(), (target, c) => applyCaseComplement(target, c));
+    }
+    /** Words view, one word per line. Read splits on non-word chars; the
+     *  complement is the separator layout, restored on write (added words
+     *  get single spaces). Non-word chars typed into a line are stripped —
+     *  edit `Trimmed` / `Lowercased` / `Source` to add punctuation. */
+    words() {
+        return complementLens(this, s => ({ separators: parseWords(s).seps }), s => parseWords(s).words.join("\n"), (target, c) => {
+            const words = target
+                .split(/\n/)
+                .map(stripNonWord)
+                .filter(w => w.length > 0);
+            return rebuildWords(words, c.separators);
+        });
+    }
+    /** Sorted, case-insensitively-unique words, one per line. The
+     *  complement records each entry's source positions and original case,
+     *  so editing one line broadcasts to every occurrence in the source —
+     *  each rebuilt with its own original casing. */
+    sortedUnique() {
+        return complementLens(this, s => {
+            const { words, seps } = parseWords(s);
+            const buckets = new Map();
+            for (let i = 0; i < words.length; i++) {
+                const w = words[i];
+                const key = w.toLowerCase();
+                let arr = buckets.get(key);
+                if (arr === undefined) {
+                    arr = [];
+                    buckets.set(key, arr);
+                }
+                arr.push({ index: i, sourceCase: w });
+            }
+            const unique = [...buckets.keys()].sort();
+            return {
+                unique,
+                positions: unique.map(k => buckets.get(k)),
+                separators: seps,
+                sourceWords: words,
+            };
+        }, s => {
+            const { words } = parseWords(s);
+            return [...new Set(words.map(w => w.toLowerCase()))].sort().join("\n");
+        }, (target, c) => {
+            // Strip non-word chars typed into the view, same as `words`.
+            const edited = target
+                .split(/\n/)
+                .map(stripNonWord)
+                .filter(w => w.length > 0);
+            const sourceWords = c.sourceWords.slice();
+            const n = Math.min(edited.length, c.unique.length);
+            for (let i = 0; i < n; i++) {
+                const newWord = edited[i];
+                for (const { index, sourceCase } of c.positions[i]) {
+                    if (index >= sourceWords.length)
+                        continue;
+                    sourceWords[index] = applyCasePattern(newWord, caseMaskOf(sourceCase));
+                }
+            }
+            return rebuildWords(sourceWords, c.separators);
+        });
+    }
+}
+/** Writable `Str`. Strict factory: literal seeds a fresh cell;
+ *  existing `Writable<Str>` passes through by identity. RO sources
+ *  are rejected at the type level — use `Str.derive(...)` for
+ *  reactive RO tracking, or `cell.value` to snapshot. */
+export function str(v = "") {
+    if (v instanceof Str)
+        return v;
+    return new Str(v);
+}

package/dist/core/values/template.d.ts

@@ -0,0 +1,49 @@
+import type { Read, Writable } from "../signal.js";
+import { type Num } from "./num.js";
+import { Str } from "./str.js";
+/** Textual codec for a slot value. `parse` returns `undefined` to reject. */
+export interface Codec<T> {
+    format(v: T): string;
+    parse(s: string): T | undefined;
+}
+/** Identity codec for string slots. */
+export declare const strCodec: Codec<string>;
+/** Numeric codec; `int` rounds on both read and write. Rejects non-finite. */
+export declare const numCodec: (int?: boolean) => Codec<number>;
+/** Enumerated string codec: accepts only members of `options`. */
+export declare const enumCodec: (options: readonly string[]) => Codec<string>;
+/** A typed hole: the parent cell plus its `string ⇄ T` codec. */
+export interface Slot<T> {
+    name: string;
+    cell: Writable<Read<T>>;
+    codec: Codec<T>;
+}
+/** Slot constructors that infer the codec from the cell's value class. */
+export declare const slot: {
+    str: (cell: Writable<Str>, name?: string) => Slot<string>;
+    num: (cell: Writable<Num>, name?: string) => Slot<number>;
+    int: (cell: Writable<Num>, name?: string) => Slot<number>;
+    pick: (cell: Writable<Str>, options: readonly string[], name?: string) => Slot<string>;
+};
+/** Core builder: `literals.length === slots.length + 1`. Returns the
+ *  rendered text as a `Writable<Str>` that parses back into the slots. */
+export declare function template(literals: readonly string[], slots: readonly Slot<unknown>[]): Writable<Str>;
+/** Tagged template; interpolate `slot.*` holes. Bring your own cells:
+ *
+ *      tpl`Hello ${slot.str(name)}, ×${slot.int(count)}` */
+export declare function tpl(strings: TemplateStringsArray, ...slots: Slot<unknown>[]): Writable<Str>;
+type ParamKind = "str" | "int" | "num";
+type ParamCell<K extends ParamKind> = K extends "str" ? Writable<Str> : Writable<Num>;
+/** Parse a `:name` pattern against a kind schema, owning fresh slot cells.
+ *  Returns the rendered URL `text` and the typed `params` cells; edit
+ *  either side and the other stays in sync.
+ *
+ *      const { text, params } = route("/users/:id/posts/:slug",
+ *        { id: "int", slug: "str" }); */
+export declare function route<S extends Record<string, ParamKind>>(pattern: string, schema: S): {
+    text: Writable<Str>;
+    params: {
+        [K in keyof S]: ParamCell<S[K]>;
+    };
+};
+export {};