bireactive 0.2.0

package/dist/assert/scope.js

@@ -0,0 +1,233 @@
+// scope() — wrap a factory so its invocations carry identity.
+//
+// The wrapped factory returns an Animator-shaped wrapper that:
+//   - captures parent at construction (call-site `currentSpan`).
+//   - opens the span on first `.next()` (start aligns to engine clock).
+//   - pushes `currentSpan = self` around every `.next()`/`.return()`/
+//     `.throw()`, so attribution flows through `yield`, `yield*`, and
+//     nesting (the parent wrapper is on the stack while its body runs).
+//   - closes on done, cancellation, or error.
+//
+// Per-factory queries (`alive`, `last`, `runs`, `duration`, `touched`,
+// `touchedDeep`) hang off the wrapper as lazy signal getters.
+import { cell, derive } from "../core/index.js";
+import { closeSpan, currentSpan, notifySpanOpen, openSpan, withSpan } from "./span.js";
+/** Bumped by record() on each open/close so derived signals refresh. */
+const traceVersion = cell(0);
+/** Bump so `alive` / `last` / `runs` etc. recompute. Called by record(). */
+export function bumpTraceVersion() {
+    traceVersion.value++;
+}
+/** Version signal driving the lazy per-factory stat signals. */
+export function traceVersionSignal() {
+    return traceVersion;
+}
+/** Per-factory live history; survives `stop()` so post-stop queries work. */
+const spansByFactory = new WeakMap();
+export function recordFactorySpan(s) {
+    let arr = spansByFactory.get(s.fn);
+    if (!arr) {
+        arr = [];
+        spansByFactory.set(s.fn, arr);
+    }
+    arr.push(s);
+}
+export function spansOf(fn) {
+    return spansByFactory.get(fn) ?? [];
+}
+export function scope(...args) {
+    const [name, fn] = typeof args[0] === "string" ? args : [undefined, args[0]];
+    const tagged = name ?? fn.name ?? "anon";
+    const factory = ((...args) => {
+        const parent = currentSpan;
+        const inner = fn(...args);
+        return makeWrapper(fn, tagged, args, parent, inner);
+    });
+    Object.defineProperty(factory, "name", {
+        value: tagged,
+        configurable: true,
+    });
+    // Lazy stat signals: allocate the Computed on first access, memoize
+    // after. Each reads `traceVersion` directly so it dirties on every
+    // open/close — an `allSpans` intermediate fails because spansOf()
+    // returns a stable array ref that signal equality treats as unchanged.
+    const lazy = (make) => {
+        let cached;
+        return {
+            get() {
+                if (!cached)
+                    cached = make();
+                return cached;
+            },
+        };
+    };
+    const lastSpan = lazy(() => derive(() => {
+        traceVersion.value;
+        const list = spansOf(fn);
+        return list.length === 0 ? undefined : list[list.length - 1];
+    }));
+    Object.defineProperty(factory, "alive", {
+        get: lazy(() => derive(() => {
+            traceVersion.value;
+            const list = spansOf(fn);
+            for (const s of list)
+                if (s.status === "open")
+                    return true;
+            return false;
+        })).get,
+    });
+    Object.defineProperty(factory, "last", { get: () => lastSpan.get() });
+    Object.defineProperty(factory, "runs", {
+        get: lazy(() => derive(() => {
+            traceVersion.value;
+            return spansOf(fn).length;
+        })).get,
+    });
+    Object.defineProperty(factory, "duration", {
+        get: lazy(() => derive(() => {
+            traceVersion.value;
+            const list = spansOf(fn);
+            let total = 0;
+            for (const s of list) {
+                const end = s.end ?? s.start;
+                total += Math.max(0, end - s.start);
+            }
+            return total;
+        })).get,
+    });
+    Object.defineProperty(factory, "touched", {
+        get: lazy(() => derive(() => {
+            traceVersion.value;
+            const list = spansOf(fn);
+            if (list.length === 0)
+                return [];
+            return Array.from(list[list.length - 1].touched);
+        })).get,
+    });
+    Object.defineProperty(factory, "touchedDeep", {
+        get: lazy(() => derive(() => {
+            traceVersion.value;
+            const list = spansOf(fn);
+            if (list.length === 0)
+                return [];
+            return collectTouchedDeep(list[list.length - 1]);
+        })).get,
+    });
+    return factory;
+}
+/** Union of `touched` over `root` and its descendants (via `parent`
+ *  back-links). */
+function collectTouchedDeep(root) {
+    const out = new Set(root.touched);
+    // `parent` is a back-link, so walk every span and test ancestry.
+    // `descends(s, root)` is O(depth); traces are small in practice.
+    for (const arr of allFactoryLists()) {
+        for (const s of arr) {
+            if (s === root)
+                continue;
+            if (descends(s, root)) {
+                for (const sig of s.touched)
+                    out.add(sig);
+            }
+        }
+    }
+    return Array.from(out);
+}
+function descends(s, ancestor) {
+    let cur = s.parent;
+    while (cur) {
+        if (cur === ancestor)
+            return true;
+        cur = cur.parent;
+    }
+    return false;
+}
+/** Parallel list of seen factories — WeakMap isn't iterable. */
+const knownFactories = [];
+export function rememberFactory(fn) {
+    if (!spansByFactory.has(fn))
+        knownFactories.push(fn);
+}
+function* allFactoryLists() {
+    for (const fn of knownFactories)
+        yield spansOf(fn);
+}
+/** Animator-shaped wrapper around `inner`: push/pop the span on each
+ *  gen entry, observe lifecycle from inside. */
+function makeWrapper(fn, name, args, parent, inner) {
+    let span;
+    const ensureOpen = () => {
+        if (!span) {
+            rememberFactory(fn);
+            span = openSpan(fn, name, args, parent);
+            // Record BEFORE notifying so downstream computeds see the span
+            // when they re-evaluate during the listener-driven flush.
+            recordFactorySpan(span);
+            notifySpanOpen(span);
+        }
+        return span;
+    };
+    return {
+        next(t) {
+            const s = ensureOpen();
+            // Close outside withSpan so the close event's writes aren't
+            // attributed to this span's `touched` set.
+            let r;
+            try {
+                r = withSpan(s, () => inner.next(t));
+            }
+            catch (e) {
+                if (s.status === "open")
+                    closeSpan(s, "errored");
+                throw e;
+            }
+            if (r.done && s.status === "open")
+                closeSpan(s, "settled");
+            return r;
+        },
+        return(v) {
+            // Engine may `.return()` on cancel before any `.next()`; an
+            // un-resumed span never really ran, so skip it.
+            if (!span)
+                return inner.return(v);
+            let r;
+            try {
+                r = withSpan(span, () => inner.return(v));
+            }
+            catch (e) {
+                if (span.status === "open")
+                    closeSpan(span, "errored");
+                throw e;
+            }
+            if (span.status === "open")
+                closeSpan(span, "cancelled");
+            return r;
+        },
+        throw(e) {
+            const s = ensureOpen();
+            let r;
+            try {
+                r = withSpan(s, () => inner.throw(e));
+            }
+            catch (err) {
+                if (s.status === "open")
+                    closeSpan(s, "errored");
+                throw err;
+            }
+            if (r.done && s.status === "open")
+                closeSpan(s, "settled");
+            return r;
+        },
+        [Symbol.iterator]() {
+            return this;
+        },
+    };
+}
+/** Batch-scope a record of factories; each key becomes the `name`. */
+export function scopeAll(o) {
+    const out = {};
+    for (const k of Object.keys(o)) {
+        out[k] = scope(k, o[k]);
+    }
+    return out;
+}

