@neoloopy/cld-canvas 0.1.0

package/dist/view/painter.js

@@ -0,0 +1,471 @@
+/**
+ * Canvas painter — renders a prepared scene (node boxes, curved edges, loop
+ * badges) with the app's visual language ported from
+ * `app/lib/painters/graph_painter.dart`. Pure: takes a 2D context + scene +
+ * camera + theme + interaction state and draws. Deferred flourishes (valence/CLA
+ * marks) are tracked in Status.md; the core CLD reading — node types, arc edges
+ * with polarity chips, R/B badges, the subsystem-link corner mark, and selection
+ * + live-edit highlight — is here. Per-node
+ * quantitative detail lives in the ƒx node-menu modal, not on the canvas.
+ */
+import { groupSwatch, swatchBorder, swatchFill, swatchInk, withAlpha } from "./theme";
+import { LoopType } from "../engine/types";
+const EDGE_WIDTH = [1.6, 2.5, 3.4];
+/**
+ * Canvas label font. The desktop app renders its canvas text in Helvetica Neue
+ * (`ThemeData.fontFamily` in `app/lib/main.dart`) at weight 600. A
+ * `var(--font-interface)` inside a canvas `font` string is NOT resolved by the
+ * 2D context — the weight silently falls back to 400 and the family to the
+ * system UI font — so the family and weight are spelled out concretely here to
+ * match the app pixel-for-pixel. The monospace badge font mirrors Dart's
+ * generic `'monospace'`.
+ */
+export const LABEL_FONT = '"Helvetica Neue", Helvetica, Arial, sans-serif';
+const MONO_FONT = "monospace";
+/** Matches the app's `letterSpacing: -0.1` on every canvas label. */
+export const LABEL_TRACKING = "-0.1px";
+/** Set canvas letter-spacing without depending on it being in the DOM lib. */
+function setLetterSpacing(ctx, v) {
+    ctx.letterSpacing = v;
+}
+export function paint(ctx, scene, camera, theme, ui) {
+    ctx.setTransform(ui.dpr, 0, 0, ui.dpr, 0, 0);
+    ctx.fillStyle = theme.paper;
+    ctx.fillRect(0, 0, ui.cssWidth, ui.cssHeight);
+    drawGrid(ctx, camera, theme, ui);
+    ctx.translate(camera.tx, camera.ty);
+    ctx.scale(camera.scale, camera.scale);
+    const hl = ui.loopHighlight;
+    for (const g of scene.edges) {
+        drawEdge(ctx, g, theme, g.id === ui.selectedEdgeId, hl, ui.flowPhase);
+    }
+    for (const n of scene.nodes) {
+        const box = scene.boxes.get(n.id);
+        if (box) {
+            drawNode(ctx, box, n, theme, n.id === ui.selectedNodeId, ui.liveNodeIds.has(n.id), hl ? !hl.nodeIds.has(n.id) : false, n.id === ui.selectedNodeId ? ui.pulsePhase : 0);
+        }
+    }
+    for (const lp of scene.loops) {
+        const c = scene.badges.get(lp.key);
+        if (c) {
+            drawBadge(ctx, c, scene.labels.get(lp.key) ?? "", lp.type, theme, lp.key === ui.selectedLoopKey, loopClockwise(lp.nodeIds, scene.boxes));
+        }
+    }
+    if (ui.linkPreview) {
+        const box = scene.boxes.get(ui.linkPreview.from);
+        if (box)
+            drawLinkPreview(ctx, { x: box.cx, y: box.cy }, ui.linkPreview.to, theme);
+    }
+}
+function drawGrid(ctx, camera, theme, ui) {
+    if (camera.scale < 0.25)
+        return;
+    const step = 32;
+    const tl = camera.toWorld(0, 0);
+    const br = camera.toWorld(ui.cssWidth, ui.cssHeight);
+    const x0 = Math.floor(tl.x / step) * step;
+    const y0 = Math.floor(tl.y / step) * step;
+    ctx.fillStyle = withAlpha(theme.line, theme.dark ? 0.6 : 0.9);
+    for (let wx = x0; wx <= br.x; wx += step) {
+        for (let wy = y0; wy <= br.y; wy += step) {
+            const p = camera.toScreen(wx, wy);
+            ctx.fillRect(p.x, p.y, 1, 1);
+        }
+    }
+}
+/** Append a rounded-rect sub-path to the current path (no beginPath). */
+function roundRectInto(ctx, x, y, w, h, r) {
+    const rr = Math.min(r, w / 2, h / 2);
+    ctx.moveTo(x + rr, y);
+    ctx.arcTo(x + w, y, x + w, y + h, rr);
+    ctx.arcTo(x + w, y + h, x, y + h, rr);
+    ctx.arcTo(x, y + h, x, y, rr);
+    ctx.arcTo(x, y, x + w, y, rr);
+    ctx.closePath();
+}
+function roundRect(ctx, x, y, w, h, r) {
+    ctx.beginPath();
+    roundRectInto(ctx, x, y, w, h, r);
+}
+function circle(ctx, c, r) {
+    ctx.beginPath();
+    ctx.arc(c.x, c.y, r, 0, Math.PI * 2);
+}
+function drawNode(ctx, box, node, theme, selected, live, dim, pulse) {
+    const x = box.cx - box.w / 2;
+    const y = box.cy - box.h / 2;
+    const r = box.type === "stock" ? 5 : box.h / 2;
+    ctx.save();
+    if (dim)
+        ctx.globalAlpha = 0.18;
+    if (selected) {
+        // Soft teal shade radiating from the rim — the app's `Motion.selectPulse`:
+        // a blurred ring (inflated stadium minus the node body) that swells and
+        // fades, drawn instead of any hard outline. Ported from the Dart
+        // MaskFilter.blur shade, so under reduced motion (pulse=0) it rests as a
+        // quiet glow hugging the node.
+        const grow = 6 + 26 * pulse;
+        ctx.save();
+        ctx.filter = "blur(5px)";
+        ctx.beginPath();
+        roundRectInto(ctx, x - grow, y - grow, box.w + grow * 2, box.h + grow * 2, (box.h + grow * 2) / 2);
+        roundRectInto(ctx, x, y, box.w, box.h, r);
+        ctx.fillStyle = withAlpha(theme.teal, 0.26 * (1 - pulse));
+        ctx.fill("evenodd");
+        ctx.restore();
+    }
+    if (live) {
+        roundRect(ctx, x - 11, y - 11, box.w + 22, box.h + 22, 22);
+        ctx.fillStyle = withAlpha(theme.live, 0.12);
+        ctx.fill();
+        roundRect(ctx, x - 6, y - 6, box.w + 12, box.h + 12, 18);
+        ctx.lineWidth = 2;
+        ctx.strokeStyle = theme.live;
+        ctx.stroke();
+    }
+    if (selected) {
+        // Thin steady ring at the connect radius marks the drag-to-link boundary
+        // (a solid hairline in the app, not a dashed ring).
+        const gap = 20;
+        roundRect(ctx, x - gap, y - gap, box.w + gap * 2, box.h + gap * 2, (box.h + gap * 2) / 2);
+        ctx.lineWidth = 1;
+        ctx.strokeStyle = withAlpha(theme.teal, 0.55);
+        ctx.stroke();
+    }
+    // Optional group tint: soft fill + ink + border, dodging the reserved R/B/live
+    // hues. Selection / live / loop colors render around it and still win. Ported
+    // from the app's `_paintNode` (stock keeps its graphite border regardless).
+    const swatch = groupSwatch(node.group);
+    roundRect(ctx, x, y, box.w, box.h, r);
+    ctx.fillStyle = swatch ? swatchFill(swatch, theme.dark) : theme.surface;
+    ctx.fill();
+    ctx.lineWidth = box.type === "stock" ? 1.6 : 1.3;
+    ctx.strokeStyle =
+        swatch && box.type !== "stock"
+            ? swatchBorder(swatch, theme.dark)
+            : box.type === "stock"
+                ? theme.graphite
+                : theme.line2;
+    ctx.stroke();
+    if (box.type === "stock") {
+        ctx.strokeStyle = theme.graphite;
+        ctx.lineWidth = 2.4;
+        for (const bx of [x + 1, x + box.w - 1]) {
+            ctx.beginPath();
+            ctx.moveTo(bx, y + 6);
+            ctx.lineTo(bx, y + box.h - 6);
+            ctx.stroke();
+        }
+    }
+    else if (box.type === "flow") {
+        drawValve(ctx, x + 13, box.cy, theme);
+    }
+    ctx.fillStyle = swatch ? swatchInk(swatch, theme.dark) : theme.ink;
+    ctx.font = "600 13px " + LABEL_FONT;
+    setLetterSpacing(ctx, LABEL_TRACKING);
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    const labelX = box.cx + (box.type === "flow" ? 8 : 0);
+    const maxW = box.w - (box.type === "flow" ? 26 : 14);
+    ctx.fillText(fitText(ctx, node.label, maxW), labelX, box.cy);
+    // Top-LEFT corner badge when the node drills into a child model (`subsystem`
+    // link set). Empty string is falsy in JS, so this mirrors Dart's
+    // `subsystem != null && subsystem.isNotEmpty`.
+    if (node.subsystem)
+        drawSubsystemMark(ctx, x + 10, y + 10, theme);
+    ctx.restore();
+}
+/**
+ * Stacked-sheets "layers" glyph marking that a node has a connected subsystem,
+ * in subtle theme ink (`ink2`) so it reads as "open me" while staying distinct
+ * from selection teal and loop R/B hues. Mirrors `_paintSubsystemMark` (which
+ * paints Material `Icons.layers`) in `app/lib/painters/graph_painter.dart`;
+ * hand-drawn here because a canvas 2D context can't resolve the Material icon
+ * font. Centered on (cx, cy) within a ~16px box, matching the app's
+ * `rect.left + 10, rect.top + 10` placement.
+ */
+function drawSubsystemMark(ctx, cx, cy, theme) {
+    ctx.strokeStyle = theme.ink2;
+    ctx.lineWidth = 1.4;
+    ctx.lineJoin = "round";
+    ctx.lineCap = "round";
+    // Front sheet: a rhombus filling the upper half of the icon box.
+    ctx.beginPath();
+    ctx.moveTo(cx, cy - 7);
+    ctx.lineTo(cx + 7, cy - 2.5);
+    ctx.lineTo(cx, cy + 2);
+    ctx.lineTo(cx - 7, cy - 2.5);
+    ctx.closePath();
+    ctx.stroke();
+    // Back sheet: a chevron peeking out beneath the front rhombus.
+    ctx.beginPath();
+    ctx.moveTo(cx - 7, cy + 0.5);
+    ctx.lineTo(cx, cy + 5);
+    ctx.lineTo(cx + 7, cy + 0.5);
+    ctx.stroke();
+}
+function drawValve(ctx, cx, cy, theme) {
+    // Stock-and-flow valve: two triangles meeting tip-to-tip (a bowtie ▷◁).
+    // Each sub-path must be closed so its outer base edge is drawn — otherwise
+    // the four spokes read as an ✕, not a valve (matches the Dart painter).
+    ctx.strokeStyle = theme.graphite;
+    ctx.lineWidth = 1.5;
+    ctx.lineJoin = "round";
+    ctx.beginPath();
+    ctx.moveTo(cx - 6, cy - 6);
+    ctx.lineTo(cx, cy);
+    ctx.lineTo(cx - 6, cy + 6);
+    ctx.closePath();
+    ctx.moveTo(cx + 6, cy - 6);
+    ctx.lineTo(cx, cy);
+    ctx.lineTo(cx + 6, cy + 6);
+    ctx.closePath();
+    ctx.stroke();
+}
+function drawEdge(ctx, g, theme, selected, hl, flowPhase) {
+    const inLoop = hl ? hl.edgeIds.has(g.id) : false;
+    const dim = hl ? !inLoop : false;
+    const loopColor = inLoop ? (hl?.type === LoopType.reinforcing ? theme.teal : theme.amber) : null;
+    ctx.save();
+    if (dim)
+        ctx.globalAlpha = 0.16;
+    const w = EDGE_WIDTH[Math.max(0, Math.min(2, g.link.weight ?? 0))];
+    ctx.lineCap = "round";
+    ctx.lineJoin = "round";
+    // Soft glow: a wide, faint band under a highlighted loop's edges (loop hue)
+    // or a selected edge (teal), so the active line pops off the canvas.
+    if (loopColor) {
+        tracePath(ctx, g.points);
+        ctx.lineWidth = 9;
+        ctx.strokeStyle = withAlpha(loopColor, 0.22);
+        ctx.stroke();
+    }
+    else if (selected) {
+        tracePath(ctx, g.points);
+        ctx.lineWidth = 7;
+        ctx.strokeStyle = withAlpha(theme.teal, 0.22);
+        ctx.stroke();
+    }
+    if (loopColor) {
+        // Highlighted loop edge: coloured marching ants ONLY (no continuous line
+        // under them), gaps left open over the glow — the app's `_drawMarching`.
+        tracePath(ctx, g.points);
+        ctx.lineWidth = 3.4;
+        ctx.strokeStyle = loopColor;
+        ctx.setLineDash([7, 6]);
+        ctx.lineDashOffset = -(flowPhase * 13);
+        ctx.stroke();
+        ctx.setLineDash([]);
+        ctx.lineDashOffset = 0;
+    }
+    else if (g.link.indirect) {
+        // Cosmetic dotted line (independent of polarity).
+        tracePath(ctx, g.points);
+        ctx.lineWidth = w;
+        ctx.strokeStyle = theme.graphite;
+        ctx.setLineDash([1, 5]);
+        ctx.stroke();
+        ctx.setLineDash([]);
+    }
+    else {
+        tracePath(ctx, g.points);
+        ctx.lineWidth = selected ? w + 0.8 : w;
+        ctx.strokeStyle = selected ? theme.teal : theme.graphite;
+        ctx.stroke();
+    }
+    const arrowColor = loopColor ?? theme.graphite;
+    drawArrow(ctx, g.arrowTip, g.arrowAngle, arrowColor);
+    if (g.link.delay)
+        drawDelay(ctx, g.delay, g.delayAngle, theme);
+    if (g.link.nonlinear)
+        drawNonlinear(ctx, g.nl, g.nlAngle, theme);
+    drawPolarityChip(ctx, g.mid, g.link.polarity, theme, selected);
+    ctx.restore();
+}
+function tracePath(ctx, pts) {
+    ctx.beginPath();
+    ctx.moveTo(pts[0].x, pts[0].y);
+    for (let i = 1; i < pts.length; i++)
+        ctx.lineTo(pts[i].x, pts[i].y);
+}
+function drawArrow(ctx, tip, angle, color) {
+    const size = 8;
+    const perp = size * 0.55;
+    const bx = tip.x - Math.cos(angle) * size;
+    const by = tip.y - Math.sin(angle) * size;
+    const nx = -Math.sin(angle);
+    const ny = Math.cos(angle);
+    ctx.beginPath();
+    ctx.moveTo(tip.x, tip.y);
+    ctx.lineTo(bx + nx * perp, by + ny * perp);
+    ctx.lineTo(bx - nx * perp, by - ny * perp);
+    ctx.closePath();
+    ctx.fillStyle = color;
+    ctx.fill();
+}
+function drawPolarityChip(ctx, c, polarity, theme, selected) {
+    circle(ctx, c, 9);
+    ctx.fillStyle = theme.surface;
+    ctx.fill();
+    ctx.lineWidth = 1.2;
+    ctx.strokeStyle = theme.line2;
+    ctx.stroke();
+    if (selected) {
+        circle(ctx, c, 13);
+        ctx.lineWidth = 2;
+        ctx.strokeStyle = theme.teal;
+        ctx.stroke();
+    }
+    ctx.fillStyle = theme.ink;
+    ctx.font = "700 15px " + LABEL_FONT;
+    setLetterSpacing(ctx, LABEL_TRACKING);
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    // En-dash (U+2013) for the negative glyph, matching the app.
+    ctx.fillText(polarity === "-" ? "–" : "+", c.x, c.y + 0.5);
+}
+function drawDelay(ctx, c, angle, theme) {
+    ctx.save();
+    ctx.translate(c.x, c.y);
+    // Delay ticks read as a "‖" CROSSING the edge: each tick perpendicular to the
+    // flow, the pair offset along it. Rotating by the tangent angle (not +90°)
+    // makes the two vertical bars stand across the line, not lie along it.
+    ctx.rotate(angle);
+    ctx.strokeStyle = theme.graphite;
+    ctx.lineWidth = 1.8;
+    ctx.lineCap = "round";
+    for (const dx of [-2.6, 2.6]) {
+        ctx.beginPath();
+        ctx.moveTo(dx, -6);
+        ctx.lineTo(dx, 6);
+        ctx.stroke();
+    }
+    ctx.restore();
+}
+function drawNonlinear(ctx, c, angle, theme) {
+    ctx.save();
+    ctx.translate(c.x, c.y);
+    ctx.rotate(angle + Math.PI / 2);
+    ctx.strokeStyle = theme.graphite;
+    ctx.lineWidth = 1.6;
+    ctx.lineCap = "round";
+    ctx.beginPath();
+    for (let x = -8; x <= 8; x += 1) {
+        const y = 3 * Math.sin((x / 6) * Math.PI * 2);
+        if (x === -8)
+            ctx.moveTo(x, y);
+        else
+            ctx.lineTo(x, y);
+    }
+    ctx.stroke();
+    ctx.restore();
+}
+/** True when the loop's member nodes wind clockwise on screen (y-down), so the
+ *  badge's rotor matches the real flow direction. Mirrors `loopClockwise` in the
+ *  app's CanvasController. */
+function loopClockwise(nodeIds, boxes) {
+    const order = [];
+    for (const id of nodeIds) {
+        if (order.length && order[order.length - 1] === id)
+            continue;
+        order.push(id);
+    }
+    if (order.length > 1 && order[0] === order[order.length - 1])
+        order.pop();
+    const poly = [];
+    for (const id of order) {
+        const b = boxes.get(id);
+        if (b)
+            poly.push({ x: b.cx, y: b.cy });
+    }
+    if (poly.length < 3)
+        return true;
+    let a = 0;
+    for (let i = 0; i < poly.length; i++) {
+        const p0 = poly[i];
+        const p1 = poly[(i + 1) % poly.length];
+        a += p0.x * p1.y - p1.x * p0.y;
+    }
+    return a > 0;
+}
+function drawBadge(ctx, c, label, type, theme, selected, clockwise) {
+    const r = selected ? 19 : 14;
+    const reinforcing = type === LoopType.reinforcing;
+    const color = reinforcing ? theme.tealInk : theme.amberInk;
+    const soft = reinforcing ? theme.tealSoft : theme.amberSoft;
+    if (selected) {
+        circle(ctx, c, r + 5);
+        ctx.lineWidth = 2;
+        ctx.strokeStyle = color;
+        ctx.stroke();
+    }
+    circle(ctx, c, r);
+    ctx.fillStyle = theme.surface;
+    ctx.fill();
+    circle(ctx, c, r);
+    ctx.fillStyle = withAlpha(soft, 0.6);
+    ctx.fill();
+    circle(ctx, c, r);
+    ctx.lineWidth = selected ? 1.8 : 1.4;
+    ctx.strokeStyle = color;
+    ctx.stroke();
+    // Circular loop arrow on the emphasised (selected) badge, sweeping in the
+    // loop's real flow direction — the app's `_loopBadge` rotor.
+    if (selected) {
+        const ar = 24;
+        const start = clockwise ? -Math.PI * 0.55 : Math.PI * 0.55;
+        const sweep = (clockwise ? 1 : -1) * Math.PI * 1.5;
+        const end = start + sweep;
+        ctx.beginPath();
+        ctx.arc(c.x, c.y, ar, start, end, sweep < 0);
+        ctx.lineWidth = 1.6;
+        ctx.lineCap = "round";
+        ctx.strokeStyle = color;
+        ctx.stroke();
+        const dir = clockwise ? 1 : -1;
+        const tan = { x: -Math.sin(end) * dir, y: Math.cos(end) * dir };
+        const perp = { x: -tan.y, y: tan.x };
+        const tip = { x: c.x + Math.cos(end) * ar, y: c.y + Math.sin(end) * ar };
+        const s = 5;
+        ctx.beginPath();
+        ctx.moveTo(tip.x, tip.y);
+        ctx.lineTo(tip.x - tan.x * s + perp.x * (s * 0.5), tip.y - tan.y * s + perp.y * (s * 0.5));
+        ctx.lineTo(tip.x - tan.x * s - perp.x * (s * 0.5), tip.y - tan.y * s - perp.y * (s * 0.5));
+        ctx.closePath();
+        ctx.fillStyle = color;
+        ctx.fill();
+    }
+    let size = selected ? 17 : 13;
+    if (label.length >= 3)
+        size -= 4;
+    else if (label.length === 2)
+        size -= 2;
+    ctx.fillStyle = color;
+    ctx.font = `800 ${size}px ${MONO_FONT}`;
+    setLetterSpacing(ctx, "0px");
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillText(label, c.x, c.y + 0.5);
+}
+function drawLinkPreview(ctx, from, to, theme) {
+    ctx.setLineDash([5, 4]);
+    ctx.lineWidth = 1.6;
+    ctx.strokeStyle = theme.teal;
+    ctx.beginPath();
+    ctx.moveTo(from.x, from.y);
+    ctx.lineTo(to.x, to.y);
+    ctx.stroke();
+    ctx.setLineDash([]);
+    circle(ctx, to, 4);
+    ctx.fillStyle = theme.teal;
+    ctx.fill();
+}
+function fitText(ctx, text, maxW) {
+    if (ctx.measureText(text).width <= maxW)
+        return text;
+    let s = text;
+    while (s.length > 1 && ctx.measureText(s + "…").width > maxW) {
+        s = s.slice(0, -1);
+    }
+    return s + "…";
+}

