@fluixi/devtools 0.2.0-alpha.2 → 0.2.0-alpha.4

package/dist/observe.js

@@ -0,0 +1,893 @@
+// Watching an ordinary app.
+//
+// createReactor hands out its own primitives, so it only ever sees code written against it.
+// This sees code written against @fluixi/core: the runtime reports each node it makes, and
+// the node it reports carries its own edges. A source keeps `observers` and a consumer keeps
+// `sources`, so dependencies are read off the real graph instead of being rebuilt from
+// wrapped reads.
+//
+// The graph it fills is the same Map<number, RNode> createGraphView already draws, so a
+// renderer does not care which of the two produced it.
+import { observeReactiveNodes, untrack, } from '@fluixi/reactive/signal';
+import { componentSource, holeLocation, installSourceMarker, propsLocations, takeReactiveSource } from './source.js';
+import { currentCallSite } from './callsite.js';
+import { KIND_OF_BUILTIN } from './instrument.js';
+import { formatValue, shorten } from './format.js';
+import { createHistory } from './history.js';
+import { diffValues } from './diff.js';
+import { describeNode } from './describe.js';
+import { describeAll, tagDepths } from './dom.js';
+import { devtoolsPlugins, } from './plugin.js';
+import { TREE_KINDS } from './tree.js';
+/**
+ * Number each tag by where its element sits in the document.
+ *
+ * A keyed list rebuilds a row instead of mutating it, so the replacement carries the highest
+ * id. Sorting by id then put the new card last whichever row changed, and the flash always
+ * appeared at the bottom of the list. Only something holding the elements can say otherwise.
+ *
+ * Done in `sample`, not when a description is asked for: the graph view never asks for one,
+ * so stamping this lazily left every node unnumbered there and the fix showed only in the tree.
+ */
+function stampDocumentOrder(graph, rendered) {
+    const roots = [];
+    for (const node of graph.values()) {
+        if (!TREE_KINDS.has(node.kind))
+            continue;
+        const element = rendered(node.id)[0];
+        if (element?.isConnected)
+            roots.push({ id: node.id, element });
+    }
+    // DOCUMENT_POSITION_FOLLOWING: b comes after a, so a sorts first.
+    roots.sort((a, b) => (a.element.compareDocumentPosition(b.element) & 4 ? -1 : 1));
+    for (const node of graph.values())
+        node.order = undefined;
+    roots.forEach(({ id }, at) => {
+        const node = graph.get(id);
+        if (node)
+            node.order = at;
+    });
+}
+/** How far back a consumer may be and still be told what was dropped. */
+const REMOVED_LOG = 500;
+const KINDS = {
+    signal: 'state',
+    memo: 'memo',
+    effect: 'effect',
+    store: 'store',
+    resource: 'resource',
+};
+/** Long enough for an object's first fields, short enough that a few hundred stays small. */
+const HISTORY_VALUE = 80;
+/** How many distinct places may be remembered as writing one signal. */
+const SET_SITES = 8;
+const PREFIX = {
+    state: 's',
+    memo: 'm',
+    effect: 'e',
+    store: 'st',
+    resource: 'r',
+    component: 'c',
+    // Only the static graph makes these: at runtime control flow is a named memo, and a route
+    // handler never reaches a browser.
+    control: 'x',
+    router: 'rt',
+    handler: 'h',
+    // Never produced here: these are cards a view draws, not nodes anything creates.
+    group: 'g',
+    binding: 'b',
+    setter: 'w',
+    // A plugin's, and it names them itself.
+    directive: 'd',
+    context: 'ctx',
+    provider: 'p',
+};
+/**
+ * Start watching. Nodes made before this returns are not in the graph, so attach before the
+ * app's modules load, which in practice means before the entry import.
+ */
+/**
+ * What a component was handed, read for display.
+ *
+ * Every prop is a getter over whatever the caller wrote, so reading one runs that
+ * expression. Untracked, or the read would subscribe whatever is sampling to it and the
+ * panel would drive the graph by looking at it. `children` is skipped: reading it builds
+ * the subtree, which is a side effect nobody asked for by opening an inspector.
+ */
+function readProps(props) {
+    const at = propsLocations(props);
+    const out = [];
+    for (const name of Object.keys(props)) {
+        if (name === 'children')
+            continue;
+        const where = at?.[name];
+        const report = {
+            name,
+            ...(where ? { at: { line: where[0], column: where[1] } } : {}),
+        };
+        try {
+            report.value = formatValue(untrack(() => props[name]), 200);
+        }
+        catch {
+            // A getter that throws is still a prop worth naming.
+        }
+        out.push(report);
+    }
+    return out.length ? out : undefined;
+}
+export function observeGraph(options = {}) {
+    installSourceMarker();
+    const origin = options.origin ?? (typeof location === 'object' ? location.origin : undefined);
+    const graph = new Map();
+    /**
+     * Whether this node is the wrapper that made the stamped value rather than one further
+     * down that only passes it along.
+     *
+     * `$name` is set on what a component returns, so it travels with the value and every memo
+     * holding it looks like the component. The one that made it is the one none of its
+     * dependencies already has. Otherwise a component under `Suspense` draws twice.
+     */
+    const claims = (node, value) => {
+        for (const dep of node.deps) {
+            const other = graph.get(dep);
+            if (other?.read && other.read() === value)
+                return false;
+        }
+        return true;
+    };
+    /** Core node → id, so a report about a node already seen finds it. */
+    const ids = new WeakMap();
+    /**
+     * Plumbing the graph does not draw, mapped to the drawn node it was created inside. A row
+     * added to a list is created inside a render effect; without this it would arrive with no
+     * ancestor at all, and the component that caused it would sit on its own.
+     */
+    const through = new WeakMap();
+    /**
+     * The same plumbing, iterable.
+     *
+     * A signal whose only readers are dom bindings looks like a node nothing uses, because the
+     * bindings are not drawn. They are still what makes it matter, so they are counted.
+     * Dropped when the effect that holds them is disposed.
+     */
+    const internals = new Set();
+    /**
+     * What each binding effect writes into, keyed by the effect: one effect can read several
+     * signals and all of them drive the same place. A description, never the element.
+     */
+    const targets = new WeakMap();
+    /** The props object each component was handed, so its values can be read on request. */
+    const handed = new Map();
+    /**
+     * Where each binding was wired up. Taken at creation: the first run is scheduled, so by the
+     * time it reports, the frame that asked for it has left the stack.
+     */
+    const bindingSites = new WeakMap();
+    /**
+     * The element each binding writes into, weakly.
+     *
+     * `targets` describes elements rather than holding them, because holding one keeps a
+     * removed subtree alive. A WeakRef does not, so this can answer "show me that on the
+     * page" without pinning anything.
+     */
+    const boundTo = new WeakMap();
+    /** The reverse, for a pointer landing somewhere: element → the node driving it. */
+    const drivenBy = new WeakMap();
+    /** Per node, the elements it drives. Rebuilt each sample, like the descriptions are. */
+    let reaches = new Map();
+    /** Cleared on each sample: the page has moved on. */
+    let described = null;
+    /**
+     * What each tag rendered, weakly.
+     *
+     * A component's value is the dom it returned, so this is exact where the bindings are
+     * only nearby: a binding is recorded against the element containing it, which for a small
+     * component is whatever the page happens to have put it in.
+     */
+    const rendered = new Map();
+    /** The elements in a component's return value, however it was shaped. */
+    const elementsIn = (value) => {
+        if (value instanceof Element)
+            return [value];
+        if (value instanceof DocumentFragment)
+            return [...value.children];
+        // A component returning several roots hands back an array of nodes.
+        if (Array.isArray(value))
+            return value.flatMap(elementsIn);
+        return [];
+    };
+    const cores = new Map();
+    /**
+     * How to write each signal, when the runtime said.
+     *
+     * The core node can be set directly, and doing that marks its readers dirty without
+     * flushing them: the graph moves and the page does not. This is the application's own
+     * setter, so a write from a panel lands the same way a click would.
+     */
+    const setters = new Map();
+    const runsAtLastSample = new Map();
+    const unnamed = new Set();
+    const recording = (options.history ?? 200) > 0;
+    const wantSites = options.bindingSources ?? true;
+    /** A stack location in the author's terms, when the host can say. */
+    const mapped = (location) => {
+        if (!options.mapSource)
+            return location;
+        try {
+            // A mapper that cannot place a position must not turn a usable location into none.
+            const found = options.mapSource(location);
+            // The compiled position is kept: it distinguishes bindings the map cannot.
+            return found
+                ? { ...location, ...found, compiled: { line: location.line, column: location.column } }
+                : location;
+        }
+        catch {
+            return location;
+        }
+    };
+    const history = createHistory(options.history ?? 200);
+    let seq = 0;
+    /**
+     * The raw value each node last reported, so a write can be diffed against it. A formatted
+     * string cannot be. One reference per node, so this pins no more than the graph does.
+     */
+    const raws = new Map();
+    /** Untracked: this runs inside a write, and a tracked read would change what it watches. */
+    const readRaw = (node) => {
+        if (!node.read)
+            return undefined;
+        try {
+            return untrack(() => node.read());
+        }
+        catch {
+            // A reader that throws is not worth losing the event over.
+            return undefined;
+        }
+    };
+    /**
+     * Removals, kept rather than drained, each stamped with the revision it happened at.
+     *
+     * Draining meant whichever consumer polled first took them, and a page with both a
+     * browser panel and an editor panel watching has two. Bounded, because nothing here is
+     * ever consumed. A consumer older than the oldest entry is told to start again.
+     */
+    const removed = [];
+    /** Monotonic, bumped for every node the sample finds moved. */
+    let revision = 0;
+    /** The revision each node last moved at. */
+    const revs = new Map();
+    /** How far `takeRemoved` has drained, for a caller too old to keep a cursor of its own. */
+    let drained = 0;
+    /** What plugins asked to hear about. Empty unless one registered. */
+    const onDirective = [];
+    const onContext = [];
+    /** What plugins decided a node really is, applied once it has been named. */
+    const retyped = new Map();
+    /** Where each context was written, taken from the stack at the moment it was made. */
+    const contextSites = new Map();
+    /** What plugins attached to elements, by element then plugin name. */
+    const elementExtra = new WeakMap();
+    /** The nearest node the graph knows, looking outward through anything it does not. */
+    const ancestor = (parents) => {
+        if (!parents)
+            return undefined;
+        for (let i = parents.length - 1; i >= 0; i--) {
+            const key = parents[i];
+            const found = ids.get(key) ?? through.get(key);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    };
+    const stop = (options.observe ?? observeReactiveNodes)({
+        created(report) {
+            const core = report.node;
+            if (!core || typeof core !== 'object')
+                return;
+            if (report.internal) {
+                // Not drawn, but remembered: whatever it creates belongs to what created it, and
+                // what it reads is the reason a signal with no visible readers is not idle.
+                const owner = ancestor(report.parents);
+                if (owner !== undefined)
+                    through.set(core, owner);
+                internals.add(core);
+                if (wantSites) {
+                    // The package's frame when there is no application one: a binding inside a library
+                    // component is still somewhere. `external` marks the difference.
+                    const site = currentCallSite(origin);
+                    if (site)
+                        bindingSites.set(core, mapped(site.location));
+                }
+                return;
+            }
+            const id = seq++;
+            const handle = report.handle;
+            // One mark, one node, read here and nowhere else, matching the reactor.
+            const mark = takeReactiveSource();
+            // What a builtin tag is, decided from its name before anything reads its value.
+            //
+            // `Switch` names its own memo and returns a dom node, so nothing downstream carries a
+            // `$name` to recognise it by later. `Router`, `Suspense` and `Outlet` are not named by
+            // the runtime at all. What names them is the compiler's mark on the tag, and without
+            // reading that they stay plain memos and the tree lists them as values.
+            //
+            // A mark on a memo is a tag the compiler saw. On anything else it is whatever the
+            // author called their own value, so a signal someone named `Show` is left alone.
+            const base = KINDS[report.kind];
+            const marked = base === 'memo' && mark?.name ? KIND_OF_BUILTIN[mark.name] : undefined;
+            const kind = (report.name ? KIND_OF_BUILTIN[report.name] : undefined) ?? marked ?? base;
+            const named = report.name ?? mark?.name;
+            if (!named)
+                unnamed.add(id);
+            // Only for a node the compiler did not mark. This is called from inside the creating
+            // call, so the frames that led to it are still on the stack.
+            const site = mark?.location ? undefined : currentCallSite(origin);
+            const node = {
+                id,
+                label: named ?? `${PREFIX[kind]}${id}`,
+                kind,
+                // Only a compiler mark means the author wrote this and gave it that name. A name
+                // the runtime supplies, such as `Show.when`, `mapArray` or `row index`, describes framework
+                // machinery, and so does no name at all.
+                authored: mark?.name != null,
+                deps: new Set(),
+                // A write edge needs to know which consumer was running when a setter fired, and
+                // nothing observed records that. Reads carry the graph; writes do not.
+                writes: new Set(),
+                runs: 0,
+                lastPulse: 0,
+                core,
+                // The application's line is where it was asked for; a package's is where it was made,
+                // and for a node made while that package loaded it is the only thing there is.
+                ...(mark?.location ? { source: mark.location } : {}),
+                // Mapped, unlike `mark`: these two came off a stack, so they are positions in the
+                // compiled file until a host translates them.
+                ...(site && !site.external ? { usedAt: mapped(site.location) } : {}),
+                ...(site && site.external && !mark?.location ? { source: mapped(site.location) } : {}),
+            };
+            const owner = ancestor(report.parents);
+            if (owner !== undefined)
+                node.createdIn = owner;
+            // A node made on another's behalf, such as a store's key signal built the first time
+            // something reads it, belongs where that one was declared rather than where it was read.
+            const originId = report.origin ? ids.get(report.origin) : undefined;
+            const from = originId !== undefined ? graph.get(originId) : undefined;
+            if (from) {
+                node.createdIn = originId;
+                if (from.source)
+                    node.source = from.source;
+            }
+            // An effect returns nothing worth showing, so it has no reader and pulses on its runs.
+            if (kind !== 'effect' && typeof handle === 'function') {
+                // Not read here: a memo is lazy, and forcing it from inside its own creation would
+                // run the author's fn earlier than the app asked for. The first sample reads it.
+                const read = handle;
+                node.read = () => untrack(read);
+            }
+            ids.set(core, id);
+            // The accessor too: a node built on another's behalf names its owner by the handle it
+            // was given, which is the reader, not the core node behind it.
+            if (handle && (typeof handle === 'object' || typeof handle === 'function')) {
+                ids.set(handle, id);
+            }
+            cores.set(id, core);
+            if (typeof report.set === 'function')
+                setters.set(id, report.set);
+            graph.set(id, node);
+            history.created(id, node.createdIn, node.label);
+        },
+        ran(target) {
+            const id = ids.get(target);
+            if (id !== undefined) {
+                const node = graph.get(id);
+                if (node)
+                    node.runs++;
+                history.ran(id);
+            }
+        },
+        wrote(target, by) {
+            const writer = by ? ids.get(by) : undefined;
+            const written = ids.get(target);
+            if (written === undefined)
+                return;
+            // Nothing running: a handler, a timer, a socket, none of which the graph has a node
+            // for. Where it was called is all there is to say, and the stack still has it.
+            if (wantSites && writer === undefined) {
+                const node = graph.get(written);
+                const site = currentCallSite(origin);
+                if (node && site) {
+                    const seen = (node.setAt ??= []);
+                    const at = mapped(site.location);
+                    // One handler called two hundred times is one place.
+                    if (!seen.some((s) => s.file === at.file && s.line === at.line && s.column === at.column)) {
+                        if (seen.length >= SET_SITES)
+                            seen.shift();
+                        seen.push(at);
+                    }
+                }
+            }
+            // Before the edge check and whether or not anything was running: the write with no
+            // writer is the one the timeline is built around.
+            if (recording) {
+                const node = graph.get(written);
+                // The write has landed, so this is the new value; the old one was kept last time.
+                const after = node ? readRaw(node) : undefined;
+                const before = raws.get(written);
+                if (node)
+                    raws.set(written, after);
+                // Both sides cut to the same budget, or the arrow reads as two kinds of thing.
+                const shown = node?.detail ?? node?.value;
+                history.wrote(written, writer, {
+                    from: shown === undefined ? undefined : shorten(shown, HISTORY_VALUE),
+                    to: node ? shorten(formatValue(after, HISTORY_VALUE * 2), HISTORY_VALUE) : undefined,
+                    // Which row was added is the fact a reader is after.
+                    change: diffValues(before, after),
+                    label: node?.label,
+                });
+            }
+            // Only a write from inside a computation is an edge: a handler is not a node.
+            if (writer === undefined || writer === written)
+                return;
+            graph.get(writer)?.writes.add(written);
+        },
+        directive(node, target, kind, name, accessor) {
+            if (!onDirective.length)
+                return;
+            const core = node;
+            const owner = core && typeof core === 'object' ? ids.get(core) : undefined;
+            const at = holeLocation(accessor);
+            const report = {
+                owner: owner !== undefined ? (through.get(core) ?? owner) : undefined,
+                kind,
+                name,
+                element: describeNode(target),
+                target,
+                ...(at ? { at } : {}),
+            };
+            for (const fn of onDirective) {
+                try {
+                    fn(report);
+                }
+                catch {
+                    // A plugin with a bug does not get to stop the graph being built.
+                }
+            }
+        },
+        contextCreated(id) {
+            if (!onContext.length || contextSites.has(id))
+                return;
+            const site = currentCallSite(origin);
+            if (site)
+                contextSites.set(id, mapped(site.location));
+        },
+        context(node, id, kind, value) {
+            if (!onContext.length)
+                return;
+            const core = node;
+            const owner = core && typeof core === 'object' ? ids.get(core) : undefined;
+            const report = {
+                owner: owner !== undefined ? (through.get(core) ?? owner) : undefined,
+                id,
+                name: id.description || 'context',
+                ...(owner !== undefined ? { ownerLabel: graph.get(owner)?.label } : {}),
+                // Where the context itself was written. The provider's line is a fallback, and it
+                // reads as a lie when two providers share one context.
+                ...(contextSites.get(id) ?? graph.get(owner ?? -1)?.source
+                    ? { at: contextSites.get(id) ?? graph.get(owner ?? -1)?.source }
+                    : {}),
+                kind,
+                ...(value === undefined ? {} : { value: formatValue(value) }),
+            };
+            for (const fn of onContext) {
+                try {
+                    fn(report);
+                }
+                catch {
+                    /* ignored */
+                }
+            }
+        },
+        props(node, props) {
+            const core = node;
+            if (!core || typeof core !== 'object' || !props)
+                return;
+            const id = ids.get(core);
+            // Held, not read. Every prop is a getter over what the caller passed, so reading one
+            // here would subscribe whatever is running to it.
+            if (id !== undefined)
+                handed.set(id, props);
+        },
+        bound(node, target, kind, name, accessor) {
+            const core = node;
+            if (!core || typeof core !== 'object')
+                return;
+            // The compiler's mark first. It names the hole itself; the stack only names the call
+            // that built the template, which every binding in that template shares.
+            const hole = holeLocation(accessor);
+            const site = hole
+                ? { ...hole, file: bindingSites.get(core)?.file }
+                : bindingSites.get(core);
+            // A content hole is reported against its marker comment, which has no box to draw.
+            const box = target instanceof Element
+                ? target
+                : (target?.parentElement ?? undefined);
+            if (box)
+                boundTo.set(core, new WeakRef(box));
+            targets.set(core, {
+                kind,
+                element: describeNode(target),
+                ...(name ? { name } : {}),
+                ...(site ? { source: site } : {}),
+            });
+        },
+        moved(target, origin, name) {
+            const node = graph.get(ids.get(target) ?? -1);
+            if (!node)
+                return;
+            const owner = ids.get(origin);
+            if (owner !== undefined && graph.has(owner))
+                node.createdIn = owner;
+            if (name) {
+                node.label = name;
+                unnamed.delete(node.id);
+            }
+        },
+        disposed(target) {
+            internals.delete(target);
+            const id = ids.get(target);
+            if (id === undefined)
+                return;
+            removed.push({ id, rev: ++revision });
+            revs.delete(id);
+            if (removed.length > REMOVED_LOG)
+                removed.splice(0, removed.length - REMOVED_LOG);
+            // The label goes with it: nothing is left to look the name up in.
+            history.disposed(id, graph.get(id)?.label);
+            graph.delete(id);
+            handed.delete(id);
+            raws.delete(id);
+            cores.delete(id);
+            rendered.delete(id);
+            setters.delete(id);
+            runsAtLastSample.delete(id);
+            unnamed.delete(id);
+        },
+    });
+    /** What this node read on its last run, as ids: the edges the core already holds. */
+    const edges = (id, node) => {
+        const sources = cores.get(id)?.sources;
+        node.deps.clear();
+        if (!sources)
+            return;
+        for (const source of sources) {
+            const dep = ids.get(source);
+            if (dep !== undefined && dep !== id)
+                node.deps.add(dep);
+        }
+    };
+    const api = {
+        graph,
+        sample() {
+            described = null;
+            const changed = [];
+            /** Recorded once here, so every consumer can be told about it at its own pace. */
+            const moved = (id) => {
+                changed.push(id);
+                revs.set(id, ++revision);
+            };
+            const now = Date.now();
+            // What the dom reads, per node. Recounted rather than kept: a binding's sources change
+            // with every run, and a stale count is worse than none.
+            const bindings = new Map();
+            const drives = new Map();
+            const seen = new Map();
+            for (const internal of internals) {
+                const target = targets.get(internal);
+                const element = boundTo.get(internal);
+                for (const source of internal.sources ?? []) {
+                    const id = ids.get(source);
+                    if (id === undefined)
+                        continue;
+                    bindings.set(id, (bindings.get(id) ?? 0) + 1);
+                    if (element) {
+                        const found = element.deref();
+                        // First writer wins: an element driven by two values answers with the one that
+                        // reached it first, and the rest are still reachable from the node itself.
+                        if (found && !drivenBy.has(found))
+                            drivenBy.set(found, id);
+                        const held = seen.get(id);
+                        if (held)
+                            held.push(element);
+                        else
+                            seen.set(id, [element]);
+                    }
+                    if (!target)
+                        continue;
+                    const list = drives.get(id);
+                    if (list)
+                        list.push(target);
+                    else
+                        drives.set(id, [target]);
+                }
+            }
+            reaches = seen;
+            for (const node of graph.values()) {
+                const count = bindings.get(node.id) ?? 0;
+                if (node.bindings !== count)
+                    node.bindings = count || undefined;
+                const list = drives.get(node.id);
+                node.targets = list?.length ? list : undefined;
+            }
+            for (const node of graph.values()) {
+                if (!node.read) {
+                    edges(node.id, node);
+                    // A node absent from the table is one this call is seeing for the first time. It
+                    // counts as changed, or an effect would be created into a delta nobody sends.
+                    const seen = runsAtLastSample.get(node.id);
+                    if (seen === undefined || node.runs > seen) {
+                        node.lastPulse = now;
+                        moved(node.id);
+                    }
+                    runsAtLastSample.set(node.id, node.runs);
+                    continue;
+                }
+                const raw = node.read();
+                // For the next write to diff against; without it the first change has no entries.
+                if (recording)
+                    raws.set(node.id, raw);
+                // After the read: a memo that has never been pulled has no sources yet, and reading
+                // it is what makes it collect them.
+                edges(node.id, node);
+                // A memo holding something the runtime stamped a component name on is the wrapper
+                // the compiler put round that component, so it can say what the author wrote.
+                const stamped = raw?.$name;
+                if (node.kind === 'memo' && typeof stamped === 'string' && stamped && claims(node, raw)) {
+                    // A control-flow tag stamps its name the same way, so the name decides what this
+                    // is. Without it `Show` and `Match` are drawn as components the author wrote.
+                    node.kind = KIND_OF_BUILTIN[stamped] ?? 'component';
+                    node.declaredAt = componentSource(stamped);
+                    node.source ??= node.declaredAt;
+                    // Loaded as its own chunk. Worth saying: it explains a tag that only turns up after
+                    // a navigation, and a suspense boundary that had something to wait for.
+                    if (raw.$lazy)
+                        node.lazy = true;
+                    if (unnamed.has(node.id)) {
+                        node.label = stamped;
+                        unnamed.delete(node.id);
+                    }
+                }
+                // Whatever it returned, for a panel asking where this is on the page. Read every
+                // sample because a tag can re-render into different elements.
+                if (TREE_KINDS.has(node.kind)) {
+                    const found = elementsIn(raw);
+                    if (found.length)
+                        rendered.set(node.id, found.map((el) => new WeakRef(el)));
+                    const given = handed.get(node.id);
+                    if (given)
+                        node.props = readProps(given);
+                }
+                // Formatted once: the card shows the head of it, the tooltip and the inspector the
+                // rest. Reading the value twice would be reading a proxy twice.
+                const detail = formatValue(raw);
+                const next = shorten(detail);
+                if (next !== node.value || detail !== node.detail) {
+                    node.detail = detail;
+                    node.value = next;
+                    // A signal never recomputes, so a write is the only thing it can count.
+                    if (node.kind === 'state')
+                        node.runs++;
+                    node.lastPulse = now;
+                    moved(node.id);
+                }
+                runsAtLastSample.set(node.id, node.runs);
+            }
+            // After the promotion above, so a plugin's answer survives being named.
+            //
+            // Two limits, both because a kind decides more than a colour. Only a plain component
+            // is sharpened, so a Router that provides a context is still a Router. And only into
+            // another tag: every other kind is outside TREE_KINDS, which is what puts a node in
+            // the tree and lets it own the elements it rendered, so a component turned into a
+            // state would quietly take its whole subtree with it.
+            for (const [id, kind] of retyped) {
+                const node = graph.get(id);
+                if (node?.kind === 'component' && TREE_KINDS.has(kind))
+                    node.kind = kind;
+            }
+            // When something moved, and when a tag is still unnumbered. The first samples run
+            // before the elements are on the page, so without the second test the numbering only
+            // appeared after the first edit and the layout shifted under the user at that point.
+            // A still page with everything numbered does none of this.
+            const unnumbered = () => {
+                for (const node of graph.values()) {
+                    if (TREE_KINDS.has(node.kind) && node.order === undefined)
+                        return true;
+                }
+                return false;
+            };
+            if (changed.length || unnumbered())
+                stampDocumentOrder(graph, (of) => api.renderedFor(of));
+            return changed;
+        },
+        get revision() {
+            return revision;
+        },
+        takeRemoved() {
+            const out = removed.filter((entry) => entry.rev > drained).map((entry) => entry.id);
+            drained = revision;
+            return out;
+        },
+        changedSince(rev) {
+            const out = [];
+            for (const [id, at] of revs)
+                if (at > rev)
+                    out.push(id);
+            return out;
+        },
+        removedSince(rev) {
+            return removed.filter((entry) => entry.rev > rev).map((entry) => entry.id);
+        },
+        outrun(rev) {
+            return removed.length >= REMOVED_LOG && rev < removed[0].rev;
+        },
+        elementsFor(id) {
+            const live = [];
+            const collect = (from, where = reaches) => {
+                for (const ref of where.get(from) ?? []) {
+                    const found = ref.deref();
+                    // Still in the document: an element detached since the last sample is not
+                    // somewhere anything can be shown.
+                    if (found?.isConnected && !live.includes(found))
+                        live.push(found);
+                }
+            };
+            // What the tag itself rendered, which is exact.
+            collect(id, rendered);
+            if (live.length)
+                return live;
+            collect(id);
+            // A value drives the element its binding was recorded against. A tag that returned
+            // nothing usable falls back to where the values inside it reach.
+            if (!live.length) {
+                const inside = (node) => {
+                    const seen = new Set();
+                    let at = node.createdIn;
+                    while (at !== undefined && !seen.has(at)) {
+                        if (at === id)
+                            return true;
+                        seen.add(at);
+                        at = graph.get(at)?.createdIn;
+                    }
+                    return false;
+                };
+                for (const node of graph.values())
+                    if (inside(node))
+                        collect(node.id);
+            }
+            return live;
+        },
+        setValue(id, next) {
+            const node = graph.get(id);
+            const write = setters.get(id);
+            if (!node || node.kind !== 'state' || !write)
+                return false;
+            write(next);
+            return true;
+        },
+        renderedFor(id) {
+            const live = [];
+            for (const ref of rendered.get(id) ?? []) {
+                const found = ref.deref();
+                if (found?.isConnected && !live.includes(found))
+                    live.push(found);
+            }
+            return live;
+        },
+        domFor(id) {
+            // Built once per sample. Every tag needs the same element maps, and a page redraws
+            // this many times a second.
+            described ??= describeAll(graph, (of) => api.renderedFor(of), (of) => api.elementsFor(of), TREE_KINDS, (element) => elementExtra.get(element));
+            return described.get(id) ?? [];
+        },
+        nodeAt(element) {
+            // What rendered it, before what writes into it.
+            //
+            // `drivenBy` answers with the value that reached an element first, which for a row in
+            // a keyed list is the `For` that put it there rather than the component the row is.
+            // Picking a TodoItem, or anything inside one, therefore selected `For` every time.
+            //
+            // Several tags can claim one element, since a component returning another component's
+            // output shares it. The innermost is the one a pointer is over, so depth in the
+            // component nesting decides, the same way the dom description does.
+            const depth = tagDepths(graph, TREE_KINDS);
+            const rendering = new Map();
+            for (const node of graph.values()) {
+                if (!TREE_KINDS.has(node.kind))
+                    continue;
+                for (const found of api.renderedFor(node.id)) {
+                    const held = rendering.get(found);
+                    if (held === undefined || (depth.get(node.id) ?? 0) > (depth.get(held) ?? 0)) {
+                        rendering.set(found, node.id);
+                    }
+                }
+            }
+            for (let at = element; at; at = at.parentElement) {
+                const owner = rendering.get(at);
+                if (owner !== undefined && graph.has(owner))
+                    return owner;
+            }
+            // Nothing rendered it, so fall back to whatever writes into it.
+            for (let at = element; at; at = at.parentElement) {
+                const id = drivenBy.get(at);
+                if (id !== undefined && graph.has(id))
+                    return id;
+            }
+            return undefined;
+        },
+        takeEvents() {
+            return history.take();
+        },
+        detach() {
+            stop();
+            internals.clear();
+            graph.clear();
+            cores.clear();
+            rendered.clear();
+            setters.clear();
+            runsAtLastSample.clear();
+            unnamed.clear();
+            raws.clear();
+            history.clear();
+        },
+    };
+    // Started last, so a plugin adding a node finds the graph ready.
+    for (const plugin of devtoolsPlugins()) {
+        if (!plugin.collect)
+            continue;
+        const context = {
+            onDirective: (fn) => onDirective.push(fn),
+            onContext: (fn) => onContext.push(fn),
+            annotate: (id, data) => {
+                const node = graph.get(id);
+                if (node)
+                    (node.extra ??= {})[plugin.name] = data;
+            },
+            annotation: (id) => graph.get(id)?.extra?.[plugin.name],
+            // Remembered, not applied here. A component is still a memo when its context is
+            // provided, and the promotion that gives it its name only runs while it is one.
+            retype: (id, kind) => retyped.set(id, kind),
+            annotateElement: (target, data) => {
+                if (!target || typeof target !== 'object')
+                    return;
+                const held = elementExtra.get(target) ?? {};
+                held[plugin.name] = data;
+                elementExtra.set(target, held);
+            },
+            elementAnnotation: (target) => target && typeof target === 'object' ? elementExtra.get(target)?.[plugin.name] : undefined,
+            add: (spec) => {
+                const id = seq++;
+                graph.set(id, {
+                    id,
+                    label: spec.label,
+                    kind: spec.kind,
+                    deps: new Set(spec.deps ?? []),
+                    writes: new Set(),
+                    runs: 0,
+                    lastPulse: 0,
+                    authored: spec.authored ?? false,
+                    ...(spec.createdIn !== undefined ? { createdIn: spec.createdIn } : {}),
+                    ...(spec.value !== undefined ? { value: spec.value } : {}),
+                    ...(spec.detail !== undefined ? { detail: spec.detail } : {}),
+                    ...(spec.source ? { source: spec.source } : {}),
+                });
+                return id;
+            },
+        };
+        try {
+            plugin.collect(context);
+        }
+        catch {
+            /* ignored */
+        }
+    }
+    return api;
+}