@graphty/graphty-element 2.3.1 → 2.4.0

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

@@ -2,7 +2,7 @@
  * @file The layout catalogue: the arrangements the element offers, and the engines behind them.
  *
  * A public layout name says what the arrangement IS -- "force", "hierarchical", "circular" --
- * and never which library draws it. The element registers seventeen engines whose registered
+ * and never which library draws it. The element registers nineteen engines whose registered
  * names ARE their implementations ("ngraph", "d3", "forceatlas2"), and freezing those into the
  * public API makes swapping an implementation a rename every consumer can see. So the engine is
  * data on the descriptor instead: `LayoutDescriptor.engine` names the implementation the element
@@ -14,10 +14,11 @@
  * descriptor a consumer reads carries the default engine and that engine's options; the rest of
  * the list is there for a consumer that wants to choose.
  *
- * Two names in the built-in layout list have no engine behind them yet, and two engines describe
- * an arrangement that list has no name for. Both are recorded here -- {@link UNSERVED_LAYOUT_IDS}
- * and the `spiral` and `planar` entries -- rather than left for a consumer to discover by asking
- * for a layout that never answers, or by never learning a capability exists.
+ * A name in the built-in layout list with no engine behind it would be recorded in
+ * {@link UNSERVED_LAYOUT_IDS} (none is, today), and two engines describe an arrangement that list
+ * has no name for, which the `spiral` and `planar` entries record -- rather than left for a
+ * consumer to discover by asking for a layout that never answers, or by never learning a
+ * capability exists.
  *
  * `sizeRating` is the largest graph the default engine is recommended for, read from its cost: a
  * placement that visits each node once rates "any", an iterative all-pairs force rates 2000.
@@ -78,7 +79,7 @@ export declare const LAYOUT_DESCRIPTORS: readonly LayoutDescriptor[];
 /**
  * The built-in layout names no registered engine draws yet. Listed rather than omitted, because
  * a name that is in the type and missing from the catalogue is otherwise discovered by asking
- * for it and getting an error.
+ * for it and getting an error. Empty today: every built-in name has an engine.
  */
 export declare const UNSERVED_LAYOUT_IDS: readonly UnservedLayout[];
 /**

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

@@ -53,10 +53,29 @@ export type Query = string;
 /**
  * The built-in algorithms. The list is also available at runtime so a consumer can enumerate
  * the built-in set without a catalogue instance.
+ *
+ * Two of these names are deprecated: `all-paths` and `clustering-coefficient` are reserved but
+ * not implemented, and starting either fails with `E_UNSUPPORTED`. See
+ * {@link DEPRECATED_ALGORITHMS}.
  */
 export declare const KNOWN_ALGORITHMS: readonly ["degree", "betweenness", "closeness", "pagerank", "eigenvector", "katz", "hits", "louvain", "leiden", "label-propagation", "components", "shortest-path", "all-pairs-distance", "all-paths", "max-flow", "min-cut", "k-core", "clustering-coefficient", "girvan-newman", "bfs", "dfs", "kruskal", "prim", "bipartite-matching", "link-prediction"];
-/** One of the built-in algorithms. */
+/**
+ * One of the built-in algorithms. `all-paths` and `clustering-coefficient` are deprecated and do
+ * not run; see {@link DEPRECATED_ALGORITHMS}.
+ */
 export type KnownAlgorithm = (typeof KNOWN_ALGORITHMS)[number];
+/**
+ * The built-in algorithm names the element reserves but does not run.
+ *
+ * Nothing implements these two yet. The names stay in {@link KNOWN_ALGORITHMS}, so no plugin can
+ * claim them and no code that names them stops compiling, but starting one fails with
+ * `E_UNSUPPORTED` rather than `E_UNKNOWN_ALGORITHM`. Each is removed at the next major release
+ * unless it is implemented first: `all-paths` is tracked by issue #329 and
+ * `clustering-coefficient` by issue #330.
+ */
+export declare const DEPRECATED_ALGORITHMS: readonly ["all-paths", "clustering-coefficient"];
+/** A built-in algorithm name the element reserves but does not run, and will remove. */
+export type DeprecatedAlgorithm = (typeof DEPRECATED_ALGORITHMS)[number];
 /**
  * An algorithm key. The built-in names keep autocomplete alive; the string arm accepts a
  * plugin's name.
@@ -446,13 +465,23 @@ export interface ScaleDescriptor {
     domainKind: "numeric" | "categorical" | "boolean";
     options: readonly OptionDescriptor[];
 }
-/** One named style document, offered as a whole look. */
+/**
+ * One named style document, offered as a whole look.
+ *
+ * Nothing produces one yet: it is returned only by the deprecated `CatalogApi.themes()`, and goes
+ * with it at the next major release unless that is implemented first (issue #331).
+ */
 export interface ThemeDescriptor {
     name: string;
     plainName: string;
     document: StyleDocument;
 }
