index.d.ts

/**
 * Node Selection Hook
 *
 * This module provides a Node.js interface for monitoring text selections
 * across applications on Windows, macOS, and Linux using platform-specific
 * accessibility and input APIs.
 */

import { EventEmitter } from "events";

/**
 * Represents a 2D coordinate point in screen coordinates (pixels).
 */
export interface Point {
  x: number;
  y: number;
}

/**
 * Text selection data returned by the native module
 *
 * Contains the selected text and its position information.
 * Position coordinates are in screen coordinates (pixels).
 *
 * On Linux, `startTop`/`startBottom`/`endTop`/`endBottom` are always
 * `-99999` (INVALID_COORDINATE) because selection bounding rectangles are
 * not available. On Linux Wayland, `mousePosStart`/`mousePosEnd` may also
 * be `-99999` when the coordinate source cannot provide screen positions.
 */
export interface TextSelectionData {
  /** The selected text content */
  text: string;
  /** The program name that triggered the selection */
  programName: string;
  /** First paragraph's top-left point (x, y) in pixels */
  startTop: Point;
  /** First paragraph's bottom-left point (x, y) in pixels */
  startBottom: Point;
  /** Last paragraph's top-right point (x, y) in pixels */
  endTop: Point;
  /** Last paragraph's bottom-right point (x, y) in pixels */
  endBottom: Point;
  /** Mouse position when selection started (x, y) in pixels */
  mousePosStart: Point;
  /** Mouse position when selection ended (x, y) in pixels */
  mousePosEnd: Point;
  /** Selection method identifier */
  method: (typeof SelectionHook.SelectionMethod)[keyof typeof SelectionHook.SelectionMethod];
  /** Position level identifier */
  posLevel: (typeof SelectionHook.PositionLevel)[keyof typeof SelectionHook.PositionLevel];
  /** Whether the current app's front window is in fullscreen mode, macOS only */
  isFullscreen?: boolean;
}

/**
 * Mouse event data structure
 *
 * Contains information about mouse events such as clicks and movements.
 * Coordinates are in screen coordinates (pixels).
 * On Linux Wayland, `x`/`y` may be `-99999` (INVALID_COORDINATE) when
 * the coordinate source cannot provide screen positions.
 */
export interface MouseEventData {
  /** X coordinate of mouse pointer (px) */
  x: number;
  /** Y coordinate of mouse pointer (px) */
  y: number;
  /** Mouse button identifier,
   * same as WebAPIs' MouseEvent.button
   * None = -1, Left = 0, Middle = 1, Right = 2, Back = 3, Forward = 4,
   * Unknown = 99
   */
  button: number;
}

/**
 * Mouse wheel event data structure
 *
 * Contains information about mouse wheel events.
 * On Linux Wayland, `x`/`y` may be `-99999` (INVALID_COORDINATE) when
 * the coordinate source cannot provide screen positions.
 */
export interface MouseWheelEventData {
  /** X coordinate of mouse pointer (px) */
  x: number;
  /** Y coordinate of mouse pointer (px) */
  y: number;
  /** Mouse wheel button type
   * 0: Vertical
   * 1: Horizontal
   */
  button: number;
  /** Mouse wheel direction flag
   * 1: Up/Right
   * -1: Down/Left
   */
  flag: number;
}

/**
 * Keyboard event data structure
 *
 * Contains information about keyboard events such as key presses and releases.
 */
export interface KeyboardEventData {
  /**
   * Unified key value of the vkCode. Same as MDN `KeyboardEvent.key` values.
   * Converted from platform-specific vkCode.
   *
   * Values defined in https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values
   */
  uniKey: string;
  /** Virtual key code. The value is different on different platforms.
   *
   * Windows: VK_* values of vkCode, refer to https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes
   * macOS: kVK_* values of kCGKeyboardEventKeycode, defined in `HIToolbox/Events.h`
   * Linux: KEY_* values from `<linux/input-event-codes.h>`, refer to https://github.com/torvalds/linux/blob/master/include/uapi/linux/input-event-codes.h
   */
  vkCode: number;
  /** Whether modifier keys (Alt/Ctrl/Win/⌘/⌥/Fn) are pressed simultaneously */
  sys: boolean;
  /** Keyboard scan code. Windows Only. */
  scanCode?: number;
  /** Additional key flags. Varies on different platforms.
   *
   * Linux: Modifier bitmask — 0x01 Shift, 0x02 Ctrl, 0x04 Alt, 0x08 Meta(Super)
   */
  flags: number;
}

