bireactive 0.2.0

package/dist/assert/algebra.js

@@ -0,0 +1,79 @@
+// Bool-signal primitives. The claim algebra is these three plus signal
+// arithmetic; compose with `and` / `or` / `not`.
+//
+//   intervals(scope)   — Scope → "is this open now?" bool signal.
+//   latch(p, init, sc) — invariant/liveness latch, auto re-arm on `sc`.
+//   firstOf(...e)      — event ordering over bool signals.
+import { cell, derive, effect } from "../core/index.js";
+import { activeRecorder } from "./record.js";
+const ALWAYS_TRUE = derive(() => true);
+/** "Is this scope open right now?" Spans → one-shot interval; scoped
+ *  factories → "any open invocation"; bool signals pass through. */
+export function intervals(s) {
+    if (isScoped(s))
+        return s.alive;
+    if (isSpan(s)) {
+        return derive(() => s.status === "open");
+    }
+    return s;
+}
+/** Always-true scope; useful as a default when no scope is given. */
+export function always() {
+    return ALWAYS_TRUE;
+}
+/** Latch a predicate. Holds at `init` until `pred` is observed `!init`
+ *  within `scope`, then flips and stays; re-arms on each `scope` rising
+ *  edge. Outside `scope`, `pred` isn't consulted (latch holds). */
+export function latch(pred, init, scope = ALWAYS_TRUE) {
+    const held = cell(init);
+    let prevScope = false;
+    effect(() => {
+        const inScope = scope.value;
+        // Track pred.value before any short-circuit so deps stay live.
+        const pv = pred.value;
+        if (inScope && !prevScope) {
+            held.value = init;
+        }
+        prevScope = inScope;
+        if (!inScope)
+            return;
+        if (held.peek() === init && pv !== init) {
+            held.value = !init;
+        }
+    });
+    return held;
+}
+/** First false→true edge wins. Returns `{ first, at }` (winner index +
+ *  recorder-clock time), or undefined until one fires. Sticky once decided. */
+export function firstOf(...events) {
+    const result = cell(undefined);
+    const prev = events.map(e => e.peek());
+    effect(() => {
+        if (result.peek() !== undefined) {
+            for (const e of events)
+                e.value;
+            return;
+        }
+        for (let i = 0; i < events.length; i++) {
+            const v = events[i].value;
+            if (v && !prev[i]) {
+                const at = activeRecorder()?.anim.clock ?? 0;
+                result.value = { first: i, at };
+                prev[i] = v;
+                return;
+            }
+            prev[i] = v;
+        }
+    });
+    return result;
+}
+function isScoped(v) {
+    return typeof v === "function" && "alive" in v && "last" in v;
+}
+function isSpan(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        "status" in v &&
+        "fn" in v &&
+        "id" in v);
+}

package/dist/assert/claim.d.ts

@@ -0,0 +1,40 @@
+import type { Box, Vec } from "../core/index.js";
+import { type Inner, type Read } from "../core/index.js";
+import { type Scope } from "./algebra.js";
+/** Fluent claim — a labeled bool signal with the algebra. */
+export interface Claim extends Read<boolean> {
+    readonly label?: string;
+    /** The raw predicate (pre-latching), useful for custom `latch()` shapes. */
+    readonly pred: Read<boolean>;
+    and(other: Read<boolean>): Claim;
+    or(other: Read<boolean>): Claim;
+    not(): Claim;
+    during(scope: Scope): Claim;
+    labelled(name: string): Claim;
+}
+/** Entry point: `claim(sig).stays.in([0,1])`. `label` flows into
+ *  sub-clause failure messages. */
+export declare function claim<T>(sig: Read<T>, label?: string): SignalClaim<T>;
+/** Mood selector. */
+export interface SignalClaim<T> {
+    readonly sig: Read<T>;
+    readonly label?: string;
+    readonly stays: Predicates<T>;
+    readonly becomes: Predicates<T>;
+    readonly never: Predicates<T>;
+}
+/** Predicate vocabulary; numeric/vector preds narrow via `this:`. */
+export interface Predicates<T> {
+    satisfies(fn: (v: T) => boolean, label?: string): Claim;
+    equal(v: T): Claim;
+    isEqual(other: Read<T>): Claim;
+    in(this: Predicates<number>, range: readonly [number, number]): Claim;
+    above(this: Predicates<number>, n: number): Claim;
+    below(this: Predicates<number>, n: number): Claim;
+    near(this: Predicates<number>, n: number, tol?: number): Claim;
+    following(this: Predicates<number>, other: Read<number>, tol?: number): Claim;
+    inside(this: Predicates<Inner<Vec>>, region: Box): Claim;
+    /** True/false predicates — for moods over already-bool signals. */
+    true(this: Predicates<boolean>): Claim;
+    false(this: Predicates<boolean>): Claim;
+}

