bireactive 0.2.0

package/dist/shapes/debug.js

@@ -0,0 +1,97 @@
+// debug.* — read-only diagnostic shapes that visualize layout state.
+import { Box, derive, transformBox, transformPoint, Vec } from "../core/index.js";
+import { circle } from "./circle.js";
+import { group } from "./group.js";
+import { label } from "./label.js";
+import { line } from "./line.js";
+import { rect } from "./rect.js";
+import { Shape } from "./shape.js";
+const COLOR = "var(--bireactive-debug, #c026d3)";
+const baseOpts = { aside: true, opacity: 0.6 };
+const outlineOpts = {
+    stroke: COLOR,
+    fill: "none",
+    thin: true,
+    dashed: true,
+    ...baseOpts,
+};
+/** Parent-frame Box. Shapes have their transform applied (so the
+ *  Box reflects the visual footprint); raw Boxes pass through. */
+function parentBox(b) {
+    if (b instanceof Shape) {
+        return Box.derive(() => transformBox(b.localFrame.value, b.box.value));
+    }
+    return b;
+}
+/** Dashed rect over a Shape's parent-frame box (or a raw Box). */
+const boxOutline = (b) => rect(parentBox(b), outlineOpts);
+/** Small filled dot at a point or a Box's / Shape's center. */
+const dot = (p, r = 2.5) => {
+    const at = p instanceof Vec ? p : p instanceof Shape ? p.center : p.center;
+    return circle(at, r, { fill: COLOR, stroke: "none", ...baseOpts });
+};
+/** Crosshair at a Shape's rotate/scale pivot, in parent frame. */
+const origin = (s, size = 8) => {
+    const pivot = Vec.derive(() => transformPoint(s.localFrame.value, s.origin.value));
+    const half = size / 2;
+    return group({ aside: true, opacity: 0.75 }, line(pivot.left(half), pivot.right(half), { stroke: COLOR, thin: true }), line(pivot.up(half), pivot.down(half), { stroke: COLOR, thin: true }), circle(pivot, 1.5, { fill: COLOR, stroke: "none" }));
+};
+/** Dots at the 9 standard anchor positions: corners, edge midpoints,
+ *  center. */
+const anchors = (b, r = 2.5) => {
+    const g = group({ aside: true, opacity: 0.7 });
+    for (const u of [0, 0.5, 1]) {
+        for (const v of [0, 0.5, 1]) {
+            g.add(circle(b.at(u, v), r, {
+                fill: COLOR,
+                stroke: "none",
+            }));
+        }
+    }
+    return g;
+};
+/** Faint dashed line between two shapes' (or points') centers. */
+const connect = (a, b) => {
+    const aP = a instanceof Shape ? a.center : a;
+    const bP = b instanceof Shape ? b.center : b;
+    return line(aP, bP, {
+        stroke: COLOR,
+        thin: true,
+        dashed: true,
+        ...baseOpts,
+    });
+};
+/** `connect(a, b)` + a live distance label at the midpoint. */
+const distance = (a, b) => {
+    const aP = a instanceof Shape ? a.center : a;
+    const bP = b instanceof Shape ? b.center : b;
+    const mid = aP.lerp(bP, 0.5);
+    const d = aP.distance(bP);
+    return group({ aside: true }, connect(aP, bP), label(mid.up(6), derive(() => d.value.toFixed(0)), { size: 10, opacity: 0.85 }));
+};
+/** Markers + tiny tangent ticks at evenly-spaced t along a Path. */
+const path = (p, ticks = 5) => {
+    const g = group({ aside: true, opacity: 0.75 });
+    for (let i = 0; i < ticks; i++) {
+        const t = ticks === 1 ? 0 : i / (ticks - 1);
+        const head = p.pointAt(t);
+        const tan = p.tangentAt(t);
+        const tip = Vec.derive(() => ({
+            x: head.value.x + tan.value.x * 6,
+            y: head.value.y + tan.value.y * 6,
+        }));
+        g.add(circle(head, 2.5, { fill: COLOR, stroke: "none" }), line(head, tip, { stroke: COLOR, thin: true }));
+    }
+    return g;
+};
+/** debug.* — diagnostic overlays. All are `aside: true` so they don't
+ *  infect autofit. Drop in during development, remove when done. */
+export const debug = {
+    box: boxOutline,
+    dot,
+    origin,
+    anchors,
+    connect,
+    distance,
+    path,
+};

