From a1ea8d5a5da784ab2190fe83b784151d7639a03d Mon Sep 17 00:00:00 2001
From: Brittany Ellich <brittany.ellich@outlook.com>
Date: Mon, 1 Jun 2026 07:35:57 -0700
Subject: [PATCH] docs: implementation plan for client-side QR decode

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

diff --git a/docs/superpowers/plans/2026-06-01-qr-decode.md b/docs/superpowers/plans/2026-06-01-qr-decode.md
new file mode 100644
index 0000000..1750f35
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-01-qr-decode.md
@@ -0,0 +1,668 @@
+# Client-side QR Decode Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Turn the existing mobile camera button into a working live QR scanner that opens the rear camera, decodes atmo.quest connect codes with jsQR, and navigates to them.
+
+**Architecture:** All work is client-side plus templ markup tweaks and CSS — no Go handler/route changes. A new `qr-scan.js` module builds a fullscreen overlay, runs `getUserMedia({facingMode:'environment'})`, decodes each frame with the vendored jsQR library, and on a valid `/c/{did}` or `/c/l/{id}` code navigates to that path on the current origin (the existing `/c/...` handler then connects). Non-connect codes are ignored with a transient hint; if the live camera is unavailable it falls back to a single still capture via a hidden file input, decoded the same way.
+
+**Tech Stack:** Vanilla JS (matching `web/resources/static/js/*.js`), jsQR 1.4.0 (vendored, MIT), templ, Go static asset server, `node --test` for the one pure function.
+
+Reference spec: `docs/superpowers/specs/2026-06-01-qr-decode-design.md`
+
+---
+
+## File structure
+
+- `web/resources/static/js/qr-scan.js` — **new.** The scanner module. Contains the pure `parseConnectPath` function (unit-tested) plus all browser-only overlay/camera/decode/fallback wiring. DOM code is guarded so the file can be `require`d in Node for testing.
+- `web/resources/static/js/qr-scan.test.js` — **new.** Node test for `parseConnectPath`.
+- `web/resources/static/js/vendor/jsqr.js` — **new.** Vendored jsQR UMD build.
+- `web/resources/static/css/terminal.css` — **modify.** Update the `.camera-scan` rule for the new wrapper element; add overlay styles.
+- `features/common/layouts/camerabutton.templ` — **modify.** Button markup change.
+- `features/common/layouts/base.templ` — **modify.** Add two `<script defer>` includes.
+- `features/index/pages/index.templ` — **modify.** Add the shared button to the home dashboard.
+
+No `sw.js` change: the service worker already serves `/static/*` cache-first, so the new JS is cached automatically on first load.
+
+---
+
+## Task 1: Pure connect-URL matcher + tests (TDD)
+
+**Files:**
+- Create: `web/resources/static/js/qr-scan.js`
+- Test: `web/resources/static/js/qr-scan.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `web/resources/static/js/qr-scan.test.js`:
+
+```js
+const test = require("node:test");
+const assert = require("node:assert");
+const { parseConnectPath } = require("./qr-scan.js");
+
+const ORIGIN = "http://127.0.0.1:9090";
+
+test("matches /c/{did} and returns the same-origin path", () => {
+  assert.strictEqual(
+    parseConnectPath("https://atmo.quest/c/did:plc:abc", ORIGIN),
+    "/c/did:plc:abc",
+  );
+});
+
+test("matches /c/l/{local_id}", () => {
+  assert.strictEqual(
+    parseConnectPath("https://atmo.quest/c/l/local_abc-123", ORIGIN),
+    "/c/l/local_abc-123",
+  );
+});
+
+test("drops a foreign origin, keeps the connect path", () => {
+  assert.strictEqual(
+    parseConnectPath("https://prod.example.com/c/did:plc:xyz", ORIGIN),
+    "/c/did:plc:xyz",
+  );
+});
+
+test("preserves query and hash", () => {
+  assert.strictEqual(
+    parseConnectPath("https://atmo.quest/c/did:plc:abc?x=1#y", ORIGIN),
+    "/c/did:plc:abc?x=1#y",
+  );
+});
+
+test("rejects a non-connect URL", () => {
+  assert.strictEqual(parseConnectPath("https://example.com/foo", ORIGIN), null);
+});
+
+test("rejects plain garbage text", () => {
+  assert.strictEqual(parseConnectPath("just some text $$$", ORIGIN), null);
+});
+
+test("rejects the bare /c/l with no id", () => {
+  assert.strictEqual(parseConnectPath("https://atmo.quest/c/l", ORIGIN), null);
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `node --test web/resources/static/js/qr-scan.test.js`
+Expected: FAIL — `Cannot find module './qr-scan.js'`.
+
+- [ ] **Step 3: Create `qr-scan.js` with the pure function only**
+
+Create `web/resources/static/js/qr-scan.js`:
+
+```js
+// qr-scan.js — live QR scanner for the "scan to connect" button.
+//
+// Tapping any [data-qr-scan] button opens a fullscreen overlay with the rear
+// camera, decodes frames with jsQR, and navigates to a decoded atmo.quest
+// connect URL (/c/{did} or /c/l/{id}) on the current origin. Non-connect codes
+// are ignored with a transient hint. If the live camera is unavailable or
+// permission is denied, it falls back to a single still capture via the
+// button's hidden <input type="file" capture="environment">, decoded the same
+// way.
+
+(function () {
+  "use strict";
+
+  // --- Pure URL matching (unit-tested) --------------------------------
+  // Returns the same-origin path to navigate to for an atmo.quest connect
+  // QR, or null if `text` is not one of our connect URLs. The origin is
+  // dropped on purpose so a QR baked with the production PublicURL still
+  // works when scanned against a local/dev origin.
+  function parseConnectPath(text, origin) {
+    let url;
+    try {
+      url = new URL(text, origin);
+    } catch (e) {
+      return null;
+    }
+    const m = url.pathname.match(/^\/c\/(?:l\/([^/]+)|([^/]+))\/?$/);
+    if (!m) return null;
+    // Reject the bare "/c/l" case (segment captured as "l", no local id).
+    if (!m[1] && m[2] === "l") return null;
+    return url.pathname + url.search + url.hash;
+  }
+
+  // Export for Node tests; harmless in the browser (no `module`).
+  if (typeof module !== "undefined" && module.exports) {
+    module.exports = { parseConnectPath };
+  }
+
+  // Browser-only wiring is added in a later task; bail out under Node.
+  if (typeof document === "undefined") return;
+})();
+```
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `node --test web/resources/static/js/qr-scan.test.js`
+Expected: PASS — 7 tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web/resources/static/js/qr-scan.js web/resources/static/js/qr-scan.test.js
+git commit -m "feat(qr): add connect-URL matcher with tests"
+```
+
+---
+
+## Task 2: Vendor the jsQR library
+
+**Files:**
+- Create: `web/resources/static/js/vendor/jsqr.js`
+
+- [ ] **Step 1: Download jsQR 1.4.0 into the vendor directory**
+
+Run:
+```bash
+mkdir -p web/resources/static/js/vendor
+curl -fsSL "https://cdn.jsdelivr.net/npm/jsqr@1.4.0/dist/jsQR.js" -o web/resources/static/js/vendor/jsqr.js
+```
+
+- [ ] **Step 2: Verify the file downloaded and exposes the global**
+
+Run:
+```bash
+test -s web/resources/static/js/vendor/jsqr.js && grep -c 'root\["jsQR"\]' web/resources/static/js/vendor/jsqr.js
+```
+Expected: prints `1` (the UMD build assigns `window.jsQR`). If the file is empty or the count is `0`, the download failed — retry, or fetch from `https://unpkg.com/jsqr@1.4.0/dist/jsQR.js`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add web/resources/static/js/vendor/jsqr.js
+git commit -m "chore(qr): vendor jsQR 1.4.0 (MIT)"
+```
+
+---
+
+## Task 3: Build the scanner overlay + camera/decode/fallback logic
+
+**Files:**
+- Modify: `web/resources/static/js/qr-scan.js`
+
+- [ ] **Step 1: Replace the browser-only bail-out with the full wiring**
+
+In `web/resources/static/js/qr-scan.js`, replace this block:
+
+```js
+  // Browser-only wiring is added in a later task; bail out under Node.
+  if (typeof document === "undefined") return;
+})();
+```
+
+with:
+
+```js
+  // Browser-only wiring below; bail out under Node (used only for tests).
+  if (typeof document === "undefined") return;
+
+  let activeStream = null;
+  let rafId = null;
+  let overlayEl = null;
+  let hintTimer = null;
+
+  function stopCamera() {
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+    if (activeStream) {
+      activeStream.getTracks().forEach((t) => t.stop());
+      activeStream = null;
+    }
+  }
+
+  function closeOverlay() {
+    stopCamera();
+    if (hintTimer) {
+      clearTimeout(hintTimer);
+      hintTimer = null;
+    }
+    if (overlayEl && overlayEl.parentNode) {
+      overlayEl.parentNode.removeChild(overlayEl);
+    }
+    overlayEl = null;
+  }
+
+  function navigateTo(path) {
+    stopCamera();
+    window.location.assign(path);
+  }
+
+  function showHint(hintEl, msg) {
+    if (!hintEl) return;
+    hintEl.textContent = msg;
+    hintEl.classList.add("show");
+    if (hintTimer) clearTimeout(hintTimer);
+    hintTimer = setTimeout(() => hintEl.classList.remove("show"), 2000);
+  }
+
+  function buildOverlay() {
+    const overlay = document.createElement("div");
+    overlay.className = "qr-scan-overlay";
+    overlay.innerHTML =
+      '<div class="qr-scan-backdrop" data-qr-close></div>' +
+      '<div class="qr-scan-stage">' +
+      '<video class="qr-scan-video" playsinline muted></video>' +
+      '<div class="qr-scan-frame"></div>' +
+      '<p class="qr-scan-hint" role="status"></p>' +
+      "</div>" +
+      '<button type="button" class="btn btn-ghost qr-scan-cancel" data-qr-close>cancel</button>';
+    document.body.appendChild(overlay);
+    overlay
+      .querySelectorAll("[data-qr-close]")
+      .forEach((el) => el.addEventListener("click", closeOverlay));
+    return overlay;
+  }
+
+  function decodeLoop(video, canvas, ctx, hintEl) {
+    if (!activeStream) return; // overlay was closed
+    if (video.readyState === video.HAVE_ENOUGH_DATA) {
+      const w = video.videoWidth;
+      const h = video.videoHeight;
+      if (w && h) {
+        canvas.width = w;
+        canvas.height = h;
+        ctx.drawImage(video, 0, 0, w, h);
+        const img = ctx.getImageData(0, 0, w, h);
+        const result = window.jsQR ? window.jsQR(img.data, w, h) : null;
+        if (result && result.data) {
+          const path = parseConnectPath(result.data, window.location.origin);
+          if (path) {
+            navigateTo(path);
+            return;
+          }
+          showHint(hintEl, "not an atmo.quest code — keep scanning");
+        }
+      }
+    }
+    rafId = requestAnimationFrame(() => decodeLoop(video, canvas, ctx, hintEl));
+  }
+
+  function fallbackToFile(fileInput, hintEl) {
+    showHint(hintEl, "camera unavailable — tap to take a photo of the QR");
+    if (fileInput) fileInput.click();
+  }
+
+  async function startLiveScan(fileInput) {
+    overlayEl = buildOverlay();
+    const video = overlayEl.querySelector(".qr-scan-video");
+    const hintEl = overlayEl.querySelector(".qr-scan-hint");
+    const canvas = document.createElement("canvas");
+    const ctx = canvas.getContext("2d", { willReadFrequently: true });
+
+    if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
+      fallbackToFile(fileInput, hintEl);
+      return;
+    }
+    try {
+      activeStream = await navigator.mediaDevices.getUserMedia({
+        video: { facingMode: "environment" },
+        audio: false,
+      });
+    } catch (err) {
+      fallbackToFile(fileInput, hintEl);
+      return;
+    }
+    video.srcObject = activeStream;
+    await video.play().catch(() => {});
+    rafId = requestAnimationFrame(() => decodeLoop(video, canvas, ctx, hintEl));
+  }
+
+  function decodeImageFile(file) {
+    const reader = new FileReader();
+    reader.onload = function () {
+      const img = new Image();
+      img.onload = function () {
+        const canvas = document.createElement("canvas");
+        canvas.width = img.naturalWidth;
+        canvas.height = img.naturalHeight;
+        const ctx = canvas.getContext("2d", { willReadFrequently: true });
+        ctx.drawImage(img, 0, 0);
+        const data = ctx.getImageData(0, 0, canvas.width, canvas.height);
+        const result = window.jsQR
+          ? window.jsQR(data.data, canvas.width, canvas.height)
+          : null;
+        const hintEl = overlayEl && overlayEl.querySelector(".qr-scan-hint");
+        if (result && result.data) {
+          const path = parseConnectPath(result.data, window.location.origin);
+          if (path) {
+            navigateTo(path);
+            return;
+          }
+        }
+        showHint(hintEl, "no atmo.quest code found — try again");
+      };
+      img.src = reader.result;
+    };
+    reader.readAsDataURL(file);
+  }
+
+  function initQrScan() {
+    document.querySelectorAll("[data-qr-scan]").forEach((btn) => {
+      const fileInput = btn.parentNode
+        ? btn.parentNode.querySelector('input[type="file"]')
+        : null;
+      btn.addEventListener("click", function (e) {
+        e.preventDefault();
+        startLiveScan(fileInput);
+      });
+      if (fileInput) {
+        fileInput.addEventListener("change", function () {
+          if (fileInput.files && fileInput.files[0]) {
+            decodeImageFile(fileInput.files[0]);
+          }
+        });
+      }
+    });
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initQrScan);
+  } else {
+    initQrScan();
+  }
+})();
+```
+
+- [ ] **Step 2: Re-run the pure-function test (the Node require must still work)**
+
+Run: `node --test web/resources/static/js/qr-scan.test.js`
+Expected: PASS — 7 tests pass (the DOM code is skipped under Node because `document` is undefined).
+
+- [ ] **Step 3: Lint-check the file parses as valid JS**
+
+Run: `node --check web/resources/static/js/qr-scan.js`
+Expected: no output, exit 0.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add web/resources/static/js/qr-scan.js
+git commit -m "feat(qr): live camera overlay, decode loop, and file fallback"
+```
+
+---
+
+## Task 4: Overlay + button CSS
+
+**Files:**
+- Modify: `web/resources/static/css/terminal.css:219-230` (the existing `.camera-scan` block)
+
+- [ ] **Step 1: Update the `.camera-scan` rule and add overlay styles**
+
+In `web/resources/static/css/terminal.css`, replace this block:
+
+```css
+/* Mobile-only camera-launch button (profile + event screens).
+   Hidden by default; shown only on mobile, matching the .bottom-nav
+   breakpoint (max-width: 768px). */
+.camera-scan {
+  display: none;
+}
+@media (max-width: 768px) {
+  .camera-scan {
+    display: inline-flex;
+    margin: 12px auto 0;
+  }
+}
+```
+
+with:
+
+```css
+/* Mobile-only "scan to connect" button (profile + event + home screens).
+   The wrapper is hidden by default and shown only on mobile, matching the
+   .bottom-nav breakpoint (max-width: 768px). */
+.camera-scan {
+  display: none;
+}
+@media (max-width: 768px) {
+  .camera-scan {
+    display: flex;
+    justify-content: center;
+    margin: 12px 0 0;
+  }
+}
+
+/* Fullscreen live QR scanner overlay (built by js/qr-scan.js). */
+.qr-scan-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.92);
+}
+.qr-scan-backdrop {
+  position: absolute;
+  inset: 0;
+}
+.qr-scan-stage {
+  position: relative;
+  z-index: 1;
+  width: min(90vw, 90vh);
+  max-width: 480px;
+  aspect-ratio: 1 / 1;
+}
+.qr-scan-video {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  border-radius: 8px;
+  background: #000;
+}
+.qr-scan-frame {
+  position: absolute;
+  inset: 12%;
+  border: 2px solid rgba(255, 255, 255, 0.9);
+  border-radius: 8px;
+  box-shadow: 0 0 0 9999px rgba(0, 0, 0, 0.25);
+  pointer-events: none;
+}
+.qr-scan-hint {
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: -2.4rem;
+  text-align: center;
+  color: #fff;
+  font-size: 0.85rem;
+  opacity: 0;
+  transition: opacity 0.2s;
+}
+.qr-scan-hint.show {
+  opacity: 1;
+}
+.qr-scan-cancel {
+  position: relative;
+  z-index: 1;
+  margin-top: 2.6rem;
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add web/resources/static/css/terminal.css
+git commit -m "feat(qr): scanner overlay and mobile button styles"
+```
+
+---
+
+## Task 5: Update the CameraScanButton component
+
+**Files:**
+- Modify: `features/common/layouts/camerabutton.templ`
+
+- [ ] **Step 1: Replace the component markup**
+
+Replace the entire contents of `features/common/layouts/camerabutton.templ` with:
+
+```templ
+package layouts
+
+// CameraScanButton renders a mobile-only "scan to connect" button. Tapping it
+// opens a fullscreen live QR scanner (js/qr-scan.js): the rear camera streams,
+// frames are decoded with jsQR, and a scanned atmo.quest connect code
+// (/c/{did} or /c/l/{id}) navigates straight into the connect flow.
+//
+// The hidden file input is a fallback: if the live camera is unavailable or
+// the user denies permission, qr-scan.js triggers it so the user can snap a
+// single photo of the QR, which is decoded the same way.
+//
+// Visibility is controlled entirely by CSS: the .camera-scan wrapper is
+// display:none by default and only shown under @media (max-width: 768px),
+// matching the .bottom-nav mobile breakpoint.
+templ CameraScanButton() {
+	<div class="camera-scan">
+		<button type="button" class="btn btn-ghost" data-qr-scan>📷 scan to connect</button>
+		<input type="file" accept="image/*" capture="environment" hidden/>
+	</div>
+}
+```
+
+- [ ] **Step 2: Regenerate templ**
+
+Run: `go tool templ generate -f features/common/layouts/camerabutton.templ`
+Expected: exit 0.
+
+- [ ] **Step 3: Verify the build compiles**
+
+Run: `go build ./...`
+Expected: exit 0, no output.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add features/common/layouts/camerabutton.templ features/common/layouts/camerabutton_templ.go
+git commit -m "feat(qr): turn camera button into a scan-to-connect trigger"
+```
+
+---
+
+## Task 6: Load the scanner scripts in the base layout
+
+**Files:**
+- Modify: `features/common/layouts/base.templ:38-39` (after the existing JS includes)
+
+- [ ] **Step 1: Add the two script includes**
+
+In `features/common/layouts/base.templ`, find:
+
+```templ
+			<script src={ resources.StaticPath("js/badge-toast.js") } defer></script>
+			<script src={ resources.StaticPath("js/handle-autocomplete.js") } defer></script>
+```
+
+and add the two lines immediately after them so the block reads:
+
+```templ
+			<script src={ resources.StaticPath("js/badge-toast.js") } defer></script>
+			<script src={ resources.StaticPath("js/handle-autocomplete.js") } defer></script>
+			<script src={ resources.StaticPath("js/vendor/jsqr.js") } defer></script>
+			<script src={ resources.StaticPath("js/qr-scan.js") } defer></script>
+```
+
+(jsqr.js must come before qr-scan.js; both are `defer` so they execute in document order. qr-scan.js no-ops on pages without a `[data-qr-scan]` button.)
+
+- [ ] **Step 2: Regenerate templ**
+
+Run: `go tool templ generate -f features/common/layouts/base.templ`
+Expected: exit 0.
+
+- [ ] **Step 3: Verify the build compiles**
+
+Run: `go build ./...`
+Expected: exit 0, no output.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add features/common/layouts/base.templ features/common/layouts/base_templ.go
+git commit -m "feat(qr): load jsqr + qr-scan scripts in base layout"
+```
+
+---
+
+## Task 7: Add the button to the home dashboard
+
+**Files:**
+- Modify: `features/index/pages/index.templ:132` (after the `.profile-flip-wrap` closing `</div>`)
+
+- [ ] **Step 1: Insert the shared component under the QR flip card**
+
+In `features/index/pages/index.templ`, find this region (around lines 130-133):
+
+```templ
+								>copy link</button>
+							}
+						</div>
+						<div class="home-identity-text">
+```
+
+and insert `@layouts.CameraScanButton()` between the `</div>` that closes `.profile-flip-wrap` and the `.home-identity-text` div, so it reads:
+
+```templ
+								>copy link</button>
+							}
+						</div>
+						@layouts.CameraScanButton()
+						<div class="home-identity-text">
+```
+
+- [ ] **Step 2: Regenerate templ**
+
+Run: `go tool templ generate -f features/index/pages/index.templ`
+Expected: exit 0.
+
+- [ ] **Step 3: Verify the build compiles and the button renders**
+
+Run: `go build ./... && grep -c "CameraScanButton" features/index/pages/index_templ.go`
+Expected: build exit 0; grep prints `1`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add features/index/pages/index.templ features/index/pages/index_templ.go
+git commit -m "feat(qr): add scan-to-connect button to home dashboard"
+```
+
+---
+
+## Task 8: Final verification
+
+**Files:** none (verification only)
+
+- [ ] **Step 1: Full build + regen + JS tests are clean**
+
+Run:
+```bash
+go build ./... && go tool templ generate && go test ./... && node --test web/resources/static/js/qr-scan.test.js && node --check web/resources/static/js/qr-scan.js
+```
+Expected: all succeed — Go build silent, `templ generate` clean, Go tests `ok`, the 7 jsQR tests pass, `node --check` silent.
+
+- [ ] **Step 2: Confirm the button is present on all four pages**
+
+Run:
+```bash
+grep -l "CameraScanButton" features/profile/pages/profile.templ features/event/pages/event.templ features/events/pages/detail.templ features/index/pages/index.templ
+```
+Expected: all four files listed.
+
+- [ ] **Step 3: Manual device verification (mobile or emulated mobile ≤768px)**
+
+Confirm by hand (cannot be automated — camera + DOM):
+- The `📷 scan to connect` button appears on profile, `/e/{token}`, `/events/{token}`, and `/` (home), and is hidden on desktop widths.
+- Tapping opens the fullscreen overlay using the **rear** camera.
+- Scanning another profile's QR navigates to `/c/...` and connects.
+- A non-atmo.quest QR shows the "not an atmo.quest code — keep scanning" hint and keeps scanning.
+- Denying camera permission falls back to the photo-capture sheet; a photo of a valid QR still connects.
+- Cancel / tapping the backdrop closes the overlay and releases the camera (camera indicator clears).
-- 
knotmirror 0.0.1