package/dist/assert/span.d.ts

@@ -0,0 +1,37 @@
+import type { Cell } from "../core/index.js";
+export type SpanStatus = "open" | "settled" | "cancelled" | "errored";
+/** One factory invocation, possibly nested. */
+export interface Span {
+    readonly id: number;
+    /** Factory reference; the canonical identity. */
+    readonly fn: Function;
+    /** Display name from `scope()`'s arg or `fn.name`. Kept separate so
+     *  bundler renames of named function expressions don't leak in. */
+    readonly name: string;
+    readonly args: readonly unknown[];
+    readonly parent?: Span;
+    /** Set by the recorder on open. `0` outside a `record()` session. */
+    start: number;
+    /** Set by the recorder on close. */
+    end?: number;
+    status: SpanStatus;
+    /** Signals written while this span (not its descendants) was on top
+     *  of the stack. Populated by the recorder; empty otherwise. */
+    readonly touched: Set<Cell<unknown>>;
+}
+/** Top-of-stack span; read by `scope` (parent capture) and `record`
+ *  (write attribution). */
+export declare let currentSpan: Span | undefined;
+/** Run `fn` with `currentSpan = s`, restoring on exit. Keeps the stack
+ *  consistent through `yield`, `yield*`, and re-entrant calls. */
+export declare function withSpan<T>(s: Span | undefined, fn: () => T): T;
+/** Register span-lifecycle listeners. Returns disposer. */
+export declare function addSpanListener(open: (s: Span) => void, close: (s: Span) => void): () => void;
+/** Create a span (`start` = 0; recorder stamps it). Does NOT notify —
+ *  finish bookkeeping, then call `notifySpanOpen(s)`. */
+export declare function openSpan(fn: Function, name: string, args: readonly unknown[], parent: Span | undefined): Span;
+/** Notify recorders that `s` opened. Call AFTER per-factory bookkeeping
+ *  downstream observers may read. */
+export declare function notifySpanOpen(s: Span): void;
+/** End `s` with `status` (no-op if already closed); fires close listeners. */
+export declare function closeSpan(s: Span, status: Exclude<SpanStatus, "open">): void;

