Workspace & Layout Management
Relevant source files
The following files were used as context for generating this wiki page:
Workspace & Layout Management in Termul organizes terminal sessions, editors, and browser tabs into a project-aware, persistent environment. The system treats workspaces as first-class citizens, allowing you to arrange components side-by-side using resizable panes and tabbed interfaces. It maintains state through a portable manifest system that survives application restarts and supports cross-platform parity between Tauri desktop and web clients.
Architecture and Topology
Termul represents the workspace as a recursive tree of nodes. A PaneNode is either a SplitNode, which divides the view into horizontal or vertical sections, or a LeafNode, which contains the actual terminal and editor instances.
Workspace Node Types
| Node Type | Description | Key Fields |
|---|---|---|
| SplitNode | A container that divides space between multiple child nodes. | direction, children, sizes |
| LeafNode | A terminal/editor container that holds active and background tabs. | terminalIds, editorIds, activeTabId |
Sources: src/shared/types/workspace-manifest.types.ts:25-50
Topology Structure
The following diagram illustrates the relationship between split and leaf nodes in the workspace manifest:
The manifest ensures that proportional sizes and tab associations remain consistent across sessions.
Sources: src/shared/types/workspace-manifest.types.ts:86-98
Manifest Management and Persistence
Persistence relies on a versioned WorkspaceManifest. The host (Rust runtime or web server) owns this manifest, which contains the project topology, active terminal descriptors, and editor file paths.
Manifest Synchronization
The renderer uses a manifest sync hook to manage state transitions. When a project is active, the system performs revision-checked writes to prevent data loss during concurrent access.
Key Data Structures
- TerminalDescriptor: Contains the
terminalId,shell,cwd, and an opaqueclaimHandlefor session restoration. - EditorDescriptor: Stores the
editorIdand thefilePathof the open buffer. - WriteOutcome: A discriminated union that returns either an
updatedstatus with a new revision or aconflictstatus containing current host metadata.
Sources: src/shared/types/workspace-manifest.types.ts:59-113
Layout Rendering and Components
The UI renders the workspace using a set of specialized React components that respond to the workspace-store.
Core Components
- WorkspaceLayout: The root layout component that manages the overall grid, sidebar visibility, and the macOS-native title bar strip.
- PaneRenderer: Recursively walks the topology tree to render splits and leaves.
- WorkspaceTabBar: A Windows Terminal-style tab bar supporting drag-and-drop reordering, renaming, and context menus.
- ActivityRail: Provides global navigation and quick access to Git changes, history, and SSH profiles.
Sources: README.md:95-108, src/renderer/layouts/WorkspaceLayout.test.tsx:325-335
Desktop vs. Mobile Rendering
Termul adjusts the layout based on the viewport. On mobile devices (viewports ≤ 767px), the IDE chrome is replaced by a simplified mobile shell that prioritizes the chat and terminal interface.
Cross-Platform Parity
The Workspace Management system maintains parity between the Tauri desktop application and the standalone web server through a facade layer.
| Feature | Tauri Desktop Implementation | Web Server Implementation |
|---|---|---|
| Transport | Tauri invoke IPC | HTTP / WebSockets |
| Filesystem | tauri-plugin-fs | /fs/* HTTP Endpoints |
| Manifest API | tauri-workspace-manifest-api | web-workspace-manifest-api |
| Watcher | Host-native notify | Control WS fs_changed bridge |
Sources: src/renderer/lib/tests/parity-checklist.test.ts:187-200, AGENTS.md:35-45
Workspace Lifecycle and Cleanup
The system manages the lifecycle of terminals and editors to prevent resource leaks while ensuring session continuity.
- Project Switch: When you switch projects, the
WorkspaceLayoutunwatches the old root and initiates a watch on the new project directory. - Session Preservation: Active PTY sessions are preserved across project switches; the application does not kill sessions during navigation.
- Unload Persistence: Before the window unloads, the
saveTerminalLayoutfunction persists the current state for the active project.
Sources: src/renderer/layouts/WorkspaceLayout.test.tsx:645-660, AGENTS.md:73-75, src/renderer/layouts/WorkspaceLayout.test.tsx:340-350