@neo4j-nvl/base 1.2.1 → 2.0.0

package/dist/types/index.d.ts

@@ -1,12 +1,12 @@
 import type { ExternalCallbacks } from './modules/ExternalCallbackHandler';
-import type { CircularOptions, ForceDirectedOptions, HierarchicalOptions, Renderer as InternalRenderer, Layout, LayoutOptions, NvlOptions, NvlState, ZoomOptions } from './modules/state/types';
+import type { CircularOptions, Cluster, ClusterByFn, ClusterId, ClusteringOptions, ForceDirectedOptions, HierarchicalOptions, Renderer as InternalRenderer, Layout, LayoutOptions, NvlOptions, NvlState, ZoomOptions } from './modules/state/types';
 import { CanvasRendererType, CircularLayoutType, ForceDirectedLayoutType, FreeLayoutType, GridLayoutType, HierarchicalLayoutType, SvgRendererType, WebGLRendererType, d3ForceLayoutType } from './modules/state/types';
 import { drawCircleBand } from './renderers/domrenderer/canvasrenderer/nodeDrawing';
 import type { StyledCaption } from './renderers/domrenderer/shared/types';
-import type { Node, PartialNode, PartialRelationship, Relationship } from './types/graph-element';
+import type { Node, NodeWithClientPosition, PartialNode, PartialRelationship, Relationship } from './types/graph-element';
 import { CompatibilityError } from './utils/errors';
 import type { Point } from './utils/geometry';
-import type { HitTargetNode, HitTargetRelationship, HitTargets } from './utils/hittest';
+import type { HitTargetCluster, HitTargetNode, HitTargetRelationship, HitTargets, HitTestTarget } from './utils/hittest';
 import { nvlResultTransformer } from './utils/jsDriverResultTransformer';
 import { getZoomTargetForNodePositions } from './utils/zoomFunctions';
 /**
@@ -139,9 +139,10 @@ declare class NVL {
     removeRelationshipsWithIds(relationshipIds: string[]): void;
     /**
      * Returns all nodes that is currently stored in the visualisation.
-     * @returns The array of {@link Node nodes}.
+     * Each node includes layout coordinates (`x`, `y`) and a `clientPosition` in screen space.
+     * @returns The array of {@link NodeWithClientPosition nodes}.
      */
