@mintplex-labs/tab-complete

Native addon for system-wide autocomplete on macOS and Windows. Detects the active text field, tracks caret position, hooks keyboard events, and inserts completion text — via the macOS Accessibility/CoreGraphics APIs and Windows UI Automation/Win32.

Linux is not supported. Importing on an unsupported platform returns a safe no-op module (every function is callable but does nothing).

Supported Platforms

| Platform | Architectures | Status | |----------|--------------|--------| | macOS (darwin) | arm64, x64 | Stable | | Windows (win32) | arm64, x64 | Stable | | Linux | — | Not supported (no-op) |

Installation

Install as a dependency in the consuming repo:

yarn add @mintplex-labs/tab-complete

The package ships with prebuilt binaries in prebuilds/. No compilation is required at install time. The client (index.js) loads the correct binary for the current platform and architecture automatically.

Building from Source

These commands are only needed when developing this package itself:

# macOS — builds Swift dylib + node-gyp addon → dist/
yarn build

# Windows — builds node-gyp addon (auto-detects Electron) → dist/
yarn build:windows

# macOS production — builds + copies artifacts to prebuilds/ for committing
yarn build:prod:mac

Prebuild Workflow

Since Windows on ARM does not have CI runners, prebuilds are committed to the repo:

1. Run yarn build:prod:mac on each Mac architecture (arm64 and x64)
2. Build on Windows and copy dist/tab_complete.node to prebuilds/win32-x64/ and prebuilds/win32-arm64/
3. Commit the prebuilds/ directory

Consumers get the prebuilt binary at require-time with zero build steps.

Architecture

macOS — Three-layer bridge (Swift → C → N-API)

┌─────────────────────────────────────────────────────┐
│  JavaScript (Electron main process)                 │
│  require('@mintplex-labs/tab-complete')              │
└──────────────────────┬──────────────────────────────┘
                       │ N-API calls
┌──────────────────────▼──────────────────────────────┐
│  addon.cc (C++ N-API module)                        │
│  - Loads libTabComplete.dylib via rpath             │
│  - Wraps C bridge functions as napi_value exports   │
│  - Thread-safe functions for async callbacks        │
└──────────────────────┬──────────────────────────────┘
                       │ C function calls
┌──────────────────────▼──────────────────────────────┐
│  Bridge.swift (@_cdecl → C linkage)                 │
│  - tc_start_focus_polling, tc_start_keyboard_hook…  │
│  - Marshals Swift types to C structs                │
└──────────────────────┬──────────────────────────────┘
                       │ Swift method calls
┌──────────────────────▼──────────────────────────────┐
│  Swift implementation                               │
│  AXHelper · FocusResolver · KeyboardHook ·          │
│  TextInserter · TabCompleteAddon                    │
└─────────────────────────────────────────────────────┘

Windows — Direct C++ N-API module

On Windows there is no Swift layer. The native addon (tab_complete.node) is compiled directly from C++ sources in windows/ that call Win32 and COM APIs:

| Capability | Implementation | |---|---| | Focus tracking | IUIAutomation + ITextPattern via COM | | Caret geometry | ITextRange::GetBoundingRectangles / GetCaretPos + ClientToScreen | | Keyboard hook | SetWindowsHookEx with WH_KEYBOARD_LL | | Text insertion | SendInput with KEYEVENTF_UNICODE | | Permission check | Always returns true (no permission gate on Windows) |

API Surface

All functions are synchronous unless noted:

| Function | Description | |----------|-------------| | isAccessibilityTrusted() | Returns whether the process has Accessibility permission (always true on Windows) | | startFocusPolling(intervalMs?) | Begins polling for the focused text field | | stopFocusPolling() | Stops the polling timer | | startKeyboardHook() | Installs a global keyboard hook for key-down events | | stopKeyboardHook() | Removes the keyboard hook | | setConsumeKeys(consume) | When true, key events are swallowed before reaching the host app | | onFocusChange(callback) | Registers a callback for focus context changes (async via TSFN) | | onKeyDown(callback) | Registers a callback for key-down events (async via TSFN) | | insertText(text) | Types text into the focused field via synthetic events | | refreshFocusNow() | Immediate focus capture outside the polling cadence | | setIgnoredBundleIdentifier(id) | Skip self-process AX queries (bundle ID on macOS, exe name on Windows) |

Key Design Decisions

Swift dylib + C bridge (macOS) — SPM produces frameworks that are awkward to load from N-API. A plain dylib with @_cdecl exports gives direct access with zero framework overhead.

Synchronous key consumption — The event tap/hook callback must return synchronously. Since the JS callback is async (thread-safe function), Tab consumption is based on the consumeKeys flag which JS sets ahead of time when a suggestion is visible.

Coordinate flipping (macOS) — The Accessibility API uses CoreGraphics coordinates (Y=0 at top-left). Bridge.swift converts to screen coordinates (Y=0 at top) for Electron's BrowserWindow.setPosition.

Text insertion chunking (macOS) — CGEvent.keyboardSetUnicodeString truncates beyond 20 UTF-16 units. TextInserter splits text into chunks.

Prebuilds over postinstall — Native binaries are committed in prebuilds/ and loaded at require-time. No compilation step runs during yarn install, avoiding build toolchain requirements for consumers and working around missing CI runners for Windows on ARM.