archy/docs/qr-scanner-snappiness-handover.md

QR scanner snappiness — research + companion-dev handover

2026-07-29. Owner: web side = node repo (this doc's "web" items); native side = companion app dev (Mac). Backlog origin: UNIFIED-TASK-TRACKER "optimise companion QR scan (quicker start/decode, low-light)".

Where scanning happens today

Path	Stack	Used when
Web live scan	nimiq qr-scanner 1.4.x over getUserMedia, in WalletScanModal.vue	HTTPS browsers / secure contexts
Photo fallback	<input capture> photo → BarcodeDetector if present, else qr-scanner.scanImage multi-pass (decodePhotoRobust)	Plain-http (LAN) where getUserMedia doesn't exist
Native scan	ArchipelagoQr JS bridge → companion's native scanner (0.5.22 fixed dense invoice QRs)	Inside the companion app

What makes it feel slow (ranked)

1. Camera cold-start — the stream starts only after the user reaches the scan pane; on phones getUserMedia + first frame is routinely 600–1500ms, and the native path pays a similar CameraX bind + ML Kit model cold-start.
2. Decode cadence — web live scan was capped at 4 scans/sec (WebView preview lagged at 10/s when decoding on the JS worker). A hand-held code therefore waits up to 250ms after it's already sharp and centered.
3. Low light / focus hunting — no torch control anywhere; no explicit continuous-focus request. Dense LN invoices need sharpness more than resolution.
4. Dense-QR decode budget — big bolt11/catalog QRs push the JS decoder hard; the native ML Kit path is far better at these (proven by 0.5.22).

Web side (node repo — can be done here)

• ✅ DONE (2026-07-29): scan at 10/s when BarcodeDetector exists (Chrome/ Android WebView decode natively — cheap), keep 4/s only for the JS-worker fallback.
• Pre-warm the camera: start getUserMedia the moment the modal opens (action pane), not when the scan pane is reached — hide the preview until needed. Saves the entire cold-start from the user's perceived timeline.
• Torch toggle: qr-scanner exposes hasFlash()/turnFlashOn() — add a 🔦 button on the scan pane (it silently no-ops where unsupported).
• Continuous focus + modest resolution: pass constraints { focusMode: 'continuous', width: { ideal: 1280 } } — 720p-class frames start faster AND decode faster than 1080p+, with no loss for QR density that matters to us.
• Don't stop/start between panes: returning from amount → scan currently re-inits the scanner; keep the (paused) stream alive while the modal lives.

Native side (companion dev handover)

The ArchipelagoQr bridge overlay is the right architecture — these are tuning items inside the native scanner activity:

1. Pre-warm CameraX + ML Kit: bind the camera provider and instantiate BarcodeScanning.getClient(...) when the WebView requests the overlay — or even when the wallet modal opens (add a ArchipelagoQr.prewarm() bridge method; the web side will call it if present). ML Kit's first-inference model load is 100–300ms — pay it before the user aims.
2. Restrict formats: BarcodeScannerOptions with FORMAT_QR_CODE only — skipping the other symbologies measurably cuts per-frame latency.
3. Analysis resolution ≈ 1280×720 with ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST — never queue stale frames; decode the newest one only.
4. Continuous autofocus + tap-to-focus on the preview, and a torch toggle (low-light was an explicit user complaint).
5. zoomRatio nudge for small codes: if no hit after ~2s, step zoom to 1.5× — helps distant/small printed codes without user action.
6. Success haptic + instant dismiss: vibrate on decode and close the overlay immediately; perceived speed is heavily back-loaded.
7. Optional: ML Kit enableAllPotentialBarcodes off and skip inverted scans unless first pass fails (inverted QRs are rare; halves work).

Acceptance criteria

• Cold open → first successful scan of a normal invoice QR in < 2s on the companion app, < 3s in a mobile browser.
• Dense (700+ char) bolt11 QR decodes in < 1.5s once framed, both paths.
• Dim-room scan succeeds with the torch toggle without leaving the scanner.

Verification notes for whoever implements

• Measure with a timestamp log: overlay-requested → camera-first-frame → decode-success. The three deltas map 1:1 onto items above.
• Web BarcodeDetector presence differs per WebView/Play-Services build — keep the JS-worker fallback path intact.