tinky-mouse 0.1.0

package/lib/contexts/MouseContext.js

@@ -0,0 +1,169 @@
+"use strict";
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MouseContext = void 0;
+exports.enableMouseEvents = enableMouseEvents;
+exports.disableMouseEvents = disableMouseEvents;
+exports.MouseProvider = MouseProvider;
+var jsx_runtime_1 = require("react/jsx-runtime");
+var tinky_1 = require("tinky");
+var react_1 = require("react");
+var sequences_js_1 = require("../utils/sequences.js");
+var mouse_js_1 = require("../utils/mouse.js");
+var MAX_MOUSE_BUFFER_SIZE = 4096;
+// ANSI escape sequences for mouse event control
+var ENABLE_MOUSE_SEQUENCES = [
+    "\x1b[?1000h", // Enable basic mouse mode (button press/release)
+    "\x1b[?1002h", // Enable button event tracking (motion while button down)
+    "\x1b[?1003h", // Enable any event tracking (all motion) - optional
+    "\x1b[?1006h", // Enable SGR extended mode (better coordinate reporting)
+];
+var DISABLE_MOUSE_SEQUENCES = [
+    "\x1b[?1006l", // Disable SGR extended mode
+    "\x1b[?1003l", // Disable any event tracking
+    "\x1b[?1002l", // Disable button event tracking
+    "\x1b[?1000l", // Disable basic mouse mode
+];
+/**
+ * Enable mouse event reporting in the terminal.
+ */
+function enableMouseEvents() {
+    var e_1, _a;
+    try {
+        for (var ENABLE_MOUSE_SEQUENCES_1 = __values(ENABLE_MOUSE_SEQUENCES), ENABLE_MOUSE_SEQUENCES_1_1 = ENABLE_MOUSE_SEQUENCES_1.next(); !ENABLE_MOUSE_SEQUENCES_1_1.done; ENABLE_MOUSE_SEQUENCES_1_1 = ENABLE_MOUSE_SEQUENCES_1.next()) {
+            var seq = ENABLE_MOUSE_SEQUENCES_1_1.value;
+            process.stdout.write(seq);
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (ENABLE_MOUSE_SEQUENCES_1_1 && !ENABLE_MOUSE_SEQUENCES_1_1.done && (_a = ENABLE_MOUSE_SEQUENCES_1.return)) _a.call(ENABLE_MOUSE_SEQUENCES_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+}
+/**
+ * Disable mouse event reporting in the terminal.
+ */
+function disableMouseEvents() {
+    var e_2, _a;
+    try {
+        for (var DISABLE_MOUSE_SEQUENCES_1 = __values(DISABLE_MOUSE_SEQUENCES), DISABLE_MOUSE_SEQUENCES_1_1 = DISABLE_MOUSE_SEQUENCES_1.next(); !DISABLE_MOUSE_SEQUENCES_1_1.done; DISABLE_MOUSE_SEQUENCES_1_1 = DISABLE_MOUSE_SEQUENCES_1.next()) {
+            var seq = DISABLE_MOUSE_SEQUENCES_1_1.value;
+            process.stdout.write(seq);
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (DISABLE_MOUSE_SEQUENCES_1_1 && !DISABLE_MOUSE_SEQUENCES_1_1.done && (_a = DISABLE_MOUSE_SEQUENCES_1.return)) _a.call(DISABLE_MOUSE_SEQUENCES_1);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+}
+/**
+ * Context for managing mouse events.
+ */
+exports.MouseContext = (0, react_1.createContext)(undefined);
+/**
+ * Provider component that sets up mouse event listening and distribution.
+ *
+ * It enables mouse reporting on mount (if enabled) and disables it on unmount.
+ * It uses the `tinky` `useStdin` hook to read from the input stream.
+ *
+ * @example
+ * ```tsx
+ * <MouseProvider mouseEventsEnabled={true}>
+ *   <App />
+ * </MouseProvider>
+ * ```
+ *
+ * @param props - The component props.
+ * @param props.children - The child components.
+ * @param props.mouseEventsEnabled - Whether to enable mouse event reporting. Defaults to `false` (implicit).
+ */
+function MouseProvider(_a) {
+    var children = _a.children, mouseEventsEnabled = _a.mouseEventsEnabled;
+    var stdin = (0, tinky_1.useStdin)().stdin;
+    var subscribers = (0, react_1.useRef)(new Set()).current;
+    var subscribe = (0, react_1.useCallback)(function (handler) {
+        subscribers.add(handler);
+    }, [subscribers]);
+    var unsubscribe = (0, react_1.useCallback)(function (handler) {
+        subscribers.delete(handler);
+    }, [subscribers]);
+    (0, react_1.useEffect)(function () {
+        if (!mouseEventsEnabled) {
+            return;
+        }
+        // Enable mouse event reporting in terminal
+        enableMouseEvents();
+        var mouseBuffer = "";
+        var broadcast = function (event) {
+            var e_3, _a;
+            try {
+                for (var subscribers_1 = __values(subscribers), subscribers_1_1 = subscribers_1.next(); !subscribers_1_1.done; subscribers_1_1 = subscribers_1.next()) {
+                    var handler = subscribers_1_1.value;
+                    handler(event);
+                }
+            }
+            catch (e_3_1) { e_3 = { error: e_3_1 }; }
+            finally {
+                try {
+                    if (subscribers_1_1 && !subscribers_1_1.done && (_a = subscribers_1.return)) _a.call(subscribers_1);
+                }
+                finally { if (e_3) throw e_3.error; }
+            }
+        };
+        var handleData = function (data) {
+            mouseBuffer += typeof data === "string" ? data : data.toString("utf-8");
+            // Safety cap to prevent infinite buffer growth on garbage
+            if (mouseBuffer.length > MAX_MOUSE_BUFFER_SIZE) {
+                mouseBuffer = mouseBuffer.slice(-MAX_MOUSE_BUFFER_SIZE);
+            }
+            while (mouseBuffer.length > 0) {
+                var parsed = (0, mouse_js_1.parseMouseEvent)(mouseBuffer);
+                if (parsed) {
+                    broadcast(parsed.event);
+                    mouseBuffer = mouseBuffer.slice(parsed.length);
+                    continue;
+                }
+                if ((0, mouse_js_1.isIncompleteMouseSequence)(mouseBuffer)) {
+                    break; // Wait for more data
+                }
+                // Not a valid sequence at start, and not waiting for more data.
+                // Discard garbage until next possible sequence start.
+                var nextEsc = mouseBuffer.indexOf(sequences_js_1.ESC, 1);
+                if (nextEsc !== -1) {
+                    mouseBuffer = mouseBuffer.slice(nextEsc);
+                    // Loop continues to try parsing at new location
+                }
+                else {
+                    mouseBuffer = "";
+                    break;
+                }
+            }
+        };
+        if (!stdin)
+            return;
+        var stdinStream = stdin;
+        stdinStream.on("data", handleData);
+        return function () {
+            stdinStream.removeListener("data", handleData);
+            // Disable mouse event reporting when unmounting
+            disableMouseEvents();
+        };
+    }, [stdin, mouseEventsEnabled, subscribers]);
+    return ((0, jsx_runtime_1.jsx)(exports.MouseContext.Provider, { value: { subscribe: subscribe, unsubscribe: unsubscribe }, children: children }));
+}

package/lib/hooks/use-mouse-context.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Hook to access the MouseContext.
+ *
+ * Must be used within a `MouseProvider`.
+ *
+ * @returns The mouse context value containing `subscribe` and `unsubscribe` methods.
+ * @throws Error if used outside of a `MouseProvider`.
+ */
+export declare function useMouseContext(): import("../contexts/MouseContext.js").MouseContextValue;

package/lib/hooks/use-mouse-context.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMouseContext = useMouseContext;
+var react_1 = require("react");
+var MouseContext_js_1 = require("../contexts/MouseContext.js");
+/**
+ * Hook to access the MouseContext.
+ *
+ * Must be used within a `MouseProvider`.
+ *
+ * @returns The mouse context value containing `subscribe` and `unsubscribe` methods.
+ * @throws Error if used outside of a `MouseProvider`.
+ */
+function useMouseContext() {
+    var context = (0, react_1.useContext)(MouseContext_js_1.MouseContext);
+    if (!context) {
+        throw new Error("useMouseContext must be used within a MouseProvider");
+    }
+    return context;
+}

package/lib/hooks/use-mouse.d.ts

@@ -0,0 +1,20 @@
+import type { MouseHandler } from "../utils/mouse.js";
+/**
+ * Hook to subscribe to mouse events.
+ *
+ * @param handler - The function to call when a mouse event occurs.
+ * @param options - Configuration options.
+ * @param options.isActive - Whether the subscription is active. Defaults to `true`.
+ *
+ * @example
+ * ```tsx
+ * useMouse((event) => {
+ *   if (event.name === 'left-press') {
+ *     console.log('Clicked at', event.col, event.row);
+ *   }
+ * });
+ * ```
+ */
+export declare function useMouse(handler: MouseHandler, { isActive }?: {
+    isActive?: boolean | undefined;
+}): void;

package/lib/hooks/use-mouse.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMouse = useMouse;
+var react_1 = require("react");
+var use_mouse_context_js_1 = require("./use-mouse-context.js");
+/**
+ * Hook to subscribe to mouse events.
+ *
+ * @param handler - The function to call when a mouse event occurs.
+ * @param options - Configuration options.
+ * @param options.isActive - Whether the subscription is active. Defaults to `true`.
+ *
+ * @example
+ * ```tsx
+ * useMouse((event) => {
+ *   if (event.name === 'left-press') {
+ *     console.log('Clicked at', event.col, event.row);
+ *   }
+ * });
+ * ```
+ */
+function useMouse(handler, _a) {
+    var _b = _a === void 0 ? {} : _a, _c = _b.isActive, isActive = _c === void 0 ? true : _c;
+    var _d = (0, use_mouse_context_js_1.useMouseContext)(), subscribe = _d.subscribe, unsubscribe = _d.unsubscribe;
+    (0, react_1.useEffect)(function () {
+        if (!isActive) {
+            return;
+        }
+        subscribe(handler);
+        return function () { return unsubscribe(handler); };
+    }, [isActive, handler, subscribe, unsubscribe]);
+}

package/lib/hooks/useMouse.d.ts

@@ -0,0 +1,4 @@
+import type { MouseHandler } from "../utils/mouse.js";
+export declare function useMouse(handler: MouseHandler, { isActive }?: {
+    isActive?: boolean | undefined;
+}): void;

package/lib/hooks/useMouse.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMouse = useMouse;
+var react_1 = require("react");
+var useMouseContext_js_1 = require("./useMouseContext.js");
+function useMouse(handler, _a) {
+    var _b = _a === void 0 ? {} : _a, _c = _b.isActive, isActive = _c === void 0 ? true : _c;
+    var _d = (0, useMouseContext_js_1.useMouseContext)(), subscribe = _d.subscribe, unsubscribe = _d.unsubscribe;
+    (0, react_1.useEffect)(function () {
+        if (!isActive) {
+            return;
+        }
+        subscribe(handler);
+        return function () { return unsubscribe(handler); };
+    }, [isActive, handler, subscribe, unsubscribe]);
+}

package/lib/hooks/useMouseContext.d.ts

@@ -0,0 +1 @@
+export declare function useMouseContext(): import("../contexts/MouseContext.js").MouseContextValue;

package/lib/hooks/useMouseContext.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMouseContext = useMouseContext;
+var react_1 = require("react");
+var MouseContext_js_1 = require("../contexts/MouseContext.js");
+function useMouseContext() {
+    var context = (0, react_1.useContext)(MouseContext_js_1.MouseContext);
+    if (!context) {
+        throw new Error("useMouseContext must be used within a MouseProvider");
+    }
+    return context;
+}

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export { MouseProvider, enableMouseEvents, disableMouseEvents, type MouseEvent, type MouseEventName, type MouseHandler, type MouseContextValue, } from "./contexts/MouseContext.js";
+export { useMouseContext } from "./hooks/use-mouse-context.js";
+export { useMouse } from "./hooks/use-mouse.js";

package/lib/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMouse = exports.useMouseContext = exports.disableMouseEvents = exports.enableMouseEvents = exports.MouseProvider = void 0;
+var MouseContext_js_1 = require("./contexts/MouseContext.js");
+Object.defineProperty(exports, "MouseProvider", { enumerable: true, get: function () { return MouseContext_js_1.MouseProvider; } });
+Object.defineProperty(exports, "enableMouseEvents", { enumerable: true, get: function () { return MouseContext_js_1.enableMouseEvents; } });
+Object.defineProperty(exports, "disableMouseEvents", { enumerable: true, get: function () { return MouseContext_js_1.disableMouseEvents; } });
+var use_mouse_context_js_1 = require("./hooks/use-mouse-context.js");
+Object.defineProperty(exports, "useMouseContext", { enumerable: true, get: function () { return use_mouse_context_js_1.useMouseContext; } });
+var use_mouse_js_1 = require("./hooks/use-mouse.js");
+Object.defineProperty(exports, "useMouse", { enumerable: true, get: function () { return use_mouse_js_1.useMouse; } });

package/lib/utils/events.d.ts

@@ -0,0 +1,17 @@
+import { EventEmitter } from "node:events";
+export declare enum AppEvent {
+    OpenDebugConsole = "open-debug-console",
+    OauthDisplayMessage = "oauth-display-message",
+    Flicker = "flicker",
+    McpClientUpdate = "mcp-client-update",
+    SelectionWarning = "selection-warning",
+    PasteTimeout = "paste-timeout"
+}
+export interface AppEvents {
+    [AppEvent.OpenDebugConsole]: never[];
+    [AppEvent.OauthDisplayMessage]: string[];
+    [AppEvent.Flicker]: never[];
+    [AppEvent.SelectionWarning]: never[];
+    [AppEvent.PasteTimeout]: never[];
+}
+export declare const appEvents: EventEmitter<AppEvents>;

package/lib/utils/events.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appEvents = exports.AppEvent = void 0;
+var node_events_1 = require("node:events");
+var AppEvent;
+(function (AppEvent) {
+    AppEvent["OpenDebugConsole"] = "open-debug-console";
+    AppEvent["OauthDisplayMessage"] = "oauth-display-message";
+    AppEvent["Flicker"] = "flicker";
+    AppEvent["McpClientUpdate"] = "mcp-client-update";
+    AppEvent["SelectionWarning"] = "selection-warning";
+    AppEvent["PasteTimeout"] = "paste-timeout";
+})(AppEvent || (exports.AppEvent = AppEvent = {}));
+exports.appEvents = new node_events_1.EventEmitter();

package/lib/utils/input.d.ts

@@ -0,0 +1,12 @@
+export declare const ESC = "\u001B";
+export declare const SGR_EVENT_PREFIX = "\u001B[<";
+export declare const X11_EVENT_PREFIX = "\u001B[M";
+export declare const SGR_MOUSE_REGEX: RegExp;
+export declare const X11_MOUSE_REGEX: RegExp;
+export declare function couldBeSGRMouseSequence(buffer: string): boolean;
+export declare function couldBeMouseSequence(buffer: string): boolean;
+/**
+ * Checks if the buffer *starts* with a complete mouse sequence.
+ * Returns the length of the sequence if matched, or 0 if not.
+ */
+export declare function getMouseSequenceLength(buffer: string): number;

package/lib/utils/input.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X11_MOUSE_REGEX = exports.SGR_MOUSE_REGEX = exports.X11_EVENT_PREFIX = exports.SGR_EVENT_PREFIX = exports.ESC = void 0;
+exports.couldBeSGRMouseSequence = couldBeSGRMouseSequence;
+exports.couldBeMouseSequence = couldBeMouseSequence;
+exports.getMouseSequenceLength = getMouseSequenceLength;
+exports.ESC = "\u001B";
+exports.SGR_EVENT_PREFIX = "".concat(exports.ESC, "[<");
+exports.X11_EVENT_PREFIX = "".concat(exports.ESC, "[M");
+// eslint-disable-next-line no-control-regex
+exports.SGR_MOUSE_REGEX = /^\x1b\[<(\d+);(\d+);(\d+)([mM])/; // SGR mouse events
+// X11 is ESC [ M followed by 3 bytes.
+// eslint-disable-next-line no-control-regex
+exports.X11_MOUSE_REGEX = /^\x1b\[M([\s\S]{3})/;
+function couldBeSGRMouseSequence(buffer) {
+    if (buffer.length === 0)
+        return true;
+    // Check if buffer is a prefix of a mouse sequence starter
+    if (exports.SGR_EVENT_PREFIX.startsWith(buffer))
+        return true;
+    // Check if buffer is a mouse sequence prefix
+    if (buffer.startsWith(exports.SGR_EVENT_PREFIX))
+        return true;
+    return false;
+}
+function couldBeMouseSequence(buffer) {
+    if (buffer.length === 0)
+        return true;
+    // Check SGR prefix
+    if (exports.SGR_EVENT_PREFIX.startsWith(buffer) ||
+        buffer.startsWith(exports.SGR_EVENT_PREFIX))
+        return true;
+    // Check X11 prefix
+    if (exports.X11_EVENT_PREFIX.startsWith(buffer) ||
+        buffer.startsWith(exports.X11_EVENT_PREFIX))
+        return true;
+    return false;
+}
+/**
+ * Checks if the buffer *starts* with a complete mouse sequence.
+ * Returns the length of the sequence if matched, or 0 if not.
+ */
+function getMouseSequenceLength(buffer) {
+    var sgrMatch = buffer.match(exports.SGR_MOUSE_REGEX);
+    if (sgrMatch)
+        return sgrMatch[0].length;
+    var x11Match = buffer.match(exports.X11_MOUSE_REGEX);
+    if (x11Match)
+        return x11Match[0].length;
+    return 0;
+}

package/lib/utils/mouse.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Represents the type of mouse event.
+ *
+ * - `*-press`: Mouse button pressed.
+ * - `*-release`: Mouse button released.
+ * - `scroll-*`: Scroll wheel action.
+ * - `move`: Mouse movement (requires tracking enabled).
+ */
+export type MouseEventName = "left-press" | "left-release" | "right-press" | "right-release" | "middle-press" | "middle-release" | "scroll-up" | "scroll-down" | "scroll-left" | "scroll-right" | "move";
+/**
+ * Structure representing a parsed mouse event.
+ */
+export interface MouseEvent {
+    /** The name/type of the event. */
+    name: MouseEventName;
+    /** zero-based column/x-coordinate. */
+    col: number;
+    /** zero-based row/y-coordinate. */
+    row: number;
+    /** Whether the Shift key was held. */
+    shift: boolean;
+    /** Whether the Meta/Alt key was held. */
+    meta: boolean;
+    /** Whether the Ctrl key was held. */
+    ctrl: boolean;
+    /** The specific button involved in the event. */
+    button: "left" | "middle" | "right" | "none";
+}
+/**
+ * Function signature for handling mouse events.
+ * @param event - The parsed mouse event.
+ * @returns `boolean` or `undefined`. If it returns `true`, it might indicate the event was handled (depending on consumer logic), but commonly used for side effects.
+ */
+export type MouseHandler = (event: MouseEvent) => boolean | undefined;
+/**
+ * Derives the `MouseEventName` from the SGR button code and release state.
+ *
+ * @param buttonCode - The numerical code from the SGR sequence.
+ * @param isRelease - Whether the event is a release event (last char is 'm').
+ * @returns The `MouseEventName` or `null` if unknown.
+ */
+export declare function getMouseEventName(buttonCode: number, isRelease: boolean): MouseEventName | null;
+/**
+ * Parses an SGR (1006) mouse sequence.
+ *
+ * @param buffer - The input string containing the sequence.
+ * @returns An object containing the parsed event and the length of the matched sequence, or `null` if not an SGR sequence.
+ *
+ * @example
+ * ```ts
+ * parseSGRMouseEvent("\x1b[<0;10;10M"); // Left press at 10,10
+ * ```
+ */
+export declare function parseSGRMouseEvent(buffer: string): {
+    event: MouseEvent;
+    length: number;
+} | null;
+/**
+ * Parses an X11 mouse sequence.
+ *
+ * @param buffer - The input string containing the sequence.
+ * @returns An object containing the parsed event and the length of the matched sequence, or `null` if not an X11 sequence.
+ *
+ * @example
+ * ```ts
+ * parseX11MouseEvent("\x1b[M..."); // Parsed X11 event
+ * ```
+ */
+export declare function parseX11MouseEvent(buffer: string): {
+    event: MouseEvent;
+    length: number;
+} | null;
+/**
+ * Attempts to parse a mouse event from the buffer, trying both SGR and X11 formats.
+ *
+ * @param buffer - The input string.
+ * @returns The parsed event and length, or `null`.
+ */
+export declare function parseMouseEvent(buffer: string): {
+    event: MouseEvent;
+    length: number;
+} | null;
+/**
+ * Checks if the buffer contains an incomplete mouse sequence.
+ * This is useful for knowing if we should wait for more data before processing.
+ *
+ * @param buffer - The input string.
+ * @returns `true` if the buffer looks like the start of a mouse sequence but is incomplete.
+ */
+export declare function isIncompleteMouseSequence(buffer: string): boolean;