code-coordinator 0.5.46__py3-none-any.whl

coord/dashboard/webapp/e2e/live-update-fixture.spec.ts

@@ -0,0 +1,113 @@
+/**
+ * Live update against a REAL `coord web --fixture` process (#1551, M-W1's
+ * exit gate).
+ *
+ * `realtime.spec.ts` proves the app reacts correctly to the SSE wire shape
+ * `coord/events.py` / `coord/dashboard/fixture.py` claim to emit, using a
+ * hand-rolled fake `EventSource` -- fast and deterministic, but it can never
+ * catch the wire shape itself drifting (a rename, a missing `event:` line, a
+ * JSON encoding bug) because nothing on the other end is real. This file is
+ * the one spec in the repo that boots the actual `coord web --fixture`
+ * server (`fixtureServer.ts`) and drives a real browser `EventSource`
+ * against it end to end:
+ *
+ *   1. a genuine `/events` connection reaches "Live" -- proves the real wire
+ *      format parses;
+ *   2. `POST /api/fixture/events/replay` (the fixture's scripted-event
+ *      trigger, `coord/dashboard/fixture.py`'s `ScriptedEvent`) causes a
+ *      real, unprompted `GET /api/pipeline` refetch -- "no manual refresh";
+ *   3. killing the server process (not a route interception -- the actual
+ *      subprocess) makes the badge honestly report the stream is gone.
+ *
+ * What this does NOT (and structurally cannot) prove: that the refetched
+ * data itself changes. `FixtureServer.board()` rebuilds the same static
+ * `board_payload` on every call by design (#1538's whole point is a board
+ * that "does not move under" an assertion) -- a scripted event announces a
+ * change, it does not enact one. So step 2 asserts the real live-update
+ * *mechanism* (event -> invalidation -> refetch, with no test-driven
+ * reload/click), not a visible content diff; `realtime.spec.ts` already
+ * covers "the badge/card text actually changes" against a fake transport
+ * that CAN mutate its own seed mid-test.
+ *
+ * Slower than the rest of this suite -- a production build plus a real
+ * subprocess boot, on top of Playwright's own browser launch. Recorded here
+ * rather than hidden: this file alone typically adds several seconds to
+ * `npm run test:e2e`. If that ever becomes disruptive, split it into its own
+ * `npm run test:e2e:live` script rather than skipping the coverage.
+ *
+ * Run: npm run test:e2e (requires `coord` on $PATH, see fixtureServer.ts)
+ */
+import { test, expect } from '@playwright/test'
+import { startFixtureServer, type FixtureServerHandle } from './fixtureServer'
+
+test.describe.configure({ mode: 'serial' })
+
+test.describe('live update against a real coord web --fixture process (#1551)', () => {
+  let server: FixtureServerHandle
+
+  test.beforeAll(async () => {
+    server = await startFixtureServer()
+  })
+
+  test.afterAll(async () => {
+    await server?.stop()
+  })
+
+  test('a real SSE connection reaches Live, and a scripted event triggers an unprompted refetch', async ({
+    page,
+  }) => {
+    const pipelineRequests: number[] = []
+    page.on('request', (req) => {
+      if (new URL(req.url()).pathname === '/api/pipeline') pipelineRequests.push(Date.now())
+    })
+
+    await page.goto(server.baseUrl)
+
+    // Seeded fixture: one running item (#4101), among others -- proves the
+    // real dist bundle booted against the real fixture data. `#4101` shows up
+    // twice (the Live sessions card and the pipeline card both surface the
+    // same seeded assignment) -- `.first()` only cares that at least one is
+    // there, not which.
+    await expect(page.getByText('#4101').first()).toBeVisible()
+
+    const badge = page.getByRole('status', { name: /Connection:/ })
+    await expect(badge).toHaveText('Live', { timeout: 10_000 })
+
+    const requestsBeforeReplay = pipelineRequests.length
+    expect(requestsBeforeReplay).toBeGreaterThan(0)
+
+    // The fixture's scripted sequence (tests/fixtures/board-pipeline-basic.json
+    // `events`) -- played over the REAL /events stream, not injected into the
+    // page. Nothing here reloads the page or clicks a refresh control.
+    const replay = await page.request.post(`${server.baseUrl}/api/fixture/events/replay`)
+    expect(replay.ok()).toBe(true)
+
+    await expect
+      .poll(() => pipelineRequests.length, { timeout: 5_000 })
+      .toBeGreaterThan(requestsBeforeReplay)
+  })
+
+  test('killing the server surfaces the disconnected state', async ({ page }) => {
+    await page.goto(server.baseUrl)
+
+    const badge = page.getByRole('status', { name: /Connection:/ })
+    await expect(badge).toHaveText('Live', { timeout: 10_000 })
+
+    // A real process death, not a route interception -- the honest-disconnect
+    // criterion this test exists to prove is that the browser's own
+    // `EventSource` onerror fires against a genuinely severed connection.
+    server.kill()
+
+    await expect(badge).toContainText('Stale since', { timeout: 10_000 })
+
+    // Deliberately not also asserting "Reconnecting…" here: against a truly
+    // dead port every retry fails via an essentially instant connection
+    // refusal, so `connection.ts`'s 'reconnecting' state is a single-tick
+    // flash between backoff timers rather than something Playwright's poll
+    // can reliably sample -- flaky by construction, not by mistake. The
+    // disconnected -> reconnecting -> live transition is already pinned
+    // deterministically by `realtime.spec.ts`'s fake-EventSource test, where
+    // the test (not a dead socket) controls exactly when each state change
+    // happens.
+  })
+})

