bireactive 0.2.0

package/dist/shapes/connect.d.ts

@@ -0,0 +1,16 @@
+import { type Val, type Vec } from "../core/index.js";
+import { Line, type LineOpts } from "./line.js";
+import { Shape } from "./shape.js";
+/** Line between two shapes/points; shape endpoints meet the analytic
+ *  boundary. */
+export declare function connect(a: Shape | Vec, b: Shape | Vec, opts?: LineOpts): Line;
+export interface ArrowOpts extends LineOpts {
+    /** Standoff between visible line and source/target. Default 4. */
+    gap?: Val<number>;
+}
+/** Arrow from `a` to `b`. Endpoints are adjusted so the round cap lines
+ *  up gap-ish past the source and the tip lands gap-ish before the
+ *  target (the marker extends past the line end). */
+export declare function arrow(a: Shape | Vec, b: Shape | Vec, opts?: ArrowOpts): Line;
+/** Idempotently install the arrow `<marker>` in this SVG's `<defs>`. */
+export declare function ensureArrowMarker(svg: SVGSVGElement): void;

package/dist/shapes/connect.js

@@ -0,0 +1,70 @@
+// Connectors. Uses `shape.boundary` so analytic edges work without
+// per-kind dispatch.
+import { derive, reader } from "../core/index.js";
+import { Line } from "./line.js";
+import { Shape, SVG_NS } from "./shape.js";
+import { tokens } from "./tokens.js";
+const ARROW_ID = "bireactive-arrow";
+const ARROW_W = 10;
+const ARROW_GAP_DEFAULT = 4;
+/** Line between two shapes/points; shape endpoints meet the analytic
+ *  boundary. */
+export function connect(a, b, opts) {
+    const aP = a instanceof Shape ? a.boundary(b instanceof Shape ? b.center : b) : a;
+    const bP = b instanceof Shape ? b.boundary(a instanceof Shape ? a.center : a) : b;
+    return new Line(aP, bP, opts);
+}
+/** Arrow from `a` to `b`. Endpoints are adjusted so the round cap lines
+ *  up gap-ish past the source and the tip lands gap-ish before the
+ *  target (the marker extends past the line end). */
+export function arrow(a, b, opts = {}) {
+    const aBase = a instanceof Shape ? a.boundary(b instanceof Shape ? b.center : b) : a;
+    const bBase = b instanceof Shape ? b.boundary(a instanceof Shape ? a.center : a) : b;
+    const gap = reader(opts.gap ?? ARROW_GAP_DEFAULT);
+    const dir = bBase.sub(aBase).normalize();
+    const aP = aBase.add(dir.scale(derive(() => gap() + tokens.weight)));
+    const bP = bBase.sub(dir.scale(derive(() => gap() + ARROW_W)));
+    const line = new Line(aP, bP, opts);
+    line.attr("marker-end", `url(#${ARROW_ID})`);
+    return line;
+}
+/** Idempotently install the arrow `<marker>` in this SVG's `<defs>`. */
+export function ensureArrowMarker(svg) {
+    let defs = svg.querySelector(":scope > defs");
+    if (!defs) {
+        defs = document.createElementNS(SVG_NS, "defs");
+        svg.insertBefore(defs, svg.firstChild);
+    }
+    if (defs.querySelector(`#${ARROW_ID}`))
+        return;
+    const marker = document.createElementNS(SVG_NS, "marker");
+    marker.id = ARROW_ID;
+    marker.setAttribute("markerWidth", "10");
+    marker.setAttribute("markerHeight", "7");
+    marker.setAttribute("refX", "0");
+    marker.setAttribute("refY", "3.5");
+    marker.setAttribute("orient", "auto");
+    marker.setAttribute("markerUnits", "userSpaceOnUse");
+    // Triangle with rounded vertices: trace each edge from its rounded
+    // start to its rounded end, then a short Q through each vertex.
+    const r = 0.9;
+    const v0 = { x: 0, y: 0 };
+    const v1 = { x: 10, y: 3.5 };
+    const v2 = { x: 0, y: 7 };
+    const corner = (v, prev, next) => {
+        const dPrev = Math.hypot(prev.x - v.x, prev.y - v.y);
+        const dNext = Math.hypot(next.x - v.x, next.y - v.y);
+        return {
+            approach: { x: v.x + (r * (prev.x - v.x)) / dPrev, y: v.y + (r * (prev.y - v.y)) / dPrev },
+            depart: { x: v.x + (r * (next.x - v.x)) / dNext, y: v.y + (r * (next.y - v.y)) / dNext },
+        };
+    };
+    const c0 = corner(v0, v2, v1);
+    const c1 = corner(v1, v0, v2);
+    const c2 = corner(v2, v1, v0);
+    const path = document.createElementNS(SVG_NS, "path");
+    path.setAttribute("d", `M ${c0.depart.x} ${c0.depart.y} L ${c1.approach.x} ${c1.approach.y} Q ${v1.x} ${v1.y} ${c1.depart.x} ${c1.depart.y} L ${c2.approach.x} ${c2.approach.y} Q ${v2.x} ${v2.y} ${c2.depart.x} ${c2.depart.y} L ${c0.approach.x} ${c0.approach.y} Q ${v0.x} ${v0.y} ${c0.depart.x} ${c0.depart.y} Z`);
+    path.setAttribute("fill", tokens.stroke);
+    marker.appendChild(path);
+    defs.appendChild(marker);
+}

