polly-graph 0.2.4 → 0.2.6

package/dist/index.d.cts

@@ -233,11 +233,11 @@ type UIColors = typeof DEFAULT_COLORS.ui;
  * Consolidated icons used across V1, V2, and demo
  */
 declare const icons: {
-    readonly fit: string;
-    readonly reset: string;
-    readonly plus: string;
-    readonly minus: string;
-    readonly caret: string;
+    readonly fit: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n  <path d=\"M5 9V5H9\" />\n  <path d=\"M19 9V5H15\" />\n  <path d=\"M5 15V19H9\" />\n  <path d=\"M19 15V19H15\" />\n</svg>";
+    readonly reset: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n  <path d=\"M20 12a8 8 0 1 1-2.3-5.7\" />\n  <path d=\"M20 4.5v4h-4\" />\n</svg>";
+    readonly plus: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n  <path d=\"M5 12h14m-7-7v14\" />\n</svg>";
+    readonly minus: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n  <path d=\"M5 12h14\" />\n</svg>";
+    readonly caret: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n  <path d=\"M6 9l6 6 6-6\" />\n</svg>";
 };
 declare const iconSvg: {
     readonly fit: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n    <path d=\"M5 9V5H9\" />\n    <path d=\"M19 9V5H15\" />\n    <path d=\"M5 15V19H9\" />\n    <path d=\"M19 15V19H15\" />\n  </svg>";
@@ -261,12 +261,12 @@ interface Coordinates {
 }
 type Position = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
 type Orientation = 'vertical' | 'horizontal';
-type GraphControlsPosition = Position;
-type GraphControlsOrientation = Orientation;
-interface GraphControlsConfig {
+type GraphControlsPosition$1 = Position;
+type GraphControlsOrientation$1 = Orientation;
+interface GraphControlsConfig$1 {
     readonly enabled: boolean;
-    readonly position?: GraphControlsPosition;
-    readonly orientation?: GraphControlsOrientation;
+    readonly position?: GraphControlsPosition$1;
+    readonly orientation?: GraphControlsOrientation$1;
     readonly offset?: Coordinates;
     readonly show?: {
         readonly zoomIn?: boolean;
@@ -303,6 +303,11 @@ interface SelectionInteractionConfig {
     readonly nodeStyle?: Partial<NodeStyle>;
     readonly linkStyle?: Partial<LinkStyle>;
 }
+interface HighlightInteractionConfig {
+    readonly enabled?: boolean;
+    readonly nodeStyle?: Partial<NodeStyle>;
+    readonly linkStyle?: Partial<LinkStyle>;
+}
 interface DragInteractionConfig {
     readonly enabled?: boolean;
 }
@@ -310,6 +315,7 @@ interface GraphInteractionConfig {
     readonly drag?: DragInteractionConfig;
     readonly hover?: HoverInteractionConfig;
     readonly selection?: SelectionInteractionConfig;
+    readonly highlight?: HighlightInteractionConfig;
 }
 
 type LegendPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
@@ -336,7 +342,7 @@ interface BaseGraphConfig {
     readonly responsive?: boolean;
     readonly simulation?: SimulationConfig;
     readonly interaction?: GraphInteractionConfig;
-    readonly controls?: GraphControlsConfig;
+    readonly controls?: GraphControlsConfig$1;
     readonly legend?: LegendConfig;
 }
 interface ControlsController {
@@ -374,9 +380,10 @@ interface V2Link extends SimulationLinkDatum<V2Node> {
     __indexColor?: string;
     __indexColorRGB?: [number, number, number];
 }
-interface InteractionConfig {
+interface InteractionConfig$1 {
     readonly hover?: HoverInteractionConfig;
     readonly selection?: SelectionInteractionConfig;
+    readonly highlight?: HighlightInteractionConfig;
 }
 interface V2Config {
     container: HTMLElement;
@@ -385,8 +392,8 @@ interface V2Config {
     width?: number;
     height?: number;
     backgroundColor?: string;
-    interaction?: InteractionConfig;
-    controls?: GraphControlsConfig;
+    interaction?: InteractionConfig$1;
+    controls?: GraphControlsConfig$1;
     legend?: LegendConfig;
     autoFitView?: boolean;
     cooldownTime?: number;
@@ -406,6 +413,11 @@ interface V2Instance {
     zoomIn(factor?: number, center?: [number, number]): void;
     zoomOut(factor?: number, center?: [number, number]): void;
     clearSelection(): void;
+    highlightNode(nodeId: string): void;
+    highlightNodes(nodeIds: string[]): void;
+    unhighlightNode(nodeId: string): void;
+    clearHighlights(): void;
+    getHighlightedNodes(): Set<string>;
     on(event: 'nodeSelect', handler: (node: V2Node, element: HTMLCanvasElement) => void): () => void;
     on(event: 'nodeDeselect', handler: (node: V2Node, element: HTMLCanvasElement) => void): () => void;
     on(event: 'linkSelect', handler: (link: V2Link, element: HTMLCanvasElement) => void): () => void;
@@ -623,12 +635,30 @@ declare class PhysicsManager {
     private hasInitialAutoFitCompleted;
     private timerManager;
     private isVisibilityListenerAttached;
-    private nodeMap;
+    private stateManager;
+    private isWarmingUp;
+    private warmupSteps;
     constructor(timerManager: TimerManager);
     /**
      * Initialize physics simulation
      */
     initialize(config: PhysicsConfig): void;
+    /**
+     * Handle tick with smooth warmup progression
+     */
+    private handleTick;
+    /**
+     * Start smooth warmup process for large graphs
+     */
+    private startSmoothWarmup;
+    /**
+     * Progress warmup over time for smoother initial animation
+     */
+    private progressWarmup;
+    /**
+     * Apply scaled forces during warmup
+     */
+    private applyWarmupForces;
     /**
      * Handle simulation end
      */
@@ -641,10 +671,6 @@ declare class PhysicsManager {
      * Setup cooldown timer (force-graph pattern)
      */
     private setupCooldownTimer;
-    /**
-     * Build node index for O(1) lookups (Step 3 optimization)
-     */
-    private buildNodeIndex;
     /**
      * Get simulation instance
      */
@@ -684,7 +710,7 @@ declare class PhysicsManager {
      */
     private getLinkArrowLength;
     /**
-     * Initialize node positions if not set
+     * Initialize node positions with improved distribution for smoother startup
      */
     initializePositions(): void;
     /**
@@ -765,6 +791,7 @@ declare class HoverManager {
     private flushShadowCanvas?;
     private hasValidPointerPosition;
     private containerWarningLogged;
+    private boundHandlers;
     /**
      * Initialize hover manager with force-graph pattern
      */
@@ -849,6 +876,10 @@ interface DragConfig {
     physicsManager: PhysicsManager;
     hoverManager: HoverManager;
     onRender: () => void;
+    renderer?: {
+        setDragState(isDragging: boolean): void;
+        setDraggedNode(node: V2Node): void;
+    };
 }
 interface DragState {
     isDragging: boolean;
@@ -858,6 +889,9 @@ declare class DragManager {
     private config?;
     private state;
     private readonly DRAG_CLICK_TOLERANCE_PX;
+    private dragRenderPending;
+    private lastDragRenderTime;
+    private pendingAnimationFrame?;
     /**
      * Initialize drag behavior
      */
@@ -874,6 +908,10 @@ declare class DragManager {
      * Handle drag movement
      */
     private handleDrag;
+    /**
+     * RAF-throttled render during drag (like ZoomManager pattern)
+     */
+    private throttledDragRender;
     /**
      * Handle drag end
      */
@@ -906,6 +944,10 @@ interface ZoomConfig {
     canvas: HTMLCanvasElement;
     canvasManager: CanvasManager;
     onRender: () => void;
+    onZoomEnd?: () => void;
+    renderer?: {
+        setZoomState(isZooming: boolean): void;
+    };
     minZoom?: number;
     maxZoom?: number;
     isOverEntity?: () => boolean;
@@ -913,6 +955,9 @@ interface ZoomConfig {
 declare class ZoomManager {
     private config?;
     private zoomBehavior?;
+    private isZooming;
+    private zoomRenderPending;
+    private isProgrammaticZoom;
     /**
      * Initialize zoom behavior
      */
@@ -926,13 +971,14 @@ declare class ZoomManager {
      */
     private handleZoomStart;
     /**
-     * Handle zoom events
+     * Handle zoom events with RAF throttling for smooth performance
      */
     private handleZoom;
     /**
      * Handle zoom end (when panning ends)
      */
     private handleZoomEnd;
+    isCurrentlyZooming(): boolean;
     /**
      * Get zoom behavior instance
      */
@@ -1014,6 +1060,7 @@ declare class SelectionManager {
     private selectionState;
     private eventHandlers;
     private container?;
+    private boundHandlers;
     /**
      * Initialize selection manager
      */
@@ -1081,161 +1128,263 @@ declare class SelectionManager {
 }
 
 /**
- * V2 Canvas Graph - Renderer (Force-Graph Pattern)
+ * V2 Canvas Graph - State Manager
  *
- * Clean implementation following force-graph's exact architecture
+ * Centralized state management for O(1) lookups across all renderers.
+ * Eliminates duplicate Maps and provides consistent caching patterns.
  */
 
-declare class Renderer {
-    private config?;
-    private canvasState?;
-    private hoverManager?;
-    private selectionManager?;
-    private styleResolver?;
+interface GraphState {
+    nodes: V2Node[];
+    links: V2Link[];
+}
+interface NodeLookupState {
+    isHovered: boolean;
+    isSelected: boolean;
+    isHighlighted: boolean;
+}
+interface LinkLookupState {
+    isHovered: boolean;
+    isSelected: boolean;
+}
+declare class StateManager {
     private nodeMap;
-    private shadowCanvasDirty;
-    private lastShadowRenderTime;
-    private readonly SHADOW_RENDER_THROTTLE;
-    private hasLoggedLargeGraphOptimization;
-    private performanceMetrics;
-    private linkHoverPrecision;
+    private linkMap;
+    private nodeStateCache;
+    private linkStateCache;
+    private linkIdToLinkMap;
+    private highlightedNodes;
     /**
-     * Initialize the renderer
+     * Initialize with graph data
      */
-    initialize(config: {
-        nodes: V2Node[];
-        links: V2Link[];
-        interaction?: InteractionConfig;
-    }, canvasState: CanvasState, hoverManager: HoverManager, selectionManager?: SelectionManager): void;
+    initialize(state: GraphState): void;
     /**
-     * Main render method with performance metrics (Instrumented)
+     * Update with new graph data
      */
-    render(): void;
+    updateState(state: GraphState): void;
     /**
-     * Render with transform (called during zoom/pan) with shadow canvas dirty marking (Step 6 optimization)
+     * Build node map for O(1) node lookups
      */
-    renderWithTransform(): void;
+    private buildNodeMap;
     /**
-     * Render shadow canvas for hit detection with throttling (Step 6 optimization)
+     * Build link maps for O(1) link lookups
      */
-    renderShadowCanvas(): void;
+    private buildLinkMaps;
     /**
-     * Mark shadow canvas as dirty for next render (Step 6 optimization)
+     * Get node by ID (O(1) lookup)
      */
-    markShadowCanvasDirty(): void;
+    getNode(nodeId: string): V2Node | undefined;
     /**
-     * Force shadow canvas render (Step 6 optimization)
+     * Get link by link ID (O(1) lookup)
      */
-    forceShadowCanvasRender(): void;
+    getLink(linkId: string): V2Link | undefined;
     /**
-     * Clear canvas context
+     * Get link by source/target IDs (O(1) lookup)
      */
-    private clearCanvas;
+    getLinkByNodes(sourceId: string, targetId: string): V2Link | undefined;
     /**
-     * Apply transform to canvas context
+     * Get all nodes (returns reference to avoid copying)
      */
-    private applyTransform;
+    getAllNodes(): V2Node[];
     /**
-     * Get unique link ID for tracking (consistent with LinkLabelsRenderer)
+     * Get all links (returns reference to avoid copying)
      */
-    private getLinkId;
+    getAllLinks(): V2Link[];
     /**
-     * Render main canvas nodes
+     * Get node map (for renderers that need direct map access)
      */
-    private renderNodes;
+    getNodeMap(): Map<string, V2Node>;
     /**
-     * Render node labels
+     * Get link ID to link map (for renderers that need direct map access)
      */
-    private renderNodeLabels;
+    getLinkIdToLinkMap(): Map<string, V2Link>;
     /**
-     * Render shadow links with __indexColor (force-graph pattern)
+     * Cache node state for performance (avoid repeated hover/selection checks)
      */
-    private renderShadowLinks;
+    cacheNodeState(nodeId: string, state: NodeLookupState): void;
     /**
-     * Render shadow link labels for hit detection
+     * Get cached node state
      */
-    private renderShadowLinkLabels;
+    getCachedNodeState(nodeId: string): NodeLookupState | undefined;
     /**
-     * Render shadow nodes with __indexColor (force-graph pattern)
+     * Cache link state for performance (avoid repeated hover/selection checks)
      */
-    private renderShadowNodes;
+    cacheLinkState(linkId: string, state: LinkLookupState): void;
     /**
-     * Get currently hovered node ID directly (Critical Performance Fix)
+     * Get cached link state
      */
-    private getCurrentlyHoveredNodeId;
+    getCachedLinkState(linkId: string): LinkLookupState | undefined;
     /**
-     * Get currently selected node ID directly (Critical Performance Fix)
+     * Clear state caches (call when hover/selection state changes)
      */
-    private getCurrentlySelectedNodeId;
+    clearStateCache(): void;
     /**
-     * Get currently hovered link (Critical Performance Fix)
+     * Clear only node state cache
      */
-    private getCurrentlyHoveredLink;
+    clearNodeStateCache(): void;
     /**
-     * Get currently selected link (Critical Performance Fix)
+     * Clear only link state cache
      */
-    private getCurrentlySelectedLink;
+    clearLinkStateCache(): void;
     /**
-     * Log performance metrics for analysis
+     * Generate consistent link ID
      */
-    private logPerformanceMetrics;
+    getLinkId(link: V2Link): string;
     /**
-     * Reset performance metrics
+     * Calculate link midpoint (common utility)
      */
-    resetPerformanceMetrics(): void;
+    getLinkMidpoint(link: V2Link): {
+        x: number;
+        y: number;
+    } | null;
     /**
-     * Get current performance metrics
+     * Highlight a node by ID
      */
-    getPerformanceMetrics(): StatsMetrics;
+    highlightNode(nodeId: string): void;
     /**
-     * Force log performance metrics immediately (for debugging)
+     * Highlight multiple nodes by IDs
      */
-    forceLogMetrics(): void;
+    highlightNodes(nodeIds: string[]): void;
     /**
-     * Check if a node is currently hovered
+     * Remove highlight from a node
      */
-    private isNodeHovered;
+    unhighlightNode(nodeId: string): void;
     /**
-     * Check if a link is currently hovered (either directly or through associated node hover)
+     * Clear all node highlights
      */
-    private isLinkHovered;
+    clearHighlights(): void;
     /**
-     * Check if a node is currently selected
+     * Check if a node is highlighted
      */
-    private isNodeSelected;
+    isNodeHighlighted(nodeId: string): boolean;
     /**
-     * Check if a link is currently selected
+     * Get all highlighted node IDs
      */
-    private isLinkSelected;
+    getHighlightedNodes(): Set<string>;
     /**
-     * Check if a link's label should be visible due to selection
-     * (either the link itself is selected, or its connected node is selected)
+     * Clear state cache for a specific node
      */
-    private shouldShowLinkLabelForSelection;
+    private clearSingleNodeStateCache;
     /**
-     * Calculate midpoint of a link for label positioning
+     * Get statistics about cached state
      */
-    private getLinkMidpoint;
+    getStats(): {
+        nodeCount: number;
+        linkCount: number;
+        cachedNodeStates: number;
+        cachedLinkStates: number;
+        highlightedNodes: number;
+    };
     /**
-     * Render directed link with arrow head
+     * Destroy and clean up all maps
      */
-    private renderDirectedLink;
+    destroy(): void;
+}
+
+/**
+ * V2 Canvas Graph - Renderer (Force-Graph Pattern)
+ *
+ * Clean implementation following force-graph's exact architecture
+ */
+
+declare class Renderer {
+    private config?;
+    private canvasState?;
+    private hoverManager?;
+    private selectionManager?;
+    private styleResolver?;
+    private stateManager;
+    private metricsManager;
+    private interactionResolver;
+    private dragOptimizer;
+    private zIndexRenderer;
+    private zoomRenderer;
+    private hitDetectionRenderer;
     /**
-     * V1-compatible link shortening for source point
+     * Initialize the renderer
      */
-    private getShortenedSourcePoint;
+    initialize(config: {
+        nodes: V2Node[];
+        links: V2Link[];
+        interaction?: InteractionConfig$1;
+    }, canvasState: CanvasState, hoverManager: HoverManager, selectionManager?: SelectionManager): void;
     /**
-     * V1-compatible link shortening for target point
+     * Initialize the optimized z-index renderer with all required dependencies
      */
-    private getShortenedTargetPoint;
+    private initializeZIndexRenderer;
     /**
-     * Render arrow head at specific points
+     * Initialize the zoom renderer for zoom-specific optimizations
      */
-    private renderArrowAtPoint;
+    private initializeZoomRenderer;
     /**
-     * Render arrow head (legacy method for backward compatibility)
+     * Initialize the hit detection renderer for shadow canvas
      */
-    private renderArrow;
+    private initializeHitDetectionRenderer;
+    /**
+     * Initialize the drag optimizer for fast drag rendering
+     */
+    private initializeDragOptimizer;
+    /**
+     * Main render method with performance metrics (Instrumented)
+     */
+    render(): void;
+    /**
+     * Render with transform (called during zoom/pan) - OPTIMIZED PATTERN
+     * Fast rendering during zoom, full rendering when stopped
+     */
+    renderWithTransform(): void;
+    /**
+     * Set zoom state for performance optimization (delegates to ZoomRenderer)
+     */
+    setZoomState(isZooming: boolean): void;
+    /**
+     * Set drag state for performance optimization (like setZoomState)
+     */
+    setDragState(isDragging: boolean): void;
+    /**
+     * Set the currently dragged node
+     */
+    setDraggedNode(draggedNode: V2Node): void;
+    /**
+     * Render shadow canvas for hit detection (delegates to HitDetectionRenderer)
+     */
+    renderShadowCanvas(): void;
+    /**
+     * Mark shadow canvas as dirty for next render (delegates to HitDetectionRenderer)
+     */
+    markShadowCanvasDirty(): void;
+    /**
+     * Force shadow canvas render (delegates to HitDetectionRenderer)
+     */
+    forceShadowCanvasRender(): void;
+    /**
+     * Clear canvas context
+     */
+    private clearCanvas;
+    /**
+     * Apply transform to canvas context
+     */
+    private applyTransform;
+    /**
+     * Get unique link ID for tracking (delegates to StateManager)
+     */
+    private getLinkId;
+    /**
+     * Reset performance metrics
+     */
+    resetPerformanceMetrics(): void;
+    /**
+     * Get current performance metrics
+     */
+    getPerformanceMetrics(): StatsMetrics;
+    /**
+     * Force log performance metrics immediately (for debugging)
+     */
+    forceLogMetrics(): void;
+    /**
+     * Calculate midpoint of a link for label positioning (delegates to StateManager)
+     */
+    private getLinkMidpoint;
     /**
      * Initialize node positions if needed
      */
@@ -1260,44 +1409,16 @@ declare class Renderer {
         };
     };
     /**
-     * Debug shadow canvas export (force-graph pattern)
+     * Debug shadow canvas export (delegates to HitDetectionRenderer)
      */
     debugShadowCanvas(): void;
-    /**
-     * Build node index for O(1) lookups (Step 3 optimization)
-     */
-    private buildNodeIndex;
-    /**
-     * Get node by ID using O(1) lookup (Step 3 optimization)
-     */
-    private getNodeById;
-    /**
-     * Render with z-index layers (for renderWithTransform)
-     */
-    private renderWithLayers;
-    /**
-     * Render with z-index layers and performance metrics (for main render)
-     */
-    private renderWithLayersAndMetrics;
-    /**
-     * Helper methods for getting current interaction states
-     */
-    private getHoveredNode;
-    private getSelectedNode;
-    private getHoveredLink;
-    private getSelectedLink;
-    /**
-     * Layer-specific rendering methods (render subsets of entities)
-     */
-    private renderNodesWithLabelsLayer;
-    /**
-     * Helper method to truncate labels (copied from NodeLabelsRenderer)
-     */
-    private truncateLabel;
     private renderLinksLayer;
-    private renderLinkLabelsLayer;
     private renderNodesLayer;
     private renderNodeLabelsLayer;
+    /**
+     * Get the state manager for highlight operations
+     */
+    getStateManager(): StateManager;
     /**
      * Destroy renderer and clean up resources
      */
@@ -1457,6 +1578,26 @@ declare class V2Graph implements V2Instance {
      * Draw legend on export canvas
      */
     private drawLegendOnExportCanvas;
+    /**
+     * Highlight a node by ID
+     */
+    highlightNode(nodeId: string): void;
+    /**
+     * Highlight multiple nodes by IDs
+     */
+    highlightNodes(nodeIds: string[]): void;
+    /**
+     * Remove highlight from a node
+     */
+    unhighlightNode(nodeId: string): void;
+    /**
+     * Clear all node highlights
+     */
+    clearHighlights(): void;
+    /**
+     * Get all highlighted node IDs
+     */
+    getHighlightedNodes(): Set<string>;
     /**
      * Destroy the graph and clean up resources
      */
@@ -1467,4 +1608,951 @@ declare class V2Graph implements V2Instance {
  */
 declare function createV2Graph(config: V2Config): V2Instance;
 
-export { type ArrowRenderStyle, type BaseGraphConfig, CanvasManager, type CanvasRenderConfig, type CanvasState, type ControlsController, type Coordinates, DEFAULT_COLORS, DEFAULT_HOVER_STYLES, DEFAULT_LINK_LABEL_STYLE, DEFAULT_LINK_STYLE, type DragConfig, type DragInteractionConfig, DragManager, type DragState, ErrorHandler, type GraphControlsConfig, type GraphControlsOrientation, type GraphControlsPosition, type GraphInteractionConfig, type GraphLink, type GraphNode, type GraphNodeWithInitial, type GraphTooltipTheme, type HoverEvent, type HoverInteractionConfig, HoverManager, type HoverState, type HoverStyles, type IconName, type IconSvgName, type InteractionColors, type InteractionConfig, type LegendConfig, type LegendPosition, type LinkArrowStyle, type LinkColors, type LinkLabelRenderStyle, type LinkLabelStyle, type LinkRenderStyle, type LinkSelectHandler, type LinkStyle, NeutralColor, type NodeColorPalette, type NodeLabelRenderStyle, type NodeRenderStyle, type NodeSelectHandler, type NodeStyle, type Orientation, type PhysicsConfig, PhysicsManager, PointerManager, type PointerState, type Position, PrimaryColor, type RenderStyles, Renderer, type ResolvedLinkLabelStyle, type ResolvedLinkStyle, SecondaryColor, type SelectionEvent, type SelectionInteractionConfig, SelectionManager, type SelectionState, type SimulationConfig, StandardColor, type TooltipInteractionConfig, type TooltipPlacement, type UIColors, type V2Config, V2Graph, type V2Instance, type V2Link, type V2Node, ValidationError, type ZoomConfig, ZoomManager, createV2Graph, getIcon, getIconSvg, iconSvg, icons, isValidLinkStyle, isValidNodeStyle, mergeLinkStyle, mergeNodeStyle };
+/**
+ * Force-Graph Wrapper Types
+ *
+ * Minimal overhead generic types with strategic use of 'any'
+ * for force-graph library integration
+ */
+/**
+ * Base node interface with generic data payload
+ */
+interface ForceGraphNode<T = Record<string, unknown>> {
+    /** Unique identifier for the node */
+    id: string;
+    /** Optional custom data payload */
+    data?: T;
+    /** Position coordinates (managed by physics simulation) */
+    x?: number;
+    y?: number;
+    vx?: number;
+    vy?: number;
+    /** Node properties for force-graph compatibility */
+    [key: string]: unknown;
+}
+/**
+ * Base link interface with generic data payload
+ */
+interface ForceGraphLink<NodeType = ForceGraphNode, T = Record<string, unknown>> {
+    /** Source node reference - can be string ID or node object */
+    source: string | NodeType;
+    /** Target node reference - can be string ID or node object */
+    target: string | NodeType;
+    /** Optional custom data payload */
+    data?: T;
+    /** Link properties for force-graph compatibility */
+    [key: string]: unknown;
+}
+/**
+ * Graph data structure
+ */
+interface ForceGraphData<NodeType extends ForceGraphNode, LinkType extends ForceGraphLink<NodeType>> {
+    nodes: NodeType[];
+    links: LinkType[];
+}
+/**
+ * Event handler types with proper generics
+ */
+type NodeEventHandler<NodeType> = (node: NodeType, event?: MouseEvent) => void;
+type LinkEventHandler<LinkType> = (link: LinkType, event?: MouseEvent) => void;
+type BackgroundEventHandler = (event: MouseEvent) => void;
+type CanvasRenderHandler = (ctx: CanvasRenderingContext2D, globalScale: number) => void;
+/**
+ * Accessor types - can be property name or function
+ */
+type NodeAccessor<NodeType, ReturnType> = ReturnType | keyof NodeType | ((node: NodeType) => ReturnType);
+type LinkAccessor<LinkType, ReturnType> = ReturnType | keyof LinkType | ((link: LinkType) => ReturnType);
+/**
+ * Common accessor return types
+ */
+type ColorAccessor<T> = T extends ForceGraphNode ? NodeAccessor<T, string> : T extends ForceGraphLink<unknown> ? LinkAccessor<T, string> : never;
+type NumberAccessor<T> = T extends ForceGraphNode ? NodeAccessor<T, number> : T extends ForceGraphLink<unknown> ? LinkAccessor<T, number> : never;
+type StringAccessor<T> = T extends ForceGraphNode ? NodeAccessor<T, string> : T extends ForceGraphLink<unknown> ? LinkAccessor<T, string> : never;
+type BooleanAccessor<T> = T extends ForceGraphNode ? NodeAccessor<T, boolean> : T extends ForceGraphLink<unknown> ? LinkAccessor<T, boolean> : never;
+/**
+ * Canvas custom render modes for nodeCanvasObjectMode and linkCanvasObjectMode
+ */
+type CanvasCustomRenderMode = 'replace' | 'before' | 'after';
+/**
+ * Force simulation configuration
+ */
+interface ForceConfig {
+    /** D3 force simulation parameters */
+    d3AlphaMin?: number;
+    d3AlphaDecay?: number;
+    d3VelocityDecay?: number;
+    /** Simulation control */
+    warmupTicks?: number;
+    cooldownTicks?: number;
+    cooldownTime?: number;
+}
+/**
+ * Canvas configuration
+ */
+interface CanvasConfig {
+    width?: number;
+    height?: number;
+    backgroundColor?: string;
+    /** Zoom and pan controls */
+    enableZoomInteraction?: boolean | ((event: MouseEvent) => boolean);
+    enablePanInteraction?: boolean | ((event: MouseEvent) => boolean);
+    minZoom?: number;
+    maxZoom?: number;
+    /** Rendering optimization */
+    autoPauseRedraw?: boolean;
+}
+/**
+ * Interaction configuration
+ */
+interface InteractionConfig<NodeType, LinkType> {
+    /** Pointer interaction */
+    enablePointerInteraction?: boolean;
+    enableNodeDrag?: boolean;
+    linkHoverPrecision?: number;
+    /** Event handlers */
+    onNodeClick?: NodeEventHandler<NodeType>;
+    onNodeDoubleClick?: NodeEventHandler<NodeType>;
+    onNodeRightClick?: NodeEventHandler<NodeType>;
+    onNodeHover?: NodeEventHandler<NodeType>;
+    onNodeDrag?: NodeEventHandler<NodeType>;
+    onNodeDragEnd?: NodeEventHandler<NodeType>;
+    onLinkClick?: LinkEventHandler<LinkType>;
+    onLinkRightClick?: LinkEventHandler<LinkType>;
+    onLinkHover?: LinkEventHandler<LinkType>;
+    onBackgroundClick?: BackgroundEventHandler;
+    onBackgroundRightClick?: BackgroundEventHandler;
+    /** Canvas rendering hooks */
+    onRenderFramePre?: CanvasRenderHandler;
+    onRenderFramePost?: CanvasRenderHandler;
+}
+/**
+ * Node styling configuration with generics
+ */
+interface NodeStylingConfig<NodeType> {
+    /** Node appearance */
+    nodeRelSize?: number;
+    nodeId?: StringAccessor<NodeType>;
+    nodeLabel?: StringAccessor<NodeType>;
+    nodeVal?: NumberAccessor<NodeType>;
+    nodeVisibility?: BooleanAccessor<NodeType>;
+    nodeColor?: ColorAccessor<NodeType>;
+    nodeAutoColorBy?: StringAccessor<NodeType>;
+    /** Custom node rendering */
+    nodeCanvasObjectMode?: NodeAccessor<NodeType, CanvasCustomRenderMode>;
+    nodeCanvasObject?: (node: NodeType, ctx: CanvasRenderingContext2D, globalScale: number) => void;
+    nodePointerAreaPaint?: (node: NodeType, color: string, ctx: CanvasRenderingContext2D, globalScale: number) => void;
+}
+/**
+ * Link styling configuration with generics
+ */
+interface LinkStylingConfig<LinkType> {
+    /** Link appearance */
+    linkSource?: string;
+    linkTarget?: string;
+    linkLabel?: StringAccessor<LinkType>;
+    linkVisibility?: BooleanAccessor<LinkType>;
+    linkColor?: ColorAccessor<LinkType>;
+    linkAutoColorBy?: StringAccessor<LinkType>;
+    linkWidth?: NumberAccessor<LinkType>;
+    linkLineDash?: LinkAccessor<LinkType, number[]>;
+    linkCurvature?: NumberAccessor<LinkType>;
+    /** Directional arrows */
+    linkDirectionalArrowLength?: NumberAccessor<LinkType>;
+    linkDirectionalArrowColor?: ColorAccessor<LinkType>;
+    linkDirectionalArrowRelPos?: NumberAccessor<LinkType>;
+    /** Directional particles */
+    linkDirectionalParticles?: NumberAccessor<LinkType>;
+    linkDirectionalParticleSpeed?: NumberAccessor<LinkType>;
+    linkDirectionalParticleOffset?: NumberAccessor<LinkType>;
+    linkDirectionalParticleWidth?: NumberAccessor<LinkType>;
+    linkDirectionalParticleColor?: ColorAccessor<LinkType>;
+    linkDirectionalParticleCanvasObject?: (link: LinkType, ctx: CanvasRenderingContext2D, globalScale: number) => void;
+    /** Custom link rendering */
+    linkCanvasObjectMode?: StringAccessor<LinkType>;
+    linkCanvasObject?: (link: LinkType, ctx: CanvasRenderingContext2D, globalScale: number) => void;
+    linkPointerAreaPaint?: (link: LinkType, color: string, ctx: CanvasRenderingContext2D, globalScale: number) => void;
+}
+/**
+ * Performance targets for validation
+ */
+interface PerformanceTargets {
+    creation: number;
+    dataLoad: number;
+    firstRender: number;
+    render?: number;
+    methodCall: number;
+    memoryGrowth: number;
+}
+/**
+ * Performance metrics collected during runtime
+ */
+interface PerformanceMetrics {
+    creation: number;
+    dataLoad: number;
+    firstRender: number;
+    render: number;
+    memoryUsage: number;
+    nodeCount: number;
+    linkCount: number;
+    methodCalls: number;
+    optimizedForNodeCount: number;
+    timestamp: number;
+}
+
+/**
+ * Force Graph Wrapper - Controls Component
+ * Simple graph controls UI for zoom/pan/fit operations
+ */
+type GraphControlsPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+type GraphControlsOrientation = 'vertical' | 'horizontal';
+interface GraphControlsConfig {
+    readonly enabled: boolean;
+    readonly position?: GraphControlsPosition;
+    readonly orientation?: GraphControlsOrientation;
+    readonly offset?: {
+        x: number;
+        y: number;
+    };
+    readonly show?: {
+        readonly zoomIn?: boolean;
+        readonly zoomOut?: boolean;
+        readonly reset?: boolean;
+        readonly fit?: boolean;
+    };
+}
+
+/**
+ * Force Graph Wrapper - Legends Component
+ * Graph legends UI showing node types with colored indicators
+ */
+type GraphLegendsPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+interface GraphLegendsConfig {
+    readonly enabled: boolean;
+    readonly position?: GraphLegendsPosition;
+    readonly offset?: {
+        x: number;
+        y: number;
+    };
+    readonly maxItems?: number;
+    readonly showTitle?: boolean;
+    readonly title?: string;
+}
+
+/**
+ * Configuration Types for Force-Graph Wrapper
+ *
+ * Complete configuration interface combining all aspects
+ * of the force-graph wrapper functionality
+ */
+
+/**
+ * Complete configuration for Force-Graph Wrapper
+ */
+interface ForceGraphConfig<NodeType extends ForceGraphNode = ForceGraphNode, LinkType extends ForceGraphLink<NodeType> = ForceGraphLink<NodeType>> extends ForceConfig, CanvasConfig, InteractionConfig<NodeType, LinkType>, NodeStylingConfig<NodeType>, LinkStylingConfig<LinkType> {
+    /** Container element */
+    container: HTMLElement;
+    /** Graph data */
+    graphData?: ForceGraphData<NodeType, LinkType>;
+    /** Performance monitoring */
+    enablePerformanceMonitoring?: boolean;
+    performanceTargets?: Partial<PerformanceTargets>;
+    /** Page visibility handling for deterministic layouts */
+    handlePageVisibility?: boolean;
+    deterministicLayout?: boolean;
+    /** Graph controls UI */
+    controls?: GraphControlsConfig;
+    /** Graph legends UI */
+    legends?: GraphLegendsConfig;
+    /** Lifecycle callbacks */
+    onEngineTick?: () => void;
+    onEngineStop?: () => void;
+    onZoom?: (transform: {
+        k: number;
+        x: number;
+        y: number;
+    }) => void;
+    onZoomEnd?: (transform: {
+        k: number;
+        x: number;
+        y: number;
+    }) => void;
+}
+/**
+ * Minimal configuration for quick setup
+ */
+interface MinimalForceGraphConfig<NodeType extends ForceGraphNode = ForceGraphNode, LinkType extends ForceGraphLink<NodeType> = ForceGraphLink<NodeType>> {
+    container: HTMLElement;
+    graphData: ForceGraphData<NodeType, LinkType>;
+    width?: number;
+    height?: number;
+}
+/**
+ * Performance-focused configuration
+ */
+interface PerformanceConfig {
+    enablePerformanceMonitoring: true;
+    autoPauseRedraw: boolean;
+    warmupTicks: number;
+    cooldownTime: number;
+    performanceTargets: PerformanceTargets;
+}
+/**
+ * Common presets for different use cases
+ */
+declare const ConfigPresets: {
+    /**
+     * High-performance preset for large graphs (5000+ nodes)
+     */
+    readonly highPerformance: <NodeType extends ForceGraphNode, LinkType extends ForceGraphLink<NodeType>>() => Partial<ForceGraphConfig<NodeType, LinkType>>;
+    /**
+     * Interactive preset for medium graphs (50-1000 nodes)
+     */
+    readonly interactive: <NodeType extends ForceGraphNode, LinkType extends ForceGraphLink<NodeType>>() => Partial<ForceGraphConfig<NodeType, LinkType>>;
+    /**
+     * Minimal preset for small graphs (5-50 nodes)
+     */
+    readonly minimal: <NodeType extends ForceGraphNode, LinkType extends ForceGraphLink<NodeType>>() => Partial<ForceGraphConfig<NodeType, LinkType>>;
+};
+/**
+ * Configuration builder for fluent API
+ */
+declare class ForceGraphConfigBuilder<NodeType extends ForceGraphNode = ForceGraphNode, LinkType extends ForceGraphLink<NodeType> = ForceGraphLink<NodeType>> {
+    private config;
+    constructor(container: HTMLElement);
+    data(graphData: ForceGraphData<NodeType, LinkType>): this;
+    size(width: number, height: number): this;
+    performance(preset: 'highPerformance' | 'interactive' | 'minimal'): this;
+    nodeColor(accessor: NodeStylingConfig<NodeType>['nodeColor']): this;
+    onNodeClick(handler: NodeEventHandler<NodeType>): this;
+    build(): ForceGraphConfig<NodeType, LinkType>;
+}
+
+/**
+ * Performance Monitor for Force-Graph Wrapper
+ *
+ * Built-in performance tracking to catch bottlenecks early
+ * and prevent exponential complexity growth
+ */
+
+declare class PerformanceMonitor {
+    private metrics;
+    private methodCallsDetailed;
+    /**
+     * Track execution time of any operation
+     */
+    track<T>(operation: string, fn: () => T): T;
+    /**
+     * Set specific metric values
+     */
+    setMetric(key: keyof PerformanceMetrics, value: number): void;
+    /**
+     * Get current metrics snapshot
+     */
+    getMetrics(): PerformanceMetrics;
+    /**
+     * Get performance summary with statistics
+     */
+    getSummary(): {
+        averages: Record<string, number>;
+        peaks: Record<string, number>;
+        warnings: string[];
+        nodeScaling: string;
+    };
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+    /**
+     * Log performance summary to console
+     */
+    logSummary(): void;
+}
+
+/**
+ * Core methods available on force-graph instances
+ * These mirror the methods from react-force-graph-2d
+ */
+interface ForceGraphMethods<NodeType extends ForceGraphNode = ForceGraphNode, LinkType extends ForceGraphLink<NodeType> = ForceGraphLink<NodeType>> {
+    d3ReheatSimulation(): void;
+    stopAnimation(): void;
+    pauseAnimation(): void;
+    resumeAnimation(): void;
+    centerAt(x: number, y: number, duration?: number): void;
+    zoom(): number;
+    zoom(scale: number, duration?: number): void;
+    zoomToFit(padding?: number, duration?: number): void;
+    screen2GraphCoords(screenX: number, screenY: number): {
+        x: number;
+        y: number;
+    };
+    graph2ScreenCoords(graphX: number, graphY: number): {
+        x: number;
+        y: number;
+    };
+    getGraphBbox(nodes?: NodeType[]): {
+        x: [number, number];
+        y: [number, number];
+    };
+    emitParticle(link: LinkType): void;
+    d3Force(forceName: string): unknown;
+    d3Force(forceName: string, forceImpl: unknown): ForceGraphInstance<NodeType, LinkType>;
+    exportGraph(fileName?: string): Promise<void>;
+}
+/**
+ * Configuration methods for fluent API
+ */
+interface ForceGraphConfigMethods<NodeType extends ForceGraphNode = ForceGraphNode, LinkType extends ForceGraphLink<NodeType> = ForceGraphLink<NodeType>> {
+    graphData(): ForceGraphData<NodeType, LinkType>;
+    graphData(data: ForceGraphData<NodeType, LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    width(): number;
+    width(width: number): ForceGraphInstance<NodeType, LinkType>;
+    height(): number;
+    height(height: number): ForceGraphInstance<NodeType, LinkType>;
+    backgroundColor(): string;
+    backgroundColor(color: string): ForceGraphInstance<NodeType, LinkType>;
+    nodeRelSize(): number;
+    nodeRelSize(size: number): ForceGraphInstance<NodeType, LinkType>;
+    nodeColor(): ColorAccessor<NodeType>;
+    nodeColor(color: ColorAccessor<NodeType>): ForceGraphInstance<NodeType, LinkType>;
+    nodeVal(): NumberAccessor<NodeType>;
+    nodeVal(val: NumberAccessor<NodeType>): ForceGraphInstance<NodeType, LinkType>;
+    nodeLabel(): StringAccessor<NodeType>;
+    nodeLabel(label: StringAccessor<NodeType>): ForceGraphInstance<NodeType, LinkType>;
+    nodeVisibility(): BooleanAccessor<NodeType>;
+    nodeVisibility(visibility: BooleanAccessor<NodeType>): ForceGraphInstance<NodeType, LinkType>;
+    nodeCanvasObjectMode(): NodeAccessor<NodeType, CanvasCustomRenderMode>;
+    nodeCanvasObjectMode(mode: NodeAccessor<NodeType, CanvasCustomRenderMode>): ForceGraphInstance<NodeType, LinkType>;
+    linkColor(): ColorAccessor<LinkType>;
+    linkColor(color: ColorAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkWidth(): NumberAccessor<LinkType>;
+    linkWidth(width: NumberAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkLabel(): StringAccessor<LinkType>;
+    linkLabel(label: StringAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkVisibility(): BooleanAccessor<LinkType>;
+    linkVisibility(visibility: BooleanAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkDirectionalArrowLength(): NumberAccessor<LinkType>;
+    linkDirectionalArrowLength(length: NumberAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkDirectionalArrowColor(): ColorAccessor<LinkType>;
+    linkDirectionalArrowColor(color: ColorAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkDirectionalArrowRelPos(): NumberAccessor<LinkType>;
+    linkDirectionalArrowRelPos(position: NumberAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkDirectionalParticles(): NumberAccessor<LinkType>;
+    linkDirectionalParticles(particles: NumberAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkDirectionalParticleSpeed(): NumberAccessor<LinkType>;
+    linkDirectionalParticleSpeed(speed: NumberAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkDirectionalParticleWidth(): NumberAccessor<LinkType>;
+    linkDirectionalParticleWidth(width: NumberAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkDirectionalParticleColor(): ColorAccessor<LinkType>;
+    linkDirectionalParticleColor(color: ColorAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkCurvature(): NumberAccessor<LinkType>;
+    linkCurvature(curvature: NumberAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkCanvasObjectMode(): StringAccessor<LinkType>;
+    linkCanvasObjectMode(mode: StringAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    onNodeClick(): NodeEventHandler<NodeType> | null;
+    onNodeClick(handler: NodeEventHandler<NodeType> | null): ForceGraphInstance<NodeType, LinkType>;
+    onNodeDoubleClick(): NodeEventHandler<NodeType> | null;
+    onNodeDoubleClick(handler: NodeEventHandler<NodeType> | null): ForceGraphInstance<NodeType, LinkType>;
+    onNodeHover(): NodeEventHandler<NodeType> | null;
+    onNodeHover(handler: NodeEventHandler<NodeType> | null): ForceGraphInstance<NodeType, LinkType>;
+    onLinkClick(): LinkEventHandler<LinkType> | null;
+    onLinkClick(handler: LinkEventHandler<LinkType> | null): ForceGraphInstance<NodeType, LinkType>;
+    onLinkHover(): LinkEventHandler<LinkType> | null;
+    onLinkHover(handler: LinkEventHandler<LinkType> | null): ForceGraphInstance<NodeType, LinkType>;
+    onRenderFramePre(): CanvasRenderHandler | null;
+    onRenderFramePre(handler: CanvasRenderHandler | null): ForceGraphInstance<NodeType, LinkType>;
+    onRenderFramePost(): CanvasRenderHandler | null;
+    onRenderFramePost(handler: CanvasRenderHandler | null): ForceGraphInstance<NodeType, LinkType>;
+    cooldownTime(): number;
+    cooldownTime(time: number): ForceGraphInstance<NodeType, LinkType>;
+    cooldownTicks(): number;
+    cooldownTicks(ticks: number): ForceGraphInstance<NodeType, LinkType>;
+    d3AlphaDecay(): number;
+    d3AlphaDecay(decay: number): ForceGraphInstance<NodeType, LinkType>;
+    d3AlphaMin(): number;
+    d3AlphaMin(min: number): ForceGraphInstance<NodeType, LinkType>;
+    d3VelocityDecay(): number;
+    d3VelocityDecay(decay: number): ForceGraphInstance<NodeType, LinkType>;
+    enableNodeDrag(): boolean;
+    enableNodeDrag(enable: boolean): ForceGraphInstance<NodeType, LinkType>;
+    enableZoomInteraction(): boolean;
+    enableZoomInteraction(enable: boolean): ForceGraphInstance<NodeType, LinkType>;
+    enablePanInteraction(): boolean;
+    enablePanInteraction(enable: boolean): ForceGraphInstance<NodeType, LinkType>;
+    autoPauseRedraw(): boolean;
+    autoPauseRedraw(enable: boolean): ForceGraphInstance<NodeType, LinkType>;
+    nodeCanvasObject(): ((node: NodeType, ctx: CanvasRenderingContext2D, globalScale: number) => void) | null;
+    nodeCanvasObject(paintFunction: ((node: NodeType, ctx: CanvasRenderingContext2D, globalScale: number) => void) | null): ForceGraphInstance<NodeType, LinkType>;
+    linkCanvasObject(): ((link: LinkType, ctx: CanvasRenderingContext2D, globalScale: number) => void) | null;
+    linkCanvasObject(paintFunction: ((link: LinkType, ctx: CanvasRenderingContext2D, globalScale: number) => void) | null): ForceGraphInstance<NodeType, LinkType>;
+    onEngineStop(): (() => void) | undefined;
+    onEngineStop(handler: (() => void) | undefined): ForceGraphInstance<NodeType, LinkType>;
+    onEngineTick(): (() => void) | undefined;
+    onEngineTick(handler: (() => void) | undefined): ForceGraphInstance<NodeType, LinkType>;
+}
+/**
+ * Performance monitoring methods
+ */
+interface ForceGraphPerformanceMethods {
+    getPerformanceMetrics(): PerformanceMetrics;
+    resetPerformanceMetrics(): void;
+    logPerformanceSummary(): void;
+    validatePerformance(): {
+        passed: boolean;
+        warnings: string[];
+        recommendations: string[];
+    };
+}
+/**
+ * Complete Force-Graph instance interface
+ */
+interface ForceGraphInstance<NodeType extends ForceGraphNode = ForceGraphNode, LinkType extends ForceGraphLink<NodeType> = ForceGraphLink<NodeType>> extends ForceGraphMethods<NodeType, LinkType>, ForceGraphConfigMethods<NodeType, LinkType>, ForceGraphPerformanceMethods {
+    render(): void;
+    destroy(): void;
+    triggerKapsuleUpdate(): void;
+    _getForceGraphInstance(): unknown;
+}
+/**
+ * Factory function type for creating instances
+ */
+interface CreateForceGraphFunction {
+    <NodeType extends ForceGraphNode = ForceGraphNode, LinkType extends ForceGraphLink<NodeType> = ForceGraphLink<NodeType>>(container: HTMLElement): ForceGraphInstance<NodeType, LinkType>;
+}
+
+/**
+ * Step 4: Rendering Performance Monitor
+ *
+ * Monitors canvas rendering performance, frame rates, and optimization metrics
+ * Target: 60fps @ 1000 nodes with smooth animations
+ */
+interface RenderingMetrics {
+    fps: number;
+    averageFps: number;
+    frameTime: number;
+    averageFrameTime: number;
+    droppedFrames: number;
+    renderCalls: number;
+    canvasOperations: number;
+    nodeCount: number;
+    linkCount: number;
+    lastMeasurement: number;
+    renderingEfficiency: number;
+    memoryUsage: number;
+}
+
+/**
+ * Force-Graph Wrapper - Main Implementation
+ *
+ * Framework-independent wrapper around the core force-graph library
+ * with built-in performance monitoring and TypeScript generics
+ */
+
+/**
+ * Main Force-Graph Wrapper Class
+ *
+ * Step 1: Basic class structure with performance monitoring
+ * Target: Creation time < 1ms
+ */
+declare class ForceGraphWrapper<NodeType extends ForceGraphNode = ForceGraphNode, LinkType extends ForceGraphLink<NodeType> = ForceGraphLink<NodeType>> implements ForceGraphInstance<NodeType, LinkType> {
+    private forceGraph;
+    private container;
+    private performanceMonitor;
+    private renderingMonitor;
+    private canvasOptimizer;
+    private config;
+    private isInitialized;
+    private isDestroyed;
+    private isRenderingOptimized;
+    private enableVerboseLogging;
+    private wasInitializedHidden;
+    private visibilityChangeHandler;
+    private wasInitializedOutOfView;
+    private intersectionObserver;
+    private webWorkerPhysicsCompleted;
+    private physicsTimeoutId;
+    private lastKnownDimensions;
+    private deferredFitViewParams;
+    private pendingFitView;
+    private performanceTestInterval;
+    private canvasClickHandler;
+    private exportTimeoutId;
+    private controlsInstance;
+    private legendsInstance;
+    /**
+     * Helper method to safely cast and call methods on the force graph instance
+     */
+    private getGraphInstance;
+    /**
+     * Constructor - Step 1 Performance Test
+     * Target: < 1ms creation time
+     */
+    constructor(container: HTMLElement, config?: Partial<ForceGraphConfig<NodeType, LinkType>>);
+    /**
+     * Step 1 Performance Validation
+     */
+    private validateCreationPerformance;
+    /**
+     * Setup automatic page visibility handling for deterministic layouts
+     * Ensures consistent graph layouts regardless of tab visibility during initialization
+     */
+    private setupPageVisibilityHandling;
+    /**
+     * Cleanup page visibility handling
+     */
+    private cleanupPageVisibilityHandling;
+    /**
+     * Setup deterministic physics handling for viewport visibility
+     * Ensures consistent physics timing regardless of element visibility
+     */
+    private setupDeterministicPhysics;
+    /**
+     * Find the scrollable parent container for intersection observer
+     * Similar to Angular component approach but more generic
+     */
+    private findScrollableParent;
+    /**
+     * Setup deferred fitView mechanism using IntersectionObserver
+     * This handles library-level viewport-aware fitView
+     */
+    private setupDeferredFitView;
+    /**
+     * Execute fitView immediately (bypass visibility checks)
+     */
+    private executeFitViewNow;
+    /**
+     * Cleanup deferred fitView intersection observer
+     */
+    private cleanupDeferredFitView;
+    /**
+     * Cleanup performance test interval
+     */
+    private cleanupPerformanceTest;
+    /**
+     * Cleanup export animation timeout
+     */
+    private cleanupExportTimeout;
+    /**
+     * Cleanup canvas event listeners
+     */
+    private cleanupCanvasEventListeners;
+    /**
+     * Check if element is currently visible (even partially) in viewport
+     */
+    private isElementInViewport;
+    /**
+     * Cache container dimensions when they're valid (non-zero)
+     */
+    private cacheContainerDimensions;
+    /**
+     * Check if container has valid dimensions and cache them
+     */
+    private hasValidDimensions;
+    /**
+     * Run deterministic physics using Web Worker for off-screen graphs only
+     */
+    private runWebWorkerPhysics;
+    /**
+     * Apply Web Worker results to force-graph instance WITHOUT disrupting interactions
+     */
+    private applyWebWorkerResults;
+    /**
+     * Cleanup deterministic physics handling
+     */
+    private cleanupDeterministicPhysics;
+    /**
+     * Initialize the underlying force-graph instance
+     * Step 2: Data loading with performance validation
+     * Target: Linear scaling, < 10ms per 1000 nodes
+     */
+    private initializeForceGraph;
+    /**
+     * Apply configuration to force-graph instance
+     * Step 2: Performance-optimized configuration application
+     */
+    private applyConfiguration;
+    /**
+     * Step 2 Performance Validation for Initialization
+     */
+    private validateInitializationPerformance;
+    /**
+     * Validate data loading performance based on node/link count
+     * Step 2: Linear scaling validation
+     */
+    private validateDataLoadingPerformance;
+    d3ReheatSimulation(): void;
+    stopAnimation(): void;
+    pauseAnimation(): void;
+    resumeAnimation(): void;
+    centerAt(x: number, y: number, duration?: number): void;
+    zoom(): number;
+    zoom(scale: number, duration?: number): void;
+    zoomToFit(padding?: number, duration?: number): void;
+    screen2GraphCoords(screenX: number, screenY: number): {
+        x: number;
+        y: number;
+    };
+    graph2ScreenCoords(graphX: number, graphY: number): {
+        x: number;
+        y: number;
+    };
+    getGraphBbox(nodes?: NodeType[]): {
+        x: [number, number];
+        y: [number, number];
+    };
+    emitParticle(link: LinkType): void;
+    d3Force(forceName: string): unknown;
+    d3Force(forceName: string, forceImpl: unknown): ForceGraphInstance<NodeType, LinkType>;
+    graphData(): ForceGraphData<NodeType, LinkType>;
+    graphData(data: ForceGraphData<NodeType, LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    width(): number;
+    width(width: number): ForceGraphInstance<NodeType, LinkType>;
+    height(): number;
+    height(height: number): ForceGraphInstance<NodeType, LinkType>;
+    backgroundColor(): string;
+    backgroundColor(color: string): ForceGraphInstance<NodeType, LinkType>;
+    nodeColor(): ColorAccessor<NodeType>;
+    nodeColor(color: ColorAccessor<NodeType>): ForceGraphInstance<NodeType, LinkType>;
+    nodeVal(): NumberAccessor<NodeType>;
+    nodeVal(val: NumberAccessor<NodeType>): ForceGraphInstance<NodeType, LinkType>;
+    nodeRelSize(): number;
+    nodeRelSize(size: number): ForceGraphInstance<NodeType, LinkType>;
+    nodeLabel(): StringAccessor<NodeType>;
+    nodeLabel(label: StringAccessor<NodeType>): ForceGraphInstance<NodeType, LinkType>;
+    nodeVisibility(): BooleanAccessor<NodeType>;
+    nodeVisibility(visibility: BooleanAccessor<NodeType>): ForceGraphInstance<NodeType, LinkType>;
+    nodeCanvasObjectMode(): NodeAccessor<NodeType, CanvasCustomRenderMode>;
+    nodeCanvasObjectMode(mode: NodeAccessor<NodeType, CanvasCustomRenderMode>): ForceGraphInstance<NodeType, LinkType>;
+    linkColor(): ColorAccessor<LinkType>;
+    linkColor(color: ColorAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkWidth(): NumberAccessor<LinkType>;
+    linkWidth(width: NumberAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkLabel(): StringAccessor<LinkType>;
+    linkLabel(label: StringAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkVisibility(): BooleanAccessor<LinkType>;
+    linkVisibility(visibility: BooleanAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkDirectionalArrowLength(): NumberAccessor<LinkType>;
+    linkDirectionalArrowLength(length: NumberAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkDirectionalParticles(): NumberAccessor<LinkType>;
+    linkDirectionalParticles(particles: NumberAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkDirectionalArrowColor(): ColorAccessor<LinkType>;
+    linkDirectionalArrowColor(color: ColorAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkDirectionalArrowRelPos(): NumberAccessor<LinkType>;
+    linkDirectionalArrowRelPos(position: NumberAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkDirectionalParticleSpeed(): NumberAccessor<LinkType>;
+    linkDirectionalParticleSpeed(speed: NumberAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkDirectionalParticleWidth(): NumberAccessor<LinkType>;
+    linkDirectionalParticleWidth(width: NumberAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkDirectionalParticleColor(): ColorAccessor<LinkType>;
+    linkDirectionalParticleColor(color: ColorAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkCurvature(): NumberAccessor<LinkType>;
+    linkCurvature(curvature: NumberAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    linkCanvasObjectMode(): StringAccessor<LinkType>;
+    linkCanvasObjectMode(mode: StringAccessor<LinkType>): ForceGraphInstance<NodeType, LinkType>;
+    onNodeClick(): NodeEventHandler<NodeType> | null;
+    onNodeClick(handler: NodeEventHandler<NodeType> | null): ForceGraphInstance<NodeType, LinkType>;
+    onNodeDoubleClick(): NodeEventHandler<NodeType> | null;
+    onNodeDoubleClick(handler: NodeEventHandler<NodeType> | null): ForceGraphInstance<NodeType, LinkType>;
+    onNodeHover(): NodeEventHandler<NodeType> | null;
+    onNodeHover(handler: NodeEventHandler<NodeType> | null): ForceGraphInstance<NodeType, LinkType>;
+    onLinkClick(): LinkEventHandler<LinkType> | null;
+    onLinkClick(handler: LinkEventHandler<LinkType> | null): ForceGraphInstance<NodeType, LinkType>;
+    onLinkHover(): LinkEventHandler<LinkType> | null;
+    onLinkHover(handler: LinkEventHandler<LinkType> | null): ForceGraphInstance<NodeType, LinkType>;
+    onRenderFramePre(): CanvasRenderHandler | null;
+    onRenderFramePre(handler: CanvasRenderHandler | null): ForceGraphInstance<NodeType, LinkType>;
+    onRenderFramePost(): CanvasRenderHandler | null;
+    onRenderFramePost(handler: CanvasRenderHandler | null): ForceGraphInstance<NodeType, LinkType>;
+    cooldownTime(): number;
+    cooldownTime(time: number): ForceGraphInstance<NodeType, LinkType>;
+    d3AlphaDecay(): number;
+    d3AlphaDecay(decay: number): ForceGraphInstance<NodeType, LinkType>;
+    d3VelocityDecay(): number;
+    d3VelocityDecay(decay: number): ForceGraphInstance<NodeType, LinkType>;
+    onEngineStop(): (() => void) | undefined;
+    onEngineStop(handler: (() => void) | undefined): ForceGraphInstance<NodeType, LinkType>;
+    onEngineTick(): (() => void) | undefined;
+    onEngineTick(handler: (() => void) | undefined): ForceGraphInstance<NodeType, LinkType>;
+    getPerformanceMetrics(): PerformanceMetrics;
+    resetPerformanceMetrics(): void;
+    logPerformanceSummary(): void;
+    validatePerformance(): {
+        passed: boolean;
+        warnings: string[];
+        recommendations: string[];
+    };
+    /**
+     * Setup advanced rendering performance monitoring
+     * Target: 60fps @ 1000 nodes with optimizations
+     */
+    private setupRenderingMonitoring;
+    /**
+     * Start advanced rendering performance monitoring
+     */
+    private startRenderingMonitoring;
+    /**
+     * Stop rendering performance monitoring
+     */
+    private stopRenderingMonitoring;
+    /**
+     * Get current rendering performance metrics
+     */
+    getRenderingMetrics(): RenderingMetrics | null;
+    /**
+     * Validate rendering performance against Step 4 targets
+     */
+    validateRenderingPerformance(): {
+        passed: boolean;
+        metrics: RenderingMetrics;
+        validation: {
+            passed: boolean;
+            results: {
+                fpsTarget: {
+                    expected: number;
+                    actual: number;
+                    passed: boolean;
+                };
+                frameTimeTarget: {
+                    expected: number;
+                    actual: number;
+                    passed: boolean;
+                };
+                droppedFramesTarget: {
+                    expected: number;
+                    actual: number;
+                    passed: boolean;
+                };
+                efficiencyTarget: {
+                    expected: number;
+                    actual: number;
+                    passed: boolean;
+                };
+            };
+            overallScore: number;
+        };
+        recommendations: string[];
+    };
+    /**
+     * Optimize rendering for large datasets
+     * Implements performance optimizations based on node count
+     */
+    optimizeForDataset(nodeCount: number): void;
+    /**
+     * Force a rendering performance test
+     * Useful for validation during data loading
+     */
+    testRenderingPerformance(durationMs?: number): Promise<{
+        averageFPS: number;
+        minFPS: number;
+        maxFPS: number;
+        passed: boolean;
+        targetFPS: number;
+    }>;
+    render(): void;
+    cooldownTicks(): number;
+    cooldownTicks(ticks: number): ForceGraphInstance<NodeType, LinkType>;
+    d3AlphaMin(): number;
+    d3AlphaMin(min: number): ForceGraphInstance<NodeType, LinkType>;
+    enableNodeDrag(): boolean;
+    enableNodeDrag(enable: boolean): ForceGraphInstance<NodeType, LinkType>;
+    nodeCanvasObject(): ((node: NodeType, ctx: CanvasRenderingContext2D, globalScale: number) => void) | null;
+    nodeCanvasObject(paintFunction: ((node: NodeType, ctx: CanvasRenderingContext2D, globalScale: number) => void) | null): ForceGraphInstance<NodeType, LinkType>;
+    linkCanvasObject(): ((link: LinkType, ctx: CanvasRenderingContext2D, globalScale: number) => void) | null;
+    linkCanvasObject(paintFunction: ((link: LinkType, ctx: CanvasRenderingContext2D, globalScale: number) => void) | null): ForceGraphInstance<NodeType, LinkType>;
+    autoPauseRedraw(): boolean;
+    autoPauseRedraw(enable: boolean): ForceGraphInstance<NodeType, LinkType>;
+    enableZoomInteraction(): boolean;
+    enableZoomInteraction(enable: boolean): ForceGraphInstance<NodeType, LinkType>;
+    enablePanInteraction(): boolean;
+    enablePanInteraction(enable: boolean): ForceGraphInstance<NodeType, LinkType>;
+    /**
+     * Initialize graph controls if enabled
+     */
+    private initializeControls;
+    /**
+     * Zoom in by a factor of 1.5
+     */
+    private zoomIn;
+    /**
+     * Zoom out by a factor of 0.67
+     */
+    private zoomOut;
+    /**
+     * Fit the graph to the viewport
+     */
+    private fitView;
+    /**
+     * Reset the view to initial state
+     */
+    private resetView;
+    /**
+     * Cleanup graph controls
+     */
+    private cleanupControls;
+    /**
+     * Initialize graph legends if enabled
+     */
+    private initializeLegends;
+    /**
+     * Update legends with current graph data
+     */
+    private updateLegends;
+    /**
+     * Cleanup graph legends
+     */
+    private cleanupLegends;
+    /**
+     * Draw legends on the export canvas (similar to React implementation)
+     */
+    private drawLegendsOnExportCanvas;
+    /**
+     * Draw rounded rectangle helper method
+     */
+    private drawRoundedRect;
+    /**
+     * Export graph as PNG image
+     */
+    exportGraph(fileName?: string): Promise<void>;
+    /**
+     * Setup double-click functionality
+     * - Double-click on node: center and zoom to node
+     * - Double-click on canvas: fit view
+     */
+    private setupDoubleClickHandling;
+    /**
+     * Smooth zoom to fit that animates from current position
+     */
+    private smoothZoomToFit;
+    /**
+     * Trigger Kapsule update to ensure render callbacks continue working
+     * This is essential for onRenderFramePost callbacks after physics simulation stops
+     */
+    triggerKapsuleUpdate(): void;
+    /**
+     * Find node at given graph coordinates
+     */
+    private findNodeAtPosition;
+    destroy(): void;
+    _getForceGraphInstance(): unknown;
+}
+/**
+ * Factory function for creating force-graph instances
+ * Step 1 Performance Target: < 1ms total creation time
+ */
+declare function createForceGraph<NodeType extends ForceGraphNode = ForceGraphNode, LinkType extends ForceGraphLink<NodeType> = ForceGraphLink<NodeType>>(container: HTMLElement, config?: Partial<ForceGraphConfig<NodeType, LinkType>>): ForceGraphInstance<NodeType, LinkType>;
+
+/**
+ * Force-Graph Wrapper - Main Export
+ *
+ * Framework-independent wrapper around force-graph library
+ * with TypeScript generics and performance monitoring
+ */
+
+declare const VERSION = "1.0.0-alpha.1";
+declare const LIBRARY_INFO: {
+    readonly name: "force-graph-wrapper";
+    readonly version: "1.0.0-alpha.1";
+    readonly description: "Framework-independent TypeScript wrapper for force-graph library";
+    readonly performance: "Built-in performance monitoring and optimization";
+    readonly compatibility: "Vanilla JS, React, Angular, Vue.js";
+};
+
+export { type ArrowRenderStyle, type BaseGraphConfig, CanvasManager, type CanvasRenderConfig, type CanvasRenderHandler, type CanvasState, ConfigPresets, type ControlsController, type Coordinates, type CreateForceGraphFunction, DEFAULT_COLORS, DEFAULT_HOVER_STYLES, DEFAULT_LINK_LABEL_STYLE, DEFAULT_LINK_STYLE, type DragConfig, type DragInteractionConfig, DragManager, type DragState, ErrorHandler, type ForceGraphConfig, ForceGraphConfigBuilder, type ForceGraphConfigMethods, type ForceGraphData, type ForceGraphInstance, type ForceGraphLink, type ForceGraphMethods, type ForceGraphNode, type ForceGraphPerformanceMethods, ForceGraphWrapper, type GraphControlsConfig$1 as GraphControlsConfig, type GraphControlsOrientation$1 as GraphControlsOrientation, type GraphControlsPosition$1 as GraphControlsPosition, type GraphInteractionConfig, type GraphLink, type GraphNode, type GraphNodeWithInitial, type GraphTooltipTheme, type HighlightInteractionConfig, type HoverEvent, type HoverInteractionConfig, HoverManager, type HoverState, type HoverStyles, type IconName, type IconSvgName, type InteractionColors, type InteractionConfig$1 as InteractionConfig, LIBRARY_INFO, type LegendConfig, type LegendPosition, type LinkArrowStyle, type LinkColors, type LinkEventHandler, type LinkLabelRenderStyle, type LinkLabelStyle, type LinkRenderStyle, type LinkSelectHandler, type LinkStyle, type MinimalForceGraphConfig, NeutralColor, type NodeColorPalette, type NodeEventHandler, type NodeLabelRenderStyle, type NodeRenderStyle, type NodeSelectHandler, type NodeStyle, type Orientation, type PerformanceConfig, type PerformanceMetrics, PerformanceMonitor, type PhysicsConfig, PhysicsManager, PointerManager, type PointerState, type Position, PrimaryColor, type RenderStyles, Renderer, type ResolvedLinkLabelStyle, type ResolvedLinkStyle, SecondaryColor, type SelectionEvent, type SelectionInteractionConfig, SelectionManager, type SelectionState, type SimulationConfig, StandardColor, type TooltipInteractionConfig, type TooltipPlacement, type UIColors, type V2Config, V2Graph, type V2Instance, type V2Link, type V2Node, VERSION, ValidationError, type ZoomConfig, ZoomManager, createForceGraph, createV2Graph, getIcon, getIconSvg, iconSvg, icons, isValidLinkStyle, isValidNodeStyle, mergeLinkStyle, mergeNodeStyle };