Window Manager

Shell chrome and Mission Control UX: ../design/os-shell-design-language.md. State ownership: state-model.md.

Source Files

• Zustand implementation: apps/os-shell/src/window-manager/store.ts
• Shell-local window entrypoint: apps/os-shell/src/shell/window-manager/windowStore.ts
• Selectors/helpers: apps/os-shell/src/shell/window-manager/windowSelectors.ts
• Window layer: apps/os-shell/src/shell/window-manager/WindowLayer.tsx
• Single window component: apps/os-shell/src/shell/window-manager/AppWindow.tsx
• Titlebar controls: apps/os-shell/src/shell/window-manager/WindowTitlebar.tsx
• Mission Control / Spaces overlay: apps/os-shell/src/shell/spaces/MissionControlOverlay.tsx
• Spaces model: apps/os-shell/src/window-manager/space-model.ts
• Window model helpers: apps/os-shell/src/window-manager/window-model.ts
• Mobile viewport presets: apps/os-shell/src/shell/window-manager/mobilePresets.ts
• Shell window actions: apps/os-shell/src/shell/state/useWindowActions.ts
• Window resize menu: apps/os-shell/src/shell/chrome/WindowResizeMenu.tsx

WindowInstance

Current shape:

type WindowInstance = {
  windowId: string
  appId: ShellAppId
  title: string
  subtitle: string
  icon: string
  zIndex: number
  spaceId: string
  layout?: WindowLayout
  restoreLayout?: WindowLayout
  fullscreenOrigin?: { spaceId: string; layout?: WindowLayout }
  fullscreenSpaceId?: string
  isMinimized?: boolean
  isDesktopMaximized?: boolean
  isPinned?: boolean
}

WindowLayout is { x, y, width, height }.

isDesktopMaximized means "zoom inside the current desktop Space." It is intentionally separate from fullscreenSpaceId, which means the window has moved into a dedicated fullscreen Space.

Spaces

The shell store now owns virtual desktop state because Spaces are browser OS local UI state:

type Space = {
  id: string
  kind: 'desktop' | 'fullscreen'
  name: string
  order: number
  windowIds: string[]
  fullscreenWindowId?: string
  originSpaceId?: string
  createdAt: number
}

Main fields:

• spaces: ordered desktop and fullscreen Spaces.
• activeSpaceId: the currently visible Space.
• previousSpaceId: previous active Space for transition and restore context.
• missionControlMode: none, spaces, or windows.
• spaceTransitionDirection: horizontal animation hint for Space switches.

Desktop Spaces can hold multiple windows. Fullscreen Spaces hold one fullscreenWindowId and remember originSpaceId so exiting fullscreen returns to the desktop where the window started.

Ordering And Focus

• There is no separate windowOrder array yet.
• Order is currently implicit through zIndex.
• Focused window is stored as activeWindowId.
• Active Space is stored as activeSpaceId; visible windows are filtered by spaceId.
• focusWindow raises a window by assigning the next zIndex.
• fallbackActiveWindowId chooses the top non-minimized window in the active Space, preferring pinned windows.
• Pinned window behavior is represented by isPinned; rendering maps pinned windows to a higher shell layer.

Window Actions

Current actions in useShellStore:

• openApp(appId, bounds?): create a new window or focus an existing app window.
• closeWindow(windowId): remove one window and pick fallback focus if needed.
• closeOtherWindows(windowId): keep only the target window.
• closeAllWindows(): clear all windows.
• focusWindow(windowId): unminimize and raise a window.
• minimizeWindow(windowId): mark minimized and update active fallback.
• saveWindowSize(windowId): persist current size to localStorage.
• togglePinWindow(windowId): pin exactly one window at a time.
• toggleDesktopMaximizeWindow(windowId, bounds): titlebar-double-click zoom inside the current desktop Space.
• toggleFullscreenSpace(windowId, bounds): move a window into or out of a dedicated fullscreen Space.
• centerWindow(windowId, bounds): restore to centered default layout.
• hydrateWindowLayouts(bounds): assign/clamp layouts after workspace bounds are known.
• updateWindowLayout(windowId, layout): apply drag/resize result.
• createDesktopSpace(insertIndex?): create a desktop Space, capped at 17 desktop Spaces.
• closeDesktopSpace(spaceId): remove a desktop Space and move its windows to the nearest remaining desktop Space.
• moveWindowToSpace(windowId, spaceId): move a window to an existing desktop Space from Mission Control drag/drop.
• createDesktopSpaceForWindow(windowId, insertIndex): create a desktop Space at a Mission Control insertion point and move the dragged window into it.
• switchSpace(spaceId), switchSpaceByDirection(direction): manage desktop and fullscreen Space navigation.
• toggleMissionControl(), toggleWindowExpose(), closeMissionControl(): own Mission Control and current desktop window overview state.

Shell-level animation and snap behavior currently lives in useWindowActions.