package/dist/shapes/curve.d.ts

@@ -0,0 +1,60 @@
+import { type Cell, type Inner, type Val, Vec } from "../core/index.js";
+import { type CommonOpts, Shape } from "./shape.js";
+type V = Inner<Vec>;
+export interface CurveOpts extends CommonOpts {
+    closed?: boolean;
+}
+/** One curve piece: an SVG path command plus closed-form sampling by `s ∈ [0,1]`. */
+export type CurveSegment = {
+    kind: "line";
+    from: V;
+    to: V;
+} | {
+    kind: "ellipseArc";
+    /** Centre of the (possibly rotated) ellipse. */
+    center: V;
+    /** Semi-axes along the rotated frame. */
+    a: number;
+    b: number;
+    /** Rotation of the ellipse's major axis from +x, in radians. */
+    rotation: number;
+    /** Start / end parameter angles in the rotated frame, radians. */
+    a0: number;
+    a1: number;
+};
+/** Initialiser: static array (writable, fluent) or reactive builder
+ *  (computed, immutable). */
+export type CurveInit = readonly CurveSegment[] | (() => readonly CurveSegment[]);
+/** Piecewise curve with line and ellipse-arc segments. */
+export declare class Curve<O extends CurveOpts = CurveOpts> extends Shape<O> {
+    private readonly _segments;
+    /** True if segments are reactive (computed); fluent methods then no-op. */
+    private readonly _reactive;
+    readonly closed: boolean;
+    readonly length: Cell<number>;
+    constructor(init?: CurveInit, opts?: O);
+    /** Untracked snapshot of the segment list. */
+    get segs(): readonly CurveSegment[];
+    /** Segments for the dashed renderer: lines pass through, circular arcs
+     *  (`a ≈ b`, rotation ≈ 0) become native arcs, other ellipse arcs tessellate. */
+    segments(): import("./shape.js").Segment[];
+    /** Sample at `t ∈ [0, 1]` along arc length. */
+    pointAt(t: Val<number>): Vec;
+    /** Unit tangent at `t ∈ [0, 1]`. */
+    tangentAt(t: Val<number>): Vec;
+    private push;
+    private get last();
+    /** Append a line segment to `p`. */
+    to(p: V): this;
+    /** Append an elliptic-arc segment. `a0`, `a1` are parametric angles
+     *  in the ellipse's rotated frame. */
+    ellipseArc(center: V, a: number, b: number, rotation: number, a0: number, a1: number): this;
+}
+/** Start a piecewise curve: `curve()` fluent, `curve([segs])` explicit, or
+ *  `curve(() => segs)` reactive. */
+export declare function curve<const O extends CurveOpts>(init?: CurveInit, opts?: O): Curve<O>;
+/** A closed ellipse centred at `center` with semi-axes `a, b` and
+ *  optional `rotation` (radians). All four args accept `Val<>`, so the
+ *  ellipse re-renders when any input changes. */
+export declare function ellipse<O extends CurveOpts>(center: Val<V>, a: Val<number>, b: Val<number>, rotation?: Val<number>, opts?: O): Curve<O>;
+export {};

