Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/apursley2012/dev-os/llms.txt

Use this file to discover all available pages before exploring further.

WindowManager is the central nervous system of DevOS. It uses a React Context to broadcast window state — which apps are open, which is focused, and what their geometry should be — to every component in the tree without prop drilling. All mutations (open, close, minimize, maximize, focus) flow through a single provider, keeping the rest of the codebase stateless and predictable.

​
WindowManagerProvider

Wrap your entire application in WindowManagerProvider (typically in main.js) so that every child component can access the window registry: 
// main.js
import { WindowManagerProvider } from './components/system/WindowManager';
import { Desktop } from './components/system/Desktop';
import { Taskbar } from './components/system/Taskbar';

export default function App() {
  return (
    <WindowManagerProvider>
      <Desktop />
      <Taskbar />
    </WindowManagerProvider>
  );
}
The provider initialises three pieces of state internally:
StateInitial valueDescription
windows[]The array of all currently tracked window objects
focusedWindowIdnullThe id of the window that is currently active
zIndexCounter10A monotonically increasing integer used to layer windows

​
useWindowManager() hook

Call useWindowManager() inside any component that is a descendant of WindowManagerProvider to read state or dispatch actions. 
import { useWindowManager } from '../system/WindowManager';

const {
  windows,
  focusedWindowId,
  openWindow,
  closeWindow,
  minimizeWindow,
  maximizeWindow,
  focusWindow,
} = useWindowManager();

​
Return values

​
windows: WindowData[]

A snapshot array of every window that has been opened in the current session. Windows that have been closed are removed from the array entirely; windows that have been minimised remain in the array with isMinimized: true.

​
focusedWindowId: string | null

The id string of the window currently receiving keyboard/pointer focus, or null when no window is focused (e.g. immediately after the desktop loads, or after the last open window is closed).

​
openWindow(id, options)

Opens a new window, or un-minimises an existing window with the same id. 
openWindow(id: string, options: {
  title: string;
  icon: React.ComponentType;
  component: React.ComponentType;
  defaultSize?: { width: number; height: number };
}): void
If a window with the given id is already open and not minimised, openWindow is a no-op for that window — it will not create a duplicate. If the window is minimised, it is restored and brought to the front. Newly created windows receive the current zIndexCounter value, and the counter is incremented.

​
closeWindow(id)

Removes the window with the given id from the windows array entirely and clears focusedWindowId if it matched. The app component inside the window is unmounted and its local state is discarded.

​
minimizeWindow(id)

Sets isMinimized: true on the target window and clears focusedWindowId if it matched. The window component returns null when minimised, but remains in the windows array, so the Taskbar button stays visible.

​
maximizeWindow(id)

Toggles isMaximized on the target window and brings it to the front by calling focusWindow internally. When maximised, the Window component animates to full-viewport width and calc(100vh - 48px) height.

​
focusWindow(id)

Sets focusedWindowId to id, assigns the current zIndexCounter value to that window’s zIndex, and increments the counter. This guarantees the most recently focused window is always rendered on top of all others.

​
Window object shape

Every entry in the windows array conforms to the following interface: 
interface WindowData {
  id: string;
  title: string;
  icon: React.ComponentType;
  component: React.ComponentType;
  isOpen: boolean;
  isMinimized: boolean;
  isMaximized: boolean;
  zIndex: number;
  defaultSize: { width: number; height: number };
}
FieldDescription
idUnique key; used to prevent duplicate windows and to target mutations
titleDisplayed in the window title bar and the Taskbar button
iconA Lucide React (or any React) component rendered at 16 px in the title bar
componentThe app component rendered inside the window body; receives no props
isOpenAlways true for windows currently in the array
isMinimizedtrue while the window is hidden to the taskbar
isMaximizedtrue while the window fills the viewport
zIndexCSS z-index applied to the Framer Motion div; higher = in front
defaultSizeThe { width, height } in pixels used for the initial window size

​
Code example

The following shows how to trigger openWindow from an arbitrary component anywhere in the tree: 
import { useWindowManager } from '../system/WindowManager';

function MyButton() {
  const { openWindow } = useWindowManager();
  return (
    <button onClick={() => openWindow('my-app', {
      title: 'My App',
      icon: MyIcon,
      component: MyAppComponent,
      defaultSize: { width: 600, height: 400 },
    })}>
      Open My App
    </button>
  );
}

​
Usage outside the provider

useWindowManager throws a descriptive error if it is called outside of WindowManagerProvider: 
Error: useWindowManager must be used within WindowManagerProvider
This fail-fast behaviour surfaces misconfigured component trees during development rather than producing a silent undefined reference at runtime.
zIndex starts at 10 and increments on every openWindow or focusWindow call. The most recently focused window is therefore always rendered above every other window — no manual z-index management is needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us