/**
 * Configuration interface for text selection monitoring
 *
 * Contains settings that control the behavior of the text selection hook
 * and its various features like mouse tracking and clipboard fallback.
 */
export interface SelectionConfig {
  /** Enable debug logging for warnings and errors */
  debug?: boolean;
  /** Enable high CPU usage mouse movement tracking */
  enableMouseMoveEvent?: boolean;
  /** Enable clipboard fallback for text selection */
  enableClipboard?: boolean;
  /** Enable passive mode where selection requires manual trigger */
  selectionPassiveMode?: boolean;
  /** Mode for clipboard fallback behavior */
  clipboardMode?: (typeof SelectionHook.FilterMode)[keyof typeof SelectionHook.FilterMode];
  /** Mode for global filter behavior */
  globalFilterMode?: (typeof SelectionHook.FilterMode)[keyof typeof SelectionHook.FilterMode];
  /** List of program names for clipboard mode filtering */
  clipboardFilterList?: string[];
  /** List of program names for global filter mode filtering */
  globalFilterList?: string[];
}

/**
 * Linux environment information returned by linuxGetEnvInfo()
 */
export interface LinuxEnvInfo {
  /** Display protocol: 0=Unknown, 1=X11, 2=Wayland */
  displayProtocol: (typeof SelectionHook.DisplayProtocol)[keyof typeof SelectionHook.DisplayProtocol];
  /** Compositor type: 0=Unknown, 1=KWin, 2=Mutter, 3=Hyprland, 4=Sway, 5=Wlroots, 6=CosmicComp */
  compositorType: (typeof SelectionHook.CompositorType)[keyof typeof SelectionHook.CompositorType];
  /** Whether the user can access input devices (needed for Wayland input monitoring) */
  hasInputDeviceAccess: boolean;
  /** Whether the process is running as root */
  isRoot: boolean;
}

/**
 * SelectionHook - Main class for text selection monitoring
 *
 * This class provides methods to start/stop monitoring text selections
 * across applications on Windows, macOS, and Linux, and emits events when selections occur.
 */
declare class SelectionHook extends EventEmitter {
  static SelectionMethod: {
    NONE: 0;
    UIA: 1;
    /** @deprecated This method has been removed */
    FOCUSCTL: 2;
    ACCESSIBLE: 3;
    AXAPI: 11;
    /** @reserved AT-SPI method is reserved for future use */
    ATSPI: 21;
    PRIMARY: 22;
    CLIPBOARD: 99;
  };

  static PositionLevel: {
    NONE: 0;
    MOUSE_SINGLE: 1;
    MOUSE_DUAL: 2;
    SEL_FULL: 3;
    SEL_DETAILED: 4;
  };

  static FilterMode: {
    DEFAULT: 0;
    INCLUDE_LIST: 1;
    EXCLUDE_LIST: 2;
  };

  static FineTunedListType: {
    EXCLUDE_CLIPBOARD_CURSOR_DETECT: 0;
    INCLUDE_CLIPBOARD_DELAY_READ: 1;
  };

  /**
   * Sentinel value indicating coordinates are unavailable (-99999).
   * Returned when the coordinate source (e.g. libevdev on Wayland) cannot
   * provide actual screen positions. Check coordinate fields against this
   * value before using them for positioning.
   */
  static INVALID_COORDINATE: -99999;

  static DisplayProtocol: {
    UNKNOWN: 0;
    X11: 1;
    WAYLAND: 2;
  };

  /**
   * Compositor type constants (Linux only).
   *
   * Values represent the compositor, not the desktop environment (DE).
   * DE-bundled compositors are detected via XDG_CURRENT_DESKTOP:
   *   KDE Plasma → KWin, GNOME → mutter, COSMIC → cosmic-comp.
   * Standalone compositors are detected via their own env vars:
   *   Hyprland → HYPRLAND_INSTANCE_SIGNATURE, sway → SWAYSOCK.
   * WLROOTS is a catch-all for generic wlroots-based compositors.
   */
  static CompositorType: {
    UNKNOWN: 0;
    /** KWin — KDE Plasma's compositor (kwin_wayland) */
    KWIN: 1;
    /** mutter — GNOME's compositor (mutter / gnome-shell) */
    MUTTER: 2;
    /** Hyprland — standalone tiling compositor */
    HYPRLAND: 3;
    /** sway — standalone i3-compatible compositor */
    SWAY: 4;
    /** wlroots-based compositors (labwc, river, etc.) */
    WLROOTS: 5;
    /** cosmic-comp — System76 COSMIC's compositor */
    COSMIC_COMP: 6;
  };

