Frontend State & Custom Hooks

The frontend of the Atmos project utilizes a combination of React custom hooks and Zustand stores to manage complex application states, including workspaces, terminal sessions, and editor environments. This architecture ensures that shared state—such as the active project context or file content—is accessible across decoupled components while maintaining a clean separation of concerns.

The state management system is designed to handle asynchronous operations like file system access and terminal orchestration through WebSocket APIs, effectively bridging the gap between the user interface and the backend engine.

Workspace and Context Management

Workspace state is managed through specialized hooks that derive the current execution environment. The system distinguishes between a workspacePath and a projectPath to determine an effectivePath, which is critical for file system operations and terminal commands.

Context Resolution Logic

The useWorkspaceContext hook serves as the primary mechanism for identifying the active environment. It prioritizes the currentWorkspace but falls back to the currentProject if no specific workspace is active. This resolution is essential for features like the Project Wiki, which requires a stable path to locate metadata.

Global Stores (Zustand)

Atmos uses Zustand to manage persistent global state for the editor, terminal, and wiki modules. These stores provide both data state and action functions to manipulate that data.

Editor and Terminal Stores

The useEditorStore and useTerminalStore manage the core functional areas of the IDE. The editor store tracks open files and their content, while the terminal store manages multiple terminal panes and their interactive states.

Sources: apps/web/src/hooks/use-editor-store.ts, apps/web/src/hooks/use-terminal-store.ts, specs/tech/project-wiki.md:47-60

Wiki State Management

The useWikiStore specifically manages the lifecycle of the Project Wiki. It tracks the existence of the .atmos/wiki/ directory and maintains a hierarchical catalog of articles.

Terminal Orchestration and Command Execution

A critical aspect of the frontend state is the ability to programmatically control terminal instances. The TerminalGridHandle interface allows components like WikiSetup to spawn a new terminal tab and execute specific commands (e.g., wiki generation) without manual user input.

Execution Flow

When a user triggers an action that requires terminal execution, the frontend follows a sequence to ensure the terminal is ready before sending input.

Git Integration and Incremental Updates

State management extends to tracking Git metadata to detect when the frontend content is out of sync with the underlying repository. The WikiViewer component coordinates with the gitApi to compare stored commit hashes with the current HEAD.

Update Detection Logic

1. Load Catalog: The frontend reads _catalog.json which contains a commit_hash.
2. Fetch HEAD: The gitApi.getHeadCommit(path) call retrieves the latest commit from the backend.
3. Compare: If catalog.commit_hash !== currentHead, the state updates hasUpdate: true.
4. UI Response: The WikiSidebar listens to this state and renders a "Refresh" indicator.

Sources: specs/tech/wiki_incremental_update.md:67-85, specs/tech/wiki_incremental_update.md:12-30

Conclusion

The Atmos frontend relies on a structured hierarchy of custom hooks and stores to manage the complexity of a workspace-aware IDE. By utilizing hooks like useWorkspaceContext and stores like useWikiStore, the application ensures that state is consistently resolved, whether the user is browsing documentation, editing code, or executing terminal commands. This decoupled architecture allows for robust features like automatic wiki updates and programmatic terminal orchestration.