@falkordb/canvas 0.0.45 → 0.0.50

package/dist/canvas.js

@@ -1,14 +1,14 @@
-/* eslint-disable no-param-reassign */
 import ForceGraph from "force-graph";
 import * as d3 from "d3";
-import { dataToGraphData, getContrastTextColor, getNodeDisplayText, graphDataToData, LINK_DISTANCE, wrapTextForCircularNode, } from "./canvas-utils.js";
+import { dataToGraphData, getContrastTextColor, 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)
 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.
@@ -18,6 +18,15 @@ 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;
 // Create styles for the web component
 function createStyles(backgroundColor, foregroundColor) {
     const style = document.createElement("style");
@@ -63,6 +72,8 @@ class FalkorDBCanvas extends HTMLElement {
             foregroundColor: '#1A1A1A',
             captionsKeys: [],
             showPropertyKeyPrefix: false,
+            layoutMode: "force",
+            layoutOptions: {},
         };
         this.nodeMode = 'replace';
         this.linkMode = 'replace';
@@ -70,11 +81,25 @@ class FalkorDBCanvas extends HTMLElement {
         // Per-node font size cache: computed once per node, read every frame.
         this.nodeDisplayFontSize = new Map();
         this.relationshipsTextCache = 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.
+         */
+        this.cullingBounds = null;
+        /** Current zoom level, cached alongside cullingBounds. */
+        this.cullingZoom = 1;
+        /** Last d3-zoom transform, cached so bounds can be recomputed on resize. */
+        this.lastTransform = null;
         this.onFontsLoadingDone = () => {
             this.relationshipsTextCache.clear();
             this.nodeDisplayFontSize.clear();
+            for (const node of this.data.nodes) {
+                node.displayName = ["", ""];
+            }
             this.triggerRender();
         };
+        this.shouldZoomToFitOnNonForceSettle = false;
         this.attachShadow({ mode: "open" });
     }
     /**
@@ -122,12 +147,12 @@ class FalkorDBCanvas extends HTMLElement {
             this.resizeObserver = null;
         }
         if (this.graph) {
-            // eslint-disable-next-line no-underscore-dangle
             this.graph._destructor();
         }
     }
     setConfig(config) {
         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.
         if (config.captionsKeys && JSON.stringify(config.captionsKeys) !== JSON.stringify(this.config.captionsKeys)) {
@@ -136,7 +161,62 @@ class FalkorDBCanvas extends HTMLElement {
                 node.displayName = ["", ""];
             }
         }
-        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 ||
             config.onNodeHover || config.onLinkHover || config.onBackgroundClick || config.onBackgroundRightClick || config.onZoom ||
@@ -152,6 +232,7 @@ class FalkorDBCanvas extends HTMLElement {
         this.config.width = width;
         if (this.graph) {
             this.graph.width(width);
+            this.recomputeCullingBoundsIfNeeded();
         }
     }
     setHeight(height) {
@@ -161,6 +242,7 @@ class FalkorDBCanvas extends HTMLElement {
         this.config.height = height;
         if (this.graph) {
             this.graph.height(height);
+            this.recomputeCullingBoundsIfNeeded();
         }
     }
     setBackgroundColor(color) {
@@ -197,25 +279,42 @@ 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() {
         return graphDataToData(this.data);
     }
     setData(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);
-        this.config.cooldownTicks = this.data.nodes.length > 0 ? undefined : 0;
-        this.config.isLoading = this.data.nodes.length > 0;
+        const previousPositions = this.getNodePositionMap();
+        const oldNodesMap = new Map();
+        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);
+        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
         if (!this.graph && this.container) {
             this.log('Initializing graph');
@@ -225,11 +324,23 @@ class FalkorDBCanvas extends HTMLElement {
             return;
         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();
     }
     getViewport() {
@@ -253,13 +364,23 @@ class FalkorDBCanvas extends HTMLElement {
     }
     setGraphData(data) {
         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);
+        // 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);
             this.graph.zoom(this.viewport.zoom, 0);
@@ -294,6 +415,167 @@ class FalkorDBCanvas extends HTMLElement {
         // Use the force-graph's built-in zoomToFit method
         this.graph.zoomToFit(500, padding * paddingMultiplier, filter);
     }
+    isForceLayoutMode() {
+        return isForceLayout(this.config.layoutMode);
+    }
+    getNodePositionMap() {
+        const positions = new Map();
+        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;
+    }
+    getGraphCenter(positions) {
+        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,
+        };
+    }
+    getConnectedExistingPosition(nodeId, previousPositions) {
+        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,
+        };
+    }
+    clearLayoutTargets() {
+        for (const node of this.data.nodes) {
+            node.layoutTargetX = undefined;
+            node.layoutTargetY = undefined;
+        }
+    }
+    prepareNodePositionsForCurrentLayout(previousPositions) {
+        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;
+    }
+    setupAnchoredLayoutForces() {
+        if (!this.graph)
+            return;
+        const linkForce = this.graph.d3Force("link");
+        if (linkForce) {
+            linkForce
+                .distance((link) => {
+                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) => 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) => node.layoutTargetX ?? node.x ?? 0).strength(NON_FORCE_TARGET_STRENGTH));
+        this.graph.d3Force("layoutTargetY", d3.forceY((node) => 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);
+    }
+    startNonForceSettleAnimation(cooldownTicks) {
+        if (!this.graph || this.data.nodes.length === 0 || this.isForceLayoutMode())
+            return;
+        this.graph.cooldownTicks(cooldownTicks);
+        this.updateCanvasSimulationAttribute(true);
+        this.graph.d3ReheatSimulation();
+    }
+    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;
+        }
+    }
+    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);
+    }
     triggerRender() {
         if (!this.graph || this.graph.cooldownTicks() !== 0)
             return;
@@ -408,6 +690,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();
                 }
             }
         });
@@ -420,7 +703,6 @@ class FalkorDBCanvas extends HTMLElement {
         this.calculateNodeDegree();
         // 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()(this.container)
             .width(this.config.width || 800)
             .height(this.config.height || 600)
@@ -435,7 +717,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)
@@ -464,6 +746,12 @@ class FalkorDBCanvas extends HTMLElement {
             if (this.config.onNodeHover) {
                 this.config.onNodeHover(node);
             }
+        })
+            .onNodeDrag((node) => {
+            this.handleNodeDrag(node);
+        })
+            .onNodeDragEnd((node) => {
+            this.handleNodeDragEnd(node);
         })
             .onLinkHover((link) => {
             if (this.config.onLinkHover) {
@@ -481,6 +769,7 @@ class FalkorDBCanvas extends HTMLElement {
             }
         })
             .onZoom((transform) => {
+            this.updateCullingBounds(transform);
             if (this.config.onZoom) {
                 this.config.onZoom(transform);
             }
@@ -523,8 +812,7 @@ class FalkorDBCanvas extends HTMLElement {
                 this.pointerLink(link, color, ctx);
             }
         });
-        // Setup forces
-        this.setupForces();
+        this.configureSimulationForCurrentLayout();
         this.log('Force graph initialization complete');
     }
     setupForces() {
@@ -534,6 +822,8 @@ class FalkorDBCanvas extends HTMLElement {
             return;
         if (!this.graph)
             return;
+        this.graph.d3Force("layoutTargetX", null);
+        this.graph.d3Force("layoutTargetY", null);
         // distance based on node size + constant
         linkForce
             .distance((link) => {
@@ -564,11 +854,148 @@ 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]
+     */
+    updateCullingBounds(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). */
+    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.
+     */
+    isNodeInCullingBounds(node) {
+        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.
+     */
+    isLinkInCullingBounds(link) {
+        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;
+    }
+    handleNodeDrag(node) {
+        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);
+    }
+    handleNodeDragEnd(node) {
+        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);
+    }
     drawNode(node, ctx) {
         if (node.x === undefined || node.y === undefined) {
             node.x = 0;
             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;
@@ -579,6 +1006,12 @@ class FalkorDBCanvas extends HTMLElement {
         ctx.beginPath();
         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";
@@ -591,32 +1024,46 @@ class FalkorDBCanvas extends HTMLElement {
             ctx.font = `400 ${NODE_FONT_SIZE_BASE}px SofiaSans`;
             [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;
             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`;
             node.displayName = [line1, line2];
@@ -650,6 +1097,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;
         ctx.beginPath();
@@ -665,17 +1115,27 @@ class FalkorDBCanvas extends HTMLElement {
             end.x = 0;
             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;
         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 = 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;
             if (this.config.linkLineDash)
@@ -737,7 +1197,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 };
@@ -786,7 +1246,7 @@ class FalkorDBCanvas extends HTMLElement {
             // Draw regular link line and arrowhead
             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;
             let tArrow;
@@ -815,7 +1275,7 @@ class FalkorDBCanvas extends HTMLElement {
             const tipX = uArrow * uArrow * start.x + 2 * uArrow * tArrow * controlX + tArrow * tArrow * end.x;
             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;
             let tStart = 0;
@@ -863,7 +1323,7 @@ class FalkorDBCanvas extends HTMLElement {
             const atx = 2 * uArrow * (controlX - start.x) + 2 * tArrow * (end.x - controlX);
             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 };
@@ -873,40 +1333,42 @@ class FalkorDBCanvas extends HTMLElement {
         ctx.textAlign = "center";
         // 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);
-        }
-        const { textWidth, textHeight, textYOffset } = cached;
-        ctx.save();
-        ctx.translate(textX, textY);
-        ctx.rotate(angle);
-        // 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);
-        ctx.fillStyle = getContrastTextColor(this.config.backgroundColor);
-        ctx.fillText(link.relationship, 0, textYOffset);
-        ctx.restore();
+        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;
+            ctx.save();
+            ctx.translate(textX, textY);
+            ctx.rotate(angle);
+            // 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);
+            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) {
             const { tipX, tipY, nx, ny, arrowLen: aLen, arrowHalfWidth: aHW } = pendingArrow;
@@ -924,6 +1386,9 @@ class FalkorDBCanvas extends HTMLElement {
         const end = link.target;
         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;
@@ -939,7 +1404,7 @@ class FalkorDBCanvas extends HTMLElement {
         ctx.beginPath();
         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;
             const borderRadius = nodeSize + nodeStrokeWidth + PADDING;
@@ -984,7 +1449,7 @@ class FalkorDBCanvas extends HTMLElement {
                 const controlX = (start.x + end.x) / 2 + perpX * curvature * distance;
                 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;
                 let tArrow;
@@ -1013,7 +1478,7 @@ class FalkorDBCanvas extends HTMLElement {
                 const tipX = uArrow * uArrow * start.x + 2 * uArrow * tArrow * controlX + tArrow * tArrow * end.x;
                 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;
                 let tStart = 0;
@@ -1068,6 +1533,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) {
@@ -1136,6 +1611,12 @@ class FalkorDBCanvas extends HTMLElement {
             if (this.config.onNodeHover) {
                 this.config.onNodeHover(node);
             }
+        })
+            .onNodeDrag((node) => {
+            this.handleNodeDrag(node);
+        })
+            .onNodeDragEnd((node) => {
+            this.handleNodeDragEnd(node);
         })
             .onLinkHover((link) => {
             if (this.config.onLinkHover) {
@@ -1153,6 +1634,7 @@ class FalkorDBCanvas extends HTMLElement {
             }
         })
             .onZoom((transform) => {
+            this.updateCullingBounds(transform);
             if (this.config.onZoom) {
                 this.config.onZoom(transform);
             }
@@ -1185,7 +1667,9 @@ class FalkorDBCanvas extends HTMLElement {
             });
         }
         else {
-            this.graph.nodePointerAreaPaint();
+            this.graph.nodePointerAreaPaint((node, color, ctx) => {
+                this.pointerNode(node, color, ctx);
+            });
         }
         if (this.config.link) {
             this.graph.linkPointerAreaPaint((link, color, ctx) => {
@@ -1193,7 +1677,9 @@ class FalkorDBCanvas extends HTMLElement {
             });
         }
         else {
-            this.graph.linkPointerAreaPaint();
+            this.graph.linkPointerAreaPaint((link, color, ctx) => {
+                this.pointerLink(link, color, ctx);
+            });
         }
     }
     updateTooltipStyles() {