  /**
   * Start monitoring text selections
   *
   * Initiates the native hooks to listen for text selection events
   * across all applications. This must be called before any events
   * will be emitted.
   *
   * Configuration methods (e.g., enableClipboard, setGlobalFilterMode) can be
   * called before start(). If start() is called with a config object, the config
   * values will override any pre-start settings.
   *
   * @param config Optional configuration object
   * @returns Success status (true if started successfully)
   */
  start(config?: SelectionConfig | null): boolean;

  /**
   * Stop monitoring text selections
   *
   * Stops the native hooks and prevents further events from being emitted.
   * This should be called when monitoring is no longer needed to free resources.
   *
   * @returns Success status (true if stopped successfully or wasn't running)
   */
  stop(): boolean;

  /**
   * Check if hook is running
   *
   * Determines if the selection monitoring is currently active.
   *
   * @returns Running status (true if monitoring is active)
   */
  isRunning(): boolean;

  /**
   * Get current text selection
   *
   * Retrieves the current text selection, if any exists.
   * Returns null if no text is currently selected or hook isn't running.
   *
   * @returns Current selection data or null if no selection exists
   */
  getCurrentSelection(): TextSelectionData | null;

  /**
   * Enable mousemove events (high CPU usage)
   *
   * Enables "mouse-move" events to be emitted when the mouse moves.
   * Note: This can cause high CPU usage due to frequent event firing.
   * Can be called before start().
   *
   * @returns Success status (true if enabled successfully)
   */
  enableMouseMoveEvent(): boolean;

  /**
   * Disable mousemove events
   *
   * Stops emitting "mouse-move" events to reduce CPU usage.
   * This is the default state after starting the hook.
   * Can be called before start().
   *
   * @returns Success status (true if disabled successfully)
   */
  disableMouseMoveEvent(): boolean;

  /**
   * Enable clipboard fallback for text selection
   *
   * Uses Ctrl+C as a last resort to get selected text when other methods fail.
   * This might modify clipboard contents.
   * Can be called before start().
   *
   * @returns Success status (true if enabled successfully)
   */
  enableClipboard(): boolean;

  /**
   * Disable clipboard fallback for text selection
   *
   * Will not use Ctrl+C to get selected text.
   * This preserves clipboard contents.
   * Can be called before start().
   *
   * @returns Success status (true if disabled successfully)
   */
  disableClipboard(): boolean;

  /**
   * Set clipboard mode and program list for text selection
   *
   * Configures how the clipboard fallback mechanism works for different programs.
   * Can be called before start().
   * Mode can be:
   * - DEFAULT: Use clipboard for all programs
   * - INCLUDE_LIST: Only use clipboard for programs in the list
   * - EXCLUDE_LIST: Use clipboard for all programs except those in the list
   *
   * @param {number} mode - Clipboard mode (SelectionHook.ClipboardMode)
   * @param {string[]} programList - Array of program names to include/exclude
   * @returns {boolean} Success status
   */
  setClipboardMode(
    mode: (typeof SelectionHook.FilterMode)[keyof typeof SelectionHook.FilterMode],
    programList?: string[]
  ): boolean;

  /**
   * Set global filter mode for text selection
   *
   * Configures how the global filter mechanism works for different programs.
   * Can be called before start().
   * Mode can be:
   * - DEFAULT: disable global filter
   * - INCLUDE_LIST: Only use global filter for programs in the list
   * - EXCLUDE_LIST: Use global filter for all programs except those in the list
   *
   * @param {number} mode - Filter mode (SelectionHook.FilterMode)
   * @param {string[]} programList - Array of program names to include/exclude
   * @returns {boolean} Success status
   */
  setGlobalFilterMode(
    mode: (typeof SelectionHook.FilterMode)[keyof typeof SelectionHook.FilterMode],
    programList?: string[]
  ): boolean;

