@graphty/graphty-element 2.6.2 → 3.0.1

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

@@ -94,6 +94,7 @@ export declare class ElementPositions {
      */
     private pins;
     private rows;
+    private moves;
     /**
      * Allocate the backing array, every row unplaced and unpinned.
      * @param capacity - rows to reserve before the first growth; a non-negative integer
@@ -104,6 +105,18 @@ export declare class ElementPositions {
      * @returns the current capacity in rows
      */
     get capacity(): number;
+    /**
+     * Moves whenever coordinates are written on purpose: by {@link ElementPositions.write}, which
+     * every layout, drag and placement goes through, and by {@link ElementPositions.moved}, which a
+     * writer that fills the array {@link ElementPositions.view} lends (a GPU readback, a restore)
+     * calls once per batch. Seeding a new row and renumbering rows do not move it: those follow
+     * the graph, not the arrangement. The undo history compares it with the generation of its
+     * last capture to tell whether the lane has moved since (design/undo/undo-design.md 6.4).
+     * @returns the generation
+     */
+    get generation(): number;
+    /** Say that coordinates were written straight into the lent array. */
+    moved(): void;
     /**
      * Rows currently in use. Equals the last snapshot's nodeCount.
      * @returns the live row count

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

@@ -0,0 +1,16 @@
+/**
+ * The file-unit coordinate a record carries, in the two shapes the element's own data has always
+ * used, or null when it carries none.
+ *
+ * `{ x, y, z? }` is what `FixedLayoutEngine` reads off `node.data` today
+ * (`src/layout/FixedLayoutEngine.ts`), and `[x, y]` / `[x, y, z]` is the array form the importers
+ * produce. A missing z is 0, not NaN: a 2D record IS placed, on the z = 0 plane, and NaN is
+ * reserved for "no layout has run".
+ *
+ * Anything non-finite makes the WHOLE record unseeded rather than partly seeded. A row stored with
+ * one NaN component reports itself PLACED (`ElementPositions.isPlaced` tests x), so a layout would
+ * never repair it and the mesh would vanish; left unseeded, the node is laid out like any other.
+ * @param record - the raw node record
+ * @returns the file-unit triple, or null when there is nothing usable to seed
+ */
+export declare function readSeedPosition(record: Record<string | number, unknown>): [number, number, number] | null;

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

@@ -12,7 +12,9 @@ import { type GraphtyErrorCode } from "./codes";
  * It answers "who was doing this" without the consumer parsing a message, and it is what an
  * error panel groups on.
  */
-export type GraphtyErrorSource = "data" | "run" | "layout" | "style" | "view" | "acceleration" | "registry" | "config";
+export type GraphtyErrorSource = "data" | "run" | "layout" | "style" | "view" | "acceleration" | "registry" | "config"
+/** Undo, redo, transactions and the one path every change to project state takes. */
+ | "history";
 /**
  * The thing a failure belongs to, when it belongs to a thing rather than to the session.
  *

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

@@ -308,6 +308,29 @@ export type GraphtyErrorCode =
  * was disposed. The caller creates a new session; nothing about the disposed one recovers.
  */
  | "E_DISPOSED"
+/**
+ * An extension's own code threw: a function in a simple-tier definition (an algorithm's
+ * `node`, a layout's `place`), called by the element. `details.extension` is the extension's
+ * id, `details.member` the function, and `cause` the original error. The extension's author
+ * fixes their code; this is not a defect in graphty-element, which is what `E_INTERNAL` means.
+ */
+ | "E_EXTENSION_FAILED"
+/**
+ * A command was dispatched through a transaction's `tx` after the transaction's callback had
+ * settled, so the step it belonged to was already recorded. `details.transaction` names the
+ * transaction. The caller dispatches everything the transaction should contain before its
+ * callback returns (awaiting what it needs), or dispatches later work through the session as
+ * its own step.
+ */
+ | "E_TRANSACTION_CLOSED"
+/**
+ * A command needs a node or edge id (or a whole graph or pin slice) that an open transaction
+ * has written and holds until it is recorded. It fails at once rather than waiting, because
+ * the transaction's callback may itself be waiting on this command. `details.transaction`
+ * names the transaction and `details.key` the held key. The caller dispatches the command
+ * through that transaction's `tx`, or dispatches it again once the transaction has settled.
+ */
+ | "E_HELD_BY_TRANSACTION"
 /**
  * An invariant inside the element broke. This is a bug in graphty-element, not in the call.
  * `details` and `cause` carry whatever is safe to report. The caller files an issue with the

package/dist/src/events.d.ts

@@ -8,6 +8,7 @@ import type { Edge } from "./Edge";
 import type { Graph } from "./Graph";
 import type { Node } from "./Node";
 import type { StyleChange } from "./session/styles/StylesApi";
+import type { HistoryCause } from "./session/types";
 export type EventType = GraphEventType | NodeEventType | EdgeEventType | AiEventType;
 export type EventCallbackType = (evt: GraphEvent | NodeEvent | EdgeEvent | AiEvent) => void;
 type AnyEvent = GraphEvent | NodeEvent | EdgeEvent | AiEvent;
@@ -71,6 +72,8 @@ export interface GraphDataLoadedEvent {
          */
         loadId?: number;
     };
