bireactive 0.2.0

package/dist/propagators/relations.js

@@ -0,0 +1,343 @@
+// relations.ts — propagator combinators (the solver-role layer).
+//
+// Where lenses define values, these propagators impose relations
+// between cells that already exist for other reasons (handles,
+// animation targets, external signals). Each combinator returns
+// `Propagator`s for `p.add(...)`.
+//
+// Arithmetic combinators dispatch on the value class's `linear`
+// trait, so `add(a, b, c)` works for `Num`, `Vec`, `Box`, `Pose`,
+// anything `Linear<T>`.
+import { isCell, reader, requireLinear } from "../core/index.js";
+import { propagator } from "./propagator.js";
+/** `a + b = c`. Three propagators (any two derive the third). */
+export function add(a, b, c) {
+    const L = requireLinear(a);
+    return [
+        propagator([a, b], [c], () => {
+            c.value = L.add(a.value, b.value);
+        }),
+        propagator([a, c], [b], () => {
+            b.value = L.sub(c.value, a.value);
+        }),
+        propagator([b, c], [a], () => {
+            a.value = L.sub(c.value, b.value);
+        }),
+    ];
+}
+/** `a - b = c`. b-deriving propagator listed before a-deriving so
+ *  drag-on-c updates b first (matches "c changed because b changed"). */
+export function sub(a, b, c) {
+    const L = requireLinear(a);
+    return [
+        propagator([a, b], [c], () => {
+            c.value = L.sub(a.value, b.value);
+        }),
+        propagator([a, c], [b], () => {
+            b.value = L.sub(a.value, c.value);
+        }),
+        propagator([b, c], [a], () => {
+            a.value = L.add(b.value, c.value);
+        }),
+    ];
+}
+/** `(a + b) / 2 = m` (midpoint). Drag m → both a and b translate
+ *  by the delta; drag a or b → m re-derives. */
+export function mid(a, b, m) {
+    const L = requireLinear(a);
+    return [
+        propagator([a, b], [m], () => {
+            m.value = L.scale(L.add(a.value, b.value), 0.5);
+        }),
+        propagator([m], [a, b], () => {
+            const cur = L.scale(L.add(a.value, b.value), 0.5);
+            const delta = L.sub(m.value, cur);
+            a.value = L.add(a.value, delta);
+            b.value = L.add(b.value, delta);
+        }),
+    ];
+}
+/** Centroid of N values: `c = mean(...vs)`. Drag any vertex →
+ *  centroid follows; drag centroid → all vertices translate by the
+ *  delta (rigid translation of the cluster). */
+export function centroid(c, ...vs) {
+    if (vs.length === 0)
+        return [];
+    const L = requireLinear(c);
+    const inv = 1 / vs.length;
+    const computeMean = () => {
+        let acc = vs[0].value;
+        for (let i = 1; i < vs.length; i++)
+            acc = L.add(acc, vs[i].value);
+        return L.scale(acc, inv);
+    };
+    return [
+        propagator(vs, [c], () => {
+            c.value = computeMean();
+        }),
+        propagator([c], vs, () => {
+            const cur = computeMean();
+            const delta = L.sub(c.value, cur);
+            for (const v of vs)
+                v.value = L.add(v.value, delta);
+        }),
+    ];
+}
+/** `a * b = c` (scalar). Three propagators; division-by-zero skips
+ *  the inverse direction. */
+export function mul(a, b, c) {
+    return [
+        propagator([a, b], [c], () => {
+            c.value = a.value * b.value;
+        }),
+        propagator([a, c], [b], () => {
+            const av = a.value;
+            if (av !== 0)
+                b.value = c.value / av;
+        }),
+        propagator([b, c], [a], () => {
+            const bv = b.value;
+            if (bv !== 0)
+                a.value = c.value / bv;
+        }),
+    ];
+}
+/** `a / b = k` constant aspect ratio (scalar). */
+export function aspectRatio(a, b, k) {
+    return [
+        propagator([a], [b], () => {
+            b.value = a.value / k;
+        }),
+        propagator([b], [a], () => {
+            a.value = b.value * k;
+        }),
+    ];
+}
+/** `a₁ + a₂ + … + aₙ = total` (scalar). N+1 propagators: parts → total,
+ *  and total + (n-1 parts) → missing part for each i. */
+export function sum(parts, total) {
+    if (parts.length === 0)
+        return [];
+    if (parts.length === 1)
+        return eq(parts[0], total);
+    const props = [];
+    props.push(propagator(parts, [total], () => {
+        let s = 0;
+        for (const p of parts)
+            s += p.value;
+        total.value = s;
+    }));
+    for (let i = 0; i < parts.length; i++) {
+        const missing = parts[i];
+        const others = parts.filter((_, j) => j !== i);
+        props.push(propagator([total, ...others], [missing], () => {
+            let s = 0;
+            for (const o of others)
+                s += o.value;
+            missing.value = total.value - s;
+        }));
+    }
+    return props;
+}
+/** `a = b`. Bidirectional. Works for any value type. */
+export function eq(a, b) {
+    return [
+        propagator([a], [b], () => {
+            b.value = a.value;
+        }),
+        propagator([b], [a], () => {
+            a.value = b.value;
+        }),
+    ];
+}
+/** Pin a signal to a fixed value. Subscribes to its own target so
+ *  external writes that diverge from the constant get restored. */
+export function constant(s, v) {
+    return propagator([s], [s], () => {
+        s.value = v;
+    });
+}
+/** Variadic mutual equality: all cells share the same value. Drag
+ *  any one → others follow. N(N-1) propagators. */
+export function align(...cells) {
+    const props = [];
+    for (let i = 0; i < cells.length; i++) {
+        for (let j = 0; j < cells.length; j++) {
+            if (i === j)
+                continue;
+            const src = cells[i];
+            const dst = cells[j];
+            props.push(propagator([src], [dst], () => {
+                dst.value = src.value;
+            }));
+        }
+    }
+    return props;
+}
+/** Point at parameter `t ∈ [0,1]` along segment a → b.
+ *
+ *  Drag p (default): project p onto the segment, update t (clamped).
+ *  Drag p with `freeze: 'a'`: a stays, b moves to fit.
+ *  Drag p with `freeze: 'b'`: b stays, a moves to fit. */
+export function between(a, b, t, p, freeze) {
+    const props = [];
+    // Forward: p = a + t * (b - a).
+    props.push(propagator([a.x, a.y, b.x, b.y, t], [p.x, p.y], () => {
+        const tv = t.value;
+        p.x.value = a.x.value + tv * (b.x.value - a.x.value);
+        p.y.value = a.y.value + tv * (b.y.value - a.y.value);
+    }));
+    if (freeze === "b") {
+        props.push(propagator([p.x, p.y, t, b.x, b.y], [a.x, a.y], () => {
+            const tv = t.value;
+            if (tv === 1)
+                return;
+            a.x.value = (p.x.value - tv * b.x.value) / (1 - tv);
+            a.y.value = (p.y.value - tv * b.y.value) / (1 - tv);
+        }));
+    }
+    else if (freeze === "a") {
+        props.push(propagator([p.x, p.y, t, a.x, a.y], [b.x, b.y], () => {
+            const tv = t.value;
+            if (tv === 0)
+                return;
+            b.x.value = (p.x.value - (1 - tv) * a.x.value) / tv;
+            b.y.value = (p.y.value - (1 - tv) * a.y.value) / tv;
+        }));
+    }
+    else {
+        props.push(propagator([p.x, p.y, a.x, a.y, b.x, b.y], [t], () => {
+            const dx = b.x.value - a.x.value;
+            const dy = b.y.value - a.y.value;
+            const len2 = dx * dx + dy * dy;
+            if (len2 < 1e-12)
+                return;
+            const px = p.x.value - a.x.value;
+            const py = p.y.value - a.y.value;
+            t.value = Math.max(0, Math.min(1, (px * dx + py * dy) / len2));
+        }));
+    }
+    return props;
+}
+/** Keep `|a − b| = d`. Drag a → b moves along (b−a) to maintain
+ *  distance; drag b → symmetric. `d` may be a number, a Num signal,
+ *  a computed (e.g. `|p − q|` driven by other points), or a closure. */
+export function keepDistance(a, b, d) {
+    const dRead = reader(d);
+    const dDeps = isCell(d) ? [d] : [];
+    return [
+        propagator([a.x, a.y, ...dDeps], [b.x, b.y], () => {
+            const dx = b.x.value - a.x.value;
+            const dy = b.y.value - a.y.value;
+            const cur = Math.hypot(dx, dy);
+            if (cur < 1e-12)
+                return;
+            const k = dRead() / cur;
+            b.x.value = a.x.value + dx * k;
+            b.y.value = a.y.value + dy * k;
+        }),
+        propagator([b.x, b.y, ...dDeps], [a.x, a.y], () => {
+            const dx = a.x.value - b.x.value;
+            const dy = a.y.value - b.y.value;
+            const cur = Math.hypot(dx, dy);
+            if (cur < 1e-12)
+                return;
+            const k = dRead() / cur;
+            a.x.value = b.x.value + dx * k;
+            a.y.value = b.y.value + dy * k;
+        }),
+    ];
+}
+/** Project `p` onto the line through `a → b`. p sticks to the line. */
+export function onLine(p, a, b) {
+    return propagator([p.x, p.y, a.x, a.y, b.x, b.y], [p.x, p.y], () => {
+        const dx = b.x.value - a.x.value;
+        const dy = b.y.value - a.y.value;
+        const len2 = dx * dx + dy * dy;
+        if (len2 < 1e-12)
+            return;
+        const px = p.x.value - a.x.value;
+        const py = p.y.value - a.y.value;
+        const t = (px * dx + py * dy) / len2;
+        const newX = a.x.value + t * dx;
+        const newY = a.y.value + t * dy;
+        if (Math.abs(newX - p.x.value) > 1e-9 || Math.abs(newY - p.y.value) > 1e-9) {
+            p.x.value = newX;
+            p.y.value = newY;
+        }
+    });
+}
+/** Keep `p` on a circle of radius `r` around `c`. `r` may be a
+ *  number, a Num signal, a computed, or a closure. */
+export function onCircle(p, c, r) {
+    const rRead = reader(r);
+    const rDeps = isCell(r) ? [r] : [];
+    return propagator([p.x, p.y, c.x, c.y, ...rDeps], [p.x, p.y], () => {
+        const dx = p.x.value - c.x.value;
+        const dy = p.y.value - c.y.value;
+        const cur = Math.hypot(dx, dy);
+        if (cur < 1e-12)
+            return;
+        const k = rRead() / cur;
+        const newX = c.x.value + dx * k;
+        const newY = c.y.value + dy * k;
+        if (Math.abs(newX - p.x.value) > 1e-9 || Math.abs(newY - p.y.value) > 1e-9) {
+            p.x.value = newX;
+            p.y.value = newY;
+        }
+    });
+}
+/** Reflect `src` across the line through `a → b` to get `dst`.
+ *  Bidirectional. */
+export function reflect(src, a, b, dst) {
+    const reflectPt = (px, py, ax, ay, bx, by) => {
+        const dx = bx - ax;
+        const dy = by - ay;
+        const len2 = dx * dx + dy * dy;
+        if (len2 < 1e-12)
+            return [px, py];
+        const t = ((px - ax) * dx + (py - ay) * dy) / len2;
+        const cx = ax + t * dx;
+        const cy = ay + t * dy;
+        return [2 * cx - px, 2 * cy - py];
+    };
+    return [
+        propagator([src.x, src.y, a.x, a.y, b.x, b.y], [dst.x, dst.y], () => {
+            const [x, y] = reflectPt(src.x.value, src.y.value, a.x.value, a.y.value, b.x.value, b.y.value);
+            dst.x.value = x;
+            dst.y.value = y;
+        }),
+        propagator([dst.x, dst.y, a.x, a.y, b.x, b.y], [src.x, src.y], () => {
+            const [x, y] = reflectPt(dst.x.value, dst.y.value, a.x.value, a.y.value, b.x.value, b.y.value);
+            src.x.value = x;
+            src.y.value = y;
+        }),
+    ];
+}
+/** "These cells must contain DIFFERENT values." If any cell is a
+ *  singleton {v}, eliminate v from the others. */
+export function allDifferent(...cells) {
+    const props = [];
+    for (let i = 0; i < cells.length; i++) {
+        for (let j = 0; j < cells.length; j++) {
+            if (i === j)
+                continue;
+            const src = cells[i];
+            const dst = cells[j];
+            props.push(propagator([src], [dst], () => {
+                const sv = src.value;
+                if (sv.size !== 1)
+                    return;
+                const [only] = sv;
+                const dv = dst.value;
+                if (!dv.has(only))
+                    return;
+                const next = new Set(dv);
+                next.delete(only);
+                if (next.size !== dv.size)
+                    dst.value = next;
+            }));
+        }
+    }
+    return props;
+}