package/dist/assert/claim.js

@@ -0,0 +1,129 @@
+// claim() — fluent builder over `latch` + the predicate library.
+//
+//   claim(sig, "α").stays.in([0, 1]).during(intro)
+import { derive } from "../core/index.js";
+import { intervals, latch } from "./algebra.js";
+import { above, below, equal, following, inRange, inside, isEqual, near } from "./predicates.js";
+/** Entry point: `claim(sig).stays.in([0,1])`. `label` flows into
+ *  sub-clause failure messages. */
+export function claim(sig, label) {
+    return {
+        sig,
+        label,
+        get stays() {
+            return predicates(sig, "stays", label);
+        },
+        get becomes() {
+            return predicates(sig, "becomes", label);
+        },
+        get never() {
+            return predicates(sig, "never", label);
+        },
+    };
+}
+function predicates(sig, mood, lbl) {
+    const build = (pred, what) => {
+        const label = `${lbl ?? "cell"} ${mood} ${what}`;
+        // "never": operative predicate is `¬pred`. Carry operative predicate
+        // and init through to `during()`.
+        switch (mood) {
+            case "stays":
+                return makeClaim(pred, latch(pred, true), true, label);
+            case "never": {
+                const negated = derive(() => !pred.value);
+                return makeClaim(negated, latch(negated, true), true, label);
+            }
+            case "becomes":
+                return makeClaim(pred, latch(pred, false), false, label);
+        }
+    };
+    return {
+        satisfies: (fn, what = "predicate") => build(derive(() => fn(sig.value)), what),
+        equal: v => build(equal(sig, v), `= ${fmt(v)}`),
+        isEqual: other => build(isEqual(sig, other), `= other`),
+        in(range) {
+            return build(inRange(sig, range), `∈ [${range[0]}, ${range[1]}]`);
+        },
+        above(n) {
+            return build(above(sig, n), `> ${n}`);
+        },
+        below(n) {
+            return build(below(sig, n), `< ${n}`);
+        },
+        near(n, tol) {
+            return build(near(sig, n, tol), `≈ ${n}`);
+        },
+        following(other, tol) {
+            return build(following(sig, other, tol), `≈ other`);
+        },
+        inside(region) {
+            return build(inside(sig, region), `inside`);
+        },
+        true: () => build(sig, `= true`),
+        false: () => build(derive(() => !sig.value), `= false`),
+    };
+}
+/** Wrap (predicate, latched-signal, init, label) into a Claim. `init`
+ *  (true for stays/never, false for becomes) is kept so `.during()`
+ *  can rebuild the latch; `pred` is the operative (mood-applied) predicate. */
+function makeClaim(pred, latched, init, label) {
+    return wrapClaim(pred, latched, init, label);
+}
+function wrapClaim(pred, body, init, label) {
+    return {
+        get value() {
+            return body.value;
+        },
+        peek() {
+            return body.peek();
+        },
+        label,
+        pred,
+        and(other) {
+            const next = derive(() => body.value && other.value);
+            const otherLabel = other.label;
+            return wrapClaim(pred, next, init, `${label} ∧ ${otherLabel ?? "?"}`);
+        },
+        or(other) {
+            const next = derive(() => body.value || other.value);
+            const otherLabel = other.label;
+            return wrapClaim(pred, next, init, `${label} ∨ ${otherLabel ?? "?"}`);
+        },
+        not() {
+            // Flipping init too swaps invariant ↔ liveness.
+            return wrapClaim(pred, derive(() => !body.value), !init, `¬(${label})`);
+        },
+        during(scope) {
+            const sc = intervals(scope);
+            // Rebuild the latch with the scope so it auto-rearms on each rising
+            // edge. Outside the scope the claim is vacuously satisfied.
+            const next = latch(pred, init, sc);
+            const gated = init === true
+                ? derive(() => !sc.value || next.value)
+                : derive(() => sc.value && next.value);
+            return wrapClaim(pred, gated, init, `(${label}) during ${scopeName(scope)}`);
+        },
+        labelled(name) {
+            return wrapClaim(pred, body, init, name);
+        },
+    };
+}
+function scopeName(s) {
+    if (typeof s === "function")
+        return s.name || "fn";
+    if (typeof s === "object" && s !== null && "name" in s) {
+        return s.name ?? "span";
+    }
+    return "scope";
+}
+function fmt(v) {
+    if (typeof v === "number")
+        return String(+v.toFixed(6));
+    if (typeof v === "string")
+        return JSON.stringify(v);
+    if (v && typeof v === "object" && "x" in v && "y" in v) {
+        const p = v;
+        return `(${fmt(p.x)}, ${fmt(p.y)})`;
+    }
+    return String(v);
+}

