bireactive 0.2.0

package/dist/core/values/matrix.js

@@ -0,0 +1,140 @@
+// matrix.ts — reactive 2D affine matrix (SVG/Canvas convention).
+//
+// Sparse-trait: only `equals`. Element-wise linear combine / lerp don't
+// decompose for matrices, so `spring`/`tween`/`mean` reject Matrix at
+// compile time. Two invertibles, both `: this` via `Cell#lens`:
+//   - `multiply(b)` — inverse multiplies by `invert(b)`
+//   - `invert()`    — its own inverse
+import { Cell, reader } from "../signal.js";
+import { derived, field } from "../writable.js";
+import { Num, num } from "./num.js";
+export const identity = () => ({ a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 });
+export const fromTranslate = (x, y) => ({ a: 1, b: 0, c: 0, d: 1, e: x, f: y });
+export const fromScale = (x, y) => ({ a: x, b: 0, c: 0, d: y, e: 0, f: 0 });
+export const fromRotate = (angle) => {
+    const s = Math.sin(angle);
+    const c = Math.cos(angle);
+    return { a: c, b: s, c: -s, d: c, e: 0, f: 0 };
+};
+export const isIdentity = (m) => m.a === 1 && m.b === 0 && m.c === 0 && m.d === 1 && m.e === 0 && m.f === 0;
+export const equals = (m, n) => m === n ||
+    (m.a === n.a && m.b === n.b && m.c === n.c && m.d === n.d && m.e === n.e && m.f === n.f);
+export function multiply(a, b) {
+    return {
+        a: a.a * b.a + a.c * b.b,
+        b: a.b * b.a + a.d * b.b,
+        c: a.a * b.c + a.c * b.d,
+        d: a.b * b.c + a.d * b.d,
+        e: a.a * b.e + a.c * b.f + a.e,
+        f: a.b * b.e + a.d * b.f + a.f,
+    };
+}
+export function invert(m) {
+    const det = m.a * m.d - m.b * m.c;
+    if (det === 0)
+        throw new Error("Matrix not invertible");
+    const inv = 1 / det;
+    return {
+        a: m.d * inv,
+        b: -m.b * inv,
+        c: -m.c * inv,
+        d: m.a * inv,
+        e: (m.c * m.f - m.d * m.e) * inv,
+        f: (m.b * m.e - m.a * m.f) * inv,
+    };
+}
+export const determinant = (m) => m.a * m.d - m.b * m.c;
+export const transformPoint = (m, p) => ({
+    x: m.a * p.x + m.c * p.y + m.e,
+    y: m.b * p.x + m.d * p.y + m.f,
+});
+export function transformBox(m, b) {
+    if (isIdentity(m))
+        return b;
+    const x0 = b.x, y0 = b.y, x1 = b.x + b.w, y1 = b.y + b.h;
+    const ax = m.a * x0 + m.c * y0 + m.e;
+    const ay = m.b * x0 + m.d * y0 + m.f;
+    const bx = m.a * x1 + m.c * y0 + m.e;
+    const by = m.b * x1 + m.d * y0 + m.f;
+    const cx = m.a * x1 + m.c * y1 + m.e;
+    const cy = m.b * x1 + m.d * y1 + m.f;
+    const dx = m.a * x0 + m.c * y1 + m.e;
+    const dy = m.b * x0 + m.d * y1 + m.f;
+    return {
+        x: Math.min(ax, bx, cx, dx),
+        y: Math.min(ay, by, cy, dy),
+        w: Math.max(ax, bx, cx, dx) - Math.min(ax, bx, cx, dx),
+        h: Math.max(ay, by, cy, dy) - Math.min(ay, by, cy, dy),
+    };
+}
+const SCALE_EPS = 1e-7;
+export function compose(t, r, s, pivot) {
+    const sx = Math.abs(s.x) < SCALE_EPS ? (s.x < 0 ? -SCALE_EPS : SCALE_EPS) : s.x;
+    const sy = Math.abs(s.y) < SCALE_EPS ? (s.y < 0 ? -SCALE_EPS : SCALE_EPS) : s.y;
+    let m = fromTranslate(t.x, t.y);
+    m = multiply(m, fromTranslate(pivot.x, pivot.y));
+    if (r !== 0)
+        m = multiply(m, fromRotate(r));
+    if (sx !== 1 || sy !== 1)
+        m = multiply(m, fromScale(sx, sy));
+    m = multiply(m, fromTranslate(-pivot.x, -pivot.y));
+    return m;
+}
+export const toMatrixString = (m) => `matrix(${m.a},${m.b},${m.c},${m.d},${m.e},${m.f})`;
+export class Matrix extends Cell {
+    static traits = { equals };
+    constructor(v = identity()) {
+        super(v, { equals });
+    }
+    multiply(b) {
+        const bf = reader(b);
+        return this.lens(v => multiply(v, bf()), n => multiply(n, invert(bf())));
+    }
+    invert() {
+        return this.lens(invert, invert);
+    }
+    get a() {
+        return field(this, "a", Num);
+    }
+    get b() {
+        return field(this, "b", Num);
+    }
+    get c() {
+        return field(this, "c", Num);
+    }
+    get d() {
+        return field(this, "d", Num);
+    }
+    get e() {
+        return field(this, "e", Num);
+    }
+    get f() {
+        return field(this, "f", Num);
+    }
+    get determinant() {
+        return derived(this, "determinant", Num, determinant);
+    }
+}
+/** Writable `Matrix` with entries `(a, b, c, d, e, f)` (SVG/Canvas order).
+ *  Each entry 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 `Matrix.derive(...)` for reactive RO tracking, or
+ *  `cell.value` to snapshot. Lock an entry with `Num.pin(c)`. */
+export function matrix(a = 1, b = 0, c = 0, d = 1, e = 0, f = 0) {
+    if (typeof a === "number" &&
+        typeof b === "number" &&
+        typeof c === "number" &&
+        typeof d === "number" &&
+        typeof e === "number" &&
+        typeof f === "number") {
+        return new Matrix({ a, b, c, d, e, f });
+    }
+    const aN = num(a);
+    const bN = num(b);
+    const cN = num(c);
+    const dN = num(d);
+    const eN = num(e);
+    const fN = num(f);
+    // The view fully reconstructs all 6 cells (1-arg bwd ⇒ no source read).
+    return Matrix.lens([aN, bN, cN, dN, eN, fN], ([a, b, c, d, e, f]) => ({ a, b, c, d, e, f }), v => [v.a, v.b, v.c, v.d, v.e, v.f]);
+}

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

