bireactive 0.2.0

package/dist/core/values/vec.js

@@ -0,0 +1,219 @@
+// vec.ts — reactive 2D point.
+//
+// Invertibles return `: this` and ride on `Cell#lens(fwd, bwd)`;
+// chained calls compose into a lens chain. Field-lens getters use
+// `field()` (propagates writability); `derived()` wraps RO views.
+import { tween } from "../anim.js";
+import { Cell, reader, readNow } from "../signal.js";
+import { derived, field } from "../writable.js";
+import { Num, num } from "./num.js";
+export const add = (a, b) => ({ x: a.x + b.x, y: a.y + b.y });
+export const sub = (a, b) => ({ x: a.x - b.x, y: a.y - b.y });
+export const scale = (a, k) => ({ x: a.x * k, y: a.y * k });
+export const lerp = (a, b, t) => ({
+    x: a.x + (b.x - a.x) * t,
+    y: a.y + (b.y - a.y) * t,
+});
+export const metric = (a, b) => Math.hypot(a.x - b.x, a.y - b.y);
+export const equals = (a, b) => a === b || (a.x === b.x && a.y === b.y);
+export const normalize = (v) => {
+    const m = Math.hypot(v.x, v.y);
+    return m === 0 ? { x: 0, y: 0 } : { x: v.x / m, y: v.y / m };
+};
+export const perp = (v) => ({ x: v.y, y: -v.x });
+/** Tangent point on the circle (radius `r`, centre `c`) from external
+ *  point `p`. `side: -1` picks the CCW tangent from `pc`, `+1` the CW
+ *  (y-down screen coords flip the visual sense). Returns `c` if `p` is
+ *  inside or on the circle. */
+export function tangentPoint(p, c, r, side = -1) {
+    const dx = p.x - c.x;
+    const dy = p.y - c.y;
+    const d = Math.hypot(dx, dy);
+    if (d <= r)
+        return c;
+    const baseAngle = Math.atan2(dy, dx);
+    const offset = Math.acos(r / d);
+    const a = baseAngle + side * offset;
+    return { x: c.x + r * Math.cos(a), y: c.y + r * Math.sin(a) };
+}
+/** Wrap `x` to the half-open interval `(-π, π]`. */
+const wrapToPi = (x) => x - 2 * Math.PI * Math.round(x / (2 * Math.PI));
+/** Representative of cyclic angle `target` closest to `current`
+ *  (shortest-arc inverse). */
+const nearestAngle = (target, current) => current + wrapToPi(target - current);
+const linearImpl = { add, sub, scale };
+const packImpl = {
+    dim: 2,
+    read: (v, a, o) => {
+        a[o] = v.x;
+        a[o + 1] = v.y;
+    },
+    write: (a, o) => ({ x: a[o], y: a[o + 1] }),
+};
+const pivotalImpl = {
+    rotateAbout: (v, p, dθ) => {
+        const cos = Math.cos(dθ);
+        const sin = Math.sin(dθ);
+        const dx = v.x - p.x;
+        const dy = v.y - p.y;
+        return { x: p.x + cos * dx - sin * dy, y: p.y + sin * dx + cos * dy };
+    },
+    scaleAbout: (v, p, k) => ({
+        x: p.x + k * (v.x - p.x),
+        y: p.y + k * (v.y - p.y),
+    }),
+};
+export class Vec extends Cell {
+    static traits = {
+        linear: linearImpl,
+        lerp,
+        metric,
+        equals,
+        pack: packImpl,
+        pivotal: pivotalImpl,
+    };
+    constructor(v = { x: 0, y: 0 }) {
+        super(v, { equals });
+    }
+    add(b) {
+        const bf = reader(b);
+        return this.lens(v => {
+            const o = bf();
+            return { x: v.x + o.x, y: v.y + o.y };
+        }, n => {
+            const o = bf();
+            return { x: n.x - o.x, y: n.y - o.y };
+        });
+    }
+    sub(b) {
+        const bf = reader(b);
+        return this.lens(v => {
+            const o = bf();
+            return { x: v.x - o.x, y: v.y - o.y };
+        }, n => {
+            const o = bf();
+            return { x: n.x + o.x, y: n.y + o.y };
+        });
+    }
+    scale(k) {
+        const kf = reader(k);
+        return this.lens(v => {
+            const k = kf();
+            return { x: v.x * k, y: v.y * k };
+        }, n => {
+            const k = kf();
+            return { x: n.x / k, y: n.y / k };
+        });
+    }
+    offset(dx, dy) {
+        const xf = reader(dx);
+        const yf = reader(dy);
+        return this.lens(v => ({ x: v.x + xf(), y: v.y + yf() }), n => ({ x: n.x - xf(), y: n.y - yf() }));
+    }
+    // Axis-aligned offset sugar — same fwd/bwd shape as offset.
+    up(n) {
+        const f = reader(n);
+        return this.lens(v => ({ x: v.x, y: v.y - f() }), o => ({ x: o.x, y: o.y + f() }));
+    }
+    down(n) {
+        const f = reader(n);
+        return this.lens(v => ({ x: v.x, y: v.y + f() }), o => ({ x: o.x, y: o.y - f() }));
+    }
+    left(n) {
+        const f = reader(n);
+        return this.lens(v => ({ x: v.x - f(), y: v.y }), o => ({ x: o.x + f(), y: o.y }));
+    }
+    right(n) {
+        const f = reader(n);
+        return this.lens(v => ({ x: v.x + f(), y: v.y }), o => ({ x: o.x - f(), y: o.y }));
+    }
+    normalize() {
+        return Vec.derive(() => normalize(this.value));
+    }
+    perp() {
+        return Vec.derive(() => perp(this.value));
+    }
+    lerp(b, t) {
+        return Vec.derive(() => lerp(this.value, readNow(b), readNow(t)));
+    }
+    distance(other) {
+        return Num.derive(this, v => metric(v, readNow(other)));
+    }
+    get x() {
+        return field(this, "x", Num);
+    }
+    get y() {
+        return field(this, "y", Num);
+    }
+    get magnitude() {
+        return derived(this, "magnitude", Num, v => Math.hypot(v.x, v.y));
+    }
+    /** Tween-builder; `this: Writable<Vec>` gates the call to writable
+     *  receivers. */
+    to(target, dur, ease) {
+        return tween(this, target, dur, ease);
+    }
+}
+/** @internal — 2-input lens over two writable `Num`s; `vec()` delegates
+ *  here after lifting literals. */
+function axes(x, y) {
+    // The view fully reconstructs both axes (1-arg bwd ⇒ no source read).
+    return Vec.lens([x, y], ([xv, yv]) => ({ x: xv, y: yv }), v => [v.x, v.y]);
+}
+/** Writable `Vec` at `(x, y)`. Each axis 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 `Vec.derive(...)` for
+ *  reactive RO tracking, or `cell.value` to snapshot. Lock an axis with
+ *  `Num.pin(c)`: `vec(slider, Num.pin(100))`. */
+export function vec(x = 0, y = 0) {
+    if (typeof x === "number" && typeof y === "number") {
+        return new Vec({ x, y });
+    }
+    return axes(num(x), num(y));
+}
+/** Vec at polar offset from `center`: `center + (r·cos a, r·sin a)`.
+ *  Bidirectional; each input is a literal (lifted to a fresh seed) or an
+ *  existing writable cell. RO inputs are rejected at the type level.
+ *  `policy` selects which inputs absorb writes; lock one with
+ *  `Num.pin(c)`: `polar(c, Num.pin(100), a)`. */
+export function polar(center, r, a, policy = "rotate") {
+    // Lift literals; already-writable inputs pass through by identity.
+    const cSig = center instanceof Vec ? center : vec(center.x, center.y);
+    const rSig = num(r);
+    const aSig = num(a);
+    const project = (c, rv, av) => ({
+        x: c.x + rv * Math.cos(av),
+        y: c.y + rv * Math.sin(av),
+    });
+    let bwd;
+    switch (policy) {
+        case "rotate":
+            bwd = (p, [cv, , av]) => {
+                const dx = p.x - cv.x;
+                const dy = p.y - cv.y;
+                return [undefined, Math.hypot(dx, dy), nearestAngle(Math.atan2(dy, dx), av)];
+            };
+            break;
+        case "translate":
+            bwd = (p, [cv, rv, av]) => {
+                const f = project(cv, rv, av);
+                return [{ x: cv.x + (p.x - f.x), y: cv.y + (p.y - f.y) }, undefined, undefined];
+            };
+            break;
+        case "radial":
+            bwd = (p, [cv, , av]) => {
+                const dx = p.x - cv.x;
+                const dy = p.y - cv.y;
+                return [undefined, dx * Math.cos(av) + dy * Math.sin(av), undefined];
+            };
+            break;
+        case "circular":
+            bwd = (p, [cv, , av]) => [
+                undefined,
+                undefined,
+                nearestAngle(Math.atan2(p.y - cv.y, p.x - cv.x), av),
+            ];
+            break;
+    }
+    return Vec.lens([cSig, rSig, aSig], ([c, rv, av]) => project(c, rv, av), bwd);
+}

