​

WorkspaceView Component

​

Overview

• Project and worktree state (sidebar navigation)
• Session lifecycle (create, resume, close)
• Tab bar and split-pane layout
• Work-done detection for agent sessions
• Keyboard shortcuts and global events
• Theme switching
• Settings and configuration

interface Props {
  zen?: true;           // Zen mode: single project, flat worktree list
  name?: string;        // Project name for zen mode
  path?: string;        // Root path for zen mode
}

​

Data Model

​

Session Interface

interface Session {
  id: string;                          // Ephemeral PTY session UUID
  name: string;                        // Display name (worktree branch or custom)
  cwd: string;                         // Working directory path
  projectId: string;                   // Parent project UUID
  kind?: "terminal" | "diff" | "preview" | "editor"; // Tab type (defaults to "terminal")
  previewUrl?: string;                 // Current URL for preview tabs
  agent?: string;                      // CLI command (e.g. "claude")
  conversationId?: string;             // Claude conversation UUID for resuming
  instanceId: string;                  // Stable identity across restarts (never changes)
  createdAt: string;                   // ISO timestamp
  isRootSession?: boolean;             // true when running in project root (no worktree)
  noGit?: boolean;                     // true when user skipped git init for root session
  parentSessionId?: string;            // Set when spawned via split
  storeKey?: string;                   // localStorage key for persistence
  metadata: {
    resumeCount: number;               // How many times this session has resumed
    hasBeenResumed: boolean;
  };
}

​

Project and Worktree

interface Worktree {
  name: string;  // Branch name (e.g. "feature-auth")
  path: string;  // Full filesystem path
}

interface Project {
  id: string;                  // UUID
  name: string;                // Project folder name
  path: string;                // Root directory
  expanded: boolean;           // Sidebar expand/collapse state
  worktrees: Worktree[];       // Cached worktree list
}

​

Tab System

​

State Management

​

Session Management

• sessions: Array of all open Session objects
• activeSessionId: Currently focused session UUID
• renamingSessionId: Session being renamed (if any)

​

Tab Bar

• dragTabId, dragOverTabId, dragOverSide: Tab reordering state
• Refs (dragTabIdRef, dragOverTabIdRef) to avoid stale closures

​

Layout

• paneLayout: Split pane tree (null = single pane mode)
• activeSplitIds: Set of session IDs in current split layout
• paneRects: Computed absolute positions for each pane

​

Navigation

• activeSection: “overview” | “nexus” (main page when no tab active)
• sidebarOpen: Left sidebar visibility
• rightSidebarOpen: Right sidebar visibility

​

Terminal/Worktree Creation

• showTerminalNaming: Modal open state for naming new sessions
• terminalName, terminalPrompt: User input for new sessions
• terminalLaunching: Async operation in progress
• gitNotFound, gitNotFoundRoot: Git initialization dialogs
• pendingProjectId, pendingAgent: Deferred session creation

​

Project Management

• projects: Array of projects (default mode only)
• zenWorktrees: Worktree list for zen mode

​

UI State

• settingsOpen, broadcastOpen, promptPickerOpen: Modal states
• ctxMenu: Right-click context menu position/context
• deleteDialog: Workspace deletion confirmation state
• atlasPromptPath, atlasIndexingPaths: Atlas (Token Intelligence) state
• queueOpenSessionId: Message queue panel visibility
• gitRevision: Increment counter that triggers DiffPane refreshes

​

Split Pane Layout

​

Tree Structure

type SplitDir = "h" | "v";  // horizontal or vertical split

interface SplitLeaf {
  type: "leaf";
  sessionId: string;  // Which session occupies this pane
}

interface SplitBranch {
  type: "split";
  id: string;        // Unique branch identifier
  dir: SplitDir;     // "h" (stacked) or "v" (side-by-side)
  ratio: number;     // 0.0-1.0: proportion of space for first child
  first: PaneNode;   // Left/top subtree
  second: PaneNode;  // Right/bottom subtree
}

type PaneNode = SplitLeaf | SplitBranch;

​

Pane Positioning

interface PaneRect {
  top: number;     // 0.0-1.0 fractional offset from top
  left: number;    // 0.0-1.0 fractional offset from left
  width: number;   // 0.0-1.0 fractional width
  height: number;  // 0.0-1.0 fractional height
}

function computeRects(n: PaneNode): Map<string, PaneRect>
function collectHandles(n: PaneNode): HandleInfo[]

​

Split Operations

async function splitPane(dir: SplitDir) {
  // Create new session at same cwd as active pane
  const newId = crypto.randomUUID();
  const branch: SplitBranch = {
    type: "split", id: crypto.randomUUID(), dir, ratio: 0.5,
    first:  { type: "leaf", sessionId: activeSessionId },
    second: { type: "leaf", sessionId: newId },
  };
  setPaneLayout(...)  // Insert branch into tree
  await openSession(..., newId, activeSessionId)  // Link as sub-session
}

​

Session Lifecycle

​

Creating a Session

