@graphty/graphty-element 2.6.2 → 3.0.0

package/dist/src/Graph.d.ts

@@ -21,16 +21,49 @@ import { type GraphSession } from "./session";
 import type { Run, StartOptions } from "./session/runs";
 import type { SelectionDelta, SelectionOp, SelectionTarget } from "./session/selection";
 import type { StyleSuggestion } from "./session/styles";
+import type { TransactionScope } from "./session/types";
 import { Styles } from "./Styles";
 import type { QueueableOptions, RunAlgorithmOptions, SetLayoutOptions } from "./utils/queue-migration";
 import { XRSessionManager } from "./xr/XRSessionManager";
+/**
+ * Load the element's data-source pair through `addDataFromSource`, as every load goes, with what
+ * only the pair has: a coalesce key, so the two halves assigned in one tick are one load, and
+ * whether the page declared it at construction, which makes it the baseline. No entry point
+ * exports it.
+ * @param graph - The graph.
+ * @param type - The data source type.
+ * @param config - Its configuration.
+ * @param how - The coalesce key, and whether it is setup.
+ * @param how.coalesce - The key two pair loads coalesce under while the first waits.
+ * @param how.setup - Declared at construction.
+ * @returns The load, as `addDataFromSource` returns it.
+ */
+export declare function loadSourcePair(graph: Graph, type: string, config: object, how: {
+    readonly coalesce: string;
+    readonly setup: boolean;
+}): Promise<{
+    loadId: number;
+}>;
+/**
+ * A graph's operation queue: what the element's own parts (the element's data doors, the
+ * screenshot capture) and its tests queue work on and wait for. Not published: code queued there
+ * could run between the steps of a command, so a consumer waits with `graph.waitForSettled()`.
+ * @param graph - The graph.
+ * @returns Its queue.
+ */
+export declare function operationQueueOf(graph: Graph): OperationQueueManager;
 /**
  * Main orchestrator class for graph visualization and interaction.
  * Integrates Babylon.js scene management, coordinates nodes, edges, layouts, and styling.
  */
 export declare class Graph implements GraphContext {
     #private;
-    styles: Styles;
+    /**
+     * The element's configuration document, read-only: its `config` is the frozen merged view.
+     * Change a setting through `getSession().config.set`, which is an undoable step.
+     * @returns The configuration document.
+     */
+    get styles(): Styles;
     element: Element;
     canvas: HTMLCanvasElement;
     engine: WebGPUEngine | Engine;
@@ -38,7 +71,6 @@ export declare class Graph implements GraphContext {
     camera: CameraManager;
     private initialCameraState?;
     private initialCameraStateCaptured;
-    private userCameraPresets;
     skybox?: string;
     xrHelper: WebXRDefaultExperience | null;
     needRays: boolean;
@@ -46,8 +78,13 @@ export declare class Graph implements GraphContext {
     fetchNodes?: FetchNodesFn;
     fetchEdges?: FetchEdgesFn;
     initialized: boolean;
-    runAlgorithmsOnLoad: boolean;
     enableDetailedProfiling?: boolean;
+    /** The view settings, as set; see {@link ViewSettings}. Written only through `writeViewSettings`. */
+    private readonly viewSettings;
+    /** Moves on every write of the view settings, so the frozen configuration knows to rebuild. */
+    private viewVersion;
+    /** The frozen configuration, and the three write counts it was built at. */
+    private configCache;
     private wasSettled;
     /** How many loads `addDataFromSource` has started; the last one's id. */
     private loadCount;
@@ -72,6 +109,10 @@ export declare class Graph implements GraphContext {
     private updateManager;
     private algorithmManager;
     private inputManager;
+    /** While an immersive session is active: its mode and when it started, stamped on steps. */
+    private immersiveSince;
+    /** How many `batchOperations` callbacks are open. */
+    private openBatches;
     private selectionManager;
     /**
      * What the session's style stack resolved for each element, and which stack owns the paint.
@@ -90,18 +131,24 @@ export declare class Graph implements GraphContext {
      * it is why every data question this class answers is forwarded rather than computed.
      */
     private readonly session;
-    operationQueue: OperationQueueManager;
+    /** The queue loads, layouts, runs and style passes take their turn in; see {@link operationQueueOf}. */
+    private readonly operationQueue;
     private xrSessionManager;
     private xrUIManager;
     private graphContext;
     private activeCapture;
-    private savedZPositions;
     /**
      * Creates a new Graph instance and initializes the rendering engine and managers.
      * @param element - DOM element or element ID to attach the graph canvas to
      * @param useMockInput - Whether to use mock input for testing (defaults to false)
      */
     constructor(element: Element | string, useMockInput?: boolean);
+    /**
+     * Build the engine for the `layout` slice when nothing has yet: the default layout, until one
+     * is chosen, in the dimension the slice holds.
+     * @param signal - Fires when a layout the consumer asked for replaces this one first.
+     */
+    private buildOpeningLayout;
     private cleanup;
     /**
      * Shuts down the graph, stopping animations and disposing all resources.
@@ -133,6 +180,17 @@ export declare class Graph implements GraphContext {
      * The entry's run options ride along either way, with no per-algorithm branch.
      * @param entry - An algorithm, or an algorithm with its run options.
      */
+    /**
+     * Run the on-load algorithms, when `runAlgorithmsOnLoad` is set. Each is queued, not awaited.
+     * @param dispatch - Where their commands go: the deferred members of the command that added
+     *     the rows, so they merge into its step.
+     */
+    private startOnLoadRuns;
+    /**
+     * Run one entry of the load-time algorithm list.
+     * @param entry - An algorithm, or an algorithm with its run options.
+     * @param dispatch - Where a catalogue run's command goes.
+     */
     private runOnLoad;
     /**
      * Initializes the graph instance, setting up managers, styles, and rendering pipeline.
@@ -143,15 +201,27 @@ export declare class Graph implements GraphContext {
      * All update logic is now handled by UpdateManager
      */
     update(): void;
+    /**
+     * Whether the algorithms in the configuration's `data.algorithms` run once data has loaded.
+     * A project setting: setting it is one step, which undo takes back.
+     * @returns The setting.
+     */
+    get runAlgorithmsOnLoad(): boolean;
+    /**
+     * Set whether the on-load algorithms run.
+     * @param value - The setting.
+     */
+    set runAlgorithmsOnLoad(value: boolean);
     /**
      * Set what the graph is drawn against: a flat colour, or a photo-dome skybox.
      *
-     * The colour reaches the scene's clear colour and a skybox builds a `PhotoDome` around the
-     * graph, announcing `skybox-loaded` once its texture has arrived. The value is also written
-     * into the configuration document, so a later read of `styles.config.graph.background` and a
-     * rebuild of the scene both see what was asked for.
+     * A project setting: one step, which undo takes back. The colour reaches the scene's clear
+     * colour and a skybox builds a `PhotoDome` around the graph, announcing `skybox-loaded` once
+     * its texture has arrived; the scene never holds more than one dome. A later read of
+     * `styles.config.graph.background` sees the value, parsed.
      * @param background - A colour (`{backgroundType: "color", color}`) or a skybox
      *     (`{backgroundType: "skybox", data}`), where `data` is an image URL or a base64 PNG.
+     * @throws A Zod error when the value is not a background; nothing is changed then.
      */
     setBackground(background: GraphBackgroundConfig): void;
     /**
@@ -159,8 +229,8 @@ export declare class Graph implements GraphContext {
      * node, and how solid it is.
      *
      * MERGED, NOT REPLACED: naming the colour leaves the scale and the opacity where they were.
-     * It takes effect immediately, on a selection that is already on screen as well as on the
-     * next one.
+     * A project setting: one step, which undo takes back. It takes effect on a selection that is
+     * already on screen as well as on the next one.
      *
      * THE HALO IS NOT A STYLE LAYER, deliberately. A selection is what a person is pointing at
      * rather than a property of the data, so it is drawn by the renderer from the selection mask
@@ -178,32 +248,62 @@ export declare class Graph implements GraphContext {
      * means that field and not "reset every other pacing setting to its default", which is what
      * parsing a partial document against a schema of defaults would do.
      *
+     * `layout.preSteps`, `layout.stepMultiplier` and `layout.minDelta` are project settings:
+     * setting any of them is one step, which undo takes back. The rest -- label declutter, pin on
+     * drag, the throughput settings, the fetchers -- are preferences of this view, and undo does
+     * not touch them.
+     *
      * The settings take effect on the next layout the element runs. `preSteps` is read when a
      * layout starts, so setting it after a graph has already settled changes nothing that is
      * already on screen. `labels.declutter` is the exception: it takes effect on the next frame.
      * @param behavior - The fields to change. Anything omitted keeps its current value.
+     * @throws A Zod error when a value is outside what the schema allows; nothing is changed then.
      */
     setLayoutBehavior(behavior: GraphBehaviorConfig): void;
     /**
-     * Adds graph data from a registered data source.
-     *
-     * PAINTS WHAT IT LOADED, and that is not incidental. Data reaches the element two ways and a
-     * consumer chooses between them by which method they call: records handed in through
-     * `addNodes`/`setEdges`, which are queued operations, or a file, string or URL read by a data
-     * source, which is this method and which deliberately bypasses the queue (`DataManager`
-     * streams chunks straight into the store so a large file does not queue an operation per
-     * chunk). The element's whole-graph repaint hangs off the QUEUED path, so a graph
-     * loaded this way was never painted from the style stack at all: every node and edge kept the
-     * bootstrap appearance `DataManager` gives it at construction, `styleOf` answered `{}`, and
-     * `styles.explain(...)` truthfully reported that no layer -- not even the element's own
-     * defaults -- had painted anything. The picture happened to resemble the default layer's
-     * colour, so it read as success until a story asked for something else.
-     *
-     * The repaint is here, once per load, rather than on the `data-added` event, which fires per
-     * chunk and per kind and would put a whole-graph pass behind each one.
+     * The layout behaviour: the view preferences somebody set on this graph, and the pacing
+     * settings saved with the project (`preSteps`, `stepMultiplier`, `minDelta`) as they are in
+     * effect. Those three always read their value, so assigning one its default reads back even
+     * though it records no step.
+     * @returns The behaviour settings.
+     */
+    getLayoutBehavior(): GraphBehaviorConfig | undefined;
+    /**
+     * Change project settings as one step, reporting a refusal rather than leaving it unhandled:
+     * the doors that call this hand their caller no promise.
+     * @param values - The settings.
+     */
+    private setProjectConfig;
+    /**
+     * Write the view settings, so the frozen configuration is rebuilt on its next read.
+     * @param write - Changes the settings.
+     */
+    private writeViewSettings;
+    /**
+     * The configuration document `styles.config` reads: frozen, merged from the project settings
+     * and the view settings, and rebuilt only when one of them has changed since the last read,
+     * so two reads with no change between them return the same object.
+     * @returns The document.
+     */
+    private configDocument;
+    /**
+     * Merge project settings, the layout and the view settings into one frozen configuration
+     * document. `graph.viewMode` and the deprecated `graph.twoD` are computed from the layout's
+     * dimension, and from the immersive session the view is in; they are stored nowhere.
+     * @param project - The project settings.
+     * @param layout - The `layout` slice.
+     * @returns The document.
+     */
+    private mergeConfig;
+    /**
+     * Adds graph data from a registered data source, as one undoable step.
      *
-     * A load that fails part-way still paints: the rows that did arrive are in the store and on
-     * screen, so leaving them unpainted would be the same defect with a smaller blast radius.
+     * The load takes its turn on the operation queue behind the loads and layouts asked for
+     * before it, and is added to what the graph holds unless it replaces it. It paints what it
+     * loaded before the promise settles: the pass that follows its last chunk repaints the graph
+     * from the style stack, so a graph loaded this way is painted exactly as one built from
+     * records is. A load that fails part way records nothing and takes back the rows that did
+     * arrive, so a replacing load that fails leaves the graph it would have replaced.
      *
      * EVERY LOAD HAS AN ID. The promise resolves to it, and every event about this load --
      * `data-loading-progress`, `data-loading-complete`, `data-loading-error`, `data-loaded` and
@@ -231,7 +331,7 @@ export declare class Graph implements GraphContext {
      */
     private reserveLoad;
     /**
-     * Run a load whose place `reserveLoad` already took, then repaint what it loaded.
+     * Run a load whose place `reserveLoad` already took.
      * @param type - Type/name of the registered data source
      * @param opts - Options to pass to the data source
      * @param load - The reservation
@@ -403,7 +503,7 @@ export declare class Graph implements GraphContext {
      */
     setEdges(edges: Record<string | number, unknown>[], options?: AddEdgesOptions & QueueableOptions): Promise<void>;
     /**
-     * Replace every node in the graph with a new set.
+     * Replace every node in the graph with a new set, as one undoable step.
      *
      * What the `node-data` property does, and the node half of {@link setEdges}. A node whose id is
      * not in the new set is removed the way {@link removeNodes} removes one, so the edges attached
@@ -479,6 +579,13 @@ export declare class Graph implements GraphContext {
      * @since 2.5.0
      */
     setLayoutScope(scope: ScopeInput | undefined): Promise<void>;
+    /**
+     * A layout scope as the `layout` slice keeps it.
+     * @param scope - The scope as given.
+     * @returns Its canonical form; `"graph"` for the whole graph.
+     * @throws A `GraphtyError` with `E_BAD_COMMAND` when it is not a scope.
+     */
+    private canonicalLayoutScope;
     /**
      * Run a graph algorithm, addressed the 1.10 way.
      * @remarks
@@ -538,6 +645,7 @@ export declare class Graph implements GraphContext {
      * @param options - Algorithm options and queue settings.
      * @param start - Run options for a catalogue run, such as `style`; a plugin without a
      *     descriptor has no run to give them to.
+     * @param dispatch - Where a catalogue run's command goes; the session's own by default.
      */
     private runLegacyAddress;
     /**
@@ -575,8 +683,10 @@ export declare class Graph implements GraphContext {
      * @param mapping - The catalogue key to start, and the parameters it needs.
      * @param namespace - The 1.10 namespace, for the error event and the suggested styles.
      * @param type - The 1.10 type, for the same two.
-     * @param options - What the caller passed.
+     * @param options - What the caller passed. `applySuggestedStyles` is carried out in the run's
+     *     own step, so one undo takes the run and those layers away together.
      * @param start - Run options to start it with, such as `style`.
+     * @param dispatch - Where the run's command goes; the session's own by default.
      */
     private runLegacyAsRun;
     /**
@@ -622,7 +732,8 @@ export declare class Graph implements GraphContext {
      */
     getSuggestedStyles(algorithmKey: string): readonly StyleSuggestion[];
     /**
-     * Remove nodes from the graph by their IDs, and with them every edge attached to one.
+     * Remove nodes from the graph by their IDs, and with them every edge attached to one, as one
+     * undoable step. Undo puts them back at the rows they held.
      *
      * One `elements-removed` event is emitted per call, naming the nodes and every edge
      * that went with them. A removal used to be silent, so a consumer watching the element saw its
@@ -630,24 +741,58 @@ export declare class Graph implements GraphContext {
      * which is why the notification lands with the cascade rather than after it.
      * @param nodeIds - Array of node IDs to remove
      * @param options - Queue options for operation ordering
+     * @returns Settles once the change is drawn
      */
     removeNodes(nodeIds: (string | number)[], options?: QueueableOptions): Promise<void>;
     /**
-     * Write each update into its node's attributes through the one attribute writer, so the
-     * revision of every field written moves. `id` is the address, not an attribute, and is not
-     * written.
-     * @param updates - the updates, each naming its node by `id`
+     * Remove edges from the graph by their ids, as one undoable step. Undo puts them back at the
+     * rows they held, with their weights and ids.
+     * @param edgeIds - The element-assigned edge ids
+     * @param options - Queue options for operation ordering
+     * @returns Settles once the change is drawn
      */
-    private writeNodeUpdates;
+    removeEdges(edgeIds: string[], options?: QueueableOptions): Promise<void>;
     /**
-     * Update node data for existing nodes in the graph.
+     * Update node data for existing nodes in the graph, as one undoable step.
      * @param updates - Array of update objects containing node ID and properties to update
      * @param options - Queue options for operation ordering
+     * @returns Settles once the change is drawn
      */
     updateNodes(updates: {
         id: string | number;
         [key: string]: unknown;
     }[], options?: QueueableOptions): Promise<void>;
+    /**
+     * Update edge data for existing edges in the graph, 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 Settles once the change is drawn
+     */
+    updateEdges(updates: {
+        id: string;
+        [key: string]: unknown;
+    }[], options?: QueueableOptions): Promise<void>;
+    /**
+     * Tell the selection about a removal before it is written, whichever door dispatched it.
+     *
+     * THE SELECTION IS TOLD FIRST, and that ordering is the whole of it. The session's masks are
+     * keyed by dense index; an id is resolved to an index through the current snapshot. Once the
+     * builder has tombstoned these rows, the next freeze compacts and every surviving edge slides
+     * down -- so a mask still holding the dead indices would silently be holding the SURVIVORS
+     * instead, and a removal would leave two edges the reader never selected highlighted on screen.
+     * @param nodeIds - The nodes removed, whose incident edges go with them.
+     * @param edgeIds - The edges removed.
+     */
+    private selectRemoval;
+    /**
+     * Dispatch one `data.apply`, or a batch of them. It takes its turn on the operation queue,
+     * which keeps an add ordered against the loads and layouts queued before it, or starts at once
+     * with `skipQueue`.
+     * @param mutation - The mutation, or the batch.
+     * @param options - Queue options.
+     */
+    private applyData;
     /**
      * Activate the camera that belongs to the current view mode: `"2d"` in 2D, `"orbit"` in 3D.
      *
@@ -669,11 +814,31 @@ export declare class Graph implements GraphContext {
      */
     setRenderSettings(_settings: Record<string, unknown>, options?: QueueableOptions): Promise<void>;
     /**
-     * Execute multiple operations as a batch
-     * Operations will be queued and executed in dependency order
-     * @param fn - Function containing operations to batch
+     * Make several changes one undoable step.
+     *
+     * A transaction of this graph's session: what `fn` does through `tx` -- `tx.data.addNodes`,
+     * `tx.layout.set`, `tx.run`, `tx.styles.add` -- is recorded as one step once `fn` settles, and
+     * a throw rolls all of it back. A call on this graph itself while `fn` runs is a step of its
+     * own, and logs a warning naming the `tx` verb to use instead.
+     * @param fn - The changes, made through `tx`.
+     * @param label - The step's label.
+     * @returns Once the step is recorded and drawn.
+     * @since 3.0.0
+     * @example
+     * ```typescript
+     * await graph.batchOperations(async (tx) => {
+     *     await tx.data.addNodes([{ id: "a" }, { id: "b" }]);
+     *     await tx.data.addEdges([{ src: "a", dst: "b" }]);
+     *     await tx.layout.set("circular");
+     * });
+     * ```
+     */
+    batchOperations(fn: (tx: TransactionScope) => Promise<void> | void, label?: string): Promise<void>;
+    /**
+     * While a batch is open, make each of this graph's doors warn that it is a step of its own,
+     * naming the `tx` verb that would join the batch.
      */
-    batchOperations(fn: () => Promise<void> | void): Promise<void>;
+    private warnOutsideBatch;
     /**
      * The headless model behind this renderer: the graph data, the coordinates, the statistics,
      * the catalogue, the configuration and what this machine can do.
@@ -739,7 +904,8 @@ export declare class Graph implements GraphContext {
      */
     removeListener(id: symbol): boolean;
     /**
-     * Remove every node and edge, leaving the graph empty and ready for the next dataset.
+     * Remove every node and edge, leaving the graph empty and ready for the next dataset, as one
+     * undoable step.
      *
      * The verb the data guide has always taught -- as `graph.clear()`, which has never existed.
      * `<graphty-element>` has had `clearData()` throughout; a consumer holding a `Graph` had to
@@ -814,6 +980,12 @@ export declare class Graph implements GraphContext {
      *     or the pass was stopped.
      */
     private repaintFromSession;
+    /**
+     * Strict state: the drawn maps are keyed exactly like the `graph` slice, and the layout engine
+     * holds each drawn edge once, where it can place it.
+     * @param slice - The `graph` slice the pass derived.
+     */
+    private checkDrawn;
     /**
      * Get the DataManager instance.
      * @returns The DataManager instance
@@ -979,14 +1151,13 @@ export declare class Graph implements GraphContext {
      *
      * WHY THE ELEMENT NEEDED THIS AT ALL. `setupCameras` ends with an unconditional
      * `activateCamera("orbit")` and RenderManager is handed no configuration, so a freshly built
-     * scene was always perspective 3D no matter what `config.graph.viewMode` said. The only route
-     * to the orthographic camera was `_setViewModeInternal`, which is a TRANSITION: it clears the
-     * mesh cache, rebuilds every node and edge, saves and restores Z, and reframes the camera. A
-     * graph whose opening state is 2D has nothing to transition from -- there are no meshes yet
-     * and no Z to save -- and a consumer who wrote `<graphty-element view-mode="2d">` or set
-     * `config.graph.viewMode` on a bare `Graph` got a graph that reported "2d" from every property
-     * while drawing through a perspective camera, spreading the layout through three dimensions
-     * and building every edge as a 3D tube.
+     * scene was always perspective 3D no matter what the `layout` slice's dimension said. The
+     * other route to the orthographic camera is the `layout` hook, which is a TRANSITION: it
+     * clears the mesh cache, rebuilds every node and edge, and reframes the camera. A graph whose
+     * opening state is 2D has nothing to transition from -- there are no meshes yet -- and a
+     * consumer who wrote `<graphty-element view-mode="2d">` got a graph that reported "2d" from
+     * every property while drawing through a perspective camera, spreading the layout through
+     * three dimensions and building every edge as a 3D tube.
      *
      * WHY HERE. This runs immediately before `markCategoryCompleted("style-init")`, and the
      * position is load-bearing: `data-add` depends on `style-init`, so no node or edge mesh can be
@@ -1000,11 +1171,27 @@ export declare class Graph implements GraphContext {
      *
      * AR AND VR OPEN AS 3D, deliberately. Entering an immersive session is `requestSession`,
      * which browsers only grant inside a user gesture, so it cannot happen during init; the
-     * XR session manager is merely constructed later in `init()`. An opening `viewMode` of "ar"
-     * or "vr" therefore gets the perspective camera and is recorded in the scene metadata, and
-     * the session begins when a consumer calls `setViewMode` from a click.
+     * XR session manager is merely constructed later in `init()`, and the session begins when a
+     * consumer calls `setViewMode` from a click.
      */
     private applyOpeningViewMode;
+    /**
+     * The dimension the `layout` slice holds: the one home of 2D versus 3D.
+     * @returns "2d" or "3d".
+     */
+    private dimension;
+    /**
+     * Record in the scene whether it is drawn flat, which the edge meshes read. The only writer of
+     * `scene.metadata.twoD`: the `layout` hook and the opening view call it, from the slice.
+     * @param twoD - Whether the scene is 2D.
+     */
+    private writeSceneDimension;
+    /**
+     * Whether the scene already draws a value of the `layout` slice in its dimension.
+     * @param choice - The value.
+     * @returns True when nothing about the scene needs to change for it.
+     */
+    private sceneDrawn;
     /**
      * Frame the graph on the element's own initiative -- after a data load, a new layout, or the
      * first settlement -- unless the configuration placed the camera itself with
@@ -1029,8 +1216,14 @@ export declare class Graph implements GraphContext {
     /**
      * Set the view mode.
      * This controls the camera type, input handling, and rendering approach.
+     *
+     * Switching between 2D and 3D is one undoable step (`view.dimension`). Entering VR or AR is
+     * not a step -- it is a device session -- but VR and AR draw in 3D, so asking for one from 2D
+     * switches to 3D first, and the switch and the entry are one step. When entry fails, because
+     * the browser has no WebXR or the session is refused, nothing is recorded, the graph stays in
+     * the dimension it was in, and the failure is logged rather than thrown.
      * @param mode - The view mode to set: "2d", "3d", "ar", or "vr"
-     * @param options - Optional queueing options
+     * @param options - Optional queueing options; `skipQueue` switches at once.
      * @returns Promise that resolves when view mode is set
      * @example
      * ```typescript
@@ -1043,25 +1236,49 @@ export declare class Graph implements GraphContext {
      */
     setViewMode(mode: ViewMode, options?: QueueableOptions): Promise<void>;
     /**
-     * Internal method for setting view mode - bypasses queue
-     * Used by operations that are already queued
-     *
-     * WHAT "PREVIOUS" MEANS HERE IS THE SCENE, NOT THE CONFIGURATION, and the distinction is the
-     * whole reason an opening 2D used to be impossible. This method's job is to move the scene
-     * from the view it is drawing to the view that was asked for, so the only honest reading of
-     * "the view it is drawing" is the scene itself -- which camera is active and what
-     * `scene.metadata` records. The configuration is a statement of what the graph should be,
-     * written by `applyOpeningViewMode` at init and by the public `setViewMode` before its
-     * operation is queued, so diffing against it answers "has anyone asked for this yet" rather
-     * than "is it already so", and those are different questions the moment a mode is asked for
-     * before there is a scene to put it in.
-     *
-     * Reading the scene also makes the method idempotent and self-repairing: a redundant switch
-     * to the mode already on screen costs nothing, and a scene that has drifted out of step with
-     * its configuration is brought back rather than declared fine.
-     * @param mode - The view mode to set
+     * Dispatch a door's command, resolving rather than rejecting when a newer request of the same
+     * kind made it redundant before it ran: that is the caller's own later decision, not a failure
+     * they have to handle. Undone or failed, it rejects.
+     * @param command - The command.
+     * @param options - How it joins the queue.
+     * @param options.beside - Start at once, beside the queue.
+     */
+    private dispatchSuperseded;
+    /**
+     * Bring the engine, the scene's dimension and the camera to a value of the `layout` slice:
+     * the `layout` hook. Run inline by `layout.set` and `view.dimension`, and by the derivation
+     * pass after undo, redo or a rollback.
+     * @param choice - The value.
+     * @param how - `restoring` for undo, redo, a restore or a rollback; `signal` stops the build.
+     * @param how.restoring - Whether this is a restore: no pre-steps, the layout left at rest.
+     * @param how.signal - The asking command's signal.
+     * @param how.explicitScope - Whether the command named the scope, so a scope that cannot be
+     *     laid out is refused rather than left inactive.
+     * @returns Settles once the engine is built and its pre-steps have landed.
+     */
+    private applyLayout;
+    /**
+     * Rebuild the scene for a new dimension, before the engine is rebuilt: the mesh cache, the
+     * scene's record, the camera, and every node and edge mesh.
+     * @param twoD - Whether the scene becomes 2D.
      */
-    private _setViewModeInternal;
+    private enterDimension;
+    /**
+     * Put the nodes and edges where the new dimension draws them, once the engine is rebuilt:
+     * flat in 2D, and at the coordinates the position array holds in 3D.
+     * @param twoD - Whether the scene is 2D now.
+     * @param frame - Frame the camera on the nodes, as a forward switch does.
+     */
+    private settleDimension;
+    /**
+     * Enter or leave an immersive session: `view.immersive`. Exempt from history -- a device
+     * session is not the document -- and refused from 2D, which the caller switches out of in
+     * the same step first.
+     * @param mode - VR, AR, or null to leave.
+     * @throws A `GraphtyError` with `E_BAD_COMMAND` from 2D, or `E_UNSUPPORTED` without WebXR;
+     *     whatever the browser rejects the session with otherwise.
+     */
+    private setImmersive;
     /**
      * Check if ray updates are needed for edge arrows.
      * @returns True if rays need updating
@@ -1547,6 +1764,37 @@ export declare class Graph implements GraphContext {
      * @returns Promise that resolves when camera is reset
      */
     resetCamera(options?: import("./screenshot/types.js").CameraAnimationOptions): Promise<void>;
+    /**
+     * 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: the 3D orbit camera's distance from its pivot is divided or
+     * multiplied by it, and the 2D camera's zoom multiplied or divided. The
+     * camera is view state, so this is not an undoable step.
+     * @param direction - `"in"` to approach, `"out"` to withdraw.
+     * @param options - Optional animation configuration.
+     * @returns Promise that resolves when the camera has moved.
+     * @since 3.0.0
+     * @example
+     * ```typescript
+     * await graph.zoomStep("in");
+     * ```
+     */
+    zoomStep(direction: "in" | "out", options?: import("./screenshot/types.js").CameraAnimationOptions): Promise<void>;
+    /**
+     * Centre the camera on the selected nodes, keeping where it stands.
+     *
+     * The camera turns to look at the centre of the box around the selected nodes; with nothing
+     * selected it does not move. The camera is view state, so this is not an undoable step.
+     * @param options - Optional animation configuration.
+     * @returns Promise that resolves when the camera has moved.
+     * @since 3.0.0
+     * @example
+     * ```typescript
+     * await graph.select({ nodes: ["n1"] });
+     * await graph.zoomToSelection();
+     * ```
+     */
+    zoomToSelection(options?: import("./screenshot/types.js").CameraAnimationOptions): Promise<void>;
     /**
      * Get default camera state for current camera type
      * Lazily captures the initial state on first use, or returns captured state
@@ -1607,15 +1855,25 @@ export declare class Graph implements GraphContext {
         params?: Readonly<Record<string, unknown>>;
     } & import("./screenshot/types.js").CameraAnimationOptions): Promise<void>;
     /**
-     * Save where the camera is now under a name of the consumer's choosing.
+     * Save where the camera is now under a name of the consumer's choosing. One undoable step.
      *
      * A snapshot records a POSITION, not a rule: it cannot re-derive itself for a different graph
      * the way a camera view does. Which is why a name a view already holds -- the element's own
      * or a registered one -- is refused rather than shadowed.
      * @param name - The name to save it under.
+     * @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): void;
+    saveCameraPreset(name: string, camera?: import("./screenshot/types.js").CameraState): void;
+    /**
+     * Forget a camera state saved with `saveCameraPreset` or `importCameraPresets`. One undoable
+     * step.
+     * @param name - The name it was saved under.
+     * @returns Settles once the step is recorded.
+     * @throws A `GraphtyError` (as a rejection) with `E_BAD_COMMAND` when nothing is saved under
+     *     the name.
+     */
+    removeCameraPreset(name: string): Promise<void>;
     /**
      * Load a camera preset (built-in or user-defined)
      * @param name - Name of the preset to load
@@ -1643,7 +1901,7 @@ export declare class Graph implements GraphContext {
      */
     exportCameraPresets(): Record<string, import("./screenshot/types.js").CameraState>;
     /**
-     * Import user-defined presets from JSON
+     * Import user-defined presets from JSON, as one undoable step.
      * @param presets - Object mapping preset names to camera states
      */
     importCameraPresets(presets: Record<string, import("./screenshot/types.js").CameraState>): void;