package/dist/shapes/group.d.ts

@@ -0,0 +1,5 @@
+import { type AnyShape, Shape, type ShapeOpts } from "./shape.js";
+/** Empty container — bundles children under one transform / opacity.
+ *  Pass children after `opts` for JSX-ish nesting:
+ *  `group({ translate }, rect(...), label(...))`. */
+export declare function group<const O extends ShapeOpts>(opts?: O, ...children: AnyShape[]): Shape<O>;

package/dist/shapes/group.js

@@ -0,0 +1,10 @@
+import { Shape } from "./shape.js";
+/** Empty container — bundles children under one transform / opacity.
+ *  Pass children after `opts` for JSX-ish nesting:
+ *  `group({ translate }, rect(...), label(...))`. */
+export function group(opts, ...children) {
+    const g = new Shape(undefined, undefined, opts);
+    if (children.length > 0)
+        g.add(...children);
+    return g;
+}

package/dist/shapes/handle.d.ts

@@ -0,0 +1,32 @@
+import { type Cell, type Val, Vec, type Writable } from "../core/index.js";
+import { Circle } from "./circle.js";
+import type { Path } from "./path.js";
+import type { AnyShape, Has } from "./shape.js";
+export interface HandleOpts {
+    /** Handle radius (px). Default 6. */
+    r?: number;
+    /** Fill color. Default `--bireactive-handle`. Accepts reactive values. */
+    fill?: Val<string>;
+    /** CSS cursor on hover. Default `grab`. */
+    cursor?: string;
+}
+/** Draggable circular handle. A `Circle` plus a `dragging` signal (true
+ *  between pointerdown and pointerup/cancel) for coordinating animations. */
+export declare class Handle extends Circle {
+    readonly dragging: Writable<Cell<boolean>>;
+    constructor(target: Writable<Vec>, opts?: HandleOpts);
+}
+declare function handleFn(target: Writable<Vec>, opts?: HandleOpts): Handle;
+/** `handle(point)` is the atom; `.move`, `.centroid`, etc. are sugar. */
+export declare const handle: typeof handleFn & {
+    move: (shape: AnyShape & Has<"translate">, opts?: HandleOpts) => Handle;
+    anchor: (shape: AnyShape & Has<"translate">, u: number, v: number, opts?: HandleOpts) => Handle;
+    centroid: (...shapes: (AnyShape & Has<"translate">)[]) => Handle;
+    midpoint: (a: Writable<Vec>, b: Writable<Vec>, opts?: HandleOpts) => Handle;
+    rotate: (shape: AnyShape & Has<"rotate">, radius?: number, opts?: HandleOpts) => Handle;
+    scale: (shape: AnyShape & Has<"scale">, radius?: number, opts?: HandleOpts) => Handle;
+    tOnPath: (p: Path, t: Cell<number>, opts?: HandleOpts & {
+        samples?: number;
+    }) => Handle;
+};
+export {};

package/dist/shapes/handle.js

