@fluixi/devtools 0.2.0-alpha.1 → 0.2.0-alpha.3

package/dist/graph-view.js

@@ -1,11 +1,82 @@
+import { shortenPath } from './path.js';
+import { pluginBadge } from './plugin.js';
+import { kindRules } from './palette.js';
+import { inPageOrder } from './tree.js';
 const SVGNS = 'http://www.w3.org/2000/svg';
 const COL = 200;
 const ROW = 92;
 const NW = 132;
-const NH = 56;
+/** file.ts:12, the path's tail only. The full one is for an inspector with room for it. */
+/**
+ * The location a card shows.
+ *
+ * `source` is where the compiler marked it. A node the compiler never saw, meaning anything
+ * the framework made on the application's behalf, carries `usedAt` instead, and a component
+ * carries where it was declared. The inspector already falls back this way; the card read
+ * only the first of the three, so those nodes showed a location in one place and not the
+ * other.
+ */
+const placeOf = (node) => node.source ?? node.usedAt ?? node.declaredAt;
+const shortSource = (s) => {
+    const file = (s.file ?? '').split('/').pop() ?? '';
+    return s.line == null ? file : `${file}:${s.line}`;
+};
+/** What the value column holds at 12px monospace, ellipsis included. */
+const VALUE_CHARS = 7;
+const fit = (v) => {
+    const text = v ?? '';
+    return text.length > VALUE_CHARS ? text.slice(0, VALUE_CHARS - 1) + '…' : text;
+};
+const NH = 62;
 const PAD = 48;
