@followbin/dsh-selection 0.0.0-stage → 0.2.0

package/vendor/selection-hook/index.d.ts

@@ -0,0 +1,517 @@
+/**
+ * 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;