@neo4j-nvl/base 1.2.1 → 2.0.0

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

@@ -0,0 +1 @@
+export {};

package/dist/types/layouts/forcedirectedlayout/{physlayout/solarmerger → clustering}/types.d.ts

@@ -1,4 +1,4 @@
-import type { Node } from '../../../../types/graph-element';
+import type { Node } from '../../../types/graph-element';
 export interface SolarNode extends Omit<Node, 'id' | 'size'> {
     id: number;
     weight?: number;
@@ -13,6 +13,7 @@ export interface SolarNode extends Omit<Node, 'id' | 'size'> {
         y: number;
     };
     size?: number | (() => number);
+    synthetic?: boolean;
 }
 export interface SolarRelationship {
     id: string;
@@ -23,6 +24,11 @@ export interface CoarsenedGraph {
     nodes: SolarNode[];
     relationships: number[][];
     idToRel: Record<string, SolarRelationship>;
+    /**
+     * Contains the "real" {@link relationships} plus any synthetic edges purely for layout purposes.
+     * Undefined when there are no synthetic edges (e.g. SolarMerger).
+     */
+    springRelationships?: number[][];
 }
 export interface Sun extends SolarNode {
     planets: Planet[];
@@ -30,6 +36,8 @@ export interface Sun extends SolarNode {
     children: () => Planet[];
     previousIndex: number;
 }
+/** Sun fields known before {@link attachPlanetsToSun} fills planets/size/children/weight. */
+export type PartialSun = Omit<Sun, 'planets' | 'size' | 'children' | 'previousIndex' | 'weight'>;
 export interface Planet extends SolarNode {
     parent: Sun;
     sunId: number;
@@ -37,6 +45,8 @@ export interface Planet extends SolarNode {
     size: () => number;
     children: () => Moon[];
 }
+/** Planet fields known before {@link attachPlanetsToSun} sets parent. */
+export type PartialPlanet = Omit<Planet, 'parent'>;
 export interface Moon extends SolarNode {
     parent: Planet;
     sunId: number;

package/dist/types/layouts/forcedirectedlayout/shaders/multilevel-fragment.d.ts

@@ -0,0 +1,2 @@
+declare const _default: "#version 300 es\nprecision mediump float;\n\nuniform sampler2D u_physData;\nuniform sampler2D u_connections;\nuniform sampler2D u_connectionOffsets;\nuniform sampler2D u_pinnedNodes;\nuniform sampler2D u_sizeTexture;\nuniform float u_baseLength;\nuniform float u_curIteration;\nuniform float u_iterationMultiplier;\nuniform vec2 u_gravityCenter;\nuniform float u_numNodes;\nuniform float u_gravity;\n\nuniform sampler2D u_clusterData;\nuniform sampler2D u_prevForce;\nuniform float u_collisionMultiplier;\nuniform float u_maxNodeSize;\nuniform float u_crossClusterRelationshipMultiplier;\n\nout vec4 fragColor;\n\nfloat DAMP = 0.6;\nfloat COOL = 0.99998;\nfloat TIMESTEP = 1.0 / 30.0;\nfloat VELOCITYDECAY = 0.6;\nfloat accLimitLow = 500000.0;\nfloat accLimitHigh = 750000.0;\nfloat accLimitPosHigh = 10000000.0;\n\nconst float denseNodeThreshold = 1000.0;\nconst float MIN_DISTANCE = 0.00000001;\nconst float MAX_DISTANCE = 1000000000.0;\nconst float MAX_ACCELERATION = 50000.0;\n\nvec4 getTextureData(sampler2D tex, float index, float base) {\n  float x = mod(index, base);\n  float y = (index - x) / base;\n  return texture(tex, vec2(x + 0.5, y + 0.5) / base);\n}\n\nbool isNan(float val) {\n  return (val < 0.0 || 0.0 < val || val == 0.0) ? false : true;\n}\n\nconst float BIG_NUMBER = 999999999999999999.0;\nbool isInf(float val) {\n  return val > BIG_NUMBER || val < -BIG_NUMBER;\n}\n\nvec2 getDelta(vec2 v1, vec2 v2) {\n  vec2 delta = v1 - v2;\n  float dist = length(delta);\n  if (dist < MIN_DISTANCE || isNan(dist)) {\n    return vec2(MIN_DISTANCE, MIN_DISTANCE);\n  }\n  if (dist > MAX_DISTANCE) {\n    vec2 normDelta = delta / dist;\n    return normDelta * MAX_DISTANCE;\n  }\n  return delta;\n}\n\nvec4 getOtherNodePosition(float i) {\n  return getTextureData(u_physData, i, 256.0);\n}\n\nfloat getCombinedNodeSize(float i, float nodeSize) {\n  float otherNodeSize = getTextureData(u_sizeTexture, i, 256.0).r;\n  return nodeSize + otherNodeSize;\n}\n\nvec2 getSpringForce(float curConnection, float numConnections, float springFScale, vec4 myPosition, float i, float myClusterStartIndex) {\n  float curSpring = getTextureData(u_connections, curConnection + i, 4096.0).r;\n\n  vec4 otherPosition = getTextureData(u_physData, curSpring, 256.0);\n  float otherDataPosition = getTextureData(u_connectionOffsets, curSpring, 256.0).r;\n  float otherNumConnections = getTextureData(u_connections, otherDataPosition, 4096.0).r;\n  float avgDegree = max((otherNumConnections + numConnections * 3.0) / 4.0, 4.0);\n\n  vec2 delta = getDelta(myPosition.xy, otherPosition.xy);\n  float dist = length(delta);\n\n  float F = (dist * dist * springFScale) / (u_baseLength * avgDegree) * u_collisionMultiplier;\n\n  // u_crossClusterRelationshipMultiplier only damps edges that cross a cluster boundary\n  if (u_crossClusterRelationshipMultiplier < 1.0) {\n    float otherClusterStartIndex = getTextureData(u_clusterData, curSpring, 256.0).y;\n    F *= otherClusterStartIndex == myClusterStartIndex ? 1.0 : u_crossClusterRelationshipMultiplier;\n  }\n\n  return (-delta / dist) * F;\n}\n\nvec2 getCollisionForce(float combinedNodeSize, float dist, float fScale, vec2 delta) {\n  float collisionForce = (combinedNodeSize - dist) / (dist) * u_collisionMultiplier;\n  return (delta * collisionForce * fScale * combinedNodeSize) / (combinedNodeSize + 1.0);\n}\n\nvec2 getRepulsionForce(float dist, float fScale, vec2 delta) {\n  float F = (u_baseLength * u_baseLength * fScale) / (dist) * u_collisionMultiplier;\n  return (delta / dist) * F * 0.05;\n}\n\nvoid main(void) {\n  float textureSide = 256.0; //#TEXTURE_SIDE#;\n  float index = (gl_FragCoord.x - 0.5) + (gl_FragCoord.y - 0.5) * textureSide;\n\n  if (index >= u_numNodes) {\n    discard;\n  }\n\n  vec4 clusterData = getTextureData(u_clusterData, index, 256.0);\n\n  float clusterIndex = clusterData.x;\n  float clusterStartIndex = clusterData.y;\n  float clusterSize = clusterData.z;\n\n  vec4 myPosition = getTextureData(u_physData, index, 256.0);\n  vec4 previousForce = getTextureData(u_prevForce, clusterIndex, 256.0);\n\n  vec2 acceleration = previousForce.xy;\n\n  float isPinned = getTextureData(u_pinnedNodes, index, 256.0).r;\n  float nodeSize = getTextureData(u_sizeTexture, index, 256.0).r;\n\n  if (isPinned > 0.5) {\n    fragColor = vec4(myPosition.xy, 0.0, 0.0);\n    return;\n  }\n\n  // Prime the second ping-pong texture with the initial state without calculating forces\n  // that would otherwise be discarded at the end of this first iteration.\n  if (u_curIteration == 0.0) {\n    fragColor = vec4(myPosition.xy, myPosition.zw);\n    return;\n  }\n\n  float curConnection = getTextureData(u_connectionOffsets, index, 256.0).r;\n  float numConnections = getTextureData(u_connections, curConnection, 4096.0).r;\n\n  float fScale = 1.0 + sqrt(u_iterationMultiplier);\n  float springFScale = fScale;\n\n  if (numConnections > denseNodeThreshold) {\n    springFScale = sqrt(fScale);\n  }\n\n  float numOfRels = 0.0;\n\n  // Springs\n  for (float i = 1.0; i <= 256.0 * 256.0; i++) {\n    if (numOfRels >= numConnections) {\n      break;\n    }\n    acceleration += getSpringForce(curConnection, numConnections, springFScale, myPosition, i, clusterStartIndex);\n    numOfRels += 1.0;\n  }\n\n  // Repulsion && collision detection.\n  if (u_collisionMultiplier > 0.0) {\n    float number_of_collisions = 0.0;\n    for (float i = 0.0; i < 256.0 * 256.0; i++) {\n      if (i >= u_numNodes) {\n        break;\n      }\n\n      if (i == index) {\n        continue;\n      }\n\n      vec4 otherPosition = getOtherNodePosition(i);\n      vec2 delta = getDelta(myPosition.xy, otherPosition.xy);\n      float dist = length(delta);\n\n      if (number_of_collisions < 40.0 && dist < (nodeSize + u_maxNodeSize) * 2.0) {\n        float combinedNodeSize = getCombinedNodeSize(i, nodeSize) * 2.0;\n        if (dist < combinedNodeSize) {\n          number_of_collisions++;\n          acceleration += getCollisionForce(combinedNodeSize, dist, fScale, delta);\n        }\n      }\n\n      if (i >= clusterStartIndex && i < clusterStartIndex + clusterSize) {\n        acceleration += getRepulsionForce(dist, fScale, delta);\n      }\n    }\n  }\n\n  // Gravity\n  vec2 delta = getDelta(u_gravityCenter, myPosition.xy);\n  float dist = length(delta);\n\n  vec2 grav = (delta / dist) * u_gravity * fScale * (dist / 1000.0);\n  acceleration += grav;\n\n  float accMagnitude = length(acceleration);\n  acceleration *= min(MAX_ACCELERATION, accMagnitude) / accMagnitude;\n\n  float iterationFrictionThreshold = 1000.0;\n\n  if (u_curIteration > iterationFrictionThreshold) {\n    float friction = 1.0 + pow((u_curIteration - iterationFrictionThreshold), 2.0) / 100.0;\n    acceleration *= 1.0 / friction;\n  }\n\n  float TEMP = max(0.02, pow(COOL, u_curIteration));\n  vec2 prevVelocity = myPosition.zw;\n  vec2 currentPos = myPosition.xy;\n\n  vec2 newPos = currentPos + TEMP * ( DAMP * (prevVelocity) + acceleration * TIMESTEP * TIMESTEP);\n  vec2 newVelocity = newPos - currentPos;\n  fragColor = vec4(newPos, newVelocity);\n}";
+export default _default;

package/dist/types/layouts/forcedirectedlayout/shaders/multilevel-repulsive-fragment.d.ts

@@ -0,0 +1,2 @@
+declare const _default: "#version 300 es\nprecision mediump float;\nuniform sampler2D u_physData;\nuniform sampler2D u_clusterData;\nuniform sampler2D u_finestIndexes;\nuniform sampler2D u_prevForce;\n\nuniform float u_baseLength;\nuniform float u_numNodes;\nuniform float u_iterationMultiplier;\nuniform float u_isTopLevel;\n\nout vec4 fragColor;\n\nfloat PI = 3.1415926535897932384626433832795;\nfloat TIMESTEP = 1.0 / 30.0;\nfloat VELOCITYDECAY = 1.0;\n\nvec4 getTextureData(sampler2D tex, float index, float base) {\n  float x = mod(index, base);\n  float y = (index - x) / base;\n  return texture(tex, vec2(x + 0.5, y + 0.5) / base);\n}\n\nfloat getAdjustedClusterWeight(float clusterWeight) {\n  return (clusterWeight * clusterWeight) / (clusterWeight + 1.0);\n}\n\n// Repulsion area from peer mass (weight). .z size is only for mid-level loop bounds.\nfloat getPeerFootprintArea(float peerWeight) {\n  return pow(sqrt(peerWeight) * 4.0 + u_baseLength * 2.0, 2.0);\n}\n\nvoid main(void) {\n  float index = (gl_FragCoord.x - 0.5) + (gl_FragCoord.y - 0.5) * 256.0;\n\n  if (index >= u_numNodes) {\n    discard;\n  }\n\n  vec4 clusterData = getTextureData(u_clusterData, index, 256.0);\n  bool isTopLevel = u_isTopLevel == 1.0;\n\n  float clusterIndex = clusterData.x;\n  float clusterStartIndex = clusterData.y;\n  float clusterSize = clusterData.z;\n  float singleNodeRepulsionScale = isTopLevel && clusterSize == 1.0 ? 0.5 : 1.0;\n\n  float finestIndex = getTextureData(u_finestIndexes, index, 256.0).r;\n  vec4 myPosition = getTextureData(u_physData, finestIndex, 256.0);\n  vec4 previousForce = getTextureData(u_prevForce, clusterIndex, 256.0);\n  float fScale = 1.0 + sqrt(u_iterationMultiplier);\n\n  vec2 acceleration = previousForce.xy;\n\n  float loopEnd = isTopLevel ? u_numNodes : (clusterStartIndex + clusterSize);\n\n  // Repulsion & Collision Detection\n  for (float i = 0.0; i < 256.0 * 256.0; i++) {\n    if (i >= loopEnd || i >= u_numNodes) {\n      break;\n    }\n    if ((!isTopLevel && i < clusterStartIndex) || i == index) {\n      continue;\n    }\n\n    vec4 otherClusterData = getTextureData(u_clusterData, i, 256.0);\n    float otherClusterWeight = getAdjustedClusterWeight(otherClusterData.w);\n\n    float otherFinestIndex = getTextureData(u_finestIndexes, i, 256.0).r;\n    vec4 otherPosition = getTextureData(u_physData, otherFinestIndex, 256.0);\n\n    vec2 delta = myPosition.xy - otherPosition.xy;\n    float dist = max(length(delta), 0.0000001);\n    float maxDist = 25.0;\n    float repulsionForceScale = 0.1;\n\n    float area = getPeerFootprintArea(otherClusterData.w);\n    float F = (area * fScale) / (dist * dist);\n\n    if (isTopLevel) {\n      repulsionForceScale = 0.2;\n    }\n\n    acceleration += ((delta / sqrt(dist)) * F) * repulsionForceScale * otherClusterWeight * singleNodeRepulsionScale;\n\n    if (dist < maxDist) {\n      float collide = (maxDist - dist) / (dist * dist);\n      acceleration += delta * collide * fScale * maxDist / (maxDist + 1.0);\n    }\n  }\n\n  fragColor = vec4(acceleration, vec2(finestIndex, 0));\n}";
+export default _default;

package/dist/types/layouts/forcedirectedlayout/shaders/multilevel-update-fragment.d.ts

@@ -0,0 +1,2 @@
+declare const _default: "#version 300 es\nprecision mediump float;\n\nuniform sampler2D u_physData;\nuniform sampler2D u_updateData;\nuniform float u_numNodesNew;\n\nout vec4 fragColor;\n\nconst float INDEX_FLAG = 999999.0;\n\nvec4 getTextureData(sampler2D tex, float index, float base) {\n  float x = mod(index, base);\n  float y = (index - x) / base;\n  return texture(tex, vec2(x + 0.5, y + 0.5) / base);\n}\n\nvoid main(void) {\n  float textureSide = 256.0; //#TEXTURE_SIDE#;\n  float index = (gl_FragCoord.x - 0.5) + (gl_FragCoord.y - 0.5)*textureSide;\n\n  if (index >= u_numNodesNew) {\n    discard;\n  }\n\n  float firstValue = getTextureData(u_updateData, index * 2.0, 256.0).r;\n  float secondValue = getTextureData(u_updateData, index * 2.0 + 1.0, 256.0).r;\n\n  if (secondValue == INDEX_FLAG) {\n    vec4 myPosition = getTextureData(u_physData, firstValue, 256.0);\n    fragColor = myPosition;\n  } else {\n    fragColor = vec4(firstValue, secondValue, 0.0, 0.0);\n  }\n}\n";
+export default _default;

package/dist/types/layouts/forcedirectedlayout/shaders/sim-vertex.d.ts

@@ -0,0 +1,2 @@
+declare const _default: "#version 300 es\nuniform mat4 u_projection;\n\nin vec2 a_position;\n//in float a_index;\n\n//out highp float index;\n\nvoid main() {\n//  index = a_index;\n  gl_Position = u_projection * vec4(a_position, 0.0, 1.0);\n}";
+export default _default;

package/dist/types/layouts/freeLayout/FreeLayout.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';
 import type { Point } from '../../utils/geometry';
 export declare class FreeLayout {
     private state;
@@ -10,9 +10,7 @@ export declare class FreeLayout {
         state: NvlState;
     });
     setOptions(): any;
-    updateNodes(positionList: (Point & {
-        id: string;
-    })[]): void;
+    updateNodes(positionList: PartialNode[]): void;
     update(refreshPositions?: boolean): void;
     layout(nodes: Node[], nodeIds: Record<string, Node>, idToPosition: Record<string, Node>): void;
     setNodePositions(p: Record<string, Point>): void;

package/dist/types/layouts/gridLayout/GridLayout.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';
 import type { Point } from '../../utils/geometry';
 export declare class GridLayout {
     state: NvlState;
@@ -10,11 +10,7 @@ export declare class GridLayout {
         state: NvlState;
     });
     setOptions(): void;
-    updateNodes(positionList: {
-        id: string;
-        x: number;
-        y: number;
-    }[]): void;
+    updateNodes(positionList: PartialNode[]): void;
     update(refreshPositions?: boolean): void;
     layout(mobxNodes: any): void;
     setNodePositions(idToPosition: Record<string, Node & Point>): void;

package/dist/types/layouts/hierarchicallayout/HierarchicalLayout.d.ts

@@ -7,6 +7,8 @@ type HierarchicalLayoutConfig = {
 export declare class HierarchicalLayout extends AnimatedLayout {
     private direction;
     private packing;
+    private clusterBy?;
+    private lastClusterByAssignments;
     private stateDisposers;
     private oldComputing;
     private computing;
@@ -14,9 +16,12 @@ export declare class HierarchicalLayout extends AnimatedLayout {
     private worker;
     private directionChanged;
     private packingChanged;
+    private clusterByChanged;
     private workersDisabled;
     constructor(config: HierarchicalLayoutConfig);
     setOptions(options: LayoutOptions): void;
+    private applyClusterByOption;
+    private buildClusterAssignments;
     update(refreshPositions?: boolean): void;
     getShouldUpdate(): boolean;
     getComputing(): boolean;

package/dist/types/modules/ExternalCallbackHandler.d.ts

@@ -1,4 +1,4 @@
-import type { Node } from '../types/graph-element';
+import type { NodeWithClientPosition } from '../types/graph-element';
 /**
  * An object specifying the required callback functions for certain actions
  */
@@ -6,7 +6,7 @@ export interface ExternalCallbacks {
     /** Triggered when a layout is done moving. */
     onLayoutDone?: () => void;
     /** Triggered on each step of a layout. */
-    onLayoutStep?: (p: Node[]) => void;
+    onLayoutStep?: (p: NodeWithClientPosition[]) => void;
     /** Triggered when NVL throws an error after initialization. */
     onError?: (error: Error) => void;
     /** Triggered when NVL is initialized. */
@@ -32,7 +32,7 @@ export default class ExternalCallbackHandler {
     onInitialization(): void;
     onZoomTransitionDone(): void;
     onLayoutDone(): void;
-    onLayoutStep(p: Node[]): void;
+    onLayoutStep(p: NodeWithClientPosition[]): void;
     onLayoutComputing(isComputing: boolean): void;
     onError(error: Error): void;
     onWebGLContextLost(webGLContextEvent: WebGLContextEvent): void;

package/dist/types/modules/NvlController.d.ts

@@ -1,4 +1,4 @@
-import { type Node, type PartialNode, type PartialRelationship, type Relationship } from '../types/graph-element';
+import { type Node, type NodeWithClientPosition, type PartialNode, type PartialRelationship, type Relationship } from '../types/graph-element';
 import '../types/nvl-window-functions';
 import type { Point } from '../utils/geometry';
 import type { ExternalCallbacks } from './ExternalCallbackHandler';
@@ -31,10 +31,13 @@ export default class NvlController {
     private readonly forceLayout;
     private readonly canvasRenderer;
     private readonly svgRenderer;
+    private clusterOverlay;
     private readonly glCanvas;
     private canvasRect;
     private readonly glMinimapCanvas;
     private readonly c2dCanvas;
+    private clusterOverlayCanvas;
+    private readonly canvasParent;
     private readonly svg;
     private isInRenderSwitchAnimation;
     private previousRenderer;
@@ -46,25 +49,96 @@ export default class NvlController {
     private readonly stateDisposers;
     private readonly zoomTransitionHandler;
     private currentLayout;
+    private lastTimestamp;
+    private accumulator;
     private readonly layoutTimeLimit;
+    private readonly smoothFrameBudgetMs;
     private pixelRatio;
     private readonly removeResizeListener;
     private readonly removeMinimapResizeListener;
     private pendingZoom;
     private pendingPan;
     private pendingViewportOverride;
-    private layoutRunner;
     private animationRequestId;
     private layoutDoneCallback;
     private layoutComputingCallback;
     private currentLayoutType;
     private descriptionElement;
+    /** True when a minimap container was provided at construction. */
+    private readonly hasMinimap;
+    private lastMinimapPositions;
+    private lastMinimapCacheVersion;
     constructor(state: NvlState, frame: HTMLElement, options: NvlOptions);
     private onWebGLContextLost;
+    private fpsToFrameBudgetMs;
+    private getLayoutNeedsToUpdate;
+    private isWithinBudget;
+    /**
+     * Add elapsed frame time to the layout-step accumulator, capped at `layoutTimeLimit`.
+     * Prevents a slow frame (e.g. blocked GPU readback) from inflating catch-up debt and
+     * scheduling ever more work in a feedback loop; the layout falls behind gracefully instead.
+     */
+    private accumulateLayoutElapsedTime;
+    /**
+     * Whether the GPU force-directed layout is active.
+     * @returns `true` when PhysLayout is the current layout.
+     */
+    private usesGpuSimulation;
+    /**
+     * Whether the GPU-texture fast path can be taken this frame.
+     * Requires the WebGL renderer, GPU layout active, and no CPU-position consumers
+     * (layout-step callback, HTML overlays). A provided minimap no longer blocks this path;
+     * the minimap and cluster overlay are updated from the lagged async position cache instead.
+     * @returns `true` when rendering directly from the GPU position texture is safe.
+     */
+    private canRenderFromGpuTexture;
+    /**
+     * Uploads lagged PhysLayout cache positions to the minimap when the cache version changed.
+     * @returns `true` when positions were refreshed this call.
+     */
+    private refreshMinimapFromCacheIfStale;
+    /**
+     * Fits, renders, and caches minimap positions (and PhysLayout cache version when applicable).
+     */
+    private syncMinimap;
+    /** Whether either cluster decoration is enabled in the current layout options. */
+    private hasClusterDecorations;
+    /**
+     * Creates the decoration canvas and its overlay.
+     * @returns The overlay to draw with.
+     */
+    private createClusterOverlay;
+    /**
+     * Resolves the overlay to draw into, allocating it on first use and tearing it down again
+     * while cluster decorations are off.
+     * @returns The overlay to draw with, or null when decorations are disabled.
+     */
+    private ensureClusterOverlay;
+    /** Tears the overlay and its canvas back down once decorations are switched off. */
+    private destroyClusterOverlay;
+    /**
+     * Draws (or clears) cluster decorations on the Canvas2D overlay from explicit positions.
+     * @param positions - CPU node positions for this frame, or null to clear.
+     */
+    private renderClusterOverlay;
+    /**
+     * Draws cluster decorations from PhysLayout's lagged async PBO cache without a sync dump.
+     * @param forceLayout - The PhysLayout instance to render the cluster overlay from.
+     */
+    private renderClusterOverlayFromCache;
+    /** Syncs idToPosition from the GPU layout on demand; no-op for CPU layouts. */
+    syncPositionsFromLayout(): void;
+    /**
+     * Fitted {@link ClusteringOptions.clusterBy} hull regions for the current layout, or [].
+     * @returns Cluster hit regions for picking.
+     */
+    getClusterByHitRegions(): import("../utils/clusterHitRegions").ClusterHitRegion[];
     private updateMinimapZoom;
     private startMainLoop;
+    private renderNodeHtmlOverlays;
+    private renderRelationshipHtmlOverlays;
     updateHtmlOverlay(): void;
-    dumpNodes(): Node[];
+    dumpNodes(): NodeWithClientPosition[];
     dumpRelationships(): Relationship[];
     /**
      * Map a relative Canvas space to the DOM position
@@ -93,7 +167,7 @@ export default class NvlController {
     };
     registerDoneCallback(cb: NvlController['layoutDoneCallback']): void;
     registerComputingCallback(cb: NvlController['layoutComputingCallback']): void;
-    getPosition(nodeId: string): Node;
+    getPosition(nodeId: string): Node & Point;
     getScale(): number;
     getPan(): {
         x: number;
@@ -113,10 +187,16 @@ export default class NvlController {
     getCanvasNodesAt(point: Point, hitNodeMarginWidth?: number): import("..").HitTargetNode[];
     private getLayout;
     setLayout(layoutType: Layout): void;
-    setLayoutOptions(options: LayoutOptions): void;
+    setLayoutOptions(options?: LayoutOptions): void;
+    /**
+     * Syncs positions if needed and redraws (or clears) the cluster overlay from current state.
+     */
+    private refreshClusterOverlay;
     private getDataUrlForCanvas;
     private initiateFileDownload;
     private updateLayoutAndPositions;
+    private getAndUpdatePositions;
+    private getLayoutPositions;
     saveToFile(options: SaveToFileOptions): void;
     private createSvgString;
     saveToSvg(options?: SaveToFileOptions): Promise<void>;

package/dist/types/modules/Shader.d.ts

@@ -4,7 +4,7 @@ export default class Shader {
     private curTexture;
     private attributeInfo;
     private uniformInfo;
-    constructor(gl: WebGLRenderingContext, vsSource: string, fsSource: string, defines?: {});
+    constructor(gl: WebGL2RenderingContext, vsSource: string, fsSource: string, defines?: {});
     setUniform(name: string, value: any): void;
     setAttributePointer(name: string, size: number, start: number, stride: number): void;
     setAttributePointerFloat(name: string, size: number, start: number, stride: number): void;

package/dist/types/modules/dataset.d.ts

@@ -1,5 +1,5 @@
 import type { Node, Relationship } from '../types/graph-element';
-import type { Point } from '../utils/geometry';
+import { type Point } from '../utils/geometry';
 /** A graph stored with mobx. */
 export interface DataSet<T> {
     items: T[];
@@ -8,6 +8,7 @@ export interface DataSet<T> {
     idToPosition: Record<string, Node & Point>;
     idToHtmlOverlay?: Record<string, HTMLElement>;
     version: number;
+    maxDimension: number;
     addChannel: (this: DataSet<T>, channelName: string) => void;
     removeChannel: (this: DataSet<T>, channelName: string) => void;
     clearChannel: (this: DataSet<T>, channelName: string) => void;
@@ -29,7 +30,8 @@ export interface Channel<T> {
     updates: Record<string, T>;
     removes: Record<string, T>;
 }
-export declare const getHtmlProperty: (item: Partial<Node | Relationship>) => HTMLElement | undefined;
+export declare const getHtmlKey: (item: Node | Relationship) => "html" | "captionHtml";
+export declare const getHtmlProperty: (item: Node | Relationship) => HTMLElement | undefined;
 /**
  * Creates an empty dataset in which a graph be stored and updated using mobx actions.
  * @returns A new and empty {@link DataSet}.

package/dist/types/modules/state/types.d.ts

@@ -34,29 +34,98 @@ export type DisabledItemStyles = {
     fontColor: string;
 };
 /**
- * The options for the force directed layout
+ * Identifier returned by {@link ClusterByFn} to group nodes into physical clusters.
+ * Nodes sharing the same string or number are clustered together.
  */
-export interface ForceDirectedOptions {
+export type ClusterId = string | number;
+/**
+ * A physical cluster produced by {@link ClusteringOptions.clusterBy}.
+ * Not a graph element — used for hit-testing and interaction callbacks.
+ */
+export type Cluster = {
+    /** Semantic cluster id returned by {@link ClusterByFn}. */
+    id: ClusterId;
+    /** Real member node ids belonging to this cluster (at least two). */
+    nodeIds: string[];
+};
+/**
+ * Function that maps a node id to a {@link ClusterId} for force-directed clustering.
+ * Returns `undefined` for nodes that should remain independent.
+ */
+export type ClusterByFn = (nodeId: string) => ClusterId | undefined;
+/**
+ * Options that control physical clustering and cluster decorations for the force-directed layout.
+ */
+export interface ClusteringOptions {
+    /**
+     * Optional function to group nodes into physical clusters based on a custom identifier.
+     * Nodes returning the same string or number will be grouped together in the layout.
+     * Nodes returning undefined will be treated as independent.
+     *
+     * @note Ensure this function has a stable reference to avoid evaluation on every render.
+     */
+    clusterBy?: ClusterByFn;
     /**
-     * Enables a workaround for Intel GPU compatibility issues in WebGL shader compilation.
-     * When enabled, this flag modifies how physics simulation shaders are compiled to avoid
-     * rendering problems on Intel graphics hardware.
+     * Draws a convex-hull outline around each cluster.
      *
-     * @remarks Requires a restart of NVL as shaders need to be recompiled.
+     * @note Outline color is the same as the nodes in the cluster.
+     * If the nodes in the cluster have different colors, the outline uses
+     * {@link NvlOptions.styling.overlayLineColor}.
+     * @defaultValue false
+     */
+    drawOutline?: boolean;
+    /**
+     * Fills a soft glowing halo around each cluster.
      *
-     * @deprecated This option will be removed in a future release, where WebGL will be upgraded to WebGL2,
-     * which resolves the compatibility issues with Intel GPUs.
+     * @note Halo color is the same as the nodes in the cluster.
+     * If the nodes in the cluster have different colors, the halo won't be shown.
+     * @defaultValue false
      */
-    intelWorkaround?: boolean;
+    drawHalo?: boolean;
     /**
-     * @deprecated This option will be removed in a future release. For small datasets, use the d3Force layout instead.
-     * Whether to enable automatic switching to CoseBilkent layout for small graphs.
-     * When enabled, small graphs will automatically use the CoseBilkent layout algorithm
-     * which can provide better initial positioning for smaller datasets.
-     * @defaultValue true
+     * Spring force multiplier for relationships that cross a {@link ClusteringOptions.clusterBy}
+     * cluster boundary.
+     * Capped between `0` and `1`.
+     * `0` disables cross-cluster spring pull. `1` is full strength. Intra-cluster edges are always
+     * full strength. Only applies when {@link ClusteringOptions.clusterBy} is set.
+     * @defaultValue 0
+     * @experimental
+     * @note Can cause unstable layouts when set to close to `1` in highly connected graphs.
+     */
+    crossClusterRelationshipMultiplier?: number;
+}
+/**
+ * The options for the force directed layout
+ */
+export interface ForceDirectedOptions {
+    /**
+     * How initial node positions are seeded before the physics simulation runs.
+     * @defaultValue 'box'
+     */
+    seedingMethod?: 'box' | 'circle';
+    /**
+     * Physical clustering and cluster decoration options.
      */
-    enableCytoscape?: boolean;
+    clustering?: ClusteringOptions;
 }
+/**
+ * Returns the clustering options from force-directed layout options, if present.
+ * @param layoutOptions - The layout options to read from.
+ * @returns The clustering options, or undefined when absent / not force-directed.
+ */
+export declare const getClusteringOptions: (layoutOptions?: LayoutOptions) => ClusteringOptions | undefined;
+/**
+ * Whether {@link ClusteringOptions.drawOutline} is enabled on the given layout options.
+ * @param layoutOptions - The layout options to check.
+ * @returns Whether {@link ClusteringOptions.drawOutline} is enabled on the given layout options.
+ */
+export declare const isDrawClusterOutlineEnabled: (layoutOptions?: LayoutOptions) => boolean;
+/**
+ * Whether {@link ClusteringOptions.drawHalo} is enabled on the given layout options.
+ * @param layoutOptions - The layout options to check.
+ * @returns Whether {@link ClusteringOptions.drawHalo} is enabled on the given layout options.
+ */
+export declare const isDrawClusterHaloEnabled: (layoutOptions?: LayoutOptions) => boolean;
 /**
  * The options for the hierarchical layout
  */
@@ -65,6 +134,16 @@ export interface HierarchicalOptions {
     direction?: 'up' | 'down' | 'left' | 'right';
     /** The packing method to be used */
     packing?: 'bin' | 'stack';
+    /**
+     * Optional function to group nodes into semantic clusters based on a custom identifier.
+     * Nodes returning the same string or number will be grouped together in the layout via
+     * dagre compound subgraphs. Nodes returning undefined will be treated as independent.
+     *
+     * @note Ensure this function has a stable reference to avoid evaluation on every render.
+     *
+     * @experimental
+     */
+    clusterBy?: ClusterByFn;
 }
 export declare const isHierarchicalLayoutOptions: (options: LayoutOptions) => options is HierarchicalOptions;
 /**
@@ -102,11 +181,12 @@ export declare const d3ForceLayoutType = "d3Force";
  */
 export declare const CircularLayoutType = "circular";
 /**
- * A WebGL renderer that uses the GPU for rendering.
+ * A WebGL2 renderer that uses the GPU for rendering.
  *
  * @remarks
- * This renderer has better performance than the canvas renderer,
- * but does not support captions and arrowheads.
+ * Upgraded to WebGL2 in NVL 2.0.
+ * This renderer has better performance than the canvas renderer.
+ * Supports rendering node icons and relationship arrowheads, but does not support captions.
  */
 export declare const WebGLRendererType = "webgl";
 /**
@@ -114,7 +194,7 @@ export declare const WebGLRendererType = "webgl";
  *
  * @remarks
  * This renderer has lower performance than the WebGL renderer,
- * but supports captions and arrowheads.
+ * but supports captions.
  */
 export declare const CanvasRendererType = "canvas";
 /**
@@ -183,8 +263,9 @@ export interface NvlOptions {
     /**
      * What renderer to use
      * @defaultValue 'canvas'
-     * WebGL renderer uses GPU and has better performance.
-     * Captions and arrowheads are only displayed when using the canvas or svg renderer.
+     * WebGL renderer uses GPU (WebGL2) and has better performance.
+     * Supports node icons and relationship arrowheads.
+     * Captions are only displayed when using the canvas or svg renderer.
      */
     renderer?: Renderer;
     /**
@@ -226,15 +307,36 @@ export interface NvlOptions {
         disabledItemColor?: string;
         /** The color to use for the labels of the disabled nodes and relationships */
         disabledItemFontColor?: string;
-        /** The color to use for the viewport box in the minimap */
+        /**
+         * Stroke color for overlay UI lines (e.g. minimap viewport box).
+         * Use a dark color on light backgrounds and a light color on dark backgrounds.
+         * @defaultValue `#1A1B1D`
+         */
+        overlayLineColor?: string;
+        /**
+         * The color to use for the viewport box in the minimap.
+         * @deprecated Use {@link overlayLineColor}.
+         */
         minimapViewportBoxColor?: string;
     };
     /**
-     * @internal
-     * @hidden
-     * Defines a time limit for how long layout iterations may run
+     * Target minimum presentation fps while layout is active, at the cost of stabilization speed when set higher.
+     * Budgets layout steps only. Actual fps may undershoot when rendering is expensive.
+     *
+     * @defaultValue 3
+     *
+     * @note Will be capped between 1 and 120.
+     */
+    minFps?: number;
+    /**
+     * Target maximum presentation fps while layout is active; extra time in the tick goes to layout stabilization.
+     * Budgets layout steps only. Actual fps may undershoot when rendering is expensive.
+     *
+     * @defaultValue 30
+     *
+     * @note Will be capped between 1 and 120.
      */
-    layoutTimeLimit?: number;
+    maxFps?: number;
     /**
      * Disables tracking of library usage
      * @defaultValue false
@@ -320,6 +422,6 @@ export interface NvlState {
     disabledItemStyles: DisabledItemStyles;
     defaultNodeColor: string;
     defaultRelationshipColor: string;
-    minimapViewportBoxColor: string;
+    overlayLineColor: string;
 }
 export {};

package/dist/types/modules/state/utils.d.ts

@@ -6,7 +6,7 @@ import type { NvlOptions } from './types';
  * If both caption and captions are provided, captions takes precedence.
  */
 export declare const processCaptions: (item: Partial<Node | Relationship>) => StyledCaption[];
-export declare const processColorStyles: (styling: NvlOptions["styling"]) => {
+export declare const processColorStyles: (styling?: NvlOptions["styling"]) => {
     nodeBorderStyles: {
         default: {
             rings?: {
@@ -42,5 +42,5 @@ export declare const processColorStyles: (styling: NvlOptions["styling"]) => {
     };
     defaultNodeColor: string;
     defaultRelationshipColor: string;
-    minimapViewportBoxColor: string;
+    overlayLineColor: string;
 };

package/dist/types/renderers/ClusterOverlay.d.ts

@@ -0,0 +1,73 @@
+import { type CoarsenedGraph } from '../layouts/forcedirectedlayout/clustering/types';
+import { type NvlState } from '../modules/state/types';
+import type { Node } from '../types/graph-element';
+import { type Point } from '../utils/geometry';
+type ClusterPositions = Readonly<Record<string, Point>> | (() => (Node & Point)[]);
+/**
+ * Canvas2D overlay for cluster decorations.
+ */
+export default class ClusterOverlay {
+    private readonly canvas;
+    private readonly context;
+    private readonly state;
+    private readonly stateDisposers;
+    private readonly clusterColors;
+    private clusterColorsDirty;
+    private cachedFirstSubGraphLevel;
+    private cachedIdToPosition;
+    private cachedPositionListVersion;
+    private readonly clusterGeometry;
+    private geometryPositionsVersion;
+    constructor(canvas: HTMLCanvasElement, context: CanvasRenderingContext2D, state: NvlState);
+    /** Clears the overlay. */
+    clear(): void;
+    /**
+     * Draws cluster decorations for a given multi-member first-level sun system and positions.
+     * @param subGraphs - Layout coarsening hierarchy (`subGraphs[1]` = first-level suns).
+     * @param positions - Node id to position map, or a getter for a lagged position list.
+     * @param cacheVersion - PhysLayout positions-cache version.
+     */
+    render(subGraphs: CoarsenedGraph[], positions: ClusterPositions, cacheVersion: number): void;
+    destroy(): void;
+    private resetClusterColorCache;
+    private resetGeometryCache;
+    private syncGeometryCacheVersion;
+    private resetPositionCache;
+    /**
+     * Returns an id to position map. Records are used as-is. Getters are converted once per `cacheVersion`.
+     * @param positions - Node id to position map, or a getter for a lagged position list.
+     * @param cacheVersion - PhysLayout positions-cache version; ignored for maps.
+     * @returns An id to position map.
+     */
+    private resolveIdToPosition;
+    /**
+     * Rebuilds {@link clusterColors} for every multi-member first-level sun.
+     * @param firstSubGraphLevel - `subGraphs[1]` from the current layout coarsening hierarchy.
+     */
+    private rebuildClusterColors;
+    /**
+     * Returns fitted world-space hull for a cluster, reusing the last fit while the
+     * positions cache version is unchanged (e.g. pan/zoom-only frames while layout is stable).
+     * @param sunId - Original id of the sun the hull belongs to.
+     * @param collectMembers - Builds the member disks to fit; only called on a cache miss.
+     * @returns The fitted hull, or null when the cluster cannot be fitted.
+     */
+    private getCachedHull;
+    private fillHalo;
+    private strokeOutline;
+    /**
+     * Traces a closed rounded path along the given points.
+     * @param points - The points to trace the path along.
+     */
+    private traceSmoothClosedPath;
+    private applyZoomAndPan;
+    /**
+     * Returns the shared member color when color is consistent; otherwise null.
+     * @param nodeIds - The IDs of the nodes in the cluster.
+     * @param idToItem - The map of node IDs to items.
+     * @param defaultNodeColor - The default node color.
+     * @returns The shared member color when color is consistent; otherwise null.
+     */
+    private resolveUnanimousClusterColor;
+}
+export {};