TheRock/rocm-systems/emulation/mirage/dashboard/web/USER_STORIES.md

Mirage Dashboard – User Stories

The dashboard is the visual control plane for mirage. The goal is a desktop-class experience inspired by Docker Desktop (resource cards, prominent status, persistent left rail, command bar) and the iOS Simulator (single hero device card, scoped device-detail toolbar, plays of subtle motion when state changes).

Every story has acceptance criteria. The e2e/dashboard.spec.ts Playwright suite covers each one end-to-end via the same daemon binary the user runs.

Personas

• DevOps Diego — runs a long-lived mirage daemon and uses the dashboard to inspect profiles and clean up stale sessions.
• Researcher Rita — wants to launch a one-off session, attach to a command, see its output stream, and tear it down.
• Plugin author Pat — needs to see what emulator backends are installed on this host and which plugins they expose.

1. Overview at a glance (Diego)

As a dashboard user I want the first screen to show me how many profiles and sessions exist, the health of each running session, and where on disk mirage stores its data so that I can confirm the daemon is healthy in under three seconds.

Acceptance criteria

• The route / renders a 4-card metric strip: Profiles, Sessions, Healthy, Execs running (last number aggregates across sessions).
• Every metric card is keyboard-focusable and links to its detail page.
• A Storage panel lists the five XDG-derived paths in a copy-friendly table.
• A System panel shows the daemon version + the list of detected emulator backends (each with an installed / not installed badge).
• The page polls /api/sessions every 3 s and updates without a full reload.

2. Browse and create profiles (Pat)

As a plugin author I want to pick the emulator backend from a dropdown (showing which are installed locally) and choose plugins from a multi-select so that I never have to remember which emulator strings the daemon accepts.

Acceptance criteria

• /profiles lists every profile in a sortable table with: name, emulator badge, nodes, GPUs/node, exec mode, description.
• A primary New profile… button opens a modal with:
  • Name field (required, lowercased automatically).
  • Emulator dropdown populated from /api/emulators (shows installed badge per entry; defaults to the daemon's default_emulator).
  • Nodes / GPUs per node number steppers.
  • Exec mode segmented control (Functional / Clocked).
  • Plugins multi-select fed by the chosen emulator's available_plugins list.
  • Description textarea.
• The modal validates the name, disables submit while inflight, surfaces daemon errors inline, and closes on success while triggering a table refresh.
• Each profile row exposes a kebab menu with Duplicate, Edit JSON, Delete (Delete asks for confirmation in a modal, not a confirm()).

3. Launch a session and watch it boot (Rita)

As a researcher I want to start a session against a profile and watch the health badge transition from pending → starting → ready so that I know exactly when I can attach an exec.

Acceptance criteria

• /sessions shows every session as a card (iOS-simulator-style), not just a row: profile name, ID, age, health badge, exec count.
• Cards expose Open, Stop, and Copy ID.
• A persistent toolbar carries New session…, a profile filter dropdown, and a Refresh button.
• Starting a session opens a modal pre-filled with the most-recently used profile. While the session is starting the card shows an animated badge and a progress shimmer.
• The status badge derives from health.state plus health.healthy (pending/starting/ready/unhealthy/terminal).

4. Drive an exec with live output (Rita)

As a researcher I want to type a shell command, hit run, and see streamed output in a real terminal pane (xterm) so that I can iterate on a debug command without leaving the browser.

Acceptance criteria

• /sessions/:id shows session metadata in a hero card, then a two-column layout: exec list on the left, attached terminal on the right.
• The terminal is an xterm.js instance bound to the daemon /attach WebSocket. Resize the column → terminal resizes.
• A command palette at the bottom: command input, + env-var chip input (KEY=VALUE), keep checkbox, Run button. Submitting selects the new exec automatically.
• Each exec row shows: id, started timestamp, runtime, exit code (red if non-zero, green if 0, neutral while running), kebab menu (Attach, Send SIGINT, Send SIGKILL, Remove).
• The kebab is keyboard-navigable.

5. Trust the dashboard's status (Diego)

As an operator I want transient daemon failures (network blip, 500 from the API) to show as a toast that I can dismiss so that I don't lose state when one request fails.

Acceptance criteria

• Every page registers a global toast handler. API errors push a toast with the HTTP status + message; toasts auto-dismiss after 6 s.
• Toasts stack bottom-right, are keyboard-dismissable (Esc).
• A success toast appears after profile create, session create, session destroy, and exec remove.

6. Keyboard-first navigation (everyone)

• g o, g p, g s navigate to Overview / Profiles / Sessions.
• Cmd/Ctrl-K opens a command palette (out of scope for this PR, but the layout reserves the slot in the header).
• Sidebar links are reachable via Tab and respect :focus-visible.