package/dist/shapes/curve.js

@@ -0,0 +1,285 @@
+// curve.ts — reactive piecewise curve with line + elliptic-arc segments.
+//
+// Segments render as SVG `d` chunks (`L`/`A`) and sample in closed form (arc
+// length exact for lines, 16-sample for ellipse arcs). Static mode takes an
+// array with fluent `.to`/`.ellipseArc`; reactive mode takes a builder fn.
+import { cell, derive, reader, readNow, Vec, } from "../core/index.js";
+import { Shape } from "./shape.js";
+const TAU = Math.PI * 2;
+const clamp01 = (v) => (v < 0 ? 0 : v > 1 ? 1 : v);
+const ARC_SAMPLES = 16;
+/** Endpoint of a segment at local s ∈ [0, 1]. Closed-form. */
+function sampleSegment(seg, s) {
+    if (seg.kind === "line") {
+        return {
+            x: seg.from.x + (seg.to.x - seg.from.x) * s,
+            y: seg.from.y + (seg.to.y - seg.from.y) * s,
+        };
+    }
+    const t = seg.a0 + (seg.a1 - seg.a0) * s;
+    const cosT = Math.cos(t);
+    const sinT = Math.sin(t);
+    const cosR = Math.cos(seg.rotation);
+    const sinR = Math.sin(seg.rotation);
+    return {
+        x: seg.center.x + seg.a * cosT * cosR - seg.b * sinT * sinR,
+        y: seg.center.y + seg.a * cosT * sinR + seg.b * sinT * cosR,
+    };
+}
+/** Unit tangent at local s. Closed-form derivative of `sampleSegment`. */
+function tangentSegment(seg, s) {
+    if (seg.kind === "line") {
+        const dx = seg.to.x - seg.from.x;
+        const dy = seg.to.y - seg.from.y;
+        const len = Math.hypot(dx, dy) || 1;
+        return { x: dx / len, y: dy / len };
+    }
+    const t = seg.a0 + (seg.a1 - seg.a0) * s;
+    const cosT = Math.cos(t);
+    const sinT = Math.sin(t);
+    const cosR = Math.cos(seg.rotation);
+    const sinR = Math.sin(seg.rotation);
+    let dx = -seg.a * sinT * cosR - seg.b * cosT * sinR;
+    let dy = -seg.a * sinT * sinR + seg.b * cosT * cosR;
+    const len = Math.hypot(dx, dy) || 1;
+    dx /= len;
+    dy /= len;
+    return { x: dx, y: dy };
+}
+/** Arc length of one segment. Exact for lines, 16-sample for ellipse arcs. */
+function segmentLength(seg) {
+    if (seg.kind === "line") {
+        return Math.hypot(seg.to.x - seg.from.x, seg.to.y - seg.from.y);
+    }
+    const N = ARC_SAMPLES;
+    let acc = 0;
+    let prev = sampleSegment(seg, 0);
+    for (let i = 1; i <= N; i++) {
+        const p = sampleSegment(seg, i / N);
+        acc += Math.hypot(p.x - prev.x, p.y - prev.y);
+        prev = p;
+    }
+    return acc;
+}
+/** SVG `d` chunk for one segment. Ellipse arcs spanning more than π
+ *  are split at the midpoint so SVG's `large-arc-flag` stays unambiguous. */
+function segmentD(seg) {
+    if (seg.kind === "line") {
+        return `L ${seg.to.x} ${seg.to.y}`;
+    }
+    const { a, b, rotation, a0, a1 } = seg;
+    const sweep = a1 >= a0 ? 1 : 0;
+    const span = Math.abs(a1 - a0);
+    const rotDeg = (rotation * 180) / Math.PI;
+    if (span <= Math.PI + 1e-9) {
+        const large = span > Math.PI ? 1 : 0;
+        const end = sampleSegment(seg, 1);
+        return `A ${a} ${b} ${rotDeg} ${large} ${sweep} ${end.x} ${end.y}`;
+    }
+    const mid = sampleSegment(seg, 0.5);
+    const end = sampleSegment(seg, 1);
+    return (`A ${a} ${b} ${rotDeg} 0 ${sweep} ${mid.x} ${mid.y} ` +
+        `A ${a} ${b} ${rotDeg} 0 ${sweep} ${end.x} ${end.y}`);
+}
+function segmentStart(seg) {
+    return seg.kind === "line" ? seg.from : sampleSegment(seg, 0);
+}
+/** Piecewise curve with line and ellipse-arc segments. */
+export class Curve extends Shape {
+    _segments;
+    /** True if segments are reactive (computed); fluent methods then no-op. */
+    _reactive;
+    closed;
+    length;
+    constructor(init = [], opts = {}) {
+        const reactive = typeof init === "function";
+        const segs = reactive
+            ? derive(init)
+            : cell(init);
+        const closed = opts.closed ?? false;
+        const cumLen = derive(() => {
+            const arr = segs.value;
+            const out = [0];
+            for (let i = 0; i < arr.length; i++) {
+                out.push(out[i] + segmentLength(arr[i]));
+            }
+            return out;
+        });
+        const total = derive(() => {
+            const c = cumLen.value;
+            return c[c.length - 1] ?? 0;
+        });
+        super("path", () => {
+            const arr = segs.value;
+            if (arr.length === 0)
+                return { x: 0, y: 0, w: 0, h: 0 };
+            let xMin = Number.POSITIVE_INFINITY, yMin = Number.POSITIVE_INFINITY, xMax = Number.NEGATIVE_INFINITY, yMax = Number.NEGATIVE_INFINITY;
+            for (const seg of arr) {
+                const N = seg.kind === "line" ? 1 : ARC_SAMPLES;
+                for (let i = 0; i <= N; i++) {
+                    const p = sampleSegment(seg, i / N);
+                    if (p.x < xMin)
+                        xMin = p.x;
+                    if (p.y < yMin)
+                        yMin = p.y;
+                    if (p.x > xMax)
+                        xMax = p.x;
+                    if (p.y > yMax)
+                        yMax = p.y;
+                }
+            }
+            return { x: xMin, y: yMin, w: xMax - xMin, h: yMax - yMin };
+        }, opts, {
+            origin: derive(() => {
+                const arr = segs.value;
+                return arr.length > 0 ? segmentStart(arr[0]) : { x: 0, y: 0 };
+            }),
+        });
+        this._segments = segs;
+        this._reactive = reactive;
+        this.closed = closed;
+        this.length = total;
+        this.stroke(opts, closed, {
+            d: derive(() => {
+                const arr = segs.value;
+                if (arr.length === 0)
+                    return "";
+                const start = segmentStart(arr[0]);
+                const parts = [`M ${start.x} ${start.y}`];
+                for (const seg of arr)
+                    parts.push(segmentD(seg));
+                if (closed)
+                    parts.push("Z");
+                return parts.join(" ");
+            }),
+        });
+    }
+    /** Untracked snapshot of the segment list. */
+    get segs() {
+        return this._segments.peek();
+    }
+    /** Segments for the dashed renderer: lines pass through, circular arcs
+     *  (`a ≈ b`, rotation ≈ 0) become native arcs, other ellipse arcs tessellate. */
+    segments() {
+        const arr = this._segments.value;
+        const out = [];
+        for (const seg of arr) {
+            if (seg.kind === "line") {
+                out.push({ type: "line", from: seg.from, to: seg.to });
+            }
+            else if (Math.abs(seg.a - seg.b) < 1e-6 && Math.abs(seg.rotation) < 1e-6) {
+                const cx = seg.center.x;
+                const cy = seg.center.y;
+                const r = seg.a;
+                const a0 = seg.a0;
+                const a1 = seg.a1;
+                out.push({
+                    type: "arc",
+                    cx: () => cx,
+                    cy: () => cy,
+                    r: () => r,
+                    a0: () => a0,
+                    a1: () => a1,
+                });
+            }
+            else {
+                const N = 64;
+                let prev = sampleSegment(seg, 0);
+                for (let i = 1; i <= N; i++) {
+                    const p = sampleSegment(seg, i / N);
+                    out.push({ type: "line", from: prev, to: p });
+                    prev = p;
+                }
+            }
+        }
+        return out;
+    }
+    /** Sample at `t ∈ [0, 1]` along arc length. */
+    pointAt(t) {
+        const ts = reader(t);
+        return Vec.derive(() => {
+            const arr = this._segments.value;
+            if (arr.length === 0)
+                return { x: 0, y: 0 };
+            const target = clamp01(ts()) * this.length.value;
+            let acc = 0;
+            for (const seg of arr) {
+                const segLen = segmentLength(seg);
+                if (target <= acc + segLen || seg === arr[arr.length - 1]) {
+                    const s = segLen > 0 ? (target - acc) / segLen : 0;
+                    return sampleSegment(seg, s);
+                }
+                acc += segLen;
+            }
+            return sampleSegment(arr[arr.length - 1], 1);
+        });
+    }
+    /** Unit tangent at `t ∈ [0, 1]`. */
+    tangentAt(t) {
+        const ts = reader(t);
+        return Vec.derive(() => {
+            const arr = this._segments.value;
+            if (arr.length === 0)
+                return { x: 1, y: 0 };
+            const target = clamp01(ts()) * this.length.value;
+            let acc = 0;
+            for (const seg of arr) {
+                const segLen = segmentLength(seg);
+                if (target <= acc + segLen || seg === arr[arr.length - 1]) {
+                    const s = segLen > 0 ? (target - acc) / segLen : 0;
+                    return tangentSegment(seg, s);
+                }
+                acc += segLen;
+            }
+            return tangentSegment(arr[arr.length - 1], 1);
+        });
+    }
+    push(seg) {
+        if (this._reactive) {
+            throw new Error("Curve(builder): fluent .to/.ellipseArc unavailable on reactive curves");
+        }
+        this._segments.value = [
+            ...this._segments.peek(),
+            seg,
+        ];
+        return this;
+    }
+    get last() {
+        const arr = this._segments.peek();
+        if (arr.length === 0)
+            return undefined;
+        return sampleSegment(arr[arr.length - 1], 1);
+    }
+    /** Append a line segment to `p`. */
+    to(p) {
+        const from = this.last ?? { x: 0, y: 0 };
+        return this.push({ kind: "line", from, to: p });
+    }
+    /** Append an elliptic-arc segment. `a0`, `a1` are parametric angles
+     *  in the ellipse's rotated frame. */
+    ellipseArc(center, a, b, rotation, a0, a1) {
+        return this.push({ kind: "ellipseArc", center, a, b, rotation, a0, a1 });
+    }
+}
+/** Start a piecewise curve: `curve()` fluent, `curve([segs])` explicit, or
+ *  `curve(() => segs)` reactive. */
+export function curve(init, opts) {
+    return new Curve(init ?? [], opts);
+}
+/** A closed ellipse centred at `center` with semi-axes `a, b` and
+ *  optional `rotation` (radians). All four args accept `Val<>`, so the
+ *  ellipse re-renders when any input changes. */
+export function ellipse(center, a, b, rotation = 0, opts) {
+    const o = { ...(opts ?? {}), closed: true };
+    return new Curve(() => [
+        {
+            kind: "ellipseArc",
+            center: readNow(center),
+            a: readNow(a),
+            b: readNow(b),
+            rotation: readNow(rotation),
+            a0: 0,
+            a1: TAU,
+        },
+    ], o);
+}

