bireactive 0.2.0

package/dist/core/traits.d.ts

@@ -0,0 +1,61 @@
+export interface Linear<T> {
+    add(a: T, b: T): T;
+    sub(a: T, b: T): T;
+    scale(a: T, k: number): T;
+}
+export type Lerp<T> = (a: T, b: T, t: number) => T;
+export type Metric<T> = (a: T, b: T) => number;
+export type Equals<T> = (a: T, b: T) => boolean;
+/** Flat-buffer codec: view a typed value as a `dim`-sized slice of a
+ *  shared `Float64Array`, read/written by offset to avoid allocations
+ *  in hot numerical loops. */
+export interface Pack<T> {
+    readonly dim: number;
+    read(value: T, into: Float64Array, offset: number): void;
+    write(from: Float64Array, offset: number): T;
+}
+/** 2-D group action: rotation + uniform scale about a pivot. Used by
+ *  closed-form aggregate lenses ("rotate/scale the cluster about its
+ *  centroid"). Per-value-class semantics — Pose rotates position AND
+ *  orientation, Vec only position; pivot is always a 2-D `{x, y}`.
+ *  Caller passes signed dθ (wraps) and k (k < 0 reflects). */
+export interface Pivotal<T> {
+    rotateAbout(value: T, pivot: {
+        x: number;
+        y: number;
+    }, dθ: number): T;
+    scaleAbout(value: T, pivot: {
+        x: number;
+        y: number;
+    }, k: number): T;
+}
+/** Shape of a value class's `static traits` dict. Subclasses fill the
+ *  subset they implement; consumers constrain on `Traits<T, …keys>`. */
+export interface TraitDict<T> {
+    linear?: Linear<T>;
+    lerp?: Lerp<T>;
+    metric?: Metric<T>;
+    equals?: Equals<T>;
+    pack?: Pack<T>;
+    pivotal?: Pivotal<T>;
+}
+/** Valid keys of `TraitDict`. The set of declarable traits. */
+export type TraitKey = keyof TraitDict<unknown>;
+/** "A reactive whose class declares the listed traits." `_t` is a
+ *  phantom slot typed against `typeof Cls.traits`; listed keys must
+ *  resolve to non-null. Pure constraint — doesn't imply `Cell<T>`;
+ *  intersect with `Writable<Cell<T>>` / `Read<T>` for capability.
+ *
+ *      function spring<T>(sig: Traits<T, "linear" | "metric">, target: Val<T>)
+ *      function tween<T>(sig: Traits<T, "lerp">, target: T, dur: Val<number>) */
+export type Traits<T, K extends TraitKey = never> = {
+    readonly _t: {
+        [P in K]-?: NonNullable<TraitDict<T>[P]>;
+    } & TraitDict<T>;
+};
+export declare function requireLinear<T>(s: Traits<T, "linear">): Linear<T>;
+export declare function requireLerp<T>(s: Traits<T, "lerp">): Lerp<T>;
+export declare function requireMetric<T>(s: Traits<T, "metric">): Metric<T>;
+export declare function requireEquals<T>(s: Traits<T, "equals">): Equals<T>;
+export declare function requirePack<T>(s: Traits<T, "pack">): Pack<T>;
+export declare function requirePivotal<T>(s: Traits<T, "pivotal">): Pivotal<T>;

package/dist/core/traits.js