Fullscreen And Zoom Semantics

• Titlebar double-click calls toggleDesktopMaximizeWindow. It saves restoreLayout and does not create a Space.
• Window titlebar controls render as left-aligned traffic-light dots in close, minimize, fullscreen order. Inactive windows show gray dots by default; hovering any dot reveals all three colors, but the resize hover menu only opens for the active window.
• The titlebar maximize control calls toggleFullscreenSpace. Entering fullscreen creates a new kind: "fullscreen" Space, moves the window there, expands its layout to workspace bounds, and records fullscreenOrigin.
• Hovering or right-clicking the active window's fullscreen dot opens WindowResizeMenu, which groups icon actions under Move & Resize, Fill & Arrange, and Full Screen. The menu calls the same snap, center, desktop zoom, and fullscreen Space actions as drag and keyboard flows instead of duplicating layout state.
• Exiting fullscreen removes the fullscreen Space, moves the window back to its origin desktop Space, and restores its saved layout.
• Mission Control shows a shrink action on fullscreen Space thumbnails. The action exits fullscreen and returns the app to its origin desktop window.
• Control Shift Down does nothing in fullscreen Spaces; Control Shift Left/Right still switches between Spaces.

Snap And Space Dragging

Window dragging supports direct edge targets:

• Top-left, top-right, bottom-left, and bottom-right corners snap to quarter layouts.
• Left and right edges snap to half-screen layouts.
• Top-half and bottom-half layouts are available from the resize menu. Direct bottom-edge drag snapping remains intentionally absent so ordinary vertical resizing does not accidentally arrange a window.
• The top edge toggles desktop maximize, which is the same state as titlebar double-click zoom and does not create a fullscreen Space.
• If a desktop-maximized window is dragged from its titlebar, the shell restores its previous layout before continuing the drag.

Dragging a normal desktop window to the top edge and holding for about 1.5 seconds opens Mission Control as a drop target. While the pointer stays in the Spaces strip:

• Hovering an existing desktop Space marks that Space as the drop target.
• Hovering the left edge, right edge, or a gap between Spaces shows a temporary translucent desktop placeholder with a +.
• Releasing on an existing desktop moves the window into that desktop.
• Releasing on a placeholder creates a new desktop Space at that position and moves the window into it.
• Fullscreen Spaces are visible in the strip but are not window drop targets.

Mission Control Design Contract

Control Shift Up and Control Shift Down are deliberately split:

• Control Shift Up is the OS-level Mission Control surface for Space switching and Space creation.
• Control Shift Down is the current desktop window overview. It reuses window transforms and keeps the active Space mental model intact.

The Mission Control strip is a shell overlay, not app content. It should:

• Use a single restrained glass panel at the top instead of applying blur to every window.
• Render desktop thumbnails with --os-desktop-background so the selected user background appears in miniature.
• Keep the Space thumbnail list scrollable when many Spaces exist.
• Center the list when there are only a few Spaces, then let it grow outward before it becomes scrollable.
• Pin the + create control to the far right of the strip.
• Cap normal desktop creation at 17 desktop Spaces.
• Animate the new-desktop preview from the right edge toward the + hover area before creation.
• Show a hover X action on desktop thumbnails when the desktop can be closed.
• Show a hover shrink action on fullscreen Space thumbnails to return that app to its origin desktop.
• Show fullscreen Spaces as app-identity thumbnails and desktop Spaces as miniature desktop surfaces with small window previews.

MobileMode Preview

MobileMode layout presets still exist as shell actions and can be re-exposed from a future app/window menu. They are no longer part of the default three-dot titlebar control set.

• Presets update only the current WindowLayout; they do not persist unless the user explicitly saves the window size.
• Apps with window.maximizable === false, such as Display options, should not expose MobileMode.

Shell vs Window Manager Boundary

Should stay in shell:

• Shellbar, command palette, drawers, dialogs, notifications.
• Route synchronization with TanStack Router.
• Link interception and external link menu behavior.
• System toasts and overlay placement.
• Screensaver and large cursor.

Should move deeper into window-manager over time:

• Snap target calculation.
• Minimize animation target calculation.
• Mission Control, App Expose, and overview layout transforms.
• Layout persistence.
• Explicit windowOrder if z-index becomes insufficient.
• Future per-window appRoute.

Oversized Or Broad Files

Current files are all below 500 lines, but some functions still carry broad responsibility:

• apps/os-shell/src/window-manager/store.ts: core Zustand actions; helpers are split into space-model.ts, space-state.ts, and window-model.ts.
• apps/os-shell/src/shell/state/useWindowActions.ts: close, snap, minimize animation, clamp, maximize, center.
• apps/os-shell/src/shell/useDesktopShellController.ts: shell orchestration and model wiring.
• apps/os-shell/src/shell/GlobalShortcuts.tsx: many shortcut branches.

These are candidates for later behavior-preserving splits.