Window Manager

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

Source Files

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.

Recently Closed Windows

The shell keeps a small in-memory closedWindowStack for user-initiated app window closes. It is runtime-only state, not persistence, app data, or a canonical URL resource.

Current conceptual shape:

type ClosedWindowSnapshot = {
  appId: ShellAppId
  title?: string
  subtitle?: string
  icon?: string
  route?: WindowRouteState
  layout?: WindowLayout
  snapTarget?: WindowSnapTarget
  restoreLayout?: WindowLayout
  spaceId?: string
  closedAt: number
}

Rules:

Window-Manager Spaces

The shell store still uses Space as an implementation name for the Desktop Runtime window manager. User-facing switching is expressed as Runtime/Studio switching and Scene switching.

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

Main fields:

Desktop window-manager 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

App open and focus

User-initiated opens (command palette, desktop icons, shell menus, in-app requestOpenApp) should flow through openShellApp in apps/os-shell/src/shell/open-shell-app.ts. That helper:

1. Calls openApp / openAppWithRecent, which uses resolveExistingWindowForApp in apps/os-shell/src/window-manager/resolve-app-window.ts to focus the best matching window (prefer the active window when it matches the app, otherwise the highest zIndex) instead of creating a duplicate.
2. Syncs the shell route via getShellRoutePath so the address bar matches the focused app.

Direct URL navigation still uses useShellRouting, which calls openAppWithRecent when the pathname changes. Shell bar dock icons are now split into persistent Dock apps and temporary running apps. A persistent app without a window calls openShellApp; a running app focuses its best existing window. Temporary apps are derived from open windows and disappear after quit unless the user keeps them in Dock.

Browser before-unload protection is scoped to Studio workspace routes. Public landing and content routes should not show a native "Leave site?" prompt; Studio routes may guard against accidental tab or window closes while workspace state is active.

Singleton App Window

Singleton App Window is separate from the Desktop Runtime window manager. It is a single lightweight floating surface that can appear on public pages and non-Desktop Runtime routes for small tasks. It renders the selected app through AppRuntime, but it does not create a WindowInstance, does not join a Desktop Runtime Space, and does not persist layout in the window store.

MVP constraints:

This preserves the host distinction: open light apps anywhere, organize multi-window app work in Desktop Runtime, build in Studios, and keep Alma as the companion layer.

Dock Semantics

The shell Dock is local browser OS state, not the app registry itself:

Window Actions

Current actions in useShellStore:

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

Fullscreen And Zoom Semantics

Snap And Space Dragging

Window dragging supports direct edge targets:

Geometry rules:

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:

Mission Control Design Contract

Control Shift Up and Control Shift Down are deliberately split:

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

• 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:

• Runtime Command Strip, command palette, drawers, dialogs, notifications.
• App-owned global modal overlays rendered through @prox-os/os-ui WindowDialog. These look window-like, but they are not window manager instances and do not create route, Dock, z-index, or layout state.
• Alma as a shell surface that resizes the measured workspace but does not become a normal window instance.
• 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.
• Per-window route state for app-owned appPath, search, and hash.

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.