  /**
   * Set fine-tuned list for specific behaviors
   *
   * Configures fine-tuned lists for specific application behaviors.
   * Can be called before start().
   * List types:
   * - EXCLUDE_CLIPBOARD_CURSOR_DETECT: Exclude cursor detection for clipboard operations
   * - INCLUDE_CLIPBOARD_DELAY_READ: Include delay when reading clipboard content
   *
   * @param {number} listType - Fine-tuned list type (SelectionHook.FineTunedListType)
   * @param {string[]} programList - Array of program names for the fine-tuned list
   * @returns {boolean} Success status
   */
  setFineTunedList(
    listType: (typeof SelectionHook.FineTunedListType)[keyof typeof SelectionHook.FineTunedListType],
    programList?: string[]
  ): boolean;

  /**
   * Set selection passive mode
   *
   * Can be called before start().
   *
   * @param {boolean} passive - Passive mode
   * @returns {boolean} Success status
   */
  setSelectionPassiveMode(passive: boolean): boolean;

  /**
   * Write text to clipboard
   *
   * Not supported on Linux. Host applications should use their own clipboard API
   * (e.g., Electron clipboard).
   * Can be called before start() (Windows/macOS only).
   *
   * @param {string} text - Text to write to clipboard
   * @returns {boolean} Success status. Always returns false on Linux.
   */
  writeToClipboard(text: string): boolean;

  /**
   * Read text from clipboard
   *
   * Not supported on Linux. Host applications should use their own clipboard API
   * (e.g., Electron clipboard).
   * Can be called before start() (Windows/macOS only).
   *
   * @returns {string|null} Text from clipboard or null if empty or error. Always returns null on Linux.
   */
  readFromClipboard(): string | null;

  /**
   * Check if the process is trusted for accessibility (macOS only)
   *
   * Checks whether the current process has accessibility permissions
   * required for text selection monitoring on macOS.
   * Can be called before start().
   *
   * @returns {boolean} True if the process is trusted for accessibility, false otherwise
   */
  macIsProcessTrusted(): boolean;

  /**
   * Try to request accessibility permissions (macOS only)
   *
   * This MAY show a dialog to the user if permissions are not granted.
   * Can be called before start().
   *
   * @returns {boolean} The current permission status, not the request result
   */
  macRequestProcessTrust(): boolean;

  /**
   * Get Linux environment information (Linux only)
   *
   * Returns an object containing display protocol, compositor type,
   * input device access status, and root status. All values are detected
   * once at construction time and cached.
   * Can be called before start().
   *
   * @returns {LinuxEnvInfo | null} Linux environment info or null on non-Linux
   */
  linuxGetEnvInfo(): LinuxEnvInfo | null;

  /**
   * Release resources
   *
   * Stops monitoring and releases all native resources.
   * Should be called before the application exits to prevent memory leaks.
   */
  cleanup(): void;

  /**
   * Register event listeners
   *
   * The hook emits various events that can be listened for:
   */

  /**
   * Emitted when text is selected in any application
   * @param event The event name
   * @param listener Callback function receiving selection data
   */
  on(event: "text-selection", listener: (data: TextSelectionData) => void): this;

  on(event: "mouse-up", listener: (data: MouseEventData) => void): this;
  on(event: "mouse-down", listener: (data: MouseEventData) => void): this;
  on(event: "mouse-move", listener: (data: MouseEventData) => void): this;
  on(event: "mouse-wheel", listener: (data: MouseWheelEventData) => void): this;

  on(event: "key-down", listener: (data: KeyboardEventData) => void): this;
  on(event: "key-up", listener: (data: KeyboardEventData) => void): this;

  on(event: "status", listener: (status: string) => void): this;
  on(event: "error", listener: (error: Error) => void): this;

  // Same events available with once() for one-time listeners
  once(event: "text-selection", listener: (data: TextSelectionData) => void): this;
  once(event: "mouse-up", listener: (data: MouseEventData) => void): this;
  once(event: "mouse-down", listener: (data: MouseEventData) => void): this;
  once(event: "mouse-move", listener: (data: MouseEventData) => void): this;
  once(event: "mouse-wheel", listener: (data: MouseWheelEventData) => void): this;
  once(event: "key-down", listener: (data: KeyboardEventData) => void): this;
  once(event: "key-up", listener: (data: KeyboardEventData) => void): this;
  once(event: "status", listener: (status: string) => void): this;
  once(event: "error", listener: (error: Error) => void): this;
}

/**
 * Instance type for the SelectionHook class
 */
export type SelectionHookInstance = InstanceType<typeof SelectionHook>;

// LinuxEnvInfo is already exported via its interface declaration above

/**
 * Constructor type for the SelectionHook class
 */
export type SelectionHookConstructor = typeof SelectionHook;

// Export the SelectionHook class
export default SelectionHook;