package/dist/core/writable.d.ts

@@ -0,0 +1,15 @@
+import { Cell, type Inner, type Writable, type WritableBrand } from "./signal.js";
+/** Bidirectional field lens onto `parent.value[key]`; write spread-
+ *  replaces the composite. Cached per (instance, key). Return type is
+ *  conditional: `Writable<Cls>` on a writable parent, bare `Cls` on RO
+ *  (runtime dispatch in `Cell.fieldOf` mirrors this).
+ *
+ *      get x() { return field(this, "x", Num); } */
+export declare function field<S extends Cell<any>, K extends keyof Inner<S>, C extends new (...args: never[]) => Cell<Inner<S>[K]>>(parent: S, key: K, Cls: C): S extends WritableBrand ? Writable<InstanceType<C>> : InstanceType<C>;
+/** Read-only derived view via `Cls.derive(parent, fn)`. Cached per
+ *  (instance, key); always bare `Cls` (RO).
+ *
+ *      get magnitude() {
+ *        return derived(this, "magnitude", Num, v => Math.hypot(v.x, v.y));
+ *      } */
+export declare function derived<S extends Cell<any>, C extends new (...args: never[]) => Cell<any>>(parent: S, key: string | symbol, Cls: C, fn: (v: Inner<S>) => Inner<InstanceType<C>>): InstanceType<C>;