@@ -0,0 +1,56 @@
+// Traits — polymorphic interfaces declared on the class via a single
+// `static traits = { … }` dictionary. One nominal constraint type
+// `Traits<T, K>` covers any combination of required traits via a union
+// of keys (no per-trait alias proliferation):
+//
+//   function spring<T>(sig: Traits<T, "linear" | "metric">, target: Val<T>) …
+//   function tween<T>(sig: Traits<T, "lerp">, target: T, dur: Val<number>) …
+//
+// The dictionary shape is `TraitDict<T>`; `Traits<T, K>` is the
+// constraint consumers see. Two separate axes:
+//   - Type level: `Traits<T, K>` requires a phantom `_t` slot typed
+//     against the class's static traits (`declare readonly _t: …`).
+//   - Runtime: `requireLinear` & siblings walk `s.constructor.traits.*`.
+//
+// The engine (signal.ts) is trait-ignorant; subclasses thread equality
+// through `super(v, { equals })` themselves.
+/** Class-level traits dictionary for any Cell subclass. */
+const dictOf = (s) => s.constructor?.traits ?? {};
+const className = (s) => s.constructor?.name ?? "?";
+const missing = (s, slot) => new Error(`require${slot}: ${className(s)} has no traits.${slot.toLowerCase()}`);
+export function requireLinear(s) {
+    const v = dictOf(s).linear;
+    if (!v)
+        throw missing(s, "Linear");
+    return v;
+}
+export function requireLerp(s) {
+    const v = dictOf(s).lerp;
+    if (!v)
+        throw missing(s, "Lerp");
+    return v;
+}
+export function requireMetric(s) {
+    const v = dictOf(s).metric;
+    if (!v)
+        throw missing(s, "Metric");
+    return v;
+}
+export function requireEquals(s) {
+    const v = dictOf(s).equals;
+    if (!v)
+        throw missing(s, "Equals");
+    return v;
+}
+export function requirePack(s) {
+    const v = dictOf(s).pack;
+    if (!v)
+        throw missing(s, "Pack");
+    return v;
+}
+export function requirePivotal(s) {
+    const v = dictOf(s).pivotal;
+    if (!v)
+        throw missing(s, "Pivotal");
+    return v;
+}

package/dist/core/tree.d.ts

@@ -0,0 +1,23 @@
+/** Recursive container: a value plus zero-or-more children of the same
+ *  shape. Value is unconstrained — a single cell or a compound record
+ *  (e.g. a bone with local + world poses). Structural edits go through
+ *  `network()`. */
+export interface TreeNode<T> {
+    readonly value: T;
+    readonly children: readonly TreeNode<T>[];
+}
+/** Construct a tree node. */
+export declare function node<T>(value: T, children?: readonly TreeNode<T>[]): TreeNode<T>;
+/** Depth-first traversal. `visit` receives the node, its depth from
+ *  the root, and the path of child-indices from the root. */
+export declare function walkTree<T>(root: TreeNode<T>, visit: (n: TreeNode<T>, depth: number, path: readonly number[]) => void): void;
+/** Collect every leaf (a node with no children) in depth-first order. */
+export declare function leavesOf<T>(root: TreeNode<T>): TreeNode<T>[];
+/** Collect every node (leaf and internal) in depth-first order. */
+export declare function allNodes<T>(root: TreeNode<T>): TreeNode<T>[];
+/** Index a node by path from root. Empty path returns root. */
+export declare function atPath<T>(root: TreeNode<T>, path: readonly number[]): TreeNode<T>;
+/** True iff `n` is a leaf (no children). */
+export declare function isLeaf<T>(n: TreeNode<T>): boolean;
+/** Count nodes in the tree. */
+export declare function nodeCount<T>(root: TreeNode<T>): number;

package/dist/core/tree.js

@@ -0,0 +1,62 @@
+// tree.ts — hierarchical structure of (typically reactive) values.
+//
+// A `TreeNode<T>` is the structural relationship between values, not a
+// single big `Cell<TreeShape>`. Each node's value is typically a
+// Cell subclass or a compound of cells; writes flow through the
+// individual cells with the engine's usual O(1) incrementality.
+//
+// Two bidirectional patterns layer on top (as free factory functions):
+//   1. AGGREGATE (bottom-up): an internal node lenses over its leaves —
+//      merge on read, redistribute on write (sum-trees, mean-trees, …).
+//   2. PROPAGATE (top-down): each node carries a local value; its
+//      "world" view composes the parent's with its own. The classical
+//      scene-graph / armature shape, parametrised by compose/decompose.
+/** Construct a tree node. */
+export function node(value, children = []) {
+    return { value, children };
+}
+/** Depth-first traversal. `visit` receives the node, its depth from
+ *  the root, and the path of child-indices from the root. */
+export function walkTree(root, visit) {
+    const inner = (n, depth, path) => {
+        visit(n, depth, path);
+        for (let i = 0; i < n.children.length; i++) {
+            inner(n.children[i], depth + 1, [...path, i]);
+        }
+    };
+    inner(root, 0, []);
+}
+/** Collect every leaf (a node with no children) in depth-first order. */
+export function leavesOf(root) {
+    const out = [];
+    walkTree(root, n => {
+        if (n.children.length === 0)
+            out.push(n);
+    });
+    return out;
+}
+/** Collect every node (leaf and internal) in depth-first order. */
+export function allNodes(root) {
+    const out = [];
+    walkTree(root, n => out.push(n));
+    return out;
+}
+/** Index a node by path from root. Empty path returns root. */
+export function atPath(root, path) {
+    let n = root;
+    for (const i of path)
+        n = n.children[i];
+    return n;
+}
+/** True iff `n` is a leaf (no children). */
+export function isLeaf(n) {
+    return n.children.length === 0;
+}
+/** Count nodes in the tree. */
+export function nodeCount(root) {
+    let c = 0;
+    walkTree(root, () => {
+        c++;
+    });
+    return c;
+}

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

