---
phase: 03-dashboard-intake-ui
plan: "05"
subsystem: ui, pwa
tags: [react, typescript, pwa, service-worker, qr-scanner, zxing, camera]

# Dependency graph
requires:
  - web/src/store/ui.ts (useUIStore.setScannerActive)
  - web/src/components/ui/button.tsx
  - @zxing/browser (already in package.json from Plan 01)
provides:
  - web/public/manifest.json (PWA installable config)
  - web/public/sw.js (app-shell service worker)
  - web/public/icons/icon-192.png, icon-512.png (PWA icons)
  - web/src/hooks/usePWA.ts (service worker registration hook)
  - web/src/pages/ScanPage.tsx (/scan QR camera scanner)
  - web/src/lib/api.ts (fetchInventory, fetchInventoryItem typed wrappers)
  - web/src/components/layout/AppShell.tsx (page layout wrapper)
affects:
  - web/index.html (theme-color meta added)
  - web/src/App.tsx (usePWA() call added)
  - web/src/router.tsx (scanRoute lazy-loads ScanPage)

# Tech tracking
tech-stack:
  added: []
  patterns:
    - PWA app-shell cache strategy (navigation cache-first, API network-only, static assets cache-first)
    - @zxing/browser decodeFromVideoDevice for live camera QR scanning
    - lazy() + Suspense code-splitting for heavy QR scanner bundle (444KB chunk)
    - extractHWID() regex — strict pattern matching before any navigation

key-files:
  created:
    - web/public/manifest.json
    - web/public/sw.js
    - web/public/icons/icon-192.png
    - web/public/icons/icon-512.png
    - web/scripts/gen-icons.cjs
    - web/src/hooks/usePWA.ts
    - web/src/pages/ScanPage.tsx
    - web/src/lib/api.ts
    - web/src/components/layout/AppShell.tsx
  modified:
    - web/index.html (theme-color meta)
    - web/src/App.tsx (usePWA hook)
    - web/src/router.tsx (lazy ScanPage + Suspense)

decisions:
  - id: PWA-D01
    summary: "ScanPage code-split as separate lazy chunk (444KB) — @zxing/browser is large; lazy loading keeps initial bundle lean at 275KB"
  - id: PWA-D02
    summary: "api.ts and AppShell.tsx created as minimal stubs in this plan — Plans 03-03/03-04 run in parallel and hadn't built them yet; stubs provide exactly the interface ScanPage needs without duplicating plan scope"
  - id: PWA-D03
    summary: "Icon generation uses pure Node.js + zlib (no ImageMagick/canvas) — zero external tooling required; gen-icons.cjs is committed for reproducibility"

# Metrics
duration: ~15min
completed: 2026-04-10T06:22:00Z
tasks_completed: 2
files_created: 9
files_modified: 3
---

# Phase 3 Plan 05: PWA Manifest + Service Worker + QR Scanner Summary

**PWA installable manifest with app-shell service worker, programmatically generated icons, and a live camera QR scanner at /scan that resolves HW-XXXXX labels to NetBox inventory items.**

## Performance

- **Duration:** ~15 min
- **Started:** 2026-04-10T06:07:00Z
- **Completed:** 2026-04-10T06:22:00Z
- **Tasks:** 2
- **Files created:** 9
- **Files modified:** 3

## Accomplishments

- `web/public/manifest.json` — PWA web app manifest: `display=standalone`, `theme_color=#faff69`, `background_color=#000000`, 192px + 512px icons, portrait-primary orientation
- `web/public/sw.js` — App shell service worker with three-tier fetch strategy: API calls always network-only (no stale inventory), navigation requests cache-first (offline shell), static assets cache-first with network fallback and cache population
- `web/public/icons/icon-192.png` + `icon-512.png` — Valid PNG icons generated by `web/scripts/gen-icons.cjs` (pure Node.js, no external deps): black canvas with volt `#faff69` H monogram
- `web/src/hooks/usePWA.ts` — Service worker registration hook called from `App.tsx` on window load
- `web/src/pages/ScanPage.tsx` — Full camera QR scanner:
  - Rear camera preference (label matching: `back|rear|environment`)
  - Volt corner-bracket reticle overlay on live viewfinder
  - `extractHWID()` regex matches `http://.../hw/HW-XXXXX` URLs and bare `HW-XXXXX` IDs
  - `lastScanned` debounce prevents duplicate navigation
  - Resolves HW ID to NetBox numeric ID via `GET /api/inventory`, then navigates to `/item/:id`
  - Graceful camera-denied error state (no crash)
