macOS Spaces & Window Restore — Research Notes

Research reference for a macOS-only limitation: after quitting and relaunching, Tranquil windows all open on the current desktop (Space) instead of returning to the Spaces they were on. Recorded as a wontfix with rationale so the private-API route is not re-explored later.

Status

Wontfix (platform limitation). No code change planned. This is inherent to how Electron apps create windows and applies equally to VS Code, Chrome, Slack, and every other Electron app.

The symptom

With Tranquil windows spread across multiple macOS desktops (Spaces), quitting and relaunching the app opens every restored window on whichever Space is active at launch. The windows’ sizes and positions are restored; their Space assignment is not.

Root cause

On relaunch, the main process recreates each BrowserWindow programmatically from saved state, and that saved state is geometry only — x/y/width/height (getDimensionsForNewWindow in src/main-process/atom-application.js). macOS places newly created windows on the active Space, always.

Native Mac apps that do return windows to their original Spaces get that behavior from AppKit’s own state-restoration machinery (NSWindowRestoration / restorableStateKeyPaths), where the OS resurrects the windows and remembers their Space assignment.^{nswindowrestoration} Electron apps do not participate in that system — Electron rebuilds windows itself at startup, so macOS treats every restored window as brand new.

Why it cannot be fixed with supported APIs

• macOS has no public API to ask “which Space is this window on?” or to move a window to a specific Space.
• Electron exposes nothing for Spaces beyond win.setVisibleOnAllWorkspaces(), which is a different feature (show on every Space).^electronwin
• Tools that do manipulate Spaces (yabai, etc.) rely on private CoreGraphics CGS* APIs, and some operations additionally require partially disabling System Integrity Protection.^yabai That means a native module poking at private frameworks that break across macOS releases — not something worth carrying in the fork for this.

Workarounds

• Leave the app running. macOS keeps windows on their Spaces for as long as the process lives; this is the only way placement truly survives.
• Assign the app to one desktop: right-click the dock icon → Options → Assign To → a specific desktop. Coarse (all windows land on that one Space) but stable across restarts.
• For the underlying goal — telling project windows apart at a glance — the per-window accent color (tranquil-window-color) is the in-app mechanism, since Space placement cannot be pinned.