package/dist/shapes/annular-sector.d.ts

@@ -0,0 +1,15 @@
+import { type Cell, type Val, type Vec } from "../core/index.js";
+import { type CommonOpts, type Segment, Shape } from "./shape.js";
+export interface AnnularSectorOpts extends CommonOpts {
+}
+/** Pie wedge with a hole — between two radii swept across two angles. */
+export declare class AnnularSector<O extends AnnularSectorOpts = AnnularSectorOpts> extends Shape<O> {
+    readonly rOuter: Cell<number>;
+    readonly rInner: Cell<number>;
+    readonly a0: Cell<number>;
+    readonly a1: Cell<number>;
+    constructor(center: Vec, rOuter: Val<number>, rInner: Val<number>, a0: Val<number>, a1: Val<number>, opts?: O);
+    /** Local-frame segments, derived from the Box (center = the given center). */
+    segments(): Segment[];
+}
+export declare const annularSector: <const O extends AnnularSectorOpts>(center: Vec, rOuter: Val<number>, rInner: Val<number>, a0: Val<number>, a1: Val<number>, opts?: O) => AnnularSector<O>;

package/dist/shapes/annular-sector.js

@@ -0,0 +1,64 @@
+import { derive, Num } from "../core/index.js";
+import { Shape } from "./shape.js";
+/** Pie wedge with a hole — between two radii swept across two angles. */
+export class AnnularSector extends Shape {
+    rOuter;
+    rInner;
+    a0;
+    a1;
+    constructor(center, rOuter, rInner, a0, a1, opts = {}) {
+        const ro = Num.from(rOuter);
+        const ri = Num.from(rInner);
+        const a0s = Num.from(a0);
+        const a1s = Num.from(a1);
+        super("path", () => ({
+            x: center.x.value - ro.value,
+            y: center.y.value - ro.value,
+            w: 2 * ro.value,
+            h: 2 * ro.value,
+        }), opts, { origin: center });
+        this.rOuter = ro;
+        this.rInner = ri;
+        this.a0 = a0s;
+        this.a1 = a1s;
+        this.stroke(opts, true, {
+            d: derive(() => {
+                const cx = center.x.value;
+                const cy = center.y.value;
+                const _ro = ro.value;
+                const _ri = ri.value;
+                const _a0 = a0s.value;
+                const _a1 = a1s.value;
+                const span = Math.abs(_a1 - _a0);
+                const largeArc = span > Math.PI ? 1 : 0;
+                const sweep = _a1 > _a0 ? 1 : 0;
+                const back = sweep ? 0 : 1;
+                const o0x = cx + _ro * Math.cos(_a0), o0y = cy + _ro * Math.sin(_a0);
+                const o1x = cx + _ro * Math.cos(_a1), o1y = cy + _ro * Math.sin(_a1);
+                const i1x = cx + _ri * Math.cos(_a1), i1y = cy + _ri * Math.sin(_a1);
+                const i0x = cx + _ri * Math.cos(_a0), i0y = cy + _ri * Math.sin(_a0);
+                return `M ${o0x},${o0y} A ${_ro},${_ro} 0 ${largeArc} ${sweep} ${o1x},${o1y} L ${i1x},${i1y} A ${_ri},${_ri} 0 ${largeArc} ${back} ${i0x},${i0y} Z`;
+            }),
+        });
+    }
+    /** Local-frame segments, derived from the Box (center = the given center). */
+    segments() {
+        const cx = () => this.box.value.x + this.box.value.w / 2;
+        const cy = () => this.box.value.y + this.box.value.h / 2;
+        const ro = () => this.rOuter.value;
+        const ri = () => this.rInner.value;
+        const a0 = () => this.a0.value;
+        const a1 = () => this.a1.value;
+        const polar = (rfn, afn) => ({
+            x: cx() + rfn() * Math.cos(afn()),
+            y: cy() + rfn() * Math.sin(afn()),
+        });
+        return [
+            { type: "arc", cx, cy, r: ro, a0, a1 },
+            { type: "line", from: polar(ro, a1), to: polar(ri, a1) },
+            { type: "arc", cx, cy, r: ri, a0: a1, a1: a0 },
+            { type: "line", from: polar(ri, a0), to: polar(ro, a0) },
+        ];
+    }
+}
+export const annularSector = (center, rOuter, rInner, a0, a1, opts) => new AnnularSector(center, rOuter, rInner, a0, a1, opts);

