@simular-ai/simulib-log-viewer

A floating, always-on-top log window for automation scripts. 100% click-through by default — every mouse click passes straight through to whatever is underneath, so the window never interferes with the page or app being automated. To move the window or pause execution, the user presses a deliberately rare global hotkey (Ctrl+Shift+Option+L on macOS, Ctrl+Shift+Alt+L everywhere else — same physical key combo, different keycap name) which is displayed inside the window: pressing it once enters "grab mode" (click-through off, execution paused, native title bar draggable); pressing it again restores click-through and resumes. Excluded from screenshots on macOS.

The package ships two artifacts per platform:

• A napi .node file (the JS bindings).
• A simulib-log-viewer executable (the eframe GUI).

Both ride along in the per-platform npm subpackage; npm install picks the correct one for your OS/arch. The Rust bindings discover the bundled binary at runtime via dladdr (Unix) / GetModuleHandleExW (Windows), so there is no viewerPath argument or path probing on the JS side.

Usage

Runnable, typechecked examples live under examples/:

• examples/basic.mjs — full LogWindow API tour (spawn / log / waitIfPaused / clear / close).
• examples/with-simulib-js.mjs — wires @simular-ai/simulib-js's initLogger into the window so every Rust-side log::*! record shows up automatically.

See examples/README.md for how to run them.

API

| Method | Description | | ------------------- | -------------------------------------------------------------------------------------------- | | new LogWindow() | Construct a handle. Does not open the window. | | spawn() | Launch the viewer subprocess. | | log(message) | Append a line. | | clear() | Drop all displayed messages. | | isPaused (getter) | true while the user has pressed the grab hotkey (paused & interactive); false otherwise. | | waitIfPaused() | await-able; returns immediately if not paused. | | close() | Shut down the viewer subprocess. Optional — happens automatically on parent exit. |

Why a separate process

Cross-platform Rust GUI toolkits (eframe, winit, iced, slint) require the OS process main thread on macOS, which Node already owns. The window therefore runs in its own process, with NDJSON over stdin/stdout for IPC. Same constraint Electron and Tauri are built around.

Development

npm install
npm run build:debug          # builds the .node + the viewer binary, copies both to the package root
node examples/basic.mjs      # opens the window

The viewer Cargo feature gates eframe and macOS objc2 extras so the cdylib build (napi build) does not pull the GUI deps.

Releasing

See PUBLISH.md. Releases are cut from CI on tag push; per-platform packages are produced and published automatically.

License

MIT © 2026 Simular AI