bireactive 0.3.1 → 0.3.3

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

@@ -12,15 +12,14 @@ export declare const sub: (a: V, b: V) => V;
 export declare const scale: (a: V, k: number) => V;
 export declare const lerp: (a: V, b: V, t: number) => V;
 export declare const equals: (a: V, b: V) => boolean;
-/** L2 distance over (lo, hi). Treats a range as a point in 2-space. */
+/** Euclidean distance over (lo, hi). */
 export declare const metric: (a: V, b: V) => number;
 export declare const width: (r: V) => number;
 export declare const center: (r: V) => number;
 export declare const contains: (r: V, v: number) => boolean;
 export declare const clamp: (r: V, v: number) => number;
-/** Closest value STRICTLY outside `[lo, hi]`, displaced past the
- *  nearest endpoint by `eps`. Used by `Range#contains` as the bwd's
- *  false-side policy. */
+/** Closest value strictly outside `[lo, hi]`, displaced past the nearest
+ *  endpoint by `eps`. */
 export declare const eject: (r: V, v: number, eps?: number) => number;
 /** Sample at parameter `t`: `lo + t·(hi - lo)`. `t ∈ [0, 1]` stays
  *  inside the range; values outside extrapolate linearly. */
@@ -43,43 +42,36 @@ export declare class Range extends Cell<V> {
     /** End endpoint. Writes preserve `lo` (end-knob semantics). */
     get hi(): this extends WritableBrand ? Writable<Num> : Num;
     get width(): Num;
-    /** Midpoint body-drag: read returns the center; write shifts the range
-     *  so the center matches (width preserved). `.start` is the lo-anchored
-     *  variant; `.lo` / `.hi` edit the endpoints. */
+    /** Midpoint body-drag: reads the center; a write shifts the range so the
+     *  center matches (width preserved). */
     get center(): Writable<Num>;
-    /** Translate by `by`. Reads shift the interval; writes shift back. */
+    /** Translate by `by`. */
     shift(by: Val<number>): this;
-    /** Scale uniformly about the origin. Iso for `k ≠ 0`. */
+    /** Scale about the origin. Invertible when k ≠ 0. */
     scale(k: Val<number>): this;
-    /** Body-drag handle: read returns `lo`; write shifts the range so `lo`
-     *  matches (width preserved). For start-knob editing use `.lo`. */
+    /** Body-drag handle: reads `lo`; a write shifts the range so `lo` matches
+     *  (width preserved). */
     get start(): Writable<Num>;
     /** RO sample at `t`. `t ∈ [0, 1]` stays inside; outside extrapolates. */
     sample(t: Val<number>): Num;
     /** Bidirectional `t ↔ value` slider. Read `lo + t·(hi - lo)`; write
      *  solves for `t` and updates `t` only, leaving `lo` / `hi` put. */
     slider(t: Writable<Num>): Writable<Num>;
-    /** 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`. */
+    /** True when `v` is in `[lo, hi]`. A writable `Num` yields a `Writable<Bool>`:
+     *  flipping it clamps `v` inside (`true`) or ejects it past the nearest
+     *  endpoint (`false`). Literal/RO inputs yield a read-only `Bool`. */
     contains<P extends Val<number>>(v: P): P extends WritableBrand ? Writable<Bool> : Bool;
-    /** RO clamp: read `v` into `[lo, hi]`. For a writable clamping lens
-     *  on a single Num, see `Num#clamp(lo, hi)`. */
+    /** Read-only clamp of `v` into `[lo, hi]`. */
     clampedRead(v: Val<number>): Num;
     /** Inverse of `sample`: derive the `t` that would produce `v`. */
     paramOf(v: Val<number>): Num;
-    /** Tween-builder; animates `{lo, hi}` jointly. */
+    /** Tween-builder. */
     to(this: Writable<Range>, target: V, dur: Val<number>, ease?: Easing): Tween<V>;
 }
