---
title: Swift Runtime
description: 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`](/docs/reference/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.