@@ -0,0 +1,88 @@
+// handle.* — writable derived shapes (draggable circles wired to a Vec).
+import { cell, centroidLens, midpointLens, polar as polarLens, Vec, } from "../core/index.js";
+import { Circle } from "./circle.js";
+import { drag } from "./interaction.js";
+const COLOR = "var(--bireactive-handle, #2563eb)";
+/** Draggable circular handle. A `Circle` plus a `dragging` signal (true
+ *  between pointerdown and pointerup/cancel) for coordinating animations. */
+export class Handle extends Circle {
+    dragging;
+    constructor(target, opts = {}) {
+        const circleOpts = {
+            fill: opts.fill ?? COLOR,
+            // Background-colored halo so the handle pops on either theme.
+            stroke: "var(--bg-color, white)",
+            strokeWidth: 2,
+            aside: true,
+        };
+        super(target, opts.r ?? 6, circleOpts);
+        this.el.style.cursor = opts.cursor ?? "grab";
+        this.dragging = cell(false);
+        this.disposers.push(drag(this, target, this.dragging));
+    }
+}
+function handleFn(target, opts = {}) {
+    return new Handle(target, opts);
+}
+/** Drag handle at the shape's center — drags translate the shape. */
+const move = (shape, opts) => handleFn(shape.center, opts);
+/** Drag handle at a specific anchor `(u, v)` of the shape — drag
+ *  translates the shape so that anchor lands at the pointer. */
+const anchor = (shape, u, v, opts) => handleFn(shape.at(u, v), opts);
+/** Drag handle at the centroid of N shapes' visual centers; drags translate
+ *  all shapes rigidly. Reads the centroid of visible positions (cf. `centroid`
+ *  in `shape.ts`, which works on translate deltas). */
+const centroidHandle = (...shapes) => handleFn(centroidLens(shapes.map(s => s.center)));
+/** Drag handle at the midpoint of two writable Points — drags both
+ *  along with it. */
+const midpoint = (a, b, opts) => handleFn(midpointLens(a, b), opts);
+/** Rotation knob orbiting the shape's center at `radius`; drag to write
+ *  `shape.rotate`. */
+const rotate = (shape, radius = 40, opts) => {
+    // `polar` with `circular` policy: c and r fixed, writes only update θ.
+    return handleFn(polarLens(shape.center, radius, shape.rotate, "circular"), {
+        cursor: "grab",
+        ...opts,
+    });
+};
+/** Uniform-scale knob along +x at `radius * scale.x`; drag x-distance writes
+ *  both scale axes. */
+const scaleHandle = (shape, radius = 40, opts) => {
+    // Reads center and scale; writes only scale.
+    const pos = Vec.lens([shape.center, shape.scale], vals => ({ x: vals[0].x + radius * vals[1].x, y: vals[0].y }), (target, vals) => {
+        const k = Math.max(0.05, Math.abs(target.x - vals[0].x) / radius);
+        return [undefined, { x: k, y: k }];
+    });
+    return handleFn(pos, { cursor: "ew-resize", ...opts });
+};
+/** Handle constrained to a Path: each drag projects the pointer onto the path
+ *  and sets `t` to the nearest parameter (re-projects, so animated paths work). */
+const tOnPath = (p, t, opts) => {
+    const N = opts?.samples ?? 64;
+    const project = (target) => {
+        let bestT = 0;
+        let bestD = Number.POSITIVE_INFINITY;
+        for (let i = 0; i <= N; i++) {
+            const tt = i / N;
+            const pp = p.pointAt(tt).value;
+            const d = (pp.x - target.x) ** 2 + (pp.y - target.y) ** 2;
+            if (d < bestD) {
+                bestD = d;
+                bestT = tt;
+            }
+        }
+        return bestT;
+    };
+    const pos = Vec.lens([t], ([tv]) => p.pointAt(tv).value, target => [project(target)]);
+    return handleFn(pos, opts);
+};
+/** `handle(point)` is the atom; `.move`, `.centroid`, etc. are sugar. */
+export const handle = Object.assign(handleFn, {
+    move,
+    anchor,
+    centroid: centroidHandle,
+    midpoint,
+    rotate,
+    scale: scaleHandle,
+    tOnPath,
+});

package/dist/shapes/index.d.ts

@@ -0,0 +1,23 @@
+export { AnnularSector, type AnnularSectorOpts, annularSector, } from "./annular-sector.js";
+export { type ButtonOpts, button } from "./button.js";
+export { assemble, orbit, splay, stagger, swap } from "./choreographers.js";
+export { Circle, type CircleOpts, circle } from "./circle.js";
+export { clipPath } from "./clip.js";
+export { type ArrowOpts, arrow, connect, ensureArrowMarker } from "./connect.js";
+export { Curve, type CurveOpts, type CurveSegment, curve, ellipse } from "./curve.js";
+export { dashedPath } from "./dashed.js";
+export { debug } from "./debug.js";
+export { group } from "./group.js";
+export { type HandleOpts, handle } from "./handle.js";
+export { cursor, drag, draggable, dragRotate, dragWithState, hoverSignal } from "./interaction.js";
+export { Label, type LabelOpts, label } from "./label.js";
+export { type ArrangeOpts, arrange, expand, grid, split } from "./layout.js";
+export { Line, type LineOpts, line } from "./line.js";
+export { type ForEachOptions, forEach } from "./list.js";
+export { type Mount, mount } from "./mount.js";
+export { Path, type PathDOpts, type PathOpts, path, pathD } from "./path.js";
+export { Rect, type RectOpts, rect } from "./rect.js";
+export { type AnimatableKey, type AnyShape, type CommonOpts, centroid, type Has, meanRotation, meanScale, type Segment, Shape, type ShapeOpts, SVG_NS, } from "./shape.js";
+export { type Content, Text, type TextPart, t } from "./text.js";
+export { type Tokens, tokens } from "./tokens.js";
+export { bounceIn, fadeIn, fadeOut, fadeUp, fadeUpOut, scaleIn, slideIn, slideOut, spinIn, zoomOut, } from "./transitions.js";