package/dist/core/writable.js

@@ -0,0 +1,29 @@
+// writable.ts — value-class authoring helpers.
+//
+// `field(this, "x", Num)` — bidirectional field lens; conditional
+// return (writable on writable parent, bare on RO). `derived(this,
+// "k", Cls, fn)` — read-only derived view via `Cls.derive`. The choice
+// between them IS the local declaration of writability at each getter,
+// mirroring `: this` invertible method returns. For arbitrary cached
+// views, use `lazy()` from "../signal" directly.
+import { Cell, lazy } from "./signal.js";
+/** Bidirectional field lens onto `parent.value[key]`; write spread-
+ *  replaces the composite. Cached per (instance, key). Return type is
+ *  conditional: `Writable<Cls>` on a writable parent, bare `Cls` on RO
+ *  (runtime dispatch in `Cell.fieldOf` mirrors this).
+ *
+ *      get x() { return field(this, "x", Num); } */
+export function field(parent, key, Cls) {
+    return lazy(parent, key, () => Cell.fieldOf(parent, key, Cls));
+}
+/** Read-only derived view via `Cls.derive(parent, fn)`. Cached per
+ *  (instance, key); always bare `Cls` (RO).
+ *
+ *      get magnitude() {
+ *        return derived(this, "magnitude", Num, v => Math.hypot(v.x, v.y));
+ *      } */
+// biome-ignore lint/suspicious/noExplicitAny: variance escape, mirrors Cls.derive
+export function derived(parent, key, Cls, fn) {
+    // biome-ignore lint/suspicious/noExplicitAny: variance escape on Cls.derive
+    return lazy(parent, key, () => Cls.derive(parent, fn));
+}

