@fusion.dev/helix-graph 0.122.0 → 0.124.0

package/README.md

@@ -75,11 +75,15 @@ 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 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.
+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.
 
 ```js
 frame.signal('Checkout', 'Payments', { tone: 'success' })
@@ -108,7 +112,15 @@ frame.nodes = [
 ```
 
 `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
+where it does not say. A note without a material is matte, lit across so it
+reads as round. In three dimensions every note is a solid: a circle is a
+sphere, worked out for each pixel and written at its depth, so notes meet the
+shape and each other as solids do; a square is a cube and a diamond an
+octahedron. On a dark ground a sphere is an orb of energy, a dark glassy body
+with a glowing rim and a hot point at its middle, and on a light ground frosted
+glass; a cube or an octahedron is a hologram, faint faces with fine edges of
+light. Each catches a glint from a light fixed in the scene, so the glint moves
+as the reader turns the graph. 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
@@ -211,9 +223,27 @@ makes one from what a page has, and a field is a stencil itself:
 
 | 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 |
+| `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 |
+| `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' }
+connectGraph(frame, threeDriver(box), { stencil })
+```
+
+**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
+holes is read as closed where it can be. A model served from another origin
+needs that origin to allow it, as any `fetch` does. Use a model whose license
+lets your readers copy it, since the examples a reader takes away name it.
 
 ## In three dimensions
 