1. Mints or reuses a stable instanceId for persistence
2. Determines the storage key (storeKey): root sessions use rootSessionKey(cwd, sessionId), worktree agents key on cwd
3. Builds agent arguments via buildAgentArgs(): session/resume flags + prompt
4. Calls invoke("create_pty_session") → Rust PTY spawns
5. Registers with SessionManager, which owns the Channel and runs work-done detection
6. Adds to sessions state, making it appear as a tab
7. Persists metadata to localStorage

​

Resuming a Conversation

await openSession(
  name, cwd, projectId, agent,
  undefined,      // no initial prompt
  undefined,      // metadata
  conversationId, // pass stored UUID
  isRootSession,
  noGit
);

config.resumeArgs?.forEach(arg => {
  args.push(arg.replace("{UUID}", conversationId))
})

​

Closing and Cleanup

1. Recursively closes all sub-sessions (spawned via split)
2. Kills the PTY: invoke("close_pty_session", {sessionId})
3. Marks persisted entry as closed: markWorktreeSessionClosed(storeKey)
4. Unregisters from SessionManager
5. Removes from pane layout tree if in split mode
6. Clears work state badge
7. Updates active session if needed

​

Work-Done Detection

​

Detection Logic (in SessionManager)

1. Byte-quiet timer: Start on first data chunk from the agent
2. Title watching: Monitor OSC 0/2 escape sequences (agent sends status like ”✳ refactoring”)
3. Two thresholds:
   • 5 seconds of silence without title changes = “work done”
   • 12 seconds of silence with title changes (still thinking) = extend to “done”
4. User input resets: When user types and presses Enter, arm a new quiet timer

​

Display

const WorkStateBadge = memo(function WorkStateBadge({ sessionId }) {
  const state = useWorkState(sessionId);
  if (state === "working") return <Loader size={11} className="spin" />;
  if (state === "done") return <span className="work-done-dot" />;
  return null;
});

​

Restore on Launch

1. Discover valid paths: Scan each project’s .tempest/ for worktrees, add to validPaths
2. Mark root sessions as valid: Retrieve all root session store keys (project.path + “::root::” + sessionId)
3. Prune orphaned entries: Delete persisted sessions whose paths no longer exist on disk
4. Collect restore items: Build list from sessionOrder (tab bar order) + saved active session
5. Open in order: Restore non-active sessions, then active session last so it gets focus

​

Keyboard Shortcuts

​

Event Listeners

listen<{ path: string; line: string }>("atlas:log", (e) => {
  console.log(`[Atlas] ${e.payload.line}`);
});

​

Persistence

1. sessionOrder, activeInstanceId: Via setRuntimeState()
   • Restores tab bar order and last active tab on launch
2. Per-session metadata: Via saveWorktreeSession(storeKey, {...})
   • name, agent, conversationId, instanceId, projectId, isRootSession, noGit
3. Transient tabs (diff/preview/editor): Via runtimeState.tabs array
   • Includes kind, cwd, projectId, previewUrl for preview tabs
4. Project list: Via saveOpenProjects()
   • Only default mode (not zen)

​

Theme Integration

• Read current theme name (“Tempest Dark” vs “Tempest Light”)
• Provide sun/moon toggle button in sub-bar
• Pass theme context to all child components

​

Context Menus

• Close session
• Delete workspace (with optional branch deletion)

• Remove session (delete persisted entry)

• Index project (Atlas/Token Intelligence)
• Remove project (close all its sessions)

​

Modal Dialogs

1. Terminal naming modal: Enter worktree name, optional prompt, choose git init strategy
2. Delete workspace dialog: Two-step confirm with optional branch deletion
3. Atlas index prompt: Ask user to opt-in to local indexing
4. Settings panel: Full settings UI
5. Broadcast dialog: Send message to all agent sessions
6. Right sidebar: File tree + git operations

​

Memoization Strategy

const WorkStateBadge = memo(function WorkStateBadge({ sessionId }) {
  const state = useWorkState(sessionId);  // Only re-render when THIS session's state changes
  ...
});

const QueueBadge = memo(function QueueBadge({ sessionId, onClick }) {
  const queue = useQueue(sessionId);  // Isolated queue subscription
  ...
});

const SidebarWorkBadge = memo(function SidebarWorkBadge({ sessionId }) {
  // Sidebar row updates only when this specific session's work state changes
  ...
});

​

Refs for Avoiding Stale Closures

const paneLayoutRef = useRef<PaneNode | null>(null);
paneLayoutRef.current = paneLayout;  // Updated every render

const shortcutHandlerRef = useRef<(e: KeyboardEvent) => void>(() => {});
// Updated in useEffect, used in addEventListener (registered once)

const sessionsRef = useRef<Session[]>([]);
sessionsRef.current = sessions;  // Read in post-restore active-session lookup

​

Sidebar Navigation

• Expandable header with project name
• Root sessions (agent + terminal in project root, badged “main”)
• Worktree sessions (git branches with their own sessions)
• Sub-sessions (spawned via split, indented with connecting lines)

​

Future-Proofing

{s.kind === "diff" ? <DiffPane ... />
 : s.kind === "preview" ? <PreviewPane ... />
 : s.kind === "editor" ? <CodeMirrorPane ... />
 : <TerminalPane ... />  // default
}