package/dist/ext/events.d.ts

@@ -0,0 +1,10 @@
+import { type Animator } from "../animation/index.js";
+export declare class EventBus {
+    private handlers;
+    emit(name: string, data?: unknown): void;
+    on(name: string, handler: (data: unknown) => void): () => void;
+    /** Wake on the next emit of `name`; resume with the emit data. Pass
+     *  an explicit type parameter (`yield* bus.until<string>("msg")`) to
+     *  type the payload at the call site. */
+    until<T = unknown>(name: string): Animator<T>;
+}

package/dist/ext/events.js

@@ -0,0 +1,31 @@
+// Named event bus. Subscribe/emit synchronously; `until(name)` returns
+// an `Animator<T>` that wakes the next time `name` fires, carrying the
+// emit data as the resume value.
+import { suspend } from "../animation/index.js";
+export class EventBus {
+    handlers = new Map();
+    emit(name, data) {
+        const set = this.handlers.get(name);
+        if (!set)
+            return;
+        for (const fn of set)
+            fn(data);
+    }
+    on(name, handler) {
+        let set = this.handlers.get(name);
+        if (!set) {
+            set = new Set();
+            this.handlers.set(name, set);
+        }
+        set.add(handler);
+        return () => {
+            set.delete(handler);
+        };
+    }
+    /** Wake on the next emit of `name`; resume with the emit data. Pass
+     *  an explicit type parameter (`yield* bus.until<string>("msg")`) to
+     *  type the payload at the call site. */
+    until(name) {
+        return suspend(wake => this.on(name, wake));
+    }
+}

package/dist/ext/index.d.ts

@@ -0,0 +1,4 @@
+export { EventBus } from "./events.js";
+export { snapshot } from "./snapshot.js";
+export { type Clip, sequential, type Timeline, type TimelineOf, timeline, } from "./timeline.js";
+export { inView, native, scrollProgress, untilAnimation, untilInView, untilOutOfView, type ViewRange, viewProgress, } from "./waapi.js";

package/dist/ext/index.js

@@ -0,0 +1,4 @@
+export { EventBus } from "./events.js";
+export { snapshot } from "./snapshot.js";
+export { sequential, timeline, } from "./timeline.js";
+export { inView, native, scrollProgress, untilAnimation, untilInView, untilOutOfView, viewProgress, } from "./waapi.js";

package/dist/ext/snapshot.d.ts

@@ -0,0 +1,8 @@
+import { type Read } from "../core/index.js";
+/** Capture current values; return a reset function.
+ *
+ *      const reset = snapshot(score, position);
+ *      // … later, on cancel/reset …
+ *      reset();
+ */
+export declare function snapshot(...args: ReadonlyArray<Read<unknown> | Record<string, unknown>>): () => void;

package/dist/ext/snapshot.js

@@ -0,0 +1,29 @@
+// `snapshot(...sigs)` — capture current signal values; return a reset
+// function. Args are signals or plain records whose signal-valued
+// properties get flattened. Useful at the top of `loop(...)` bodies so
+// each iteration starts from a known baseline.
+import { Cell } from "../core/index.js";
+/** Capture current values; return a reset function.
+ *
+ *      const reset = snapshot(score, position);
+ *      // … later, on cancel/reset …
+ *      reset();
+ */
+export function snapshot(...args) {
+    const sigs = [];
+    for (const arg of args) {
+        if (arg instanceof Cell) {
+            sigs.push(arg);
+            continue;
+        }
+        for (const v of Object.values(arg)) {
+            if (v instanceof Cell)
+                sigs.push(v);
+        }
+    }
+    const initials = sigs.map(s => s.peek());
+    return () => {
+        for (let i = 0; i < sigs.length; i++)
+            sigs[i].value = initials[i];
+    };
+}

package/dist/ext/timeline.d.ts