-const KIND_CLASS = { state: 'n-state', memo: 'n-memo', effect: 'n-effect', store: 'n-store', resource: 'n-resource' };
-const KIND_GLYPH = { state: '◆ state', memo: 'ƒ memo', effect: '⚡ effect', store: '▤ store', resource: '⟳ resource' };
+/** How far apart two steps of a propagation land, and how long each glow lasts. */
+const STEP = 110;
+const FLASH = 560;
+/** An edge lights while the value is crossing it: from its source's step to the next. */
+const EDGE_FLASH = 260;
+const MIN_ZOOM = 0.2;
+/**
+ * How far past natural size the zoom goes.
+ *
+ * The ceiling cannot be a constant. The viewBox is the whole graph, so a big one is already
+ * shrunk to fit before `scale` applies. A five-hundred-node graph is shrunk enormously, and
+ * any fixed limit leaves its cards unreadable. The limit is worked out from how much the
+ * viewBox is shrinking, so it grows with the graph.
+ */
+const OVER_NATURAL = 12;
+/** For a graph smaller than the panel, where the viewBox is not shrinking anything. */
+const MIN_MAX_ZOOM = 8;
+/** A transform this deep is a bug somewhere, not a reader looking closely. */
+const ABSOLUTE_MAX_ZOOM = 4000;
+/** Past this the pointer was panning, not clicking. */
+const DRAG_SLOP = 4;
+const KIND_CLASS = { state: 'n-state', memo: 'n-memo', effect: 'n-effect', store: 'n-store', resource: 'n-resource', component: 'n-component', control: 'n-control', router: 'n-router', handler: 'n-handler', group: 'n-group', binding: 'n-binding', setter: 'n-setter', directive: 'n-directive', context: 'n-context', provider: 'n-provider' };
+const KIND_GLYPH = { state: '◆ state', memo: 'ƒ memo', effect: '⚡ effect', store: '▤ store', resource: '⟳ resource', component: '◧ component', control: '⑂ control flow', router: '⤳ router', handler: '⇄ route', group: '▤ framework', binding: '⇥ dom', setter: '✎ sets', directive: '⌘ directive', context: '◈ context', provider: '◈ provider' };
+/** The card that stands for everything a dependency made and the application never touched. */
+const GROUP_ID = -1;
+/**
+ * Ids for the cards that stand for something outside the graph.
+ *
+ * Counted down from below the group card, and derived from the node they hang off so they
+ * stay the same across renders. An id that moved would make the view rebuild every frame.
+ */
+/**
+ * One card per place in the document, not per reader.
+ *
+ * Several values can drive the same binding, as a resource's three signals all write the same
+ * heading, and a card each made them look like duplicates of one another. Ids are handed
+ * out per place and kept, so a card kept its identity between frames.
+ */
+const bindingIds = new Map();
+const bindingId = (place) => {
+    const held = bindingIds.get(place);
+    if (held !== undefined)
+        return held;
+    const id = -100 - bindingIds.size;
+    bindingIds.set(place, id);
+    return id;
+};
+const setterId = (owner, index) => -100000 - owner * 32 - index;
 function el(tag, attrs = {}) {
     const n = document.createElementNS(SVGNS, tag);
     for (const k in attrs)
@@ -13,7 +84,7 @@ function el(tag, attrs = {}) {
     return n;
 }
 // Longest-path depth so every read edge points strictly rightward (the read graph is a DAG).
-function computeDepths(graph) {
+function computeDepths(graph, deps) {
     const memo = new Map();
     const depth = (id, seen) => {
         if (memo.has(id))
@@ -24,7 +95,7 @@ function computeDepths(graph) {
         const node = graph.get(id);
         let d = 0;
         if (node)
-            for (const dep of node.deps)
+            for (const dep of deps(node))
                 d = Math.max(d, depth(dep, seen) + 1);
         seen.delete(id);
         memo.set(id, d);
@@ -36,37 +107,499 @@ function computeDepths(graph) {
 export function createGraphView(svg, options = {}) {
     let signature = '';
     let selected = null;
+    /** A set held lit until something clears it, being one commit from the timeline. */
+    let focused = null;
     const nodeEls = new Map();
+    /** Edges as ids, so hovering a node can pick out the ones that touch it. */
+    const edgeEls = [];
+    /**
+     * When each node and edge should glow.
+     *
+     * A write reaches every node that depends on it in one flush, so the graph knows about all
+     * of them in the same frame. Flashing them together says "these changed"; flashing them a
+     * step apart, along the edges between them, says which one caused which, and that is the
+     * thing the graph is for.
+     */
+    const staged = new Map();
+    const edgeStaged = new Map();
+    /** The pulse each node was last staged for, so one change is staged once. */
+    const stagedFor = new Map();
+    /** Where a folded-away node is drawn: itself, unless a store it belongs to is folded. */
+    let standIn = (id) => id;
+    /** Stores the viewer opened, and ones it closed again. Nothing else is remembered. */
+    const opened = new Set();
+    const closed = new Set();
+    const foldStores = options.collapseStores !== false;
+    let direction = options.direction ?? 'horizontal';
+    let groupExternal = options.groupExternal !== false;
+    let showBindings = options.showBindings === true;
+    /** Which kinds to draw. Null is every kind, which is not the same as a set holding them all. */
+    let kinds = options.kinds ? new Set(options.kinds) : null;
+    // A clip region per text, not one for the box: the label grows right from the left edge
+    // and the value grows left from the right, so clipping both to the same box still let a
+    // long label run under the value. Each gets its own half, with a gap between.
+    const uid = Math.random().toString(36).slice(2, 8);
+    const labelClip = `fx-label-clip-${uid}`;
+    const valueClip = `fx-value-clip-${uid}`;
+    const LABEL_W = 66;
+    const defs = el('defs');
+    const forLabel = el('clipPath', { id: labelClip });
+    forLabel.appendChild(el('rect', { x: 8, y: 0, width: LABEL_W, height: NH }));
+    const sourceClip = `fx-source-clip-${uid}`;
+    const forSource = el('clipPath', { id: sourceClip });
+    forSource.appendChild(el('rect', { x: 8, y: 0, width: NW - 16, height: NH }));
+    const forValue = el('clipPath', { id: valueClip });
+    // A little past the box on the right, so the ellipsis itself is not the thing clipped.
+    forValue.appendChild(el('rect', { x: 8 + LABEL_W + 6, y: 0, width: NW - LABEL_W - 10, height: NH }));
+    defs.append(forLabel, forValue, forSource);
+    // Everything drawn hangs off one group, which is what pan and zoom move. The viewBox still
+    // sizes the drawing to the graph; this rides on top of it.
+    const viewport = el('g', { class: 'fx-viewport' });
     let edgeLayer = el('g', { class: 'fx-edges' });
     let nodeLayer = el('g', { class: 'fx-nodes' });
-    svg.append(edgeLayer, nodeLayer);
+    viewport.append(edgeLayer, nodeLayer);
+    svg.append(defs, viewport);
+    /**
+     * The furthest in this graph is worth zooming.
+     *
+     * `meet` fits by whichever axis is tighter, so the scale at which a card is its natural size
+     * is the *larger* of the two ratios. Measuring width alone left a tall graph clamped while
+     * its nodes were unreadable.
+     */
+    const maxZoom = () => {
+        const box = svg.viewBox?.baseVal;
+        const rect = svg.getBoundingClientRect?.();
+        if (!box?.width || !rect?.width || !rect.height)
+            return MIN_MAX_ZOOM;
+        const natural = Math.max(box.width / rect.width, (box.height || 0) / rect.height);
+        return Math.min(ABSOLUTE_MAX_ZOOM, Math.max(MIN_MAX_ZOOM, natural * OVER_NATURAL));
+    };
+    let scale = 1;
+    let panX = 0;
+    let panY = 0;
+    const applyView = () => viewport.setAttribute('transform', `translate(${panX} ${panY}) scale(${scale})`);
+    /** Client pixels → the coordinates the drawing is in, before pan and zoom. */
+    const toUserSpace = (clientX, clientY) => {
+        const ctm = svg.getScreenCTM?.();
+        if (!ctm)
+            return { x: 0, y: 0 };
+        const point = Object.assign(svg.createSVGPoint(), { x: clientX, y: clientY }).matrixTransform(ctm.inverse());
+        return { x: point.x, y: point.y };
+    };
+    const zoomAt = (factor, at) => {
+        const next = Math.min(maxZoom(), Math.max(MIN_ZOOM, scale * factor));
+        if (next === scale)
+            return;
+        // Keep whatever is under the cursor under the cursor.
+        panX = at.x - ((at.x - panX) * next) / scale;
+        panY = at.y - ((at.y - panY) * next) / scale;
+        scale = next;
+        applyView();
+    };
+    svg.addEventListener('wheel', (event) => {
+        event.preventDefault();
+        zoomAt(Math.exp(-event.deltaY * 0.0015), toUserSpace(event.clientX, event.clientY));
+    }, { passive: false });
+    let dragging = null;
+    svg.addEventListener('pointerdown', (event) => {
+        if (event.button !== 0)
+            return;
+        // No capture yet. Capturing here retargets every later event at the svg, so the click
+        // that follows never reaches the node it was aimed at and nothing gets selected.
+        dragging = { x: event.clientX, y: event.clientY, panX, panY, moved: false };
+    });
+    svg.addEventListener('pointermove', (event) => {
+        if (!dragging)
+            return;
+        const dx = event.clientX - dragging.x;
+        const dy = event.clientY - dragging.y;
+        if (!dragging.moved && Math.abs(dx) + Math.abs(dy) < DRAG_SLOP)
+            return;
+        if (!dragging.moved)
+            svg.setPointerCapture?.(event.pointerId);
+        dragging.moved = true;
+        // Screen pixels are not user units once the viewBox has scaled the drawing.
+        const ratio = svg.getScreenCTM?.()?.a || 1;
+        panX = dragging.panX + dx / ratio;
+        panY = dragging.panY + dy / ratio;
+        applyView();
+    });
+    const endDrag = (event) => {
+        if (dragging?.moved)
+            svg.releasePointerCapture?.(event.pointerId);
+        // Cleared after the click event, so a pan does not also select what it started on.
+        setTimeout(() => {
+            dragging = null;
+        }, 0);
+    };
+    svg.addEventListener('pointerup', endDrag);
+    svg.addEventListener('pointercancel', endDrag);
+    svg.addEventListener('dblclick', () => {
+        scale = 1;
+        panX = 0;
+        panY = 0;
+        applyView();
+    });
+    /** Order this frame's changes into steps, following the edges that are actually drawn. */
+    function stageWave(graph, now) {
+        const fresh = [];
+        for (const node of graph.values()) {
+            if (!node.lastPulse || stagedFor.get(node.id) === node.lastPulse)
+                continue;
+            stagedFor.set(node.id, node.lastPulse);
+            if (nodeEls.has(node.id))
+                fresh.push(node.id);
+        }
+        if (!fresh.length)
+            return;
+        const changed = new Set(fresh);
+        // Only the edges between things that changed together: the rest of the graph is not
+        // part of this propagation.
+        const after = new Map();
+        for (const { a, b } of edgeEls) {
+            if (changed.has(a) && changed.has(b))
+                (after.get(a) ?? after.set(a, []).get(a)).push(b);
+        }
+        const fed = new Set([...after.values()].flat());
+        // Breadth-first from what nothing else in this change fed: those are the writes.
+        const step = new Map();
+        const queue = fresh
+            .filter((id) => !fed.has(id))
+            .map((id) => ({ id, depth: 0 }));
+        // A cycle, or a change with no clear source, still has to be shown.
+        if (!queue.length)
+            for (const id of fresh)
+                queue.push({ id, depth: 0 });
+        while (queue.length) {
+            const { id, depth } = queue.shift();
+            if (step.has(id))
+                continue;
+            step.set(id, depth);
+            for (const next of after.get(id) ?? [])
+                if (!step.has(next))
+                    queue.push({ id: next, depth: depth + 1 });
+        }
+        for (const id of fresh)
+            staged.set(id, now + (step.get(id) ?? 0) * STEP);
+        for (const { a, b, el } of edgeEls) {
+            const from = step.get(a);
+            const to = step.get(b);
+            if (from === undefined || to === undefined || to <= from)
+                continue;
+            // Lit while the value is between the two, which is the gap the nodes leave.
+            edgeStaged.set(el, now + from * STEP + STEP * 0.35);
+        }
+    }
     function applySelected() {
         for (const [id, { g }] of nodeEls)
             g.classList.toggle('selected', id === selected);
     }
-    function rebuild(graph) {
-        computeDepths(graph);
+    /**
+     * What this node is part of: everything upstream of it and everything downstream, along
+     * the direction values actually travel.
+     *
+     * Ownership is one hop only. A component owns most of a page, and following it would
+     * light the whole graph up, which is the same as highlighting nothing.
+     */
+    function related(graph, from) {
+        const feeds = new Map();
+        const fedBy = new Map();
+        const link = (source, target) => {
+            (feeds.get(source) ?? feeds.set(source, new Set()).get(source)).add(target);
+            (fedBy.get(target) ?? fedBy.set(target, new Set()).get(target)).add(source);
+        };
+        for (const node of graph.values()) {
+            for (const dep of node.deps)
+                link(dep, node.id);
+            for (const written of node.writes)
+                link(node.id, written);
+        }
+        const out = new Set([from]);
+        const walk = (edges) => {
+            const queue = [from];
+            while (queue.length) {
+                for (const next of edges.get(queue.pop()) ?? []) {
+                    if (!out.has(next)) {
+                        out.add(next);
+                        queue.push(next);
+                    }
+                }
+            }
+        };
+        walk(feeds);
+        walk(fedBy);
+        const node = graph.get(from);
+        if (node?.createdIn !== undefined)
+            out.add(node.createdIn);
+        for (const other of graph.values())
+            if (other.createdIn === from)
+                out.add(other.id);
+        return out;
+    }
+    /** Light this set and dim the rest; no set puts everything back. */
+    function light(set) {
+        if (!set) {
+            svg.classList.remove('fx-hovering');
+            for (const { g } of nodeEls.values())
+                g.classList.remove('hot');
+            for (const { el: path } of edgeEls)
+                path.classList.remove('hot');
+            return;
+        }
+        svg.classList.add('fx-hovering');
+        for (const [nodeId, { g }] of nodeEls)
+            g.classList.toggle('hot', set.has(nodeId));
+        for (const { a, b, el: path } of edgeEls)
+            path.classList.toggle('hot', set.has(a) && set.has(b));
+    }
+    function hover(graph, id) {
+        // Back to the focus, not to nothing: leaving a node must not undo a picked commit.
+        if (id === null)
+            return light(focused);
+        // Through the fold: a memo reading `cart.items` is reading the card marked `cart`.
+        const set = new Set([...related(graph, id)].map(standIn));
+        light(set);
+        // Hovering a node that is folded away is hovering the card it is drawn as.
+        nodeEls.get(standIn(id))?.g.classList.add('hot');
+    }
+    /**
+     * The graph as it is drawn: the nodes the application made, plus one card standing for
+     * everything a dependency made on its own account.
+     *
+     * A copy, not the host's map. What is drawn is a view of the graph, and the graph belongs
+     * to whoever is filling it.
+     */
+    /**
+     * The document and the handlers, as cards.
+     *
+     * A binding is not a node, which is why they are plumbing. But "where does this end up" is
+     * the one thing the graph cannot otherwise answer, so they can be turned on.
+     */
+    function withEdges(graph) {
+        if (!showBindings)
+            return graph;
+        const shown = new Map(graph);
+        let added = false;
+        for (const node of graph.values()) {
+            node.targets?.forEach((target) => {
+                const at = target.source;
+                const place = `${target.name ?? ''}|${target.element}|${at?.file ?? ''}:${at?.line ?? ''}:${at?.column ?? ''}`;
+                const id = bindingId(place);
+                const card = shown.get(id) ?? {
+                    id,
+                    label: target.name ? `${target.name} of ${target.element}` : target.element,
+                    kind: 'binding',
+                    // The card reads the signal, so the arrow runs the way the value does.
+                    deps: new Set(),
+                    writes: new Set(),
+                    runs: 0,
+                    lastPulse: 0,
+                    ...(at ? { source: at } : {}),
+                };
+                card.deps.add(node.id);
+                // Whichever of its readers ran last is when this place last changed.
+                card.runs = Math.max(card.runs, node.runs);
+                card.lastPulse = Math.max(card.lastPulse, node.lastPulse);
+                shown.set(id, card);
+                added = true;
+            });
+            node.setAt?.forEach((at, i) => {
+                const id = setterId(node.id, i);
+                shown.set(id, {
+                    id,
+                    // Two handlers in one component can share an original position; the compiled line
+                    // is what separates the cards.
+                    label: `set at ${(at.file ?? '').split('/').pop() ?? '?'}:${at.line ?? ''}${at.compiled && at.compiled.line !== at.line ? `→${at.compiled.line}` : ''}`,
+                    kind: 'setter',
+                    deps: new Set(),
+                    // A handler writes the signal, so it gets the write edge a computation would.
+                    writes: new Set([node.id]),
+                    runs: node.runs,
+                    // The write edge runs setter → signal, so the wave starts here.
+                    lastPulse: node.lastPulse,
+                    source: at,
+                });
+                added = true;
+            });
+        }
+        return added ? shown : graph;
+    }
+    /**
+     * A node the author did not write: the memo the compiler wraps a component in, the
+     * signals a resource keeps, `Show.when`, `mapArray`, `row index`. All of it is real and
+     * none of it is anything the author can go and edit.
+     *
+     * Control flow is excluded on purpose. `Show` and `Switch` are tags in the source, so
+     * they stay drawn as themselves.
+     *
+     * A tag is harder: `LazyWrapper` is made by `lazy()` and is nobody's to edit, while the
+     * routed component it loads is created in the same file and is entirely the author's. The
+     * difference is whether the project holds a line for it, not where it was instantiated.
+     */
+    const inProject = (at) => !!at?.file && at.external !== true;
+    const machinery = (n) => {
+        if (n.authored !== false)
+            return false;
+        if (n.kind === 'state' || n.kind === 'memo' || n.kind === 'effect' || n.kind === 'context') {
+            return true;
+        }
+        if (n.kind === 'component' || n.kind === 'provider') {
+            return !inProject(n.declaredAt) && !inProject(n.source) && !inProject(n.usedAt);
+        }
+        return false;
+    };
+    /**
+     * Cards a view makes rather than nodes the application has. They follow their own toggles
+     * and their owner's visibility, so a kind filter does not reach them.
+     */
+    const VIEW_CARD = new Set(['group', 'binding', 'setter']);
+    const kindKey = () => (kinds ? [...kinds].sort().join('+') : '*');
+    /**
+     * Keep only the kinds asked for. `createdIn` is re-pointed at the nearest ancestor that
+     * survived, so hiding the memos around a component does not orphan what they made.
+     */
+    function onlyKinds(graph) {
+        if (!kinds)
+            return graph;
+        const keep = (n) => VIEW_CARD.has(n.kind) || kinds.has(n.kind);
+        const out = new Map();
+        for (const [id, node] of graph) {
+            if (!keep(node))
+                continue;
+            let owner = node.createdIn;
+            const seen = new Set();
+            while (owner !== undefined && !seen.has(owner)) {
+                seen.add(owner);
+                const up = graph.get(owner);
+                if (up && keep(up))
+                    break;
+                owner = up?.createdIn;
+            }
+            out.set(id, owner === node.createdIn ? node : { ...node, createdIn: owner });
+        }
+        return out;
+    }
+    function grouped(graph) {
+        if (!groupExternal)
+            return graph;
+        const outsiders = [...graph.values()].filter(
+        // A card carries the source of whatever made it, often a package. It already hangs off
+        // its signal and must not be moved under the group.
+        (n) => (n.source?.external && n.createdIn === undefined && n.kind !== 'binding' && n.kind !== 'setter') ||
+            machinery(n));
+        if (!outsiders.length)
+            return graph;
+        const shown = new Map(graph);
+        shown.set(GROUP_ID, {
+            id: GROUP_ID,
+            label: 'framework',
+            kind: 'group',
+            deps: new Set(),
+            writes: new Set(),
+            runs: 0,
+            lastPulse: 0,
+        });
+        // Hung off the card, which is what the existing folding already knows how to draw.
+        const moved = new Set(outsiders.map((n) => n.id));
+        for (const node of outsiders)
+            shown.set(node.id, { ...node, createdIn: GROUP_ID });
+        // What the machinery made is not machinery. A `Show` created inside the memo the
+        // compiler wrapped it in would otherwise fold away with it, and the tag the author
+        // wrote would be missing from the graph.
+        for (const [id, node] of graph) {
+            if (moved.has(id) || node.createdIn === undefined)
+                continue;
+            let owner = node.createdIn;
+            const seen = new Set();
+            while (owner !== undefined && moved.has(owner) && !seen.has(owner)) {
+                seen.add(owner);
+                owner = graph.get(owner)?.createdIn;
+            }
+            if (owner !== node.createdIn)
+                shown.set(id, { ...node, createdIn: owner });
+        }
+        return shown;
+    }
+    function rebuild(graph, folded) {
         edgeLayer.remove();
         nodeLayer.remove();
         nodeEls.clear();
+        edgeEls.length = 0;
+        edgeStaged.clear();
         edgeLayer = el('g', { class: 'fx-edges' });
         nodeLayer = el('g', { class: 'fx-nodes' });
+        // A node inside a folded store is drawn as the store: its edges become the store's, so
+        // a memo reading `cart.total` still visibly reads something.
+        standIn = (id) => {
+            let at = id;
+            let outermost = id;
+            const seen = new Set();
+            while (at !== undefined && !seen.has(at)) {
+                seen.add(at);
+                if (folded.has(at) && at !== id)
+                    outermost = at;
+                at = graph.get(at)?.createdIn;
+            }
+            return outermost;
+        };
+        const visible = new Map();
+        const hiddenCount = new Map();
+        for (const node of graph.values()) {
+            const shown = standIn(node.id);
+            if (shown === node.id)
+                visible.set(node.id, node);
+            else
+                hiddenCount.set(shown, (hiddenCount.get(shown) ?? 0) + 1);
+        }
+        /** Read edges after folding, deduplicated: several keys of one store are one edge. */
+        const readsOf = (node) => {
+            const out = new Set();
+            for (const dep of node.deps) {
+                const from = standIn(dep);
+                if (from !== node.id && visible.has(from))
+                    out.add(from);
+            }
+            if (node.createdIn !== undefined) {
+                const owner = standIn(node.createdIn);
+                if (owner !== node.id && visible.has(owner))
+                    out.add(owner);
+            }
+            return out;
+        };
+        computeDepths(visible, readsOf);
         const byDepth = new Map();
         let maxDepth = 0;
-        for (const node of graph.values()) {
+        for (const node of visible.values()) {
             const d = node.depth ?? 0;
             (byDepth.get(d) ?? byDepth.set(d, []).get(d)).push(node);
             maxDepth = Math.max(maxDepth, d);
         }
+        // Page order inside a band, for the same reason the tree uses it.
+        for (const [d, nodes] of byDepth)
+            byDepth.set(d, inPageOrder(nodes));
         let maxRows = 0;
         for (const nodes of byDepth.values())
             maxRows = Math.max(maxRows, nodes.length);
+        // Depth runs along one axis and the nodes at a depth along the other; which is which is
+        // the only difference between the two layouts.
+        const down = direction === 'vertical';
+        const STEP_ACROSS = down ? COL + 24 : ROW;
         const pos = new Map();
         for (const [d, nodes] of byDepth) {
-            const top = PAD + (maxRows * ROW - nodes.length * ROW) / 2;
-            nodes.forEach((node, i) => pos.set(node.id, { x: PAD + d * COL, y: top + i * ROW }));
+            const offset = PAD + (maxRows * STEP_ACROSS - nodes.length * STEP_ACROSS) / 2;
+            nodes.forEach((node, i) => pos.set(node.id, down
+                ? { x: offset + i * STEP_ACROSS, y: PAD + d * (NH + 46) }
+                : { x: PAD + d * COL, y: offset + i * STEP_ACROSS }));
         }
         const curve = (from, to) => {
+            if (down) {
+                const x1 = from.x + NW / 2;
+                const y1 = from.y + NH;
+                const x2 = to.x + NW / 2;
+                const y2 = to.y;
+                const my = (y1 + y2) / 2;
+                return `M ${x1} ${y1} C ${x1} ${my}, ${x2} ${my}, ${x2} ${y2}`;
+            }
             const x1 = from.x + NW;
             const y1 = from.y + NH / 2;
             const x2 = to.x;
@@ -74,92 +607,375 @@ export function createGraphView(svg, options = {}) {
             const mx = (x1 + x2) / 2;
             return `M ${x1} ${y1} C ${mx} ${y1}, ${mx} ${y2}, ${x2} ${y2}`;
         };
-        for (const node of graph.values()) {
+        const addEdge = (a, b, kind, d) => {
+            const path = el('path', { class: kind, d });
+            edgeLayer.appendChild(path);
+            edgeEls.push({ a, b, el: path });
+        };
+        for (const node of visible.values()) {
             const to = pos.get(node.id);
-            for (const dep of node.deps) {
+            const owner = node.createdIn !== undefined ? standIn(node.createdIn) : undefined;
+            for (const dep of readsOf(node)) {
                 const from = pos.get(dep);
-                if (from)
-                    edgeLayer.appendChild(el('path', { class: 'fx-edge', d: curve(from, to) }));
+                // The one that created it is drawn as what it is, unless it is also read.
+                const own = dep === owner && !node.deps.has(dep);
+                addEdge(dep, node.id, own ? 'fx-oedge' : 'fx-edge', curve(from, to));
             }
             // write edges: this node → the signal it sets (reverse direction, dashed)
             for (const w of node.writes) {
-                const target = pos.get(w);
-                if (target)
-                    edgeLayer.appendChild(el('path', { class: 'fx-wedge', d: curve(to, target) }));
+                const target = pos.get(standIn(w));
+                if (target && standIn(w) !== node.id)
+                    addEdge(node.id, standIn(w), 'fx-wedge', curve(to, target));
             }
         }
-        for (const node of graph.values()) {
+        for (const node of visible.values()) {
             const p = pos.get(node.id);
-            const g = el('g', { class: `fx-node ${KIND_CLASS[node.kind]}`, transform: `translate(${p.x} ${p.y})`, 'data-id': node.id });
+            // A node a dependency made is drawn back, so what the application itself created reads
+            // first. Only ever set when the compiler was told to mark dependencies.
+            const from = node.source?.external ? ' n-external' : '';
+            const g = el('g', { class: `fx-node ${KIND_CLASS[node.kind]}${from}`, transform: `translate(${p.x} ${p.y})`, 'data-id': node.id });
             g.appendChild(el('rect', { class: 'fx-box', width: NW, height: NH, rx: 12 }));
             const kind = el('text', { class: 'fx-kind', x: 12, y: 20 });
             kind.textContent = KIND_GLYPH[node.kind];
             const label = el('text', { class: 'fx-label', x: 12, y: 38 });
+            label.setAttribute('clip-path', `url(#${labelClip})`);
             label.textContent = node.label;
-            const value = el('text', { class: 'fx-value', x: NW - 12, y: 38, 'text-anchor': 'end' });
-            value.textContent = node.value ?? '';
+            // Left-anchored and truncated rather than clipped from the right: an end-anchored
+            // string is cut at its start, so a store's value showed the tail of a json blob,
+            // `unter...` or `"App"}`, instead of what it is.
+            const value = el('text', { class: 'fx-value', x: 8 + LABEL_W + 6, y: 38 });
+            value.setAttribute('clip-path', `url(#${valueClip})`);
+            value.textContent = fit(node.value);
+            // The card has room for a dozen characters of a value that can be an object. The rest
+            // is here, on hover, rather than nowhere.
+            const full = node.detail ?? node.value;
+            if (full)
+                value.appendChild(el('title')).textContent = full;
             g.append(kind, label, value);
+            // A routed component arrives with its chunk, so it is missing from the graph until the
+            // navigation that fetches it. Saying so beats looking like it was never there.
+            if (node.lazy) {
+                const chunk = el('text', { class: 'fx-lazy', x: 12, y: 52 });
+                chunk.textContent = 'lazy';
+                chunk.appendChild(el('title')).textContent = 'loaded as its own chunk';
+                g.appendChild(chunk);
+            }
+            // What a plugin wants said about this node. Right-aligned so it does not collide with
+            // the lazy mark on the same line.
+            const mark = pluginBadge(node);
+            if (mark) {
+                const badge = el('text', { class: 'fx-plugin', x: NW - 12, y: 52, 'text-anchor': 'end' });
+                badge.textContent = fit(mark);
+                badge.appendChild(el('title')).textContent = mark;
+                g.appendChild(badge);
+            }
+            const summary = el('title');
+            summary.textContent = `${node.kind} ${node.label}${node.lazy ? ' (lazy)' : ''}${full ? ` = ${full}` : ''}${placeOf(node)
+                ? `\n${placeOf(node).file ?? ''}:${placeOf(node).line ?? ''}:${placeOf(node).column ?? ''}`
+                : ''}`;
+            g.appendChild(summary);
+            // Always made, filled per frame. A source can arrive after the card does, and the layout
+            // signature does not depend on it, so waiting for a rebuild meant it never showed.
+            // Empty text draws nothing, so an unmarked node still reads as unmarked.
+            const source = el('text', { class: 'fx-source', x: 12, y: 52 });
+            source.setAttribute('clip-path', `url(#${sourceClip})`);
+            const sourceTitle = el('title');
+            source.appendChild(sourceTitle);
+            g.appendChild(source);
+            // Anything that made other nodes can hide them. A store makes one per key it is read
+            // by, which is most of what fills a graph up.
+            const inside = hiddenCount.get(node.id) ?? 0;
+            const owns = inside > 0 || [...graph.values()].some((n) => n.createdIn === node.id);
+            if (owns) {
+                const badge = el('text', { class: 'fx-fold', x: NW - 12, y: 20, 'text-anchor': 'end' });
+                badge.textContent = inside > 0 ? `▸ ${inside}` : '▾';
+                badge.appendChild(el('title')).textContent = inside > 0 ? `show ${inside} inside` : 'fold what is inside';
+                badge.addEventListener('click', (event) => {
+                    event.stopPropagation();
+                    toggleFold(node.id);
+                });
+                g.appendChild(badge);
+            }
             g.addEventListener('click', () => {
+                // A pan that ended on a node is not a click on it.
+                if (dragging?.moved)
+                    return;
                 selected = node.id;
                 applySelected();
                 options.onSelect?.(node);
             });
+            g.addEventListener('dblclick', (event) => {
+                if (!options.onReveal)
+                    return;
+                // The svg's own dblclick resets the zoom, which is not what a double-click on a
+                // card is asking for.
+                event.stopPropagation();
+                options.onReveal(node);
+            });
+            g.addEventListener('mouseenter', () => hover(graph, node.id));
+            g.addEventListener('mouseleave', () => hover(graph, null));
             g.style.cursor = 'pointer';
             nodeLayer.appendChild(g);
-            nodeEls.set(node.id, { g, value });
+            nodeEls.set(node.id, { g, value, source, sourceTitle });
         }
-        svg.append(edgeLayer, nodeLayer);
-        svg.setAttribute('viewBox', `0 0 ${Math.max(PAD * 2 + maxDepth * COL + NW, 400)} ${Math.max(PAD * 2 + maxRows * ROW, 240)}`);
+        viewport.append(edgeLayer, nodeLayer);
+        const width = down ? PAD * 2 + maxRows * STEP_ACROSS + NW : PAD * 2 + maxDepth * COL + NW;
+        const height = down ? PAD * 2 + (maxDepth + 1) * (NH + 46) : PAD * 2 + maxRows * ROW;
+        svg.setAttribute('viewBox', `0 0 ${Math.max(width, 400)} ${Math.max(height, 240)}`);
         applySelected();
     }
+    let lastGraph = new Map();
+    /**
+     * The graph as drawn, including the cards the view invents.
+     *
+     * A host holds the real graph and cannot resolve a binding card by id, so selecting one
+     * left the inspector empty. This is what it should look the selection up in.
+     */
+    let lastShown = new Map();
+    /**
+     * What is folded right now: a store and anything inside it, minus what the viewer opened.
+     *
+     * Nesting matters: a cart holds items, an item holds its properties. Opening the store
+     * shows the items as their own cards, each still folded over its own keys, rather than
+     * every signal in the tree at once.
+     */
+    function foldedIn(graph) {
+        const hasChildren = new Set();
+        for (const node of graph.values())
+            if (node.createdIn !== undefined)
+                hasChildren.add(node.createdIn);
+        const inStore = (id) => {
+            const seen = new Set();
+            let at = graph.get(id)?.createdIn;
+            while (at !== undefined && !seen.has(at)) {
+                seen.add(at);
+                const up = graph.get(at);
+                if (up?.kind === 'store')
+                    return true;
+                at = up?.createdIn;
+            }
+            return false;
+        };
+        const folded = new Set();
+        for (const node of graph.values()) {
+            if (!hasChildren.has(node.id))
+                continue;
+            const byDefault = (node.kind === 'group' || (foldStores && (node.kind === 'store' || inStore(node.id)))) &&
+                !opened.has(node.id);
+            if (byDefault || closed.has(node.id))
+                folded.add(node.id);
+        }
+        return folded;
+    }
+    function toggleFold(id) {
+        // The grouped view, not the host's graph: the card standing for the packages only exists
+        // in the former, so asking the latter says it is not folded and the toggle does nothing.
+        const folded = foldedIn(grouped(lastGraph)).has(id);
+        if (folded) {
+            opened.add(id);
+            closed.delete(id);
+        }
+        else {
+            closed.add(id);
+            opened.delete(id);
+        }
+        signature = '';
+        // What is on screen changed shape, so whatever the view was zoomed into is gone. Back to
+        // the whole graph in frame rather than a viewport pointing at nothing.
+        scale = 1;
+        panX = 0;
+        panY = 0;
+        applyView();
+        return !folded;
+    }
     return {
-        update(graph, now = performance.now()) {
-            let sig = '';
-            for (const n of graph.values())
-                sig += `${n.id}:${n.kind}:${[...n.deps].sort().join(',')}>${[...n.writes].sort().join(',')};`;
+        // Date.now, matching what the reactor stamps on a node. See instrument.ts.
+        update(graph, now = Date.now()) {
+            lastGraph = graph;
+            // Bindings first: a card hung off a signal is not an outsider.
+            const shown = grouped(withEdges(onlyKinds(graph)));
+            lastShown = shown;
+            const folded = foldedIn(shown);
+            let sig = `${[...folded].sort().join(',')}|${groupExternal}|${direction}|${kindKey()}|`;
+            for (const n of shown.values())
+                sig += `${n.id}:${n.kind}:${[...n.deps].sort().join(',')}>${[...n.writes].sort().join(',')}^${n.createdIn ?? ''};`;
             if (sig !== signature) {
                 signature = sig;
-                rebuild(graph);
+                rebuild(shown, folded);
+                // The elements are new, so what was lit is not.
+                if (focused)
+                    light(focused);
             }
-            for (const node of graph.values()) {
+            stageWave(shown, now);
+            for (const node of shown.values()) {
                 const eles = nodeEls.get(node.id);
                 if (!eles)
                     continue;
-                if (node.value !== undefined && eles.value.textContent !== node.value)
-                    eles.value.textContent = node.value;
-                const age = now - node.lastPulse;
-                eles.g.style.setProperty('--pulse', (age < 600 ? 1 - age / 600 : 0).toFixed(3));
+                const next = fit(node.value);
+                if (eles.value.textContent !== next)
+                    eles.value.textContent = next;
+                const place = placeOf(node);
+                const where = place ? shortSource(place) : '';
+                if (eles.source.textContent !== where) {
+                    eles.source.textContent = where;
+                    // The card shows the file name; the tooltip has room for where it sits, which for
+                    // a node the framework made is a path on the machine that ran it.
+                    eles.sourceTitle.textContent = place
+                        ? `${place.file ? shortenPath(place.file, options.root) : ''}:${place.line ?? ''}:${place.column ?? ''}`
+                        : '';
+                }
+                // Nothing before its turn: a node three steps down the chain sits dark until the
+                // change reaches it.
+                const age = now - (staged.get(node.id) ?? node.lastPulse);
+                eles.g.style.setProperty('--pulse', (age >= 0 && age < FLASH ? 1 - age / FLASH : 0).toFixed(3));
+            }
+            for (const { el } of edgeEls) {
+                const at = edgeStaged.get(el);
+                const age = at === undefined ? Infinity : now - at;
+                el.style.setProperty('--pulse', (age >= 0 && age < EDGE_FLASH ? 1 - age / EDGE_FLASH : 0).toFixed(3));
             }
         },
         clear() {
             signature = '';
             selected = null;
+            focused = null;
+            svg.classList.remove('fx-hovering');
             edgeLayer.replaceChildren();
             nodeLayer.replaceChildren();
             nodeEls.clear();
+            edgeEls.length = 0;
+            staged.clear();
+            stagedFor.clear();
+            edgeStaged.clear();
             options.onSelect?.(null);
         },
         select(id) {
             selected = id;
             applySelected();
         },
+        zoomBy(factor) {
+            const box = svg.viewBox?.baseVal;
+            zoomAt(factor, { x: (box?.width ?? 400) / 2, y: (box?.height ?? 240) / 2 });
+        },
+        resetView() {
+            scale = 1;
+            panX = 0;
+            panY = 0;
+            applyView();
+        },
+        toggle: toggleFold,
+        setGroupExternal(next) {
+            if (groupExternal === next)
+                return;
+            groupExternal = next;
+            signature = '';
+            scale = 1;
+            panX = 0;
+            panY = 0;
+            applyView();
+        },
+        get groupExternal() {
+            return groupExternal;
+        },
+        setShowBindings(next) {
+            if (showBindings === next)
+                return;
+            showBindings = next;
+            // The topology changed, so the layout is worked out again.
+            signature = '';
+        },
+        get showBindings() {
+            return showBindings;
+        },
+        setKinds(next) {
+            const key = next ? [...next].sort().join('+') : '*';
+            if (key === kindKey())
+                return;
+            kinds = next ? new Set(next) : null;
+            // Fewer nodes is a different graph: it is laid out again rather than hidden in place.
+            signature = '';
+        },
+        get kinds() {
+            return kinds;
+        },
+        get shown() {
+            return lastShown;
+        },
+        focus(ids) {
+            // Through the fold, like hovering.
+            focused = ids?.length ? new Set(ids.map(standIn)) : null;
+            light(focused);
+        },
+        setDirection(next) {
+            if (direction === next)
+                return;
+            direction = next;
+            signature = '';
+            // The drawing is a different shape now, so the viewport starts over.
+            scale = 1;
+            panX = 0;
+            panY = 0;
+            applyView();
+        },
+        get direction() {
+            return direction;
+        },
     };
 }
-// default theme; override the fx-* classes to restyle
+/**
+ * Default theme.
+ *
+ * Every colour reads a custom property first, so a host that defines them, a page with a
+ * light mode say, restyles the graph without replacing this. The fallbacks are the dark
+ * values it always had. The four node hues stay as they are: here colour is the distinction
+ * being drawn, not decoration.
+ */
 export const DEVTOOLS_CSS = `
-.fx-edge { fill: none; stroke: #38415a; stroke-width: 1.6; opacity: .75; }
-.fx-wedge { fill: none; stroke: #fb7185; stroke-width: 1.4; stroke-dasharray: 3 4; opacity: .65; }
-.fx-node { color: #5eead4; filter: drop-shadow(0 0 calc(var(--pulse,0) * 13px) var(--glow, #5eead4)); }
-.fx-node.n-state { --glow: #34d399; }
-.fx-node.n-memo { --glow: #a78bfa; }
-.fx-node.n-effect { --glow: #fbbf24; }
-.fx-node.n-store { --glow: #38bdf8; }
-.fx-node.n-resource { --glow: #fb7185; }
-.fx-box { fill: #131722; stroke: var(--glow, #5eead4); stroke-width: 1.4; stroke-opacity: calc(.5 + var(--pulse,0) * .5); }
-.fx-node.selected .fx-box { fill: #1a2230; stroke-width: 2.4; }
+/* An edge carries a pulse while the change is crossing it, so a propagation reads as one
+   thing moving rather than everything lighting at once. */
+.fx-edge {
+  fill: none;
+  stroke: var(--fx-edge, #38415a);
+  stroke-width: calc(1.6px + var(--pulse, 0) * 1.7px);
+  opacity: calc(.75 + var(--pulse, 0) * .25);
+  filter: drop-shadow(0 0 calc(var(--pulse, 0) * 5px) var(--fx-accent, #5eead4));
+}
+.fx-oedge { fill: none; stroke: var(--fx-own, #64748b); stroke-width: 1.2; stroke-dasharray: 1 4; stroke-linecap: round; opacity: .55; }
+.fx-wedge {
+  fill: none;
+  stroke: var(--fx-write, #fb7185);
+  stroke-width: calc(1.4px + var(--pulse, 0) * 1.6px);
+  stroke-dasharray: 3 4;
+  opacity: calc(.65 + var(--pulse, 0) * .35);
+}
+.fx-node { color: var(--fx-accent, #5eead4); filter: drop-shadow(0 0 calc(var(--pulse,0) * 13px) var(--glow, #5eead4)); }
+${kindRules((k) => `.fx-node.n-${k}`, '--glow')}
+.fx-node.n-group { opacity: .8; }
+.fx-node.n-group .fx-box { stroke-dasharray: 4 3; }
+/* Neither is a node: dashed and dimmer, so the reactive shape reads first. */
+.fx-node.n-binding { opacity: .72; }
+.fx-node.n-setter { opacity: .72; }
+.fx-node.n-binding .fx-box, .fx-node.n-setter .fx-box { stroke-dasharray: 3 3; }
+.fx-node.n-external { opacity: .55; }
+.fx-node.n-external .fx-box { stroke-dasharray: 3 2; }
+.fx-box { fill: var(--fx-node-bg, #131722); stroke: var(--glow, #5eead4); stroke-width: 1.4; stroke-opacity: calc(.5 + var(--pulse,0) * .5); }
+.fx-node.selected .fx-box { fill: var(--fx-node-bg-selected, #1a2230); stroke-width: 2.4; }
 .fx-kind { fill: var(--glow, #5eead4); font-family: ui-monospace, monospace; font-size: 9.5px; opacity: .85; }
-.fx-label { fill: #e7e9ee; font-family: ui-sans-serif, system-ui, sans-serif; font-size: 13px; font-weight: 600; }
-.fx-value { fill: #8a90a2; font-family: ui-monospace, monospace; font-size: 12px; }
-.fx-node.n-effect .fx-value { fill: #fbbf24; }
-.fx-node.n-resource .fx-value { fill: #fb7185; }
+.fx-label { fill: var(--fx-label, #e7e9ee); font-family: ui-sans-serif, system-ui, sans-serif; font-size: 13px; font-weight: 600; }
+.fx-value { fill: var(--fx-muted, #8a90a2); font-family: ui-monospace, monospace; font-size: 12px; }
+.fx-source { fill: var(--fx-muted, #8a90a2); font-family: ui-monospace, monospace; font-size: 9.5px; opacity: .75; }
+.fx-plugin { fill: var(--fx-accent, #5eead4); font-family: ui-monospace, monospace; font-size: 9px; opacity: .9; }
+.fx-lazy { fill: var(--fx-router, #7dd3fc); font-family: ui-monospace, monospace; font-size: 9px; letter-spacing: .04em; opacity: .9; }
+.fx-fold { fill: var(--glow, #5eead4); font-family: ui-monospace, monospace; font-size: 10px; cursor: pointer; opacity: .8; }
+.fx-fold:hover { opacity: 1; }
+.fx-node.n-effect .fx-value { fill: var(--effect, #fbbf24); }
+.fx-node.n-resource .fx-value { fill: var(--fx-write, #fb7185); }
+/* Hovering one node is a question about that node: everything it cannot reach steps back. */
+.fx-hovering .fx-node { opacity: .2; transition: opacity .12s ease; }
+.fx-hovering .fx-node.hot { opacity: 1; }
+.fx-hovering .fx-node.n-external.hot { opacity: .7; }
+.fx-hovering .fx-edge, .fx-hovering .fx-oedge, .fx-hovering .fx-wedge { opacity: .08; }
+.fx-hovering .fx-edge.hot { opacity: 1; stroke: var(--fx-accent, #5eead4); }
+.fx-hovering .fx-oedge.hot { opacity: .8; }
+.fx-hovering .fx-wedge.hot { opacity: .9; }
 `;