@fusion.dev/helix-graph 0.126.0 → 0.127.0

package/README.md

@@ -1,7 +1,7 @@
 # @fusion.dev/helix-graph
 
-Connects the Helix `Graph` frame to whatever draws the graph: Sigma.js, cosmos.gl, or a
-driver of your own, colored from your tokens.
+Connects the Helix `Graph` frame to whatever draws the graph: Sigma.js, cosmos.gl,
+three.js, or a driver of your own, colored from your tokens.
 
 ```sh
 bun add @fusion.dev/helix @fusion.dev/helix-graph sigma graphology graphology-layout-forceatlas2
@@ -22,7 +22,9 @@ const frame = document.querySelector('helix-graph')
 frame.nodes = notes // [{ id, label, group, size, x, y }]
 frame.links = links // [{ source, target, label }]
 
-const sigma = new Sigma(new Graph(), document.getElementById('drawing'))
+// The box the drawing goes in: a <div> inside the frame, sized by it.
+const box = frame.querySelector('div')
+const sigma = new Sigma(new Graph(), box)
 const connection = connectGraph(
   frame,
   sigmaDriver(sigma, {
@@ -36,10 +38,20 @@ frame.addEventListener('helix-graph-layout', (event) => save(event.detail.positi
 // After replacing a stylesheet, which no attribute shows:
 connection.restyle()
 
-// Later, when the graph goes away:
+// Lay the graph out again from the start, ignoring every place it has.
+connection.relayout()
+
+// Later, when the graph goes away: the connection first, then the renderer.
 connection.disconnect()
+sigma.kill()
 ```
 
+**The renderer is the page's to free.** After `disconnect()`, call
+`sigma.kill()` for Sigma and `graph.destroy()` for cosmos.gl; `threeDriver`
+makes its own renderer, and `disconnect()` frees it. A frame taken off the
+page without `disconnect()` leaves its renderer running, so disconnect it
+first.
+
 ## What it does
 
 - Draws the frame's `nodes` and `links`, and draws them again when either changes.