package/dist/assert/span.js

@@ -0,0 +1,68 @@
+// Span — one factory invocation. The assert package's single nominal
+// data type; everything else is a function over Spans and Signals.
+//
+// Identity is `fn` (the factory reference); a Span is one particular
+// call, possibly nested. `scope()`'s wrapper opens it on first `.next()`,
+// captures parent at construction, closes on settle/cancel/error.
+//
+// This module never stamps `start` / `end` — the recorder does, on the
+// open/close listener, keeping the engine assert-free. `currentSpan` is
+// a single module slot; `withSpan` push/pop is correct around any
+// synchronous gen body (used by `scope` and `record`).
+/** Top-of-stack span; read by `scope` (parent capture) and `record`
+ *  (write attribution). */
+export let currentSpan;
+/** Run `fn` with `currentSpan = s`, restoring on exit. Keeps the stack
+ *  consistent through `yield`, `yield*`, and re-entrant calls. */
+export function withSpan(s, fn) {
+    const prev = currentSpan;
+    currentSpan = s;
+    try {
+        return fn();
+    }
+    finally {
+        currentSpan = prev;
+    }
+}
+/** Lifecycle listeners; each `record()` adds a pair. Multiple recorders
+ *  coexist. They stamp `s.start` / `s.end`; this module is engine-agnostic. */
+const openListeners = new Set();
+const closeListeners = new Set();
+/** Register span-lifecycle listeners. Returns disposer. */
+export function addSpanListener(open, close) {
+    openListeners.add(open);
+    closeListeners.add(close);
+    return () => {
+        openListeners.delete(open);
+        closeListeners.delete(close);
+    };
+}
+let nextId = 1;
+/** Create a span (`start` = 0; recorder stamps it). Does NOT notify —
+ *  finish bookkeeping, then call `notifySpanOpen(s)`. */
+export function openSpan(fn, name, args, parent) {
+    return {
+        id: nextId++,
+        fn,
+        name,
+        args,
+        parent,
+        start: 0,
+        status: "open",
+        touched: new Set(),
+    };
+}
+/** Notify recorders that `s` opened. Call AFTER per-factory bookkeeping
+ *  downstream observers may read. */
+export function notifySpanOpen(s) {
+    for (const cb of openListeners)
+        cb(s);
+}
+/** End `s` with `status` (no-op if already closed); fires close listeners. */
+export function closeSpan(s, status) {
+    if (s.status !== "open")
+        return;
+    s.status = status;
+    for (const cb of closeListeners)
+        cb(s);
+}

