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

package/dist/source.js

@@ -0,0 +1,153 @@
+/**
+ * Where a reactive node was created.
+ *
+ * The compiler marks each creation site in development (`sourceLocations`) by calling the
+ * global installed here, just before the statement that makes the node. The instrumented
+ * primitive takes the mark and keeps it on the graph node.
+ *
+ * A single slot, not a stack: in `signal(compute(signal(1)))` the inner call takes the mark
+ * and the outer gets none, rather than claiming a location that is not its own.
+ */
+/** Kept in step with SOURCE_MARKER and COMPONENT_MARKER in the compiler. */
+const MARKER = '__fx_source';
+const COMPONENT_MARKER = '__fx_component';
+const HOLE_MARKER = '__fx_hole';
+const PROPS_MARKER = '__fx_props';
+const MARKS = '__FLUIXI_DEVTOOLS_MARKS__';
+const host = globalThis;
+const shared = host[MARKS] ?? {
+    pending: null,
+    expiring: false,
+    components: new Map(),
+};
+host[MARKS] = shared;
+/**
+ * Where each component was declared, by name.
+ *
+ * The graph sees the memo the compiler wraps a component in, and all that memo carries back
+ * is the name stamped on what the component returned — so name is the only key available.
+ * Two components sharing a name are recorded as ambiguous and reported as unknown, since a
+ * location pointing at the wrong file is worse than none.
+ */
+/**
+ * Record where the next node is about to be created. The compiler calls this; call it
+ * yourself only for a node the compiler cannot see, immediately before the primitive.
+ */
+export function markReactiveSource(file, line, column, name) {
+    const location = locate(file, line, column);
+    // With dependencies marked, `signal()` in the framework marks its own `createSignal` line
+    // in between the application's mark and the node it asked for. The call site is the useful
+    // location, so a dependency never takes a mark the project has already left unclaimed.
+    if (shared.pending && location.external && !shared.pending.location?.external)
+        return;
+    shared.pending = { name, location };
+    shared.expiring = false;
+}
+/**
+ * A project file is named relative to the project root, so anything absolute or under
+ * node_modules came from a dependency. Derived here rather than sent, so the mark the
+ * compiler emits stays the four arguments it has always been.
+ */
+function locate(file, line, column) {
+    const external = !!file && (/^([a-zA-Z]:)?[\\/]/.test(file) || file.includes('node_modules/'));
+    return external ? { file, line, column, external } : { file, line, column };
+}
+/** Record where a component was declared. The compiler calls this. */
+export function markComponentSource(name, file, line, column) {
+    const seen = shared.components.get(name);
+    const next = locate(file, line, column);
+    if (seen === undefined) {
+        shared.components.set(name, next);
+        return;
+    }
+    if (!seen || seen.file !== file || seen.line !== line)
+        shared.components.set(name, null);
+}
+/** Where a component of this name was declared, when exactly one was. */
+export function componentSource(name) {
+    return shared.components.get(name) ?? undefined;
+}
+/**
+ * Reading keeps it for the rest of the turn.
+ *
+ * One statement can make several nodes: `createStore({ a, b })` builds a signal per key
+ * inside the framework, and all of them belong to the line that asked for the store. So the
+ * mark survives the read and is dropped on the next microtask, which is the end of the
+ * statement that left it as far as anything synchronous is concerned.
+ */
+export function takeReactiveSource() {
+    const mark = shared.pending;
+    if (mark) {
+        // The variable name belongs to the node the author was declaring, not to the ones the
+        // framework built underneath it — `cart`, then two unnamed signals at the same line.
+        if (mark.name !== undefined)
+            shared.pending = { location: mark.location };
+        if (!shared.expiring) {
+            shared.expiring = true;
+            queueMicrotask(() => {
+                shared.expiring = false;
+                shared.pending = null;
+            });
+        }
+    }
+    return mark;
+}
+/** Never replaces an existing marker: two copies of devtools would each hold half the marks. */
+/**
+ * Where each hole was written, by the accessor the compiler stamped. Keyed by the function,
+ * not a slot: it is built and read at different moments.
+ */
+const HOLES = new WeakMap();
+/**
+ * Also written onto the accessor itself, because the runtime does not always hand the same
+ * object on to `insert`: hydration wraps an accessor so the cursor can be replaced when it
+ * is finally read. The wrapper copies this across, and the WeakMap alone would miss it.
+ */
+const HOLE_TAG = '__fx_at';
+/** Returns the accessor, not a wrapper: it is the binding's value. */
+function markHole(accessor, line, column, name) {
+    if (accessor && (typeof accessor === 'object' || typeof accessor === 'function')) {
+        const at = name === undefined ? { line, column } : { line, column, name };
+        HOLES.set(accessor, at);
+        try {
+            Object.defineProperty(accessor, HOLE_TAG, { value: at, configurable: true });
+        }
+        catch {
+            // Frozen or a proxy that refuses writes; the WeakMap still covers the unwrapped case.
+        }
+    }
+    // The template is being built, so whatever declaration left a mark is finished with. A
+    // mark outlives the statement that set it on purpose — a store's key signals are made
+    // inside the call and belong to its line — but a component body is one long synchronous
+    // run, and without this every node the template makes claimed the last signal's position.
+    shared.pending = null;
+    return accessor;
+}
+/** Where each prop of a component tag was written, by the props object it was passed in. */
+const PROPS = new WeakMap();
+/** Returns the props object untouched: it is what the component is about to be handed. */
+function markProps(props, at) {
+    if (props && typeof props === 'object')
+        PROPS.set(props, at);
+    return props;
+}
+/** Where the props of this object were written, when the compiler recorded them. */
+export function propsLocations(props) {
+    return props && typeof props === 'object' ? PROPS.get(props) : undefined;
+}
+/** The hole an accessor came from, when the compiler marked it. */
+export function holeLocation(accessor) {
+    if (!accessor || (typeof accessor !== 'object' && typeof accessor !== 'function'))
+        return undefined;
+    return HOLES.get(accessor) ?? accessor[HOLE_TAG];
+}
+export function installSourceMarker() {
+    if (typeof host[MARKER] !== 'function')
+        host[MARKER] = markReactiveSource;
+    if (typeof host[COMPONENT_MARKER] !== 'function')
+        host[COMPONENT_MARKER] = markComponentSource;
+    if (typeof host[HOLE_MARKER] !== 'function')
+        host[HOLE_MARKER] = markHole;
+    if (typeof host[PROPS_MARKER] !== 'function')
+        host[PROPS_MARKER] = markProps;
+}