@@ -0,0 +1,23 @@
+import type { Inner } from "../signal.js";
+import type { Vec } from "./vec.js";
+type V = Inner<Vec>;
+/** Anchor points on the unit box (`Center = {0.5, 0.5}`). */
+export declare const Anchor: {
+    TopLeft: V;
+    Top: V;
+    TopRight: V;
+    Left: V;
+    Center: V;
+    Right: V;
+    BottomLeft: V;
+    Bottom: V;
+    BottomRight: V;
+};
+/** Unit direction vectors (y-down: `Up = {0,-1}`). */
+export declare const Dir: {
+    Left: V;
+    Right: V;
+    Up: V;
+    Down: V;
+};
+export {};

package/dist/core/values/anchor.js

@@ -0,0 +1,23 @@
+// anchor.ts — points on the unit box `[0,1]²` (registration on a shape).
+// dir.ts — unit direction vectors in `[-1,1]²` (displacement from rest).
+//
+// Plain constants — no reactive wrapping. Use as defaults / arguments.
+/** Anchor points on the unit box (`Center = {0.5, 0.5}`). */
+export const Anchor = {
+    TopLeft: { x: 0, y: 0 },
+    Top: { x: 0.5, y: 0 },
+    TopRight: { x: 1, y: 0 },
+    Left: { x: 0, y: 0.5 },
+    Center: { x: 0.5, y: 0.5 },
+    Right: { x: 1, y: 0.5 },
+    BottomLeft: { x: 0, y: 1 },
+    Bottom: { x: 0.5, y: 1 },
+    BottomRight: { x: 1, y: 1 },
+};
+/** Unit direction vectors (y-down: `Up = {0,-1}`). */
+export const Dir = {
+    Left: { x: -1, y: 0 },
+    Right: { x: 1, y: 0 },
+    Up: { x: 0, y: -1 },
+    Down: { x: 0, y: 1 },
+};

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

@@ -0,0 +1,33 @@
+import { Cell, type Init, type Val, type Writable } from "../signal.js";
+import { Num } from "./num.js";
+/** Clip header. The graph compares `epoch`; `pcm` is one channel buffer each. */
+export interface AudioClip {
+    readonly pcm: readonly Float32Array[];
+    readonly sampleRate: number;
+    readonly epoch: number;
+}
+type V = AudioClip;
+/** Stamp channel buffers with a fresh epoch — the only way to mint a value. */
+export declare const stamp: (pcm: readonly Float32Array[], sampleRate: number) => V;
+export declare const equals: (a: V, b: V) => boolean;
+export declare class Audio extends Cell<V> {
+    static traits: {
+        equals: (a: V, b: V) => boolean;
+    };
+    readonly _t: typeof Audio.traits;
+    constructor(v?: V);
+    /** Time-reverse every channel. Involution. */
+    reverse(): this;
+    /** Scalar gain. Invertible while k ≠ 0 — the audio twin of Canvas.brightness. */
+    gain(k: Val<number>): this;
+    /** Peak-normalize to reactive `target` (default 1). The view alone can't
+     *  know the source's loudness, so the complement carries the original peak and
+     *  the backward pass restores it. The audio analog of str.lowercase(). */
+    normalize(target?: Val<number>): Writable<Audio>;
+    /** RMS loudness as a writable `Num`; writing rescales the clip to hit it. */
+    rms(): Writable<Num>;
+}
+/** Writable `Audio`. A `Clip` seeds a fresh cell; an existing `Writable<Audio>`
+ *  passes through by identity. */
+export declare function audio(v: Init<Audio>): Writable<Audio>;
+export {};

