@fusion.dev/helix-graph 0.120.0 → 0.122.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,212 @@ 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.
+
+**Every shape becomes a distance field**: for each point in its box, how far
+it is from the shape's edge, below zero inside. `@fusion.dev/helix-graph/shapes`
+makes one from what a page has, and a field is a stencil itself:
+
+| Function | Makes |
+|---|---|
+| `shapeFromPath(path, width, height)` | A flat field from an SVG path |
+| `shapeFromInside(inside, { width, height, depth })` | A flat field, or a solid where `depth` is given, from a test of what is inside |
+| `inflate(field, { depth, roundness })` | A solid puffed out of a flat field, as a cushion is, cut through where the flat shape has a hole |
+
+## In three dimensions
+
+**`threeDriver(box)` draws the graph in three dimensions** with three.js, to
+be turned and looked into. The frame, the list, selection, names and signals
+are the same as in two:
+
+```sh
+bun add three d3-force-3d
+```
+
+```js
+import { connectGraph } from '@fusion.dev/helix-graph'
+import { inflate, shapeFromPath } from '@fusion.dev/helix-graph/shapes'
+import { threeDriver } from '@fusion.dev/helix-graph/three'
+
+connectGraph(frame, threeDriver(box), {
+  stencil: { ...inflate(shapeFromPath(path, 220, 170), { depth: 140 }), place: 'surface' },
+})
+```
+
+- **A solid stencil draws the notes in the solid**: all through it, or, with
+  `place: 'surface'`, in a thin shell just inside its edge, which is how a
+  solid reads as the thing it is shaped like. Each group takes one side of
+  the shape, and each hub's notes a patch around it.
+- **Without a stencil, a layout runs in three dimensions** with d3-force-3d.
+- **Dragging turns the graph, and the wheel and a pinch bring it nearer.** It
+  turns slowly by itself while nobody is handling it, and never for a reader
+  who asks for less motion.
+- **The far side recedes.** On a surface, the far side of the shape falls to
+  a tenth, so the near side reads; through a graph, its far notes are a
+  little quieter than its near ones.
+- **Each group is named over its near side**, and a group's name moves a line
+  where it would cover another's.
+
+| `threeDriver` option | Default | What else it takes |
+|---|---|---|
+| `autoRotate` | `true` | `false` leaves the graph still until the reader turns it |
+| `shape` | `circle` | `square` or `diamond`, for every note that does not say |
+| `groupLabels` | `true` | `false` leaves each group unnamed |
+| `layoutLimit` | `10000` | The longest a layout runs, in milliseconds |
+
 ## 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)` |
+| `@fusion.dev/helix-graph/three` | `threeDriver(box, options)` |
+| `@fusion.dev/helix-graph/shapes` | `shapeFromPath`, `shapeFromInside`, `inflate`, and the `ShapeField` type |
 
-**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, cosmos.gl, three.js and d3-force-3d 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: a field from `shapes`, `{ path, width, height }` or `{ inside, width, height }`, with `place`, `fill` or `surface` |
 
 | `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,20 @@
+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, or a sphere in a solid, 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[], { solid }?: {
+    solid?: boolean;
+}) => Map<string, GraphPoint>;

package/dist/connect-graph/arrange.js

@@ -0,0 +1,125 @@
+const TURN = Math.PI * (3 - Math.sqrt(5));
+const STEP = (Math.sqrt(5) - 1) / 2;
+const spiral = (at, spacing, solid) => {
+    if (!solid) {
+        return {
+            x: Math.cos(at * TURN) * Math.sqrt(at + 0.5) * spacing,
+            y: Math.sin(at * TURN) * Math.sqrt(at + 0.5) * spacing,
+        };
+    }
+    const height = 1 - 2 * ((at * STEP) % 1);
+    const around = Math.sqrt(1 - height * height);
+    const out = Math.cbrt(at + 0.5) * spacing;
+    return {
+        x: Math.cos(at * TURN) * around * out,
+        y: height * out,
+        z: Math.sin(at * TURN) * around * out,
+    };
+};
+const around = (at, count, solid) => {
+    if (!solid) {
+        const turn = (at / count) * Math.PI * 2;
+        return { x: Math.cos(turn), y: Math.sin(turn) };
+    }
+    const height = 1 - (2 * (at + 0.5)) / count;
+    const ring = Math.sqrt(1 - height * height);
+    return { x: Math.cos(at * TURN) * ring, y: height, z: Math.sin(at * TURN) * ring };
+};
+const plus = (one, other) => ({
+    x: one.x + other.x,
+    y: one.y + other.y,
+    ...(one.z === undefined && other.z === undefined ? {} : { z: (one.z ?? 0) + (other.z ?? 0) }),
+});
+export const arrangeByGroup = (nodes, links, { solid = false } = {}) => {
+    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 (solid ? Math.cbrt(count) : Math.sqrt(count)) * 1.5;
+    };
+    const radii = [...groups.values()].map(radiusOf);
+    const widest = Math.max(0, ...radii);
+    const ring = groups.size > 1
+        ? solid
+            ? (widest * 2.4) / Math.sqrt((4 * Math.PI) / groups.size)
+            : (widest * 1.2) / Math.sin(Math.PI / groups.size)
+        : 0;
+    const positions = new Map();
+    [...groups.values()].forEach((hubs, at) => {
+        const way = around(at, groups.size, solid);
+        const middle = {
+            x: way.x * ring,
+            y: way.y * ring,
+            ...(solid ? { z: (way.z ?? 0) * 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 center = plus(middle, spiral(place, (solid ? Math.cbrt(mean) : Math.sqrt(mean)) * 2, solid));
+            positions.set(hub, center);
+            members
+                .sort((one, other) => rank(other) - rank(one))
+                .forEach((member, step) => {
+                positions.set(member, plus(center, spiral(step + 1, 1, solid)));
+            });
+        });
+    });
+    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,33 @@ 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;
+    /**
+     * Where in a shape the notes are drawn, where a `stencil` gives one:
+     * `surface`, a shell, whose far side a renderer that draws in three
+     * dimensions sets back so its near side reads; `fill`, all through it; or
+     * undefined, no shape.
+     */
+    shape?(place: 'fill' | 'surface' | undefined): 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 +110,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 { fieldOf, 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,16 +93,35 @@ 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()], {
+                solid: fieldOf(options.stencil).depth > 0,
+            }), options.stencil)
+            : undefined;
+        driver.shape?.(options.stencil ? (options.stencil.place ?? 'fill') : 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,
+                ...(at.z === undefined ? {} : { z: at.z }),
             });
         }
         for (const id of waiting) {
@@ -103,7 +144,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;
@@ -114,20 +157,25 @@ export const connectGraph = (frame, driver, options = {}) => {
                 for (const [id, at] of settled) {
                     const node = drawnNodes.get(id);
                     if (node) {
-                        drawnNodes.set(id, { ...node, x: at.x, y: at.y });
+                        drawnNodes.set(id, { ...node, x: at.x, y: at.y, z: at.z });
                     }
                 }
                 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 +187,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 +203,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,10 +2,12 @@
 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;
+    /** How near the viewer, for a renderer that draws in three dimensions. */
+    z?: number | undefined;
 }
 /** A link as the renderer draws it, between two notes the graph holds. */
 export interface DrawnLink {