package/dist/shapes/button.d.ts

@@ -0,0 +1,14 @@
+import { type Cell, type Val, type Vec, type Writable } from "../core/index.js";
+import type { AnyShape } from "./shape.js";
+import type { Content } from "./text.js";
+export interface ButtonOpts {
+    width?: number;
+    height?: number;
+    size?: Val<number>;
+    /** Externally-controlled hover signal — share across shapes if needed. */
+    hovered?: Writable<Cell<boolean>>;
+}
+/** A clickable, labelled region positioned at `pos` (top-left). The
+ *  `hovered` signal (auto-created) tracks pointer state — computed from
+ *  it to drive ancillary visuals. */
+export declare function button(pos: Vec, content: Val<Content>, onClick: () => void, opts?: ButtonOpts): AnyShape;

package/dist/shapes/button.js

@@ -0,0 +1,31 @@
+// Labelled, clickable region — group + tinted-rect + label, with
+// hover/click handlers wired.
+import { Anchor, cell, derive, Num, vec, } from "../core/index.js";
+import { group } from "./group.js";
+import { label } from "./label.js";
+import { rect } from "./rect.js";
+import { tokens } from "./tokens.js";
+/** A clickable, labelled region positioned at `pos` (top-left). The
+ *  `hovered` signal (auto-created) tracks pointer state — computed from
+ *  it to drive ancillary visuals. */
+export function button(pos, content, onClick, opts = {}) {
+    const w = opts.width ?? 80;
+    const h = opts.height ?? 26;
+    const size = Num.from(opts.size ?? 11);
+    const hovered = opts.hovered ?? cell(false);
+    // Hover tint behind the border so outline weight stays constant.
+    const g = group({ translate: pos }, rect(0, 0, w, h, {
+        fill: tokens.stroke,
+        opacity: derive(() => (hovered.value ? 0.08 : 0)),
+        stroke: "none",
+    }), rect(0, 0, w, h, { thin: true }), label(vec(w / 2, h / 2), content, { size, align: Anchor.Center }));
+    g.on("pointerover", () => {
+        hovered.value = true;
+    });
+    g.on("pointerout", () => {
+        hovered.value = false;
+    });
+    g.on("click", onClick);
+    g.el.style.cursor = "pointer";
+    return g;
+}

