@graphty/graphty-element 2.6.1 → 3.0.0

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

@@ -2,6 +2,7 @@ import type { Scene } from "@babylonjs/core";
 import type { AccelerationController } from "../acceleration";
 import type { XRConfig } from "../config/XRConfig";
 import type { MeshCache } from "../meshes/MeshCache";
+import type { GraphSession } from "../session/types";
 import type { Styles } from "../Styles";
 import type { XRSessionManager } from "../xr/XRSessionManager";
 import type { DataManager } from "./DataManager";
@@ -36,6 +37,12 @@ export interface GraphContext {
      * Get the DataManager for node/edge operations
      */
     getDataManager(): DataManager;
+    /**
+     * Get the session whose state this graph draws, when there is one: what a node's own doors
+     * dispatch through.
+     * @returns The session, or undefined for a context built without one.
+     */
+    getSession?(): GraphSession;
     /**
      * Get the LayoutManager for layout operations
      */

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

@@ -36,6 +36,17 @@ export interface InputManagerConfig {
      */
     recordInput?: boolean;
     playbackFile?: string;
+    /**
+     * Whether Mod+Z undoes and Shift+Mod+Z or Mod+Y redoes, through {@link InputManagerConfig.history}.
+     * On by default. A handled key has its default prevented, so a host binding the same keys
+     * skips events with `defaultPrevented` set.
+     */
+    historyKeys?: boolean;
+    /** What the history keys call: the graph's session. */
+    history?: {
+        undo(): unknown;
+        redo(): unknown;
+    };
 }
 /**
  * Manages all user input for the graph

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

@@ -5,6 +5,7 @@ import type { Edge } from "../Edge";
 import { LayoutEngine } from "../layout/LayoutEngine";
 import { type SimulationEngineOptions } from "../layout/SimulationLayoutEngine";
 import type { Node, NodeIdType } from "../Node";
+import type { LayoutChoice } from "../session/project/state";
 import type { Styles } from "../Styles";
 import type { DataManager } from "./DataManager";
 import type { EventManager } from "./EventManager";
@@ -33,6 +34,25 @@ import type { Manager } from "./interfaces";
  * @throws A `ZodError` when an option is outside the range its published schema declares.
  */
 export declare function resolveSimulationOptions(type: SimulationType, options: Record<string, unknown>, behavior: GraphLayoutBehavior): SimulationEngineOptions;
+/**
+ * The element's own reach into a layout manager, past its public surface: `Graph` registers the
+ * `layout` hook, and a standalone manager test builds or installs an engine outside the `layout`
+ * slice. No entry point exports it; a consumer chooses a layout with `session.layout.set`.
+ */
+export declare const layoutManagerInternals: {
+    /** The `layout` hook; see `LayoutManager.apply`. */
+    apply(manager: LayoutManager, choice: LayoutChoice, options: {
+        readonly restoring: boolean;
+        readonly signal?: AbortSignal;
+        readonly explicitScope?: boolean;
+    }): Promise<void>;
+    /** Build an engine outside the `layout` slice; see `LayoutManager.setLayout`. */
+    setLayout(manager: LayoutManager, type: string, opts?: object, scope?: ScopeInput): Promise<void>;
+    /** Take the members a scoped layout built over an empty graph owes; see `LayoutManager.takeOwedMembers`. */
+    takeOwedMembers(manager: LayoutManager): void;
+    /** Install an engine, or none, as a standalone test's stand-in for a build. */
+    setEngine(manager: LayoutManager, engine: LayoutEngine | undefined): void;
+};
 /**
  * What a layout manager reads of the session to scope a layout. `Graph` hands its session's in.
  */
@@ -63,10 +83,17 @@ interface LayoutScopeSource {
  * Coordinates layout updates and transitions
  */
 export declare class LayoutManager implements Manager {
+    #private;
     private eventManager;
     private dataManager;
     private styles;
-    layoutEngine?: LayoutEngine;
+    /** The engine drawing the graph, built by the `layout` hook. */
+    private engine?;
+    /**
+     * The engine drawing the graph, read-only: choose a layout with `session.layout.set`.
+     * @returns The engine, or undefined before the first build.
+     */
+    get layoutEngine(): LayoutEngine | undefined;
     private _running;
     /**
      * Set while a CONSUMER has paused the layout, through {@link LayoutManager.setPaused}. Nothing
@@ -81,12 +108,27 @@ export declare class LayoutManager implements Manager {
      * {@link LayoutManager.runPreStepsOnceThereIsSomethingToStep}.
      */
     private preStepsOwed;
+    /**
+     * Set when a scoped layout was built over a graph with nothing in it: its members are taken
+     * again when the first node arrives, which is when the layout really starts. A scope captured
+     * over an empty graph holds nothing it names, so it would hold every node that arrives.
+     */
+    private membersOwed;
     /**
      * The dimension the running engine was built for, so a view mode that already matches it
-     * does not rebuild the layout. See {@link LayoutManager.updateLayoutDimension}.
+     * does not rebuild the layout. See {@link LayoutManager.apply}.
      */
     private engineDimension?;
     private logger;
+    /** Told when the layout comes to rest: it settled, was paused, or finished placing. */
+    onRest: (() => void) | null;
+    /**
+     * Whether undo, redo or a restore is on its way to the position array. While it is, a new
+     * snapshot or accelerator reloads the engine without starting it, so nothing moves the
+     * arrangement being restored.
+     * @returns True while one is.
+     */
+    restoring: () => boolean;
     /** Where a scope is canonicalised and resolved, once `Graph` has a session to hand in. */
     private scopeSource;
     /**
@@ -101,6 +143,18 @@ export declare class LayoutManager implements Manager {
      * outside it is held, including one that arrives later.
      */
     private members;
+    /**
+     * Strict state: something asked to step the layout while the lane was restoring, which only a
+     * forward change may. Refused either way; strict state reports it, because the caller is
+     * running outside the derivation lane's order.
+     * @param what - What asked.
+     */
+    private reportRestoringStep;
+    /**
+     * Whether a layout is being built now, spending its own pre-steps.
+     * @returns True while one is.
+     */
+    get building(): boolean;
     /**
      * Gets the running state of the layout
      * @returns True if layout is running, false otherwise
@@ -170,13 +224,6 @@ export declare class LayoutManager implements Manager {
      * @param event - The freeze, carrying the snapshot every consumer must switch to.
      */
     private onSnapshotReplaced;
-    /**
-     * Forget the cleared graph: stop the engine and build a fresh one of the same type with the
-     * consumer's own options, so the next load lays out from scratch instead of inheriting the old
-     * engine's bodies and its settled state. A failure is already reported on the error channel
-     * by `_setLayoutInternal`, which also leaves the old engine in place.
-     */
-    private reset;
     /**
      * Report a failure that happened to a layout already running, on the element's error channel.
      * @param error - Whatever was thrown.
@@ -201,8 +248,7 @@ export declare class LayoutManager implements Manager {
      * Used by operations that are already queued to prevent nested queueing
      * @param layout - A registered engine name, or a catalogue layout id
      * @param opts - Layout-specific options
-     * @param explicitScope - Whether the carried scope was named in this call, which is the only
-     * case in which a scope the engine cannot use, or cannot resolve, is refused
+     * @param how - The dimension, whether this is a restore, and whether the build is still wanted.
      */
     private _setLayoutInternal;
     /**
@@ -221,10 +267,26 @@ export declare class LayoutManager implements Manager {
      * BEFORE IT PINS, because `D3GraphLayoutEngine.pin` copies the node's CURRENT simulated
      * position into the fixed-position fields: a bare pin replayed into a fresh engine would nail
      * the node to d3's arbitrary starting coordinates instead of where the reader put it.
+     *
+     * A 2D ENGINE GETS THE PIN ON THE PLANE. A node pinned in 3D keeps its Z in the position
+     * array, and a 2D engine handed that Z keeps it: the node is drawn where the orthographic
+     * camera hides the Z, but each of its edges is a flat quad whose length is the 3D distance, so
+     * every edge of the pinned node ran past it into empty space. Clicking a node pins it
+     * (`pinOnDrag`), so selecting a node and switching to 2D was enough. The X and Y are kept.
      * @param engine - the engine that is about to become current
      * @param nodes - every node in the graph, which is what was just added to that engine
      */
     private replayPins;
+    /**
+     * A stored position as the current engine can hold it: on the Z = 0 plane for a 2D engine.
+     * See `replayPins`; a node held out of a scoped layout carries its Z into 2D the same way.
+     * @param at - The position read from the array.
+     * @param at.x - Its X, kept.
+     * @param at.y - Its Y, kept.
+     * @param at.z - Its Z, kept by a 3D engine only.
+     * @returns The position to hand the engine.
+     */
+    private onEnginePlane;
     /**
      * Log a layout failure, tell the consumer about it, and say what to throw.
      *
@@ -255,7 +317,54 @@ export declare class LayoutManager implements Manager {
      * @throws A `GraphtyError` with `E_UNSUPPORTED` for a scope on an engine that is not scoped,
      * or `E_BAD_COMMAND` for a scope that is malformed or names a removed set.
      */
-    setLayout(type: string, opts?: object, scope?: ScopeInput): Promise<void>;
+    private setLayout;
+    /**
+     * Whether the engine is built, or being built, for exactly this value of the `layout` slice.
+     * Compared by identity: a `layout.set` writes a new value even for the same layout, which is
+     * how asking for the same layout again runs it again.
+     * @param choice - The value.
+     * @returns True when nothing needs building for it.
+     */
+    isCurrent(choice: LayoutChoice): boolean;
+    /**
+     * The `layout` hook: bring the engine to a value of the `layout` slice. A new layout or new
+     * options build a new engine; a new dimension rebuilds the engine only when the layout draws
+     * differently in two dimensions than in three. Builds run one at a time.
+     * @param choice - The value.
+     * @param options - How: `restoring` for undo, redo, a restore or a rollback (no pre-steps,
+     *     nothing published, left at rest); `signal` stops the build, publishing nothing, when
+     *     the command that asked for it is cancelled or overtaken.
+     * @param options.restoring - Whether this is a restore.
+     * @param options.signal - The asking command's signal.
+     * @param options.explicitScope - Whether the asking command named the scope.
+     * @returns Settles once the engine is built and its pre-steps have landed.
+     */
+    private apply;
+    /**
+     * Build what {@link LayoutManager.apply} asked for, when it differs from what is built.
+     * @param choice - The value.
+     * @param options - How.
+     * @param options.restoring - Whether this is a restore.
+     * @param options.signal - The asking command's signal.
+     * @param options.explicitScope - Whether the asking command named the scope.
+     * @param generation - The arrangement generation it was asked for under.
+     */
+    private build;
+    /**
+     * Hand the engine the coordinates the `arrangement` hook has just written. After a restore,
+     * the pre-steps of any build still computing from the coordinates it held before are dropped.
+     *
+     * A 2D ENGINE THEN PUTS EVERY NODE BACK ON THE PLANE, for the reason `replayPins` does: a Z
+     * written while the view is 2D -- a script's `positions.set`, a restore -- is hidden by the
+     * camera but drawn by the node's edges. The engine publishes the flattened row like any move.
+     * @param restoring - Whether undo, redo, a restore or a rollback wrote them.
+     */
+    loadArrangement(restoring: boolean): void;
+    /**
+     * The dimension the current engine was built for.
+     * @returns 2 or 3, or undefined before any engine is built.
+     */
+    get dimension(): 2 | 3 | undefined;
     /**
      * Hand the manager the session it resolves scopes through.
      * @param source - The session's canonicaliser and resolver.
@@ -268,21 +377,6 @@ export declare class LayoutManager implements Manager {
      * @internal
      */
     get scope(): Scope | undefined;
-    /**
-     * Change the carried scope without starting a layout. The next layout, and
-     * {@link LayoutManager.rescope}, run over it. It never refuses a scope that cannot be resolved:
-     * a carried scope that means nothing is inactive.
-     * @param scope - The scope; undefined or `"graph"` for the whole graph.
-     * @throws A `GraphtyError` with `E_BAD_COMMAND` when it is not a scope.
-     * @internal
-     */
-    carryScope(scope: ScopeInput | undefined): void;
-    /**
-     * Restart the running layout, with its options, over the carried scope.
-     * @returns A promise that resolves once the layout has restarted; at once when none is set.
-     * @internal
-     */
-    rescope(): Promise<void>;
     /**
      * The layout as a user of the sets it names, for "Used by": present only while a layout
      * is actually holding nodes for its scope.
@@ -350,7 +444,9 @@ export declare class LayoutManager implements Manager {
      * awaited one chunk at a time, the chunk being the largest batch the GPU package takes, and
      * every other engine keeps the plain loop, whose `step()` returns having done the work.
      * @param engine - the engine to settle.
-     * @returns A promise that resolves once every pre-step has been taken and published.
+     * @param live - Asked after every await: false once the build that spends them is cancelled or
+     *     overtaken, or the arrangement was restored since, and then nothing is published.
+     * @returns True once every pre-step has been taken and published; false when stopped.
      */
     private spendPreSteps;
     /**
@@ -374,6 +470,11 @@ export declare class LayoutManager implements Manager {
      * guarantees for one is that every owed iteration is computed rather than coalesced away.
      */
     private runPreStepsOnceThereIsSomethingToStep;
+    /**
+     * Take the members a scoped layout built over an empty graph owes, once nodes have arrived:
+     * the layout starts now, over the nodes its scope names among them.
+     */
+    private takeOwedMembers;
     /**
      * Step the layout engine forward
      */
@@ -421,28 +522,6 @@ export declare class LayoutManager implements Manager {
      * @returns Current layout type identifier or undefined if no layout is set
      */
     get layoutType(): string | undefined;
-    /**
-     * Update layout dimension when 2D/3D mode changes
-     * @param twoD - Whether to use 2D mode
-     */
-    updateLayoutDimension(twoD: boolean): Promise<void>;
-    /**
-     * Apply layout from style template if specified
-     * @param layoutType - Layout type identifier from template
-     * @param layoutOptions - Layout options from template
-     */
-    applyTemplateLayout(layoutType?: string, layoutOptions?: object): Promise<void>;
-    /**
-     * What the consumer last asked this layout for, with the element's own dimension options left
-     * out. It is what a 2D/3D rebuild starts from, and what a template's options are compared to.
-     */
-    private currentLayoutOptions?;
-    /**
-     * Check if layout options have changed
-     * @param newOptions - New layout options to compare
-     * @returns True if options have changed, false otherwise
-     */
-    private hasOptionsChanged;
     /**
      * Get layout statistics
      * @returns Object containing layout statistics

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

@@ -1,5 +1,6 @@
 import { Engine, Scene, TransformNode, WebGPUEngine } from "@babylonjs/core";
 import { CameraManager } from "../cameras/CameraManager";
+import type { GraphBackgroundConfig } from "../config/GraphStyle";
 import type { EventManager } from "./EventManager";
 import type { Manager } from "./interfaces";
 /**
@@ -25,6 +26,8 @@ export declare class RenderManager implements Manager {
     /** How many callers currently hold the frames back; see {@link holdFrames}. */
     private frameHolds;
     private resizeHandler;
+    /** The one skybox dome, and the image it shows; null while the background is a colour. */
+    private dome;
     /**
      * Stands in for Babylon's own pointer handling, which calls preventDefault and then
      * `canvas.focus()` on every pointer down and up. That focus call scrolls the host page to the
@@ -75,11 +78,21 @@ export declare class RenderManager implements Manager {
      * @returns Releases this hold.
      */
     holdFrames(): () => void;
+    /**
+     * Draw the graph against a background: a clear colour, or a photo-dome skybox.
+     *
+     * The scene holds at most one dome. A colour disposes it; a different skybox replaces it; the
+     * skybox already shown is left alone, so drawing the same background again (a redo, a repeat)
+     * builds nothing.
+     * @param background - The background, parsed.
+     * @param onSkyboxLoaded - Called with the image once a new skybox's texture has arrived.
+     */
+    applyBackground(background: GraphBackgroundConfig, onSkyboxLoaded: (url: string) => void): void;
     /**
      * Update the background color
      * @param color - Hex color string (e.g., "#FFFFFF")
      */
-    setBackgroundColor(color: string): void;
+    private setBackgroundColor;
     /**
      * Get current render statistics
      * @returns Current FPS and active mesh count

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

@@ -303,6 +303,19 @@ export declare class UpdateManager implements Manager {
      * @returns True when the last drawn frame drew the finished picture.
      */
     get frameIsStable(): boolean;
+    /**
+     * Say that meshes were built outside a pass that moves anything, so the finished picture has
+     * to be earned again.
+     *
+     * A new mesh can bring a shader variant nothing has compiled, or a texture still loading, and
+     * a frame skips a mesh that is not ready. Most doors that build meshes also move something -- a
+     * load starts the layout, a forward dimension change frames the camera -- and that clears the
+     * finished flags on the next pass. An undo of a dimension change moves nothing, because the
+     * layout stays at rest and the camera is the reader's; nor does a skybox. Without this the
+     * last finished frame would still be called final while the new meshes are drawn as nothing:
+     * an empty canvas after undoing 2D to 3D, and the old background after setting a skybox.
+     */
+    meshesAdded(): void;
     /**
      * What is still keeping the picture from being final, in a consumer's words.
      *
@@ -396,6 +409,13 @@ export declare class UpdateManager implements Manager {
      *     no placed nodes has not settled, it has not started.
      */
     private largestMove;
+    /**
+     * Move every node and edge to where the position array has it now, without stepping the
+     * layout: how a restored arrangement reaches the picture while the layout is at rest.
+     * @param moved - Whether any coordinate was written; when none was, the nodes are placed and
+     *     the edges, whose endpoints are where they were, are left as they are drawn.
+     */
+    redrawArrangement(moved?: boolean): void;
     /**
      * Update all nodes.
      */

package/dist/src/screenshot/ScreenshotCapture.d.ts

@@ -1,5 +1,5 @@
 import { type Engine, type Scene, type WebGPUEngine } from "@babylonjs/core";
-import type { Graph } from "../Graph.js";
+import { type Graph } from "../Graph.js";
 import type { ScreenshotOptions, ScreenshotResult } from "./types.js";
 /**
  * Handles screenshot capture for graph visualizations using Babylon.js rendering engine.

package/dist/src/session/GraphSession.d.ts

@@ -11,11 +11,87 @@
  * entry point's import graph and fails if a renderer appears in it.
  */
 import type { RuleTree, Scope } from "../catalog/types";
+import type { ElementPositions } from "../data/positions";
 import { type InputCounters } from "./attributes";
+import { Dispatcher, type Scheduler } from "./project/Dispatcher";
+import { type SessionRunsApi } from "./runs";
 import { type ScopeResolver } from "./scope";
 import { SetsNotifier } from "./sets/notify";
 import type { SetsApi, SetUser } from "./sets/types";
-import type { CreateGraphSessionOptions, ElementSession, GraphSession } from "./types";
+import type { CreateGraphSessionOptions, ElementSession, GraphSession, SessionDataConfig, SessionGraphStore, SessionRecordSource } from "./types";
+/**
+ * A store with its coordinate lane writable: what the arrangement hook restores coordinates and
+ * pins into. The element's data manager is one; a consumer only ever sees the read-only form.
+ * @internal
+ */
+export interface LaneStore extends Omit<SessionGraphStore, "positions"> {
+    /** The lane itself. */
+    readonly positions: ElementPositions;
+    /** Whether structural changes wait for the next read of the graph; see `GraphStore.deferring`. */
+    readonly deferring?: boolean;
+    /** Whether the next read of the graph would freeze a snapshot; see `GraphStore.stale`. */
+    readonly stale?: boolean;
+    /**
+     * The attribute revisions and input tick of whoever builds the stores (design/sets 6.2): the
+     * data manager's, the same across a Clear. Absent, the store's own.
+     */
+    readonly inputs?: InputCounters;
+}
+/**
+ * What the element's own session takes beyond {@link CreateGraphSessionOptions}: the data
+ * manager's store, whose only writer is the dispatcher, a record source, and a data configuration
+ * read live. No entry point exports it.
+ * @internal
+ */
+export interface ElementSessionOptions extends Omit<CreateGraphSessionOptions, "config"> {
+    /** The store to read. When absent the session builds one of its own and disposes it. */
+    readonly store?: LaneStore;
+    /** Where to read the attributes a record arrived with, for rows the graph slice lacks. */
+    readonly records?: SessionRecordSource;
+    /** The configuration; `data` may be a function, read on every use. */
+    readonly config?: Omit<NonNullable<CreateGraphSessionOptions["config"]>, "data"> & {
+        readonly data?: SessionDataConfig | (() => SessionDataConfig);
+    };
+}
+/**
+ * What the element's own tests hand a session besides its options: the clock of the coalescing
+ * window and the queue queued commands take their turn on, so a random sequence can drive both.
+ */
+interface SessionInternals {
+    readonly now?: () => number;
+    readonly scheduler?: Scheduler;
+    /** Open the baseline window: what the page declared at construction is not undoable. */
+    readonly baselineWindow?: boolean;
+}
+/**
+ * The runs API behind a session, with `startVia`: how the renderer starts the on-load runs as
+ * deferred members of the command that added the rows. Not published.
+ * @param session - A session this module built.
+ * @returns Its runs API.
+ */
+export declare function sessionRunsOf(session: GraphSession): SessionRunsApi;
+/**
+ * Hand a session's repaint after a data change to the renderer drawing it, which repaints once
+ * it has reconciled its own objects. Only the element calls it, before registering its own
+ * `graph` hook; without it a session repaints by itself.
+ * @param session - A session this module built.
+ */
+export declare function handGraphPaintToRenderer(session: GraphSession): void;
+/**
+ * The coordinate lane behind a session, writable: what a layout engine writes every frame, and
+ * what a test standing in for one writes. Not published; a consumer places nodes through
+ * `session.positions.set`.
+ * @param session - A session this module built.
+ * @returns Its lane.
+ */
+export declare function laneOf(session: GraphSession): ElementPositions;
+/**
+ * The dispatcher behind a session. Not published: the element's own tests spy on it and read the
+ * project state it holds.
+ * @param session - A session this module built.
+ * @returns Its dispatcher.
+ */
+export declare function dispatcherOf(session: GraphSession): Dispatcher;
 /**
  * Build a graph session.
  *
@@ -23,10 +99,10 @@ import type { CreateGraphSessionOptions, ElementSession, GraphSession } from "./
  * accelerator, disposed with it. That is the headless case -- a CI job, a Node test, a check on
  * a server -- and it needs no canvas, no GPU and no DOM.
  *
- * Handed a store, it reads that one instead and disposes nothing that arrived from outside. That
- * is how a rendered graph gets a session: the element's data manager already owns one store for
- * the life of the graph, and a second one would be a second, disagreeing copy.
- * @param options - the store, the record source, the configuration and the accelerator, each
+ * The session is the only writer of its graph and settings, which is what makes every change an
+ * undoable step: data arrives through `session.data.import`, `addNodes` and `addEdges`, and
+ * settings through `session.config.set`.
+ * @param options - the starting configuration, the accelerator and how runs execute, each
  *     optional
  * @returns the session
  * @example
@@ -47,9 +123,10 @@ export declare function createGraphSession(options?: CreateGraphSessionOptions):
  * the difference is a shape one, and it exists because a renderer tests one element at a time
  * where a consumer reads a list of ids.
  * @param options - The store, the record source, the configuration and the accelerator.
+ * @param internals - The history clock and queue, which only the element's own tests replace.
  * @returns The session.
  */
-export declare function createElementSession(options?: CreateGraphSessionOptions): ElementSession;
+export declare function createElementSession(options?: ElementSessionOptions, internals?: SessionInternals): ElementSession;
 /** What names a set from outside the session, for `usedBy`. */
 type SetsUsersProvider = () => Iterable<{
     readonly user: SetUser;