@petrarca/sonnet-graph 0.1.6

package/dist/index.d.ts

@@ -0,0 +1,858 @@
+import * as zustand from 'zustand';
+import { UseBoundStore, StoreApi } from 'zustand';
+import * as react from 'react';
+import react__default, { ReactNode } from 'react';
+import { GraphEdge, GraphNode } from 'reagraph';
+import cytoscape from 'cytoscape';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Visual Graph Model - Domain types combining API data with UI enrichment.
+ *
+ * These types are the canonical graph representation used throughout the application.
+ * They combine backend API data (GraphNode/GraphEdge DTOs) with visual enrichment
+ * (colors, display names, etc.) computed once at the data boundary.
+ *
+ * This is an internal refactoring - NO functional changes to the application.
+ * All behavior, visuals, and capabilities remain identical.
+ */
+/**
+ * Visual enrichment data for a node.
+ * Computed once during data ingress, then reused everywhere.
+ */
+interface NodeVisual {
+    /** User-friendly name extracted from properties (name, title, label, etc.) */
+    displayName: string;
+    /** Color from unified palette based on node label */
+    color: string;
+    /** Optional: Node size (can be computed from degree, importance, etc.) */
+    size?: number;
+    /** Optional: Icon URL for the node */
+    icon?: string;
+}
+/**
+ * Visual enrichment data for an edge.
+ */
+interface EdgeVisual {
+    /** Edge color (typically based on type or neutral color) */
+    color: string;
+    /** Optional: Edge thickness/width */
+    size?: number;
+    /** Optional: Whether to render as dashed line */
+    dashed?: boolean;
+}
+/**
+ * VisualGraphNode - The canonical node type for the application.
+ *
+ * Combines API data (aligned with backend GraphNode DTO) with visual enrichment.
+ * This replaces the previous pattern of using reagraph GraphNode types throughout
+ * the application, which caused coupling to the visualization library.
+ *
+ * Structure matches backend API exactly:
+ * - id_: Unique node identifier
+ * - label_: Node type/class (e.g., "Person", "Movie")
+ * - properties_: Key-value pairs from the database
+ *
+ * Plus visual enrichment for UI consistency:
+ * - visual.displayName: Computed once from properties
+ * - visual.color: Assigned once from unified palette
+ */
+interface VisualGraphNode {
+    id_: number;
+    label_: string;
+    properties_: Record<string, string | number | Array<string | number>>;
+    visual: NodeVisual;
+}
+/**
+ * VisualGraphEdge - The canonical edge type for the application.
+ *
+ * Combines API data (aligned with backend GraphEdge DTO) with visual enrichment.
+ *
+ * Structure matches backend API exactly:
+ * - id_: Unique edge identifier
+ * - label_: Relationship type (e.g., "ACTED_IN", "DIRECTED")
+ * - start_id_: Source node ID
+ * - end_id_: Target node ID
+ * - properties_: Optional key-value pairs
+ *
+ * Plus visual enrichment for UI consistency.
+ */
+interface VisualGraphEdge {
+    id_: number;
+    label_: string;
+    start_id_: number;
+    end_id_: number;
+    properties_?: Record<string, string | number | Array<string | number>>;
+    visual: EdgeVisual;
+}
+/**
+ * Normalized graph structure using visual models.
+ *
+ * Provides O(1) lookup by ID for efficient access in components.
+ * This is the internal representation used by the application after
+ * data is fetched and enriched.
+ */
+interface VisualGraphNormalized {
+    /** Nodes indexed by string ID for O(1) lookup */
+    nodesById: Record<string, VisualGraphNode>;
+    /** Edges indexed by string ID for O(1) lookup */
+    edgesById: Record<string, VisualGraphEdge>;
+    /** Array of all node IDs (for iteration) */
+    nodeIds: string[];
+    /** Array of all edge IDs (for iteration) */
+    edgeIds: string[];
+}
+/**
+ * Type guard to check if an object is a VisualGraphNode.
+ *
+ * @param obj - Object to check
+ * @returns true if obj is a valid VisualGraphNode
+ */
+declare function isVisualNode(obj: unknown): obj is VisualGraphNode;
+/**
+ * Type guard to check if an object is a VisualGraphEdge.
+ *
+ * @param obj - Object to check
+ * @returns true if obj is a valid VisualGraphEdge
+ */
+declare function isVisualEdge(obj: unknown): obj is VisualGraphEdge;
+
+/**
+ * Package-local raw graph types.
+ *
+ * These are the minimal structural types needed by the graph visualization layer.
+ * They are structurally compatible with the API DTO types in `api/types.ts`
+ * (GraphNode, GraphEdge) but live in the domain layer so graph-generic code
+ * does not depend on API/transport types.
+ */
+type GraphProperty = string | number | Array<string | number>;
+type GraphProperties = Record<string, GraphProperty>;
+type RawGraphNode = {
+    id_?: number;
+    label_: string;
+    properties_?: GraphProperties;
+};
+type RawGraphEdge = {
+    id_?: number;
+    label_: string;
+    start_id_: number;
+    end_id_: number;
+    properties_?: GraphProperties;
+};
+/**
+ * Type guard to check if an object is a RawGraphNode (vs RawGraphEdge).
+ * Edges have start_id_ and end_id_ properties, nodes don't.
+ */
+declare function isRawGraphNode(obj: RawGraphNode | RawGraphEdge): obj is RawGraphNode;
+/**
+ * Display configuration from schema metadata.
+ * Mirrors api/types.ts DisplayConfig but lives in the domain layer so
+ * graph-generic code (enrichment, extraction) does not depend on API types.
+ */
+type GraphDisplayConfig = {
+    labelTemplate?: string;
+    labelProperty?: string;
+    fallbackProperty?: string;
+    sortProperty?: string;
+    sortOrder?: "ASC" | "DESC";
+    filterProperty?: string;
+};
+/**
+ * Resolved display config map: node label → GraphDisplayConfig.
+ * Built once from schema data and passed into enrichNodes().
+ * Only labels with explicit display config appear in this map.
+ */
+type LabelDisplayMap = Record<string, GraphDisplayConfig>;
+
+/**
+ * Graph data enrichment - Converts API DTOs to Visual Graph Models.
+ *
+ * This is where API data gets transformed into the domain model with UI enrichment.
+ * Enrichment happens ONCE at the data boundary (in useLiveGraphData), then the
+ * enriched models are used throughout the application.
+ */
+
+/**
+ * Color palette mapping node labels to colors.
+ * Built once from label counts, then used for all nodes.
+ */
+type ColorPalette = Record<string, string>;
+/**
+ * Builds a unified color palette from label counts.
+ *
+ * Colors are assigned to labels based on their order, cycling through BASE_COLORS.
+ * Includes 'neutral' and 'faded' colors for edges and unlabeled nodes.
+ *
+ * @param labelCounts - Object mapping label names to counts
+ * @returns Color palette mapping labels to hex colors
+ *
+ * @example
+ * const counts = { Person: 10, Movie: 5 };
+ * const palette = buildColorPalette(counts);
+ * // { Person: '#f94144', Movie: '#118ab2', neutral: '#6c757d', faded: '#adb5bd' }
+ */
+declare function buildColorPalette(labelCounts: Record<string, number>): ColorPalette;
+/**
+ * Convenience: build a color palette directly from an array of nodes.
+ * Counts labels, then delegates to buildColorPalette.
+ *
+ * @param nodes - Array of nodes (any object with a `label_` string property)
+ * @returns Color palette mapping labels to hex colors
+ */
+declare function buildColorPaletteFromNodes(nodes: {
+    label_: string;
+}[]): ColorPalette;
+/**
+ * Enriches an API node with visual data to create a VisualGraphNode.
+ *
+ * This is the primary transformation from API DTO to domain model.
+ * Extracts displayName from node properties, assigns color from the palette,
+ * and provides fallback to neutral color for unlabeled nodes.
+ *
+ * @param apiNode - Node from backend API
+ * @param colorPalette - Unified color palette
+ * @param displayConfig - Optional resolved GraphDisplayConfig for this node's label
+ * @returns Enriched VisualGraphNode
+ */
+declare function enrichNode(apiNode: RawGraphNode, colorPalette: ColorPalette, displayConfig?: GraphDisplayConfig): VisualGraphNode;
+/**
+ * Enriches an API edge with visual data to create a VisualGraphEdge.
+ *
+ * Adds neutral color and default size to edges for consistent visualization.
+ *
+ * @param apiEdge - Edge from backend API
+ * @param colorPalette - Optional unified color palette (for neutral color)
+ * @returns Enriched VisualGraphEdge
+ */
+declare function enrichEdge(apiEdge: RawGraphEdge, colorPalette?: ColorPalette): VisualGraphEdge;
+/**
+ * Batch enrichment for multiple nodes.
+ * More efficient than calling enrichNode repeatedly.
+ *
+ * @param apiNodes - Array of nodes from backend API
+ * @param colorPalette - Unified color palette
+ * @param labelDisplayMap - Optional resolved display config map (label → GraphDisplayConfig)
+ * @returns Array of enriched VisualGraphNodes
+ */
+declare function enrichNodes(apiNodes: RawGraphNode[], colorPalette: ColorPalette, labelDisplayMap?: LabelDisplayMap): VisualGraphNode[];
+/**
+ * Batch enrichment for multiple edges.
+ * More efficient than calling enrichEdge repeatedly.
+ *
+ * @param apiEdges - Array of edges from backend API
+ * @param colorPalette - Optional unified color palette
+ * @returns Array of enriched VisualGraphEdges
+ */
+declare function enrichEdges(apiEdges: RawGraphEdge[], colorPalette?: ColorPalette): VisualGraphEdge[];
+
+/**
+ * Type alias for backward compatibility during refactoring.
+ * This allows existing code to continue working while we migrate.
+ */
+type NormalizedGraph = VisualGraphNormalized;
+/**
+ * Normalizes visual graph data into an indexed structure for efficient lookups.
+ *
+ * This function converts arrays of nodes and edges into a Record structure
+ * for O(1) lookup by ID, which is essential for performance in graph operations.
+ *
+ * INTERNAL REFACTORING: Function signature changed to use VisualGraph types,
+ * but behavior is identical - same normalization logic, same performance.
+ *
+ * @param nodes - Array of VisualGraphNodes
+ * @param edges - Array of VisualGraphEdges
+ * @returns Normalized graph with indexed nodes and edges
+ */
+declare function normalizeGraph(nodes: VisualGraphNode[], edges: VisualGraphEdge[]): VisualGraphNormalized;
+/**
+ * Empty normalized graph constant for initial state.
+ */
+declare const EMPTY_NORMALIZED: VisualGraphNormalized;
+
+/**
+ * Extract display label from a node or edge using resolved display config.
+ *
+ * @param item    - RawGraphNode or RawGraphEdge
+ * @param displayConfig - Optional resolved GraphDisplayConfig for this label
+ */
+declare function extractDisplayLabel(item: RawGraphNode | RawGraphEdge, displayConfig?: GraphDisplayConfig): string;
+
+/**
+ * Graph Data Hook Interface
+ *
+ * Contract for providing graph data to visualizer components.
+ * Host applications that bring their own data pipeline implement this
+ * instead of (or in addition to) using useLiveGraphData.
+ */
+
+/**
+ * Graph statistics summary
+ */
+interface GraphStatistics {
+    nodes: number;
+    edges: number;
+    node_labels?: Record<string, number>;
+    edge_labels?: Record<string, number>;
+    /** Non-zero for tabular (non-graph) query results */
+    values?: number;
+}
+/**
+ * Contract for providing graph data to visualizer components.
+ *
+ * Implement this in your application when you want to use the graph
+ * visualization without the built-in useLiveGraphData pipeline.
+ *
+ * @example
+ * ```tsx
+ * function useMyGraphData(): GraphDataHook {
+ *   const [nodes, setNodes] = useState<VisualGraphNode[]>([]);
+ *   const [edges, setEdges] = useState<VisualGraphEdge[]>([]);
+ *   // ... fetch and enrich data
+ *   return {
+ *     nodes,
+ *     edges,
+ *     normalized: normalizeGraph(nodes, edges),
+ *     baseNormalized: normalizeGraph(allNodes, allEdges),
+ *     stats: { nodes: nodes.length, edges: edges.length },
+ *     colorPalette: buildColorPalette(labelCounts),
+ *     labelCounts,
+ *     edgeLabelCounts,
+ *   };
+ * }
+ * ```
+ */
+interface GraphDataHook {
+    nodes: VisualGraphNode[];
+    edges: VisualGraphEdge[];
+    normalized: NormalizedGraph;
+    baseNormalized: NormalizedGraph;
+    stats?: GraphStatistics;
+    colorPalette: ColorPalette;
+    labelCounts: Record<string, number>;
+    edgeLabelCounts: Record<string, number>;
+    /** Value rows for tabular (non-graph) query results */
+    values?: string[][];
+}
+
+interface SelectionStore {
+    selectedNodeIds: string[];
+    setSelectedNodeIds: (ids: string[]) => void;
+    selectedEdge: VisualGraphEdge | null;
+    setSelectedEdge: (edge: VisualGraphEdge | null) => void;
+    clear: () => void;
+}
+/**
+ * Factory function to create a new Selection store instance.
+ * Used by workspace system to create isolated store instances per workspace.
+ *
+ * For backward compatibility, the default export is a singleton instance.
+ * Existing code continues to work without changes.
+ */
+declare function createSelectionStore(): zustand.UseBoundStore<zustand.StoreApi<SelectionStore>>;
+
+interface GraphDataStore {
+    /** All nodes (from query + expansions) */
+    nodes: VisualGraphNode[];
+    /** All edges (from query + expansions) */
+    edges: VisualGraphEdge[];
+    /** Query statistics from the last query execution */
+    stats: GraphStatistics | undefined;
+    /** Tabular values from value-set queries */
+    values: string[][];
+    /** Whether the last query was a value-set (tabular) query */
+    isValueSet: boolean;
+    /** IDs of nodes from the original query */
+    queryNodeIds: Set<string>;
+    /** IDs of nodes from expansion operations */
+    expandedNodeIds: Set<string>;
+    /** IDs of edges from the original query */
+    queryEdgeIds: Set<string>;
+    /** IDs of edges from expansion operations */
+    expandedEdgeIds: Set<string>;
+    /**
+     * Set graph data from a query execution.
+     * Replaces all existing data.
+     *
+     * @param nodes - Enriched nodes from query
+     * @param edges - Enriched edges from query
+     * @param stats - Query statistics
+     * @param values - Tabular values for value-set queries
+     * @param isValueSet - Whether this is a value-set query
+     */
+    setQueryData: (nodes: VisualGraphNode[], edges: VisualGraphEdge[], stats?: GraphStatistics, values?: string[][], isValueSet?: boolean) => void;
+    /**
+     * Merge expanded nodes/edges into existing graph.
+     * Deduplicates by ID - existing elements are preserved.
+     *
+     * @param nodes - New nodes from expansion
+     * @param edges - New edges from expansion
+     */
+    mergeExpandedData: (nodes: VisualGraphNode[], edges: VisualGraphEdge[]) => void;
+    /**
+     * Clear all graph data
+     */
+    clear: () => void;
+    /**
+     * Get statistics about data sources
+     */
+    getStats: () => {
+        totalNodes: number;
+        totalEdges: number;
+        queryNodes: number;
+        expandedNodes: number;
+        queryEdges: number;
+        expandedEdges: number;
+    };
+}
+/**
+ * Factory function to create a new GraphData store instance.
+ * Used by workspace system to create isolated store instances per workspace.
+ *
+ * For backward compatibility, the default export is a singleton instance.
+ * Existing code continues to work without changes.
+ */
+declare function createGraphDataStore(): zustand.UseBoundStore<zustand.StoreApi<GraphDataStore>>;
+
+/**
+ * GraphFilterStore - Node/edge label filtering and data-change tracking.
+ *
+ * Graph-generic filtering store. Separated from Cypher-specific
+ * query editing (QueryEditorStore stays in the consumer).
+ */
+interface GraphFilterStore {
+    nodeLabelFilters: string[];
+    allLabelsDisabled: boolean;
+    toggleNodeLabelFilter: (label: string, allAvailableLabels?: string[]) => void;
+    clearNodeLabelFilters: () => void;
+    setNodeLabelFilters: (labels: string[]) => void;
+    toggleAllLabelsDisabled: () => void;
+    edgeLabelFilters: string[];
+    allEdgeLabelsDisabled: boolean;
+    toggleEdgeLabelFilter: (label: string, allAvailableLabels?: string[], edgeToNodeLabels?: Record<string, string[]>) => void;
+    clearEdgeLabelFilters: () => void;
+    setEdgeLabelFilters: (labels: string[]) => void;
+    toggleAllEdgeLabelsDisabled: () => void;
+    lastDataChangeTime: number;
+    notifyDataChange: () => void;
+    resetFilters: () => void;
+}
+declare function createGraphFilterStore(): zustand.UseBoundStore<zustand.StoreApi<GraphFilterStore>>;
+
+/**
+ * GraphFocus Store
+ *
+ * Manages graph element focus/zoom actions across different renderers (Cytoscape, Reagraph).
+ * Provides a decoupled way for tools to request focus on specific elements without
+ * needing direct access to the renderer instance.
+ *
+ * Pattern: tools dispatch focus actions → store holds state → renderers subscribe and react
+ */
+/** Descriptor for a pending focus action */
+interface GraphFocusAction {
+    /** ID of the node or edge to focus on */
+    elementId: string;
+    /** Type of element */
+    elementType: "node" | "edge";
+    /** Action to perform: focus only or focus and select */
+    action: "focus" | "focus-and-select";
+    /** Timestamp ensures uniqueness — triggers subscription even for same element */
+    timestamp: number;
+}
+interface GraphFocusStore {
+    /** Current focus action (null when no action is pending) */
+    focusAction: GraphFocusAction | null;
+    /** Element IDs to show despite active filters (temporary override) */
+    overrideElementIds: Set<string>;
+    /**
+     * Request focus on a graph element.
+     * @param elementId - ID of the node or edge
+     * @param elementType - 'node' or 'edge'
+     * @param shouldSelect - Also select the element after focusing
+     */
+    requestFocus: (elementId: string, elementType: "node" | "edge", shouldSelect: boolean) => void;
+    /** Clear the current focus action and all overrides */
+    clear: () => void;
+    /** Clear filter overrides only (keeps the current focus action) */
+    clearOverrides: () => void;
+}
+/** Create an isolated GraphFocus store instance (use for multi-workspace scenarios). */
+declare function createGraphFocusStore(): zustand.UseBoundStore<zustand.StoreApi<GraphFocusStore>>;
+/** Global singleton — sufficient for single-workspace applications. */
+declare const useGraphFocus: zustand.UseBoundStore<zustand.StoreApi<GraphFocusStore>>;
+
+/**
+ * GraphExploration Store
+ *
+ * Manages visual exploration state for the graph visualizer:
+ * - Focus mode: Show only selected nodes
+ * - Hidden elements: Temporarily hide nodes/edges from view
+ * - Expansion tracking: Track which nodes have been expanded
+ *
+ * This state is separate from:
+ * - Selection (which elements are selected)
+ * - GraphFocus (zoom/pan actions)
+ * - GraphFilter (label filters)
+ */
+
+/**
+ * Store dependencies for GraphExploration.
+ * Allows workspace-specific or global store injection.
+ */
+interface GraphExplorationDeps {
+    graphData: UseBoundStore<StoreApi<GraphDataStore>>;
+    selection: UseBoundStore<StoreApi<SelectionStore>>;
+    graphFocus: UseBoundStore<StoreApi<GraphFocusStore>>;
+    graphFilter: UseBoundStore<StoreApi<GraphFilterStore>>;
+    expandNode: (id: number) => Promise<{
+        nodes: RawGraphNode[];
+        edges: RawGraphEdge[];
+    }>;
+    getNodes: (ids: number[]) => Promise<RawGraphNode[]>;
+    getLabelDisplayMap?: () => LabelDisplayMap;
+}
+interface GraphExplorationStore {
+    /** Node IDs to show in focus mode (empty = not in focus mode) */
+    focusedNodeIds: Set<string>;
+    /** Whether focus mode is active */
+    isFocusMode: boolean;
+    /** Element IDs (nodes + edges) to hide from view */
+    hiddenElementIds: Set<string>;
+    /** Node IDs that have been expanded (for UI feedback) */
+    expandedNodeIds: Set<string>;
+    /**
+     * Enter focus mode showing only specified nodes
+     * @param nodeIds - IDs of nodes to focus on
+     */
+    setFocusMode: (nodeIds: string[]) => void;
+    /**
+     * Enter focus mode on a node and its immediate neighborhood
+     * (includes the node itself + all directly connected nodes)
+     * @param nodeId - ID of the node to focus on
+     */
+    setFocusModeWithNeighborhood: (nodeId: string) => void;
+    /**
+     * Exit focus mode (show all label-filtered nodes)
+     */
+    clearFocusMode: () => void;
+    /**
+     * Hide elements from the graph
+     * @param elementIds - IDs of nodes and/or edges to hide
+     */
+    hideElements: (elementIds: string[]) => void;
+    /**
+     * Show previously hidden elements
+     * @param elementIds - IDs of nodes and/or edges to show
+     */
+    showElements: (elementIds: string[]) => void;
+    /**
+     * Hide all nodes that have paths leading TO the specified node (predecessors/ancestors).
+     * The clicked node itself remains VISIBLE as a boundary marker.
+     * Uses recursive traversal with cycle protection.
+     * @param nodeId - ID of the node (kept visible)
+     */
+    hideNodeIncoming: (nodeId: string) => void;
+    /**
+     * Hide all nodes that have paths FROM the specified node (successors/descendants).
+     * The clicked node itself remains VISIBLE as a boundary marker.
+     * Uses recursive traversal with cycle protection.
+     * @param nodeId - ID of the node (kept visible)
+     */
+    hideNodeOutgoing: (nodeId: string) => void;
+    /**
+     * Hide the edge AND the forward path (target node + all its outgoing connections).
+     * The source node of the edge remains VISIBLE as a boundary marker.
+     * Uses recursive traversal with cycle protection.
+     * @param edgeId - ID of the edge to hide
+     */
+    hideEdgeForwardPath: (edgeId: string) => void;
+    /**
+     * Hide the edge AND the reverse path (source node + all its incoming connections).
+     * The target node of the edge remains VISIBLE as a boundary marker.
+     * Uses recursive traversal with cycle protection.
+     * @param edgeId - ID of the edge to hide
+     */
+    hideEdgeReversePath: (edgeId: string) => void;
+    /**
+     * Focus on edges of a specific type, automatically determining direction from selection state.
+     *
+     * Behavior:
+     * - If 1 node + edge selected: Uses the selected node as reference (outgoing if source, incoming if target)
+     * - If 2 nodes + edge selected: Defaults to outgoing from start node
+     * - Shows all nodes connected via edges of the same type in the determined direction
+     *
+     * @param edgeId - ID of the edge (to get type and endpoints)
+     */
+    focusEdge: (edgeId: string) => void;
+    /**
+     * Focus on a specific edge type: show only edges of this type and their connected nodes.
+     * All other nodes and edges are hidden.
+     *
+     * @param edgeId - ID of the edge (to determine the edge type/label)
+     */
+    focusOnEdgeType: (edgeId: string) => void;
+    /**
+     * Reset all exploration state (clear focus + hidden)
+     * Note: Keeps expandedNodeIds since those nodes are still in the data
+     */
+    resetView: () => void;
+    /**
+     * Reset ALL exploration state including expanded nodes.
+     * Should be called when new query data is loaded to ensure clean state.
+     */
+    resetForNewQuery: () => void;
+    /**
+     * Mark a node as expanded (for UI feedback)
+     * @param nodeId - ID of expanded node
+     */
+    markNodeExpanded: (nodeId: string) => void;
+    /**
+     * Check if a node has been expanded
+     * @param nodeId - ID to check
+     */
+    isNodeExpanded: (nodeId: string) => boolean;
+    /**
+     * Expand a node by fetching connected nodes/edges from backend
+     * and merging them into the graph data.
+     * @param nodeId - ID of the node to expand
+     * @returns Promise that resolves when expansion is complete
+     */
+    expandNode: (nodeId: string) => Promise<void>;
+    /**
+     * Add a node to the graph by ID.
+     * If the node already exists in the graph, just focuses it (if autoFocus=true).
+     * If not, fetches it from the API, enriches it with visual data,
+     * adds it to the graph, and optionally focuses it.
+     *
+     * @param nodeId - ID of the node to add
+     * @param autoFocus - Whether to automatically focus the node after adding (default: false)
+     * @returns Promise that resolves when the node is added/focused
+     */
+    addNodeById: (nodeId: number, autoFocus?: boolean) => Promise<void>;
+}
+/**
+ * Factory function to create a new GraphExploration store instance.
+ * Used by workspace system to create isolated store instances per workspace.
+ *
+ * @param deps - Store and service dependencies (graphData, selection, graphFocus, graphFilter, expandNode, getNodes)
+ */
+declare function createGraphExplorationStore(deps: GraphExplorationDeps): UseBoundStore<StoreApi<GraphExplorationStore>>;
+
+type ActionPanelState = "hidden" | "visible";
+interface ActionPanelStore {
+    state: ActionPanelState;
+    setState: (state: ActionPanelState) => void;
+    hide: () => void;
+    show: () => void;
+    isHidden: () => boolean;
+}
+/** Create an isolated ActionPanel store instance. */
+declare function createActionPanelStore(): zustand.UseBoundStore<zustand.StoreApi<ActionPanelStore>>;
+/** Global singleton — sufficient for single-workspace applications. */
+declare const useActionPanelStore: zustand.UseBoundStore<zustand.StoreApi<ActionPanelStore>>;
+
+/**
+ * Store factory types for workspace-isolated store instances.
+ */
+
+/**
+ * Generic store factory type that creates new store instances.
+ */
+type StoreFactory<T> = () => UseBoundStore<StoreApi<T>>;
+/**
+ * Bundle of graph-related workspace-scoped store instances.
+ * Each workspace gets its own isolated set of these stores.
+ *
+ * Note: QueryEditorStore stays in the consumer (e.g., explorer) since
+ * it is Cypher/query-specific, not part of generic graph visualization.
+ */
+interface WorkspaceStores {
+    graphFilter: UseBoundStore<StoreApi<GraphFilterStore>>;
+    graphData: UseBoundStore<StoreApi<GraphDataStore>>;
+    graphExploration: UseBoundStore<StoreApi<GraphExplorationStore>>;
+    selection: UseBoundStore<StoreApi<SelectionStore>>;
+}
+
+/**
+ * Context for providing graph stores to visualization components.
+ * Must be set by the host application (e.g., explorer, Atlas).
+ */
+declare const GraphStoresContext: react.Context<WorkspaceStores | null>;
+/** Get GraphFilter store from context. */
+declare function useWorkspaceGraphFilter(): UseBoundStore<StoreApi<GraphFilterStore>>;
+/** Get GraphData store from context. */
+declare function useWorkspaceGraphData(): UseBoundStore<StoreApi<GraphDataStore>>;
+/** Get GraphExploration store from context. */
+declare function useWorkspaceGraphExploration(): UseBoundStore<StoreApi<GraphExplorationStore>>;
+/** Get Selection store from context. */
+declare function useWorkspaceSelection(): UseBoundStore<StoreApi<SelectionStore>>;
+
+/**
+ * Result type for useLiveGraphData hook.
+ *
+ * Returns enriched VisualGraph data with color palette and statistics.
+ */
+interface LiveGraphDataResult {
+    nodes: VisualGraphNode[];
+    edges: VisualGraphEdge[];
+    stats: GraphStatistics | undefined;
+    /** Node label counts after hidden/focus filters, before label-checkbox filters */
+    labelCounts: Record<string, number>;
+    /** Edge label counts after node visibility filters, before edge-label-checkbox filters */
+    edgeLabelCounts: Record<string, number>;
+    /** Value rows for non-graph (tabular) query results */
+    values: string[][];
+    colorPalette: ColorPalette;
+    /** Filtered graph for visualization (respects all active filters) */
+    normalized: NormalizedGraph;
+    /** Unfiltered graph containing all nodes/edges from the last query */
+    baseNormalized: NormalizedGraph;
+}
+declare function useLiveGraphData(): {
+    nodes: VisualGraphNode[];
+    edges: VisualGraphEdge[];
+    stats: {
+        nodes: number;
+        edges: number;
+        node_labels?: Record<string, number>;
+        edge_labels?: Record<string, number>;
+        values?: number;
+    } | undefined;
+    labelCounts: Record<string, number>;
+    edgeLabelCounts: Record<string, number>;
+    values: string[][];
+    colorPalette: ColorPalette;
+    normalized: VisualGraphNormalized;
+    baseNormalized: VisualGraphNormalized;
+};
+
+/**
+ * Converts a VisualGraphNode to reagraph's node format.
+ * Exported for use in tests and custom renderers.
+ */
+declare function toReagraphNode(visualNode: VisualGraphNode): GraphNode;
+/**
+ * Converts a VisualGraphEdge to reagraph's edge format.
+ * Exported for use in tests and custom renderers.
+ */
+declare function toReagraphEdge(visualEdge: VisualGraphEdge): GraphEdge;
+/**
+ * Returns live graph data converted to reagraph's node/edge format.
+ * Consumes the workspace GraphData + filter stores via useLiveGraphData.
+ */
+declare function useReagraphData(): {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    stats: {
+        nodes: number;
+        edges: number;
+        node_labels?: Record<string, number>;
+        edge_labels?: Record<string, number>;
+        values?: number;
+    } | undefined;
+    colorPalette: ColorPalette;
+};
+
+/**
+ * Converts a VisualGraphNode to Cytoscape's element format.
+ * Exported for use in tests and custom renderers.
+ */
+declare function toCytoscapeNode(visualNode: VisualGraphNode): {
+    data: {
+        id: string;
+        label: string;
+        id_: number;
+        label_: string;
+        properties_: Record<string, string | number | (string | number)[]>;
+        displayName: string;
+        color: string;
+        size: number;
+        icon: string | undefined;
+        visualGraph: VisualGraphNode;
+    };
+};
+/**
+ * Converts a VisualGraphEdge to Cytoscape's element format.
+ * Exported for use in tests and custom renderers.
+ */
+declare function toCytoscapeEdge(visualEdge: VisualGraphEdge): {
+    data: {
+        id: string;
+        source: string;
+        target: string;
+        label: string;
+        id_: number;
+        label_: string;
+        start_id_: number;
+        end_id_: number;
+        properties_: Record<string, string | number | (string | number)[]> | undefined;
+        color: string;
+        size: number;
+        dashed: true | undefined;
+    };
+};
+/**
+ * Returns live graph data converted to Cytoscape's element format.
+ * Consumes the workspace GraphData + filter stores via useLiveGraphData.
+ */
+declare function useCytoscapeData(): {
+    elements: cytoscape.ElementsDefinition;
+    stats: {
+        nodes: number;
+        edges: number;
+        node_labels?: Record<string, number>;
+        edge_labels?: Record<string, number>;
+        values?: number;
+    } | undefined;
+    colorPalette: ColorPalette;
+};
+
+type GraphRenderer = "reagraph" | "cytoscape";
+type GraphRendererContextType = {
+    renderer: GraphRenderer;
+    setRenderer: (renderer: GraphRenderer) => void;
+};
+declare function useGraphRenderer(): GraphRendererContextType;
+
+type ProviderProps = {
+    children: react__default.ReactNode;
+    /**
+     * Initial renderer to use. Defaults to 'cytoscape'.
+     * The host application controls which renderer is active — typically
+     * driven by route state, user preference, or local storage.
+     */
+    defaultRenderer?: GraphRenderer;
+    /**
+     * Optional callback invoked when the user switches renderer via the toolbar.
+     * Use this to persist the choice (e.g. URL, localStorage, zustand store).
+     */
+    onRendererChange?: (renderer: GraphRenderer) => void;
+};
+declare function GraphRendererProvider({ children, defaultRenderer, onRendererChange, }: ProviderProps): react__default.ReactElement;
+
+interface GraphVisualizerProps {
+    /** Callback when a node is copied (e.g. to clipboard). Decouples renderers from clipboard store. */
+    onCopyNode?: (node: VisualGraphNode) => void;
+    /** Extra toolbar content (e.g. clipboard UI) injected into the renderer toolbar. */
+    extraToolbarContent?: ReactNode;
+}
+declare function GraphVisualizer({ onCopyNode, extraToolbarContent, }: GraphVisualizerProps): react_jsx_runtime.JSX.Element;
+
+interface ActionPanelProps {
+    /** Optional actions rendered at the top of the panel (e.g. CRUD buttons) */
+    actions?: ReactNode;
+}
+declare function ActionPanel({ actions }: ActionPanelProps): react_jsx_runtime.JSX.Element;
+
+type Props$1 = {
+    node: VisualGraphNode;
+};
+declare function NodeInfoCard({ node }: Props$1): react_jsx_runtime.JSX.Element;
+
+type Props = {
+    edge: VisualGraphEdge;
+};
+declare function EdgeInfoCard({ edge }: Props): react_jsx_runtime.JSX.Element;
+
+declare function Overview(): react_jsx_runtime.JSX.Element | null;
+
+export { ActionPanel, type ActionPanelState, type ActionPanelStore, type ColorPalette, EMPTY_NORMALIZED, EdgeInfoCard, type EdgeVisual, type GraphDataHook, type GraphDataStore, type GraphDisplayConfig, type GraphExplorationDeps, type GraphExplorationStore, type GraphFilterStore, type GraphFocusAction, type GraphFocusStore, type GraphProperties, type GraphProperty, type GraphRenderer, GraphRendererProvider, type GraphStatistics, type WorkspaceStores as GraphStoreBundle, GraphStoresContext, GraphVisualizer, type GraphVisualizerProps, type LabelDisplayMap, type LiveGraphDataResult, NodeInfoCard, type NodeVisual, type NormalizedGraph, Overview, type RawGraphEdge, type RawGraphNode, type SelectionStore, type StoreFactory, type VisualGraphEdge, type VisualGraphNode, type VisualGraphNormalized, type WorkspaceStores, buildColorPalette, buildColorPaletteFromNodes, createActionPanelStore, createGraphDataStore, createGraphExplorationStore, createGraphFilterStore, createGraphFocusStore, createSelectionStore, enrichEdge, enrichEdges, enrichNode, enrichNodes, extractDisplayLabel, isRawGraphNode, isVisualEdge, isVisualNode, normalizeGraph, toCytoscapeEdge, toCytoscapeNode, toReagraphEdge, toReagraphNode, useActionPanelStore, useCytoscapeData, useGraphFocus, useGraphRenderer, useLiveGraphData, useReagraphData, useWorkspaceGraphData, useWorkspaceGraphExploration, useWorkspaceGraphFilter, useWorkspaceSelection };