- `web/src/router.tsx` — scanRoute uses `lazy()` + `Suspense` to code-split the 444KB @zxing chunk
- `npm run build` exits 0, dist contains correctly split bundles

## Task Commits

1. **Task 1: PWA manifest, service worker, icons, registration hook** — `95a50f4`
2. **Task 2: QR scanner page + router wiring** — `75c91a5`

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 3 - Blocking] Created api.ts and AppShell.tsx stubs — parallel plan dependencies missing**
- **Found during:** Task 2 (creating ScanPage.tsx)
- **Issue:** ScanPage imports `fetchInventory` from `@/lib/api` and `AppShell` from `@/components/layout/AppShell`. Plans 03-03 and 03-04 (which build these) run in wave 2 alongside this plan and had not yet executed.
- **Fix:** Created `web/src/lib/api.ts` with `InventoryItem`, `fetchInventory`, `fetchInventoryItem` typed wrappers (full API contract matching Plan 03-02 handler output); created `web/src/components/layout/AppShell.tsx` as a minimal page wrapper. Both files are documented as stubs that Plans 03-03/03-04 will extend.
- **Files modified:** `web/src/lib/api.ts` (new), `web/src/components/layout/AppShell.tsx` (new)
- **Impact:** No scope creep — the stubs expose the exact interface ScanPage needs. Plans 03-03/03-04 will extend them without conflict.
- **Commits:** 75c91a5

**2. [Rule 1 - Bug] Fixed recursive startScanner call pattern — removed self-reference via useCallback dep**
- **Found during:** Task 2 implementation review
- **Issue:** Plan's ScanPage template called `startScanner()` recursively inside its own `useCallback`, which would cause an undefined reference (function not yet assigned at first call). Also called `stopScanner` before `stopScanner` was defined.
- **Fix:** Reordered hook definitions (stopScanner before startScanner), removed `startScanner` from its own dependency array, and used `void startScanner()` call pattern for the retry paths.
- **Files modified:** `web/src/pages/ScanPage.tsx`

## Known Stubs

| Stub | File | Reason |
|------|------|--------|
| `AppShell` (minimal layout, no TopBar/nav) | `web/src/components/layout/AppShell.tsx` | Plan 03-03 will replace with full navigation shell |
| `fetchInventory`/`fetchInventoryItem` (no caching) | `web/src/lib/api.ts` | Plan 03-03 will add TanStack Query hooks wrapping these; raw fetch is fully functional |

Both stubs are wire-complete (they make real API calls). ScanPage functionality is not blocked by stub status.

## Threat Surface Coverage

All four threats from the plan's threat register are addressed:

| Threat | Mitigation | Where |
|--------|------------|-------|
| T-03-14: QR text → navigation tampering | `extractHWID()` strict regex `HW-\d{5,}` — arbitrary text cannot trigger navigation; NetBox numeric ID comes from server response, not QR content | ScanPage.tsx:extractHWID |
| T-03-15: Camera stream info disclosure | @zxing decodes frames locally; no frames sent to server | ScanPage.tsx (client-only) |
| T-03-16: SW cache tampering | API responses explicitly excluded (network-only path in sw.js) | sw.js fetch handler |
| T-03-17: Rapid QR scan DoS | `lastScanned` state debounce; scanner stops before resolving | ScanPage.tsx:startScanner callback |

## Self-Check

Files created:
- web/public/manifest.json: FOUND
- web/public/sw.js: FOUND
- web/public/icons/icon-192.png: FOUND (valid PNG)
- web/public/icons/icon-512.png: FOUND (valid PNG)
- web/src/hooks/usePWA.ts: FOUND
- web/src/pages/ScanPage.tsx: FOUND
- web/src/lib/api.ts: FOUND
- web/src/components/layout/AppShell.tsx: FOUND

Commits:
- 95a50f4: feat(03-05): PWA manifest, service worker, icons, and registration hook
- 75c91a5: feat(03-05): QR scanner page with @zxing/browser and router wiring

Build: `cd web && npm run build` exits 0, 4 output files in dist/

## Self-Check: PASSED