@falkordb/canvas 0.0.49 → 0.0.50

package/README.md

@@ -8,7 +8,7 @@ A standalone web component for visualizing FalkorDB graphs using force-directed
 - 🧭 **Multiple layout modes** - Switch between `force`, `tree`, `flow`, `radial-tree`, `concentric`, `components`, and `arc` graph views
 - 🎯 **Interactive** - Click, hover, right-click interactions on nodes, links, and background
 - 🌓 **Theme support** - Light and dark mode compatible with customizable colors
-- ⚡ **Performance** - Optimized rendering with HTML5 canvas
+- ⚡ **Performance** - Optimized rendering with HTML5 canvas, including viewport culling and low-zoom draw skipping for large graphs
 - 💫 **Loading states** - Built-in skeleton loading with pulse animation
 - 🎨 **Customizable** - Colors, sizes, behaviors, and custom rendering functions
 - 📦 **TypeScript support** - Full type definitions included
@@ -159,6 +159,7 @@ function GraphVisualization() {
 | `isLinkSelected` | | Function to determine if a link is selected. Signature: `(link: GraphLink) => boolean` |
 | `node` | | Custom node rendering functions (see Custom Rendering) |
 | `link` | | Custom link rendering functions (see Custom Rendering) |
+| `largeGraph` | | Large-graph rendering optimizations (see [Large-Graph Optimizations](#large-graph-optimizations)) |
 
 ### Layout Modes
 
@@ -432,6 +433,63 @@ while (true) {
 2. **Static graphs**: Set `cooldownTicks: 0` after initial layout
 3. **Custom rendering**: Optimize your custom `nodeCanvasObject` and `linkCanvasObject` functions
 4. **Viewport**: Use `getViewport()` and `setViewport()` to preserve user's view when updating data
+5. **Very large graphs**: Enable viewport culling via the `largeGraph` option (see below)
+
+## Large-Graph Optimizations
+
+For graphs with thousands of nodes and links, enable the built-in viewport culling and low-zoom draw-skipping optimizations via the `largeGraph` configuration option.
+
+> **Note:** These optimizations are applied by the default renderer. If you provide custom
+> `nodeCanvasObject` / `linkCanvasObject` callbacks, the library will not cull or skip
+> drawing for those elements automatically. Implement equivalent viewport culling and
+> low-zoom checks in your custom renderer if needed.
+
+```typescript
+canvas.setConfig({
+  largeGraph: {
+    enabled: true,           // master switch (false by default – no behavioural change unless true)
+    viewportPadding: 50,     // world-unit padding around the visible viewport (default: 0)
+    lowZoomThreshold: 0.5,  // zoom level below which expensive details are skipped
+    skipLabelsAtLowZoom: true,      // skip node labels at low zoom (default: true)
+    skipArrowsAtLowZoom: true,      // skip link arrowheads at low zoom (default: true)
+    skipLinkLabelsAtLowZoom: true,  // skip link relationship labels at low zoom (default: true)
+  }
+});
+```
+
+### How it works
+
+**Viewport culling** – before each node or link is drawn, the renderer checks whether its world-space bounding box overlaps the currently visible area (with optional extra `viewportPadding`).  Elements that are entirely offscreen are skipped without any canvas work.
+
+- For **nodes**: the bounding box is a circle of radius `node.size + 2`.
+- For **links**: the bounding box is the convex-hull axis-aligned rectangle of the Bezier curve's control points (source, control point, target).  This is a conservative bound – it never produces false negatives.
+- For **self-loops**: the bounding box is a square centered on the node with a side length derived from the loop curvature.
+
+**Low-zoom draw skipping** – when the current zoom level drops below `lowZoomThreshold`, expensive per-element details that would be too small to read are skipped:
+
+- Node labels (text inside nodes) – controlled by `skipLabelsAtLowZoom`
+- Link arrowheads – controlled by `skipArrowsAtLowZoom`
+- Link relationship labels – controlled by `skipLinkLabelsAtLowZoom`
+
+Node and link shapes are always drawn so the overall graph structure remains visible.
+
+### Recommended settings for large graphs
+
+```typescript
+// Good starting point for graphs with 1,000 – 10,000+ elements
+canvas.setConfig({
+  cooldownTicks: 300,   // limit physics simulation ticks
+  largeGraph: {
+    enabled: true,
+    viewportPadding: 100,  // pre-render elements slightly off-screen to avoid pop-in
+    lowZoomThreshold: 0.4, // tune to match your typical minimum zoom
+  }
+});
+```
+
+### Backward compatibility
+
+The feature is **disabled by default** (`enabled: false` / property absent).  Existing code that does not set `largeGraph` is completely unaffected.
 
 ## Debugging
 

package/dist/canvas-types.d.ts

@@ -1,4 +1,45 @@
 import { NodeObject } from "force-graph";
+/**
+ * Configuration for large-graph rendering optimisations.
+ * All options are optional; the feature is disabled by default (`enabled: false`).
+ */
+export interface LargeGraphConfig {
+    /**
+     * Master switch. When `false` (default) the component behaves exactly as before –
+     * no culling is applied and no draw calls are skipped.
+     */
+    enabled?: boolean;
+    /**
+     * Extra padding added around the visible viewport (in world-space units) when
+     * deciding whether a node or link is offscreen.  Increase this to pre-render
+     * elements just outside the visible area and avoid pop-in during fast panning.
+     * Default: `0`.
+     */
+    viewportPadding?: number;
+    /**
+     * Zoom level below which expensive per-element details are skipped.
+     * At a zoom of `1` each world-unit covers one screen pixel; at `0.5` elements
+     * are drawn at half size, making labels and arrows too small to be useful.
+     * Default: `0.5`.
+     */
+    lowZoomThreshold?: number;
+    /**
+     * Skip drawing node labels when the current zoom is below `lowZoomThreshold`.
+     * Node circles are still drawn so the graph shape remains visible.
+     * Default: `true`.
+     */
+    skipLabelsAtLowZoom?: boolean;
+    /**
+     * Skip drawing link arrowheads when the current zoom is below `lowZoomThreshold`.
+     * Default: `true`.
+     */
+    skipArrowsAtLowZoom?: boolean;
+    /**
+     * Skip drawing link relationship labels when the current zoom is below `lowZoomThreshold`.
+     * Default: `true`.
+     */
+    skipLinkLabelsAtLowZoom?: boolean;
+}
 export interface ForceGraphConfig {
     width?: number;
     height?: number;
@@ -34,6 +75,8 @@ export interface ForceGraphConfig {
         linkCanvasObject: (link: GraphLink, ctx: CanvasRenderingContext2D, globalScale: number) => void;
         linkPointerAreaPaint: (link: GraphLink, color: string, ctx: CanvasRenderingContext2D) => void;
     };
+    /** Large-graph rendering optimisations (viewport culling and low-zoom draw skipping). */
+    largeGraph?: LargeGraphConfig;
 }
 export interface InternalForceGraphConfig extends Omit<ForceGraphConfig, 'backgroundColor' | 'foregroundColor' | 'captionsKeys' | 'showPropertyKeyPrefix' | 'layoutMode' | 'layoutOptions'> {
     backgroundColor: string;

package/dist/canvas-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canvas-types.d.ts","sourceRoot":"","sources":["../src/canvas-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"canvas-types.d.ts","sourceRoot":"","sources":["../src/canvas-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC3D,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC3D,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAChE,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAChE,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,KAAK,IAAI,CAAC;IAC/C,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,KAAK,IAAI,CAAC;IAC/C,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAChD,sBAAsB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACrD,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC;IAC9C,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC;IAC9C,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,EAAE,CAAC;IAC7C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE;QACL,gBAAgB,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,wBAAwB,KAAK,IAAI,CAAC;QAC3E,oBAAoB,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,wBAAwB,KAAK,IAAI,CAAC;KAC/F,CAAC;IACF,IAAI,CAAC,EAAE;QACL,gBAAgB,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;QAChG,oBAAoB,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,wBAAwB,KAAK,IAAI,CAAC;KAC/F,CAAC;IACF,yFAAyF;IACzF,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CAAC,gBAAgB,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,cAAc,GAAG,uBAAuB,GAAG,YAAY,GAAG,eAAe,CAAC;IACzL,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAClC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,UAAU,EAAE,UAAU,CAAC;IACvB,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,YAAY,GAAG,YAAY,GAAG,KAAK,CAAC;AAEzG,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AACxD,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,CAAC;AACvC,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;AAChF,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,GAAG,QAAQ,CAAC;AACrD,MAAM,MAAM,qBAAqB,GAAG,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC;AACnF,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,WAAW,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AACD,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,YAAY,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,kBAAkB,CAAC;CACvC;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,UAAU,CAAC,EAAE,uBAAuB,CAAC;IACrC,UAAU,CAAC,EAAE,uBAAuB,CAAC;IACrC,UAAU,CAAC,EAAE,uBAAuB,CAAC;IACrC,GAAG,CAAC,EAAE,gBAAgB,CAAC;CACxB;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE;QACJ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;IACF,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE;QACJ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;CACH,CAAC;AAEF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,MAAM,MAAM,IAAI,GAAG,IAAI,CACrB,SAAS,EACT,GAAG,GAAG,GAAG,GAAG,eAAe,GAAG,eAAe,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,2BAA2B,GAAG,aAAa,GAAG,MAAM,CACjI,GAAG;IACF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAA;AAED,MAAM,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC,GAAG;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,WAAW,IAAI;IACnB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,SAAS,CAAC;AAEd,MAAM,MAAM,SAAS,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAI9D,MAAM,MAAM,kBAAkB,GAAG,OAAO,aAAa,EAAE,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,GAAG,SAAS,CAAC"}

package/dist/canvas.d.ts

@@ -12,6 +12,16 @@ declare class FalkorDBCanvas extends HTMLElement {
     private nodeDegreeMap;
     private nodeDisplayFontSize;
     private relationshipsTextCache;
+    /**
+     * 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;
+    /** Current zoom level, cached alongside cullingBounds. */
+    private cullingZoom;
+    /** Last d3-zoom transform, cached so bounds can be recomputed on resize. */
+    private lastTransform;
     private onFontsLoadingDone;
     private viewport;
     private shouldZoomToFitOnNonForceSettle;
@@ -63,6 +73,35 @@ declare class FalkorDBCanvas extends HTMLElement {
     private setupResizeObserver;
     private initGraph;
     private setupForces;
+    /**
+     * 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;
+    /** Recompute culling bounds using the last known transform (e.g. after resize). */
+    private recomputeCullingBoundsIfNeeded;
+    /**
+     * 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;
+    /**
+     * 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;
     private handleNodeDrag;
     private handleNodeDragEnd;
     private drawNode;

package/dist/canvas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../src/canvas.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,IAAI,EACJ,kBAAkB,EAClB,SAAS,EAET,SAAS,EACT,gBAAgB,EAChB,aAAa,EAId,MAAM,mBAAmB,CAAC;AA0E3B,cAAM,cAAe,SAAQ,WAAW;IACtC,OAAO,CAAC,KAAK,CAAqB;IAElC,OAAO,CAAC,SAAS,CAA+B;IAEhD,OAAO,CAAC,cAAc,CAA+B;IAErD,OAAO,CAAC,cAAc,CAA+B;IAErD,OAAO,CAAC,IAAI,CAAuC;IAEnD,OAAO,CAAC,YAAY,CAAkB;IAEtC,OAAO,CAAC,MAAM,CAOZ;IAEF,OAAO,CAAC,QAAQ,CAA+B;IAE/C,OAAO,CAAC,QAAQ,CAA+B;IAE/C,OAAO,CAAC,aAAa,CAAkC;IAGvD,OAAO,CAAC,mBAAmB,CAAkC;IAE7D,OAAO,CAAC,sBAAsB,CAOhB;IAEd,OAAO,CAAC,kBAAkB,CAOxB;IAEF,OAAO,CAAC,QAAQ,CAAgB;IAEhC,OAAO,CAAC,+BAA+B,CAAkB;;IAOzD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO;IAMzB;;;OAGG;IACH,OAAO,CAAC,GAAG;IAMX,iBAAiB;IAuBjB,oBAAoB;IAYpB,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC;IA6D3C,QAAQ,CAAC,KAAK,EAAE,MAAM;IAStB,SAAS,CAAC,MAAM,EAAE,MAAM;IASxB,kBAAkB,CAAC,KAAK,EAAE,MAAM;IAahC,kBAAkB,CAAC,KAAK,EAAE,MAAM;IAQhC,YAAY,CAAC,SAAS,EAAE,OAAO;IAO/B,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS;IAa1C,OAAO,IAAI,IAAI;IAIf,OAAO,CAAC,IAAI,EAAE,IAAI;IA8DlB,WAAW,IAAI,aAAa;IAc5B,WAAW,CAAC,QAAQ,EAAE,aAAa;IAKnC,YAAY,IAAI,SAAS;IAIzB,YAAY,CAAC,IAAI,EAAE,SAAS;IA8C5B,QAAQ,IAAI,kBAAkB,GAAG,SAAS;IAInC,OAAO,IAAI,MAAM;IAIjB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAOvD,SAAS,CAAC,iBAAiB,SAAI,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO;IAkB7E,OAAO,CAAC,iBAAiB;IAGzB,OAAO,CAAC,kBAAkB;IAW1B,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,4BAA4B;IAkCpC,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,oCAAoC;IAkD5C,OAAO,CAAC,yBAAyB;IAgDjC,OAAO,CAAC,4BAA4B;IAQpC,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,mCAAmC;IAoB3C,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,+BAA+B;IAUvC,OAAO,CAAC,mBAAmB;IAsB3B,OAAO,CAAC,oBAAoB;IAmE5B,OAAO,CAAC,MAAM;IAuBd,OAAO,CAAC,mBAAmB;IAiB3B,OAAO,CAAC,SAAS;IAuHjB,OAAO,CAAC,WAAW;IAqDnB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,QAAQ;IA+GhB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,QAAQ;IA8ShB,OAAO,CAAC,WAAW;IA4InB,OAAO,CAAC,kBAAkB;IAY1B,OAAO,CAAC,gBAAgB;IAyDxB,OAAO,CAAC,mBAAmB;IA6F3B,OAAO,CAAC,mBAAmB;CAS5B;AAOD,eAAe,cAAc,CAAC"}
+{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../src/canvas.ts"],"names":[],"mappings":"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"}

package/dist/canvas.js

@@ -81,6 +81,16 @@ 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();
@@ -151,7 +161,23 @@ 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) {
@@ -206,6 +232,7 @@ class FalkorDBCanvas extends HTMLElement {
         this.config.width = width;
         if (this.graph) {
             this.graph.width(width);
+            this.recomputeCullingBoundsIfNeeded();
         }
     }
     setHeight(height) {
@@ -215,6 +242,7 @@ class FalkorDBCanvas extends HTMLElement {
         this.config.height = height;
         if (this.graph) {
             this.graph.height(height);
+            this.recomputeCullingBoundsIfNeeded();
         }
     }
     setBackgroundColor(color) {
@@ -336,40 +364,23 @@ class FalkorDBCanvas extends HTMLElement {
     }
     setGraphData(data) {
         this.log('setGraphData called with', data.nodes.length, 'nodes and', data.links.length, 'links');
-        const previousPositions = this.getNodePositionMap();
         this.data = applyGraphLayout(data, this.config.layoutMode, this.config.layoutOptions);
-        const shouldAnimateNonForceLayout = this.prepareNodePositionsForCurrentLayout(previousPositions);
-        if (this.isForceLayoutMode() && this.config.cooldownTicks === 0 && this.data.nodes.length > 0) {
-            this.config.cooldownTicks = undefined;
-            this.shouldZoomToFitOnNonForceSettle = false;
-        }
+        this.shouldZoomToFitOnNonForceSettle = false;
         if (!this.graph)
             return;
         this.calculateNodeDegree();
         this.graph
             .graphData(this.data);
-        this.configureSimulationForCurrentLayout(shouldAnimateNonForceLayout);
-        if (this.isForceLayoutMode() && this.data.nodes.length > 0) {
+        // 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();
         }
-        if (!this.isForceLayoutMode()) {
-            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);
-                    this.triggerRender();
-                }
-            }
-            else {
-                this.shouldZoomToFitOnNonForceSettle = false;
-            }
-        }
+        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);
@@ -679,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();
                 }
             }
         });
@@ -757,6 +769,7 @@ class FalkorDBCanvas extends HTMLElement {
             }
         })
             .onZoom((transform) => {
+            this.updateCullingBounds(transform);
             if (this.config.onZoom) {
                 this.config.onZoom(transform);
             }
@@ -841,6 +854,118 @@ 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;
@@ -868,6 +993,9 @@ class FalkorDBCanvas extends HTMLElement {
             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;
@@ -878,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";
@@ -963,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();
@@ -978,11 +1115,21 @@ 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).
@@ -1050,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 };
@@ -1176,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 };
@@ -1186,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;
@@ -1237,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;
@@ -1482,6 +1634,7 @@ class FalkorDBCanvas extends HTMLElement {
             }
         })
             .onZoom((transform) => {
+            this.updateCullingBounds(transform);
             if (this.config.onZoom) {
                 this.config.onZoom(transform);
             }
@@ -1514,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) => {
@@ -1522,7 +1677,9 @@ class FalkorDBCanvas extends HTMLElement {
             });
         }
         else {
-            this.graph.linkPointerAreaPaint();
+            this.graph.linkPointerAreaPaint((link, color, ctx) => {
+                this.pointerLink(link, color, ctx);
+            });
         }
     }
     updateTooltipStyles() {