-/** 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. */
+/** Range over `[at, at + dur]`, backed by the live `at` and `dur` Nums. */
 export declare function span(at: Writable<Num>, dur: Writable<Num>): Writable<Range>;
-/** 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)`. */
+/** Writable `Range` over `[lo, hi]`. Each endpoint is a literal (new cell) or
+ *  existing writable (passed through); for read-only sources use `Range.derive`.
+ *  Lock an endpoint with `Num.pin`. */
 export declare function range(lo?: Init<Num>, hi?: Init<Num>): Writable<Range>;
 export {};

package/dist/core/values/range.js

@@ -1,10 +1,3 @@
-// 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` / `.center`
-// are body-drags (shift both, preserving width — anchored at lo / midpoint
-// respectively); `.slider(t)` is the bidirectional `t ↔ lo + t·(hi - lo)`
-// iso. Traits: `linear`, `lerp`, `equals`, `pack` (scalar-only).
 import { tween } from "../../animation/index.js";
 import { Cell, cachedDerive, fieldLens, isReadonly, reader, readNow, SKIP, } from "../cell.js";
 import { Bool } from "./bool.js";
@@ -17,15 +10,14 @@ export const lerp = (a, b, 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. */
+/** Euclidean distance over (lo, hi). */
 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. */
+/** Closest value strictly outside `[lo, hi]`, displaced past the nearest
+ *  endpoint by `eps`. */
 export const eject = (r, v, eps = 1e-6) => {
     if (!contains(r, v))
         return v;
@@ -71,21 +63,20 @@ export class Range extends Cell {
     get width() {
         return cachedDerive(this, "width", Num, width);
     }
-    /** Midpoint body-drag: read returns the center; write shifts the range
-     *  so the center matches (width preserved). `.start` is the lo-anchored
-     *  variant; `.lo` / `.hi` edit the endpoints. */
+    /** Midpoint body-drag: reads the center; a write shifts the range so the
+     *  center matches (width preserved). */
     get center() {
         return Num.lens(this, center, (c, src) => {
             const half = (src.hi - src.lo) / 2;
             return { lo: c - half, hi: c + half };
         });
     }
-    /** Translate by `by`. Reads shift the interval; writes shift back. */
+    /** Translate by `by`. */
     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 about the origin. Invertible when k ≠ 0. */
     scale(k) {
         const kf = reader(k);
         return this.lens(v => {
@@ -96,8 +87,8 @@ export class Range extends Cell {
             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`. */
+    /** Body-drag handle: reads `lo`; a write shifts the range so `lo` matches
+     *  (width preserved). */
     get start() {
         return Num.lens(this, v => v.lo, (newLo, src) => ({ lo: newLo, hi: newLo + (src.hi - src.lo) }));
     }
@@ -108,21 +99,19 @@ export class Range extends Cell {
     /** 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]`).
+        // `this as Range` pins the tuple element type; polymorphic `this` breaks
+        // the mapped-tuple inference.
         return Num.lens([this, t], ([r, tv]) => sample(r, tv), (v, [r]) => {
             const w = r.hi - r.lo;
             return [SKIP, 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`. */
+    /** True when `v` is in `[lo, hi]`. A writable `Num` yields a `Writable<Bool>`:
+     *  flipping it clamps `v` inside (`true`) or ejects it past the nearest
+     *  endpoint (`false`). Literal/RO inputs yield a read-only `Bool`. */
     contains(v) {
         if (v instanceof Num) {
-            // RO Num has no backward path → RO branch. Sources and
-            // writable lenses both accept write-back.
+            // RO Num has no backward path; only writable Nums accept write-back.
             if (!isReadonly(v)) {
                 return Bool.lens([this, v], (vals) => contains(vals[0], vals[1]), (target, vals) => {
                     const [r, n] = vals;
@@ -134,8 +123,7 @@ export class Range extends Cell {
         }
         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)`. */
+    /** Read-only clamp of `v` into `[lo, hi]`. */
     clampedRead(v) {
         return Num.derive(() => clamp(this.value, readNow(v)));
     }
@@ -143,27 +131,22 @@ export class Range extends Cell {
     paramOf(v) {
         return Num.derive(() => paramOf(this.value, readNow(v)));
     }
-    /** Tween-builder; animates `{lo, hi}` jointly. */
+    /** Tween-builder. */
     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. */
+/** Lens combining two writable `Num`s into a `Range`. */
 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. */
+/** Range over `[at, at + dur]`, backed by the live `at` and `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)`. */
+/** Writable `Range` over `[lo, hi]`. Each endpoint is a literal (new cell) or
+ *  existing writable (passed through); for read-only sources use `Range.derive`.
+ *  Lock an endpoint with `Num.pin`. */
 export function range(lo = 0, hi = 1) {
     if (typeof lo === "number" && typeof hi === "number") {
         return new Range({ lo, hi });

package/dist/core/values/reg/ambiguity.d.ts

@@ -0,0 +1,8 @@
+import { type Re } from "./engine.js";
+/** A witness in `L(a) ∩ L(b)` (shortest), or `null` if the languages are
+ *  disjoint. Product BFS over derivative pairs. */
+export declare function intersects(a: Re, b: Re): string | null;
+/** A witness string that `a · b` factors two distinct ways, or `null` if the
+ *  concatenation is unambiguous. Ambiguous iff some nonempty bridge `t` can
+ *  both extend a word of `L(a)` and be absorbed into `L(b)`. */
+export declare function concatAmbiguity(a: Re, b: Re): string | null;

package/dist/core/values/reg/ambiguity.js

@@ -0,0 +1,131 @@
+import { alphabetOf, der, nullable, reKey } from "./engine.js";
+const cp = (c) => String.fromCharCode(c);
+/** Representative code units that distinguish every transition in `a` and `b`
+ *  (the range endpoints of every char class). Sufficient to realize every
+ *  reachable derivative pair. */
+function alphaUnion(a, b) {
+    const set = alphabetOf(a);
+    alphabetOf(b, set);
+    return [...set];
+}
+/** Fold the derivative across a string. */
+function applyStr(r, s) {
+    let cur = r;
+    for (let i = 0; i < s.length && cur.k !== "emp"; i++)
+        cur = der(cur, s.charCodeAt(i));
+    return cur;
+}
+/** A witness in `L(a) ∩ L(b)` (shortest), or `null` if the languages are
+ *  disjoint. Product BFS over derivative pairs. */
+export function intersects(a, b) {
+    const alpha = alphaUnion(a, b);
+    const seen = new Set([`${reKey(a)}|${reKey(b)}`]);
+    const queue = [{ a, b, w: "" }];
+    for (let head = 0; head < queue.length; head++) {
+        const { a: da, b: db, w } = queue[head];
+        if (nullable(da) && nullable(db))
+            return w;
+        for (const c of alpha) {
+            const na = der(da, c);
+            if (na.k === "emp")
+                continue;
+            const nb = der(db, c);
+            if (nb.k === "emp")
+                continue;
+            const key = `${reKey(na)}|${reKey(nb)}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            queue.push({ a: na, b: nb, w: w + cp(c) });
+        }
+    }
+    return null;
+}
+/** All reachable derivative states of `r`, each with a shortest word reaching
+ *  it (BFS over the derivative automaton). */
+function reachableStates(r) {
+    const alpha = [...alphabetOf(r)];
+    const out = new Map([[reKey(r), { re: r, word: "" }]]);
+    const queue = [{ re: r, word: "" }];
+    for (let head = 0; head < queue.length; head++) {
+        const { re, word } = queue[head];
+        for (const c of alpha) {
+            const d = der(re, c);
+            if (d.k === "emp")
+                continue;
+            const k = reKey(d);
+            if (out.has(k))
+                continue;
+            const w = word + cp(c);
+            out.set(k, { re: d, word: w });
+            queue.push({ re: d, word: w });
+        }
+    }
+    return out;
+}
+const SET_KEY = (states) => states.map(reKey).sort().join(",");
+const dedup = (states) => {
+    const seen = new Set();
+    const out = [];
+    for (const s of states) {
+        const k = reKey(s);
+        if (!seen.has(k)) {
+            seen.add(k);
+            out.push(s);
+        }
+    }
+    return out;
+};
+// A generous bound: if the product search explodes past this, refuse to certify
+// (sound — we reject rather than risk admitting an ambiguous grammar).
+const MAX_STATES = 200000;
+/** A witness string that `a · b` factors two distinct ways, or `null` if the
+ *  concatenation is unambiguous. Ambiguous iff some nonempty bridge `t` can
+ *  both extend a word of `L(a)` and be absorbed into `L(b)`. */
+export function concatAmbiguity(a, b) {
+    const statesA = reachableStates(a);
+    const accepting = [];
+    for (const st of statesA.values())
+        if (nullable(st.re))
+            accepting.push(st);
+    if (accepting.length === 0)
+        return null; // L(a) = ∅: nothing to split
+    const alpha = alphaUnion(a, b);
+    // Search for a nonempty bridge `t`: state = (set of A-derivatives reached
+    // from A's accepting states by `t`, der(b, t)).
+    const start = dedup(accepting.map(s => s.re));
+    const seen = new Set([`${SET_KEY(start)}|${reKey(b)}`]);
+    const queue = [{ sa: start, db: b, t: "" }];
+    for (let head = 0; head < queue.length; head++) {
+        if (seen.size > MAX_STATES)
+            throw new Error("reg: grammar too complex to verify");
+        const { sa, db, t } = queue[head];
+        if (t.length > 0 && sa.some(nullable)) {
+            const v = intersects(db, b); // v ∈ L(b) with t·v ∈ L(b)
+            if (v !== null)
+                return witnessFor(accepting, t, v);
+        }
+        for (const c of alpha) {
+            const db2 = der(db, c);
+            if (db2.k === "emp")
+                continue; // t·… can no longer be a prefix of L(b)
+            const sa2 = dedup(sa.map(s => der(s, c)).filter(s => s.k !== "emp"));
+            if (sa2.length === 0)
+                continue; // no accepting continuation on the left
+            const key = `${SET_KEY(sa2)}|${reKey(db2)}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            queue.push({ sa: sa2, db: db2, t: t + cp(c) });
+        }
+    }
+    return null;
+}
+/** Assemble the full doubly-parsing string `u·t·v`: pick an accepting `u ∈ L(a)`
+ *  (shortest known) with `u·t ∈ L(a)`; falls back to `t·v` if none is found. */
+function witnessFor(accepting, t, v) {
+    for (const s of accepting)
+        if (nullable(applyStr(s.re, t)))
+            return s.word + t + v;
+    return t + v;
+}

package/dist/core/values/reg/engine.d.ts

@@ -0,0 +1,91 @@
+/** A set of UTF-16 code units as sorted, merged, inclusive ranges. Negation is
+ *  resolved at construction, so a set is always a positive union of ranges. */
+export declare class CharSet {
+    readonly ranges: ReadonlyArray<readonly [number, number]>;
+    private constructor();
+    /** Build from arbitrary (possibly overlapping/unsorted) ranges. */
+    static of(ranges: ReadonlyArray<readonly [number, number]>): CharSet;
+    static char(cp: number): CharSet;
+    static range(lo: number, hi: number): CharSet;
+    /** The full code-unit alphabet. */
+    static full(): CharSet;
+    static empty(): CharSet;
+    has(cp: number): boolean;
+    isEmpty(): boolean;
+    union(other: CharSet): CharSet;
+    /** Do the two sets share any code unit? (Both are sorted/normalized.) */
+    overlaps(other: CharSet): boolean;
+    /** Complement against the full code-unit alphabet. */
+    complement(): CharSet;
+    /** Case-fold (ASCII + via `toUpperCase`/`toLowerCase`) for the `i` flag.
+     *  Conservative: adds the upper/lower variant of every unit in range. */
+    ignoreCase(): CharSet;
+}
+/** A regular expression over code units. `emp` = ∅ (matches nothing), `eps` =
+ *  ε (matches the empty string). Built only through the smart constructors
+ *  below so that derivatives stay simplified. */
+export type Re = {
+    readonly k: "emp";
+} | {
+    readonly k: "eps";
+} | {
+    readonly k: "chr";
+    readonly set: CharSet;
+} | {
+    readonly k: "seq";
+    readonly a: Re;
+    readonly b: Re;
+} | {
+    readonly k: "alt";
+    readonly a: Re;
+    readonly b: Re;
+} | {
+    readonly k: "star";
+    readonly r: Re;
+};
+export declare const EMP: Re;
+export declare const EPS: Re;
+export declare function chr(set: CharSet): Re;
+/** Concatenation, simplified: `∅·_ = _·∅ = ∅`, `ε·b = b`, `a·ε = a`. */
+export declare function seq(a: Re, b: Re): Re;
+/** Union, normalized modulo ACI: flatten nested alts and drop duplicate
+ *  branches, preserving first-occurrence order. The derivative-state set is
+ *  finite only modulo ACI, so this keeps `der` bounded. Order is preserved (not
+ *  sorted) to keep greedy/backtracking semantics. */
+export declare function alt(a: Re, b: Re): Re;
+/** Kleene star, simplified: `∅* = ε* = ε`, `(r*)* = r*`. */
+export declare function star(r: Re): Re;
+/** N-ary concatenation (right-nested). */
+export declare function seqAll(parts: readonly Re[]): Re;
+/** N-ary union. */
+export declare function altAll(branches: readonly Re[]): Re;
+/** Bounded repetition `r{lo,hi}` (hi `undefined` = unbounded). */
+export declare function repeat(r: Re, lo: number, hi: number | undefined): Re;
+/** A canonical structural key, used both for ACI dedup in `alt` and for
+ *  derivative-state dedup during language enumeration. */
+export declare function reKey(r: Re): string;
+/** Does `r` match the empty string? */
+export declare function nullable(r: Re): boolean;
+/** Brzozowski derivative of `r` with respect to code unit `cp`. */
+export declare function der(r: Re, cp: number): Re;
+/** Does `r` match exactly `s[from..to)`? */
+export declare function accepts(r: Re, s: string, from?: number, to?: number): boolean;
+/** Every prefix length `k ≥ 0` such that `r` matches `s[pos..pos+k)`, ascending.
+ *  This is the backtracking lexer primitive: a leaf can accept several lengths
+ *  (`\d+` over "123" accepts 1, 2, 3) and the value parser tries them
+ *  greedily (longest first) with proper fallback. */
+export declare function matchLengths(r: Re, s: string, pos: number): number[];
+/** Characters that can begin a word in `L(r)`. */
+export declare function firstSet(r: Re): CharSet;
+/** Characters that can extend an already-complete match of `r` (the union of
+ *  the first-sets of every reachable accepting derivative state). Finite and
+ *  terminating because the derivative-state set is finite modulo ACI. */
+export declare function followLast(r: Re): CharSet;
+/** Representative code units that exercise every char-set boundary in `r`
+ *  (each range's low/high endpoint). Enough to drive structural exploration
+ *  without iterating the whole alphabet. */
+export declare function alphabetOf(r: Re, out?: Set<number>): Set<number>;
+/** Enumerate strings in `L(r)` over `alphabet`, shortest-first, up to `maxLen`
+ *  and `cap` results. Used by the ambiguity oracle to find minimal
+ *  counterexamples; bounded so it always terminates. */
+export declare function language(r: Re, alphabet: readonly number[], maxLen: number, cap: number): Generator<string>;