package/dist/timeline.d.ts

@@ -0,0 +1,30 @@
+import { type Commit, type GraphEvent } from './history.js';
+import type { RNode } from './instrument.js';
+export interface Timeline {
+    /** Fold in what a snapshot carried. Events already seen are ignored, so polling is safe. */
+    push(events: readonly GraphEvent[]): void;
+    /** Stop taking new events, or start again. Paused, what is on screen holds still. */
+    setPaused(paused: boolean): void;
+    readonly paused: boolean;
+    /** Draw. `graph` supplies the labels, which the events only carry ids for. */
+    render(graph: Map<number, RNode>): void;
+    /** Node ids in the selected commit, for a view to highlight. Empty when none is selected. */
+    selected(): number[];
+    clear(): void;
+}
+export interface TimelineOptions {
+    /** What to say before anything has happened. */
+    empty?: string;
+    /** How many commits to keep. */
+    limit?: number;
+    /** A commit was selected, or deselected with null. */
+    onSelect?(ids: number[], commit: Commit | null): void;
+    /** A side panel can say six rows changed; it cannot show six before-and-after objects. */
+    onExpand?(commit: Commit): void;
+}
+/** The graph first, since a node can be renamed; then the name the event carried. */
+export type NameOf = (event: GraphEvent) => string;
+export declare function createTimeline(host: HTMLElement, options?: TimelineOptions): Timeline;
+/** Default styling for what createTimeline writes, in the shape DEVTOOLS_CSS is used. */
+export declare const TIMELINE_CSS = "\n.tl-head { position: relative; display: flex; gap: 4px; padding: 0 .25rem; }\n.tl-pause {\n  position: absolute; right: .4rem; top: 40%; transform: translateY(-50%);\n  flex: none; width: 26px; cursor: pointer; font: inherit; font-size: 10px;\n  border: 1px solid var(--fx-line, #ffffff1f); border-radius: 4px;\n  background: transparent; color: var(--fx-muted, #8a90a2);\n}\n.tl-pause:hover { color: var(--fx-label, #e7e9ee); }\n.tl-pause.on { color: var(--fx-accent, #5eead4); border-color: var(--fx-accent, #5eead4); }\n.tl-filter {\n  flex: 1; min-width: 0; box-sizing: border-box; padding: 3px 6px;\n  font: inherit; font-size: 11.5px; border-radius: 4px;\n  border: 1px solid var(--fx-line, #ffffff1f);\n  background: var(--fx-input, transparent); color: var(--fx-label, #e7e9ee);\n  padding-inline-end: 2rem;\n}\n.tl-empty { color: var(--fx-muted, #8a90a2); font-size: 12px; }\n.tl-commit { padding: 4px 6px; border-radius: 4px; cursor: pointer; font-size: 11.5px; }\n.tl-commit:hover { background: var(--fx-hover, #ffffff10); }\n.tl-commit.selected { background: var(--fx-selected, #ffffff1a); }\n.tl-line { display: flex; align-items: baseline; gap: 6px; }\n.tl-caret { color: var(--fx-muted, #8a90a2); font-size: 9px; flex: none; }\n.tl-time { font-family: ui-monospace, monospace; font-size: 10px; color: var(--fx-muted, #8a90a2); flex: none; }\n.tl-name { color: var(--fx-label, #e7e9ee); font-family: ui-monospace, monospace; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n.tl-did { margin-left: auto; color: var(--fx-muted, #8a90a2); flex: none; }\n.tl-body { margin: 3px 0 2px 15px; }\n/* Wraps: an open entry exists to show the whole value. */\n.tl-change {\n  font-family: ui-monospace, monospace; font-size: 11px;\n  color: var(--fx-accent, #5eead4); overflow-wrap: anywhere; white-space: pre-wrap;\n}\n.tl-part { margin-top: 2px; color: var(--fx-label, #e7e9ee); font-size: 11px; overflow-wrap: anywhere; }\n.tl-verb { color: var(--fx-muted, #8a90a2); }\n.tl-more {\n  margin-top: 5px; padding: 2px 8px; font: inherit; font-size: 10.5px; cursor: pointer;\n  border: 1px solid var(--fx-line, #ffffff1f); border-radius: 4px;\n  background: transparent; color: var(--fx-muted, #8a90a2);\n}\n.tl-more:hover { color: var(--fx-label, #e7e9ee); }\n\n.ch-list { margin-top: 4px; font-family: ui-monospace, monospace; font-size: 11px; }\n.ch-size { color: var(--fx-muted, #8a90a2); margin-bottom: 2px; }\n.ch-row { display: flex; gap: 6px; align-items: baseline; padding: 1px 0; }\n.ch-row.ch-stacked { align-items: flex-start; padding: 3px 0; }\n.ch-sign { flex: none; width: 9px; text-align: center; }\n.ch-added .ch-sign { color: var(--state, #34d399); }\n.ch-removed .ch-sign { color: var(--fx-write, #fb7185); }\n.ch-changed .ch-sign { color: var(--effect, #fbbf24); }\n.ch-key { flex: none; color: var(--fx-muted, #8a90a2); }\n.ch-sides { min-width: 0; flex: 1; overflow-wrap: anywhere; }\n.ch-stacked .ch-sides { display: flex; flex-direction: column; gap: 2px; }\n.ch-from { color: var(--fx-muted, #8a90a2); }\n.ch-row:not(.ch-stacked) .ch-from { text-decoration: line-through; }\n.ch-arrow { color: var(--fx-muted, #8a90a2); margin: 0 4px; }\n.ch-to { color: var(--fx-label, #e7e9ee); }\n.ch-more { color: var(--fx-muted, #8a90a2); margin-top: 2px; }\n/* In the corner: an object can be tall, and a button under it is a scroll away. */\n.ch-block { position: relative; border-radius: 4px; border: 1px solid var(--fx-line, #ffffff14); }\n.ch-block.ch-from { opacity: .72; }\n.ch-json { margin: 0; padding: 5px 7px; overflow-x: auto; white-space: pre; font: inherit; }\n.ch-copy {\n  position: absolute; top: 3px; right: 3px; padding: 1px 6px; cursor: pointer;\n  font: inherit; font-size: 9.5px; opacity: 0; transition: opacity .12s;\n  border: 1px solid var(--fx-line, #ffffff26); border-radius: 3px;\n  background: var(--fx-panel, #14161c); color: var(--fx-muted, #8a90a2);\n}\n.ch-block:hover .ch-copy, .ch-copy:focus { opacity: 1; }\n.ch-copy:hover { color: var(--fx-label, #e7e9ee); }\n";
+//# sourceMappingURL=timeline.d.ts.map

