@fusion.dev/helix-graph 0.120.0 → 0.121.0

package/README.md

@@ -1,6 +1,6 @@
 # @fusion.dev/helix-graph
 
-Connects the Helix `Graph` frame to whatever draws the graph: Sigma.js, or a
+Connects the Helix `Graph` frame to whatever draws the graph: Sigma.js, cosmos.gl, or a
 driver of your own, colored from your tokens.
 
 ```sh
@@ -75,8 +75,9 @@ socket.addEventListener('message', ({ data }) => {
 ```
 
 **`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
+notes**: a message, a request, a payment. It is drawn as a pulse of light
+traveling from one to the other, turning from the first note's color to the
+second's, or in the tone's color where it has one, 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.
 
@@ -88,27 +89,159 @@ 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.
 
+## How notes look
+
+Each note can say how it is drawn, in the words Helix's other components use:
+
+| Field | Values | What it does |
+|---|---|---|
+| `shape` | `circle`, `square`, `diamond`, `ring` | What kind of note it is at a glance |
+| `emphasis` | `solid`, `outlined`, `subtle` | Filled, a ring with the ground showing through, or a tinted fill with a ring |
+| `material` | `glass`, `frosted` | A shaded sphere with a highlight and a lit rim, or a milky body with a soft fall of light |
+| `tone` | `primary`, `accent`, `info`, `success`, `warning`, `danger`, `neutral` | What it means, which colors it over its group |
+
+```js
+frame.nodes = [
+  { id: 'Roadmap', group: 'Product', shape: 'square' },
+  { id: 'Outage 14', group: 'Support', tone: 'danger', emphasis: 'outlined' },
+]
+```
+
+`sigmaDriver(sigma, { material, shape, emphasis })` sets what a note is drawn as
+where it does not say. The selected note keeps its own color and is told apart by
+a ring and a glow in that color.
+
+**A note without a `size` is as large as it is connected**, so hubs read at a
+glance. Links are tinted by the note they leave, the selected note's and the
+hovered note's in their color, and choosing a note in the list frames it with
+its neighbors.
+
+**Notes are named on hover**, and the selected note and its neighbors where
+there is room, each name ringed in the ground's color so it reads over the
+links. Each group's name is drawn over its notes, which is how a reader finds
+their way. `labels: 'hubs'` names the busiest notes at rest as well, quietly,
+and `labels: 'all'` every note where its name does not cover another.
+
+## Large graphs
+
+**Past fifty thousand notes, draw with cosmos.gl**, which lays the graph out
+and draws it on the GPU. The frame, the list, selection and signals are the
+same; only the driver changes:
+
+```sh
+bun add @cosmos.gl/graph
+```
+
+```js
+import { Graph } from '@cosmos.gl/graph'
+import { connectGraph } from '@fusion.dev/helix-graph'
+import { cosmosDriver } from '@fusion.dev/helix-graph/cosmos'
+
+const box = document.getElementById('drawing')
+const graph = new Graph(box, { attribution: '', enableSimulation: true, scalePointsOnZoom: false })
+connectGraph(frame, cosmosDriver(graph, box))
+```
+
+cosmos.gl draws notes with its own shaders, so a note's `shape` is honored and
+its `material` and `emphasis` are not. Each group is given a place of its own
+and its notes are drawn toward it, so twenty thousand notes in twelve groups
+come apart into twelve regions. The view follows the layout as it opens out,
+until the reader moves it. Zoomed out, a note is a fine point and a leaf is
+drawn partly clear, so a group reads as a field of points with its hubs
+standing out; notes grow as the reader zooms in.
+
+**cosmos.gl's own start reports a `ResizeObserver loop` error**, which is
+harmless and shows in the console: it observes its canvas from inside
+luma.gl's resize callback. Make the GPU device yourself and hand it over a
+frame after its canvas is measured, and cosmos.gl starts outside any callback:
+
+```js
+import { luma } from '@luma.gl/core'
+import { webgl2Adapter } from '@luma.gl/webgl'
+
+const canvas = Object.assign(document.createElement('canvas'), {
+  style: 'width:100%;height:100%',
+})
+box.append(canvas)
+const device = luma
+  .createDevice({
+    adapters: [webgl2Adapter],
+    createCanvasContext: { autoResize: true, canvas, useDevicePixels: true },
+    type: 'webgl',
+    webgl: { antialias: false },
+  })
+  .then(async (made) => {
+    await made.canvasContext?.initialized
+    await new Promise((done) => requestAnimationFrame(done))
+    return made
+  })
+const graph = new Graph(box, { attribution: '', enableSimulation: true }, device)
+```
+
+Use the `@luma.gl` version `@cosmos.gl/graph` depends on, since two versions
+on one page throw, and destroy the device after the graph.
+
+**The driver is for `@cosmos.gl/graph`, which is MIT.** Cosmograph, the
+product built on it, is licensed for noncommercial use only.
+
+## Shapes
+
+**`stencil` draws the notes in a shape**, such as a brain or a country's
+outline. Pass an SVG path and the box it is drawn in, as the SVG's `viewBox`
+gives it:
+
+```js
+connectGraph(frame, driver, {
+  stencil: { path: brain.getAttribute('d'), width: 220, height: 170 },
+})
+```
+
+No layout runs, so the shape is there from the first frame. Each group takes
+a region of the shape, each note sits by the hub it links to, and the notes
+fill the shape evenly, with borders between regions that curve. Holes are cut
+by the even-odd rule, which is how the grooves of a brain show. Only a graph
+with no places of its own is shaped; a note added later is placed by the
+layout beside its neighbors. `stencil` also takes `inside(x, y)`, a test of
+whether a point in the box is in the shape, in place of `path`, and
+`fitToStencil` fits places a page has into one.
+
 ## What it exports
 
 | Import | What |
 |---|---|
-| `@fusion.dev/helix-graph` | `connectGraph`, `diffGraph`, `graphColorsFrom`, `seedPositions`, and the `GraphDriver` and `GraphChanges` types |
+| `@fusion.dev/helix-graph` | `connectGraph`, `diffGraph`, `fitToStencil`, `graphColorsFrom`, `seedPositions`, and the `GraphDriver`, `GraphChanges` and `GraphStencil` types |
 | `@fusion.dev/helix-graph/sigma` | `sigmaDriver(sigma, options)` |
+| `@fusion.dev/helix-graph/cosmos` | `cosmosDriver(graph, box, options)` |
 
-**Neither Sigma nor graphology is a dependency.** The driver types the renderer
-by the calls it makes on it, so a page brings whichever version it has. A spec
-holds those shapes to the real classes, so a renamed method fails a typecheck
-here rather than a page.
+**Sigma and cosmos.gl are optional peers, and graphology is the page's.** Each
+driver types its renderer by the calls it makes on it, so a page brings
+whichever version it has, and a spec holds those shapes to the real classes,
+so a renamed method fails a typecheck here before it reaches a page. `@fusion.dev/helix-graph/sigma` imports
+Sigma's rendering module for the program that draws the notes, which is why
+Sigma 3 is a peer dependency.
 
 | `connectGraph` option | Default | What else it takes |
 |---|---|---|
 | `center` | `true` | `false` leaves the view where it is when a note is chosen in the list |
+| `stencil` | none | A shape to draw the notes in: `{ path, width, height }` or `{ inside, width, height }` |
 
 | `sigmaDriver` option | Default | What else it takes |
 |---|---|---|
 | `layout` | none | A function that makes a layout for the graph, such as ForceAtlas2's worker |
+| `material` | flat | `glass` or `frosted`, for every note that does not say |
+| `shape` | `circle` | `square`, `diamond` or `ring`, for every note that does not say |
+| `emphasis` | `solid` | `outlined` or `subtle`, for every note that does not say |
+| `labels` | `'hover'` | `'hubs'` or `'all'`: which notes are named at rest |
+| `groupLabels` | `true` | `false` leaves each group unnamed |
 | `layoutLimit` | `10000` | The longest a layout runs, in milliseconds, about where 10,000 notes settle |
 
+| `cosmosDriver` option | Default | What else it takes |
+|---|---|---|
+| `shape` | `circle` | `square` or `diamond`, for every note that does not say |
+| `groupLabels` | `true` | `false` leaves each group unnamed |
+| `layoutLimit` | `15000` | The longest a layout runs, in milliseconds |
+| `spaceSize` | `4096` | The size of cosmos.gl's space, as its own `spaceSize` says |
+
 ## Working on it
 
 ```sh

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

