# Convoy: scanner-rebuild

**Status:** In Progress (auto-approved — overnight build)  
**Owner:** Agent  
**Created:** 2026-06-13  

## Goal

Rebuild the card scanner from a desktop-first, configuration-heavy, everything-at-once layout into a mobile-first, three-phase flow optimized for rapid multi-card scanning.

## Architecture Decisions

### D1 — Three-phase flow

The scanner page becomes a state machine with three phases:
- **Setup** — choose destination + game (one-time per session)
- **Scanning** — full-screen camera with success toasts + count pill
- **Review** — card list with per-card edits + batch confirm

### D2 — Mobile-first camera

Camera fills the viewport during scanning phase. No side panels, no scrolling to see results. Success feedback via overlay toasts + haptic vibration.

### D3 — Auto-everything during scan

- Cards auto-route to chosen destination immediately
- Condition defaults NM, foil auto-detected from vision response
- Game auto-detected from vision (no pre-filter needed)
- Duplicates auto-increment quantity

### D4 — Deck Mode

Toggle in setup phase. Shows progress toward format-aware deck size (60/99/40). Auto-suggests stop when target reached.

### D5 — Disambiguation as bottom sheet

Replace full-screen modal with a slide-up bottom sheet. One tap to pick, then immediately resume scanning.

### D6 — New features

- **Scan history** — last 5 sessions persisted in localStorage
- **Sound feedback** — subtle blip on successful scan (configurable)
- **Offline queue** — if network drops, queue identification calls and retry
- **Camera flash toggle** — torch mode for foil detection in dim lighting

## File ownership

| Workstream | Files | Agent |
|---|---|---|
| Core orchestrator | `pages/scanner.js`, `lib/use-scanner-session.js` | A |
| Camera phase | `components/scanner/ScannerCamera.js`, `ScannerToast.js`, `ScannerCountPill.js`, `lib/use-camera-scanner.js`, `lib/use-scanner-sound.js`, `lib/use-scanner-flash.js` | B |
| Setup + Review | `components/scanner/ScannerSetup.js`, `ScannerReview.js`, `ScannerDisambiguation.js`, `DeckModeIndicator.js` | C |
| Queue + API | `lib/use-scanner-queue.js`, `lib/use-scanner-offline.js`, `pages/api/cards/batch-ownership.js` | D |

## Risks

- R1: Parallel agents may produce interface mismatches → mitigated by specifying contracts in each agent's prompt
- R2: Existing hooks (`use-scanner-identification.js`, `scanner-card-identify.js`, `scanner-card-detection.js`) are not being rewritten — the rebuild layers on top of them
- R3: Visual regression risk — existing smoke tests may break → handled in integration pass

## Human gates bypassed

Per user instruction (overnight build, 2026-06-13), all architect/reviewer gates are bypassed for this convoy. The user will review the final output in the morning.