package/dist/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../src/timeline.ts"],"names":[],"mappings":"AAOA,OAAO,EAAa,KAAK,MAAM,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEvE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAE7C,MAAM,WAAW,QAAQ;IACvB,4FAA4F;IAC5F,IAAI,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAAC;IAC1C,qFAAqF;IACrF,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,8EAA8E;IAC9E,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC;IACxC,6FAA6F;IAC7F,QAAQ,IAAI,MAAM,EAAE,CAAC;IACrB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,QAAQ,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IACtD,0FAA0F;IAC1F,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAWD,qFAAqF;AACrF,MAAM,MAAM,MAAM,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC;AA6CnD,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE,eAAoB,GAAG,QAAQ,CAwLzF;AAED,yFAAyF;AACzF,eAAO,MAAM,YAAY,o8HAwCX,CAAC"}

package/dist/timeline.js

@@ -0,0 +1,271 @@
+// The history, as something to read.
+//
+// Commits, not a flat log: one click makes a write, four runs and a disposal, interleaved with
+// whatever the router was doing. Grouped, they read as "this is what that click did".
+//
+// Newest first, and re-rendered only when it would say something different — a panel that
+// repaints on every poll cannot be scrolled or selected.
+import { toCommits } from './history.js';
+import { changeRows, handleCopyClick, CHANGE_CSS } from './change-view.js';
+const escape = (text) => text.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+const clock = (t) => {
+    const d = new Date(t);
+    const pad = (n, width = 2) => String(n).padStart(width, '0');
+    return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}`;
+};
+/** The name of what the commit started from: `count`, or what to say when there is none. */
+function subject(commit, nameOf) {
+    if (!commit.cause)
+        return commit.commit === 0 ? 'first render' : 'continued';
+    return nameOf(commit.cause);
+}
+/** `0 → 1`, when the write carried both sides of it. */
+function change(commit) {
+    const cause = commit.cause;
+    if (!cause || cause.from === undefined || cause.to === undefined)
+        return '';
+    return `${cause.from} → ${cause.to}`;
+}
+/** The whole of it, for the tooltip: the row elides, this does not. */
+function detail(commit, nameOf) {
+    const lines = [`${subject(commit, nameOf)} ${change(commit)}`.trim()];
+    const named = (kind, verb) => {
+        const ids = commit.events.filter((e) => e.kind === kind && e !== commit.cause).map(nameOf);
+        if (ids.length)
+            lines.push(`${verb}: ${[...new Set(ids)].join(', ')}`);
+    };
+    named('ran', 'ran');
+    named('write', 'written');
+    named('created', 'made');
+    named('disposed', 'gone');
+    return lines.join('\n');
+}
+/** "2 ran · 1 created" — what the commit caused, without listing every line of it. */
+function summary(commit) {
+    const counts = { ran: 0, created: 0, disposed: 0, write: 0 };
+    for (const event of commit.events)
+        counts[event.kind]++;
+    // The opening write is the title, so it is not also a thing the commit did.
+    const writes = counts.write - (commit.cause ? 1 : 0);
+    return [
+        counts.ran && `${counts.ran} ran`,
+        writes > 0 && `${writes} written`,
+        counts.created && `${counts.created} made`,
+        counts.disposed && `${counts.disposed} gone`,
+    ]
+        .filter(Boolean)
+        .join(' · ');
+}
+export function createTimeline(host, options = {}) {
+    const empty = options.empty ?? 'nothing has happened yet';
+    const limit = options.limit ?? 100;
+    let events = [];
+    /** The highest seq folded in. Every producer counts up, so this is all dedupe needs. */
+    let seen = -1;
+    /** Selected, expanded and lit on the graph are one state: all three say "this one". */
+    let selected = null;
+    let filter = '';
+    let signature = '';
+    /**
+     * Held still on request.
+     *
+     * A page that writes on every frame fills this faster than anyone can read it, and the
+     * entry being looked at scrolls away. Dropped rather than buffered: catching up on a
+     * thousand events nobody watched is not what the button is for.
+     */
+    let paused = false;
+    // Built once: re-rendering the box being typed in would take the caret with it.
+    host.innerHTML =
+        '<div class="tl-head">' +
+            '<input class="tl-filter" type="search" placeholder="filter by name or value" aria-label="Filter the timeline" />' +
+            '<button type="button" class="tl-pause" title="Stop taking new updates, so the list holds still while you read it">❚❚</button>' +
+            '</div>' +
+            '<div class="tl-list"></div>';
+    const input = host.querySelector('.tl-filter');
+    const list = host.querySelector('.tl-list');
+    const pause = host.querySelector('.tl-pause');
+    const all = () => toCommits(events).slice(-limit).reverse();
+    const idsOf = (commit) => {
+        const ids = new Set();
+        for (const event of commit.events) {
+            ids.add(event.id);
+            if (event.by !== undefined)
+                ids.add(event.by);
+        }
+        return [...ids];
+    };
+    /** Everything the row says, which is what a reader is searching against. */
+    const haystack = (commit, nameOf) => `${detail(commit, nameOf)} ${summary(commit)}`.toLowerCase();
+    const shown = (nameOf) => filter ? all().filter((c) => haystack(c, nameOf).includes(filter)) : all();
+    input.addEventListener('input', () => {
+        filter = input.value.trim().toLowerCase();
+        signature = '';
+    });
+    const showPaused = () => {
+        pause.textContent = paused ? '▶' : '❚❚';
+        pause.classList.toggle('on', paused);
+        pause.title = paused
+            ? 'Taking updates again'
+            : 'Stop taking new updates, so the list holds still while you read it';
+    };
+    pause.addEventListener('click', () => {
+        paused = !paused;
+        showPaused();
+        signature = '';
+    });
+    list.addEventListener('click', (e) => {
+        // Copying from an open row must not also shut it.
+        if (handleCopyClick(e))
+            return;
+        const row = e.target?.closest?.('.tl-commit');
+        if (!row)
+            return;
+        const number = Number(row.dataset.commit);
+        // Inside the row, so it would otherwise shut what it was opening.
+        if (e.target.classList.contains('tl-more')) {
+            const full = all().find((c) => c.commit === number);
+            if (full)
+                options.onExpand?.(full);
+            return;
+        }
+        // Clicking the open one shuts it — the only way back to watching everything.
+        selected = selected === number ? null : number;
+        const commit = all().find((c) => c.commit === selected) ?? null;
+        options.onSelect?.(commit ? idsOf(commit) : [], commit);
+        signature = '';
+    });
+    return {
+        setPaused(next) {
+            paused = next;
+            showPaused();
+            signature = '';
+        },
+        get paused() {
+            return paused;
+        },
+        push(incoming) {
+            if (paused)
+                return;
+            let added = false;
+            for (const event of incoming) {
+                if (event.seq <= seen)
+                    continue;
+                events.push(event);
+                seen = event.seq;
+                added = true;
+            }
+            if (!added)
+                return;
+            // Bounded by commits: cutting mid-commit shows a click with half of what it caused.
+            if (events.length > limit * 40)
+                events = events.slice(-limit * 40);
+        },
+        render(graph) {
+            const nameOf = (e) => graph.get(e.id)?.label ?? e.label ?? `#${e.id}`;
+            const rows = shown(nameOf);
+            const next = `${seen}|${selected ?? ''}|${filter}|${rows.length}|${graph.size}`;
+            if (next === signature)
+                return;
+            signature = next;
+            if (!rows.length) {
+                // With a filter typed, "nothing has happened" would read as recording being broken.
+                list.innerHTML = `<span class="tl-empty">${escape(filter ? 'nothing matches' : empty)}</span>`;
+                return;
+            }
+            list.innerHTML = rows
+                .map((commit) => {
+                const open = commit.commit === selected;
+                const did = summary(commit);
+                const moved = change(commit);
+                const parts = [
+                    ['ran', 'ran'],
+                    ['write', 'written'],
+                    ['created', 'made'],
+                    ['disposed', 'gone'],
+                ];
+                const body = parts
+                    .map(([kind, verb]) => {
+                    const names = [
+                        ...new Set(commit.events.filter((e) => e.kind === kind && e !== commit.cause).map(nameOf)),
+                    ];
+                    return names.length
+                        ? `<div class="tl-part"><span class="tl-verb">${verb}</span> ${escape(names.join(', '))}</div>`
+                        : '';
+                })
+                    .join('');
+                return (`<div class="tl-commit${open ? ' selected' : ''}"` +
+                    ` data-commit="${commit.commit}" title="${escape(detail(commit, nameOf))}">` +
+                    '<div class="tl-line">' +
+                    `<span class="tl-caret">${open ? '▾' : '▸'}</span>` +
+                    `<span class="tl-time">${clock(commit.t)}</span>` +
+                    `<span class="tl-name">${escape(subject(commit, nameOf))}</span>` +
+                    (did ? `<span class="tl-did">${escape(did)}</span>` : '') +
+                    '</div>' +
+                    // Open, the value gets the width and wraps.
+                    (open
+                        ? `<div class="tl-body">${moved ? `<div class="tl-change">${escape(moved)}</div>` : ''}${changeRows(commit.cause?.change, 6)}${body}${
+                        // Only worth offering when there is more than the row can hold.
+                        options.onExpand && (commit.cause?.change || commit.events.length > 6)
+                            ? '<button type="button" class="tl-more">open in full</button>'
+                            : ''}</div>`
+                        : '') +
+                    '</div>');
+            })
+                .join('');
+        },
+        selected() {
+            const commit = all().find((c) => c.commit === selected);
+            return commit ? idsOf(commit) : [];
+        },
+        clear() {
+            events = [];
+            seen = -1;
+            selected = null;
+            signature = '';
+            // The filter box stays: a new run is usually a rerun of what they were narrowing to.
+            list.innerHTML = `<span class="tl-empty">${escape(empty)}</span>`;
+        },
+    };
+}
+/** Default styling for what createTimeline writes, in the shape DEVTOOLS_CSS is used. */
+export const TIMELINE_CSS = `
+.tl-head { position: relative; display: flex; gap: 4px; padding: 0 .25rem; }
+.tl-pause {
+  position: absolute; right: .4rem; top: 40%; transform: translateY(-50%);
+  flex: none; width: 26px; cursor: pointer; font: inherit; font-size: 10px;
+  border: 1px solid var(--fx-line, #ffffff1f); border-radius: 4px;
+  background: transparent; color: var(--fx-muted, #8a90a2);
+}
+.tl-pause:hover { color: var(--fx-label, #e7e9ee); }
+.tl-pause.on { color: var(--fx-accent, #5eead4); border-color: var(--fx-accent, #5eead4); }
+.tl-filter {
+  flex: 1; min-width: 0; box-sizing: border-box; padding: 3px 6px;
+  font: inherit; font-size: 11.5px; border-radius: 4px;
+  border: 1px solid var(--fx-line, #ffffff1f);
+  background: var(--fx-input, transparent); color: var(--fx-label, #e7e9ee);
+  padding-inline-end: 2rem;
+}
+.tl-empty { color: var(--fx-muted, #8a90a2); font-size: 12px; }
+.tl-commit { padding: 4px 6px; border-radius: 4px; cursor: pointer; font-size: 11.5px; }
+.tl-commit:hover { background: var(--fx-hover, #ffffff10); }
+.tl-commit.selected { background: var(--fx-selected, #ffffff1a); }
+.tl-line { display: flex; align-items: baseline; gap: 6px; }
+.tl-caret { color: var(--fx-muted, #8a90a2); font-size: 9px; flex: none; }
+.tl-time { font-family: ui-monospace, monospace; font-size: 10px; color: var(--fx-muted, #8a90a2); flex: none; }
+.tl-name { color: var(--fx-label, #e7e9ee); font-family: ui-monospace, monospace; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.tl-did { margin-left: auto; color: var(--fx-muted, #8a90a2); flex: none; }
+.tl-body { margin: 3px 0 2px 15px; }
+/* Wraps: an open entry exists to show the whole value. */
+.tl-change {
+  font-family: ui-monospace, monospace; font-size: 11px;
+  color: var(--fx-accent, #5eead4); overflow-wrap: anywhere; white-space: pre-wrap;
+}
+.tl-part { margin-top: 2px; color: var(--fx-label, #e7e9ee); font-size: 11px; overflow-wrap: anywhere; }
+.tl-verb { color: var(--fx-muted, #8a90a2); }
+.tl-more {
+  margin-top: 5px; padding: 2px 8px; font: inherit; font-size: 10.5px; cursor: pointer;
+  border: 1px solid var(--fx-line, #ffffff1f); border-radius: 4px;
+  background: transparent; color: var(--fx-muted, #8a90a2);
+}
+.tl-more:hover { color: var(--fx-label, #e7e9ee); }
+${CHANGE_CSS}`;

