← Feature index · Architecture
Dock the whole Ferail window to the left or right screen edge as an auto-hiding, always-on-top drawer: a Quake/iTerm-hotkey-style panel. When docked it floats above every other app and slides off-screen, leaving only a thin grab handle on that edge. Slamming the cursor into the docked screen edge slides the window back in; moving the pointer away tucks it out again. The point is to reach the file manager from inside any other app without cluttering the desktop.
Left/right only by design: the top edge fights the menu bar and the horizontal drawer is the useful shape.
macOS-only in practice: it bottoms out in AppKit NSWindow calls, and
Shell::window_ns_view yields None off AppKit so set_dock early-returns.
The toolbar control is cfg!(target_os = "macos")-gated and the actions are
bound to no key and absent from the command catalogue, so the feature is simply
absent elsewhere rather than a menu that does nothing. Porting it is not
stub-filling: the frame math below is in macOS global screen space (origin
bottom-left, y-up) and has to be mapped onto the target's coordinate system;
see TODO.md § Cross-Platform.
- Toolbar → the dock glyph (top-right cluster, after Refresh). Its dropdown offers Dock Left, Dock Right, and Undock, each with an icon. The button shows a pressed state while docked.
- Actions:
DockLeft,DockRight,Undock(shell/actions.rs). The toolbar dropdown is their only surface today: they carry no key binding and no command-catalogue entry, so they do not appear in the Cmd+K palette.
- Snap, then tuck. Docking snaps the window flush to the edge fully shown, then (unless the cursor is already at that edge) it slides out to the handle, so the transition reads as "snap to edge → tuck away".
- Reveal = edge-slam. The whole docked screen edge is the trigger, not just the handle, so it is easy to hit; the handle is the visual hint. Once shown, the drawer stays open while the pointer is over it and tucks away when the pointer leaves both the drawer and the edge (hysteresis).
- Floats, doesn't steal focus. Revealing slides the window in over your
current app without activating Ferail (
NSFloatingWindowLevel); a click activates it. It also joins all Spaces and floats over full-screen apps (NSWindowCollectionBehaviorCanJoinAllSpaces | FullScreenAuxiliary), so it's reachable from any Space. - Drawer size. Docking NEVER resizes the window: the drawer is the
window at its own size, purely translated to the edge (
yclamped onto the screen). gpui's drawable doesn't follow an out-of-band AppKitsetFrame:resize, so the earlier full-screen-height drawer rendered its stretched area black. Undocking restores the exact pre-dock frame (clamped onto the live screen in case the display arrangement changed while docked).
Three layers, matching the repo's boundaries:
shell/dock.rs: pure geometry. No GPUI, no AppKit, no wall-clock:DockEdge,DockState, and the frame math (revealed_frame,hidden_frame,cursor_in_trigger_zone,current_frame,step,wants_reveal). All in macOS global screen space (origin bottom-left, y-up) so values fromNSEvent/NSScreen/NSWindowflow through unflipped. Fully unit-tested.shell.rs: GPUI glue.Shell::set_dockcaptures the window/screen frames once, sets the float + all-Spaces behaviours, and starts the reveal poll. The poll is a self-re-arming one-shot (schedule_dock_poll→dock_poll_tick, like the viewer's slideshow timer, epoch-guarded): each tick readsNSEvent.mouseLocation, flips the drawer's revealed target, steps the slide, and moves the window only when the slide actually advanced: a settled drawer touches AppKit zero times per tick. It polls ~16 ms mid-slide, ~33 ms once settled, and runs only while docked. The window'sNSViewis captured as ausize(raw pointers aren'tSend) so the async loop can move the window without aWindowhandle.ferail-shell-mac: the AppKit primitives.current_mouse_location,screen_visible_frame_for_window,window_frame,set_window_frame(deliberately not animated: the host drives the slide so nothing spins the run loop, per the Prime Directive; size stays fixed so gpui never resizes its drawable), andset_window_all_spaces. Reuses the existingset_window_floating.
The handle is a Root-level overlay (Shell::dock_handle) anchored to the
window edge opposite the dock edge (the side left on-screen), drawn only while
docked and not fully revealed.
Nothing here runs on the paint path. The reveal poll is a scheduled task that
exists only while docked; rendering just reads DockState and draws the handle.
- No persistence / auto-restore. Docking is a session action (like the viewer's "Stay on top"), intentionally not persisted: auto-restoring on launch would start the app already hidden as a handle, which is surprising and only recoverable through the handle itself. A future opt-in setting could restore the docked state, ideally starting revealed.
- Native titlebar in drawer mode. The traffic-light titlebar still shows when docked. A borderless drawer chrome (and hiding the traffic lights) is a follow-up.
- No per-item active-edge checkmark. The menu items carry directional icons instead of a checkmark; the active edge is shown by the toolbar button's pressed state and by the drawer itself being visibly on a side.
- Multi-display: docks to the display the window currently occupies; the captured screen frame goes stale if the display layout changes while docked.
- Full-screen coverage: join-all-Spaces +
FullScreenAuxiliarylets the drawer appear over most full-screen apps, but a true-full-screen app on its own Space can still occlude it in some cases.