@fusion.dev/helix-graph 0.126.0 → 0.128.0

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

@@ -1,6 +1,8 @@
 /** A point in the renderer's own units. */
 export interface GraphPoint {
+    /** Across. */
     x: number;
+    /** Up. */
     y: number;
     /** How near the viewer, for a renderer that draws in three dimensions. */
     z?: number | undefined;
@@ -17,6 +19,13 @@ export interface SeedLink {
     source: string;
     target: string;
 }
+/** The angle between one place and the next on a spiral: the golden angle, which never lines two up. */
+export declare const TURN: number;
+/**
+ * Each note's neighbors across the links, both ways, kept to the links
+ * whose two ends `keep` allows where it is given.
+ */
+export declare const neighborsOf: (links: readonly SeedLink[], keep?: (id: string) => boolean) => Map<string, string[]>;
 /**
  * Where each note starts, and which of them a layout still has to place.
  *

package/dist/connect-graph/seed.js

@@ -1,4 +1,23 @@
-const TURN = Math.PI * (3 - Math.sqrt(5));
+export const TURN = Math.PI * (3 - Math.sqrt(5));
+export const neighborsOf = (links, keep) => {
+    const neighbors = new Map();
+    const add = (from, to) => {
+        const list = neighbors.get(from);
+        if (list) {
+            list.push(to);
+        }
+        else {
+            neighbors.set(from, [to]);
+        }
+    };
+    for (const { source, target } of links) {
+        if (!keep || (keep(source) && keep(target))) {
+            add(source, target);
+            add(target, source);
+        }
+    }
+    return neighbors;
+};
 const NEAR = 0.5;
 const nudge = (id) => {
     let hash = 2166136261;
@@ -26,20 +45,7 @@ export const seedPositions = (nodes, links, known = new Map()) => {
             }
         }
     }
-    const neighbors = new Map();
-    const add = (from, to) => {
-        const list = neighbors.get(from);
-        if (list) {
-            list.push(to);
-        }
-        else {
-            neighbors.set(from, [to]);
-        }
-    };
-    for (const { source, target } of links) {
-        add(source, target);
-        add(target, source);
-    }
+    const neighbors = neighborsOf(links);
     let spiral = positions.size;
     for (const node of nodes) {
         if (positions.has(node.id)) {

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

@@ -1,5 +1,5 @@
+import { type ShapeField } from '../shapes/shape-field.js';
 import type { GraphPoint } from './seed.js';
-import { type ShapeField } from './shape-field.js';
 /**
  * A shape the notes are drawn in. **Any shape field**, flat or solid, such as
  * `inflate` makes; or, flat, an SVG path in a box `width` by `height`, as an
@@ -63,7 +63,9 @@ export declare const fitToStencil: (positions: ReadonlyMap<string, GraphPoint>,
  * `middle.y - (y - height / 2) * scale` and `middle.z + (z - depth / 2) * scale`.
  */
 export interface StencilFrame {
+    /** The stencil's shape, as a field, whatever form it was given in. */
     field: ShapeField;
+    /** Where the middle of the stencil's box was put, in the places' units. */
     middle: {
         x: number;
         y: number;

package/dist/connect-graph/stencil.js

@@ -1,4 +1,4 @@
-import { fieldFromInside, fieldFromPath } from './shape-field.js';
+import { fieldFromInside, fieldFromPath } from '../shapes/shape-field.js';
 import { surfaceWeb } from './surface-web.js';
 const PROBE = { flat: 64, solid: 32 };
 const SHELL = 0.04;
@@ -78,9 +78,9 @@ export const placesIn = (field, count, { place = 'fill', shell = SHELL } = {}) =
     }
     return [];
 };
-const placesByRegion = (field, wanted, options) => {
+const placesByRegion = (field, asked, options) => {
     const regionOf = field.regionOf;
-    const count = [...wanted.values()].reduce((sum, many) => sum + many, 0);
+    const count = [...asked.values()].reduce((sum, many) => sum + many, 0);
     if (!regionOf) {
         return undefined;
     }
@@ -101,6 +101,16 @@ const placesByRegion = (field, wanted, options) => {
                 byRegion.set(region, [place]);
             }
         });
+        const found = new Set([...byRegion.keys()].filter((region) => region !== undefined));
+        const missing = [...asked.keys()].filter((region) => region !== undefined && !found.has(region));
+        if (missing.length > 0 && times * 2 <= 24) {
+            continue;
+        }
+        const wanted = new Map();
+        for (const [region, many] of asked) {
+            const part = region !== undefined && found.has(region) ? region : undefined;
+            wanted.set(part, (wanted.get(part) ?? 0) + many);
+        }
         const claimed = new Set([...wanted.keys()].filter((region) => region !== undefined));
         const places = [];
         const regions = [];
@@ -130,7 +140,7 @@ const placesByRegion = (field, wanted, options) => {
             places.push(place);
             regions.push(undefined);
         }
-        return { places, regions };
+        return { found, missing, places, regions };
     }
     return undefined;
 };