package/dist/shapes/index.js

@@ -0,0 +1,23 @@
+export { AnnularSector, annularSector, } from "./annular-sector.js";
+export { button } from "./button.js";
+export { assemble, orbit, splay, stagger, swap } from "./choreographers.js";
+export { Circle, circle } from "./circle.js";
+export { clipPath } from "./clip.js";
+export { arrow, connect, ensureArrowMarker } from "./connect.js";
+export { Curve, curve, ellipse } from "./curve.js";
+export { dashedPath } from "./dashed.js";
+export { debug } from "./debug.js";
+export { group } from "./group.js";
+export { handle } from "./handle.js";
+export { cursor, drag, draggable, dragRotate, dragWithState, hoverSignal } from "./interaction.js";
+export { Label, label } from "./label.js";
+export { arrange, expand, grid, split } from "./layout.js";
+export { Line, line } from "./line.js";
+export { forEach } from "./list.js";
+export { mount } from "./mount.js";
+export { Path, path, pathD } from "./path.js";
+export { Rect, rect } from "./rect.js";
+export { centroid, meanRotation, meanScale, Shape, SVG_NS, } from "./shape.js";
+export { Text, t } from "./text.js";
+export { tokens } from "./tokens.js";
+export { bounceIn, fadeIn, fadeOut, fadeUp, fadeUpOut, scaleIn, slideIn, slideOut, spinIn, zoomOut, } from "./transitions.js";

package/dist/shapes/interaction.d.ts

@@ -0,0 +1,32 @@
+import { type Cell, type Inner, type Num, Vec, type Writable } from "../core/index.js";
+import type { AnyShape } from "./shape.js";
+/** Set `sig` true/false from `mouseenter`/`mouseleave` on `shape`; returns a
+ *  disposer. Lower-level than `hover(el, marker)` — writes the signal directly. */
+export declare function hoverSignal(shape: AnyShape, sig: Writable<Cell<boolean>>): () => void;
+/** Reactive `Vec` tracking the page pointer in `shape`'s SVG-root frame, via
+ *  the shared window listener (N callers, one listener). `init` is returned
+ *  before the first `pointermove` to avoid a first-frame jolt to (0, 0). */
+export declare function cursor(shape: AnyShape, init?: Inner<Vec>): Vec;
+/** Wire `handle` for pointer-drag. Each pointermove while pressed
+ *  calls `onDrag(local)` with the pointer in `handle`'s local frame;
+ *  pointer-captured so drags survive leaving the handle. The optional
+ *  `onState(active)` callback fires `true` on pointerdown and `false`
+ *  on pointerup/cancel — `Handle` uses it to drive `.dragging`. */
+export declare function draggable(handle: AnyShape, onDrag: (local: Inner<Vec>) => void, onState?: (active: boolean) => void): () => void;
+/** Bind pointer drag on `shape` directly to a writable `Vec` (no handle dot);
+ *  returns a disposer. `target` is in the SVG-root frame and coords are read
+ *  via `toWorld`, so the grab offset survives bwd writes back through
+ *  `shape.translate`. Grab offset is captured on pointerdown; optional
+ *  `dragging` reports active state. Defaults `cursor` to `"grab"`. */
+export declare function drag(shape: AnyShape, target: Writable<Vec>, dragging?: Writable<Cell<boolean>>): () => void;
+/** Wrap a `drag(shape, target)` call and return a local `dragging`
+ *  Cell<boolean>. Sugar for "give me a drag handle that exposes its
+ *  own state." */
+export declare function dragWithState(shape: AnyShape, target: Writable<Vec>): {
+    dragging: Cell<boolean>;
+    dispose: () => void;
+};
+/** Drag-to-rotate about the shape's local origin: writes `angle` so the
+ *  grabbed point tracks the cursor (Δ = current − grab angle, shortest arc).
+ *  Returns a disposer. */
+export declare function dragRotate(shape: AnyShape, angle: Writable<Num>, dragging?: Writable<Cell<boolean>>): () => void;

