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

package/README.md

@@ -9,7 +9,7 @@ import { createReactor, createGraphView, DEVTOOLS_CSS } from '@fluixi/devtools';
 const reactor = createReactor();
 reactor.run(({ createSignal, createMemo, createEffect }) => {
   const [count, setCount] = createSignal(0, { name: 'count' });
-  const double = createMemo(() => count() * 2, { name: 'double' });
+  const double = createMemo(() => count() * 2, undefined, { name: 'double' });
   createEffect(() => console.log(double()), { name: 'log' });
   setInterval(() => setCount((n) => n + 1), 1000);
 });
@@ -21,13 +21,91 @@ tick();
 
 ## How it works
 
-The instrumented `signal`/`memo`/`effect` wrap the real `@fluixi/reactive` primitives. A read is a
+The instrumented `createSignal`/`createMemo`/`createEffect` wrap the real `@fluixi/reactive`
+primitives. A read is a
 subscription, so edges are recorded from actual reads — it's the genuine dependency graph, not a
 reconstruction. Values are re-read untracked each frame and effects count their own re-runs, so the
 inspector animates exactly as the core propagates.
 
+## Watching an app you did not write
+
+createReactor hands out its own primitives, so it only sees code written against them. observeGraph() sees an ordinary app: the runtime reports each node as it is made, and the graph fills from plain `import { signal } from '@fluixi/core'`. Call it before the app's modules load — a node made earlier is not in the graph.
+
+```ts
+import { observeGraph, createGraphView } from '@fluixi/devtools';
+const observed = observeGraph();
+await import('./src/main.js');
+const view = createGraphView(svgEl);
+const tick = () => { observed.sample(); view.update(observed.graph); requestAnimationFrame(tick); };
+tick();
+```
+
+The same Map<number, RNode> the reactor produces, so createGraphView and anything else reading the graph does not care which made it. Dependencies are read off the core node, which already keeps its own sources and observers, so nothing is wrapped and no read is intercepted.
+
+No write edges, because nothing records which computation was running when a setter fired. Render effects are left out — the dom layer makes one per binding. An unwatched runtime pays one null check per node creation and per recompute.
+
+## Getting the graph somewhere else
+
+serializeGraph flattens the graph to json — Sets become arrays, the live core node becomes version and state, the reader is dropped — and snapshotToRenderMap turns it back into something the view draws. sample() returns what moved, so a delta is the same call with those ids, and applySnapshot folds one into a graph already on screen.
+
+installDevtoolsHook() is for a tool that cannot be imported by the app. It leaves a global behind; when the application's runtime loads it finds it and hands over its own registration function, so the graph is built from the app's copy of the framework rather than the tool's. It has to be installed before the app runs — a browser agent at document_start — because the runtime offers once. It works against a production build too, without names or locations.
+
+```js
+import { installDevtoolsHook } from '@fluixi/devtools';
+const hook = installDevtoolsHook();          // before the app loads
+// …the app runs…
+hook.snapshot();                  // everything
+hook.snapshot({ partial: true }); // only what moved since the last call
+```
+
+Read edges survive the trip; write edges do not exist on an observed graph, since nothing records which computation was running when a setter fired.
+
+## Where a node came from
+
+A graph node can carry an optional source: file, line and column of the place the author created it, plus the variable name when the source gave one. Every field optional, and the whole thing absent for a node the compiler did not see.
+
+The compiler marks each creation site when `sourceLocations` is on, the mark names the file and position from the original source rather than the generated output, and the instrumented primitive takes the mark and keeps it on the node:
+
+```ts
+// what the compiler emits in development
+globalThis.__fx_source?.("src/App.ts", 10, 15, "count");
+const count = signal(0);
+```
+
+A renderer needs nothing else — no compiler, no source file, no ast — and file, line and column are enough for a host to decide how to open it. For example:
+
+```ts
+for (const node of reactor.graph.values()) {
+  if (node.source) {
+    console.log(node.label, `${node.source.file}:${node.source.line}:${node.source.column}`);
+  }
+}
+```
+
+The compiler wraps every component in a memo, so the graph sees the wrapper rather than the component. A node whose value carries a component's name reports its kind as `component` and takes that name as its label, so the graph reads `App` rather than `m5`. Nothing about the node changes — it is the same memo, with the same dependencies.
+
+A component node's `source` is where its tag was written, which is where the node was made — the same meaning `source` has for every other kind. `declaredAt` is where the component itself was declared, which is usually another file. It stands in for `source` when nothing marked the tag, and two components sharing a name are reported without a location rather than with the wrong one.
+
+### Making a node the compiler cannot see
+
+For a primitive built at runtime, call `markReactiveSource` yourself immediately before it, since the next node created takes the mark:
+
+```ts
+import { markReactiveSource } from '@fluixi/devtools';
+
+markReactiveSource('src/factory.ts', 8, 2, 'fromFactory');
+const s = signal(0);
+```
+
+A production build should leave `sourceLocations` off and then carries none of it. One statement carries one mark, so `signal(compute(signal(1)))` labels the inner call and leaves the outer bare rather than giving it a location that is not its own.
+
 ## API
 
 - `createReactor()` → `{ graph, run(setup), sample(), dispose() }`