package/dist/shapes/choreographers.d.ts

@@ -0,0 +1,22 @@
+import { type Animator, type Easing, type Yieldable } from "../animation/index.js";
+import { type Inner, type Val, Vec } from "../core/index.js";
+import type { Has } from "./shape.js";
+/** Swap two shapes' positions over `sec`. */
+export declare function swap(a: Has<"translate">, b: Has<"translate">, sec?: number, ease?: Easing): Animator;
+/** Run `fn(item)` for each item, lagged by `stride` seconds. All in
+ *  parallel; completes when the longest child finishes:
+ *  `yield* stagger(0.05, shapes, s => fadeIn(s, 0.3))`. */
+export declare function stagger<S>(stride: number, items: readonly S[], fn: (item: S, i: number) => Yieldable): Animator;
+/** Distribute shapes radially around `center` at `radius`, evenly
+ *  spaced. Each shape tweens to its slot in parallel. */
+export declare function splay(center: Vec, radius: number, shapes: readonly Has<"translate">[], sec?: number, ease?: Easing): Animator;
+/** Tween each shape to its paired target (matched by index). */
+export declare function assemble(shapes: readonly Has<"translate">[], targets: readonly (Vec | Inner<Vec>)[], sec?: number, ease?: Easing): Animator;
+/** Continuous orbit around `center`, one revolution per `period` seconds.
+ *  Picks up each shape's current radius/angle (no jump). Never returns.
+ *  `rate` is a reactive multiplier — tween for ease-in/out; negative
+ *  reverses; 0 pauses. */
+export declare function orbit(center: Vec, shapes: readonly Has<"translate">[], opts?: {
+    period?: number;
+    rate?: Val<number>;
+}): Animator;