package/dist/shapes/interaction.js

@@ -0,0 +1,187 @@
+// DOM input → signal-world bridges that bind to scene-graph shapes.
+import { cell, Vec } from "../core/index.js";
+// Shared page-pointer state for `cursor()`: one lazy window listener feeding
+// one signal. `null` until the first `pointermove`. Never disposed.
+let _clientPointer = null;
+function pageClientPointer() {
+    if (_clientPointer)
+        return _clientPointer;
+    const sig = cell(null);
+    window.addEventListener("pointermove", (e) => {
+        sig.value = { clientX: e.clientX, clientY: e.clientY };
+    });
+    _clientPointer = sig;
+    return sig;
+}
+const TAU = Math.PI * 2;
+const wrapToPi = (x) => x - TAU * Math.round(x / TAU);
+/** Stop a touch that lands on a draggable element from scrolling/zooming
+ *  the page. Set on both the `<g>` and its intrinsic (the actual hit
+ *  target on iOS Safari) so the gesture is owned by the drag, not the
+ *  page. Non-draggable scenery keeps `touch-action: auto`, so swiping
+ *  past a diagram still scrolls. */
+function ownTouchGesture(shape) {
+    shape.el.style.touchAction = "none";
+    if (shape.intrinsic)
+        shape.intrinsic.style.touchAction = "none";
+}
+/** iOS Safari ignores `touch-action` on inner SVG nodes, so a drag that
+ *  starts on a handle still pans the page. For the lifetime of an active
+ *  drag we also `preventDefault` a non-passive document `touchmove`,
+ *  which reliably suppresses scroll/zoom in every browser. Returns a
+ *  disposer that re-enables scrolling; call it on pointerup/cancel. */
+function blockPageScroll() {
+    const onMove = (e) => e.preventDefault();
+    document.addEventListener("touchmove", onMove, { passive: false });
+    return () => document.removeEventListener("touchmove", onMove);
+}
+/** Set `sig` true/false from `mouseenter`/`mouseleave` on `shape`; returns a
+ *  disposer. Lower-level than `hover(el, marker)` — writes the signal directly. */
+export function hoverSignal(shape, sig) {
+    const off1 = shape.on("mouseenter", () => {
+        sig.value = true;
+    });
+    const off2 = shape.on("mouseleave", () => {
+        sig.value = false;
+    });
+    return () => {
+        off1();
+        off2();
+    };
+}
+/** Reactive `Vec` tracking the page pointer in `shape`'s SVG-root frame, via
+ *  the shared window listener (N callers, one listener). `init` is returned
+ *  before the first `pointermove` to avoid a first-frame jolt to (0, 0). */
+export function cursor(shape, init) {
+    const cp = pageClientPointer();
+    const fallback = init ?? { x: 0, y: 0 };
+    return Vec.derive(cp, p => (p ? shape.toWorld(p) : fallback));
+}
+/** Wire `handle` for pointer-drag. Each pointermove while pressed
+ *  calls `onDrag(local)` with the pointer in `handle`'s local frame;
+ *  pointer-captured so drags survive leaving the handle. The optional
+ *  `onState(active)` callback fires `true` on pointerdown and `false`
+ *  on pointerup/cancel — `Handle` uses it to drive `.dragging`. */
+export function draggable(handle, onDrag, onState) {
+    let dragging = false;
+    let pointerId = -1;
+    let unblock = null;
+    ownTouchGesture(handle);
+    const offs = [];
+    offs.push(handle.on("pointerdown", e => {
+        const pe = e;
+        dragging = true;
+        pointerId = pe.pointerId;
+        handle.el.setPointerCapture(pointerId);
+        unblock = blockPageScroll();
+        onState?.(true);
+        onDrag(handle.toLocal(pe));
+    }));
+    offs.push(handle.on("pointermove", e => {
+        if (!dragging)
+            return;
+        onDrag(handle.toLocal(e));
+    }));
+    const stop = () => {
+        if (dragging && pointerId !== -1) {
+            try {
+                handle.el.releasePointerCapture(pointerId);
+            }
+            catch {
+                /* ok */
+            }
+        }
+        dragging = false;
+        pointerId = -1;
+        unblock?.();
+        unblock = null;
+        onState?.(false);
+    };
+    offs.push(handle.on("pointerup", stop));
+    offs.push(handle.on("pointercancel", stop));
+    return () => offs.forEach(d => d());
+}
+/** Bind pointer drag on `shape` directly to a writable `Vec` (no handle dot);
+ *  returns a disposer. `target` is in the SVG-root frame and coords are read
+ *  via `toWorld`, so the grab offset survives bwd writes back through
+ *  `shape.translate`. Grab offset is captured on pointerdown; optional
+ *  `dragging` reports active state. Defaults `cursor` to `"grab"`. */
+export function drag(shape, target, dragging) {
+    if (!shape.el.style.cursor)
+        shape.el.style.cursor = "grab";
+    ownTouchGesture(shape);
+    let dx = 0;
+    let dy = 0;
+    let pointerId = -1;
+    let unblock = null;
+    const offs = [];
+    offs.push(shape.on("pointerdown", e => {
+        const pe = e;
+        pointerId = pe.pointerId;
+        shape.el.setPointerCapture(pointerId);
+        unblock = blockPageScroll();
+        const world = shape.toWorld(pe);
+        const v = target.value;
+        dx = world.x - v.x;
+        dy = world.y - v.y;
+        if (dragging)
+            dragging.value = true;
+    }));
+    offs.push(shape.on("pointermove", e => {
+        if (pointerId === -1)
+            return;
+        const world = shape.toWorld(e);
+        target.value = { x: world.x - dx, y: world.y - dy };
+    }));
+    const stop = () => {
+        if (pointerId !== -1) {
+            try {
+                shape.el.releasePointerCapture(pointerId);
+            }
+            catch {
+                /* ok */
+            }
+            pointerId = -1;
+        }
+        unblock?.();
+        unblock = null;
+        if (dragging)
+            dragging.value = false;
+    };
+    offs.push(shape.on("pointerup", stop));
+    offs.push(shape.on("pointercancel", stop));
+    return () => offs.forEach(d => d());
+}
+/** Wrap a `drag(shape, target)` call and return a local `dragging`
+ *  Cell<boolean>. Sugar for "give me a drag handle that exposes its
+ *  own state." */
+export function dragWithState(shape, target) {
+    const dragging = cell(false);
+    const dispose = drag(shape, target, dragging);
+    return { dragging, dispose };
+}
+/** Drag-to-rotate about the shape's local origin: writes `angle` so the
+ *  grabbed point tracks the cursor (Δ = current − grab angle, shortest arc).
+ *  Returns a disposer. */
+export function dragRotate(shape, angle, dragging) {
+    if (!shape.el.style.cursor)
+        shape.el.style.cursor = "grab";
+    let grabAngle = 0;
+    const offDown = shape.on("pointerdown", e => {
+        const local = shape.toLocal(e);
+        grabAngle = Math.atan2(local.y, local.x);
+    });
+    const stop = draggable(shape, local => {
+        const currentAngle = Math.atan2(local.y, local.x);
+        const current = angle.peek();
+        angle.value = current + wrapToPi(currentAngle - grabAngle);
+    }, dragging
+        ? active => {
+            dragging.value = active;
+        }
+        : undefined);
+    return () => {
+        offDown();
+        stop();
+    };
+}