package/dist/assert/index.d.ts

@@ -0,0 +1,7 @@
+export { always, firstOf, intervals, latch, type Scope, } from "./algebra.js";
+export { type Claim, claim, type Predicates, type SignalClaim, } from "./claim.js";
+export { above, below, equal, following, inRange, inside, isEqual, near, } from "./predicates.js";
+export { activeRecorder, authorOf, type Recorder, record } from "./record.js";
+export { type Scoped, scope, scopeAll, } from "./scope.js";
+export { addSpanListener, closeSpan, currentSpan, notifySpanOpen, openSpan, type Span, type SpanStatus, withSpan, } from "./span.js";
+export { type TraceBatch, type TraceNode, type TraceTree, traceTree, } from "./tree.js";

package/dist/assert/index.js

@@ -0,0 +1,19 @@
+// bireactive/assert — identity, recording, claims.
+//
+// One nominal data type (`Span`); everything else is a function over
+// spans and signals. Three entry points:
+//
+//   scope(name, fn) — give a factory identity (becomes traceable).
+//   record(anim)    — start recording; spans flow into a Read<Span[]>.
+//   claim(sig).…    — fluent builder over `latch` + predicates.
+//
+// Composition is signal algebra. Predicates, scopes, and claims are
+// all `Read<boolean>` values; `and` / `or` / `not` / `during` are the
+// only verbs. See `_test/assert.test.ts` for the full vocabulary.
+export { always, firstOf, intervals, latch, } from "./algebra.js";
+export { claim, } from "./claim.js";
+export { above, below, equal, following, inRange, inside, isEqual, near, } from "./predicates.js";
+export { activeRecorder, authorOf, record } from "./record.js";
+export { scope, scopeAll, } from "./scope.js";
+export { addSpanListener, closeSpan, currentSpan, notifySpanOpen, openSpan, withSpan, } from "./span.js";
+export { traceTree, } from "./tree.js";

package/dist/assert/predicates.d.ts

@@ -0,0 +1,18 @@
+import type { Box, Vec } from "../core/index.js";
+import { type Inner, type Read } from "../core/index.js";
+/** `lo ≤ s ≤ hi`. */
+export declare function inRange(s: Read<number>, range: readonly [number, number]): Read<boolean>;
+/** `s === v` (strict). */
+export declare function equal<T>(s: Read<T>, v: T): Read<boolean>;
+/** `s > n`. */
+export declare function above(s: Read<number>, n: number): Read<boolean>;
+/** `s < n`. */
+export declare function below(s: Read<number>, n: number): Read<boolean>;
+/** `|s - n| ≤ tol`. */
+export declare function near(s: Read<number>, n: number, tol?: number): Read<boolean>;
+/** Point lies inside a Box (signal or shape's `.box`). */
+export declare function inside(s: Read<Inner<Vec>>, region: Box): Read<boolean>;
+/** `|a - b| ≤ tol`. */
+export declare function following(a: Read<number>, b: Read<number>, tol?: number): Read<boolean>;
+/** Pointwise equality with another signal. */
+export declare function isEqual<T>(a: Read<T>, b: Read<T>): Read<boolean>;