coord/dashboard/webapp/e2e/realtime.spec.ts

@@ -0,0 +1,238 @@
+/**
+ * E2E tests for the SSE-driven live data layer (#1549).
+ *
+ * There's no Playwright `routeEventSource()` (unlike `routeWebSocket()`,
+ * which `terminal.spec.ts` uses for the PTY bridge) and `page.route()` can
+ * only fulfil a static, connection-closing body -- not a genuinely long-lived
+ * push stream. So this suite injects a controllable fake `EventSource` as
+ * `window.EventSource` via `page.addInitScript()`, the same technique
+ * `terminal.spec.ts` uses for its fake WebSocket, just hand-rolled since
+ * Playwright has no built-in for this transport. Every assertion here is
+ * driven by explicit `emitOpen`/`emitError`/`emitMessage` calls standing in
+ * for a real `coord web --fixture <board.json>` scripted SSE sequence
+ * (`coord/dashboard/fixture.py`'s `ScriptedEvent` -- `{type, data, after}`
+ * played over `/events`); the wire shape (`event: <type>` + JSON `data:`)
+ * is identical, only the transport is faked, exactly like every other spec
+ * in this suite fakes its own backend per playwright.config.ts's contract.
+ *
+ * Run:  npm run test:e2e
+ */
+
+import { test, expect, type Page } from '@playwright/test'
+
+// ── Fake EventSource injection ──────────────────────────────────────────────
+
+/**
+ * Installs `window.EventSource` before any app script runs, and a
+ * `window.__sse` control surface the test drives from Node via
+ * `page.evaluate()`. Must be called before `page.goto()`.
+ */
+async function installFakeEventSource(page: Page): Promise<void> {
+  await page.addInitScript(() => {
+    class FakeEventSource {
+      url: string
+      closed = false
+      onopen: ((ev: unknown) => void) | null = null
+      onerror: ((ev: unknown) => void) | null = null
+      private listeners: Record<string, Array<(ev: { data: string }) => void>> = {}
+
+      constructor(url: string) {
+        this.url = url
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ;(window as any).__sse.instances.push(this)
+      }
+
+      addEventListener(type: string, cb: (ev: { data: string }) => void): void {
+        ;(this.listeners[type] ??= []).push(cb)
+      }
+
+      close(): void {
+        this.closed = true
+      }
+
+      emitOpen(): void {
+        this.onopen?.({})
+      }
+
+      emitError(): void {
+        this.onerror?.({})
+      }
+
+      emitMessage(type: string, data: unknown): void {
+        for (const cb of this.listeners[type] ?? []) cb({ data: JSON.stringify(data) })
+      }
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ;(window as any).__sse = { instances: [] as FakeEventSource[] }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ;(window as any).EventSource = FakeEventSource
+  })
+}
+
+/** Number of currently-open (non-superseded) fake EventSource instances. */
+function openCount(page: Page): Promise<number> {
+  return page.evaluate(() => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sse = (window as any).__sse
+    return sse.instances.filter((i: { closed: boolean }) => !i.closed).length
+  })
+}
+
+/** Runs `fn` (by name) against the current open instance -- 'open' | 'error' | ['message', type, data]. */
+async function emit(
+  page: Page,
+  action: 'open' | 'error' | { message: [string, unknown] },
+): Promise<void> {
+  await page.waitForFunction(() => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sse = (window as any).__sse
+    return sse.instances.filter((i: { closed: boolean }) => !i.closed).length === 1
+  })
+  await page.evaluate((act) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sse = (window as any).__sse
+    const open = sse.instances.filter((i: { closed: boolean }) => !i.closed)
+    const inst = open[open.length - 1]
+    if (act === 'open') inst.emitOpen()
+    else if (act === 'error') inst.emitError()
+    else inst.emitMessage(act.message[0], act.message[1])
+  }, action)
+}
+
+// ── Seeded pipeline data (mutable across the fetch lifetime) ────────────────
+
+function makeItem(currentStage: string) {
+  return {
+    assignment_id: 'work-1',
+    issue_number: 42,
+    issue_title: 'Fix the dashboard rendering',
+    repo_name: 'api',
+    machine_name: 'laptop',
+    current_stage: currentStage,
+    stages: [
+      { name: 'coding', status: currentStage === 'coding' ? 'active' : 'completed', is_current: currentStage === 'coding' },
+      { name: 'review', status: 'waiting', is_current: false },
+      { name: 'smoke', status: 'waiting', is_current: false },
+      { name: 'merge', status: 'waiting', is_current: false },
+    ],
+    available_gates: [],
+    progress_pct: 20,
+    review_findings_pending: false,
+    review_verdict: null,
+    review_verdict_original: null,
+    review_verdict_override_reason: null,
+    review_findings_body: null,
+    test_verdict: null,
+    needs_attention: false,
+    needs_attention_reason: null,
+    needs_attention_detail: null,
+    finished_at: null,
+  }
+}
+
+/** Serves /api/pipeline from a mutable box so a test can change it mid-run. */
+async function mockPipeline(page: Page, box: { stage: string }): Promise<void> {
+  await page.route('**/api/pipeline', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([makeItem(box.stage)]),
+    }),
+  )
+  await page.route('**/api/sessions', (route) =>
+    route.fulfill({ status: 200, contentType: 'application/json', body: '[]' }),
+  )
+  await page.route('**/api/board', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ round_number: 1, active: [], completed: [] }),
+    }),
+  )
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+test.describe('SSE live data layer (#1549)', () => {
+  /**
+   * The board-change acceptance criterion: a scripted SSE event changes what
+   * the *next* /api/pipeline fetch would return, and the card updates with
+   * no manual refresh action from the test -- only the invalidation the
+   * event triggers.
+   */
+  test('a board change (assignment_failed) is reflected on Home with no manual refresh', async ({
+    page,
+  }) => {
+    const pipelineState = { stage: 'coding' }
+    await installFakeEventSource(page)
+    await mockPipeline(page, pipelineState)
+
+    await page.goto('/')
+
+    // Initial state: running.
+    await expect(page.getByText('running', { exact: true })).toBeVisible()
+
+    await emit(page, 'open')
+
+    // The server-side state changes (as if a worker just failed) and the
+    // scripted event announces it -- exactly the shape
+    // coord/events.py publish_assignment_failed / fixture.py ScriptedEvent
+    // put on the wire.
+    pipelineState.stage = 'failed'
+    await emit(page, { message: ['assignment_failed', { assignment_id: 'work-1' }] })
+
+    // No reload, no click -- the badge flips from the SSE-triggered refetch alone.
+    await expect(page.getByText('failed', { exact: true })).toBeVisible({ timeout: 5_000 })
+  })
+
+  /**
+   * The honest connection-state criterion: killing and restoring the stream
+   * shows disconnected -> reconnecting -> live, via the header's
+   * ConnectionBadge (role="status").
+   */
+  test('killing and restoring the stream shows disconnected -> reconnecting -> live', async ({
+    page,
+  }) => {
+    await installFakeEventSource(page)
+    await mockPipeline(page, { stage: 'coding' })
+
+    await page.goto('/')
+
+    const badge = page.getByRole('status', { name: /Connection:/ })
+    await expect(badge).toBeVisible()
+
+    await emit(page, 'open')
+    await expect(badge).toHaveText('Live', { timeout: 5_000 })
+
+    // Kill it.
+    await emit(page, 'error')
+    await expect(badge).toContainText('Stale since', { timeout: 5_000 })
+
+    // Backoff fires (default schedule's first delay, ~1s +/- jitter) and a
+    // fresh attempt starts.
+    await expect(badge).toHaveText('Reconnecting…', { timeout: 5_000 })
+
+    // Restore it.
+    await emit(page, 'open')
+    await expect(badge).toHaveText('Live', { timeout: 5_000 })
+  })
+
+  /**
+   * Guards the StrictMode double-mount trap this module's doc comments
+   * describe (connection.ts, RealtimeProvider.tsx): the dev server runs
+   * React 18 StrictMode, so mounting Home for real must settle to exactly
+   * one open stream, not leak a socket per re-render.
+   */
+  test('settles to exactly one open stream under StrictMode dev double-mount', async ({
+    page,
+  }) => {
+    await installFakeEventSource(page)
+    await mockPipeline(page, { stage: 'coding' })
+
+    await page.goto('/')
+    await expect(page.getByText('running', { exact: true })).toBeVisible()
+
+    expect(await openCount(page)).toBe(1)
+  })
+})