package/dist/shapes/label.d.ts

@@ -0,0 +1,20 @@
+import { type Inner, type Val, type Vec } from "../core/index.js";
+import { Shape, type ShapeOpts } from "./shape.js";
+import { type Content } from "./text.js";
+export interface LabelOpts extends ShapeOpts {
+    size?: Val<number>;
+    /** Bbox point that sits at `at` — `{0, 0}` = top-left, `{0.5, 0.5}`
+     *  (default) = center. See `Anchor` for named consts. */
+    align?: Inner<Vec>;
+    bold?: boolean;
+    /** Text color. Default `tokens.stroke` (i.e. `var(--text-color)`,
+     *  flips with dark mode). Accepts a reactive `Val<string>`. */
+    fill?: Val<string>;
+}
+export declare class Label<O extends LabelOpts = LabelOpts> extends Shape<O> {
+    /** The position the label attaches to (subject to `align`); distinct from
+     *  the inherited Box `center` / `at(u, v)`. */
+    readonly anchor: Vec;
+    constructor(anchor: Vec, content: Val<Content>, opts?: O);
+}
+export declare const label: <const O extends LabelOpts>(at: Vec, content: Val<Content>, opts?: O) => Label<O>;

package/dist/shapes/label.js

@@ -0,0 +1,42 @@
+import { Cell, cell, derive, Num } from "../core/index.js";
+import { Shape } from "./shape.js";
+import { flattenText, renderContent } from "./text.js";
+import { tokens } from "./tokens.js";
+const xAttr = (x) => (x <= 0.25 ? "start" : x >= 0.75 ? "end" : "middle");
+const yAttr = (y) => (y <= 0.25 ? "hanging" : y >= 0.75 ? "alphabetic" : "central");
+export class Label extends Shape {
+    /** The position the label attaches to (subject to `align`); distinct from
+     *  the inherited Box `center` / `at(u, v)`. */
+    anchor;
+    constructor(anchor, content, opts = {}) {
+        const contentSig = content instanceof Cell
+            ? content
+            : typeof content === "function"
+                ? derive(content)
+                : cell(content);
+        const sizeSig = Num.from(opts.size ?? tokens.fontSize);
+        const a = opts.align ?? { x: 0.5, y: 0.5 };
+        super("text", () => {
+            const text = flattenText(contentSig.value);
+            const fs = sizeSig.value;
+            const w = fs * Math.max(1, text.length) * tokens.charWidth;
+            return { x: anchor.x.value - a.x * w, y: anchor.y.value - a.y * fs, w, h: fs };
+        }, opts, 
+        // Pivot rotations on the anchor, not the bbox center.
+        { origin: anchor });
+        this.anchor = anchor;
+        this.attr("x", anchor.x);
+        this.attr("y", anchor.y);
+        this.attr("font-family", tokens.font);
+        this.attr("font-size", sizeSig);
+        this.attr("fill", opts.fill ?? tokens.stroke);
+        this.attr("text-anchor", xAttr(a.x));
+        this.attr("dominant-baseline", yAttr(a.y));
+        if (opts.bold)
+            this.attr("font-weight", 700);
+        this.effect(() => {
+            this.intrinsic.innerHTML = renderContent(contentSig.value);
+        });
+    }
+}
+export const label = (at, content, opts) => new Label(at, content, opts);

