@anmol-srv/sigil 0.18.2 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +37 -25
  2. package/dist/cli.js +1191 -790
  3. package/dist/daemon.js +664 -302
  4. package/dist/hooks/post-tool-use.js +1 -69
  5. package/dist/hooks/session-end.js +13 -236
  6. package/dist/hooks/stop.js +36 -246
  7. package/dist/hooks/user-prompt-submit.js +25 -288
  8. package/dist/mcp/worker-server.js +6 -0
  9. package/dist/npm-entry.js +10 -0
  10. package/dist/server.js +64 -56
  11. package/install.sh +207 -0
  12. package/integrations/hermes/README.md +30 -24
  13. package/integrations/hermes/plugin/README.md +1 -1
  14. package/integrations/hermes/plugin/__init__.py +68 -24
  15. package/knexfile.js +19 -22
  16. package/package.json +9 -28
  17. package/prompts/audm-decision.md +26 -1
  18. package/prompts/entity-extraction.md +32 -30
  19. package/prompts/graph-extraction.md +20 -2
  20. package/src/db/drivers/index.js +38 -15
  21. package/src/db/migrations/20260629120000_add-trace-event-attribution.cjs +29 -0
  22. package/src/db/migrations/20260629120001_add-llm-log-session-correlation.cjs +29 -0
  23. package/src/db/migrations/20260806120000_add-document-content.cjs +27 -0
  24. package/src/db/migrations/20260806120001_llm-log-model-nullable.cjs +36 -0
  25. package/src/db/migrations/20260811120000_add-relation-provenance.cjs +42 -0
  26. package/src/db/migrations/20260811130000_add-fact-visibility.cjs +67 -0
  27. package/src/db/migrations/20260813090000_rescore-defaulted-vital.cjs +57 -0
  28. package/src/db/migrations/20260814120000_create-ingestion-job.cjs +52 -0
  29. package/src/db/migrations/20260814120100_add-llm-log-queued-ms.cjs +8 -0
  30. package/src/db/migrations/20260814120200_add-active-fact-content-hash-index.cjs +16 -0
  31. package/src/db/migrations/20260814120300_create-relation-candidate-judgment.cjs +25 -0
  32. package/src/gui/web/app.css +851 -84
  33. package/src/gui/web/app.js +796 -383
  34. package/src/gui/web/cmdk.js +238 -0
  35. package/src/gui/web/components.js +64 -0
  36. package/src/gui/web/design/colors_and_type.css +6 -1
  37. package/src/gui/web/graph/GraphIsland.jsx +450 -0
  38. package/src/gui/web/graph/cluster.js +305 -0
  39. package/src/gui/web/graph/cluster.test.js +219 -0
  40. package/src/gui/web/health.js +117 -0
  41. package/src/gui/web/health.test.js +159 -0
  42. package/src/gui/web/icons.js +65 -0
  43. package/src/gui/web/index.html +310 -115
  44. package/src/gui/web/settings.js +386 -0
  45. package/src/gui/web/setup.js +2 -2
  46. package/src/gui/web/toast.js +6 -3
  47. package/src/gui/web/vendor/graph-island.js +52 -0