@@ -237,15 +267,22 @@ connectGraph(frame, threeDriver(box), {
 
 - **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.
+  solid reads as the thing it is shaped like. **Each group is given a piece
+  of the shape of its own**, as many places as it has notes, and each hub a
+  piece of its group's, so no group is cut in two: on a knot, a group is a
+  stretch of its tube, and on a brain, a region of it.
+- **On a surface, the shape itself is drawn** just inside the notes, so what
+  is behind it is hidden and the pointer finds only the notes in front.
+  **Each region is washed in its notes' color**, a translucent stain that
+  fades into the next region's, and glows in that color at the edge turning
+  away. It is lit faintly from above, and a model's own surface is drawn,
+  with every fold the field's cells are too coarse to hold.
 - **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.
+- **The far side recedes.** 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.
 
@@ -264,7 +301,7 @@ connectGraph(frame, threeDriver(box), {
 | `@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 |
+| `@fusion.dev/helix-graph/shapes` | `shapeFromModel`, `shapeFromTriangles`, `shapeFromSvg`, `shapeFromImage`, `shapeFromPath`, `shapeFromInside`, `inflate`, `sphere`, `torus`, `box`, `onSphere`, `surfaceOf`, and the `ShapeField` type |
 
 **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

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

@@ -4,6 +4,16 @@ export interface ArrangedNode {
     group?: string | undefined;
     id: string;
 }
+/**
+ * The hub each note hangs from, and how connected each note is: a note
+ * hangs from its most connected neighbor in its group, where that neighbor
+ * is more connected than it is, and the note at the end of the chain is the
+ * hub. A note nothing is more connected than is its own hub.
+ */
+export declare const hubsOf: (nodes: readonly ArrangedNode[], links: readonly SeedLink[]) => {
+    hubOf: (id: string) => string;
+    rank: (id: string) => number;
+};
 /**
  * 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

package/dist/connect-graph/arrange.js

@@ -30,7 +30,7 @@ const plus = (one, other) => ({
     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 } = {}) => {
+export const hubsOf = (nodes, links) => {
     const groupOf = new Map(nodes.map((node) => [node.id, node.group ?? '']));
     const degree = new Map();
     const neighbors = new Map();
@@ -75,6 +75,11 @@ export const arrangeByGroup = (nodes, links, { solid = false } = {}) => {
         }
         return at;
     };
+    return { hubOf, rank };
+};
+export const arrangeByGroup = (nodes, links, { solid = false } = {}) => {
+    const groupOf = new Map(nodes.map((node) => [node.id, node.group ?? '']));
+    const { hubOf, rank } = hubsOf(nodes, links);
     const groups = new Map();
     for (const { id } of nodes) {
         const group = groupOf.get(id);

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

@@ -2,7 +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';
+import { type GraphStencil, type StencilFrame } 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
@@ -85,9 +85,11 @@ export interface GraphDriver {
      * 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.
+     * undefined, no shape. `frame` is the shape and where it was put among the
+     * notes, once the connector has drawn the notes in it, for a renderer that
+     * draws the shape as well.
      */
-    shape?(place: 'fill' | 'surface' | undefined): void;
+    shape?(place: 'fill' | 'surface' | undefined, frame?: StencilFrame): void;
     /** Removes whatever the driver added to the renderer or the page, when the connection ends. */
     stop?(): void;
 }

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

@@ -1,9 +1,14 @@
 import { HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphSignalEvent, HelixGraphZoomEvent, isRtl, watchTheme, } from '@fusion.dev/helix-core';
-import { arrangeByGroup } from './arrange.js';
+import { arrangeByGroup, hubsOf } from './arrange.js';
 import { diffGraph, isEmpty, linkKey, } from './diff.js';
 import { graphColorsFrom, looksOf, toneColor, } from './looks.js';
 import { seedPositions } from './seed.js';
-import { fieldOf, fitToStencil } from './stencil.js';
+import { fieldOf, fitInStencil } from './stencil.js';
+const clustersOf = (nodes, links) => {
+    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) => {
     const box = (frame.shadowRoot?.querySelector('[part="viewport"]') ?? frame).getBoundingClientRect();
     return { height: box.height, width: box.width };
@@ -12,6 +17,7 @@ const still = () => typeof matchMedia === 'function' && matchMedia('(prefers-red
 export const connectGraph = (frame, driver, options = {}) => {
     const graph = frame;
     let known = new Map();
+    let shapeFrame;
     let drawnNodes = new Map();
     let drawnLinks = new Map();
     let first = true;
@@ -94,12 +100,16 @@ export const connectGraph = (frame, driver, options = {}) => {
             }
         }
         let { positions, unplaced } = seedPositions(nodes, [...nextLinks.values()], known);
-        const shaped = options.stencil && ids.size > 0 && unplaced.size === ids.size
-            ? fitToStencil(arrangeByGroup(nodes, [...nextLinks.values()], {
+        const fit = options.stencil && ids.size > 0 && unplaced.size === ids.size
+            ? fitInStencil(arrangeByGroup(nodes, [...nextLinks.values()], {
                 solid: fieldOf(options.stencil).depth > 0,
-            }), options.stencil)
+            }), options.stencil, { clustersOf: clustersOf(nodes, [...nextLinks.values()]) })
             : undefined;
-        driver.shape?.(options.stencil ? (options.stencil.place ?? 'fill') : undefined);
+        const shaped = fit?.positions;
+        if (fit?.frame) {
+            shapeFrame = fit.frame;
+        }
+        driver.shape?.(options.stencil ? (options.stencil.place ?? 'fill') : undefined, shapeFrame);
         if (shaped) {
             positions = shaped;
             unplaced = new Set();

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

@@ -14,9 +14,33 @@ export interface ShapeField {
     distance(x: number, y: number, z?: number): number;
     /** How tall the box is. Its y points down, as an SVG's does. */
     readonly height: number;
+    /**
+     * The surface the field was read from, where it was read from one, in the
+     * box's units: corners three numbers each, and triangles three corners
+     * each. A renderer draws it in place of a surface it would make from the
+     * field, since it holds every detail the field's cells are too coarse for.
+     */
+    readonly mesh?: {
+        corners: Float32Array;
+        triangles: Uint32Array;
+    } | undefined;
     /** How wide the box is. */
     readonly width: number;
 }
+/** How many cells a field has along its longer side, flat and solid. */
+export declare const FLAT = 512;
+export declare const SOLID = 96;
+/**
+ * A field from a grid of cells marked inside, `cell` box units a cell, x
+ * fastest and z slowest: the distance to the nearest outside cell, taken
+ * from the distance to the nearest inside one, so the sign says which side
+ * of the edge a point is on.
+ */
+export declare const fieldFromCells: (inside: Uint8Array, sizes: readonly [number, number, number], cell: number, box: {
+    depth: number;
+    height: number;
+    width: number;
+}) => ShapeField;
 /**
  * A field from a test of whether a point in the box is inside, sampled at
  * the center of each cell: flat when `depth` is zero, solid otherwise.

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

@@ -1,5 +1,5 @@
-const FLAT = 512;
-const SOLID = 96;
+export const FLAT = 512;
+export const SOLID = 96;
 const FAR = 1e20;
 const line = (values, count, out) => {
     const hull = new Int32Array(count);
@@ -67,7 +67,7 @@ const transform = (marked, sizes) => {
     }
     return grid;
 };
-const fieldFromCells = (inside, sizes, cell, box) => {
+export const fieldFromCells = (inside, sizes, cell, box) => {
     const outside = new Uint8Array(inside.length);
     for (let at = 0; at < inside.length; at++) {
         outside[at] = inside[at] ? 0 : 1;

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

@@ -48,3 +48,33 @@ export declare const placesIn: (field: ShapeField, count: number, { place, shell
  * they were.
  */
 export declare const fitToStencil: (positions: ReadonlyMap<string, GraphPoint>, stencil: GraphStencil) => Map<string, GraphPoint>;
+/**
+ * Where a stencil's box was put, in the places' units: its middle, and how
+ * many of the places' units one of the box's is. A point in the box at `x`,
+ * `y` and `z` is at `middle.x + (x - width / 2) * scale`,
+ * `middle.y - (y - height / 2) * scale` and `middle.z + (z - depth / 2) * scale`.
+ */
+export interface StencilFrame {
+    field: ShapeField;
+    middle: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** How many of the places' units one of the box's is. */
+    scale: number;
+    /** How thick the shell the notes were placed in is, in the box's units: none where they fill the shape. */
+    shell: number;
+}
+/** `fitToStencil`, saying where it put the stencil's box as well, where it fitted the places at all. */
+export declare const fitInStencil: (positions: ReadonlyMap<string, GraphPoint>, stencil: GraphStencil, { clustersOf, }?: {
+    /**
+     * The clusters a note is in, broadest first, such as its group and then
+     * its hub. Each cluster is given a piece of a solid of its own, as many
+     * places as it has notes, so no cluster is cut in two.
+     */
+    clustersOf?: ((id: string) => readonly string[]) | undefined;
+}) => {
+    frame?: StencilFrame | undefined;
+    positions: Map<string, GraphPoint>;
+};

package/dist/connect-graph/stencil.js

@@ -1,4 +1,5 @@
 import { fieldFromInside, fieldFromPath } from './shape-field.js';
+import { surfaceWeb } from './surface-web.js';
 const PROBE = { flat: 64, solid: 32 };
 const SHELL = 0.04;
 const WAVE = 0.07;
@@ -93,10 +94,11 @@ const nested = (items, keys) => {
     }
     return out;
 };
-export const fitToStencil = (positions, stencil) => {
+export const fitToStencil = (positions, stencil) => fitInStencil(positions, stencil).positions;
+export const fitInStencil = (positions, stencil, { clustersOf, } = {}) => {
     const notes = [...positions].map(([id, at]) => ({ at, id }));
     if (notes.length === 0) {
-        return new Map();
+        return { positions: new Map() };
     }
     const field = fieldOf(stencil);
     const places = placesIn(field, notes.length, {
@@ -104,9 +106,12 @@ export const fitToStencil = (positions, stencil) => {
         shell: stencil.shell ?? SHELL,
     });
     if (places.length < notes.length) {
-        return new Map(positions);
+        return { positions: new Map(positions) };
     }
     const solid = field.depth > 0;
+    const thickness = (stencil.place ?? 'fill') === 'surface'
+        ? (stencil.shell ?? SHELL) * Math.max(field.width, field.height, field.depth)
+        : 0;
     const low = {
         x: Number.POSITIVE_INFINITY,
         y: Number.POSITIVE_INFINITY,
@@ -142,17 +147,6 @@ export const fitToStencil = (positions, stencil) => {
     });
     const fitted = new Map();
     if (solid) {
-        const surface = (stencil.place ?? 'fill') === 'surface';
-        const way = (point) => {
-            if (!surface) {
-                return point;
-            }
-            const x = point.x - middle.x;
-            const y = point.y - middle.y;
-            const z = (point.z ?? 0) - middle.z;
-            const length = Math.hypot(x, y, z) || 1;
-            return { x: x / length, y: y / length, z: z / length };
-        };
         const widest = (points) => {
             let best = 'x';
             let spread = Number.NEGATIVE_INFINITY;
@@ -171,29 +165,85 @@ export const fitToStencil = (positions, stencil) => {
             }
             return best;
         };
-        const halve = (ours, theirs) => {
+        const targets = spots.map((spot) => spot.at);
+        const web = (stencil.place ?? 'fill') === 'surface' ? surfaceWeb(targets) : undefined;
+        const halveTargets = (places, first) => {
+            if (web && places.length > 2) {
+                return web.halve(places, first);
+            }
+            const axis = widest(places.map((at) => targets[at]));
+            const ordered = [...places].sort((one, other) => (targets[one][axis] ?? 0) - (targets[other][axis] ?? 0));
+            return [ordered.slice(0, first), ordered.slice(first)];
+        };
+        const keysOf = new Map(notes.map((note) => [note.id, clustersOf?.(note.id) ?? []]));
+        const halve = (ours, theirs, level = 0) => {
             if (ours.length === 1) {
-                fitted.set(ours[0].id, theirs[0].at);
+                fitted.set(ours[0].id, targets[theirs[0]]);
                 return;
             }
             if (ours.length === 0) {
                 return;
             }
-            const mine = widest(ours.map((note) => note.key));
-            const yours = widest(theirs.map((spot) => spot.key));
-            ours.sort((one, other) => (one.key[mine] ?? 0) - (other.key[mine] ?? 0));
-            theirs.sort((one, other) => (one.key[yours] ?? 0) - (other.key[yours] ?? 0));
+            const clusters = new Map();
+            for (const note of ours) {
+                const key = keysOf.get(note.id)?.[level];
+                if (key !== undefined) {
+                    const list = clusters.get(key);
+                    if (list) {
+                        list.push(note);
+                    }
+                    else {
+                        clusters.set(key, [note]);
+                    }
+                }
+            }
+            if (clusters.size === 1) {
+                halve(ours, theirs, level + 1);
+                return;
+            }
+            if (clusters.size > 1 &&
+                [...clusters.values()].reduce((sum, list) => sum + list.length, 0) === ours.length) {
+                const middles = [...clusters.values()].map((list) => ({
+                    list,
+                    middle: {
+                        x: list.reduce((sum, note) => sum + note.at.x, 0) / list.length,
+                        y: list.reduce((sum, note) => sum + note.at.y, 0) / list.length,
+                        z: list.reduce((sum, note) => sum + (note.at.z ?? 0), 0) / list.length,
+                    },
+                }));
+                const axis = widest(middles.map((one) => one.middle));
+                middles.sort((one, other) => one.middle[axis] - other.middle[axis]);
+                let cut = 1;
+                let count = 0;
+                let best = Number.POSITIVE_INFINITY;
+                let first = 0;
+                for (let at = 0; at < middles.length - 1; at++) {
+                    count += middles[at].list.length;
+                    if (Math.abs(count - ours.length / 2) < best) {
+                        best = Math.abs(count - ours.length / 2);
+                        cut = at + 1;
+                        first = count;
+                    }
+                }
+                const [near, rest] = halveTargets(theirs, first);
+                halve(middles.slice(0, cut).flatMap((one) => one.list), near, level);
+                halve(middles.slice(cut).flatMap((one) => one.list), rest, level);
+                return;
+            }
+            const mine = widest(ours.map((note) => note.at));
+            ours.sort((one, other) => (one.at[mine] ?? 0) - (other.at[mine] ?? 0));
             const half = Math.floor(ours.length / 2);
-            halve(ours.slice(0, half), theirs.slice(0, half));
-            halve(ours.slice(half), theirs.slice(half));
+            const [near, rest] = halveTargets(theirs, half);
+            halve(ours.slice(0, half), near, level);
+            halve(ours.slice(half), rest, level);
         };
-        halve(notes.map((note) => ({ ...note, key: way(note.at) })), spots.map((spot) => ({ at: spot.at, key: way(spot.at) })));
-        return fitted;
+        halve([...notes], targets.map((_, at) => at));
+        return { frame: { field, middle, scale, shell: thickness }, positions: fitted };
     }
     const ours = nested(notes, [(note) => note.at.x, (note) => note.at.y]);
     const theirs = nested(spots, [(spot) => spot.across, (spot) => spot.down]);
     ours.forEach((note, at) => {
         fitted.set(note.id, theirs[at].at);
     });
-    return fitted;
+    return { frame: { field, middle, scale, shell: thickness }, positions: fitted };
 };

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

@@ -0,0 +1,18 @@
+import type { GraphPoint } from './seed.js';
+/**
+ * Places on a surface, joined to their near neighbors, and split in halves
+ * by how far apart they are across the surface, not through the air.
+ *
+ * **Half a surface measured across it is one piece of it**: a stretch of a
+ * knot's tube, or one lobe of a brain. Half of it by position can be its
+ * front and its back, and half of it by direction from its middle can be
+ * three passes of a tube that crosses itself.
+ */
+export declare const surfaceWeb: (points: readonly GraphPoint[]) => {
+    /**
+     * A set of places in two halves, `first` as many as the first: the
+     * places nearer one end of the set, across the surface, and the rest.
+     * The ends are two places about as far apart across it as any.
+     */
+    halve: (places: readonly number[], first: number) => [number[], number[]];
+};

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

@@ -0,0 +1,99 @@
+export const surfaceWeb = (points) => {
+    const count = points.length;
+    const x = (at) => points[at].x;
+    const y = (at) => points[at].y;
+    const z = (at) => points[at].z ?? 0;
+    const far = (one, other) => Math.hypot(x(one) - x(other), y(one) - y(other), z(one) - z(other));
+    const sample = Math.min(count, 256);
+    const nearest = [];
+    for (let step = 0; step < sample; step++) {
+        const one = Math.floor((step * count) / sample);
+        let best = Number.POSITIVE_INFINITY;
+        for (let other = 0; other < count; other++) {
+            if (other !== one) {
+                best = Math.min(best, far(one, other));
+            }
+        }
+        if (Number.isFinite(best)) {
+            nearest.push(best);
+        }
+    }
+    nearest.sort((one, other) => one - other);
+    const reach = (nearest[Math.floor(nearest.length / 2)] ?? 1) * 2.2;
+    const cells = new Map();
+    const cellOf = (at) => [
+        Math.floor(x(at) / reach),
+        Math.floor(y(at) / reach),
+        Math.floor(z(at) / reach),
+    ];
+    for (let at = 0; at < count; at++) {
+        const key = cellOf(at).join(',');
+        const list = cells.get(key);
+        if (list) {
+            list.push(at);
+        }
+        else {
+            cells.set(key, [at]);
+        }
+    }
+    const neighbors = Array.from({ length: count }, () => []);
+    for (let at = 0; at < count; at++) {
+        const [cx, cy, cz] = cellOf(at);
+        for (let dx = -1; dx <= 1; dx++) {
+            for (let dy = -1; dy <= 1; dy++) {
+                for (let dz = -1; dz <= 1; dz++) {
+                    for (const other of cells.get(`${cx + dx},${cy + dy},${cz + dz}`) ?? []) {
+                        if (other > at && far(at, other) <= reach) {
+                            ;
+                            neighbors[at].push(other);
+                            neighbors[other].push(at);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    const member = new Int32Array(count).fill(-1);
+    let round = 0;
+    const steps = (from, out) => {
+        out.fill(-1);
+        const queue = [from];
+        out[from] = 0;
+        let last = from;
+        for (let head = 0; head < queue.length; head++) {
+            const at = queue[head];
+            last = at;
+            for (const next of neighbors[at]) {
+                if (member[next] === round && out[next] === -1) {
+                    out[next] = out[at] + 1;
+                    queue.push(next);
+                }
+            }
+        }
+        return last;
+    };
+    const fromA = new Int32Array(count);
+    const fromB = new Int32Array(count);
+    return {
+        halve: (places, first) => {
+            round += 1;
+            for (const at of places) {
+                member[at] = round;
+            }
+            const a = steps(places[0], fromA);
+            const b = steps(a, fromA);
+            steps(b, fromB);
+            const unreached = places.length * 4;
+            const key = (at) => {
+                const one = fromA[at];
+                const other = fromB[at];
+                if (one < 0 || other < 0) {
+                    return unreached + far(at, a) - far(at, b);
+                }
+                return one - other;
+            };
+            const ordered = [...places].sort((one, other) => key(one) - key(other));
+            return [ordered.slice(0, first), ordered.slice(first)];
+        },
+    };
+};

package/dist/index.d.ts

@@ -2,4 +2,4 @@ export { type ConnectGraphOptions, connectGraph, type DrawnLink, type DrawnNode,
 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 { fitToStencil, type GraphStencil } from './connect-graph/stencil.js';
+export { fitToStencil, type GraphStencil, type StencilFrame, } from './connect-graph/stencil.js';

package/dist/index.js

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

package/dist/overlay/overlay.d.ts

@@ -7,6 +7,11 @@ 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. */
@@ -24,7 +29,7 @@ export interface Box {
  * 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) => {
+export declare const signalsOver: (container: HTMLElement, onScreen: OnScreen, bend?: Bend) => {
     look: (looks: GraphLooks) => void;
     signal: (from: string, to: string, colors: {
         from: string;