@@ -0,0 +1,62 @@
+import type { Easing } from "../../animation/index.js";
+import { type Tween } from "../anim.js";
+import { Cell, type Init, type Val, type Writable, type WritableBrand } from "../signal.js";
+import type { Linear, Pack } from "../traits.js";
+import { Bool } from "./bool.js";
+type V = number;
+export declare const add: (a: V, b: V) => number;
+export declare const sub: (a: V, b: V) => number;
+export declare const scale: (a: V, k: number) => number;
+export declare const lerp: (a: V, b: V, t: number) => number;
+export declare const metric: (a: V, b: V) => number;
+export declare const equals: (a: V, b: V) => boolean;
+export declare class Num extends Cell<V> {
+    static traits: {
+        linear: Linear<number>;
+        lerp: (a: V, b: V, t: number) => number;
+        metric: (a: V, b: V) => number;
+        equals: (a: V, b: V) => boolean;
+        pack: Pack<number>;
+    };
+    readonly _t: typeof Num.traits;
+    constructor(v?: V);
+    add(b: Val<V>): this;
+    sub(b: Val<V>): this;
+    scale(k: Val<number>): this;
+    /** Affine `v ↦ k·v + off`. Invertible iff k ≠ 0; readability alias
+     *  for `.scale(k).add(off)`. */
+    affine(k: Val<number>, off: Val<number>): this;
+    /** Lossy clamping lens to `[lo, hi]`. PutGet only (a write outside
+     *  the range reads back clamped, not as written). */
+    clamp(lo: Val<V>, hi: Val<V>): this;
+    /** Lossy lens snapping reads/writes to the nearest multiple of `step`. */
+    quantize(step: Val<number>): this;
+    /** Cyclic-coordinate lens. Reads pass through; writes pick the
+     *  representative closest to current modulo `period`, so dragging an
+     *  angle never jumps a full revolution. The 2-arg bwd is arity-detected
+     *  as stateful, threading the accumulated value through `s`. */
+    cyclic(period: Val<number>): this;
+    /** `this > t` as a Bool. Flipping the view bumps the source across
+     *  the threshold by `eps`. */
+    greaterThan<T extends Num>(this: T, t: Val<V>, eps?: Val<V>): T extends WritableBrand ? Writable<Bool> : Bool;
+    /** `this < t`. Dual of `greaterThan`. */
+    lessThan<T extends Num>(this: T, t: Val<V>, eps?: Val<V>): T extends WritableBrand ? Writable<Bool> : Bool;
+    /** `round(this) ≡ 0 (mod d)` as a Bool; pair with `quantize(1)` for
+     *  integer sliders. Bwd: to make divisible, snap to the nearer
+     *  multiple of `d`; to make non-divisible, bump by `+1`; no-op when
+     *  the class already matches. */
+    divisibleBy<T extends Num>(this: T, d: Val<V>): T extends WritableBrand ? Writable<Bool> : Bool;
+    /** `divisibleBy(2)` — lazy getter for the common case. */
+    get isEven(): this extends WritableBrand ? Writable<Bool> : Bool;
+    /** `not(divisibleBy(2))` — lazy getter. */
+    get isOdd(): this extends WritableBrand ? Writable<Bool> : Bool;
+    /** Tween-builder; `this: Writable<Num>` gates the call to writable
+     *  receivers. */
+    to(this: Writable<Num>, target: V, dur: Val<number>, ease?: Easing): Tween<V>;
+}
+/** Writable `Num`. Literal seeds a fresh cell; existing `Writable<Num>`
+ *  passes through by identity. RO sources are rejected at the type level —
+ *  use `Num.derive(...)` for reactive RO tracking, or `Num.from(...)` for
+ *  the permissive lift over any `Val<number>`. */
+export declare function num(v?: Init<Num>): Writable<Num>;
+export {};