@@ -0,0 +1,18 @@
+import type { GraphPoint, SeedLink } from './seed.js';
+/** A note as the arrangement reads it: its group, if it has one. */
+export interface ArrangedNode {
+    group?: string | undefined;
+    id: string;
+}
+/**
+ * Places for every note from the graph's structure alone, with no layout to
+ * wait for: **each group around a circle, each hub in its group, and each
+ * note beside the hub it hangs from**, the most connected note it links to
+ * in its group.
+ *
+ * Not a layout to look at, since fans overlap and nothing is pushed apart:
+ * it is where a stencil starts, which reads only which notes are near which,
+ * so the shape is drawn from the first frame with each group a region and
+ * each hub's notes around it.
+ */
+export declare const arrangeByGroup: (nodes: readonly ArrangedNode[], links: readonly SeedLink[]) => Map<string, GraphPoint>;

package/dist/connect-graph/arrange.js

@@ -0,0 +1,92 @@
+const TURN = Math.PI * (3 - Math.sqrt(5));
+const spiral = (at, spacing) => ({
+    x: Math.cos(at * TURN) * Math.sqrt(at + 0.5) * spacing,
+    y: Math.sin(at * TURN) * Math.sqrt(at + 0.5) * spacing,
+});
+export const arrangeByGroup = (nodes, links) => {
+    const groupOf = new Map(nodes.map((node) => [node.id, node.group ?? '']));
+    const degree = new Map();
+    const neighbors = new Map();
+    const add = (from, to) => {
+        degree.set(from, (degree.get(from) ?? 0) + 1);
+        const list = neighbors.get(from);
+        if (list) {
+            list.push(to);
+        }
+        else {
+            neighbors.set(from, [to]);
+        }
+    };
+    for (const { source, target } of links) {
+        if (groupOf.has(source) && groupOf.has(target)) {
+            add(source, target);
+            add(target, source);
+        }
+    }
+    const rank = (id) => degree.get(id) ?? 0;
+    const above = (one, other) => rank(one) > rank(other) || (rank(one) === rank(other) && one < other);
+    const parent = new Map();
+    for (const { id } of nodes) {
+        let best = id;
+        for (const near of neighbors.get(id) ?? []) {
+            if (groupOf.get(near) === groupOf.get(id) && above(near, best)) {
+                best = near;
+            }
+        }
+        parent.set(id, best);
+    }
+    const hubOf = (id) => {
+        let at = id;
+        while (parent.get(at) !== at) {
+            at = parent.get(at);
+        }
+        let step = id;
+        while (step !== at) {
+            const next = parent.get(step);
+            parent.set(step, at);
+            step = next;
+        }
+        return at;
+    };
+    const groups = new Map();
+    for (const { id } of nodes) {
+        const group = groupOf.get(id);
+        const hubs = groups.get(group) ?? new Map();
+        groups.set(group, hubs);
+        const hub = hubOf(id);
+        const members = hubs.get(hub) ?? [];
+        hubs.set(hub, members);
+        if (hub !== id) {
+            members.push(id);
+        }
+    }
+    const radiusOf = (hubs) => {
+        let count = 0;
+        for (const members of hubs.values()) {
+            count += members.length + 1;
+        }
+        return Math.sqrt(count) * 1.5;
+    };
+    const radii = [...groups.values()].map(radiusOf);
+    const widest = Math.max(0, ...radii);
+    const ring = groups.size > 1 ? (widest * 1.2) / Math.sin(Math.PI / groups.size) : 0;
+    const positions = new Map();
+    [...groups.values()].forEach((hubs, at) => {
+        const turn = (at / groups.size) * Math.PI * 2;
+        const middle = { x: Math.cos(turn) * ring, y: Math.sin(turn) * ring };
+        const ordered = [...hubs].sort(([, one], [, other]) => other.length - one.length);
+        const mean = ordered.reduce((sum, [, members]) => sum + members.length + 1, 0) / ordered.length;
+        ordered.forEach(([hub, members], place) => {
+            const spot = spiral(place, Math.sqrt(mean) * 2);
+            const center = { x: middle.x + spot.x, y: middle.y + spot.y };
+            positions.set(hub, center);
+            members
+                .sort((one, other) => rank(other) - rank(one))
+                .forEach((member, step) => {
+                const off = spiral(step + 1, 1);
+                positions.set(member, { x: center.x + off.x, y: center.y + off.y });
+            });
+        });
+    });
+    return positions;
+};

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