-/** One function the expression grammar accepts. */
+/**
+ * One function the expression grammar accepts.
+ *
+ * Nothing produces one yet: it is returned only by the deprecated `CatalogApi.functions()`, and
+ * goes with it at the next major release unless that is implemented first (issue #332).
+ */
 export interface FunctionDescriptor {
     name: string;
     /** The smallest and largest argument count accepted. */
@@ -524,7 +553,12 @@ export type Scope = "visible" | "graph" | "selection" | "largest-component" | {
 } | {
     nodes: readonly NodeId[];
 };
-/** The catalogue: everything the element can offer, as data. */
+/**
+ * The catalogue: everything the element can offer, as data.
+ *
+ * `session.catalog` implements every method here except the six named in
+ * {@link DeprecatedCatalogMethod}, which nothing implements yet.
+ */
 export interface CatalogApi {
     algorithms(): readonly AlgorithmDescriptor[];
     layouts(): readonly LayoutDescriptor[];
@@ -533,24 +567,61 @@ export interface CatalogApi {
     cameras(): readonly CameraDescriptor[];
     logSinks(): readonly LogSinkDescriptor[];
     scales(): readonly ScaleDescriptor[];
+    /**
+     * @deprecated Not implemented. Removed at the next major release unless it is implemented
+     * first (issue #331).
+     */
     themes(): readonly ThemeDescriptor[];
+    /**
+     * @deprecated Not implemented. Removed at the next major release unless it is implemented
+     * first (issue #332).
+     */
     functions(): readonly FunctionDescriptor[];
+    /**
+     * @deprecated Not implemented. Removed at the next major release unless it is implemented
+     * first (issue #333).
+     */
     timeAttributes(): readonly AttributeDescriptor[];
     metrics(): readonly MetricAvailability[];
-    /** The metrics that can run on this graph. A runtime query, not a static list. */
+    /**
+     * The metrics that can run on this graph. A runtime query, not a static list.
+     * @deprecated Not implemented; `metrics()` carries `available` and `reason` for the same
+     * question. Removed at the next major release unless it is implemented first (issue #334).
+     */
     applicable(): readonly MetricAvailability[];
+    /**
+     * @deprecated Not implemented. Removed at the next major release unless it is implemented
+     * first (issue #335).
+     */
     validate(query: Query, o?: {
         kind?: "selector" | "filter" | "formula";
     }): QueryValidation;
-    /** The options for one algorithm or layout, with data-dependent bounds resolved. */
+    /**
+     * The options for one algorithm or layout, with data-dependent bounds resolved.
+     * @deprecated Not implemented; `algorithms()` and `layouts()` carry the static option
+     * descriptors. Removed at the next major release unless it is implemented first (issue #336).
+     */
     optionsFor(key: AlgorithmKey | LayoutId, scope?: Scope): Promise<readonly OptionDescriptor[]>;
 }
+/**
+ * The {@link CatalogApi} methods nothing implements yet, which `session.catalog` leaves out.
+ *
+ * Implementing one means deleting its name here: `SessionCatalogApi` is derived from this list,
+ * so the two cannot drift apart.
+ */
+export type DeprecatedCatalogMethod = "themes" | "functions" | "timeAttributes" | "applicable" | "validate" | "optionsFor";
 /**
  * Tell whether a value is one of the option types.
  * @param value - The value to test.
  * @returns True when the value is a member of OPTION_TYPES.
  */
 export declare function isOptionType(value: unknown): value is OptionType;
+/**
+ * Tell whether an algorithm key names a built-in the element reserves but does not run.
+ * @param key - The algorithm key.
+ * @returns True when the key is a member of DEPRECATED_ALGORITHMS.
+ */
+export declare function isDeprecatedAlgorithm(key: string): key is DeprecatedAlgorithm;
 /**
  * Tell whether a value is one of the cost classes.
  * @param value - The value to test.

package/dist/src/config/EdgeStyle.d.ts

@@ -1,4 +1,39 @@
 import { z } from "zod/v4";
+/**
+ * Every arrow the edge renderer can draw at the head or tail of an edge, in schema order.
+ * Read `EdgeArrowTypes.options` for the list, e.g. to build a picker.
+ */
+export declare const EdgeArrowTypes: z.ZodEnum<{
+    none: "none";
+    dot: "dot";
+    normal: "normal";
+    inverted: "inverted";
+    "sphere-dot": "sphere-dot";
+    "open-dot": "open-dot";
+    tee: "tee";
+    "open-normal": "open-normal";
+    diamond: "diamond";
+    "open-diamond": "open-diamond";
+    crow: "crow";
+    box: "box";
+    "half-open": "half-open";
+    vee: "vee";
+}>;
+/**
+ * Every line pattern the edge renderer can draw, in schema order.
+ * Read `EdgeLineTypes.options` for the list, e.g. to build a picker.
+ */
+export declare const EdgeLineTypes: z.ZodEnum<{
+    solid: "solid";
+    dot: "dot";
+    diamond: "diamond";
+    box: "box";
+    star: "star";
+    dash: "dash";
+    "dash-dot": "dash-dot";
+    sinewave: "sinewave";
+    zigzag: "zigzag";
+}>;
 /**
  * Everything a style layer can say about how one edge is drawn.
  *

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

@@ -1,7 +1,7 @@
 export type { AdHocData, ImageData } from "./common";
 export { colorToHex } from "./common";
 export type { EdgeStyleConfig } from "./EdgeStyle";
-export { defaultEdgeStyle, EdgeStyle } from "./EdgeStyle";
+export { defaultEdgeStyle, EdgeArrowTypes, EdgeLineTypes, EdgeStyle } from "./EdgeStyle";
 export type { FetchEdgesFn, FetchNodesFn, GraphBehaviorConfig } from "./GraphBehavior";
 export type { NodeIdType } from "./GraphBehavior";
 export { GraphBehaviorOpts } from "./GraphBehavior";

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

@@ -185,6 +185,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