package/dist/view/sceneCache.d.ts

@@ -0,0 +1,61 @@
+/**
+ * SceneCache — builds the renderable `Scene` (node boxes, curved edges, loop
+ * badges) from a `GraphView`, and caches the heavy parts:
+ *
+ *  - **Label-width memo:** each distinct label is measured once (via the canvas
+ *    `measureText`), not per node per rebuild.
+ *  - **Dirty-tracking:** a rebuild is skipped — the previous `Scene` object is
+ *    returned by reference — when no geometric input changed (graph identity,
+ *    node positions/labels/types, link curvature, bow signs, badge overrides).
+ *    Idle renders and live-edit reloads stop rebuilding geometry needlessly; a
+ *    drag still rebuilds because the moved node changes the signature.
+ *
+ * Pure of canvas-view state: it owns only its measure context and memo, and is
+ * handed the graph + interaction caches to build from.
+ */
+import { Camera, Point } from "./camera";
+import { GraphView } from "../engine/engine";
+import { Scene } from "./painter";
+/** Measure a label's pixel width at the canvas label font. */
+export type LabelMeasurer = (label: string) => number;
+/**
+ * A canvas-backed label measurer matching the painter font (and the app's
+ * `NodeBox.sizeFor`). Falls back to the character-count estimate that
+ * `buildNodeBoxes` uses when there's no canvas (tests/headless), so box sizing
+ * stays deterministic either way.
+ */
+export declare function canvasLabelMeasurer(): LabelMeasurer;
+export declare class SceneCache {
+    private readonly rawMeasure;
+    private readonly widthMemo;
+    private scene;
+    private lastGraph;
+    private lastSig;
+    constructor(rawMeasure?: LabelMeasurer);
+    /** Measure a label width, memoized so each distinct label costs one measure. */
+    private measure;
+    /** Drop the label-width memo — call if the measure font/context ever changes. */
+    invalidateMeasurements(): void;
+    /** Force the next `build` to recompute even if the signature is unchanged. */
+    invalidate(): void;
+    /**
+     * Build (or reuse) the `Scene` for `graph`. Returns the previous `Scene` by
+     * reference when no geometric input moved; otherwise recomputes boxes, edges,
+     * and badges. Returns `null` for a null graph.
+     */
+    build(graph: GraphView | null, bowSigns: Map<string, number>, badgeOverrides: Map<string, Point>): Scene | null;
+    /**
+     * Fit `camera` to the current scene's node bounds. No-op (returns `false`)
+     * when there's no scene, no nodes, or a zero-sized viewport — the caller keeps
+     * the "fit only once" policy via its own camera-memory flag.
+     */
+    fit(camera: Camera, width: number, height: number): boolean;
+    /**
+     * A cheap signature of every input that changes box/edge/badge geometry:
+     * node id·position·type·label and each outgoing link's target·curvature (a bow
+     * drag mutates curvature in place), plus the frozen bow signs and the
+     * session-only badge overrides. Link polarity/flags don't affect geometry and
+     * arrive via a fresh graph (caught by the identity check), so they're omitted.
+     */
+    private signature;
+}

