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

package/dist/highlight.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Showing where something is on the page.
+ *
+ * Two things use this. Hovering a node in a panel draws a box round what it writes into, and
+ * picking works the other way: move over the page and the box follows whatever is under the
+ * pointer, until a click says which one.
+ *
+ * The overlay is not part of the application: it sits in its own fixed layer, takes no
+ * pointer events, and is torn down with `stop`. Nothing it holds outlives a call.
+ */
+/**
+ * Draw over everything `target` covers.
+ *
+ * A box each, rather than one around the lot: a component's regions are usually not
+ * adjacent, and a rectangle spanning them covers plenty it has nothing to do with. The
+ * label sits above the topmost.
+ *
+ * Called repeatedly while a pointer moves, so the boxes are reused rather than remade.
+ */
+export declare function showHighlight(target: Element | readonly Element[], text?: string): void;
+export declare function hideHighlight(): void;
+/** Take the overlay off the page. Safe to call when there is none. */
+export declare function removeHighlight(): void;
+export interface PickOptions {
+    /** The node under the pointer, for the box's label and for what a click reports. */
+    nodeAt: (element: Element | null) => number | undefined;
+    /**
+     * What the box is labelled. The element comes too, because the owning tag alone reads
+     * `App` over every heading and input that component wrote.
+     */
+    describe?: (id: number, element: Element) => string;
+    /**
+     * A click on something the graph knows. Picking stops first unless `sticky`.
+     *
+     * The element comes too: the owning tag alone is too coarse to be useful, since every
+     * `<h3>` and `<input>` a component wrote answers with that component.
+     */
+    onPick: (id: number, element: Element | null) => void;
+    /** Picking has ended: escape, or a click on nothing when it is not sticky. */
+    onCancel?: () => void;
+    /**
+     * Stay armed after a pick, so several elements can be chosen in a row. Escape and the
+     * returned stop still end it, and a click on nothing is ignored rather than cancelling.
+     */
+    sticky?: boolean;
+    /** Defaults to the page this module is running in. */
+    document?: Document;
+}
+/**
+ * Follow the pointer until something is clicked.
+ *
+ * Listeners are on the capture phase so the application never sees the click that chose an
+ * element, since picking a button should not press it. Returns a function that stops early.
+ */
+export declare function startPicking(options: PickOptions): () => void;
+//# sourceMappingURL=highlight.d.ts.map

package/dist/highlight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlight.d.ts","sourceRoot":"","sources":["../src/highlight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAyCH;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CA6CvF;AAED,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED,sEAAsE;AACtE,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AAED,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,KAAK,MAAM,GAAG,SAAS,CAAC;IACxD;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC;IACpD;;;;;OAKG;IACH,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,KAAK,IAAI,CAAC;IACtD,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,IAAI,CAkD7D"}

package/dist/highlight.js