package/dist/assert/predicates.js

@@ -0,0 +1,43 @@
+// Predicate factories. Each returns a plain `derive()`d `Read<boolean>`,
+// composable with `and` / `or` / `not` / hand-rolled `derive()`.
+import { derive } from "../core/index.js";
+/** `lo ≤ s ≤ hi`. */
+export function inRange(s, range) {
+    const [lo, hi] = range;
+    return derive(() => {
+        const v = s.value;
+        return v >= lo && v <= hi;
+    });
+}
+/** `s === v` (strict). */
+export function equal(s, v) {
+    return derive(() => s.value === v);
+}
+/** `s > n`. */
+export function above(s, n) {
+    return derive(() => s.value > n);
+}
+/** `s < n`. */
+export function below(s, n) {
+    return derive(() => s.value < n);
+}
+/** `|s - n| ≤ tol`. */
+export function near(s, n, tol = 1e-6) {
+    return derive(() => Math.abs(s.value - n) <= tol);
+}
+/** Point lies inside a Box (signal or shape's `.box`). */
+export function inside(s, region) {
+    return derive(() => {
+        const v = s.value;
+        const b = region.value;
+        return v.x >= b.x && v.x <= b.x + b.w && v.y >= b.y && v.y <= b.y + b.h;
+    });
+}
+/** `|a - b| ≤ tol`. */
+export function following(a, b, tol = 1e-9) {
+    return derive(() => Math.abs(a.value - b.value) <= tol);
+}
+/** Pointwise equality with another signal. */
+export function isEqual(a, b) {
+    return derive(() => a.value === b.value);
+}

package/dist/assert/record.d.ts

@@ -0,0 +1,20 @@
+import type { Anim } from "../animation/index.js";
+import { type Cell, type Read } from "../core/index.js";
+import { type Span } from "./span.js";
+/** A live recording session. */
+export interface Recorder {
+    /** The bound anim; exposed so helpers (e.g. `firstOf`) read the clock. */
+    readonly anim: Anim;
+    /** Every span seen, in open-time order; re-runs subscribers on open/close. */
+    readonly spans: Read<readonly Span[]>;
+    /** Disengage hooks. Existing spans stay queryable; no new attribution. */
+    stop(): void;
+}
+/** Begin recording. Concurrent sessions each receive every span (filter
+ *  by anim yourself). Stamps start/end from `anim.clock` on open/close. */
+export declare function record(anim: Anim): Recorder;
+/** Any active recorder, or undefined. */
+export declare function activeRecorder(): Recorder | undefined;
+/** Most recent span that wrote to `sig`, or undefined. One memoized
+ *  Cell per asked-about Cell. */
+export declare function authorOf<T>(sig: Cell<T>): Read<Span | undefined>;

package/dist/assert/record.js