@@ -0,0 +1,56 @@
+import type { Animator } from "../animation/index.js";
+import { type Cell, type Init, Num, Range, type Writable } from "../core/index.js";
+/** A clip on a timeline. `t` clamps to 0 before / 1 after, so
+ *  `derive(() => ease(clip.t.value))` needs no guards. Per-field
+ *  writability flows through `ResolvedField` / `ResolvedSpan`: writable
+ *  inputs yield draggable knobs, RO inputs (e.g. `sequential()`'s `at`)
+ *  stay RO. */
+export type Clip<A = number, D = number> = {
+    readonly at: ResolvedField<A>;
+    readonly dur: ResolvedField<D>;
+    readonly end: Num;
+    readonly span: ResolvedSpan<A, D>;
+    /** Progress: 0 before `at`, 0..1 within, 1 after `end`. */
+    readonly t: Num;
+    readonly active: Cell<boolean>;
+};
+type ResolvedField<A> = [A] extends [Writable<Num>] ? Writable<Num> : [A] extends [number] ? Writable<Num> : Num;
+type IsWritable<A> = [A] extends [Writable<Num>] ? true : [A] extends [number] ? true : false;
+type ResolvedSpan<A, D> = IsWritable<A> extends true ? (IsWritable<D> extends true ? Writable<Range> : Range) : Range;
+type ClipSpec = {
+    at: number | Num;
+    dur: number | Num;
+};
+export interface Timeline {
+    readonly clock: Writable<Num>;
+    readonly duration: Num;
+    /** `clock / duration`, clamped to `[0, 1]`. */
+    readonly t: Num;
+    readonly clips: readonly Clip[];
+    /** `yield* tl` advances `clock` to `duration`. No auto-reset (use
+     *  `snapshot(tl.clock)` for loops). */
+    [Symbol.iterator](): Animator;
+}
+/** Type-preserving named-clip access. */
+export type TimelineOf<T extends Record<string, ClipSpec>> = Timeline & {
+    readonly [K in keyof T]: T[K] extends {
+        at: infer A;
+        dur: infer D;
+    } ? Clip<A, D> : Clip;
+};
+/** Build a timeline from clip specs. `at`/`dur` accept numbers or `Num`
+ *  cells; clips may overlap or gap. See `sequential()` for cumulative starts. */
+export declare function timeline<T extends Record<string, ClipSpec>>(specs: T): TimelineOf<T>;
+type Durations = Record<string, Init<Num>>;
+/** Cumulative-start helper: each clip's `at` is the reactive sum of
+ *  prior durations (RO). Use `timeline()` directly for draggable starts.
+ *
+ *      timeline(sequential({ intro: 0.7, hold: 1.2, outro: 0.5 }));
+ */
+export declare function sequential<T extends Durations>(durs: T): {
+    [K in keyof T]: {
+        at: Num;
+        dur: ResolvedField<T[K]>;
+    };
+};
+export {};

package/dist/ext/timeline.js