+- `observeGraph()` → `{ graph, sample(), detach() }`
+- `installDevtoolsHook()` → the global a tool attaches through
+- `serializeGraph(graph, now?, { ids, removed }?)` / `snapshotToRenderMap(snapshot)`
+- `applySnapshot(graph, snapshot)` — fold a full snapshot or a delta into what is drawn
+- `formatValue(value, limit?)` — a printable rendering of any value; never throws
 - `createGraphView(svg)` → `{ update(graph, now?), clear() }`
 - `DEVTOOLS_CSS` — default theme string (override the `fx-*` classes to restyle)

package/dist/callsite.d.ts

@@ -0,0 +1,22 @@
+import type { ReactiveSourceLocation } from './source.js';
+/**
+ * Where a node came from, and whether that is the application or something it depends on.
+ *
+ * The application's own frame is the useful one, but a node made while a package was loading
+ * has no application frame above it at all — a router's revalidation counter, made when its
+ * module is evaluated. Falling back to the package's own frame is what stops that node being
+ * a card with no name, no origin and no explanation.
+ */
+export declare function callSite(stack: string | undefined, origin?: string): {
+    location: ReactiveSourceLocation;
+    external: boolean;
+} | undefined;
+/**
+ * The call site of whatever is being created right now. Called from inside the observer, so
+ * the frames of the creating call are still on the stack.
+ */
+export declare function currentCallSite(origin?: string): {
+    location: ReactiveSourceLocation;
+    external: boolean;
+} | undefined;
+//# sourceMappingURL=callsite.d.ts.map

package/dist/callsite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callsite.d.ts","sourceRoot":"","sources":["../src/callsite.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAqD1D;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,QAAQ,EAAE,sBAAsB,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAgBrE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,QAAQ,EAAE,sBAAsB,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAErE"}

package/dist/callsite.js