package/dist/core/values/num.js

@@ -0,0 +1,166 @@
+// num.ts — reactive scalar.
+//
+// Invertibles return `: this` and ride on `Cell#lens(fwd, bwd)`;
+// chained calls compose into a lens chain.
+import { tween } from "../anim.js";
+import { Cell, lazy, reader, } from "../signal.js";
+import { Bool } from "./bool.js";
+export const add = (a, b) => a + b;
+export const sub = (a, b) => a - b;
+export const scale = (a, k) => a * k;
+export const lerp = (a, b, t) => a + (b - a) * t;
+export const metric = (a, b) => Math.abs(a - b);
+export const equals = (a, b) => a === b;
+const linearImpl = { add, sub, scale };
+const packImpl = {
+    dim: 1,
+    read: (v, a, o) => {
+        a[o] = v;
+    },
+    write: (a, o) => a[o],
+};
+export class Num extends Cell {
+    static traits = {
+        linear: linearImpl,
+        lerp,
+        metric,
+        equals,
+        pack: packImpl,
+    };
+    constructor(v = 0) {
+        super(v, { equals });
+    }
+    add(b) {
+        const bf = reader(b);
+        return this.lens(v => v + bf(), n => n - bf());
+    }
+    sub(b) {
+        const bf = reader(b);
+        return this.lens(v => v - bf(), n => n + bf());
+    }
+    scale(k) {
+        const kf = reader(k);
+        return this.lens(v => v * kf(), n => n / kf());
+    }
+    /** Affine `v ↦ k·v + off`. Invertible iff k ≠ 0; readability alias
+     *  for `.scale(k).add(off)`. */
+    affine(k, off) {
+        const kf = reader(k);
+        const of = reader(off);
+        return this.lens(v => v * kf() + of(), n => (n - of()) / kf());
+    }
+    /** Lossy clamping lens to `[lo, hi]`. PutGet only (a write outside
+     *  the range reads back clamped, not as written). */
+    clamp(lo, hi) {
+        const lf = reader(lo);
+        const hf = reader(hi);
+        const c = (v) => {
+            const l = lf(), h = hf();
+            return v < l ? l : v > h ? h : v;
+        };
+        // A write whose clamped projection matches the current view leaves
+        // the source untouched (off-range source preserved).
+        return this.lens(c, (v, s) => {
+            const cv = c(v);
+            return cv === c(s) ? s : cv;
+        });
+    }
+    /** Lossy lens snapping reads/writes to the nearest multiple of `step`. */
+    quantize(step) {
+        const sf = reader(step);
+        const q = (v) => {
+            const s = sf();
+            return Math.round(v / s) * s;
+        };
+        // A write that snaps to the current bucket leaves the source
+        // untouched (off-grid remainder preserved).
+        return this.lens(q, (v, src) => {
+            const qv = q(v);
+            return qv === q(src) ? src : qv;
+        });
+    }
+    /** Cyclic-coordinate lens. Reads pass through; writes pick the
+     *  representative closest to current modulo `period`, so dragging an
+     *  angle never jumps a full revolution. The 2-arg bwd is arity-detected
+     *  as stateful, threading the accumulated value through `s`. */
+    cyclic(period) {
+        const pf = reader(period);
+        return this.lens(v => v, (v, s) => {
+            const p = pf();
+            const delta = v - s;
+            return s + delta - p * Math.round(delta / p);
+        });
+    }
+    // Predicate bridges to Bool.
+    //
+    // Cross-type quotient lenses projecting Num through a boolean
+    // predicate. Conditional return type: writable receiver yields
+    // `Writable<Bool>`, RO receiver yields RO `Bool`.
+    /** `this > t` as a Bool. Flipping the view bumps the source across
+     *  the threshold by `eps`. */
+    greaterThan(t, eps = 1e-6) {
+        const tf = reader(t);
+        const ef = reader(eps);
+        return Bool.lens(this, v => v > tf(), (target, current) => {
+            const th = tf();
+            if (target === current > th)
+                return current;
+            return target ? th + ef() : th - ef();
+        });
+    }
+    /** `this < t`. Dual of `greaterThan`. */
+    lessThan(t, eps = 1e-6) {
+        const tf = reader(t);
+        const ef = reader(eps);
+        return Bool.lens(this, v => v < tf(), (target, current) => {
+            const th = tf();
+            if (target === current < th)
+                return current;
+            return target ? th - ef() : th + ef();
+        });
+    }
+    /** `round(this) ≡ 0 (mod d)` as a Bool; pair with `quantize(1)` for
+     *  integer sliders. Bwd: to make divisible, snap to the nearer
+     *  multiple of `d`; to make non-divisible, bump by `+1`; no-op when
+     *  the class already matches. */
+    divisibleBy(d) {
+        const df = reader(d);
+        return Bool.lens(this, v => Math.round(v) % df() === 0, (target, current) => {
+            const dv = df();
+            const r = Math.round(current);
+            // ((a % b) + b) % b handles negative `r` cleanly.
+            const mod = ((r % dv) + dv) % dv;
+            const isDiv = mod === 0;
+            if (target === isDiv)
+                return current;
+            if (target) {
+                const down = r - mod;
+                const up = r + (dv - mod);
+                return Math.abs(current - down) <= Math.abs(current - up) ? down : up;
+            }
+            return r + 1;
+        });
+    }
+    /** `divisibleBy(2)` — lazy getter for the common case. */
+    get isEven() {
+        return lazy(this, "isEven", () => this.divisibleBy(2));
+    }
+    /** `not(divisibleBy(2))` — lazy getter. */
+    get isOdd() {
+        return lazy(this, "isOdd", () => this.divisibleBy(2).not());
+    }
+    /** Tween-builder; `this: Writable<Num>` gates the call to writable
+     *  receivers. */
+    to(target, dur, ease) {
+        return tween(this, target, dur, ease);
+    }
+}
+/** Writable `Num`. Literal seeds a fresh cell; existing `Writable<Num>`
+ *  passes through by identity. RO sources are rejected at the type level —
+ *  use `Num.derive(...)` for reactive RO tracking, or `Num.from(...)` for
+ *  the permissive lift over any `Val<number>`. */
+export function num(v = 0) {
+    if (v instanceof Num)
+        return v;
+    return new Num(v);
+}

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

