@fusefactory/fuse-three-forcegraph 1.0.1

package/dist/index.d.mts

@@ -0,0 +1,1468 @@
+import CameraControls from "camera-controls";
+import * as THREE from "three";
+
+//#region types/iCameraMode.d.ts
+declare enum CameraMode {
+  Orbit = "orbit",
+  Map = "map",
+}
+//#endregion
+//#region rendering/CameraController.d.ts
+interface CameraConfig {
+  fov?: number;
+  aspect?: number;
+  near?: number;
+  far?: number;
+  position?: THREE.Vector3;
+  target?: THREE.Vector3;
+  minDistance?: number;
+  maxDistance?: number;
+}
+interface ControlsConfig {
+  smoothTime?: number;
+  dollyToCursor?: boolean;
+  infinityDolly?: boolean;
+  enableZoom?: boolean;
+  enableRotation?: boolean;
+  enablePan?: boolean;
+  minDistance?: number;
+  maxDistance?: number;
+  maxPolarAngle?: number;
+  minPolarAngle?: number;
+  minAzimuthAngle?: number;
+  maxAzimuthAngle?: number;
+}
+declare class CameraController {
+  camera: THREE.PerspectiveCamera;
+  controls: CameraControls;
+  private sceneBounds;
+  private autorotateEnabled;
+  private autorotateSpeed;
+  private userIsActive;
+  constructor(domelement: HTMLElement, config?: CameraConfig);
+  private setupDefaultControls;
+  /**
+       * Set camera control mode
+       */
+  setMode(mode: CameraMode): void;
+  /**
+       * Set camera boundary
+       */
+  setBoundary(box: THREE.Box3): void;
+  /**
+       * Update camera controls (should be called in render loop)
+       * Only autorotate if enabled and user is inactive
+       */
+  update(delta: number): boolean;
+  /**
+       * Set autorotate enabled/disabled
+       */
+  setAutorotate(enabled: boolean, speed?: number): void;
+  /**
+       * Set user activity state
+       */
+  setUserIsActive(isActive: boolean): void;
+  /**
+       * Configure camera controls
+       */
+  configureControls(config: ControlsConfig): void;
+  /**
+       * Resize camera when window resizes
+       */
+  resize(width: number, height: number): void;
+  /**
+       * Animate camera to look at a specific target from a specific position
+       */
+  setLookAt(position: THREE.Vector3, target: THREE.Vector3, enableTransition?: boolean): Promise<void>;
+  /**
+       * Reset camera to default position
+       */
+  reset(enableTransition?: boolean): Promise<void>;
+  /**
+       * Enable/disable controls
+       */
+  setEnabled(enabled: boolean): void;
+  /**
+       * Get current camera target (look-at point)
+       */
+  getTarget(out?: THREE.Vector3): THREE.Vector3;
+  /**
+       * Dispose camera manager and clean up
+       */
+  dispose(): void;
+  /**
+       * Clear camera bounds (remove boundary restrictions)
+       */
+  clearBounds(): void;
+  /**
+       * Get current scene bounds
+       */
+  getSceneBounds(): THREE.Box3 | null;
+  /**
+       * Update scene bounds used by the camera manager.
+       * Stores the bounds for future use (e.g. constraining controls).
+       */
+  updateBounds(box: THREE.Box3): void;
+  /**
+       * Unified configuration method
+       */
+  setOptions(options: {
+    controls?: ControlsConfig;
+    autoRotate?: boolean;
+    autoRotateSpeed?: number;
+  }): void;
+}
+//#endregion
+//#region types/iGraphLink.d.ts
+interface GraphLink {
+  source: string;
+  target: string;
+}
+//#endregion
+//#region types/iGraphNode.d.ts
+interface GraphNode {
+  id: string;
+  label?: string;
+  description?: string;
+  thumbnailUrl?: string;
+  category?: string;
+  x?: number;
+  y?: number;
+  z?: number;
+  fx?: number;
+  fy?: number;
+  fz?: number;
+  state?: NodeState;
+  metadata?: any;
+}
+declare enum NodeState {
+  Hidden = 0,
+  // = 0 not rendered
+  Passive = 1,
+  // = 1 rendered, not influencing simulation,
+  Fixed = 2,
+  // = 2 rendered, influencing simulation, but not moving
+  Active = 3,
+}
+//#endregion
+//#region types/iGraphData.d.ts
+interface GraphData {
+  nodes: GraphNode[];
+  links: GraphLink[];
+  metadata?: any;
+}
+//#endregion
+//#region types/iForceConfig.d.ts
+interface ForceConfig {
+  collisionStrength: number;
+  collisionRadius: number;
+  collisionMaxDistance: number;
+  enableCollision: boolean;
+  manyBodyStrength: number;
+  manyBodyMinDistance: number;
+  manyBodyMaxDistance: number;
+  enableManyBody: boolean;
+  springStrength: number;
+  springLength: number;
+  springDamping: number;
+  maxLinks: number;
+  enableLinks: boolean;
+  gravity: number;
+  enableGravity: boolean;
+  attractorStrength: number;
+  enableAttractors: boolean;
+  elasticStrength: number;
+  enableElastic: boolean;
+  dragStrength: number;
+  damping: number;
+  alpha: number;
+  alphaDecay: number;
+  deltaTime: number;
+  spaceSize: number;
+  is3D: boolean;
+}
+//#endregion
+//#region types/iGraphPreset.d.ts
+interface GraphPreset {
+  name: string;
+  force?: Partial<ForceConfig>;
+  camera?: {
+    mode?: CameraMode;
+    position?: {
+      x: number;
+      y: number;
+      z: number;
+    };
+    target?: {
+      x: number;
+      y: number;
+      z: number;
+    };
+    zoom?: number;
+    transitionDuration?: number;
+    minDistance?: number;
+    maxDistance?: number;
+    boundary?: {
+      min: {
+        x: number;
+        y: number;
+        z: number;
+      };
+      max: {
+        x: number;
+        y: number;
+        z: number;
+      };
+    } | null;
+  };
+  nodes?: {
+    state?: (node: GraphNode) => NodeState;
+  };
+  links?: {
+    opacity?: number;
+  };
+}
+//#endregion
+//#region ui/Tooltips.d.ts
+/**
+ * Renderer function type for custom tooltip rendering
+ * Can mount React, Vue, or any other framework component
+ */
+type TooltipRenderer = (container: HTMLElement, node: GraphNode, type: 'preview' | 'full', x: number, y: number) => void | (() => void);
+/**
+ * Cursor handler for custom cursor behavior
+ */
+type CursorHandler = (canvas: HTMLCanvasElement | null, state: 'default' | 'pointer' | 'grab') => void;
+interface TooltipConfig {
+  /** Custom renderer for tooltips (React, Vue, etc.) */
+  renderer?: TooltipRenderer;
+  /** Custom cursor handler */
+  cursorHandler?: CursorHandler;
+}
+//#endregion
+//#region core/EventEmitter.d.ts
+declare class EventEmitter {
+  private listeners;
+  protected listenerCount(event: string): number;
+  on(event: string, listener: Function): () => void;
+  off(event: string, listener: Function): void;
+  emit(event: string, ...args: any[]): void;
+}
+//#endregion
+//#region controls/InputProcessor.d.ts
+/**
+ * Manages pointer/mouse input and emits interaction events
+ * Uses GPU picking for efficient node detection
+ */
+declare class InputProcessor extends EventEmitter {
+  private pickFn;
+  private canvas;
+  private viewport;
+  private readonly CLICK_THRESHOLD;
+  private readonly HOVER_TO_POP_MS;
+  private pointer;
+  private canvasPointer;
+  private isPointerDown;
+  private isDragging;
+  private mouseDownTime;
+  private draggedIndex;
+  private currentHoverIndex;
+  private hoverStartTime;
+  private hoverProgress;
+  private hasPopped;
+  private lastClientX;
+  private lastClientY;
+  constructor(pickFn: (x: number, y: number) => number, // Injected
+  canvas: HTMLCanvasElement, viewport: {
+    width: number;
+    height: number;
+  });
+  private setupEventListeners;
+  private handlePointerMove;
+  private handlePointerDown;
+  private handlePointerUp;
+  private handlePointerLeave;
+  private updateHover;
+  /**
+       * Update hover state even when pointer is stationary
+       * Called from render loop
+       */
+  update(): void;
+  private updatePointer;
+  /**
+       * Update viewport dimensions on resize
+       */
+  resize(width: number, height: number): void;
+  dispose(): void;
+}
+//#endregion
+//#region controls/handlers/HoverHandler.d.ts
+declare class HoverHandler extends EventEmitter {
+  private getNodeByIndex;
+  constructor(getNodeByIndex: (index: number) => GraphNode | null);
+  private handleHoverStart;
+  private handleHover;
+  private handlePop;
+  private handleHoverEnd;
+  dispose(): void;
+}
+//#endregion
+//#region controls/handlers/ClickHandler.d.ts
+declare class ClickHandler extends EventEmitter {
+  private getNodeByIndex;
+  constructor(getNodeByIndex: (index: number) => GraphNode | null);
+  private handleClick;
+  dispose(): void;
+}
+//#endregion
+//#region textures/SimulationBuffers.d.ts
+/**
+ * Manages dynamic render targets updated by force simulation
+ * Uses ping-pong technique for GPU computation
+ * Buffers are created lazily when data is initialized
+ */
+declare class SimulationBuffers {
+  private renderer;
+  private textureSize;
+  private positionBuffers;
+  private velocityBuffers;
+  private isInitialized;
+  constructor(renderer: THREE.WebGLRenderer);
+  /**
+       * Check if buffers are initialized
+       */
+  isReady(): boolean;
+  /**
+       * Initialize buffers with point count and initial positions
+       */
+  init(pointsCount: number, initialPositions?: Float32Array): void;
+  /**
+       * Resize buffers (re-initializes with new size)
+       */
+  resize(pointsCount: number, preserveData?: boolean): void;
+  private calculateTextureSize;
+  private createDynamicBuffer;
+  /**
+       * Initialize position buffers from initial data
+       */
+  setInitialPositions(positionArray: Float32Array): void;
+  /**
+       * Update current and previous positions, but keep original positions intact
+       */
+  updateCurrentPositions(positionArray: Float32Array): void;
+  /**
+       * Set original positions (anchors) separately from current positions
+       */
+  setOriginalPositions(positionArray: Float32Array): void;
+  /**
+       * Initialize velocity buffers (usually to zero)
+       */
+  initVelocities(): void;
+  /**
+       * Swap position buffers (ping-pong)
+       */
+  swapPositions(): void;
+  /**
+       * Swap velocity buffers (ping-pong)
+       */
+  swapVelocities(): void;
+  /**
+       * Reset positions to original state
+       */
+  resetPositions(): void;
+  /**
+       * Read current positions back from GPU (expensive operation)
+       * Returns RGBA float array (x, y, z, state)
+       */
+  readPositions(): Float32Array;
+  getCurrentPositionTarget(): THREE.WebGLRenderTarget | null;
+  getPreviousPositionTarget(): THREE.WebGLRenderTarget | null;
+  getCurrentPositionTexture(): THREE.Texture<unknown>;
+  getPreviousPositionTexture(): THREE.Texture | null;
+  getOriginalPositionTexture(): THREE.Texture | null;
+  getCurrentVelocityTarget(): THREE.WebGLRenderTarget | null;
+  getPreviousVelocityTarget(): THREE.WebGLRenderTarget | null;
+  getCurrentVelocityTexture(): THREE.Texture | null;
+  getPreviousVelocityTexture(): THREE.Texture | null;
+  getTextureSize(): number;
+  private arrayToTextureData;
+  private createDataTexture;
+  private copyTextureToBuffer;
+  private copyBufferToBuffer;
+  dispose(): void;
+}
+//#endregion
+//#region types/iAttractor.d.ts
+/**
+ * Simple 3D vector type
+ */
+interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+/**
+ * Attractor - A point in space that attracts nodes of specific groups
+ */
+interface Attractor {
+  /** Unique identifier */
+  id: string;
+  /** Position in world space */
+  position: Vec3;
+  /** Radius of attraction (default: 0.0) - nodes within this radius are not pulled further */
+  radius?: number;
+  /** Groups of nodes attracted to this attractor (empty = attracts all) */
+  groups: string[];
+  /** Strength of attraction (default: 1.0) */
+  strength?: number;
+}
+/**
+ * Resolved attractor with defaults applied
+ */
+interface ResolvedAttractor {
+  id: string;
+  position: Vec3;
+  groups: string[];
+  strength: number;
+  radius: number;
+}
+//#endregion
+//#region textures/StaticAssets.d.ts
+/**
+ * Manages read-only GPU textures created at initialization
+ * These never change during simulation (except for mode changes)
+ *
+ * Node data: radii, colors
+ * Link data: source/target indices, properties
+ */
+declare class StaticAssets {
+  private nodeRadiiTexture;
+  private nodeColorsTexture;
+  private linkIndicesTexture;
+  private linkPropertiesTexture;
+  private nodeLinkMapTexture;
+  private nodeTextureSize;
+  private linkTextureSize;
+  constructor();
+  /**
+       * Set/update node radii texture
+       */
+  setNodeRadii(radii: Float32Array, textureSize: number): void;
+  /**
+       * Set/update node colors texture
+       */
+  setNodeColors(colors: Float32Array, textureSize: number): void;
+  /**
+       * Set link indices (source/target pairs)
+       * Format: [sourceX, sourceY, targetX, targetY] per link
+       */
+  setLinkIndices(linkIndices: Float32Array, textureSize: number): void;
+  /**
+       * Set link properties (strength, distance, etc.)
+       */
+  setLinkProperties(linkProperties: Float32Array, textureSize: number): void;
+  setNodeLinkMap(linkMap: Float32Array, textureSize: number): void;
+  /**
+       * Create a data texture with proper settings for GPU compute
+       */
+  private createTexture;
+  getNodeRadiiTexture(): THREE.DataTexture | null;
+  getNodeColorsTexture(): THREE.DataTexture | null;
+  getLinkIndicesTexture(): THREE.DataTexture | null;
+  getLinkPropertiesTexture(): THREE.DataTexture | null;
+  getLinkMapTexture(): THREE.DataTexture | null;
+  getNodeTextureSize(): number;
+  getLinkTextureSize(): number;
+  /**
+       * Check if assets are ready
+       */
+  hasNodeAssets(): boolean;
+  hasLinkAssets(): boolean;
+  /**
+       * Cleanup
+       */
+  dispose(): void;
+}
+declare const staticAssets: StaticAssets;
+//#endregion
+//#region simulation/BasePass.d.ts
+interface PassContext {
+  scene: THREE.Scene;
+  camera: THREE.Camera;
+  quad: THREE.BufferGeometry;
+  simBuffers: SimulationBuffers;
+  assets: StaticAssets;
+  renderer: THREE.WebGLRenderer;
+  config: ForceConfig;
+  textureSize: number;
+}
+/**
+ * Base class for GPU force simulation passes
+ * Each pass operates on simulation buffers and can read from static assets
+ */
+declare abstract class BasePass {
+  protected material: THREE.ShaderMaterial | null;
+  protected enabled: boolean;
+  /**
+       * Get the name/identifier for this pass
+       */
+  abstract getName(): string;
+  /**
+       * Initialize the shader material for this pass
+       */
+  abstract initMaterial(context: PassContext): void;
+  /**
+       * Update uniforms before executing the pass
+       */
+  abstract updateUniforms(context: PassContext): void;
+  /**
+       * Execute the pass (renders to current velocity target)
+       */
+  execute(context: PassContext): void;
+  /**
+       * Render the compute shader
+       */
+  protected render(context: PassContext): void;
+  /**
+       * Create a shader material helper
+       */
+  protected createMaterial(vertexShader: string, fragmentShader: string, uniforms: {
+    [uniform: string]: THREE.IUniform;
+  }): THREE.ShaderMaterial;
+  /**
+       * Safe uniform setter - avoids TypeScript strict null check issues
+       */
+  protected setUniform(name: string, value: unknown): void;
+  /**
+       * Enable or disable this pass
+       */
+  setEnabled(enabled: boolean): void;
+  /**
+       * Check if pass is enabled
+       */
+  isEnabled(): boolean;
+  /**
+       * Get the material for external access
+       */
+  getMaterial(): THREE.ShaderMaterial | null;
+  /**
+       * Cleanup resources
+       */
+  dispose(): void;
+}
+//#endregion
+//#region simulation/passes/AttractorPass.d.ts
+/**
+ * Attractor force pass - attracts nodes to attractor points based on group membership
+ *
+ * Usage:
+ *   attractorPass.setAttractors([
+ *     { id: 'center', position: { x: 0, y: 0, z: 0 }, categories: ['root'] }, // categories acts as groups
+ *     { id: 'left', position: { x: -100, y: 0, z: 0 }, categories: ['artwork', 'series'] }
+ *   ])
+ */
+declare class AttractorPass extends BasePass {
+  private attractors;
+  private groupMap;
+  private attractorsTexture;
+  private attractorGroupsTexture;
+  private attractorParamsTexture;
+  private nodeGroupsTexture;
+  getName(): string;
+  initMaterial(context: PassContext): void;
+  updateUniforms(context: PassContext): void;
+  /**
+       * Set attractors for the simulation
+       */
+  setAttractors(attractors: Attractor[]): void;
+  /**
+       * Add a single attractor
+       */
+  addAttractor(attractor: Attractor): void;
+  /**
+       * Remove an attractor by ID
+       */
+  removeAttractor(id: string): void;
+  /**
+       * Update an existing attractor's position
+       */
+  updateAttractorPosition(id: string, position: Vec3): void;
+  /**
+       * Get current attractors
+       */
+  getAttractors(): ResolvedAttractor[];
+  /**
+       * Set node groups from graph data
+       * Call this when graph data changes or grouping criteria changes
+       */
+  setNodeGroups(groups: string[][], textureSize: number): void;
+  /**
+       * Get the group map (group name -> index)
+       */
+  getGroupMap(): Map<string, number>;
+  private createAttractorTextures;
+  private updateAttractorTextures;
+  dispose(): void;
+}
+//#endregion
+//#region simulation/ForceSimulation.d.ts
+/**
+ * ForceSimulation - GPU-based force simulation
+ *
+ * Simple architecture:
+ * - Single shared config object (ForceConfig)
+ * - All passes read directly from config via PassContext
+ * - Enable flags control which passes execute
+ * - No manual syncing required
+ */
+declare class ForceSimulation {
+  private renderer;
+  private simulationBuffers;
+  private computeScene;
+  private computeCamera;
+  private computeQuad;
+  private velocityCarryPass;
+  private collisionPass;
+  private manyBodyPass;
+  private gravityPass;
+  private linkPass;
+  private elasticPass;
+  private attractorPass;
+  private dragPass;
+  private integratePass;
+  private forcePasses;
+  readonly config: ForceConfig;
+  private isInitialized;
+  private iterationCount;
+  constructor(renderer: THREE.WebGLRenderer);
+  private createComputeQuad;
+  /**
+       * Initialize simulation with buffers
+       */
+  initialize(simulationBuffers: SimulationBuffers): void;
+  private createContext;
+  /**
+       * Check if a pass should execute based on config
+       */
+  private shouldExecutePass;
+  /**
+       * Run one simulation step
+       */
+  step(deltaTime?: number): void;
+  /**
+       * Get config for GUI binding
+       * Modify this object directly - changes take effect on next step()
+       */
+  getConfig(): ForceConfig;
+  /**
+       * Re-heat the simulation (set alpha to 1)
+       */
+  reheat(amt?: number): void;
+  startDrag(index: number, targetWorldPos: THREE.Vector3): void;
+  updateDrag(targetWorldPos: THREE.Vector3): void;
+  endDrag(): void;
+  /**
+       * Set attractors for category-based attraction
+       * @param attractors Array of attractor definitions
+       */
+  setAttractors(attractors: Attractor[]): void;
+  /**
+       * Add a single attractor
+       */
+  addAttractor(attractor: Attractor): void;
+  /**
+       * Remove an attractor by ID
+       */
+  removeAttractor(id: string): void;
+  /**
+       * Update an attractor's position (useful for animated attractors)
+       */
+  updateAttractorPosition(id: string, position: Vec3): void;
+  /**
+       * Get current attractors
+       */
+  getAttractors(): Attractor[];
+  /**
+       * Set node logic for attractor matching
+       * Call this when graph data changes
+       */
+  setNodeGroups(groups: (string | string[])[]): void;
+  setNodeGroupsFromData<T>(data: T[], accessor: (item: T, index: number) => string | string[] | undefined): void;
+  /**
+       * Get the attractor pass for direct access
+       */
+  getAttractorPass(): AttractorPass;
+  getAlpha(): number;
+  getIterationCount(): number;
+  reset(): void;
+  dispose(): void;
+}
+//#endregion
+//#region controls/handlers/DragHandler.d.ts
+declare class DragHandler extends EventEmitter {
+  private getNodeByIndex;
+  private cameraController?;
+  private forceSimulation?;
+  private viewport?;
+  private isDragging;
+  private raycaster;
+  private dragPlane;
+  private pointer;
+  constructor(getNodeByIndex: (index: number) => GraphNode | null, cameraController?: CameraController, forceSimulation?: ForceSimulation, viewport?: {
+    width: number;
+    height: number;
+  });
+  /**
+       * Set up drag plane perpendicular to camera, passing through a world point
+       */
+  private setupDragPlane;
+  private handleDragStart;
+  private handleDrag;
+  private handleDragEnd;
+  /**
+       * Convert screen coordinates to world position on drag plane
+       */
+  private screenToWorld;
+  /**
+       * Update viewport dimensions on resize
+       */
+  resize(width: number, height: number): void;
+  dispose(): void;
+}
+//#endregion
+//#region textures/PickBuffer.d.ts
+/**
+ * Manages GPU picking buffer for mouse interaction
+ * Separate from simulation buffers as it has different lifecycle
+ */
+declare class PickBuffer {
+  private renderer;
+  private pickTarget;
+  constructor(renderer: THREE.WebGLRenderer);
+  /**
+       * Ensure pick buffer matches viewport size
+       */
+  resize(width: number, height: number): void;
+  private createPickBuffer;
+  /**
+       * Read node ID at pixel coordinates
+       */
+  readIdAt(x: number, y: number): number;
+  /**
+       * Render scene to pick buffer
+       */
+  render(scene: THREE.Scene, camera: THREE.Camera): void;
+  getTarget(): THREE.WebGLRenderTarget | null;
+  dispose(): void;
+}
+//#endregion
+//#region rendering/links/LinksRenderer.d.ts
+/**
+ * LinksRenderer - Renders links as line segments
+ * Uses shared SimulationBuffers for node positions
+ * Manages link-specific opacity and highlighting
+ */
+declare class LinksRenderer {
+  private scene;
+  private renderer;
+  private lines;
+  private links;
+  private nodeIndexMap;
+  private linkIndexMap;
+  private interpolationSteps;
+  params: {
+    noiseStrength: number;
+    defaultAlpha: number;
+    highlightAlpha: number;
+    dimmedAlpha: number;
+    is2D: boolean;
+  };
+  private linkOpacity;
+  private simulationBuffers;
+  constructor(scene: THREE.Scene, renderer: THREE.WebGLRenderer);
+  /**
+       * Create link geometry and materials
+       * Receives shared buffers as dependencies
+       */
+  create(links: GraphLink[], nodes: GraphNode[], simulationBuffers: SimulationBuffers): void;
+  /**
+       * Update position texture from simulation
+       * This is the SHARED texture used by both nodes and links
+       */
+  setPositionTexture(positionTexture: THREE.Texture): void;
+  /**
+       * Update shader uniforms (called each frame)
+       */
+  update(time: number): void;
+  /**
+       * Update link opacity (called every frame)
+       */
+  updateOpacity(): void;
+  /**
+       * Highlight links connected to a specific node
+       */
+  highlightConnectedLinks(nodeId: string, step?: number): void;
+  /**
+       * Clear all highlights (return to defaultAlpha)
+       */
+  clearHighlights(step?: number): void;
+  /**
+       * Update noise strength parameter
+       */
+  setNoiseStrength(strength: number): void;
+  /**
+       * Update alpha parameters
+       */
+  setAlphaParams(params: {
+    defaultAlpha?: number;
+    highlightAlpha?: number;
+    dimmedAlpha?: number;
+  }): void;
+  /**
+       * Unified configuration method
+       */
+  setOptions(options: LinkOptions): void;
+  /**
+       * Refresh shader uniforms when params change
+       */
+  refreshUniforms(): void;
+  /**
+       * Handle window resize
+       */
+  resize(width: number, height: number): void;
+  /**
+       * Set visibility of links
+       */
+  setVisible(visible: boolean): void;
+  /**
+       * Check if links are visible
+       */
+  isVisible(): boolean;
+  /**
+       * Cleanup
+       */
+  dispose(): void;
+  /**
+       * Build node index mapping
+       */
+  private buildNodeMapping;
+  /**
+       * Create link geometry with interpolated segments
+       */
+  private createLinkGeometry;
+  /**
+       * Build all link-related textures for simulation
+       * - linkIndicesData: parent node INDEX per link entry (organized by child)
+       * - linkPropertiesData: strength/distance per link entry
+       * - nodeLinkMapData: per-node metadata (startX, startY, count, hasLinks)
+       */
+  private buildLinkTextures;
+  /**
+       * Create render material with all uniforms
+       */
+  private createRenderMaterial;
+}
+interface LinkOptions {
+  visible?: boolean;
+  noiseStrength?: number;
+  alpha?: {
+    default?: number;
+    highlight?: number;
+    dimmed?: number;
+  };
+}
+//#endregion
+//#region rendering/nodes/NodesRenderer.d.ts
+declare class NodesRenderer {
+  private scene;
+  private renderer;
+  private points;
+  private pickMaterial;
+  private nodeIndexMap;
+  private idArray;
+  private nodeOpacity;
+  private targets;
+  params: {
+    defaultAlpha: number;
+    highlightAlpha: number;
+    dimmedAlpha: number;
+  };
+  private simulationBuffers;
+  private pickBuffer;
+  constructor(scene: THREE.Scene, renderer: THREE.WebGLRenderer);
+  create(nodes: GraphNode[], simulationBuffers: SimulationBuffers, pickBuffer: PickBuffer): void;
+  setPositionTexture(positionTexture: THREE.Texture): void;
+  pick(pixelX: number, pixelY: number, camera: THREE.Camera): number;
+  highlight(nodeIds: string[], step?: number): void;
+  clearHighlights(step?: number): void;
+  /**
+       * Update node opacity (called every frame)
+       */
+  updateOpacity(): void;
+  resize(width: number, height: number): void;
+  dispose(): void;
+  private buildNodeMapping;
+  /**
+       * Create all node data in one pass
+       * Returns: colors, sizes, radii, nodeIds, pointIndices, alphaIndex
+       */
+  private createNodeData;
+  private createGeometry;
+  private createRenderMaterial;
+  private createPickMaterial;
+}
+//#endregion
+//#region rendering/GraphScene.d.ts
+/**
+ * GraphScene - Manages the 3D scene, camera, and renderers
+ * Responsibilities:
+ * - Scene setup and lifecycle
+ * - Node and link rendering
+ * - Camera control
+ * - Tooltip management
+ * - Mode application (visual changes)
+ */
+declare class GraphScene {
+  readonly scene: THREE.Scene;
+  readonly renderer: THREE.WebGLRenderer;
+  readonly camera: CameraController;
+  private nodeRenderer;
+  private clock;
+  private linkRenderer;
+  constructor(canvas: HTMLCanvasElement, cameraConfig?: CameraConfig);
+  /**
+       * Initialize scene with nodes and links
+       */
+  create(nodes: GraphNode[], links: GraphLink[], simulationBuffers: SimulationBuffers, pickBuffer: PickBuffer, groupOrder?: string[]): void;
+  /**
+       * Apply visual mode (colors, sizes, camera position)
+       */
+  applyMode(mode: string, options?: {
+    transitionDuration?: number;
+    cameraTransitionDuration?: number;
+  }): void;
+  /**
+       * Update position textures from simulation
+       */
+  updatePositions(positionTexture: THREE.Texture): void;
+  /**
+       * Update time-based uniforms (called each frame with elapsed time)
+       */
+  update(elapsedTime: number): void;
+  /**
+       * GPU picking at canvas coordinates
+       */
+  pick(pixelX: number, pixelY: number): number;
+  /**
+       * Render the scene
+       */
+  render(): void;
+  /**
+       * Handle window resize
+       */
+  resize(width: number, height: number): void;
+  /**
+       * Cleanup all resources
+       */
+  dispose(): void;
+  private applyDefaultMode;
+  getCamera(): CameraController;
+  getNodeRenderer(): NodesRenderer | null;
+  getLinkRenderer(): LinksRenderer | null;
+}
+//#endregion
+//#region ui/TooltipManager.d.ts
+declare class TooltipManager {
+  private container;
+  private canvas;
+  private mainTooltip;
+  private previewTooltip;
+  private chainTooltips;
+  private config;
+  private closeButton;
+  private onCloseCallback?;
+  constructor(container: HTMLElement, canvas: HTMLCanvasElement, config?: TooltipConfig);
+  /**
+       * Show grab cursor when hovering over a node
+       */
+  showGrabIcon(x: number, y: number, progress: number): void;
+  hideGrabIcon(): void;
+  /**
+       * Show preview tooltip (triggered by pop event when hover reaches 1.0)
+       */
+  showPreview(node: GraphNode, x: number, y: number): void;
+  hidePreview(): void;
+  /**
+       * Show full tooltip (triggered by click)
+       */
+  showFull(node: GraphNode, x: number, y: number): void;
+  hideFull(): void;
+  /**
+       * Set callback for when tooltip is closed
+       */
+  setOnCloseCallback(callback: () => void): void;
+  /**
+       * Add close button to tooltip
+       */
+  private addCloseButton;
+  /**
+       * Remove close button from tooltip
+       */
+  private removeCloseButton;
+  /**
+       * Hide all tooltips
+       */
+  hideAll(): void;
+  /**
+       * Generate preview content (subset of fields)
+       */
+  private generatePreviewContent;
+  /**
+       * Generate full tooltip content (all fields)
+       */
+  private generateFullContent;
+  private escapeHtml;
+  showMainTooltip(content: string, x: number, y: number): void;
+  hideMainTooltip(): void;
+  showChainTooltip(nodeId: string, content: string, x: number, y: number): void;
+  hideChainTooltips(): void;
+  updateMainTooltipPos(x: number, y: number): void;
+  dispose(): void;
+}
+//#endregion
+//#region controls/InteractionManager.d.ts
+declare class InteractionManager {
+  private graphScene?;
+  private getConnectedNodeIds?;
+  private pointerInput;
+  private hoverHandler;
+  private clickHandler;
+  private dragHandler;
+  tooltipManager: TooltipManager;
+  private isDragging;
+  isTooltipSticky: boolean;
+  stickyNodeId: string | null;
+  searchHighlightIds: string[];
+  constructor(pickFunction: (x: number, y: number) => number, canvas: HTMLCanvasElement, viewport: {
+    width: number;
+    height: number;
+  }, getNodeByIndex: (index: number) => GraphNode | null, cameraController?: CameraController, forceSimulation?: ForceSimulation, tooltipConfig?: TooltipConfig, graphScene?: GraphScene, getConnectedNodeIds?: (nodeId: string) => string[]);
+  private wireEvents;
+  private wireTooltipEvents;
+  /**
+       * Wire visual feedback events (opacity, highlighting)
+       * Centralized control of visual responses to interactions
+       */
+  private wireVisualFeedbackEvents;
+  getPointerInput(): InputProcessor;
+  getHoverHandler(): HoverHandler;
+  getClickHandler(): ClickHandler;
+  getDragHandler(): DragHandler;
+  getTooltipManager(): TooltipManager;
+  isTooltipStickyOpen(): boolean;
+  /**
+       * Update viewport dimensions on resize
+       */
+  resize(width: number, height: number): void;
+  cleanup(): void;
+  dispose(): void;
+}
+//#endregion
+//#region core/Clock.d.ts
+/**
+ * Clock - Unified timing for the force graph package
+ */
+declare class Clock {
+  private previousTime;
+  private elapsedTime;
+  private deltaTime;
+  private isRunning;
+  private maxDeltaTime;
+  constructor();
+  /**
+       * Start the clock
+       */
+  start(): void;
+  /**
+       * Stop the clock
+       */
+  stop(): void;
+  /**
+       * Update the clock - call once per frame
+       * @returns delta time in seconds
+       */
+  update(): number;
+  /**
+       * Get delta time in seconds
+       */
+  getDeltaTime(): number;
+  /**
+       * Get total elapsed time in seconds
+       */
+  getElapsedTime(): number;
+  /**
+       * Check if clock is running
+       */
+  getIsRunning(): boolean;
+}
+//#endregion
+//#region core/GraphStore.d.ts
+/**
+ * GraphStore - Central data management
+ * Responsibilities:
+ * - Store raw graph data (nodes, links)
+ * - Node/Link CRUD operations
+ * - ID mapping and lookups
+ * - Data validation
+ * - Change notifications
+ */
+declare class GraphStore {
+  private nodes;
+  private links;
+  private nodeArray;
+  private linkArray;
+  private nodeIdToIndex;
+  private linkIdToIndex;
+  private nodeToLinks;
+  constructor();
+  /**
+       * Set graph data (replaces all)
+       */
+  setData(data: GraphData): void;
+  /**
+       * Add nodes
+       */
+  addNodes(nodes: GraphNode[]): void;
+  /**
+       * Remove nodes (and connected links)
+       */
+  removeNodes(nodeIds: string[]): void;
+  /**
+       * Add links
+       */
+  addLinks(links: GraphLink[]): void;
+  /**
+       * Remove links
+       */
+  removeLinks(linkIds: string[]): void;
+  /**
+       * Get all nodes as array
+       */
+  getNodes(): GraphNode[];
+  /**
+       * Get all links as array
+       */
+  getLinks(): GraphLink[];
+  /**
+       * Get connected node IDs for a given node
+       */
+  getConnectedNodeIds(nodeId: string): string[];
+  /**
+       * Get node by ID
+       */
+  getNodeById(id: string): GraphNode | null;
+  /**
+       * Get node by index
+       */
+  getNodeByIndex(index: number): GraphNode | null;
+  /**
+       * Get node index
+       */
+  getNodeIndex(id: string): number;
+  /**
+       * Get link by ID
+       */
+  getLinkById(id: string): GraphLink | null;
+  /**
+       * Get links connected to node
+       */
+  getNodeLinks(nodeId: string): GraphLink[];
+  /**
+       * Get node count
+       */
+  getNodeCount(): number;
+  /**
+       * Get link count
+       */
+  getLinkCount(): number;
+  /**
+       * Clear all data
+       */
+  clear(): void;
+  private getLinkId;
+  private addLinkConnectivity;
+  private removeLinkConnectivity;
+  private rebuildNodeArrays;
+  private rebuildLinkArrays;
+}
+//#endregion
+//#region core/Engine.d.ts
+interface EngineOptions {
+  width?: number;
+  height?: number;
+  backgroundColor?: string;
+  tooltipConfig?: TooltipConfig;
+  groupOrder?: string[];
+}
+/**
+ * Engine - Main orchestrator
+ * Responsibilities:
+ * - Owns all shared buffers (StaticAssets, SimulationBuffers, PickBuffer)
+ * - Coordinates GraphStore, GraphScene, ForceSimulation
+ * - Manages render loop
+ * - Handles user interaction
+ */
+declare class Engine {
+  readonly canvas: HTMLCanvasElement;
+  readonly graphStore: GraphStore;
+  private graphScene;
+  private forceSimulation;
+  interactionManager: InteractionManager;
+  private clock;
+  private simulationBuffers;
+  private pickBuffer;
+  private animationFrameId;
+  private isRunning;
+  private boundResizeHandler;
+  private groupOrder?;
+  constructor(canvas: HTMLCanvasElement, options?: EngineOptions);
+  /**
+       * Handle window resize event
+       */
+  private handleWindowResize;
+  /**
+       * Set graph data
+       */
+  setData(data: GraphData): void;
+  /**
+       * Update node states based on a callback
+       * This allows changing visibility/behavior without resetting the simulation
+       */
+  updateNodeStates(callback: (node: GraphNode) => NodeState): void;
+  /**
+       * Reheat the simulation
+       */
+  reheat(alpha?: number): void;
+  /**
+       * Set alpha decay
+       */
+  setAlphaDecay(decay: number): void;
+  /**
+       * Get current alpha
+       */
+  getAlpha(): number;
+  /**Apply a preset to the graph
+       */
+  applyPreset(preset: GraphPreset): void;
+  /**
+       *
+       * Start render loop
+       */
+  start(): void;
+  /**
+       * Stop render loop
+       */
+  stop(): void;
+  /**
+       * Render loop
+       */
+  private animate;
+  /**
+       * GPU pick node at canvas coordinates
+       */
+  pickNode(x: number, y: number): string | null;
+  /**
+       * Get node by ID
+       */
+  getNodeById(id: string): GraphNode | null;
+  /**
+       * Highlight nodes
+       */
+  highlightNodes(nodeIds: string[]): void;
+  /**
+       * Clear highlights
+       */
+  clearHighlights(): void;
+  /**
+       * Get node position in 3D space
+       */
+  getNodePosition(nodeId: string): THREE.Vector3 | null;
+  /**
+       * Programmatically select a node (highlight + tooltip)
+       */
+  selectNode(nodeId: string): void;
+  /**
+       * Resize canvas and all dependent components
+       */
+  resize(width: number, height: number): void;
+  /**
+       * Get the unified clock for timing information
+       */
+  getClock(): Clock;
+  /**
+       * Get all nodes
+       */
+  get nodes(): GraphNode[];
+  /**
+       * Get all links
+       */
+  get links(): GraphLink[];
+  /**
+       * Get force simulation for external configuration (GUI binding)
+       */
+  get simulation(): ForceSimulation;
+  /**
+       * Get camera controller for external configuration
+       */
+  get camera(): CameraController;
+  /**
+       * Set camera mode (Orbit, Map, Fly)
+       */
+  setCameraMode(mode: CameraMode): void;
+  /**
+       * Animate camera to look at a specific target from a specific position
+       */
+  setCameraLookAt(position: {
+    x: number;
+    y: number;
+    z: number;
+  }, target: {
+    x: number;
+    y: number;
+    z: number;
+  }, transitionDuration?: number): Promise<void>;
+  /**
+       * Focus camera on a specific target node
+       */
+  setCameraFocus(target: {
+    x: number;
+    y: number;
+    z: number;
+  }, distance: number, transitionDuration?: number): Promise<void>;
+  /**
+       * Cleanup
+       */
+  dispose(): void;
+  private calculateTextureSize;
+}
+//#endregion
+//#region core/StyleRegistry.d.ts
+/** Color input - can be THREE.Color, hex number, or CSS color string */
+type ColorInput = THREE.Color | number | string;
+/**
+ * Visual properties for a node category (input)
+ */
+interface NodeStyle {
+  color: ColorInput;
+  size: number;
+}
+/**
+ * Visual properties for a link category (input)
+ */
+interface LinkStyle {
+  color: ColorInput;
+}
+/**
+ * Resolved node style with THREE.Color
+ */
+interface ResolvedNodeStyle {
+  color: THREE.Color;
+  size: number;
+}
+/**
+ * Resolved link style with THREE.Color
+ */
+interface ResolvedLinkStyle {
+  color: THREE.Color;
+}
+/**
+ * StyleRegistry - Manages visual styles for node and link categories
+ *
+ * Usage:
+ *   styleRegistry.setNodeStyle('person', { color: 0xff0000, size: 20 })
+ *   styleRegistry.setLinkStyle('friendship', { color: '#00ff00', width: 2 })
+ *
+ *   const style = styleRegistry.getNodeStyle('person')
+ */
+declare class StyleRegistry {
+  private nodeStyles;
+  private linkStyles;
+  private defaultNodeStyle;
+  private defaultLinkStyle;
+  /**
+       * Convert color input to THREE.Color
+       */
+  private toColor;
+  /**
+       * Set the default style for nodes without a category
+       */
+  setDefaultNodeStyle(style: Partial<NodeStyle>): void;
+  /**
+       * Set the default style for links without a category
+       */
+  setDefaultLinkStyle(style: Partial<LinkStyle>): void;
+  /**
+       * Register a style for a node category
+       */
+  setNodeStyle(category: string, style: NodeStyle): void;
+  /**
+       * Register multiple node styles at once
+       */
+  setNodeStyles(styles: Record<string, NodeStyle>): void;
+  /**
+       * Register a style for a link category
+       */
+  setLinkStyle(category: string, style: LinkStyle): void;
+  /**
+       * Register multiple link styles at once
+       */
+  setLinkStyles(styles: Record<string, LinkStyle>): void;
+  /**
+       * Get the resolved style for a node category
+       */
+  getNodeStyle(category?: string): ResolvedNodeStyle;
+  /**
+       * Get the resolved style for a link category
+       */
+  getLinkStyle(category?: string): ResolvedLinkStyle;
+  /**
+       * Check if a node category exists
+       */
+  hasNodeStyle(category: string): boolean;
+  /**
+       * Check if a link category exists
+       */
+  hasLinkStyle(category: string): boolean;
+  /**
+       * Remove a node style
+       */
+  removeNodeStyle(category: string): void;
+  /**
+       * Remove a link style
+       */
+  removeLinkStyle(category: string): void;
+  /**
+       * Clear all styles
+       */
+  clear(): void;
+  /**
+       * Get all registered node categories
+       */
+  getNodeCategories(): string[];
+  /**
+       * Get all registered link categories
+       */
+  getLinkCategories(): string[];
+}
+declare const styleRegistry: StyleRegistry;
+//#endregion
+//#region types/iEngineConfig.d.ts
+interface EngineConfig {
+  container: HTMLElement;
+  width?: number;
+  height?: number;
+  antialias?: boolean;
+  alpha?: boolean;
+}
+//#endregion
+export { type Attractor, type CameraConfig, CameraMode, Clock, Engine, type EngineConfig, type ForceConfig, ForceSimulation, type GraphData, type GraphLink, type GraphNode, type GraphPreset, GraphScene, GraphStore, type LinkStyle, NodeState, type NodeStyle, PickBuffer, type ResolvedAttractor, type ResolvedLinkStyle, type ResolvedNodeStyle, SimulationBuffers, StaticAssets, type Vec3, staticAssets, styleRegistry };