@@ -0,0 +1,82 @@
+/**
+ * A browser extension's own bundle.
+ *
+ * The devtools agent carries a copy of this package, so every frame inside it looked like
+ * application code and every node reported `chrome-extension://…/agent.js` as its origin.
+ * Nothing under these schemes is ever the page's own source.
+ */
+const EXTENSION = ['chrome-extension://', 'moz-extension://', 'safari-web-extension://', 'extension://'];
+/** Frames that are the machinery rather than the caller. */
+const INTERNAL = [
+    '/packages/reactive/',
+    '/packages/dom/',
+    '/packages/core/',
+    '/packages/devtools/',
+    '/@fluixi/',
+    'node_modules',
+    'fluixi-devtools',
+    ...EXTENSION,
+];
+/** The plumbing that reports a node, which is never worth naming as its origin. */
+const REPORTING = [
+    '/packages/reactive/src/lib/signal/graph/',
+    '/packages/devtools/',
+    'fluixi-devtools',
+    // Not a fallback either: naming the agent as where a node came from is worse than nothing.
+    ...EXTENSION,
+];
+/** `at name (url:line:col)` and `at url:line:col`, which is the whole of what is needed. */
+const FRAME = /(?:at\s+(?:[^(]*\()?)([^()\s]+):(\d+):(\d+)\)?$/;
+const isInternal = (frame) => INTERNAL.some((part) => frame.includes(part));
+/**
+ * The first frame that is not the framework's own.
+ *
+ * `origin` trims a dev server's url back to a project path, so a location reads
+ * `src/App.tsx:6` rather than `http://localhost:5173/src/App.tsx?t=1712`.
+ */
+function locate(frame, origin) {
+    const match = FRAME.exec(frame);
+    if (!match)
+        return undefined;
+    let file = match[1];
+    // A dev server serves a project file at its own origin, with a cache-busting query.
+    if (origin && file.startsWith(origin))
+        file = file.slice(origin.length);
+    file = file.replace(/^\/@fs\//, '/').replace(/\?.*$/, '').replace(/^\//, '');
+    return file ? { file, line: Number(match[2]), column: Number(match[3]) } : undefined;
+}
+/**
+ * Where a node came from, and whether that is the application or something it depends on.
+ *
+ * The application's own frame is the useful one, but a node made while a package was loading
+ * has no application frame above it at all — a router's revalidation counter, made when its
+ * module is evaluated. Falling back to the package's own frame is what stops that node being
+ * a card with no name, no origin and no explanation.
+ */
+export function callSite(stack, origin) {
+    if (!stack)
+        return undefined;
+    let fallback;
+    for (const line of stack.split('\n')) {
+        const frame = line.trim();
+        if (!frame.startsWith('at '))
+            continue;
+        if (!isInternal(frame)) {
+            const location = locate(frame, origin);
+            if (location)
+                return { location, external: false };
+            continue;
+        }
+        // The first frame that is a package rather than the reporting machinery itself.
+        if (!fallback && !REPORTING.some((part) => frame.includes(part)))
+            fallback = locate(frame, origin);
+    }
+    return fallback ? { location: { ...fallback, external: true }, external: true } : undefined;
+}
+/**
+ * The call site of whatever is being created right now. Called from inside the observer, so
+ * the frames of the creating call are still on the stack.
+ */
+export function currentCallSite(origin) {
+    return callSite(new Error().stack, origin);
+}

package/dist/change-view.d.ts

@@ -0,0 +1,10 @@
+import type { ValueChange } from './diff.js';
+/** Empty when there is nothing structural: a plain value is already on the row above. */
+export declare function changeRows(change: ValueChange | undefined, limit?: number): string;
+/**
+ * Delegated: the rows are rebuilt on every render and per-button listeners would go with them.
+ * True when the click was a copy, so a host does not also treat it as a click on the row.
+ */
+export declare function handleCopyClick(event: Event): boolean;
+export declare const CHANGE_CSS = "\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=change-view.d.ts.map

package/dist/change-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-view.d.ts","sourceRoot":"","sources":["../src/change-view.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAgC7C,yFAAyF;AACzF,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,KAAK,SAAW,GAAG,MAAM,CAmCpF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAKrD;AAED,eAAO,MAAM,UAAU,0tDA6BtB,CAAC"}

package/dist/change-view.js

@@ -0,0 +1,102 @@
+// A diff, drawn. Shared between the timeline's open row and the panel that opens from it —
+// same rows, cut to a handful in the sidebar and shown in full when there is room.
+//
+// An object is drawn as an object: `{id: 1, text: "go"}` on one line is what the cards
+// already say.
+import { copyText } from './copy.js';
+const escape = (text) => text.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+const SIGN = { added: '+', removed: '−', changed: '~' };
+/** Indented JSON, or nothing when the value was not JSON to begin with. */
+function pretty(json) {
+    if (!json)
+        return undefined;
+    try {
+        return JSON.stringify(JSON.parse(json), null, 2);
+    }
+    catch {
+        // It came from JSON.stringify, so this should not happen — but a malformed payload is
+        // not worth losing the row over.
+        return undefined;
+    }
+}
+/** Structured values get a block with a copy button; a number on three lines is worse. */
+function sideOf(text, json, cls) {
+    const block = pretty(json);
+    if (!block)
+        return `<span class="ch-${cls}">${escape(text ?? '')}</span>`;
+    return (`<div class="ch-block ch-${cls}">` +
+        `<button type="button" class="ch-copy" title="Copy" data-copy="${escape(block)}">copy</button>` +
+        `<pre class="ch-json">${escape(block)}</pre>` +
+        '</div>');
+}
+/** Empty when there is nothing structural: a plain value is already on the row above. */
+export function changeRows(change, limit = Infinity) {
+    if (!change?.entries?.length)
+        return '';
+    const shown = change.entries.slice(0, limit);
+    const hidden = change.entries.length - shown.length + (change.more ?? 0);
+    const rows = shown
+        .map((entry) => {
+        const from = sideOf(entry.from, entry.fromJson, 'from');
+        const to = sideOf(entry.to, entry.toJson, 'to');
+        const sides = entry.op === 'changed'
+            ? `${from}<span class="ch-arrow">→</span>${to}`
+            : entry.op === 'added'
+                ? to
+                : from;
+        // A block stacks; two inline values stay on the line.
+        const stacked = (entry.fromJson || entry.toJson) ? ' ch-stacked' : '';
+        return (`<div class="ch-row ch-${entry.op}${stacked}">` +
+            `<span class="ch-sign">${SIGN[entry.op] ?? '·'}</span>` +
+            `<span class="ch-key">${escape(entry.key)}</span>` +
+            `<span class="ch-sides">${sides}</span>` +
+            '</div>');
+    })
+        .join('');
+    // Only when it moved: an in-place replacement is not a list that grew.
+    const size = change.length
+        ? `<div class="ch-size">${change.length.from} → ${change.length.to} items</div>`
+        : '';
+    return `<div class="ch-list">${size}${rows}${hidden > 0 ? `<div class="ch-more">and ${hidden} more</div>` : ''}</div>`;
+}
+/**
+ * Delegated: the rows are rebuilt on every render and per-button listeners would go with them.
+ * True when the click was a copy, so a host does not also treat it as a click on the row.
+ */
+export function handleCopyClick(event) {
+    const button = event.target?.closest?.('.ch-copy');
+    if (!button)
+        return false;
+    void copyText(button.dataset.copy ?? '', button);
+    return true;
+}
+export const CHANGE_CSS = `
+.ch-list { margin-top: 4px; font-family: ui-monospace, monospace; font-size: 11px; }
+.ch-size { color: var(--fx-muted, #8a90a2); margin-bottom: 2px; }
+.ch-row { display: flex; gap: 6px; align-items: baseline; padding: 1px 0; }
+.ch-row.ch-stacked { align-items: flex-start; padding: 3px 0; }
+.ch-sign { flex: none; width: 9px; text-align: center; }
+.ch-added .ch-sign { color: var(--state, #34d399); }
+.ch-removed .ch-sign { color: var(--fx-write, #fb7185); }
+.ch-changed .ch-sign { color: var(--effect, #fbbf24); }
+.ch-key { flex: none; color: var(--fx-muted, #8a90a2); }
+.ch-sides { min-width: 0; flex: 1; overflow-wrap: anywhere; }
+.ch-stacked .ch-sides { display: flex; flex-direction: column; gap: 2px; }
+.ch-from { color: var(--fx-muted, #8a90a2); }
+.ch-row:not(.ch-stacked) .ch-from { text-decoration: line-through; }
+.ch-arrow { color: var(--fx-muted, #8a90a2); margin: 0 4px; }
+.ch-to { color: var(--fx-label, #e7e9ee); }
+.ch-more { color: var(--fx-muted, #8a90a2); margin-top: 2px; }
+/* In the corner: an object can be tall, and a button under it is a scroll away. */
+.ch-block { position: relative; border-radius: 4px; border: 1px solid var(--fx-line, #ffffff14); }
+.ch-block.ch-from { opacity: .72; }
+.ch-json { margin: 0; padding: 5px 7px; overflow-x: auto; white-space: pre; font: inherit; }
+.ch-copy {
+  position: absolute; top: 3px; right: 3px; padding: 1px 6px; cursor: pointer;
+  font: inherit; font-size: 9.5px; opacity: 0; transition: opacity .12s;
+  border: 1px solid var(--fx-line, #ffffff26); border-radius: 3px;
+  background: var(--fx-panel, #14161c); color: var(--fx-muted, #8a90a2);
+}
+.ch-block:hover .ch-copy, .ch-copy:focus { opacity: 1; }
+.ch-copy:hover { color: var(--fx-label, #e7e9ee); }
+`;

package/dist/copy.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Putting text on the clipboard from wherever a panel happens to be running.
+ *
+ * `navigator.clipboard` is not there in a vscode webview without permission, nor on an
+ * insecure origin. The hidden textarea is the old way and still the one that works in both.
+ */
+/** True when the text reached the clipboard. */
+export declare function copyText(text: string, button?: HTMLElement): Promise<boolean>;
+//# sourceMappingURL=copy.d.ts.map

package/dist/copy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy.d.ts","sourceRoot":"","sources":["../src/copy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgCH,gDAAgD;AAChD,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAanF"}

package/dist/copy.js

@@ -0,0 +1,52 @@
+/**
+ * Putting text on the clipboard from wherever a panel happens to be running.
+ *
+ * `navigator.clipboard` is not there in a vscode webview without permission, nor on an
+ * insecure origin. The hidden textarea is the old way and still the one that works in both.
+ */
+/** Says so on the control that was pressed: a toast needs somewhere to live. */
+function confirmOn(button, said = 'copied') {
+    if (!button)
+        return;
+    const was = button.textContent;
+    button.textContent = said;
+    setTimeout(() => {
+        button.textContent = was;
+    }, 1200);
+}
+function fallback(text, button) {
+    try {
+        const doc = button?.ownerDocument ?? document;
+        const area = doc.createElement('textarea');
+        area.value = text;
+        area.setAttribute('readonly', '');
+        area.style.position = 'fixed';
+        area.style.opacity = '0';
+        doc.body.appendChild(area);
+        area.select();
+        doc.execCommand('copy');
+        area.remove();
+        confirmOn(button);
+        return true;
+    }
+    catch {
+        // Nothing left to try; whatever is on screen can still be selected by hand.
+        return false;
+    }
+}
+/** True when the text reached the clipboard. */
+export async function copyText(text, button) {
+    const clipboard = globalThis
+        .navigator?.clipboard;
+    if (clipboard?.writeText) {
+        try {
+            await clipboard.writeText(text);
+            confirmOn(button);
+            return true;
+        }
+        catch {
+            // Denied, or a context the api refuses to work in.
+        }
+    }
+    return fallback(text, button);
+}

package/dist/describe.d.ts

@@ -0,0 +1,3 @@
+/** An element, the text node it writes, or the marker for a hole with nothing in it yet. */
+export declare function describeNode(target: unknown): string;
+//# sourceMappingURL=describe.d.ts.map

package/dist/describe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.d.ts","sourceRoot":"","sources":["../src/describe.ts"],"names":[],"mappings":"AA8BA,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAkBpD"}

package/dist/describe.js

@@ -0,0 +1,47 @@
+// A dom node, in words.
+//
+// The element is described at the moment it is reported and the reference dropped: holding
+// one would keep a removed subtree alive for as long as the panel is open.
+//
+// Enough to find it on the page — tag, id, a class or two — without being a selector.
+/** More than this is a selector, not a label. */
+const MAX_CLASSES = 2;
+/** `text in li` — the element it sits in is what locates it. */
+function textOwner(node) {
+    const parent = node.parentElement;
+    return parent ? `text in ${describeElement(parent)}` : 'text';
+}
+function describeElement(el) {
+    const tag = el.tagName.toLowerCase();
+    const id = el.id ? `#${el.id}` : '';
+    // Not a string on an SVG element.
+    const raw = typeof el.className === 'string' ? el.className : el.getAttribute('class') ?? '';
+    const classes = raw
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, MAX_CLASSES)
+        .map((c) => `.${c}`)
+        .join('');
+    return `${tag}${id}${classes}`;
+}
+/** An element, the text node it writes, or the marker for a hole with nothing in it yet. */
+export function describeNode(target) {
+    const node = target;
+    if (!node || typeof node.nodeType !== 'number')
+        return 'detached';
+    switch (node.nodeType) {
+        case 1:
+            return describeElement(node);
+        case 3:
+            return textOwner(node);
+        case 8: {
+            // The hole is empty; where it will go is what matters.
+            const parent = node.parentElement;
+            return parent ? `slot in ${describeElement(parent)}` : 'slot';
+        }
+        case 11:
+            return 'fragment';
+        default:
+            return node.nodeName?.toLowerCase() ?? 'node';
+    }
+}

package/dist/detail-panel.d.ts

@@ -0,0 +1,17 @@
+import type { Commit } from './history.js';
+import type { RNode } from './instrument.js';
+export interface DetailPanel {
+    /** Show a commit. Opening a second one replaces the first rather than stacking. */
+    open(commit: Commit, graph: Map<number, RNode>): void;
+    close(): void;
+    readonly isOpen: boolean;
+    /** Remove the panel and its listeners. */
+    destroy(): void;
+}
+export interface DetailPanelOptions {
+    /** A node in the panel was clicked — the host can select it on the graph. */
+    onPick?(id: number): void;
+}
+export declare function createDetailPanel(host: HTMLElement, options?: DetailPanelOptions): DetailPanel;
+export declare const DETAIL_PANEL_CSS = "\n.dp-panel {\n  position: fixed; z-index: 40; display: flex; flex-direction: column;\n  border: 1px solid var(--fx-line, #ffffff26); border-radius: 8px;\n  background: var(--fx-panel, #14161c); color: var(--fx-label, #e7e9ee);\n  box-shadow: 0 12px 40px rgba(0, 0, 0, .45); overflow: hidden;\n}\n.dp-panel[hidden] { display: none; }\n.dp-bar {\n  display: flex; align-items: center; gap: 8px; padding: 6px 8px 6px 12px;\n  cursor: move; user-select: none;\n  border-bottom: 1px solid var(--fx-line, #ffffff1f);\n}\n.dp-title { font-family: ui-monospace, monospace; font-size: 12px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n.dp-close {\n  margin-left: auto; width: 22px; height: 20px; padding: 0; cursor: pointer; font: inherit; font-size: 11px;\n  border: 1px solid var(--fx-line, #ffffff1f); border-radius: 4px;\n  background: transparent; color: var(--fx-muted, #8a90a2);\n}\n.dp-close:hover { color: var(--fx-label, #e7e9ee); }\n.dp-body { flex: 1; min-height: 0; overflow: auto; padding: 10px 12px; }\n.dp-change { font-family: ui-monospace, monospace; font-size: 12px; overflow-wrap: anywhere; }\n.dp-group { margin-top: 10px; }\n.dp-verb { font-size: 10.5px; text-transform: uppercase; letter-spacing: 1px; color: var(--fx-muted, #8a90a2); }\n.dp-nodes { display: flex; flex-wrap: wrap; gap: 4px; margin-top: 4px; }\n.dp-node {\n  padding: 2px 7px; cursor: pointer; font: inherit; font-family: ui-monospace, monospace; font-size: 11px;\n  border: 1px solid var(--fx-line, #ffffff1f); border-radius: 999px;\n  background: transparent; color: var(--fx-label, #e7e9ee);\n}\n.dp-node:hover { border-color: var(--fx-accent, #5eead4); }\n.dp-targets { margin-top: 4px; font-family: ui-monospace, monospace; font-size: 11px; color: var(--fx-label, #e7e9ee); }\n.dp-where { color: var(--fx-muted, #8a90a2); }\n/* Bottom-right, where every desktop puts it. */\n.dp-grip {\n  position: absolute; right: 0; bottom: 0; width: 16px; height: 16px; cursor: nwse-resize;\n  background: linear-gradient(135deg, transparent 50%, var(--fx-line, #ffffff40) 50%);\n}\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=detail-panel.d.ts.map

package/dist/detail-panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detail-panel.d.ts","sourceRoot":"","sources":["../src/detail-panel.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC;IACtD,KAAK,IAAI,IAAI,CAAC;IACd,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,0CAA0C;IAC1C,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,MAAM,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AA2DD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAwIlG;AAED,eAAO,MAAM,gBAAgB,0vHAsCf,CAAC"}