@@ -2,6 +2,7 @@ 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';
+import { type GraphStencil } from './stencil.js';
 export type { DrawnLink, DrawnNode, GraphChanges } from './diff.js';
 /**
  * What a renderer has to answer for the frame to drive it, and nothing that is
@@ -30,12 +31,16 @@ export interface GraphDriver {
      */
     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.
+     * Draws something passing from one note to another, traveling the way it
+     * went and arriving with a pulse, or, where `animate` is false, the link
+     * between them lit for a moment. It leaves in `colors.from` and arrives in
+     * `colors.to`, which are one color where the signal has a tone. `colors` is
+     * undefined while the page's colors cannot be read.
      */
-    signal?(from: string, to: string, color: string | undefined, animate: boolean): void;
+    signal?(from: string, to: string, colors: {
+        from: string;
+        to: 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.
@@ -47,6 +52,11 @@ export interface GraphDriver {
     zoomBy(direction: 1 | -1, animate: boolean): void;
     /** Brings a note into the middle of the view, where the renderer can. */
     center?(id: string, animate: boolean): void;
+    /**
+     * Frames a set of notes, the selected one and its neighbors, in the middle
+     * of the view at a zoom that holds them all, where the renderer can.
+     */
+    fit?(ids: readonly string[], animate: boolean): void;
     /** Calls `press` with a note's `id` when the reader presses it in the drawing. Returns what stops listening. */
     onPress?(press: (id: string) => void): () => void;
     /**
@@ -65,9 +75,26 @@ 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;
+    /**
+     * The graph's groups, each named over its notes, which is how a reader
+     * finds their way while notes are named only on hover. `faded` while a note
+     * outside the group is selected.
+     */
+    groups?(groups: readonly GraphGroup[]): void;
     /** Removes whatever the driver added to the renderer or the page, when the connection ends. */
     stop?(): void;
 }
+/** One group of notes, as the renderer names it over them. */
+export interface GraphGroup {
+    /** The group's color, which its name is drawn in. */
+    color: string;
+    /** Whether a note outside the group is selected, which steps its name back. */
+    faded: boolean;
+    /** The notes in the group, by `id`. */
+    ids: readonly string[];
+    /** The group's name, as the notes give it. */
+    name: string;
+}
 /** How a connection behaves where the page does not say. */
 export interface ConnectGraphOptions {
     /**
@@ -76,6 +103,14 @@ export interface ConnectGraphOptions {
      * reader is already looking at it.
      */
     center?: boolean | undefined;
+    /**
+     * A shape the notes are drawn in, such as a brain or a country's outline:
+     * an SVG path and the box it is drawn in. **No layout runs**: each group
+     * takes a region of the shape and each note sits by the hub it links to,
+     * from the first frame. Only a graph with no places of its own is shaped;
+     * a note added later is placed by the layout beside its neighbors.
+     */
+    stencil?: GraphStencil | undefined;
 }
 /** A connection, which is ended rather than left to leak. */
 export interface GraphConnection {

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

@@ -1,16 +1,13 @@
 import { HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphSignalEvent, HelixGraphZoomEvent, isRtl, watchTheme, } from '@fusion.dev/helix-core';
+import { arrangeByGroup } from './arrange.js';
 import { diffGraph, isEmpty, linkKey, } from './diff.js';
-import { graphColorsFrom, looksOf } from './looks.js';
+import { graphColorsFrom, looksOf, toneColor, } from './looks.js';
 import { seedPositions } from './seed.js';
+import { fitToStencil } from './stencil.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;
@@ -19,7 +16,9 @@ export const connectGraph = (frame, driver, options = {}) => {
     let drawnLinks = new Map();
     let first = true;
     let waiting = new Set();
+    let owed = false;
     let colors = null;
+    let current;
     let stopSettling;
     let pressed;
     let pending = 0;
@@ -43,19 +42,42 @@ export const connectGraph = (frame, driver, options = {}) => {
                 }
             }
         }
-        const groups = new Map(nodes.map((node) => [node.id, node.group]));
-        driver.look(looksOf({
+        const notes = new Map(nodes.map((node) => [node.id, node]));
+        current = looksOf({
             colors,
             font: getComputedStyle(frame)
                 .fontFamily.split(',')[0]
                 ?.trim()
                 .replace(/^["']|["']$/g, ''),
-            groupOf: (id) => groups.get(id),
             groups: nodes.flatMap((node) => (node.group === undefined ? [] : [node.group])),
             near,
+            noteOf: (id) => notes.get(id),
             selected,
             shown: graph.shown,
-        }));
+        });
+        driver.look(current);
+        if (driver.groups) {
+            const members = new Map();
+            for (const node of nodes) {
+                if (node.group !== undefined) {
+                    const list = members.get(node.group);
+                    if (list) {
+                        list.push(node.id);
+                    }
+                    else {
+                        members.set(node.group, [node.id]);
+                    }
+                }
+            }
+            const own = selected === undefined ? undefined : notes.get(selected)?.group;
+            const looks = current;
+            driver.groups([...members].map(([name, ids]) => ({
+                color: looks.colorOf(ids.find((id) => notes.get(id)?.tone === undefined) ?? ids[0] ?? ''),
+                faded: selected !== undefined && own !== name,
+                ids,
+                name,
+            })));
+        }
     };
     const draw = (whole = false) => {
         if (stopSettling) {
@@ -71,14 +93,29 @@ export const connectGraph = (frame, driver, options = {}) => {
                 nextLinks.set(linkKey({ source, target }), { label, source, target });
             }
         }
-        const { positions, unplaced } = seedPositions(nodes, [...nextLinks.values()], known);
+        let { positions, unplaced } = seedPositions(nodes, [...nextLinks.values()], known);
+        const shaped = options.stencil && ids.size > 0 && unplaced.size === ids.size
+            ? fitToStencil(arrangeByGroup(nodes, [...nextLinks.values()]), options.stencil)
+            : undefined;
+        if (shaped) {
+            positions = shaped;
+            unplaced = new Set();
+            known = new Map(shaped);
+        }
+        const degree = new Map();
+        for (const { source, target } of nextLinks.values()) {
+            degree.set(source, (degree.get(source) ?? 0) + 1);
+            degree.set(target, (degree.get(target) ?? 0) + 1);
+        }
         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,
+                size: Number.isFinite(node.size)
+                    ? node.size
+                    : 1 + Math.min(Math.sqrt(degree.get(node.id) ?? 0), 6),
                 x: at.x,
                 y: at.y,
             });
@@ -103,7 +140,9 @@ export const connectGraph = (frame, driver, options = {}) => {
         drawnLinks = nextLinks;
         known = positions;
         restyle();
-        const opening = first || whole;
+        if (first || whole) {
+            owed = true;
+        }
         first = false;
         if (unplaced.size > 0 && driver.settle) {
             waiting = unplaced;
@@ -118,16 +157,21 @@ export const connectGraph = (frame, driver, options = {}) => {
                     }
                 }
                 graph.laidOut?.(Object.fromEntries([...settled].map(([id, at]) => [id, { ...at }])));
-                if (opening) {
+                if (owed) {
+                    owed = false;
                     graph.drawn?.(true);
                 }
             });
             return;
         }
         waiting = new Set();
-        if (opening) {
+        if (shaped) {
+            graph.laidOut?.(Object.fromEntries([...shaped].map(([id, at]) => [id, { ...at }])));
+        }
+        if (owed) {
             pending = requestAnimationFrame(() => {
-                if (connected) {
+                if (connected && owed) {
+                    owed = false;
                     graph.drawn?.(true);
                 }
             });
@@ -139,7 +183,12 @@ export const connectGraph = (frame, driver, options = {}) => {
             return;
         }
         colors ??= graphColorsFrom(frame);
-        driver.signal(from, to, colors ? toneColor(colors, tone) : undefined, !still());
+        const toned = tone !== undefined && colors ? toneColor(colors, tone) : undefined;
+        driver.signal(from, to, toned
+            ? { from: toned, to: toned }
+            : current
+                ? { from: current.colorOf(from), to: current.colorOf(to) }
+                : undefined, !still());
     };
     const handlePartChange = (event) => {
         const { kind } = event.detail;
@@ -150,7 +199,21 @@ export const connectGraph = (frame, driver, options = {}) => {
             restyle();
             const selected = graph.active;
             if (selected && selected !== pressed && options.center !== false) {
-                driver.center?.(selected, !still());
+                const near = [selected];
+                for (const { source, target } of drawnLinks.values()) {
+                    if (source === selected) {
+                        near.push(target);
+                    }
+                    else if (target === selected) {
+                        near.push(source);
+                    }
+                }
+                if (driver.fit && near.length > 1) {
+                    driver.fit(near, !still());
+                }
+                else {
+                    driver.center?.(selected, !still());
+                }
             }
             pressed = undefined;
         }

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

@@ -2,7 +2,7 @@
 export interface DrawnNode {
     id: string;
     label: string;
-    /** How large it is drawn, relative to the others: the note's `size`, or 1. */
+    /** How large it is drawn, relative to the others: the note's `size`, or from how many links it has. */
     size: number;
     x: number;
     y: number;

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

@@ -58,11 +58,31 @@ export interface NodeLook {
      * neighbors drew their names over each other in a knot nobody could read.
      */
     label: 'always' | 'never' | 'room';
+    /** How heavily it is drawn, where the note says. */
+    emphasis?: 'outlined' | 'solid' | 'subtle' | undefined;
+    /** How strongly it glows, from 0 to 1: the selected note's halo. */
+    glow: number;
+    /** What it is drawn as made of, where the note says. */
+    material?: 'frosted' | 'glass' | undefined;
     /** Drawn over the rest, as the selected note and its neighbors are. */
     raised: boolean;
     /** The selected note. */
     selected: boolean;
+    /** Its shape, where the note says. */
+    shape?: 'circle' | 'diamond' | 'ring' | 'square' | undefined;
 }
+/** A tone from the `tone` axis. */
+export type GraphTone = 'accent' | 'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'warning';
+/** What the looks read off one note. */
+export interface NoteFacts {
+    emphasis?: NodeLook['emphasis'];
+    group?: string | undefined;
+    material?: NodeLook['material'];
+    shape?: NodeLook['shape'];
+    tone?: GraphTone | undefined;
+}
+/** A tone's color: `neutral` is the muted ink, and no tone is `primary`. */
+export declare const toneColor: (colors: GraphColors, tone: GraphTone | undefined) => string;
 /** How one link is drawn. */
 export interface LinkLook {
     color: string;
@@ -71,12 +91,18 @@ export interface LinkLook {
 }
 /** How every note and link is drawn, asked one at a time, so ten thousand cost nothing until drawn. */
 export interface GraphLooks {
+    /** A note's own color, its tone's or its group's, whatever the selection fades. */
+    colorOf(id: string): string;
     /** The typeface the labels are drawn in: the first of the frame's own. */
     font: string;
+    /** What the drawing is laid on, which a name is ringed in so it reads over the links. */
+    ground: 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;
+    /** The quieter ink a name at rest is drawn in, beside the selected note's and its neighbors'. */
+    quiet: string;
     link(source: string, target: string): LinkLook;
     node(id: string): NodeLook;
 }
@@ -84,8 +110,8 @@ export interface GraphLooks {
  * How the graph is drawn for one selection.
  *
  * **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
+ * selecting a note in a graph of thousands is for: the selected note
+ * glowing, the notes it links to and from in their groups' colors 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.
@@ -96,9 +122,9 @@ export interface GraphLooks {
 export declare const looksOf: (options: {
     colors: GraphColors;
     font?: string | undefined;
-    groupOf: (id: string) => string | undefined;
     groups: readonly string[];
     near: ReadonlySet<string>;
+    noteOf: (id: string) => NoteFacts | undefined;
     selected: string | undefined;
     shown: ReadonlySet<string> | undefined;
 }) => GraphLooks;