package/dist/shapes/dashed.d.ts

@@ -0,0 +1,16 @@
+import type { Segment } from "./shape.js";
+declare const TWO_PI: number;
+interface DashOpts {
+    closed?: boolean;
+    /** Target dash length. Default 4. */
+    dashSize?: number;
+    /** Target gap length. Default 3. */
+    gapSize?: number;
+    /** Optical compensation for round caps — extends each dash so the
+     *  visible length matches `dashSize`. */
+    capExtension?: number;
+}
+/** SVG path `d` for a dashed stroke through `segments` — one `M…L…/A…`
+ *  run per dash. Use with `<path fill="none">`. */
+export declare function dashedPath(segments: Segment[], opts?: DashOpts): string;
+export { TWO_PI };

package/dist/shapes/dashed.js

@@ -0,0 +1,142 @@
+// Pixel-perfect dashing via explicit `<path>` commands (sidesteps `stroke-dasharray` corner artifacts).
+const TWO_PI = Math.PI * 2;
+function evalSegments(segments) {
+    const out = [];
+    for (const s of segments) {
+        if (s.type === "line") {
+            const a = s.from;
+            const b = s.to;
+            const dx = b.x - a.x;
+            const dy = b.y - a.y;
+            const len = Math.hypot(dx, dy);
+            out.push({
+                type: "line",
+                length: len,
+                x1: a.x,
+                y1: a.y,
+                x2: b.x,
+                y2: b.y,
+            });
+        }
+        else {
+            const cx = s.cx(), cy = s.cy(), r = s.r(), a0 = s.a0(), a1 = s.a1();
+            out.push({
+                type: "arc",
+                length: Math.abs(a1 - a0) * r,
+                cx,
+                cy,
+                r,
+                a0,
+                a1,
+            });
+        }
+    }
+    return out;
+}
+function pointAt(s, t) {
+    if (s.type === "line") {
+        return { x: s.x1 + (s.x2 - s.x1) * t, y: s.y1 + (s.y2 - s.y1) * t };
+    }
+    const a = s.a0 + (s.a1 - s.a0) * t;
+    return { x: s.cx + s.r * Math.cos(a), y: s.cy + s.r * Math.sin(a) };
+}
+function computeDashGeom(length, closed, dashTarget, gapTarget) {
+    if (length <= 0)
+        return { dashSize: 0, gapSize: 0, N: 0 };
+    const period = dashTarget + gapTarget;
+    if (!closed) {
+        let N = Math.max(2, Math.round((length + gapTarget) / period));
+        let gap = (length - N * dashTarget) / (N - 1);
+        while (gap < 0 && N > 2) {
+            N--;
+            gap = (length - N * dashTarget) / (N - 1);
+        }
+        if (length < 2 * dashTarget || gap < 0) {
+            return { dashSize: length, gapSize: 0, N: 1 };
+        }
+        return { dashSize: dashTarget, gapSize: gap, N };
+    }
+    let N = Math.max(1, Math.round(length / period));
+    let gap = length / N - dashTarget;
+    while (gap < 0 && N > 1) {
+        N--;
+        gap = length / N - dashTarget;
+    }
+    if (gap < 0)
+        return { dashSize: length, gapSize: 0, N: 1 };
+    return { dashSize: dashTarget, gapSize: gap, N };
+}
+function pathFromTo(segs, start, end) {
+    let i = 0;
+    let pos = 0;
+    while (i < segs.length && pos + segs[i].length < start) {
+        pos += segs[i].length;
+        i++;
+    }
+    if (i >= segs.length)
+        return "";
+    const segLen = segs[i].length;
+    const tStart = segLen > 0 ? (start - pos) / segLen : 0;
+    const startPt = pointAt(segs[i], tStart);
+    let d = `M ${startPt.x},${startPt.y}`;
+    let remaining = end - start;
+    let curT = tStart;
+    while (remaining > 0 && i < segs.length) {
+        const seg = segs[i];
+        const lenLeft = (1 - curT) * seg.length;
+        if (remaining <= lenLeft) {
+            const endT = curT + (seg.length > 0 ? remaining / seg.length : 0);
+            const endPt = pointAt(seg, endT);
+            if (seg.type === "line") {
+                d += ` L ${endPt.x},${endPt.y}`;
+            }
+            else {
+                const sweepAngle = (seg.a1 - seg.a0) * (endT - curT);
+                const largeArc = Math.abs(sweepAngle) > Math.PI ? 1 : 0;
+                const sweepFlag = sweepAngle > 0 ? 1 : 0;
+                d += ` A ${seg.r},${seg.r} 0 ${largeArc} ${sweepFlag} ${endPt.x},${endPt.y}`;
+            }
+            return d;
+        }
+        const segEnd = pointAt(seg, 1);
+        if (seg.type === "line") {
+            d += ` L ${segEnd.x},${segEnd.y}`;
+        }
+        else {
+            const sweepAngle = (seg.a1 - seg.a0) * (1 - curT);
+            const largeArc = Math.abs(sweepAngle) > Math.PI ? 1 : 0;
+            const sweepFlag = sweepAngle > 0 ? 1 : 0;
+            d += ` A ${seg.r},${seg.r} 0 ${largeArc} ${sweepFlag} ${segEnd.x},${segEnd.y}`;
+        }
+        remaining -= lenLeft;
+        i++;
+        curT = 0;
+    }
+    return d;
+}
+/** SVG path `d` for a dashed stroke through `segments` — one `M…L…/A…`
+ *  run per dash. Use with `<path fill="none">`. */
+export function dashedPath(segments, opts = {}) {
+    const segs = evalSegments(segments);
+    if (segs.length === 0)
+        return "";
+    const closed = opts.closed ?? false;
+    const ext = opts.capExtension ?? 0;
+    const dashTarget = Math.max(0.001, (opts.dashSize ?? 4) - ext);
+    const gapTarget = (opts.gapSize ?? 3) + ext;
+    const total = segs.reduce((sum, s) => sum + s.length, 0);
+    const { dashSize, gapSize, N } = computeDashGeom(total, closed, dashTarget, gapTarget);
+    if (N === 0)
+        return "";
+    if (N === 1)
+        return pathFromTo(segs, 0, total);
+    const period = dashSize + gapSize;
+    const out = [];
+    for (let i = 0; i < N; i++) {
+        const start = i * period;
+        const end = start + dashSize;
+        out.push(pathFromTo(segs, start, end));
+    }
+    return out.join(" ");
+}
+export { TWO_PI };

