@graphty/graphty-element 2.3.1 → 2.4.1

package/dist/src/data/GEXFDataSource.d.ts

@@ -3,6 +3,14 @@ type GEXFDataSourceConfig = BaseDataSourceConfig;
 /**
  * Data source for loading graph data from GEXF (Graph Exchange XML Format) files.
  * Supports node and edge attributes, attribute types, and dynamic graphs.
+ *
+ * Dynamic graphs keep their time data on each record rather than acting on it:
+ * - a node's or edge's `start` / `end` / `timestamp` (see {@link readInterval}) go onto its data
+ *   under those names, and its `<spells>` go onto `spells` as a list of the same intervals;
+ * - an attribute with time-sliced `attvalue`s becomes a list of `{ value, start, end }` slices
+ *   instead of a single value. An attribute with no timed `attvalue` keeps its plain value.
+ *
+ * Dynamic `viz:*` elements (timed positions, colours or sizes) are not read.
  */
 export declare class GEXFDataSource extends DataSource {
     static readonly type = "gexf";
@@ -60,6 +68,21 @@ export declare class GEXFDataSource extends DataSource {
      * @returns the edge records, and how many edges stated each direction
      */
     private parseEdges;
+    /**
+     * Copy a node's or edge's lifetime, spells and attribute values onto its record.
+     *
+     * Every `attvalue` for one attribute is kept: if any of them is timed, the attribute becomes
+     * the list of all its slices, `{ value, start, end }`, in file order; otherwise it keeps its
+     * plain value, so a static file reads exactly as it always has.
+     * @param obj - the parsed `<node>` or `<edge>`
+     * @param obj.attvalues - its `<attvalues>` element, if any
+     * @param obj.attvalues.attvalue - the `<attvalue>` children
+     * @param obj.spells - its `<spells>` element, if any
+     * @param obj.spells.spell - the `<spell>` children
+     * @param record - the record being built, written in place
+     * @param attributes - the attribute definitions for this element class
+     */
+    private readTimeData;
     private parseValue;
 }
 export {};

package/dist/src/errors/codes.d.ts

@@ -163,7 +163,8 @@ export type GraphtyErrorCode =
 /**
  * A source could not be fetched: a network failure, a non-2xx status, a CORS refusal or an
  * unreadable file. `details` carry the url and the status where there was one, and `cause`
- * carries the original failure. Usually recoverable by retrying.
+ * carries the original failure. Recoverable by retrying, except a client error (a 4xx other
+ * than 408 and 429), which fails after one request with `recoverable: false`.
  */
  | "E_FETCH_FAILED"
 /**
@@ -185,6 +186,20 @@ export type GraphtyErrorCode =
  * import plan or the data.
  */
  | "E_ID_MISSING"
+/**
+ * A load read its source to the end and found nothing in it: no node records and no edge
+ * records. It is reported as a failure rather than as a success with zero counts, and a
+ * load asked to `replace` keeps the graph it would have replaced. `details` carry the
+ * format. The caller checks the file, or the format it was read as.
+ */
+ | "E_EMPTY_LOAD"
+/**
+ * A load was overtaken: a REPLACING load was called after it, or `clearData` ran, so its data
+ * would have replaced or mixed into the newer dataset. It stops without touching the graph.
+ * `details` carry the format. Not a fault in the source; the caller ignores it, or loads
+ * again.
+ */
+ | "E_SUPERSEDED"
 /**
  * The graph exceeds a hard structural limit of an index or of the accelerator, and no scope
  * or sample makes the work runnable. `details` carry the size and the limit. Distinct from

package/dist/src/events.d.ts

@@ -56,6 +56,12 @@ export interface GraphDataLoadedEvent {
         dataSourceType: string;
         /** What the load did: the endpoint spelling it resolved, and the counts it produced. */
         report: ImportReport;
+        /**
+         * Which load this is about: the id `addDataFromSource`, `loadFromFile` and `loadFromUrl`
+         * resolve to, and that every event about one load carries. Absent on a report about records
+         * handed to a setter, which is not a load.
+         */
+        loadId?: number;
     };
 }
 export interface GraphDataAddedEvent {
@@ -155,6 +161,12 @@ export interface DataLoadingProgressEvent {
      */
     edgeRecordsLoaded: number;
     chunksProcessed: number;
+    /**
+     * Which load this is about: the id `addDataFromSource`, `loadFromFile` and `loadFromUrl`
+     * resolve to, and that every event about one load carries. Absent on a report about records
+     * handed to a setter, which is not a load.
+     */
+    loadId?: number;
 }
 export interface DataLoadingErrorEvent {
     type: "data-loading-error";
@@ -165,6 +177,12 @@ export interface DataLoadingErrorEvent {
     nodeId?: unknown;
     edgeId?: string;
     canContinue: boolean;
+    /**
+     * Which load this is about: the id `addDataFromSource`, `loadFromFile` and `loadFromUrl`
+     * resolve to, and that every event about one load carries. Absent on a report about records
+     * handed to a setter, which is not a load.
+     */
+    loadId?: number;
 }
 export interface DataLoadingErrorSummaryEvent {
     type: "data-loading-error-summary";
@@ -174,6 +192,12 @@ export interface DataLoadingErrorSummaryEvent {
     message: string;
     suggestion?: string;
     detailedReport: string;
+    /**
+     * Which load this is about: the id `addDataFromSource`, `loadFromFile` and `loadFromUrl`
+     * resolve to, and that every event about one load carries. Absent on a report about records
+     * handed to a setter, which is not a load.
+     */
+    loadId?: number;
 }
 export interface DataLoadingCompleteEvent {
     type: "data-loading-complete";
@@ -203,6 +227,12 @@ export interface DataLoadingCompleteEvent {
     success: boolean;
     /** What the load did: the endpoint spelling, the repeat policy, and every count. */
     report: ImportReport;
+    /**
+     * Which load this is about: the id `addDataFromSource`, `loadFromFile` and `loadFromUrl`
+     * resolve to, and that every event about one load carries. Absent on a report about records
+     * handed to a setter, which is not a load.
+     */
+    loadId?: number;
 }
 /**
  * Emitted once per `removeNodes` call, naming everything that went.

package/dist/src/graphty-element.d.ts

@@ -122,8 +122,9 @@ export declare class Graphty extends LitElement {
     /**
      * Array of node data objects to visualize.
      * @remarks
-     * Setting this property replaces all existing nodes. For incremental
-     * updates, use the `graph.addNodes()` method instead.
+     * Setting this property REPLACES all existing nodes: a node whose id is
+     * not in the new array is removed, with the edges attached to it. For
+     * incremental updates, use the `addNodes()` method instead.
      *
      * Each node object should have an ID field (default: "id"). Additional
      * properties can be used in style selectors and accessed via `node.data`.
@@ -148,7 +149,7 @@ export declare class Graphty extends LitElement {
      */
     get nodeData(): Record<string, unknown>[] | undefined;
     /**
-     * Sets the node data array. Triggers addition of nodes to the graph.
+     * Sets the node data array. Replaces the graph's nodes with these.
      */
     set nodeData(value: Record<string, unknown>[] | undefined);
     /**
@@ -190,7 +191,8 @@ export declare class Graphty extends LitElement {
      */
     get dataSource(): string | undefined;
     /**
-     * Sets the data source type. Initializes data loading when combined with dataSourceConfig.
+     * Sets the data source type. Starts a load when combined with dataSourceConfig; see
+     * `dataSourceConfig` for what a second assignment does.
      */
     set dataSource(value: string | undefined);
     /**
@@ -200,18 +202,23 @@ export declare class Graphty extends LitElement {
      */
     get dataSourceConfig(): Record<string, unknown> | undefined;
     /**
-     * Sets the data source configuration. Initializes data loading when combined with dataSource.
+     * Sets the data source configuration. Starts a load when combined with dataSource.
+     *
+     * Every assignment of the pair starts a load, and assigning both halves in one task starts
+     * one. Assigning the pair already loaded -- the same type and the same config object --
+     * starts none, unless that load failed; pass a new object to load again. The first load adds
+     * to the graph; each later one REPLACES it, but only once the new source has parsed -- a
+     * malformed or empty source leaves the graph as it was and reports `data-loading-error`.
+     * The pair assigned LAST wins: a slower earlier load that finishes afterwards is dropped.
+     * Every event about the load carries its `loadId`. A caller that wants to await the load
+     * calls `loadFromUrl`, `loadFromFile` or `addDataFromSource` instead.
      */
     set dataSourceConfig(value: Record<string, unknown> | undefined);
     /**
-     * Removes every node and edge, and lets a later data source load.
+     * Removes every node and edge, and forgets the data-source pair. A load still in flight is
+     * abandoned: it rejects with `E_SUPERSEDED` and adds nothing.
      *
-     * The guard below is per LOAD, not per element lifetime. Latching it for the
-     * element's whole life refused every dataset after the first: a second
-     * `dataSource` / `dataSourceConfig` assignment set both properties and started no
-     * load, so a host that loaded a second file saw the element report the new source
-     * while the old graph stayed on screen. Clearing the data is the statement that the
-     * previous load is over, so it is where the guard resets.
+     * The next pair assigned after it loads into an empty graph, as the first one did.
      *
      * The two properties are reset with it, and deliberately through the private fields
      * rather than the setters: a setter would call `#tryInitializeDataSource` again, and
@@ -1043,16 +1050,27 @@ export declare class Graphty extends LitElement {
     }[], options?: import("./utils/queue-migration").QueueableOptions): Promise<void>;
     /**
      * Add data from a data source.
+     *
+     * Every load has an id: the promise resolves to it, and every load event about this load
+     * (`data-loading-progress`, `data-loading-complete`, `data-loading-error`, `data-loaded`)
+     * carries it as `loadId`. A source with no nodes and no edges rejects with `E_EMPTY_LOAD`.
      * @param type - Data source type (e.g., "json", "csv", "graphml")
      * @param opts - Data source configuration options
-     * @returns Promise that resolves when data is loaded
+     * @param options - How to load
+     * @param options.replace - Replace the graph with this data, but only once it has all parsed:
+     *     a malformed or empty source rejects and leaves the current graph untouched
+     * @returns Promise that resolves to `{ loadId }` when data is loaded
      * @since 1.5.0
      * @example
      * ```typescript
-     * await element.addDataFromSource('json', { url: 'https://example.com/data.json' });
+     * const { loadId } = await element.addDataFromSource('json', { url: 'https://example.com/data.json' });
      * ```
      */
-    addDataFromSource(type: string, opts?: object): Promise<void>;
+    addDataFromSource(type: string, opts?: object, options?: {
+        replace?: boolean;
+    }): Promise<{
+        loadId: number;
+    }>;
     /**
      * Load graph data from a URL.
      * @param url - URL to fetch graph data from
@@ -1062,7 +1080,9 @@ export declare class Graphty extends LitElement {
      * @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
-     * @returns Promise that resolves when data is loaded
+     * @param options.replace - Replace the graph with this data, but only once it has all parsed:
+     *     a malformed or empty file rejects and leaves the current graph untouched
+     * @returns Promise that resolves to `{ loadId }`, the id every event about this load carries
      * @since 1.5.0
      * @example
      * ```typescript
@@ -1074,7 +1094,10 @@ export declare class Graphty extends LitElement {
         nodeIdPath?: string;
         edgeSource?: string;
         edgeTarget?: string;
-    }): Promise<void>;
+        replace?: boolean;
+    }): Promise<{
+        loadId: number;
+    }>;
     /**
      * Load graph data from a File object.
      * @param file - File object from file input
@@ -1084,7 +1107,9 @@ export declare class Graphty extends LitElement {
      * @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
-     * @returns Promise that resolves when data is loaded
+     * @param options.replace - Replace the graph with this data, but only once it has all parsed:
+     *     a malformed or empty file rejects and leaves the current graph untouched
+     * @returns Promise that resolves to `{ loadId }`, the id every event about this load carries
      * @since 1.5.0
      * @example
      * ```typescript
@@ -1098,7 +1123,10 @@ export declare class Graphty extends LitElement {
         nodeIdPath?: string;
         edgeSource?: string;
         edgeTarget?: string;
-    }): Promise<void>;
+        replace?: boolean;
+    }): Promise<{
+        loadId: number;
+    }>;
     /**
      * Pin nodes where they are, so no layout moves them again.
      *
@@ -1279,6 +1307,10 @@ export declare class Graphty extends LitElement {
      * result shape derives. This is the verb for a run started with `{ style: false }`, or for
      * putting a picture back after a reader cleared it. Applying twice replaces the layer bound
      * to that run and channel rather than stacking a second one on it.
+     *
+     * It starts the style edits and returns at once. To wait for the picture -- for a
+     * screenshot, an export or a test -- await `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 if anything was applied, false when no finished run of that algorithm has
@@ -1288,6 +1320,7 @@ export declare class Graphty extends LitElement {
      * ```typescript
      * await element.run('degree', undefined, { style: false });
      * element.applySuggestedStyles('degree');
+     * await element.waitForStableFrame();
      * ```
      */
     applySuggestedStyles(algorithmKey: string | string[]): boolean;
@@ -1307,7 +1340,10 @@ export declare class Graphty extends LitElement {
     getSuggestedStyles(algorithmKey: string): readonly import("./session/styles").StyleSuggestion[];
     /**
      * Set the layout algorithm.
-     * @param type - Layout algorithm name
+     *
+     * Takes a layout id from `catalog.layouts()` (such as `"force"`), which runs that layout's
+     * default engine, or a registered engine name (such as `"ngraph"`).
+     * @param type - Layout id or engine name
      * @param opts - Layout-specific options
      * @param options - Queue options
      * @returns Promise that resolves when layout is initialized
@@ -1315,6 +1351,7 @@ export declare class Graphty extends LitElement {
      * @example
      * ```typescript
      * await element.setLayout('circular', { radius: 5 });
+     * await element.setLayout('force'); // the catalogue id; runs the "ngraph" engine
      * await element.setLayout('ngraph', { springLength: 100 });
      * ```
      */
@@ -1546,9 +1583,11 @@ export declare class Graphty extends LitElement {
      * camera, picking and styling stay live. There is no event for this: `isRunning()` reports
      * the state and `graph-settled` reports the arrangement coming to rest.
      *
-     * A pause is not a mode the element remembers: anything that (re)starts a layout -- loading
-     * more nodes, an accelerator attaching, setting another layout, dropping a dragged node --
-     * runs it again, so pause it after those, not before.
+     * A pause holds until `setRunning(true)`. Loading more nodes, a freeze, an accelerator
+     * attaching, setting another layout and dragging a node all still happen -- new nodes are
+     * placed and a dragged node moves -- but none of them resumes the layout. To tell a paused,
+     * half-finished arrangement from a converged one, read `getLayoutManager().isPaused` and
+     * `isSettled`.
      * @param running - True to run the layout, false to pause it.
      * @since 2.0.0
      * @example
@@ -1910,9 +1949,10 @@ export declare class Graphty extends LitElement {
      * The node count at or above which accelerated work uses the accelerator.
      *
      * Below it the element takes the CPU path even with an accelerator attached, and
-     * `capabilities.acceleration.state` reads `"idle"`. Default 0: use the accelerator whenever
-     * there is one. Raise it when the graphs you show are small enough that uploading costs more
-     * than computing; the number is machine-specific, which is why the element does not guess.
+     * `capabilities.acceleration.state` reads `"idle"`. Unset, layouts use the accelerator
+     * whenever there is one and each algorithm keeps a built-in floor measured on one card (see
+     * the acceleration guide). Any value you set, including 0, replaces those floors for every
+     * layout and algorithm; set it when you have measured the machine your graphs are drawn on.
      * @since 2.0.0
      * @example
      * ```html

package/dist/src/layout/GridLayoutEngine.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod/v4";
+import { type OptionsSchema } from "../config";
+import { SimpleLayoutEngine } from "./LayoutEngine";
+declare const GridLayoutConfig: z.ZodObject<{
+    columns: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    scale: z.ZodDefault<z.ZodNumber>;
+    center: z.ZodDefault<z.ZodUnion<[z.ZodArray<z.ZodNumber>, z.ZodNull]>>;
+    scalingFactor: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+type GridLayoutConfigType = z.infer<typeof GridLayoutConfig>;
+type GridLayoutOpts = Partial<GridLayoutConfigType>;
+/**
+ * Grid layout engine that places nodes in rows and columns on an evenly spaced lattice
+ */
+export declare class GridLayout extends SimpleLayoutEngine {
+    static type: string;
+    static maxDimensions: number;
+    static zodOptionsSchema: OptionsSchema;
+    scalingFactor: number;
+    config: GridLayoutConfigType;
+    /**
+     * Create a grid layout engine
+     * @param opts - Configuration options including the column count
+     */
+    constructor(opts: GridLayoutOpts);
+    /**
+     * Get dimension-specific options for grid layout
+     * @param dimension - The desired dimension (2 or 3)
+     * @returns Empty object for 2D, null for 3D (unsupported)
+     */
+    static getOptionsForDimension(dimension: 2 | 3): object | null;
+    /**
+     * Compute node positions on the lattice
+     */
+    doLayout(): void;
+}
+export {};

package/dist/src/layout/LayoutEngine.d.ts

@@ -48,15 +48,15 @@ export interface LayoutEngineStatics {
     /**
      * Whether this engine arranges a graph differently when its edges carry weights.
      *
-     * Optional, and false for all but two of the element's own seventeen. It exists so that a
+     * Optional, and false for all but two of the element's own nineteen. It exists so that a
      * picker can tell a reader which arrangements the `weighted` option actually does something
-     * for, instead of offering it on fifteen layouts that ignore it.
+     * for, instead of offering it on seventeen layouts that ignore it.
      */
     honoursWeights?: boolean;
     /**
      * What the catalogue publishes about this layout, so a picker can offer it.
      *
-     * REQUIRED OF A THIRD PARTY'S ENGINE and absent from the element's own seventeen, whose
+     * REQUIRED OF A THIRD PARTY'S ENGINE and absent from the element's own nineteen, whose
      * arrangements are authored in `src/catalog/layouts.ts` instead. `descriptor.id` must equal
      * {@link LayoutEngineStatics.type}: one key, so nothing is named twice and `layoutIdForEngine`
      * can answer a plugin's own id.
@@ -94,7 +94,7 @@ export declare abstract class LayoutEngine {
      * Whether this engine reads edge weights. See {@link LayoutEngineStatics.honoursWeights}.
      *
      * False here because most layouts have no weight channel at all: of the element's own
-     * seventeen, only Kamada-Kawai and ForceAtlas2 can read one, and the other fifteen would be
+     * nineteen, only Kamada-Kawai and ForceAtlas2 can read one, and the other seventeen would be
      * advertising a control that changes nothing.
      */
     static honoursWeights: boolean;
@@ -162,7 +162,7 @@ export declare abstract class LayoutEngine {
      * Take a node out of the layout, before the element disposes the mesh that drew it.
      *
      * Declared here, with a default that does nothing, because it used to be duck-typed by the
-     * element's data manager and implemented by none of the seventeen engines that ship here: an
+     * element's data manager and implemented by none of the nineteen engines that ship here: an
      * author learned it existed by reading the element's source, and got no worked example. An
      * engine that keeps its own node list must override this, or it holds every removed node --
      * and everything that node references -- for as long as the engine lives.
@@ -260,7 +260,7 @@ export declare abstract class LayoutEngine {
      * freeze counts as placed, which is what makes a file's own coordinates yield to it.
      *
      * A PINNED ROW REFUSES A LAYOUT STEP. This is the whole of "a pin is meaningful under every
-     * arrangement": twelve of the element's seventeen engines implement `pin()` as a no-op and
+     * arrangement": fourteen of the element's nineteen engines implement `pin()` as a no-op and
      * `setNodePosition` as a no-op too, so before this guard a reader who dragged a node under a
      * static layout watched it snap back the next time the layout recomputed. One refusal here
      * covers every engine, including one written by a third party that has never heard of pinning,
@@ -351,7 +351,7 @@ export declare abstract class LayoutEngine {
      * offered by a picker, described in a reader's language, or found by `layoutIdForEngine`.
      *
      * A third party's class must declare a `static descriptor` whose `id` equals its
-     * `static type`. The element's own seventeen are the one exemption, because their arrangements
+     * `static type`. The element's own nineteen are the one exemption, because their arrangements
      * are authored centrally in the layout catalogue where several engines may sit behind one
      * public name.
      * @param cls - The layout engine class.

package/dist/src/layout/NGraphLayoutEngine.d.ts

@@ -24,6 +24,8 @@ export declare class NGraphEngine extends LayoutEngine {
     _settled: boolean;
     _stepCount: number;
     _lastMoves: number[];
+    /** Places each new node when `seed` is set; null leaves placement to ngraph. */
+    private seededPlacement;
     /**
      * Create an NGraph layout engine
      * @param config - Configuration options for the NGraph simulation

package/dist/src/layout/RadialLayoutEngine.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod/v4";
+import { type OptionsSchema } from "../config";
+import { SimpleLayoutEngine } from "./LayoutEngine";
+declare const RadialLayoutConfig: z.ZodObject<{
+    root: z.ZodDefault<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    scale: z.ZodDefault<z.ZodNumber>;
+    center: z.ZodDefault<z.ZodUnion<[z.ZodArray<z.ZodNumber>, z.ZodNull]>>;
+    scalingFactor: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+type RadialLayoutConfigType = z.infer<typeof RadialLayoutConfig>;
+type RadialLayoutOpts = Partial<RadialLayoutConfigType>;
+/**
+ * Radial layout engine that places nodes on rings by hop distance from a root node
+ */
+export declare class RadialLayout extends SimpleLayoutEngine {
+    static type: string;
+    static maxDimensions: number;
+    static zodOptionsSchema: OptionsSchema;
+    scalingFactor: number;
+    config: RadialLayoutConfigType;
+    /**
+     * Create a radial layout engine
+     * @param opts - Configuration options including the root node
+     */
+    constructor(opts: RadialLayoutOpts);
+    /**
+     * Get dimension-specific options for radial layout
+     * @param dimension - The desired dimension (2 or 3)
+     * @returns Empty object for 2D, null for 3D (unsupported)
+     */
+    static getOptionsForDimension(dimension: 2 | 3): object | null;
+    /**
+     * Compute node positions on rings around the root
+     */
+    doLayout(): void;
+}
+export {};

package/dist/src/layout/SimulationLayoutEngine.d.ts

@@ -323,6 +323,18 @@ export declare class SimulationLayoutEngine extends LayoutEngine {
      * @returns A promise that resolves when the batch has landed, or rejects with its failure.
      */
     stepAsync(iterations: number): Promise<void>;
+    /**
+     * Whether the manager has stopped stepping this layout -- a consumer's pause, or any other
+     * stop. A paused layout's work span closes once its in-flight batches land, because nothing
+     * is being submitted after them.
+     * @returns True while the layout is not being stepped.
+     */
+    get paused(): boolean;
+    /**
+     * Tells the bridge whether the manager is stepping it.
+     * @param value - True when the manager has stopped stepping this layout.
+     */
+    set paused(value: boolean);
     /**
      * Starts the settle count again, on a simulation that has one.
      *

package/dist/src/managers/DataManager.d.ts

@@ -112,6 +112,12 @@ export declare class DataManager implements Manager {
     private loadEndpoints;
     /** The tally the load in progress is counting into, or null outside a load. */
     private loadTally;
+    /**
+     * Bumped by every REPLACING load as it is asked for, and by `supersedeLoads`. A load that
+     * sees it move has been overtaken, and stops with `E_SUPERSEDED` rather than touching the
+     * graph: see `addDataFromSource`.
+     */
+    private replaceGeneration;
     /**
      * Creates an instance of DataManager
      * @param eventManager - Event manager for emitting data events
@@ -273,6 +279,22 @@ export declare class DataManager implements Manager {
      * @param idPath - JMESPath expression to extract node ID from data
      */
     addNode(node: AdHocData, idPath?: string): void;
+    /**
+     * The id `addNodes` reads off a node record.
+     * @param node - the record
+     * @param idPath - JMESPath expression to extract the id; the configured node id path when unset
+     * @returns the node's id
+     */
+    nodeIdOf(node: Record<string | number, unknown>, idPath?: string): NodeIdType;
+    /**
+     * Refuse a replacing node set the renderer cannot hold, before the replace removes anything.
+     *
+     * The node half of what {@link setEdges} decides first: the new set is counted against an
+     * emptied graph, so a refused replace keeps the nodes the graph had.
+     * @param count - how many distinct nodes the graph would hold afterwards
+     * @throws A `GraphtyError` with `E_TOO_LARGE` when `count` is past the ceiling
+     */
+    refuseNodeSetAboveCeiling(count: number): void;
     /**
      * Adds multiple nodes to the graph
      * @param nodes - Array of node data objects
@@ -472,12 +494,57 @@ export declare class DataManager implements Manager {
      *     while the source has still declared nothing
      */
     private applyDeclaredDirection;
+    /**
+     * Reserve a load's place in line, at the moment the caller asked for it.
+     *
+     * A caller that reads a file or sniffs a URL before it loads calls this FIRST, so a load that
+     * was asked for later still wins however long the earlier one spends reading. A replacing load
+     * supersedes every load reserved before it.
+     * @param replace - Whether the load will replace the graph
+     * @returns The generation to hand to `addDataFromSource` and `throwIfSuperseded`
+     */
+    beginLoad(replace: boolean): number;
+    /**
+     * Abandon every load in flight: each rejects with `E_SUPERSEDED` and adds nothing more.
+     * The element's `clearData` calls this, so a load finishing after the graph was closed does
+     * not bring its data back.
+     */
+    supersedeLoads(): void;
+    /**
+     * Throw `E_SUPERSEDED` when a load reserved at `generation` has been overtaken.
+     * @param generation - What `beginLoad` returned for the load
+     * @param type - The load's format, for the message
+     */
+    throwIfSuperseded(generation: number, type: string): void;
     /**
      * Loads data from a registered data source
+     *
+     * A REPLACING load reads the whole source into memory before it touches the store, and only
+     * once the source has finished without an error does it clear the graph and add what it read.
+     * A malformed or empty file therefore leaves the graph it would have replaced exactly as it
+     * was. An additive load streams each chunk straight in, as it always has.
+     *
+     * A load that reads no node records and no edge records at all fails with `E_EMPTY_LOAD`
+     * rather than completing with zero counts. A file of edges alone is not empty: its endpoints
+     * become nodes.
+     *
+     * The load that STARTED last wins. Once a replacing load has started, every load started
+     * before it -- replacing or additive -- is superseded: it adds nothing more and rejects with
+     * `E_SUPERSEDED`, whichever order the sources finish in. A superseded load emits no
+     * `data-loading-error`, because nothing went wrong with its source.
      * @param type - Data source type identifier
      * @param opts - Options to pass to the data source
-     */
-    addDataFromSource(type: string, opts?: object): Promise<void>;
+     * @param load - Which load this is, for every event it emits, and whether it replaces the graph
+     * @param load.loadId - The id every event about this load carries
+     * @param load.replace - Swap the graph for what the source holds, once it has all parsed
+     * @param load.generation - The place `beginLoad` reserved for this load when the caller's call
+     *     was made; left unset, the load takes its place now
+     */
+    addDataFromSource(type: string, opts?: object, load?: {
+        loadId?: number;
+        replace?: boolean;
+        generation?: number;
+    }): Promise<void>;
     /**
      * Freeze one load's counters into the report a consumer reads, and keep it for `lastImport`.
      * @param format - the data source that read the file

package/dist/src/managers/EventManager.d.ts

@@ -65,8 +65,9 @@ export declare class EventManager implements Manager {
      * @param chunksLoaded - Number of data chunks loaded
      * @param dataSourceType - Type of data source used
      * @param report - What the load did, including which endpoint spelling resolved
+     * @param loadId - Which load this is, when it is one
      */
-    emitGraphDataLoaded(graph: Graph | GraphContext, chunksLoaded: number, dataSourceType: string, report: ImportReport): void;
+    emitGraphDataLoaded(graph: Graph | GraphContext, chunksLoaded: number, dataSourceType: string, report: ImportReport, loadId?: number): void;
     /**
      * Emits the removal event naming every node and edge one removal call took away.
      * @param nodes - the nodes that were removed
@@ -122,8 +123,9 @@ export declare class EventManager implements Manager {
      * @param nodeRecordsLoaded - How many node RECORDS the source has handed over so far
      * @param edgeRecordsLoaded - How many edge RECORDS the source has handed over so far
      * @param chunksProcessed - Number of data chunks processed
+     * @param loadId - Which load this is, when it is one
      */
-    emitDataLoadingProgress(format: string, bytesProcessed: number, totalBytes: number | undefined, nodeRecordsLoaded: number, edgeRecordsLoaded: number, chunksProcessed: number): void;
+    emitDataLoadingProgress(format: string, bytesProcessed: number, totalBytes: number | undefined, nodeRecordsLoaded: number, edgeRecordsLoaded: number, chunksProcessed: number, loadId?: number): void;
     /**
      * Emits a data loading error event when an error occurs during import
      * @param error - Error object
@@ -134,12 +136,14 @@ export declare class EventManager implements Manager {
      * @param details.nodeId - Node ID related to error
      * @param details.edgeId - Edge ID related to error
      * @param details.canContinue - Whether loading can continue after this error
+     * @param details.loadId - Which load this is, when it is one
      */
     emitDataLoadingError(error: Error, context: DataLoadingErrorEvent["context"], format: string | undefined, details: {
         line?: number;
         nodeId?: unknown;
         edgeId?: string;
         canContinue: boolean;
+        loadId?: number;
     }): void;
     /**
      * Emits a summary of all data loading errors after import completes
@@ -149,8 +153,9 @@ export declare class EventManager implements Manager {
      * @param detailedReport - Detailed error report
      * @param primaryCategory - Primary error category
      * @param suggestion - Suggested fix for the errors
+     * @param loadId - Which load this is, when it is one
      */
-    emitDataLoadingErrorSummary(format: string, totalErrors: number, message: string, detailedReport: string, primaryCategory?: string, suggestion?: string): void;
+    emitDataLoadingErrorSummary(format: string, totalErrors: number, message: string, detailedReport: string, primaryCategory?: string, suggestion?: string, loadId?: number): void;
     /**
      * Emits a data loading complete event when import finishes
      * @param format - Data format that was loaded
@@ -161,8 +166,9 @@ export declare class EventManager implements Manager {
      * @param warnings - Number of warnings encountered
      * @param success - Whether loading was successful
      * @param report - What the load did, including which endpoint spelling resolved
+     * @param loadId - Which load this is, when it is one
      */
-    emitDataLoadingComplete(format: string, nodesLoaded: number, edgesLoaded: number, duration: number, errors: number, warnings: number, success: boolean, report: ImportReport): void;
+    emitDataLoadingComplete(format: string, nodesLoaded: number, edgesLoaded: number, duration: number, errors: number, warnings: number, success: boolean, report: ImportReport, loadId?: number): void;
     /**
      * Emits a selection changed event when node selection changes
      * @param previousNode - Previously selected node (or null)