puter/paseo
1
0
Fork 0
mirror of https://github.com/getpaseo/paseo.git synced 2026-07-29 12:01:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add iteration plans for workspace header/layout restore

Browse Source
This commit is contained in:
Mohamed Boudra
2026-03-01 23:18:54 +07:00
parent 16984c138d
commit 18d4df339f
4 changed files with 417 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
EXECUTION_PLAN_ITERATION_3_WORKSPACE_HEADER_TABS_RESTORE.md Normal file
View File

@@ -0,0 +1,60 @@
# Iteration 3 Execution Plan — Paseo Orchestrated
## Principles
- Work happens in an isolated git worktree and merges back to `main` once verified.
- Do not restart or touch the daemon on `localhost:6767`.
- Use the repo’s existing Playwright global setup (isolated daemon/metro) for E2E.
- Pass all gates before merging:
- Typecheck
- Vitest
- Playwright E2E
- Manual `agent-browser` verification
## Agent Delegation (Paseo)
### Implementation agent (1)
- **Agent:** Codex
- **Mode:** full-access
- **Worktree:** `iter3-workspace-header-tabs-restore`
- **Mission:**
- Fix New tab dropdown visibility (on-screen, correct pattern)
- Restore workspace header structure + explorer toggle + agent kebab menu
- Add terminal close (X) from workspace tab strip
- Add/adjust Playwright E2E specs for the above
- Run verification commands before declaring done
### Reviewer (optional, if needed)
- Only used if implementation is large/risky or tests expose subtle regressions.
- Codex or Claude Sonnet as a second-pass reviewer for UI regressions.
## Merge Strategy
1. Agent commits all changes in the worktree.
2. Orchestrator reviews the diff on the worktree.
3. Run gates locally on the worktree:
- `npm run typecheck`
- `npm run test --workspace=@getpaseo/app`
- `npm run test:e2e --workspace=@getpaseo/app`
4. Manual `agent-browser` verification:
- Desktop viewport: New tab menu visible + explorer toggle + kebab menu
- Mobile viewport: explorer icon uses git/folder, toggles right sidebar, left sidebar unaffected
5. Merge worktree back into `main` with a fast-forward merge if possible; otherwise merge commit.
## Verification Checklist (strict)
- [ ] New tab menu opens and is visible (desktop)
- [ ] Selecting Agent tab routes to draft agent flow scoped to workspace
- [ ] Selecting Terminal tab creates terminal and focuses it
- [ ] Terminal tabs show X; closing kills terminal and removes tab
- [ ] Workspace header shows branch name
- [ ] Workspace header has explorer toggle with correct icon behavior
- [ ] Agent kebab menu exists when Agent tab active
- [ ] Right sidebar opens/closes via header and mobile swipe gesture
- [ ] Left sidebar gestures unchanged
- [ ] `npm run typecheck` ✅
- [ ] `npm run test --workspace=@getpaseo/app` ✅
- [ ] `npm run test:e2e --workspace=@getpaseo/app` ✅

113
EXECUTION_PLAN_ITERATION_4_WORKSPACE_HEADER_LAYOUT_RESTORE.md Normal file
View File

@@ -0,0 +1,113 @@
# Execution Plan — Iteration 4 (Paseo-orchestrated)
## Strategy
Use a Paseo-managed implementation agent in an isolated git worktree to patch the workspace screen to restore legacy header/layout parity while keeping tabs. Then review, validate with tests + agent-browser, and merge back to `main`.
## Agents
### 1) Implementation agent (Codex)
- Provider/model: `codex / gpt-5.3-codex`
- Mode: `full-access`
- Worktree: `iter4-workspace-header-layout-restore` (base: `main`)
- Responsibilities:
- Fix `New tab` dropdown to use the established dropdown/menu pattern (not off-screen combobox).
- Restore workspace header explorer toggle parity with legacy `AgentReadyScreen` (icons, aria state).
- Restore agent overflow (kebab) menu when active tab is an agent.
- Add terminal tab close `X` on desktop with confirm + kill terminal mutation.
- Add/extend Playwright E2E specs for `New tab` on-screen + explorer toggle open/close.
- Commit changes.
### 2) Reviewer/validator (you/me)
- Review diffs locally.
- Run:
- `npm run typecheck`
- `npm run test --workspace=@getpaseo/app`
- Targeted Playwright spec(s) for this iteration
- Perform agent-browser manual verification (desktop + mobile viewports).
## Tooling / Commands (canonical)
### Create agent (detached)
```bash
paseo run -d \
--worktree iter4-workspace-header-layout-restore \
--base main \
--provider codex \
--model gpt-5.3-codex \
--mode full-access \
--name "🎭 Iter4 workspace header/layout restore" \
"<paste the implementation prompt>"
```
### Wait
```bash
paseo wait <agent-id>
```
### Review worktree diff
```bash
cd ~/.paseo/worktrees/<hash>/iter4-workspace-header-layout-restore
git status --short --branch
git log -n 5 --oneline
git diff main..HEAD
```
### Merge into main
Prefer `git cherry-pick <commit>` into `/Users/moboudra/dev/paseo` `main` after verification.
## Verification gates (must be green)
### 1) Typecheck
```bash
npm run typecheck
```
### 2) App unit tests
```bash
npm run test --workspace=@getpaseo/app
```
### 3) Playwright E2E (targeted)
Run only the spec(s) for this iteration (avoid unrelated flakes):
```bash
cd packages/app
npx playwright test e2e/workspace-header-tabs-restore.spec.ts
```
## Manual verification (agent-browser)
Use explicit sessions:
```bash
agent-browser --session iter4-desktop open http://localhost:8081
agent-browser --session iter4-mobile open http://localhost:8081
```
Desktop:
- Validate `New tab` dropdown opens on-screen
- Validate explorer toggle opens/closes explorer
- Validate kebab menu appears for agent tabs
- Validate terminal tab `X` close flow
Mobile viewport:
- Validate git/folder icon for explorer toggle
- Validate gestures for left/right sidebars
## Rollback plan
If verification fails:
- Do not merge.
- Patch in worktree until acceptance criteria + gates pass.
- Only then cherry-pick/merge into `main`.

