@tobq/boardclip 0.0.0-stage → 2.1.107

package/lib/windows-hook-worker.js

@@ -0,0 +1,236 @@
+'use strict';
+// Worker thread running a Win32 low-level keyboard hook (WH_KEYBOARD_LL).
+//
+// This exists because Electron's `globalShortcut.register('Super+V')` fails
+// on Windows — Windows Clipboard History has already claimed Win+V via the
+// built-in RegisterHotKey API. A low-level hook sits *below* that system
+// shortcut layer and can swallow the key before Windows Clipboard History
+// sees it.
+//
+// Why a worker thread (not Electron's main thread):
+//   1. LL hooks are called via messages posted to the installing thread, so
+//      that thread must pump its own GetMessage loop. Electron's main thread
+//      has a Chromium message pump that doesn't guarantee LL hook delivery
+//      and can starve it under load.
+//   2. LowLevelHooksTimeout defaults to 300ms — if any JS task on the main
+//      thread runs longer, Windows silently unregisters the hook. Isolating
+//      it in a worker with a dedicated GetMessage loop removes that risk.
+//
+// State sharing with main thread uses a SharedArrayBuffer rather than
+// postMessage because the worker is blocked in a synchronous GetMessageW
+// call and can't process its JS event loop.
+
+const { parentPort, workerData } = require('worker_threads');
+const koffi = require('koffi');
+
+// --- Shared state (worker reads, main writes) ---
+// Layout: [popupVisible, slot1, slot2, ..., slot9, reserved, ...]
+const sharedState = workerData && workerData.sharedStateBuffer
+  ? new Uint8Array(workerData.sharedStateBuffer)
+  : new Uint8Array(16);
+
+// --- Win32 constants ---
+const WH_KEYBOARD_LL = 13;
+const WM_KEYDOWN = 0x0100;
+const WM_KEYUP = 0x0101;
+const WM_SYSKEYDOWN = 0x0104;
+const WM_SYSKEYUP = 0x0105;
+const VK_LWIN = 0x5B;
+const VK_RWIN = 0x5C;
+const VK_CONTROL = 0x11;
+const VK_V = 0x56;
+const VK_NUMPAD1 = 0x61;
+const VK_NUMPAD9 = 0x69;
+const KEYEVENTF_KEYUP = 0x0002;
+
+// --- koffi types ---
+// KBDLLHOOKSTRUCT is the struct Windows passes to a WH_KEYBOARD_LL hook via
+// lParam. We declare it so koffi can decode the pointer in the callback.
+const KBDLLHOOKSTRUCT = koffi.struct('KBDLLHOOKSTRUCT', {
+  vkCode: 'uint32',
+  scanCode: 'uint32',
+  flags: 'uint32',
+  time: 'uint32',
+  dwExtraInfo: 'uintptr_t',
+});
+
+// MSG is needed for the GetMessageW pump loop below.
+const MSG = koffi.struct('MSG', {
+  hwnd: 'void *',
+  message: 'uint32',
+  wParam: 'uintptr_t',
+  lParam: 'intptr_t',
+  time: 'uint32',
+  pt_x: 'int32',
+  pt_y: 'int32',
+  lPrivate: 'uint32',
+});
+
+// Hook procedure prototype. Declaring lParam as KBDLLHOOKSTRUCT* means koffi
+// gives us an External we can both decode *and* pass straight back through
+// to CallNextHookEx without reinterpreting the pointer ourselves.
+const HookProc = koffi.proto(
+  'intptr_t __stdcall HookProc(int nCode, uintptr_t wParam, KBDLLHOOKSTRUCT *lParam)'
+);
+
+// --- Load user32.dll and bind functions ---
+let user32;
+try {
+  user32 = koffi.load('user32.dll');
+} catch (err) {
+  parentPort.postMessage({ type: 'error', error: 'koffi.load user32.dll: ' + String(err) });
+  process.exit(1);
+}
+
+const SetWindowsHookExW = user32.func(
+  'void * __stdcall SetWindowsHookExW(int idHook, HookProc *lpfn, void *hmod, uint32 dwThreadId)'
+);
+const UnhookWindowsHookEx = user32.func(
+  'int __stdcall UnhookWindowsHookEx(void *hhk)'
+);
+const CallNextHookEx = user32.func(
+  'intptr_t __stdcall CallNextHookEx(void *hhk, int nCode, uintptr_t wParam, KBDLLHOOKSTRUCT *lParam)'
+);
+const GetMessageW = user32.func(
+  'int __stdcall GetMessageW(_Out_ MSG *lpMsg, void *hWnd, uint32 wMsgFilterMin, uint32 wMsgFilterMax)'
+);
+const TranslateMessage = user32.func(
+  'int __stdcall TranslateMessage(MSG *lpMsg)'
+);
+const DispatchMessageW = user32.func(
+  'intptr_t __stdcall DispatchMessageW(MSG *lpMsg)'
+);
+const GetAsyncKeyState = user32.func(
+  'int16 __stdcall GetAsyncKeyState(int vKey)'
+);
+const keybd_event = user32.func(
+  'void __stdcall keybd_event(uint8 bVk, uint8 bScan, uint32 dwFlags, uintptr_t dwExtraInfo)'
+);
+
+let winVChordActive = false;
+let winVChordConsumed = false;
+
+// Auto-repeat suppression for numpad quick-paste. When a key is physically
+// held, Windows emits repeated WM_KEYDOWN with no intervening WM_KEYUP. Without
+// tracking this, one held (or lag-stretched) press fires the paste many times.
+// numpadHeld = keys currently down; numpadIntercepted = keys whose keydown we
+// swallowed, so we also swallow their paired keyup.
+const numpadHeld = new Set();
+const numpadIntercepted = new Set();
+
+function isWinHeld() {
+  return (GetAsyncKeyState(VK_LWIN) & 0x8000) !== 0 ||
+         (GetAsyncKeyState(VK_RWIN) & 0x8000) !== 0;
+}
+
+function markWinKeyUsed() {
+  // If V is swallowed, Windows can still react to the original Win release.
+  // A tiny Ctrl tap marks the Win key as used while allowing the real Win-up
+  // through, so we avoid both Clipboard History and stuck modifier state.
+  try {
+    keybd_event(VK_CONTROL, 0, 0, 0);
+    keybd_event(VK_CONTROL, 0, KEYEVENTF_KEYUP, 0);
+  } catch {}
+}
+
+// --- Hook callback ---
+// Fires synchronously on this worker thread each time a keyboard event is
+// delivered to the thread's message queue. Return non-zero to swallow the
+// event (it will not propagate to the rest of the hook chain or any app).
+const hookCallback = koffi.register((nCode, wParam, lParamExt) => {
+  try {
+    if (nCode >= 0) {
+      const kb = koffi.decode(lParamExt, KBDLLHOOKSTRUCT);
+      const vk = kb.vkCode;
+      const keyDown = wParam === WM_KEYDOWN || wParam === WM_SYSKEYDOWN;
+      const keyUp = wParam === WM_KEYUP || wParam === WM_SYSKEYUP;
+
+      if (!keyDown && !keyUp) {
+        return CallNextHookEx(null, nCode, wParam, lParamExt);
+      }
+
+      const isWinKey = vk === VK_LWIN || vk === VK_RWIN;
+
+      // Win+V → show popup. Checked before Windows Clipboard History can.
+      if (isWinKey && keyUp && winVChordConsumed) {
+        markWinKeyUsed();
+        winVChordConsumed = false;
+      }
+
+      if (vk === VK_V) {
+        if (keyDown) {
+          if (isWinHeld() || winVChordActive) {
+            if (!winVChordActive) {
+              winVChordActive = true;
+              winVChordConsumed = true;
+              parentPort.postMessage({ type: 'show' });
+            }
+            return 1;
+          }
+        } else if (winVChordActive) {
+          winVChordActive = false;
+          return 1;
+        }
+      }
+
+      // Plain Numpad1-9 -> quick-paste when a slot is assigned and the popup
+      // is closed. When the popup is visible, pass through so the search box
+      // can accept normal numpad typing. Auto-repeat (held key) fires the paste
+      // exactly once — repeats are swallowed but not re-dispatched.
+      if (vk >= VK_NUMPAD1 && vk <= VK_NUMPAD9) {
+        const slot = vk - VK_NUMPAD1 + 1;
+        if (keyDown) {
+          const popupVisible = sharedState[0] === 1;
+          const slotAssigned = sharedState[slot] === 1;
+          if (!popupVisible && slotAssigned) {
+            if (numpadHeld.has(vk)) return 1; // auto-repeat: swallow, don't re-fire
+            numpadHeld.add(vk);
+            numpadIntercepted.add(vk);
+            parentPort.postMessage({ type: 'numpad', slot });
+            return 1;
+          }
+          // Not intercepting this press (popup open or slot unassigned): let it
+          // type normally and don't track it.
+        } else if (keyUp) {
+          numpadHeld.delete(vk);
+          if (numpadIntercepted.has(vk)) {
+            numpadIntercepted.delete(vk);
+            return 1; // swallow the keyup paired with a swallowed keydown
+          }
+        }
+      }
+    }
+  } catch (err) {
+    // Never let JS exceptions escape the hook — Windows will stall the
+    // whole keyboard chain. Best-effort report and fall through to
+    // CallNextHookEx so the key still reaches its target.
+    try { parentPort.postMessage({ type: 'error', error: String(err) }); } catch {}
+  }
+  return CallNextHookEx(null, nCode, wParam, lParamExt);
+}, koffi.pointer(HookProc));
+
+// --- Install hook ---
+// hMod=null + dwThreadId=0 → install a global LL hook owned by the current
+// process. LL hooks are the one case where a null hMod is explicitly allowed.
+const hook = SetWindowsHookExW(WH_KEYBOARD_LL, hookCallback, null, 0);
+if (!hook) {
+  parentPort.postMessage({ type: 'error', error: 'SetWindowsHookExW returned null' });
+  process.exit(1);
+}
+
+parentPort.postMessage({ type: 'ready' });
+
+// --- Message pump ---
+// Blocks this worker thread pumping messages so Windows can deliver hook
+// callbacks. Exits on WM_QUIT or worker termination from the main thread.
+const msg = {};
+while (true) {
+  const ret = GetMessageW(msg, null, 0, 0);
+  if (ret <= 0) break;
+  TranslateMessage(msg);
+  DispatchMessageW(msg);
+}
+
+// --- Cleanup (only reached on clean WM_QUIT; worker.terminate skips this) ---
+try { UnhookWindowsHookEx(hook); } catch {}
+try { koffi.unregister(hookCallback); } catch {}