package/dist/assert/tree.d.ts

@@ -0,0 +1,22 @@
+import type { Span } from "./span.js";
+export interface TraceBatch {
+    readonly start: number;
+    readonly members: readonly TraceNode[];
+}
+export interface TraceNode {
+    readonly span: Span;
+    readonly parent?: TraceNode;
+    readonly depth: number;
+    readonly batches: readonly TraceBatch[];
+    readonly children: readonly TraceNode[];
+}
+export interface TraceTree {
+    readonly roots: readonly TraceNode[];
+    readonly byId: ReadonlyMap<number, TraceNode>;
+    readonly size: number;
+    /** Pre-order DFS: parent first, then batches in start-time order,
+     *  then siblings within a batch in start order. */
+    dfs(visit: (node: TraceNode, depth: number) => void): void;
+}
+/** Build a `TraceTree`. Spans must be in start-time order (recorder is). */
+export declare function traceTree(spans: readonly Span[]): TraceTree;

package/dist/assert/tree.js

@@ -0,0 +1,65 @@
+// Structural view over `Span[]`. Pure; wrap in `derive()` to stay reactive.
+//
+// `parent` is a back-link on Span; this module produces forward links
+// (children) and groups siblings into `batches` — same-`start` siblings
+// (spawned together via `yield [a, b, c]`) share a batch.
+/** Build a `TraceTree`. Spans must be in start-time order (recorder is). */
+export function traceTree(spans) {
+    const byId = new Map();
+    for (const s of spans) {
+        byId.set(s.id, { span: s, depth: 0, batches: [], children: [] });
+    }
+    const childrenOf = new Map();
+    const roots = [];
+    for (const s of spans) {
+        const node = byId.get(s.id);
+        const parentId = s.parent?.id;
+        if (parentId === undefined) {
+            roots.push(node);
+            continue;
+        }
+        const parent = byId.get(parentId);
+        if (!parent) {
+            // Parent outside this list (trace started mid-run): treat as root.
+            roots.push(node);
+            continue;
+        }
+        node.parent = parent;
+        node.depth = parent.depth + 1;
+        const arr = childrenOf.get(parentId);
+        if (arr)
+            arr.push(node);
+        else
+            childrenOf.set(parentId, [node]);
+    }
+    for (const [parentId, kids] of childrenOf) {
+        const parent = byId.get(parentId);
+        parent.children = kids;
+        let i = 0;
+        while (i < kids.length) {
+            const t = kids[i].span.start;
+            const members = [];
+            while (i < kids.length && kids[i].span.start === t) {
+                members.push(kids[i]);
+                i++;
+            }
+            parent.batches.push({ start: t, members });
+        }
+    }
+    const rootsRO = roots;
+    const byIdRO = byId;
+    return {
+        roots: rootsRO,
+        byId: byIdRO,
+        size: spans.length,
+        dfs(visit) {
+            const walk = (n) => {
+                visit(n, n.depth);
+                for (const c of n.children)
+                    walk(c);
+            };
+            for (const r of rootsRO)
+                walk(r);
+        },
+    };
+}

package/dist/code/code.d.ts