@@ -76,14 +88,12 @@ socket.addEventListener('message', ({ data }) => {
 
 **`frame.signal(from, to, { tone })` shows something passing between two
 notes**: a message, a request, a payment. It is drawn as a comet traveling
-from one to the other along a gently bowed path, its tail tapering and turning
-from the first note's color to the second's, or in the tone's color where it
-has one. A small ring spreads from the note it leaves, and the note it reaches
-brightens and ripples. A reply on the same link bows the other way, so the two
-do not run over each other, and in three dimensions the path arcs over the
-shape. It is drawn over the graph without redrawing it, so a busy feed costs a
-few strokes each. A reader who asks for less motion sees the path lit for a
-moment instead.
+from one to the other along the link between them, its tail tapering and
+turning from the first note's color to the second's, or in the tone's color
+where it has one. A small ring spreads from the note it leaves, and the note it
+reaches brightens and ripples. It is drawn over the graph without redrawing it,
+so a busy feed costs a few strokes each. A reader who asks for less motion sees
+the link lit for a moment instead.
 
 ```js
 frame.signal('Checkout', 'Payments', { tone: 'success' })
@@ -101,7 +111,7 @@ Each note can say how it is drawn, in the words Helix's other components use:
 |---|---|---|
 | `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 |
+| `material` | `flat`, `glass`, `frosted` | Matte, 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
@@ -128,11 +138,15 @@ 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.
 
+**A press on a note selects it, and a press where no note is lets it go**,
+so the graph's colors come back, in every driver.
+
 **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.
+their way. With Sigma, `sigmaDriver(sigma, { 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
 
@@ -203,49 +217,60 @@ outline. Pass an SVG path and the box it is drawn in, as the SVG's `viewBox`
 gives it:
 
 ```js
+const brain = document.querySelector('#brain path')
 connectGraph(frame, driver, {
-  stencil: { path: brain.getAttribute('d'), width: 220, height: 170 },
+  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.
+by the even-odd rule, which is how the grooves of a brain show. Every whole
+drawing is shaped, whatever places its notes carry, so places a page kept from
+an earlier drawing come back in the same shape; a note added later is placed
+by the layout beside its neighbors. A shape with no inside to hold the notes
+is warned of in the console, and the graph is laid out instead. `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:
+makes one from what a page has, and a field is a stencil itself.
+`shapeFromModel` is an entry of its own, `@fusion.dev/helix-graph/model`, since
+it loads three.js, so a page that draws a flat shape never bundles it:
 
 | Function | Makes |
 |---|---|
-| `shapeFromModel(url)` | A solid from a glTF model, `.glb` or `.gltf`, every mesh where the model places it. Async; three.js reads the file |
+| `shapeFromModel(url)` | From `/model`: a solid from a glTF model, `.glb` or `.gltf`, every mesh where the model places it. Async; three.js reads the file, and an error names the model |
 | `shapeFromTriangles(positions, index)` | A solid from a closed surface of triangles a page already holds |
 | `shapeFromSvg(svg)` | A flat field from an `<svg>` or its markup: every path, rectangle, circle, ellipse and polygon in its `viewBox` |
 | `shapeFromImage(image, { threshold })` | A flat field from an image's opaque pixels |
 | `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 |
-| `sphere`, `torus`, `box` | Solids measured exactly from their formulas |
+| `sphere({ radius })`, `torus({ radius, tube })`, `cuboid({ width, height, depth, round })` | Solids measured exactly from their formulas |
 | `onSphere(field, { radius, thickness })` | A flat map wrapped round a ball, as a world map is round a globe |
 | `surfaceOf(field, { at, cells })` | The surface of a solid as triangles, to draw or to save as a model |
 
 ```js
-const stencil = { ...(await shapeFromModel('/models/brain.glb')), place: 'surface' }
+import { shapeFromModel } from '@fusion.dev/helix-graph/model'
+
+const stencil = { ...(await shapeFromModel('/models/brain.glb')), place: 'surface' as const }
 connectGraph(frame, threeDriver(box), { stencil })
 ```
 
+In a module script, as `await` at the top level needs. In TypeScript,
+`as const` keeps `place` the word the stencil takes, where a plain object
+widens it to any string.
+
 **`regions` sends each group to a named part of the shape**, such as a lobe
 of a brain or a state on a map:
 
 ```js
 const stencil = {
   ...(await shapeFromModel('/models/brain.glb')),
-  place: 'surface',
+  place: 'surface' as const,
   regions: { Vision: 'occipital', Hearing: 'temporal', Balance: 'cerebellum' },
 }
 ```
@@ -253,8 +278,10 @@ const stencil = {
 A model's parts are its meshes, named as it names them, where it has two or
 more; an SVG's are its shapes with an `id`, or in a group with one; and a
 field a page makes says its own with `regionOf(x, y, z)`. Each part fills
-evenly with the groups sent to it, and a group sent nowhere, or to a part the
-shape does not have, shares the parts no group claims.
+evenly with the groups sent to it, and a group sent nowhere shares the parts
+no group claims. A part the shape does not have, as one misspelled, is warned
+of in the console with the parts it has, and its groups are placed with the
+rest.
 
 **A model is read a column of cells at a time**, so one of a hundred thousand
 triangles becomes a field in a moment. Any closed mesh works; a mesh with
@@ -278,7 +305,7 @@ 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' },
+  stencil: { ...inflate(shapeFromPath(path, 220, 170), { depth: 140 }), place: 'surface' as const },
 })
 ```
 
@@ -300,13 +327,17 @@ connectGraph(frame, threeDriver(box), {
   who asks for less motion.
 - **The far side recedes.** Through a graph, its far notes are a little
   quieter than its near ones.
+- **Edges are smooth at any density.** The drawing has half as many pixels again as the screen, at least two for each of the page's, and links are lines of a set width with smooth edges, where WebGL draws its own a device pixel wide.
 - **Each group is named over its near side**, and a group's name moves a line
   where it would cover another's.
+- **It draws only while something moves**: the reader's hands, the turning, a
+  layout, or a glide. It draws nothing while its box is out of view.
 
 | `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 |
+| `density` | screen × 1.5, 2 to 3 | How many pixels the drawing has for each of the page's; fewer is faster on a slow GPU |
+| `shape` | `circle` | `square` or `diamond`, for every note that does not say; a `ring` is drawn as a circle |
 | `groupLabels` | `true` | `false` leaves each group unnamed |
 | `layoutLimit` | `10000` | The longest a layout runs, in milliseconds |
 
@@ -314,11 +345,12 @@ connectGraph(frame, threeDriver(box), {
 
 | Import | What |
 |---|---|
-| `@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` | `shapeFromModel`, `shapeFromTriangles`, `shapeFromSvg`, `shapeFromImage`, `shapeFromPath`, `shapeFromInside`, `inflate`, `sphere`, `torus`, `box`, `onSphere`, `surfaceOf`, and the `ShapeField` type |
+| `@fusion.dev/helix-graph` | `connectGraph`, `diffGraph`, `fitToStencil`, `graphColorsFrom`, `linkKey`, `seedPositions`, and the types `ConnectGraphOptions`, `DrawnLink`, `DrawnNode`, `GraphChanges`, `GraphColors`, `GraphConnection`, `GraphDriver`, `GraphGroup`, `GraphLooks`, `GraphPoint`, `GraphStencil`, `GraphTone`, `LinkLook`, `NodeLook`, `SeedLink`, `SeedNode`, `ShapeField` and `StencilFrame` |
+| `@fusion.dev/helix-graph/sigma` | `sigmaDriver(sigma, options)`, and the types `SigmaDriverOptions`, `SigmaGraph`, `SigmaLayout` and `SigmaRenderer` |
+| `@fusion.dev/helix-graph/cosmos` | `cosmosDriver(graph, box, options)`, and the types `CosmosDriverOptions` and `CosmosGraph` |
+| `@fusion.dev/helix-graph/three` | `threeDriver(box, options)`, and the type `ThreeDriverOptions` |
+| `@fusion.dev/helix-graph/shapes` | `shapeFromTriangles`, `shapeFromSvg`, `shapeFromImage`, `shapeFromPath`, `shapeFromInside`, `inflate`, `sphere`, `torus`, `cuboid`, `onSphere`, `surfaceOf`, and the types `ImageOptions`, `ShapeField` and `TriangleOptions` |
+| `@fusion.dev/helix-graph/model` | `shapeFromModel(source, options)`, which needs three.js |
 
 **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
@@ -330,12 +362,12 @@ 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` |
+| `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`; `shell`, how thick a surface's shell is as a share of the shape's size, `0.04` by default; and `regions`, the part each group goes to |
 
 | `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 |
+| `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 |
@@ -344,7 +376,7 @@ Sigma 3 is a peer dependency.
 
 | `cosmosDriver` option | Default | What else it takes |
 |---|---|---|
-| `shape` | `circle` | `square` or `diamond`, for every note that does not say |
+| `shape` | `circle` | `square` or `diamond`, for every note that does not say; a `ring` is drawn as a circle |
 | `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 |

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

@@ -1,4 +1,4 @@
-import type { GraphPoint, SeedLink } from './seed.js';
+import { type GraphPoint, type SeedLink } from './seed.js';
 /** A note as the arrangement reads it: its group, if it has one. */
 export interface ArrangedNode {
     group?: string | undefined;
@@ -25,6 +25,8 @@ export declare const hubsOf: (nodes: readonly ArrangedNode[], links: readonly Se
  * 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 }?: {
+export declare const arrangeByGroup: (nodes: readonly ArrangedNode[], links: readonly SeedLink[], { hubs, solid, }?: {
+    /** Each note's hub and the notes' ranks, where the caller worked them out already. */
+    hubs?: ReturnType<typeof hubsOf>;
     solid?: boolean;
 }) => Map<string, GraphPoint>;

package/dist/connect-graph/arrange.js

@@ -1,4 +1,4 @@
-const TURN = Math.PI * (3 - Math.sqrt(5));
+import { neighborsOf, TURN } from './seed.js';
 const STEP = (Math.sqrt(5) - 1) / 2;
 const spiral = (at, spacing, solid) => {
     if (!solid) {
@@ -32,25 +32,8 @@ const plus = (one, other) => ({
 });
 export const hubsOf = (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 neighbors = neighborsOf(links, (id) => groupOf.has(id));
+    const rank = (id) => neighbors.get(id)?.length ?? 0;
     const above = (one, other) => rank(one) > rank(other) || (rank(one) === rank(other) && one < other);
     const parent = new Map();
     for (const { id } of nodes) {
@@ -77,9 +60,9 @@ export const hubsOf = (nodes, links) => {
     };
     return { hubOf, rank };
 };
-export const arrangeByGroup = (nodes, links, { solid = false } = {}) => {
+export const arrangeByGroup = (nodes, links, { hubs = hubsOf(nodes, links), solid = false, } = {}) => {
     const groupOf = new Map(nodes.map((node) => [node.id, node.group ?? '']));
-    const { hubOf, rank } = hubsOf(nodes, links);
+    const { hubOf, rank } = hubs;
     const groups = new Map();
     for (const { id } of nodes) {
         const group = groupOf.get(id);

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

@@ -57,8 +57,12 @@ export interface GraphDriver {
      * 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;
+    /**
+     * Calls `press` with a note's `id` when the reader presses it in the
+     * drawing, and with undefined when they press where no note is. Returns
+     * what stops listening.
+     */
+    onPress?(press: (id: string | undefined) => void): () => void;
     /**
      * Runs a layout over the drawn graph, moving the notes in `unplaced` and
      * holding the rest, and calls `placed` once it has settled with where every
@@ -116,8 +120,11 @@ export interface ConnectGraphOptions {
      * 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.
+     * from the first frame. Every whole drawing is shaped, whatever places its
+     * notes carry, so places a page kept from an earlier drawing are shaped
+     * again the same way; a note added later is placed by the layout beside
+     * its neighbors. A shape that holds none of the notes is warned of, and
+     * the graph is laid out instead.
      */
     stencil?: GraphStencil | undefined;
 }
@@ -125,7 +132,10 @@ export interface ConnectGraphOptions {
 export interface GraphConnection {
     /** Stops answering the frame and puts back everything connecting changed. */
     disconnect(): void;
-    /** Lays the graph out again from where it starts, ignoring where the last layout put each note. */
+    /**
+     * Lays the graph out again from where it starts, ignoring where the last
+     * layout put each note and the places the page gave its notes.
+     */
     relayout(): void;
     /**
      * Reads the page's colors again. The connection hears a theme that changes
@@ -138,7 +148,9 @@ export interface GraphConnection {
  * Connects a Graph frame to whatever draws the graph.
  *
  * The frame is `helix-graph` or `helix-headless-graph`, and the driver is
- * `sigmaDriver` from `@fusion.dev/helix-graph/sigma` or one of your own. The
+ * `sigmaDriver` from `@fusion.dev/helix-graph/sigma`, `cosmosDriver` from
+ * `./cosmos`, `threeDriver` from `./three`, or one of your own. The page
+ * keeps the renderer it made: after `disconnect()`, kill or destroy it. The
  * 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

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

@@ -4,9 +4,8 @@ import { diffGraph, isEmpty, linkKey, } from './diff.js';
 import { graphColorsFrom, looksOf, toneColor, } from './looks.js';
 import { seedPositions } from './seed.js';
 import { fieldOf, fitInStencil } from './stencil.js';
-const clustersOf = (nodes, links) => {
+const clustersOf = (nodes, hubOf) => {
     const groupOf = new Map(nodes.map((node) => [node.id, node.group ?? '']));
-    const { hubOf } = hubsOf(nodes, links);
     return (id) => [groupOf.get(id) ?? '', hubOf(id)];
 };
 const viewportOf = (frame) => {
@@ -16,7 +15,11 @@ const viewportOf = (frame) => {
 const still = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
 export const connectGraph = (frame, driver, options = {}) => {
     const graph = frame;
+    if (!('nodes' in frame) || typeof graph.requestActive !== 'function') {
+        console.warn('connectGraph: the element given is not a Graph frame (helix-graph or helix-headless-graph), so nothing will be drawn.', frame);
+    }
     let known = new Map();
+    let framed;
     let shapeFrame;
     let drawnNodes = new Map();
     let drawnLinks = new Map();
@@ -29,14 +32,21 @@ export const connectGraph = (frame, driver, options = {}) => {
     let pressed;
     let pending = 0;
     let connected = true;
+    const selectedNote = () => {
+        const active = graph.active;
+        return active && (graph.nodes ?? []).some((node) => node.id === active) ? active : undefined;
+    };
     const restyle = () => {
+        if (!connected) {
+            return;
+        }
         colors ??= graphColorsFrom(frame);
         if (!colors) {
             return;
         }
         const nodes = graph.nodes ?? [];
         const links = graph.links ?? [];
-        const selected = graph.active || undefined;
+        const selected = selectedNote();
         const near = new Set();
         if (selected !== undefined) {
             for (const { source, target } of links) {
@@ -85,7 +95,7 @@ export const connectGraph = (frame, driver, options = {}) => {
             })));
         }
     };
-    const draw = (whole = false) => {
+    const draw = (whole = false, fresh = false) => {
         if (stopSettling) {
             stopSettling();
             stopSettling = undefined;
@@ -99,16 +109,25 @@ export const connectGraph = (frame, driver, options = {}) => {
                 nextLinks.set(linkKey({ source, target }), { label, source, target });
             }
         }
-        let { positions, unplaced } = seedPositions(nodes, [...nextLinks.values()], known);
-        const fit = options.stencil && ids.size > 0 && unplaced.size === ids.size
-            ? fitInStencil(arrangeByGroup(nodes, [...nextLinks.values()], {
-                solid: fieldOf(options.stencil).depth > 0,
-            }), options.stencil, { clustersOf: clustersOf(nodes, [...nextLinks.values()]) })
-            : undefined;
-        const shaped = fit?.positions;
+        const linkList = [...nextLinks.values()];
+        let { positions, unplaced } = seedPositions(fresh ? nodes.map(({ id }) => ({ id })) : nodes, linkList, fresh ? new Map() : known);
+        const shaping = options.stencil !== undefined &&
+            ids.size > 0 &&
+            (first || whole || unplaced.size === ids.size);
+        let fit;
+        if (shaping && options.stencil) {
+            const hubs = hubsOf(nodes, linkList);
+            fit = fitInStencil(arrangeByGroup(nodes, linkList, { hubs, solid: fieldOf(options.stencil).depth > 0 }), options.stencil, { clustersOf: clustersOf(nodes, hubs.hubOf) });
+        }
+        const shaped = fit?.frame ? fit.positions : undefined;
         if (fit?.frame) {
             shapeFrame = fit.frame;
         }
+        else if (shaping) {
+            console.warn('connectGraph: the stencil has no inside to place the notes in, so the graph is laid out instead.', options.stencil);
+            positions = seedPositions(nodes.map(({ id }) => ({ id })), linkList, new Map()).positions;
+            unplaced = new Set(ids);
+        }
         driver.shape?.(options.stencil ? (options.stencil.place ?? 'fill') : undefined, shapeFrame);
         if (shaped) {
             positions = shaped;
@@ -148,7 +167,7 @@ export const connectGraph = (frame, driver, options = {}) => {
         }
         else {
             graph.drawn?.(false);
-            driver.draw({ links: [...nextLinks.values()], nodes: [...nextNodes.values()] });
+            driver.draw({ links: linkList, nodes: [...nextNodes.values()] });
         }
         drawnNodes = nextNodes;
         drawnLinks = nextLinks;
@@ -162,6 +181,9 @@ export const connectGraph = (frame, driver, options = {}) => {
             waiting = unplaced;
             stopSettling = driver.settle(unplaced, (settled) => {
                 stopSettling = undefined;
+                if (!connected) {
+                    return;
+                }
                 waiting = new Set();
                 known = new Map(settled);
                 for (const [id, at] of settled) {
@@ -204,32 +226,44 @@ export const connectGraph = (frame, driver, options = {}) => {
                 ? { from: current.colorOf(from), to: current.colorOf(to) }
                 : undefined, !still());
     };
+    const frameSelection = () => {
+        const selected = selectedNote();
+        if (selected === framed) {
+            pressed = undefined;
+            return;
+        }
+        framed = selected;
+        if (selected !== undefined &&
+            selected !== pressed &&
+            options.center !== false &&
+            drawnNodes.has(selected)) {
+            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;
+    };
     const handlePartChange = (event) => {
         const { kind } = event.detail;
         if (kind === 'data') {
             draw();
+            frameSelection();
         }
         else if (kind === 'focus') {
             restyle();
-            const selected = graph.active;
-            if (selected && selected !== pressed && options.center !== false) {
-                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;
+            frameSelection();
         }
         else {
             driver.gestures?.(graph.gestureMode ?? 'free');
@@ -253,6 +287,13 @@ export const connectGraph = (frame, driver, options = {}) => {
     frame.addEventListener(HelixGraphPanEvent.eventName, handlePan);
     frame.addEventListener(HelixGraphZoomEvent.eventName, handleZoom);
     const stopPress = driver.onPress?.((id) => {
+        if (id === undefined) {
+            pressed = undefined;
+            if (graph.active) {
+                graph.requestActive?.('');
+            }
+            return;
+        }
         pressed = id;
         if (graph.requestActive?.(id) === false || graph.active !== id) {
             pressed = undefined;
@@ -296,9 +337,12 @@ export const connectGraph = (frame, driver, options = {}) => {
             graph.drawn?.(false);
         },
         relayout: () => {
+            if (!connected) {
+                return;
+            }
             known = new Map();
             waiting = new Set();
-            draw(true);
+            draw(true, true);
         },
         restyle: () => {
             colors = null;

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

@@ -1,18 +1,25 @@
 /** A note as the renderer draws it, placed. */
 export interface DrawnNode {
+    /** The note's `id`, as the frame holds it. */
     id: string;
+    /** The name drawn beside it: its `label`, or its `id` where it has none. */
     label: string;
     /** How large it is drawn, relative to the others: the note's `size`, or from how many links it has. */
     size: number;
+    /** Across, in the renderer's own units. */
     x: number;
+    /** Up, in the renderer's own units. */
     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 {
+    /** What the link says, where it says anything. */
     label?: string | undefined;
+    /** The `id` of the note the link runs from. */
     source: string;
+    /** The `id` of the note the link runs to. */
     target: string;
 }
 /** What changed between two drawings of a graph, which a renderer applies in place. */

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

@@ -42,10 +42,13 @@ export interface GraphColors {
  * next change.
  */
 export declare const graphColorsFrom: (element: Element) => GraphColors | null;
+/** An `rgb()` color's red, green and blue, from 0 to 255, each `missing` where the color does not say. */
+export declare const rgbOf: (color: string, missing?: number) => [number, number, number];
 /** One `rgb()` moved toward another by `amount`, from 0 to 1. */
 export declare const mixRgb: (from: string, to: string, amount: number) => string;
 /** How one note is drawn. */
 export interface NodeLook {
+    /** The color it is drawn in: its own, or faded toward the ground where the selection sets it back. */
     color: string;
     /** Outside the local graph that `depth` keeps. */
     hidden: boolean;
@@ -85,8 +88,11 @@ export interface NoteFacts {
 export declare const toneColor: (colors: GraphColors, tone: GraphTone | undefined) => string;
 /** How one link is drawn. */
 export interface LinkLook {
+    /** The color it is drawn in. */
     color: string;
+    /** Outside the local graph that `depth` keeps. */
     hidden: boolean;
+    /** Drawn over the rest, as a link that touches the selected note is. */
     raised: boolean;
 }
 /** How every note and link is drawn, asked one at a time, so ten thousand cost nothing until drawn. */
@@ -103,7 +109,9 @@ export interface GraphLooks {
     overlay: string;
     /** The quieter ink a name at rest is drawn in, beside the selected note's and its neighbors'. */
     quiet: string;
+    /** How the link from `source` to `target` is drawn. */
     link(source: string, target: string): LinkLook;
+    /** How the note `id` is drawn. */
     node(id: string): NodeLook;
 }
 /**

package/dist/connect-graph/looks.js

@@ -48,10 +48,13 @@ export const graphColorsFrom = (element) => {
         probe.remove();
     }
 };
+export const rgbOf = (color, missing = 128) => {
+    const [red = missing, green = missing, blue = missing] = color.match(/[\d.]+/g)?.map(Number) ?? [];
+    return [red, green, blue];
+};
 export const mixRgb = (from, to, amount) => {
-    const parts = (value) => value.match(/[\d.]+/g)?.map(Number) ?? [0, 0, 0];
-    const [one, other] = [parts(from), parts(to)];
-    const channel = (at) => Math.round((one[at] ?? 0) + ((other[at] ?? 0) - (one[at] ?? 0)) * amount);
+    const [one, other] = [rgbOf(from, 0), rgbOf(to, 0)];
+    const channel = (at) => Math.round(one[at] + (other[at] - one[at]) * amount);
     return `rgb(${channel(0)}, ${channel(1)}, ${channel(2)})`;
 };
 export const toneColor = (colors, tone) => tone === undefined || tone === 'primary'