codeviz 0.1.1 → 0.1.3

package/dist/useOverlayPort-dGxZQTue.d.ts

@@ -0,0 +1,2448 @@
+import Graph__default from 'graphology';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as _xyflow_react from '@xyflow/react';
+import { Viewport, Node, Edge, NodeMouseHandler, OnSelectionChangeParams, NodeProps, EdgeProps } from '@xyflow/react';
+import { Attributes } from 'graphology-types';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { LucideIcon } from 'lucide-react';
+
+/**
+ * Core type definitions for CodeViz
+ *
+ * @packageDocumentation
+ */
+/** 2D position coordinates */
+interface Position {
+    x: number;
+    y: number;
+}
+/** Size dimensions */
+interface Size {
+    width: number;
+    height: number;
+}
+/** Bounding box defined by position and size */
+interface BoundingBox$1 {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Padding for containment regions */
+interface Padding {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Source code location within a file */
+interface SourceLocation {
+    startLine: number;
+    startColumn: number;
+    endLine: number;
+    endColumn: number;
+}
+/** Metrics for a single file */
+interface FileMetrics {
+    /** Lines of code (excluding blank lines and comments) */
+    loc: number;
+    /** Total lines including blanks and comments */
+    totalLines: number;
+    /** Number of exported symbols */
+    exportCount: number;
+    /** Number of import statements */
+    importCount: number;
+    /** Cyclomatic complexity (if computed) */
+    complexity?: number;
+}
+/** Metrics for a directory (aggregated from children) */
+interface DirectoryMetrics {
+    /** Total files in directory (recursive) */
+    fileCount: number;
+    /** Total lines of code (recursive) */
+    totalLoc: number;
+    /** Average complexity of files */
+    avgComplexity?: number;
+}
+/** Metrics for a code symbol */
+interface SymbolMetrics {
+    /** Lines of code for this symbol */
+    loc: number;
+    /** Parameter count (for functions/methods) */
+    parameterCount?: number;
+    /** Cyclomatic complexity */
+    complexity?: number;
+}
+/** A file in the codebase */
+interface FileNode$1 {
+    /** Unique identifier (derived from path) */
+    id: string;
+    /** Full path relative to root */
+    path: string;
+    /** File name without directory */
+    name: string;
+    /** File extension (e.g., 'ts', 'py') */
+    extension: string;
+    /** ID of containing directory */
+    directoryId: string;
+    /** File metrics */
+    metrics: FileMetrics;
+    /** IDs of symbols defined in this file */
+    symbols: string[];
+    /** Language identifier */
+    language: string;
+    /** Whether file has parse errors */
+    hasParseErrors?: boolean;
+    /** Git conflict status */
+    hasGitConflicts?: boolean;
+}
+/** A directory in the codebase */
+interface DirectoryNode {
+    /** Unique identifier (derived from path) */
+    id: string;
+    /** Full path relative to root */
+    path: string;
+    /** Directory name */
+    name: string;
+    /** ID of parent directory (null for root) */
+    parentId: string | null;
+    /** IDs of child directories */
+    children: string[];
+    /** IDs of files directly in this directory */
+    files: string[];
+    /** Aggregated metrics */
+    metrics: DirectoryMetrics;
+    /** Nesting depth (0 for root) */
+    depth: number;
+}
+/** Kind of code symbol */
+type SymbolKind = 'function' | 'class' | 'method' | 'variable' | 'constant' | 'type' | 'interface' | 'enum' | 'namespace' | 'property';
+/** A code symbol (function, class, etc.) */
+interface SymbolNode$1 {
+    /** Unique identifier */
+    id: string;
+    /** Symbol name */
+    name: string;
+    /** Symbol kind */
+    kind: SymbolKind;
+    /** ID of containing file */
+    fileId: string;
+    /** Location in source file */
+    location: SourceLocation;
+    /** Function/method signature */
+    signature?: string;
+    /** Whether symbol is exported */
+    exported: boolean;
+    /** Symbol metrics */
+    metrics: SymbolMetrics;
+    /** Parent symbol ID (for methods in classes) */
+    parentSymbolId?: string;
+}
+/** An import relationship between files */
+interface ImportEdge$1 {
+    /** Unique identifier */
+    id: string;
+    /** Source file ID (the file with the import statement) */
+    sourceId: string;
+    /** Target file ID (the file being imported) */
+    targetId: string;
+    /** Import type */
+    importType: 'static' | 'dynamic' | 'type-only';
+    /** Specific symbols imported (empty for namespace imports) */
+    importedSymbols: string[];
+    /** Whether the import could be resolved */
+    resolved: boolean;
+}
+/** A call relationship between symbols */
+interface CallEdge$1 {
+    /** Unique identifier */
+    id: string;
+    /** Caller symbol ID */
+    sourceId: string;
+    /** Callee symbol ID */
+    targetId: string;
+    /** Number of call sites */
+    callCount: number;
+    /** Whether the call target could be resolved */
+    resolved: boolean;
+}
+/** Metadata about the analyzed codebase */
+interface CodebaseMetadata {
+    /** Root directory path */
+    rootPath: string;
+    /** Analysis timestamp */
+    analyzedAt: string;
+    /** Total file count */
+    totalFiles: number;
+    /** Total directory count */
+    totalDirectories: number;
+    /** Total symbol count */
+    totalSymbols: number;
+    /** Languages detected */
+    languages: string[];
+    /** Analysis duration in milliseconds */
+    analysisDurationMs: number;
+}
+/** Complete code graph - input to layout computation */
+interface CodeGraph {
+    /** All files in the codebase */
+    files: FileNode$1[];
+    /** All directories in the codebase */
+    directories: DirectoryNode[];
+    /** All symbols in the codebase */
+    symbols: SymbolNode$1[];
+    /** All import relationships */
+    imports: ImportEdge$1[];
+    /** All call relationships */
+    calls: CallEdge$1[];
+    /** Codebase metadata */
+    metadata: CodebaseMetadata;
+}
+/** Type of entity a map node represents */
+type MapNodeType = 'file' | 'symbol' | 'aggregate';
+/** Visual data for a map node */
+interface MapNodeData {
+    /** Display label */
+    label: string;
+    /** Truncated label for low zoom */
+    shortLabel: string;
+    /** Icon identifier */
+    icon: string;
+    /** Original entity reference */
+    entityId: string;
+    /** Entity type */
+    entityType: 'file' | 'symbol';
+    /** Metrics for sizing */
+    metrics: FileMetrics | SymbolMetrics;
+    /** File extension or symbol kind */
+    subtype: string;
+}
+/** Visual data for an aggregate node */
+interface AggregateNodeData {
+    /** Display label */
+    label: string;
+    /** Number of aggregated items */
+    count: number;
+    /** Total LOC of aggregated items */
+    totalLoc: number;
+    /** Aggregated entity IDs */
+    entityIds: string[];
+}
+/** A positioned node on the map */
+interface MapNode {
+    /** Unique identifier */
+    id: string;
+    /** Original entity ID from CodeGraph */
+    entityId: string;
+    /** Node type */
+    type: MapNodeType;
+    /** Computed position */
+    position: Position;
+    /** Computed size */
+    size: Size;
+    /** Containing scope ID */
+    scopeId: string;
+    /** Nesting depth */
+    depth: number;
+    /** Node visual data */
+    data: MapNodeData | AggregateNodeData;
+    /** Visibility by zoom level (0-4) */
+    visibleAtLevels: number[];
+}
+/** Visual data for a scope */
+interface MapScopeData {
+    /** Display label */
+    label: string;
+    /** File count in scope */
+    fileCount: number;
+    /** Total LOC in scope */
+    totalLoc: number;
+    /** Whether scope is expanded */
+    expanded: boolean;
+}
+/** A containment region (directory) on the map */
+interface MapScope {
+    /** Unique identifier */
+    id: string;
+    /** Original directory ID from CodeGraph */
+    entityId: string;
+    /** Parent scope ID (null for root) */
+    parentId: string | null;
+    /** Computed bounds */
+    bounds: BoundingBox$1;
+    /** Inner padding */
+    padding: Padding;
+    /** Nesting depth */
+    depth: number;
+    /** Scope visual data */
+    data: MapScopeData;
+    /** Child scope IDs */
+    children: string[];
+    /** Node IDs directly in this scope */
+    nodes: string[];
+}
+/** Edge type for visualization */
+type MapEdgeType = 'import' | 'call' | 'bundled';
+/** A visual edge on the map */
+interface MapEdge {
+    /** Unique identifier */
+    id: string;
+    /** Source node ID */
+    sourceId: string;
+    /** Target node ID */
+    targetId: string;
+    /** Edge type */
+    type: MapEdgeType;
+    /** Edge weight (for bundled edges, count of aggregated edges) */
+    weight: number;
+    /** Original edge IDs (for bundled edges) */
+    originalEdgeIds?: string[];
+    /** Visibility by zoom level (0-4) */
+    visibleAtLevels: number[];
+}
+/** Semantic zoom level (0-4) */
+type ZoomLevel = 0 | 1 | 2 | 3 | 4;
+/** Zoom level names */
+type ZoomLevelName = 'overview' | 'modules' | 'files' | 'symbols' | 'code';
+/** Configuration for a single zoom level */
+interface ZoomLevelConfig {
+    /** Zoom level number */
+    level: ZoomLevel;
+    /** Human-readable name */
+    name: ZoomLevelName;
+    /** Minimum zoom factor for this level */
+    minZoom: number;
+    /** Maximum zoom factor for this level */
+    maxZoom: number;
+    /** Whether to show file nodes at this level */
+    showFiles: boolean;
+    /** Minimum LOC for file to be visible (0 = all) */
+    minFileLoc: number;
+    /** Whether to show symbol nodes at this level */
+    showSymbols: boolean;
+    /** Whether to show call edges at this level */
+    showCallEdges: boolean;
+    /** Edge bundling strategy */
+    edgeBundling: 'aggregate' | 'hierarchical' | 'none';
+    /** Whether to show labels */
+    showLabels: boolean;
+    /** Maximum label length */
+    maxLabelLength: number;
+}
+/** Default zoom level configurations */
+declare const DEFAULT_ZOOM_LEVELS: ZoomLevelConfig[];
+/** Layout algorithm configuration */
+interface LayoutConfig {
+    /** ForceAtlas2 iterations */
+    iterations: number;
+    /** Gravity strength */
+    gravity: number;
+    /** Scaling ratio */
+    scalingRatio: number;
+    /** Scope padding */
+    scopePadding: Padding;
+    /** Minimum node size in pixels */
+    minNodeSize: number;
+    /** Maximum node size in pixels */
+    maxNodeSize: number;
+    /** Metric to use for node sizing */
+    sizeMetric: 'loc' | 'complexity' | 'uniform';
+    /** Minimum spacing between nodes */
+    nodeSpacing: number;
+    /** Random seed for reproducible layouts */
+    seed?: number;
+}
+/** Default layout configuration */
+declare const DEFAULT_LAYOUT_CONFIG: LayoutConfig;
+/** Complete positioned code map - output of layout computation */
+interface CodeMap$1 {
+    /** All positioned nodes */
+    nodes: MapNode[];
+    /** All scopes (directory regions) */
+    scopes: MapScope[];
+    /** All edges */
+    edges: MapEdge[];
+    /** Overall bounds of the map */
+    bounds: BoundingBox$1;
+    /** Zoom level configurations */
+    zoomLevels: ZoomLevelConfig[];
+    /** Layout configuration used */
+    layoutConfig: LayoutConfig;
+    /** Source code graph reference */
+    codeGraphMetadata: CodebaseMetadata;
+}
+/** Animation configuration */
+interface AnimationConfig {
+    /** Enable animations globally */
+    enabled: boolean;
+    /** Respect prefers-reduced-motion */
+    respectReducedMotion: boolean;
+    /** Zoom transition duration (ms) */
+    zoomTransitionDuration: number;
+    /** Scope toggle duration (ms) */
+    scopeToggleDuration: number;
+    /** Node appear duration (ms) */
+    nodeAppearDuration: number;
+    /** Cursor interpolation duration (ms) */
+    cursorInterpolationDuration: number;
+}
+/** Default animation configuration */
+declare const DEFAULT_ANIMATION_CONFIG: AnimationConfig;
+/** Main CodeMap component configuration */
+interface CodeMapConfig {
+    /** Zoom level configurations */
+    zoomLevels?: ZoomLevelConfig[];
+    /** Layout configuration */
+    layout?: Partial<LayoutConfig>;
+    /** Animation configuration */
+    animation?: Partial<AnimationConfig>;
+    /** Hysteresis percentage for zoom level transitions (0-1) */
+    zoomHysteresis?: number;
+    /** Initial zoom level */
+    initialZoomLevel?: ZoomLevel;
+    /** Initial viewport center */
+    initialCenter?: Position;
+}
+/** Default CodeMap configuration */
+declare const DEFAULT_CODEMAP_CONFIG: Required<CodeMapConfig>;
+
+/**
+ * Core utility functions for CodeViz
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Generate a deterministic ID from a file path.
+ * Uses a simple hash to create a short, URL-safe identifier.
+ */
+declare function generateFileId(path: string): string;
+/**
+ * Generate a deterministic ID from a directory path.
+ */
+declare function generateDirectoryId(path: string): string;
+/**
+ * Generate a deterministic ID for a symbol.
+ */
+declare function generateSymbolId(filePath: string, symbolName: string, line: number): string;
+/**
+ * Generate a deterministic ID for an import edge.
+ */
+declare function generateImportEdgeId(sourceId: string, targetId: string): string;
+/**
+ * Generate a deterministic ID for a call edge.
+ */
+declare function generateCallEdgeId(sourceId: string, targetId: string): string;
+/**
+ * Normalize a path to use forward slashes and remove trailing slashes.
+ */
+declare function normalizePath(path: string): string;
+/**
+ * Get the directory portion of a path.
+ */
+declare function getDirectory(path: string): string;
+/**
+ * Get the filename from a path.
+ */
+declare function getFilename(path: string): string;
+/**
+ * Get the file extension (without dot).
+ */
+declare function getExtension(path: string): string;
+/**
+ * Get the filename without extension.
+ */
+declare function getBasename(path: string): string;
+/**
+ * Get all parent directories of a path.
+ * Returns paths from immediate parent to root.
+ */
+declare function getParentDirectories(path: string): string[];
+/**
+ * Get the depth of a path (number of directory levels).
+ */
+declare function getPathDepth(path: string): number;
+/**
+ * Check if a path matches any of the given glob patterns.
+ * Simple implementation supporting * and ** wildcards.
+ */
+declare function matchesPattern(path: string, patterns: string[]): boolean;
+/**
+ * Create a bounding box from position and size.
+ */
+declare function createBoundingBox(position: Position, size: Size): BoundingBox$1;
+/**
+ * Create a bounding box from corner points.
+ */
+declare function boundingBoxFromCorners(topLeft: Position, bottomRight: Position): BoundingBox$1;
+/**
+ * Get the center point of a bounding box.
+ */
+declare function getBoundingBoxCenter(box: BoundingBox$1): Position;
+/**
+ * Check if a point is inside a bounding box.
+ */
+declare function isPointInBoundingBox(point: Position, box: BoundingBox$1): boolean;
+/**
+ * Check if two bounding boxes overlap.
+ */
+declare function boundingBoxesOverlap(a: BoundingBox$1, b: BoundingBox$1): boolean;
+/**
+ * Get the union of multiple bounding boxes.
+ */
+declare function unionBoundingBoxes(boxes: BoundingBox$1[]): BoundingBox$1;
+/**
+ * Expand a bounding box by padding.
+ */
+declare function expandBoundingBox(box: BoundingBox$1, padding: Padding): BoundingBox$1;
+/**
+ * Shrink a bounding box by padding (inner content area).
+ */
+declare function shrinkBoundingBox(box: BoundingBox$1, padding: Padding): BoundingBox$1;
+/**
+ * Calculate distance between two positions.
+ */
+declare function distance(a: Position, b: Position): number;
+/**
+ * Linearly interpolate between two positions.
+ */
+declare function lerp(a: Position, b: Position, t: number): Position;
+/**
+ * Clamp a position within a bounding box.
+ */
+declare function clampPosition(position: Position, bounds: BoundingBox$1): Position;
+/**
+ * Scale a size uniformly.
+ */
+declare function scaleSize(size: Size, factor: number): Size;
+/**
+ * Create uniform padding.
+ */
+declare function uniformPadding(value: number): Padding;
+/**
+ * Determine the semantic zoom level from a zoom factor.
+ * Applies hysteresis to prevent flickering at boundaries.
+ */
+declare function getZoomLevel(zoomFactor: number, currentLevel: number, thresholds: {
+    min: number;
+    max: number;
+}[], hysteresis?: number): number;
+/**
+ * Truncate a label to a maximum length with ellipsis.
+ */
+declare function truncateLabel(label: string, maxLength: number): string;
+/**
+ * Get a short label for a file (just the filename).
+ */
+declare function getShortFileLabel(path: string): string;
+/**
+ * Get a medium label for a file (parent/filename).
+ */
+declare function getMediumFileLabel(path: string): string;
+/**
+ * Detect language from file extension.
+ */
+declare function detectLanguage(path: string): string;
+/**
+ * Check if a file extension represents a code file.
+ */
+declare function isCodeFile(path: string): boolean;
+/**
+ * Get the Lucide icon name for a file or symbol.
+ */
+declare function getIconName(type: string): string;
+
+/**
+ * Theme type definitions for CodeViz
+ *
+ * @packageDocumentation
+ */
+/** RGB color values (0-255) */
+interface RGBColor {
+    r: number;
+    g: number;
+    b: number;
+}
+/** Color with optional alpha */
+interface RGBAColor extends RGBColor {
+    a?: number;
+}
+/** Color palette for a specific element */
+interface ColorPalette {
+    /** Primary/default color */
+    primary: string;
+    /** Secondary/muted color */
+    secondary: string;
+    /** Accent/highlight color */
+    accent: string;
+    /** Hover state color */
+    hover: string;
+    /** Selected state color */
+    selected: string;
+    /** Muted/disabled color */
+    muted: string;
+}
+/** Colors for scope depth visualization */
+interface ScopeDepthColors {
+    /** Base hue for the color family (0-360) */
+    baseHue: number;
+    /** Saturation range [min, max] (0-100) */
+    saturationRange: [number, number];
+    /** Lightness range [min, max] for light theme (0-100) */
+    lightnessRangeLight: [number, number];
+    /** Lightness range [min, max] for dark theme (0-100) */
+    lightnessRangeDark: [number, number];
+    /** Maximum depth before colors repeat */
+    maxDepth: number;
+}
+/** Colors for different node types */
+interface NodeColors {
+    /** File node colors */
+    file: ColorPalette;
+    /** Symbol node colors */
+    symbol: ColorPalette;
+    /** Aggregate node colors */
+    aggregate: ColorPalette;
+    /** Scope/directory colors */
+    scope: ColorPalette;
+}
+/** Colors for different edge types */
+interface EdgeColors {
+    /** Import edge color */
+    import: string;
+    /** Call edge color */
+    call: string;
+    /** Bundled/aggregated edge color */
+    bundled: string;
+    /** Edge hover color */
+    hover: string;
+}
+/** Colors for overlays */
+interface OverlayColors {
+    /** Cursor overlay color */
+    cursor: string;
+    /** Highlight overlay color */
+    highlight: string;
+    /** Error indicator color */
+    error: string;
+    /** Warning indicator color */
+    warning: string;
+    /** Success indicator color */
+    success: string;
+    /** Info indicator color */
+    info: string;
+}
+/** Colors for UI elements */
+interface UIColors {
+    /** Background color */
+    background: string;
+    /** Surface/card background */
+    surface: string;
+    /** Primary text color */
+    text: string;
+    /** Secondary/muted text */
+    textMuted: string;
+    /** Border color */
+    border: string;
+    /** Focus ring color */
+    focusRing: string;
+}
+/** Sigma-specific node colors by type */
+interface SigmaNodeColors {
+    directory: string;
+    file: string;
+    aggregate: string;
+    function: string;
+    class: string;
+    method: string;
+    interface: string;
+    type: string;
+    enum: string;
+    variable: string;
+    constant: string;
+    namespace: string;
+    property: string;
+}
+/** Sigma-specific edge colors by relationship type */
+interface SigmaEdgeColors {
+    import: string;
+    call: string;
+    extends: string;
+    implements: string;
+    contains: string;
+}
+/** Sigma highlight configuration */
+interface SigmaHighlightConfig {
+    /** Highlight color (cyan) */
+    color: string;
+    /** Opacity for dimmed non-highlighted nodes (0-1) */
+    dimmedOpacity: number;
+    /** Size multiplier for selected node */
+    selectedScale: number;
+    /** Size multiplier for neighbor nodes */
+    neighborScale: number;
+}
+/** Sigma label configuration */
+interface SigmaLabelConfig {
+    /** Font family */
+    font: string;
+    /** Base font size */
+    size: number;
+    /** Minimum node size to show label */
+    threshold: number;
+    /** Label text color */
+    color: string;
+}
+/** Complete Sigma theme configuration */
+interface SigmaTheme {
+    nodeColors: SigmaNodeColors;
+    edgeColors: SigmaEdgeColors;
+    highlight: SigmaHighlightConfig;
+    label: SigmaLabelConfig;
+    background: string;
+}
+/** Complete theme definition */
+interface Theme {
+    /** Theme identifier */
+    id: 'light' | 'dark' | string;
+    /** Theme display name */
+    name: string;
+    /** Whether this is a dark theme */
+    isDark: boolean;
+    /** UI colors */
+    ui: UIColors;
+    /** Node colors */
+    nodes: NodeColors;
+    /** Edge colors */
+    edges: EdgeColors;
+    /** Overlay colors */
+    overlays: OverlayColors;
+    /** Scope depth color configuration */
+    scopeDepth: ScopeDepthColors;
+    /** Sigma renderer theme (optional for backward compatibility) */
+    sigma?: SigmaTheme;
+}
+/** Theme context value */
+interface ThemeContextValue {
+    /** Current theme */
+    theme: Theme;
+    /** Set theme by ID */
+    setTheme: (themeId: string) => void;
+    /** Toggle between light and dark */
+    toggleTheme: () => void;
+    /** Get color for a specific scope depth */
+    getScopeColor: (depth: number) => string;
+}
+/** Theme provider props */
+interface ThemeProviderProps {
+    /** Initial theme ID */
+    initialTheme?: 'light' | 'dark';
+    /** Custom themes to register */
+    customThemes?: Theme[];
+    /** Children to render */
+    children?: React.ReactNode;
+}
+
+/**
+ * Light theme for CodeViz
+ *
+ * @packageDocumentation
+ */
+
+/** Light theme definition */
+declare const lightTheme: Theme;
+
+/**
+ * Dark theme for CodeViz
+ *
+ * @packageDocumentation
+ */
+
+/** Dark theme definition */
+declare const darkTheme: Theme;
+
+/**
+ * Theme utility functions for CodeViz
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Parse a hex color string to RGB values.
+ */
+declare function hexToRgb(hex: string): RGBColor;
+/**
+ * Convert RGB values to a hex color string.
+ */
+declare function rgbToHex(rgb: RGBColor): string;
+/**
+ * Convert HSL values to RGB.
+ * @param h Hue (0-360)
+ * @param s Saturation (0-100)
+ * @param l Lightness (0-100)
+ */
+declare function hslToRgb(h: number, s: number, l: number): RGBColor;
+/**
+ * Convert HSL values to a hex color string.
+ */
+declare function hslToHex(h: number, s: number, l: number): string;
+/**
+ * Convert RGB to HSL.
+ */
+declare function rgbToHsl(rgb: RGBColor): {
+    h: number;
+    s: number;
+    l: number;
+};
+/**
+ * Lighten a color by a percentage.
+ */
+declare function lighten(hex: string, amount: number): string;
+/**
+ * Darken a color by a percentage.
+ */
+declare function darken(hex: string, amount: number): string;
+/**
+ * Adjust the saturation of a color.
+ */
+declare function saturate(hex: string, amount: number): string;
+/**
+ * Mix two colors together.
+ */
+declare function mix(color1: string, color2: string, weight?: number): string;
+/**
+ * Get a color with adjusted opacity.
+ */
+declare function withOpacity(hex: string, opacity: number): string;
+/**
+ * Convert RGBA color to CSS string.
+ */
+declare function rgbaToCss(color: RGBAColor): string;
+/**
+ * Generate a color for a specific scope depth.
+ * Colors stay within the same color family but vary in lightness/saturation.
+ */
+declare function getScopeDepthColor(depth: number, config: ScopeDepthColors, isDark: boolean): string;
+/**
+ * Generate all scope depth colors for a theme.
+ */
+declare function generateScopeDepthColors(config: ScopeDepthColors, isDark: boolean): string[];
+/**
+ * Calculate relative luminance of a color.
+ */
+declare function getLuminance(hex: string): number;
+/**
+ * Calculate contrast ratio between two colors.
+ */
+declare function getContrastRatio(color1: string, color2: string): number;
+/**
+ * Check if text color should be light or dark based on background.
+ */
+declare function shouldUseDarkText(backgroundColor: string): boolean;
+/**
+ * Get appropriate text color for a background.
+ */
+declare function getTextColorForBackground(backgroundColor: string, lightText?: string, darkText?: string): string;
+/**
+ * Create a color getter function for a theme.
+ */
+declare function createScopeColorGetter(theme: Theme): (depth: number) => string;
+/**
+ * Merge a partial theme with a base theme.
+ */
+declare function mergeTheme(base: Theme, partial: Partial<Theme>): Theme;
+
+/**
+ * Theme exports for CodeViz
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Get a theme by ID.
+ */
+declare function getTheme(id: string): Theme | undefined;
+/**
+ * Register a custom theme.
+ */
+declare function registerTheme(theme: Theme): void;
+/**
+ * Get all registered theme IDs.
+ */
+declare function getThemeIds(): string[];
+/**
+ * Get the default theme based on system preference.
+ */
+declare function getDefaultTheme(): Theme;
+
+/**
+ * Graphology Integration
+ *
+ * Converts CodeGraph to graphology graph for layout algorithms.
+ * Provides bidirectional mapping between entity IDs and graph nodes.
+ */
+
+/**
+ * Node attributes stored in graphology graph
+ */
+interface GraphNodeAttributes {
+    /** Original entity ID */
+    entityId: string;
+    /** Node type */
+    type: 'file' | 'directory';
+    /** Directory ID (for files) or parent ID (for directories) */
+    parentId: string | null;
+    /** Lines of code */
+    loc: number;
+    /** Nesting depth */
+    depth: number;
+}
+/**
+ * Edge attributes stored in graphology graph
+ */
+interface GraphEdgeAttributes {
+    /** Original edge ID */
+    edgeId: string;
+    /** Edge weight based on import frequency */
+    weight: number;
+    /** Edge type */
+    type: 'import';
+    /** Whether the import was resolved */
+    resolved: boolean;
+}
+/**
+ * Directory edge attributes for aggregated edges
+ */
+interface DirectoryEdgeAttributes {
+    /** Aggregated edge weight */
+    weight: number;
+    /** Count of individual edges aggregated */
+    edgeCount: number;
+    /** Original edge IDs */
+    sourceEdgeIds: string[];
+}
+/**
+ * Bidirectional mapping between entity IDs and graph node keys
+ */
+interface EntityIdMapping {
+    /** Map from entity ID to graph node key */
+    entityToNode: Map<string, string>;
+    /** Map from graph node key to entity ID */
+    nodeToEntity: Map<string, string>;
+}
+/**
+ * Result of converting CodeGraph to graphology
+ */
+interface GraphologyConversionResult {
+    /** The graphology graph instance */
+    graph: Graph__default<GraphNodeAttributes, GraphEdgeAttributes>;
+    /** Bidirectional ID mapping */
+    mapping: EntityIdMapping;
+    /** File ID to directory ID lookup */
+    fileToDirectory: Map<string, string>;
+}
+/**
+ * Result of building directory-level graph
+ */
+interface DirectoryGraphResult {
+    /** The directory-level graphology graph */
+    graph: Graph__default<GraphNodeAttributes, DirectoryEdgeAttributes>;
+    /** Bidirectional ID mapping for directories */
+    mapping: EntityIdMapping;
+}
+/**
+ * Convert CodeGraph to graphology graph (file-level)
+ *
+ * Creates a graph where:
+ * - Nodes are files
+ * - Edges are import relationships
+ * - Edge weights reflect import frequency/importance
+ */
+declare function codeGraphToGraphology(codeGraph: CodeGraph): GraphologyConversionResult;
+/**
+ * Build directory-level aggregate graph
+ *
+ * Creates a graph where:
+ * - Nodes are directories
+ * - Edges are aggregated imports between directories
+ * - Edge weights reflect total import weight between directories
+ */
+declare function buildDirectoryGraph(codeGraph: CodeGraph, fileGraph: GraphologyConversionResult): DirectoryGraphResult;
+/**
+ * Get entity ID from graph node key
+ */
+declare function getEntityId(mapping: EntityIdMapping, nodeKey: string): string | undefined;
+/**
+ * Get graph node key from entity ID
+ */
+declare function getNodeKey(mapping: EntityIdMapping, entityId: string): string | undefined;
+/**
+ * Get all file IDs in a directory (direct children only)
+ */
+declare function getFilesInDirectory(fileGraph: GraphologyConversionResult, directoryId: string): string[];
+/**
+ * Get total edge weight between two directories
+ */
+declare function getDirectoryConnectionWeight(directoryGraph: DirectoryGraphResult, sourceDir: string, targetDir: string): number;
+
+/**
+ * Community Detection
+ *
+ * Runs Louvain algorithm on file dependency graph to cluster related files.
+ * Cluster IDs are used for coloring and grouping in visualization.
+ */
+
+/**
+ * Result of community detection
+ */
+interface ClusteringResult {
+    /** Map from node ID to cluster ID */
+    clusters: Map<string, number>;
+    /** Number of communities detected */
+    communityCount: number;
+    /** Modularity score (quality of clustering) */
+    modularity: number;
+}
+/**
+ * Options for community detection
+ */
+interface ClusteringOptions {
+    /** Resolution parameter (higher = more communities) */
+    resolution?: number;
+    /** Use random walk for reproducibility */
+    randomWalk?: boolean;
+    /** Whether to use edge weights (defaults to true) */
+    useEdgeWeight?: boolean;
+}
+/**
+ * Detect communities in the file dependency graph using Louvain algorithm
+ *
+ * @param graph - The file-level graphology graph
+ * @param options - Clustering options
+ * @returns ClusteringResult with cluster assignments
+ */
+declare function detectCommunities(graph: Graph__default<GraphNodeAttributes, GraphEdgeAttributes>, options?: ClusteringOptions): ClusteringResult;
+/**
+ * Get all nodes in a specific cluster
+ *
+ * @param result - The clustering result
+ * @param clusterId - The cluster ID to query
+ * @returns Array of node IDs in the cluster
+ */
+declare function getNodesInCluster(result: ClusteringResult, clusterId: number): string[];
+/**
+ * Get cluster statistics
+ *
+ * @param result - The clustering result
+ * @returns Statistics about the clustering
+ */
+declare function getClusterStats(result: ClusteringResult): {
+    clusterSizes: Map<number, number>;
+    avgClusterSize: number;
+    maxClusterSize: number;
+    minClusterSize: number;
+};
+/**
+ * Assign colors to clusters
+ * Uses a predefined palette with good visual separation
+ *
+ * @param communityCount - Number of communities
+ * @returns Map from cluster ID to color hex code
+ */
+declare function assignClusterColors(communityCount: number): Map<number, string>;
+/**
+ * Get the cluster ID for a specific node
+ *
+ * @param result - The clustering result
+ * @param nodeId - The node ID to query
+ * @returns The cluster ID, or undefined if node not found
+ */
+declare function getNodeCluster(result: ClusteringResult, nodeId: string): number | undefined;
+
+/**
+ * Directory Force Simulation
+ *
+ * Computes directory positions using ForceAtlas2 algorithm.
+ * Directories with more cross-imports are positioned closer together.
+ * Output positions are used as hints for hierarchical layout.
+ */
+
+/**
+ * Directory position result
+ */
+interface DirectoryPosition {
+    /** Directory entity ID */
+    directoryId: string;
+    /** Computed position */
+    position: Position;
+    /** Nesting depth */
+    depth: number;
+}
+/**
+ * Result of directory force simulation
+ */
+interface DirectoryForceResult {
+    /** Map from directory ID to position */
+    positions: Map<string, Position>;
+    /** Ordered list of positions with metadata */
+    directoryPositions: DirectoryPosition[];
+}
+/**
+ * Options for directory force simulation
+ */
+interface DirectoryForceOptions {
+    /** Number of iterations */
+    iterations?: number;
+    /** Gravity strength */
+    gravity?: number;
+    /** Scaling ratio */
+    scalingRatio?: number;
+    /** Edge weight influence */
+    edgeWeightInfluence?: number;
+    /** Random seed for initial positions */
+    seed?: number;
+}
+/**
+ * Compute directory positions using ForceAtlas2
+ *
+ * @param directoryGraph - Directory-level graph from buildDirectoryGraph
+ * @param options - Force simulation options
+ * @returns Directory positions
+ */
+declare function computeDirectoryForces(directoryGraph: DirectoryGraphResult, options?: DirectoryForceOptions): DirectoryForceResult;
+/**
+ * Normalize positions to fit within a bounding box
+ *
+ * @param result - Directory force result
+ * @param width - Target width
+ * @param height - Target height
+ * @param padding - Padding around edges
+ * @returns New result with normalized positions
+ */
+declare function normalizePositions(result: DirectoryForceResult, width: number, height: number, padding?: number): DirectoryForceResult;
+/**
+ * Get position for a specific directory
+ *
+ * @param result - Directory force result
+ * @param directoryId - Directory ID
+ * @returns Position or undefined if not found
+ */
+declare function getDirectoryPosition(result: DirectoryForceResult, directoryId: string): Position | undefined;
+/**
+ * Get all child directory positions
+ *
+ * @param result - Directory force result
+ * @param depth - Depth level to filter
+ * @returns Positions at the specified depth
+ */
+declare function getPositionsAtDepth(result: DirectoryForceResult, depth: number): DirectoryPosition[];
+
+/**
+ * Hierarchical Layout (ELK)
+ *
+ * Converts directory tree to ELK graph and computes MapScope bounds.
+ * Uses directory force positions as layout hints.
+ */
+
+/**
+ * Result of hierarchical layout computation
+ */
+interface HierarchyResult {
+    /** All scopes with computed bounds */
+    scopes: MapScope[];
+    /** Map from directory ID to scope */
+    scopeMap: Map<string, MapScope>;
+    /** Overall bounds */
+    bounds: BoundingBox$1;
+}
+/**
+ * Options for hierarchical layout
+ */
+interface HierarchyOptions {
+    /** Padding inside scopes */
+    scopePadding?: Padding;
+    /** Spacing between sibling scopes */
+    scopeSpacing?: number;
+    /** Minimum scope width */
+    minScopeWidth?: number;
+    /** Minimum scope height */
+    minScopeHeight?: number;
+    /** Use directory force positions as hints */
+    useForceHints?: boolean;
+}
+/**
+ * Compute hierarchical layout for directory tree
+ *
+ * @param codeGraph - The code graph
+ * @param forceResult - Optional directory force positions
+ * @param options - Layout options
+ * @returns Hierarchy result with scopes
+ */
+declare function computeHierarchy(codeGraph: CodeGraph, forceResult?: DirectoryForceResult, options?: HierarchyOptions): Promise<HierarchyResult>;
+/**
+ * Get scope by directory ID
+ */
+declare function getScopeByDirectoryId(result: HierarchyResult, directoryId: string): MapScope | undefined;
+/**
+ * Get all child scopes of a parent
+ */
+declare function getChildScopes(result: HierarchyResult, parentScopeId: string): MapScope[];
+/**
+ * Get root scopes (no parent)
+ */
+declare function getRootScopes(result: HierarchyResult): MapScope[];
+
+/**
+ * Force-Directed Positioning
+ *
+ * Runs ForceAtlas2 independently per scope to position nodes within bounds.
+ * Nodes are constrained to stay within their parent scope.
+ */
+
+/**
+ * Options for force-directed positioning
+ */
+interface ForcePositioningOptions {
+    /** Number of iterations */
+    iterations?: number;
+    /** Gravity strength */
+    gravity?: number;
+    /** Scaling ratio */
+    scalingRatio?: number;
+    /** Edge weight influence */
+    edgeWeightInfluence?: number;
+    /** Random seed */
+    seed?: number;
+}
+/**
+ * Calculate node size based on LOC using quantile buckets
+ */
+declare function calculateNodeSize(loc: number, allLocs: number[], minSize?: number, maxSize?: number): number;
+/**
+ * Position nodes within a single scope using ForceAtlas2
+ */
+declare function positionNodesInScope(scope: MapScope, files: FileNode$1[], edges: ImportEdge$1[], allLocs: number[], options?: ForcePositioningOptions): MapNode[];
+/**
+ * Position all nodes across all scopes
+ */
+declare function positionAllNodes(scopes: MapScope[], files: FileNode$1[], edges: ImportEdge$1[], options?: ForcePositioningOptions): MapNode[];
+
+/**
+ * Overlap Removal
+ *
+ * Uses graphology-layout-noverlap to ensure minimum spacing between nodes
+ * while respecting scope boundaries.
+ */
+
+/**
+ * Options for overlap removal
+ */
+interface NoverlapOptions {
+    /** Maximum iterations */
+    maxIterations?: number;
+    /** Margin between nodes */
+    margin?: number;
+    /** Expansion ratio per iteration */
+    ratio?: number;
+    /** Speed of adjustment */
+    speed?: number;
+}
+/**
+ * Remove overlaps for nodes within a single scope
+ */
+declare function removeOverlapsInScope(nodes: MapNode[], scope: MapScope, options?: NoverlapOptions): MapNode[];
+/**
+ * Remove overlaps for all nodes, grouped by scope
+ */
+declare function removeAllOverlaps(nodes: MapNode[], scopes: MapScope[], options?: NoverlapOptions): MapNode[];
+
+/**
+ * Edge Routing
+ *
+ * Computes visual edges for the map with aggregation at low zoom levels
+ * and direct edges at high zoom levels.
+ */
+
+/**
+ * Options for edge routing
+ */
+interface EdgeRoutingOptions {
+    /** Threshold for aggregation (edges between scopes) */
+    aggregationThreshold?: number;
+}
+/**
+ * Compute all edges for the map
+ */
+declare function computeEdges(nodes: MapNode[], scopes: MapScope[], imports: ImportEdge$1[], calls?: CallEdge$1[], _options?: EdgeRoutingOptions): MapEdge[];
+/**
+ * Get edges visible at a specific zoom level
+ */
+declare function getEdgesAtZoomLevel(edges: MapEdge[], zoomLevel: ZoomLevel): MapEdge[];
+/**
+ * Get edge count label for aggregated edges
+ */
+declare function getEdgeLabel(edge: MapEdge): string;
+
+/**
+ * Zoom Level Pre-computation
+ *
+ * Pre-computes visibility and styling for each zoom level.
+ */
+
+/**
+ * Pre-computed zoom level data
+ */
+interface ZoomLevelData {
+    /** Zoom level */
+    level: ZoomLevel;
+    /** Visible node IDs */
+    visibleNodeIds: Set<string>;
+    /** Visible scope IDs */
+    visibleScopeIds: Set<string>;
+    /** Visible edge IDs */
+    visibleEdgeIds: Set<string>;
+    /** Node sizes at this level */
+    nodeSizes: Map<string, {
+        width: number;
+        height: number;
+    }>;
+    /** Node opacities at this level */
+    nodeOpacities: Map<string, number>;
+    /** Label visibility */
+    labelVisibility: Map<string, boolean>;
+}
+/**
+ * Options for zoom pre-computation
+ */
+interface ZoomPrecomputeOptions {
+    /** Large file LOC threshold */
+    largeFileThreshold?: number;
+    /** Zoom level configurations */
+    zoomLevels?: ZoomLevelConfig[];
+}
+/**
+ * Pre-compute all zoom levels
+ */
+declare function computeZoomLevels(nodes: MapNode[], scopes: MapScope[], edges: MapEdge[], zoomConfigs: ZoomLevelConfig[], options?: ZoomPrecomputeOptions): Map<ZoomLevel, ZoomLevelData>;
+/**
+ * Get visible nodes at a zoom level
+ */
+declare function getVisibleNodes(zoomData: Map<ZoomLevel, ZoomLevelData>, level: ZoomLevel, nodes: MapNode[]): MapNode[];
+/**
+ * Get visible scopes at a zoom level
+ */
+declare function getVisibleScopes(zoomData: Map<ZoomLevel, ZoomLevelData>, level: ZoomLevel, scopes: MapScope[]): MapScope[];
+/**
+ * Get visible edges at a zoom level
+ */
+declare function getVisibleEdges(zoomData: Map<ZoomLevel, ZoomLevelData>, level: ZoomLevel, edges: MapEdge[]): MapEdge[];
+/**
+ * Get node size at a zoom level
+ */
+declare function getNodeSizeAtLevel(zoomData: Map<ZoomLevel, ZoomLevelData>, level: ZoomLevel, nodeId: string): {
+    width: number;
+    height: number;
+} | undefined;
+/**
+ * Get node opacity at a zoom level
+ */
+declare function getNodeOpacityAtLevel(zoomData: Map<ZoomLevel, ZoomLevelData>, level: ZoomLevel, nodeId: string): number;
+
+/**
+ * Layout Orchestrator
+ *
+ * Pipelines all layout stages to produce a complete CodeMap.
+ * Handles errors gracefully and always produces renderable output.
+ */
+
+/**
+ * Layout progress callback
+ */
+type LayoutProgressCallback = (stage: string, percent: number) => void;
+/**
+ * Layout options with progress callback
+ */
+interface ComputeLayoutOptions {
+    /** Layout configuration */
+    config?: Partial<LayoutConfig>;
+    /** Progress callback */
+    onProgress?: LayoutProgressCallback;
+    /** Cancellation check */
+    isCancelled?: () => boolean;
+}
+/**
+ * Compute complete layout from CodeGraph to CodeMap
+ *
+ * Pipeline:
+ * 1. Graphology conversion (0-10%)
+ * 2. Community detection (10-20%)
+ * 3. Directory force simulation (20-35%)
+ * 4. Hierarchical layout (35-50%)
+ * 5. Force-directed positioning (50-75%)
+ * 6. Overlap removal (75-85%)
+ * 7. Edge routing (85-95%)
+ * 8. Zoom pre-computation (95-100%)
+ */
+declare function computeLayout(codeGraph: CodeGraph, options?: ComputeLayoutOptions): Promise<CodeMap$1>;
+
+/**
+ * Overlay System Types
+ *
+ * Type definitions for the overlay system that renders visual indicators,
+ * annotations, documents, and agent widgets on top of the CodeMap.
+ */
+/**
+ * Anchor points for positioning overlays relative to nodes
+ */
+type AnchorPoint = 'center' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/**
+ * Absolute position in viewport coordinates
+ */
+interface AbsolutePosition {
+    type: 'absolute';
+    x: number;
+    y: number;
+}
+/**
+ * Position relative to a node
+ */
+interface NodePosition {
+    type: 'node';
+    nodeId: string;
+    anchor?: AnchorPoint;
+    offset?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Position along an edge (t = 0 to 1)
+ */
+interface EdgePosition {
+    type: 'edge';
+    edgeId: string;
+    t?: number;
+    offset?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Union of all position types
+ */
+type OverlayPosition = AbsolutePosition | NodePosition | EdgePosition;
+/**
+ * All overlay types
+ */
+type OverlayType = 'cursor' | 'highlight' | 'badge' | 'annotation' | 'document' | 'agent';
+/**
+ * Base interface for all overlays
+ */
+interface BaseOverlay {
+    id: string;
+    type: OverlayType;
+    position: OverlayPosition;
+    zIndex?: number;
+    visible?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Cursor overlay for showing user/agent presence
+ */
+interface CursorOverlay extends BaseOverlay {
+    type: 'cursor';
+    /** Display label (user/agent name) */
+    label?: string;
+    /** Cursor color */
+    color: string;
+    /** Avatar URL */
+    avatar?: string;
+    /** Show movement trail */
+    trail?: boolean;
+}
+/**
+ * Bounding box for region highlights
+ */
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Style configuration for highlights
+ */
+interface HighlightStyle {
+    /** Highlight color */
+    color: string;
+    /** Opacity (0-1) */
+    opacity?: number;
+    /** Stroke width for outlines */
+    strokeWidth?: number;
+    /** Animated pulse effect */
+    pulse?: boolean;
+    /** Glow effect */
+    glow?: boolean;
+    /** Fill the shape (vs just outline) */
+    fill?: boolean;
+}
+/**
+ * Highlight overlay for visual emphasis
+ */
+interface HighlightOverlay extends BaseOverlay {
+    type: 'highlight';
+    /** What to highlight */
+    targetType: 'node' | 'edge' | 'region';
+    /** Target node or edge ID */
+    targetId?: string;
+    /** Bounding box for region highlights */
+    region?: BoundingBox;
+    /** Visual style */
+    style: HighlightStyle;
+}
+/**
+ * Badge variant types
+ */
+type BadgeVariant = 'count' | 'icon' | 'dot' | 'text';
+/**
+ * Badge size options
+ */
+type BadgeSize = 'small' | 'medium' | 'large';
+/**
+ * Badge overlay for small indicators on nodes
+ */
+interface BadgeOverlay extends BaseOverlay {
+    type: 'badge';
+    /** Badge display variant */
+    variant: BadgeVariant;
+    /** Value for count/text variants */
+    value?: string | number;
+    /** Icon name or URL for icon variant */
+    icon?: string;
+    /** Badge color */
+    color?: string;
+    /** Badge size */
+    size?: BadgeSize;
+}
+/**
+ * Content type for annotations
+ */
+type AnnotationContentType = 'text' | 'markdown';
+/**
+ * Annotation overlay for text content attached to positions
+ */
+interface AnnotationOverlay extends BaseOverlay {
+    type: 'annotation';
+    /** Text or markdown content */
+    content: string;
+    /** Content format */
+    contentType?: AnnotationContentType;
+    /** Maximum width in pixels */
+    maxWidth?: number;
+    /** Can be collapsed */
+    collapsible?: boolean;
+    /** Current collapsed state */
+    collapsed?: boolean;
+}
+/**
+ * Document types for document overlays
+ */
+type DocumentType = 'design-doc' | 'work-item' | 'spec' | 'custom';
+/**
+ * Document status
+ */
+type DocumentStatus = 'draft' | 'in-progress' | 'review' | 'done';
+/**
+ * Document overlay for showing related documents
+ */
+interface DocumentOverlay extends BaseOverlay {
+    type: 'document';
+    /** Type of document */
+    documentType: DocumentType;
+    /** Document title */
+    title: string;
+    /** Inline content (markdown) */
+    content?: string;
+    /** External link */
+    url?: string;
+    /** Document status */
+    status?: DocumentStatus;
+    /** Keep visible during pan/zoom */
+    pinned?: boolean;
+    /** Panel width */
+    width?: number;
+    /** Panel height */
+    height?: number;
+}
+/**
+ * Agent status types
+ */
+type AgentStatus = 'idle' | 'thinking' | 'working' | 'waiting' | 'error';
+/**
+ * Agent widget overlay for visualizing coding agents
+ */
+interface AgentWidgetOverlay extends BaseOverlay {
+    type: 'agent';
+    /** Unique agent identifier */
+    agentId: string;
+    /** Agent display name */
+    name: string;
+    /** Avatar URL */
+    avatar?: string;
+    /** Current status */
+    status: AgentStatus;
+    /** Current activity description */
+    activity?: string;
+    /** Progress percentage (0-100) */
+    progress?: number;
+    /** Nodes the agent is working on */
+    targetNodes?: string[];
+    /** Can be expanded for details */
+    expandable?: boolean;
+    /** Current expanded state */
+    expanded?: boolean;
+}
+/**
+ * Union of all overlay types
+ */
+type Overlay = CursorOverlay | HighlightOverlay | BadgeOverlay | AnnotationOverlay | DocumentOverlay | AgentWidgetOverlay;
+/**
+ * Input types for creating overlays (without ID)
+ * Uses distributive conditional to properly handle union types
+ */
+type CursorOverlayInput = Omit<CursorOverlay, 'id'>;
+type HighlightOverlayInput = Omit<HighlightOverlay, 'id'>;
+type BadgeOverlayInput = Omit<BadgeOverlay, 'id'>;
+type AnnotationOverlayInput = Omit<AnnotationOverlay, 'id'>;
+type DocumentOverlayInput = Omit<DocumentOverlay, 'id'>;
+type AgentWidgetOverlayInput = Omit<AgentWidgetOverlay, 'id'>;
+/**
+ * Union of all overlay input types (for creating new overlays)
+ */
+type OverlayInput = CursorOverlayInput | HighlightOverlayInput | BadgeOverlayInput | AnnotationOverlayInput | DocumentOverlayInput | AgentWidgetOverlayInput;
+/**
+ * Filter for querying overlays
+ */
+interface OverlayFilter {
+    /** Filter by overlay type(s) */
+    type?: OverlayType | OverlayType[];
+    /** Filter by associated node ID */
+    nodeId?: string;
+    /** Filter by visibility */
+    visible?: boolean;
+    /** Filter by metadata properties */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Batch update operation
+ */
+interface OverlayBatchUpdate {
+    id: string;
+    changes: Partial<Overlay>;
+}
+/**
+ * Event handler for overlay clicks
+ */
+type OverlayClickHandler = (id: string, overlay: Overlay) => void;
+/**
+ * Event handler for overlay hover
+ */
+type OverlayHoverHandler = (id: string, overlay: Overlay, isHovering: boolean) => void;
+/**
+ * OverlayPort interface for managing overlays imperatively
+ */
+interface IOverlayPort {
+    /** Add a new overlay, returns generated ID */
+    bind(overlay: OverlayInput): string;
+    /** Update an existing overlay */
+    update(id: string, changes: Partial<Overlay>): void;
+    /** Remove an overlay */
+    remove(id: string): void;
+    /** Remove overlays matching filter (all if no filter) */
+    clear(filter?: OverlayFilter): void;
+    /** Get overlays matching filter (all if no filter) */
+    getOverlays(filter?: OverlayFilter): Overlay[];
+    /** Get a specific overlay by ID */
+    getOverlayById(id: string): Overlay | undefined;
+    /** Apply multiple updates at once */
+    batchUpdate(updates: OverlayBatchUpdate[]): void;
+    /** Handler called when an overlay is clicked */
+    onOverlayClick?: OverlayClickHandler;
+    /** Handler called when an overlay is hovered */
+    onOverlayHover?: OverlayHoverHandler;
+    /** Trigger click event for an overlay */
+    triggerClick?(id: string): void;
+    /** Trigger hover event for an overlay */
+    triggerHover?(id: string, isHovering: boolean): void;
+    /** Subscribe to overlay changes */
+    subscribe(listener: (overlays: Overlay[]) => void): () => void;
+}
+
+/**
+ * OverlayPort Implementation
+ *
+ * Manages overlay state and provides an imperative API for external systems
+ * to add, update, and remove overlays on the CodeMap.
+ */
+
+/**
+ * OverlayPort class for managing overlay state
+ */
+declare class OverlayPort implements IOverlayPort {
+    private overlays;
+    private listeners;
+    /** Handler called when an overlay is clicked */
+    onOverlayClick?: OverlayClickHandler;
+    /** Handler called when an overlay is hovered */
+    onOverlayHover?: OverlayHoverHandler;
+    /**
+     * Create a new OverlayPort
+     */
+    constructor(options?: {
+        onOverlayClick?: OverlayClickHandler;
+        onOverlayHover?: OverlayHoverHandler;
+    });
+    /**
+     * Notify all listeners of overlay changes
+     */
+    private notifyListeners;
+    /**
+     * Add a new overlay
+     * @param overlay - Overlay data without ID
+     * @returns Generated overlay ID
+     */
+    bind(overlay: OverlayInput): string;
+    /**
+     * Update an existing overlay
+     * @param id - Overlay ID
+     * @param changes - Partial overlay data to merge
+     */
+    update(id: string, changes: Partial<Overlay>): void;
+    /**
+     * Remove an overlay
+     * @param id - Overlay ID to remove
+     */
+    remove(id: string): void;
+    /**
+     * Remove overlays matching a filter
+     * @param filter - Filter to match overlays (all if undefined)
+     */
+    clear(filter?: OverlayFilter): void;
+    /**
+     * Get overlays matching a filter
+     * @param filter - Filter to match overlays (all if undefined)
+     * @returns Array of matching overlays
+     */
+    getOverlays(filter?: OverlayFilter): Overlay[];
+    /**
+     * Get a specific overlay by ID
+     * @param id - Overlay ID
+     * @returns Overlay or undefined
+     */
+    getOverlayById(id: string): Overlay | undefined;
+    /**
+     * Apply multiple updates at once
+     * @param updates - Array of update operations
+     */
+    batchUpdate(updates: OverlayBatchUpdate[]): void;
+    /**
+     * Subscribe to overlay changes
+     * @param listener - Callback function
+     * @returns Unsubscribe function
+     */
+    subscribe(listener: (overlays: Overlay[]) => void): () => void;
+    /**
+     * Get the current overlay count
+     */
+    get size(): number;
+    /**
+     * Check if an overlay exists
+     * @param id - Overlay ID
+     */
+    has(id: string): boolean;
+    /**
+     * Get overlays by type
+     * @param type - Overlay type
+     */
+    getByType(type: OverlayType): Overlay[];
+    /**
+     * Get overlays for a specific node
+     * @param nodeId - Node ID
+     */
+    getByNode(nodeId: string): Overlay[];
+    /**
+     * Trigger click event for an overlay
+     * @param id - Overlay ID
+     */
+    triggerClick(id: string): void;
+    /**
+     * Trigger hover event for an overlay
+     * @param id - Overlay ID
+     * @param isHovering - Whether hovering or leaving
+     */
+    triggerHover(id: string, isHovering: boolean): void;
+}
+/**
+ * Create a new OverlayPort instance
+ */
+declare function createOverlayPort(options?: {
+    onOverlayClick?: OverlayClickHandler;
+    onOverlayHover?: OverlayHoverHandler;
+}): OverlayPort;
+
+/**
+ * Overlay Positioning Utilities
+ *
+ * Functions for calculating overlay positions relative to nodes, edges, and viewport.
+ */
+
+/**
+ * Calculated position in screen/viewport coordinates
+ */
+interface CalculatedPosition {
+    x: number;
+    y: number;
+}
+/**
+ * Node bounds information for position calculation
+ */
+interface NodeBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Edge path information for position calculation
+ */
+interface EdgePath {
+    sourceX: number;
+    sourceY: number;
+    targetX: number;
+    targetY: number;
+}
+/**
+ * Viewport transform for coordinate conversion
+ */
+interface ViewportTransform {
+    x: number;
+    y: number;
+    zoom: number;
+}
+/**
+ * Get the offset for an anchor point relative to node bounds
+ */
+declare function getAnchorOffset(anchor: AnchorPoint, bounds: NodeBounds): CalculatedPosition;
+/**
+ * Transform a position from graph coordinates to screen coordinates
+ */
+declare function graphToScreen(position: CalculatedPosition, viewport: ViewportTransform): CalculatedPosition;
+/**
+ * Transform a position from screen coordinates to graph coordinates
+ */
+declare function screenToGraph(position: CalculatedPosition, viewport: ViewportTransform): CalculatedPosition;
+/**
+ * Calculate the final overlay position based on position type
+ */
+declare function calculateOverlayPosition(position: OverlayPosition, context: {
+    getNodeBounds?: (nodeId: string) => NodeBounds | undefined;
+    getEdgePath?: (edgeId: string) => EdgePath | undefined;
+    viewport?: ViewportTransform;
+}): CalculatedPosition | null;
+
+/**
+ * Props for OverlayLayer
+ */
+interface OverlayLayerProps {
+    /** Overlay port for managing overlays */
+    port?: IOverlayPort;
+    /** Declarative overlays (alternative to port) */
+    overlays?: Overlay[];
+    /** Get node bounds by ID (from React Flow) */
+    getNodeBounds?: (nodeId: string) => NodeBounds | undefined;
+    /** Get edge path by ID (from React Flow) */
+    getEdgePath?: (edgeId: string) => EdgePath | undefined;
+    /** Viewport transform for coordinate conversion */
+    viewport?: ViewportTransform;
+    /** Theme (light or dark) */
+    theme?: 'light' | 'dark';
+    /** Click handler */
+    onOverlayClick?: (id: string, overlay: Overlay) => void;
+    /** Hover handler */
+    onOverlayHover?: (id: string, overlay: Overlay, isHovering: boolean) => void;
+}
+/**
+ * Overlay Layer Component
+ *
+ * Renders overlays on top of the CodeMap visualization using a hybrid approach:
+ * - SVG layer for simple, high-performance overlays (cursors, badges, highlights)
+ * - Portal layer for rich, interactive overlays (annotations, documents, agents)
+ */
+declare function OverlayLayer({ port, overlays: declarativeOverlays, getNodeBounds, getEdgePath, viewport, theme, onOverlayClick, onOverlayHover, }: OverlayLayerProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Props for SVGOverlayLayer
+ */
+interface SVGOverlayLayerProps {
+    /** Overlays to render (filtered to SVG-compatible types) */
+    overlays: Overlay[];
+    /** Get node bounds by ID */
+    getNodeBounds?: (nodeId: string) => NodeBounds | undefined;
+    /** Get edge path by ID */
+    getEdgePath?: (edgeId: string) => {
+        sourceX: number;
+        sourceY: number;
+        targetX: number;
+        targetY: number;
+    } | undefined;
+    /** Click handler */
+    onOverlayClick?: (id: string) => void;
+    /** Hover handler */
+    onOverlayHover?: (id: string, isHovering: boolean) => void;
+}
+/**
+ * SVG Overlay Layer Component
+ */
+declare function SVGOverlayLayer({ overlays, getNodeBounds, getEdgePath, onOverlayClick, onOverlayHover, }: SVGOverlayLayerProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Props for PortalOverlayLayer
+ */
+interface PortalOverlayLayerProps {
+    /** Overlays to render (filtered to portal-compatible types) */
+    overlays: Overlay[];
+    /** Get node bounds by ID */
+    getNodeBounds?: (nodeId: string) => NodeBounds | undefined;
+    /** Get edge path by ID */
+    getEdgePath?: (edgeId: string) => {
+        sourceX: number;
+        sourceY: number;
+        targetX: number;
+        targetY: number;
+    } | undefined;
+    /** Theme (light or dark) */
+    theme?: 'light' | 'dark';
+    /** Click handler */
+    onOverlayClick?: (id: string) => void;
+    /** Hover handler */
+    onOverlayHover?: (id: string, isHovering: boolean) => void;
+}
+/**
+ * Portal Overlay Layer Component
+ */
+declare function PortalOverlayLayer({ overlays, getNodeBounds, getEdgePath, theme, onOverlayClick, onOverlayHover, }: PortalOverlayLayerProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Sigma-specific type definitions for CodeViz
+ */
+
+/**
+ * Node attributes used by Sigma for rendering
+ */
+interface SigmaNodeAttributes extends Attributes {
+    x: number;
+    y: number;
+    size: number;
+    color: string;
+    label: string;
+    nodeType: 'directory' | 'file' | 'symbol' | 'aggregate';
+    entityId: string;
+    scopeId?: string;
+    depth?: number;
+    visibleAtLevels?: number[];
+    symbolKind?: string;
+    metrics?: FileMetrics;
+    hidden?: boolean;
+    zIndex?: number;
+    mass?: number;
+}
+/**
+ * Edge attributes used by Sigma for rendering
+ */
+interface SigmaEdgeAttributes extends Attributes {
+    size: number;
+    color: string;
+    type: 'curved';
+    edgeType: 'import' | 'call' | 'extends' | 'implements' | 'contains';
+    visibleAtLevels?: number[];
+    hidden?: boolean;
+    zIndex?: number;
+}
+/**
+ * View modes for Sigma renderer
+ */
+type ViewMode = 'structure' | 'nexus';
+/**
+ * Renderer types for CodeMap component
+ */
+type RendererType = 'react-flow' | 'sigma';
+
+/**
+ * CodeMap component props
+ */
+interface CodeMapProps {
+    /** Pre-computed layout data */
+    codeMap: CodeMap$1;
+    /** Theme ID or custom theme */
+    theme?: 'light' | 'dark' | Theme;
+    /** Node click handler */
+    onNodeClick?: (nodeId: string, node: MapNode) => void;
+    /** Node hover handler */
+    onNodeHover?: (nodeId: string | null, node: MapNode | null) => void;
+    /** Scope expand/collapse handler */
+    onScopeToggle?: (scopeId: string, expanded: boolean) => void;
+    /** Viewport change handler */
+    onViewportChange?: (viewport: Viewport) => void;
+    /** Zoom level change handler */
+    onZoomLevelChange?: (level: ZoomLevel) => void;
+    /** Selection change handler */
+    onSelectionChange?: (selectedIds: string[]) => void;
+    /** Initially selected node IDs */
+    defaultSelectedIds?: string[];
+    /** Controlled selected node IDs */
+    selectedIds?: string[];
+    /** Initial viewport */
+    defaultViewport?: Viewport;
+    /** Configuration overrides */
+    config?: Partial<CodeMapConfig>;
+    /** Container className */
+    className?: string;
+    /** Container style */
+    style?: React.CSSProperties;
+    /** Overlay port for managing overlays */
+    overlayPort?: IOverlayPort;
+    /** Declarative overlays (alternative to port) */
+    overlays?: Overlay[];
+    /** Overlay click handler */
+    onOverlayClick?: (id: string, overlay: Overlay) => void;
+    /** Overlay hover handler */
+    onOverlayHover?: (id: string, overlay: Overlay, isHovering: boolean) => void;
+    /**
+     * Renderer to use for visualization
+     * - 'react-flow': DOM-based rendering (default, better for <1000 nodes)
+     * - 'sigma': WebGL-based rendering (better for 1000+ nodes)
+     */
+    renderer?: RendererType;
+    /**
+     * View mode for Sigma renderer
+     * - 'structure': File system hierarchy with directory scopes
+     * - 'nexus': Flat relationship graph (calls, imports, extends)
+     * Only used when renderer='sigma'
+     */
+    view?: ViewMode;
+    /**
+     * CodeGraph data (required for nexus view)
+     * Provides symbols and relationships for the nexus visualization
+     */
+    codeGraph?: CodeGraph;
+}
+/**
+ * CodeMap component
+ *
+ * Visualizes a codebase as an interactive 2D map with:
+ * - Semantic zoom levels (overview → files → symbols → code)
+ * - Expandable/collapsible directory scopes
+ * - Import and call edges
+ * - Light and dark theme support
+ * - Two renderers: React Flow (DOM) and Sigma (WebGL)
+ */
+declare function CodeMap({ codeMap, theme, onNodeClick, onNodeHover: _onNodeHover, onScopeToggle, onViewportChange: _onViewportChange, onZoomLevelChange, onSelectionChange, defaultSelectedIds: _defaultSelectedIds, selectedIds: _selectedIds, defaultViewport, config, className, style, overlayPort, overlays, onOverlayClick, onOverlayHover, renderer, view, codeGraph, }: CodeMapProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Flow component props
+ */
+interface FlowProps {
+    /** React Flow nodes */
+    nodes: Node[];
+    /** React Flow edges */
+    edges: Edge[];
+    /** Zoom level configurations */
+    zoomLevels: ZoomLevelConfig[];
+    /** Hysteresis percentage (0-1) */
+    hysteresis?: number;
+    /** Current zoom level */
+    zoomLevel: ZoomLevel;
+    /** Zoom level change callback */
+    onZoomLevelChange?: (level: ZoomLevel) => void;
+    /** Node click callback */
+    onNodeClick?: NodeMouseHandler;
+    /** Selection change callback */
+    onSelectionChange?: (params: OnSelectionChangeParams) => void;
+    /** Initial viewport */
+    defaultViewport?: Viewport;
+    /** Show minimap */
+    showMinimap?: boolean;
+    /** Show controls */
+    showControls?: boolean;
+    /** Show background grid */
+    showBackground?: boolean;
+}
+/**
+ * Flow component - React Flow wrapper with zoom level management
+ *
+ * Handles:
+ * - Custom node/edge types registration
+ * - Zoom level detection with hysteresis
+ * - Viewport change forwarding
+ * - Selection management
+ */
+declare function Flow(props: FlowProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Theme Provider component
+ *
+ * Provides theme context to child components with support for:
+ * - Light/dark theme switching
+ * - System preference detection
+ * - Custom theme registration
+ * - Scope depth color computation
+ */
+declare function ThemeProvider({ initialTheme, customThemes, children, }: ThemeProviderProps): ReactNode;
+/**
+ * Hook to access theme context
+ *
+ * @throws Error if used outside ThemeProvider
+ */
+declare function useTheme(): ThemeContextValue;
+/**
+ * Hook to access current theme (convenience)
+ */
+declare function useCurrentTheme(): Theme;
+/**
+ * Hook to check if current theme is dark
+ */
+declare function useIsDarkTheme(): boolean;
+
+/**
+ * FileNode component for React Flow
+ */
+declare function FileNodeComponent({ data, selected }: NodeProps): react_jsx_runtime.JSX.Element;
+declare const FileNode: react.MemoExoticComponent<typeof FileNodeComponent>;
+
+/**
+ * CodeMap to React Flow Converters
+ *
+ * Converts CodeMap data structures to React Flow nodes and edges.
+ */
+
+/**
+ * Data passed to custom node components
+ * Using Record<string, unknown> compatible types for React Flow
+ */
+type FileNodeData = {
+    type: 'file';
+    label: string;
+    shortLabel: string;
+    extension: string;
+    entityId: string;
+    loc: number;
+    scopeId: string;
+    [key: string]: unknown;
+};
+type SymbolNodeData = {
+    type: 'symbol';
+    label: string;
+    shortLabel: string;
+    symbolKind: string;
+    entityId: string;
+    exported: boolean;
+    signature?: string;
+    [key: string]: unknown;
+};
+type AggregateReactFlowNodeData = {
+    type: 'aggregate';
+    label: string;
+    count: number;
+    totalLoc: number;
+    entityIds: string[];
+    scopeId: string;
+    [key: string]: unknown;
+};
+type ScopeNodeData = {
+    type: 'scope';
+    label: string;
+    entityId: string;
+    depth: number;
+    fileCount: number;
+    totalLoc: number;
+    expanded: boolean;
+    [key: string]: unknown;
+};
+type ReactFlowNodeData = FileNodeData | SymbolNodeData | AggregateReactFlowNodeData | ScopeNodeData;
+/**
+ * Convert CodeMap nodes and scopes to React Flow nodes
+ *
+ * Handles:
+ * - Scope to group node conversion
+ * - Node positioning relative to parent scopes
+ * - Visibility filtering by zoom level
+ */
+declare function codeMapToReactFlowNodes(codeMap: CodeMap$1, zoomLevel: ZoomLevel, expandedScopes?: Set<string>): Node<ReactFlowNodeData>[];
+/**
+ * Edge data for custom edge components
+ * Using Record<string, unknown> compatible types for React Flow
+ */
+type ImportEdgeData = {
+    type: 'import';
+    weight: number;
+    [key: string]: unknown;
+};
+type CallEdgeData = {
+    type: 'call';
+    weight: number;
+    [key: string]: unknown;
+};
+type BundledEdgeData = {
+    type: 'bundled';
+    weight: number;
+    originalEdgeIds: string[];
+    [key: string]: unknown;
+};
+type ReactFlowEdgeData = ImportEdgeData | CallEdgeData | BundledEdgeData;
+/**
+ * Convert CodeMap edges to React Flow edges
+ *
+ * Handles:
+ * - Visibility filtering by zoom level
+ * - Edge type mapping
+ */
+declare function codeMapToReactFlowEdges(codeMap: CodeMap$1, zoomLevel: ZoomLevel): Edge<ReactFlowEdgeData>[];
+/**
+ * Get all scope IDs that should be expanded by default
+ */
+declare function getDefaultExpandedScopes(codeMap: CodeMap$1): Set<string>;
+/**
+ * Calculate zoom level from React Flow zoom value
+ */
+declare function getZoomLevelFromZoom(zoom: number, currentLevel: ZoomLevel, hysteresis: number, zoomLevels: CodeMap$1['zoomLevels']): ZoomLevel;
+
+interface ScopeNodeProps extends NodeProps {
+    data: ScopeNodeData;
+    onToggle?: (scopeId: string, expanded: boolean) => void;
+}
+/**
+ * ScopeNode component for React Flow
+ *
+ * Renders as a container with header bar showing directory name,
+ * file count, and expand/collapse toggle.
+ */
+declare function ScopeNodeComponent({ data, selected }: ScopeNodeProps): react_jsx_runtime.JSX.Element;
+declare const ScopeNode: react.MemoExoticComponent<typeof ScopeNodeComponent>;
+
+/**
+ * SymbolNode component for React Flow
+ *
+ * Smaller than FileNode, shows symbol icon, name, and export badge.
+ */
+declare function SymbolNodeComponent({ data, selected }: NodeProps): react_jsx_runtime.JSX.Element;
+declare const SymbolNode: react.MemoExoticComponent<typeof SymbolNodeComponent>;
+
+/**
+ * AggregateNode component for React Flow
+ *
+ * Shows collapsed content summary with count and LOC.
+ */
+declare function AggregateNodeComponent({ data, selected }: NodeProps): react_jsx_runtime.JSX.Element;
+declare const AggregateNode: react.MemoExoticComponent<typeof AggregateNodeComponent>;
+
+/**
+ * Node types object for React Flow configuration
+ */
+declare const nodeTypes: {
+    readonly file: react.MemoExoticComponent<({ data, selected }: _xyflow_react.NodeProps) => react_jsx_runtime.JSX.Element>;
+    readonly scope: react.MemoExoticComponent<({ data, selected }: ScopeNodeProps) => react_jsx_runtime.JSX.Element>;
+    readonly symbol: react.MemoExoticComponent<({ data, selected }: _xyflow_react.NodeProps) => react_jsx_runtime.JSX.Element>;
+    readonly aggregate: react.MemoExoticComponent<({ data, selected }: _xyflow_react.NodeProps) => react_jsx_runtime.JSX.Element>;
+};
+type NodeType = keyof typeof nodeTypes;
+
+/**
+ * ImportEdge component for React Flow
+ *
+ * Solid line with arrow marker showing import dependencies.
+ */
+declare function ImportEdgeComponent({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, style, markerEnd, data, }: EdgeProps): react_jsx_runtime.JSX.Element;
+declare const ImportEdge: react.MemoExoticComponent<typeof ImportEdgeComponent>;
+
+/**
+ * CallEdge component for React Flow
+ *
+ * Dashed line style for call graph edges.
+ */
+declare function CallEdgeComponent({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, style, markerEnd, data, }: EdgeProps): react_jsx_runtime.JSX.Element;
+declare const CallEdge: react.MemoExoticComponent<typeof CallEdgeComponent>;
+
+/**
+ * BundledEdge component for React Flow
+ *
+ * Thicker line with count label for aggregated edges.
+ */
+declare function BundledEdgeComponent({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, style, markerEnd, data, }: EdgeProps): react_jsx_runtime.JSX.Element;
+declare const BundledEdge: react.MemoExoticComponent<typeof BundledEdgeComponent>;
+
+/**
+ * Edge types object for React Flow configuration
+ */
+declare const edgeTypes: {
+    readonly import: react.MemoExoticComponent<({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, style, markerEnd, data, }: _xyflow_react.EdgeProps) => react_jsx_runtime.JSX.Element>;
+    readonly call: react.MemoExoticComponent<({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, style, markerEnd, data, }: _xyflow_react.EdgeProps) => react_jsx_runtime.JSX.Element>;
+    readonly bundled: react.MemoExoticComponent<({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, style, markerEnd, data, }: _xyflow_react.EdgeProps) => react_jsx_runtime.JSX.Element>;
+};
+type EdgeType = keyof typeof edgeTypes;
+
+/**
+ * Component Utilities
+ *
+ * Icon mappings and label utilities for node components.
+ */
+
+/**
+ * Map file extension to Lucide icon component
+ */
+declare function getFileIcon(extension: string): LucideIcon;
+/**
+ * Map symbol kind to Lucide icon component
+ */
+declare function getSymbolIcon(kind: SymbolKind): LucideIcon;
+/**
+ * Get a display-friendly label for a symbol kind
+ */
+declare function getSymbolKindLabel(kind: SymbolKind): string;
+/**
+ * Format a number with K/M suffixes for large values
+ */
+declare function formatNumber(value: number): string;
+/**
+ * Format lines of code for display
+ */
+declare function formatLoc(loc: number): string;
+
+/**
+ * useLayout Hook
+ *
+ * React hook for computing layout from CodeGraph to CodeMap.
+ * Features debouncing, cancellation, and progress reporting.
+ */
+
+/**
+ * Layout computation progress
+ */
+interface LayoutProgress {
+    stage: string;
+    percent: number;
+}
+/**
+ * Options for useLayout hook
+ */
+interface UseLayoutOptions {
+    /** Layout configuration overrides */
+    config?: Partial<LayoutConfig>;
+    /** Debounce delay in milliseconds (default: 100) */
+    debounceMs?: number;
+    /** Whether computation is enabled (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Result of useLayout hook
+ */
+interface UseLayoutResult {
+    /** Computed CodeMap, null if not yet computed or on error */
+    codeMap: CodeMap$1 | null;
+    /** Whether computation is currently in progress */
+    isComputing: boolean;
+    /** Error from last computation attempt, null if successful */
+    error: Error | null;
+    /** Current computation progress, null if not computing */
+    progress: LayoutProgress | null;
+    /** Manually trigger recomputation */
+    recompute: () => void;
+}
+/**
+ * Hook for computing layout from CodeGraph
+ *
+ * @param codeGraph - The CodeGraph to compute layout for, or null
+ * @param options - Configuration options
+ * @returns Layout computation state and controls
+ *
+ * @example
+ * ```tsx
+ * function App({ codeGraph }: { codeGraph: CodeGraph }) {
+ *   const { codeMap, isComputing, error, progress } = useLayout(codeGraph);
+ *
+ *   if (isComputing) {
+ *     return <Progress stage={progress?.stage} percent={progress?.percent} />;
+ *   }
+ *   if (error) return <Error message={error.message} />;
+ *   if (!codeMap) return null;
+ *
+ *   return <CodeMap codeMap={codeMap} theme="dark" />;
+ * }
+ * ```
+ */
+declare function useLayout(codeGraph: CodeGraph | null, options?: UseLayoutOptions): UseLayoutResult;
+
+/**
+ * useOverlayPort Hook
+ *
+ * React hook for managing overlays using the OverlayPort API.
+ * Provides a stable port instance and reactive overlay state.
+ */
+
+/**
+ * Options for useOverlayPort hook
+ */
+interface UseOverlayPortOptions {
+    /** Handler called when an overlay is clicked */
+    onOverlayClick?: OverlayClickHandler;
+    /** Handler called when an overlay is hovered */
+    onOverlayHover?: OverlayHoverHandler;
+    /** Initial overlays to add */
+    initialOverlays?: Omit<Overlay, 'id'>[];
+}
+/**
+ * Result of useOverlayPort hook
+ */
+interface UseOverlayPortResult {
+    /** The OverlayPort instance for imperative control */
+    port: OverlayPort;
+    /** Current list of overlays (reactive) */
+    overlays: Overlay[];
+    /** Clear all overlays */
+    clearAll: () => void;
+    /** Get overlay by ID */
+    getOverlay: (id: string) => Overlay | undefined;
+    /** Check if overlay exists */
+    hasOverlay: (id: string) => boolean;
+    /** Get overlay count */
+    count: number;
+}
+/**
+ * Hook for managing overlays with OverlayPort
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { port, overlays, clearAll } = useOverlayPort({
+ *     onOverlayClick: (id, overlay) => console.log('Clicked:', id),
+ *   });
+ *
+ *   // Add a cursor overlay
+ *   const addCursor = () => {
+ *     port.bind({
+ *       type: 'cursor',
+ *       position: { type: 'absolute', x: 100, y: 100 },
+ *       color: '#ff0000',
+ *       label: 'User 1',
+ *     });
+ *   };
+ *
+ *   return (
+ *     <CodeMap codeMap={codeMap} overlayPort={port} />
+ *   );
+ * }
+ * ```
+ */
+declare function useOverlayPort(options?: UseOverlayPortOptions): UseOverlayPortResult;
+
+export { unionBoundingBoxes as $, type AggregateNodeData as A, type BoundingBox$1 as B, type CallEdge$1 as C, type DirectoryMetrics as D, generateSymbolId as E, type FileMetrics as F, generateImportEdgeId as G, generateCallEdgeId as H, type ImportEdge$1 as I, normalizePath as J, getDirectory as K, type LayoutConfig as L, type MapNodeType as M, getFilename as N, getExtension as O, type Position as P, getBasename as Q, getParentDirectories as R, type Size as S, getPathDepth as T, matchesPattern as U, createBoundingBox as V, boundingBoxFromCorners as W, getBoundingBoxCenter as X, isPointInBoundingBox as Y, type ZoomLevel as Z, boundingBoxesOverlap as _, type Padding as a, type NoverlapOptions as a$, expandBoundingBox as a0, shrinkBoundingBox as a1, distance as a2, lerp as a3, clampPosition as a4, scaleSize as a5, uniformPadding as a6, getZoomLevel as a7, truncateLabel as a8, getShortFileLabel as a9, lighten as aA, darken as aB, saturate as aC, mix as aD, withOpacity as aE, rgbaToCss as aF, getScopeDepthColor as aG, generateScopeDepthColors as aH, getLuminance as aI, getContrastRatio as aJ, shouldUseDarkText as aK, getTextColorForBackground as aL, createScopeColorGetter as aM, mergeTheme as aN, type GraphNodeAttributes as aO, type GraphEdgeAttributes as aP, type DirectoryEdgeAttributes as aQ, type EntityIdMapping as aR, type GraphologyConversionResult as aS, type DirectoryGraphResult as aT, type ClusteringOptions as aU, type ClusteringResult as aV, type DirectoryForceOptions as aW, type DirectoryForceResult as aX, type HierarchyOptions as aY, type HierarchyResult as aZ, type ForcePositioningOptions as a_, getMediumFileLabel as aa, detectLanguage as ab, isCodeFile as ac, getIconName as ad, type RGBColor as ae, type RGBAColor as af, type ColorPalette as ag, type ScopeDepthColors as ah, type NodeColors as ai, type EdgeColors as aj, type OverlayColors as ak, type UIColors as al, type Theme as am, type ThemeContextValue as an, type ThemeProviderProps as ao, lightTheme as ap, darkTheme as aq, getTheme as ar, registerTheme as as, getThemeIds as at, getDefaultTheme as au, hexToRgb as av, rgbToHex as aw, hslToRgb as ax, hslToHex as ay, rgbToHsl as az, type SourceLocation as b, type CodeMapProps as b$, type EdgeRoutingOptions as b0, type ZoomPrecomputeOptions as b1, type ZoomLevelData as b2, type ComputeLayoutOptions as b3, type LayoutProgressCallback as b4, codeGraphToGraphology as b5, buildDirectoryGraph as b6, getEntityId as b7, getNodeKey as b8, getFilesInDirectory as b9, getNodeSizeAtLevel as bA, getNodeOpacityAtLevel as bB, computeLayout as bC, CodeMap as bD, Flow as bE, ThemeProvider as bF, useTheme as bG, useCurrentTheme as bH, useIsDarkTheme as bI, FileNode as bJ, ScopeNode as bK, SymbolNode as bL, AggregateNode as bM, nodeTypes as bN, ImportEdge as bO, CallEdge as bP, BundledEdge as bQ, edgeTypes as bR, getFileIcon as bS, getSymbolIcon as bT, getSymbolKindLabel as bU, formatNumber as bV, formatLoc as bW, codeMapToReactFlowNodes as bX, codeMapToReactFlowEdges as bY, getDefaultExpandedScopes as bZ, getZoomLevelFromZoom as b_, getDirectoryConnectionWeight as ba, detectCommunities as bb, getNodesInCluster as bc, getClusterStats as bd, assignClusterColors as be, getNodeCluster as bf, computeDirectoryForces as bg, normalizePositions as bh, getDirectoryPosition as bi, getPositionsAtDepth as bj, computeHierarchy as bk, getScopeByDirectoryId as bl, getChildScopes as bm, getRootScopes as bn, positionNodesInScope as bo, positionAllNodes as bp, calculateNodeSize as bq, removeOverlapsInScope as br, removeAllOverlaps as bs, computeEdges as bt, getEdgesAtZoomLevel as bu, getEdgeLabel as bv, computeZoomLevels as bw, getVisibleNodes as bx, getVisibleScopes as by, getVisibleEdges as bz, type SymbolMetrics as c, calculateOverlayPosition as c$, type FlowProps as c0, type ScopeNodeProps as c1, type NodeType as c2, type EdgeType as c3, type FileNodeData as c4, type SymbolNodeData as c5, type AggregateReactFlowNodeData as c6, type ScopeNodeData as c7, type ReactFlowNodeData as c8, type ImportEdgeData as c9, type HighlightOverlayInput as cA, type BadgeOverlayInput as cB, type AnnotationOverlayInput as cC, type DocumentOverlayInput as cD, type AgentWidgetOverlayInput as cE, type HighlightStyle as cF, type BadgeVariant as cG, type BadgeSize as cH, type AnnotationContentType as cI, type DocumentType as cJ, type DocumentStatus as cK, type AgentStatus as cL, type OverlayFilter as cM, type OverlayBatchUpdate as cN, type OverlayClickHandler as cO, type OverlayHoverHandler as cP, type IOverlayPort as cQ, type OverlayLayerProps as cR, type CalculatedPosition as cS, type NodeBounds as cT, type EdgePath as cU, type ViewportTransform as cV, OverlayPort as cW, createOverlayPort as cX, OverlayLayer as cY, SVGOverlayLayer as cZ, PortalOverlayLayer as c_, type CallEdgeData as ca, type BundledEdgeData as cb, type ReactFlowEdgeData as cc, useLayout as cd, useOverlayPort as ce, type LayoutProgress as cf, type UseLayoutOptions as cg, type UseLayoutResult as ch, type UseOverlayPortOptions as ci, type UseOverlayPortResult as cj, type AnchorPoint as ck, type AbsolutePosition as cl, type NodePosition as cm, type EdgePosition as cn, type OverlayPosition as co, type OverlayType as cp, type BaseOverlay as cq, type CursorOverlay as cr, type HighlightOverlay as cs, type BadgeOverlay as ct, type AnnotationOverlay as cu, type DocumentOverlay as cv, type AgentWidgetOverlay as cw, type Overlay as cx, type OverlayInput as cy, type CursorOverlayInput as cz, type FileNode$1 as d, getAnchorOffset as d0, graphToScreen as d1, screenToGraph as d2, type ViewMode as d3, type SigmaTheme as d4, type SigmaNodeAttributes as d5, type SigmaEdgeAttributes as d6, type RendererType as d7, type SigmaNodeColors as d8, type SigmaEdgeColors as d9, type SigmaHighlightConfig as da, type SigmaLabelConfig as db, type DirectoryNode as e, type SymbolKind as f, type SymbolNode$1 as g, type CodebaseMetadata as h, type CodeGraph as i, type MapNodeData as j, type MapNode as k, type MapScopeData as l, type MapScope as m, type MapEdgeType as n, type MapEdge as o, type CodeMap$1 as p, type ZoomLevelName as q, type ZoomLevelConfig as r, type AnimationConfig as s, type CodeMapConfig as t, DEFAULT_ZOOM_LEVELS as u, DEFAULT_LAYOUT_CONFIG as v, DEFAULT_ANIMATION_CONFIG as w, DEFAULT_CODEMAP_CONFIG as x, generateFileId as y, generateDirectoryId as z };