@graphty/graphty-element 2.3.0 → 2.4.0

package/dist/graphty.js

@@ -1,62 +1,62 @@
-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 t, L, 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 l } from "./chunks/index-CD0_RJv-.js";
-import { a as p, S as G, b as f } from "./chunks/paletteRegistry-DnWHQsAD.js";
-import { D as y, E as D } from "./chunks/DataSource-bt0DhBjG.js";
-import { k as P, l as U, g as c, h as m, A as u, C as x, i as B } from "./chunks/Algorithm-RQ629NLb.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 v, b as w, c as Q } from "./chunks/NodeStyle-DKj7HjMJ.js";
-import { A as j, a as q, G as z, i as J, 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 ta, P as La, 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 la, G as da, V as pa, i as Ga } from "./chunks/GraphStyle-D0PXnZKu.js";
-import { c as ha } from "./chunks/common-DWNKjpH_.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 {
-  j as ACCELERATION_ERROR_CODES,
+  Q as ACCELERATION_ERROR_CODES,
   P as ACCELERATION_MIN_NODES_DEFAULT,
   U as ACCELERATION_MIN_NODES_KEY,
   c as ACCELERATION_POLICIES,
   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,
-  la as DEFAULT_VIEW_MODE,
+  pa as DEFAULT_VIEW_MODE,
   O as DataManager,
-  y as DataSource,
+  D as DataSource,
   H as EDGE_CONSTANTS,
   o as Edge,
   b as EdgeStyle,
-  D as ErrorAggregator,
+  M as ErrorAggregator,
   S as EventManager,
-  q as GRAPHTY_ERROR_CODES,
-  ra as GREENS_COLORS,
+  X as GRAPHTY_ERROR_CODES,
+  Ea as GREENS_COLORS,
   Oa as GREEN_SUCCESS,
   R as Graph,
   da as GraphBackground,
   _ as Graphty,
-  z as GraphtyError,
+  j as GraphtyError,
   oa as INFERNO_COLORS,
-  t as InputManager,
-  p as LayoutEngine,
-  L as LayoutManager,
+  L as InputManager,
+  l as LayoutEngine,
+  t as LayoutManager,
   C as Node,
   Y as NodeShapes,
   F as NodeStyle,
   Sa as OKABE_ITO_COLORS,
   Ra as ORANGES_COLORS,
   _a as ORANGE_WARNING,
-  ta as OTHER_GROUP_COLOR,
+  La as OTHER_GROUP_COLOR,
   A as OperationQueueManager,
-  La as PASTEL_COLORS,
+  ta as PASTEL_COLORS,
   Ca as PLASMA_COLORS,
   Aa as PURPLE_GREEN_COLORS,
   W as PolyhedronType,
   Na as RED_BLUE_COLORS,
   N as RenderManager,
-  k as RichTextStyle,
-  K as SHAPE_CONSTANTS,
+  K as RichTextStyle,
+  k as SHAPE_CONSTANTS,
   n as ScreenshotError,
   I as ScreenshotErrorCode,
   T as SelectionManager,
@@ -66,16 +66,16 @@ export {
   na as TOL_MUTED_COLORS,
   Ia as TOL_VIBRANT_COLORS,
   i as UpdateManager,
-  pa as VIEW_MODE_VALUES,
+  la as VIEW_MODE_VALUES,
   Ta as VIRIDIS_COLORS,
   ga as YLORBR_COLORS,
-  ha as colorToHex,
-  v as defaultEdgeStyle,
-  w as defaultNodeStyle,
-  Q as defaultRichTextLabelStyle,
-  l as defaultXRConfig,
+  ya as colorToHex,
+  q as defaultEdgeStyle,
+  v as defaultNodeStyle,
+  w as defaultRichTextLabelStyle,
+  p as defaultXRConfig,
   B as isAccelerationPolicy,
-  J as isGraphtyError,
+  z as isGraphtyError,
   Z as isGraphtyErrorCode,
   Ga as isViewMode
 };

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-D0PXnZKu.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.d.ts

