Spotlight file/directory picker
The Spotlight picker is a fast, keyboard-driven file and directory search modal that replaces the matching native OS file or folder dialog on macOS. Instead of navigating the full file tree, you type a few letters and the picker streams matching results from the Spotlight index in real time.
Where it appears
The picker is used by the app's deliberately local file surfaces:
| Surface | What you pick |
|---|---|
| External File Editor — Load/Add files | One or more local files to open. |
| Empty frame — Load file | A local file handed off to External File Editor. |
These are outside the encrypted cloud workspace. The picker does not choose a Project Root, add a cloud workspace, or select where a generated text app stores workspace content; those pre-cloud local-workspace flows were retired.
Picker layout
The picker has three persistent areas:
Header - shows the picker title, such as "Find folder" or "Find file".
Search row - contains the search icon, text input, loading spinner, and a mode chip.
Results - streams matching rows as Spotlight returns them.
The old separate badge row has been retired. The current mode is shown as a compact chip inside the input row:
| Mode | Chip text |
|---|---|
directory | Folders |
file | Files |
any | Anything |
When the caller passes a search scope, the picker shows it as a separate scope chip below the input row. Click the chip's close button to clear the scope and search the wider Spotlight index.
Result rows
Each result row shows:
Icon - folder or document.
Name - highlighted against the current query.
Path - the parent directory, truncated from the start so the closest folder remains visible.
Modified date - recent files show relative labels such as
todayor3d ago; older files show a compact calendar date.
When the app knows your home directory, paths under it are shortened with ~. For example, / is displayed as ~/Documents/notes.
Keyboard shortcuts
| Key | Action |
|---|---|
| ↑ / ↓ | Move highlight up or down the result list |
| Enter | Select the highlighted result |
| Esc | Close the picker without selecting |
| Cmd+B | Fall back to "Browse with Finder…" (the matching native file or folder dialog) |
Indexing latency
The picker queries the macOS Spotlight index. Files and directories you just created may not appear immediately — Spotlight typically indexes new items within a few seconds to a minute, depending on system load and Privacy settings.
If you cannot find a recently created file or folder, use the Browse with Finder… fallback (footer button or Cmd+B) to open the matching standard macOS dialog instead. The fallback is always available.
macOS only — iOS uses the native dialog
The Spotlight index is a macOS-only API. On iOS, every surface that shows the Spotlight picker on macOS automatically falls through to the iOS native document browser instead. No configuration is needed; the app detects the platform at runtime.
Disabling Spotlight search
If you experience performance issues with the Spotlight picker, or simply prefer the native folder dialog everywhere, you can turn it off in Settings → General:
Checkbox: Use Spotlight for file/directory search (checked by default)
Unchecking this setting makes all picker surfaces listed above fall through to the native OS dialog, the same way iOS does. The setting takes effect immediately — no restart required.