bireactive 0.2.0

package/dist/core/values/canvas.js

@@ -0,0 +1,495 @@
+// canvas.ts — GPU-resident reactive raster (handle-as-value).
+//
+// Every Canvas value is a float texture in the shared WebGL2 context (see
+// gpu.ts); the reactive graph transports only a tiny HEADER {tex, w, h,
+// epoch}, comparing the monotonic epoch, so propagation never reads a pixel
+// and nothing is copied across the bus. Forward lenses render into a per-lens
+// scratch texture (reused across recomputes); the single ownership rule that
+// keeps no-copy safe is the same as on the CPU — a node writes only its own
+// texture, never one another live node still reads, which holds under the
+// engine's glitch-free flush.
+//
+// Tiers mirror the rest of values/:
+//   - pure isomorphisms (`invert`, `flipH`) — one pointwise shader each way.
+//   - reactive-param invertibles (`brightness(k)`) — read `Val<number>`.
+//   - complement projections (`grayscale`, `downsample`) — the lossy view
+//     plus a complement texture (chroma / Laplacian residual) recovered on
+//     write-back, the raster analog of str.ts's case-preserving lenses.
+//   - cross-type lenses (`meanColor` → Color, `brighterThan` → Bool).
+//
+// A backward pass that produces a ROOT cell's next value reads that root and
+// writes a result that becomes its value, so it uses `scratch2` (a feedback-
+// safe pair) to avoid reading and writing the same texture.
+import { Cell, reader } from "../signal.js";
+import { derived } from "../writable.js";
+import { Bool } from "./bool.js";
+import { Color } from "./color.js";
+import { copy, newTex, pass, reduceMean, Spring, scratch, scratch2, } from "./gpu.js";
+import { Vec } from "./vec.js";
+let EPOCH = 0;
+/** Stamp a texture with a fresh epoch — the only way to mint a value. */
+export const stamp = (tex, w, h) => ({
+    tex,
+    w,
+    h,
+    epoch: ++EPOCH,
+});
+export const equals = (a, b) => a.epoch === b.epoch;
+const DECONV_ITERS = 18;
+const MAXR = 10;
+const LUMA_W = "vec3(0.299, 0.587, 0.114)";
+const HEAD = `#version 300 es
+precision highp float;
+in vec2 v_uv;
+out vec4 o;`;
+const INVERT = `${HEAD}
+uniform sampler2D u_s;
+void main() { vec4 c = texture(u_s, v_uv); o = vec4(1.0 - c.rgb, c.a); }`;
+const FLIPH = `${HEAD}
+uniform sampler2D u_s;
+void main() { o = texture(u_s, vec2(1.0 - v_uv.x, v_uv.y)); }`;
+const SCALE3 = `${HEAD}
+uniform sampler2D u_s; uniform float u_k;
+void main() { vec4 c = texture(u_s, v_uv); o = vec4(c.rgb * u_k, c.a); }`;
+const LUMA = `${HEAD}
+uniform sampler2D u_s;
+void main() { vec4 c = texture(u_s, v_uv); float y = dot(c.rgb, ${LUMA_W}); o = vec4(y, y, y, c.a); }`;
+const CHROMA = `${HEAD}
+uniform sampler2D u_s;
+void main() { vec4 c = texture(u_s, v_uv); float y = dot(c.rgb, ${LUMA_W}); o = vec4(c.rgb - y, c.a); }`;
+const RECOLOR = `${HEAD}
+uniform sampler2D u_t; uniform sampler2D u_c;
+void main() { float y = texture(u_t, v_uv).r; vec4 c = texture(u_c, v_uv); o = vec4(y + c.rgb, c.a); }`;
+// chroma() view: (r−Y, g−Y, b−Y) lifted by +0.5 so it shows on a mid-grey
+// base; complement is the luma Y, recovered by DELUMA on write-back.
+const CHROMA_VIEW = `${HEAD}
+uniform sampler2D u_s;
+void main() { vec4 c = texture(u_s, v_uv); float y = dot(c.rgb, ${LUMA_W}); o = vec4(c.rgb - y + 0.5, c.a); }`;
+const DELUMA = `${HEAD}
+uniform sampler2D u_t; uniform sampler2D u_c;
+void main() {
+  vec4 t = texture(u_t, v_uv);
+  vec3 cv = t.rgb - 0.5;
+  cv -= dot(cv, ${LUMA_W});          // strip any luma the painted chroma carries
+  float y = texture(u_c, v_uv).r;    // restore the source's luma exactly
+  o = vec4(cv + y, t.a);
+}`;
+const CROP_FWD = `${HEAD}
+uniform sampler2D u_s; uniform vec2 u_off; uniform vec2 u_csize; uniform vec2 u_ssize;
+void main() { vec2 sp = (u_off + v_uv * u_csize) / u_ssize; o = texture(u_s, sp); }`;
+const CROP_BWD = `${HEAD}
+uniform sampler2D u_s; uniform sampler2D u_t; uniform vec2 u_off; uniform vec2 u_csize; uniform vec2 u_ssize;
+void main() {
+  vec2 sp = v_uv * u_ssize;
+  vec2 rel = sp - u_off;
+  if (rel.x >= 0.0 && rel.y >= 0.0 && rel.x < u_csize.x && rel.y < u_csize.y)
+    o = texture(u_t, rel / u_csize);
+  else o = texture(u_s, v_uv);
+}`;
+const BLUR1D = `${HEAD}
+uniform sampler2D u_s; uniform vec2 u_dir; uniform float u_sigma; uniform int u_r;
+void main() {
+  vec3 acc = vec3(0.0); float wsum = 0.0; float a = texture(u_s, v_uv).a;
+  for (int k = -${MAXR}; k <= ${MAXR}; k++) {
+    if (k < -u_r || k > u_r) continue;
+    float wk = exp(-float(k * k) / (2.0 * u_sigma * u_sigma));
+    acc += texture(u_s, v_uv + u_dir * float(k)).rgb * wk;
+    wsum += wk;
+  }
+  o = vec4(acc / wsum, a);
+}`;
+// Richardson–Lucy step. RL_RATIO forms target / blur(estimate) (guarded);
+// RL_MUL multiplies the estimate by blur(ratio) and clamps to [0,1]. Both
+// the non-negativity clamp and the multiplicative form keep ringing far
+// below an additive Van-Cittert iteration.
+const RL_RATIO = `${HEAD}
+uniform sampler2D u_t; uniform sampler2D u_est;
+void main() {
+  vec4 t = texture(u_t, v_uv); vec3 e = texture(u_est, v_uv).rgb;
+  o = vec4(t.rgb / max(e, vec3(1e-3)), t.a);
+}`;
+const RL_MUL = `${HEAD}
+uniform sampler2D u_x; uniform sampler2D u_c;
+void main() {
+  vec4 x = texture(u_x, v_uv); vec3 c = texture(u_c, v_uv).rgb;
+  o = vec4(clamp(x.rgb * c.rgb, 0.0, 1.0), x.a);
+}`;
+const BOXDOWN = `${HEAD}
+uniform highp sampler2D u_s; uniform int u_f; uniform ivec2 u_ssize;
+void main() {
+  ivec2 d = ivec2(gl_FragCoord.xy); vec4 sum = vec4(0.0); float n = 0.0;
+  for (int dy = 0; dy < ${MAXR}; dy++) { if (dy >= u_f) break;
+    for (int dx = 0; dx < ${MAXR}; dx++) { if (dx >= u_f) break;
+      ivec2 sp = clamp(ivec2(d.x * u_f + dx, d.y * u_f + dy), ivec2(0), u_ssize - 1);
+      sum += texelFetch(u_s, sp, 0); n += 1.0;
+    } }
+  o = sum / n;
+}`;
+const UP = `${HEAD}
+uniform highp sampler2D u_small; uniform int u_f; uniform ivec2 u_smallsize;
+void main() {
+  ivec2 d = ivec2(gl_FragCoord.xy);
+  ivec2 sp = clamp(d / u_f, ivec2(0), u_smallsize - 1);
+  o = texelFetch(u_small, sp, 0);
+}`;
+const ADD = `${HEAD}
+uniform sampler2D u_a; uniform sampler2D u_b;
+void main() { o = texture(u_a, v_uv) + texture(u_b, v_uv); }`;
+const SUB = `${HEAD}
+uniform sampler2D u_a; uniform sampler2D u_b;
+void main() { o = texture(u_a, v_uv) - texture(u_b, v_uv); }`;
+const SHIFT = `${HEAD}
+uniform sampler2D u_s; uniform vec3 u_d;
+void main() { vec4 c = texture(u_s, v_uv); o = vec4(c.rgb + u_d, c.a); }`;
+/** Separable Gaussian of `srcTex` → `out` via `tmp` (all distinct). */
+function gauss(srcTex, w, h, radius, tmp, out) {
+    const r = Math.min(MAXR, Math.max(0, Math.round(radius)));
+    const sigma = Math.max(0.5, radius / 2);
+    pass(BLUR1D, tmp, s => {
+        s.tex("u_s", 0, srcTex);
+        s.v2("u_dir", 1 / w, 0);
+        s.f("u_sigma", sigma);
+        s.i("u_r", r);
+    });
+    pass(BLUR1D, out, s => {
+        s.tex("u_s", 0, tmp.tex);
+        s.v2("u_dir", 0, 1 / h);
+        s.f("u_sigma", sigma);
+        s.i("u_r", r);
+    });
+}
+export class Canvas extends Cell {
+    static traits = { equals };
+    constructor(v = { tex: null, w: 0, h: 0, epoch: 0 }) {
+        super(v, { equals });
+    }
+    /** Per-channel invert (alpha preserved). Involution. */
+    invert() {
+        const sf = scratch();
+        const sb = scratch();
+        const run = (alloc) => (v) => {
+            const out = alloc(v.w, v.h);
+            pass(INVERT, out, s => s.tex("u_s", 0, v.tex));
+            return stamp(out.tex, v.w, v.h);
+        };
+        return this.lens(run(sf), run(sb));
+    }
+    /** Horizontal flip. Involution. */
+    flipH() {
+        const sf = scratch();
+        const sb = scratch();
+        const run = (alloc) => (v) => {
+            const out = alloc(v.w, v.h);
+            pass(FLIPH, out, s => s.tex("u_s", 0, v.tex));
+            return stamp(out.tex, v.w, v.h);
+        };
+        return this.lens(run(sf), run(sb));
+    }
+    /** Multiply RGB by reactive `k` (alpha preserved). Invertible while
+     *  k ≠ 0. */
+    brightness(k) {
+        const kf = reader(k);
+        const sf = scratch();
+        const sb = scratch();
+        const run = (alloc, gain) => (v) => {
+            const out = alloc(v.w, v.h);
+            pass(SCALE3, out, s => {
+                s.tex("u_s", 0, v.tex);
+                s.f("u_k", gain());
+            });
+            return stamp(out.tex, v.w, v.h);
+        };
+        return this.lens(run(sf, () => kf()), run(sb, () => 1 / kf()));
+    }
+    /** 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() {
+        const sc = scratch();
+        const sf = scratch();
+        const sb = scratch();
+        const chromaOf = (v) => {
+            const c = sc(v.w, v.h);
+            pass(CHROMA, c, s => s.tex("u_s", 0, v.tex));
+            return c;
+        };
+        const self = this;
+        return Canvas.lens([self], {
+            init: ([s]) => chromaOf(s),
+            step: ([s], c, external) => (external ? chromaOf(s) : c),
+            fwd: ([s]) => {
+                const out = sf(s.w, s.h);
+                pass(LUMA, out, x => x.tex("u_s", 0, s.tex));
+                return stamp(out.tex, s.w, s.h);
+            },
+            bwd: (target, [s], c) => {
+                const out = sb(s.w, s.h);
+                pass(RECOLOR, out, x => {
+                    x.tex("u_t", 0, target.tex);
+                    x.tex("u_c", 1, c.tex);
+                });
+                return { updates: [stamp(out.tex, s.w, s.h)], complement: c };
+            },
+        });
+    }
+    /** 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() {
+        const sc = scratch();
+        const sf = scratch();
+        const sb = scratch();
+        const lumaOf = (v) => {
+            const c = sc(v.w, v.h);
+            pass(LUMA, c, s => s.tex("u_s", 0, v.tex));
+            return c;
+        };
+        const self = this;
+        return Canvas.lens([self], {
+            init: ([s]) => lumaOf(s),
+            step: ([s], c, external) => (external ? lumaOf(s) : c),
+            fwd: ([s]) => {
+                const out = sf(s.w, s.h);
+                pass(CHROMA_VIEW, out, x => x.tex("u_s", 0, s.tex));
+                return stamp(out.tex, s.w, s.h);
+            },
+            bwd: (target, [s], c) => {
+                const out = sb(s.w, s.h);
+                pass(DELUMA, out, x => {
+                    x.tex("u_t", 0, target.tex);
+                    x.tex("u_c", 1, c.tex);
+                });
+                return { updates: [stamp(out.tex, s.w, s.h)], complement: c };
+            },
+        });
+    }
+    /** 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, y, w, h) {
+        const xf = reader(x);
+        const yf = reader(y);
+        const wf = reader(w);
+        const hf = reader(h);
+        const sf = scratch();
+        const sb = scratch2();
+        const self = this;
+        return Canvas.lens(self, v => {
+            const cw = Math.max(1, wf() | 0);
+            const ch = Math.max(1, hf() | 0);
+            const out = sf(cw, ch);
+            pass(CROP_FWD, out, s => {
+                s.tex("u_s", 0, v.tex);
+                s.v2("u_off", xf() | 0, yf() | 0);
+                s.v2("u_csize", cw, ch);
+                s.v2("u_ssize", v.w, v.h);
+            });
+            return stamp(out.tex, cw, ch);
+        }, (target, v) => {
+            const out = sb(v.w, v.h, v.tex);
+            pass(CROP_BWD, out, s => {
+                s.tex("u_s", 0, v.tex);
+                s.tex("u_t", 1, target.tex);
+                s.v2("u_off", xf() | 0, yf() | 0);
+                s.v2("u_csize", target.w, target.h);
+                s.v2("u_ssize", v.w, v.h);
+            });
+            return stamp(out.tex, v.w, v.h);
+        });
+    }
+    /** 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) {
+        const f = Math.max(1, Math.floor(factor));
+        const dw = (n) => Math.max(1, Math.floor(n / f));
+        const sdF = scratch();
+        const sdR = scratch();
+        const suR = scratch();
+        const sc = scratch();
+        const suB = scratch();
+        const sb = scratch();
+        const down = (alloc, srcTex, sw, sh) => {
+            const small = alloc(dw(sw), dw(sh));
+            pass(BOXDOWN, small, x => {
+                x.tex("u_s", 0, srcTex);
+                x.i("u_f", f);
+                x.i2("u_ssize", sw, sh);
+            });
+            return small;
+        };
+        const residualOf = (s) => {
+            const small = down(sdR, s.tex, s.w, s.h);
+            const up = suR(s.w, s.h);
+            pass(UP, up, x => {
+                x.tex("u_small", 0, small.tex);
+                x.i("u_f", f);
+                x.i2("u_smallsize", small.w, small.h);
+            });
+            const res = sc(s.w, s.h);
+            pass(SUB, res, x => {
+                x.tex("u_a", 0, s.tex);
+                x.tex("u_b", 1, up.tex);
+            });
+            return res;
+        };
+        const self = this;
+        return Canvas.lens([self], {
+            init: ([s]) => residualOf(s),
+            step: ([s], c, external) => (external ? residualOf(s) : c),
+            fwd: ([s]) => {
+                const small = down(sdF, s.tex, s.w, s.h);
+                return stamp(small.tex, small.w, small.h);
+            },
+            bwd: (target, [s], c) => {
+                const up = suB(s.w, s.h);
+                pass(UP, up, x => {
+                    x.tex("u_small", 0, target.tex);
+                    x.i("u_f", f);
+                    x.i2("u_smallsize", target.w, target.h);
+                });
+                const out = sb(s.w, s.h);
+                pass(ADD, out, x => {
+                    x.tex("u_a", 0, up.tex);
+                    x.tex("u_b", 1, c.tex);
+                });
+                return { updates: [stamp(out.tex, s.w, s.h)], complement: c };
+            },
+        });
+    }
+    /** 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) {
+        const rf = reader(radius);
+        const fTmp = scratch();
+        const fOut = scratch();
+        const xa = scratch();
+        const xb = scratch();
+        const gTmp = scratch();
+        const est = scratch();
+        const ratio = scratch();
+        const corr = scratch();
+        return this.lens(v => {
+            const tmp = fTmp(v.w, v.h);
+            const out = fOut(v.w, v.h);
+            gauss(v.tex, v.w, v.h, rf(), tmp, out);
+            return stamp(out.tex, v.w, v.h);
+        }, (target, v) => {
+            const A = xa(v.w, v.h);
+            const B = xb(v.w, v.h);
+            let cur = v.tex === A.tex ? B : A;
+            let other = cur === A ? B : A;
+            copy(v.tex, cur);
+            const r = rf();
+            for (let it = 0; it < DECONV_ITERS; it++) {
+                const e = est(v.w, v.h);
+                gauss(cur.tex, v.w, v.h, r, gTmp(v.w, v.h), e);
+                const ra = ratio(v.w, v.h);
+                pass(RL_RATIO, ra, s => {
+                    s.tex("u_t", 0, target.tex);
+                    s.tex("u_est", 1, e.tex);
+                });
+                const co = corr(v.w, v.h);
+                gauss(ra.tex, v.w, v.h, r, gTmp(v.w, v.h), co);
+                pass(RL_MUL, other, s => {
+                    s.tex("u_x", 0, cur.tex);
+                    s.tex("u_c", 1, co.tex);
+                });
+                const t = cur;
+                cur = other;
+                other = t;
+            }
+            return stamp(cur.tex, v.w, v.h);
+        });
+    }
+    /** 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() {
+        const self = this;
+        const sb = scratch2();
+        return Color.lens(self, v => {
+            const [r, g, b, a] = reduceMean({ tex: v.tex, w: v.w, h: v.h });
+            return { r, g, b, a };
+        }, (target, v) => {
+            const [mr, mg, mb] = reduceMean({ tex: v.tex, w: v.w, h: v.h });
+            const out = sb(v.w, v.h, v.tex);
+            pass(SHIFT, out, s => {
+                s.tex("u_s", 0, v.tex);
+                s.v3("u_d", target.r - mr, target.g - mg, target.b - mb);
+            });
+            return stamp(out.tex, v.w, v.h);
+        });
+    }
+    /** 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) {
+        const tf = reader(threshold);
+        const self = this;
+        const xa = scratch();
+        const xb = scratch();
+        const meanLuma = (t, w, h) => {
+            const m = reduceMean({ tex: t, w, h });
+            return 0.299 * m[0] + 0.587 * m[1] + 0.114 * m[2];
+        };
+        return Bool.lens(self, v => meanLuma(v.tex, v.w, v.h) >= tf(), (target, v) => {
+            const t = tf();
+            const want = target ? t + 0.03 : t - 0.03;
+            const A = xa(v.w, v.h);
+            const B = xb(v.w, v.h);
+            let cur = v.tex === A.tex ? B : A;
+            let other = cur === A ? B : A;
+            copy(v.tex, cur);
+            for (let it = 0; it < 40; it++) {
+                const Y = meanLuma(cur.tex, v.w, v.h);
+                if (target ? Y >= t : Y < t)
+                    break;
+                const k = Y > 0.002 ? want / Y : target ? 2 : 0;
+                if (Math.abs(k - 1) < 1e-3)
+                    break;
+                pass(SCALE3, other, s => {
+                    s.tex("u_s", 0, cur.tex);
+                    s.f("u_k", k);
+                });
+                const tmp = cur;
+                cur = other;
+                other = tmp;
+            }
+            return stamp(cur.tex, v.w, v.h);
+        });
+    }
+    /** Dimensions `(w, h)` as a read-only `Vec`. */
+    get dimensions() {
+        return derived(this, "dimensions", Vec, v => ({ x: v.w, y: v.h }));
+    }
+    /** 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) {
+        const s = new Spring(this.value.w, this.value.h, opts);
+        s.seed(this.value.tex);
+        return s;
+    }
+}
+/** 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 function canvas(w, h, painter) {
+    const f = new Float32Array(w * h * 4);
+    if (painter !== undefined) {
+        let o = 0;
+        for (let y = 0; y < h; y++) {
+            for (let x = 0; x < w; x++) {
+                const [r, g, b, a] = painter(x, y);
+                f[o++] = r / 255;
+                f[o++] = g / 255;
+                f[o++] = b / 255;
+                f[o++] = a / 255;
+            }
+        }
+    }
+    return new Canvas(stamp(newTex(w, h, f), w, h));
+}

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

@@ -0,0 +1,49 @@
+import type { Easing } from "../../animation/index.js";
+import { type Tween } from "../anim.js";
+import { Cell, type Init, type Val, type Writable } from "../signal.js";
+import type { Linear, Pack } from "../traits.js";
+import { Num } from "./num.js";
+type V = {
+    r: number;
+    g: number;
+    b: number;
+    a: 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 in RGBA-space. */
+export declare const metric: (a: V, b: V) => number;
+export declare class Color 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 Color.traits;
+    constructor(v?: V);
+    add(b: Val<V>): this;
+    sub(b: Val<V>): this;
+    scale(k: Val<number>): this;
+    lerp(b: Val<V>, t: Val<number>): Color;
+    get r(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
+    get g(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
+    get b(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
+    get a(): this extends import("../index.js").WritableBrand ? Writable<Num> : Num;
+    get luminance(): Num;
+    get css(): Cell<string>;
+    /** Tween-builder, implied by the lerp trait. */
+    to(this: Writable<Color>, target: V, dur: Val<number>, ease?: Easing): Tween<V>;
+}
+/** Writable `Color` from RGB channels (alpha = 1). Each channel is a
+ *  literal `number` (lifted to a fresh seed) or an existing `Writable<Num>`
+ *  (identity passthrough). All-literal inputs take a fast path; mixed
+ *  inputs build a lens so channel-writes round-trip to source. */
+export declare function rgb(r: Init<Num>, g: Init<Num>, b: Init<Num>): Writable<Color>;
+/** Writable `Color` from RGBA channels. Same lift rule as `rgb`. */
+export declare function rgba(r: Init<Num>, g: Init<Num>, b: Init<Num>, a: Init<Num>): Writable<Color>;
+export {};

package/dist/core/values/color.js

@@ -0,0 +1,106 @@
+// color.ts — reactive RGBA color.
+//
+// Invertibles (`add`, `sub`, `scale`) return `: this` and ride on
+// `Cell#lens(fwd, bwd)`. Chained calls compose into a lens chain.
+import { tween } from "../anim.js";
+import { Cell, derive, lazy, reader, readNow } from "../signal.js";
+import { derived, field } from "../writable.js";
+import { Num, num } from "./num.js";
+export const add = (a, b) => ({ r: a.r + b.r, g: a.g + b.g, b: a.b + b.b, a: a.a + b.a });
+export const sub = (a, b) => ({ r: a.r - b.r, g: a.g - b.g, b: a.b - b.b, a: a.a - b.a });
+export const scale = (a, k) => ({ r: a.r * k, g: a.g * k, b: a.b * k, a: a.a * k });
+export const lerp = (a, b, t) => ({
+    r: a.r + (b.r - a.r) * t,
+    g: a.g + (b.g - a.g) * t,
+    b: a.b + (b.b - a.b) * t,
+    a: a.a + (b.a - a.a) * t,
+});
+export const equals = (a, b) => a === b || (a.r === b.r && a.g === b.g && a.b === b.b && a.a === b.a);
+/** L2 distance in RGBA-space. */
+export const metric = (a, b) => Math.hypot(a.r - b.r, a.g - b.g, a.b - b.b, a.a - b.a);
+const linearImpl = { add, sub, scale };
+const packImpl = {
+    dim: 4,
+    read: (v, a, o) => {
+        a[o] = v.r;
+        a[o + 1] = v.g;
+        a[o + 2] = v.b;
+        a[o + 3] = v.a;
+    },
+    write: (a, o) => ({ r: a[o], g: a[o + 1], b: a[o + 2], a: a[o + 3] }),
+};
+export class Color extends Cell {
+    static traits = {
+        linear: linearImpl,
+        lerp,
+        metric,
+        equals,
+        pack: packImpl,
+    };
+    constructor(v = { r: 0, g: 0, b: 0, a: 1 }) {
+        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()));
+    }
+    lerp(b, t) {
+        return Color.derive(() => lerp(this.value, readNow(b), readNow(t)));
+    }
+    get r() {
+        return field(this, "r", Num);
+    }
+    get g() {
+        return field(this, "g", Num);
+    }
+    get b() {
+        return field(this, "b", Num);
+    }
+    get a() {
+        return field(this, "a", Num);
+    }
+    get luminance() {
+        return derived(this, "luminance", Num, c => 0.299 * c.r + 0.587 * c.g + 0.114 * c.b);
+    }
+    get css() {
+        return lazy(this, "css", () => derive(() => {
+            const c = this.value;
+            const r = Math.round(c.r * 255);
+            const g = Math.round(c.g * 255);
+            const b = Math.round(c.b * 255);
+            return `rgba(${r}, ${g}, ${b}, ${c.a})`;
+        }));
+    }
+    /** Tween-builder, implied by the lerp trait. */
+    to(target, dur, ease) {
+        return tween(this, target, dur, ease);
+    }
+}
+/** Writable `Color` from RGB channels (alpha = 1). Each channel is a
+ *  literal `number` (lifted to a fresh seed) or an existing `Writable<Num>`
+ *  (identity passthrough). All-literal inputs take a fast path; mixed
+ *  inputs build a lens so channel-writes round-trip to source. */
+export function rgb(r, g, b) {
+    if (typeof r === "number" && typeof g === "number" && typeof b === "number") {
+        return new Color({ r, g, b, a: 1 });
+    }
+    return Color.lens([num(r), num(g), num(b)], ([r, g, b]) => ({ r, g, b, a: 1 }), target => [target.r, target.g, target.b]);
+}
+/** Writable `Color` from RGBA channels. Same lift rule as `rgb`. */
+export function rgba(r, g, b, a) {
+    if (typeof r === "number" &&
+        typeof g === "number" &&
+        typeof b === "number" &&
+        typeof a === "number") {
+        return new Color({ r, g, b, a });
+    }
+    return Color.lens([num(r), num(g), num(b), num(a)], ([r, g, b, a]) => ({ r, g, b, a }), target => [target.r, target.g, target.b, target.a]);
+}

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

@@ -0,0 +1,18 @@
+import { Cell, type Writable } from "../signal.js";
+import { Bool } from "./bool.js";
+export declare class Flags<K extends string> extends Cell<number> {
+    #private;
+    readonly names: readonly K[];
+    static traits: {
+        equals: (a: number, b: number) => boolean;
+    };
+    readonly _t: typeof Flags.traits;
+    constructor(names: readonly K[], v?: number);
+    /** Bit lens for `name`; set/clear round-trips through the packed mask.
+     *  Cached per name so repeated calls return the same lens. */
+    flag<F extends K>(name: F): Writable<Bool>;
+}
+/** Writable `Flags` from variadic bit names (bit `i` = the i-th name), or
+ *  from an object of name→default (keys are the bits in insertion order). */
+export declare function flags<const N extends readonly string[]>(...names: N): Writable<Flags<N[number]>>;
+export declare function flags<const R extends Record<string, boolean>>(defaults: R): Writable<Flags<keyof R & string>>;