@@ -78,7 +78,7 @@ export type { LayoutRecommendation, LayoutRecommendationOptions } from "./src/se
 export { recommendLayout } from "./src/session";
 export type { BatchResult, BatchStep, Caveats, EngineVersions, Precision, Progress, QueueEntry, QueuePolicy, ResolvedScope, Run, RunChange, RunDirection, RunExecutionContext, RunExecutor, RunOptions, RunOutcome, RunPhase, RunProgressReport, RunQueue, RunRecord, RunRemoval, RunsApi, RunScopeRecord, RunSpec, RunStatus, RunStyle, StaleNote, StartOptions, WeightMeaning, } from "./src/session/runs";
 export { isRunId, isRunStatus, isTerminalRunStatus, QUEUE_POLICIES, RUN_ID_PATTERN, RUN_PHASES, RUN_STATUSES, TERMINAL_RUN_STATUSES, } from "./src/session/runs";
-export type { Histogram, HistogramBin, HistogramBinning, HistogramOptions, Normalization, NumericColumnView, RankingEntry, ReadingOptions, ResultsApi, ResultSummary, RunRef, RunResult, SummaryEntry, SummaryGroup, } from "./src/session/results";
+export type { Histogram, HistogramBin, HistogramBinning, HistogramOptions, Normalization, NumericColumnView, RankingEntry, ReadingOptions, ResultsApi, ResultSummary, RunRef, RunResult, SummaryEntry, SummaryGroup, TopRanking, } from "./src/session/results";
 export { defaultReading, RESULT_FIELD_NAMES, RESULT_ROOT, RESULT_SHAPE_CONTRACTS, resultPath } from "./src/session/results";
 export type { SavedScope, ScopeApi, ScopeCount, ScopeCountOptions } from "./src/session/scope";
 export { DEFAULT_SCOPE_SAMPLE } from "./src/session/scope";

package/dist/session.js

@@ -1,10 +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 g } from "./chunks/GraphtyError-BwcnblTH.js";
-import { g as O, h as U, i as I } from "./chunks/Algorithm-RQ629NLb.js";
-import { D as h } from "./chunks/GraphSession-iNyKm7Ds.js";
-import { a as N, b as y, c as D, d as v, Q as w, R as G, e as b, f as x, S as F, T as M, g as z, i as k, h as H, j as Y, k as j } from "./chunks/GraphSession-iNyKm7Ds.js";
-import { R as Q, t as X, u as B, v as J, w as K, x as V } from "./chunks/paletteRegistry-DnWHQsAD.js";
-import { L as s } from "./chunks/scales-DyuwlJKI.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",
@@ -53,34 +52,34 @@ export {
   c as ACCELERATION_ERROR_CODES,
   O as ACCELERATION_POLICIES,
   U as ACCELERATION_POLICY_DEFAULT,
-  N as DEFAULT_COST_GATE_LIMITS,
-  y as DEFAULT_EXACT_COMPUTATION_CAP_SECONDS,
+  b as DEFAULT_COST_GATE_LIMITS,
+  x as DEFAULT_EXACT_COMPUTATION_CAP_SECONDS,
   h as DEFAULT_LIMITS,
-  D as DEFAULT_SCOPE_SAMPLE,
-  v as DEFAULT_SELECTION_CAP,
+  F as DEFAULT_SCOPE_SAMPLE,
+  z as DEFAULT_SELECTION_CAP,
   C as GRAPHTY_ERROR_CODES,
   p as GraphtyError,
-  w as QUEUE_POLICIES,
-  Q as RESULT_FIELD_NAMES,
-  X as RESULT_ROOT,
+  M as QUEUE_POLICIES,
+  I as RESULT_FIELD_NAMES,
+  P as RESULT_ROOT,
   R as RESULT_SHAPES,
-  B as RESULT_SHAPE_CONTRACTS,
-  G as RUN_ID_PATTERN,
-  b as RUN_PHASES,
-  x as RUN_STATUSES,
-  F as SET_OPS,
-  M as TERMINAL_RUN_STATUSES,
-  z as createGraphSession,
-  J as defaultReading,
-  I as isAccelerationPolicy,
-  k as isAlgorithmRunCommand,
+  y as RESULT_SHAPE_CONTRACTS,
+  k as RUN_ID_PATTERN,
+  H as RUN_PHASES,
+  Y as RUN_STATUSES,
+  j as SET_OPS,
+  q as TERMINAL_RUN_STATUSES,
+  Q as createGraphSession,
+  N as defaultReading,
+  D as isAccelerationPolicy,
+  X as isAlgorithmRunCommand,
   m as isGraphtyError,
-  g as isGraphtyErrorCode,
+  L as isGraphtyErrorCode,
   _ as isResultShape,
-  H as isRunId,
-  Y as isRunStatus,
-  j as isTerminalRunStatus,
-  K as quotePath,
+  B as isRunId,
+  J as isRunStatus,
+  K as isTerminalRunStatus,
+  w as quotePath,
   T as recommendLayout,
-  V as resultPath
+  v as resultPath
 };

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
@@ -558,9 +621,17 @@ export declare class Graph implements GraphContext {
         [key: string]: unknown;
     }[], options?: QueueableOptions): Promise<void>;
     /**
-     * Set the active camera mode (e.g., "arcRotate", "universal").
-     * @param mode - Camera mode key to activate
+     * Activate the camera that belongs to the current view mode: `"2d"` in 2D, `"orbit"` in 3D.
+     *
+     * A camera belongs to one view mode, and switching between them is `setViewMode`'s job: it
+     * also rebuilds the meshes and the layout for the new mode. A camera from the other mode is
+     * refused rather than activated, because activating it would leave the scene drawing through
+     * one mode's camera while recording the other, and `setViewMode` would then take the scene
+     * for already being where it was asked to go.
+     * @param mode - Camera key to activate
      * @param options - Queue options for operation ordering
+     * @throws A `GraphtyError` with `E_BAD_COMMAND` when the camera does not belong to the view
+     * mode the graph is in (or is going to, once queued view-mode changes run).
      */
     setCameraMode(mode: CameraKey, options?: QueueableOptions): Promise<void>;
     /**
@@ -706,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;
     /**
@@ -900,6 +977,27 @@ export declare class Graph implements GraphContext {
      * the session begins when a consumer calls `setViewMode` from a click.
      */
     private applyOpeningViewMode;