-    getNodes(): Node[];
+    getNodes(): NodeWithClientPosition[];
     /**
      * Returns the relationships that are currently in the visualization.
      * @returns An array of the {@link Relationship relationships} in the visualization.
@@ -178,7 +179,7 @@ declare class NVL {
      */
     deselectAll(): void;
     /**
-     * Updates pan and zoom fit the specified nodes in the viewport.
+     * Updates pan and zoom to fit the specified nodes in the viewport.
      * @param nodeIds - The ids of the nodes to fit on the screen.
      * @param zoomOptions - Specific options on how to transition the zoom.
      *
@@ -298,11 +299,15 @@ declare class NVL {
      *
      * @example
      * ```typescript
-     * const svgDataUrl = await nvl.getSvgDataUrl({ backgroundColor: '#ffffff' })
-     * const img = document.createElement('img')
-     * img.src = svgDataUrl
-     * img.alt = 'Graph Visualization'
-     * document.body.appendChild(img)
+     * import { NVL } from '@neo4j-nvl/base'
+     *
+     * const nvl = new NVL(document.getElementById('frame'), [{ id: '0' }], [])
+     * const renderSvg = async () => {
+     *   const svgDataUrl = await nvl.getSvgDataUrl({ backgroundColor: '#ffffff' })
+     *   const img = document.createElement('img')
+     *   img.src = svgDataUrl
+     *   document.body.appendChild(img)
+     * }
      * ```
      */
     getSvgDataUrl(options?: {
@@ -373,12 +378,12 @@ declare class NVL {
      */
     getPan(): Point;
     /**
-     * Gets the nodes and relationships that have been hit by a pointer event.
+     * Gets the nodes, relationships, and clusters that have been hit by a pointer event.
      * @param evt - The mouse event.
-     * @param targets - The graph elements to check for hits. Defaults to ['node', 'relationship'].
+     * @param targets - The graph elements to check for hits. Defaults to ['node', 'relationship', 'cluster'].
      * @param hitOptions - Options for the hit test.
      * @returns A {@link NvlMouseEvent} with the {@link HitTargets} property
-     * containing the nodes and relationships that have been hit by the pointer event.
+     * containing the nodes, relationships, and clusters that have been hit by the pointer event.
      *
      * @example
      * ```js
@@ -392,7 +397,7 @@ declare class NVL {
      * })
      * ```
      */
-    getHits(evt: MouseEvent, targets?: ('node' | 'relationship')[], hitOptions?: {
+    getHits(evt: MouseEvent, targets?: HitTestTarget[], hitOptions?: {
         hitNodeMarginWidth: number;
     }): NvlMouseEvent;
     /**
@@ -415,5 +420,5 @@ declare const colorMapperFunctions: {
  */
 type Renderer = Exclude<InternalRenderer, typeof SvgRendererType>;
 export default NVL;
-export type { NvlOptions, Renderer, Node, Relationship, PartialNode, PartialRelationship, Layout, LayoutOptions, ForceDirectedOptions, HierarchicalOptions, CircularOptions, ExternalCallbacks, HitTargets, HitTargetNode, HitTargetRelationship, Point, NvlMouseEvent, ZoomOptions, StyledCaption, WebGLRendererType, CanvasRendererType };
+export type { NvlOptions, Renderer, Node, NodeWithClientPosition, Relationship, PartialNode, PartialRelationship, Layout, LayoutOptions, ForceDirectedOptions, ClusteringOptions, Cluster, ClusterByFn, ClusterId, HierarchicalOptions, CircularOptions, ExternalCallbacks, HitTargets, HitTargetNode, HitTargetRelationship, HitTargetCluster, HitTestTarget, Point, NvlMouseEvent, ZoomOptions, StyledCaption, WebGLRendererType, CanvasRendererType };
 export { NVL, colorMapperFunctions, CompatibilityError, ForceDirectedLayoutType, HierarchicalLayoutType, GridLayoutType, FreeLayoutType, d3ForceLayoutType, CircularLayoutType, drawCircleBand, nvlResultTransformer, getZoomTargetForNodePositions };

package/dist/types/layouts/animatedlayout/AnimatedLayout.d.ts

@@ -1,5 +1,5 @@
 import type { NvlState } from '../../modules/state/types';
-import type { Node } from '../../types/graph-element';
+import type { Node, PartialNode } from '../../types/graph-element';
 export default class AnimatedLayout {
     positions: Record<string, Node>;
     oldPositions: Record<string, Node>;
@@ -20,6 +20,6 @@ export default class AnimatedLayout {
     updateOldPositionFromState(): void;
     startAnimation(): void;
     update(): void;
-    updateNodes(positionList: Node[]): void;
+    updateNodes(positionList: PartialNode[]): void;
     getNodePositions(nodeList: Node[]): Node[];
 }

package/dist/types/layouts/d3forcelayout/constants.d.ts

@@ -12,7 +12,6 @@ export declare const BARNES_HUT_THETA = 1.2;
 export declare const FORCE_LINK_DISTANCE: (relationship: SimulationLinkDatum<D3Node>) => number;
 export declare const FORCE_LINK_STRENGTH: (link: SimulationLinkDatum<SimulationNodeDatum>, count: number[]) => number;
 export declare const FORCE_COLLIDE_RADIUS: (node: D3Node) => number;
-export declare const LAYOUT_RADIUS: (numberOfNodes: number) => number;
 export declare const FORCE_CHARGE: () => number;
 export declare const FORCE_CHARGE_START: () => number;
 export declare const FORCE_CENTER_X = 0.03;

package/dist/types/layouts/d3forcelayout/d3ForceLayout.d.ts

@@ -1,7 +1,7 @@
 import type { Simulation, SimulationLinkDatum, SimulationNodeDatum } from 'd3-force';
 import type { NvlState } from '../../modules/state/types';
-import type { Node, Relationship } from '../../types/graph-element';
-import type { Point } from '../../utils/geometry';
+import type { Node, PartialNode, Relationship } from '../../types/graph-element';
+import { type Point } from '../../utils/geometry';
 import type { D3Node } from './types';
 export declare class D3ForceLayout {
     state: NvlState;
@@ -20,7 +20,7 @@ export declare class D3ForceLayout {
         state: NvlState;
     });
     setOptions(options: any): void;
-    updateNodes(positionList: D3Node[]): void;
+    updateNodes(positionList: PartialNode[]): void;
     update(refreshPositions?: boolean): void;
     layout(_nodes: Node[], _rels: Relationship[], firstTimeAddingNodes: boolean): void;
     getNodePositions(nodeList: D3Node[]): any[];

package/dist/types/layouts/forcedirectedlayout/PhysLayout.d.ts

@@ -0,0 +1,275 @@
+import type { ForceDirectedOptions, NvlState } from '../../modules/state/types';
+import type { Node, PartialNode, Relationship } from '../../types/graph-element';
+import { type ClusterHitRegion } from '../../utils/clusterHitRegions';
+import { type Point } from '../../utils/geometry';
+import type { CoarsenedGraph } from './clustering/types';
+/**
+ * Collision multipliers below this are floored to 0, which makes the shader skip its
+ * all-pairs collision loop. Every fine-level force in that loop is scaled by the same
+ * multiplier, so at this strength they move nothing worth the O(n^2) cost.
+ */
+export declare const CollisionMultiplierSkipThreshold = 0.05;
+export declare const ConvergenceCheckInterval = 20;
+/**
+ * Number of consecutive convergence checks that must report a below-threshold
+ * graph speed before the layout is considered settled. This debounces a single
+ * lucky-low reading so a still-moving graph isn't stopped prematurely.
+ */
+export declare const StableChecksToConverge = 3;
+export declare class PhysLayout {
+    private physVbo;
+    private physSmallVbo;
+    private physProjection;
+    private physSmallProjection;
+    private gl;
+    private averageNodeSize;
+    private shouldUpdate;
+    private iterationCount;
+    private nodeVariation;
+    private nodeCenterPoint;
+    private peakIterationMultiplier;
+    private stateDisposers;
+    private state;
+    private dpr;
+    private maxGlNodeSize;
+    private simulationStopVelocitySquared;
+    private gravity;
+    private force;
+    private nodeIdToIndex;
+    private nodeIndexToId;
+    private flatRelationshipKeys;
+    private numNodes;
+    private subGraphs;
+    private firstUpdate;
+    private curPhysData;
+    private apprxRepForceShader;
+    private levelsClusterTexture;
+    private levelsFinestIndexTexture;
+    private initalLevelTexture;
+    private levelsData;
+    private collisionDetectionMultiplier;
+    private physShader;
+    private physData;
+    private pinData;
+    private updateData;
+    private updateShader;
+    private physPositions;
+    private physDirty;
+    private positionsCacheVersion;
+    private convergencePbo;
+    private convergenceFence;
+    private convergenceSnapshot;
+    private readonly cpuWritesSinceAsyncReadback;
+    private hadSyncReadback;
+    private graphIsStableCount;
+    private springTexture;
+    private sizeTexture;
+    private offsetTexture;
+    private pinTexture;
+    private addedNodes;
+    private seedingMethod;
+    private clusterBy?;
+    private crossClusterRelationshipMultiplier;
+    private lastClusterByAssignments;
+    private lastClusterIdsBySun;
+    private sunMap;
+    private cachedClusterHitRegions;
+    private cachedClusterHitRegionsVersion;
+    private updateTexture;
+    private physVao;
+    private physSmallVao;
+    private updateVao;
+    constructor(config: ForceDirectedOptions & {
+        webGLContext: WebGL2RenderingContext;
+        state: NvlState;
+    });
+    /**
+     * Sets the layout options.
+     * @param options - The object with the options.
+     * @param initial - Whether this is the first setting of options.
+     */
+    setOptions(options?: ForceDirectedOptions, initial?: boolean): void;
+    private applyClusteringOptions;
+    private applyCrossClusterMultiplier;
+    private applyClusterBy;
+    private wakeLayout;
+    private coarsenGraph;
+    /**
+     * Sets graph data to be used
+     * @param {{ nodes: Node[]; rels: Relationship[] }} data the graph object
+     * @returns The top level graph of the subgraphs created by the solar merger.
+     */
+    setData(data: {
+        nodes: Node[];
+        rels: Relationship[];
+    }): CoarsenedGraph;
+    /**
+     * Updates the node's positions for the next step in the physics layout iterations if the layout needs to update
+     * @param refreshPositions whether the entire layout should be reheated
+     * @returns Whether the layout should update in the following step.
+     */
+    update(refreshPositions?: boolean): boolean;
+    /**
+     * Stops the layout
+     */
+    terminateUpdate(): void;
+    /**
+     * Synchronously reads the latest node positions/velocities from the GPU into
+     * this.physPositions.
+     */
+    private readbackPositions;
+    /**
+     * Drives the convergence-readback state machine for the current iteration:
+     * consumes a pending fence if one is ready, otherwise starts a new readback
+     * when a convergence check is due.
+     * @returns Whether fresh velocity data is available.
+     */
+    private tryConsumeConvergenceReadback;
+    /**
+     * The GPU texture holding the latest node positions (xy) and velocities (zw).
+     * @returns The RGBA32F position texture.
+     *
+     * @note Texel layout matches the WebGL renderer's `u_positions` sampler, so it
+     * can be bound directly to webgl renderer.
+     */
+    getPositionTexture(): WebGLTexture;
+    /**
+     * Maps node id to its texel index in the position texture.
+     * @returns The node-id-to-texel-index map.
+     *
+     * @note This is the coarsening / solar-hierarchy order (re-derived on add/remove), which
+     * differs from the renderer's insertion order. Consumers rendering from {@link getPositionTexture}
+     * must build their sampling indices from this.
+     */
+    getNodeTexelIndices(): Readonly<Record<Node['id'], number>>;
+    /**
+     * Multilevel coarsening hierarchy produced by {@link SolarMerger} / {@link ClusterByMerger}.
+     * @returns The coarsened graph hierarchy.
+     * @see {@link CoarsenedGraph}
+     */
+    getSubGraphs(): CoarsenedGraph[];
+    /**
+     * Fitted convex-hull hit regions for multi-member {@link ClusteringOptions.clusterBy} clusters.
+     * Results are cached against {@link getPositionsCacheVersion}.
+     * @returns Cluster hit regions, or an empty array when clustering is inactive.
+     */
+    getClusterByHitRegions(): ClusterHitRegion[];
+    private shouldCheckConvergence;
+    /** Allocates the pixel-pack buffer used for the async convergence readback. */
+    private setupConvergencePbo;
+    /**
+     * Kicks off an async copy of the position texture into the pixel-pack buffer
+     * and fences it. Only issued when no readback is already in flight.
+     */
+    private issueConvergenceReadback;
+    /**
+     * Polls the in-flight fence without blocking; if the readback is ready,
+     * copies it into physPositions and clears the fence.
+     * @returns Whether fresh velocity data was consumed this call.
+     */
+    private consumeConvergenceReadback;
+    private restoreCpuWrittenPositions;
+    /** Drops any in-flight readback fence (on stop, reset, or destroy). */
+    private cancelConvergenceReadback;
+    /**
+     * Returns whether the current layout needs to be updated in the next iteration step.
+     * @returns Whether the layout should update in the following step.
+     */
+    getShouldUpdate(): boolean;
+    /**
+     * Returns whether the current layout is computing.
+     * Always returns false because the force-directed layout has no computing step.
+     * @returns Whether the layout is computing.
+     */
+    getComputing(): boolean;
+    /**
+     * Version of the CPU position cache. Advances on GPU readback, CPU-mirror
+     * writes, and physics buffer reset.
+     * @returns The current cache version.
+     */
+    getPositionsCacheVersion(): number;
+    /**
+     * Adds the current x,y coordinates for each node to a given list of nodes.
+     * Forces a synchronous GPU readback when the cache is dirty.
+     * @param nodeList - The list of nodes to get positions for.
+     * @returns The list of nodes containing the x,y coordinates on each node object.
+     */
+    getNodePositions(nodeList: Node[]): (Node & Point)[];
+    /**
+     * Maps {@link physPositions} onto a node list without forcing a GPU readback.
+     * Positions may lag behind the live GPU texture until the next sync/async refresh.
+     * @param nodeList - The list of nodes to get positions for.
+     * @returns The list of nodes containing the cached x,y coordinates.
+     */
+    getCachedNodePositions(nodeList: Node[]): (Node & Point)[];
+    /**
+     * Reheats the layout
+     * @param fullData - The entire graph object.
+     */
+    reheat(fullData: {
+        nodes: Node[];
+        rels?: Relationship[];
+    }): void;
+    /**
+     * Updates the existing nodes of a graph with a given list of updates
+     * @param nodeList - The list of updates.
+     */
+    updateNodes(nodeList: PartialNode[]): void;
+    /**
+     * Writes a node position into the current phys position texture and CPU mirror.
+     * Caller must bind {@link getPositionTexture} first.
+     */
+    private writePhysPosition;
+    /**
+     * Adds and removes nodes from the graph based on given updates
+     * @param fullData - The entire graph object.
+     * @param fullData.nodes - The nodes in the graph.
+     * @param fullData.rels - The relationships in the graph.
+     * @param nodeChanges - The changes in the graph.
+     * @param nodeChanges.adds - A list of nodes to be added.
+     * @param nodeChanges.removes - A list of nodes to be removed.
+     */
+    addRemoveData(fullData: {
+        nodes: Node[];
+        rels: Relationship[];
+    }, nodeChanges: {
+        adds: Record<string, Node>;
+        removes: Record<string, Node>;
+    }, relationshipChanges: {
+        adds: Record<string, Relationship>;
+        removes: Record<string, Relationship>;
+    }): CoarsenedGraph;
+    /**
+     * Destroys the class and all buffers and textures.
+     */
+    destroy(): void;
+    /**
+     * Takes the new flat key set of relationships and the current relationship changes
+     * and checks whether removed relationships are still in the new flat key set.
+     * and whether added relationships were already in the old flat key set.
+     * @param newFlatKeySet The new flat key set of relationships.
+     * @param relationshipChanges The changes in the relationships.
+     * @returns Whether the relationship flat map has changed.
+     */
+    private hasRelationshipFlatMapChanged;
+    private dumpTexture;
+    private getScaleNumber;
+    private getBaseLength;
+    private checkForUpdates;
+    private getNodePosition;
+    private getMaxSpeedSquared;
+    private getPhysData;
+    private newTexture;
+    private newFramebuffer;
+    private checkCompatibility;
+    private printGlStats;
+    private adjustToGlSize;
+    private setupSize;
+    private setupSprings;
+    private setupPhysics;
+    private setupPhysicsForNodes;
+    private setupPhysicsForCoarse;
+    private setupPinData;
+    private setupUpdates;
+    private definePhysicsArrays;
+}

package/dist/types/layouts/forcedirectedlayout/clustering/ClusterByMerger.d.ts

@@ -0,0 +1,62 @@
+import type { ClusterByFn, ClusterId } from '../../../modules/state/types';
+import type { Node, Relationship } from '../../../types/graph-element';
+import type { CoarsenedGraph } from './types';
+/**
+ * Default value for {@link ForceDirectedOptions.crossClusterRelationshipMultiplier}.
+ */
+export declare const DEFAULT_CROSS_CLUSTER_RELATIONSHIP_MULTIPLIER = 0;
+/**
+ * Builds a two-level Sun/Planet hierarchy from semantic cluster identifiers.
+ * Nodes sharing the same cluster id become planets orbiting a new synthetic cluster sun.
+ * Nodes without a cluster id remain independent suns.
+ */
+export default class ClusterByMerger {
+    subGraphs: CoarsenedGraph[];
+    sunMap: Record<string, string>;
+    memberMap: Record<string, string[]>;
+    relIdMap: string[][];
+    clusterAssignments: Map<string, ClusterId | undefined>;
+    clusterIdsBySun: Map<string, ClusterId>;
+    private nodeSortMap;
+    /**
+     * Coarsens the input graph into a property-based solar hierarchy.
+     * @param inputGraph - The nodes and relationships to coarsen.
+     * @param nodeIdToIndex - Maps node ids to contiguous array indices.
+     * @param clusterBy - Returns a cluster id for each node, or undefined for independent nodes.
+     */
+    constructor(inputGraph: {
+        nodes: Node[];
+        rels: Relationship[];
+    }, nodeIdToIndex: Record<string, number>, clusterBy: ClusterByFn);
+    /**
+     * Clones the finest adjacency and adds an undirected "star" edge from each cluster member to its
+     * Sun, skipping any pair already connected by a real edge.
+     * Layout-only: fed to the spring solver, never written back into the real
+     * adjacency and never rendered.
+     * @param suns - The cluster suns, each with its planets, post-sort.
+     * @param finestRelationships - The finest-level real adjacency (sorted index space).
+     * @returns A cloned adjacency augmented with intra-cluster star edges.
+     */
+    private buildClusterSpringRelationships;
+    /**
+     * Groups node indices into buckets by cluster id, preserving first-seen order.
+     * Nodes without a cluster id each get their own single-node bucket.
+     * @param nodes - Input graph nodes indexed by position.
+     * @param clusterBy - Returns a cluster id for each node, or undefined for independent nodes.
+     * @returns Arrays of node indices, one bucket per cluster or independent node.
+     */
+    private groupNodesByCluster;
+    /**
+     * Converts cluster buckets into a Sun/Planet hierarchy for the first coarsening level.
+     * Each bucket with more than one node gets a synthetic Sun and the members become its planets.
+     * Single-member buckets keep the real node as Sun.
+     * @param buckets - Node index groups produced by {@link groupNodesByCluster}.
+     * @param nodes - Input graph nodes indexed by position.
+     * @param solarNodes - Solar nodes to extend with synth suns.
+     * @param relationships - Adjacency lists to extend with rows for synth suns.
+     * @param relIdMap - Relationship id lists to extend with rows for synth suns.
+     * @returns Cluster suns, index maps for node-sun and relationship ids and
+     * copies of solar nodes / adjacency / rel id lists with synth suns appended.
+     */
+    private buildPropertyHierarchy;
+}

package/dist/types/layouts/forcedirectedlayout/clustering/SolarMerger.d.ts

@@ -0,0 +1,56 @@
+import type { Node, Relationship } from '../../../types/graph-element';
+import type { CoarsenedGraph, SolarRelationship } from './types';
+/**
+ * Coarsens a graph into a hierarchy of "solar systems", following the sun/planet/moon partitioning scheme from
+ * Hachul and Jünger, "Drawing Large Graphs with a Potential-Field-Based Multilevel Algorithm".
+ *
+ * @see {@link https://kups.ub.uni-koeln.de/1409/ Drawing Large Graphs with a Potential-Field-Based Multilevel Algorithm}
+ */
+export default class SolarMerger {
+    graph: {
+        nodes: Node[];
+        relationships: number[][];
+        idToRel: Record<string, SolarRelationship>;
+    };
+    subGraphs: CoarsenedGraph[];
+    sunMap: Record<string, string>;
+    memberMap: Record<string, string[]>;
+    relIdMap: string[][];
+    nodeSortMap?: Record<number, number>;
+    constructor(inputGraph: {
+        nodes: Node[];
+        rels: Relationship[];
+    }, nodeIdToIndex: Record<string, number>);
+    /**
+     * Repeatedly coarsens the graph, one solar-system level at a time, until it has at most `targetSize` nodes or
+     * cannot be coarsened further. Each level's result is recorded in {@link SolarMerger.subGraphs}.
+     *
+     * @param targetSize - The node count to coarsen down to.
+     * @returns The coarsest graph reached.
+     */
+    coarsenTo(targetSize: number): CoarsenedGraph;
+    /**
+     * Repeatedly coarsens the graph by exactly `levelToCoarsenBy` solar-system levels, regardless of the resulting
+     * node count. Each level's result is recorded in {@link SolarMerger.subGraphs}.
+     *
+     * @param levelToCoarsenBy - The number of levels to coarsen by.
+     * @returns The coarsest graph reached.
+     */
+    coarsenBy(levelToCoarsenBy: number): CoarsenedGraph;
+    /**
+     * Partitions `graph` into one level of solar systems and collapses each into a single node, producing the next
+     * coarser graph.
+     *
+     * Follows the three-step solar-system construction from Hachul and Jünger, "Drawing Large Graphs with a
+     * Potential-Field-Based Multilevel Algorithm" (create suns, label their neighbors as planets, assign
+     * remaining nodes as moons of their nearest planet).
+     *
+     * @param graph - The graph to coarsen by one level.
+     * @param firstIteration - Whether `graph` is the original, uncoarsened input graph.
+     * @returns The collapsed graph (`output`), the input graph with nodes reordered by solar system (`sortedInput`),
+     * and a map from the input graph's node ids to their position in `sortedInput` (`nodeSortMap`).
+     * @see {@link https://kups.ub.uni-koeln.de/1409/ Drawing Large Graphs with a Potential-Field-Based Multilevel Algorithm}
+     *
+     */
+    private coarsen;
+}

package/dist/types/layouts/forcedirectedlayout/clustering/clustering-utils.d.ts

@@ -0,0 +1,143 @@
+import type { Node, Relationship } from '../../../types/graph-element';
+import type { CoarsenedGraph, PartialPlanet, PartialSun, SolarNode, SolarRelationship, Sun } from './types';
+/**
+ * Gets the original node ids belonging to a sun and its planets and moons.
+ * @param sun - The sun to get the original node ids for.
+ * @returns The original node ids belonging to the sun system.
+ *
+ * @note Synthetic suns are not included in the returned array.
+ */
+export declare const getSunSystemOriginalIds: (sun: Sun) => string[];
+/**
+ * How many times a node's degree must exceed the graph's average degree before it is treated as a hub, see
+ * {@link isHub}.
+ *
+ * @remarks
+ * Mi et al., "Interactive Graph Layout of a Million Nodes", Sec. 4.3, proposes capping cluster *size* to avoid
+ * the outlier clusters this multiplier targets. `HubDegreeMultiplier` targets this problem by checking a node's
+ * own degree at claim time, before moon-matching runs.
+ * @see {@link https://www.mdpi.com/2227-9709/3/4/23 Interactive Graph Layout of a Million Nodes} Sec. 4.3
+ */
+export declare const HubDegreeMultiplier = 3;
+/**
+ * @param relationships - The graph's adjacency list, indexed by node id.
+ * @returns The degree a node must exceed to be treated as a hub by {@link isHub}.
+ */
+export declare const getHubDegreeThreshold: (relationships: number[][]) => number;
+/**
+ * Whether a node's degree is enough of an outlier that it must become its own sun rather than being absorbed as
+ * a planet/moon of another sun.
+ *
+ * @param index - The node id to check.
+ * @param relationships - The graph's adjacency list, indexed by node id.
+ * @param hubDegreeThreshold - The threshold from {@link getHubDegreeThreshold}.
+ * @see {@link HubDegreeMultiplier}
+ */
+export declare const isHub: (index: number, relationships: number[][], hubDegreeThreshold: number) => boolean;
+/**
+ * Builds adjacency lists and relationship id maps from the input graph.
+ * @param inputGraph - The nodes and relationships to convert.
+ * @param nodeIdToIndex - Maps node ids to contiguous array indices.
+ * @returns Parsed adjacency data for coarsening.
+ */
+export declare const buildAdjacencyGraph: (inputGraph: {
+    nodes: Node[];
+    rels: Relationship[];
+}, nodeIdToIndex: Record<string, number>) => {
+    nodes: Node[];
+    relationships: number[][];
+    relIdMap: string[][];
+    idToRel: Record<string, SolarRelationship>;
+};
+/**
+ * Wraps input nodes as {@link SolarNode}s indexed by their original position.
+ * @param nodes - The input graph nodes.
+ * @returns {SolarNode[]} Solar nodes with positional ids and original ids preserved.
+ */
+export declare const createSolarNodesFromInput: (nodes: Node[]) => SolarNode[];
+/**
+ * Creates a Planet with an unsettled parent link (caller must attach via {@link attachPlanetsToSun}).
+ */
+export declare const createPlanet: (params: {
+    id: number;
+    sunId: number;
+    weight: number;
+    originalId: string;
+    finestIndex?: number;
+    size?: () => number;
+}) => PartialPlanet;
+/**
+ * Finalises a sun's planets list, weight/size/children closures, and back-links parent on each planet.
+ * @param partialSun - The sun under construction (planets/size/children/weight not yet set).
+ * @param planets - The planets to attach to the sun (parent not yet set).
+ * @param centreWeight - The weight of the sun itself, added to the sum of its planets' weights.
+ * @param centreSize - The size of the sun itself, added to the sum of its planets' sizes.
+ * @returns A new sun object with planets attached. `previousIndex` is a placeholder until
+ * {@link sortHierarchyForShaderLayout} assigns the real value.
+ */
+export declare const attachPlanetsToSun: (partialSun: PartialSun, planets: PartialPlanet[], centreWeight: number, centreSize: number) => Sun;
+/**
+ * Appends a synthetic sun node to the finest-level arrays for a multi-member clusterBy cluster.
+ * Uses a reserved {@link SolarNode.originalId} (`synth-sun:${clusterId}`) so it cannot collide with
+ * real node ids; {@link SolarNode.synthetic} marks it for detection.
+ * @param params.clusterId - Semantic cluster id embedded in the synth sun's stable originalId.
+ * @param params.solarNodesWithSynths - Finest solar nodes; the synth sun is appended here.
+ * @param params.relationshipsWithSynths - Finest adjacency lists; an empty row is appended for the synth sun.
+ * @param params.relIdMapWithSynths - Finest relationship id lists; an empty row is appended for the synth sun.
+ * @returns A sun under construction, ready for {@link attachPlanetsToSun} (separate from the finest SolarNode).
+ */
+export declare const createSynthClusterSun: (params: {
+    clusterId: string | number;
+    solarNodesWithSynths: SolarNode[];
+    relationshipsWithSynths: number[][];
+    relIdMapWithSynths: string[][];
+}) => PartialSun;
+/**
+ * Rolls node-level adjacency up to sun-level adjacency between clusters.
+ * When `weakLinkSunIds` is provided, edges where either endpoint is a Sun are skipped.
+ * @param relationships - Node adjacency lists indexed by node position.
+ * @param nodeIndexToSunIndex - Maps each node index to its sun index.
+ * @param sunCount - Number of suns in the coarse graph.
+ * @param weakLinkSunIds - Optional set of node indices that are Suns. When set, Sun-leaf and Sun-Sun edges are ignored.
+ * @returns {number[][]} Sun-level adjacency lists without duplicate edges.
+ */
+export declare const rollupInterSunRelationships: (relationships: number[][], nodeIndexToSunIndex: Record<number, number>, sunCount: number, weakLinkSunIds?: Set<number>) => number[][];
+/**
+ * Remaps adjacency lists to a sorted node order.
+ * @param relationships - Node adjacency lists in the pre-sort index order.
+ * @param nodeSortMap - Maps old node indices to sorted indices.
+ * @param relIdMap - Relationship ids aligned with adjacency lists.
+ * @param remapRelIds - Whether relationship ids should be remapped as well.
+ * @returns {{ relationships: number[][]; relIdMap: string[][] }} Remapped adjacency data.
+ */
+export declare const remapAdjacencyWithSortMap: (relationships: number[][], nodeSortMap: Record<number, number>, relIdMap: string[][], remapRelIds?: boolean) => {
+    relationships: number[][];
+    relIdMap: string[][];
+};
+/** Input nodes that may receive a layout `finestIndex` during sorting (plain Node on first pass). */
+type SourceNode = (Node | SolarNode) & {
+    finestIndex?: number;
+};
+export type SortHierarchyOptions = {
+    suns: Sun[];
+    solarNodes: SolarNode[];
+    sourceNodes?: SourceNode[];
+    relationships: number[][];
+    relIdMap: string[][];
+    idToRel: Record<string, SolarRelationship>;
+    firstIteration?: boolean;
+    includeMoons?: boolean;
+};
+/**
+ * Sorts suns, planets, and optionally moons into shader layout order and builds the finest subgraph.
+ * @param options - Hierarchy members and adjacency data to sort.
+ * @returns The finest subgraph, sort map, member-sun maps, and remapped relationship ids.
+ */
+export declare const sortHierarchyForShaderLayout: ({ suns, solarNodes, sourceNodes, relationships, relIdMap, idToRel, firstIteration, includeMoons }: SortHierarchyOptions) => {
+    sortedInput: CoarsenedGraph;
+    nodeSortMap: Record<number, number>;
+    sunMap: Record<string, string>;
+    memberMap: Record<string, string[]>;
+    relIdMap: string[][];
+};
+export {};