@@ -0,0 +1,154 @@
+/**
+ * Showing where something is on the page.
+ *
+ * Two things use this. Hovering a node in a panel draws a box round what it writes into, and
+ * picking works the other way: move over the page and the box follows whatever is under the
+ * pointer, until a click says which one.
+ *
+ * The overlay is not part of the application: it sits in its own fixed layer, takes no
+ * pointer events, and is torn down with `stop`. Nothing it holds outlives a call.
+ */
+const LAYER = 'fx-highlight-layer';
+let overlay = null;
+function build(doc) {
+    const layer = doc.createElement('div');
+    layer.id = LAYER;
+    layer.style.cssText =
+        'position:fixed;inset:0;z-index:2147483646;pointer-events:none;contain:strict;';
+    const label = doc.createElement('div');
+    label.style.cssText =
+        'position:absolute;padding:1px 5px;border-radius:3px;background:#5eead4;color:#07131a;' +
+            "font:11px/1.5 ui-monospace,monospace;white-space:nowrap;";
+    layer.append(label);
+    doc.body.appendChild(layer);
+    return { layer, boxes: [], label };
+}
+function boxIn(overlay, index) {
+    const held = overlay.boxes[index];
+    if (held)
+        return held;
+    const box = overlay.layer.ownerDocument.createElement('div');
+    box.style.cssText =
+        'position:absolute;border:1px solid #5eead4;background:rgba(94,234,212,.16);' +
+            'border-radius:2px;transition:none;';
+    overlay.layer.append(box);
+    overlay.boxes.push(box);
+    return box;
+}
+/**
+ * Draw over everything `target` covers.
+ *
+ * A box each, rather than one around the lot: a component's regions are usually not
+ * adjacent, and a rectangle spanning them covers plenty it has nothing to do with. The
+ * label sits above the topmost.
+ *
+ * Called repeatedly while a pointer moves, so the boxes are reused rather than remade.
+ */
+export function showHighlight(target, text) {
+    const elements = (Array.isArray(target) ? target : [target]).filter((el) => el?.isConnected);
+    const first = elements[0];
+    const doc = first?.ownerDocument;
+    if (!doc?.body) {
+        hideHighlight();
+        return;
+    }
+    // Rebuilt when the document changed, or when the page removed the layer from under us.
+    if (!overlay || overlay.layer.ownerDocument !== doc || !overlay.layer.isConnected) {
+        overlay = build(doc);
+    }
+    const { label, layer } = overlay;
+    layer.style.display = '';
+    let top = Infinity;
+    let left = Infinity;
+    let bottom = 0;
+    elements.forEach((element, index) => {
+        const rect = element.getBoundingClientRect();
+        const box = boxIn(overlay, index);
+        box.style.display = '';
+        box.style.left = `${rect.left}px`;
+        box.style.top = `${rect.top}px`;
+        box.style.width = `${rect.width}px`;
+        box.style.height = `${rect.height}px`;
+        top = Math.min(top, rect.top);
+        left = Math.min(left, rect.left);
+        bottom = Math.max(bottom, rect.bottom);
+    });
+    // Whatever the last target needed and this one does not.
+    for (let i = elements.length; i < overlay.boxes.length; i++) {
+        overlay.boxes[i].style.display = 'none';
+    }
+    if (!text) {
+        label.style.display = 'none';
+        return;
+    }
+    label.style.display = '';
+    label.textContent = text;
+    label.style.left = `${Math.max(2, left)}px`;
+    label.style.top = top >= 20 ? `${top - 18}px` : `${bottom + 4}px`;
+}
+export function hideHighlight() {
+    if (overlay)
+        overlay.layer.style.display = 'none';
+}
+/** Take the overlay off the page. Safe to call when there is none. */
+export function removeHighlight() {
+    overlay?.layer.remove();
+    overlay = null;
+}
+/**
+ * Follow the pointer until something is clicked.
+ *
+ * Listeners are on the capture phase so the application never sees the click that chose an
+ * element, since picking a button should not press it. Returns a function that stops early.
+ */
+export function startPicking(options) {
+    const doc = options.document ?? globalThis.document;
+    if (!doc?.body)
+        return () => { };
+    const was = doc.body.style.cursor;
+    doc.body.style.cursor = 'crosshair';
+    const under = (event) => {
+        const target = event.target;
+        // Inside the overlay is not a pick; it should not be hit anyway, but a page can move it.
+        return target?.closest?.(`#${LAYER}`) ? null : target;
+    };
+    const move = (event) => {
+        const element = under(event);
+        const id = options.nodeAt(element);
+        if (element && id !== undefined)
+            showHighlight(element, options.describe?.(id, element));
+        else
+            hideHighlight();
+    };
+    const click = (event) => {
+        event.preventDefault();
+        event.stopPropagation();
+        const target = under(event);
+        const id = options.nodeAt(target);
+        if (!options.sticky)
+            stop();
+        if (id !== undefined)
+            options.onPick(id, target);
+        // Only a real end reports a cancel. A sticky miss leaves the pointer armed, so saying
+        // it ended would put the toolbar out of step with the listeners still attached.
+        else if (!options.sticky)
+            options.onCancel?.();
+    };
+    const key = (event) => {
+        if (event.key !== 'Escape')
+            return;
+        stop();
+        options.onCancel?.();
+    };
+    const stop = () => {
+        doc.body.style.cursor = was;
+        doc.removeEventListener('pointermove', move, true);
+        doc.removeEventListener('click', click, true);
+        doc.removeEventListener('keydown', key, true);
+        hideHighlight();
+    };
+    doc.addEventListener('pointermove', move, true);
+    doc.addEventListener('click', click, true);
+    doc.addEventListener('keydown', key, true);
+    return stop;
+}

package/dist/history.d.ts

