brain-of-reese/.agent/user_stories/mobile-hamburger-nav.md

# Story: Mobile hamburger nav

**Phase:** `46_mobile_hamburger_nav` · **Source:** `TODO.md` L9 ·
**E2E:** `tests/e2e/test_mobile_hamburger_nav.py`

## Bug report (verbatim, `TODO.md` L9)

> "The navbar on mobile is way too squished. Make it a hamburger
> dropdown menu with a nice animation"

## Narrative

As **a mobile user**, the 58px header currently crams up to four text
nav pills (Chat / Sources / Git sources / Tuning) next to the brand and
four icon action pills — the phase-34/35 squeeze at 360–375px leaves
0.72rem-font pills that are hard to hit and hard to read. The nav links
move into a **hamburger dropdown menu** on small screens: one
`#nav-toggle` button in the bar, and the links open as an animated
panel below the header with comfortable touch targets.

- **Given** a viewport ≤640px
- **When** I tap the hamburger
- **Then** the nav menu drops down with a short slide+fade animation and
  full-size links; tapping a link navigates and closes the menu.
- **Given** a viewport >640px
- **When** the page loads
- **Then** nothing changes — the inline nav pills render exactly as
  today.

## Acceptance criteria
1. **Mobile (≤640px):** the inline nav pills are hidden from the bar; a
   hamburger button (`#nav-toggle`, `aria-label="Menu"`,
   `aria-controls="app-nav"`, `aria-expanded`) appears — 44px touch
   target, icon-only.
2. **Menu:** `.app-nav` (now `id="app-nav"`) becomes a dropdown panel
   below the header — vertical full-width rows, ≥44px targets, readable
   font size; the **auth visibility contract is preserved inside the
   menu** (anonymous: only "Chat"; admin: Chat / Sources / Git sources /
   Tuning — the same ship-hidden `hidden` attributes the whoami gate
   already drives).
3. **Animation:** opening/closing animates (slide-down + fade, ≈180ms);
   `prefers-reduced-motion: reduce` stills it (no transition).
4. **Behavior:** toggle flips `aria-expanded`; `Esc` closes while open;
   a link click navigates **and** closes the menu; resizing back to
   >640px closes it (the inline nav reappears, no stale state).
5. **Bar layout:** the action pills (Tuning toggle, Sync, New chat,
   Sign in/out) stay in the bar icon-only — the phase-35 tightest
   squeeze rules on `.nav-link` / `.app-nav` gaps are replaced by the
   roomier menu; the bar fits 360px with the brand intact or clipped as
   today.
6. **All six pages** get the identical toggle + menu (the phase-34
   "same bar on every page" contract).

## Owner-confirmed (2026-08-27, roadmap A5)
1. **The hamburger contains the nav links only** (Chat / Sources / Git
   sources / Tuning). The action pills stay in the bar.
2. **Animation:** slide-down + fade, 180ms; `prefers-reduced-motion`
   stills it.
3. **Breakpoint:** the existing ≤640px mobile block (no new breakpoint).

## UI Visualization & Structure
- **Markup (all six pages — `index.html`, `sources.html`,
  `document.html`, `git-sources.html`, `login.html`, `tuning.html`):**
  a `#nav-toggle` button inserted before `<nav class="app-nav"
  aria-label="Primary">` (which gains `id="app-nav"`); the nav keeps
  its existing links and `hidden` attributes byte-identically.
- **CSS** (`frontend/assets/styles.css`, the `@media (max-width: 640px)`
  block): `.nav-toggle { display: none }` outside, `display:
  inline-flex` + 44px target inside; `.app-nav` becomes the dropdown:
  absolute below the header, `flex-direction: column`, surface background
  + bottom border/shadow, full-width row links; closed state
  (`visibility: hidden; opacity: 0; transform: translateY(-8px);
  pointer-events: none`) → `.is-open` (`visible; opacity: 1; transform:
  none`), `transition: opacity/transform 180ms ease`; a
  `prefers-reduced-motion` override kills the transition. The old
  nav-pill squeeze rules (`.nav-link` 0.72rem, `.app-nav` gap 0.05rem)
  are superseded for the menu rows.
- **JS** (`frontend/assets/header.js`, module-import binding like
  sign-out): null-safe `#nav-toggle` / `#app-nav` — click toggles
  `.is-open` + `aria-expanded`; delegated click on nav links closes it;
  `document` keydown `Esc` closes while open; a
  `matchMedia("(max-width: 640px)")` change listener closes on
  desktop. No other header.js behavior touched.
- **Non-goals:** no change to the 900px tablet rules, the action pills,
  the viewer's title bar height, or the no-CDN/A11 constraints.

## Playwright Mapping Rule
**Test Scenario → `tests/e2e/test_mobile_hamburger_nav.py`** (mock
LLM; DB up):
1. `test_mobile_hamburger_visible_and_bar_roomy` — 375×812: `#nav-toggle`
   visible with `aria-expanded="false"`; the inline nav links are not
   visible in the bar (menu closed); the header has no horizontal
   overflow.
2. `test_anonymous_menu_contents` — anonymous: open the menu → exactly
   "Chat" is visible; open/close flips `aria-expanded`.
3. `test_admin_menu_contents` — login: open the menu → Chat / Sources /
   Git sources / Tuning all visible (auth contract inside the menu).
4. `test_link_click_navigates_and_closes` — open, click "Sources"
   (admin): navigates to `/sources.html`, and the menu on the arrival
   page is closed.
5. `test_esc_and_backdrop_close` — open, `Esc` closes (aria-expanded
   false); open again, click outside the panel closes.
6. `test_animation_and_reduced_motion` — with motion allowed, the menu
   has a transition (computed `transition-duration` ≈180ms on the
   opacity/transform pair); with `reducedMotion: "reduce"` emulated,
   the transition is none/0s and the menu still opens/closes.
7. `test_desktop_unchanged` (regression) — 1280×800: no hamburger,
   inline nav pills exactly as before (the phase-34/35 bar contract,
   `test_nav_consistency` / `test_header_consistency` pass in the
   regression pass).