Window Manager State Machine
Relevant source files
The following files were used as context for generating this wiki page:
The Window Manager State Machine is the core logic responsible for managing the lifecycle, positioning, and layering of application windows within the portfolio's desktop environment. It operates as a centralized state container that handles opening, closing, focusing, and transforming windows through a predictable action-based system.
This system ensures that the desktop maintains a "single-instance" policy per application, where re-opening an already active application will simply restore and focus the existing window rather than creating a duplicate.
Sources: workflows/windowManager.ts:1-10, workflows/windowManager.test.ts:25-33
Architecture and Data Structures
The state machine is built using a Redux-style pattern with a defined state shape and a reducer function. It tracks an array of active windows, the currently focused window ID, and a global nextZIndex to manage visual depth.
Core Data Models
| Interface | Description | Key Fields |
|---|---|---|
WindowState | Represents an individual window instance. | id, appId, zIndex, isMinimized, x, y, width, height |
WindowManagerState | The global state of the window manager. | windows[], focusedId, nextZIndex |
Sources: workflows/windowManager.ts:3-17
State Machine Schema
This entity-relationship diagram illustrates the structure of the state held within the manager.
Sources: workflows/windowManager.ts:3-23
Action Handlers and Logic
The windowReducer processes several distinct action types to modify the state.
Action Types
| Action | Description |
|---|---|
open | Adds a new window or restores/focuses an existing one. |
close | Removes a window from the state and clears focus if necessary. |
minimize | Sets isMinimized to true and clears the focusedId. |
focus | Increments nextZIndex, assigns it to the window, and sets focusedId. |
move | Updates the x and y coordinates of a specific window. |
resize | Updates the width and height dimensions of a specific window. |
Sources: workflows/windowManager.ts:25-33, workflows/windowManager.test.ts:35-86
Window Z-Index and Focus Flow
When a window is focused or opened, the manager uses a internal bringToFront utility. This ensures the window is always visually on top of others by assigning it the current nextZIndex and then incrementing that global counter.
Sources: workflows/windowManager.ts:35-64
Context Integration
The state machine is exposed to the React component tree via the WindowManagerProvider. This provider uses the useReducer hook with the windowReducer and provides a set of memoized callback functions to child components like the Dock and individual Windows.
WindowManagerValue Interface
interface WindowManagerValue {
windows: WindowState[];
focusedId: string | null;
open: (appId: AppId, geometry: Geometry) => void;
close: (id: string) => void;
minimize: (id: string) => void;
focus: (id: string) => void;
move: (id: string, x: number, y: number) => void;
resize: (id: string, width: number, height: number) => void;
isOpen: (appId: AppId) => boolean;
}
Sources: context/WindowManagerContext.tsx:11-23
Component Interactions
The following sequence diagram demonstrates how a user interaction in the Dock triggers the state machine to render a window.
Drag and Resize Logic
Individual Window components utilize the move and resize actions via a custom useDrag hook. The Window component enforces constraints such as minimum dimensions (MIN_W: 320, MIN_H: 240) and ensures the window cannot be dragged completely off-screen.
Sources: features/desktop/components/Window.tsx:10-50
Implementation Summary
The Window Manager State Machine provides a robust, testable foundation for the desktop environment. By centralizing window properties (geometry and depth) and lifecycle (open/close/minimize), it allows UI components to remain declarative while the underlying state handles complex layering and persistence logic.
Sources: workflows/windowManager.test.ts:1-87