@@ -0,0 +1,59 @@
+import type { ValueChange } from './diff.js';
+export type GraphEventKind = 'write' | 'ran' | 'created' | 'disposed';
+export interface GraphEvent {
+    /** Monotonic across the session, so a consumer folding deltas never reorders them. */
+    readonly seq: number;
+    /** Producer clock, matching the snapshot's. */
+    readonly t: number;
+    readonly kind: GraphEventKind;
+    /** The node it happened to. */
+    readonly id: number;
+    /** What caused it. Absent on a write means nothing was running: an event handler did it. */
+    readonly by?: number;
+    /** One write from outside and everything it caused. Commit 0 is the first render. */
+    readonly commit: number;
+    /** Writes only: the value before and after, already formatted and short. */
+    readonly from?: string;
+    readonly to?: string;
+    /** Writes only, and only when the two sides differ structurally: which entries moved. */
+    readonly change?: ValueChange;
+    /**
+     * The name at the time. A consumer normally reads it off the graph, but a disposed node is
+     * no longer there — and a list re-render is mostly disposals — so it travels with the event.
+     */
+    readonly label?: string;
+}
+/** What a write is worth recording about, beyond who did it. */
+export interface WriteDetail {
+    from?: string;
+    to?: string;
+    change?: ValueChange;
+    label?: string;
+}
+export interface History {
+    wrote(id: number, by: number | undefined, detail?: WriteDetail): void;
+    ran(id: number, by?: number): void;
+    created(id: number, by?: number, label?: string): void;
+    disposed(id: number, label?: string): void;
+    /** Everything since the last call. Draining is what keeps a producer nobody polls bounded. */
+    take(): GraphEvent[];
+    /** How many events were dropped for being older than the limit. */
+    readonly dropped: number;
+    clear(): void;
+}
+/** Keep the last `limit`. An app nobody is polling still runs effects. */
+export declare function createHistory(limit: number): History;
+/** One commit, as a reader of the timeline sees it. */
+export interface Commit {
+    readonly commit: number;
+    readonly t: number;
+    readonly events: GraphEvent[];
+    /** The write that opened it, if the buffer still holds it. */
+    readonly cause?: GraphEvent;
+}
+/**
+ * Oldest first. A commit whose opening write has aged out still groups — its events carry the
+ * number, and a partial commit beats dropping the runs after it.
+ */
+export declare function toCommits(events: readonly GraphEvent[]): Commit[];
+//# sourceMappingURL=history.d.ts.map

package/dist/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,KAAK,GAAG,SAAS,GAAG,UAAU,CAAC;AAEtE,MAAM,WAAW,UAAU;IACzB,sFAAsF;IACtF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACtE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvD,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,8FAA8F;IAC9F,IAAI,IAAI,UAAU,EAAE,CAAC;IACrB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;CACf;AAaD,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CA4CpD;AAED,uDAAuD;AACvD,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,EAAE,CAejE"}

package/dist/history.js

@@ -0,0 +1,85 @@
+// What happened, in order.
+//
+// A snapshot says what the graph is; by the time a panel polls, the propagation is over and
+// everything reads as settled. So the observer's callbacks are recorded as they arrive — the
+// runtime calls them from inside the write, so the order is real rather than reconstructed.
+//
+// Events group into commits: a write with nothing running came from a handler and opens one.
+// Deferred effects land in the commit that scheduled them.
+/** Records nothing and costs nothing, for `history: 0`. */
+const OFF = {
+    wrote() { },
+    ran() { },
+    created() { },
+    disposed() { },
+    take: () => [],
+    dropped: 0,
+    clear() { },
+};
+/** Keep the last `limit`. An app nobody is polling still runs effects. */
+export function createHistory(limit) {
+    if (limit <= 0)
+        return OFF;
+    let events = [];
+    let seq = 0;
+    let commit = 0;
+    let dropped = 0;
+    const push = (event) => {
+        events.push({ ...event, seq: seq++, t: Date.now(), commit });
+        if (events.length > limit) {
+            dropped += events.length - limit;
+            events = events.slice(-limit);
+        }
+    };
+    return {
+        wrote(id, by, detail) {
+            // Nothing running: it came from outside, which is where a reader wants the cut.
+            if (by === undefined)
+                commit++;
+            push({ kind: 'write', id, by, ...detail });
+        },
+        ran(id, by) {
+            push({ kind: 'ran', id, by });
+        },
+        created(id, by, label) {
+            push({ kind: 'created', id, by, label });
+        },
+        disposed(id, label) {
+            push({ kind: 'disposed', id, label });
+        },
+        take() {
+            const taken = events;
+            events = [];
+            return taken;
+        },
+        get dropped() {
+            return dropped;
+        },
+        clear() {
+            events = [];
+            dropped = 0;
+        },
+    };
+}
+/**
+ * Oldest first. A commit whose opening write has aged out still groups — its events carry the
+ * number, and a partial commit beats dropping the runs after it.
+ */
+export function toCommits(events) {
+    const byNumber = new Map();
+    for (const event of events) {
+        const bucket = byNumber.get(event.commit);
+        if (bucket)
+            bucket.push(event);
+        else
+            byNumber.set(event.commit, [event]);
+    }
+    return [...byNumber.entries()]
+        .sort((a, b) => a[0] - b[0])
+        .map(([commit, group]) => ({
+        commit,
+        t: group[0].t,
+        events: group,
+        cause: group.find((e) => e.kind === 'write' && e.by === undefined),
+    }));
+}

