From ffb7ef0d21487348fb273889e71672e4e41b1f7f Mon Sep 17 00:00:00 2001 From: Alex Blank Date: Sun, 24 May 2026 11:50:16 +0000 Subject: [PATCH] feat: add session list overhaul proposal - Add proposal for unified session list components - Add design doc with component architecture - Add specs for SessionCard and SessionList requirements - Add implementation tasks Refs: session-list-overhaul --- .../session-list-overhaul/.openspec.yaml | 2 + .../changes/session-list-overhaul/design.md | 60 ++++++++++++ .../changes/session-list-overhaul/proposal.md | 28 ++++++ .../specs/session-list-ui/spec.md | 93 +++++++++++++++++++ .../changes/session-list-overhaul/tasks.md | 53 +++++++++++ 5 files changed, 236 insertions(+) create mode 100644 openspec/changes/session-list-overhaul/.openspec.yaml create mode 100644 openspec/changes/session-list-overhaul/design.md create mode 100644 openspec/changes/session-list-overhaul/proposal.md create mode 100644 openspec/changes/session-list-overhaul/specs/session-list-ui/spec.md create mode 100644 openspec/changes/session-list-overhaul/tasks.md diff --git a/openspec/changes/session-list-overhaul/.openspec.yaml b/openspec/changes/session-list-overhaul/.openspec.yaml new file mode 100644 index 0000000..6894814 --- /dev/null +++ b/openspec/changes/session-list-overhaul/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-05-24 diff --git a/openspec/changes/session-list-overhaul/design.md b/openspec/changes/session-list-overhaul/design.md new file mode 100644 index 0000000..cec125c --- /dev/null +++ b/openspec/changes/session-list-overhaul/design.md @@ -0,0 +1,60 @@ +## Context + +The current session list implementation duplicates rendering logic across `dashboard.tsx` and `sessions.tsx`. Both pages fetch the same data, apply similar filtering (active vs recent/stopped), and render session cards with inconsistent styling and controls. The dashboard has a compact grid view while the sessions page has a list view, but neither provides all control actions (open, stop, start, delete) in a consistent way. + +## Goals / Non-Goals + +**Goals:** +- Unified session card component with all control actions visible and accessible +- Unified session list component that handles filtering, grouping, and empty states +- Consistent visual design across dashboard and sessions pages +- Clear status indicators (running, stopped, error, building, etc.) +- Project/repository context visible on each card +- Responsive layout that works on mobile and desktop + +**Non-Goals:** +- No API changes +- No new session management features (just better UI for existing ones) +- No changes to session creation flow +- No real-time updates beyond existing polling + +## Decisions + +**Decision: Two levels of components** +- `SessionCard`: Individual session display with actions +- `SessionList`: Container that handles grouping and layout +This allows the dashboard to use `SessionList` directly while the sessions page can add additional filtering/controls around it. + +**Decision: Card-based layout over table** +Cards provide better mobile experience and can show richer information (project context, tool icon, status badge). Tables are harder to make responsive. + +**Decision: Inline actions on cards** +Each card shows primary action (Open for running, Start for stopped) and secondary actions in a dropdown or secondary button row. This matches the existing dashboard pattern but makes it consistent. + +**Decision: Status colors** +- Running: green +- Building/Starting/Probing: yellow/amber +- Stopped: gray +- Error: red +- Unhealthy: orange + +## Risks / Trade-offs + +**Risk: Breaking existing dashboard layout** +→ Mitigation: Keep the same grid layout structure, just swap the inner rendering to use SessionCard + +**Risk: Mobile experience with many action buttons** +→ Mitigation: Use icon buttons on mobile, text buttons on desktop. Collapse secondary actions into a "..." menu. + +## Migration Plan + +1. Create SessionCard and SessionList components +2. Update dashboard.tsx to use SessionList +3. Update sessions.tsx to use SessionList +4. Remove old duplicated session rendering code +5. Update styles +6. Test both pages + +## Open Questions + +None diff --git a/openspec/changes/session-list-overhaul/proposal.md b/openspec/changes/session-list-overhaul/proposal.md new file mode 100644 index 0000000..41eb5ca --- /dev/null +++ b/openspec/changes/session-list-overhaul/proposal.md @@ -0,0 +1,28 @@ +## Why + +The current session list UI is fragmented between the dashboard home page and the dedicated sessions page, with duplicated rendering logic, inconsistent styling, and missing control actions. Users need a unified, clear view of their sessions with easy access to controls (start, stop, delete, open) regardless of which page they're on. + +## What Changes + +- Create a unified `SessionCard` component used on both dashboard and sessions pages +- Create a `SessionList` component that handles filtering, grouping, and layout +- Add clear status indicators and action buttons (open, stop, start, delete) to each session card +- Remove duplicated session rendering logic from dashboard.tsx and sessions.tsx +- Consistent empty states and loading states across both pages +- Better visual hierarchy with project/repository context + +## Capabilities + +### New Capabilities +- `session-list-ui`: Unified session list components with clear information display and control buttons + +### Modified Capabilities +- `session-lifecycle-ux`: Update to include unified list component requirements +- `sessions-hub`: Update to use unified components instead of page-specific rendering + +## Impact + +- Frontend: New components in `apps/web/src/components/session-list.tsx` and `apps/web/src/components/session-card.tsx` +- Modified pages: `apps/web/src/pages/dashboard.tsx`, `apps/web/src/pages/sessions.tsx` +- Modified styles: `apps/web/src/styles.css` +- No API changes required diff --git a/openspec/changes/session-list-overhaul/specs/session-list-ui/spec.md b/openspec/changes/session-list-overhaul/specs/session-list-ui/spec.md new file mode 100644 index 0000000..910e89c --- /dev/null +++ b/openspec/changes/session-list-overhaul/specs/session-list-ui/spec.md @@ -0,0 +1,93 @@ +## ADDED Requirements + +### Requirement: Session card displays session information +The system SHALL display each session in a card format showing: +- Tool type name and icon +- Session display name or generated name +- Project and repository name +- Current status with visual indicator +- Clone mode indicator (if clone mode) +- Port number (if applicable) +- Created time + +#### Scenario: View active session card +- **WHEN** user views the sessions list +- **THEN** each running session card shows a green status indicator +- **AND** the card displays the tool type name +- **AND** the card displays the project and repository names +- **AND** the card displays the port number + +#### Scenario: View stopped session card +- **WHEN** user views the sessions list +- **THEN** each stopped session card shows a gray status indicator +- **AND** the card does not display a port number +- **AND** the card shows when it was last active + +#### Scenario: View clone mode session card +- **WHEN** user views a clone-mode session +- **THEN** the card displays a clone indicator +- **AND** the card shows the branch name (if applicable) + +### Requirement: Session card provides control actions +The system SHALL provide action buttons on each session card: +- Running sessions: Open (primary), Stop, Delete +- Stopped sessions: Start (primary), Delete +- Building/Starting sessions: Show progress indicator, no actions +- Error sessions: Show error state, Delete + +#### Scenario: Open running session +- **WHEN** user clicks the "Open" button on a running session card +- **THEN** the session opens in the appropriate interface (web, terminal, IDE) + +#### Scenario: Stop running session +- **WHEN** user clicks the "Stop" button on a running session card +- **THEN** a confirmation dialog appears +- **AND** upon confirmation, the session stops + +#### Scenario: Start stopped session +- **WHEN** user clicks the "Start" button on a stopped session card +- **THEN** the session starts +- **AND** the card updates to show building/starting status + +#### Scenario: Delete session +- **WHEN** user clicks the "Delete" button on any session card +- **THEN** a confirmation dialog appears +- **AND** upon confirmation, the session is deleted +- **AND** the card is removed from the list immediately + +### Requirement: Session list supports grouping and filtering +The system SHALL group sessions by status category: +- Active: running, building, starting, probing +- Recent: stopped, error (limited to last 5) +- The list SHALL support filtering by status + +#### Scenario: View grouped sessions +- **WHEN** user views the sessions page +- **THEN** active sessions appear in an "Active" section +- **AND** recent stopped sessions appear in a "Recent" section +- **AND** each section has a clear heading with count + +### Requirement: Unified components across pages +The system SHALL use the same SessionCard and SessionList components on both the dashboard and sessions pages. + +#### Scenario: Dashboard uses unified components +- **WHEN** user views the dashboard home page +- **THEN** the session grid uses SessionCard components +- **AND** the visual style matches the sessions page + +#### Scenario: Sessions page uses unified components +- **WHEN** user views the sessions page +- **THEN** the session list uses SessionList and SessionCard components +- **AND** the visual style matches the dashboard + +## MODIFIED Requirements + +### Requirement: Sessions page layout +**FROM:** Sessions page renders sessions with page-specific layout and styling +**TO:** Sessions page uses SessionList component with consistent layout and styling + +#### Scenario: Sessions page renders unified list +- **WHEN** user navigates to the sessions page +- **THEN** the page uses the SessionList component +- **AND** sessions are displayed in a card grid +- **AND** each card has consistent control actions diff --git a/openspec/changes/session-list-overhaul/tasks.md b/openspec/changes/session-list-overhaul/tasks.md new file mode 100644 index 0000000..7ddbef3 --- /dev/null +++ b/openspec/changes/session-list-overhaul/tasks.md @@ -0,0 +1,53 @@ +## 1. Create SessionCard Component + +- [ ] 1.1 Create `apps/web/src/components/session-card.tsx` with session display and actions +- [ ] 1.2 Implement status indicator with color coding (running=green, building=yellow, stopped=gray, error=red) +- [ ] 1.3 Display tool type name, session name, project/repo context +- [ ] 1.4 Add clone mode indicator and branch name when applicable +- [ ] 1.5 Implement action buttons: Open (running), Start (stopped), Stop (running), Delete (all) +- [ ] 1.6 Add confirmation dialogs for Stop and Delete actions +- [ ] 1.7 Handle loading states during actions + +## 2. Create SessionList Component + +- [ ] 2.1 Create `apps/web/src/components/session-list.tsx` with grouping logic +- [ ] 2.2 Implement active sessions grouping (running, building, starting, probing) +- [ ] 2.3 Implement recent sessions grouping (stopped, error, limited to last 5) +- [ ] 2.4 Add section headers with counts +- [ ] 2.5 Handle empty states for each section +- [ ] 2.6 Support filtering by status + +## 3. Update Dashboard Page + +- [ ] 3.1 Import SessionCard and SessionList in dashboard.tsx +- [ ] 3.2 Replace existing session grid rendering with SessionList +- [ ] 3.3 Remove duplicated session rendering code +- [ ] 3.4 Ensure "Open sessions" section uses unified components +- [ ] 3.5 Ensure "Recent sessions" section uses unified components + +## 4. Update Sessions Page + +- [ ] 4.1 Import SessionCard and SessionList in sessions.tsx +- [ ] 4.2 Replace existing session list rendering with SessionList +- [ ] 4.3 Remove duplicated session rendering code +- [ ] 4.4 Keep page-level controls (create session button, filters) +- [ ] 4.5 Ensure "Last Session" section uses SessionCard + +## 5. Styles and Polish + +- [ ] 5.1 Add CSS styles for SessionCard layout (responsive grid) +- [ ] 5.2 Add CSS styles for action buttons (icon vs text based on viewport) +- [ ] 5.3 Style status indicators and badges +- [ ] 5.4 Ensure consistent spacing and typography +- [ ] 5.5 Test responsive layout on mobile viewport + +## 6. Testing and Verification + +- [ ] 6.1 Verify dashboard renders sessions correctly +- [ ] 6.2 Verify sessions page renders sessions correctly +- [ ] 6.3 Test action buttons (open, start, stop, delete) +- [ ] 6.4 Test confirmation dialogs +- [ ] 6.5 Test empty states +- [ ] 6.6 Test responsive layout +- [ ] 6.7 Run TypeScript compilation +- [ ] 6.8 Run ESLint