@graphty/graphty-element 2.3.1 → 2.4.1

package/dist/graphty.js

@@ -1,81 +1,85 @@
-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 pa, G as da, V as la, i as Ga } from "./chunks/GraphStyle-Cwr55SAE.js";
-import { c as ya } from "./chunks/common-DWNKjpH_.js";
+import { A as s, a as r, b as E, D as O, E as o, d as S, G as R, e as t, I as L, L as _, N as C, O as A, R as N, S as g, f as i, g as n, h as I, U as T, i as p } from "./chunks/index-6GDfNfwJ.js";
+import { L as d, S as G, a as f, r as y } from "./chunks/paletteRegistry-jg9uS7wo.js";
+import { D as M, E as P } from "./chunks/DataSource-xL3Yn0Pa.js";
+import { I as m, J as U, p as c, q as x, A as u, C as B, x as V, r as H } from "./chunks/optionsFromZod-DHLLiX_8.js";
+import { r as Y } from "./chunks/GraphtyLogger-kbOx2zq3.js";
+import { g as W, b as k, N as w, c as K, P as q, R as v, S as J, d as Q, e as X, f as j } from "./chunks/NodeStyle-CtmA7dXi.js";
+import { A as Z, a as $, G as aa, i as ea, b as sa } from "./chunks/pluginRegistry-MaTIDh6l.js";
+import { B as Ea, a as Oa, b as oa, C as Sa, G as Ra, c as ta, I as La, O as _a, d as Ca, e as Aa, f as Na, P as ga, g as ia, h as na, R as Ia, T as Ta, i as pa, V as la, Y as da } from "./chunks/sequential-Zym81qm7.js";
+import { a as fa, G as ya, V as Da, i as Ma } from "./chunks/GraphStyle-Cwr55SAE.js";
+import { c as ha } from "./chunks/common-DWNKjpH_.js";
 export {
-  Q as ACCELERATION_ERROR_CODES,
-  P as ACCELERATION_MIN_NODES_DEFAULT,
+  Z as ACCELERATION_ERROR_CODES,
+  m as ACCELERATION_MIN_NODES_DEFAULT,
   U as ACCELERATION_MIN_NODES_KEY,
   c as ACCELERATION_POLICIES,
-  m as ACCELERATION_POLICY_DEFAULT,
+  x as ACCELERATION_POLICY_DEFAULT,
   u as Algorithm,
-  e as AlgorithmManager,
-  E as AnimationCancelledError,
-  aa as BLUES_COLORS,
-  sa as BLUE_HIGHLIGHT,
-  ea as BLUE_ORANGE_COLORS,
-  r as BUILTIN_PRESETS,
-  Ea as CARBON_COLORS,
-  x as CPU_PRECISION,
-  pa as DEFAULT_VIEW_MODE,
+  s as AlgorithmManager,
+  r as AnimationCancelledError,
+  Ea as BLUES_COLORS,
+  Oa as BLUE_HIGHLIGHT,
+  oa as BLUE_ORANGE_COLORS,
+  E as BUILTIN_PRESETS,
+  Sa as CARBON_COLORS,
+  B as CPU_PRECISION,
+  fa as DEFAULT_VIEW_MODE,
   O as DataManager,
-  D as DataSource,
-  H as EDGE_CONSTANTS,
+  M as DataSource,
+  W as EDGE_CONSTANTS,
   o as Edge,
-  b as EdgeStyle,
-  M as ErrorAggregator,
+  k as EdgeStyle,
+  P as ErrorAggregator,
   S as EventManager,
-  X as GRAPHTY_ERROR_CODES,
-  ra as GREENS_COLORS,
-  Oa as GREEN_SUCCESS,
+  $ as GRAPHTY_ERROR_CODES,
+  Ra as GREENS_COLORS,
+  ta as GREEN_SUCCESS,
   R as Graph,
-  da as GraphBackground,
-  _ as Graphty,
-  j as GraphtyError,
-  oa as INFERNO_COLORS,
+  ya as GraphBackground,
+  t as Graphty,
+  aa as GraphtyError,
+  La as INFERNO_COLORS,
   L as InputManager,
-  l as LayoutEngine,
-  t as LayoutManager,
+  d as LayoutEngine,
+  _ as LayoutManager,
   C as Node,
-  Y as NodeShapes,
-  F as NodeStyle,
-  Sa as OKABE_ITO_COLORS,
-  Ra as ORANGES_COLORS,
-  _a as ORANGE_WARNING,
-  La as OTHER_GROUP_COLOR,
+  w as NodeShapes,
+  K as NodeStyle,
+  _a as OKABE_ITO_COLORS,
+  Ca as ORANGES_COLORS,
+  Aa as ORANGE_WARNING,
+  Na as OTHER_GROUP_COLOR,
   A as OperationQueueManager,
-  ta as PASTEL_COLORS,
-  Ca as PLASMA_COLORS,
-  Aa as PURPLE_GREEN_COLORS,
-  W as PolyhedronType,
-  Na as RED_BLUE_COLORS,
+  ga as PASTEL_COLORS,
+  ia as PLASMA_COLORS,
+  na as PURPLE_GREEN_COLORS,
+  q as PolyhedronType,
+  Ia as RED_BLUE_COLORS,
   N as RenderManager,
-  K as RichTextStyle,
-  k as SHAPE_CONSTANTS,
-  n as ScreenshotError,
-  I as ScreenshotErrorCode,
-  T as SelectionManager,
+  v as RichTextStyle,
+  J as SHAPE_CONSTANTS,
+  g as ScreenshotError,
+  i as ScreenshotErrorCode,
+  n as SelectionManager,
   G as SimpleLayoutConfig,
   f as SimpleLayoutEngine,
-  g as StatsManager,
-  na as TOL_MUTED_COLORS,
-  Ia as TOL_VIBRANT_COLORS,
-  i as UpdateManager,
-  la as VIEW_MODE_VALUES,
-  Ta as VIRIDIS_COLORS,
-  ga as YLORBR_COLORS,
-  ya as colorToHex,
-  q as defaultEdgeStyle,
-  v as defaultNodeStyle,
-  w as defaultRichTextLabelStyle,
+  I as StatsManager,
+  Ta as TOL_MUTED_COLORS,
+  pa as TOL_VIBRANT_COLORS,
+  T as UpdateManager,
+  Da as VIEW_MODE_VALUES,
+  la as VIRIDIS_COLORS,
+  da as YLORBR_COLORS,
+  ha as colorToHex,
+  Q as defaultEdgeStyle,
+  X as defaultNodeStyle,
+  j as defaultRichTextLabelStyle,
   p as defaultXRConfig,
-  B as isAccelerationPolicy,
-  z as isGraphtyError,
-  Z as isGraphtyErrorCode,
-  Ga as isViewMode
+  V as isAccelerationPolicy,
+  ea as isGraphtyError,
+  sa as isGraphtyErrorCode,
+  Ma as isViewMode,
+  H as registerCameraView,
+  Y as registerLogSink,
+  y as registerPalette
 };