package/dist/shapes/choreographers.js

@@ -0,0 +1,69 @@
+// Multi-shape recipes. `swap`/`splay`/`assemble`/`stagger` are bounded
+// (yield-array compositions over `.to(...)`); `orbit` is continuous (a
+// `drive` step over N translates). For rigid group translate, reach for
+// `centroid(...shapes).to(...)` instead.
+import { drive } from "../animation/index.js";
+import { reader, Vec } from "../core/index.js";
+/** Swap two shapes' positions over `sec`. */
+export function* swap(a, b, sec = 0.5, ease) {
+    const av = a.translate.peek();
+    const bv = b.translate.peek();
+    yield [a.translate.to(bv, sec, ease), b.translate.to(av, sec, ease)];
+}
+/** Run `fn(item)` for each item, lagged by `stride` seconds. All in
+ *  parallel; completes when the longest child finishes:
+ *  `yield* stagger(0.05, shapes, s => fadeIn(s, 0.3))`. */
+export function* stagger(stride, items, fn) {
+    yield items.map((item, i) => (function* () {
+        yield i * stride;
+        yield fn(item, i);
+    })());
+}
+/** Distribute shapes radially around `center` at `radius`, evenly
+ *  spaced. Each shape tweens to its slot in parallel. */
+export function* splay(center, radius, shapes, sec = 0.5, ease) {
+    const c = center.value;
+    const N = shapes.length;
+    yield shapes.map((s, i) => {
+        // Start at top (-π/2) so first shape sits straight up; clockwise
+        // — natural reading order for left-to-right layouts above.
+        const angle = (i / N) * Math.PI * 2 - Math.PI / 2;
+        return s.translate.to({ x: c.x + radius * Math.cos(angle), y: c.y + radius * Math.sin(angle) }, sec, ease);
+    });
+}
+/** Tween each shape to its paired target (matched by index). */
+export function* assemble(shapes, targets, sec = 0.5, ease) {
+    yield shapes.map((s, i) => {
+        const t = targets[i];
+        return s.translate.to(t instanceof Vec ? t.value : t, sec, ease);
+    });
+}
+/** Continuous orbit around `center`, one revolution per `period` seconds.
+ *  Picks up each shape's current radius/angle (no jump). Never returns.
+ *  `rate` is a reactive multiplier — tween for ease-in/out; negative
+ *  reverses; 0 pauses. */
+export function orbit(center, shapes, opts = {}) {
+    const period = opts.period ?? 4;
+    const rateFn = reader(opts.rate ?? 1);
+    const omega = (2 * Math.PI) / period;
+    const N = shapes.length;
+    const c0 = center.value;
+    const init = shapes.map(sh => {
+        const v = sh.translate.peek();
+        const dx = v.x - c0.x;
+        const dy = v.y - c0.y;
+        return { angle: Math.atan2(dy, dx), radius: Math.hypot(dx, dy) };
+    });
+    let t = 0;
+    return drive(tick => {
+        t += tick.dt * rateFn();
+        const c = center.value;
+        for (let i = 0; i < N; i++) {
+            const angle = init[i].angle + omega * t;
+            shapes[i].translate.value = {
+                x: c.x + init[i].radius * Math.cos(angle),
+                y: c.y + init[i].radius * Math.sin(angle),
+            };
+        }
+    });
+}

