Swift Runtime

The native controllers that move icons, capture input, and play audio on macOS.

The Swift code is the native control layer. Its sources live in packages/host/src/swift, and pnpm swift:build (from the repository root) compiles four binaries, each as a universal arm64 and x86_64 build.

The binaries

• IconController moves icons, sets custom icons and colors, controls the grid and view options, owns the park cover window, and handles Finder round-trips. Every visible desktop change goes through it. PositionMotion.swift is compiled into it.
• InputListener captures global keyboard input and desktop mouse events (clicks, right-clicks, drags) and streams them to the host bridge. Game controls do not work until this process has Accessibility permission.
• AudioController keeps one AVAudioEngine running with cached PCM buffers, so filedom/sound plays effects with low latency instead of starting a process per sound.
• StashController is a filesystem-only helper for the Desktop hide journal. It locks the Desktop and sets or clears the hidden flag on the user’s items. It runs only for a hide or restore, never stays resident, and never starts Finder or input services.

IconPositionReader.swift is also in the tree. It is a standalone position reader that the build does not compile and the runtime does not use.

Runtime role

The Swift layer is the native endpoint for the TypeScript host bridge. IconController and AudioController start once and stay alive, receiving commands over stdio. The bridge looks for each binary next to the published package or in the monorepo build. Override the locations with FILEDOM_ICON_CONTROLLER_PATH, FILEDOM_INPUT_LISTENER_PATH, FILEDOM_AUDIO_CONTROLLER_PATH, or FILEDOM_STASH_CONTROLLER_PATH.

Permissions

• Automation (System Settings → Privacy & Security → Automation) is required for Finder control.
• Accessibility is required for global input capture.

Run pnpm exec filedom doctor to check both with a live round-trip.