package/dist/shapes/layout.d.ts

@@ -0,0 +1,29 @@
+import { Box, type Val } from "../core/index.js";
+import type { Shape } from "./shape.js";
+export interface ArrangeOpts {
+    /** Spacing between adjacent bounding boxes. Default 0. */
+    gap?: number;
+    /** Cross-axis align vs the first shape: 0 top/left, 0.5 center,
+     *  1 bottom/right. Default 0. */
+    align?: number;
+}
+/** Lay out `shapes` in a row/column. First stays put; the rest bind
+ *  their `translate` reactively to sit `gap` past the previous.
+ *  Reflows on size or anchor change. */
+export declare function arrange(shapes: readonly Shape[], axis: "row" | "column", opts?: ArrangeOpts): void;
+/** Inflate a Box on each side by `by`. */
+export declare function expand(b: Box, by: Val<number>): Box;
+/** Split a Box along an axis into N reactive sub-Boxes.
+ *
+ *   split(b, "x", 3)              — 3 equal columns
+ *   split(b, "x", [3, 2, 2])      — weighted 3:2:2
+ *   split(b, "x", 3, { gap: 4 })  — 4px between
+ */
+export declare function split(source: Box, axis: "x" | "y", parts: number | number[], opts?: {
+    gap?: Val<number>;
+}): Box[];
+/** Two-axis split into a `rows × cols` grid (sugar over `split`).
+ *  Returns `[row][col]`. */
+export declare function grid(source: Box, rows: number, cols: number, opts?: {
+    gap?: Val<number>;
+}): Box[][];