package/dist/core/values/audio.js

@@ -0,0 +1,107 @@
+// audio.ts — reactive audio clip (handle-as-value), the sound twin of canvas.ts.
+//
+// A Clip is context-free PCM: one Float32Array per channel plus a sample rate.
+// The graph transports only the tiny header {pcm, sampleRate, epoch} and compares
+// the monotonic epoch, so propagation never scans a sample and nothing is copied
+// across the bus (same handle-as-value rule as Canvas, minus the GL context — PCM
+// needs no ambient AudioContext, that only appears at the playback sink).
+//
+// Tiers mirror the rest of values/:
+//   - pure isomorphisms (`reverse`) — one pass each way.
+//   - reactive-param invertible (`gain(k)`) — reads `Val<number>`.
+//   - complement projection (`normalize`) — the lossy view (peak-scaled) plus a
+//     complement (the original peak) recovered on write-back, the audio analog of
+//     str.lowercase()/canvas.grayscale().
+//   - cross-type lens (`rms` → Num).
+import { Cell, reader } from "../signal.js";
+import { Num } from "./num.js";
+let EPOCH = 0;
+/** Stamp channel buffers with a fresh epoch — the only way to mint a value. */
+export const stamp = (pcm, sampleRate) => ({
+    pcm,
+    sampleRate,
+    epoch: ++EPOCH,
+});
+export const equals = (a, b) => a.epoch === b.epoch;
+const peak = (v) => {
+    let m = 0;
+    for (const ch of v.pcm) {
+        for (let i = 0; i < ch.length; i++) {
+            const a = ch[i] < 0 ? -ch[i] : ch[i];
+            if (a > m)
+                m = a;
+        }
+    }
+    return m;
+};
+const rmsOf = (v) => {
+    let sum = 0;
+    let n = 0;
+    for (const ch of v.pcm) {
+        for (let i = 0; i < ch.length; i++)
+            sum += ch[i] * ch[i];
+        n += ch.length;
+    }
+    return n === 0 ? 0 : Math.sqrt(sum / n);
+};
+const scaled = (v, k) => stamp(v.pcm.map(ch => {
+    const o = new Float32Array(ch.length);
+    for (let i = 0; i < ch.length; i++)
+        o[i] = ch[i] * k;
+    return o;
+}), v.sampleRate);
+export class Audio extends Cell {
+    static traits = { equals };
+    constructor(v = { pcm: [], sampleRate: 44100, epoch: 0 }) {
+        super(v, { equals });
+    }
+    /** Time-reverse every channel. Involution. */
+    reverse() {
+        const run = (v) => stamp(v.pcm.map(ch => {
+            const o = new Float32Array(ch.length);
+            for (let i = 0; i < ch.length; i++)
+                o[i] = ch[ch.length - 1 - i];
+            return o;
+        }), v.sampleRate);
+        return this.lens(run, run);
+    }
+    /** Scalar gain. Invertible while k ≠ 0 — the audio twin of Canvas.brightness. */
+    gain(k) {
+        const kf = reader(k);
+        return this.lens(v => scaled(v, kf()), n => scaled(n, 1 / kf()));
+    }
+    /** Peak-normalize to reactive `target` (default 1). The view alone can't
+     *  know the source's loudness, so the complement carries the original peak and
+     *  the backward pass restores it. The audio analog of str.lowercase(). */
+    normalize(target = 1) {
+        const tf = reader(target);
+        const self = this;
+        return Audio.lens([self], {
+            init: ([s]) => peak(s),
+            step: ([s], c, external) => (external ? peak(s) : c),
+            fwd: ([s]) => {
+                const p = peak(s);
+                return p === 0 ? s : scaled(s, tf() / p);
+            },
+            bwd: (view, _src, c) => {
+                const t = tf();
+                return { updates: [t === 0 ? view : scaled(view, c / t)], complement: c };
+            },
+        });
+    }
+    /** RMS loudness as a writable `Num`; writing rescales the clip to hit it. */
+    rms() {
+        const self = this;
+        return Num.lens(self, v => rmsOf(v), (target, v) => {
+            const cur = rmsOf(v);
+            return cur === 0 ? v : scaled(v, target / cur);
+        });
+    }
+}
+/** Writable `Audio`. A `Clip` seeds a fresh cell; an existing `Writable<Audio>`
+ *  passes through by identity. */
+export function audio(v) {
+    if (v instanceof Audio)
+        return v;
+    return new Audio(v);
+}

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

