Suggest edit — 007-mobile-first-webui

Title

Name

Note

---
visibility: public
---

# Spec 007 — Mobile-first web UI

**Status:** Draft
**Related:** [PRD FR-18..FR-21](../prd/001-picortex-v1.md#mobile-first-web-ui), [bettergpt mockups](../mockups/README.md)

## Goal

Jacob on iPhone Safari can manage picortex. Swipe panels between messages, files, and terminal. Desktop gets a three-column split view.

## Stack

- Vite + React 18 + TypeScript
- Tailwind CSS (mobile-first by convention — base classes target phones; `md:`/`lg:` add up)
- TanStack Query for server state
- React Router v7

## Layouts

### Mobile (< 768px)

```
┌───────────────────────────────┐
│ [< back]  ChatName      [⚙]   │
├───────────────────────────────┤
│                               │
│   (messages | files | term)   │
│   swipe-tabs, one at a time   │
│                               │
├───────────────────────────────┤
│  [compose box]         [send] │
└───────────────────────────────┘
```

Swipe-tabs: three panels side-by-side in a horizontally-scrolling container with snap points. Tab bar shows `●○○` indicator at top.

### Tablet / desktop (≥ 768px)

```
┌──────────────┬──────────┬──────────────┐
│   Chats      │ Messages │  Files       │
│   list       │          │  & Terminal  │
│              │          │  split       │
└──────────────┴──────────┴──────────────┘
```

## Routes

- `/` — chat list (mobile) or three-column (desktop)
- `/c/:chat_id` — single chat, current panel = messages
- `/c/:chat_id/files` — files panel
- `/c/:chat_id/files/*` — specific file
- `/c/:chat_id/terminal` — terminal panel
- `/settings/:chat_id` — chat settings (attention, sharing bridge history)

## Messages panel

- Message list virtualized (`@tanstack/react-virtual`)
- Reply-to pill: shows quoted source with tap-to-jump
- Reactions stacked under message bubbles
- Long-press (mobile) / right-click (desktop) → react, reply, copy
- Compose supports multi-line (Shift+Enter)

## Version + update badge

Footer:

```
picortex v0.0.1  [●]
```

Dot badge visible when a newer commit is on main vs running commit. Clicking the footer shows the diff summary and "refresh to get updates" (or triggers a deploy webhook — v0.2).

Version read from `/api/version` (returns `package.json` version + git commit + build time).

## Accessibility

- Tap targets ≥ 44pt
- Keyboard nav on desktop (j/k to move between messages, Tab cycles panels)
- Focus rings visible
- Dark mode via `prefers-color-scheme`

## Testing

- Vitest + Testing Library
- Storybook for components
- Playwright for E2E (mobile viewport + desktop viewport)

## Open questions

- OQ1: PWA (installable)? Defer to v0.2 but leave manifest stub.
- OQ2: Group chat UI on mobile — explicit non-goal for v1. Desktop-only renders.