@@ -0,0 +1,450 @@
1
+ /**
2
+ * Graph view — a React island around react-force-graph-2d.
3
+ *
4
+ * The rest of the dashboard is vanilla ES modules with no build step, so this
5
+ * is deliberately the ONLY React in the app: it mounts into one container, owns
6
+ * only presentation, and exposes an imperative handle so app.js keeps driving
7
+ * data-loading and routing exactly as before. Nothing else needs to know React
8
+ * is here.
9
+ *
10
+ * Colours are read from the CSS custom properties at mount rather than
11
+ * hardcoded. The previous canvas renderer duplicated --etype-* as literal hex
12
+ * in JS, so the graph and the legend beside it could drift apart the moment a
13
+ * token changed. Now DESIGN.md's token file is the single source of truth for
14
+ * both.
15
+ *
16
+ * Bundled by `npm run build:gui` into ../vendor/graph-island.js.
17
+ */
18
+ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
19
+ import { createRoot } from 'react-dom/client';
20
+ import ForceGraph2D from 'react-force-graph-2d';
21
+ // d3-force-3d is the exact force library force-graph runs internally, so these
22
+ // compose with its simulation rather than fighting it. forceX/forceY are how
23
+ // d3 does gravity — forceCenter only translates the centroid, it does not pull
24
+ // anything inward, which is why the graph drifted apart without them.
25
+ import { forceX, forceY, forceCollide } from 'd3-force-3d';
26
+ import { clusterGraph } from './cluster.js';
27
+
28
+ /** Design tokens, read live so the graph can never drift from the stylesheet. */
29
+ function readTokens() {
30
+ const s = getComputedStyle(document.documentElement);
31
+ const t = (name, fallback) => s.getPropertyValue(name).trim() || fallback;
32
+ return {
33
+ person: t('--etype-person', '#9bd6ff'),
34
+ topic: t('--etype-topic', '#2f81f7'),
35
+ document: t('--etype-document', '#36cfa6'),
36
+ fact: t('--etype-fact', '#565a63'),
37
+ brand: t('--brand', '#0084ff'),
38
+ fg1: t('--fg-1', '#f4f5f6'),
39
+ fg3: t('--fg-3', '#82858c'),
40
+ fg4: t('--fg-4', '#50535a'),
41
+ bg: t('--bg-1', '#0b0c0e'),
42
+ fontSans: t('--font-sans', "'Geist', ui-sans-serif, system-ui, sans-serif"),
43
+ };
44
+ }
45
+
46
+ const prefersReducedMotion = () =>
47
+ Boolean(window.matchMedia?.('(prefers-reduced-motion: reduce)').matches);
48
+
49
+ /** `#rrggbb` → `rgba(r,g,b,a)`, so link alpha can come off a design token. */
50
+ function alpha(hex, a) {
51
+ const m = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(String(hex).trim());
52
+ if (!m) return `rgba(130,133,140,${a})`;
53
+ const [r, g, b] = [1, 2, 3].map((i) => parseInt(m[i], 16));
54
+ return `rgba(${r},${g},${b},${a})`;
55
+ }
56
+
57
+ /**
58
+ * Deterministic 32-bit string hash. Used only to scatter a cluster's nodes
59
+ * around their anchor — Math.random() would make the layout differ run to run,
60
+ * which is the thing cluster.js goes out of its way to avoid.
61
+ */
62
+ function hash(s) {
63
+ let h = 2166136261;
64
+ for (let i = 0; i < s.length; i++) {
65
+ h ^= s.charCodeAt(i);
66
+ h = Math.imul(h, 16777619);
67
+ }
68
+ return Math.abs(h);
69
+ }
70
+
71
+ /** Entities scale gently with connectivity; facts stay small dots. */
72
+ function nodeRadius(n) {
73
+ if (n.kind !== 'entity') return 2.4;
74
+ const deg = n.degree || 0;
75
+ return Math.max(3.5, Math.min(3 + Math.sqrt(deg + (n.mentions || 0)) * 1.5, 11));
76
+ }
77
+
78
+ function GraphView({ api }) {
79
+ const fgRef = useRef(null);
80
+ const wrapRef = useRef(null);
81
+ const [size, setSize] = useState({ width: 0, height: 0 });
82
+ const [graph, setGraph] = useState({ nodes: [], links: [] });
83
+ const [hover, setHover] = useState(null);
84
+ const [pointer, setPointer] = useState({ x: 0, y: 0 });
85
+ const tokens = useMemo(readTokens, []);
86
+ const fitted = useRef(false);
87
+ const labelRects = useRef([]); // per-frame label occlusion buffer
88
+ // force-graph mutates the very node objects handed to the graphData PROP,
89
+ // adding x/y/vx/vy in place — so holding them here is how we reach live
90
+ // positions. The ref exposes no graphData() getter (see relayout).
91
+ const nodesRef = useRef([]);
92
+
93
+ // Adjacency for hover highlight, rebuilt whenever data changes. Built from
94
+ // the ORIGINAL ids: force-graph mutates each link's source/target from an id
95
+ // string into a node reference once the simulation starts.
96
+ const adjacency = useMemo(() => {
97
+ const m = new Map();
98
+ for (const n of graph.nodes) m.set(n.id, new Set());
99
+ for (const l of graph.links) {
100
+ const s = l.source?.id ?? l.source;
101
+ const t = l.target?.id ?? l.target;
102
+ if (m.has(s) && m.has(t)) { m.get(s).add(t); m.get(t).add(s); }
103
+ }
104
+ return m;
105
+ }, [graph]);
106
+
107
+ // Only label the biggest hubs on a dense graph; zooming past 1.45 reveals the
108
+ // rest. Without this the centre of a real store is unreadable overlap.
109
+ const hubMin = graph.nodes.length > 150 ? 10 : 2;
110
+
111
+ useEffect(() => {
112
+ api.current = {
113
+ setData: (data) => {
114
+ fitted.current = false;
115
+ // Communities first: every node carries its cluster's anchor, which is
116
+ // what the gravity forces below pull toward instead of a shared origin.
117
+ // Large stores need materially more room between community anchors.
118
+ // A fixed 150px spread let the outer communities overlap the centre
119
+ // once facts and their mention edges were present.
120
+ const n = data.nodes.length;
121
+ const { assignment, clusters } = clusterGraph(data.nodes, data.edges, {
122
+ spread: n > 400 ? 280 : n > 150 ? 220 : 160,
123
+ });
124
+ const anchors = new Map(clusters.map((c) => [c.id, c]));
125
+ const seeded = {
126
+ // Sorted by connectivity, descending. force-graph paints in array
127
+ // order, and the label occlusion buffer is first-come-first-served —
128
+ // so drawing hubs first is what makes the important labels win the
129
+ // space instead of whichever node happened to be earlier in the JSON.
130
+ nodes: data.nodes
131
+ .map((n) => {
132
+ const anchor = anchors.get(assignment.get(n.id));
133
+ return {
134
+ ...n,
135
+ r: nodeRadius(n),
136
+ cluster: assignment.get(n.id),
137
+ clusterColor: anchor?.color ?? null,
138
+ // Seed the position at the anchor too, not just the target: a
139
+ // node that STARTS in its cluster settles there, instead of
140
+ // migrating across the canvas from a random origin and dragging
141
+ // its neighbours through every other cluster on the way.
142
+ cx: anchor?.x ?? 0,
143
+ cy: anchor?.y ?? 0,
144
+ x: (anchor?.x ?? 0) + (hash(n.id) % 40) - 20,
145
+ y: (anchor?.y ?? 0) + (hash(`${n.id}#`) % 40) - 20,
146
+ };
147
+ })
148
+ .sort((a, b) => (b.degree || 0) - (a.degree || 0)),
149
+ links: data.edges.map((e) => ({ ...e })),
150
+ };
151
+ nodesRef.current = seeded.nodes;
152
+ api.current?.onClusters?.(clusters);
153
+ setGraph(seeded);
154
+ },
155
+ zoomBy: (f) => fgRef.current?.zoom(fgRef.current.zoom() * f, 200),
156
+ fit: () => fgRef.current?.zoomToFit(400, 64),
157
+ // Reheating alone looked like a no-op: alpha went back to 1 but every
158
+ // node was already at its solution, so the forces just re-converged on the
159
+ // same picture. Re-seed positions first — unpin, scatter onto a ring sized
160
+ // to the node count, zero velocity — so the run genuinely explores a new
161
+ // layout, then re-fit when it settles.
162
+ refit: () => { setHover(null); fgRef.current?.zoomToFit(400, 64); },
163
+ };
164
+ }, [api]);
165
+
166
+ // Keep the canvas matched to its container — the old renderer's 0×0 races
167
+ // came from letting the library guess.
168
+ useEffect(() => {
169
+ const el = wrapRef.current;
170
+ if (!el) return undefined;
171
+ const measure = () => setSize({ width: el.clientWidth, height: el.clientHeight });
172
+ measure();
173
+ const ro = new ResizeObserver(measure);
174
+ ro.observe(el);
175
+ return () => ro.disconnect();
176
+ }, []);
177
+
178
+ // Degree per node id — drives both link distance and link strength below.
179
+ const degrees = useMemo(() => {
180
+ const d = new Map();
181
+ for (const l of graph.links) {
182
+ const s = l.source?.id ?? l.source;
183
+ const t = l.target?.id ?? l.target;
184
+ d.set(s, (d.get(s) || 0) + 1);
185
+ d.set(t, (d.get(t) || 0) + 1);
186
+ }
187
+ return d;
188
+ }, [graph]);
189
+
190
+ // Force tuning distinguishes the knowledge skeleton (entity relations) from
191
+ // supporting evidence (fact mentions). A single spring value turns a hub and
192
+ // hundreds of fact leaves into a compact star; longer, weaker mention springs
193
+ // plus stronger repulsion keep all nodes present without making that star the
194
+ // whole picture. Link distance also grows with degree so hubs get room for
195
+ // their labels, while wider anchors and a longer charge range keep regions
196
+ // from stacking on one another.
197
+ useEffect(() => {
198
+ const fg = fgRef.current;
199
+ if (!fg || !graph.nodes.length) return;
200
+ const n = graph.nodes.length;
201
+ const deg = (node) => degrees.get(node.id ?? node) || 1;
202
+
203
+ fg.d3Force('charge')
204
+ .strength(n > 400 ? -95 : n > 150 ? -125 : -150)
205
+ .distanceMax(n > 400 ? 720 : 560);
206
+ fg.d3Force('link')
207
+ .distance((l) => {
208
+ const endpoints = deg(l.source) + deg(l.target);
209
+ // Relations establish the skeleton; fact mentions are its evidence.
210
+ // Give both enough air to avoid text and leaves collapsing on hubs.
211
+ return (l.kind === 'relation' ? 62 : 48) + Math.min(endpoints, 40) * 2;
212
+ })
213
+ .strength((l) => {
214
+ const endpointDegree = Math.max(1, Math.min(deg(l.source), deg(l.target)));
215
+ // The old inverse-degree rule still gives a fact leaf a strength of 1.
216
+ // Hundreds of those leaves form a tight star around a hub. Mentions are
217
+ // intentionally springier than explicit relations, while every node
218
+ // and edge remains in the graph.
219
+ const base = l.kind === 'relation' ? 0.34 : 0.13;
220
+ return base / Math.sqrt(endpointDegree);
221
+ });
222
+
223
+ // Gravity. forceCenter (force-graph's default 'center') only re-centres the
224
+ // centroid — it exerts no inward pull, so with repulsion raised to break the
225
+ // hairball the components simply drifted apart and orphans flew to the
226
+ // margins. forceX/forceY toward the origin is d3's actual gravity: it pulls
227
+ // everything toward one mass without collapsing structure, because the
228
+ // charge/link forces still set local spacing. Scaled down as the graph grows
229
+ // so a big store doesn't get crushed into the middle.
230
+ // Toward each node's CLUSTER anchor, not a single shared origin. Same
231
+ // mechanism and same strengths as before — only the target moved. This is
232
+ // what stops 78 components from stacking on one point.
233
+ const g = n > 400 ? 0.02 : n > 150 ? 0.032 : 0.05;
234
+ fg.d3Force('x', forceX((nd) => nd.cx ?? 0).strength(g));
235
+ fg.d3Force('y', forceY((nd) => nd.cy ?? 0).strength(g));
236
+
237
+ // d3's quadtree collide — O(n log n) against the previous hand-rolled
238
+ // O(n²) pass, and it is the implementation force-graph's own simulation
239
+ // expects. Radius leaves room for the label under each node.
240
+ fg.d3Force('collide', forceCollide()
241
+ .radius((nd) => nd.r + (n > 400 ? 16 : 13))
242
+ .strength(0.9));
243
+ }, [graph, degrees]);
244
+
245
+ const paintNode = useCallback((n, ctx, scale) => {
246
+ const lit = hover ? adjacency.get(hover.id) : null;
247
+ const on = !hover || n.id === hover.id || lit?.has(n.id);
248
+ ctx.globalAlpha = on ? 1 : 0.18;
249
+ ctx.beginPath();
250
+ ctx.arc(n.x, n.y, n.r, 0, Math.PI * 2);
251
+ if (n.kind === 'entity') {
252
+ // Colour carries CLUSTER, not entity type. On a real store the type
253
+ // channel was near-constant — 301 topics against 1 person and 4
254
+ // documents — so it spent the whole colour budget saying nothing.
255
+ // Cluster membership is the thing you actually need to see. Type still
256
+ // reads in the tooltip and the KB list, where it isn't competing with
257
+ // 500 dots. Clusters past the palette stay neutral by design.
258
+ ctx.fillStyle = n.clusterColor || tokens.fg4;
259
+ ctx.fill();
260
+ if (n.id === hover?.id) { ctx.lineWidth = 2 / scale; ctx.strokeStyle = tokens.fg1; ctx.stroke(); }
261
+ } else if (n.kind === 'document') {
262
+ ctx.fillStyle = tokens.document;
263
+ ctx.fill();
264
+ if (n.id === hover?.id) { ctx.lineWidth = 2 / scale; ctx.strokeStyle = tokens.fg1; ctx.stroke(); }
265
+ } else {
266
+ ctx.fillStyle = tokens.fact;
267
+ ctx.fill();
268
+ if (n.id === hover?.id) { ctx.lineWidth = 2 / scale; ctx.strokeStyle = tokens.brand; ctx.stroke(); }
269
+ }
270
+ ctx.globalAlpha = 1;
271
+
272
+ const isHub = n.kind === 'entity' && (n.degree || 0) >= hubMin;
273
+ const wantLabel = n.id === hover?.id || (n.kind === 'entity' && on && (isHub || scale > 1.45));
274
+ if (!wantLabel) return;
275
+
276
+ const label = n.label.length > 26 ? `${n.label.slice(0, 25)}…` : n.label;
277
+ const size = 11 / scale;
278
+ ctx.font = `${n.kind === 'entity' ? 600 : 400} ${size}px ${tokens.fontSans}`;
279
+ const w = ctx.measureText(label).width;
280
+ const x = n.x - w / 2;
281
+ const y = n.y + n.r + 2 / scale;
282
+
283
+ // Occlusion culling. Nodes are painted hub-first, so a label only draws if
284
+ // it doesn't collide with one already placed this frame — which is what
285
+ // turns a dense cluster from overlapping mush into a readable subset. The
286
+ // hovered node always wins; you can still read anything by pointing at it,
287
+ // and zooming in frees space so the rest reappear.
288
+ const pad = 2 / scale;
289
+ const rect = { x1: x - pad, y1: y - pad, x2: x + w + pad, y2: y + size + pad };
290
+ const hovered = n.id === hover?.id;
291
+ if (!hovered) {
292
+ for (const r of labelRects.current) {
293
+ if (rect.x1 < r.x2 && rect.x2 > r.x1 && rect.y1 < r.y2 && rect.y2 > r.y1) return;
294
+ }
295
+ }
296
+ labelRects.current.push(rect);
297
+
298
+ // Halo so a label crossing a link stays legible without a solid backing box.
299
+ ctx.textAlign = 'center';
300
+ ctx.textBaseline = 'top';
301
+ ctx.lineWidth = 3 / scale;
302
+ ctx.strokeStyle = tokens.bg;
303
+ ctx.lineJoin = 'round';
304
+ ctx.strokeText(label, n.x, y);
305
+ ctx.fillStyle = on ? tokens.fg1 : tokens.fg3;
306
+ ctx.fillText(label, n.x, y);
307
+ }, [hover, adjacency, hubMin, tokens]);
308
+
309
+ // Generous, radius-aware hit target — small fact dots are otherwise
310
+ // effectively unclickable.
311
+ const paintPointerArea = useCallback((n, color, ctx) => {
312
+ ctx.fillStyle = color;
313
+ ctx.beginPath();
314
+ ctx.arc(n.x, n.y, Math.max(n.r, 6), 0, 2 * Math.PI);
315
+ ctx.fill();
316
+ }, []);
317
+
318
+ // Three tiers: incident-to-hover, idle, and faded-while-hovering-elsewhere,
319
+ // so the focused subgraph reads clearly without hiding the rest.
320
+ // Links are grey, off --fg-4, in every state — colour on an edge competes
321
+ // with colour on a node, and the nodes are what carry meaning here. The
322
+ // mention/relation distinction moves to opacity and width instead, so the
323
+ // three hover tiers (incident / idle / faded) still read.
324
+ const linkColor = useCallback((l) => {
325
+ const sid = l.source?.id ?? l.source;
326
+ const tid = l.target?.id ?? l.target;
327
+ const incident = hover && (sid === hover.id || tid === hover.id);
328
+ const faded = hover && !incident;
329
+ const strong = l.kind === 'relation';
330
+ if (incident) return alpha(tokens.fg3, strong ? 0.95 : 0.75);
331
+ if (faded) return alpha(tokens.fg4, 0.06);
332
+ return alpha(tokens.fg4, strong ? 0.55 : 0.32);
333
+ }, [hover, tokens]);
334
+
335
+ const reduced = prefersReducedMotion();
336
+
337
+ return (
338
+ <div
339
+ ref={wrapRef}
340
+ className="graph-react-wrap"
341
+ onPointerMove={(e) => {
342
+ const r = wrapRef.current.getBoundingClientRect();
343
+ setPointer({ x: e.clientX - r.left, y: e.clientY - r.top });
344
+ }}
345
+ onPointerLeave={() => setHover(null)}
346
+ >
347
+ {size.width > 0 && (
348
+ <ForceGraph2D
349
+ ref={fgRef}
350
+ width={size.width}
351
+ height={size.height}
352
+ graphData={graph}
353
+ backgroundColor="rgba(0,0,0,0)"
354
+ nodeId="id"
355
+ nodeCanvasObject={paintNode}
356
+ nodePointerAreaPaint={paintPointerArea}
357
+ linkColor={linkColor}
358
+ linkWidth={(l) => (l.kind === 'relation' ? 1.3 : 1)}
359
+ onRenderFramePre={() => { labelRects.current.length = 0; }}
360
+ onNodeHover={setHover}
361
+ onNodeClick={(n) => api.current?.onNodeClick?.(n)}
362
+ // Release the node instead of pinning it. Setting fx/fy on drop froze
363
+ // whatever you dragged, so gravity could never reclaim it and its
364
+ // neighbours stretched away from the mass trying to follow — which is
365
+ // exactly the "dragged clusters flow away" behaviour. Dropping it back
366
+ // into the simulation lets the layout re-absorb it.
367
+ onNodeDragEnd={(n) => { n.fx = undefined; n.fy = undefined; }}
368
+ onBackgroundClick={() => setHover(null)}
369
+ warmupTicks={reduced ? 200 : 0}
370
+ cooldownTicks={reduced ? 0 : 200}
371
+ onEngineStop={() => {
372
+ if (fitted.current) return;
373
+ fitted.current = true;
374
+ fgRef.current?.zoomToFit(0, 55);
375
+ if (fgRef.current && fgRef.current.zoom() > 1.5) fgRef.current.zoom(1.5, 0);
376
+ }}
377
+ />
378
+ )}
379
+ {hover && <Tooltip node={hover} pointer={pointer} wrap={wrapRef.current} />}
380
+ </div>
381
+ );
382
+ }
383
+
384
+ function Tooltip({ node, pointer, wrap }) {
385
+ const ref = useRef(null);
386
+ const [pos, setPos] = useState({ left: 0, top: 0 });
387
+ useEffect(() => {
388
+ const el = ref.current;
389
+ if (!el || !wrap) return;
390
+ const w = el.offsetWidth || 220;
391
+ const h = el.offsetHeight || 64;
392
+ setPos({
393
+ left: Math.max(4, Math.min(pointer.x + 14, wrap.clientWidth - w - 4)),
394
+ top: Math.max(4, Math.min(pointer.y + 14, wrap.clientHeight - h - 4)),
395
+ });
396
+ }, [pointer, wrap, node]);
397
+
398
+ const kind = node.kind === 'entity'
399
+ ? String(node.entityType || 'topic').replace(/_/g, ' ')
400
+ : 'Fact';
401
+ return (
402
+ <div ref={ref} className="graph-tooltip" style={{ left: pos.left, top: pos.top }}>
403
+ <span className="gt-kind">{kind}</span>
404
+ {node.label}
405
+ {node.kind === 'entity' && (
406
+ <span className="gt-meta">{node.mentions} mentions · {node.degree} links</span>
407
+ )}
408
+ </div>
409
+ );
410
+ }
411
+
412
+ /**
413
+ * Mount the island. Returns the imperative handle app.js drives; `onNodeClick`
414
+ * is assigned onto it by the caller so routing stays outside React.
415
+ */
416
+ export function mountGraph(container) {
417
+ let impl = null; // the component's methods, registered on mount
418
+ let pending = null; // data that arrived before React committed
419
+
420
+ const handle = {
421
+ // createRoot().render() is asynchronous, so the caller's first setData()
422
+ // lands BEFORE the component exists. Optional-chaining it away silently
423
+ // drops the initial graph and leaves a correctly-sized, permanently blank
424
+ // canvas — buffer instead and flush on mount.
425
+ setData: (d) => { if (impl) impl.setData(d); else pending = d; },
426
+ zoomBy: (f) => impl?.zoomBy(f),
427
+ fit: () => impl?.fit(),
428
+ refit: () => impl?.refit(),
429
+ onNodeClick: null,
430
+ onClusters: null,
431
+ };
432
+
433
+ // The component assigns its methods to `api.current`; this setter is where
434
+ // the buffered data gets flushed and the click handler is bridged back out.
435
+ const api = {
436
+ get current() { return impl; },
437
+ set current(v) {
438
+ impl = v;
439
+ if (!impl) return;
440
+ impl.onNodeClick = (n) => handle.onNodeClick?.(n);
441
+ impl.onClusters = (c) => handle.onClusters?.(c);
442
+ if (pending) { impl.setData(pending); pending = null; }
443
+ },
444
+ };
445
+
446
+ const root = createRoot(container);
447
+ root.render(<GraphView api={api} />);
448
+ handle.destroy = () => root.unmount();
449
+ return handle;
450
+ }