+    /** What loaded it; absent for a load that does not yet come through the session's history. */
+    cause?: HistoryCause;
 }
 export interface GraphDataAddedEvent {
     type: "data-added";
@@ -78,6 +81,13 @@ export interface GraphDataAddedEvent {
     count: number;
     shouldStartLayout: boolean;
     shouldZoomToFit: boolean;
+    /**
+     * What added the rows: a command, or undo, redo or a rollback bringing them back. Absent for a
+     * load that does not yet come through the session's history (a data source, a file, a URL).
+     * The element starts a layout, frames the camera and runs the on-load algorithms only for
+     * rows a command or such a load added, never for rows undo or redo brought back.
+     */
+    cause?: HistoryCause;
 }
 /**
  * Emitted by DataManager after every freeze, once the element's position column is attached to the
@@ -281,6 +291,8 @@ export interface ElementsRemovedEvent {
     nodes: NodeId[];
     /** Every edge that was attached to one of them, and therefore went with it. */
     edges: EdgeId[];
+    /** What removed them; absent for a removal that does not yet come through the history. */
+    cause?: HistoryCause;
 }
 export interface SelectionChangedEvent {
     type: "selection-changed";

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

@@ -10,6 +10,8 @@ import type { ScreenshotOptions, ScreenshotResult } from "./screenshot/types.js"
 import type { GraphSession } from "./session";
 import type { Run, StartOptions } from "./session/runs";
 import type { SelectionDelta, SelectionOp, SelectionTarget } from "./session/selection";
+import type { DefaultPalettes } from "./session/styles";
+import type { TransactionScope } from "./session/types";
 /**
  * Graphty creates a graph
  */
@@ -97,6 +99,28 @@ export declare class Graphty extends LitElement {
      * ```
      */
     select(target: SelectionTarget, op?: SelectionOp): Promise<SelectionDelta>;
+    /**
+     * Choose the palette a colour binding uses when it names none, one per palette kind.
+     *
+     * Forwarded from `session.styles.setDefaultPalettes`. A default is resolved when a style
+     * layer is written, so a saved document always names a concrete palette: call it before
+     * loading data or adding layers. A later call warns and names the layers that keep the
+     * previous default, or with `reapply: true` repaints them with the new one.
+     * @param palettes - A palette id per kind: `categorical`, `sequential` and `diverging`.
+     * @param options - How a late call treats the layers already written.
+     * @param options.reapply - True re-resolves the layers that took the previous default.
+     * @since 2.7.0
+     * @example
+     * ```ts
+     * import { definePalette } from "@graphty/graphty-element/extend";
+     *
+     * definePalette({ id: "acme-brand", kind: "categorical", colors: ["#0B1D51", "#1B7F79"] });
+     * element.setDefaultPalettes({ categorical: "acme-brand" });
+     * ```
+     */
+    setDefaultPalettes(palettes: DefaultPalettes, options?: {
+        readonly reapply?: boolean;
+    }): void;
     /**
      * Called when the element is added to the DOM. Sets up the graph container and resize observer.
      */
@@ -149,7 +173,8 @@ export declare class Graphty extends LitElement {
      */
     get nodeData(): Record<string, unknown>[] | undefined;
     /**
-     * Sets the node data array. Replaces the graph's nodes with these.
+     * Replaces the graph's nodes with these, as one undoable step: a node the array names again
+     * keeps its row and its edges, and one it no longer names goes, with its edges.
      */
     set nodeData(value: Record<string, unknown>[] | undefined);
     /**
@@ -181,7 +206,7 @@ export declare class Graphty extends LitElement {
      */
     get edgeData(): Record<string, unknown>[] | undefined;
     /**
-     * Sets the edge data array. Triggers addition of edges to the graph.
+     * Replaces the graph's edges with these, as one undoable step.
      */
     set edgeData(value: Record<string, unknown>[] | undefined);
     /**
@@ -191,8 +216,8 @@ export declare class Graphty extends LitElement {
      */
     get dataSource(): string | undefined;
     /**
-     * Sets the data source type. Starts a load when combined with dataSourceConfig; see
-     * `dataSourceConfig` for what a second assignment does.
+     * Sets the data source type. Loads the graph from it, replacing what the graph held, once the
+     * configuration is set too.
      */
     set dataSource(value: string | undefined);
     /**
@@ -202,35 +227,21 @@ export declare class Graphty extends LitElement {
      */
     get dataSourceConfig(): Record<string, unknown> | undefined;
     /**
-     * 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.
+     * Sets the data source configuration. Loads the graph from it, replacing what the graph
+     * held, once the type is set too.
      */
     set dataSourceConfig(value: Record<string, unknown> | undefined);
     /**
-     * Removes every node and edge, and forgets the data-source pair. A load still in flight is
+     * Removes every node and edge, as one undoable step. The data source goes with them, so the
+     * next `dataSource` / `dataSourceConfig` assignment loads afresh. A load still in flight is
      * abandoned: it rejects with `E_SUPERSEDED` and adds nothing.
-     *
-     * 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
-     * leaving the old pair in place would let the next half-assignment load the NEW
-     * source against the OLD config.
      */
     clearData(): void;
     /**
      * A jmespath string that can be used to select the unique node identifier
      * for each node. Defaults to "id", as in `{id: 42}` is the identifier of
      * the node.
-     * @returns JMESPath string or undefined if not set
+     * @returns The value set on this element, else the value in effect (undefined when that is none)
      */
     get nodeIdPath(): string | undefined;
     /**
@@ -245,7 +256,7 @@ export declare class Graphty extends LitElement {
      * then `from`/`to`, deciding once per batch of edge records. Setting this settles the question
      * and turns the probe off, and a record that does not answer it is then a rejected record
      * rather than a reason to guess again.
-     * @returns JMESPath string or undefined if not set
+     * @returns The value set on this element, else the value in effect (undefined when that is none)
      */
     get edgeSrcIdPath(): string | undefined;
     /**
@@ -257,7 +268,7 @@ export declare class Graphty extends LitElement {
      * jmespath that describes where to find the destination node identifier for this edge.
      *
      * Unset by default, which means PROBE; see {@link edgeSrcIdPath}.
-     * @returns JMESPath string or undefined if not set
+     * @returns The value set on this element, else the value in effect (undefined when that is none)
      */
     get edgeDstIdPath(): string | undefined;
     /**
@@ -279,7 +290,7 @@ export declare class Graphty extends LitElement {
      * ```html
      * <graphty-element edge-id-path="edgeId"></graphty-element>
      * ```
-     * @returns JMESPath string or undefined if not set
+     * @returns The value set on this element, else the value in effect (undefined when that is none)
      */
     get edgeIdPath(): string | undefined;
     /**
@@ -302,7 +313,7 @@ export declare class Graphty extends LitElement {
      * ```html
      * <graphty-element repeated-edges="sum"></graphty-element>
      * ```
-     * @returns The policy, or undefined when none has been set on this element
+     * @returns The value set on this element, else the value in effect (undefined when that is none)
      */
     get repeatedEdges(): DuplicatePolicy | undefined;
     /**
@@ -320,7 +331,7 @@ export declare class Graphty extends LitElement {
      * ```html
      * <graphty-element node-label-path="name"></graphty-element>
      * ```
-     * @returns JMESPath string or undefined if not set
+     * @returns The value set on this element, else the value in effect (undefined when that is none)
      */
     get nodeLabelPath(): string | undefined;
     /**
@@ -338,7 +349,7 @@ export declare class Graphty extends LitElement {
      * ```html
      * <graphty-element edge-weight-path="cost"></graphty-element>
      * ```
-     * @returns JMESPath string or undefined if not set
+     * @returns The value set on this element, else the value in effect (undefined when that is none)
      */
     get edgeWeightPath(): string | undefined;
     /**
@@ -362,7 +373,7 @@ export declare class Graphty extends LitElement {
      * ```html
      * <graphty-element position-scale="0.01"></graphty-element>
      * ```
-     * @returns The multiplier, or undefined when none has been set on this element
+     * @returns The value set on this element, else the value in effect (undefined when that is none)
      */
     get positionScale(): number | undefined;
     /**
@@ -382,7 +393,7 @@ export declare class Graphty extends LitElement {
      * ```html
      * <graphty-element directed="true"></graphty-element>
      * ```
-     * @returns The setting, or undefined when none has been set on this element
+     * @returns The value set on this element, else the value in effect ("auto" by default)
      */
     get directed(): boolean | "auto" | undefined;
     /**
@@ -416,7 +427,9 @@ export declare class Graphty extends LitElement {
      */
     get layout(): string | undefined;
     /**
-     * Sets the layout algorithm. Triggers layout recalculation with merged config.
+     * Sets the layout algorithm: one undoable step, which undo takes back to the layout, the
+     * engine and the options before it. Assigned with `layoutConfig` in the same tick, the two are
+     * one step.
      */
     set layout(value: string | undefined);
     /**
@@ -426,7 +439,7 @@ export declare class Graphty extends LitElement {
      */
     get layoutConfig(): Record<string, unknown> | undefined;
     /**
-     * Sets layout-specific configuration. Updates active layout if one is set.
+     * Sets layout-specific configuration: the layout is drawn again with it, as one undoable step.
      */
     set layoutConfig(value: Record<string, unknown> | undefined);
     /**
@@ -484,7 +497,8 @@ export declare class Graphty extends LitElement {
      * element.layoutBehavior = { layout: { preSteps: 1000 } };
      * element.layoutBehavior = { labels: { declutter: true } };
      * ```
-     * @returns The behaviour settings, or undefined when none have been set on this element
+     * @returns The view preferences set on this element, with the pacing settings saved in the
+     *     project (`preSteps`, `stepMultiplier`, `minDelta`) as they are in effect
      */
     get layoutBehavior(): GraphBehaviorConfig | undefined;
     /**
@@ -512,7 +526,7 @@ export declare class Graphty extends LitElement {
      * ```typescript
      * element.selectionStyle = { color: "#00BCD4", scale: 1.8 };
      * ```
-     * @returns The highlight settings, or undefined when none have been set on this element
+     * @returns The value set on this element, else the value in effect (undefined when that is none)
      */
     get selectionStyle(): GraphSelectionStyleInput | undefined;
     /**
@@ -542,7 +556,7 @@ export declare class Graphty extends LitElement {
      * element.algorithmsOnLoad = ["degree", { algorithm: "pagerank", style: { size: [1, 5] } }];
      * element.runAlgorithmsOnLoad = true;
      * ```
-     * @returns The entries, or undefined when none have been set on this element
+     * @returns The value set on this element, else the value in effect (undefined when that is none)
      */
     get algorithmsOnLoad(): readonly AlgorithmOnLoad[] | undefined;
     /**
@@ -571,7 +585,8 @@ export declare class Graphty extends LitElement {
      */
     get viewMode(): ViewMode | undefined;
     /**
-     * Sets the view mode. Switches camera and rendering mode accordingly.
+     * Sets the view mode. Switching between 2D and 3D is one undoable step; entering VR or AR is
+     * not a step, and from 2D it switches to 3D first in the same step.
      */
     set viewMode(value: ViewMode | undefined);
     /**
@@ -603,7 +618,7 @@ export declare class Graphty extends LitElement {
      * ```html
      * <graphty-element background='{"backgroundType":"color","color":"black"}'></graphty-element>
      * ```
-     * @returns The background, or undefined when none has been set on this element
+     * @returns The background set on this element, else the one in effect
      */
     get background(): GraphBackgroundConfig | undefined;
     /**
@@ -641,13 +656,27 @@ export declare class Graphty extends LitElement {
      * A boolean attribute: its presence turns it on, as `hidden` does. It was read as a string,
      * so `<graphty-element run-algorithms-on-load>` handed the setter "" -- which is false -- and
      * the documented HTML form ran nothing.
-     * @returns Boolean flag or undefined if not set
+     * @returns The value set on this element, else the value in effect (undefined when that is none)
      */
     get runAlgorithmsOnLoad(): boolean | undefined;
     /**
      * Sets whether to run algorithms when a style template loads. Updates graph configuration.
      */
     set runAlgorithmsOnLoad(value: boolean | undefined);
+    /**
+     * Whether the element handles the undo keys itself: Ctrl+Z (Cmd+Z on macOS) undoes one step
+     * and Ctrl+Shift+Z or Ctrl+Y redoes it, while the graph's canvas has keyboard focus. On by
+     * default. A handled key has its default prevented, so a host page binding the same keys
+     * skips a keydown whose `defaultPrevented` is set; or turns this off with
+     * `history-keys="false"` and calls `session.undo()` itself.
+     * @returns Whether the undo keys are handled.
+     * @since 3.0.0
+     */
+    get historyKeys(): boolean;
+    /**
+     * Turns the element's own undo keys on or off.
+     */
+    set historyKeys(value: boolean);
     /**
      * Enable detailed performance profiling.
      * When enabled, hierarchical timing and advanced statistics will be collected.
@@ -955,11 +984,46 @@ export declare class Graphty extends LitElement {
      */
     resetCamera(options?: import("./screenshot/types.js").CameraAnimationOptions): Promise<void>;
     /**
-     * Save current camera state as a named preset.
-     * Available from Phase 5 onwards.
+     * Move the camera one step nearer or further, the way a Zoom in or Zoom out button does.
+     * One step is a factor of 1.25 on the 3D camera's distance or the 2D camera's zoom. Not an
+     * undoable step: the camera is view state.
+     * @param direction - `"in"` to approach, `"out"` to withdraw.
+     * @param options - Animation options
+     * @returns Promise that resolves when the camera has moved
+     * @since 3.0.0
+     * @example
+     * ```typescript
+     * await element.zoomStep("out");
+     * ```
+     */
+    zoomStep(direction: "in" | "out", options?: import("./screenshot/types.js").CameraAnimationOptions): Promise<void>;
+    /**
+     * Centre the camera on the selected nodes, keeping where it stands. With nothing selected
+     * the camera does not move. Not an undoable step: the camera is view state.
+     * @param options - Animation options
+     * @returns Promise that resolves when the camera has moved
+     * @since 3.0.0
+     * @example
+     * ```typescript
+     * await element.session.selection.apply({ nodes: ["n1"] });
+     * await element.zoomToSelection();
+     * ```
+     */
+    zoomToSelection(options?: import("./screenshot/types.js").CameraAnimationOptions): Promise<void>;
+    /**
+     * Save the current camera state as a named preset. One undoable step.
      * @param name - Name for the preset
+     * @param camera - The camera state to save instead of where the camera is now
+     * @throws A `GraphtyError` with `E_PROTECTED` when a camera view already answers to the name.
+     */
+    saveCameraPreset(name: string, camera?: import("./screenshot/types.js").CameraState): void;
+    /**
+     * Forget a preset saved with `saveCameraPreset` or `importCameraPresets`. One undoable step.
+     * @param name - The name it was saved under
+     * @returns Settles once the step is recorded; rejects with `E_BAD_COMMAND` when nothing is
+     *   saved under the name
      */
-    saveCameraPreset(name: string): void;
+    removeCameraPreset(name: string): Promise<void>;
     /**
      * Load a camera preset (built-in or user-defined).
      * Available from Phase 5 onwards.
@@ -983,8 +1047,7 @@ export declare class Graphty extends LitElement {
      */
     exportCameraPresets(): Record<string, import("./screenshot/types.js").CameraState>;
     /**
-     * Import user-defined presets from JSON
-     * Available from Phase 5 onwards
+     * Import user-defined presets from JSON, as one undoable step
      * @param presets - Record of preset names to their state
      */
     importCameraPresets(presets: Record<string, import("./screenshot/types.js").CameraState>): void;
@@ -1054,7 +1117,7 @@ export declare class Graphty extends LitElement {
      */
     addEdges(edges: import("./config").AdHocData[], options?: import("./managers").AddEdgesOptions & import("./utils/queue-migration").QueueableOptions): Promise<void>;
     /**
-     * Remove nodes from the graph.
+     * Remove nodes from the graph, and every edge attached to one, as one undoable step.
      * @param nodeIds - Array of node IDs to remove
      * @param options - Queue options for operation ordering
      * @returns Promise that resolves when nodes are removed
@@ -1066,7 +1129,18 @@ export declare class Graphty extends LitElement {
      */
     removeNodes(nodeIds: (string | number)[], options?: import("./utils/queue-migration").QueueableOptions): Promise<void>;
     /**
-     * Update node data.
+     * Remove edges from the graph, as one undoable step.
+     * @param edgeIds - The element-assigned edge ids
+     * @param options - Queue options for operation ordering
+     * @returns Promise that resolves when the edges are removed
+     * @example
+     * ```typescript
+     * await element.removeEdges(['0', '3']);
+     * ```
+     */
+    removeEdges(edgeIds: string[], options?: import("./utils/queue-migration").QueueableOptions): Promise<void>;
+    /**
+     * Update node data, as one undoable step.
      * @param updates - Array of update objects with id and properties to update
      * @param options - Queue options for operation ordering
      * @returns Promise that resolves when nodes are updated
@@ -1082,6 +1156,21 @@ export declare class Graphty extends LitElement {
         id: string | number;
         [key: string]: unknown;
     }[], options?: import("./utils/queue-migration").QueueableOptions): Promise<void>;
+    /**
+     * Update edge data, as one undoable step. Keys not named are kept; an id the graph does not
+     * hold is skipped.
+     * @param updates - The edge id and the new values of each edge
+     * @param options - Queue options for operation ordering
+     * @returns Promise that resolves when the edges are updated
+     * @example
+     * ```typescript
+     * await element.updateEdges([{ id: "0", label: "knows" }]);
+     * ```
+     */
+    updateEdges(updates: {
+        id: string;
+        [key: string]: unknown;
+    }[], options?: import("./utils/queue-migration").QueueableOptions): Promise<void>;
     /**
      * Add data from a data source.
      *
@@ -1453,20 +1542,26 @@ export declare class Graphty extends LitElement {
      */
     get isFrameStable(): boolean;
     /**
-     * Execute multiple operations as a batch.
-     * @param fn - Function containing batch operations
-     * @returns Promise that resolves when batch completes
+     * Make several changes one undoable step.
+     *
+     * `fn` receives `tx`, the session as seen from inside the step: what it does through `tx` is
+     * recorded as one step once `fn` settles, and a throw rolls all of it back. A call on the
+     * element itself while `fn` runs is a step of its own, and logs a warning naming the `tx`
+     * verb to use instead. The same as `session.transaction`, with a default label.
+     * @param fn - The changes, made through `tx`.
+     * @param label - The step's label in the history.
+     * @returns Once the step is recorded and drawn.
      * @since 1.5.0
      * @example
      * ```typescript
-     * await element.batchOperations(async () => {
-     *   await element.addNodes(nodes);
-     *   await element.addEdges(edges);
-     *   await element.setLayout('circular');
+     * await element.batchOperations(async (tx) => {
+     *   await tx.data.addNodes(nodes);
+     *   await tx.data.addEdges(edges);
+     *   await tx.layout.set("circular");
      * });
      * ```
      */
-    batchOperations(fn: () => Promise<void> | void): Promise<void>;
+    batchOperations(fn: (tx: TransactionScope) => Promise<void> | void, label?: string): Promise<void>;
     /**
      * Subscribe to graph events.
      * @param type - Event type to listen for

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

@@ -37,4 +37,6 @@ export interface KeyboardInfo {
     shiftKey: boolean;
     altKey: boolean;
     metaKey: boolean;
+    /** Cancels the DOM event's default action, so a host listening further out can skip it. */
+    preventDefault?: () => void;
 }

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

@@ -109,7 +109,14 @@ export declare class D3GraphEngine extends LayoutEngine {
      * @param n - The node to set position for
      * @param newPos - The new position coordinates
      */
-    setNodePosition(n: Node, newPos: Position): void;
+    protected setNodePosition(n: Node, newPos: Position): void;
+    /**
+     * Take the position array as this engine's own. Nodes still waiting for the next refresh are
+     * taken into the simulation first: undo and rollback rebuild the nodes they bring back, and a
+     * node left waiting would be placed by d3's own initial layout at its first tick -- over the
+     * coordinates the restore wrote for it.
+     */
+    loadArrangement(): void;
     /**
      * Get the position of an edge based on its endpoint positions
      * @param e - The edge to get position for
@@ -120,12 +127,12 @@ export declare class D3GraphEngine extends LayoutEngine {
      * Pin a node to its current position
      * @param n - The node to pin
      */
-    pin(n: Node): void;
+    protected pin(n: Node): void;
     /**
      * Unpin a node to allow it to move freely
      * @param n - The node to unpin
      */
-    unpin(n: Node): void;
+    protected unpin(n: Node): void;
     /**
      * Holds the nodes a scoped layout may not move, as d3 fixes a node: at its current position.
      *
@@ -161,6 +168,13 @@ export declare class D3GraphEngine extends LayoutEngine {
      * @param e - the edge leaving the graph
      */
     removeEdge(e: Edge): void;
+    /**
+     * Strict state: {@link LayoutEngine.edgeProblems} over the links and the edges still waiting
+     * for the next refresh, each once, with both endpoints held.
+     * @param drawn - The edges the element draws.
+     * @returns One sentence per problem.
+     */
+    protected edgeProblems(drawn: ReadonlyMap<string, Edge>): string[];
     private _getMappedNode;
     private _getMappedEdge;
 }

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

@@ -1,5 +1,6 @@
 import { z } from "zod/v4";
 import { type OptionsSchema } from "../config";
+import type { Node } from "../Node";
 import { SimpleLayoutEngine } from "./LayoutEngine";
 declare const FixedLayoutConfig: z.ZodObject<{
     dim: z.ZodDefault<z.ZodNumber>;
@@ -8,9 +9,17 @@ declare const FixedLayoutConfig: z.ZodObject<{
 type FixedLayoutConfigType = z.infer<typeof FixedLayoutConfig>;
 type FixedLayoutOpts = Partial<FixedLayoutConfigType>;
 /**
- * Fixed layout engine that doesn't move nodes - uses positions from node data
+ * The fixed layout: every node goes to its `data.position`, and then stays where it is put.
+ *
+ * The first time an engine lays out, every node carrying a `data.position` is placed there (scaled
+ * by `data.knownFields.positionScale`), whatever an earlier layout left in the element's position
+ * array -- switching to "fixed" means "put the nodes where the data says". After that the engine
+ * keeps what the array holds, so a drag survives a later recompute; a node added later reaches the
+ * array from its own `data.position` when the graph is frozen. A node with no coordinates at all
+ * is placed at the origin.
  */
 export declare class FixedLayout extends SimpleLayoutEngine {
+    #private;
     static type: string;
     static maxDimensions: number;
     static zodOptionsSchema: OptionsSchema;
@@ -22,12 +31,19 @@ export declare class FixedLayout extends SimpleLayoutEngine {
      */
     constructor(opts?: FixedLayoutOpts);
     /**
-     * Add a node and apply its fixed position immediately
+     * Add a node, and put its mesh at its `data.position` straight away.
+     *
+     * The array is not touched here: the node's row is seeded from the same `data.position` when
+     * the graph is next frozen, which is before this engine next reads it. This only spares the
+     * node the frames between its arrival and that read, which it would otherwise spend wherever a
+     * new mesh starts -- and a caller that reads a node's mesh position as soon as the add has
+     * finished, as the element's own tests do, gets the node's place rather than that.
      * @param n - The node to add
      */
-    addNode(n: import("../Node.js").Node): void;
+    addNode(n: Node): void;
     /**
-     * Read positions from node data and apply them directly
+     * Place every node at its data position on the first run; later, keep every placed row. An
+     * unplaced row goes to the origin.
      */
     doLayout(): void;
 }