bireactive 0.2.0

package/dist/core/values/box.js

@@ -0,0 +1,211 @@
+// box.ts — reactive axis-aligned rectangle.
+//
+// Invertibles (`add`, `sub`, `scale`, `expand`) return `: this` and ride
+// on `Cell#lens(fwd, bwd)`. Chained calls compose into a lens chain.
+import { tween } from "../anim.js";
+import { Cell, isComputed, lazy, reader, readNow, } from "../signal.js";
+import { derived, field } from "../writable.js";
+import { Bool } from "./bool.js";
+import { Num, num } from "./num.js";
+import { Vec } from "./vec.js";
+export const add = (a, b) => ({ x: a.x + b.x, y: a.y + b.y, w: a.w + b.w, h: a.h + b.h });
+export const sub = (a, b) => ({ x: a.x - b.x, y: a.y - b.y, w: a.w - b.w, h: a.h - b.h });
+export const scale = (a, k) => ({ x: a.x * k, y: a.y * k, w: a.w * k, h: a.h * k });
+export const lerp = (a, b, t) => ({
+    x: a.x + (b.x - a.x) * t,
+    y: a.y + (b.y - a.y) * t,
+    w: a.w + (b.w - a.w) * t,
+    h: a.h + (b.h - a.h) * t,
+});
+export const equals = (a, b) => a === b || (a.x === b.x && a.y === b.y && a.w === b.w && a.h === b.h);
+/** L2 distance over the flat (x, y, w, h) representation. */
+export const metric = (a, b) => Math.hypot(a.x - b.x, a.y - b.y, a.w - b.w, a.h - b.h);
+export const expand = (b, n) => ({
+    x: b.x - n,
+    y: b.y - n,
+    w: b.w + 2 * n,
+    h: b.h + 2 * n,
+});
+export const contains = (b, p) => p.x >= b.x && p.x <= b.x + b.w && p.y >= b.y && p.y <= b.y + b.h;
+/** Closest point inside `b` to `p`. Already-inside is identity; outside
+ *  snaps to the nearest boundary point. `Box#contains`'s true-side bwd. */
+export const clampToBox = (p, b) => ({
+    x: Math.max(b.x, Math.min(b.x + b.w, p.x)),
+    y: Math.max(b.y, Math.min(b.y + b.h, p.y)),
+});
+/** 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 const ejectFromBox = (p, b, eps = 1e-6) => {
+    if (!contains(b, p))
+        return p;
+    const dLeft = p.x - b.x;
+    const dRight = b.x + b.w - p.x;
+    const dTop = p.y - b.y;
+    const dBot = b.y + b.h - p.y;
+    const min = Math.min(dLeft, dRight, dTop, dBot);
+    if (min === dLeft)
+        return { x: b.x - eps, y: p.y };
+    if (min === dRight)
+        return { x: b.x + b.w + eps, y: p.y };
+    if (min === dTop)
+        return { x: p.x, y: b.y - eps };
+    return { x: p.x, y: b.y + b.h + eps };
+};
+/** Bounding box around a set of boxes. */
+export function union(...bs) {
+    if (bs.length === 0)
+        return { x: 0, y: 0, w: 0, h: 0 };
+    let xMin = bs[0].x, yMin = bs[0].y;
+    let xMax = xMin + bs[0].w, yMax = yMin + bs[0].h;
+    for (let i = 1; i < bs.length; i++) {
+        const o = bs[i];
+        if (o.x < xMin)
+            xMin = o.x;
+        if (o.y < yMin)
+            yMin = o.y;
+        if (o.x + o.w > xMax)
+            xMax = o.x + o.w;
+        if (o.y + o.h > yMax)
+            yMax = o.y + o.h;
+    }
+    return { x: xMin, y: yMin, w: xMax - xMin, h: yMax - yMin };
+}
+/** Perimeter point on a Box facing `toward`. Default `Shape.boundary`. */
+export function edgeFrom(b, toward) {
+    const cx = b.x + b.w / 2;
+    const cy = b.y + b.h / 2;
+    const dx = toward.x - cx;
+    const dy = toward.y - cy;
+    if (dx === 0 && dy === 0)
+        return { x: cx, y: cy };
+    const k = Math.min(dx === 0 ? Number.POSITIVE_INFINITY : b.w / 2 / Math.abs(dx), dy === 0 ? Number.POSITIVE_INFINITY : b.h / 2 / Math.abs(dy));
+    return { x: cx + dx * k, y: cy + dy * k };
+}
+const linearImpl = { add, sub, scale };
+const packImpl = {
+    dim: 4,
+    read: (v, a, o) => {
+        a[o] = v.x;
+        a[o + 1] = v.y;
+        a[o + 2] = v.w;
+        a[o + 3] = v.h;
+    },
+    write: (a, o) => ({ x: a[o], y: a[o + 1], w: a[o + 2], h: a[o + 3] }),
+};
+export class Box extends Cell {
+    static traits = {
+        linear: linearImpl,
+        lerp,
+        metric,
+        equals,
+        pack: packImpl,
+    };
+    constructor(v = { x: 0, y: 0, w: 0, h: 0 }) {
+        super(v, { equals });
+    }
+    add(b) {
+        const bf = reader(b);
+        return this.lens(v => add(v, bf()), n => sub(n, bf()));
+    }
+    sub(b) {
+        const bf = reader(b);
+        return this.lens(v => sub(v, bf()), n => add(n, bf()));
+    }
+    scale(k) {
+        const kf = reader(k);
+        return this.lens(v => scale(v, kf()), n => scale(n, 1 / kf()));
+    }
+    expand(n) {
+        const nf = reader(n);
+        return this.lens(v => expand(v, nf()), o => expand(o, -nf()));
+    }
+    lerp(b, t) {
+        return Box.derive(() => lerp(this.value, readNow(b), readNow(t)));
+    }
+    /** 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) {
+        if (p instanceof Vec) {
+            // A computed Vec has no backward path → RO branch; sources and
+            // writable lenses accept write-back.
+            if (!isComputed(p)) {
+                // `.bind(Bool)` + cast steps past the generic overloads, whose
+                // mapped-tuple inference over the full class types otherwise blows
+                // the instantiation depth.
+                const mk = Bool.lens.bind(Bool);
+                return mk([this, p], vals => contains(vals[0], vals[1]), (target, vals) => {
+                    const [b, v] = vals;
+                    if (contains(b, v) === target)
+                        return [undefined, undefined];
+                    return [undefined, target ? clampToBox(v, b) : ejectFromBox(v, b)];
+                });
+            }
+        }
+        return Bool.derive(() => contains(this.value, readNow(p)));
+    }
+    get x() {
+        return field(this, "x", Num);
+    }
+    get y() {
+        return field(this, "y", Num);
+    }
+    get w() {
+        return field(this, "w", Num);
+    }
+    get h() {
+        return field(this, "h", Num);
+    }
+    get area() {
+        return derived(this, "area", Num, b => b.w * b.h);
+    }
+    /** 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, v) {
+        return Vec.derive(this, b => ({ x: b.x + u * b.w, y: b.y + v * b.h }));
+    }
+    // Named edges — RO views over `at(u, v)`, memoised under stable keys
+    // so subscribers always see the same Vec. `lazy()` directly since
+    // `at()` already returns a Vec.
+    get center() {
+        return lazy(this, "center", () => this.at(0.5, 0.5));
+    }
+    get top() {
+        return lazy(this, "top", () => this.at(0.5, 0));
+    }
+    get bottom() {
+        return lazy(this, "bottom", () => this.at(0.5, 1));
+    }
+    get left() {
+        return lazy(this, "left", () => this.at(0, 0.5));
+    }
+    get right() {
+        return lazy(this, "right", () => this.at(1, 0.5));
+    }
+    /** Tween-builder, implied by the lerp trait. */
+    to(target, dur, ease) {
+        return tween(this, target, dur, ease);
+    }
+}
+/** 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 function box(x = 0, y = 0, w = 0, h = 0) {
+    if (typeof x === "number" &&
+        typeof y === "number" &&
+        typeof w === "number" &&
+        typeof h === "number") {
+        return new Box({ x, y, w, h });
+    }
+    const xN = num(x);
+    const yN = num(y);
+    const wN = num(w);
+    const hN = num(h);
+    // The view fully reconstructs all 4 axes (1-arg bwd ⇒ no source read).
+    return Box.lens([xN, yN, wN, hN], ([bx, by, bw, bh]) => ({ x: bx, y: by, w: bw, h: bh }), v => [v.x, v.y, v.w, v.h]);
+}

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

@@ -0,0 +1,71 @@
+import { Cell, type Val, type Writable } from "../signal.js";
+import { Bool } from "./bool.js";
+import { Color } from "./color.js";
+import { Spring, type SpringOpts } from "./gpu.js";
+import { Vec } from "./vec.js";
+/** Raster header. The graph compares `epoch`; `tex` is an RGBA32F texture in
+ *  the shared GL context (channels 0–1, may overshoot mid-deconvolution). */
+export interface Raster {
+    readonly tex: WebGLTexture;
+    readonly w: number;
+    readonly h: number;
+    readonly epoch: number;
+}
+type V = Raster;
+/** Stamp a texture with a fresh epoch — the only way to mint a value. */
+export declare const stamp: (tex: WebGLTexture, w: number, h: number) => V;
+export declare const equals: (a: V, b: V) => boolean;
+export declare class Canvas extends Cell<V> {
+    static traits: {
+        equals: (a: V, b: V) => boolean;
+    };
+    readonly _t: typeof Canvas.traits;
+    constructor(v?: V);
+    /** Per-channel invert (alpha preserved). Involution. */
+    invert(): this;
+    /** Horizontal flip. Involution. */
+    flipH(): this;
+    /** Multiply RGB by reactive `k` (alpha preserved). Invertible while
+     *  k ≠ 0. */
+    brightness(k: Val<number>): this;
+    /** Grayscale (Rec.601 luma) view; complement is the per-pixel chroma
+     *  residual `(r−Y, g−Y, b−Y)`, so editing the gray view recolours the
+     *  source. The raster analog of `str.lowercase()`. */
+    grayscale(): Writable<Canvas>;
+    /** Chroma view (the dual of `grayscale`): `(r−Y, g−Y, b−Y)` on a mid-grey
+     *  base, complement is the luma `Y`. Editing the colour re-lights nothing —
+     *  it rewrites hue while keeping the original brightness. */
+    chroma(): Writable<Canvas>;
+    /** Sub-rectangle view (reactive `x,y,w,h`). Editing the crop composites
+     *  back into the source; the surround reads straight from the parent. */
+    crop(x: Val<number>, y: Val<number>, w: Val<number>, h: Val<number>): Writable<Canvas>;
+    /** Box-downsampled thumbnail (integer `factor`). Complement is the
+     *  Laplacian residual `source − up(down(source))`; editing the thumbnail
+     *  reconstructs full-res detail on top of the edit. */
+    downsample(factor: number): Writable<Canvas>;
+    /** Gaussian blur (reactive `radius`). Writable: the backward direction
+     *  runs an iterated Richardson–Lucy deconvolution seeded from the source.
+     *  Each step is `x ← x · H(target / H(x))`, non-negative and multiplicative,
+     *  so untouched regions stay fixed (their ratio is 1) while a stroke
+     *  back-solves to a sharp pre-image with far less ringing than an additive
+     *  solve. PutGet, not exact GetPut — the residual is the honest signature
+     *  of an ill-posed inverse. */
+    blur(radius: Val<number>): this;
+    /** Mean colour (0–1) as a writable `Color`; the GPU reduces, the write
+     *  shifts every pixel by the delta (a rigid translate in RGB). */
+    meanColor(): Writable<Color>;
+    /** Mean luma ≥ reactive `threshold` (0–1) as a writable `Bool`; flipping
+     *  the bit auto-exposes — iterate the gain (clipping caps a single step)
+     *  until the mean crosses the line. */
+    brighterThan(threshold: Val<number>): Writable<Bool>;
+    /** Dimensions `(w, h)` as a read-only `Vec`. */
+    get dimensions(): Vec;
+    /** A GPU per-pixel spring driver seeded from this value's texture. The
+     *  host steps it and writes `current()` back into a root cell each frame;
+     *  settle is the GPU energy reduction. */
+    spring(opts?: SpringOpts): Spring;
+}
+/** Writable `Canvas` of size `w×h`. `painter` fills it pixel-by-pixel
+ *  (RGBA, 0–255); omit for transparent black. Uploaded once to a texture. */
+export declare function canvas(w: number, h: number, painter?: (x: number, y: number) => readonly [number, number, number, number]): Writable<Canvas>;
+export {};