From 90b52dfc80efc5ebf53b8560b05d5b13fd268b4c Mon Sep 17 00:00:00 2001
From: KazanderDad <98373366+KazanderDad@users.noreply.github.com>
Date: Sun, 9 Nov 2025 12:37:17 -0500
Subject: [PATCH 1/2] feat(frontend): improve qr share and handshake flow

---
 frontend/__tests__/app-header.test.tsx        |   2 +-
 frontend/__tests__/profile-page.test.tsx      |  82 ++++++++
 frontend/__tests__/scan-camera-page.test.tsx  |  61 +++++-
 frontend/__tests__/scan-qr-page.test.tsx      |  92 +++++++++
 frontend/package.json                         |   1 +
 frontend/src/app/(routes)/new-user/page.tsx   |  10 +-
 frontend/src/app/(routes)/profile/page.tsx    | 121 ++++++++---
 .../src/app/(routes)/scan/camera/page.tsx     | 189 ++++++++++--------
 frontend/src/app/(routes)/scan/my-qr/page.tsx |  57 +++++-
 frontend/src/app/layout.tsx                   |   2 +-
 frontend/src/app/page.tsx                     |   4 +-
 frontend/src/components/AppFooter.tsx         |   2 +-
 frontend/src/components/AppHeader.tsx         |   8 +-
 frontend/src/components/QRDisplay.tsx         |  39 +++-
 frontend/src/components/QRScanner.tsx         | 105 ++++++++--
 frontend/src/lib/handshake.ts                 |  73 +++++++
 pnpm-lock.yaml                                |  15 ++
 17 files changed, 710 insertions(+), 153 deletions(-)
 create mode 100644 frontend/__tests__/profile-page.test.tsx
 create mode 100644 frontend/__tests__/scan-qr-page.test.tsx
 create mode 100644 frontend/src/lib/handshake.ts

