@graphty/graphty-element 2.3.1 → 2.4.0

package/dist/graphty.js

@@ -1,10 +1,10 @@
-import { A as e, a as E, b as r, D as O, E as o, d as S, G as R, e as _, I as L, L as t, N as C, O as A, R as N, S as n, f as I, g as T, h as g, U as i, i as p } from "./chunks/index-C0mIoumR.js";
-import { L as l, S as G, a as f } from "./chunks/paletteRegistry-x7WOEKZY.js";
-import { D, E as M } from "./chunks/DataSource-OeN3NeyD.js";
-import { I as P, J as U, p as c, q as m, A as u, C as x, x as B } from "./chunks/optionsFromZod-17lkrAJs.js";
-import { e as H, E as b, N as Y, a as F, P as W, R as K, S as k, d as q, b as v, c as w } from "./chunks/NodeStyle-DKj7HjMJ.js";
-import { A as Q, a as X, G as j, i as z, b as Z } from "./chunks/GraphtyError-BwcnblTH.js";
-import { B as aa, a as sa, b as ea, C as Ea, G as ra, c as Oa, I as oa, O as Sa, d as Ra, e as _a, f as La, P as ta, g as Ca, h as Aa, R as Na, T as na, i as Ia, V as Ta, Y as ga } from "./chunks/sequential-Zym81qm7.js";
+import { A as e, a as r, b as E, D as O, E as o, d as S, G as R, e as _, I as L, L as t, N as C, O as A, R as N, S as n, f as I, g as T, h as g, U as i, i as p } from "./chunks/index-2xkq7wyD.js";
+import { L as l, S as G, a as f } from "./chunks/paletteRegistry-A63C71Gn.js";
+import { D, E as M } from "./chunks/DataSource-B8vf2uhW.js";
+import { I as P, J as U, p as c, q as m, A as u, C as x, x as B } from "./chunks/optionsFromZod-BuTOFgVM.js";
+import { g as H, b, N as Y, c as F, P as W, R as K, S as k, d as q, e as v, f as w } from "./chunks/NodeStyle-CtmA7dXi.js";
+import { A as Q, a as X, G as j, i as z, b as Z } from "./chunks/GraphtyError-B93WRH3e.js";
+import { B as aa, a as sa, b as ea, C as ra, G as Ea, c as Oa, I as oa, O as Sa, d as Ra, e as _a, f as La, P as ta, g as Ca, h as Aa, R as Na, T as na, i as Ia, V as Ta, Y as ga } from "./chunks/sequential-Zym81qm7.js";
 import { a as pa, G as da, V as la, i as Ga } from "./chunks/GraphStyle-Cwr55SAE.js";
 import { c as ya } from "./chunks/common-DWNKjpH_.js";
 export {
@@ -15,12 +15,12 @@ export {
   m as ACCELERATION_POLICY_DEFAULT,
   u as Algorithm,
   e as AlgorithmManager,
-  E as AnimationCancelledError,
+  r as AnimationCancelledError,
   aa as BLUES_COLORS,
   sa as BLUE_HIGHLIGHT,
   ea as BLUE_ORANGE_COLORS,
-  r as BUILTIN_PRESETS,
-  Ea as CARBON_COLORS,
+  E as BUILTIN_PRESETS,
+  ra as CARBON_COLORS,
   x as CPU_PRECISION,
   pa as DEFAULT_VIEW_MODE,
   O as DataManager,
@@ -31,7 +31,7 @@ export {
   M as ErrorAggregator,
   S as EventManager,
   X as GRAPHTY_ERROR_CODES,
-  ra as GREENS_COLORS,
+  Ea as GREENS_COLORS,
   Oa as GREEN_SUCCESS,
   R as Graph,
   da as GraphBackground,

package/dist/logging.js

@@ -1,5 +1,5 @@
-import { d as c, p } from "./chunks/GraphtyLogger-5KEttFUo.js";
-import { G, e as C, f as M, g as w, h as N, i as V, j as I, k as P, m as U, n as T, o as x } from "./chunks/GraphtyLogger-5KEttFUo.js";
+import { d as c, p } from "./chunks/GraphtyLogger-CqOVV13Y.js";
+import { G, e as C, f as M, g as w, h as N, i as V, j as I, k as P, m as U, n as T, o as x } from "./chunks/GraphtyLogger-CqOVV13Y.js";
 const g = "graphty-element-logging-config";
 function O(t) {
   try {

package/dist/schema.d.ts

@@ -22,7 +22,7 @@
 export type { Binding, BindingOverflow, Channel, ChannelValue, EdgeId, EdgeLinePattern, Encoding, LabelStyle, LayerId, LayerKind, LayerSource, LayerSpec, NodeId, Path, Query, ResultShape, Rgba, RunId, Scope, ScopeId, Selector, StaticStyle, StyleDocument, ThemeDescriptor, } from "./src/catalog/types";
 export { isResultShape, RESULT_SHAPES } from "./src/catalog/types";
 export type { AdHocData, EdgeStyleConfig, GraphBackgroundConfig, GraphSelectionStyleConfig, GraphSelectionStyleInput, ImageData, NodeStyleConfig, RichTextStyleType, ViewMode, } from "./src/config/index";
-export { colorToHex, DEFAULT_SELECTION_STYLE, DEFAULT_VIEW_MODE, defaultEdgeStyle, defaultNodeStyle, defaultRichTextLabelStyle, EdgeStyle, GraphBackground, GraphSelectionStyleOpts, isViewMode, NodeShapes, NodeStyle, RichTextStyle, VIEW_MODE_VALUES, } from "./src/config/index";
+export { colorToHex, DEFAULT_SELECTION_STYLE, DEFAULT_VIEW_MODE, defaultEdgeStyle, defaultNodeStyle, defaultRichTextLabelStyle, EdgeArrowTypes, EdgeLineTypes, EdgeStyle, GraphBackground, GraphSelectionStyleOpts, isViewMode, NodeShapes, NodeStyle, RichTextStyle, VIEW_MODE_VALUES, } from "./src/config/index";
 export * from "./src/config/palettes/index";
 export { areDistinguishableInGrayscale, colorDifference, isPaletteSafe, simulateDeuteranopia, simulateProtanopia, simulateTritanopia, toGrayscale, } from "./src/utils/styleHelpers/accessibility/colorblindSimulation";
 export type { RgbColor } from "./src/utils/styleHelpers/color/interpolation";

package/dist/schema.js

@@ -1,9 +1,9 @@
-import { R as N, e as x } from "./chunks/types-B7bX5c0K.js";
-import { M as A, h as y, i as M } from "./chunks/interpolation-DY-PNpqX.js";
-import { B as D, a as U, b as B, C as P, G as H, c as V, I as $, O as w, d as F, e as W, f as Y, P as j, g as k, h as q, R as K, T as v, i as z, V as J, Y as Q } from "./chunks/sequential-Zym81qm7.js";
-import { D as Z, a as tt, G as nt, b as at, V as st, i as et } from "./chunks/GraphStyle-Cwr55SAE.js";
-import { E as rt, N as ct, a as it, R as Ot, d as St, b as Rt, c as lt } from "./chunks/NodeStyle-DKj7HjMJ.js";
-import { c as ft } from "./chunks/common-DWNKjpH_.js";
+import { R as N, e as x } from "./chunks/types-C_c53VgR.js";
+import { M as h, h as y, i as M } from "./chunks/interpolation-DY-PNpqX.js";
+import { B as D, a as U, b as B, C as P, G as H, c as V, I as w, O as $, d as F, e as W, f as Y, P as j, g as k, h as q, R as K, T as v, i as z, V as J, Y as Q } from "./chunks/sequential-Zym81qm7.js";
+import { D as Z, a as tt, G as nt, b as at, V as et, i as st } from "./chunks/GraphStyle-Cwr55SAE.js";
+import { E as rt, a as ct, b as it, N as Ot, c as St, R as Rt, d as lt, e as ut, f as ft } from "./chunks/NodeStyle-CtmA7dXi.js";
+import { c as Lt } from "./chunks/common-DWNKjpH_.js";
 function l(t) {
   const n = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(t);
   if (!n)
@@ -11,11 +11,11 @@ function l(t) {
   return [parseInt(n[1], 16), parseInt(n[2], 16), parseInt(n[3], 16)];
 }
 function E(t, n, o) {
-  const e = (a) => {
-    const s = Math.round(Math.max(0, Math.min(255, a))).toString(16);
-    return s.length === 1 ? `0${s}` : s;
+  const s = (a) => {
+    const e = Math.round(Math.max(0, Math.min(255, a))).toString(16);
+    return e.length === 1 ? `0${e}` : e;
   };
-  return `#${e(t)}${e(n)}${e(o)}`;
+  return `#${s(t)}${s(n)}${s(o)}`;
 }
 function S(t) {
   const n = t / 255;
@@ -25,44 +25,44 @@ function R(t) {
   return t <= 31308e-7 ? t * 12.92 * 255 : (1.055 * Math.pow(t, 1 / 2.4) - 0.055) * 255;
 }
 function L(t) {
-  const [n, o, e] = l(t), a = S(n), s = S(o), r = S(e), O = 0.567 * a + 0.433 * s + 0 * r, c = 0.558 * a + 0.442 * s + 0 * r, i = 0 * a + 0.242 * s + 0.758 * r;
+  const [n, o, s] = l(t), a = S(n), e = S(o), r = S(s), O = 0.567 * a + 0.433 * e + 0 * r, c = 0.558 * a + 0.442 * e + 0 * r, i = 0 * a + 0.242 * e + 0.758 * r;
   return E(R(O), R(c), R(i));
 }
 function _(t) {
-  const [n, o, e] = l(t), a = S(n), s = S(o), r = S(e), O = 0.625 * a + 0.375 * s + 0 * r, c = 0.7 * a + 0.3 * s + 0 * r, i = 0 * a + 0.3 * s + 0.7 * r;
+  const [n, o, s] = l(t), a = S(n), e = S(o), r = S(s), O = 0.625 * a + 0.375 * e + 0 * r, c = 0.7 * a + 0.3 * e + 0 * r, i = 0 * a + 0.3 * e + 0.7 * r;
   return E(R(O), R(c), R(i));
 }
 function p(t) {
-  const [n, o, e] = l(t), a = S(n), s = S(o), r = S(e), O = 0.95 * a + 0.05 * s + 0 * r, c = 0 * a + 0.433 * s + 0.567 * r, i = 0 * a + 0.475 * s + 0.525 * r;
+  const [n, o, s] = l(t), a = S(n), e = S(o), r = S(s), O = 0.95 * a + 0.05 * e + 0 * r, c = 0 * a + 0.433 * e + 0.567 * r, i = 0 * a + 0.475 * e + 0.525 * r;
   return E(R(O), R(c), R(i));
 }
 function g(t) {
-  const [n, o, e] = l(t), a = 0.2126 * n + 0.7152 * o + 0.0722 * e;
+  const [n, o, s] = l(t), a = 0.2126 * n + 0.7152 * o + 0.0722 * s;
   return E(a, a, a);
 }
 function f(t, n) {
-  const [o, e, a] = l(t), [s, r, O] = l(n), c = o - s, i = e - r, u = a - O;
+  const [o, s, a] = l(t), [e, r, O] = l(n), c = o - e, i = s - r, u = a - O;
   return Math.sqrt(c * c + i * i + u * u) / 2.55;
 }
-function b(t, n, o = 10) {
-  const e = g(t), a = g(n);
-  return f(e, a) > o;
+function C(t, n, o = 10) {
+  const s = g(t), a = g(n);
+  return f(s, a) > o;
 }
-function d(t, n = 10) {
+function b(t, n = 10) {
   const o = {
     protanopia: !0,
     deuteranopia: !0,
     tritanopia: !0,
     grayscale: !0
   };
-  for (let e = 0; e < t.length; e++)
-    for (let a = e + 1; a < t.length; a++) {
-      const s = t[e], r = t[a], O = L(s), c = L(r);
+  for (let s = 0; s < t.length; s++)
+    for (let a = s + 1; a < t.length; a++) {
+      const e = t[s], r = t[a], O = L(e), c = L(r);
       f(O, c) < n && (o.protanopia = !1);
-      const i = _(s), u = _(r);
+      const i = _(e), u = _(r);
       f(i, u) < n && (o.deuteranopia = !1);
-      const C = p(s), T = p(r);
-      f(C, T) < n && (o.tritanopia = !1), b(s, r, n) || (o.grayscale = !1);
+      const T = p(e), d = p(r);
+      f(T, d) < n && (o.tritanopia = !1), C(e, r, n) || (o.grayscale = !1);
     }
   return o;
 }
@@ -73,16 +73,18 @@ export {
   P as CARBON_COLORS,
   Z as DEFAULT_SELECTION_STYLE,
   tt as DEFAULT_VIEW_MODE,
-  rt as EdgeStyle,
+  rt as EdgeArrowTypes,
+  ct as EdgeLineTypes,
+  it as EdgeStyle,
   H as GREENS_COLORS,
   V as GREEN_SUCCESS,
   nt as GraphBackground,
   at as GraphSelectionStyleOpts,
-  $ as INFERNO_COLORS,
-  A as MISSING_DATA_COLOR,
-  ct as NodeShapes,
-  it as NodeStyle,
-  w as OKABE_ITO_COLORS,
+  w as INFERNO_COLORS,
+  h as MISSING_DATA_COLOR,
+  Ot as NodeShapes,
+  St as NodeStyle,
+  $ as OKABE_ITO_COLORS,
   F as ORANGES_COLORS,
   W as ORANGE_WARNING,
   Y as OTHER_GROUP_COLOR,
@@ -91,23 +93,23 @@ export {
   q as PURPLE_GREEN_COLORS,
   K as RED_BLUE_COLORS,
   N as RESULT_SHAPES,
-  Ot as RichTextStyle,
+  Rt as RichTextStyle,
   v as TOL_MUTED_COLORS,
   z as TOL_VIBRANT_COLORS,
-  st as VIEW_MODE_VALUES,
+  et as VIEW_MODE_VALUES,
   J as VIRIDIS_COLORS,
   Q as YLORBR_COLORS,
-  b as areDistinguishableInGrayscale,
+  C as areDistinguishableInGrayscale,
   f as colorDifference,
-  ft as colorToHex,
-  St as defaultEdgeStyle,
-  Rt as defaultNodeStyle,
-  lt as defaultRichTextLabelStyle,
+  Lt as colorToHex,
+  lt as defaultEdgeStyle,
+  ut as defaultNodeStyle,
+  ft as defaultRichTextLabelStyle,
   y as hexToRgb,
   M as interpolatePalette,
-  d as isPaletteSafe,
+  b as isPaletteSafe,
   x as isResultShape,
-  et as isViewMode,
+  st as isViewMode,
   _ as simulateDeuteranopia,
   L as simulateProtanopia,
   p as simulateTritanopia,

package/dist/session.js

@@ -1,9 +1,9 @@
-import { R, e as _ } from "./chunks/types-B7bX5c0K.js";
-import { A as c, a as C, G as p, i as m, b as L } from "./chunks/GraphtyError-BwcnblTH.js";
-import { p as O, q as U, R as I, t as P, u as y, w as N, x as D, y as w, z as v } from "./chunks/optionsFromZod-17lkrAJs.js";
-import { D as h } from "./chunks/GraphSession-Bef1AYw9.js";
-import { a as b, b as x, c as F, d as z, Q as M, R as k, e as H, f as Y, S as j, T as q, g as Q, i as X, h as B, j as J, k as K } from "./chunks/GraphSession-Bef1AYw9.js";
-import { L as s } from "./chunks/scales-BRwl51k8.js";
+import { R, e as _ } from "./chunks/types-C_c53VgR.js";
+import { A as c, a as C, G as p, i as m, b as L } from "./chunks/GraphtyError-B93WRH3e.js";
+import { p as O, q as U, R as I, t as P, u as y, w as N, x as D, y as w, z as v } from "./chunks/optionsFromZod-BuTOFgVM.js";
+import { D as h } from "./chunks/GraphSession-dcwOjGJh.js";
+import { a as b, b as x, c as F, d as z, Q as M, R as k, e as H, f as Y, S as j, T as q, g as Q, i as X, h as B, j as J, k as K } from "./chunks/GraphSession-dcwOjGJh.js";
+import { L as s } from "./chunks/scales-B2d-7Bf0.js";
 const u = [
   {
     id: "fixed",

package/dist/src/Graph.d.ts

@@ -49,6 +49,8 @@ export declare class Graph implements GraphContext {
     runAlgorithmsOnLoad: boolean;
     enableDetailedProfiling?: boolean;
     private wasSettled;
+    /** How many loads `addDataFromSource` has started; the last one's id. */
+    private loadCount;
     private resizeHandler;
     /**
      * The one acceleration controller this graph, its session and its element share.
@@ -202,11 +204,43 @@ export declare class Graph implements GraphContext {
      *
      * A load that fails part-way still paints: the rows that did arrive are in the store and on
      * screen, so leaving them unpainted would be the same defect with a smaller blast radius.
+     *
+     * EVERY LOAD HAS AN ID. The promise resolves to it, and every event about this load --
+     * `data-loading-progress`, `data-loading-complete`, `data-loading-error`, `data-loaded` and
+     * the `error` beside a failure -- carries it as `loadId`, so a consumer that started two loads
+     * can tell whose report is whose.
      * @param type - Type/name of the registered data source
      * @param opts - Options to pass to the data source
-     * @returns Promise that resolves when data is loaded
+     * @param options - How to load
+     * @param options.replace - Replace the graph with what the source holds, but only once all of
+     *     it has parsed: a malformed or empty source rejects and leaves the graph as it was
+     * @returns Promise that resolves to the load's id when data is loaded
+     */
+    addDataFromSource(type: string, opts?: object, options?: {
+        replace?: boolean;
+    }): Promise<{
+        loadId: number;
+    }>;
+    /**
+     * Give a load its id and its place in line, synchronously, at the moment it was asked for.
+     *
+     * `loadFromFile` and `loadFromUrl` read before they load, so taking the place when the read
+     * finished would let an earlier, slower read overtake a later load. Ids rise in call order.
+     * @param replace - Whether the load replaces the graph
+     * @returns The reservation to hand to `loadReserved`
      */
-    addDataFromSource(type: string, opts?: object): Promise<void>;
+    private reserveLoad;
+    /**
+     * Run a load whose place `reserveLoad` already took, then repaint what it loaded.
+     * @param type - Type/name of the registered data source
+     * @param opts - Options to pass to the data source
+     * @param load - The reservation
+     * @param load.loadId - The load's id
+     * @param load.generation - The load's place in line
+     * @param load.replace - Whether the load replaces the graph
+     * @returns The load's id
+     */
+    private loadReserved;
     /**
      * Load graph data from a File object with auto-format detection
      * @param file - File object from file input
@@ -216,13 +250,18 @@ export declare class Graph implements GraphContext {
      * @param options.edgeSource - Where the node an edge starts at is named in the record. Left
      *     unset, the element reads `source`, then `src`, then `from`
      * @param options.edgeTarget - Where the node an edge ends at is named in the record
+     * @param options.replace - Replace the graph, once the file has parsed; see `addDataFromSource`
+     * @returns Promise that resolves to the load's id when data is loaded
      */
     loadFromFile(file: File, options?: {
         format?: string;
         nodeIdPath?: string;
         edgeSource?: string;
         edgeTarget?: string;
-    }): Promise<void>;
+        replace?: boolean;
+    }): Promise<{
+        loadId: number;
+    }>;
     /**
      * Load graph data from a URL with auto-format detection
      * @remarks
@@ -237,6 +276,8 @@ export declare class Graph implements GraphContext {
      * @param options.edgeSource - Where the node an edge starts at is named in the record. Left
      *     unset, the element reads `source`, then `src`, then `from`
      * @param options.edgeTarget - Where the node an edge ends at is named in the record
+     * @param options.replace - Replace the graph, once the data has parsed; see `addDataFromSource`
+     * @returns Promise that resolves to the load's id when data is loaded
      * @example
      * ```typescript
      * // Auto-detect format from extension
@@ -254,7 +295,10 @@ export declare class Graph implements GraphContext {
         nodeIdPath?: string;
         edgeSource?: string;
         edgeTarget?: string;
-    }): Promise<void>;
+        replace?: boolean;
+    }): Promise<{
+        loadId: number;
+    }>;
     /**
      * Add a single node to the graph.
      * @param node - Node data object to add
@@ -358,6 +402,21 @@ export declare class Graph implements GraphContext {
      * @returns Promise that resolves once the graph holds exactly these edges
      */
     setEdges(edges: Record<string | number, unknown>[], options?: AddEdgesOptions & QueueableOptions): Promise<void>;
+    /**
+     * Replace every node in the graph with a new set.
+     *
+     * What the `node-data` property does, and the node half of {@link setEdges}. A node whose id is
+     * not in the new set is removed the way {@link removeNodes} removes one, so the edges attached
+     * to it go too. A node whose id IS in the new set keeps its object and its position; its data
+     * is not rewritten. A set past the render ceiling is refused with `E_TOO_LARGE` before a node
+     * is removed, so the graph keeps the nodes it had.
+     * @param nodes - the nodes the graph should hold afterwards
+     * @param idPath - Key to use for node IDs (default: the configured node id path)
+     * @param options - Queue options for operation ordering
+     * @returns Promise that resolves once the graph holds exactly these nodes
+     * @since 2.3.0
+     */
+    setNodes(nodes: Record<string | number, unknown>[], idPath?: string, options?: QueueableOptions): Promise<void>;
     /**
      * Set the layout algorithm and configuration.
      * @remarks
@@ -523,6 +582,10 @@ export declare class Graph implements GraphContext {
      * already-applied layer kept that layer's place, and the place it had was the order the RUNS
      * FINISHED in -- so `applySuggestedStyles(["pagerank", "louvain"])` painted a PageRank
      * picture whenever PageRank happened to finish last, and a Louvain one whenever it did not.
+     *
+     * It starts the style edits and returns at once. To wait for the picture, await
+     * {@link Graph.waitForStableFrame} after the call: it settles only once every suggested layer
+     * is added, stacked in the order named and painted.
      * @param algorithmKey - A catalogue key such as "degree", a 1.10 address such as
      *     "graphty:degree", or an array of either.
      * @returns True when at least one suggestion was applied, false when no finished run of that
@@ -714,7 +777,13 @@ export declare class Graph implements GraphContext {
      *
      * It does nothing while no style pass is bound: a pass whose answer nothing draws is a pass
      * over the graph for no picture.
-     * @returns A promise that settles when the pass has finished.
+     *
+     * NOTHING AFTER TEARDOWN, AND NOTHING ACROSS A CLEAR. It is queued behind loads and runs, so
+     * it can come due after `dispose()` or while the data it started on is being cleared. Either
+     * one stops it, quietly: the graph it was painting is gone, and that is not an error.
+     * @param signal - The queue operation's own signal, when it runs as one.
+     * @returns True when the whole graph was painted, false when there was nothing to paint with
+     *     or the pass was stopped.
      */
     private repaintFromSession;
     /**
@@ -984,7 +1053,9 @@ export declare class Graph implements GraphContext {
      * Set whether the layout engine should run.
      *
      * Resuming a simulation layout that had settled restarts it, so "play" moves nodes again;
-     * pausing stops the per-frame stepping and nothing else.
+     * pausing stops the per-frame stepping and nothing else. A pause holds until
+     * `setRunning(true)`: loading data, setting a layout, an accelerator attaching or a drag
+     * never resume it.
      * @param running - True to start the layout, false to stop it
      */
     setRunning(running: boolean): void;
@@ -1552,7 +1623,8 @@ export declare class Graph implements GraphContext {
      * Set graph data (delegates to data manager)
      * @param data - Graph data object
      * @param data.nodes - Array of node data objects
-     * @param data.edges - Array of edge data objects
+     * @param data.edges - Array of edge data objects. They load as one batch, so the endpoint
+     * spelling (source/target, src/dst or from/to) is decided once for all of them.
      */
     setData(data: {
         nodes: Record<string, unknown>[];

package/dist/src/acceleration/AccelerationController.d.ts

@@ -82,7 +82,11 @@ type AccelerationOutcome<T> = {
 interface AccelerationControllerOptions {
     /** What the consumer asked for. Defaults to `"auto"`. */
     readonly policy?: AccelerationPolicy;
-    /** The `acceleration.minNodes` threshold. Defaults to 0: accelerate whenever possible. */
+    /**
+     * The `acceleration.minNodes` threshold. Left out, the general threshold is 0 and the
+     * built-in per-capability floors of {@link ACCELERATION_MIN_NODES_BY_CAPABILITY} apply; any
+     * value, including 0, is the consumer's own number and switches those floors off.
+     */
     readonly minNodes?: number;
     /** The largest graph an accelerator will be asked to compute exactly, passed to the factory. */
     readonly exactMaxNodes?: number;
@@ -223,9 +227,10 @@ export declare class AccelerationController {
     /**
      * Decides where one piece of work runs, before any of it starts.
      *
-     * The decision is the only place a CPU answer can come from, and there are four of them:
+     * The decision is the only place a CPU answer can come from, and there are five of them:
      * the policy is `"off"`, no accelerator is attached, the graph is below
-     * `acceleration.minNodes`, or the attached accelerator does not implement this capability.
+     * `acceleration.minNodes`, the graph is below the built-in floor measured for this
+     * capability, or the attached accelerator does not implement this capability.
      *
      * Under `"required"` two of them throw instead of answering quietly -- no accelerator, and
      * an accelerator without this capability -- because both are absence, and absence is what
@@ -233,6 +238,12 @@ export declare class AccelerationController {
      * runs on the CPU: an accelerator IS attached and healthy, and the threshold is a statement
      * about what pays, not about what is possible. `"off"` cannot arise under `"required"`,
      * because a policy is one of three.
+     *
+     * The built-in floor is different from the threshold in both directions. It applies only
+     * while the consumer has NOT set `acceleration.minNodes` -- a consumer's number, even 0,
+     * replaces it -- and it does NOT apply under `"required"`, because `"required"` is the
+     * policy a benchmark runs under and a benchmark of the small end of the curve must be able to
+     * reach the device.
      * @param work - The capability the work needs and the size of the graph it is over.
      * @returns Where the work runs.
      * @throws A `GraphtyError` with `E_NO_ACCELERATOR` when the policy is `"required"` and the

package/dist/src/acceleration/types.d.ts

@@ -16,6 +16,7 @@
  * The file is free of Babylon.js, Lit and DOM references so it can be re-exported from the
  * Node-safe entry points.
  */
+import type { AlgorithmAccelerator } from "@graphty/algorithms";
 import type { AccelerationErrorCode } from "../errors";
 /**
  * Where hardware acceleration stands, in one word.
@@ -362,3 +363,80 @@ export declare const ACCELERATION_MIN_NODES_KEY = "acceleration.minNodes";
  * which is not part of the published documentation site.
  */
 export declare const ACCELERATION_MIN_NODES_DEFAULT = 0;
+/**
+ * Where and when the per-capability floors below were measured, as the plan's reason quotes it.
+ */
+export declare const ACCELERATION_MIN_NODES_MEASUREMENT = "RTX 4070 SUPER, headless Chromium, 2026-09-25";
+/**
+ * The node count below which the element declines the accelerator for one capability, when the
+ * consumer has not set {@link ACCELERATION_MIN_NODES_KEY} themselves.
+ *
+ * {@link ACCELERATION_MIN_NODES_DEFAULT} is 0 because it was measured for the forceatlas2
+ * LAYOUT, whose accelerated frame was never slower than the CPU's at any size. A traversal is a
+ * different shape of work: the whole walk is one call, and on the device that call has a floor
+ * of several submit round trips whatever the size, so below some node count the CPU walk is done
+ * before the device has started. One number cannot serve both, which is why the layout default
+ * stays 0 and each algorithm capability the adapters route carries its own floor here.
+ *
+ * MEASURED, not guessed. `tmp/traversal-threshold/kernel-cpu-vs-gpu.ts` (the harness, kept
+ * out of the tree) mounted `<graphty-element acceleration="required">` in headless Chromium on
+ * the dev box (RTX 4070 SUPER through ANGLE's Vulkan backend, 2026-09-25, load average
+ * 18 to 23), took the accelerator the element built, built seeded undirected graphs with ten
+ * edges per node and integer weights 1..10 in the page, and timed the two dispatchers
+ * `Algorithm.accelerated()` uses -- `accelerated(null)` for the CPU port and
+ * `accelerated(narrowAlgorithms(accelerator))` for the device -- directly on the snapshot, so no
+ * renderer frame is in the loop. Medians of nine warm calls after one cold call, in ms:
+ *
+ * | nodes / edges | BFS cpu | BFS gpu | sssp cpu | sssp gpu | pageRank cpu | pageRank gpu | components cpu | components gpu |
+ * | ------------- | ------: | ------: | -------: | -------: | -----------: | -----------: | -------------: | -------------: |
+ * | 1k / 10k      |     0.1 |     7.8 |      0.3 |      7.3 |          0.7 |          3.0 |            0.2 |            3.9 |
+ * | 5k / 50k      |     0.6 |     8.8 |      1.6 |      7.9 |          5.3 |          2.9 |            1.2 |            5.3 |
+ * | 10k / 100k    |     1.0 |     7.5 |      2.8 |      7.2 |          4.6 |          2.9 |            2.3 |            7.4 |
+ * | 20k / 200k    |     1.7 |     9.1 |      3.8 |     13.5 |         16.2 |          3.0 |            4.8 |            7.5 |
+ * | 50k / 500k    |     5.7 |    13.0 |     25.8 |     27.6 |         50.3 |          4.3 |           11.6 |            7.8 |
+ * | 100k / 1M     |     9.8 |    17.3 |     30.4 |     49.2 |         67.4 |          5.6 |           16.2 |            8.6 |
+ * | 200k / 2M     |    17.6 |    23.2 |     73.0 |     79.6 |        148.3 |         10.5 |           29.9 |           11.5 |
+ * | 500k / 5M     |    88.3 |    33.6 |    343.8 |    150.3 |        523.0 |         36.1 |           99.7 |           20.9 |
+ * | 1M / 10M      |   250.9 |    24.2 |   1031.1 |    274.9 |       1762.4 |         17.5 |          215.7 |           43.2 |
+ *
+ * The two traversals were then measured twice more around their crossover, because the device's
+ * time at one size moves with what else the box is doing (the first sweep's 200k row was taken
+ * at a load average of 22.6, the repeats at about 18):
+ *
+ * | nodes / edges | BFS cpu | BFS gpu | sssp cpu | sssp gpu |
+ * | ------------- | ------: | ------: | -------: | -------: |
+ * | 100k / 1M     |     7.4 |     9.5 |     26.9 |     20.9 |
+ * | 200k / 2M     |    15.6 |    10.1 |     66.3 |     37.8 |
+ * | 200k / 2M     |    17.8 |    11.0 |     70.6 |     42.5 |
+ * | 300k / 3M     |    35.2 |    13.3 |    129.2 |     77.1 |
+ * | 300k / 3M     |    34.4 |    18.9 |    129.8 |     65.2 |
+ * | 400k / 4M     |    63.3 |    30.7 |    226.6 |    128.2 |
+ * | 500k / 5M     |    93.1 |    32.5 |    361.9 |    200.0 |
+ *
+ * So: BFS loses at 100k in both runs and splits at 200k (one loss, two wins); Dijkstra splits at
+ * both 100k and 200k; from 300k up the device wins every run of both by two to ten times.
+ * PageRank wins from 5k and connected components from 50k, in the one run each was measured.
+ *
+ * A floor is the smallest measured size at which the device's median was at or below the CPU
+ * port's IN EVERY RUN, so a size that won under one load and lost under another is below it. A
+ * capability that is not listed has no floor and follows {@link ACCELERATION_MIN_NODES_DEFAULT}.
+ *
+ * Two things the table does not cover. It is one card and one browser: a slower CPU or a
+ * slower device moves the crossover, and a consumer who has measured their own machine sets
+ * `acceleration.minNodes`, which replaces every floor here with their number. And it is the
+ * kernel's time, not the run's: through the element a run also publishes its result rows,
+ * which costs the same on either path and is why the element-level numbers in the issue read
+ * higher on both sides.
+ *
+ * Under `acceleration="required"` the floors do not apply: `"required"` is what a benchmark
+ * runs under, and a benchmark of the small end of the curve has to reach the device.
+ */
+/**
+ * The capabilities a floor can name: the seam's algorithm members, by their exact names.
+ *
+ * Typed against the seam rather than as a string so that a member renamed on one side and not
+ * the other is a compile error here, not a floor that silently stops applying and sends that
+ * capability back to the GPU at every size.
+ */
+export type FlooredCapability = Exclude<keyof AlgorithmAccelerator, "kind" | "release">;
+export declare const ACCELERATION_MIN_NODES_BY_CAPABILITY: Readonly<Partial<Record<FlooredCapability, number>>>;

package/dist/src/algorithms/KCoreAlgorithm.d.ts

@@ -0,0 +1,26 @@
+import type { FieldDescriptor, NodeId } from "../catalog/types";
+import { MetricAlgorithm } from "./metrics/MetricAlgorithm";
+import type { MetricMeasurement, MetricRunContext } from "./metrics/types";
+/**
+ * K-core decomposition: how deep in the graph's densely connected core each node sits.
+ *
+ * A node's core number is the largest k for which it belongs to a k-core -- the largest part of
+ * the graph in which every node has at least k neighbours. Every node has one, so every node is
+ * measured.
+ */
+export declare class KCoreAlgorithm extends MetricAlgorithm {
+    static namespace: string;
+    static type: string;
+    /**
+     * The fields a k-core result publishes.
+     * @returns The uniform node-metric fields.
+     */
+    protected resultFields(): readonly FieldDescriptor[];
+    /**
+     * Give every node its core number.
+     * @param context - Where progress goes and where cancellation arrives.
+     * @param nodeIds - The nodes to measure.
+     * @returns One core number per node.
+     */
+    protected measure(context: MetricRunContext, nodeIds: readonly NodeId[]): Promise<MetricMeasurement>;
+}

package/dist/src/algorithms/LinkPredictionAlgorithm.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @file Link prediction: the pairs of unconnected nodes most likely to be joined next.
+ *
+ * The answer is a list of scored pairs, not a value on each node or edge -- a predicted link is
+ * an edge that does not exist yet, so there is no element to hang it on. The result is shaped as
+ * a pair list, which is why a run of it suggests no style: painting it would mean inventing the
+ * thing it painted.
+ */
+import { adamicAdarPrediction, commonNeighborsPrediction } from "@graphty/algorithms";
+import { type OptionsSchema as ZodOptionsSchema } from "../config";
+import { type AlgorithmOutput, type AlgorithmRunContext, DeclaredAlgorithm } from "./results";
+import type { OptionsSchema } from "./types/OptionSchema";
+/** The two scoring methods, by the name the `method` option takes. */
+declare const METHODS: {
+    readonly "adamic-adar": typeof adamicAdarPrediction;
+    readonly "common-neighbors": typeof commonNeighborsPrediction;
+};
+/** Options for link prediction. */
+interface LinkPredictionOptions extends Record<string, unknown> {
+    /** Which score ranks the pairs. */
+    method: keyof typeof METHODS;
+    /** How many of the best-scoring pairs to keep. */
+    topK: number;
+}
+/**
+ * Link prediction: scores every pair of nodes that is not already joined by how many neighbours
+ * the two share, and keeps the best.
+ */
+export declare class LinkPredictionAlgorithm extends DeclaredAlgorithm<LinkPredictionOptions> {
+    static namespace: string;
+    static type: string;
+    static zodOptionsSchema: ZodOptionsSchema;
+    static optionsSchema: OptionsSchema;
+    /**
+     * Score every unconnected pair of nodes and keep the best.
+     * @param context - What the element gave the run.
+     * @returns The scored pairs, best first, or null when the graph has no nodes.
+     */
+    compute(context: AlgorithmRunContext): Promise<AlgorithmOutput | null>;
+}
+export {};

package/dist/src/catalog/algorithms.d.ts

@@ -20,10 +20,10 @@
  *   `JSON.stringify`, a `postMessage` to a worker and a write to a saved document, and a
  *   closure survives none of those. A cost estimate that needs code belongs to
  *   `session.estimate()`, which runs where the code is.
- * - **The table only lists what ships.** Four members of `KNOWN_ALGORITHMS` -- `all-paths`,
- *   `clustering-coefficient`, `k-core` and `link-prediction` -- are not registered by this
- *   package and therefore have no descriptor here. A catalogue that advertised them would be
- *   lying about what the element can run.
+ * - **The table only lists what ships.** Two members of `KNOWN_ALGORITHMS` -- `all-paths` and
+ *   `clustering-coefficient`, listed in `DEPRECATED_ALGORITHMS` -- are not implemented and
+ *   therefore have no descriptor here. A catalogue that advertised them would be lying about
+ *   what the element can run.
  *
  * Two conventions worth stating once:
  *
@@ -70,7 +70,7 @@ export interface BuiltInAlgorithmDescriptor extends AlgorithmDescriptor {
 /**
  * Every algorithm this package registers, as a plain-JSON descriptor.
  *
- * Twenty-one descriptors for twenty-three registered algorithms: the two single-source
+ * Twenty-three descriptors for twenty-five registered algorithms: the two single-source
  * shortest-path engines are one key with a `method` parameter, and the two component algorithms
  * are one key with a `strength` parameter. Each descriptor's `legacyKeys` names the 1.10 keys it
  * replaces and the parameters that reproduce them.

package/dist/src/catalog/index.d.ts

@@ -9,8 +9,8 @@ export type { LabelAnimation, LabelBadge, LabelGradientDirection, LabelGradientT
 export { LABEL_STYLE_FIELDS } from "./label-style";
 export type { OptionsFromZodOptions, OptionsSource, OptionUiMeta } from "./optionsFromZod";
 export { optionsFromZod } from "./optionsFromZod";
-export type { AlgorithmDescriptor, AlgorithmKey, AttributeDescriptor, AttributeType, Binding, CameraDescriptor, CameraId, CatalogApi, Channel, ChannelValue, CostClass, DrawingMode, EdgeId, EdgeLinePattern, Encoding, FieldDescriptor, FormatDescriptor, FormatId, FunctionDescriptor, GraphtyErrorCode, KnownAlgorithm, LabelStyle, LayerId, LayerKind, LayerSource, LayerSpec, LayoutDescriptor, LayoutId, LogSinkDescriptor, LogSinkId, MetricAvailability, NodeId, OptionBound, OptionChoice, OptionDescriptor, OptionType, PaletteDescriptor, PaletteId, Path, Query, QueryValidation, ResultShape, Rgba, RunId, ScaleDescriptor, Scope, ScopeId, Selector, StaticStyle, StyleDocument, ThemeDescriptor, } from "./types";
-export { ATTRIBUTE_TYPES, COST_CLASSES, isAttributeType, isCostClass, isOptionBound, isOptionType, isResultShape, KNOWN_ALGORITHMS, KNOWN_CAMERA_IDS, KNOWN_FORMAT_IDS, KNOWN_LAYOUT_IDS, KNOWN_LOG_SINK_IDS, KNOWN_PALETTE_IDS, OPTION_BOUND_SOURCES, OPTION_TYPES, RESULT_SHAPES, } from "./types";
+export type { AlgorithmDescriptor, AlgorithmKey, AttributeDescriptor, AttributeType, Binding, CameraDescriptor, CameraId, CatalogApi, Channel, ChannelValue, CostClass, DeprecatedAlgorithm, DeprecatedCatalogMethod, DrawingMode, EdgeId, EdgeLinePattern, Encoding, FieldDescriptor, FormatDescriptor, FormatId, FunctionDescriptor, GraphtyErrorCode, KnownAlgorithm, LabelStyle, LayerId, LayerKind, LayerSource, LayerSpec, LayoutDescriptor, LayoutId, LogSinkDescriptor, LogSinkId, MetricAvailability, NodeId, OptionBound, OptionChoice, OptionDescriptor, OptionType, PaletteDescriptor, PaletteId, Path, Query, QueryValidation, ResultShape, Rgba, RunId, ScaleDescriptor, Scope, ScopeId, Selector, StaticStyle, StyleDocument, ThemeDescriptor, } from "./types";
+export { ATTRIBUTE_TYPES, COST_CLASSES, DEPRECATED_ALGORITHMS, isAttributeType, isCostClass, isOptionBound, isOptionType, isResultShape, KNOWN_ALGORITHMS, KNOWN_CAMERA_IDS, KNOWN_FORMAT_IDS, KNOWN_LAYOUT_IDS, KNOWN_LOG_SINK_IDS, KNOWN_PALETTE_IDS, OPTION_BOUND_SOURCES, OPTION_TYPES, RESULT_SHAPES, } from "./types";
 /**
  * What the element does NOT serve on the styling surface, said out loud.
  *