package/dist/view/sceneCache.js

@@ -0,0 +1,134 @@
+/**
+ * SceneCache — builds the renderable `Scene` (node boxes, curved edges, loop
+ * badges) from a `GraphView`, and caches the heavy parts:
+ *
+ *  - **Label-width memo:** each distinct label is measured once (via the canvas
+ *    `measureText`), not per node per rebuild.
+ *  - **Dirty-tracking:** a rebuild is skipped — the previous `Scene` object is
+ *    returned by reference — when no geometric input changed (graph identity,
+ *    node positions/labels/types, link curvature, bow signs, badge overrides).
+ *    Idle renders and live-edit reloads stop rebuilding geometry needlessly; a
+ *    drag still rebuilds because the moved node changes the signature.
+ *
+ * Pure of canvas-view state: it owns only its measure context and memo, and is
+ * handed the graph + interaction caches to build from.
+ */
+import { buildEdgeGeoms, buildNodeBoxes, collectEdges, computeBadges, nodeBounds, } from "./geometry";
+import { LABEL_FONT, LABEL_TRACKING } from "./painter";
+/**
+ * A canvas-backed label measurer matching the painter font (and the app's
+ * `NodeBox.sizeFor`). Falls back to the character-count estimate that
+ * `buildNodeBoxes` uses when there's no canvas (tests/headless), so box sizing
+ * stays deterministic either way.
+ */
+export function canvasLabelMeasurer() {
+    const ctx = typeof activeDocument !== "undefined"
+        ? activeDocument.createElement("canvas").getContext("2d")
+        : null;
+    if (!ctx)
+        return (label) => label.length * 7.2;
+    return (label) => {
+        ctx.font = "600 13px " + LABEL_FONT;
+        ctx.letterSpacing = LABEL_TRACKING;
+        return ctx.measureText(label).width;
+    };
+}
+export class SceneCache {
+    constructor(rawMeasure = canvasLabelMeasurer()) {
+        this.widthMemo = new Map();
+        this.scene = null;
+        this.lastGraph = null;
+        this.lastSig = null;
+        this.rawMeasure = rawMeasure;
+    }
+    /** Measure a label width, memoized so each distinct label costs one measure. */
+    measure(label) {
+        let w = this.widthMemo.get(label);
+        if (w === undefined) {
+            w = this.rawMeasure(label);
+            this.widthMemo.set(label, w);
+        }
+        return w;
+    }
+    /** Drop the label-width memo — call if the measure font/context ever changes. */
+    invalidateMeasurements() {
+        this.widthMemo.clear();
+    }
+    /** Force the next `build` to recompute even if the signature is unchanged. */
+    invalidate() {
+        this.lastGraph = null;
+        this.lastSig = null;
+    }
+    /**
+     * Build (or reuse) the `Scene` for `graph`. Returns the previous `Scene` by
+     * reference when no geometric input moved; otherwise recomputes boxes, edges,
+     * and badges. Returns `null` for a null graph.
+     */
+    build(graph, bowSigns, badgeOverrides) {
+        if (!graph) {
+            this.scene = null;
+            this.lastGraph = null;
+            this.lastSig = null;
+            return null;
+        }
+        const sig = this.signature(graph, bowSigns, badgeOverrides);
+        if (this.scene && graph === this.lastGraph && sig === this.lastSig)
+            return this.scene;
+        const boxes = buildNodeBoxes(graph.nodes, (s) => this.measure(s));
+        const edges = buildEdgeGeoms(collectEdges(graph.nodes), boxes, bowSigns);
+        const badges = computeBadges(graph.loops, boxes, badgeOverrides);
+        this.scene = {
+            nodes: graph.nodes,
+            boxes,
+            edges,
+            loops: graph.loops,
+            labels: graph.labels,
+            badges,
+        };
+        this.lastGraph = graph;
+        // `buildEdgeGeoms` freezes a bow sign for each previously-unseen edge *into*
+        // `bowSigns`, which feeds the signature — so the pre-build `sig` is already
+        // stale. Record the post-build signature instead, or the next unchanged call
+        // would needlessly rebuild once before the cache settles.
+        this.lastSig = this.signature(graph, bowSigns, badgeOverrides);
+        return this.scene;
+    }
+    /**
+     * Fit `camera` to the current scene's node bounds. No-op (returns `false`)
+     * when there's no scene, no nodes, or a zero-sized viewport — the caller keeps
+     * the "fit only once" policy via its own camera-memory flag.
+     */
+    fit(camera, width, height) {
+        if (!this.scene || this.scene.boxes.size === 0)
+            return false;
+        if (width === 0 || height === 0)
+            return false;
+        camera.fit(nodeBounds(this.scene.boxes), width, height);
+        return true;
+    }
+    /**
+     * A cheap signature of every input that changes box/edge/badge geometry:
+     * node id·position·type·label and each outgoing link's target·curvature (a bow
+     * drag mutates curvature in place), plus the frozen bow signs and the
+     * session-only badge overrides. Link polarity/flags don't affect geometry and
+     * arrive via a fresh graph (caught by the identity check), so they're omitted.
+     */
+    signature(graph, bowSigns, badgeOverrides) {
+        const parts = [];
+        for (const n of graph.nodes) {
+            parts.push(`${n.id}:${n.x}:${n.y}:${n.type}:${n.label}`);
+            for (const l of n.links)
+                parts.push(`>${l.to}:${l.curvature ?? ""}`);
+        }
+        parts.push("|");
+        for (const [k, v] of bowSigns)
+            parts.push(`${k}=${v}`);
+        parts.push("|");
+        for (const [k, p] of badgeOverrides)
+            parts.push(`${k}=${p.x},${p.y}`);
+        parts.push("|");
+        for (const l of graph.loops)
+            parts.push(l.key);
+        return parts.join(";");
+    }
+}