paseo/PLAN_ITERATION_3_WORKSPACE_HEADER_TABS_RESTORE.md

Iteration 3 Plan — Workspace Header + Tabs Restore

Goal

Bring the Workspace screen layout back in line with the pre-tabs “Agent screen” structure (left sidebar + center content + right explorer sidebar), while keeping the new workspace-scoped tabs model (Agent + Terminal tabs) and the project → workspaces sidebar.

This iteration focuses on restoring missing/incorrect UX affordances:

• New tab dropdown must open and be visible.
• Right explorer sidebar must be togglable from the workspace header (with the correct icon behavior).
• Chat overflow (kebab) menu must exist again when an Agent tab is active.
• Terminal tabs must be closable from the workspace tab strip (X), since terminals are first-class tabs.
• Gestures for opening/closing sidebars must remain unchanged.

Non‑Goals (for this iteration)

• Panel splitting / VS Code-style split views (explicitly deferred).
• Changing the existing left sidebar open/close gestures or right explorer swipe gestures (must remain behaviorally identical).
• Introducing a DB / rehydration changes (agent hydration is already handled at startup).

Acceptance Criteria

A. New Tab menu

1. Clicking New tab in the workspace header opens a visible dropdown/menu on desktop web.
2. The menu contains exactly:
   • Agent tab → navigates to the draft agent flow pre-scoped to the current workspace.
   • Terminal tab → creates a new terminal for the current workspace and focuses it.
3. The menu placement is correct (not off-screen), following established in-app patterns.

B. Workspace header parity (restored controls)

1. Workspace header shows workspace name = branch name (as already implemented).
2. Header contains:
   • Left sidebar toggle (existing)
   • Right explorer sidebar toggle (restored)
   • Chat overflow kebab menu (restored) when an Agent tab is active
3. Right explorer toggle icon matches legacy behavior:
   • On mobile: Git workspace → Git icon; non-git → Folder icon
   • Visual “open” state is reflected (muted vs active color).

C. Tabs UX parity

1. Desktop workspace tab strip:
   • Shows provider icon for Agent tabs (Claude/Codex) and terminal icon for Terminal tabs.
   • Terminal tabs include an X close affordance.
2. Closing a terminal tab:
   • Calls the existing kill terminal API
   • Removes the terminal from the workspace tab strip
   • Leaves the workspace in a valid focused state (falls back to another available tab).

D. Right explorer sidebar structure & gestures (no regressions)

1. Explorer sidebar is the same right panel conceptually as before:
   • Not embedded “inside” the tab content surface
   • Toggled by header button and swipe gesture on mobile
2. Gestures remain unchanged:
   • Left sidebar: swipe right to open (mobile), swipe left/backdrop to close
   • Right sidebar: swipe left to open (mobile), swipe right/backdrop/X to close

E. Verification gates

1. npm run typecheck passes.
2. npm run test --workspace=@getpaseo/app (vitest) passes.
3. Playwright E2E:
   • Add/update a spec that proves New tab menu opens and is on-screen.
   • Add/update a spec that toggles the explorer sidebar from the workspace header.
   • Run npm run test:e2e --workspace=@getpaseo/app (uses isolated daemon/metro; must NOT hit :6767).
4. Manual verification with agent-browser (desktop + mobile viewport) confirms:
   • New tab menu visible and clickable
   • Explorer toggle present and works
   • Kebab menu present for Agent tab
   • Terminal close X works

Implementation Outline

1) Workspace header composition

• Refactor packages/app/src/screens/workspace/workspace-screen.tsx header to match the legacy “agent header” affordances:
  • Use the same header primitives used by AgentReadyScreen (MenuHeader, HeaderToggleButton, DropdownMenu).
  • Restore explorer toggle button in the workspace header.
  • Restore agent kebab menu (only when active tab is an Agent tab).

2) New tab dropdown placement fix

• Ensure the New tab dropdown uses a pattern that cannot render off-screen near the top of the viewport:
  • Prefer the existing header-menu pattern (DropdownMenu), or
  • If using Combobox, set an explicit desktopPlacement that renders below the trigger.

3) Terminal tab close affordance

• Add close (X) for terminal tabs in the workspace tab strip.
• Implement a minimal kill-terminal mutation in WorkspaceScreen (mirroring the existing TerminalPane mutation behavior) and ensure focus fallback.

4) E2E coverage

• Add packages/app/e2e/workspace-tabs-header.spec.ts (or similar) covering:
  • New tab menu opening (visible on screen)
  • Explorer toggle presence + open/close behavior

User Flows (must work)

1. Open workspace

   • Tap workspace in sidebar → sidebar closes → workspace screen opens
   • Header shows branch name

2. Open new terminal tab

   • Header → New tab → Terminal tab
   • Terminal appears as a tab (with terminal icon)
   • Terminal is focused

3. Close terminal tab

   • Click X on terminal tab
   • Terminal is killed and disappears from tab strip
   • Focus returns to another tab

4. Toggle explorer

   • Header right icon toggles right sidebar
   • Mobile swipe gesture still opens the right sidebar

5. Agent overflow menu

   • With an Agent tab active, kebab menu opens
   • Menu content appears (parity with previous agent overflow)