package/dist/index.d.ts

@@ -54,6 +54,9 @@ export { DataSource } from "./src/data/DataSource";
 export type { DataLoadingError, ErrorSummary } from "./src/data/index";
 export { ErrorAggregator } from "./src/data/index";
 export { Algorithm } from "./src/algorithms/Algorithm";
+export { registerCameraView } from "./src/catalog/cameraRegistry";
+export { registerLogSink } from "./src/catalog/logSinkRegistry";
+export { registerPalette } from "./src/catalog/paletteRegistry";
 export type { CameraStateChangedEvent, DataLoadingCompleteEvent, DataLoadingErrorEvent, DataLoadingErrorSummaryEvent, DataLoadingProgressEvent, EdgeAddEvent, EdgeEvent, EdgeEventType, EdgeGenericEvent, EventCallbackType, EventType, GraphDataAddedEvent, GraphDataLoadedEvent, GraphErrorEvent, GraphEvent, GraphEventType, GraphGenericEvent, GraphLayoutInitializedEvent, GraphSettledEvent, NodeAddEvent, NodeClickEvent, NodeDragEndEvent, NodeDragStartEvent, NodeEvent, NodeEventDetail, NodeEventType, NodeGenericEvent, NodeHoverEvent, } from "./src/events";
 export type { Manager, ManagerConfig, ManagerContext, QueueableManager } from "./src/managers/index";
 export { AlgorithmManager, DataManager, EventManager, InputManager, LayoutManager, OperationQueueManager, RenderManager, SelectionManager, StatsManager, UpdateManager, } from "./src/managers/index";

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-kbOx2zq3.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-kbOx2zq3.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/pluginRegistry-MaTIDh6l.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-DHLLiX_8.js";
+import { D as h } from "./chunks/GraphSession-PFm2tJ_j.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-PFm2tJ_j.js";
+import { L as s } from "./chunks/scales-BXHmwPXC.js";
 const u = [
   {
     id: "fixed",

package/dist/src/Edge.d.ts

@@ -239,10 +239,10 @@ export declare class Edge {
      * cached SOURCE meshes -- and Babylon disposes a source mesh's instances with it. That is why
      * node spheres and 3D solid edge lines vanished on a dataset clear while roughly sixty grey
      * ARROWHEADS stayed on the canvas, in rosettes where the previous dataset's edges had
-     * converged. Arrowheads are deliberately not cached (`EdgeMesh.createArrowHead` carries a
-     * "PERFORMANCE FIX: Create individual meshes for all arrow types" note): they are built bare
-     * against the scene and parented to the `graph-root` TransformNode, which outlives every
-     * dataset, so nothing ever disposed them. The same was true of the patterned-line meshes
+     * converged. Arrowheads are not in the MeshCache (today each is an instance of a per-scene
+     * batch that `FilledArrowRenderer.instanceOf` frees with its last head): they are parented
+     * to the `graph-root` TransformNode, which outlives every dataset, so nothing but this
+     * dispose frees them. The same was true of the patterned-line meshes
      * (dot/dash/star/...), 2D lines, bezier curves and all three RichTextLabels.
      *
      * Every dispose is guarded with `isDisposed()` -- matching the idiom already used in

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;
@@ -186,6 +190,12 @@ export declare class AccelerationController {
      *
      * Switching to `"off"` releases the accelerator, because holding a device nobody is allowed
      * to use is a cost with no benefit. Switching back to `"auto"` or `"required"` probes again.
+     * Leaving `"required"` releases a software accelerator, which only `"required"` accepts, and
+     * probes again.
+     *
+     * A no-op on a disposed controller, rather than a throw: the element forwards its
+     * `acceleration` attribute here from `attributeChangedCallback`, where a throw would leave the
+     * element unrendered, and a probe nobody can hear would request a device for nothing.
      * @param policy - The new policy.
      */
     setPolicy(policy: AccelerationPolicy): void;
@@ -223,9 +233,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 +244,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/registry.d.ts

@@ -92,6 +92,9 @@ export declare class AcceleratorRegistry {
 /**
  * The registry the element uses when it is not given another, and the one the `./webgpu` entry
  * point registers into.
+ *
+ * One per page rather than one per copy of graphty-element, so the `./webgpu` entry reaches the
+ * element whichever copy defined it.
  */
 export declare const acceleratorRegistry: AcceleratorRegistry;
 /**