package/lib/windows-hook.js

@@ -0,0 +1,91 @@
+'use strict';
+// Main-thread wrapper around the Win32 keyboard hook worker.
+//
+// On Windows we can't use Electron's `globalShortcut.register('Super+V')`
+// because Windows Clipboard History owns Win+V at the RegisterHotKey layer
+// and silently rejects our registration. This module installs a
+// WH_KEYBOARD_LL hook on a dedicated worker thread which intercepts Win+V
+// and numpad keys *before* Windows Clipboard History sees them.
+//
+// See lib/windows-hook-worker.js for the hook implementation and the
+// rationale for running it in a worker.
+//
+// Shared state (popup visible + which numpad slots are assigned) is passed
+// via a SharedArrayBuffer because the worker is synchronously blocked in
+// GetMessageW and can't process postMessage events from its JS event loop.
+
+const { Worker } = require('worker_threads');
+const path = require('path');
+
+let currentHook = null;
+
+function install({ onShowPopup, onNumpadPaste }) {
+  if (process.platform !== 'win32') {
+    // Non-Windows platforms use Electron's globalShortcut; no-op API here.
+    return {
+      setPopupVisible() {},
+      setSlotAssignments() {},
+      uninstall() {},
+    };
+  }
+  if (currentHook) return currentHook;
+
+  // Layout: [popupVisible, slot1, slot2, ..., slot9, reserved...]
+  const sharedStateBuffer = new SharedArrayBuffer(16);
+  const sharedState = new Uint8Array(sharedStateBuffer);
+
+  const worker = new Worker(path.join(__dirname, 'windows-hook-worker.js'), {
+    workerData: { sharedStateBuffer },
+  });
+
+  worker.on('message', (msg) => {
+    switch (msg.type) {
+      case 'show':
+        try { onShowPopup(); } catch (e) { console.error('[windows-hook] onShowPopup:', e); }
+        break;
+      case 'numpad':
+        try { onNumpadPaste(msg.slot); } catch (e) { console.error('[windows-hook] onNumpadPaste:', e); }
+        break;
+      case 'ready':
+        // Hook installed successfully — no action needed.
+        break;
+      case 'error':
+        console.error('[windows-hook]', msg.error);
+        break;
+    }
+  });
+
+  worker.on('error', (err) => {
+    console.error('[windows-hook] worker crashed:', err);
+    currentHook = null;
+  });
+
+  worker.on('exit', (code) => {
+    if (code !== 0) console.error(`[windows-hook] worker exited with code ${code}`);
+    currentHook = null;
+  });
+
+  currentHook = {
+    setPopupVisible(visible) {
+      sharedState[0] = visible ? 1 : 0;
+    },
+    setSlotAssignments(assignedSet) {
+      // assignedSet: Set<number> of assigned numpad slot numbers (1-9)
+      for (let n = 1; n <= 9; n++) {
+        sharedState[n] = assignedSet && assignedSet.has(n) ? 1 : 0;
+      }
+    },
+    uninstall() {
+      if (!currentHook) return;
+      currentHook = null;
+      // worker.terminate() kills the thread; Windows reclaims the hook on
+      // thread exit. A cleaner PostThreadMessageW(WM_QUIT) would require
+      // exposing the worker thread ID — not worth the extra FFI surface.
+      worker.terminate().catch(() => {});
+    },
+  };
+
+  return currentHook;
+}
+
+module.exports = { install };

