From 575e01912c570b92ceaec0b196811438fff371c1 Mon Sep 17 00:00:00 2001
From: Brittany Ellich <brittany.ellich@outlook.com>
Date: Mon, 1 Jun 2026 07:13:52 -0700
Subject: [PATCH] docs: design spec for client-side QR decode

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../specs/2026-06-01-qr-decode-design.md      | 156 ++++++++++++++++++
 1 file changed, 156 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-01-qr-decode-design.md

diff --git a/docs/superpowers/specs/2026-06-01-qr-decode-design.md b/docs/superpowers/specs/2026-06-01-qr-decode-design.md
new file mode 100644
index 0000000..9b833c6
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-01-qr-decode-design.md
@@ -0,0 +1,156 @@
+# Design: Client-side QR decode for the camera button
+
+**Date:** 2026-06-01
+**Status:** Approved, pending implementation plan
+
+## Summary
+
+Upgrade the existing mobile "open camera" button from a no-op photo-capture
+affordance into a working live QR scanner. Tapping it opens a fullscreen
+overlay showing the rear-camera feed; the [jsQR](https://github.com/cozmo/jsQR)
+library decodes each video frame; when it detects one of atmo.quest's connect
+codes, the page navigates to it and the existing auto-connect flow takes over.
+
+This builds directly on the prior camera-button work (see
+`2026-05-31-mobile-camera-button-design.md`), which deliberately shipped the
+button as a v1 stub with no decode step. This spec adds that decode step.
+
+## Motivation
+
+atmo.quest's connect flow relies on scanning a QR code. Each profile exposes a
+QR that encodes `<PublicURL>/c/<did>` (or `<PublicURL>/c/l/<local_id>` for local
+accounts); visiting that URL writes the connection and redirects. Today the
+in-app camera button opens the native camera capture sheet but discards the
+photo — users still have to switch to their phone's standalone camera app to
+actually scan. This feature makes the in-app button do the scan itself.
+
+## Key decisions
+
+- **Capture mode: live viewfinder.** Use `getUserMedia` with
+  `facingMode: 'environment'` (rear camera) in a fullscreen overlay, decoding
+  frames continuously and auto-navigating the instant a valid connect code is
+  seen. This is the scanner UX people expect for connecting in person.
+- **Decoder: jsQR only.** iOS Safari does not support the native
+  `BarcodeDetector` API, so a pure-JS decoder is required for universal
+  coverage anyway. jsQR (~40KB, MIT) decodes every frame the same way on all
+  browsers, giving one code path. Vendored as a static asset.
+- **Non-app codes: keep scanning + transient hint.** A decoded QR that is not
+  an atmo.quest connect code is ignored; the viewfinder stays live and shows a
+  small transient hint ("not an atmo.quest code — keep scanning"). The overlay
+  only navigates on a valid connect code or closes on user cancel.
+
+## Architecture
+
+No Go handler or route changes. A successful scan is a same-origin navigation
+to an existing `/c/...` route. All new code is client-side plus a templ markup
+tweak and CSS.
+
+### Components
+
+- **`web/resources/static/js/vendor/jsqr.js`** — the vendored jsQR UMD build
+  (MIT license). New `vendor/` subdirectory under the existing static JS dir.
+- **`web/resources/static/js/qr-scan.js`** — new vanilla JS module, matching the
+  existing plain-JS pattern (`badge-toast.js`, `notes.js`, etc.). Responsible
+  for:
+  - attaching a click handler to every `[data-qr-scan]` button on the page;
+  - building the overlay DOM dynamically (no templ overlay markup required);
+  - starting/stopping the camera (`getUserMedia`) and explicit track teardown;
+  - the per-frame decode loop (draw video frame to an offscreen canvas, pass
+    its `ImageData` to `jsQR`);
+  - URL matching and navigation;
+  - the file-input fallback path.
+  The module no-ops cleanly if no `[data-qr-scan]` element is present.
+- **`CameraScanButton` templ component**
+  (`features/common/layouts/camerabutton.templ`) — changes from a `<label>`
+  wrapping a file input to:
+  - a `<button type="button" class="btn btn-ghost camera-scan" data-qr-scan>`
+    with the label `📷 scan to connect` (accurate now that it decodes), plus
+  - a hidden `<input type="file" accept="image/*" capture="environment">` used
+    only for the fallback path.
+  This single shared component already drives all three placements (profile,
+  `/e/{token}` scan-landing, and `/events/{token}` event detail), so they all
+  inherit the scanner automatically.
+- **CSS** (`web/resources/static/css/terminal.css`) — new overlay/viewfinder
+  styles. The existing mobile-only `.camera-scan` rule
+  (`display:none` above 768px) is unchanged, keeping the button mobile-only.
+- **Service worker** (`web/resources/static/js/sw.js`) — add `jsqr.js` and
+  `qr-scan.js` to the precache list so the scanner works offline / in the
+  installed PWA.
+- **Base layout** (`features/common/layouts/base.templ`) — load `jsqr.js` and
+  `qr-scan.js` with `defer`, alongside the existing global JS includes.
+
+### Data flow
+
+1. User taps the `📷 scan to connect` button (`[data-qr-scan]`).
+2. `qr-scan.js` builds and shows the fullscreen overlay and calls
+   `getUserMedia({ video: { facingMode: 'environment' } })`.
+3. The stream is attached to a `<video>` element. A decode loop
+   (`requestAnimationFrame`) draws each frame to an offscreen canvas and calls
+   `jsQR(imageData.data, width, height)`.
+4. On a successful decode, the decoded text is passed to the pure function
+   `parseConnectPath(text, origin)`:
+   - parse `text` as a URL;
+   - if its pathname matches `/c/{did}` or `/c/l/{id}`, return that **pathname
+     (+ query/hash)**;
+   - otherwise return `null`.
+5. If `parseConnectPath` returns a path, stop the camera, tear down the overlay,
+   and `window.location.assign(path)` on the **current origin** (so a QR baked
+   with the production `PublicURL` still works during local testing). The
+   existing `/c/...` handler performs the connect + redirect.
+6. If it returns `null`, ignore the code, show the transient hint, and keep
+   decoding.
+
+## Error handling and edge cases
+
+- **Permission denied / no camera / `getUserMedia` unsupported:** the overlay
+  shows an explanatory message and falls back to the hidden
+  `<input type="file" capture="environment">`. The user snaps one photo, which
+  is decoded with the same jsQR path; on a valid code it navigates, otherwise it
+  shows the hint.
+- **Camera teardown:** the Cancel button and tapping the backdrop both close the
+  overlay and stop every `MediaStreamTrack` so the camera indicator clears and
+  the device camera is released.
+- **Repeated/duplicate frames:** once a valid code triggers navigation, the
+  decode loop is cancelled to avoid double navigation.
+- **Mobile-only:** unchanged from the prior design — the button is hidden above
+  the 768px breakpoint via the existing `.camera-scan` CSS.
+
+## Testing
+
+- **Pure function unit tests** for `parseConnectPath(text, origin)`:
+  - `https://atmo.quest/c/did:plc:abc` → `/c/did:plc:abc`
+  - `https://atmo.quest/c/l/local_abc-123` → `/c/l/local_abc-123`
+  - an absolute production URL when the page origin differs → still returns the
+    same-origin path
+  - a non-connect URL (`https://example.com/foo`) → `null`
+  - plain text / garbage → `null`
+  The function is exported in a way that can be exercised by a test. If the repo
+  has no JS test runner, add a minimal Node-based test for this function.
+- **Manual device verification:** on a real mobile device (or emulated mobile),
+  confirm the overlay opens the rear camera, a profile QR scans and connects, a
+  non-app QR is ignored with the hint, permission-denied falls back to the file
+  input, and Cancel releases the camera. Confirm the button remains hidden on
+  desktop widths.
+- **Build checks:** `templ generate` runs clean; `go build` / existing checks
+  pass.
+
+## Out of scope (YAGNI)
+
+- Scanning non-connect QR types or arbitrary URLs.
+- Torch/flashlight, zoom, or multi-camera selection controls.
+- Decoding a QR from a gallery-uploaded image (only the live feed and the
+  permission-fallback single capture are supported).
+
+## Files touched
+
+- `web/resources/static/js/vendor/jsqr.js` — new (vendored MIT library).
+- `web/resources/static/js/qr-scan.js` — new module.
+- `features/common/layouts/camerabutton.templ` — button markup change
+  (+ regenerated `*_templ.go`).
+- `features/common/layouts/base.templ` — script includes
+  (+ regenerated `*_templ.go`).
+- `web/resources/static/css/terminal.css` — overlay styles.
+- `web/resources/static/js/sw.js` — precache the two new JS files.
+- templ regeneration via the project's `templ generate` task.
+
+No new server-side dependencies, handlers, or routes.
-- 
2.51.2