@@ -0,0 +1,70 @@
+import type { Animator, Easing } from "../animation/index.js";
+import { type Cell, type Num as NumSignal, type Val, type Vec, type Writable } from "../core/index.js";
+import { Shape, type ShapeOpts } from "../shapes/index.js";
+export interface CodeOpts extends ShapeOpts {
+    /** Font size in user units. Default 14. */
+    size?: number;
+    /** Monospace font stack. */
+    font?: string;
+    /** Prism language id. Default `"typescript"`. */
+    language?: string;
+}
+/** A single-line span placed absolutely; `position` / `opacity` /
+ *  `rotation` are animatable signals. */
+export declare class Part {
+    #private;
+    readonly el: HTMLSpanElement;
+    /** Current text. Use `setText` to update (instant). */
+    text: string;
+    /** Top-left in user units. */
+    readonly position: Writable<Vec>;
+    /** [0..1]. */
+    readonly opacity: Writable<NumSignal>;
+    /** Radians around the part's centre. */
+    readonly rotation: Writable<NumSignal>;
+    /** Optional identity tag; shared keys form a `c.group(key)`. */
+    key?: string;
+    constructor(text: string, x: number, y: number, key?: string);
+    /** Instant text update (text itself doesn't tween — animate around it). */
+    setText(t: string): void;
+    dispose(): void;
+}
+/** A Shape rendering monospace source code as a list of `Part`s. */
+export declare class CodeShape extends Shape {
+    #private;
+    readonly source: Writable<Cell<string>>;
+    readonly width: Writable<Cell<number>>;
+    readonly height: Writable<Cell<number>>;
+    readonly language: string;
+    /** Host wrapper (`position: relative`) for the absolute parts. */
+    readonly wrapper: HTMLDivElement;
+    /** Flat parts list; morph re-sorts by (row, col) on completion. */
+    readonly parts: Part[];
+    /** Monospace char width and line height in CSS pixels. */
+    readonly charW: number;
+    readonly lineH: number;
+    constructor(initial: Val<string>, opts?: CodeOpts);
+    /** Paint syntax highlights: tokenise each row's joined text, route
+     *  each typed token to a Range in its containing part. Re-entrant
+     *  (clears prior syntax Ranges; leaves other buckets untouched). */
+    paint(): void;
+    /** Split `part` at char offsets into N+1 same-row sub-parts (0 and
+     *  `text.length` implicit). Sub-parts inherit `part.key`; returned
+     *  left-to-right. */
+    cut(part: Part, offsets: readonly number[]): Part[];
+    /** Merge same-row contiguous `parts` into one (inherits the leftmost's
+     *  key). Single part is a no-op; empty throws. */
+    uncut(parts: readonly Part[]): Part;
+    /** All parts sharing `key`. Returns a fresh array. */
+    group(key: string): Part[];
+    /** Animate from current source to `target`. See `morph.ts`. */
+    morphTo(target: string, dur: number, ease?: Easing): Animator<void>;
+    /** @internal Morph's on-completion commit: set `source` (rebuild
+     *  suppressed), re-sort parts row/col, refresh size + highlights. */
+    _finalize(src: string): void;
+}
+/** Factory: `code("source", { language: "typescript", size: 14 })`. */
+export declare const code: (source: Val<string>, opts?: CodeOpts) => CodeShape;
+/** Prism token-class colours via CSS Custom Highlights. Drop into a
+ *  `Diagram.styles` block so the rules reach the shadow root. */
+export declare const codeStyles = "\n  ::highlight(keyword),\n  ::highlight(rule) { color: var(--prettylights-keyword, #cf222e); }\n  ::highlight(string),\n  ::highlight(attr-value) { color: var(--prettylights-string, #0a3069); }\n  ::highlight(comment),\n  ::highlight(prolog),\n  ::highlight(doctype),\n  ::highlight(cdata) { color: var(--prettylights-comment, #59636e); }\n  ::highlight(function),\n  ::highlight(class-name),\n  ::highlight(entity),\n  ::highlight(selector) { color: var(--prettylights-entity, #6639ba); }\n  ::highlight(tag),\n  ::highlight(boolean),\n  ::highlight(property),\n  ::highlight(symbol) { color: var(--prettylights-entity-tag, #0550ae); }\n  ::highlight(constant),\n  ::highlight(attr-name),\n  ::highlight(builtin),\n  ::highlight(char),\n  ::highlight(operator) { color: var(--prettylights-constant, #0550ae); }\n  ::highlight(variable) { color: var(--prettylights-variable, #953800); }\n  ::highlight(regex) { color: var(--prettylights-string-regexp, #116329); }\n";