@falkordb/canvas 0.0.45 → 0.0.50

package/src/canvas.ts

@@ -1,5 +1,3 @@
-/* eslint-disable no-param-reassign */
-
 import ForceGraph from "force-graph";
 import * as d3 from "d3";
 import {
@@ -20,8 +18,10 @@ import {
   getNodeDisplayText,
   graphDataToData,
   LINK_DISTANCE,
+  NODE_SIZE,
   wrapTextForCircularNode,
 } from "./canvas-utils.js";
+import { applyGraphLayout, isForceLayout } from "./layouts.js";
 
 const PADDING = 2;
 // Arrow geometry constants (shared by self-loop and regular-link drawing paths)
@@ -29,7 +29,7 @@ const ARROW_WH_RATIO = 1.6;
 const ARROW_VLEN_RATIO = 0.2;
 // Multiplier to convert node size → cubic bezier control-point distance for self-loops
 const SELF_LOOP_CURVE_FACTOR = 11.67;
-// Base font size used for the initial measurement and for two-line text.
+// Base font size used for the initial wrap-measurement pass.
 const NODE_FONT_SIZE_BASE = 2;
 // Fraction of the chord width that single-line text should fill (0–1).
 // Leaves (1 - ratio)/2 of the radius as horizontal padding on each side.
@@ -40,6 +40,25 @@ const CHARGE_STRENGTH = -400;
 const CENTER_STRENGTH = 0.03;
 const VELOCITY_DECAY = 0.4;
 const ALPHA_MIN = 0.05;
+const NON_FORCE_CHARGE_STRENGTH = -220;
+const NON_FORCE_COLLIDE_PADDING = 18;
+const NON_FORCE_CENTER_STRENGTH = 0.02;
+const NON_FORCE_LINK_STRENGTH = 0.08;
+const NON_FORCE_TARGET_STRENGTH = 0.3;
+const NON_FORCE_VELOCITY_DECAY = 0.5;
+const NON_FORCE_ALPHA_MIN = 0.03;
+const NON_FORCE_LAYOUT_COOLDOWN_TICKS = 120;
+const NON_FORCE_DRAG_COOLDOWN_TICKS = 90;
+
+type NodePosition = { x: number; y: number };
+
+/** Axis-aligned bounding box in world-space coordinates. */
+type WorldBounds = {
+  minX: number;
+  maxX: number;
+  minY: number;
+  maxY: number;
+};
 
 // Create styles for the web component
 function createStyles(backgroundColor: string, foregroundColor: string): HTMLStyleElement {
@@ -92,6 +111,8 @@ class FalkorDBCanvas extends HTMLElement {
     foregroundColor: '#1A1A1A',
     captionsKeys: [],
     showPropertyKeyPrefix: false,
+    layoutMode: "force",
+    layoutOptions: {},
   };
 
   private nodeMode: CanvasRenderMode = 'replace';
@@ -112,14 +133,32 @@ class FalkorDBCanvas extends HTMLElement {
     }
   > = new Map();
 
+  /**
+   * Cached world-space axis-aligned bounding box of the currently visible
+   * viewport.  Updated on every zoom/pan event and on resize.
+   * `null` means culling is disabled or not yet computed.
+   */
+  private cullingBounds: WorldBounds | null = null;
+
+  /** Current zoom level, cached alongside cullingBounds. */
+  private cullingZoom: number = 1;
+
+  /** Last d3-zoom transform, cached so bounds can be recomputed on resize. */
+  private lastTransform: Transform | null = null;
+
   private onFontsLoadingDone = () => {
     this.relationshipsTextCache.clear();
     this.nodeDisplayFontSize.clear();
+    for (const node of this.data.nodes) {
+      node.displayName = ["", ""];
+    }
     this.triggerRender();
   };
 
   private viewport: ViewportState;
 
+  private shouldZoomToFitOnNonForceSettle: boolean = false;
+
   constructor() {
     super();
     this.attachShadow({ mode: "open" });
@@ -176,13 +215,13 @@ class FalkorDBCanvas extends HTMLElement {
       this.resizeObserver = null;
     }
     if (this.graph) {
-      // eslint-disable-next-line no-underscore-dangle
       this.graph._destructor();
     }
   }
 
   setConfig(config: Partial<ForceGraphConfig>) {
     this.log('Setting config:', config);
+    const layoutChanged = config.layoutMode !== undefined || config.layoutOptions !== undefined;
 
     // If captionsKeys changed, invalidate cached display names and font sizes
     // so text is recomputed with the new keys on the next render.
@@ -193,7 +232,59 @@ class FalkorDBCanvas extends HTMLElement {
       }
     }
 
-    Object.assign(this.config, config);
+    // Deep-merge largeGraph to avoid wiping sibling fields on partial updates.
+    if (config.largeGraph && typeof config.largeGraph === 'object' && this.config.largeGraph) {
+      const mergedLargeGraph = { ...this.config.largeGraph, ...config.largeGraph };
+      Object.assign(this.config, config, { largeGraph: mergedLargeGraph });
+    } else {
+      Object.assign(this.config, config);
+    }
+
+    // Recompute or clear culling bounds when largeGraph config changes.
+    if ('largeGraph' in config) {
+      if (this.config.largeGraph?.enabled) {
+        this.recomputeCullingBoundsIfNeeded();
+      } else {
+        this.cullingBounds = null;
+      }
+    }
+
+    if (layoutChanged) {
+      const previousPositions = this.getNodePositionMap();
+      if (this.isForceLayoutMode() && this.config.cooldownTicks === 0 && this.data.nodes.length > 0) {
+        this.config.cooldownTicks = undefined;
+      }
+      this.data = applyGraphLayout(this.data, this.config.layoutMode, this.config.layoutOptions);
+      const shouldAnimateNonForceLayout = this.prepareNodePositionsForCurrentLayout(previousPositions);
+      if (this.graph) {
+        this.calculateNodeDegree();
+        this.graph.graphData(this.data);
+        this.configureSimulationForCurrentLayout(shouldAnimateNonForceLayout);
+        if (this.isForceLayoutMode()) {
+          this.shouldZoomToFitOnNonForceSettle = false;
+          this.config.isLoading = this.data.nodes.length > 0;
+          this.config.onLoadingChange?.(this.config.isLoading);
+          this.updateLoadingState();
+        } else {
+          this.config.isLoading = false;
+          this.config.onLoadingChange?.(false);
+          this.updateLoadingState();
+          if (this.data.nodes.length > 0) {
+            if (shouldAnimateNonForceLayout) {
+              this.shouldZoomToFitOnNonForceSettle = true;
+            } else {
+              this.shouldZoomToFitOnNonForceSettle = false;
+              this.zoomToFit(1);
+            }
+          } else {
+            this.shouldZoomToFitOnNonForceSettle = false;
+          }
+          if (!shouldAnimateNonForceLayout) {
+            this.triggerRender();
+          }
+        }
+      }
+    }
 
     // Update event handlers if they were provided
     if (config.onNodeClick || config.onLinkClick || config.onNodeRightClick || config.onLinkRightClick ||
@@ -210,6 +301,7 @@ class FalkorDBCanvas extends HTMLElement {
     this.config.width = width;
     if (this.graph) {
       this.graph.width(width);
+      this.recomputeCullingBoundsIfNeeded();
     }
   }
 
@@ -219,6 +311,7 @@ class FalkorDBCanvas extends HTMLElement {
     this.config.height = height;
     if (this.graph) {
       this.graph.height(height);
+      this.recomputeCullingBoundsIfNeeded();
     }
   }
 
@@ -255,10 +348,12 @@ class FalkorDBCanvas extends HTMLElement {
     this.log('Setting cooldown ticks to:', ticks);
     this.config.cooldownTicks = ticks;
     if (this.graph) {
-      this.graph.cooldownTicks(ticks ?? Infinity);
+      this.graph.cooldownTicks(this.isForceLayoutMode() ? (ticks ?? Infinity) : 0);
     }
 
-    this.updateCanvasSimulationAttribute(ticks !== 0);
+    this.updateCanvasSimulationAttribute(
+      this.isForceLayoutMode() && ticks !== 0 && this.data.nodes.length > 0
+    );
   }
 
   getData(): Data {
@@ -267,17 +362,33 @@ class FalkorDBCanvas extends HTMLElement {
 
   setData(data: Data) {
     this.log('setData called with', data.nodes.length, 'nodes and', data.links.length, 'links');
-    // Convert data and apply circular layout to new nodes only
-    this.data = dataToGraphData(data);
+    const previousPositions = this.getNodePositionMap();
+    const oldNodesMap = new Map<number, GraphNode>();
+    for (const node of this.data.nodes) {
+      oldNodesMap.set(node.id, node);
+    }
+
+    // Convert data and preserve positions for existing nodes
+    this.data = dataToGraphData(data, undefined, oldNodesMap);
+    this.data = applyGraphLayout(this.data, this.config.layoutMode, this.config.layoutOptions);
+    const shouldAnimateNonForceLayout = this.prepareNodePositionsForCurrentLayout(previousPositions);
 
-    this.config.cooldownTicks = this.data.nodes.length > 0 ? undefined : 0;
-    this.config.isLoading = this.data.nodes.length > 0;
+    if (this.isForceLayoutMode()) {
+      this.shouldZoomToFitOnNonForceSettle = false;
+      this.config.cooldownTicks = this.data.nodes.length > 0 ? undefined : 0;
+      this.config.isLoading = this.data.nodes.length > 0;
+    } else {
+      this.config.cooldownTicks = 0;
+      this.config.isLoading = false;
+    }
     this.log('Loading state:', this.config.isLoading);
     this.config.onLoadingChange?.(this.config.isLoading);
 
     // Update simulation state
-    if (this.data.nodes.length > 0) {
+    if (this.data.nodes.length > 0 && this.isForceLayoutMode()) {
       this.updateCanvasSimulationAttribute(true);
+    } else {
+      this.updateCanvasSimulationAttribute(false);
     }
 
     // Initialize graph if it hasn't been initialized yet
@@ -290,12 +401,23 @@ class FalkorDBCanvas extends HTMLElement {
 
     this.log('Calculating node degrees and setting up forces');
     this.calculateNodeDegree();
-    this.setupForces();
 
     // Update graph data and properties
     this.graph
-      .graphData(this.data)
-      .cooldownTicks(this.config.cooldownTicks ?? Infinity);
+      .graphData(this.data);
+    this.configureSimulationForCurrentLayout(shouldAnimateNonForceLayout);
+
+    if (!this.isForceLayoutMode() && this.data.nodes.length > 0) {
+      if (shouldAnimateNonForceLayout) {
+        this.shouldZoomToFitOnNonForceSettle = true;
+      } else {
+        this.shouldZoomToFitOnNonForceSettle = false;
+        this.zoomToFit(1);
+        this.triggerRender();
+      }
+    } else {
+      this.shouldZoomToFitOnNonForceSettle = false;
+    }
 
     this.updateLoadingState();
   }
@@ -325,16 +447,28 @@ class FalkorDBCanvas extends HTMLElement {
 
   setGraphData(data: GraphData) {
     this.log('setGraphData called with', data.nodes.length, 'nodes and', data.links.length, 'links');
-
-    this.data = data;
+    this.data = applyGraphLayout(data, this.config.layoutMode, this.config.layoutOptions);
+    this.shouldZoomToFitOnNonForceSettle = false;
 
     if (!this.graph) return;
 
     this.calculateNodeDegree();
-    this.setupForces();
 
     this.graph
-      .graphData(this.data)
+      .graphData(this.data);
+
+    // setGraphData restores pre-positioned data — freeze simulation, just render.
+    this.config.cooldownTicks = 0;
+    this.graph.cooldownTicks(0);
+    this.updateCanvasSimulationAttribute(false);
+
+    if (this.data.nodes.length > 0) {
+      this.triggerRender();
+    }
+
+    this.config.isLoading = false;
+    this.config.onLoadingChange?.(false);
+    this.updateLoadingState();
 
     if (this.viewport) {
       this.log('Applying viewport:', this.viewport);
@@ -377,6 +511,214 @@ class FalkorDBCanvas extends HTMLElement {
     this.graph.zoomToFit(500, padding * paddingMultiplier, filter);
   }
 
+  private isForceLayoutMode() {
+    return isForceLayout(this.config.layoutMode);
+  }
+  private getNodePositionMap(): Map<number, NodePosition> {
+    const positions = new Map<number, NodePosition>();
+
+    for (const node of this.data.nodes) {
+      if (node.x === undefined || node.y === undefined) continue;
+      positions.set(node.id, { x: node.x, y: node.y });
+    }
+
+    return positions;
+  }
+
+  private getGraphCenter(positions: Map<number, NodePosition>): NodePosition | undefined {
+    if (positions.size === 0) return undefined;
+
+    let sumX = 0;
+    let sumY = 0;
+
+    for (const position of positions.values()) {
+      sumX += position.x;
+      sumY += position.y;
+    }
+
+    return {
+      x: sumX / positions.size,
+      y: sumY / positions.size,
+    };
+  }
+
+  private getConnectedExistingPosition(
+    nodeId: number,
+    previousPositions: Map<number, NodePosition>
+  ): NodePosition | undefined {
+    let sumX = 0;
+    let sumY = 0;
+    let count = 0;
+
+    for (const link of this.data.links) {
+      const sourceId = link.source.id;
+      const targetId = link.target.id;
+
+      if (sourceId === nodeId) {
+        const existingPosition = previousPositions.get(targetId);
+        if (!existingPosition) continue;
+        sumX += existingPosition.x;
+        sumY += existingPosition.y;
+        count += 1;
+      } else if (targetId === nodeId) {
+        const existingPosition = previousPositions.get(sourceId);
+        if (!existingPosition) continue;
+        sumX += existingPosition.x;
+        sumY += existingPosition.y;
+        count += 1;
+      }
+    }
+
+    if (count === 0) return undefined;
+    return {
+      x: sumX / count,
+      y: sumY / count,
+    };
+  }
+
+  private clearLayoutTargets() {
+    for (const node of this.data.nodes) {
+      node.layoutTargetX = undefined;
+      node.layoutTargetY = undefined;
+    }
+  }
+
+  private prepareNodePositionsForCurrentLayout(previousPositions: Map<number, NodePosition>): boolean {
+    if (this.isForceLayoutMode()) {
+      this.clearLayoutTargets();
+      return false;
+    }
+
+    const graphCenter = this.getGraphCenter(previousPositions);
+    let shouldAnimate = false;
+
+    for (const node of this.data.nodes) {
+      const targetX = node.x ?? 0;
+      const targetY = node.y ?? 0;
+
+      node.layoutTargetX = targetX;
+      node.layoutTargetY = targetY;
+      node.fx = undefined;
+      node.fy = undefined;
+      node.vx = 0;
+      node.vy = 0;
+
+      if (previousPositions.size === 0) {
+        node.x = targetX;
+        node.y = targetY;
+        continue;
+      }
+
+      const previousPosition = previousPositions.get(node.id)
+        ?? this.getConnectedExistingPosition(node.id, previousPositions)
+        ?? graphCenter;
+
+      if (!previousPosition) {
+        node.x = targetX;
+        node.y = targetY;
+        continue;
+      }
+
+      node.x = previousPosition.x;
+      node.y = previousPosition.y;
+
+      if (
+        Math.abs(previousPosition.x - targetX) > 0.5
+        || Math.abs(previousPosition.y - targetY) > 0.5
+      ) {
+        shouldAnimate = true;
+      }
+    }
+
+    return shouldAnimate;
+  }
+
+  private setupAnchoredLayoutForces() {
+    if (!this.graph) return;
+
+    const linkForce = this.graph.d3Force("link");
+    if (linkForce) {
+      linkForce
+        .distance((link: GraphLink) => {
+          const sourceSize = link.source.size;
+          const targetSize = link.target.size;
+          return sourceSize + targetSize + LINK_DISTANCE * 1.6;
+        })
+        .strength(NON_FORCE_LINK_STRENGTH);
+    }
+
+    this.graph.d3Force(
+      "collide",
+      d3.forceCollide((node: GraphNode) => node.size + NON_FORCE_COLLIDE_PADDING)
+    );
+
+    this.graph.d3Force(
+      "centerX",
+      d3.forceX(0).strength(NON_FORCE_CENTER_STRENGTH)
+    );
+
+    this.graph.d3Force(
+      "centerY",
+      d3.forceY(0).strength(NON_FORCE_CENTER_STRENGTH)
+    );
+
+    this.graph.d3Force(
+      "layoutTargetX",
+      d3.forceX((node: GraphNode) => node.layoutTargetX ?? node.x ?? 0).strength(NON_FORCE_TARGET_STRENGTH)
+    );
+
+    this.graph.d3Force(
+      "layoutTargetY",
+      d3.forceY((node: GraphNode) => node.layoutTargetY ?? node.y ?? 0).strength(NON_FORCE_TARGET_STRENGTH)
+    );
+
+    const chargeForce = this.graph.d3Force("charge");
+    if (chargeForce) {
+      chargeForce.strength(NON_FORCE_CHARGE_STRENGTH);
+    }
+
+    this.graph.d3VelocityDecay(NON_FORCE_VELOCITY_DECAY);
+    this.graph.d3AlphaMin(NON_FORCE_ALPHA_MIN);
+  }
+
+  private startNonForceSettleAnimation(cooldownTicks: number) {
+    if (!this.graph || this.data.nodes.length === 0 || this.isForceLayoutMode()) return;
+
+    this.graph.cooldownTicks(cooldownTicks);
+    this.updateCanvasSimulationAttribute(true);
+    this.graph.d3ReheatSimulation();
+  }
+
+  private applyLayoutTargets() {
+    for (const node of this.data.nodes) {
+      if (node.layoutTargetX === undefined || node.layoutTargetY === undefined) continue;
+      node.x = node.layoutTargetX;
+      node.y = node.layoutTargetY;
+      node.vx = 0;
+      node.vy = 0;
+    }
+  }
+
+  private configureSimulationForCurrentLayout(shouldAnimateNonForceLayout = false) {
+    if (!this.graph) return;
+
+    if (this.isForceLayoutMode()) {
+      this.setupForces();
+      const cooldownTicks = this.config.cooldownTicks ?? Infinity;
+      this.graph.cooldownTicks(cooldownTicks);
+      this.updateCanvasSimulationAttribute(cooldownTicks !== 0 && this.data.nodes.length > 0);
+      return;
+    }
+    this.setupAnchoredLayoutForces();
+    if (shouldAnimateNonForceLayout) {
+      this.startNonForceSettleAnimation(NON_FORCE_LAYOUT_COOLDOWN_TICKS);
+      return;
+    }
+
+    this.graph.cooldownTicks(0);
+    this.updateCanvasSimulationAttribute(false);
+  }
+
   private triggerRender() {
     if (!this.graph || this.graph.cooldownTicks() !== 0) return;
 
@@ -516,6 +858,7 @@ class FalkorDBCanvas extends HTMLElement {
         if (this.graph && width > 0 && height > 0) {
           this.log('Container resized to:', width, 'x', height);
           this.graph.width(width).height(height);
+          this.recomputeCullingBoundsIfNeeded();
         }
       }
     });
@@ -531,7 +874,6 @@ class FalkorDBCanvas extends HTMLElement {
 
     // Initialize force-graph
     // Cast to any for the factory call pattern, result is properly typed as ForceGraphInstance
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     this.graph = (ForceGraph as any)()(this.container)
       .width(this.config.width || 800)
       .height(this.config.height || 600)
@@ -548,7 +890,7 @@ class FalkorDBCanvas extends HTMLElement {
       .linkCurvature("curve")
       .linkVisibility("visible")
       .nodeVisibility("visible")
-      .cooldownTicks(this.config.cooldownTicks ?? Infinity) // undefined = infinite
+      .cooldownTicks(this.isForceLayoutMode() ? (this.config.cooldownTicks ?? Infinity) : 0) // undefined = infinite
       .cooldownTime(this.config.cooldownTime ?? 2000)
       .enableNodeDrag(true)
       .enableZoomInteraction(true)
@@ -578,6 +920,12 @@ class FalkorDBCanvas extends HTMLElement {
           this.config.onNodeHover(node);
         }
       })
+      .onNodeDrag((node: GraphNode) => {
+        this.handleNodeDrag(node);
+      })
+      .onNodeDragEnd((node: GraphNode) => {
+        this.handleNodeDragEnd(node);
+      })
       .onLinkHover((link: GraphLink | null) => {
         if (this.config.onLinkHover) {
           this.config.onLinkHover(link);
@@ -594,6 +942,7 @@ class FalkorDBCanvas extends HTMLElement {
         }
       })
       .onZoom((transform: Transform) => {
+        this.updateCullingBounds(transform);
         if (this.config.onZoom) {
           this.config.onZoom(transform);
         }
@@ -633,8 +982,7 @@ class FalkorDBCanvas extends HTMLElement {
         }
       });
 
-    // Setup forces
-    this.setupForces();
+    this.configureSimulationForCurrentLayout();
     this.log('Force graph initialization complete');
   }
 
@@ -645,6 +993,9 @@ class FalkorDBCanvas extends HTMLElement {
     if (!linkForce) return;
     if (!this.graph) return;
 
+    this.graph.d3Force("layoutTargetX", null);
+    this.graph.d3Force("layoutTargetY", null);
+
     // distance based on node size + constant
     linkForce
       .distance((link: GraphLink) => {
@@ -688,6 +1039,152 @@ class FalkorDBCanvas extends HTMLElement {
     this.log('Force simulation setup complete');
   }
 
+  /**
+   * Recompute the world-space culling bounds from the d3-zoom transform delivered
+   * by force-graph's `onZoom` callback.
+   *
+   * The d3-zoom transform maps world → screen as:
+   *   screen_x = world_x * k + tx
+   *   screen_y = world_y * k + ty
+   * Inverting for the canvas edges (screen_x ∈ [0, W], screen_y ∈ [0, H]):
+   *   world_x ∈ [(0 − tx) / k,  (W − tx) / k]
+   *   world_y ∈ [(0 − ty) / k,  (H − ty) / k]
+   */
+  private updateCullingBounds(transform: Transform) {
+    this.lastTransform = transform;
+    if (!this.config.largeGraph?.enabled) {
+      this.cullingBounds = null;
+      return;
+    }
+
+    const w = this.graph?.width() ?? 0;
+    const h = this.graph?.height() ?? 0;
+    const { k, x: tx, y: ty } = transform;
+
+    if (k <= 0 || w <= 0 || h <= 0) {
+      this.cullingBounds = null;
+      this.cullingZoom = 1;
+      return;
+    }
+
+    const padding = this.config.largeGraph?.viewportPadding ?? 0;
+
+    this.cullingBounds = {
+      minX: -tx / k - padding,
+      maxX: (w - tx) / k + padding,
+      minY: -ty / k - padding,
+      maxY: (h - ty) / k + padding,
+    };
+    this.cullingZoom = k;
+  }
+
+  /** Recompute culling bounds using the last known transform (e.g. after resize). */
+  private recomputeCullingBoundsIfNeeded() {
+    if (!this.config.largeGraph?.enabled) return;
+    if (this.lastTransform) {
+      this.updateCullingBounds(this.lastTransform);
+    } else if (this.graph) {
+      // Seed initial transform from current graph state before first onZoom fires.
+      const k = this.graph.zoom() ?? 1;
+      const center = this.graph.centerAt() ?? { x: 0, y: 0 };
+      const w = this.graph.width() ?? 0;
+      const h = this.graph.height() ?? 0;
+      if (k > 0 && w > 0 && h > 0) {
+        const tx = w / 2 - center.x * k;
+        const ty = h / 2 - center.y * k;
+        this.updateCullingBounds({ k, x: tx, y: ty });
+      }
+    }
+  }
+
+  /**
+   * Returns `true` when the node is (at least partially) inside the current
+   * culling viewport, or when culling is disabled / bounds are not yet known.
+   */
+  private isNodeInCullingBounds(node: GraphNode): boolean {
+    if (!this.cullingBounds) return true;
+    const { minX, maxX, minY, maxY } = this.cullingBounds;
+    const r = node.size + PADDING;
+    const x = node.x ?? 0;
+    const y = node.y ?? 0;
+    return x + r >= minX && x - r <= maxX && y + r >= minY && y - r <= maxY;
+  }
+
+  /**
+   * Returns `true` when a link's visual representation overlaps the current
+   * culling viewport, or when culling is disabled / bounds are not yet known.
+   *
+   * For straight / quadratic-bezier links the test uses the convex-hull bounding
+   * box of (source, control point, target), which is always a conservative
+   * (never-false-negative) bound.  For self-loops the test uses a square of
+   * side ≈ the loop diameter centred on the node.
+   */
+  private isLinkInCullingBounds(link: GraphLink): boolean {
+    if (!this.cullingBounds) return true;
+    const { minX, maxX, minY, maxY } = this.cullingBounds;
+
+    const sx = link.source.x ?? 0;
+    const sy = link.source.y ?? 0;
+    const ex = link.target.x ?? 0;
+    const ey = link.target.y ?? 0;
+
+    if (link.source.id === link.target.id) {
+      // Self-loop: the cubic bezier extends roughly |curve| * nodeSize * factor
+      // away from the node centre. Use that as a conservative radius.
+      const nodeSize = link.source.size || NODE_SIZE;
+      const loopRadius = Math.abs(link.curve || 1) * nodeSize * SELF_LOOP_CURVE_FACTOR;
+      return (
+        sx + loopRadius >= minX && sx - loopRadius <= maxX &&
+        sy + loopRadius >= minY && sy - loopRadius <= maxY
+      );
+    }
+
+    // Compute quadratic-bezier control point (same formula as drawLink).
+    const dx = ex - sx;
+    const dy = ey - sy;
+    const distance = Math.sqrt(dx * dx + dy * dy);
+    if (distance === 0) {
+      // Co-located nodes: just check the point.
+      return sx >= minX && sx <= maxX && sy >= minY && sy <= maxY;
+    }
+
+    const curvature = link.curve ?? 0;
+    const perpX = dy / distance;
+    const perpY = -dx / distance;
+    const cx = (sx + ex) / 2 + perpX * curvature * distance;
+    const cy = (sy + ey) / 2 + perpY * curvature * distance;
+
+    // Convex-hull AABB of the three control points.
+    const lMinX = Math.min(sx, ex, cx);
+    const lMaxX = Math.max(sx, ex, cx);
+    const lMinY = Math.min(sy, ey, cy);
+    const lMaxY = Math.max(sy, ey, cy);
+
+    return lMaxX >= minX && lMinX <= maxX && lMaxY >= minY && lMinY <= maxY;
+  }
+
+  private handleNodeDrag(node: GraphNode) {
+    if (this.isForceLayoutMode()) return;
+    if (node.x === undefined || node.y === undefined) return;
+
+    node.layoutTargetX = node.x;
+    node.layoutTargetY = node.y;
+    this.shouldZoomToFitOnNonForceSettle = false;
+    this.startNonForceSettleAnimation(NON_FORCE_DRAG_COOLDOWN_TICKS);
+  }
+
+  private handleNodeDragEnd(node: GraphNode) {
+    if (this.isForceLayoutMode()) return;
+    if (node.x === undefined || node.y === undefined) return;
+
+    node.layoutTargetX = node.x;
+    node.layoutTargetY = node.y;
+    node.fx = undefined;
+    node.fy = undefined;
+    this.shouldZoomToFitOnNonForceSettle = false;
+    this.startNonForceSettleAnimation(NON_FORCE_DRAG_COOLDOWN_TICKS);
+  }
+
   private drawNode(node: GraphNode, ctx: CanvasRenderingContext2D) {
 
     if (node.x === undefined || node.y === undefined) {
@@ -695,6 +1192,9 @@ class FalkorDBCanvas extends HTMLElement {
       node.y = 0;
     }
 
+    // Viewport culling: skip nodes that are entirely outside the visible area.
+    if (this.config.largeGraph?.enabled && !this.isNodeInCullingBounds(node)) return;
+
     ctx.lineWidth = this.config.isNodeSelected?.(node) ? 1 : 0.5;
     ctx.strokeStyle = this.config.foregroundColor;
     ctx.fillStyle = node.color;
@@ -709,6 +1209,12 @@ class FalkorDBCanvas extends HTMLElement {
     ctx.arc(node.x, node.y, node.size, 0, 2 * Math.PI, false);
     ctx.fill();
 
+    // Low-zoom optimisation: skip labels when they would be too small to read.
+    const skipLabels = this.config.largeGraph?.enabled &&
+      (this.config.largeGraph?.skipLabelsAtLowZoom ?? true) &&
+      this.cullingZoom < (this.config.largeGraph?.lowZoomThreshold ?? 0.5);
+    if (skipLabels) return;
+
     // Draw text
     ctx.fillStyle = getContrastTextColor(node.color);
     ctx.textAlign = "center";
@@ -725,32 +1231,49 @@ class FalkorDBCanvas extends HTMLElement {
       [line1, line2] = wrapTextForCircularNode(ctx, text, textRadius);
 
       let chosenSize = NODE_FONT_SIZE_BASE;
+      // Measure at a large reference size (20px) where canvas metrics are
+      // precise, then compute the exact scale to fill the node.
+      const REF = 20;
+      ctx.font = `400 ${REF}px SofiaSans`;
+      // Switch to "left" for measurement: actualBoundingBoxLeft/Right are
+      // unreliable with textAlign="center" and can double on some engines.
+      ctx.textAlign = "left";
+      const refMetrics = ctx.measureText(line1);
+      // Use the actual visual bounding box (not advance width) so glyphs
+      // with overshoot (e.g. "7") are fully accounted for.
+      const visualWidth = (refMetrics.actualBoundingBoxLeft ?? 0)
+        + (refMetrics.actualBoundingBoxRight ?? 0);
+      let refWidth = Math.max(visualWidth, refMetrics.width);
+      const singleLineHeight = (refMetrics.actualBoundingBoxAscent ?? 0)
+        + (refMetrics.actualBoundingBoxDescent ?? 0);
+
+      let refHeight: number;
       if (!line2) {
-        // Single-line: measure at a large reference size (20px) where canvas
-        // metrics are precise, then compute the exact scale to fill the node.
-        const REF = 20;
-        ctx.font = `400 ${REF}px SofiaSans`;
-        const refMetrics = ctx.measureText(line1);
-        // Use the actual visual bounding box (not advance width) so glyphs
-        // with overshoot (e.g. "7") are fully accounted for.
-        const visualWidth = (refMetrics.actualBoundingBoxLeft ?? 0)
-          + (refMetrics.actualBoundingBoxRight ?? 0);
-        const refWidth = Math.max(visualWidth, refMetrics.width);
-        const refHeight = (refMetrics.actualBoundingBoxAscent ?? 0)
-          + (refMetrics.actualBoundingBoxDescent ?? 0);
-
-        // Inscribed-rectangle-in-circle constraint: every corner of the text
-        // bounding box must lie inside the circle, i.e.
-        //   sqrt((w/2)² + (h/2)²) ≤ r
-        // Solving for the uniform scale factor s:
-        //   s = 2·r / sqrt(refWidth² + refHeight²)
-        const r = NODE_TEXT_FILL_RATIO * textRadius;
-        if (refWidth > 0 && refHeight > 0) {
-          const diagonal = Math.sqrt(refWidth * refWidth + refHeight * refHeight);
-          chosenSize = REF * (2 * r / diagonal);
-        } else if (refWidth > 0) {
-          chosenSize = REF * (2 * r / refWidth);
-        }
+        refHeight = singleLineHeight;
+      } else {
+        // Two-line: use the wider line and account for the vertical span
+        // of both lines including the 1.5× spacing used by the rendering code.
+        const m2 = ctx.measureText(line2);
+        const vis2 = Math.max(
+          (m2.actualBoundingBoxLeft ?? 0) + (m2.actualBoundingBoxRight ?? 0),
+          m2.width,
+        );
+        refWidth = Math.max(refWidth, vis2);
+        refHeight = singleLineHeight * 2.5;
+      }
+      ctx.textAlign = "center";
+
+      // Inscribed-rectangle-in-circle constraint: every corner of the text
+      // bounding box must lie inside the circle, i.e.
+      //   sqrt((w/2)² + (h/2)²) ≤ r
+      // Solving for the uniform scale factor s:
+      //   s = 2·r / sqrt(refWidth² + refHeight²)
+      const r = NODE_TEXT_FILL_RATIO * textRadius;
+      if (refWidth > 0 && refHeight > 0) {
+        const diagonal = Math.sqrt(refWidth * refWidth + refHeight * refHeight);
+        chosenSize = REF * (2 * r / diagonal);
+      } else if (refWidth > 0) {
+        chosenSize = REF * (2 * r / refWidth);
       }
 
       ctx.font = `400 ${chosenSize}px SofiaSans`;
@@ -788,6 +1311,9 @@ class FalkorDBCanvas extends HTMLElement {
       node.y = 0;
     };
 
+    // Viewport culling: skip hit-test painting for offscreen nodes.
+    if (this.config.largeGraph?.enabled && !this.isNodeInCullingBounds(node)) return;
+
     const radius = node.size + PADDING;
 
     ctx.fillStyle = color;
@@ -807,6 +1333,11 @@ class FalkorDBCanvas extends HTMLElement {
       end.y = 0;
     }
 
+    // Viewport culling: skip links whose visual extent is entirely outside the
+    // visible area.  The check is conservative (convex-hull AABB) so it never
+    // produces false negatives.
+    if (this.config.largeGraph?.enabled && !this.isLinkInCullingBounds(link)) return;
+
     let textX;
     let textY;
     let angle;
@@ -814,13 +1345,19 @@ class FalkorDBCanvas extends HTMLElement {
     const isLinkSelected = this.config.isLinkSelected?.(link) ?? false;
     const arrowLen = isLinkSelected ? 4 : 2;
 
+    // Low-zoom flags – evaluated once per link draw.
+    const lowZoomThreshold = this.config.largeGraph?.lowZoomThreshold ?? 0.5;
+    const atLowZoom = this.config.largeGraph?.enabled && this.cullingZoom < lowZoomThreshold;
+    const skipArrows = atLowZoom && (this.config.largeGraph?.skipArrowsAtLowZoom ?? true);
+    const skipLinkLabels = atLowZoom && (this.config.largeGraph?.skipLinkLabelsAtLowZoom ?? true);
+
     // Deferred arrowhead — drawn after the label so it is never covered by
     // the label background rect (which happens for short links where the
     // bezier midpoint and the arrow tip are at almost the same position).
     let pendingArrow: { tipX: number; tipY: number; nx: number; ny: number; arrowLen: number; arrowHalfWidth: number } | null = null;
 
     if (start.id === end.id) {
-      const nodeSize = start.size || 6;
+      const nodeSize = start.size || NODE_SIZE;
       const d = (link.curve || 0) * nodeSize * SELF_LOOP_CURVE_FACTOR;
 
       ctx.lineWidth = (isLinkSelected ? 2 : 1) / globalScale;
@@ -891,7 +1428,7 @@ class FalkorDBCanvas extends HTMLElement {
       // Guard against zero-length tangent vector (e.g. when d ≈ 0) to avoid NaN
       // normals and invalid arrowhead geometry. Also skip when d is too small to
       // place the arrowhead at the node border (canReachBorder is false).
-      if (tLen !== 0 && canReachBorder) {
+      if (!skipArrows && tLen !== 0 && canReachBorder) {
         const nx = tdx / tLen;
         const ny = tdy / tLen;
         pendingArrow = { tipX, tipY, nx, ny, arrowLen, arrowHalfWidth };
@@ -947,7 +1484,7 @@ class FalkorDBCanvas extends HTMLElement {
       const arrowHalfWidth = arrowLen / ARROW_WH_RATIO / 2;
 
       // Target-side clip: find t where bezier enters target node border + PADDING
-      const endNodeSize = end.size || 6;
+      const endNodeSize = end.size || NODE_SIZE;
       const borderRadius = endNodeSize + (this.config.isNodeSelected?.(end) ? 1 : 0.5) + PADDING;
       const borderRadiusSq = borderRadius * borderRadius;
 
@@ -975,7 +1512,7 @@ class FalkorDBCanvas extends HTMLElement {
       const tipY = uArrow * uArrow * start.y + 2 * uArrow * tArrow * controlY + tArrow * tArrow * end.y;
 
       // Source-side clip: find t where bezier exits source node border + PADDING
-      const startNodeSize = start.size || 6;
+      const startNodeSize = start.size || NODE_SIZE;
       const srcBorderRadius = startNodeSize + (this.config.isNodeSelected?.(start) ? 1 : 0.5) + PADDING;
       const srcBorderRadiusSq = srcBorderRadius * srcBorderRadius;
 
@@ -1026,7 +1563,7 @@ class FalkorDBCanvas extends HTMLElement {
       const aty = 2 * uArrow * (controlY - start.y) + 2 * tArrow * (end.y - controlY);
       const atLen = Math.sqrt(atx * atx + aty * aty);
 
-      if (atLen !== 0) {
+      if (!skipArrows && atLen !== 0) {
         const nx = atx / atLen;
         const ny = aty / atLen;
         pendingArrow = { tipX, tipY, nx, ny, arrowLen, arrowHalfWidth };
@@ -1038,52 +1575,54 @@ class FalkorDBCanvas extends HTMLElement {
     // Draw text with alphabetic baseline, positioned so visual center is at y=0
     ctx.textBaseline = "alphabetic";
 
-    // Separate cache entries per weight so each state is measured with its own
-    // font, giving equal visual padding regardless of selection state.
-    const cacheKey = `${link.relationship}_${isLinkSelected ? "700" : "400"}`;
-    let cached = this.relationshipsTextCache.get(cacheKey);
-
-    if (!cached) {
-      // ctx.font is already set to the correct weight above; measure it directly.
-      const metrics = ctx.measureText(link.relationship);
-      // Use actual ink bounds for vertical metrics; fontBoundingBox* is the full
-      // line-box and adds excessive space for lighter weights.
-      // Use metrics.width for horizontal extent: actualBoundingBoxLeft/Right are
-      // unreliable with textAlign="center" and can double the value on some engines.
-      const inkAscent = metrics.actualBoundingBoxAscent ?? metrics.fontBoundingBoxAscent;
-      const inkDescent = metrics.actualBoundingBoxDescent ?? metrics.fontBoundingBoxDescent;
-      const inkWidth = metrics.width;
-      const bgPadding = 0.3;
-
-      cached = {
-        textWidth: inkWidth + bgPadding * 2,
-        textHeight: inkAscent + inkDescent + bgPadding * 2,
-        // Shift baseline up so the ink block is centred inside the bg rect.
-        textYOffset: (inkAscent - inkDescent) / 2,
-      };
-      this.relationshipsTextCache.set(cacheKey, cached);
-    }
+    if (!skipLinkLabels) {
+      // Separate cache entries per weight so each state is measured with its own
+      // font, giving equal visual padding regardless of selection state.
+      const cacheKey = `${link.relationship}_${isLinkSelected ? "700" : "400"}`;
+      let cached = this.relationshipsTextCache.get(cacheKey);
+
+      if (!cached) {
+        // ctx.font is already set to the correct weight above; measure it directly.
+        const metrics = ctx.measureText(link.relationship);
+        // Use actual ink bounds for vertical metrics; fontBoundingBox* is the full
+        // line-box and adds excessive space for lighter weights.
+        // Use metrics.width for horizontal extent: actualBoundingBoxLeft/Right are
+        // unreliable with textAlign="center" and can double the value on some engines.
+        const inkAscent = metrics.actualBoundingBoxAscent ?? metrics.fontBoundingBoxAscent;
+        const inkDescent = metrics.actualBoundingBoxDescent ?? metrics.fontBoundingBoxDescent;
+        const inkWidth = metrics.width;
+        const bgPadding = 0.3;
+
+        cached = {
+          textWidth: inkWidth + bgPadding * 2,
+          textHeight: inkAscent + inkDescent + bgPadding * 2,
+          // Shift baseline up so the ink block is centred inside the bg rect.
+          textYOffset: (inkAscent - inkDescent) / 2,
+        };
+        this.relationshipsTextCache.set(cacheKey, cached);
+      }
 
-    const { textWidth, textHeight, textYOffset } = cached;
+      const { textWidth, textHeight, textYOffset } = cached;
 
-    ctx.save();
-    ctx.translate(textX, textY);
-    ctx.rotate(angle);
+      ctx.save();
+      ctx.translate(textX, textY);
+      ctx.rotate(angle);
 
-    // Draw background centered on the link line (y=0)
-    ctx.fillStyle = this.config.backgroundColor;
+      // Draw background centered on the link line (y=0)
+      ctx.fillStyle = this.config.backgroundColor;
 
-    // Offset background to match text visual center
-    ctx.fillRect(
-      -textWidth / 2,
-      -textHeight / 2,
-      textWidth,
-      textHeight
-    );
+      // Offset background to match text visual center
+      ctx.fillRect(
+        -textWidth / 2,
+        -textHeight / 2,
+        textWidth,
+        textHeight
+      );
 
-    ctx.fillStyle = getContrastTextColor(this.config.backgroundColor);
-    ctx.fillText(link.relationship, 0, textYOffset);
-    ctx.restore();
+      ctx.fillStyle = getContrastTextColor(this.config.backgroundColor);
+      ctx.fillText(link.relationship, 0, textYOffset);
+      ctx.restore();
+    }
 
     // Draw arrowhead last so it always appears on top of the label background.
     if (pendingArrow) {
@@ -1104,6 +1643,9 @@ class FalkorDBCanvas extends HTMLElement {
 
     if (start.x == null || start.y == null || end.x == null || end.y == null) return;
 
+    // Viewport culling: skip hit-test painting for offscreen links.
+    if (this.config.largeGraph?.enabled && !this.isLinkInCullingBounds(link)) return;
+
     ctx.strokeStyle = color;
     const basePointerWidth = 10; // Desired on-screen pointer area thickness
     const transform = typeof ctx.getTransform === 'function' ? ctx.getTransform() : null;
@@ -1119,7 +1661,7 @@ class FalkorDBCanvas extends HTMLElement {
 
     if (start.id === end.id) {
       // Self-loop: replicate exact cubic bezier clip from drawLink
-      const nodeSize = start.size || 6;
+      const nodeSize = start.size || NODE_SIZE;
       const d = (link.curve || 0) * nodeSize * SELF_LOOP_CURVE_FACTOR;
 
       const nodeStrokeWidth = this.config.isNodeSelected?.(start) ? 1 : 0.5;
@@ -1170,7 +1712,7 @@ class FalkorDBCanvas extends HTMLElement {
         const controlY = (start.y + end.y) / 2 + perpY * curvature * distance;
 
         // Use the same borderRadius and binary-search clip as drawLink
-        const endNodeSize = end.size || 6;
+        const endNodeSize = end.size || NODE_SIZE;
         const borderRadius = endNodeSize + (this.config.isNodeSelected?.(end) ? 1 : 0.5) + PADDING;
         const borderRadiusSq = borderRadius * borderRadius;
 
@@ -1197,7 +1739,7 @@ class FalkorDBCanvas extends HTMLElement {
         const tipY = uArrow * uArrow * start.y + 2 * uArrow * tArrow * controlY + tArrow * tArrow * end.y;
 
         // Source-side clip: mirror of drawLink source gap
-        const startNodeSize = start.size || 6;
+        const startNodeSize = start.size || NODE_SIZE;
         const srcBorderRadius = startNodeSize + (this.config.isNodeSelected?.(start) ? 1 : 0.5) + PADDING;
         const srcBorderRadiusSq = srcBorderRadius * srcBorderRadius;
 
@@ -1254,6 +1796,16 @@ class FalkorDBCanvas extends HTMLElement {
     if (!this.graph) return;
 
     this.log('Engine stopped');
+    if (!this.isForceLayoutMode()) {
+      this.applyLayoutTargets();
+      this.graph.cooldownTicks(0);
+      this.updateCanvasSimulationAttribute(false);
+      if (this.shouldZoomToFitOnNonForceSettle && this.data.nodes.length > 0) {
+        this.zoomToFit(1);
+      }
+      this.shouldZoomToFitOnNonForceSettle = false;
+      return;
+    }
     // If already stopped, just ensure any leftover loading state is cleared and return
     if (this.config.cooldownTicks === 0) {
       if (this.config.isLoading) {
@@ -1326,6 +1878,12 @@ class FalkorDBCanvas extends HTMLElement {
           this.config.onNodeHover(node);
         }
       })
+      .onNodeDrag((node: GraphNode) => {
+        this.handleNodeDrag(node);
+      })
+      .onNodeDragEnd((node: GraphNode) => {
+        this.handleNodeDragEnd(node);
+      })
       .onLinkHover((link: GraphLink | null) => {
         if (this.config.onLinkHover) {
           this.config.onLinkHover(link);
@@ -1342,6 +1900,7 @@ class FalkorDBCanvas extends HTMLElement {
         }
       })
       .onZoom((transform: Transform) => {
+        this.updateCullingBounds(transform);
         if (this.config.onZoom) {
           this.config.onZoom(transform);
         }
@@ -1372,7 +1931,9 @@ class FalkorDBCanvas extends HTMLElement {
         this.config.node!.nodePointerAreaPaint(node, color, ctx);
       });
     } else {
-      this.graph.nodePointerAreaPaint();
+      this.graph.nodePointerAreaPaint((node: GraphNode, color: string, ctx: CanvasRenderingContext2D) => {
+        this.pointerNode(node, color, ctx);
+      });
     }
 
     if (this.config.link) {
@@ -1380,7 +1941,9 @@ class FalkorDBCanvas extends HTMLElement {
         this.config.link!.linkPointerAreaPaint(link, color, ctx);
       });
     } else {
-      this.graph.linkPointerAreaPaint();
+      this.graph.linkPointerAreaPaint((link: GraphLink, color: string, ctx: CanvasRenderingContext2D) => {
+        this.pointerLink(link, color, ctx);
+      });
     }
   }