@fusion.dev/helix-graph 0.118.0 → 0.120.0

package/README.md

@@ -33,6 +33,9 @@ const connection = connectGraph(
 // Keep where the layout put each note, and pass it back as `x` and `y` next time.
 frame.addEventListener('helix-graph-layout', (event) => save(event.detail.positions))
 
+// After replacing a stylesheet, which no attribute shows:
+connection.restyle()
+
 // Later, when the graph goes away:
 connection.disconnect()
 ```
@@ -52,12 +55,44 @@ connection.disconnect()
   changes.
 - Answers the frame's pan and zoom buttons and keys, and tells the renderer which
   gestures the frame's `gestures` lets it take.
+- Draws only what changed when the page hands the frame new notes or links, and
+  draws the frame's `signal()`s.
+
+## Live graphs
+
+**Hand the frame new arrays as often as the graph changes.** The connection
+compares them with what is drawn, by each note's `id` and each link's two ends,
+and the renderer is told only what was added, taken away, renamed or moved. New
+notes grow in and are laid out with the rest held still, and the frame stays
+`:state(ready)` throughout.
+
+```js
+socket.addEventListener('message', ({ data }) => {
+  const note = JSON.parse(data)
+  frame.nodes = [...frame.nodes, note]
+  frame.links = [...frame.links, { source: note.id, target: note.parent }]
+})
+```
+
+**`frame.signal(from, to, { tone })` shows something passing between two
+notes**: a message, a request, a payment. It is drawn traveling from one to the
+other and arriving with a pulse, in the tone's color, over the graph and without
+redrawing it, so a busy feed costs a dot each. A reader who asks for less motion
+sees the link lit for a moment instead.
+
+```js
+frame.signal('Checkout', 'Payments', { tone: 'success' })
+frame.signal('Payments', 'Fraud review', { tone: 'danger' })
+```
+
+A signal is drawn and never said: a screen reader does not hear it. Where what
+passed matters to a reader, say it in the page's own words as well.
 
 ## What it exports
 
 | Import | What |
 |---|---|
-| `@fusion.dev/helix-graph` | `connectGraph`, `graphColorsFrom`, `seedPositions`, and the `GraphDriver` type |
+| `@fusion.dev/helix-graph` | `connectGraph`, `diffGraph`, `graphColorsFrom`, `seedPositions`, and the `GraphDriver` and `GraphChanges` types |
 | `@fusion.dev/helix-graph/sigma` | `sigmaDriver(sigma, options)` |
 
 **Neither Sigma nor graphology is a dependency.** The driver types the renderer

package/dist/connect-graph/connect-graph.d.ts

@@ -1,21 +1,8 @@
 import { type ViewportGestureMode } from '@fusion.dev/helix-core';
+import { type DrawnLink, type DrawnNode, type GraphChanges } from './diff.js';
 import { type GraphLooks } from './looks.js';
 import { type GraphPoint } from './seed.js';
-/** A note as the renderer draws it, placed. */
-export interface DrawnNode {
-    id: string;
-    label: string;
-    /** How large it is drawn, relative to the others: the note's `size`, or 1. */
-    size: number;
-    x: number;
-    y: number;
-}
-/** A link as the renderer draws it, between two notes the graph holds. */
-export interface DrawnLink {
-    label?: string | undefined;
-    source: string;
-    target: string;
-}
+export type { DrawnLink, DrawnNode, GraphChanges } from './diff.js';
 /**
  * What a renderer has to answer for the frame to drive it, and nothing that is
  * the same for every renderer: that is the connector's.
@@ -34,6 +21,21 @@ export interface GraphDriver {
         links: DrawnLink[];
         nodes: DrawnNode[];
     }): void;
+    /**
+     * Applies what changed since the last drawing, in place: what to add, what
+     * to take away and which notes moved or were renamed. `animate` says
+     * whether the reader may watch it happen. Without one, every change is a
+     * whole `draw`, which is right for a graph that changes now and then and
+     * wasteful for one that changes on every message.
+     */
+    update?(changes: GraphChanges, animate: boolean): void;
+    /**
+     * Draws something passing from one note to another, in `color`, traveling
+     * the way it went and arriving with a pulse, or, where `animate` is false,
+     * the link between them lit for a moment. `color` is undefined while the
+     * page's colors cannot be read.
+     */
+    signal?(from: string, to: string, color: string | undefined, animate: boolean): void;
     /**
      * How each note and link is drawn from now on, asked one at a time as the
      * renderer draws them: a selection or a theme changed.
@@ -63,6 +65,8 @@ export interface GraphDriver {
     gestures?(mode: ViewportGestureMode): void;
     /** The element the renderer made focusable, which the connector takes out of the tab order. */
     focusTarget?(): HTMLElement | null;
+    /** Removes whatever the driver added to the renderer or the page, when the connection ends. */
+    stop?(): void;
 }
 /** How a connection behaves where the page does not say. */
 export interface ConnectGraphOptions {
@@ -79,6 +83,12 @@ export interface GraphConnection {
     disconnect(): void;
     /** Lays the graph out again from where it starts, ignoring where the last layout put each note. */
     relayout(): void;
+    /**
+     * Reads the page's colors again. The connection hears a theme that changes
+     * by a class, a mode or the reader's preference on its own; call this after
+     * replacing a stylesheet, which no attribute shows.
+     */
+    restyle(): void;
 }
 /**
  * Connects a Graph frame to whatever draws the graph.
@@ -88,7 +98,11 @@ export interface GraphConnection {
  * connection draws the frame's `nodes` and `links`, lays out the notes that
  * have no position and says where it put them in `helix-graph-layout`, answers
  * the frame's pan and zoom, keeps the selection the same in the list and the
- * drawing, colors the graph from the page's tokens, and tells the renderer
- * which gestures it may take.
+ * drawing, colors the graph from the page's tokens, tells the renderer which
+ * gestures it may take, and draws the frame's `signal()`s.
+ *
+ * **A page changes the graph by handing the frame new arrays**, as often as
+ * it likes: the connection compares them with what is drawn and the renderer
+ * is told only what changed.
  */
 export declare const connectGraph: (frame: HTMLElement, driver: GraphDriver, options?: ConnectGraphOptions) => GraphConnection;

package/dist/connect-graph/connect-graph.js

@@ -1,14 +1,24 @@
-import { HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphZoomEvent, isRtl, watchTheme, } from '@fusion.dev/helix-core';
+import { HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphSignalEvent, HelixGraphZoomEvent, isRtl, watchTheme, } from '@fusion.dev/helix-core';
+import { diffGraph, isEmpty, linkKey, } from './diff.js';
 import { graphColorsFrom, looksOf } from './looks.js';
 import { seedPositions } from './seed.js';
 const viewportOf = (frame) => {
     const box = (frame.shadowRoot?.querySelector('[part="viewport"]') ?? frame).getBoundingClientRect();
     return { height: box.height, width: box.width };
 };
+const toneColor = (colors, tone) => tone === undefined || tone === 'primary'
+    ? colors.primary
+    : tone === 'neutral'
+        ? colors.muted
+        : colors[tone];
 const still = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
 export const connectGraph = (frame, driver, options = {}) => {
     const graph = frame;
     let known = new Map();
+    let drawnNodes = new Map();
+    let drawnLinks = new Map();
+    let first = true;
+    let waiting = new Set();
     let colors = null;
     let stopSettling;
     let pressed;
@@ -47,44 +57,89 @@ export const connectGraph = (frame, driver, options = {}) => {
             shown: graph.shown,
         }));
     };
-    const draw = () => {
-        stopSettling?.();
-        stopSettling = undefined;
+    const draw = (whole = false) => {
+        if (stopSettling) {
+            stopSettling();
+            stopSettling = undefined;
+        }
         cancelAnimationFrame(pending);
         const nodes = graph.nodes ?? [];
         const ids = new Set(nodes.map((node) => node.id));
-        const links = (graph.links ?? []).filter(({ source, target }) => source !== target && ids.has(source) && ids.has(target));
-        const { positions, unplaced } = seedPositions(nodes, links, known);
-        graph.drawn?.(false);
-        driver.draw({
-            links: links.map(({ label, source, target }) => ({ label, source, target })),
-            nodes: nodes.map((node) => {
-                const at = positions.get(node.id);
-                return {
-                    id: node.id,
-                    label: node.label || node.id,
-                    size: Number.isFinite(node.size) ? node.size : 1,
-                    x: at.x,
-                    y: at.y,
-                };
-            }),
-        });
+        const nextLinks = new Map();
+        for (const { label, source, target } of graph.links ?? []) {
+            if (source !== target && ids.has(source) && ids.has(target)) {
+                nextLinks.set(linkKey({ source, target }), { label, source, target });
+            }
+        }
+        const { positions, unplaced } = seedPositions(nodes, [...nextLinks.values()], known);
+        const nextNodes = new Map();
+        for (const node of nodes) {
+            const at = positions.get(node.id);
+            nextNodes.set(node.id, {
+                id: node.id,
+                label: node.label || node.id,
+                size: Number.isFinite(node.size) ? node.size : 1,
+                x: at.x,
+                y: at.y,
+            });
+        }
+        for (const id of waiting) {
+            if (ids.has(id)) {
+                unplaced.add(id);
+            }
+        }
+        const incremental = !first && !whole && driver.update !== undefined;
+        if (incremental) {
+            const changes = diffGraph({ links: drawnLinks, nodes: drawnNodes }, { links: nextLinks, nodes: nextNodes });
+            if (!isEmpty(changes)) {
+                driver.update?.(changes, !still());
+            }
+        }
+        else {
+            graph.drawn?.(false);
+            driver.draw({ links: [...nextLinks.values()], nodes: [...nextNodes.values()] });
+        }
+        drawnNodes = nextNodes;
+        drawnLinks = nextLinks;
+        known = positions;
         restyle();
+        const opening = first || whole;
+        first = false;
         if (unplaced.size > 0 && driver.settle) {
+            waiting = unplaced;
             stopSettling = driver.settle(unplaced, (settled) => {
                 stopSettling = undefined;
+                waiting = new Set();
                 known = new Map(settled);
+                for (const [id, at] of settled) {
+                    const node = drawnNodes.get(id);
+                    if (node) {
+                        drawnNodes.set(id, { ...node, x: at.x, y: at.y });
+                    }
+                }
                 graph.laidOut?.(Object.fromEntries([...settled].map(([id, at]) => [id, { ...at }])));
-                graph.drawn?.(true);
+                if (opening) {
+                    graph.drawn?.(true);
+                }
             });
             return;
         }
-        known = positions;
-        pending = requestAnimationFrame(() => {
-            if (connected) {
-                graph.drawn?.(true);
-            }
-        });
+        waiting = new Set();
+        if (opening) {
+            pending = requestAnimationFrame(() => {
+                if (connected) {
+                    graph.drawn?.(true);
+                }
+            });
+        }
+    };
+    const handleSignal = (event) => {
+        const { from, to, tone } = event.detail;
+        if (!driver.signal || !drawnNodes.has(from) || !drawnNodes.has(to)) {
+            return;
+        }
+        colors ??= graphColorsFrom(frame);
+        driver.signal(from, to, colors ? toneColor(colors, tone) : undefined, !still());
     };
     const handlePartChange = (event) => {
         const { kind } = event.detail;
@@ -117,6 +172,7 @@ export const connectGraph = (frame, driver, options = {}) => {
         }
     };
     frame.addEventListener(HelixGraphPartChangeEvent.eventName, handlePartChange);
+    frame.addEventListener(HelixGraphSignalEvent.eventName, handleSignal);
     frame.addEventListener(HelixGraphPanEvent.eventName, handlePan);
     frame.addEventListener(HelixGraphZoomEvent.eventName, handleZoom);
     const stopPress = driver.onPress?.((id) => {
@@ -147,6 +203,7 @@ export const connectGraph = (frame, driver, options = {}) => {
             stopPress?.();
             stopTheme();
             frame.removeEventListener(HelixGraphPartChangeEvent.eventName, handlePartChange);
+            frame.removeEventListener(HelixGraphSignalEvent.eventName, handleSignal);
             frame.removeEventListener(HelixGraphPanEvent.eventName, handlePan);
             frame.removeEventListener(HelixGraphZoomEvent.eventName, handleZoom);
             if (focusable) {
@@ -158,11 +215,17 @@ export const connectGraph = (frame, driver, options = {}) => {
                 }
             }
             driver.gestures?.('free');
+            driver.stop?.();
             graph.drawn?.(false);
         },
         relayout: () => {
             known = new Map();
-            draw();
+            waiting = new Set();
+            draw(true);
+        },
+        restyle: () => {
+            colors = null;
+            restyle();
         },
     };
 };

package/dist/connect-graph/diff.d.ts

@@ -0,0 +1,50 @@
+/** A note as the renderer draws it, placed. */
+export interface DrawnNode {
+    id: string;
+    label: string;
+    /** How large it is drawn, relative to the others: the note's `size`, or 1. */
+    size: number;
+    x: number;
+    y: number;
+}
+/** A link as the renderer draws it, between two notes the graph holds. */
+export interface DrawnLink {
+    label?: string | undefined;
+    source: string;
+    target: string;
+}
+/** What changed between two drawings of a graph, which a renderer applies in place. */
+export interface GraphChanges {
+    /** Links to draw that were not drawn. */
+    addLinks: DrawnLink[];
+    /** Notes to draw that were not drawn, placed. */
+    addNodes: DrawnNode[];
+    /** Notes still drawn whose name, size or place changed. */
+    changeNodes: DrawnNode[];
+    /** Links no longer drawn. */
+    removeLinks: DrawnLink[];
+    /** Notes no longer drawn, by `id`. */
+    removeNodes: string[];
+}
+/** A link's key: its two ends, which no `id` can contain both of by accident. */
+export declare const linkKey: (link: {
+    source: string;
+    target: string;
+}) => string;
+/** Whether a diff changed nothing. */
+export declare const isEmpty: (changes: GraphChanges) => boolean;
+/**
+ * What changed from one drawing to the next, matched by `id` and by a link's
+ * two ends.
+ *
+ * **Linear in the size of the graph and nothing more**, so a page can hand the
+ * frame a new array for every message on a busy feed and the renderer is told
+ * only what moved: ten thousand notes with one added is one note drawn.
+ */
+export declare const diffGraph: (before: {
+    links: ReadonlyMap<string, DrawnLink>;
+    nodes: ReadonlyMap<string, DrawnNode>;
+}, after: {
+    links: ReadonlyMap<string, DrawnLink>;
+    nodes: ReadonlyMap<string, DrawnNode>;
+}) => GraphChanges;

package/dist/connect-graph/diff.js

@@ -0,0 +1,48 @@
+export const linkKey = (link) => `${link.source}\u0000${link.target}`;
+export const isEmpty = (changes) => changes.addLinks.length === 0 &&
+    changes.addNodes.length === 0 &&
+    changes.changeNodes.length === 0 &&
+    changes.removeLinks.length === 0 &&
+    changes.removeNodes.length === 0;
+export const diffGraph = (before, after) => {
+    const changes = {
+        addLinks: [],
+        addNodes: [],
+        changeNodes: [],
+        removeLinks: [],
+        removeNodes: [],
+    };
+    for (const [id, node] of after.nodes) {
+        const was = before.nodes.get(id);
+        if (!was) {
+            changes.addNodes.push(node);
+        }
+        else if (was.label !== node.label ||
+            was.size !== node.size ||
+            was.x !== node.x ||
+            was.y !== node.y) {
+            changes.changeNodes.push(node);
+        }
+    }
+    for (const id of before.nodes.keys()) {
+        if (!after.nodes.has(id)) {
+            changes.removeNodes.push(id);
+        }
+    }
+    for (const [key, link] of after.links) {
+        const was = before.links.get(key);
+        if (!was) {
+            changes.addLinks.push(link);
+        }
+        else if (was.label !== link.label) {
+            changes.removeLinks.push(was);
+            changes.addLinks.push(link);
+        }
+    }
+    for (const [key, link] of before.links) {
+        if (!after.links.has(key)) {
+            changes.removeLinks.push(link);
+        }
+    }
+    return changes;
+};

package/dist/connect-graph/looks.d.ts

@@ -3,6 +3,10 @@
  * where the frame is.
  */
 export interface GraphColors {
+    /** A signal meaning something to look at: `accent`. */
+    accent: string;
+    /** A signal meaning something went wrong: `danger`. */
+    danger: string;
     /** What the drawing is laid on, which faded notes are mixed toward: `surface-sunken`. */
     ground: string;
     /** The links: `border`. */
@@ -11,10 +15,18 @@ export interface GraphColors {
     ink: string;
     /** A note in no group, and the links that touch the selected note: `foreground-muted`. */
     muted: string;
+    /** What a note's name is drawn on while the pointer is over it: `surface-overlay`. */
+    overlay: string;
     /** The selected note: `primary`. */
     primary: string;
     /** One color for each group, in the order of the groups' names: `series-1` and on. */
     series: string[];
+    /** A signal meaning something done: `success`. */
+    success: string;
+    /** A signal meaning something to know: `info`. */
+    info: string;
+    /** A signal meaning something to watch: `warning`. */
+    warning: string;
 }
 /**
  * The page's colors where the frame is, or `null` while they cannot be read.
@@ -37,8 +49,15 @@ export interface NodeLook {
     color: string;
     /** Outside the local graph that `depth` keeps. */
     hidden: boolean;
-    /** Its name is drawn whatever the room, as the selected note's and its neighbors' are. */
-    label: boolean;
+    /**
+     * When its name is drawn: `always`, whatever the room, as the selected
+     * note's is; `room`, where it does not cover another name, as the
+     * renderer decides for every note at rest; `never`, as a faded note's is.
+     *
+     * **The neighbors get room and not always.** Forced, a hub's twenty
+     * neighbors drew their names over each other in a knot nobody could read.
+     */
+    label: 'always' | 'never' | 'room';
     /** Drawn over the rest, as the selected note and its neighbors are. */
     raised: boolean;
     /** The selected note. */
@@ -56,6 +75,8 @@ export interface GraphLooks {
     font: string;
     /** The color the labels are drawn in. */
     ink: string;
+    /** What a name is drawn on while the pointer is over its note. */
+    overlay: string;
     link(source: string, target: string): LinkLook;
     node(id: string): NodeLook;
 }
@@ -65,7 +86,8 @@ export interface GraphLooks {
  * **The neighborhood stands out and the rest steps back**, which is what
  * selecting a note in a graph of thousands is for: the selected note in the
  * brand color, the notes it links to and from in their groups' colors with
- * their names drawn, and every other note faded toward the ground. With
+ * their names drawn where there is room, and every other note faded toward
+ * the ground, unnamed. With
  * nothing selected, every note is in its group's color.
  *
  * Groups take the series in the order of their names, so a group keeps its

package/dist/connect-graph/looks.js

@@ -1,11 +1,17 @@
 import { readColor } from '@fusion.dev/helix-core';
 const SERIES = 24;
 const TOKENS = {
+    accent: '--helix-color-accent',
+    danger: '--helix-color-danger',
     ground: '--helix-color-surface-sunken',
+    info: '--helix-color-info',
     ink: '--helix-color-foreground',
     line: '--helix-color-border',
     muted: '--helix-color-foreground-muted',
+    overlay: '--helix-color-surface-overlay',
     primary: '--helix-color-primary',
+    success: '--helix-color-success',
+    warning: '--helix-color-warning',
 };
 export const graphColorsFrom = (element) => {
     if (typeof document === 'undefined') {
@@ -81,7 +87,7 @@ export const looksOf = (options) => {
                 return {
                     color: colors.primary,
                     hidden: hidden(id),
-                    label: true,
+                    label: 'always',
                     raised: true,
                     selected: true,
                 };
@@ -90,10 +96,11 @@ export const looksOf = (options) => {
             return {
                 color: focused && !neighbor ? mixRgb(own(id), colors.ground, FADED) : own(id),
                 hidden: hidden(id),
-                label: neighbor,
+                label: focused && !neighbor ? 'never' : 'room',
                 raised: neighbor,
                 selected: false,
             };
         },
+        overlay: colors.overlay,
     };
 };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-export { type ConnectGraphOptions, connectGraph, type DrawnLink, type DrawnNode, type GraphConnection, type GraphDriver, } from './connect-graph/connect-graph.js';
+export { type ConnectGraphOptions, connectGraph, type DrawnLink, type DrawnNode, type GraphChanges, type GraphConnection, type GraphDriver, } from './connect-graph/connect-graph.js';
+export { diffGraph } from './connect-graph/diff.js';
 export { type GraphColors, type GraphLooks, graphColorsFrom, type LinkLook, type NodeLook, } from './connect-graph/looks.js';
 export { type GraphPoint, seedPositions } from './connect-graph/seed.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export { connectGraph, } from './connect-graph/connect-graph.js';
+export { diffGraph } from './connect-graph/diff.js';
 export { graphColorsFrom, } from './connect-graph/looks.js';
 export { seedPositions } from './connect-graph/seed.js';

package/dist/sigma/sigma-driver.d.ts

@@ -4,10 +4,13 @@ export interface SigmaGraph {
     addEdge(source: string, target: string, attributes?: Record<string, unknown>): unknown;
     addNode(node: string, attributes?: Record<string, unknown>): unknown;
     clear(): void;
+    dropEdge(source: string, target: string): void;
+    dropNode(node: string): void;
     forEachNode(callback: (node: string, attributes: Record<string, unknown>) => void): void;
     getNodeAttributes(node: string): Record<string, unknown>;
     hasEdge(source: string, target: string): boolean;
     hasNode(node: string): boolean;
+    mergeNodeAttributes(node: string, attributes: Record<string, unknown>): unknown;
     readonly order: number;
     setNodeAttribute(node: string, name: string, value: unknown): unknown;
 }
@@ -41,7 +44,16 @@ export interface SigmaRenderer {
         width: number;
     };
     getGraph(): SigmaGraph;
+    framedGraphToViewport(point: {
+        x: number;
+        y: number;
+    }): {
+        x: number;
+        y: number;
+    };
     getNodeDisplayData(node: string): {
+        hidden?: boolean;
+        size: number;
         x: number;
         y: number;
     } | undefined;
@@ -52,7 +64,9 @@ export interface SigmaRenderer {
         node: string;
     }) => void): unknown;
     refresh(): unknown;
-    setSetting(name: 'edgeReducer' | 'labelColor' | 'labelFont' | 'nodeReducer', value: unknown): unknown;
+    resize(force?: boolean): unknown;
+    scaleSize(size?: number): number;
+    setSetting(name: 'defaultDrawNodeHover' | 'edgeReducer' | 'labelColor' | 'labelFont' | 'labelRenderedSizeThreshold' | 'nodeReducer', value: unknown): unknown;
     viewportToFramedGraph(point: {
         x: number;
         y: number;

package/dist/sigma/sigma-driver.js

@@ -5,6 +5,31 @@ const STILL = 0.004;
 const HELD = 2;
 const IDLE = 2000;
 const pixels = (size) => 2 + 2 * Math.sqrt(Math.max(size, 0));
+const hoverOf = (looks) => (context, data, settings) => {
+    if (!data.label) {
+        return;
+    }
+    const size = settings.labelSize;
+    context.font = `${settings.labelWeight} ${size}px ${settings.labelFont}`;
+    const width = context.measureText(data.label).width;
+    const x = data.x + data.size + 2;
+    const height = size + 8;
+    context.save();
+    context.shadowBlur = 8;
+    context.shadowColor = 'rgba(0, 0, 0, 0.25)';
+    context.fillStyle = looks.overlay;
+    context.beginPath();
+    context.roundRect(x - 4, data.y - height / 2, width + 8, height, 4);
+    context.fill();
+    context.restore();
+    context.fillStyle = looks.ink;
+    context.fillText(data.label, x, data.y + size / 3);
+};
+const TRAVEL = 700;
+const PULSE = 450;
+const GROW = 300;
+const FLYING = 400;
+const ease = (at) => (at < 0.5 ? 2 * at * at : 1 - (-2 * at + 2) ** 2 / 2);
 const positionsOf = (graph) => {
     const positions = new Map();
     graph.forEachNode((node, attributes) => {
@@ -45,6 +70,110 @@ export const sigmaDriver = (sigma, options = {}) => {
     for (const type of held) {
         container.addEventListener(type, hold, { capture: true, passive: false });
     }
+    const sized = typeof ResizeObserver === 'function'
+        ? new ResizeObserver(() => {
+            sigma.resize(true);
+            sigma.refresh();
+        })
+        : undefined;
+    sized?.observe(container);
+    let overlay;
+    let flights = [];
+    let flying = 0;
+    let ink = 'rgb(128, 128, 128)';
+    const onScreen = (id) => {
+        const data = sigma.getNodeDisplayData(id);
+        if (!data || data.hidden) {
+            return undefined;
+        }
+        const at = sigma.framedGraphToViewport(data);
+        return { radius: sigma.scaleSize(data.size), x: at.x, y: at.y };
+    };
+    const fly = (now) => {
+        const context = overlay?.getContext('2d');
+        if (!overlay || !context) {
+            flights = [];
+            return;
+        }
+        const ratio = window.devicePixelRatio || 1;
+        const width = Math.round(container.clientWidth * ratio);
+        const height = Math.round(container.clientHeight * ratio);
+        if (overlay.width !== width || overlay.height !== height) {
+            overlay.width = width;
+            overlay.height = height;
+        }
+        context.setTransform(ratio, 0, 0, ratio, 0, 0);
+        context.clearRect(0, 0, width, height);
+        flights = flights.filter((flight) => {
+            const from = onScreen(flight.from);
+            const to = onScreen(flight.to);
+            const gone = (now - flight.started) / TRAVEL;
+            if (!from || !to || gone >= 1 + PULSE / TRAVEL) {
+                return false;
+            }
+            context.save();
+            context.strokeStyle = flight.color;
+            context.fillStyle = flight.color;
+            if (gone < 1) {
+                if (flight.animate) {
+                    const along = ease(gone);
+                    const x = from.x + (to.x - from.x) * along;
+                    const y = from.y + (to.y - from.y) * along;
+                    context.globalAlpha = 0.6;
+                    context.lineWidth = 2;
+                    context.beginPath();
+                    context.moveTo(from.x, from.y);
+                    context.lineTo(x, y);
+                    context.stroke();
+                    context.globalAlpha = 1;
+                    context.shadowBlur = 14;
+                    context.shadowColor = flight.color;
+                    context.beginPath();
+                    context.arc(x, y, 5, 0, Math.PI * 2);
+                    context.fill();
+                    context.shadowBlur = 0;
+                    context.fillStyle = 'rgba(255, 255, 255, 0.85)';
+                    context.beginPath();
+                    context.arc(x, y, 2, 0, Math.PI * 2);
+                    context.fill();
+                }
+                else {
+                    context.globalAlpha = 1 - gone;
+                    context.lineWidth = 2;
+                    context.beginPath();
+                    context.moveTo(from.x, from.y);
+                    context.lineTo(to.x, to.y);
+                    context.stroke();
+                }
+            }
+            else if (flight.animate) {
+                const opened = (gone - 1) / (PULSE / TRAVEL);
+                context.globalAlpha = 1 - opened;
+                context.lineWidth = 2.5;
+                context.beginPath();
+                context.arc(to.x, to.y, to.radius + 2 + opened * 16, 0, Math.PI * 2);
+                context.stroke();
+            }
+            context.restore();
+            return true;
+        });
+        flying = flights.length > 0 ? requestAnimationFrame(fly) : 0;
+    };
+    const grow = (sizes) => {
+        const started = performance.now();
+        const step = (now) => {
+            const along = Math.min((now - started) / GROW, 1);
+            for (const [id, size] of sizes) {
+                if (graph.hasNode(id)) {
+                    graph.setNodeAttribute(id, 'size', size * ease(along));
+                }
+            }
+            if (along < 1) {
+                requestAnimationFrame(step);
+            }
+        };
+        requestAnimationFrame(step);
+    };
     return {
         center: (id, animate) => {
             const at = sigma.getNodeDisplayData(id);
@@ -85,16 +214,21 @@ export const sigmaDriver = (sigma, options = {}) => {
                 next === 'free' ? touchAction : next === 'cooperative' ? 'pan-x pan-y' : 'auto';
         },
         look: (looks) => {
+            ink = looks.ink;
             sigma.setSetting('labelColor', { color: looks.ink });
             sigma.setSetting('labelFont', looks.font);
+            sigma.setSetting('labelRenderedSizeThreshold', 0);
+            sigma.setSetting('defaultDrawNodeHover', hoverOf(looks));
             sigma.setSetting('nodeReducer', (node, data) => {
                 const look = looks.node(node);
+                const grown = look.selected ? 1.5 : look.raised ? 1.25 : 1;
                 return {
                     ...data,
                     color: look.color,
-                    forceLabel: look.label,
+                    forceLabel: look.label === 'always',
                     hidden: look.hidden,
-                    size: look.selected && typeof data.size === 'number' ? data.size * 1.5 : data.size,
+                    label: look.label === 'never' ? null : data.label,
+                    size: typeof data.size === 'number' ? data.size * grown : data.size,
                     zIndex: look.selected ? 2 : look.raised ? 1 : 0,
                 };
             });
@@ -127,6 +261,82 @@ export const sigmaDriver = (sigma, options = {}) => {
                 camera.setState(to);
             }
         },
+        signal: (from, to, color, animate) => {
+            if (!overlay) {
+                overlay = document.createElement('canvas');
+                overlay.setAttribute('aria-hidden', 'true');
+                overlay.style.cssText =
+                    'position:absolute;inset:0;width:100%;height:100%;pointer-events:none';
+                container.append(overlay);
+            }
+            flights.push({ animate, color: color ?? ink, from, started: performance.now(), to });
+            if (flights.length > FLYING) {
+                flights = flights.slice(-FLYING);
+            }
+            if (!flying) {
+                flying = requestAnimationFrame(fly);
+            }
+        },
+        stop: () => {
+            cancelAnimationFrame(flying);
+            flying = 0;
+            flights = [];
+            overlay?.remove();
+            overlay = undefined;
+            sized?.disconnect();
+            for (const type of held) {
+                container.removeEventListener(type, hold, { capture: true });
+            }
+            container.style.touchAction = touchAction;
+        },
+        update: (changes, animate) => {
+            for (const id of changes.removeNodes) {
+                if (graph.hasNode(id)) {
+                    graph.dropNode(id);
+                }
+            }
+            for (const link of changes.removeLinks) {
+                if (graph.hasEdge(link.source, link.target)) {
+                    graph.dropEdge(link.source, link.target);
+                }
+            }
+            const growing = new Map();
+            for (const node of changes.addNodes) {
+                const size = pixels(node.size);
+                graph.addNode(node.id, {
+                    label: node.label,
+                    size: animate ? 0 : size,
+                    x: node.x,
+                    y: node.y,
+                });
+                if (animate) {
+                    growing.set(node.id, size);
+                }
+            }
+            for (const node of changes.changeNodes) {
+                graph.mergeNodeAttributes(node.id, {
+                    label: node.label,
+                    size: pixels(node.size),
+                    x: node.x,
+                    y: node.y,
+                });
+            }
+            for (const link of changes.addLinks) {
+                if (graph.hasNode(link.source) &&
+                    graph.hasNode(link.target) &&
+                    !graph.hasEdge(link.source, link.target)) {
+                    graph.addEdge(link.source, link.target, {
+                        from: link.source,
+                        label: link.label,
+                        size: 1,
+                        to: link.target,
+                    });
+                }
+            }
+            if (growing.size > 0) {
+                grow(growing);
+            }
+        },
         zoomBy: (direction, animate) => {
             const ratio = camera.getState().ratio * (direction > 0 ? 1 / ZOOM : ZOOM);
             if (animate) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-graph",
   "description": "Connects the Helix Graph frame to a graph renderer: Sigma.js, or a driver of your own.",
-  "version": "0.118.0",
+  "version": "0.120.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -35,11 +35,11 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.118.0"
+    "@fusion.dev/helix-core": "0.120.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-headless": "0.118.0",
-    "@fusion.dev/helix-testing": "0.118.0",
+    "@fusion.dev/helix-headless": "0.120.0",
+    "@fusion.dev/helix-testing": "0.120.0",
     "@types/bun": "^1.3.0",
     "graphology": "^0.26.0",
     "graphology-layout-forceatlas2": "^0.10.1",