Zustand State Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/renderer/stores/workspace-store.ts
• src/renderer/stores/acp-store/index.ts
• src/renderer/stores/terminal-store.ts
• src/renderer/layouts/WorkspaceLayout.test.tsx
• src/renderer/lib/tests/parity-checklist.test.ts
• README.md

Termul utilizes Zustand to manage reactive state across its React-based frontend. This system centralizes domain logic for workspaces, terminal sessions, agent communications, and application settings into specialized stores. These stores serve as the primary source of truth for the renderer, ensuring UI consistency during complex operations like project switching or pane resizing.

The architecture separates state concerns into domain slices. This approach allows components to subscribe only to relevant data, minimizing unnecessary re-renders. Key domains include workspace-store for layout topology, terminal-store for PTY session management, and acp-store for handling Agent Client Protocol communications.

Sources: README.md:120-129, src/renderer/lib/tests/parity-checklist.test.ts:742-764

Store Architecture and Data Flow

The project structures state management through a series of specialized hooks that interface with the Zustand stores. These stores manage both volatile UI state and persistent data synchronized with the Tauri backend.

Component Relationship Diagram

The following diagram illustrates how different Zustand stores interact with the renderer and shared services.

Domain Stores

Workspace Store

The workspace-store manages the visual arrangement of the application, including the tree-based pane topology. It handles split layouts and tab organization.

• Pane Topology: Manages the hierarchical structure of PaneNode objects, which can be either leaf nodes (containing tabs) or split nodes.
• Tab Management: Tracks terminal and editor descriptors within specific leaf panes.
• Sync Logic: Coordinates with useWorkspaceManifestSync to persist layout changes to the host.

Sources: src/renderer/stores/workspace-store.ts:1-20, src/renderer/lib/tests/parity-checklist.test.ts:255-265

Terminal Store

The terminal-store acts as the coordinator for terminal sessions. It maintains the link between the renderer UI and the backend PTY processes.

Action	Description
addTerminal	Spawns a new terminal session for a specific project.
selectTerminal	Updates the active terminal ID for UI focus.
setTerminalPtyId	Maps a renderer terminal instance to a native PTY ID.
cleanupProjectTerminals	Kills active PTY sessions when a project is closed.

Sources: src/renderer/stores/terminal-store.ts:1-30, src/renderer/layouts/WorkspaceLayout.test.tsx:65-75

ACP Store (Agent Client Protocol)

The acp-store handles agent communications and session transcripts. It is organized into domain slices to manage different aspects of the protocol.

• Session Management: Tracks active agent chats and their durability status.
• Timeline Splicing: Merges live agent switch events into the transcript timeline for seamless conversation history.
• MCP Integration: Manages Model Context Protocol server registrations and mutations.

Sources: src/renderer/stores/acp-store/index.ts:1-10, src/renderer/lib/tests/parity-checklist.test.ts:742-764

Persistent State and Synchronization

Termul stores are often synchronized with the filesystem or Tauri plugins to ensure state persistence across application restarts.

Sync Workflow Diagram

This sequence diagram shows how the WorkspaceLayout coordinates saving state to the host via stores and hooks.

Synchronization Mechanisms

• Debounced Persistence: The app-settings-store utilizes writeDebounced via the persistenceApi to prevent excessive disk I/O during rapid setting changes.
• Manifest Revisions: The workspace-store uses a revision-based conflict detection system when writing to workspace_manifest.json.
• PTY Restoration: The terminal-store works with useTerminalAutoSave to reload previous terminal sessions upon project activation.

Sources: src/renderer/layouts/WorkspaceLayout.test.tsx:210-225, src/renderer/lib/tests/parity-checklist.test.ts:255-265

Store Summary Table

Store Name	Key State Variables	Core Responsibilities
workspace-store	root, activePaneId	Layout topology, pane splitting, tab positioning.
terminal-store	terminals, activeTerminalId	PTY session mapping, terminal lifecycle, activity tracking.
acp-store	agentSwitches, sessions	Agent communications, transcript history, tool calls.
project-store	projects, activeProjectId	Project registry, worktree locks, path resolution.
app-settings-store	settings, colorTheme	UI preferences, keyboard shortcuts, theme tokens.

Sources: src/renderer/layouts/WorkspaceLayout.test.tsx:43-150, README.md:120-129

Zustand state management in Termul provides a reactive, hook-based interface that abstracts complex backend interactions. By using domain-specific stores, the application maintains a clear separation of concerns, ensuring that UI components remain decoupled from the underlying Tauri and Rust implementations.