package/dist/shapes/debug.d.ts

@@ -0,0 +1,43 @@
+import { Box, Vec } from "../core/index.js";
+import type { Path } from "./path.js";
+import { type AnyShape, Shape } from "./shape.js";
+/** debug.* — diagnostic overlays. All are `aside: true` so they don't
+ *  infect autofit. Drop in during development, remove when done. */
+export declare const debug: {
+    box: (b: Shape | Box) => import("./rect.js").Rect<{
+        aside: boolean;
+        opacity: number;
+        stroke: string;
+        fill: string;
+        thin: boolean;
+        dashed: boolean;
+    }>;
+    dot: (p: Vec | Shape | Box, r?: number) => import("./circle.js").Circle<{
+        readonly aside: boolean;
+        readonly opacity: number;
+        readonly fill: "var(--bireactive-debug, #c026d3)";
+        readonly stroke: "none";
+    }>;
+    origin: (s: Shape, size?: number) => Shape<{
+        readonly aside: true;
+        readonly opacity: 0.75;
+    }>;
+    anchors: (b: Shape | Box, r?: number) => Shape<{
+        readonly aside: true;
+        readonly opacity: 0.7;
+    }>;
+    connect: (a: AnyShape | Vec, b: AnyShape | Vec) => import("./line.js").Line<{
+        readonly aside: boolean;
+        readonly opacity: number;
+        readonly stroke: "var(--bireactive-debug, #c026d3)";
+        readonly thin: true;
+        readonly dashed: true;
+    }>;
+    distance: (a: AnyShape | Vec, b: AnyShape | Vec) => Shape<{
+        readonly aside: true;
+    }>;
+    path: (p: Path, ticks?: number) => Shape<{
+        readonly aside: true;
+        readonly opacity: 0.75;
+    }>;
+};