package/dist/hook.d.ts

@@ -0,0 +1,60 @@
+import { type ObservedGraph } from './observe.js';
+import { type GraphSnapshot } from './wire.js';
+export interface DevtoolsHook {
+    /**
+     * Called by the runtime when it loads.
+     *
+     * `watch` is how the caller says it brought its own devtools. Two copies live on a page
+     * routinely — a browser extension injects one at document_start and an application's own
+     * agent loads another — and the first to arrive owns the hook. Without this the graph is
+     * built by whichever copy got there first, which for an installed extension is a build
+     * that knows nothing of the compiler that made the application.
+     */
+    inject(runtime: {
+        observeReactiveNodes: (o: never) => () => void;
+        version: string;
+        watch?: (options: {
+            observe: (o: never) => () => void;
+        }) => ObservedGraph;
+    }): void;
+    /** The graph, once a runtime has turned up. */
+    readonly observed: ObservedGraph | null;
+    /** The version of the runtime that injected, for a panel reporting what it is attached to. */
+    readonly version: string | null;
+    /**
+     * How many copies of this module tried to install one.
+     *
+     * Ordinarily two: an extension's and the application's own. Worth having for a panel
+     * reporting what it is attached to; which one watches is settled by `inject`.
+     */
+    readonly copies: number;
+    /**
+     * Everything, or only what moved after `since`.
+     *
+     * The cursor comes back on every snapshot; a consumer folding in deltas keeps it and
+     * hands it back. Asking consumes nothing, so a page with a browser panel and an editor
+     * panel watching at the same time gives each of them every change. Draining a shared
+     * one meant whichever polled first took them.
+     *
+     * A cursor older than the removal log gets a full snapshot instead, since there is no
+     * longer any way to say what went missing.
+     */
+    snapshot(options?: {
+        partial?: boolean;
+        since?: number;
+    }): GraphSnapshot | null;
+    /**
+     * Draw the overlay over something in the page, for a panel that is not in it.
+     *
+     * A number is a node, and covers everywhere it reaches. A string is one element, written
+     * as the tree keys them: the tag's id, the index of the root it rendered, then a child
+     * index per step — `12:0/1/2`. Null clears it.
+     */
+    highlight(target: number | string | null): void;
+}
+/**
+ * Install the hook. Returns the existing one if something got there first, so two agents on
+ * one page share a graph rather than each seeing half of it.
+ */
+export declare function installDevtoolsHook(): DevtoolsHook;
+//# sourceMappingURL=hook.d.ts.map

package/dist/hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../src/hook.ts"],"names":[],"mappings":"AAYA,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAEhE,OAAO,EAAmC,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAQhF,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,EAAE;QACd,oBAAoB,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,MAAM,IAAI,CAAC;QAC/C,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE;YAAE,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,MAAM,IAAI,CAAA;SAAE,KAAK,aAAa,CAAC;KAC3E,GAAG,IAAI,CAAC;IACT,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IACxC,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,aAAa,GAAG,IAAI,CAAC;IAChF;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;CACjD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,YAAY,CAiHlD"}

package/dist/hook.js