package/dist/shapes/circle.d.ts

@@ -0,0 +1,17 @@
+import { Num, type Val, Vec } from "../core/index.js";
+import { type CommonOpts, type Segment, Shape } from "./shape.js";
+export interface CircleOpts extends CommonOpts {
+}
+export declare class Circle<O extends CircleOpts = CircleOpts> extends Shape<O> {
+    readonly radius: Num;
+    constructor(center: Vec, radius: Val<number>, opts?: O);
+    /** Point on perimeter at angle θ (radians, y-down). */
+    atAngle(angle: Val<number>): Vec;
+    /** Unit tangent at angle θ. */
+    tangentAt(angle: Val<number>): Vec;
+    boundary(toward: Vec): Vec;
+    /** Two half-arcs (each span ≤ π, so `largeArc` stays unambiguous), in
+     *  local frame — derived from the Box, not parent-frame `this.center`. */
+    segments(): Segment[];
+}
+export declare const circle: <const O extends CircleOpts>(at: Vec, r: Val<number>, opts?: O) => Circle<O>;

package/dist/shapes/circle.js

@@ -0,0 +1,57 @@
+import { Num, reader, Vec } from "../core/index.js";
+import { TWO_PI } from "./dashed.js";
+import { Shape } from "./shape.js";
+export class Circle extends Shape {
+    radius;
+    constructor(center, radius, opts = {}) {
+        const r = Num.from(radius);
+        super(opts.dashed ? "path" : "circle", () => ({
+            x: center.x.value - r.value,
+            y: center.y.value - r.value,
+            w: 2 * r.value,
+            h: 2 * r.value,
+        }), opts, { origin: center });
+        this.radius = r;
+        this.stroke(opts, true, { cx: center.x, cy: center.y, r });
+    }
+    /** Point on perimeter at angle θ (radians, y-down). */
+    atAngle(angle) {
+        const a = reader(angle);
+        return Vec.derive(() => ({
+            x: this.center.x.value + this.radius.value * Math.cos(a()),
+            y: this.center.y.value + this.radius.value * Math.sin(a()),
+        }));
+    }
+    /** Unit tangent at angle θ. */
+    tangentAt(angle) {
+        const a = reader(angle);
+        return Vec.derive(() => ({ x: -Math.sin(a()), y: Math.cos(a()) }));
+    }
+    boundary(toward) {
+        return Vec.derive(() => {
+            const t = toward.value;
+            const c = this.center.value;
+            const sc = this.scale.value;
+            // Boundary tracks the visual radius so pulses scale it; for
+            // non-uniform scale, approximate as a circle of the larger axis.
+            const r = this.radius.value * Math.max(sc.x, sc.y);
+            const len = Math.hypot(t.x - c.x, t.y - c.y) || 1;
+            return {
+                x: c.x + ((t.x - c.x) / len) * r,
+                y: c.y + ((t.y - c.y) / len) * r,
+            };
+        });
+    }
+    /** Two half-arcs (each span ≤ π, so `largeArc` stays unambiguous), in
+     *  local frame — derived from the Box, not parent-frame `this.center`. */
+    segments() {
+        const cx = () => this.box.value.x + this.box.value.w / 2;
+        const cy = () => this.box.value.y + this.box.value.h / 2;
+        const r = () => this.radius.value;
+        return [
+            { type: "arc", cx, cy, r, a0: () => 0, a1: () => Math.PI },
+            { type: "arc", cx, cy, r, a0: () => Math.PI, a1: () => TWO_PI },
+        ];
+    }
+}
+export const circle = (at, r, opts) => new Circle(at, r, opts);