@@ -0,0 +1,94 @@
+// Timeline + Clip. A timeline is a clock plus named clips (each an
+// `[at, at + dur)` interval); `yield* tl` advances the clock to
+// `duration`. `sequential({...})` produces cumulative-start specs.
+import { derive, isComputed, Num, num, Range, span, } from "../core/index.js";
+class TimelineImpl {
+    clock;
+    duration;
+    t;
+    clips;
+    constructor(clock, clips) {
+        this.clock = clock;
+        this.clips = clips;
+        this.duration = Num.derive(() => {
+            let max = 0;
+            for (const c of clips) {
+                const e = c.end.value;
+                if (e > max)
+                    max = e;
+            }
+            return max;
+        });
+        this.t = Num.derive(() => {
+            const d = this.duration.value;
+            return d > 0 ? Math.min(this.clock.value / d, 1) : 0;
+        });
+    }
+    *[Symbol.iterator]() {
+        while (this.clock.value < this.duration.value) {
+            const { dt } = yield;
+            this.clock.value += dt;
+        }
+    }
+}
+function makeClip(spec, clock) {
+    const at = Num.from(spec.at);
+    const dur = Num.from(spec.dur);
+    const end = Num.derive(() => at.value + dur.value);
+    // Bidirectional span when both inputs are writable; RO derive when
+    // either is computed. Mirrors `ResolvedSpan`.
+    const sp = isComputed(at) || isComputed(dur)
+        ? Range.derive(() => ({ lo: at.value, hi: at.value + dur.value }))
+        : span(at, dur);
+    const t = Num.derive(() => {
+        const c = clock.value;
+        const a = at.value;
+        const d = dur.value;
+        if (c <= a)
+            return 0;
+        if (c >= a + d)
+            return 1;
+        return d > 0 ? (c - a) / d : 1;
+    });
+    const active = derive(() => {
+        const c = clock.value;
+        return c >= at.value && c < end.value;
+    });
+    return { at, dur, span: sp, end, t, active };
+}
+/** Build a timeline from clip specs. `at`/`dur` accept numbers or `Num`
+ *  cells; clips may overlap or gap. See `sequential()` for cumulative starts. */
+export function timeline(specs) {
+    const clock = num(0);
+    const clips = [];
+    const named = {};
+    for (const key of Object.keys(specs)) {
+        const clip = makeClip(specs[key], clock);
+        clips.push(clip);
+        named[key] = clip;
+    }
+    const tl = new TimelineImpl(clock, clips);
+    Object.assign(tl, named);
+    return tl;
+}
+/** Cumulative-start helper: each clip's `at` is the reactive sum of
+ *  prior durations (RO). Use `timeline()` directly for draggable starts.
+ *
+ *      timeline(sequential({ intro: 0.7, hold: 1.2, outro: 0.5 }));
+ */
+export function sequential(durs) {
+    const keys = Object.keys(durs);
+    const durSigs = keys.map(k => num(durs[k]));
+    const out = {};
+    keys.forEach((key, i) => {
+        const idx = i;
+        const at = Num.derive(() => {
+            let sum = 0;
+            for (let j = 0; j < idx; j++)
+                sum += durSigs[j].value;
+            return sum;
+        });
+        out[key] = { at, dur: durSigs[i] };
+    });
+    return out;
+}

package/dist/ext/waapi.d.ts

@@ -0,0 +1,25 @@
+import { type Animator } from "../animation/index.js";
+import { type Cell } from "../core/index.js";
+/** WAAPI animation as a bireactive Animator. Bare-number `opts` is seconds;
+ *  object `opts` passes through to `Element.animate` (ms). */
+export declare function native(el: Element, keyframes: Keyframe[] | PropertyIndexedKeyframes | null, opts?: number | KeyframeAnimationOptions): Animator<void>;
+/** Wake on the animation's `finish` event; resume with the event. */
+export declare function untilAnimation(a: Animation): Animator<AnimationPlaybackEvent>;
+/** Wake when `el` enters the viewport. Wakes immediately if already in. */
+export declare function untilInView(el: Element, opts?: IntersectionObserverInit): Animator<void>;
+/** Wake when `el` leaves the viewport. Wakes immediately if already out. */
+export declare function untilOutOfView(el: Element, opts?: IntersectionObserverInit): Animator<void>;
+/** Global page scroll progress in `[0, 1]`; `0` if page doesn't scroll. */
+export declare function scrollProgress(): Cell<number>;
+/** Slice of an element's viewport traversal mapped to `[0, 1]`. Names
+ *  match CSS `view-timeline`:
+ *    cover   leading enters ↦ trailing exits
+ *    entry   leading enters ↦ fully in view
+ *    contain fully in view (pinned at 0.5 when taller than vp)
+ *    exit    starts exiting ↦ trailing exits */
+export type ViewRange = "cover" | "entry" | "contain" | "exit";
+/** Element view-progress in `[0, 1]` over `range` (default `cover`). */
+export declare function viewProgress(el: Element, range?: ViewRange): Cell<number>;
+/** Reactive boolean; `true` while `el` intersects the viewport. Seeded
+ *  synchronously from rect, then maintained by IntersectionObserver. */
+export declare function inView(el: Element, opts?: IntersectionObserverInit): Cell<boolean>;