@@ -0,0 +1,142 @@
+// The agent side of the rendezvous.
+//
+// A browser extension or a dev-server injection runs this before the application loads. It
+// leaves a global behind; when the app's copy of @fluixi/reactive is first evaluated, the
+// runtime finds it and hands over its own `observeReactiveNodes`. The graph is then built
+// from the app's framework rather than this bundle's — two copies of the runtime each keep
+// their own nodes, so watching the wrong one shows an empty graph.
+//
+// The app imports nothing and knows nothing about this. It also works against a production
+// build: the reporting calls are unconditional, so only the names and source locations are
+// missing there.
+import { withoutElements } from './dom.js';
+import { observeGraph } from './observe.js';
+import { hideHighlight, showHighlight } from './highlight.js';
+import { serializeGraph } from './wire.js';
+/** A few hundred interactions' worth. */
+const HISTORY = 500;
+/** Kept in step with the name in @fluixi/reactive's observe.ts. */
+const HOOK = '__FLUIXI_DEVTOOLS_HOOK__';
+/**
+ * Install the hook. Returns the existing one if something got there first, so two agents on
+ * one page share a graph rather than each seeing half of it.
+ */
+export function installDevtoolsHook() {
+    const host = globalThis;
+    const existing = host[HOOK];
+    if (existing) {
+        // Counted, not complained about. Two copies is the ordinary case — an extension injects
+        // one before anything else runs and the application's agent loads another — and `inject`
+        // sorts out which of them ends up watching.
+        existing.copies = (existing.copies ?? 1) + 1;
+        return existing;
+    }
+    let observed = null;
+    /** Whether whoever is watching brought its own devtools, rather than being given this one. */
+    let owned = false;
+    let version = null;
+    /** What has happened, for whoever asks. Bounded: nothing here is ever consumed. */
+    const history = [];
+    const hook = {
+        copies: 1,
+        inject(runtime) {
+            version = runtime.version;
+            if (!observed) {
+                observed = (runtime.watch ?? observeGraph)({ observe: runtime.observeReactiveNodes });
+                owned = runtime.watch !== undefined;
+                return;
+            }
+            // The runtime injects the moment it is evaluated, and it brings no devtools of its
+            // own — so an extension's copy starts watching first. The application's agent runs
+            // straight after, before any of its own modules have made a node, and hands over an
+            // observer that matches the compiler that built it. That one takes over.
+            if (owned || !runtime.watch)
+                return;
+            observed.detach();
+            observed = runtime.watch({ observe: runtime.observeReactiveNodes });
+            owned = true;
+        },
+        get observed() {
+            return observed;
+        },
+        get version() {
+            return version;
+        },
+        highlight(target) {
+            if (!observed || target === null) {
+                hideHighlight();
+                return;
+            }
+            if (typeof target === 'number') {
+                const found = observed.elementsFor(target);
+                if (found.length)
+                    showHighlight(found, observed.graph.get(target)?.label);
+                else
+                    hideHighlight();
+                return;
+            }
+            // Walked through the description rather than the elements, because that is what the
+            // keys were built from: a tag's roots there include what it was mounted into and what
+            // it writes to, neither of which it rendered.
+            const [head, ...steps] = target.split('/');
+            const [tag, root] = (head ?? '').split(':');
+            let node = observed.domFor(Number(tag))[Number(root)];
+            for (const step of steps)
+                node = node?.children[Number(step)];
+            const element = node?.element;
+            if (element)
+                showHighlight(element, element.tagName.toLowerCase());
+            else
+                hideHighlight();
+        },
+        snapshot({ partial = false, since } = {}) {
+            if (!observed)
+                return null;
+            // Detection is shared and has to run: it is what notices anything moved at all.
+            const changed = observed.sample();
+            const cursor = observed.revision;
+            // Kept, not handed out once. The hook can have more than one reader — a dev server
+            // agent polling and a browser panel open at the same time — and draining here gave
+            // each of them whichever events the other had not taken yet. Every event carries a
+            // seq, so a reader keeps what is new to it.
+            history.push(...observed.takeEvents());
+            if (history.length > HISTORY)
+                history.splice(0, history.length - HISTORY);
+            const events = history.slice();
+            // Described, not held: whoever reads this snapshot is usually not in the page, and the
+            // elements would only cross as empty objects anyway.
+            const dom = (id) => {
+                const described = observed.domFor(id);
+                return described.length ? withoutElements(described) : undefined;
+            };
+            // The observer can be older than this hook. The application hands its own over and the
+            // two are built separately, so a cursor is only offered when it can be honoured.
+            const cursors = typeof observed.changedSince === 'function';
+            // Everything, and the cursor to come back with. Also the answer for a consumer that
+            // has fallen further behind than the log reaches.
+            const whole = partial === false || since === undefined || !cursors || observed.outrun(since);
+            if (whole) {
+                // An older observer cannot say what was dropped after a revision, so a delta from
+                // it would quietly keep nodes that are gone. Everything, every time, is correct.
+                if (partial && !cursors) {
+                    return serializeGraph(observed.graph, Date.now(), {
+                        ids: changed,
+                        removed: observed.takeRemoved(),
+                        events,
+                        dom,
+                    });
+                }
+                return serializeGraph(observed.graph, Date.now(), { events, dom, cursor });
+            }
+            return serializeGraph(observed.graph, Date.now(), {
+                ids: observed.changedSince(since),
+                removed: observed.removedSince(since),
+                events,
+                dom,
+                cursor,
+            });
+        },
+    };
+    host[HOOK] = hook;
+    return hook;
+}