@@ -0,0 +1,31 @@
+import { Cell, type Init, type Writable } from "../signal.js";
+import type { Linear, Pack, Pivotal } from "../traits.js";
+type V = {
+    x: number;
+    y: number;
+    theta: number;
+};
+export declare const add: (a: V, b: V) => V;
+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 metric: (a: V, b: V) => number;
+export declare const equals: (a: V, b: V) => boolean;
+export declare class Pose extends Cell<V> {
+    static traits: {
+        linear: Linear<V>;
+        lerp: (a: V, b: V, t: number) => V;
+        metric: (a: V, b: V) => number;
+        equals: (a: V, b: V) => boolean;
+        pack: Pack<V>;
+        pivotal: Pivotal<V>;
+    };
+    readonly _t: typeof Pose.traits;
+    constructor(v?: V);
+}
+/** Writable `Pose`. Literal seeds a fresh cell; existing `Pose` passes
+ *  through by identity. RO sources are rejected at the type level — use
+ *  `Pose.derive(...)` for reactive RO tracking, or `cell.value` to
+ *  snapshot. */
+export declare function pose(v?: Init<Pose>): Writable<Pose>;
+export {};

package/dist/core/values/pose.js

@@ -0,0 +1,83 @@
+// pose.ts — reactive 2D rigid-body pose: { x, y, theta }.
+//
+// Single source of truth for a rigid body. The solver binds the cell as
+// a 3-DOF block and writes back through it, so renderers, drag handlers,
+// IK, and physics all observe the same value. Vec / Num lenses compose
+// for consumers that care only about translation or rotation.
+import { Cell } from "../signal.js";
+export const add = (a, b) => ({
+    x: a.x + b.x,
+    y: a.y + b.y,
+    theta: a.theta + b.theta,
+});
+export const sub = (a, b) => ({
+    x: a.x - b.x,
+    y: a.y - b.y,
+    theta: a.theta - b.theta,
+});
+export const scale = (a, k) => ({
+    x: a.x * k,
+    y: a.y * k,
+    theta: a.theta * k,
+});
+export const lerp = (a, b, t) => ({
+    x: a.x + (b.x - a.x) * t,
+    y: a.y + (b.y - a.y) * t,
+    theta: a.theta + (b.theta - a.theta) * t,
+});
+export const metric = (a, b) => Math.hypot(a.x - b.x, a.y - b.y, a.theta - b.theta);
+export const equals = (a, b) => a === b || (a.x === b.x && a.y === b.y && a.theta === b.theta);
+const linearImpl = { add, sub, scale };
+const packImpl = {
+    dim: 3,
+    read: (v, a, o) => {
+        a[o] = v.x;
+        a[o + 1] = v.y;
+        a[o + 2] = v.theta;
+    },
+    write: (a, o) => ({ x: a[o], y: a[o + 1], theta: a[o + 2] }),
+};
+/** Rotate-about-pivot moves the position and adds dθ to orientation;
+ *  scale-about-pivot scales position, orientation untouched. */
+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,
+            theta: v.theta + dθ,
+        };
+    },
+    scaleAbout: (v, p, k) => ({
+        x: p.x + k * (v.x - p.x),
+        y: p.y + k * (v.y - p.y),
+        theta: v.theta,
+    }),
+};
+export class Pose extends Cell {
+    static traits = {
+        linear: linearImpl,
+        lerp,
+        metric,
+        equals,
+        pack: packImpl,
+        pivotal: pivotalImpl,
+    };
+    constructor(v = { x: 0, y: 0, theta: 0 }) {
+        super(v, { equals });
+    }
+}
+/** Writable `Pose`. Literal seeds a fresh cell; existing `Pose` passes
+ *  through by identity. RO sources are rejected at the type level — use
+ *  `Pose.derive(...)` for reactive RO tracking, or `cell.value` to
+ *  snapshot. */
+export function pose(v = { x: 0, y: 0, theta: 0 }) {
+    if (v instanceof Pose)
+        return v;
+    const p = new Pose();
+    p.value = v;
+    return p;
+}

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