+    /**
+     * Frame the graph on the element's own initiative -- after a data load, a new layout, or the
+     * first settlement -- unless the configuration placed the camera itself with
+     * `startingCameraDistance`. An explicit `zoomToFit()` is not affected.
+     */
+    private autoFrame;
+    /**
+     * Set how far the camera stands from the graph, and stop the element framing the graph on its
+     * own. Undefined hands framing back to zoom-to-fit.
+     *
+     * The 3D orbit camera is moved to the distance (floored at its minimum zoom distance). The 2D
+     * camera's half-width becomes the half-extent the 3D camera's field of view covers at that
+     * distance, so switching view mode keeps a comparable framing.
+     * @param distance - The distance, in scene units, or undefined for automatic framing.
+     * @throws A `GraphtyError` with `E_OPTION_RANGE` when the distance is not a finite number.
+     */
+    setStartingCameraDistance(distance: number | undefined): void;
+    /**
+     * Place both cameras from the configured `startingCameraDistance`, when there is one.
+     */
+    private applyStartingCameraDistance;
     /**
      * Set the view mode.
      * This controls the camera type, input handling, and rendering approach.
@@ -955,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;
@@ -1340,8 +1440,9 @@ export declare class Graph implements GraphContext {
      * Required because cameraDistance is not a scene node property
      * @param orbitController - Orbit camera controller instance
      * @param orbitController.cameraDistance - Current camera distance from pivot
+     * @param orbitController.clampDistance - The controller's distance rule (the zoom floor)
      * @param orbitController.updateCameraPosition - Function to update camera position
-     * @param targetDistance - Target camera distance to animate to
+     * @param requestedDistance - Camera distance to animate to, before the zoom floor applies
      * @param frameCount - Number of frames for the animation
      * @param fps - Frames per second for the animation
      * @param easing - Optional easing function name
@@ -1522,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