124
PLAN_ITERATION_3_WORKSPACE_HEADER_TABS_RESTORE.md Normal file
View File

@@ -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)

120
PLAN_ITERATION_4_WORKSPACE_HEADER_LAYOUT_RESTORE.md Normal file
View File

@@ -0,0 +1,120 @@
# Iteration 4 — Workspace header/layout restore (tabs + explorer parity)
## Goal
Fix regressions introduced by the workspace-tabs migration by restoring the **legacy workspace/agent screen layout and gestures**, while keeping the new **workspace tab model** (agent + terminal tabs).
This iteration focuses on **header controls + panel layout parity**, and fixing the broken **New tab** menu on desktop.
## Context (what must remain true)
- **Left sidebar** stays as-is (projects/workspaces list) and keeps existing swipe/gesture behavior.
- **Right sidebar** stays as-is (Changes/Files explorer) and keeps existing swipe/gesture behavior.
- **Terminals and agents are first-class tabs**:
- Terminal tabs are not “special” or in a different layout region.
- New tab creation UI must treat agent + terminal options equally (same menu surface).
- Workspace header shows **workspace name (branch name when git, otherwise workspace name)**.
- No “legacy view” routing or duplicate UI kept around; everything uses the new workspace-tabs flow.
- Do **not** touch/restart the main daemon on `:6767`. Tests/dev servers must use isolated ports/homes.
## UX Requirements (desktop + mobile)
### Header structure (parity with legacy AgentReadyScreen)
Workspace screen header must include:
1) **Left sidebar toggle** (same component/gesture behavior as before).
2) **Title** = branch name if git & branch is known; otherwise workspace name.
3) **Right explorer toggle** (same behavior as before):
- Desktop icon: panel/right icon
- Mobile icon: `GitBranch` if git checkout, else `Folder`
- Correct `aria-expanded` state and open/closed coloring
4) **New tab** dropdown button that reliably opens on-screen (desktop + mobile).
5) **Overflow (kebab / 3-dot) menu for agent chat**:
- Visible only when the active tab is an **agent** (i.e. “chat context”).
- Menu items should mirror legacy intent (at minimum: open chat view with full header).
### Tabs
- Tabs remain horizontally scrollable (browser-style).
- Tabs must include an icon per tab type:
- Agent tabs show provider icon (Claude/Codex; fallback bot).
- Terminal tabs show terminal icon.
- Tabs must support closing terminal tabs via `X` (desktop):
- Confirm destructive close.
- Killing terminal updates the list and selects a valid remaining tab (or falls back to workspace root).
### Panel layout
- Keep the screen layout: **header → tabs row → content center → explorer right panel**.
- Do not nest the explorer UI inside tab content in a way that changes layout/gesture wiring.
### Gestures (must not regress)
- Left sidebar open/close gestures unchanged.
- Explorer (right sidebar) open/close gestures unchanged.
- Mobile “open explorer” pan gesture on content remains wired the same as before.
## Acceptance Criteria
### New tab dropdown
- Clicking the `New tab` header button opens a dropdown that is **visible on-screen** on desktop (not positioned off-screen).
- Dropdown contains **two options**:
- Agent tab → opens draft agent flow for that workspace.
- Terminal tab → creates a terminal and opens its tab.
### Workspace header parity
- Header shows both sidebar toggles (left menu + right explorer toggle).
- Right explorer toggle icon matches legacy behavior:
- Mobile: git vs folder icon
- Desktop: panel-right icon
- Explorer toggle opens/closes the explorer reliably and updates `aria-expanded`.
### Agent kebab menu
- When an agent tab is active, the kebab menu is visible and opens correctly.
- When a terminal tab is active, the kebab menu is not shown.
### Tab close
- Terminal tabs display an `X` close affordance on desktop (hover or active).
- Closing a terminal:
- Confirms close
- Calls kill terminal RPC
- Removes the tab from the list
- Focuses a valid remaining tab (or navigates to workspace root if none)
### Regression checks
- Explorer panel remains on the right and behaves the same as before (including gestures).
- Left sidebar gestures remain unchanged.
## Verification
### Automated
- `npm run typecheck` (must pass)
- `npm run test --workspace=@getpaseo/app` (must pass)
- Playwright E2E:
- Add/ensure a spec that asserts `New tab` dropdown opens and is within the viewport.
- Add/ensure a spec that toggles explorer via header button and asserts open/close.
### Manual (agent-browser)
Desktop (Metro web):
- Confirm header shows: left toggle, title, explorer toggle, `New tab` dropdown, kebab menu (agent only).
- Confirm `New tab` dropdown opens and is visible.
- Confirm terminal tab shows `X` close and closes correctly.
Mobile viewport (Metro web responsive):
- Confirm explorer toggle uses git/folder icon.
- Confirm swipes/gestures for sidebars still work.
## Non-goals (explicitly out of scope for this iteration)
- Panel splitting / drag-to-split implementation (architectural compatibility only).
- New workspace creation UX, workspace archiving rules beyond existing behavior.
- Agent hydration/indexing redesign (local SQL DB) beyond current in-memory hydration.