Skip to content
filedom
Esc
↑↓navigate↵open⌘Jpreview
On this page

Host Runtime

The TypeScript bridge that orchestrates processes and talks to the macOS-native Swift binaries.

The host runtime connects the React renderer to macOS. It lives in @filedom/host and is public through the filedom/system entry point.

What it does

The bridge:

  • launches and supervises the long-lived native controllers
  • turns renderer intent (move this icon, set this color, play this sound) into native operations
  • keeps macOS-specific behavior out of the React layer
  • captures global keyboard input and desktop mouse input

Mental model

reconciler intent
  -> host bridge command
  -> native controller process
  -> icon movement / input / audio / desktop interaction

The bridge is split into modules (daemon for metrics and lifecycle, input, finder-commands, background, positions, system, system-ui, permissions, and audio), and its index re-exports the public surface. Native controllers stay alive across commands instead of being spawned per operation. IconController receives newline-delimited JSON commands over stdio. Keyboard capture and mouse capture run as separate InputListener processes. When Finder Mode launches a game, the app owns the keyboard tap and streams key events to the game over a loopback socket.

Reliability details

  • flushPendingCommands() waits for in-flight native commands to finish, so a fast process exit does not drop moves or a desktop restore. It gives up after a timeout so a hung daemon cannot block exit.
  • The run log is JSONL in ~/Library/Logs/filedom/, one file per process. Set FILEDOM_DEBUG=true for reconciler and template timing events in that log, and FILEDOM_DEBUG_ICONS=true for icon-pipeline detail. The Swift icon daemon keeps its own text log at /tmp/filedom.log (override the path with FILEDOM_LOG_FILE).
  • Desktop icon-view settings such as icon size and grid spacing are written through CFPreferences, not by editing Finder’s plist file, so a relaunched Finder reads the new values and not a stale cached copy.

Was this page helpful?