@@ -0,0 +1,37 @@
+import { Cell, type Init, type Val, type Writable } from "../signal.js";
+import type { Linear } from "../traits.js";
+type V = boolean;
+export declare const not: (a: V) => V;
+export declare const and: (a: V, b: V) => V;
+export declare const or: (a: V, b: V) => V;
+export declare const xor: (a: V, b: V) => V;
+export declare const equals: (a: V, b: V) => boolean;
+export declare class Bool extends Cell<V> {
+    static traits: {
+        linear: Linear<boolean>;
+        equals: (a: V, b: V) => boolean;
+    };
+    readonly _t: typeof Bool.traits;
+    constructor(v?: V);
+    /** Logical negation. Involution; chains compose. */
+    not(): this;
+    /** Symmetric difference / parity. Invertible:
+     *  `a ^ b = c  ↔  a = c ^ b`. The F₂ analog of `Num#add`. */
+    xor(b: Val<V>): this;
+    /** `this && b`. RO: fan-in write-back isn't unique — use
+     *  `Bool.lens([a, b], ...)` with an explicit policy for a writable AND. */
+    and(b: Val<V>): Bool;
+    or(b: Val<V>): Bool;
+    /** `this → b ≡ ¬this ∨ b`. */
+    implies(b: Val<V>): Bool;
+    /** Boolean equality — XNOR. */
+    eq(b: Val<V>): Bool;
+    nand(b: Val<V>): Bool;
+    nor(b: Val<V>): Bool;
+}
+/** Writable `Bool`. Literal seeds a fresh cell; existing `Writable<Bool>`
+ *  passes through by identity. RO sources are rejected at the type level —
+ *  use `Bool.derive(...)` for reactive RO tracking, or `cell.value` to
+ *  snapshot. */
+export declare function bool(v?: Init<Bool>): Writable<Bool>;
+export {};

package/dist/core/values/bool.js

@@ -0,0 +1,75 @@
+// bool.ts — reactive boolean.
+//
+// Invertibles ride the plain endo `.lens(fwd, bwd)`: `not()` (involution,
+// `.not().not()` round-trips to identity) and `xor(b)` (its own inverse;
+// `a ^ b = c ↔ a = c ^ b`). xor carries Bool's `linear` trait.
+//
+// `and` / `or` / `implies` / `eq` / `nand` / `nor` return bare RO `Bool`
+// — lossy fan-ins whose write-back is ambiguous. Lift to writable via
+// `Bool.lens([a, b], fwd, bwd)` with an explicit policy.
+import { Cell, reader } from "../signal.js";
+export const not = (a) => !a;
+export const and = (a, b) => a && b;
+export const or = (a, b) => a || b;
+export const xor = (a, b) => a !== b;
+export const equals = (a, b) => a === b;
+// F₂-linear structure: xor is both add and sub (a ^ a = false);
+// scale-by-integer collapses by parity (even k → false, odd k → a).
+const linearImpl = {
+    add: xor,
+    sub: xor,
+    scale: (a, k) => (Math.round(k) % 2 !== 0 ? a : false),
+};
+export class Bool extends Cell {
+    static traits = { linear: linearImpl, equals };
+    constructor(v = false) {
+        super(v, { equals });
+    }
+    /** Logical negation. Involution; chains compose. */
+    not() {
+        return this.lens(not, not);
+    }
+    /** Symmetric difference / parity. Invertible:
+     *  `a ^ b = c  ↔  a = c ^ b`. The F₂ analog of `Num#add`. */
+    xor(b) {
+        const bf = reader(b);
+        return this.lens(v => v !== bf(), n => n !== bf());
+    }
+    /** `this && b`. RO: fan-in write-back isn't unique — use
+     *  `Bool.lens([a, b], ...)` with an explicit policy for a writable AND. */
+    and(b) {
+        const bf = reader(b);
+        return Bool.derive(() => this.value && bf());
+    }
+    or(b) {
+        const bf = reader(b);
+        return Bool.derive(() => this.value || bf());
+    }
+    /** `this → b ≡ ¬this ∨ b`. */
+    implies(b) {
+        const bf = reader(b);
+        return Bool.derive(() => !this.value || bf());
+    }
+    /** Boolean equality — XNOR. */
+    eq(b) {
+        const bf = reader(b);
+        return Bool.derive(() => this.value === bf());
+    }
+    nand(b) {
+        const bf = reader(b);
+        return Bool.derive(() => !(this.value && bf()));
+    }
+    nor(b) {
+        const bf = reader(b);
+        return Bool.derive(() => !(this.value || bf()));
+    }
+}
+/** Writable `Bool`. Literal seeds a fresh cell; existing `Writable<Bool>`
+ *  passes through by identity. RO sources are rejected at the type level —
+ *  use `Bool.derive(...)` for reactive RO tracking, or `cell.value` to
+ *  snapshot. */
+export function bool(v = false) {
+    if (v instanceof Bool)
+        return v;
+    return new Bool(v);
+}

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