package/dist/index.d.ts

@@ -1,5 +1,48 @@
 export { createReactor, nodeVersion, nodeState } from './instrument.js';
 export type { Reactor, ReactorApi, RNode, NodeKind, NodeState } from './instrument.js';
+export { observeGraph } from './observe.js';
+export type { ObservedGraph, ObserveOptions } from './observe.js';
+export { installDevtoolsHook } from './hook.js';
+export type { DevtoolsHook } from './hook.js';
+export { formatValue, shorten } from './format.js';
+export { callSite, currentCallSite } from './callsite.js';
+export { serializeGraph, snapshotToRenderMap, applySnapshot } from './wire.js';
+export type { GraphSnapshot, WireNode, SerializeOptions } from './wire.js';
+export { toCommits } from './history.js';
+export type { GraphEvent, GraphEventKind, Commit, History } from './history.js';
+export { markReactiveSource } from './source.js';
+export type { ReactiveSourceLocation, ReactiveSourceMetadata } from './source.js';
 export { createGraphView, DEVTOOLS_CSS } from './graph-view.js';
-export type { GraphView, GraphViewOptions } from './graph-view.js';
+export { createInspector, INSPECTOR_CSS } from './inspector.js';
+export { createValuePane, VALUE_PANE_CSS } from './value-pane.js';
+export type { ValuePane } from './value-pane.js';
+export { indentValue } from './format.js';
+export type { Inspector, InspectorOptions, ElementInspection } from './inspector.js';
+export { createTimeline, TIMELINE_CSS } from './timeline.js';
+export type { Timeline, TimelineOptions } from './timeline.js';
+export { shortenPath } from './path.js';
+export { registerDevtoolsPlugin, devtoolsPlugins, annotationOf, pluginRows, pluginBadge } from './plugin.js';
+export type { DevtoolsPlugin, CollectContext, DirectiveReport, PluginNode, PluginRow, } from './plugin.js';
+export { createComponentTree, componentTree, TREE_KINDS, TREE_CSS } from './tree.js';
+export { showHighlight, hideHighlight, removeHighlight, startPicking } from './highlight.js';
+export { makeFloatable, FLOAT_CSS } from './float.js';
+export type { Floatable, FloatOptions } from './float.js';
+export type { PickOptions } from './highlight.js';
+export type { ComponentTree, ComponentTreeOptions, TreeNode, ElementPick } from './tree.js';
+export { createKindFilter, FILTERABLE_KINDS, DROPDOWN_FILTER_CSS, KIND_FILTER_CSS } from './kind-filter.js';
+export type { KindFilter, KindFilterOptions } from './kind-filter.js';
+export type { DomNode } from './dom.js';
+export { createMenu, MENU_CSS } from './menu.js';
+export type { Menu, MenuItem, MenuOptions } from './menu.js';
+export { createDetailPanel, DETAIL_PANEL_CSS } from './detail-panel.js';
+export type { DetailPanel, DetailPanelOptions } from './detail-panel.js';
+export { changeRows, handleCopyClick, CHANGE_CSS } from './change-view.js';
+export { copyText } from './copy.js';
+export { exportGraph, graphToJson } from './export.js';
+export type { ExportedGraph, ExportOptions } from './export.js';
+export { diffValues } from './diff.js';
+export type { ValueChange, ChangeEntry, ChangeOp } from './diff.js';
+export { describeNode } from './describe.js';
+export type { DomTarget } from './instrument.js';
+export type { GraphView, GraphViewOptions, GraphDirection } from './graph-view.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACxE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAChE,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}