coord/dashboard/webapp/e2e/shell.spec.ts

@@ -0,0 +1,309 @@
+/**
+ * E2E coverage for the responsive shell (#1547) — "acceptance coverage at both
+ * breakpoints (Playwright viewport sizes)".
+ *
+ * `smoke.spec.ts` is pinned to a phone and guards the narrow app's existing
+ * flows; this file drives the layouts that only exist in a real browser with
+ * real layout: the three-column wide composition, the mid-width icon rail +
+ * detail overlay, and the persistence of panel geometry across a reload.
+ *
+ * Everything is asserted through `[data-region="…"]`-scoped locators rather
+ * than page-wide text, because the point of the wide layout is that the same
+ * issue title is legitimately on screen twice (once as a list row, once as the
+ * detail heading) — a page-wide `getByText` would be a strict-mode violation
+ * *by design*.
+ *
+ * Run: npm run test:e2e
+ */
+
+import { test, expect, type Page } from '@playwright/test'
+
+const PHONE = { width: 390, height: 844 }
+const TABLET = { width: 900, height: 900 }
+const DESKTOP = { width: 1440, height: 900 }
+
+const SEEDED_PIPELINE = [
+  {
+    assignment_id: 'work-1',
+    issue_number: 42,
+    issue_title: 'Fix the dashboard rendering',
+    repo_name: 'api',
+    machine_name: 'laptop',
+    current_stage: 'coding',
+    stages: [
+      { name: 'coding', status: 'active', is_current: true },
+      { name: 'review', status: 'waiting', is_current: false },
+      { name: 'merge', status: 'waiting', is_current: false },
+    ],
+    available_gates: [],
+    progress_pct: 20,
+    review_findings_pending: false,
+    review_verdict: null,
+    review_findings_body: null,
+    test_verdict: null,
+  },
+  {
+    assignment_id: 'work-2',
+    issue_number: 99,
+    issue_title: 'Refactor merge queue',
+    repo_name: 'api',
+    machine_name: 'server',
+    current_stage: 'review_running',
+    stages: [
+      { name: 'coding', status: 'completed', is_current: false },
+      { name: 'review', status: 'active', is_current: true },
+      { name: 'merge', status: 'waiting', is_current: false },
+    ],
+    available_gates: [],
+    progress_pct: 60,
+    review_findings_pending: false,
+    review_verdict: null,
+    review_findings_body: null,
+    test_verdict: null,
+  },
+]
+
+// Deliberately a *different* issue title from anything in SEEDED_PIPELINE:
+// Home surfaces live sessions above the pipeline cards, so a shared title
+// would resolve twice inside the list region and every row locator below
+// would trip strict mode for reasons that have nothing to do with the shell.
+const SEEDED_SESSIONS = [
+  {
+    session_id: 'sess-1',
+    session_name: 'coord-sess-1',
+    machine: 'dellserver',
+    host: 'dellserver.local',
+    repo: 'api',
+    issue: 7,
+    issue_title: 'Live session takeover',
+    stage: 'work',
+    status: 'running',
+    attached: false,
+    pane_dead: false,
+  },
+]
+
+async function mockApi(page: Page): Promise<void> {
+  await page.route('**/api/pipeline', (route) =>
+    route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify(SEEDED_PIPELINE) }),
+  )
+  await page.route('**/api/sessions', (route) =>
+    route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify(SEEDED_SESSIONS) }),
+  )
+  await page.route('**/api/board', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ round_number: 1, active: [], completed: [] }),
+    }),
+  )
+  await page.route('**/api/diff/**', (route) =>
+    route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify({ diff: '', source: 'compare' }) }),
+  )
+}
+
+const shell = (page: Page) => page.locator('[data-shell-mode]')
+const rail = (page: Page) => page.locator('[data-region="rail"]')
+const list = (page: Page) => page.locator('[data-region="list"]')
+const detail = (page: Page) => page.locator('[data-region="detail"]')
+
+// ── wide ──────────────────────────────────────────────────────────────────────
+
+test.describe('shell — wide viewport', () => {
+  test.use({ viewport: DESKTOP })
+
+  test('renders rail, list and detail side by side', async ({ page }) => {
+    await mockApi(page)
+    await page.goto('/')
+
+    await expect(shell(page)).toHaveAttribute('data-shell-mode', 'wide')
+    await expect(rail(page)).toBeVisible()
+    await expect(list(page)).toBeVisible()
+    await expect(detail(page)).toBeVisible()
+
+    // The list is the pipeline; the detail is the empty-selection placeholder.
+    await expect(list(page).getByText('Fix the dashboard rendering')).toBeVisible()
+    await expect(detail(page).getByText('Nothing selected')).toBeVisible()
+
+    // Left to right, actually laid out as three columns.
+    const [railBox, listBox, detailBox] = await Promise.all([
+      rail(page).boundingBox(),
+      list(page).boundingBox(),
+      detail(page).boundingBox(),
+    ])
+    expect(railBox!.x).toBeLessThan(listBox!.x)
+    expect(listBox!.x).toBeLessThan(detailBox!.x)
+  })
+
+  test('shows unbuilt panels in the rail as "soon" rather than hiding them', async ({ page }) => {
+    await mockApi(page)
+    await page.goto('/')
+
+    await expect(rail(page).getByRole('button', { name: /Milestones/ })).toHaveAttribute(
+      'aria-disabled',
+      'true',
+    )
+    await expect(rail(page).getByText('soon').first()).toBeVisible()
+  })
+
+  test('selecting a row fills the detail column and keeps the list', async ({ page }) => {
+    await mockApi(page)
+    await page.goto('/')
+
+    await list(page).getByText('Fix the dashboard rendering').click()
+    // #1548: the URL is keyed on repo + issue (`api`/`42`), not the
+    // assignment id (`work-1`) — an issue outlives any one assignment.
+    await expect(page).toHaveURL(/\/pipeline\/api\/42/)
+
+    await expect(detail(page).getByText('Fix the dashboard rendering')).toBeVisible()
+    // The list did not go anywhere — that's what makes this the wide layout.
+    await expect(list(page).getByText('Refactor merge queue')).toBeVisible()
+  })
+
+  test('F6 cycles focus rail -> list -> detail', async ({ page }) => {
+    await mockApi(page)
+    await page.goto('/')
+    await expect(list(page).getByText('Fix the dashboard rendering')).toBeVisible()
+
+    const focusedRegion = () =>
+      page.evaluate(() => document.activeElement?.getAttribute('data-region') ?? null)
+
+    await page.keyboard.press('F6')
+    expect(await focusedRegion()).toBe('rail')
+    await page.keyboard.press('F6')
+    expect(await focusedRegion()).toBe('list')
+    await page.keyboard.press('F6')
+    expect(await focusedRegion()).toBe('detail')
+    await page.keyboard.press('F6')
+    expect(await focusedRegion()).toBe('rail')
+
+    await page.keyboard.press('Shift+F6')
+    expect(await focusedRegion()).toBe('detail')
+  })
+
+  test('dragging the separator resizes the list, and the width survives a reload', async ({
+    page,
+  }) => {
+    await mockApi(page)
+    await page.goto('/')
+    await expect(list(page).getByText('Fix the dashboard rendering')).toBeVisible()
+
+    const before = (await list(page).boundingBox())!.width
+    const handle = page.getByRole('separator', { name: 'Resize list panel' })
+    const handleBox = (await handle.boundingBox())!
+
+    await page.mouse.move(handleBox.x + handleBox.width / 2, handleBox.y + handleBox.height / 2)
+    await page.mouse.down()
+    await page.mouse.move(handleBox.x + handleBox.width / 2 + 90, handleBox.y + handleBox.height / 2, {
+      steps: 8,
+    })
+    await page.mouse.up()
+
+    await expect
+      .poll(async () => (await list(page).boundingBox())!.width)
+      .toBeGreaterThan(before + 60)
+
+    const widened = (await list(page).boundingBox())!.width
+    await page.reload()
+    await expect(list(page).getByText('Fix the dashboard rendering')).toBeVisible()
+    expect(Math.abs((await list(page).boundingBox())!.width - widened)).toBeLessThan(2)
+  })
+
+  test('the selected view survives a reload', async ({ page }) => {
+    await mockApi(page)
+    await page.goto('/')
+
+    await rail(page).getByRole('button', { name: /^Sessions/ }).click()
+    await expect(list(page).getByRole('heading', { name: 'Sessions' })).toBeVisible()
+
+    await page.reload()
+    await expect(list(page).getByRole('heading', { name: 'Sessions' })).toBeVisible()
+  })
+
+  test('minimising the list gives the whole width to the detail', async ({ page }) => {
+    await mockApi(page)
+    await page.goto('/')
+    await expect(list(page)).toBeVisible()
+
+    await rail(page).getByRole('button', { name: 'Minimize list panel' }).click()
+    await expect(list(page)).toHaveCount(0)
+    await expect(shell(page)).toHaveAttribute('data-panel', 'collapsed')
+
+    await rail(page).getByRole('button', { name: 'Show list panel' }).click()
+    await expect(list(page)).toBeVisible()
+  })
+})
+
+// ── mid ───────────────────────────────────────────────────────────────────────
+
+test.describe('shell — mid viewport', () => {
+  test.use({ viewport: TABLET })
+
+  test('collapses the rail to icons and overlays the detail on the list', async ({ page }) => {
+    await mockApi(page)
+    await page.goto('/')
+
+    await expect(shell(page)).toHaveAttribute('data-shell-mode', 'medium')
+    // Icon strip: narrow, and the labels are gone.
+    expect((await rail(page).boundingBox())!.width).toBeLessThan(80)
+    await expect(rail(page).getByText('soon')).toHaveCount(0)
+
+    await list(page).getByText('Fix the dashboard rendering').click()
+
+    // The list is still mounted underneath, but inert — a drill-in that
+    // doesn't cost you the list you drilled in from.
+    await expect(list(page)).toHaveAttribute('inert', '')
+    const [listBox, detailBox] = await Promise.all([
+      list(page).boundingBox(),
+      detail(page).boundingBox(),
+    ])
+    expect(Math.abs(listBox!.x - detailBox!.x)).toBeLessThan(2)
+  })
+})
+
+// ── narrow ────────────────────────────────────────────────────────────────────
+
+test.describe('shell — narrow viewport', () => {
+  test.use({ viewport: PHONE })
+
+  test('keeps the phone drill-in: list, then detail, then back', async ({ page }) => {
+    await mockApi(page)
+    await page.goto('/')
+
+    await expect(shell(page)).toHaveAttribute('data-shell-mode', 'narrow')
+    await expect(list(page)).toBeVisible()
+    await expect(detail(page)).toHaveCount(0)
+
+    await list(page).getByText('Fix the dashboard rendering').click()
+    await expect(detail(page)).toBeVisible()
+    // Drill-in: the list is gone, not merely covered.
+    await expect(list(page)).toHaveCount(0)
+
+    await page.getByLabel('Back').click()
+    await expect(list(page)).toBeVisible()
+    await expect(detail(page)).toHaveCount(0)
+  })
+
+  test('puts the rail at the bottom of the screen with only built views', async ({ page }) => {
+    await mockApi(page)
+    await page.goto('/')
+
+    const [railBox, listBox] = await Promise.all([rail(page).boundingBox(), list(page).boundingBox()])
+    expect(railBox!.y).toBeGreaterThan(listBox!.y)
+    expect(railBox!.width).toBeGreaterThan(300)
+
+    await expect(rail(page).getByRole('button', { name: /Pipeline/ })).toBeVisible()
+    await expect(rail(page).getByRole('button', { name: /Milestones/ })).toHaveCount(0)
+  })
+
+  test('switches views from the bottom row', async ({ page }) => {
+    await mockApi(page)
+    await page.goto('/')
+
+    await rail(page).getByRole('button', { name: /Sessions/ }).click()
+    await expect(list(page).getByRole('heading', { name: 'Sessions' })).toBeVisible()
+
+    await rail(page).getByRole('button', { name: /Pipeline/ }).click()
+    await expect(list(page).getByRole('heading', { name: 'Pipeline' })).toBeVisible()
+  })
+})