Add iteration plans for workspace header/layout restore

2026-03-01 23:18:54 +07:00
parent 16984c138d
commit 18d4df339f
4 changed files with 417 additions and 0 deletions
@@ -0,0 +1,124 @@
+# 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)
+