@@ -163,18 +173,30 @@ export const fitInStencil = (positions, stencil, { clustersOf, } = {}) => {
         const group = groupOf(note.id);
         return [note.id, group === undefined ? undefined : stencil.regions?.[group]];
     }));
-    const wanted = new Map();
+    const asked = new Map();
     for (const region of noteRegion.values()) {
-        wanted.set(region, (wanted.get(region) ?? 0) + 1);
+        asked.set(region, (asked.get(region) ?? 0) + 1);
     }
-    const regional = stencil.regions && [...wanted.keys()].some((region) => region !== undefined)
-        ? placesByRegion(field, wanted, options)
+    const regional = [...asked.keys()].some((region) => region !== undefined)
+        ? placesByRegion(field, asked, options)
         : undefined;
-    if (!regional) {
-        for (const id of noteRegion.keys()) {
+    if (regional && regional.missing.length > 0) {
+        console.warn(`fitInStencil: the shape has no part named ${regional.missing.map((part) => `"${part}"`).join(', ')}, so the notes sent there are placed with the rest. Its parts: ${[...regional.found].join(', ') || 'none'}.`);
+    }
+    else if (!regional && [...asked.keys()].some((region) => region !== undefined)) {
+        console.warn(field.regionOf
+            ? 'fitInStencil: the parts named in regions are too small for the notes sent to them, so the notes are placed over the whole shape.'
+            : 'fitInStencil: the shape has no named parts, so regions is not used and the notes are placed over the whole shape.');
+    }
+    for (const [id, region] of noteRegion) {
+        if (region !== undefined && !regional?.found.has(region)) {
             noteRegion.set(id, undefined);
         }
     }
+    const wanted = new Map();
+    for (const region of noteRegion.values()) {
+        wanted.set(region, (wanted.get(region) ?? 0) + 1);
+    }
     const places = regional?.places ?? placesIn(field, notes.length, options);
     const placeRegion = regional?.regions ?? places.map(() => undefined);
     if (places.length < notes.length) {

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

@@ -1,5 +1,5 @@
 import type { GraphDriver } from '../connect-graph/connect-graph.js';
-import type { NodeLook } from '../connect-graph/looks.js';
+import { type NodeLook } from '../connect-graph/looks.js';
 /** A cosmos.gl graph, as far as the driver calls it. */
 export interface CosmosGraph {
     fitView(duration?: number, padding?: number): void;
@@ -24,7 +24,7 @@ export interface CosmosGraph {
     setPointShapes(pointShapes: Float32Array): void;
     setPointSizes(pointSizes: Float32Array): void;
     setZoomLevel(value: number, duration?: number): void;
-    setZoomTransformByPointPositions(positions: Float32Array, duration?: number, scale?: number): void;
+    setZoomTransformByPointPositions(positions: Float32Array, duration?: number, scale?: number, padding?: number): void;
     spaceToScreenPosition(spacePosition: [number, number]): [number, number];
     spaceToScreenRadius(spaceRadius: number): number;
     start(alpha?: number): void;
@@ -40,7 +40,7 @@ export interface CosmosDriverOptions {
      * default, past where twenty thousand notes settle on a laptop's GPU.
      */
     layoutLimit?: number | undefined;
-    /** A note's shape where it does not say: `circle` by default, `square` or `diamond`. */
+    /** A note's shape where it does not say: `circle` by default, `square` or `diamond`. A `ring` is drawn as a circle. */
     shape?: NodeLook['shape'];
     /** The size of cosmos.gl's space, as its own `spaceSize` says. 4096 by default. */
     spaceSize?: number | undefined;
@@ -62,6 +62,7 @@ export interface CosmosDriverOptions {
  * each group, over the drawing, as the Sigma driver does.
  *
  * **It is `@cosmos.gl/graph`, which is MIT**, and not Cosmograph, which is
- * licensed for noncommercial use only.
+ * licensed for noncommercial use only. The graph is the page's: after
+ * `disconnect()`, `graph.destroy()` frees it.
  */
 export declare const cosmosDriver: (graph: CosmosGraph, container: HTMLElement, options?: CosmosDriverOptions) => GraphDriver;

package/dist/cosmos/cosmos-driver.js

@@ -1,3 +1,5 @@
+import { linkKey } from '../connect-graph/diff.js';
+import { rgbOf } from '../connect-graph/looks.js';
 import { gesturesHeld, groupsOver, namesOver, signalsOver, } from '../overlay/overlay.js';
 const SHAPES = { circle: 0, diamond: 3, ring: 0, square: 1 };
 const STEP = 250;
@@ -9,8 +11,10 @@ const pixels = (size) => 0.5 * (1.6 + 1.35 * Math.max(size, 0));
 const CLUSTER = 0.1;
 const FOLLOW = 1000;
 const PADDING = 0.08;
+const SIGNALED = 2500;
+const still = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
 const channels = (color, alpha = 1) => {
-    const [red = 128, green = 128, blue = 128] = color.match(/[\d.]+/g)?.map(Number) ?? [];
+    const [red, green, blue] = rgbOf(color);
     return [red / 255, green / 255, blue / 255, alpha];
 };
 export const cosmosDriver = (graph, container, options = {}) => {
@@ -25,6 +29,7 @@ export const cosmosDriver = (graph, container, options = {}) => {
     let near = new Set();
     let groupSample = [];
     let following = new Set();
+    const signaled = new Map();
     let moved = false;
     let stopped = false;
     let uploaded = 0;
@@ -51,8 +56,17 @@ export const cosmosDriver = (graph, container, options = {}) => {
         if (hovered !== undefined) {
             next.add(hovered);
         }
+        const now = performance.now();
         for (const at of extra) {
-            next.add(at);
+            signaled.set(at, now + SIGNALED);
+        }
+        for (const [at, until] of signaled) {
+            if (until < now) {
+                signaled.delete(at);
+            }
+            else {
+                next.add(at);
+            }
         }
         if (next.size !== following.size || [...next].some((at) => !following.has(at))) {
             following = next;
@@ -80,7 +94,7 @@ export const cosmosDriver = (graph, container, options = {}) => {
     };
     const held = gesturesHeld(container);
     const signals = signalsOver(container, onScreen);
-    const groups = groupsOver(container, onScreen);
+    const groups = groupsOver(container, onScreen, () => names.boxes());
     const names = namesOver(container, onScreen);
     const drawNames = () => {
         const lit = hovered === undefined ? undefined : ids[hovered];
@@ -96,10 +110,11 @@ export const cosmosDriver = (graph, container, options = {}) => {
     const flatNow = () => live()
         ? graph.getPointPositions()
         : ids.flatMap((id) => toSpace(drawnNow.get(id) ?? { x: 0, y: 0 }));
-    const fitAll = (duration) => {
+    const fitAll = (asked) => {
         if (stopped) {
             return;
         }
+        const duration = still() ? 0 : asked;
         if (!graph.isReady) {
             void graph.ready.then(() => requestAnimationFrame(() => fitAll(duration)));
             return;
@@ -123,30 +138,59 @@ export const cosmosDriver = (graph, container, options = {}) => {
             graph.setConfigPartial({ pointSizeScale: by });
             if (Math.abs(clarity() - painted) > 0.04) {
                 paintLinks();
-                graph.render();
+                graph.render(undefined, 0);
             }
         }
     };
     const clarity = () => FAINT + (1 - FAINT) * Math.min(Math.max((grown - 1) / 0.8, 0), 1);
     let painted = 1;
+    let linkColors = new Float32Array(0);
+    let widths = new Float32Array(0);
+    let linksOf = new Map();
+    const paintLink = (at, lit) => {
+        const link = links[at];
+        const look = looks.link(link.source, link.target);
+        const touches = lit !== undefined && (link.source === lit || link.target === lit);
+        const whole = look.raised || touches;
+        linkColors.set(channels(touches ? looks.node(lit).color : look.color, look.hidden ? 0 : whole ? 1 : painted), at * 4);
+        widths[at] = whole ? 1.6 : 0.8;
+    };
     const paintLinks = () => {
         if (!looks) {
             return;
         }
         painted = clarity();
-        const linkColors = new Float32Array(links.length * 4);
-        const widths = new Float32Array(links.length);
+        if (linkColors.length !== links.length * 4) {
+            linkColors = new Float32Array(links.length * 4);
+            widths = new Float32Array(links.length);
+        }
         const lit = hovered === undefined ? undefined : ids[hovered];
-        links.forEach((link, at) => {
-            const look = looks.link(link.source, link.target);
-            const touches = lit !== undefined && (link.source === lit || link.target === lit);
-            const whole = look.raised || touches;
-            linkColors.set(channels(touches ? looks.node(lit).color : look.color, look.hidden ? 0 : whole ? 1 : painted), at * 4);
-            widths[at] = whole ? 1.6 : 0.8;
-        });
+        for (let at = 0; at < links.length; at++) {
+            paintLink(at, lit);
+        }
+        graph.setLinkColors(linkColors);
+        graph.setLinkWidths(widths);
+    };
+    const hover = (next) => {
+        const was = hovered === undefined ? undefined : ids[hovered];
+        hovered = next;
+        container.style.cursor = next === undefined ? cursor : 'pointer';
+        if (!looks) {
+            return;
+        }
+        const lit = next === undefined ? undefined : ids[next];
+        for (const id of [was, lit]) {
+            for (const at of id === undefined ? [] : (linksOf.get(id) ?? [])) {
+                paintLink(at, lit);
+            }
+        }
         graph.setLinkColors(linkColors);
         graph.setLinkWidths(widths);
+        follow();
+        graph.render(undefined, 0);
+        redraw();
     };
+    const cursor = container.style.cursor;
     const paint = (transition = 0) => {
         if (!looks) {
             return;
@@ -181,12 +225,7 @@ export const cosmosDriver = (graph, container, options = {}) => {
             hoveredPointRingColor: channels(looks.ink, 0.6),
         });
         follow();
-        if (transition > 0) {
-            graph.render(undefined, transition);
-        }
-        else {
-            graph.render();
-        }
+        graph.render(undefined, still() ? 0 : transition);
         redraw();
     };
     const load = (nodes, next, positions, transition = 0) => {
@@ -194,7 +233,20 @@ export const cosmosDriver = (graph, container, options = {}) => {
         index = new Map(ids.map((id, at) => [id, at]));
         drawnNow = new Map(nodes.map((node) => [node.id, node]));
         sizes = nodes.map((node) => pixels(node.size));
+        hovered = undefined;
         links = next.filter((link) => index.has(link.source) && index.has(link.target));
+        linksOf = new Map();
+        links.forEach((link, at) => {
+            for (const end of [link.source, link.target]) {
+                const list = linksOf.get(end);
+                if (list) {
+                    list.push(at);
+                }
+                else {
+                    linksOf.set(end, [at]);
+                }
+            }
+        });
         const pairs = new Float32Array(links.length * 2);
         links.forEach((link, at) => {
             pairs[at * 2] = index.get(link.source);
@@ -215,14 +267,8 @@ export const cosmosDriver = (graph, container, options = {}) => {
     };
     graph.setConfigPartial({
         backgroundColor: [0, 0, 0, 0],
-        onPointMouseOut: () => {
-            hovered = undefined;
-            paint();
-        },
-        onPointMouseOver: (at) => {
-            hovered = at;
-            paint();
-        },
+        onPointMouseOut: () => hover(undefined),
+        onPointMouseOver: (at) => hover(at),
         onSimulationTick: redraw,
         onTransition: redraw,
         onZoom: () => {
@@ -243,11 +289,15 @@ export const cosmosDriver = (graph, container, options = {}) => {
         center: (id, animate) => {
             const at = index.get(id);
             if (at !== undefined) {
+                moved = true;
                 graph.zoomToPointByIndex(at, animate ? STEP * 2 : 0, graph.getZoomLevel(), true);
             }
         },
         draw: ({ links: next, nodes }) => {
-            const reach = Math.max(1, ...nodes.map((node) => Math.max(Math.abs(node.x), Math.abs(node.y))));
+            let reach = 1;
+            for (const node of nodes) {
+                reach = Math.max(reach, Math.abs(node.x), Math.abs(node.y));
+            }
             scale = (space * 0.12) / reach;
             moved = false;
             const positions = new Float32Array(nodes.length * 2);
@@ -259,11 +309,41 @@ export const cosmosDriver = (graph, container, options = {}) => {
             fitAll(0);
         },
         fit: (fitted, animate) => {
-            const indices = fitted.flatMap((id) => {
+            const flat = flatNow();
+            const box = { bottom: -Infinity, left: Infinity, right: -Infinity, top: Infinity };
+            for (const id of fitted) {
                 const at = index.get(id);
-                return at === undefined ? [] : [at];
-            });
-            graph.fitViewByPointIndices(indices, animate ? STEP * 2 : 0, 0.25);
+                if (at !== undefined) {
+                    const x = flat[at * 2] ?? 0;
+                    const y = flat[at * 2 + 1] ?? 0;
+                    box.left = Math.min(box.left, x);
+                    box.right = Math.max(box.right, x);
+                    box.top = Math.min(box.top, y);
+                    box.bottom = Math.max(box.bottom, y);
+                }
+            }
+            if (!Number.isFinite(box.left)) {
+                return;
+            }
+            let low = Infinity;
+            let high = -Infinity;
+            for (let at = 0; at < flat.length; at++) {
+                low = Math.min(low, flat[at]);
+                high = Math.max(high, flat[at]);
+            }
+            const least = Math.max((high - low) * 0.2, 1);
+            const middle = { x: (box.left + box.right) / 2, y: (box.top + box.bottom) / 2 };
+            const half = {
+                x: Math.max(box.right - box.left, least) / 2,
+                y: Math.max(box.bottom - box.top, least) / 2,
+            };
+            moved = true;
+            graph.setZoomTransformByPointPositions(new Float32Array([
+                middle.x - half.x,
+                middle.y - half.y,
+                middle.x + half.x,
+                middle.y + half.y,
+            ]), animate && !still() ? STEP * 2 : 0, undefined, 0.25);
         },
         gestures: (next) => {
             held.set(next);
@@ -309,6 +389,7 @@ export const cosmosDriver = (graph, container, options = {}) => {
         },
         onPress: (press) => {
             graph.setConfigPartial({
+                onBackgroundClick: () => press(undefined),
                 onPointClick: (at) => {
                     const id = ids[at];
                     if (id !== undefined) {
@@ -316,11 +397,12 @@ export const cosmosDriver = (graph, container, options = {}) => {
                     }
                 },
             });
-            return () => graph.setConfigPartial({ onPointClick: undefined });
+            return () => graph.setConfigPartial({ onBackgroundClick: undefined, onPointClick: undefined });
         },
         panBy: (x, y, animate) => {
             const { height, width } = container.getBoundingClientRect();
             const to = graph.screenToSpacePosition([width / 2 + x, height / 2 + y]);
+            moved = true;
             graph.setZoomTransformByPointPositions(new Float32Array(to), animate ? STEP : 0, graph.getZoomLevel());
         },
         settle: (unplaced, placed) => {
@@ -349,6 +431,7 @@ export const cosmosDriver = (graph, container, options = {}) => {
                 clearInterval(fitting);
                 graph.setConfigPartial({ onSimulationEnd: undefined });
                 graph.setPinnedPoints(null);
+                graph.pause();
             };
         },
         signal: (from, to, colors, animate) => {
@@ -359,7 +442,9 @@ export const cosmosDriver = (graph, container, options = {}) => {
         stop: () => {
             stopped = true;
             clearTimeout(overviewing);
+            container.style.cursor = cursor;
             graph.setConfigPartial({
+                onBackgroundClick: undefined,
                 onPointClick: undefined,
                 onPointMouseOut: undefined,
                 onPointMouseOver: undefined,
@@ -396,11 +481,8 @@ export const cosmosDriver = (graph, container, options = {}) => {
             for (const node of changes.addNodes) {
                 kept.set(node.id, node);
             }
-            const removed = new Set(changes.removeLinks.map((link) => `${link.source}\u0000${link.target}`));
-            const next = [
-                ...links.filter((link) => !removed.has(`${link.source}\u0000${link.target}`)),
-                ...changes.addLinks,
-            ];
+            const removed = new Set(changes.removeLinks.map(linkKey));
+            const next = [...links.filter((link) => !removed.has(linkKey(link))), ...changes.addLinks];
             const nodes = [...kept.values()];
             const positions = new Float32Array(nodes.length * 2);
             nodes.forEach((node, at) => {
@@ -413,6 +495,7 @@ export const cosmosDriver = (graph, container, options = {}) => {
             }
         },
         zoomBy: (direction, animate) => {
+            moved = true;
             graph.setZoomLevel(graph.getZoomLevel() * (direction > 0 ? ZOOM : 1 / ZOOM), animate ? STEP : 0);
         },
     };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { type ConnectGraphOptions, connectGraph, type DrawnLink, type DrawnNode, type GraphChanges, type GraphConnection, type GraphDriver, type GraphGroup, } from './connect-graph/connect-graph.js';
-export { diffGraph } from './connect-graph/diff.js';
-export { type GraphColors, type GraphLooks, graphColorsFrom, type LinkLook, type NodeLook, } from './connect-graph/looks.js';
-export { type GraphPoint, seedPositions } from './connect-graph/seed.js';
+export { diffGraph, linkKey } from './connect-graph/diff.js';
+export { type GraphColors, type GraphLooks, type GraphTone, graphColorsFrom, type LinkLook, type NodeLook, } from './connect-graph/looks.js';
+export { type GraphPoint, type SeedLink, type SeedNode, seedPositions, } from './connect-graph/seed.js';
 export { fitToStencil, type GraphStencil, type StencilFrame, } from './connect-graph/stencil.js';
+export type { ShapeField } from './shapes/shape-field.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { connectGraph, } from './connect-graph/connect-graph.js';
-export { diffGraph } from './connect-graph/diff.js';
+export { diffGraph, linkKey } from './connect-graph/diff.js';
 export { graphColorsFrom, } from './connect-graph/looks.js';
-export { seedPositions } from './connect-graph/seed.js';
+export { seedPositions, } from './connect-graph/seed.js';
 export { fitToStencil, } from './connect-graph/stencil.js';

package/dist/model/index.d.ts

@@ -0,0 +1 @@
+export { shapeFromModel } from './model.js';

package/dist/model/index.js

@@ -0,0 +1 @@
+export { shapeFromModel } from './model.js';

package/dist/{shapes → model}/model.d.ts

@@ -1,5 +1,5 @@
-import type { ShapeField } from '../connect-graph/shape-field.js';
-import { type TriangleOptions } from './triangles.js';
+import type { ShapeField } from '../shapes/shape-field.js';
+import { type TriangleOptions } from '../shapes/triangles.js';
 /**
  * A solid field from a glTF model, the web's standard format for one: a
  * URL to a `.glb` or `.gltf` file, or the file's bytes. Every mesh in it is
@@ -10,6 +10,7 @@ import { type TriangleOptions } from './triangles.js';
  *
  * **three.js reads the file**, imported when this is first called, so a page
  * that draws no model never downloads a loader. It is an optional peer of
- * this package.
+ * this package. A model that cannot be fetched or read is an error that
+ * names it, the loader's own error as its `cause`.
  */
 export declare const shapeFromModel: (source: string | ArrayBuffer, options?: TriangleOptions) => Promise<ShapeField>;

package/dist/{shapes → model}/model.js

@@ -1,13 +1,18 @@
-import { shapeFromTriangles } from './triangles.js';
+import { shapeFromTriangles } from '../shapes/triangles.js';
 export const shapeFromModel = async (source, options = {}) => {
+    const which = typeof source === 'string' ? `The model ${source}` : 'The model given as bytes';
     const [{ GLTFLoader }, { Mesh, Vector3 }] = await Promise.all([
         import('three/addons/loaders/GLTFLoader.js'),
         import('three'),
-    ]);
+    ]).catch((cause) => {
+        throw new Error(`${which} could not be read, because three.js could not be loaded. Install three alongside @fusion.dev/helix-graph.`, { cause });
+    });
     const loader = new GLTFLoader();
-    const model = typeof source === 'string'
-        ? await loader.loadAsync(source)
-        : await loader.parseAsync(source, '');
+    const model = await (typeof source === 'string'
+        ? loader.loadAsync(source)
+        : loader.parseAsync(source, '')).catch((cause) => {
+        throw new Error(`${which} could not be read as a glTF model: ${String(cause)}`, { cause });
+    });
     model.scene.updateMatrixWorld(true);
     const corners = [];
     const names = [];

package/dist/overlay/overlay.d.ts

@@ -7,11 +7,6 @@ export type OnScreen = (id: string) => {
     x: number;
     y: number;
 } | undefined;
-/** A point and how to bend toward it: the control point of a curve on screen. */
-export type Bend = (from: string, to: string) => {
-    x: number;
-    y: number;
-} | undefined;
 /** Whether an `rgb()` color is light, which a light ink says the ground is dark. */
 export declare const isLight: (color: string) => boolean;
 /** Eases in and out, so a signal leaves and arrives gently. */
@@ -23,13 +18,19 @@ export interface Box {
     right: number;
     top: number;
 }
+/**
+ * How many pixels a layer has for each of the page's: the screen's own, and
+ * never fewer than two, so on a screen of one a name's edges and a signal's
+ * tail are drawn twice as finely and smoothed down. At most three.
+ */
+export declare const overlayDensity: () => number;
 /**
  * **Signals are drawn on a canvas of the driver's own**, over the renderer's,
  * so a signal never makes the renderer redraw the graph: ten signals a second
  * over ten thousand notes draw ten dots. It draws only while something is in
  * flight, and takes no pointer, so a press reaches the note under it.
  */
-export declare const signalsOver: (container: HTMLElement, onScreen: OnScreen, bend?: Bend) => {
+export declare const signalsOver: (container: HTMLElement, onScreen: OnScreen) => {
     look: (looks: GraphLooks) => void;
     signal: (from: string, to: string, colors: {
         from: string;
@@ -50,14 +51,18 @@ export interface Named {
  * order given.
  */
 export declare const namesOver: (container: HTMLElement, onScreen: OnScreen) => {
+    /** The boxes the names last drawn take. */
+    boxes: () => readonly Box[];
     draw: (looks: GraphLooks | undefined, named: readonly Named[]) => void;
     stop: () => void;
 };
 /**
  * **Group names are drawn on a canvas of their own**, under the signals', and
  * drawn again whenever the driver says the view moved, so they follow it.
+ * `avoid` says where notes' names are drawn, which a group's name keeps
+ * clear of: moved a line, or left out where no line is clear.
  */
-export declare const groupsOver: (container: HTMLElement, onScreen: OnScreen) => {
+export declare const groupsOver: (container: HTMLElement, onScreen: OnScreen, avoid?: () => readonly Box[]) => {
     draw: () => void;
     look: (next: GraphLooks) => void;
     set: (next: readonly GraphGroup[]) => void;
@@ -69,7 +74,8 @@ export declare const groupsOver: (container: HTMLElement, onScreen: OnScreen) =>
  * frame's buttons stopped working with them. A listener on the container in
  * the capture phase runs before the renderer's, and keeps from it what the
  * page has: the plain wheel and one finger while cooperative, and every
- * gesture while a waiting surface is off.
+ * gesture while a waiting surface is off, a double click among them, which
+ * zooms where a renderer zooms on one. A single click still selects a note.
  */
 export declare const gesturesHeld: (container: HTMLElement) => {
     /**