package/dist/tree.d.ts

@@ -0,0 +1,128 @@
+/**
+ * What the page is made of, as a tree.
+ *
+ * The graph answers which value depends on which. It does not answer what the page is built
+ * from, and that is the question a tree is for: `<Router>` holding a `<Counter>` and an
+ * `<Another>`, each openable to see what it holds.
+ *
+ * Both are drawn from the same nodes. A component's place in the tree is `createdIn`, the
+ * node whose run made it, lifted through everything that is not itself a tag, since the
+ * compiler wraps each component in a memo and that memo is not something anyone wrote.
+ */
+import type { NodeKind, RNode } from './instrument.js';
+import type { DomNode } from './dom.js';
+/** Kinds that are tags in the source, and so have a place in a tree of them. */
+export declare const TREE_KINDS: ReadonlySet<NodeKind>;
+export interface TreeNode {
+    id: number;
+    label: string;
+    kind: NodeKind;
+    children: TreeNode[];
+    /** A value the author declared rather than a tag they wrote. */
+    value?: boolean;
+    /** Came down as its own chunk. */
+    lazy?: boolean;
+    /** What a plugin wants said beside the label. */
+    badge?: string;
+}
+/**
+ * An element row, for a host that wants to say something about one.
+ *
+ * An element is not a node, so it has no id to select. What it does have is the tag it
+ * belongs to and the values writing into it, which between them are what there is to say.
+ */
+export interface ElementPick {
+    /** The row key, which doubles as a path to the element. */
+    key: string;
+    /** The element as a selector: `div#app.card`. */
+    label: string;
+    owner?: number;
+    writes?: number[];
+    /** Where the element itself was written, when the build recorded it. */
+    at?: {
+        file: string;
+        line: number;
+        column: number;
+    };
+    /** What plugins attached to this element. */
+    extra?: Record<string, unknown>;
+    /** Only in a host that is in the page. */
+    element?: Element;
+}
+/** Whatever the host can say about the dom under a tag. Elements only when it has them. */
+export type { DomNode } from './dom.js';
+/**
+ * The tags in `graph`, each under the tag that made it.
+ *
+ * Ordered by id, which is creation order, so siblings read down the page the way they were
+ * rendered. A node whose ancestors are all untagged is a root.
+ */
+export interface TreeOptions {
+    /**
+     * Also list the reactive values each tag made: the signals and memos the author wrote
+     * inside it. Machinery is left out: a node the framework named itself does not count, so
+     * a component shows `count` and not the memo it was wrapped in.
+     *
+     * Only an explicit `authored: false` is machinery. A graph read from the source says
+     * nothing either way, and everything in it was written by hand.
+     */
+    values?: boolean;
+    /**
+     * Keep only what this names, and whatever holds it. An ancestor is kept even when its own
+     * name does not match, since dropping it would leave the match with nothing above it.
+     */
+    filter?: string;
+}
+/**
+ * Put the tags that rendered back into page order, leaving everything else untouched.
+ *
+ * Sorting by id alone reads as creation order, which is wrong for a keyed list: rebuilding a
+ * row hands the replacement the highest id, so the row you edited jumped to the bottom.
+ *
+ * Only the slots those tags already occupy are reshuffled. Sorting the whole list by `order`
+ * instead sent every value to the end of its band, so editing a todo moved the `left` memo
+ * as well, which had nothing to do with the change.
+ */
+export declare function inPageOrder<T extends {
+    order?: number;
+}>(nodes: T[]): T[];
+export declare function componentTree(graph: Map<number, RNode>, options?: TreeOptions): TreeNode[];
+/** Every id in the tree, for a caller that wants to open or shut all of it. */
+export declare function idsIn(nodes: readonly TreeNode[]): number[];
+export interface ComponentTreeOptions {
+    /** Clicking a row. The host decides what selecting means, usually the inspector. */
+    onSelect?: (id: number) => void;
+    /**
+     * Clicking an element row. Elements have no id, so a host that leaves this out gets no
+     * selection for them at all, which is what made half the tree look inert.
+     */
+    onPick?: (pick: ElementPick) => void;
+    /** Double-clicking a row, for a host that can open the file it came from. */
+    onReveal?: (id: number) => void;
+    /** Double-clicking an element row. */
+    onRevealPick?: (pick: ElementPick) => void;
+    /**
+     * The row under the pointer, and null on the way out. For a host that can reach the page
+     * and show where the node writes. An element row gives the element itself, which needs no
+     * looking up.
+     */
+    onHover?: (id: number | null, element?: Element, path?: string) => void;
+    /**
+     * What each tag rendered. A host in the page walks its own elements; one reading a
+     * snapshot passes what the producer described. Omitted draws tags only.
+     */
+    domFor?: (id: number) => readonly DomNode[];
+    /** What to say when nothing has rendered yet. */
+    empty?: string;
+    /** Start with the values shown. @default false */
+    values?: boolean;
+}
+export interface ComponentTree {
+    /** Draw `graph`, with `selected` marked. Cheap to call every frame. */
+    render(graph: Map<number, RNode>, selected?: number | null): void;
+    clear(): void;
+    destroy(): void;
+}
+export declare function createComponentTree(host: HTMLElement, options?: ComponentTreeOptions): ComponentTree;
+export declare const TREE_CSS: string;
+//# sourceMappingURL=tree.d.ts.map

package/dist/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../src/tree.ts"],"names":[],"mappings":"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"}