diff --git a/frontend/__tests__/app-header.test.tsx b/frontend/__tests__/app-header.test.tsx
index e3c70b2..072e0d4 100644
--- a/frontend/__tests__/app-header.test.tsx
+++ b/frontend/__tests__/app-header.test.tsx
@@ -38,7 +38,7 @@ describe("AppHeader", () => {
 
     render(<AppHeader />);
 
-    expect(screen.getByRole("link", { name: /Peer Mapper/i })).toHaveAttribute("href", "/");
+    expect(screen.getByRole("link", { name: /Trust Me Bro/i })).toHaveAttribute("href", "/");
     expect(screen.getByRole("link", { name: /My QR code/i })).toHaveAttribute("href", "/scan/my-qr");
     expect(screen.getByRole("link", { name: /Camera/i })).toHaveAttribute("href", "/scan/camera");
     expect(screen.getByRole("link", { name: /My Circle/i })).toHaveAttribute("href", "/circle");
diff --git a/frontend/__tests__/profile-page.test.tsx b/frontend/__tests__/profile-page.test.tsx
new file mode 100644
index 0000000..5b102bf
--- /dev/null
+++ b/frontend/__tests__/profile-page.test.tsx
@@ -0,0 +1,82 @@
+import type { Session } from "@supabase/supabase-js";
+import { act, fireEvent, render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import ProfilePage from "../src/app/(routes)/profile/page";
+import { useUserStore } from "../src/lib/store";
+
+const { replaceMock } = vi.hoisted(() => ({
+  replaceMock: vi.fn(),
+}));
+
+vi.mock("next/navigation", () => ({
+  useRouter: () => ({
+    replace: replaceMock,
+  }),
+}));
+
+describe("ProfilePage", () => {
+  beforeEach(() => {
+    replaceMock.mockReset();
+    act(() => {
+      useUserStore.getState().reset();
+    });
+
+    const session = {
+      access_token: "token",
+      user: { id: "user-1", email: "user@example.com" },
+    } as unknown as Session;
+
+    act(() => {
+      useUserStore.setState({
+        session,
+        user: {
+          user_id: session.user.id,
+          cubid_id: "cubid_me",
+          display_name: "Maple Leaf",
+          photo_url: "https://example.com/photo.png",
+        },
+      });
+    });
+  });
+
+  afterEach(() => {
+    act(() => {
+      useUserStore.getState().reset();
+    });
+  });
+
+  it("shows an on-page preview of the profile", () => {
+    render(<ProfilePage />);
+
+    expect(screen.getByText(/This name can be a nickname/i)).toBeInTheDocument();
+    expect(screen.getByText(/Maple Leaf/)).toBeInTheDocument();
+
+    const previewHeading = screen.getByRole("heading", { name: /Preview for peers/i });
+    const previewAside = previewHeading.closest("aside");
+    expect(previewAside).not.toBeNull();
+    if (previewAside) {
+      expect(within(previewAside).getByText(/Cubid ID: cubid_me/)).toBeInTheDocument();
+    }
+
+    const previewImage = screen.getByAltText(/Profile photo preview/i) as HTMLImageElement;
+    expect(previewImage.src).toContain("https://example.com/photo.png");
+  });
+
+  it("surfaces a warning when the photo URL cannot load", async () => {
+    const user = userEvent.setup();
+
+    render(<ProfilePage />);
+
+    const photoInput = screen.getByLabelText(/Photo URL/i);
+    await user.clear(photoInput);
+    await user.type(photoInput, "https://example.com/broken.png");
+
+    const previewImage = screen.getByAltText(/Profile photo preview/i);
+    fireEvent.error(previewImage);
+
+    expect(screen.getByText(/We couldn’t load this image/i)).toBeInTheDocument();
+    expect(screen.getByText("!")).toBeInTheDocument();
+  });
+});
diff --git a/frontend/__tests__/scan-camera-page.test.tsx b/frontend/__tests__/scan-camera-page.test.tsx
index 546c1d7..af265d2 100644
--- a/frontend/__tests__/scan-camera-page.test.tsx
+++ b/frontend/__tests__/scan-camera-page.test.tsx
@@ -1,17 +1,26 @@
 import type { Session } from "@supabase/supabase-js";
 import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 import CameraPage from "../src/app/(routes)/scan/camera/page";
 import { useScanStore } from "../src/lib/scanStore";
 import { useUserStore } from "../src/lib/store";
 
-const { pushMock, requestQrChallengeMock, verifyQrChallengeMock, ensureWalletMock } = vi.hoisted(() => ({
+const {
+  pushMock,
+  requestQrChallengeMock,
+  verifyQrChallengeMock,
+  ensureWalletMock,
+  getUserMediaMock,
+  notifyHandshakeCompleteMock,
+} = vi.hoisted(() => ({
   pushMock: vi.fn(),
   requestQrChallengeMock: vi.fn(),
   verifyQrChallengeMock: vi.fn(),
   ensureWalletMock: vi.fn(),
+  getUserMediaMock: vi.fn(),
+  notifyHandshakeCompleteMock: vi.fn(),
 }));
 
 vi.mock("next/navigation", () => ({
@@ -29,12 +38,28 @@ vi.mock("../src/lib/wallet", () => ({
   ensureWallet: ensureWalletMock,
 }));
 
+vi.mock("../src/lib/handshake", () => ({
+  notifyHandshakeComplete: notifyHandshakeCompleteMock,
+}));
+
+const originalPlay = HTMLMediaElement.prototype.play;
+
+beforeAll(() => {
+  HTMLMediaElement.prototype.play = vi.fn().mockResolvedValue(undefined);
+});
+
+afterAll(() => {
+  HTMLMediaElement.prototype.play = originalPlay;
+});
+
 describe("CameraPage", () => {
   beforeEach(() => {
     pushMock.mockReset();
     requestQrChallengeMock.mockReset();
     verifyQrChallengeMock.mockReset();
     ensureWalletMock.mockReset();
+    getUserMediaMock.mockReset();
+    notifyHandshakeCompleteMock.mockReset();
     act(() => {
       useUserStore.getState().reset();
       useScanStore.getState().reset();
@@ -51,6 +76,15 @@ describe("CameraPage", () => {
       walletAddress: null,
     });
 
+    getUserMediaMock.mockResolvedValue({
+      getTracks: () => [{ stop: vi.fn() }],
+    } as unknown as MediaStream);
+
+    Object.defineProperty(window.navigator, "mediaDevices", {
+      configurable: true,
+      value: { getUserMedia: getUserMediaMock },
+    });
+
     const ethereumRequest = vi.fn();
     (window as typeof window & { ethereum?: { request: ReturnType<typeof vi.fn> } }).ethereum = {
       request: ethereumRequest,
@@ -59,6 +93,7 @@ describe("CameraPage", () => {
 
   afterEach(() => {
     delete (window as typeof window & { ethereum?: unknown }).ethereum;
+    delete (window.navigator as Navigator & { mediaDevices?: MediaDevices }).mediaDevices;
   });
 
   it("completes the QR verification happy path", async () => {
@@ -86,8 +121,14 @@ describe("CameraPage", () => {
       ],
     });
 
+    notifyHandshakeCompleteMock.mockResolvedValueOnce(undefined);
+
     render(<CameraPage />);
 
+    await waitFor(() => expect(getUserMediaMock).toHaveBeenCalled());
+    const devSummary = await screen.findByText(/for devs only/i);
+    await user.click(devSummary);
+
     const payloadTextarea = screen.getByPlaceholderText(/Paste JSON like/);
     const targetAddress = "0x000000000000000000000000000000000000dEaD";
     fireEvent.change(payloadTextarea, {
@@ -138,6 +179,18 @@ describe("CameraPage", () => {
       ),
     );
 
+    await waitFor(() =>
+      expect(notifyHandshakeCompleteMock).toHaveBeenCalledWith({
+        challengeId: "challenge-1",
+        expiresAt: 1700001200,
+        overlaps: [
+          { issuer: "0xIssuer", trustLevel: 4, circle: null, freshnessSeconds: 42 },
+        ],
+        targetCubid: "cubid_peer",
+        viewerCubid: "cubid_me",
+      }),
+    );
+
     await waitFor(() => expect(pushMock).toHaveBeenCalledWith("/results"));
 
     const result = useScanStore.getState().lastResult;
@@ -150,6 +203,10 @@ describe("CameraPage", () => {
 
     render(<CameraPage />);
 
+    await waitFor(() => expect(getUserMediaMock).toHaveBeenCalled());
+    const devSummary = await screen.findByText(/for devs only/i);
+    await user.click(devSummary);
+
     const payloadTextarea = screen.getByPlaceholderText(/Paste JSON like/);
     fireEvent.change(payloadTextarea, {
       target: { value: '{"address":"0xPeer"}' },
diff --git a/frontend/__tests__/scan-qr-page.test.tsx b/frontend/__tests__/scan-qr-page.test.tsx
new file mode 100644
index 0000000..05be86d
--- /dev/null
+++ b/frontend/__tests__/scan-qr-page.test.tsx
@@ -0,0 +1,92 @@
+import type { Session } from "@supabase/supabase-js";
+import { act, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import MyQrPage from "../src/app/(routes)/scan/my-qr/page";
+import type { HandshakeCompletion } from "../src/lib/handshake";
+import { useScanStore } from "../src/lib/scanStore";
+import { useUserStore } from "../src/lib/store";
+
+const { pushMock, subscribeToHandshakeMock } = vi.hoisted(() => ({
+  pushMock: vi.fn(),
+  subscribeToHandshakeMock: vi.fn(),
+}));
+
+vi.mock("next/navigation", () => ({
+  useRouter: () => ({
+    push: pushMock,
+  }),
+}));
+
+vi.mock("../src/lib/handshake", () => ({
+  subscribeToHandshake: subscribeToHandshakeMock,
+}));
+
+describe("MyQrPage", () => {
+  beforeEach(() => {
+    pushMock.mockReset();
+    subscribeToHandshakeMock.mockReset();
+    act(() => {
+      useUserStore.getState().reset();
+      useScanStore.getState().reset();
+    });
+
+    const session = { access_token: "token", user: { id: "user-1" } } as unknown as Session;
+    useUserStore.setState({
+      session,
+      user: {
+        user_id: "user-1",
+        cubid_id: "cubid_me",
+        display_name: "Casey Rivers",
+      },
+    });
+  });
+
+  afterEach(() => {
+    subscribeToHandshakeMock.mockReset();
+  });
+
+  it("renders the QR code and profile name", async () => {
+    subscribeToHandshakeMock.mockReturnValue(() => undefined);
+
+    render(<MyQrPage />);
+
+    await waitFor(() => expect(subscribeToHandshakeMock).toHaveBeenCalledWith("cubid_me", expect.any(Function)));
+
+    expect(screen.getByRole("img", { name: /scan this within ninety seconds/i })).toBeInTheDocument();
+    expect(screen.getByText("Casey Rivers")).toBeInTheDocument();
+    expect(screen.getByText(/Cubid ID: cubid_me/i)).toBeInTheDocument();
+  });
+
+  it("redirects to results when a handshake completes", async () => {
+    let handler: ((payload: HandshakeCompletion) => void) | null = null;
+    subscribeToHandshakeMock.mockImplementation((_cubid, callback) => {
+      handler = callback;
+      return vi.fn();
+    });
+
+    render(<MyQrPage />);
+
+    await waitFor(() => expect(handler).toBeInstanceOf(Function));
+
+    const payload: HandshakeCompletion = {
+      challengeId: "challenge-1",
+      expiresAt: 1700001200,
+      overlaps: [],
+      targetCubid: "cubid_me",
+      viewerCubid: "cubid_peer",
+    };
+
+    await act(async () => {
+      handler?.(payload);
+    });
+
+    await waitFor(() => expect(pushMock).toHaveBeenCalledWith("/results"));
+
+    expect(screen.getByText(/Handshake completed/i)).toBeInTheDocument();
+    const result = useScanStore.getState().lastResult;
+    expect(result?.challengeId).toBe("challenge-1");
+    expect(result?.viewerCubid).toBe("cubid_peer");
+    expect(result?.targetCubid).toBe("cubid_me");
+  });
+});
diff --git a/frontend/package.json b/frontend/package.json
index 95d56d6..a187749 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -12,6 +12,7 @@
   "dependencies": {
     "@supabase/ssr": "^0.7.0",
     "@supabase/supabase-js": "^2.80.0",
+    "qrcode.react": "^4.2.0",
     "next": "16.0.1",
     "react": "19.2.0",
     "react-dom": "19.2.0",
diff --git a/frontend/src/app/(routes)/new-user/page.tsx b/frontend/src/app/(routes)/new-user/page.tsx
index 0af7f2c..a1a3b9f 100644
--- a/frontend/src/app/(routes)/new-user/page.tsx
+++ b/frontend/src/app/(routes)/new-user/page.tsx
@@ -29,10 +29,10 @@ export default function NewUserPage() {
       router.replace("/(routes)/signin");
       return;
     }
-    if (profile?.cubid_id && profile?.display_name && profile?.evm_address) {
-      router.replace("/(routes)/circle");
+    if (profile?.cubid_id) {
+      router.replace("/(routes)/profile");
     }
-  }, [profile, router, session]);
+  }, [profile?.cubid_id, router, session]);
 
   useEffect(() => {
     setForm({
@@ -105,7 +105,7 @@ export default function NewUserPage() {
   return (
     <section className="space-y-6">
       <header className="space-y-2">
-        <h1 className="text-3xl font-semibold">Welcome to Peer Mapper</h1>
+        <h1 className="text-3xl font-semibold">Welcome to Trust Me Bro</h1>
         <p className="text-muted-foreground">
           Confirm your Cubid identity, pick a display name, and connect your Nova/EVM wallet to start vouching and scanning.
         </p>
@@ -119,7 +119,7 @@ export default function NewUserPage() {
             <input
               className="rounded border border-neutral-300 px-3 py-2 text-base shadow-sm focus:border-neutral-500 focus:outline-none dark:border-neutral-700 dark:bg-neutral-900"
               onChange={(event) => setForm((prev) => ({ ...prev, displayName: event.target.value }))}
-              placeholder="Casey Mapper"
+              placeholder="Casey Rivers"
               value={form.displayName}
             />
           </label>
diff --git a/frontend/src/app/(routes)/profile/page.tsx b/frontend/src/app/(routes)/profile/page.tsx
index bf60276..74c4b4e 100644
--- a/frontend/src/app/(routes)/profile/page.tsx
+++ b/frontend/src/app/(routes)/profile/page.tsx
@@ -1,7 +1,8 @@
 "use client";
+ 
 
 import { useRouter } from "next/navigation";
-import { type FormEvent, useEffect, useState } from "react";
+import { type FormEvent, useEffect, useMemo, useState } from "react";
 
 import { upsertMyProfile } from "../../../lib/profile";
 import { useUserStore } from "../../../lib/store";
@@ -12,10 +13,23 @@ export default function ProfilePage() {
   const profile = useUserStore((state) => state.user);
   const setUser = useUserStore((state) => state.setUser);
 
-  const [displayName, setDisplayName] = useState("");
-  const [photoUrl, setPhotoUrl] = useState("");
+  const [displayName, setDisplayName] = useState(profile?.display_name ?? "");
+  const [photoUrl, setPhotoUrl] = useState(profile?.photo_url ?? "");
   const [status, setStatus] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
+  const [imageError, setImageError] = useState(false);
+
+  const photoPreviewUrl = useMemo(() => photoUrl || profile?.photo_url || "", [photoUrl, profile?.photo_url]);
+  const previewName = displayName || profile?.display_name || "Your chosen name";
+
+  useEffect(() => {
+    setDisplayName(profile?.display_name ?? "");
+    setPhotoUrl(profile?.photo_url ?? "");
+  }, [profile?.display_name, profile?.photo_url]);
+
+  useEffect(() => {
+    setImageError(false);
+  }, [photoPreviewUrl]);
 
   useEffect(() => {
     if (!session) {
@@ -51,7 +65,9 @@ export default function ProfilePage() {
     <section className="space-y-6">
       <header className="space-y-2">
         <h1 className="text-3xl font-semibold">My profile</h1>
-        <p className="text-muted-foreground">Review your Cubid ID and refresh your display information.</p>
+        <p className="text-muted-foreground">
+          This name can be a nickname. Your name, picture, and Cubid ID are what you share with anyone you invite to connect.
+        </p>
       </header>
 
       <div className="rounded border border-neutral-300 p-3 text-sm shadow-sm dark:border-neutral-800">
@@ -59,36 +75,75 @@ export default function ProfilePage() {
         <p>Wallet: {profile?.evm_address ?? "—"}</p>
       </div>
 
-      <form className="space-y-4" onSubmit={handleSubmit}>
-        <label className="flex flex-col gap-1 text-sm font-medium">
-          Display name
-          <input
-            value={displayName || profile?.display_name || ""}
-            onChange={(event) => setDisplayName(event.target.value)}
-            className="w-full rounded border border-neutral-300 px-3 py-2 text-base shadow-sm focus:border-neutral-500 focus:outline-none dark:border-neutral-700 dark:bg-neutral-900"
-            placeholder="Casey Mapper"
-          />
-        </label>
-        <label className="flex flex-col gap-1 text-sm font-medium">
-          Photo URL
-          <input
-            value={photoUrl || profile?.photo_url || ""}
-            onChange={(event) => setPhotoUrl(event.target.value)}
-            className="w-full rounded border border-neutral-300 px-3 py-2 text-base shadow-sm focus:border-neutral-500 focus:outline-none dark:border-neutral-700 dark:bg-neutral-900"
-            placeholder="https://example.com/avatar.png"
-          />
-        </label>
-        <button
-          className="rounded bg-blue-600 px-4 py-2 text-white shadow-sm transition hover:bg-blue-500 disabled:opacity-60"
-          disabled={!session}
-          type="submit"
-        >
-          Save changes
-        </button>
-      </form>
+      <div className="grid gap-8 lg:grid-cols-[minmax(0,1fr)_minmax(0,1fr)]">
+        <form className="space-y-4" onSubmit={handleSubmit}>
+          <label className="flex flex-col gap-1 text-sm font-medium">
+            Display name
+            <input
+              value={displayName}
+              onChange={(event) => setDisplayName(event.target.value)}
+              className="w-full rounded border border-neutral-300 px-3 py-2 text-base shadow-sm focus:border-neutral-500 focus:outline-none dark:border-neutral-700 dark:bg-neutral-900"
+              placeholder="Casey Rivers"
+            />
+          </label>
+          <label className="flex flex-col gap-1 text-sm font-medium">
+            Photo URL
+            <input
+              value={photoUrl}
+              onChange={(event) => setPhotoUrl(event.target.value)}
+              className="w-full rounded border border-neutral-300 px-3 py-2 text-base shadow-sm focus:border-neutral-500 focus:outline-none dark:border-neutral-700 dark:bg-neutral-900"
+              placeholder="https://example.com/avatar.png"
+            />
+          </label>
+          <button
+            className="rounded bg-blue-600 px-4 py-2 text-white shadow-sm transition hover:bg-blue-500 disabled:opacity-60"
+            disabled={!session}
+            type="submit"
+          >
+            Save changes
+          </button>
+          {status ? <p className="text-sm text-green-600 dark:text-green-400">{status}</p> : null}
+          {error ? <p className="text-sm text-red-600 dark:text-red-400">{error}</p> : null}
+        </form>
 
-      {status ? <p className="text-sm text-green-600 dark:text-green-400">{status}</p> : null}
-      {error ? <p className="text-sm text-red-600 dark:text-red-400">{error}</p> : null}
+        <aside className="space-y-4 rounded border border-neutral-300 p-4 text-sm shadow-sm dark:border-neutral-800">
+          <div className="space-y-2">
+            <h2 className="text-lg font-semibold">Preview for peers</h2>
+            <p className="text-muted-foreground">
+              Here’s how your profile appears to someone you invite. Double-check the image link below before you share it.
+            </p>
+          </div>
+          <div className="flex items-center gap-4">
+            {photoPreviewUrl && !imageError ? (
+              <span className="inline-flex h-24 w-24 overflow-hidden rounded-full border border-neutral-300 shadow-sm dark:border-neutral-700">
+                <img
+                  alt="Profile photo preview"
+                  className="h-full w-full object-cover"
+                  src={photoPreviewUrl}
+                  onError={() => setImageError(true)}
+                />
+              </span>
+            ) : (
+              <span className="inline-flex h-24 w-24 items-center justify-center rounded-full border border-dashed border-neutral-300 bg-neutral-100 text-base font-semibold text-neutral-500 dark:border-neutral-700 dark:bg-neutral-900 dark:text-neutral-400">
+                {photoPreviewUrl && imageError ? "!" : "No photo"}
+              </span>
+            )}
+            <div className="space-y-1">
+              <p className="text-base font-semibold">{previewName}</p>
+              <p className="text-xs uppercase tracking-[0.2em] text-neutral-500 dark:text-neutral-400">Trust Me Bro</p>
+              <p className="text-sm text-muted-foreground">Cubid ID: {profile?.cubid_id ?? "Pending from onboarding"}</p>
+            </div>
+          </div>
+          {photoPreviewUrl && imageError ? (
+            <p className="rounded border border-amber-400/70 bg-amber-50/70 p-2 text-sm text-amber-700 dark:border-amber-500/60 dark:bg-amber-500/10 dark:text-amber-200">
+              We couldn’t load this image. Confirm the URL works in a new tab, then paste it here again.
+            </p>
+          ) : null}
+          {!photoPreviewUrl && !imageError ? (
+            <p className="text-xs text-muted-foreground">Add a photo URL above to see it rendered here.</p>
+          ) : null}
+        </aside>
+      </div>
     </section>
   );
 }
diff --git a/frontend/src/app/(routes)/scan/camera/page.tsx b/frontend/src/app/(routes)/scan/camera/page.tsx
index 3b5db37..24fa047 100644
--- a/frontend/src/app/(routes)/scan/camera/page.tsx
+++ b/frontend/src/app/(routes)/scan/camera/page.tsx
@@ -5,6 +5,7 @@ import { type FormEvent, useState } from "react";
 
 import QRScanner from "@/components/QRScanner";
 import { requestQrChallenge, verifyQrChallenge } from "@/lib/api";
+import { notifyHandshakeComplete } from "@/lib/handshake";
 import { useScanStore } from "@/lib/scanStore";
 import { useUserStore } from "@/lib/store";
 import { ensureWallet } from "@/lib/wallet";
@@ -156,15 +157,26 @@ export default function CameraPage() {
         session.access_token,
       );
 
-      setResult({
+      const completion = {
         targetCubid: parsed.cubidId,
         viewerCubid: profile.cubid_id,
         challengeId: result.challengeId,
         expiresAt: result.expiresAt,
         overlaps: result.overlaps,
-        verifiedAt: Date.now(),
-      });
-      setStatus("Overlap ready");
+      } as const;
+
+      setResult({ ...completion, verifiedAt: Date.now() });
+      setStatus("Sharing overlaps with your peer…");
+
+      try {
+        await notifyHandshakeComplete(completion);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Failed to notify peer of handshake";
+        setError(message);
+        setStatus(null);
+        return;
+      }
+
       router.push("/results");
     } catch (err) {
       const message = err instanceof Error ? err.message : "Failed to verify challenge";
@@ -184,87 +196,108 @@ export default function CameraPage() {
         </p>
       </header>
 
-      <div className="grid gap-6 lg:grid-cols-[minmax(0,1fr)_minmax(0,1fr)]">
-        <div className="space-y-4 rounded-3xl border border-slate-700/50 bg-slate-900/50 p-6 shadow-lg shadow-black/40">
+      <div className="grid gap-6 lg:grid-cols-[minmax(0,3fr)_minmax(0,2fr)]">
+        <div className="space-y-4 rounded-3xl border border-slate-700/50 bg-slate-900/60 p-6 shadow-lg shadow-black/40">
           <QRScanner />
-          <textarea
-            className="w-full rounded-2xl border border-slate-700/60 bg-slate-950/60 p-4 text-sm text-slate-100 placeholder:text-slate-500 focus:border-sky-400/70 focus:outline-none"
-            rows={3}
-            placeholder='Paste JSON like {"cubidId":"friend","address":"0x..."}'
-            value={rawQr}
-            onChange={(event) => setRawQr(event.target.value)}
-          />
-          <button
-            className="w-full rounded-full border border-sky-400/50 bg-sky-500/20 px-5 py-2 text-sm font-semibold uppercase tracking-[0.3em] text-sky-100 shadow-lg shadow-sky-900/40 transition hover:border-sky-300 hover:bg-sky-500/30"
-            onClick={handleParse}
-            type="button"
-          >
-            Parse QR payload
-          </button>
+          <p className="text-sm text-slate-300/90">
+            Allow camera access so we can scan Cubid QR codes directly. We prioritise the rear camera on mobile to keep codes in focus.
+          </p>
+          <p className="text-xs text-slate-400">
+            If the scan struggles, use the developer tools to paste a payload manually.
+          </p>
         </div>
 
-        <div className="space-y-5">
-          {parsed ? (
-            <div className="text-sm text-slate-200 space-y-3 rounded-3xl border border-slate-700/60 bg-slate-900/60 p-5 shadow-inner shadow-black/40">
-              <p className="font-medium text-slate-50">Target Cubid: {parsed.cubidId}</p>
-              <button
-                className="rounded-full border border-slate-600/70 px-4 py-2 text-xs font-semibold uppercase tracking-[0.3em] text-slate-200 transition hover:border-sky-400/60 hover:text-sky-200"
-                onClick={handleChallenge}
-                type="button"
-              >
-                Issue challenge
-              </button>
-            </div>
-          ) : null}
-
-          {challenge ? (
-            <div className="space-y-3 rounded-3xl border border-sky-500/40 bg-sky-500/10 p-5 text-sm text-sky-100 shadow-lg shadow-sky-900/40">
-              <p className="font-medium">Challenge ID: {challenge.id}</p>
-              <p className="break-all text-xs text-sky-200/80">{challenge.value}</p>
-              <button
-                className="rounded-full border border-sky-400/70 px-4 py-2 text-xs font-semibold uppercase tracking-[0.3em] text-sky-100 transition hover:border-sky-300 hover:text-sky-50"
-                onClick={handleSignChallenge}
-                type="button"
-              >
-                Sign as viewer
-              </button>
-            </div>
-          ) : null}
-
-          {challenge ? (
-            <form className="space-y-4 rounded-3xl border border-slate-700/60 bg-slate-900/60 p-5 shadow-inner shadow-black/40" onSubmit={handleVerify}>
-              <label className="flex flex-col gap-2 text-xs font-semibold uppercase tracking-[0.3em] text-slate-300">
-                Target wallet address
-                <input
-                  value={targetAddress}
-                  onChange={(event) => setTargetAddress(event.target.value)}
-                  className="w-full rounded-xl border border-slate-700/60 bg-slate-950/60 px-4 py-2 text-sm text-slate-100 focus:border-sky-400/70 focus:outline-none"
-                  placeholder="0x…"
-                />
-              </label>
-              <label className="flex flex-col gap-2 text-xs font-semibold uppercase tracking-[0.3em] text-slate-300">
-                Target signature
+        <details className="rounded-3xl border border-slate-700/60 bg-slate-900/60 p-6 text-slate-200 shadow-lg shadow-black/40">
+          <summary className="cursor-pointer select-none text-xs font-semibold uppercase tracking-[0.3em] text-sky-300">
+            For devs only
+          </summary>
+          <div className="mt-5 space-y-6">
+            <p className="text-sm text-slate-300/90">
+              Manual challenge flow helpers live here so the production scan stays clean.
+            </p>
+            <div className="grid gap-6 lg:grid-cols-[minmax(0,1fr)_minmax(0,1fr)]">
+              <div className="space-y-4 rounded-3xl border border-slate-700/50 bg-slate-900/50 p-6 shadow-inner shadow-black/40">
                 <textarea
-                  value={targetSignature}
-                  onChange={(event) => setTargetSignature(event.target.value)}
-                  className="w-full rounded-xl border border-slate-700/60 bg-slate-950/60 p-3 text-sm text-slate-100 focus:border-sky-400/70 focus:outline-none"
+                  className="w-full rounded-2xl border border-slate-700/60 bg-slate-950/60 p-4 text-sm text-slate-100 placeholder:text-slate-500 focus:border-sky-400/70 focus:outline-none"
                   rows={3}
-                  placeholder="0x…"
+                  placeholder='Paste JSON like {"cubidId":"friend","address":"0x..."}'
+                  value={rawQr}
+                  onChange={(event) => setRawQr(event.target.value)}
                 />
-              </label>
-              <button
-                className="w-full rounded-full border border-emerald-400/60 bg-emerald-500/20 px-5 py-2 text-sm font-semibold uppercase tracking-[0.3em] text-emerald-100 shadow-lg shadow-emerald-900/30 transition hover:border-emerald-300 hover:bg-emerald-500/30 disabled:opacity-60"
-                disabled={!viewerSignature}
-                type="submit"
-              >
-                Verify overlap
-              </button>
-            </form>
-          ) : null}
+                <button
+                  className="w-full rounded-full border border-sky-400/50 bg-sky-500/20 px-5 py-2 text-sm font-semibold uppercase tracking-[0.3em] text-sky-100 shadow-lg shadow-sky-900/40 transition hover:border-sky-300 hover:bg-sky-500/30"
+                  onClick={handleParse}
+                  type="button"
+                >
+                  Parse QR payload
+                </button>
+              </div>
 
-          {status ? <p className="text-xs uppercase tracking-[0.3em] text-slate-300">{status}</p> : null}
-          {error ? <p className="text-sm text-rose-300">{error}</p> : null}
-        </div>
+              <div className="space-y-5">
+                {parsed ? (
+                  <div className="space-y-3 rounded-3xl border border-slate-700/60 bg-slate-900/60 p-5 text-sm text-slate-200 shadow-inner shadow-black/40">
+                    <p className="font-medium text-slate-50">Target Cubid: {parsed.cubidId}</p>
+                    <button
+                      className="rounded-full border border-slate-600/70 px-4 py-2 text-xs font-semibold uppercase tracking-[0.3em] text-slate-200 transition hover:border-sky-400/60 hover:text-sky-200"
+                      onClick={handleChallenge}
+                      type="button"
+                    >
+                      Issue challenge
+                    </button>
+                  </div>
+                ) : null}
+
+                {challenge ? (
+                  <div className="space-y-3 rounded-3xl border border-sky-500/40 bg-sky-500/10 p-5 text-sm text-sky-100 shadow-lg shadow-sky-900/40">
+                    <p className="font-medium">Challenge ID: {challenge.id}</p>
+                    <p className="break-all text-xs text-sky-200/80">{challenge.value}</p>
+                    <button
+                      className="rounded-full border border-sky-400/70 px-4 py-2 text-xs font-semibold uppercase tracking-[0.3em] text-sky-100 transition hover:border-sky-300 hover:text-sky-50"
+                      onClick={handleSignChallenge}
+                      type="button"
+                    >
+                      Sign as viewer
+                    </button>
+                  </div>
+                ) : null}
+
+                {challenge ? (
+                  <form className="space-y-4 rounded-3xl border border-slate-700/60 bg-slate-900/60 p-5 shadow-inner shadow-black/40" onSubmit={handleVerify}>
+                    <label className="flex flex-col gap-2 text-xs font-semibold uppercase tracking-[0.3em] text-slate-300">
+                      Target wallet address
+                      <input
+                        value={targetAddress}
+                        onChange={(event) => setTargetAddress(event.target.value)}
+                        className="w-full rounded-xl border border-slate-700/60 bg-slate-950/60 px-4 py-2 text-sm text-slate-100 focus:border-sky-400/70 focus:outline-none"
+                        placeholder="0x…"
+                      />
+                    </label>
+                    <label className="flex flex-col gap-2 text-xs font-semibold uppercase tracking-[0.3em] text-slate-300">
+                      Target signature
+                      <textarea
+                        value={targetSignature}
+                        onChange={(event) => setTargetSignature(event.target.value)}
+                        className="w-full rounded-xl border border-slate-700/60 bg-slate-950/60 p-3 text-sm text-slate-100 focus:border-sky-400/70 focus:outline-none"
+                        rows={3}
+                        placeholder="0x…"
+                      />
+                    </label>
+                    <button
+                      className="w-full rounded-full border border-emerald-400/60 bg-emerald-500/20 px-5 py-2 text-sm font-semibold uppercase tracking-[0.3em] text-emerald-100 shadow-lg shadow-emerald-900/30 transition hover:border-emerald-300 hover:bg-emerald-500/30 disabled:opacity-60"
+                      disabled={!viewerSignature}
+                      type="submit"
+                    >
+                      Verify overlap
+                    </button>
+                  </form>
+                ) : null}
+
+                {status ? <p className="text-xs uppercase tracking-[0.3em] text-slate-300">{status}</p> : null}
+                {error ? <p className="text-sm text-rose-300">{error}</p> : null}
+              </div>
+            </div>
+          </div>
+        </details>
       </div>
     </section>
   );
diff --git a/frontend/src/app/(routes)/scan/my-qr/page.tsx b/frontend/src/app/(routes)/scan/my-qr/page.tsx
index 6f6794b..330f90f 100644
--- a/frontend/src/app/(routes)/scan/my-qr/page.tsx
+++ b/frontend/src/app/(routes)/scan/my-qr/page.tsx
@@ -1,26 +1,59 @@
 "use client";
 
 import Link from "next/link";
+import { useRouter } from "next/navigation";
 import { useEffect, useMemo, useState } from "react";
 
 import QRDisplay from "@/components/QRDisplay";
+import { subscribeToHandshake } from "@/lib/handshake";
+import { useScanStore } from "@/lib/scanStore";
 import { useUserStore } from "@/lib/store";
 
 export default function MyQrPage() {
+  const router = useRouter();
   const session = useUserStore((state) => state.session);
   const profile = useUserStore((state) => state.user);
+  const setResult = useScanStore((state) => state.setResult);
 
   const [timestamp, setTimestamp] = useState(() => Date.now());
+  const [handshakeMessage, setHandshakeMessage] = useState<string | null>(null);
 
   useEffect(() => {
     setTimestamp(Date.now());
   }, [profile?.cubid_id]);
 
+  useEffect(() => {
+    setHandshakeMessage(null);
+  }, [timestamp]);
+
   const payload = useMemo(
     () => ({ cubidId: profile?.cubid_id ?? "", ts: timestamp }),
     [profile?.cubid_id, timestamp],
   );
 
+  useEffect(() => {
+    if (!profile?.cubid_id) {
+      return undefined;
+    }
+
+    const unsubscribe = subscribeToHandshake(profile.cubid_id, (payload) => {
+      setResult({
+        targetCubid: payload.targetCubid,
+        viewerCubid: payload.viewerCubid,
+        challengeId: payload.challengeId,
+        expiresAt: payload.expiresAt,
+        overlaps: payload.overlaps,
+        verifiedAt: Date.now(),
+      });
+      setHandshakeMessage("Handshake completed—opening shared overlaps…");
+      router.push("/results");
+    });
+
+    return () => {
+      unsubscribe?.();
+    };
+  }, [profile?.cubid_id, router, setResult]);
+
   if (!session) {
     return (
       <section className="space-y-4 rounded-3xl border border-white/10 bg-white/5 p-8 text-slate-200 shadow-lg shadow-sky-900/30">
@@ -40,6 +73,8 @@ export default function MyQrPage() {
     );
   }
 
+  const displayName = profile?.display_name?.trim() || "Your chosen name";
+
   return (
     <section className="space-y-8">
       <header className="space-y-3">
@@ -51,11 +86,25 @@ export default function MyQrPage() {
         </p>
       </header>
 
-      <div className="flex flex-col gap-6 md:flex-row md:items-start md:gap-12">
-        <div className="flex-1 rounded-3xl border border-slate-700/50 bg-slate-900/50 p-6 shadow-lg shadow-black/40">
-          <QRDisplay payload={payload} />
+      <div className="grid gap-6 lg:grid-cols-[minmax(0,3fr)_minmax(0,2fr)]">
+        <div className="flex flex-col items-center gap-6 rounded-3xl border border-slate-700/50 bg-slate-900/60 p-8 text-center text-slate-100 shadow-lg shadow-black/40">
+          <QRDisplay
+            caption="Scan this within ninety seconds to stay in sync."
+            payload={payload}
+            size={320}
+          />
+          <div className="space-y-1">
+            <p className="text-lg font-semibold text-slate-50">{displayName}</p>
+            <p className="text-xs uppercase tracking-[0.3em] text-slate-400">Trust Me Bro</p>
+            <p className="text-sm text-slate-300">Cubid ID: {profile?.cubid_id ?? "—"}</p>
+          </div>
+          {handshakeMessage ? (
+            <p className="rounded-full border border-emerald-400/60 bg-emerald-500/20 px-4 py-2 text-xs font-semibold uppercase tracking-[0.3em] text-emerald-100">
+              {handshakeMessage}
+            </p>
+          ) : null}
         </div>
-        <div className="max-w-sm space-y-4 text-sm text-slate-200">
+        <div className="max-w-xl space-y-4 text-left text-sm text-slate-200">
           <p>
             <strong className="text-slate-50">Need onboarding?</strong> Make sure your profile carries a Cubid ID so peers can
             locate you instantly.
diff --git a/frontend/src/app/layout.tsx b/frontend/src/app/layout.tsx
index d8bebf1..4d51860 100644
--- a/frontend/src/app/layout.tsx
+++ b/frontend/src/app/layout.tsx
@@ -8,7 +8,7 @@ import { AppHeader } from "../components/AppHeader";
 import { AuthProvider } from "../components/AuthProvider";
 
 export const metadata: Metadata = {
-  title: "Peer Mapper",
+  title: "Trust Me Bro",
   description: "QR-powered trust overlaps on Moonbeam",
 };
 
diff --git a/frontend/src/app/page.tsx b/frontend/src/app/page.tsx
index 4c1bb9a..b5e06f5 100644
--- a/frontend/src/app/page.tsx
+++ b/frontend/src/app/page.tsx
@@ -8,7 +8,7 @@ const HIGHLIGHTS = [
   {
     title: "Prove people are known, not anonymous",
     description:
-      "Peer Mapper connects Supabase auth, Cubid IDs, and Ethereum attestations so you can verify that the human in front of you is vouched for by people you already trust.",
+      "Trust Me Bro connects Supabase auth, Cubid IDs, and Ethereum attestations so you can verify that the human in front of you is vouched for by people you already trust.",
   },
   {
     title: "QR handshakes in under a minute",
@@ -72,7 +72,7 @@ export default function Home() {
       <main className="mx-auto flex w-full max-w-5xl flex-col gap-16">
         <section className="rounded-3xl border border-white/10 bg-white/5 p-10 shadow-xl shadow-sky-900/20 backdrop-blur">
           <div className="mb-6 flex flex-col gap-3 text-sky-200">
-            <span className="text-xs font-semibold uppercase tracking-[0.4em] text-sky-400/90">Peer Mapper</span>
+            <span className="text-xs font-semibold uppercase tracking-[0.4em] text-sky-400/90">Trust Me Bro</span>
             <h1 className="text-4xl font-bold leading-tight text-slate-50 sm:text-5xl">
               Trust people faster with verifiable overlaps
             </h1>
diff --git a/frontend/src/components/AppFooter.tsx b/frontend/src/components/AppFooter.tsx
index f67630f..0263343 100644
--- a/frontend/src/components/AppFooter.tsx
+++ b/frontend/src/components/AppFooter.tsx
@@ -31,7 +31,7 @@ export function AppFooter() {
             </li>
           ))}
         </ol>
-        <p className="text-xs text-slate-500">© {new Date().getFullYear()} Peer Mapper • Built for trusted introductions on Moonbeam.</p>
+        <p className="text-xs text-slate-500">© {new Date().getFullYear()} Trust Me Bro • Built for trusted introductions on Moonbeam.</p>
       </div>
     </footer>
   );
diff --git a/frontend/src/components/AppHeader.tsx b/frontend/src/components/AppHeader.tsx
index 7746819..c7f082a 100644
--- a/frontend/src/components/AppHeader.tsx
+++ b/frontend/src/components/AppHeader.tsx
@@ -7,9 +7,9 @@ import { useMemo } from "react";
 import { useUserStore } from "../lib/store";
 
 function getInitials(value: string | null | undefined): string {
-  if (!value) return "PM";
+  if (!value) return "TM";
   const trimmed = value.trim();
-  if (!trimmed) return "PM";
+  if (!trimmed) return "TM";
   const segments = trimmed.split(/\s+/).slice(0, 2);
   if (segments.length === 1) {
     return segments[0]!.slice(0, 2).toUpperCase();
@@ -25,7 +25,7 @@ export function AppHeader() {
   const session = useUserStore((state) => state.session);
   const profile = useUserStore((state) => state.user);
 
-  const displayName = profile?.display_name ?? session?.user?.email ?? "Peer Mapper";
+  const displayName = profile?.display_name ?? session?.user?.email ?? "Trust Me Bro";
   const avatarInitials = useMemo(
     () => getInitials(profile?.display_name ?? profile?.cubid_id ?? session?.user?.email),
     [profile?.cubid_id, profile?.display_name, session?.user?.email],
@@ -39,7 +39,7 @@ export function AppHeader() {
     <header className="sticky top-0 z-20 border-b border-white/10 bg-black/40 backdrop-blur">
       <div className="mx-auto flex w-full max-w-6xl items-center justify-between px-6 py-4 text-sm text-slate-200">
         <Link className="font-semibold tracking-wide text-slate-100 transition hover:text-sky-300" href="/">
-          Peer Mapper
+          Trust Me Bro
         </Link>
 
         <nav className="flex items-center gap-6 text-xs font-semibold uppercase tracking-[0.2em] text-slate-300">
diff --git a/frontend/src/components/QRDisplay.tsx b/frontend/src/components/QRDisplay.tsx
index 39d158d..869c94e 100644
--- a/frontend/src/components/QRDisplay.tsx
+++ b/frontend/src/components/QRDisplay.tsx
@@ -1,13 +1,40 @@
 "use client";
 
+import { QRCodeSVG } from "qrcode.react";
 import { useMemo } from "react";
 
-export default function QRDisplay({ payload }: { payload?: Record<string, unknown> }) {
-  const text = useMemo(() => JSON.stringify(payload ?? { cubidId: "demo", ts: Date.now() }), [payload]);
+type QRDisplayProps = {
+  payload?: Record<string, unknown>;
+  caption?: string;
+  size?: number;
+};
+
+export default function QRDisplay({ payload, caption, size = 288 }: QRDisplayProps) {
+  const text = useMemo(
+    () => JSON.stringify(payload ?? { cubidId: "demo", ts: Date.now() }),
+    [payload],
+  );
+
   return (
-    <div className="flex flex-col items-center gap-2 rounded border border-dashed border-gray-300 p-4">
-      <span className="text-sm uppercase tracking-widest text-gray-500">QR payload</span>
-      <code className="text-sm">{text}</code>
-    </div>
+    <figure className="flex flex-col items-center gap-4 text-center">
+      <span className="inline-flex rounded-3xl border border-white/10 bg-white/5 p-6 shadow-lg shadow-black/40">
+        <QRCodeSVG
+          aria-label={caption ?? "QR code"}
+          role="img"
+          includeMargin
+          size={size}
+          value={text}
+          className="h-auto w-auto max-w-full"
+        />
+      </span>
+      {caption ? (
+        <figcaption className="text-sm font-medium text-slate-200">
+          {caption}
+        </figcaption>
+      ) : null}
+      <code className="max-w-full break-words rounded-2xl border border-dashed border-slate-600/60 bg-slate-900/40 px-4 py-2 text-xs text-slate-300">
+        {text}
+      </code>
+    </figure>
   );
 }
diff --git a/frontend/src/components/QRScanner.tsx b/frontend/src/components/QRScanner.tsx
index b15c2b4..b8afced 100644
--- a/frontend/src/components/QRScanner.tsx
+++ b/frontend/src/components/QRScanner.tsx
@@ -1,24 +1,97 @@
 "use client";
 
-import { useState } from "react";
+import { useEffect, useRef, useState } from "react";
+
+type CameraStatus = "idle" | "loading" | "ready" | "error" | "unsupported";
 
 export default function QRScanner() {
-  const [value, setValue] = useState("");
+  const videoRef = useRef<HTMLVideoElement | null>(null);
+  const [status, setStatus] = useState<CameraStatus>("idle");
+  const [error, setError] = useState<string | null>(null);
+  const [attempt, setAttempt] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    let currentStream: MediaStream | null = null;
+
+    async function startCamera() {
+      if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
+        setStatus("unsupported");
+        setError("Camera access is not available in this browser.");
+        return;
+      }
+
+      setStatus("loading");
+      setError(null);
+
+      try {
+        currentStream = await navigator.mediaDevices.getUserMedia({ video: { facingMode: "environment" } });
+        if (cancelled) {
+          currentStream.getTracks().forEach((track) => track.stop());
+          return;
+        }
+
+        const video = videoRef.current;
+        if (video) {
+          video.srcObject = currentStream;
+          const playPromise = video.play();
+          if (playPromise && typeof playPromise.then === "function") {
+            playPromise.catch(() => {
+              /* ignore autoplay restrictions in tests */
+            });
+          }
+        }
+
+        setStatus("ready");
+      } catch (err) {
+        currentStream?.getTracks().forEach((track) => track.stop());
+        setStatus("error");
+        setError(err instanceof Error ? err.message : "Unable to access the camera");
+      }
+    }
+
+    void startCamera();
+
+    return () => {
+      cancelled = true;
+      currentStream?.getTracks().forEach((track) => track.stop());
+    };
+  }, [attempt]);
+
+  const showOverlay = status === "loading" || status === "error" || status === "unsupported";
+
   return (
-    <div className="space-y-2">
-      <textarea
-        className="w-full rounded border border-gray-300/70 bg-transparent p-3 text-base"
-        rows={4}
-        placeholder="Paste QR payload"
-        value={value}
-        onChange={(event) => setValue(event.target.value)}
-      />
-      <button
-        disabled={!value}
-        className="rounded bg-black px-4 py-2 text-white disabled:opacity-40 dark:bg-white dark:text-black"
-      >
-        Verify
-      </button>
+    <div className="space-y-3">
+      <div className="relative flex aspect-[3/4] w-full items-center justify-center overflow-hidden rounded-3xl border border-slate-700/60 bg-slate-950/80">
+        <video
+          aria-label="Camera preview"
+          className="h-full w-full object-cover"
+          muted
+          playsInline
+          ref={videoRef}
+        />
+        {showOverlay ? (
+          <div className="absolute inset-0 flex flex-col items-center justify-center gap-2 bg-slate-950/80 text-center text-sm text-slate-200">
+            {status === "loading" ? <span>Requesting camera access…</span> : null}
+            {status === "error" || status === "unsupported" ? (
+              <>
+                <span>{error ?? "Camera unavailable"}</span>
+                <button
+                  className="rounded-full border border-sky-400/70 px-4 py-1 text-xs font-semibold uppercase tracking-[0.3em] text-sky-100 transition hover:border-sky-300"
+                  onClick={() => setAttempt((value) => value + 1)}
+                  type="button"
+                >
+                  Try again
+                </button>
+              </>
+            ) : null}
+          </div>
+        ) : null}
+      </div>
+      <p className="text-xs uppercase tracking-[0.2em] text-slate-300">Point a Cubid QR at your camera to scan it instantly.</p>
+      {status === "ready" ? (
+        <p className="text-xs text-slate-400">We keep the feed local—no footage leaves your device.</p>
+      ) : null}
     </div>
   );
 }
diff --git a/frontend/src/lib/handshake.ts b/frontend/src/lib/handshake.ts
new file mode 100644
index 0000000..990b902
--- /dev/null
+++ b/frontend/src/lib/handshake.ts
@@ -0,0 +1,73 @@
+import type { RealtimeChannel } from "@supabase/supabase-js";
+
+import type { VerifyQrResponse } from "./api";
+import { getSupabaseClient } from "./supabaseClient";
+
+export type HandshakeCompletion = {
+  challengeId: string;
+  expiresAt: number;
+  overlaps: VerifyQrResponse["overlaps"];
+  viewerCubid: string;
+  targetCubid: string;
+};
+
+const CHANNEL_PREFIX = "handshake:";
+const EVENT_NAME = "handshake-complete";
+
+async function ensureSubscribed(channel: RealtimeChannel): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    channel.subscribe((status) => {
+      if (status === "SUBSCRIBED") {
+        resolve();
+      } else if (status === "CHANNEL_ERROR" || status === "TIMED_OUT") {
+        reject(new Error(`Realtime channel error: ${status}`));
+      }
+    });
+  });
+}
+
+export async function notifyHandshakeComplete(payload: HandshakeCompletion): Promise<void> {
+  const supabase = getSupabaseClient();
+  const channel = supabase.channel(`${CHANNEL_PREFIX}${payload.targetCubid}`, {
+    config: { broadcast: { ack: true } },
+  });
+
+  try {
+    await ensureSubscribed(channel);
+    const response = await channel.send({
+      type: "broadcast",
+      event: EVENT_NAME,
+      payload,
+    });
+
+    if (response === "timed out") {
+      throw new Error("Timed out broadcasting handshake completion");
+    }
+
+    if (response === "error") {
+      throw new Error("Failed to broadcast handshake completion");
+    }
+  } finally {
+    await channel.unsubscribe();
+  }
+}
+
+export function subscribeToHandshake(
+  targetCubid: string,
+  onComplete: (payload: HandshakeCompletion) => void,
+): () => void {
+  const supabase = getSupabaseClient();
+  const channel = supabase.channel(`${CHANNEL_PREFIX}${targetCubid}`);
+
+  channel.on("broadcast", { event: EVENT_NAME }, (event) => {
+    const payload = event.payload as HandshakeCompletion | null;
+    if (!payload) return;
+    onComplete(payload);
+  });
+
+  channel.subscribe();
+
+  return () => {
+    void channel.unsubscribe();
+  };
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7b52c87..f86c2d9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -70,6 +70,9 @@ importers:
       next:
         specifier: 16.0.1
         version: 16.0.1(@babel/core@7.28.5)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
+      qrcode.react:
+        specifier: ^4.2.0
+        version: 4.2.0(react@19.2.0)
       react:
         specifier: 19.2.0
         version: 19.2.0
@@ -5670,6 +5673,14 @@ packages:
       }
     engines: { node: '>=6' }
 
+  qrcode.react@4.2.0:
+    resolution:
+      {
+        integrity: sha512-QpgqWi8rD9DsS9EP3z7BT+5lY5SFhsqGjpgW5DY/i3mK4M9DTBNz3ErMi8BWYEfI3L0d8GIbGmcdFAS1uIRGjA==,
+      }
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
   qs@6.13.0:
     resolution:
       {
@@ -10389,6 +10400,10 @@ snapshots:
 
   punycode@2.3.1: {}
 
+  qrcode.react@4.2.0(react@19.2.0):
+    dependencies:
+      react: 19.2.0
+
   qs@6.13.0:
     dependencies:
       side-channel: 1.1.0

From 10455dfc2da453398944535f8764f693246ca4e3 Mon Sep 17 00:00:00 2001
From: KazanderDad <98373366+KazanderDad@users.noreply.github.com>
Date: Sun, 9 Nov 2025 13:36:33 -0500
Subject: [PATCH 2/2] fix(frontend): harden handshake channel security

---
 frontend/__tests__/scan-camera-page.test.tsx  |  8 ++-
 frontend/__tests__/scan-qr-page.test.tsx      | 24 ++++++--
 frontend/eslint.config.mjs                    |  1 +
 .../src/app/(routes)/scan/camera/page.tsx     | 22 +++++--
 frontend/src/app/(routes)/scan/my-qr/page.tsx | 57 ++++++++++++++-----
 frontend/src/lib/handshake.ts                 | 20 ++++---
 6 files changed, 99 insertions(+), 33 deletions(-)

diff --git a/frontend/__tests__/scan-camera-page.test.tsx b/frontend/__tests__/scan-camera-page.test.tsx
index af265d2..7c421fa 100644
--- a/frontend/__tests__/scan-camera-page.test.tsx
+++ b/frontend/__tests__/scan-camera-page.test.tsx
@@ -98,6 +98,7 @@ describe("CameraPage", () => {
 
   it("completes the QR verification happy path", async () => {
     const user = userEvent.setup();
+    const handshakeChannel = "handshake-channel";
     const ethereum = (window as typeof window & {
       ethereum?: { request: ReturnType<typeof vi.fn> };
     }).ethereum;
@@ -132,7 +133,9 @@ describe("CameraPage", () => {
     const payloadTextarea = screen.getByPlaceholderText(/Paste JSON like/);
     const targetAddress = "0x000000000000000000000000000000000000dEaD";
     fireEvent.change(payloadTextarea, {
-      target: { value: `{"cubidId":"cubid_peer","address":"${targetAddress}"}` },
+      target: {
+        value: `{"cubidId":"cubid_peer","channel":"${handshakeChannel}","address":"${targetAddress}"}`,
+      },
     });
 
     await user.click(screen.getByRole("button", { name: /parse qr payload/i }));
@@ -181,6 +184,7 @@ describe("CameraPage", () => {
 
     await waitFor(() =>
       expect(notifyHandshakeCompleteMock).toHaveBeenCalledWith({
+        channel: handshakeChannel,
         challengeId: "challenge-1",
         expiresAt: 1700001200,
         overlaps: [
@@ -209,7 +213,7 @@ describe("CameraPage", () => {
 
     const payloadTextarea = screen.getByPlaceholderText(/Paste JSON like/);
     fireEvent.change(payloadTextarea, {
-      target: { value: '{"address":"0xPeer"}' },
+      target: { value: '{"address":"0xPeer","channel":"handshake"}' },
     });
 
     await user.click(screen.getByRole("button", { name: /parse qr payload/i }));
diff --git a/frontend/__tests__/scan-qr-page.test.tsx b/frontend/__tests__/scan-qr-page.test.tsx
index 05be86d..9174a7b 100644
--- a/frontend/__tests__/scan-qr-page.test.tsx
+++ b/frontend/__tests__/scan-qr-page.test.tsx
@@ -7,9 +7,10 @@ import type { HandshakeCompletion } from "../src/lib/handshake";
 import { useScanStore } from "../src/lib/scanStore";
 import { useUserStore } from "../src/lib/store";
 
-const { pushMock, subscribeToHandshakeMock } = vi.hoisted(() => ({
+const { pushMock, subscribeToHandshakeMock, randomUuidMock } = vi.hoisted(() => ({
   pushMock: vi.fn(),
   subscribeToHandshakeMock: vi.fn(),
+  randomUuidMock: vi.fn(() => "handshake-channel"),
 }));
 
 vi.mock("next/navigation", () => ({
@@ -23,9 +24,18 @@ vi.mock("../src/lib/handshake", () => ({
 }));
 
 describe("MyQrPage", () => {
+  const originalCrypto = globalThis.crypto;
+
   beforeEach(() => {
     pushMock.mockReset();
     subscribeToHandshakeMock.mockReset();
+    Object.defineProperty(globalThis, "crypto", {
+      configurable: true,
+      value: {
+        ...originalCrypto,
+        randomUUID: randomUuidMock,
+      },
+    });
     act(() => {
       useUserStore.getState().reset();
       useScanStore.getState().reset();
@@ -44,14 +54,19 @@ describe("MyQrPage", () => {
 
   afterEach(() => {
     subscribeToHandshakeMock.mockReset();
+    randomUuidMock.mockClear();
+    Object.defineProperty(globalThis, "crypto", {
+      configurable: true,
+      value: originalCrypto,
+    });
   });
 
   it("renders the QR code and profile name", async () => {
-    subscribeToHandshakeMock.mockReturnValue(() => undefined);
+    subscribeToHandshakeMock.mockResolvedValue(() => undefined);
 
     render(<MyQrPage />);
 
-    await waitFor(() => expect(subscribeToHandshakeMock).toHaveBeenCalledWith("cubid_me", expect.any(Function)));
+    await waitFor(() => expect(subscribeToHandshakeMock).toHaveBeenCalledWith("handshake-channel", expect.any(Function)));
 
     expect(screen.getByRole("img", { name: /scan this within ninety seconds/i })).toBeInTheDocument();
     expect(screen.getByText("Casey Rivers")).toBeInTheDocument();
@@ -60,7 +75,7 @@ describe("MyQrPage", () => {
 
   it("redirects to results when a handshake completes", async () => {
     let handler: ((payload: HandshakeCompletion) => void) | null = null;
-    subscribeToHandshakeMock.mockImplementation((_cubid, callback) => {
+    subscribeToHandshakeMock.mockImplementation(async (_channel, callback) => {
       handler = callback;
       return vi.fn();
     });
@@ -70,6 +85,7 @@ describe("MyQrPage", () => {
     await waitFor(() => expect(handler).toBeInstanceOf(Function));
 
     const payload: HandshakeCompletion = {
+      channel: "handshake-channel",
       challengeId: "challenge-1",
       expiresAt: 1700001200,
       overlaps: [],
diff --git a/frontend/eslint.config.mjs b/frontend/eslint.config.mjs
index a83736a..a1f619c 100644
--- a/frontend/eslint.config.mjs
+++ b/frontend/eslint.config.mjs
@@ -9,6 +9,7 @@ const eslintConfig = defineConfig([
     rules: {
       "react-hooks/purity": "off",
       "react-hooks/set-state-in-effect": "off",
+      "@next/next/no-img-element": "off",
     },
   },
   // Override default ignores of eslint-config-next.
diff --git a/frontend/src/app/(routes)/scan/camera/page.tsx b/frontend/src/app/(routes)/scan/camera/page.tsx
index 24fa047..ac03103 100644
--- a/frontend/src/app/(routes)/scan/camera/page.tsx
+++ b/frontend/src/app/(routes)/scan/camera/page.tsx
@@ -5,13 +5,14 @@ import { type FormEvent, useState } from "react";
 
 import QRScanner from "@/components/QRScanner";
 import { requestQrChallenge, verifyQrChallenge } from "@/lib/api";
-import { notifyHandshakeComplete } from "@/lib/handshake";
+import { type HandshakeCompletion, notifyHandshakeComplete } from "@/lib/handshake";
 import { useScanStore } from "@/lib/scanStore";
 import { useUserStore } from "@/lib/store";
 import { ensureWallet } from "@/lib/wallet";
 
 type ParsedQrPayload = {
   cubidId: string;
+  channel: string;
   address?: string;
 };
 
@@ -40,6 +41,9 @@ export default function CameraPage() {
     if (!payload.cubidId) {
       throw new Error("QR payload missing cubidId");
     }
+    if (!payload.channel) {
+      throw new Error("QR payload missing channel");
+    }
     return payload;
   }
 
@@ -157,15 +161,23 @@ export default function CameraPage() {
         session.access_token,
       );
 
-      const completion = {
+      const completion: HandshakeCompletion = {
+        channel: parsed.channel,
         targetCubid: parsed.cubidId,
         viewerCubid: profile.cubid_id,
         challengeId: result.challengeId,
         expiresAt: result.expiresAt,
         overlaps: result.overlaps,
-      } as const;
+      };
 
-      setResult({ ...completion, verifiedAt: Date.now() });
+      setResult({
+        targetCubid: completion.targetCubid,
+        viewerCubid: completion.viewerCubid,
+        challengeId: completion.challengeId,
+        expiresAt: completion.expiresAt,
+        overlaps: completion.overlaps,
+        verifiedAt: Date.now(),
+      });
       setStatus("Sharing overlaps with your peer…");
 
       try {
@@ -220,7 +232,7 @@ export default function CameraPage() {
                 <textarea
                   className="w-full rounded-2xl border border-slate-700/60 bg-slate-950/60 p-4 text-sm text-slate-100 placeholder:text-slate-500 focus:border-sky-400/70 focus:outline-none"
                   rows={3}
-                  placeholder='Paste JSON like {"cubidId":"friend","address":"0x..."}'
+                  placeholder='Paste JSON like {"cubidId":"friend","channel":"uuid","address":"0x..."}'
                   value={rawQr}
                   onChange={(event) => setRawQr(event.target.value)}
                 />
diff --git a/frontend/src/app/(routes)/scan/my-qr/page.tsx b/frontend/src/app/(routes)/scan/my-qr/page.tsx
index 330f90f..a09f6b7 100644
--- a/frontend/src/app/(routes)/scan/my-qr/page.tsx
+++ b/frontend/src/app/(routes)/scan/my-qr/page.tsx
@@ -9,6 +9,14 @@ import { subscribeToHandshake } from "@/lib/handshake";
 import { useScanStore } from "@/lib/scanStore";
 import { useUserStore } from "@/lib/store";
 
+function createHandshakeChannel(): string {
+  const globalCrypto = globalThis.crypto;
+  if (globalCrypto && typeof globalCrypto.randomUUID === "function") {
+    return globalCrypto.randomUUID();
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
 export default function MyQrPage() {
   const router = useRouter();
   const session = useUserStore((state) => state.session);
@@ -16,6 +24,7 @@ export default function MyQrPage() {
   const setResult = useScanStore((state) => state.setResult);
 
   const [timestamp, setTimestamp] = useState(() => Date.now());
+  const [handshakeChannel, setHandshakeChannel] = useState(createHandshakeChannel);
   const [handshakeMessage, setHandshakeMessage] = useState<string | null>(null);
 
   useEffect(() => {
@@ -24,11 +33,12 @@ export default function MyQrPage() {
 
   useEffect(() => {
     setHandshakeMessage(null);
+    setHandshakeChannel(createHandshakeChannel());
   }, [timestamp]);
 
   const payload = useMemo(
-    () => ({ cubidId: profile?.cubid_id ?? "", ts: timestamp }),
-    [profile?.cubid_id, timestamp],
+    () => ({ cubidId: profile?.cubid_id ?? "", ts: timestamp, channel: handshakeChannel }),
+    [profile?.cubid_id, timestamp, handshakeChannel],
   );
 
   useEffect(() => {
@@ -36,23 +46,40 @@ export default function MyQrPage() {
       return undefined;
     }
 
-    const unsubscribe = subscribeToHandshake(profile.cubid_id, (payload) => {
-      setResult({
-        targetCubid: payload.targetCubid,
-        viewerCubid: payload.viewerCubid,
-        challengeId: payload.challengeId,
-        expiresAt: payload.expiresAt,
-        overlaps: payload.overlaps,
-        verifiedAt: Date.now(),
-      });
-      setHandshakeMessage("Handshake completed—opening shared overlaps…");
-      router.push("/results");
-    });
+    let active = true;
+    let unsubscribe: (() => void) | undefined;
+
+    (async () => {
+      try {
+        unsubscribe = await subscribeToHandshake(handshakeChannel, (payload) => {
+          if (!active) {
+            return;
+          }
+          if (payload.targetCubid !== profile.cubid_id) {
+            return;
+          }
+          setResult({
+            targetCubid: payload.targetCubid,
+            viewerCubid: payload.viewerCubid,
+            challengeId: payload.challengeId,
+            expiresAt: payload.expiresAt,
+            overlaps: payload.overlaps,
+            verifiedAt: Date.now(),
+          });
+          setHandshakeMessage("Handshake completed—opening shared overlaps…");
+          router.push("/results");
+        });
+      } catch {
+        if (!active) return;
+        setHandshakeMessage("We couldn’t watch for handshake updates. Refresh and try again.");
+      }
+    })();
 
     return () => {
+      active = false;
       unsubscribe?.();
     };
-  }, [profile?.cubid_id, router, setResult]);
+  }, [handshakeChannel, profile?.cubid_id, router, setResult]);
 
   if (!session) {
     return (
diff --git a/frontend/src/lib/handshake.ts b/frontend/src/lib/handshake.ts
index 990b902..57ff590 100644
--- a/frontend/src/lib/handshake.ts
+++ b/frontend/src/lib/handshake.ts
@@ -4,6 +4,7 @@ import type { VerifyQrResponse } from "./api";
 import { getSupabaseClient } from "./supabaseClient";
 
 export type HandshakeCompletion = {
+  channel: string;
   challengeId: string;
   expiresAt: number;
   overlaps: VerifyQrResponse["overlaps"];
@@ -28,7 +29,7 @@ async function ensureSubscribed(channel: RealtimeChannel): Promise<void> {
 
 export async function notifyHandshakeComplete(payload: HandshakeCompletion): Promise<void> {
   const supabase = getSupabaseClient();
-  const channel = supabase.channel(`${CHANNEL_PREFIX}${payload.targetCubid}`, {
+  const channel = supabase.channel(`${CHANNEL_PREFIX}${payload.channel}`, {
     config: { broadcast: { ack: true } },
   });
 
@@ -52,20 +53,25 @@ export async function notifyHandshakeComplete(payload: HandshakeCompletion): Pro
   }
 }
 
-export function subscribeToHandshake(
-  targetCubid: string,
+export async function subscribeToHandshake(
+  channelId: string,
   onComplete: (payload: HandshakeCompletion) => void,
-): () => void {
+): Promise<() => void> {
   const supabase = getSupabaseClient();
-  const channel = supabase.channel(`${CHANNEL_PREFIX}${targetCubid}`);
+  const channel = supabase.channel(`${CHANNEL_PREFIX}${channelId}`);
 
   channel.on("broadcast", { event: EVENT_NAME }, (event) => {
     const payload = event.payload as HandshakeCompletion | null;
-    if (!payload) return;
+    if (!payload || payload.channel !== channelId) return;
     onComplete(payload);
   });
 
-  channel.subscribe();
+  try {
+    await ensureSubscribed(channel);
+  } catch (error) {
+    await channel.unsubscribe();
+    throw error;
+  }
 
   return () => {
     void channel.unsubscribe();