package/dist/shapes/clip.d.ts

@@ -0,0 +1,5 @@
+import { type Shape } from "./shape.js";
+/** Install a `<clipPath>` mirroring `shape` and return a `url(#id)`
+ *  for use with the CSS `clip-path` property. `shape` must already be
+ *  mounted in an SVG (the parent SVG is found via `ownerSVGElement`). */
+export declare function clipPath(shape: Shape): string;

package/dist/shapes/clip.js

@@ -0,0 +1,31 @@
+// `<clipPath>` mirroring a shape's geometry via `<use href>`, so the
+// clip follows the source reactively without copying attributes.
+import { SVG_NS } from "./shape.js";
+let nextId = 0;
+function ensureDefs(svg) {
+    let defs = svg.querySelector(":scope > defs");
+    if (!defs) {
+        defs = document.createElementNS(SVG_NS, "defs");
+        svg.insertBefore(defs, svg.firstChild);
+    }
+    return defs;
+}
+/** Install a `<clipPath>` mirroring `shape` and return a `url(#id)`
+ *  for use with the CSS `clip-path` property. `shape` must already be
+ *  mounted in an SVG (the parent SVG is found via `ownerSVGElement`). */
+export function clipPath(shape) {
+    const target = shape.intrinsic ?? shape.el;
+    const svg = target.ownerSVGElement;
+    if (!svg)
+        throw new Error("clipPath: shape not yet mounted in an SVG");
+    if (!target.id)
+        target.id = `clip-target-${nextId++}`;
+    const id = `clip-${nextId++}`;
+    const cp = document.createElementNS(SVG_NS, "clipPath");
+    cp.id = id;
+    const use = document.createElementNS(SVG_NS, "use");
+    use.setAttribute("href", `#${target.id}`);
+    cp.appendChild(use);
+    ensureDefs(svg).appendChild(cp);
+    return `url(#${id})`;
+}