@@ -0,0 +1,83 @@
+import type { Easing } from "../../animation/index.js";
+import { type Tween } from "../anim.js";
+import { Cell, type Init, type Val, type Writable, type WritableBrand } from "../signal.js";
+import type { Linear, Pack } from "../traits.js";
+import { Bool } from "./bool.js";
+import { Num } from "./num.js";
+type V = {
+    lo: number;
+    hi: number;
+};
+export declare const add: (a: V, b: V) => V;
+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. */
+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. */
+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. */
+export declare const sample: (r: V, t: number) => number;
+/** Inverse of `sample`: given a value, recover the `t` that would
+ *  produce it. Degenerate (zero-width) ranges return 0. */
+export declare const paramOf: (r: V, v: number) => number;
+export declare class Range extends Cell<V> {
+    static traits: {
+        linear: Linear<V>;
+        lerp: (a: V, b: V, t: number) => V;
+        metric: (a: V, b: V) => number;
+        equals: (a: V, b: V) => boolean;
+        pack: Pack<V>;
+    };
+    readonly _t: typeof Range.traits;
+    constructor(v?: V);
+    /** Start endpoint. Writes preserve `hi` (start-knob semantics). */
+    get lo(): this extends WritableBrand ? Writable<Num> : Num;
+    /** End endpoint. Writes preserve `lo` (end-knob semantics). */
+    get hi(): this extends WritableBrand ? Writable<Num> : Num;
+    get width(): Num;
+    get center(): Num;
+    /** Translate by `by`. Reads shift the interval; writes shift back. */
+    shift(by: Val<number>): this;
+    /** Scale uniformly about the origin. Iso for `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`. */
+    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`. */
+    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)`. */
+    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. */
+    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. */
+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)`. */
+export declare function range(lo?: Init<Num>, hi?: Init<Num>): Writable<Range>;
+export {};