feat(web): Dashboard KPI strip + status-forward GameCards (#77)

Closes #60

## Summary

- New `KpiStrip` at the top of `/` — four ops tiles (Servers running,
Spend today, Forecast MTD, Active alerts) each with a top color accent
rule and a 7-bar sparkline driven by `/api/status` +
`/api/costs/estimate` + `/api/costs/actual`.
- `GameCard` redesigned: gradient top-accent rule keyed to state,
Outfit-bold game name above DM Mono hostname (with copy button), status
badge with icon + pulsing/animated dot covering all 5 states (RUNNING /
STARTING / STOPPED / NOT_DEPLOYED / ERROR), 2×2 stats grid (Last run /
Players / $/hr / Task short-id), Start-or-Stop gradient primary +
Files/Logs secondary actions.
- `DashboardPage` adds a client-side search input (filters by game name
or hostname) and switches to a responsive 3 → 2 → 1 column grid.
- e2e specs from #76 realigned with the new design — STOPPED/RUNNING
badges, single-CTA pattern (`Start.toHaveCount(0)` while running) — plus
new specs covering search filter, empty-state on no matches, and KPI
tile rendering.
- `CLAUDE.md` documents the `issue-flow` plugin as the canonical issue →
PR driver, complementing the existing `/pr` command.

## Verification — acceptance criteria mapped to landing

| AC | Where it lives |
|---|---|
| KPI strip renders 4 tiles with live data + sparkline |
`app/packages/web/src/components/KpiStrip.tsx` |
| GameCard uses shadcn Card / Button / Badge from #58 | `GameCard.tsx`
(Card root, Button variants `start`/`stop`/`secondary`/`ghost`, state
Badge) |
| Status badge shows icon + text on all 5 states | `STATE_LABELS` +
`StateIcon` in `GameCard.tsx` |
| Search filter narrows grid in real time | `DashboardPage.tsx`
`useMemo` filter on game name + hostname |
| Start, Stop, Files, Logs reachable from new card | `GameCard.tsx`
action row; Logs links to `/logs` (the route placeholder lands fully in
#63) |
| `npm run app:test` passes; existing tests updated, not deleted | 258
tests pass; no prior GameCard tests existed |

## Implementation notes

- The redesigned card swaps the primary CTA based on state instead of
disabling the inactive one — cleaner UX, but it required updating the
e2e spec from `Start.toBeDisabled()` to `Start.toHaveCount(0)` for
running games.
- KPI sparkline data is currently a single shared `/api/costs/actual`
series across all four tiles (cost itself for the cost tiles; same
series as a coarse activity proxy for Servers running; flat zeros for
Active alerts when count is 0). Per-tile historical series would need
new endpoints.
- Forecast MTD uses average-daily-spend × calendar-days-in-month —
simple extrapolation, no Cost Explorer Forecast API.
- The `Logs` per-card button is `<Link to="/logs">` (asChild). The
`/logs` page is a placeholder until #63 lands — the link exists so the
action is "reachable" per the AC.

## Test plan

- [ ] Local: `npm run app:dev`, browse to `/`, verify the four KPI tiles
render with live values and a 7-bar sparkline beneath each.
- [ ] Type a partial game name or hostname into the search input — grid
narrows in real time; clear it — grid restores.
- [ ] Start a stopped game from a card — primary CTA swaps to Stop after
the 3s refresh; click Files — modal opens; click Logs — navigates to
`/logs`.
- [ ] CI: `npm run app:test` (vitest, 258 tests) and `npm run
app:test:e2e` (Playwright via `.github/workflows/e2e.yml`) both green.


---
_Generated by [Claude
Code](https://claude.ai/code/session_01TiPfpb2vvkRMMXqc9oX5d2)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: CoderCoco

CLAUDE.md

@@ -187,6 +187,22 @@ Use `.worktrees/<branch-name>` for feature work (the directory is gitignored). C
 git worktree add .worktrees/<branch> -b <branch>
 ```
 
+## Claude Code Plugins
+
+This repo expects the **`issue-flow`** plugin (from `CoderCoco/claude-plugin-marketplace`) to drive the issue → PR loop. Two skills, used in order:
+
+- **`work-on`** — start work on a GitHub issue. Creates the `claude/issue-<N>-<slug>` branch, scaffolds a worktree, and pulls the issue checklist into the session as the source of truth for what "done" means.
+- **`open-pr`** — finish the loop. Verifies the issue checklist is actually complete, picks up the repo's PR conventions (the rules in the next section), opens the PR with the right `Closes #N` keyword, and moves the project card to "In Review".
+
+Install once:
+
+```
+/plugin marketplace add CoderCoco/claude-plugin-marketplace
+/plugin install issue-flow@claude-plugin-marketplace
+```
+
+If the plugin isn't loaded in the current environment, fetch the skill body from the marketplace repo and follow it manually — don't fall back to ad-hoc PR creation, because the skills enforce checklist-completeness and the closing keyword that this repo's `/pr` command takes for granted.
+
 ## PR Conventions
 
 - **Always use `/pr` to create pull requests.** The `.claude/commands/pr.md` skill validates the title format before calling the API. Never call `mcp__github__create_pull_request` directly without running this check first.

app/packages/web/e2e/fixtures/game-data.ts

@@ -1,4 +1,4 @@
-import type { GameStatus, CostEstimates, EnvInfo, WatchdogConfig } from '../../src/api.js';
+import type { GameStatus, CostEstimates, EnvInfo, WatchdogConfig, ActualCosts } from '@/api.js';
 
 /** Stub response for `GET /api/env`. */
 export const ENV_DATA: EnvInfo = {
@@ -48,3 +48,19 @@ export const COST_DATA: CostEstimates = {
   },
   totalPerHourIfAllOn: 0.08,
 };
+
+/** Stub response for `GET /api/costs/actual` — 7 days of synthetic spend used by the KPI sparklines. */
+export const ACTUAL_COSTS: ActualCosts = {
+  daily: [
+    { date: '2026-04-26', cost: 0.42 },
+    { date: '2026-04-27', cost: 0.31 },
+    { date: '2026-04-28', cost: 0.55 },
+    { date: '2026-04-29', cost: 0.18 },
+    { date: '2026-04-30', cost: 0.27 },
+    { date: '2026-05-01', cost: 0.40 },
+    { date: '2026-05-02', cost: 0.35 },
+  ],
+  total: 2.48,
+  currency: 'USD',
+  days: 7,
+};

app/packages/web/e2e/fixtures/index.ts

@@ -1,16 +1,20 @@
 import { test as base, type Page } from '@playwright/test';
-import type { GameStatus, CostEstimates, EnvInfo, ActionResult, WatchdogConfig } from '../../src/api.js';
-import { ENV_DATA, STOPPED_GAME, COST_DATA, WATCHDOG_CONFIG } from './game-data.js';
+import type { GameStatus, CostEstimates, EnvInfo, ActionResult, WatchdogConfig, ActualCosts } from '@/api.js';
+import { ENV_DATA, STOPPED_GAME, COST_DATA, WATCHDOG_CONFIG, ACTUAL_COSTS } from './game-data.js';
+import { AppLayout, AuthGatePage, DashboardPage } from '../pages/index.js';
 
-export type { GameStatus, CostEstimates, EnvInfo, WatchdogConfig };
-export { ENV_DATA, STOPPED_GAME, RUNNING_GAME, MULTI_GAME_STATUSES, COST_DATA, WATCHDOG_CONFIG } from './game-data.js';
+export type { GameStatus, CostEstimates, EnvInfo, WatchdogConfig, ActualCosts };
+export { ENV_DATA, STOPPED_GAME, RUNNING_GAME, MULTI_GAME_STATUSES, COST_DATA, WATCHDOG_CONFIG, ACTUAL_COSTS } from './game-data.js';
+export { AppLayout, AuthGatePage, DashboardPage } from '../pages/index.js';
 
 /** Per-spec overrides for the default `/api/*` stubs registered by `stubApis`. */
 export interface StubOptions {
   /** Game statuses returned by `GET /api/status`. Defaults to `[STOPPED_GAME]`. */
   statuses?: GameStatus[];
   /** Cost estimates returned by `GET /api/costs/estimate`. */
   costs?: CostEstimates;
+  /** Daily actual spend returned by `GET /api/costs/actual` (drives KPI sparklines). */
+  actualCosts?: ActualCosts;
   /** Env info returned by `GET /api/env`. */
   env?: EnvInfo;
   /** Watchdog config returned by `GET /api/config`. */
@@ -32,6 +36,7 @@ export interface StubOptions {
 export async function stubApis(page: Page, opts: StubOptions = {}): Promise<void> {
   const statuses = opts.statuses ?? [STOPPED_GAME];
   const costs = opts.costs ?? COST_DATA;
+  const actualCosts = opts.actualCosts ?? ACTUAL_COSTS;
   const env = opts.env ?? ENV_DATA;
   const config = opts.config ?? WATCHDOG_CONFIG;
   const startResult: ActionResult = opts.startResult ?? { success: true, message: 'Started' };
@@ -52,6 +57,8 @@ export async function stubApis(page: Page, opts: StubOptions = {}): Promise<void
 
   await page.route('**/api/costs/estimate', (route) => route.fulfill({ json: costs }));
 
+  await page.route('**/api/costs/actual*', (route) => route.fulfill({ json: actualCosts }));
+
   await page.route('**/api/config', (route) => {
     if (route.request().method() === 'POST') {
       return route.fulfill({ json: { success: true, config } });
@@ -69,9 +76,17 @@ export async function stubApis(page: Page, opts: StubOptions = {}): Promise<void
 type E2EFixtures = {
   /**
    * A page with `apiToken` pre-seeded in localStorage so every navigation
-   * starts authenticated. Use this in all specs except auth-gate tests.
+   * starts authenticated. Use this in specs that need raw page access (e.g.
+   * to call `stubApis` or `addInitScript`); prefer `dashboard` / `layout`
+   * for higher-level interactions.
    */
   authedPage: Page;
+  /** Page object for the dashboard route — use in any authed-dashboard spec. */
+  dashboard: DashboardPage;
+  /** Page object for the persistent nav shell (sidebar + top bar). */
+  layout: AppLayout;
+  /** Page object for the API-token modal — use in auth-gate specs. */
+  authGate: AuthGatePage;
 };
 
 export const test = base.extend<E2EFixtures>({
@@ -81,6 +96,19 @@ export const test = base.extend<E2EFixtures>({
     });
     await use(page);
   },
+  // `dashboard` depends on `authedPage` because every authed-dashboard spec
+  // wants the token pre-seeded. `layout` and `authGate` depend on the raw
+  // `page` so auth-gate specs (which exercise the unauthenticated state) can
+  // use them without dragging the init script along.
+  dashboard: async ({ authedPage }, use) => {
+    await use(new DashboardPage(authedPage));
+  },
+  layout: async ({ page }, use) => {
+    await use(new AppLayout(page));
+  },
+  authGate: async ({ page }, use) => {
+    await use(new AuthGatePage(page));
+  },
 });
 
 export { expect } from '@playwright/test';

app/packages/web/e2e/pages/AppLayout.ts

@@ -0,0 +1,26 @@
+import type { Page, Locator } from '@playwright/test';
+
+/**
+ * Page object for the persistent navigation shell rendered by `AppLayout.tsx`
+ * (sidebar + top bar). Encapsulates locators that are shared across every
+ * authenticated route so individual specs don't reach into the layout chrome.
+ */
+export class AppLayout {
+  constructor(public readonly page: Page) {}
+
+  /** Top-bar product heading — used as a "the dashboard mounted" smoke check. */
+  brandHeading(): Locator {
+    return this.page.getByRole('heading', { name: 'Game Server Manager' });
+  }
+
+  /** Sidebar nav link by visible label (e.g. "Logs", "Discord", "Settings"). */
+  sidebarLink(label: string): Locator {
+    return this.page.getByRole('link', { name: label });
+  }
+
+  /** Click a sidebar nav link and wait for the URL to change to `expectedPath`. */
+  async navigateTo(label: string, expectedPath: string): Promise<void> {
+    await this.sidebarLink(label).click();
+    await this.page.waitForURL(expectedPath);
+  }
+}

app/packages/web/e2e/pages/AuthGatePage.ts

@@ -0,0 +1,31 @@
+import type { Page, Locator } from '@playwright/test';
+
+/**
+ * Page object for the API-token modal rendered by `ApiTokenModal.tsx` when an
+ * `/api/*` request returns 401. Used by auth-gate specs to assert the modal
+ * appears and to drive the token-save → reload flow.
+ */
+export class AuthGatePage {
+  constructor(public readonly page: Page) {}
+
+  /** Modal heading — visible whenever the auth gate is active. */
+  modalHeading(): Locator {
+    return this.page.getByRole('heading', { name: 'API token required' });
+  }
+
+  /** API-token text input inside the modal. */
+  tokenInput(): Locator {
+    return this.page.getByPlaceholder('API token');
+  }
+
+  /** "Save & reload" submit button — persists the token to localStorage and reloads. */
+  submitButton(): Locator {
+    return this.page.getByRole('button', { name: 'Save & reload' });
+  }
+
+  /** Fill the token field and click submit in one call. */
+  async submit(token: string): Promise<void> {
+    await this.tokenInput().fill(token);
+    await this.submitButton().click();
+  }
+}

app/packages/web/e2e/pages/DashboardPage.ts

@@ -0,0 +1,81 @@
+import type { Page, Locator } from '@playwright/test';
+
+/** Status-badge labels rendered by the redesigned `GameCard` (issue #60). */
+export type ServerStateLabel =
+  | 'RUNNING'
+  | 'STARTING'
+  | 'STOPPED'
+  | 'NOT DEPLOYED'
+  | 'ERROR';
+
+/**
+ * Page object for the dashboard route (`/`). Wraps the KPI strip, the search
+ * filter, the GameCard grid, and the per-card action buttons so spec files
+ * read as test logic rather than locator soup.
+ */
+export class DashboardPage {
+  constructor(public readonly page: Page) {}
+
+  /** Navigate to the dashboard root. */
+  async goto(): Promise<void> {
+    await this.page.goto('/');
+  }
+
+  // ── GameCard grid ────────────────────────────────────────────────────
+
+  /** `<h3>` element inside a card whose game name matches `name`. */
+  gameCardHeading(name: string): Locator {
+    return this.page.getByRole('heading', { name });
+  }
+
+  /** Status badge by its rendered text label (RUNNING / STOPPED / etc.). */
+  statusBadge(state: ServerStateLabel): Locator {
+    return this.page.getByText(state);
+  }
+
+  /** Empty-state when the operator hasn't configured any games at all. */
+  emptyConfiguredMessage(): Locator {
+    return this.page.getByText(/no games configured/i);
+  }
+
+  /** Empty-state when the search input filters out every card. */
+  emptySearchMessage(): Locator {
+    return this.page.getByText(/no games match/i);
+  }
+
+  // ── Card action buttons ──────────────────────────────────────────────
+
+  /** Primary CTA shown on a stopped/not-deployed/error card. */
+  startButton(): Locator {
+    return this.page.getByRole('button', { name: 'Start' });
+  }
+
+  /** Primary CTA shown on a running/starting card. */
+  stopButton(): Locator {
+    return this.page.getByRole('button', { name: 'Stop' });
+  }
+
+  // ── Search filter ────────────────────────────────────────────────────
+
+  /** Search input above the grid that filters by game name or hostname. */
+  searchInput(): Locator {
+    return this.page.getByLabel('Filter games');
+  }
+
+  /** Type into the search input and let React rerender the filtered grid. */
+  async filter(query: string): Promise<void> {
+    await this.searchInput().fill(query);
+  }
+
+  // ── KPI strip ────────────────────────────────────────────────────────
+
+  /** A KPI tile by its label ('Servers running', 'Spend today', etc.). */
+  kpiTileLabel(label: string): Locator {
+    return this.page.getByText(label);
+  }
+
+  /** The "Servers running" KPI value (e.g. "1/2"). */
+  serversRunningValue(value: string): Locator {
+    return this.page.getByText(value, { exact: true });
+  }
+}

app/packages/web/e2e/pages/index.ts

@@ -0,0 +1,3 @@
+export { AppLayout } from './AppLayout.js';
+export { AuthGatePage } from './AuthGatePage.js';
+export { DashboardPage, type ServerStateLabel } from './DashboardPage.js';

app/packages/web/e2e/specs/auth-gate.spec.ts

@@ -1,32 +1,33 @@
-import { test, expect } from '@playwright/test';
-import { stubApis, ENV_DATA, COST_DATA } from '../fixtures/index.js';
+import { test, expect, stubApis, ENV_DATA, COST_DATA } from '../fixtures/index.js';
 
 /**
- * Auth-gate specs use the base Playwright `test` (no pre-seeded token) so
- * they can verify the 401 → modal and token-save → reload flows in isolation.
+ * Auth-gate specs use the base Playwright `page` (no pre-seeded token) so they
+ * can verify the 401 → modal and token-save → reload flows in isolation. The
+ * `authGate` page object encapsulates the modal locators; raw `page` is still
+ * needed for direct route stubbing and `addInitScript`.
  */
 
 test.describe('auth gate', () => {
-  test('should show token modal when API returns 401', async ({ page }) => {
+  test('should show token modal when API returns 401', async ({ page, authGate }) => {
     await page.route('**/api/**', (route) =>
       route.fulfill({ status: 401, body: 'Unauthorized' })
     );
     await page.goto('/');
-    await expect(page.getByRole('heading', { name: 'API token required' })).toBeVisible();
+    await expect(authGate.modalHeading()).toBeVisible();
   });
 
-  test('should load dashboard when valid token is already stored', async ({ page }) => {
+  test('should load dashboard when valid token is already stored', async ({ page, authGate, layout }) => {
     await page.addInitScript(() => {
       localStorage.setItem('apiToken', 'test-token');
     });
     await stubApis(page, { statuses: [] });
     await page.goto('/');
-    // Top-bar heading is the dashboard shell; modal should not appear.
-    await expect(page.getByRole('heading', { name: 'Game Server Manager' })).toBeVisible();
-    await expect(page.getByRole('heading', { name: 'API token required' })).not.toBeVisible();
+    // Dashboard shell mounts, modal does not.
+    await expect(layout.brandHeading()).toBeVisible();
+    await expect(authGate.modalHeading()).not.toBeVisible();
   });
 
-  test('should save token and show dashboard after reload', async ({ page }) => {
+  test('should save token and show dashboard after reload', async ({ page, authGate, layout }) => {
     // Playwright matches routes in REVERSE registration order, so register the
     // catch-all 404 FIRST and the specific 401/200 handlers after — otherwise
     // the catch-all takes precedence and the modal never triggers.
@@ -60,13 +61,12 @@ test.describe('auth gate', () => {
     });
 
     await page.goto('/');
-    await expect(page.getByRole('heading', { name: 'API token required' })).toBeVisible();
+    await expect(authGate.modalHeading()).toBeVisible();
 
-    await page.getByPlaceholder('API token').fill('my-test-token');
-    await page.getByRole('button', { name: 'Save & reload' }).click();
+    await authGate.submit('my-test-token');
 
     // After reload the stored token is sent; the modal must be gone.
-    await expect(page.getByRole('heading', { name: 'Game Server Manager' })).toBeVisible();
-    await expect(page.getByRole('heading', { name: 'API token required' })).not.toBeVisible();
+    await expect(layout.brandHeading()).toBeVisible();
+    await expect(authGate.modalHeading()).not.toBeVisible();
   });
 });