package/lib/windows-paste.js

@@ -0,0 +1,185 @@
+'use strict';
+// Fast Windows paste primitives via koffi FFI.
+//
+// Replaces the previous `cscript` + VBScript SendKeys approach which had two
+// problems:
+//   1. Spawning cscript per paste costs 200-500ms (cold start). That was the
+//      "delay" users noticed vs. the pre-Electron Python version which used
+//      direct Win32 calls via ctypes.
+//   2. VBScript `WshShell.SendKeys "^v"` has a documented Win32 quirk where
+//      it can flip NumLock state on some systems, triggering OEM keyboard
+//      software notifications (e.g. Logitech "NumLock ON" overlay).
+//
+// Uses SendInput (the modern Win32 API recommended for new code — see
+// https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-sendinput).
+// Benefits over the older keybd_event:
+//   - Events are atomic: other input from the user or from other processes
+//     cannot be interleaved between our Ctrl down / V down / V up / Ctrl up.
+//   - Microsoft explicitly flags keybd_event as superseded for new dev.
+//
+// The INPUT struct uses a tagged union in C. We target x64 (the only arch
+// Electron ships by default on Windows) and use a flat struct with explicit
+// padding that matches the x64 memory layout (40 bytes total).
+
+if (process.platform !== 'win32') {
+  module.exports = {
+    sendCtrlV() {},
+    typeText() { return { ok: false, chars: 0, events: 0 }; },
+    getForegroundWindow() { return null; },
+    getForegroundWindowAddress() { return '0'; },
+    setForegroundWindow() { return false; },
+    isMouseButtonDown() { return false; },
+  };
+  return;
+}
+
+const koffi = require('koffi');
+const user32 = koffi.load('user32.dll');
+
+// x64 INPUT struct layout (40 bytes):
+//   offset 0:  type      (DWORD, 4)
+//   offset 4:  padding   (4)      — union aligns to 8 (ULONG_PTR alignment)
+//   offset 8:  wVk       (WORD, 2)
+//   offset 10: wScan     (WORD, 2)
+//   offset 12: dwFlags   (DWORD, 4)
+//   offset 16: time      (DWORD, 4)
+//   offset 20: padding   (4)      — align dwExtraInfo to 8
+//   offset 24: dwExtraInfo (ULONG_PTR, 8)
+//   offset 32: padding   (8)      — pad to 40, matching MOUSEINPUT's size
+const INPUT = koffi.struct('INPUT', {
+  type: 'uint32',
+  _pad0: 'uint32',
+  wVk: 'uint16',
+  wScan: 'uint16',
+  dwFlags: 'uint32',
+  time: 'uint32',
+  _pad1: 'uint32',
+  dwExtraInfo: 'uintptr_t',
+  _pad2: koffi.array('uint8', 8),
+});
+
+const INPUT_KEYBOARD = 1;
+const VK_CONTROL = 0x11;
+const VK_V = 0x56;
+const VK_RETURN = 0x0D;
+const VK_TAB = 0x09;
+const VK_LBUTTON = 0x01;
+const VK_RBUTTON = 0x02;
+const KEYEVENTF_KEYUP = 0x0002;
+const KEYEVENTF_UNICODE = 0x0004;
+
+const SendInput = user32.func(
+  'uint32 __stdcall SendInput(uint32 cInputs, INPUT *pInputs, int cbSize)'
+);
+const GetForegroundWindow = user32.func(
+  'void * __stdcall GetForegroundWindow()'
+);
+const SetForegroundWindow = user32.func(
+  'int __stdcall SetForegroundWindow(void *hWnd)'
+);
+const GetAsyncKeyState = user32.func(
+  'int16 __stdcall GetAsyncKeyState(int vKey)'
+);
+
+const INPUT_SIZE = koffi.sizeof(INPUT);
+
+function keyInput(vk, keyup) {
+  return {
+    type: INPUT_KEYBOARD,
+    _pad0: 0,
+    wVk: vk,
+    wScan: 0,
+    dwFlags: keyup ? KEYEVENTF_KEYUP : 0,
+    time: 0,
+    _pad1: 0,
+    dwExtraInfo: 0,
+    _pad2: [0, 0, 0, 0, 0, 0, 0, 0],
+  };
+}
+
+function sendCtrlV() {
+  // Four events delivered atomically: Ctrl down, V down, V up, Ctrl up.
+  SendInput(4, [
+    keyInput(VK_CONTROL, false),
+    keyInput(VK_V, false),
+    keyInput(VK_V, true),
+    keyInput(VK_CONTROL, true),
+  ], INPUT_SIZE);
+}
+
+// A single Unicode character injected via KEYEVENTF_UNICODE — inserts the exact
+// codepoint as text, with no virtual-key mapping, so it is immune to keyboard
+// layout AND to Tab/Enter "action" semantics (a literal tab/space is inserted,
+// not a focus change). wVk MUST be 0 for unicode injection.
+function unicodeInput(codeUnit, keyup) {
+  return {
+    type: INPUT_KEYBOARD,
+    _pad0: 0,
+    wVk: 0,
+    wScan: codeUnit,
+    dwFlags: KEYEVENTF_UNICODE | (keyup ? KEYEVENTF_KEYUP : 0),
+    time: 0,
+    _pad1: 0,
+    dwExtraInfo: 0,
+    _pad2: [0, 0, 0, 0, 0, 0, 0, 0],
+  };
+}
+
+// Type text by synthesizing key events — bypassing the clipboard entirely, so
+// there is no backup/restore race and the user's clipboard is never touched.
+// The whole string is delivered in as few SendInput batches as possible (NOT
+// one key at a time with delays), so it is effectively instant.
+//
+// Newlines are sent as a real VK_RETURN keypress (KEYEVENTF_UNICODE '\n' does
+// not produce a newline in most apps). Everything else — including tab — goes
+// through Unicode injection so a snippet's exact characters are inserted without
+// triggering Tab-key focus behavior. Returns {ok, chars, events}.
+function typeText(text) {
+  const str = String(text == null ? '' : text);
+  if (!str) return { ok: true, chars: 0, events: 0 };
+  const events = [];
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i);
+    if (code === 0x0d) continue;               // swallow CR; LF drives the newline
+    if (code === 0x0a) {                        // LF -> real Enter keypress
+      events.push(keyInput(VK_RETURN, false));
+      events.push(keyInput(VK_RETURN, true));
+      continue;
+    }
+    events.push(unicodeInput(code, false));
+    events.push(unicodeInput(code, true));
+  }
+  if (!events.length) return { ok: true, chars: str.length, events: 0 };
+  // Chunk so a single very large array can't overflow the input pipeline; each
+  // SendInput call is atomic and there is no inter-key delay, so this stays fast.
+  const CHUNK = 400;
+  let sent = 0;
+  for (let i = 0; i < events.length; i += CHUNK) {
+    const batch = events.slice(i, i + CHUNK);
+    sent += SendInput(batch.length, batch, INPUT_SIZE);
+  }
+  return { ok: sent === events.length, chars: str.length, events: events.length, sent };
+}
+
+function getForegroundWindow() {
+  return GetForegroundWindow();
+}
+
+// Numeric address of the current foreground window, as a string (HWNDs can
+// exceed Number range on x64). Used by tests to confirm the intended window is
+// focused before injecting keystrokes, so injection can't leak into another app.
+function getForegroundWindowAddress() {
+  try { return String(koffi.address(GetForegroundWindow())); } catch { return '0'; }
+}
+
+// -> true when Windows accepted the switch.
+function setForegroundWindow(hwnd) {
+  if (!hwnd) return false;
+  return !!SetForegroundWindow(hwnd);
+}
+
+function isMouseButtonDown() {
+  return !!((GetAsyncKeyState(VK_LBUTTON) | GetAsyncKeyState(VK_RBUTTON)) & 0x8000);
+}
+
+module.exports = { sendCtrlV, typeText, getForegroundWindow, getForegroundWindowAddress, setForegroundWindow, isMouseButtonDown };