@@ -0,0 +1,77 @@
+import type { Easing } from "../../animation/index.js";
+import { type Tween } from "../anim.js";
+import { Cell, type Init, type Inner, 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";
+import { Vec } from "./vec.js";
+type V = {
+    x: number;
+    y: number;
+    w: number;
+    h: 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 the flat (x, y, w, h) representation. */
+export declare const metric: (a: V, b: V) => number;
+export declare const expand: (b: V, n: number) => V;
+export declare const contains: (b: V, p: Inner<Vec>) => boolean;
+/** Closest point inside `b` to `p`. Already-inside is identity; outside
+ *  snaps to the nearest boundary point. `Box#contains`'s true-side bwd. */
+export declare const clampToBox: (p: Inner<Vec>, b: V) => Inner<Vec>;
+/** Closest point strictly outside `b` to `p`, displaced past the nearest
+ *  edge by `eps`. Already-outside is identity. `Box#contains`'s
+ *  false-side bwd. */
+export declare const ejectFromBox: (p: Inner<Vec>, b: V, eps?: number) => Inner<Vec>;
+/** Bounding box around a set of boxes. */
+export declare function union(...bs: V[]): V;
+/** Perimeter point on a Box facing `toward`. Default `Shape.boundary`. */
+export declare function edgeFrom(b: V, toward: Inner<Vec>): Inner<Vec>;
+export declare class Box 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 Box.traits;
+    constructor(v?: V);
+    add(b: Val<V>): this;
+    sub(b: Val<V>): this;
+    scale(k: Val<number>): this;
+    expand(n: Val<number>): this;
+    lerp(b: Val<V>, t: Val<number>): Box;
+    /** Membership predicate. Conditional return type: a writable `Vec`
+     *  yields `Writable<Bool>` and flipping the view moves the source —
+     *  `true` clamps to the nearest in-box point, `false` ejects past the
+     *  nearest edge by `eps`. Literal / RO inputs yield a bare RO `Bool`. */
+    contains<P extends Val<Inner<Vec>>>(p: P): P extends WritableBrand ? Writable<Bool> : Bool;
+    get x(): this extends WritableBrand ? Writable<Num> : Num;
+    get y(): this extends WritableBrand ? Writable<Num> : Num;
+    get w(): this extends WritableBrand ? Writable<Num> : Num;
+    get h(): this extends WritableBrand ? Writable<Num> : Num;
+    get area(): Num;
+    /** Vec at parametric (u, v) within `[0,1]²`. Not memoised (arbitrary
+     *  pairs would leak a cache entry each) — use the named edge getters
+     *  (`.center`, `.top`, …) for stable identity. */
+    at(u: number, v: number): Vec;
+    get center(): Vec;
+    get top(): Vec;
+    get bottom(): Vec;
+    get left(): Vec;
+    get right(): Vec;
+    /** Tween-builder, implied by the lerp trait. */
+    to(this: Writable<Box>, target: V, dur: Val<number>, ease?: Easing): Tween<V>;
+}
+/** Writable `Box` at `(x, y, w, h)`. Each component 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
+ *  `Box.derive(...)` for reactive RO tracking, or `cell.value` to
+ *  snapshot. Lock a component with `Num.pin(c)`. */
+export declare function box(x?: Init<Num>, y?: Init<Num>, w?: Init<Num>, h?: Init<Num>): Writable<Box>;
+export {};