@@ -0,0 +1,78 @@
+// record(anim) — start collecting a live trace.
+//
+// Multiple recorders coexist: span listeners and the signal write hook
+// fan out to all of them, each keeping its own list (two demos on one
+// page get independent traces). The recorder owns the clock — it stamps
+// `span.start` / `span.end` from its `anim.clock`; the engine is unaware.
+import { cell, derive, setCellWriteHook, } from "../core/index.js";
+import { bumpTraceVersion } from "./scope.js";
+import { addSpanListener, currentSpan } from "./span.js";
+/** Active recorders; the write hook fans attribution out to all. */
+const recorders = new Set();
+/** Global write-hook disposer; installed on first recorder, removed on last. */
+let removeWriteHook;
+/** Per-signal "current writer", lazily created by `authorOf`. GC-safe via WeakMap. */
+const writerOf = new WeakMap();
+/** Begin recording. Concurrent sessions each receive every span (filter
+ *  by anim yourself). Stamps start/end from `anim.clock` on open/close. */
+export function record(anim) {
+    const list = [];
+    const ver = cell(0);
+    const removeListener = addSpanListener(s => {
+        s.start = anim.clock;
+        list.push(s);
+        ver.value++;
+        bumpTraceVersion();
+    }, s => {
+        s.end = anim.clock;
+        ver.value++;
+        bumpTraceVersion();
+    });
+    // Install the write hook on first recorder; remove on last stop.
+    if (recorders.size === 0) {
+        removeWriteHook = setCellWriteHook(sig => {
+            const s = currentSpan;
+            if (s)
+                s.touched.add(sig);
+            const writer = writerOf.get(sig);
+            if (writer)
+                writer.value = s;
+        });
+    }
+    const spansRead = derive(() => {
+        ver.value;
+        return list;
+    });
+    const recorder = {
+        anim,
+        spans: spansRead,
+        stop() {
+            if (!recorders.has(recorder))
+                return;
+            recorders.delete(recorder);
+            removeListener();
+            if (recorders.size === 0 && removeWriteHook) {
+                removeWriteHook();
+                removeWriteHook = undefined;
+            }
+        },
+    };
+    recorders.add(recorder);
+    return recorder;
+}
+/** Any active recorder, or undefined. */
+export function activeRecorder() {
+    for (const r of recorders)
+        return r;
+    return undefined;
+}
+/** Most recent span that wrote to `sig`, or undefined. One memoized
+ *  Cell per asked-about Cell. */
+export function authorOf(sig) {
+    let writer = writerOf.get(sig);
+    if (!writer) {
+        writer = cell(undefined);
+        writerOf.set(sig, writer);
+    }
+    return writer;
+}

package/dist/assert/scope.d.ts

@@ -0,0 +1,42 @@
+import type { Animator } from "../animation/index.js";
+import { type Cell, type Read } from "../core/index.js";
+import { type Span } from "./span.js";
+/** Factory function shape. */
+type AnyFactory = (...args: any[]) => Animator<any>;
+/** Bump so `alive` / `last` / `runs` etc. recompute. Called by record(). */
+export declare function bumpTraceVersion(): void;
+/** Version signal driving the lazy per-factory stat signals. */
+export declare function traceVersionSignal(): Read<number>;
+export declare function recordFactorySpan(s: Span): void;
+export declare function spansOf(fn: Function): readonly Span[];
+/** Scoped factory: callable, carries name + lazy stats. */
+export interface Scoped<F extends AnyFactory> {
+    (...args: Parameters<F>): ReturnType<F>;
+    readonly name: string;
+    readonly alive: Read<boolean>;
+    readonly last: Read<Span | undefined>;
+    readonly runs: Read<number>;
+    /** Total wall-time across all completed spans; in-flight spans
+     *  contribute up to the current clock. */
+    readonly duration: Read<number>;
+    /** Signals written during the most recent invocation (self only). */
+    readonly touched: Read<readonly Cell<unknown>[]>;
+    /** Signals written during the most recent invocation, plus its
+     *  descendants. */
+    readonly touchedDeep: Read<readonly Cell<unknown>[]>;
+}
+/** Wrap `fn` so its invocations open Spans with identity = fn.
+ *
+ *      const fadeIn = scope("fadeIn", function* () { … });
+ *      const fadeIn = scope(function* () { … });
+ *
+ *  Prefer the name-first form: bare `fn.name` gets renamed by bundlers
+ *  when an inner `function* fadeIn` collides with an outer `const fadeIn`. */
+export declare function scope<F extends AnyFactory>(fn: F): Scoped<F>;
+export declare function scope<F extends AnyFactory>(name: string, fn: F): Scoped<F>;
+export declare function rememberFactory(fn: Function): void;
+/** Batch-scope a record of factories; each key becomes the `name`. */
+export declare function scopeAll<R extends Record<string, AnyFactory>>(o: R): {
+    [K in keyof R]: Scoped<R[K]>;
+};
+export {};