From d0650023271737bcc9a37278bd5651712d3a5741 Mon Sep 17 00:00:00 2001
From: Brent Rager <brent@rager.tech>
Date: Sat, 27 Jun 2026 09:15:21 -0400
Subject: [PATCH 1/3] =?UTF-8?q?SMOODEV-2129e:=20chat-widget=200.7.0=20?=
 =?UTF-8?q?=E2=80=94=20identity/persistence/consent=20client=20layer?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add the ADR-048 identity, persistence, and consent client layer to
@smooai/chat-widget (vanilla TS + Shadow DOM):

- Persisted Zustand (zustand/vanilla + persist) store keyed per agent
  (smoo-chat-widget:<agentId>). Persists ONLY the session pointer +
  identity + consent + verifiedEmail + browserFingerprint — never the
  transcript (server is source of truth). version drives persist.migrate;
  storage adapter tolerates missing/locked-down localStorage.
- browserFingerprint computed once + cached, sent on every
  createConversationSession. Lightweight UUID-anchored fingerprint with a
  non-invasive signal-hash suffix instead of heavyweight ThumbmarkJS — keeps
  the embed bundle small + privacy-light (tradeoff noted in the changeset).
- Same-session resume (no engine change): get_session on load → if not
  ended, reuse sessionId + hydrate history via get_conversation_messages
  (newest-first reversed to chronological); ended/404 clears only the
  pointer (identity/consent survive) and starts fresh.
- Pre-chat form: phone field shown by default (rides metadata.userPhone);
  explicit, default-unchecked email + SMS marketing-consent checkboxes that
  stamp consentAt and thread a consent record into session metadata. New
  config flags collectPhone/collectConsent/allowChatRestore (default true).
- Cross-device "Restore my chats": explicit footer affordance (not a
  mid-turn pause) runs request_identity_otp → verify_identity_otp →
  resolve_identity over a shared transport (raw frames for verbs the engine
  client doesn't yet model), reusing the OTP UI; resolved list lets the user
  pick a conversation to replay; verifiedEmail persisted on success.

All server-supplied strings rendered via textContent (0.6.0 XSS guarantees
intact); Aurora-Glass styling. Zustand bundled into the IIFE global so the
<script> embed has no undefined-global at load.

Tests: 20 new unit tests (persistence/fingerprint/conversation) + 4 mock-WS
Playwright specs (consent payload, persist→resume, ended-clears, cross-device
OTP→resolve→replay). typecheck/test/build green.

Changeset: minor → 0.7.0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .changeset/identity-persistence-consent.md |  17 +
 e2e/identity-persistence-mock.spec.ts      | 341 +++++++++++++++
 package.json                               |   3 +-
 pnpm-lock.yaml                             |  23 +
 src/config.ts                              |  21 +
 src/conversation.test.ts                   | 357 +++++++++++++++
 src/conversation.ts                        | 483 ++++++++++++++++++++-
 src/element.ts                             | 246 ++++++++++-
 src/fingerprint.test.ts                    |  47 ++
 src/fingerprint.ts                         | 122 ++++++
 src/index.ts                               |  13 +
 src/persistence.test.ts                    |  99 +++++
 src/persistence.ts                         | 215 +++++++++
 src/styles.ts                              |  66 +++
 tsdown.config.ts                           |  10 +-
 15 files changed, 2032 insertions(+), 31 deletions(-)
 create mode 100644 .changeset/identity-persistence-consent.md
 create mode 100644 e2e/identity-persistence-mock.spec.ts
 create mode 100644 src/conversation.test.ts
 create mode 100644 src/fingerprint.test.ts
 create mode 100644 src/fingerprint.ts
 create mode 100644 src/persistence.test.ts
 create mode 100644 src/persistence.ts

diff --git a/.changeset/identity-persistence-consent.md b/.changeset/identity-persistence-consent.md
new file mode 100644
index 0000000..cb2a098
--- /dev/null
+++ b/.changeset/identity-persistence-consent.md
@@ -0,0 +1,17 @@
+---
+'@smooai/chat-widget': minor
+---
+
+Identity, persistence & consent client layer (ADR-048) — same-session resume, cross-device "restore my chats", marketing consent, and a stable browser fingerprint.
+
+**Persisted state (Zustand).** A framework-agnostic `zustand/vanilla` store with the `persist` middleware now keeps a small per-agent blob in localStorage (`smoo-chat-widget:<agentId>`): the session **pointer**, visitor identity (name/email/phone), marketing consent, a verified email, and the browser fingerprint. The **transcript is never persisted** — the smooth-operator server stays the source of truth and history is re-hydrated via `get_conversation_messages`. A `version` field drives `persist.migrate` so future shape changes upgrade old blobs in place; the storage adapter tolerates missing/locked-down localStorage (SSR, privacy mode) and never throws on boot.
+
+**Browser fingerprint.** Every `create_conversation_session` now carries a stable `browserFingerprint` for anonymous-visitor correlation (and server-side CRM matching). Computed once and cached in the persisted store. Rather than pull in ThumbmarkJS — tens of KB and async device-probing, too heavy for an embed whose whole point is staying out of the host's LCP/TBT budget — the fingerprint is a persisted random UUID (the exact same-browser correlator) suffixed with a small FNV hash of a few non-invasive, stable signals (UA, language, timezone, screen). No canvas/WebGL/audio probes, no network, XSS-safe. Tradeoff: weaker cross-storage matching than a full device fingerprint, deferred to the server resolver, in exchange for a tiny, transparent, privacy-light token.
+
+**Same-session resume.** On load, if a session pointer is persisted the widget calls `get_session`; when the session isn't `ended` it reuses the `sessionId`, replays history (`get_conversation_messages`, newest-first → reversed to chronological), skips the pre-chat form, and continues the conversation. An ended/404 session clears **only** the pointer (identity & consent survive) and starts fresh.
+
+**Pre-chat form: phone + marketing consent.** The phone field is now shown by default (optional; rides session `metadata.userPhone`). Two explicit, default-unchecked consent checkboxes (email + SMS) capture marketing opt-in; ticking one stamps a `consentAt` ISO timestamp, and the consent record (`{ emailOptIn, smsOptIn, consentSource: 'chat-widget-prechat', consentAt }`) threads into the session metadata. New config flags: `collectPhone`, `collectConsent`, `allowChatRestore` (all default `true`).
+
+**Cross-device "Restore my chats."** An explicit footer affordance (not a mid-turn agent pause) runs `request_identity_otp` → `verify_identity_otp` → `resolve_identity`, reusing the existing OTP UI. On a resolved list the visitor picks a conversation to replay (`get_session` + `get_conversation_messages`); the verified email is persisted. The new verbs are sent as raw frames over a shared transport so they integrate the moment the server side (SMOODEV-2129d) lands.
+
+All server-supplied strings (masked destinations, conversation previews, history) are rendered via `textContent`, keeping the 0.6.0 XSS guarantees intact, and the new UI follows the Aurora-Glass styling.
diff --git a/e2e/identity-persistence-mock.spec.ts b/e2e/identity-persistence-mock.spec.ts
new file mode 100644
index 0000000..742a561
--- /dev/null
+++ b/e2e/identity-persistence-mock.spec.ts
@@ -0,0 +1,341 @@
+/**
+ * Headless mock-WS coverage for the 0.7.0 identity / persistence / consent layer
+ * (ADR-048, SMOODEV-2129e). Loads the BUILT global bundle into a real Chromium
+ * page, drives the REAL shadow-DOM UI, and asserts:
+ *
+ *   1. consent checkboxes + phone produce the exact metadata payload, and the
+ *      fingerprint rides create_conversation_session;
+ *   2. persist → reload → resume replays server history and reuses the sessionId;
+ *   3. an ended session clears the pointer and starts a fresh session;
+ *   4. the cross-device request → verify → resolve → replay flow.
+ *
+ * A scriptable mock WebSocket (installed via addInitScript) captures outbound
+ * frames on `window.__sent` and replays operator-shaped responses keyed by
+ * action. localStorage persists across the in-page "reload" (same origin), which
+ * is what the resume path reads.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { expect, test } from '@playwright/test';
+
+const root = fileURLToPath(new URL('..', import.meta.url));
+const GLOBAL_BUNDLE = readFileSync(`${root}/dist/chat-widget.global.js`, 'utf8');
+
+const AGENT_ID = '2590dfd6-7ed5-484b-bfb4-6d83a97d5a8e';
+const ENDPOINT = 'wss://ai.smoo.ai/ws';
+
+/**
+ * The mock WebSocket. Its `send` records frames on window.__sent and routes by
+ * action through a window.__script(frame, reply) hook the test can swap per case.
+ */
+const MOCK_WS = `
+(() => {
+  window.__sent = [];
+  class MockWS {
+    constructor(url) {
+      this.url = url; this.readyState = 0;
+      this._l = { open: [], message: [], close: [], error: [] };
+      setTimeout(() => { this.readyState = 1; this._emit('open', {}); }, 3);
+    }
+    addEventListener(t, fn) { (this._l[t] ||= []).push(fn); }
+    removeEventListener(t, fn) { const a = this._l[t]; if (a) { const i = a.indexOf(fn); if (i>=0) a.splice(i,1); } }
+    _emit(t, ev) { for (const fn of (this._l[t]||[]).slice()) fn(ev); }
+    _msg(o) { this._emit('message', { data: JSON.stringify(o) }); }
+    send(raw) {
+      let f; try { f = JSON.parse(raw); } catch { return; }
+      window.__sent.push(f);
+      (window.__script || (()=>{}))(f, (o) => this._msg(o));
+    }
+    close() { this.readyState = 3; this._emit('close', { code: 1000, reason: '' }); }
+  }
+  MockWS.CONNECTING=0; MockWS.OPEN=1; MockWS.CLOSING=2; MockWS.CLOSED=3;
+  window.WebSocket = MockWS;
+})();
+`;
+
+const sleep = `(ms) => new Promise((r) => setTimeout(r, ms))`;
+
+test('consent + phone + fingerprint produce the exact create_conversation_session payload', async ({ page }) => {
+    const pageErrors: string[] = [];
+    page.on('pageerror', (e) => pageErrors.push(`${e.name}: ${e.message}`));
+
+    await page.addInitScript(MOCK_WS);
+    await page.goto(`http://127.0.0.1:${process.env.STATIC_PORT ?? 4830}/e2e/fixtures/demo.html`).catch(async () => {
+        await page.goto('about:blank');
+    });
+    await page.addScriptTag({ content: GLOBAL_BUNDLE });
+
+    const result = await page.evaluate(
+        async ({ endpoint, agentId }) => {
+            const sleepFn = (ms: number) => new Promise((r) => setTimeout(r, ms));
+            try {
+                localStorage.clear();
+            } catch {
+                /* ignore */
+            }
+            (window as unknown as { __script: unknown }).__script = (f: Record<string, unknown>, reply: (o: unknown) => void) => {
+                if (f.action === 'create_conversation_session') {
+                    reply({ type: 'immediate_response', requestId: f.requestId, status: 202, data: { sessionId: 'sess-A', conversationId: 'c', agentId: f.agentId } });
+                }
+            };
+            // Require name+email so the pre-chat form gates; phone + consent ride along.
+            // @ts-expect-error injected global
+            const el = window.SmoothAgentChat.mount({ endpoint, agentId, greeting: '', requireName: true, requireEmail: true });
+            const root = (el as { shadowRoot: ShadowRoot }).shadowRoot;
+            (root.querySelector('.launcher') as HTMLElement | null)?.click();
+            await sleepFn(30);
+
+            // Fill the pre-chat form: name, email, phone, tick both consent boxes.
+            (root.querySelector('input[name=name]') as HTMLInputElement).value = 'Ada';
+            (root.querySelector('input[name=email]') as HTMLInputElement).value = 'ada@example.com';
+            (root.querySelector('input[name=phone]') as HTMLInputElement).value = '+15551234567';
+            (root.querySelector('input[name=emailOptIn]') as HTMLInputElement).checked = true;
+            (root.querySelector('input[name=smsOptIn]') as HTMLInputElement).checked = true;
+            // Dispatch a real submit event the handler listens for.
+            (root.querySelector('.pc-form') as HTMLFormElement).dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+
+            for (let i = 0; i < 80; i++) {
+                if ((window as unknown as { __sent: Record<string, unknown>[] }).__sent.some((s) => s.action === 'create_conversation_session')) break;
+                await sleepFn(25);
+            }
+            const sent = (window as unknown as { __sent: Record<string, unknown>[] }).__sent;
+            return sent.find((s) => s.action === 'create_conversation_session') ?? null;
+        },
+        { endpoint: ENDPOINT, agentId: AGENT_ID },
+    );
+
+    expect(pageErrors, pageErrors.join('\n')).toEqual([]);
+    expect(result, 'create_conversation_session was sent').toBeTruthy();
+    const create = result as Record<string, unknown>;
+    expect(create.userName).toBe('Ada');
+    expect(create.userEmail).toBe('ada@example.com');
+    expect(typeof create.browserFingerprint).toBe('string');
+    const meta = create.metadata as Record<string, unknown>;
+    expect(meta.userPhone).toBe('+15551234567');
+    const consent = meta.consent as Record<string, unknown>;
+    expect(consent.emailOptIn).toBe(true);
+    expect(consent.smsOptIn).toBe(true);
+    expect(consent.consentSource).toBe('chat-widget-prechat');
+    expect(typeof consent.consentAt).toBe('string');
+});
+
+test('persist → reload → resume replays history and reuses the sessionId', async ({ page }) => {
+    const pageErrors: string[] = [];
+    page.on('pageerror', (e) => pageErrors.push(`${e.name}: ${e.message}`));
+
+    await page.addInitScript(MOCK_WS);
+    // Serve a real origin so localStorage persists across the reload.
+    await page.goto(`http://127.0.0.1:${process.env.STATIC_PORT ?? 4830}/e2e/fixtures/demo.html`).catch(async () => {
+        await page.goto('about:blank');
+    });
+    await page.addScriptTag({ content: GLOBAL_BUNDLE });
+
+    // --- First visit: create a session + exchange one turn. ---
+    await page.evaluate(
+        async ({ endpoint, agentId }) => {
+            const s = (ms: number) => new Promise((r) => setTimeout(r, ms));
+            (window as unknown as { __script: unknown }).__script = (f: Record<string, unknown>, reply: (o: unknown) => void) => {
+                if (f.action === 'create_conversation_session') reply({ type: 'immediate_response', requestId: f.requestId, status: 202, data: { sessionId: 'sess-RESUME', conversationId: 'c', agentId: f.agentId } });
+                else if (f.action === 'send_message') {
+                    reply({ type: 'immediate_response', requestId: f.requestId, status: 202, data: {} });
+                    reply({ type: 'eventual_response', requestId: f.requestId, status: 200, data: { requestId: f.requestId, status: 200, data: { messageId: 'm1', response: { responseParts: ['First answer'] } } } });
+                }
+            };
+            // @ts-expect-error injected global
+            const el = window.SmoothAgentChat.mount({ endpoint, agentId, greeting: '' });
+            const root = (el as { shadowRoot: ShadowRoot }).shadowRoot;
+            (root.querySelector('.launcher') as HTMLElement | null)?.click();
+            for (let i = 0; i < 60; i++) {
+                if (/online|ready/i.test((root.querySelector('.status-text') as HTMLElement | null)?.textContent ?? '')) break;
+                await s(25);
+            }
+            const input = root.querySelector('textarea') as HTMLTextAreaElement;
+            input.value = 'hi';
+            input.dispatchEvent(new Event('input', { bubbles: true }));
+            (root.querySelector('.send') as HTMLElement | null)?.click();
+            await s(120);
+            el.remove();
+        },
+        { endpoint: ENDPOINT, agentId: AGENT_ID },
+    );
+
+    // --- Second visit (simulated reload): a NEW widget reads persisted state. ---
+    const result = await page.evaluate(
+        async ({ endpoint, agentId }) => {
+            const s = (ms: number) => new Promise((r) => setTimeout(r, ms));
+            (window as unknown as { __sent: Record<string, unknown>[] }).__sent = [];
+            (window as unknown as { __script: unknown }).__script = (f: Record<string, unknown>, reply: (o: unknown) => void) => {
+                if (f.action === 'get_session') reply({ type: 'immediate_response', requestId: f.requestId, status: 200, data: { sessionId: f.sessionId, status: 'active', agentId } });
+                else if (f.action === 'get_conversation_messages')
+                    reply({ type: 'immediate_response', requestId: f.requestId, status: 200, data: { messages: [
+                        { id: 'm1', direction: 'inbound', content: { text: 'hi' }, createdAt: '2026-01-01T00:00:00Z' },
+                        { id: 'm2', direction: 'outbound', content: { text: 'First answer' }, createdAt: '2026-01-01T00:00:01Z' },
+                    ].reverse(), hasMore: false } });
+                else if (f.action === 'send_message') {
+                    reply({ type: 'immediate_response', requestId: f.requestId, status: 202, data: {} });
+                    reply({ type: 'eventual_response', requestId: f.requestId, status: 200, data: { requestId: f.requestId, status: 200, data: { messageId: 'm3', response: { responseParts: ['Second answer'] } } } });
+                }
+            };
+            // @ts-expect-error injected global
+            const el = window.SmoothAgentChat.mount({ endpoint, agentId, greeting: '' });
+            const root = (el as { shadowRoot: ShadowRoot }).shadowRoot;
+            // Returning visitor: pre-chat form skipped. Open + resume.
+            (root.querySelector('.launcher') as HTMLElement | null)?.click();
+            for (let i = 0; i < 80; i++) {
+                const txt = Array.from(root.querySelectorAll('.bubble')).map((b) => b.textContent ?? '').join(' ');
+                if (/First answer/.test(txt)) break;
+                await s(25);
+            }
+            const sent = (window as unknown as { __sent: Record<string, unknown>[] }).__sent;
+            // Send a follow-up; assert it reuses sess-RESUME.
+            const input = root.querySelector('textarea') as HTMLTextAreaElement | null;
+            if (input) {
+                input.value = 'more';
+                input.dispatchEvent(new Event('input', { bubbles: true }));
+                (root.querySelector('.send') as HTMLElement | null)?.click();
+                await s(120);
+            }
+            const after = (window as unknown as { __sent: Record<string, unknown>[] }).__sent;
+            return {
+                hadCreate: sent.some((x) => x.action === 'create_conversation_session'),
+                resumed: sent.some((x) => x.action === 'get_session'),
+                history: Array.from(root.querySelectorAll('.bubble')).map((b) => b.textContent ?? ''),
+                sendSessionId: (after.find((x) => x.action === 'send_message') as Record<string, unknown> | undefined)?.sessionId ?? null,
+            };
+        },
+        { endpoint: ENDPOINT, agentId: AGENT_ID },
+    );
+
+    expect(pageErrors, pageErrors.join('\n')).toEqual([]);
+    expect(result.hadCreate, 'resume must NOT create a new session').toBe(false);
+    expect(result.resumed, 'resume must call get_session').toBe(true);
+    expect(result.history.join(' ')).toContain('First answer');
+    expect(result.sendSessionId, 'follow-up reuses the resumed sessionId').toBe('sess-RESUME');
+});
+
+test('ended session clears the pointer and starts fresh', async ({ page }) => {
+    const pageErrors: string[] = [];
+    page.on('pageerror', (e) => pageErrors.push(`${e.name}: ${e.message}`));
+
+    await page.addInitScript(MOCK_WS);
+    await page.goto(`http://127.0.0.1:${process.env.STATIC_PORT ?? 4830}/e2e/fixtures/demo.html`).catch(async () => {
+        await page.goto('about:blank');
+    });
+    await page.addScriptTag({ content: GLOBAL_BUNDLE });
+
+    const result = await page.evaluate(
+        async ({ endpoint, agentId }) => {
+            const s = (ms: number) => new Promise((r) => setTimeout(r, ms));
+            // Pre-seed a persisted pointer for a session the server will report ended.
+            localStorage.setItem(`smoo-chat-widget:${agentId}`, JSON.stringify({ state: { version: 1, sessionId: 'sess-ENDED', identity: { name: 'Ada' }, consent: { emailOptIn: false, smsOptIn: false }, verifiedEmail: null, browserFingerprint: 'fp-keep' }, version: 1 }));
+            (window as unknown as { __script: unknown }).__script = (f: Record<string, unknown>, reply: (o: unknown) => void) => {
+                if (f.action === 'get_session') reply({ type: 'immediate_response', requestId: f.requestId, status: 200, data: { sessionId: f.sessionId, status: 'ended', agentId } });
+                else if (f.action === 'create_conversation_session') reply({ type: 'immediate_response', requestId: f.requestId, status: 202, data: { sessionId: 'sess-FRESH', conversationId: 'c', agentId: f.agentId } });
+            };
+            // @ts-expect-error injected global
+            const el = window.SmoothAgentChat.mount({ endpoint, agentId, greeting: '' });
+            const root = (el as { shadowRoot: ShadowRoot }).shadowRoot;
+            (root.querySelector('.launcher') as HTMLElement | null)?.click();
+            for (let i = 0; i < 80; i++) {
+                if ((window as unknown as { __sent: Record<string, unknown>[] }).__sent.some((x) => x.action === 'create_conversation_session')) break;
+                await s(25);
+            }
+            const persisted = JSON.parse(localStorage.getItem(`smoo-chat-widget:${agentId}`) ?? '{}');
+            const create = (window as unknown as { __sent: Record<string, unknown>[] }).__sent.find((x) => x.action === 'create_conversation_session') as Record<string, unknown> | undefined;
+            return {
+                createdFresh: !!create,
+                fingerprintSent: create?.browserFingerprint,
+                persistedSession: persisted.state?.sessionId,
+                persistedName: persisted.state?.identity?.name,
+            };
+        },
+        { endpoint: ENDPOINT, agentId: AGENT_ID },
+    );
+
+    expect(pageErrors, pageErrors.join('\n')).toEqual([]);
+    expect(result.createdFresh, 'ended session → fresh create_conversation_session').toBe(true);
+    // Pointer rolled forward to the new session; identity + fingerprint preserved.
+    expect(result.persistedSession).toBe('sess-FRESH');
+    expect(result.persistedName).toBe('Ada');
+    expect(result.fingerprintSent).toBe('fp-keep');
+});
+
+test('cross-device restore: request → verify → resolve → replay', async ({ page }) => {
+    const pageErrors: string[] = [];
+    page.on('pageerror', (e) => pageErrors.push(`${e.name}: ${e.message}`));
+
+    await page.addInitScript(MOCK_WS);
+    await page.goto(`http://127.0.0.1:${process.env.STATIC_PORT ?? 4830}/e2e/fixtures/demo.html`).catch(async () => {
+        await page.goto('about:blank');
+    });
+    await page.addScriptTag({ content: GLOBAL_BUNDLE });
+
+    const result = await page.evaluate(
+        async ({ endpoint, agentId }) => {
+            const s = (ms: number) => new Promise((r) => setTimeout(r, ms));
+            try {
+                localStorage.clear();
+            } catch {
+                /* ignore */
+            }
+            (window as unknown as { __script: unknown }).__script = (f: Record<string, unknown>, reply: (o: unknown) => void) => {
+                switch (f.action) {
+                    case 'create_conversation_session':
+                        reply({ type: 'immediate_response', requestId: f.requestId, status: 202, data: { sessionId: 'sess-A', conversationId: 'c', agentId: f.agentId } });
+                        break;
+                    case 'request_identity_otp':
+                        reply({ type: 'otp_sent', requestId: f.requestId, data: { requestId: f.requestId, data: { channel: 'email', maskedDestination: 'a***@example.com' } } });
+                        break;
+                    case 'verify_identity_otp':
+                        reply({ type: 'otp_verified', requestId: f.requestId, data: { requestId: f.requestId, data: { message: 'ok' } } });
+                        break;
+                    case 'resolve_identity':
+                        reply({ type: 'immediate_response', requestId: f.requestId, status: 200, data: { resolved: true, crmContactId: 'crm', conversations: [{ conversationId: 'conv-9', sessionId: 'sess-9', lastActivityAt: '2026-01-01T00:00:00Z', preview: 'Past chat about pricing' }] } });
+                        break;
+                    case 'get_session':
+                        reply({ type: 'immediate_response', requestId: f.requestId, status: 200, data: { sessionId: f.sessionId, status: 'active', agentId } });
+                        break;
+                    case 'get_conversation_messages':
+                        reply({ type: 'immediate_response', requestId: f.requestId, status: 200, data: { messages: [{ id: 'h1', direction: 'inbound', content: { text: 'Replayed pricing chat' }, createdAt: '2026-01-01T00:00:00Z' }], hasMore: false } });
+                        break;
+                }
+            };
+            // @ts-expect-error injected global
+            const el = window.SmoothAgentChat.mount({ endpoint, agentId, greeting: '' });
+            const root = (el as { shadowRoot: ShadowRoot }).shadowRoot;
+            (root.querySelector('.launcher') as HTMLElement | null)?.click();
+            await s(40);
+
+            // Click the "Restore my chats" affordance in the footer.
+            (root.querySelector('.restore-link') as HTMLElement | null)?.click();
+            await s(30);
+            // Email entry.
+            const emailInput = root.querySelector('.int-card .int-input') as HTMLInputElement;
+            emailInput.value = 'ada@example.com';
+            (root.querySelector('.int-card .int-btn.primary') as HTMLElement).click();
+            await s(40);
+            // Code entry.
+            const codeInput = root.querySelector('.int-card .int-input') as HTMLInputElement;
+            codeInput.value = '123456';
+            (root.querySelector('.int-card .int-btn.primary') as HTMLElement).click();
+            await s(60);
+            // The resolved conversation list appears — pick it.
+            const item = root.querySelector('.restore-item') as HTMLElement | null;
+            const hadList = !!item;
+            item?.click();
+            await s(80);
+
+            return {
+                hadList,
+                verifiedEmailPersisted: JSON.parse(localStorage.getItem(`smoo-chat-widget:${agentId}`) ?? '{}').state?.verifiedEmail,
+                replayed: Array.from(root.querySelectorAll('.bubble')).map((b) => b.textContent ?? '').join(' '),
+            };
+        },
+        { endpoint: ENDPOINT, agentId: AGENT_ID },
+    );
+
+    expect(pageErrors, pageErrors.join('\n')).toEqual([]);
+    expect(result.hadList, 'resolve_identity produced a conversation list').toBe(true);
+    expect(result.verifiedEmailPersisted, 'verifiedEmail persisted after verify').toBe('ada@example.com');
+    expect(result.replayed).toContain('Replayed pricing chat');
+});
diff --git a/package.json b/package.json
index 9a74ba3..3171e20 100644
--- a/package.json
+++ b/package.json
@@ -70,7 +70,8 @@
         "ci:publish": "pnpm build && changeset publish"
     },
     "dependencies": {
-        "@smooai/smooth-operator": "^1.8.0"
+        "@smooai/smooth-operator": "^1.8.0",
+        "zustand": "^5.0.14"
     },
     "devDependencies": {
         "@changesets/cli": "^2.28.1",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 466d016..bd93d8f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -12,6 +12,9 @@ importers:
       '@smooai/smooth-operator':
         specifier: ^1.8.0
         version: 1.8.0
+      zustand:
+        specifier: ^5.0.14
+        version: 5.0.14
     devDependencies:
       '@changesets/cli':
         specifier: ^2.28.1
@@ -1485,6 +1488,24 @@ packages:
   xmlchars@2.2.0:
     resolution: {integrity: sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==}
 
+  zustand@5.0.14:
+    resolution: {integrity: sha512-/8tAspM5LMPr28b3fwLYrtdj77ECpfZviaP75CMTnwO8ISyaE4GDIG/9rDDYq/cH9D2Xw2A2RXglLInmVBQB/g==}
+    engines: {node: '>=12.20.0'}
+    peerDependencies:
+      '@types/react': '>=18.0.0'
+      immer: '>=9.0.6'
+      react: '>=18.0.0'
+      use-sync-external-store: '>=1.2.0'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      immer:
+        optional: true
+      react:
+        optional: true
+      use-sync-external-store:
+        optional: true
+
 snapshots:
 
   '@asamuzakjp/css-color@3.2.0':
@@ -2811,3 +2832,5 @@ snapshots:
   xml-name-validator@5.0.0: {}
 
   xmlchars@2.2.0: {}
+
+  zustand@5.0.14: {}
diff --git a/src/config.ts b/src/config.ts
index 891cf50..eb76d1c 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -90,6 +90,24 @@ export interface ChatWidgetConfig {
     requireEmail?: boolean;
     /** Require the visitor's phone before chatting. */
     requirePhone?: boolean;
+    /**
+     * Show the phone field on the pre-chat form (optional unless {@link requirePhone}).
+     * Defaults to `true` for this widget — phone rides the session metadata as
+     * `userPhone` so the agent can follow up by SMS. Set `false` to hide it.
+     */
+    collectPhone?: boolean;
+    /**
+     * Show the email + SMS marketing-consent checkboxes on the pre-chat form.
+     * Explicit opt-in, default UNCHECKED; a `consentAt` timestamp is stamped when
+     * a box is ticked. Defaults to `true`. The consent record is threaded into the
+     * session metadata (ADR-048).
+     */
+    collectConsent?: boolean;
+    /**
+     * Offer the cross-device "Restore my chats" affordance — an explicit link that
+     * runs the identity-OTP → resolve → replay flow. Defaults to `true`.
+     */
+    allowChatRestore?: boolean;
     /**
      * Let visitors chat without providing any identity. When `true`, the
      * `require*` flags are ignored and the pre-chat form is skipped.
@@ -135,6 +153,9 @@ export function resolveConfig(config: ChatWidgetConfig): ResolvedConfig {
         requireName: config.requireName ?? false,
         requireEmail: config.requireEmail ?? false,
         requirePhone: config.requirePhone ?? false,
+        collectPhone: config.collectPhone ?? true,
+        collectConsent: config.collectConsent ?? true,
+        allowChatRestore: config.allowChatRestore ?? true,
         allowAnonymous: config.allowAnonymous ?? false,
         theme: {
             text: theme.text ?? '#f8fafc',
diff --git a/src/conversation.test.ts b/src/conversation.test.ts
new file mode 100644
index 0000000..49307e8
--- /dev/null
+++ b/src/conversation.test.ts
@@ -0,0 +1,357 @@
+/**
+ * ConversationController integration tests (jsdom + a deterministic mock
+ * WebSocket). The controller builds its own browser transport over the global
+ * `WebSocket`, so we install a scriptable mock that captures outbound frames and
+ * replays operator-shaped responses correlated by `requestId`.
+ *
+ * These cover the 0.7.0 identity / persistence / consent contract (ADR-048):
+ *   - createConversationSession carries browserFingerprint + identity + consent
+ *     + phone-on-metadata,
+ *   - same-session resume hydrates history and reuses the sessionId,
+ *   - an ended session clears the pointer and starts fresh,
+ *   - the cross-device request → verify → resolve → replay flow.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ConversationController, type ConversationEvents, type IdentityRestore } from './conversation.js';
+import { createWidgetStore } from './persistence.js';
+
+const ENDPOINT = 'wss://example.test/ws';
+const AGENT = 'agent-xyz';
+
+interface Listeners {
+    open: Array<() => void>;
+    message: Array<(ev: { data: string }) => void>;
+    close: Array<(ev: { code?: number; reason?: string }) => void>;
+    error: Array<(ev: unknown) => void>;
+}
+
+/** A scriptable mock socket. `onFrame` decides the replies for each outbound frame. */
+class MockSocket {
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSING = 2;
+    static readonly CLOSED = 3;
+    readonly CONNECTING = 0;
+    readonly OPEN = 1;
+    readonly CLOSING = 2;
+    readonly CLOSED = 3;
+    static onFrame: (frame: Record<string, unknown>, reply: (obj: unknown) => void) => void = () => {};
+    static instances: MockSocket[] = [];
+    static sentFrames: Record<string, unknown>[] = [];
+
+    readyState = 0;
+    private listeners: Listeners = { open: [], message: [], close: [], error: [] };
+
+    constructor(public url: string) {
+        MockSocket.instances.push(this);
+        queueMicrotask(() => {
+            this.readyState = 1;
+            for (const fn of this.listeners.open.slice()) fn();
+        });
+    }
+    addEventListener(type: keyof Listeners, fn: (ev: never) => void): void {
+        (this.listeners[type] as Array<typeof fn>).push(fn);
+    }
+    removeEventListener(): void {
+        /* not needed for these tests */
+    }
+    private reply(obj: unknown): void {
+        for (const fn of this.listeners.message.slice()) fn({ data: JSON.stringify(obj) });
+    }
+    send(raw: string): void {
+        const frame = JSON.parse(raw) as Record<string, unknown>;
+        MockSocket.sentFrames.push(frame);
+        MockSocket.onFrame(frame, (obj) => this.reply(obj));
+    }
+    close(): void {
+        this.readyState = 3;
+        for (const fn of this.listeners.close.slice()) fn({ code: 1000, reason: '' });
+    }
+}
+
+function installMockWs(): void {
+    MockSocket.instances = [];
+    MockSocket.sentFrames = [];
+    (globalThis as unknown as { WebSocket: unknown }).WebSocket = MockSocket;
+}
+
+/** Default operator behaviour: create → immediate_response, send → token+eventual. */
+function defaultOnFrame(frame: Record<string, unknown>, reply: (obj: unknown) => void): void {
+    const requestId = frame.requestId;
+    if (frame.action === 'create_conversation_session') {
+        reply({ type: 'immediate_response', requestId, status: 202, data: { sessionId: 'sess-new', conversationId: 'conv-1', agentId: frame.agentId } });
+    } else if (frame.action === 'send_message') {
+        reply({ type: 'immediate_response', requestId, status: 202, data: {} });
+        reply({ type: 'stream_token', requestId, token: 'Hi' });
+        reply({ type: 'eventual_response', requestId, status: 200, data: { requestId, status: 200, data: { messageId: 'm1', response: { responseParts: ['Hi there'] } } } });
+    }
+}
+
+function makeController(events: Partial<ConversationEvents> = {}, config: Record<string, unknown> = {}) {
+    const store = createWidgetStore(AGENT);
+    const onMessages = vi.fn();
+    const onStatus = vi.fn();
+    const onInterrupt = vi.fn();
+    const onIdentityRestore = vi.fn();
+    const controller = new ConversationController(
+        { endpoint: ENDPOINT, agentId: AGENT, ...config },
+        { onMessages, onStatus, onInterrupt, onIdentityRestore, ...events },
+        store,
+    );
+    return { controller, store, onMessages, onStatus, onIdentityRestore };
+}
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+describe('ConversationController — session creation (ADR-048 §a)', () => {
+    beforeEach(() => {
+        localStorage.clear();
+        installMockWs();
+        MockSocket.onFrame = defaultOnFrame;
+    });
+    afterEach(() => localStorage.clear());
+
+    it('sends browserFingerprint + identity + consent + phone-on-metadata', async () => {
+        const { controller, store } = makeController();
+        controller.setUserInfo({
+            name: 'Ada',
+            email: 'ada@example.com',
+            phone: '+15551234567',
+            consent: { emailOptIn: true, smsOptIn: false },
+        });
+        await controller.connect();
+
+        const create = MockSocket.sentFrames.find((f) => f.action === 'create_conversation_session') as Record<string, unknown>;
+        expect(create).toBeTruthy();
+        expect(create.userName).toBe('Ada');
+        expect(create.userEmail).toBe('ada@example.com');
+        expect(typeof create.browserFingerprint).toBe('string');
+        expect((create.browserFingerprint as string).length).toBeGreaterThan(10);
+
+        const meta = create.metadata as Record<string, unknown>;
+        // Phone rides metadata.userPhone (no first-class engine field).
+        expect(meta.userPhone).toBe('+15551234567');
+        const consent = meta.consent as Record<string, unknown>;
+        expect(consent.emailOptIn).toBe(true);
+        expect(consent.smsOptIn).toBe(false);
+        expect(consent.consentSource).toBe('chat-widget-prechat');
+        expect(typeof consent.consentAt).toBe('string');
+
+        // The fingerprint + session pointer are persisted.
+        expect(store.getState().browserFingerprint).toBe(create.browserFingerprint);
+        expect(store.getState().sessionId).toBe('sess-new');
+    });
+
+    it('reuses the SAME fingerprint across two sessions', async () => {
+        const { controller, store } = makeController();
+        await controller.connect();
+        const fp1 = store.getState().browserFingerprint;
+        controller.disconnect();
+        // Clear the session pointer so the next connect creates a fresh session.
+        store.getState().clearSession();
+        await controller.connect();
+        const creates = MockSocket.sentFrames.filter((f) => f.action === 'create_conversation_session');
+        expect(creates).toHaveLength(2);
+        expect(creates[0]?.browserFingerprint).toBe(creates[1]?.browserFingerprint);
+        expect(store.getState().browserFingerprint).toBe(fp1);
+    });
+
+    it('omits consent metadata when no opt-in was given', async () => {
+        const { controller } = makeController();
+        controller.setUserInfo({ name: 'Bob', consent: { emailOptIn: false, smsOptIn: false } });
+        await controller.connect();
+        const create = MockSocket.sentFrames.find((f) => f.action === 'create_conversation_session') as Record<string, unknown>;
+        // No consentAt stamped → no consent block in metadata.
+        expect(create.metadata).toBeUndefined();
+    });
+});
+
+describe('ConversationController — same-session resume (ADR-048 §b)', () => {
+    beforeEach(() => {
+        localStorage.clear();
+        installMockWs();
+    });
+    afterEach(() => localStorage.clear());
+
+    it('resumes a live persisted session, hydrates history, and reuses the sessionId', async () => {
+        // Seed a persisted pointer + identity (returning visitor).
+        const seed = createWidgetStore(AGENT);
+        seed.getState().setSessionId('sess-resume');
+        seed.getState().mergeIdentity({ name: 'Ada' });
+
+        MockSocket.onFrame = (frame, reply) => {
+            const requestId = frame.requestId;
+            if (frame.action === 'get_session') {
+                expect(frame.sessionId).toBe('sess-resume');
+                reply({ type: 'immediate_response', requestId, status: 200, data: { sessionId: 'sess-resume', status: 'active', agentId: AGENT } });
+            } else if (frame.action === 'get_conversation_messages') {
+                // Server returns newest-first.
+                reply({
+                    type: 'immediate_response',
+                    requestId,
+                    status: 200,
+                    data: {
+                        messages: [
+                            { id: 'm2', direction: 'outbound', content: { text: 'Reply two' }, createdAt: '2026-01-02T00:00:00Z' },
+                            { id: 'm1', direction: 'inbound', content: { text: 'Hello one' }, createdAt: '2026-01-01T00:00:00Z' },
+                        ],
+                        hasMore: false,
+                    },
+                });
+            } else {
+                defaultOnFrame(frame, reply);
+            }
+        };
+
+        const { controller, onMessages } = makeController();
+        await controller.connect();
+
+        // No new session was created — we resumed.
+        expect(MockSocket.sentFrames.find((f) => f.action === 'create_conversation_session')).toBeUndefined();
+        expect(MockSocket.sentFrames.find((f) => f.action === 'get_session')).toBeTruthy();
+
+        // History hydrated chronologically (oldest first).
+        const lastSnapshot = onMessages.mock.calls.at(-1)?.[0] as Array<{ role: string; text: string }>;
+        expect(lastSnapshot.map((m) => m.text)).toEqual(['Hello one', 'Reply two']);
+        expect(lastSnapshot.map((m) => m.role)).toEqual(['user', 'assistant']);
+
+        // A follow-up message reuses sess-resume (no createConversationSession).
+        await controller.send('next');
+        const sendFrame = MockSocket.sentFrames.find((f) => f.action === 'send_message') as Record<string, unknown>;
+        expect(sendFrame.sessionId).toBe('sess-resume');
+        expect(MockSocket.sentFrames.find((f) => f.action === 'create_conversation_session')).toBeUndefined();
+    });
+
+    it('clears the pointer (keeps identity) and starts fresh when the session has ended', async () => {
+        const seed = createWidgetStore(AGENT);
+        seed.getState().setSessionId('sess-dead');
+        seed.getState().mergeIdentity({ name: 'Ada' });
+
+        MockSocket.onFrame = (frame, reply) => {
+            const requestId = frame.requestId;
+            if (frame.action === 'get_session') {
+                reply({ type: 'immediate_response', requestId, status: 200, data: { sessionId: 'sess-dead', status: 'ended', agentId: AGENT } });
+            } else {
+                defaultOnFrame(frame, reply);
+            }
+        };
+
+        const { controller, store } = makeController();
+        await controller.connect();
+
+        // Fell through to a fresh create_conversation_session.
+        const create = MockSocket.sentFrames.find((f) => f.action === 'create_conversation_session') as Record<string, unknown>;
+        expect(create).toBeTruthy();
+        // New pointer persisted; identity preserved across the clear.
+        expect(store.getState().sessionId).toBe('sess-new');
+        expect(store.getState().identity.name).toBe('Ada');
+    });
+
+    it('starts fresh when get_session 404s (SESSION_NOT_FOUND)', async () => {
+        const seed = createWidgetStore(AGENT);
+        seed.getState().setSessionId('sess-gone');
+
+        MockSocket.onFrame = (frame, reply) => {
+            const requestId = frame.requestId;
+            if (frame.action === 'get_session') {
+                reply({ type: 'error', requestId, data: { requestId, error: { code: 'SESSION_NOT_FOUND', message: 'gone' } } });
+            } else {
+                defaultOnFrame(frame, reply);
+            }
+        };
+
+        const { controller, store } = makeController();
+        await controller.connect();
+        expect(MockSocket.sentFrames.find((f) => f.action === 'create_conversation_session')).toBeTruthy();
+        expect(store.getState().sessionId).toBe('sess-new');
+    });
+});
+
+describe('ConversationController — cross-device restore (ADR-048 §c)', () => {
+    beforeEach(() => {
+        localStorage.clear();
+        installMockWs();
+    });
+    afterEach(() => localStorage.clear());
+
+    it('runs request → verify → resolve → replay and persists verifiedEmail', async () => {
+        const restoreStates: IdentityRestore[] = [];
+        MockSocket.onFrame = (frame, reply) => {
+            const requestId = frame.requestId;
+            switch (frame.action) {
+                case 'create_conversation_session':
+                    reply({ type: 'immediate_response', requestId, status: 202, data: { sessionId: 'sess-new', conversationId: 'c', agentId: AGENT } });
+                    break;
+                case 'request_identity_otp':
+                    expect(frame.email).toBe('ada@example.com');
+                    reply({ type: 'otp_sent', requestId, data: { requestId, data: { channel: 'email', maskedDestination: 'a***@example.com' } } });
+                    break;
+                case 'verify_identity_otp':
+                    expect(frame.code).toBe('123456');
+                    reply({ type: 'otp_verified', requestId, data: { requestId, data: { message: 'ok' } } });
+                    break;
+                case 'resolve_identity':
+                    reply({
+                        type: 'immediate_response',
+                        requestId,
+                        status: 200,
+                        data: { resolved: true, crmContactId: 'crm-1', conversations: [{ conversationId: 'conv-9', sessionId: 'sess-9', lastActivityAt: '2026-01-01T00:00:00Z', preview: 'Past chat' }] },
+                    });
+                    break;
+                case 'get_session':
+                    reply({ type: 'immediate_response', requestId, status: 200, data: { sessionId: frame.sessionId, status: 'active', agentId: AGENT } });
+                    break;
+                case 'get_conversation_messages':
+                    reply({ type: 'immediate_response', requestId, status: 200, data: { messages: [{ id: 'h1', direction: 'inbound', content: { text: 'Restored history' }, createdAt: '2026-01-01T00:00:00Z' }], hasMore: false } });
+                    break;
+                default:
+                    break;
+            }
+        };
+
+        const { controller, store, onMessages } = makeController({ onIdentityRestore: (s) => restoreStates.push(s) });
+        await controller.connect();
+
+        controller.requestIdentityOtp('ada@example.com', 'email');
+        await tick();
+        expect(restoreStates.at(-1)?.phase).toBe('awaiting_code');
+
+        controller.verifyIdentityOtp('123456');
+        await tick();
+        // verifiedEmail persisted on success.
+        expect(store.getState().verifiedEmail).toBe('ada@example.com');
+
+        const resolved = restoreStates.find((s) => s.phase === 'resolved');
+        expect(resolved && resolved.phase === 'resolved' ? resolved.conversations[0]?.sessionId : null).toBe('sess-9');
+
+        // Picking the conversation replays its history + repoints the session.
+        await controller.restoreConversation('sess-9');
+        await tick();
+        expect(store.getState().sessionId).toBe('sess-9');
+        const snap = onMessages.mock.calls.at(-1)?.[0] as Array<{ text: string }>;
+        expect(snap.some((m) => m.text === 'Restored history')).toBe(true);
+    });
+
+    it('surfaces otp_invalid with attemptsRemaining and stays on the code step', async () => {
+        const restoreStates: IdentityRestore[] = [];
+        MockSocket.onFrame = (frame, reply) => {
+            const requestId = frame.requestId;
+            if (frame.action === 'create_conversation_session') {
+                reply({ type: 'immediate_response', requestId, status: 202, data: { sessionId: 'sess-new', conversationId: 'c', agentId: AGENT } });
+            } else if (frame.action === 'request_identity_otp') {
+                reply({ type: 'otp_sent', requestId, data: { requestId, data: { channel: 'email', maskedDestination: 'a***@x.com' } } });
+            } else if (frame.action === 'verify_identity_otp') {
+                reply({ type: 'otp_invalid', requestId, data: { requestId, data: { error: 'INVALID_CODE', attemptsRemaining: 2, message: 'nope' } } });
+            }
+        };
+        const { controller } = makeController({ onIdentityRestore: (s) => restoreStates.push(s) });
+        await controller.connect();
+        controller.requestIdentityOtp('ada@example.com');
+        await tick();
+        controller.verifyIdentityOtp('000000');
+        await tick();
+        const last = restoreStates.at(-1);
+        expect(last?.phase).toBe('awaiting_code');
+        expect(last?.phase === 'awaiting_code' ? last.attemptsRemaining : null).toBe(2);
+    });
+});
diff --git a/src/conversation.ts b/src/conversation.ts
index 553a0a1..f7d8f6f 100644
--- a/src/conversation.ts
+++ b/src/conversation.ts
@@ -8,15 +8,113 @@
  * so the swap is purely at the client-library boundary.
  *
  * Flow:
- *   1. `connect()`        → opens the WebSocket transport and `create_conversation_session`.
+ *   1. `connect()`        → opens the WebSocket transport and `create_conversation_session`
+ *                           (or RESUMES a persisted session via `get_session`/`get_messages`).
  *   2. `send(text)`       → `send_message`, streaming `stream_token` deltas into the
  *                           in-progress assistant message, then the terminal
  *                           `eventual_response`.
  *
+ * 0.7.0 (SMOODEV-2129e) adds the identity / persistence / consent client layer:
+ *   - `browserFingerprint` computed once + sent on every `create_conversation_session`.
+ *   - identity + marketing consent threaded into the session `metadata`.
+ *   - same-session RESUME on load (no engine change — `get_session` + `get_messages`).
+ *   - cross-device "restore my chats" (`request_identity_otp` / `verify_identity_otp`
+ *     / `resolve_identity`) sent as raw frames over a shared transport.
+ *
  * The controller is UI-agnostic: it emits typed events and the view renders them.
  */
-import { type Citation, ProtocolError, type ServerEvent, SmoothAgentClient } from '@smooai/smooth-operator';
+import { type Citation, ProtocolError, type ServerEvent, SmoothAgentClient, type Transport, type TransportState } from '@smooai/smooth-operator';
+import type { StoreApi } from 'zustand/vanilla';
 import type { ChatWidgetConfig } from './config.js';
+import { getOrCreateFingerprint } from './fingerprint.js';
+import { type ConsentState, createWidgetStore, type WidgetStore } from './persistence.js';
+
+/**
+ * A tiny browser `WebSocket` transport implementing the engine's {@link Transport}
+ * contract. We inject our own (rather than letting the client build its default)
+ * for two reasons: (1) it keeps a reference to `send()` so we can emit the custom
+ * cross-device frames the engine client doesn't model, and (2) it sidesteps a
+ * bundling quirk — the IIFE build aliases `@smooai/smooth-operator` to its
+ * `client.js`, which imports but does not RE-export `WebSocketTransport`, so the
+ * package's own transport isn't reachable from the global bundle. This class is a
+ * faithful, minimal equivalent of `WebSocketTransport` over the global socket.
+ */
+class BrowserWebSocketTransport implements Transport {
+    private socket: WebSocket | null = null;
+    private readonly messageHandlers = new Set<(data: string) => void>();
+    private readonly closeHandlers = new Set<(info: { code?: number; reason?: string }) => void>();
+    private readonly errorHandlers = new Set<(err: unknown) => void>();
+
+    constructor(private readonly url: string) {}
+
+    get state(): TransportState {
+        const s = this.socket;
+        if (!s) return 'closed';
+        switch (s.readyState) {
+            case WebSocket.CONNECTING:
+                return 'connecting';
+            case WebSocket.OPEN:
+                return 'open';
+            case WebSocket.CLOSING:
+                return 'closing';
+            default:
+                return 'closed';
+        }
+    }
+
+    connect(): Promise<void> {
+        return new Promise((resolve, reject) => {
+            try {
+                const socket = new WebSocket(this.url);
+                this.socket = socket;
+                socket.addEventListener('open', () => resolve());
+                socket.addEventListener('error', (ev) => {
+                    for (const h of this.errorHandlers) h(ev);
+                    if (socket.readyState !== WebSocket.OPEN) reject(new Error('WebSocket connection failed'));
+                });
+                socket.addEventListener('message', (ev: MessageEvent) => {
+                    const data = typeof ev.data === 'string' ? ev.data : String(ev.data);
+                    for (const h of this.messageHandlers) h(data);
+                });
+                socket.addEventListener('close', (ev: CloseEvent) => {
+                    for (const h of this.closeHandlers) h({ code: ev.code, reason: ev.reason });
+                });
+            } catch (err) {
+                reject(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+    }
+
+    send(data: string): void {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+            throw new Error('Transport is not open');
+        }
+        this.socket.send(data);
+    }
+
+    close(code?: number, reason?: string): void {
+        try {
+            this.socket?.close(code, reason);
+        } catch {
+            /* closing an already-closed socket is non-fatal */
+        }
+    }
+
+    onMessage(handler: (data: string) => void): () => void {
+        this.messageHandlers.add(handler);
+        return () => this.messageHandlers.delete(handler);
+    }
+
+    onClose(handler: (info: { code?: number; reason?: string }) => void): () => void {
+        this.closeHandlers.add(handler);
+        return () => this.closeHandlers.delete(handler);
+    }
+
+    onError(handler: (err: unknown) => void): () => void {
+        this.errorHandlers.add(handler);
+        return () => this.errorHandlers.delete(handler);
+    }
+}
 
 export type { Citation };
 
@@ -66,8 +164,34 @@ export interface UserInfo {
     name?: string;
     email?: string;
     phone?: string;
+    /** Marketing-consent opt-ins captured at the pre-chat form (ADR-048). */
+    consent?: { emailOptIn: boolean; smsOptIn: boolean };
 }
 
+/** One conversation surfaced by `resolve_identity` for the cross-device picker. */
+export interface RestorableConversation {
+    conversationId: string;
+    sessionId: string;
+    lastActivityAt?: string;
+    preview?: string;
+}
+
+/**
+ * State machine for the cross-device "restore my chats" flow. Mirrors the
+ * `request_identity_otp` → `verify_identity_otp` → `resolve_identity` verbs
+ * (ADR-048 §c). The view renders a panel off this.
+ */
+export type IdentityRestore =
+    | { phase: 'idle' }
+    /** UI-local: the email-entry step before any frame is sent. */
+    | { phase: 'awaiting_email'; error?: string }
+    | { phase: 'requesting'; email: string; channel: 'email' | 'sms' }
+    | { phase: 'awaiting_code'; email: string; channel: 'email' | 'sms'; maskedDestination?: string; error?: string; attemptsRemaining?: number }
+    | { phase: 'verifying'; email: string; channel: 'email' | 'sms' }
+    | { phase: 'resolving'; email: string }
+    | { phase: 'resolved'; email: string; conversations: RestorableConversation[] }
+    | { phase: 'error'; message: string };
+
 export interface ConversationEvents {
     /** Fired whenever the message list changes (append, token delta, finalize). */
     onMessages: (messages: ChatMessage[]) => void;
@@ -75,6 +199,8 @@ export interface ConversationEvents {
     onStatus: (status: ConnectionStatus, detail?: string) => void;
     /** Fired when a turn pauses for OTP / tool-confirmation, and `null` when it clears. */
     onInterrupt?: (interrupt: Interrupt | null) => void;
+    /** Fired on cross-device identity-restore state transitions. */
+    onIdentityRestore?: (state: IdentityRestore) => void;
 }
 
 /** Pull the final assistant text out of an `eventual_response` data payload. */
@@ -115,33 +241,87 @@ function extractCitations(inner: unknown): Citation[] {
     return out;
 }
 
+/** A `get_conversation_messages` row, narrowed defensively off the wire. */
+interface WireMessage {
+    id?: string;
+    direction?: 'inbound' | 'outbound';
+    content?: { text?: string };
+    createdAt?: string;
+}
+
+/** Convert a server message row into a finalized {@link ChatMessage}. */
+function wireMessageToChat(m: WireMessage, idx: number): ChatMessage | null {
+    const text = typeof m.content?.text === 'string' ? m.content.text : '';
+    if (!text) return null;
+    const role: Role = m.direction === 'outbound' ? 'assistant' : 'user';
+    return { id: typeof m.id === 'string' ? m.id : `hist-${idx}`, role, text, streaming: false };
+}
+
 export class ConversationController {
     private readonly config: ChatWidgetConfig;
     private readonly events: ConversationEvents;
+    private readonly store: StoreApi<WidgetStore>;
     private client: SmoothAgentClient | null = null;
+    /** Shared transport — kept so we can send the custom cross-device frames. */
+    private transport: BrowserWebSocketTransport | null = null;
     private sessionId: string | null = null;
     private readonly messages: ChatMessage[] = [];
     private status: ConnectionStatus = 'idle';
     private seq = 0;
-    /** Visitor identity, seeded from config and updated by the pre-chat form. */
-    private identity: UserInfo;
     /** requestId of the in-flight turn — used to resume OTP / tool confirmations. */
     private activeRequestId: string | null = null;
     private interrupt: Interrupt | null = null;
+    private identityRestore: IdentityRestore = { phase: 'idle' };
+    /** Pending cross-device verb resolvers, keyed by the requestId we minted. */
+    private readonly identityWaiters = new Map<string, (event: ServerEvent) => void>();
+    private unsubscribeEvents: (() => void) | null = null;
 
-    constructor(config: ChatWidgetConfig, events: ConversationEvents) {
+    constructor(config: ChatWidgetConfig, events: ConversationEvents, store?: StoreApi<WidgetStore>) {
         this.config = config;
         this.events = events;
-        this.identity = { name: config.userName, email: config.userEmail, phone: config.userPhone };
+        this.store = store ?? createWidgetStore(config.agentId);
+        // Seed identity from config into the persisted store (config wins on first
+        // load; the persisted values survive across reloads thereafter).
+        const seed: { name?: string; email?: string; phone?: string } = {};
+        if (config.userName) seed.name = config.userName;
+        if (config.userEmail) seed.email = config.userEmail;
+        if (config.userPhone) seed.phone = config.userPhone;
+        if (Object.keys(seed).length > 0) this.store.getState().mergeIdentity(seed);
     }
 
     get connectionStatus(): ConnectionStatus {
         return this.status;
     }
 
-    /** Merge in visitor identity (from the pre-chat form). Applied on next connect. */
+    /** The persisted store, exposed so the view can read identity for the pre-chat gate. */
+    getStore(): StoreApi<WidgetStore> {
+        return this.store;
+    }
+
+    /** True when a persisted session pointer exists (drives the resume path). */
+    hasPersistedSession(): boolean {
+        return !!this.store.getState().sessionId;
+    }
+
+    /** True when persisted identity exists (lets the view skip the pre-chat form). */
+    hasPersistedIdentity(): boolean {
+        const id = this.store.getState().identity;
+        return !!(id.name || id.email || id.phone);
+    }
+
+    /** Merge in visitor identity + consent (from the pre-chat form). Applied on next connect. */
     setUserInfo(info: UserInfo): void {
-        this.identity = { ...this.identity, ...info };
+        const { name, email, phone, consent } = info;
+        this.store.getState().mergeIdentity({ name, email, phone });
+        if (consent) {
+            const consentAt = consent.emailOptIn || consent.smsOptIn ? new Date().toISOString() : undefined;
+            this.store.getState().setConsent({
+                emailOptIn: consent.emailOptIn,
+                smsOptIn: consent.smsOptIn,
+                consentSource: 'chat-widget-prechat',
+                consentAt,
+            });
+        }
     }
 
     private setInterrupt(interrupt: Interrupt | null): void {
@@ -149,6 +329,15 @@ export class ConversationController {
         this.events.onInterrupt?.(interrupt);
     }
 
+    private setIdentityRestore(state: IdentityRestore): void {
+        this.identityRestore = state;
+        this.events.onIdentityRestore?.(state);
+    }
+
+    get currentIdentityRestore(): IdentityRestore {
+        return this.identityRestore;
+    }
+
     /** Submit an OTP code to resume the paused turn. No-op if not awaiting OTP. */
     verifyOtp(code: string): void {
         if (!this.client || !this.sessionId || !this.activeRequestId || this.interrupt?.kind !== 'otp') return;
@@ -177,21 +366,71 @@ export class ConversationController {
         this.events.onMessages(this.messages.map((m) => ({ ...m })));
     }
 
-    /** Open the transport and create a conversation session. Idempotent. */
+    /** Compute (once) + return the persisted browser fingerprint. */
+    private fingerprint(): string {
+        const state = this.store.getState();
+        return getOrCreateFingerprint(
+            () => state.browserFingerprint,
+            (fp) => this.store.getState().setBrowserFingerprint(fp),
+        );
+    }
+
+    /**
+     * Build the `metadata` payload threaded into `create_conversation_session`:
+     * phone (no first-class engine field), consent, and a verified email when known.
+     */
+    private sessionMetadata(): Record<string, unknown> | undefined {
+        const state = this.store.getState();
+        const meta: Record<string, unknown> = {};
+        if (state.identity.phone) meta.userPhone = state.identity.phone;
+        const consent = state.consent;
+        if (consent.emailOptIn || consent.smsOptIn || consent.consentAt) {
+            const c: ConsentState = {
+                emailOptIn: consent.emailOptIn,
+                smsOptIn: consent.smsOptIn,
+                consentSource: consent.consentSource ?? 'chat-widget-prechat',
+            };
+            if (consent.consentAt) c.consentAt = consent.consentAt;
+            meta.consent = c;
+        }
+        if (state.verifiedEmail) meta.verifiedEmail = state.verifiedEmail;
+        return Object.keys(meta).length > 0 ? meta : undefined;
+    }
+
+    /** Lazily open the shared transport + client. Idempotent within a connect. */
+    private async ensureClient(): Promise<void> {
+        if (this.client) return;
+        this.transport = new BrowserWebSocketTransport(this.config.endpoint);
+        this.client = new SmoothAgentClient({ url: this.config.endpoint, transport: this.transport });
+        // Route custom cross-device frames (and any unsolicited event) here.
+        this.unsubscribeEvents = this.client.onEvent((event) => this.handleUnsolicited(event));
+        await this.client.connect();
+    }
+
+    /**
+     * Open the transport and either RESUME a persisted session or create a new one.
+     *
+     * Resume (ADR-048 §b): if a persisted `sessionId` exists → `get_session`; when
+     * its `status !== 'ended'` we reuse it and hydrate the transcript from
+     * `get_messages` (newest-first page, reversed to chronological). On `ended`/404
+     * we clear ONLY the session pointer (identity/consent survive) and create fresh.
+     */
     async connect(): Promise<void> {
         if (this.status === 'connecting' || this.status === 'ready') return;
         this.setStatus('connecting');
         try {
-            this.client = new SmoothAgentClient({ url: this.config.endpoint });
-            await this.client.connect();
-            const session = await this.client.createConversationSession({
-                agentId: this.config.agentId,
-                userName: this.identity.name,
-                userEmail: this.identity.email,
-                // Phone has no first-class field yet; carry it in session metadata.
-                ...(this.identity.phone ? { metadata: { userPhone: this.identity.phone } } : {}),
-            });
-            this.sessionId = session.sessionId;
+            await this.ensureClient();
+            const persistedSessionId = this.store.getState().sessionId;
+            if (persistedSessionId) {
+                const resumed = await this.tryResume(persistedSessionId);
+                if (resumed) {
+                    this.setStatus('ready');
+                    return;
+                }
+                // Resume failed (ended/404/gone) — clear the pointer, keep identity.
+                this.store.getState().clearSession();
+            }
+            await this.createSession();
             this.setStatus('ready');
         } catch (err) {
             this.setStatus('error', err instanceof Error ? err.message : String(err));
@@ -199,6 +438,63 @@ export class ConversationController {
         }
     }
 
+    /** `create_conversation_session` with fingerprint + identity + consent metadata. */
+    private async createSession(): Promise<void> {
+        if (!this.client) throw new Error('Conversation is not connected');
+        const state = this.store.getState();
+        const metadata = this.sessionMetadata();
+        const session = await this.client.createConversationSession({
+            agentId: this.config.agentId,
+            userName: state.identity.name,
+            userEmail: state.identity.email,
+            browserFingerprint: this.fingerprint(),
+            ...(metadata ? { metadata } : {}),
+        });
+        this.sessionId = session.sessionId;
+        this.store.getState().setSessionId(session.sessionId);
+    }
+
+    /**
+     * Attempt to resume `sessionId`: returns true and hydrates the transcript when
+     * the session is live, false when it has ended / can't be fetched.
+     */
+    private async tryResume(sessionId: string): Promise<boolean> {
+        if (!this.client) return false;
+        let snap: { status?: 'active' | 'idle' | 'ended' };
+        try {
+            snap = await this.client.getSession({ sessionId });
+        } catch {
+            return false; // 404 / SESSION_NOT_FOUND / network — start fresh.
+        }
+        if (snap.status === 'ended') return false;
+
+        this.sessionId = sessionId;
+        await this.hydrateHistory(sessionId);
+        return true;
+    }
+
+    /** Page recent history (newest-first), reverse to chronological, and render. */
+    private async hydrateHistory(sessionId: string): Promise<void> {
+        if (!this.client) return;
+        try {
+            const page = await this.client.getMessages({ sessionId, limit: 50 });
+            const rows = Array.isArray(page.messages) ? page.messages : [];
+            // The server returns newest-first; reverse to chronological for the UI.
+            const chronological = [...rows].reverse();
+            const hydrated: ChatMessage[] = [];
+            chronological.forEach((m, i) => {
+                const chat = wireMessageToChat(m as WireMessage, i);
+                if (chat) hydrated.push(chat);
+            });
+            this.messages.length = 0;
+            this.messages.push(...hydrated);
+            this.emitMessages();
+        } catch {
+            // History fetch is best-effort: a resumable session with no fetchable
+            // history just shows an empty transcript rather than failing the resume.
+        }
+    }
+
     /**
      * Submit a user message. Appends the user bubble immediately, then streams the
      * assistant reply token-by-token, finalizing on `eventual_response`.
@@ -309,10 +605,159 @@ export class ConversationController {
         }
     }
 
+    // ─────────────────── Cross-device "restore my chats" (§c) ───────────────────
+
+    /**
+     * Send a raw frame over the shared transport for a custom verb the engine
+     * client doesn't model (`request_identity_otp` etc.), then route the matching
+     * response back via {@link handleUnsolicited}. Returns the minted requestId.
+     */
+    private sendIdentityFrame(action: string, payload: Record<string, unknown>, onReply: (event: ServerEvent) => void): string {
+        const requestId = this.nextId('idreq');
+        this.identityWaiters.set(requestId, onReply);
+        this.transport?.send(JSON.stringify({ action, requestId, ...payload }));
+        return requestId;
+    }
+
+    /** Read a field from either the flat event or its nested `data` / `data.data`. */
+    private static readField(event: ServerEvent, key: string): unknown {
+        const top = (event as unknown as Record<string, unknown>)[key];
+        if (top !== undefined) return top;
+        const data = (event as { data?: { data?: Record<string, unknown>; [k: string]: unknown } }).data;
+        if (data) {
+            if (data[key] !== undefined) return data[key];
+            if (data.data && data.data[key] !== undefined) return data.data[key];
+        }
+        return undefined;
+    }
+
+    /**
+     * Begin the cross-device restore: request an OTP to `email` over `channel`.
+     * The view should already have collected the email via an explicit affordance.
+     */
+    requestIdentityOtp(email: string, channel: 'email' | 'sms' = 'email'): void {
+        const trimmed = email.trim();
+        if (!trimmed || !this.transport) return;
+        this.setIdentityRestore({ phase: 'requesting', email: trimmed, channel });
+        this.sendIdentityFrame('request_identity_otp', { sessionId: this.sessionId ?? null, email: trimmed, channel }, (event) => {
+            if (event.type === 'otp_sent') {
+                const masked = ConversationController.readField(event, 'maskedDestination');
+                this.setIdentityRestore({ phase: 'awaiting_code', email: trimmed, channel, maskedDestination: typeof masked === 'string' ? masked : undefined });
+            } else if (event.type === 'error') {
+                const msg = ConversationController.readField(event, 'message');
+                this.setIdentityRestore({ phase: 'error', message: typeof msg === 'string' ? msg : 'Could not send a verification code.' });
+            }
+        });
+    }
+
+    /** Submit the code for the cross-device restore. */
+    verifyIdentityOtp(code: string): void {
+        const state = this.identityRestore;
+        const trimmed = code.trim();
+        if (!trimmed || !this.transport) return;
+        if (state.phase !== 'awaiting_code') return;
+        const { email, channel } = state;
+        this.setIdentityRestore({ phase: 'verifying', email, channel });
+        this.sendIdentityFrame('verify_identity_otp', { sessionId: this.sessionId ?? null, email, code: trimmed }, (event) => {
+            if (event.type === 'otp_verified') {
+                this.store.getState().setVerifiedEmail(email);
+                this.resolveIdentity(email);
+            } else if (event.type === 'otp_invalid') {
+                const remaining = ConversationController.readField(event, 'attemptsRemaining');
+                this.setIdentityRestore({
+                    phase: 'awaiting_code',
+                    email,
+                    channel,
+                    error: 'That code was incorrect.',
+                    attemptsRemaining: typeof remaining === 'number' ? remaining : undefined,
+                });
+            } else if (event.type === 'error') {
+                const msg = ConversationController.readField(event, 'message');
+                this.setIdentityRestore({ phase: 'error', message: typeof msg === 'string' ? msg : 'Verification failed.' });
+            }
+        });
+    }
+
+    /** Resolve the verified identity → list of restorable conversations. */
+    private resolveIdentity(email: string): void {
+        if (!this.transport) return;
+        this.setIdentityRestore({ phase: 'resolving', email });
+        this.sendIdentityFrame('resolve_identity', { sessionId: this.sessionId ?? null, email }, (event) => {
+            const resolved = ConversationController.readField(event, 'resolved');
+            if (resolved === false) {
+                this.setIdentityRestore({ phase: 'resolved', email, conversations: [] });
+                return;
+            }
+            const raw = ConversationController.readField(event, 'conversations');
+            const conversations: RestorableConversation[] = Array.isArray(raw)
+                ? raw
+                      .map((c): RestorableConversation | null => {
+                          if (!c || typeof c !== 'object') return null;
+                          const o = c as Record<string, unknown>;
+                          const conversationId = typeof o.conversationId === 'string' ? o.conversationId : '';
+                          const sessionId = typeof o.sessionId === 'string' ? o.sessionId : '';
+                          if (!sessionId) return null;
+                          return {
+                              conversationId,
+                              sessionId,
+                              lastActivityAt: typeof o.lastActivityAt === 'string' ? o.lastActivityAt : undefined,
+                              preview: typeof o.preview === 'string' ? o.preview : undefined,
+                          };
+                      })
+                      .filter((c): c is RestorableConversation => c !== null)
+                : [];
+            this.setIdentityRestore({ phase: 'resolved', email, conversations });
+        });
+    }
+
+    /**
+     * Replay a chosen restorable conversation: point the live session at its
+     * sessionId, hydrate its transcript, and persist the new pointer so the next
+     * `sendMessage` continues it.
+     */
+    async restoreConversation(sessionId: string): Promise<void> {
+        if (!this.client) await this.ensureClient();
+        const resumed = await this.tryResume(sessionId);
+        if (resumed) {
+            this.store.getState().setSessionId(sessionId);
+            this.setIdentityRestore({ phase: 'idle' });
+            this.setStatus('ready');
+        } else {
+            this.setIdentityRestore({ phase: 'error', message: 'That conversation is no longer available.' });
+        }
+    }
+
+    /** Dismiss the cross-device restore panel. */
+    cancelIdentityRestore(): void {
+        this.setIdentityRestore({ phase: 'idle' });
+    }
+
+    /**
+     * Route an unsolicited / custom-verb frame to its waiting handler. The engine
+     * client surfaces every frame it can't correlate to a pending request or turn
+     * here; we match by the echoed `requestId` of our identity frames.
+     */
+    private handleUnsolicited(event: ServerEvent): void {
+        const requestId = (event as { requestId?: string }).requestId ?? (event as { data?: { requestId?: string } }).data?.requestId;
+        if (typeof requestId === 'string' && this.identityWaiters.has(requestId)) {
+            const handler = this.identityWaiters.get(requestId);
+            // otp_invalid / otp_sent keep the flow alive (retry / interim ack);
+            // other terminals end it, so drop the waiter.
+            if (event.type !== 'otp_invalid' && event.type !== 'otp_sent') {
+                this.identityWaiters.delete(requestId);
+            }
+            handler?.(event);
+        }
+    }
+
     /** Tear down the underlying client. */
     disconnect(): void {
+        this.unsubscribeEvents?.();
+        this.unsubscribeEvents = null;
+        this.identityWaiters.clear();
         this.client?.disconnect('widget closed');
         this.client = null;
+        this.transport = null;
         this.sessionId = null;
         this.activeRequestId = null;
         this.setInterrupt(null);
diff --git a/src/element.ts b/src/element.ts
index fb2dc59..4130d13 100644
--- a/src/element.ts
+++ b/src/element.ts
@@ -16,7 +16,7 @@
  */
 import type { ChatWidgetConfig, ChatWidgetMode, ChatWidgetTheme } from './config.js';
 import { needsUserInfo, resolveConfig } from './config.js';
-import { type ChatMessage, type Citation, type ConnectionStatus, ConversationController, type Interrupt } from './conversation.js';
+import { type ChatMessage, type Citation, type ConnectionStatus, ConversationController, type IdentityRestore, type Interrupt } from './conversation.js';
 import { SMOOTH_LOGO_SVG } from './logo.js';
 import { cleanCitationSnippet, escapeHtml, renderMarkdown, safeHttpUrl } from './markdown.js';
 import { buildStyles } from './styles.js';
@@ -73,6 +73,12 @@ export class SmoothAgentChatElement extends HTMLElement {
     /** Current mid-turn interrupt (OTP / tool-confirmation), or null. */
     private interrupt: Interrupt | null = null;
     private interruptEl: HTMLElement | null = null;
+    /** Cross-device "restore my chats" flow state (ADR-048 §c). */
+    private identityRestore: IdentityRestore = { phase: 'idle' };
+    /** Whether the cross-device restore affordance is offered (config). */
+    private allowChatRestore = true;
+    /** True while the pre-chat identity gate is showing (blocks premature connect). */
+    private gating = false;
 
     // Cached DOM refs (populated in render()).
     private panelEl: HTMLElement | null = null;
@@ -136,7 +142,10 @@ export class SmoothAgentChatElement extends HTMLElement {
     openChat(): void {
         this.open = true;
         this.syncOpenState();
-        void this.controller?.connect().catch(() => {});
+        // Don't connect while the pre-chat identity gate is unsatisfied — connecting
+        // here would create a session BEFORE the visitor submits their name/email/
+        // consent, sending an empty identity. The form's submit handler connects.
+        if (!this.gating) void this.controller?.connect().catch(() => {});
     }
 
     /** Collapse the chat panel back to the launcher. */
@@ -186,6 +195,8 @@ export class SmoothAgentChatElement extends HTMLElement {
         }
         const resolved = resolveConfig(config);
 
+        this.allowChatRestore = resolved.allowChatRestore;
+
         // (Re)create the controller only when there isn't one yet. Attribute churn
         // (e.g. theme tweaks) re-renders the view without dropping the session.
         if (!this.controller) {
@@ -202,8 +213,17 @@ export class SmoothAgentChatElement extends HTMLElement {
                     this.interrupt = interrupt;
                     this.renderInterrupt();
                 },
+                onIdentityRestore: (state) => {
+                    this.identityRestore = state;
+                    this.renderInterrupt();
+                },
             });
             if (resolved.startOpen) this.open = true;
+            // Returning visitor: a persisted session or identity lets us skip the
+            // pre-chat gate and resume straight into the conversation (ADR-048 §b).
+            if (this.controller.hasPersistedSession() || this.controller.hasPersistedIdentity()) {
+                this.userInfoSatisfied = true;
+            }
         }
 
         const fullpage = resolved.mode === 'fullpage';
@@ -242,8 +262,20 @@ export class SmoothAgentChatElement extends HTMLElement {
 
         // Gate the conversation behind a pre-chat identity form when required.
         const gating = needsUserInfo(resolved) && !this.userInfoSatisfied;
-        const field = (name: string, type: string, label: string, autocomplete: string) =>
-            `<label class="pc-field"><span>${escapeHtml(label)}</span><input name="${name}" type="${type}" autocomplete="${autocomplete}" required /></label>`;
+        this.gating = gating;
+        // Phone is collected by default (optional unless requirePhone). Consent
+        // checkboxes default to shown, explicit + unchecked (ADR-048 §a/§3).
+        const showPhone = resolved.requirePhone || resolved.collectPhone;
+        const field = (name: string, type: string, label: string, autocomplete: string, required: boolean) =>
+            `<label class="pc-field"><span>${escapeHtml(label)}</span><input name="${name}" type="${type}" autocomplete="${autocomplete}"${required ? ' required' : ''} /></label>`;
+        const consentBox = (name: string, label: string) =>
+            `<label class="pc-consent"><input name="${name}" type="checkbox" /><span>${escapeHtml(label)}</span></label>`;
+        const consentHtml = resolved.collectConsent
+            ? `<div class="pc-consents">
+                    ${consentBox('emailOptIn', 'Email me product news and offers.')}
+                    ${consentBox('smsOptIn', 'Text me updates by SMS. Message/data rates may apply.')}
+                </div>`
+            : '';
         const prechatHtml = `
             <div class="prechat">
                 <div class="pc-head">
@@ -251,12 +283,14 @@ export class SmoothAgentChatElement extends HTMLElement {
                     <div class="pc-sub">A couple details so ${escapeHtml(resolved.agentName)} can help.</div>
                 </div>
                 <form class="pc-form" novalidate>
-                    ${resolved.requireName ? field('name', 'text', 'Name', 'name') : ''}
-                    ${resolved.requireEmail ? field('email', 'email', 'Email', 'email') : ''}
-                    ${resolved.requirePhone ? field('phone', 'tel', 'Phone', 'tel') : ''}
+                    ${resolved.requireName ? field('name', 'text', 'Name', 'name', true) : ''}
+                    ${resolved.requireEmail ? field('email', 'email', 'Email', 'email', true) : ''}
+                    ${showPhone ? field('phone', 'tel', 'Phone', 'tel', resolved.requirePhone) : ''}
+                    ${consentHtml}
                     <button type="submit" class="pc-submit">Start chat</button>
                 </form>
             </div>`;
+        const restoreLink = this.allowChatRestore ? ` · <button type="button" class="restore-link">Restore my chats</button>` : '';
         const chatHtml = `
                 <div class="messages"></div>
                 <div class="interrupt hidden"></div>
@@ -265,7 +299,7 @@ export class SmoothAgentChatElement extends HTMLElement {
                         <textarea rows="1" placeholder="${escapeHtml(resolved.placeholder)}"></textarea>
                         <button class="send" type="button" aria-label="Send message">${ICON.send}</button>
                     </div>
-                    <div class="footer">powered by <b>smooth&#8209;operator</b></div>
+                    <div class="footer">powered by <b>smooth&#8209;operator</b>${restoreLink}</div>
                 </div>`;
 
         const container = document.createElement('div');
@@ -313,6 +347,14 @@ export class SmoothAgentChatElement extends HTMLElement {
             this.handlePrechatSubmit(pcForm as HTMLFormElement);
         });
 
+        // Cross-device "Restore my chats": open the panel + start the email entry.
+        container.querySelector('.restore-link')?.addEventListener('click', () => {
+            // Ensure we have a live transport before the OTP request.
+            void this.controller?.connect().catch(() => {});
+            this.identityRestore = { phase: 'awaiting_email' };
+            this.renderInterrupt();
+        });
+
         // Full-page mode connects eagerly (there's no launcher click to trigger it) —
         // but only once any identity gate is cleared.
         if (fullpage && !gating) void this.controller?.connect().catch(() => {});
@@ -335,6 +377,13 @@ export class SmoothAgentChatElement extends HTMLElement {
         el.replaceChildren();
         const it = this.interrupt;
         if (!it) {
+            // No mid-turn interrupt — but the cross-device restore flow may be
+            // active, which reuses this same overlay slot.
+            if (this.identityRestore.phase !== 'idle') {
+                el.classList.remove('hidden');
+                el.appendChild(this.buildRestoreCard());
+                return;
+            }
             el.classList.add('hidden');
             return;
         }
@@ -420,12 +469,189 @@ export class SmoothAgentChatElement extends HTMLElement {
         el.appendChild(card);
     }
 
-    /** Collect identity from the pre-chat form, then drop into the chat view. */
+    /**
+     * Build the cross-device "Restore my chats" card (ADR-048 §c). Reuses the
+     * same overlay slot + visual language as the OTP interrupt. All server-supplied
+     * strings (masked destination, conversation previews) are set via `textContent`
+     * — never innerHTML — so they can't inject markup; only the static lock icon
+     * uses innerHTML.
+     */
+    private buildRestoreCard(): HTMLElement {
+        const state = this.identityRestore;
+        const card = document.createElement('div');
+        card.className = 'int-card';
+
+        const head = document.createElement('div');
+        head.className = 'int-head';
+        const ico = document.createElement('span');
+        ico.className = 'int-ico';
+        ico.innerHTML = ICON.lock; // static, trusted
+        const title = document.createElement('span');
+        title.className = 'int-title';
+        title.textContent = 'Restore your chats';
+        head.append(ico, title);
+        card.appendChild(head);
+
+        const close = document.createElement('button');
+        close.className = 'int-close';
+        close.type = 'button';
+        close.setAttribute('aria-label', 'Cancel');
+        close.textContent = '×';
+        close.addEventListener('click', () => {
+            this.controller?.cancelIdentityRestore();
+            this.identityRestore = { phase: 'idle' };
+            this.renderInterrupt();
+        });
+        card.appendChild(close);
+
+        if (state.phase === 'awaiting_email') {
+            const desc = document.createElement('div');
+            desc.className = 'int-desc';
+            desc.textContent = "Enter your email and we'll send a code to find your previous chats.";
+            card.appendChild(desc);
+
+            const row = document.createElement('div');
+            row.className = 'int-row';
+            const input = document.createElement('input');
+            input.className = 'int-input';
+            input.type = 'email';
+            input.autocomplete = 'email';
+            input.placeholder = 'you@example.com';
+            const go = () => {
+                const email = input.value.trim();
+                if (email) this.controller?.requestIdentityOtp(email, 'email');
+            };
+            input.addEventListener('keydown', (ev) => {
+                if (ev.key === 'Enter') {
+                    ev.preventDefault();
+                    go();
+                }
+            });
+            const send = document.createElement('button');
+            send.className = 'int-btn primary';
+            send.type = 'button';
+            send.textContent = 'Send code';
+            send.addEventListener('click', go);
+            row.append(input, send);
+            card.appendChild(row);
+            if (state.error) {
+                const err = document.createElement('div');
+                err.className = 'int-error';
+                err.textContent = state.error;
+                card.appendChild(err);
+            }
+            queueMicrotask(() => input.focus());
+        } else if (state.phase === 'requesting' || state.phase === 'verifying' || state.phase === 'resolving') {
+            const msg = document.createElement('div');
+            msg.className = 'int-sent';
+            msg.textContent = state.phase === 'requesting' ? 'Sending a code…' : state.phase === 'verifying' ? 'Verifying…' : 'Finding your chats…';
+            card.appendChild(msg);
+        } else if (state.phase === 'awaiting_code') {
+            if (state.maskedDestination) {
+                const sent = document.createElement('div');
+                sent.className = 'int-sent';
+                sent.textContent = `Code sent to ${state.maskedDestination}.`;
+                card.appendChild(sent);
+            }
+            const row = document.createElement('div');
+            row.className = 'int-row';
+            const input = document.createElement('input');
+            input.className = 'int-input';
+            input.type = 'text';
+            input.inputMode = 'numeric';
+            input.autocomplete = 'one-time-code';
+            input.placeholder = 'Enter code';
+            const submit = () => {
+                const code = input.value.trim();
+                if (code) this.controller?.verifyIdentityOtp(code);
+            };
+            input.addEventListener('keydown', (ev) => {
+                if (ev.key === 'Enter') {
+                    ev.preventDefault();
+                    submit();
+                }
+            });
+            const verify = document.createElement('button');
+            verify.className = 'int-btn primary';
+            verify.type = 'button';
+            verify.textContent = 'Verify';
+            verify.addEventListener('click', submit);
+            row.append(input, verify);
+            card.appendChild(row);
+            if (state.error) {
+                const err = document.createElement('div');
+                err.className = 'int-error';
+                err.textContent = state.attemptsRemaining != null ? `${state.error} (${state.attemptsRemaining} left)` : state.error;
+                card.appendChild(err);
+            }
+            queueMicrotask(() => input.focus());
+        } else if (state.phase === 'resolved') {
+            if (state.conversations.length === 0) {
+                const none = document.createElement('div');
+                none.className = 'int-desc';
+                none.textContent = 'No previous chats found for that email.';
+                card.appendChild(none);
+            } else {
+                const pick = document.createElement('div');
+                pick.className = 'int-desc';
+                pick.textContent = 'Pick a conversation to continue:';
+                card.appendChild(pick);
+                const list = document.createElement('div');
+                list.className = 'restore-list';
+                for (const conv of state.conversations) {
+                    const btn = document.createElement('button');
+                    btn.type = 'button';
+                    btn.className = 'restore-item';
+                    const preview = document.createElement('span');
+                    preview.className = 'restore-preview';
+                    preview.textContent = conv.preview || 'Conversation';
+                    btn.appendChild(preview);
+                    if (conv.lastActivityAt) {
+                        const when = document.createElement('span');
+                        when.className = 'restore-when';
+                        when.textContent = this.formatWhen(conv.lastActivityAt);
+                        btn.appendChild(when);
+                    }
+                    btn.addEventListener('click', () => {
+                        void this.controller?.restoreConversation(conv.sessionId);
+                    });
+                    list.appendChild(btn);
+                }
+                card.appendChild(list);
+            }
+        } else if (state.phase === 'error') {
+            const err = document.createElement('div');
+            err.className = 'int-error';
+            err.textContent = state.message;
+            card.appendChild(err);
+        }
+
+        return card;
+    }
+
+    /** Format an ISO timestamp as a short, locale-aware label (best-effort). */
+    private formatWhen(iso: string): string {
+        const d = new Date(iso);
+        if (Number.isNaN(d.getTime())) return '';
+        try {
+            return d.toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+        } catch {
+            return '';
+        }
+    }
+
+    /** Collect identity + consent from the pre-chat form, then drop into the chat view. */
     private handlePrechatSubmit(form: HTMLFormElement): void {
         if (!form.reportValidity()) return;
         const data = new FormData(form);
         const val = (k: string) => ((data.get(k) as string | null)?.trim() || undefined);
-        this.controller?.setUserInfo({ name: val('name'), email: val('email'), phone: val('phone') });
+        const checked = (k: string) => data.get(k) === 'on';
+        this.controller?.setUserInfo({
+            name: val('name'),
+            email: val('email'),
+            phone: val('phone'),
+            consent: { emailOptIn: checked('emailOptIn'), smsOptIn: checked('smsOptIn') },
+        });
         this.userInfoSatisfied = true;
         this.render();
         void this.controller?.connect().catch(() => {});
diff --git a/src/fingerprint.test.ts b/src/fingerprint.test.ts
new file mode 100644
index 0000000..8aefb55
--- /dev/null
+++ b/src/fingerprint.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it, vi } from 'vitest';
+import { computeFingerprint, getOrCreateFingerprint } from './fingerprint.js';
+
+describe('computeFingerprint', () => {
+    it('produces a non-empty UUID.signalHash token', () => {
+        const fp = computeFingerprint();
+        expect(fp.length).toBeGreaterThan(10);
+        // Shape: <uuid>.<8-hex>
+        const [uuid, hash] = fp.split('.');
+        expect(uuid).toMatch(/^[0-9a-f-]{36}$/i);
+        expect(hash).toMatch(/^[0-9a-f]{8}$/i);
+    });
+
+    it('generates a fresh UUID each call (the persisted value is what stabilizes it)', () => {
+        expect(computeFingerprint()).not.toBe(computeFingerprint());
+    });
+
+    it('keeps a stable signal-hash suffix across calls (same browser env)', () => {
+        const a = computeFingerprint().split('.')[1];
+        const b = computeFingerprint().split('.')[1];
+        expect(a).toBe(b);
+    });
+});
+
+describe('getOrCreateFingerprint', () => {
+    it('computes + stores once, then returns the cached value', () => {
+        let stored: string | null = null;
+        const set = vi.fn((fp: string) => {
+            stored = fp;
+        });
+        const get = () => stored;
+
+        const first = getOrCreateFingerprint(get, set);
+        expect(set).toHaveBeenCalledTimes(1);
+        const second = getOrCreateFingerprint(get, set);
+        // No second write; same value returned.
+        expect(set).toHaveBeenCalledTimes(1);
+        expect(second).toBe(first);
+    });
+
+    it('returns the existing value without recomputing', () => {
+        const set = vi.fn();
+        const fp = getOrCreateFingerprint(() => 'pre-existing.deadbeef', set);
+        expect(fp).toBe('pre-existing.deadbeef');
+        expect(set).not.toHaveBeenCalled();
+    });
+});
diff --git a/src/fingerprint.ts b/src/fingerprint.ts
new file mode 100644
index 0000000..3bdb5bb
--- /dev/null
+++ b/src/fingerprint.ts
@@ -0,0 +1,122 @@
+/**
+ * Browser fingerprint — a stable, privacy-light identifier used by the
+ * smooth-operator server to correlate an anonymous visitor's sessions across
+ * page loads (and, server-side, to match an anonymous fingerprint to a known
+ * CRM contact). It rides every `create_conversation_session` as
+ * `browserFingerprint` (see ADR-048).
+ *
+ * ## Why not ThumbmarkJS
+ *
+ * The ADR floats ThumbmarkJS as the reference implementation. For an *embed*
+ * that is injected onto arbitrary host pages, ThumbmarkJS is too heavy: its
+ * full build pulls in extensive device-detection tables and async
+ * component collection, adding tens of kilobytes (and async surface) to a
+ * bundle whose whole selling point is staying out of the host page's
+ * LCP/TBT budget. The fingerprint here is a few hundred bytes.
+ *
+ * ## What this is (and the tradeoff)
+ *
+ * The correlation that actually matters — "is this the same browser as last
+ * time?" — is carried by a **persisted random UUID** (the `browserFingerprint`
+ * field in the persisted store). That UUID is generated once and reused for
+ * the life of the localStorage entry, so same-browser resume is exact and
+ * deterministic. The signal hash below is a best-effort entropy *supplement*
+ * mixed into that UUID's derivation seed on first generation — it gives the
+ * server-side resolver a soft signal for the (rare) cross-storage case where
+ * the UUID was cleared but the device is unchanged. It is intentionally NOT a
+ * high-entropy device fingerprint: no canvas/WebGL/audio probes, no font
+ * enumeration, nothing that reads as invasive tracking. The tradeoff is weaker
+ * cross-storage matching in exchange for a tiny, transparent, no-network,
+ * XSS-safe implementation. The server's resolver (SMOODEV-2129d) is the source
+ * of truth for any fuzzy matching; the client just supplies a stable token.
+ */
+
+/** Collect a small set of stable, non-invasive browser signals. */
+function collectSignals(): string {
+    const parts: string[] = [];
+    try {
+        const nav = typeof navigator !== 'undefined' ? navigator : undefined;
+        if (nav) {
+            parts.push(`ua:${nav.userAgent ?? ''}`);
+            parts.push(`lang:${nav.language ?? ''}`);
+            parts.push(`langs:${Array.isArray(nav.languages) ? nav.languages.join(',') : ''}`);
+            // `platform` is deprecated but still widely present and stable.
+            parts.push(`plat:${(nav as Navigator & { platform?: string }).platform ?? ''}`);
+            parts.push(`hc:${(nav as Navigator & { hardwareConcurrency?: number }).hardwareConcurrency ?? ''}`);
+            parts.push(`dm:${(nav as Navigator & { deviceMemory?: number }).deviceMemory ?? ''}`);
+        }
+        if (typeof screen !== 'undefined') {
+            parts.push(`scr:${screen.width}x${screen.height}x${screen.colorDepth}`);
+        }
+        if (typeof Intl !== 'undefined') {
+            try {
+                parts.push(`tz:${Intl.DateTimeFormat().resolvedOptions().timeZone ?? ''}`);
+            } catch {
+                /* resolvedOptions can throw in locked-down environments */
+            }
+        }
+        parts.push(`tzo:${new Date().getTimezoneOffset()}`);
+    } catch {
+        /* a hostile/locked-down navigator must never break widget boot */
+    }
+    return parts.join('|');
+}
+
+/**
+ * A small, fast, non-cryptographic string hash (FNV-1a, 32-bit) rendered as
+ * an unsigned hex string. Stable across runs for the same input. Not used for
+ * any security decision — only to derive a deterministic seed from the signal
+ * string above.
+ */
+function fnv1a(input: string): string {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        h ^= input.charCodeAt(i);
+        // 32-bit FNV prime multiply via shifts to stay in int range.
+        h = Math.imul(h, 0x01000193);
+    }
+    // >>> 0 → unsigned; pad to 8 hex chars.
+    return (h >>> 0).toString(16).padStart(8, '0');
+}
+
+/** Generate a UUID, preferring `crypto.randomUUID`, falling back to a v4-shaped string. */
+function generateUuid(): string {
+    try {
+        if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+            return crypto.randomUUID();
+        }
+    } catch {
+        /* fall through to the manual generator */
+    }
+    // RFC 4122 v4 shape from Math.random — only reached when crypto.randomUUID
+    // is unavailable (very old engines). Sufficient for a correlation token.
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+
+/**
+ * Compute a fresh fingerprint token: a stable random UUID, suffixed with the
+ * FNV hash of the device signals so the server can recover a soft device
+ * signal even if it only has the token. Called ONCE per browser (the result is
+ * persisted and reused) — see {@link getOrCreateFingerprint}.
+ */
+export function computeFingerprint(): string {
+    const signalHash = fnv1a(collectSignals());
+    return `${generateUuid()}.${signalHash}`;
+}
+
+/**
+ * Return the cached fingerprint if one was already computed for this browser,
+ * otherwise compute + persist a new one via the provided accessors. The
+ * persistence layer owns storage; this function owns the "compute once" policy.
+ */
+export function getOrCreateFingerprint(get: () => string | null, set: (fp: string) => void): string {
+    const existing = get();
+    if (existing) return existing;
+    const fp = computeFingerprint();
+    set(fp);
+    return fp;
+}
diff --git a/src/index.ts b/src/index.ts
index 29f0ecb..7841454 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -37,5 +37,18 @@ export {
     type Citation,
     type ConnectionStatus,
     type ConversationEvents,
+    type IdentityRestore,
+    type RestorableConversation,
     type Role,
+    type UserInfo,
 } from './conversation.js';
+export {
+    createWidgetStore,
+    PERSIST_VERSION,
+    storageKey,
+    type ConsentState,
+    type IdentityState,
+    type PersistedWidgetState,
+    type WidgetStore,
+} from './persistence.js';
+export { computeFingerprint, getOrCreateFingerprint } from './fingerprint.js';
diff --git a/src/persistence.test.ts b/src/persistence.test.ts
new file mode 100644
index 0000000..df5b9ff
--- /dev/null
+++ b/src/persistence.test.ts
@@ -0,0 +1,99 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createWidgetStore, PERSIST_VERSION, type PersistedWidgetState, storageKey } from './persistence.js';
+
+const AGENT = 'agent-123';
+
+describe('persistence store', () => {
+    beforeEach(() => {
+        localStorage.clear();
+    });
+    afterEach(() => {
+        localStorage.clear();
+    });
+
+    it('uses the per-agent localStorage key', () => {
+        expect(storageKey(AGENT)).toBe('smoo-chat-widget:agent-123');
+    });
+
+    it('starts empty with the current version', () => {
+        const store = createWidgetStore(AGENT);
+        const s = store.getState();
+        expect(s.version).toBe(PERSIST_VERSION);
+        expect(s.sessionId).toBeNull();
+        expect(s.identity).toEqual({});
+        expect(s.consent).toEqual({ emailOptIn: false, smsOptIn: false });
+        expect(s.verifiedEmail).toBeNull();
+        expect(s.browserFingerprint).toBeNull();
+    });
+
+    it('mergeIdentity only overwrites provided fields', () => {
+        const store = createWidgetStore(AGENT);
+        store.getState().mergeIdentity({ name: 'Ada', email: 'ada@example.com' });
+        store.getState().mergeIdentity({ phone: '+15551234567' });
+        expect(store.getState().identity).toEqual({ name: 'Ada', email: 'ada@example.com', phone: '+15551234567' });
+        // undefined must NOT clobber an existing value.
+        store.getState().mergeIdentity({ name: undefined });
+        expect(store.getState().identity.name).toBe('Ada');
+    });
+
+    it('persists ONLY the pointer/identity/consent shape (never a transcript)', () => {
+        const store = createWidgetStore(AGENT);
+        store.getState().setSessionId('sess-1');
+        store.getState().mergeIdentity({ name: 'Ada' });
+        store.getState().setConsent({ emailOptIn: true, smsOptIn: false, consentSource: 'chat-widget-prechat', consentAt: '2026-01-01T00:00:00.000Z' });
+        store.getState().setVerifiedEmail('ada@example.com');
+        store.getState().setBrowserFingerprint('fp-abc');
+
+        const raw = localStorage.getItem(storageKey(AGENT));
+        expect(raw).toBeTruthy();
+        const parsed = JSON.parse(raw as string) as { state: PersistedWidgetState };
+        const keys = Object.keys(parsed.state).sort();
+        expect(keys).toEqual(['browserFingerprint', 'consent', 'identity', 'sessionId', 'verifiedEmail', 'version'].sort());
+        // No message/transcript field leaks into storage.
+        expect(JSON.stringify(parsed.state)).not.toContain('messages');
+    });
+
+    it('clearSession drops the pointer but keeps identity/consent/verifiedEmail/fingerprint', () => {
+        const store = createWidgetStore(AGENT);
+        store.getState().setSessionId('sess-1');
+        store.getState().mergeIdentity({ name: 'Ada' });
+        store.getState().setConsent({ emailOptIn: true, smsOptIn: true });
+        store.getState().setVerifiedEmail('ada@example.com');
+        store.getState().setBrowserFingerprint('fp-abc');
+
+        store.getState().clearSession();
+        const s = store.getState();
+        expect(s.sessionId).toBeNull();
+        expect(s.identity.name).toBe('Ada');
+        expect(s.consent.emailOptIn).toBe(true);
+        expect(s.verifiedEmail).toBe('ada@example.com');
+        expect(s.browserFingerprint).toBe('fp-abc');
+    });
+
+    it('rehydrates a persisted blob on a fresh store (resume across reload)', () => {
+        const a = createWidgetStore(AGENT);
+        a.getState().setSessionId('sess-keep');
+        a.getState().setBrowserFingerprint('fp-keep');
+        // A brand-new store for the same agent reads the persisted blob.
+        const b = createWidgetStore(AGENT);
+        expect(b.getState().sessionId).toBe('sess-keep');
+        expect(b.getState().browserFingerprint).toBe('fp-keep');
+    });
+
+    it('migrates an unversioned/old blob into the current shape', () => {
+        // Simulate an old persisted blob with missing fields + a stray transcript.
+        localStorage.setItem(
+            storageKey(AGENT),
+            JSON.stringify({ state: { sessionId: 'old-sess', messages: [{ text: 'leak' }] }, version: 0 }),
+        );
+        const store = createWidgetStore(AGENT);
+        const s = store.getState();
+        expect(s.version).toBe(PERSIST_VERSION);
+        expect(s.sessionId).toBe('old-sess');
+        // Missing fields backfilled to safe defaults.
+        expect(s.consent).toEqual({ emailOptIn: false, smsOptIn: false });
+        expect(s.identity).toEqual({});
+        // The stray transcript must not survive migration.
+        expect((s as unknown as Record<string, unknown>).messages).toBeUndefined();
+    });
+});
diff --git a/src/persistence.ts b/src/persistence.ts
new file mode 100644
index 0000000..1c096bc
--- /dev/null
+++ b/src/persistence.ts
@@ -0,0 +1,215 @@
+/**
+ * Persisted widget state — the identity / consent / session-pointer client layer
+ * (ADR-048, SMOODEV-2129e).
+ *
+ * Built on Zustand's framework-agnostic `vanilla` store + the `persist`
+ * middleware (the user explicitly chose Zustand; it's ~1KB and has no React
+ * dependency, so it works inside the web component). The store is keyed per
+ * agent — localStorage key `smoo-chat-widget:<agentId>` — so two agents embedded
+ * on the same origin don't clobber each other.
+ *
+ * ## What persists (and, deliberately, what does NOT)
+ *
+ * Only a **pointer** to the conversation plus the visitor's identity + marketing
+ * consent + verified email + browser fingerprint. The transcript is **never**
+ * persisted: the smooth-operator server is the source of truth and the widget
+ * re-hydrates history via `getMessages` on resume. This keeps localStorage small
+ * and avoids stale/divergent transcripts.
+ *
+ * `version` drives `persist.migrate` so future shape changes can upgrade old
+ * blobs in place instead of silently dropping them.
+ */
+import { createStore, type StoreApi } from 'zustand/vanilla';
+import { persist, type PersistStorage } from 'zustand/middleware';
+
+/** Current persisted-shape version. Bump when the shape below changes incompatibly. */
+export const PERSIST_VERSION = 1 as const;
+
+/** Marketing-consent record captured at the pre-chat form. */
+export interface ConsentState {
+    emailOptIn: boolean;
+    smsOptIn: boolean;
+    /** Where the consent was captured. The widget always stamps `chat-widget-prechat`. */
+    consentSource?: string;
+    /** ISO 8601 timestamp stamped when the visitor ticked a consent box. */
+    consentAt?: string;
+}
+
+/** Visitor identity collected from config or the pre-chat form. */
+export interface IdentityState {
+    name?: string;
+    email?: string;
+    phone?: string;
+}
+
+/**
+ * The exact persisted shape (ADR-048 §d). Only the pointer + identity + consent
+ * persist — never the transcript.
+ */
+export interface PersistedWidgetState {
+    version: typeof PERSIST_VERSION;
+    /** Pointer to the active conversation session; cleared on ended/404. */
+    sessionId: string | null;
+    identity: IdentityState;
+    consent: ConsentState;
+    /** Email proven via OTP (same-session or cross-device). Survives session clears. */
+    verifiedEmail: string | null;
+    /** Stable per-browser correlation token (see fingerprint.ts). */
+    browserFingerprint: string | null;
+}
+
+/** Store actions layered on top of the persisted state. */
+export interface WidgetStoreActions {
+    setSessionId: (sessionId: string | null) => void;
+    /** Merge identity fields (undefined values don't clobber existing ones). */
+    mergeIdentity: (identity: IdentityState) => void;
+    /** Replace consent wholesale (the pre-chat form computes the full record). */
+    setConsent: (consent: ConsentState) => void;
+    setVerifiedEmail: (email: string | null) => void;
+    setBrowserFingerprint: (fp: string) => void;
+    /**
+     * Clear the session pointer but KEEP identity / consent / verifiedEmail /
+     * fingerprint — used when a persisted session has ended or 404s so the next
+     * turn starts a fresh session for a known visitor.
+     */
+    clearSession: () => void;
+}
+
+export type WidgetStore = PersistedWidgetState & WidgetStoreActions;
+
+const EMPTY_CONSENT: ConsentState = { emailOptIn: false, smsOptIn: false };
+
+function initialPersisted(): PersistedWidgetState {
+    return {
+        version: PERSIST_VERSION,
+        sessionId: null,
+        identity: {},
+        consent: { ...EMPTY_CONSENT },
+        verifiedEmail: null,
+        browserFingerprint: null,
+    };
+}
+
+/** localStorage key for an agent's persisted widget state. */
+export function storageKey(agentId: string): string {
+    return `smoo-chat-widget:${agentId}`;
+}
+
+/**
+ * A `persist` storage adapter that tolerates the *absence* of localStorage
+ * (SSR, privacy-mode throwing on access, sandboxed iframes). When storage is
+ * unavailable the store still works in-memory; nothing is persisted, but the
+ * widget never throws on boot.
+ */
+function safeStorage(): PersistStorage<PersistedWidgetState> | undefined {
+    let ls: Storage | null = null;
+    try {
+        ls = typeof localStorage !== 'undefined' ? localStorage : null;
+        // Probe: some environments expose localStorage but throw on access.
+        if (ls) {
+            const probe = '__smoo_probe__';
+            ls.setItem(probe, '1');
+            ls.removeItem(probe);
+        }
+    } catch {
+        ls = null;
+    }
+    if (!ls) return undefined;
+    const storage = ls;
+    return {
+        getItem: (name) => {
+            try {
+                const raw = storage.getItem(name);
+                return raw ? (JSON.parse(raw) as ReturnType<PersistStorage<PersistedWidgetState>['getItem']>) : null;
+            } catch {
+                return null;
+            }
+        },
+        setItem: (name, value) => {
+            try {
+                storage.setItem(name, JSON.stringify(value));
+            } catch {
+                /* quota / privacy-mode write failures are non-fatal */
+            }
+        },
+        removeItem: (name) => {
+            try {
+                storage.removeItem(name);
+            } catch {
+                /* non-fatal */
+            }
+        },
+    };
+}
+
+/**
+ * Migrate a persisted blob from an older `version` to the current shape. Today
+ * v1 is the only version, so this just backfills any missing fields onto an
+ * unknown old blob; future versions add `case` branches here.
+ */
+function migrate(persisted: unknown): PersistedWidgetState {
+    const base = initialPersisted();
+    if (!persisted || typeof persisted !== 'object') return base;
+    const p = persisted as Partial<PersistedWidgetState>;
+    return {
+        version: PERSIST_VERSION,
+        sessionId: typeof p.sessionId === 'string' ? p.sessionId : null,
+        identity: {
+            name: typeof p.identity?.name === 'string' ? p.identity.name : undefined,
+            email: typeof p.identity?.email === 'string' ? p.identity.email : undefined,
+            phone: typeof p.identity?.phone === 'string' ? p.identity.phone : undefined,
+        },
+        consent: {
+            emailOptIn: p.consent?.emailOptIn === true,
+            smsOptIn: p.consent?.smsOptIn === true,
+            consentSource: typeof p.consent?.consentSource === 'string' ? p.consent.consentSource : undefined,
+            consentAt: typeof p.consent?.consentAt === 'string' ? p.consent.consentAt : undefined,
+        },
+        verifiedEmail: typeof p.verifiedEmail === 'string' ? p.verifiedEmail : null,
+        browserFingerprint: typeof p.browserFingerprint === 'string' ? p.browserFingerprint : null,
+    };
+}
+
+/**
+ * Create the per-agent persisted Zustand store. The `partialize` step ensures
+ * only the persisted shape (never any future transient action/UI state) is
+ * written to localStorage.
+ */
+export function createWidgetStore(agentId: string): StoreApi<WidgetStore> {
+    return createStore<WidgetStore>()(
+        persist(
+            (set) => ({
+                ...initialPersisted(),
+                setSessionId: (sessionId) => set({ sessionId }),
+                mergeIdentity: (identity) =>
+                    set((state) => ({
+                        identity: {
+                            ...state.identity,
+                            ...(identity.name !== undefined ? { name: identity.name } : {}),
+                            ...(identity.email !== undefined ? { email: identity.email } : {}),
+                            ...(identity.phone !== undefined ? { phone: identity.phone } : {}),
+                        },
+                    })),
+                setConsent: (consent) => set({ consent: { ...consent } }),
+                setVerifiedEmail: (verifiedEmail) => set({ verifiedEmail }),
+                setBrowserFingerprint: (browserFingerprint) => set({ browserFingerprint }),
+                clearSession: () => set({ sessionId: null }),
+            }),
+            {
+                name: storageKey(agentId),
+                version: PERSIST_VERSION,
+                storage: safeStorage(),
+                migrate,
+                // Persist ONLY the data shape — never the action functions.
+                partialize: (state): PersistedWidgetState => ({
+                    version: PERSIST_VERSION,
+                    sessionId: state.sessionId,
+                    identity: state.identity,
+                    consent: state.consent,
+                    verifiedEmail: state.verifiedEmail,
+                    browserFingerprint: state.browserFingerprint,
+                }),
+            },
+        ),
+    );
+}
diff --git a/src/styles.ts b/src/styles.ts
index d19c802..1e7b7eb 100644
--- a/src/styles.ts
+++ b/src/styles.ts
@@ -530,6 +530,17 @@ export function buildStyles(theme: ResolvedTheme, mode: ChatWidgetMode = 'popove
 }
 .pc-submit:hover { transform: translateY(-1px); }
 .pc-submit:active { transform: scale(.98); }
+.pc-consents { display: flex; flex-direction: column; gap: 9px; margin-top: 2px; }
+.pc-consent { display: flex; align-items: flex-start; gap: 9px; cursor: pointer; }
+.pc-consent input {
+    margin-top: 2px;
+    width: 16px;
+    height: 16px;
+    flex: 0 0 auto;
+    accent-color: var(--sac-primary);
+    cursor: pointer;
+}
+.pc-consent span { font-size: 12px; line-height: 1.4; color: color-mix(in srgb, var(--sac-text) 72%, transparent); }
 
 /* ─────────────────── Starter-prompt chips ─────────────────────────── */
 .prompts { display: flex; flex-wrap: wrap; gap: 8px; margin: 2px 0 2px 35px; }
@@ -608,6 +619,61 @@ export function buildStyles(theme: ResolvedTheme, mode: ChatWidgetMode = 'popove
 .int-row .int-btn { flex: 1; }
 .int-row .int-input + .int-btn { flex: 0 0 auto; }
 .int-error { margin-top: 8px; font-size: 12px; color: #f87171; }
+.int-card { position: relative; }
+.int-close {
+    position: absolute;
+    top: 8px;
+    right: 9px;
+    border: none;
+    background: transparent;
+    color: color-mix(in srgb, var(--sac-text) 55%, transparent);
+    font-size: 18px;
+    line-height: 1;
+    cursor: pointer;
+    padding: 2px 4px;
+    border-radius: 6px;
+    transition: color .2s ease, background .2s ease;
+}
+.int-close:hover { color: var(--sac-text); background: color-mix(in srgb, var(--sac-text) 8%, transparent); }
+
+/* ─────────────── Cross-device "Restore my chats" ──────────────────── */
+.restore-link {
+    border: none;
+    background: none;
+    padding: 0;
+    font: inherit;
+    font-size: 10.5px;
+    letter-spacing: .04em;
+    color: color-mix(in srgb, var(--sac-primary) 80%, var(--sac-text));
+    cursor: pointer;
+    text-decoration: underline;
+    text-underline-offset: 2px;
+}
+.restore-link:hover { color: var(--sac-primary); }
+.restore-list { display: flex; flex-direction: column; gap: 7px; margin-top: 9px; }
+.restore-item {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 10px;
+    text-align: left;
+    border: 1px solid color-mix(in srgb, var(--sac-border) 80%, transparent);
+    background: var(--sac-bg);
+    color: var(--sac-text);
+    border-radius: 10px;
+    padding: 9px 11px;
+    font-family: inherit;
+    font-size: 12.5px;
+    cursor: pointer;
+    transition: border-color .2s ease, background .2s ease, transform .2s ease;
+}
+.restore-item:hover {
+    border-color: color-mix(in srgb, var(--sac-primary) 50%, transparent);
+    background: color-mix(in srgb, var(--sac-primary) 8%, var(--sac-bg));
+    transform: translateY(-1px);
+}
+.restore-preview { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.restore-when { flex: 0 0 auto; font-size: 11px; color: color-mix(in srgb, var(--sac-text) 55%, transparent); }
 
 .hidden { display: none !important; }
 
diff --git a/tsdown.config.ts b/tsdown.config.ts
index 259cf50..8a1c98c 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -45,10 +45,18 @@ export default defineConfig([
         platform: 'browser',
         target: browserTarget,
         globalName: 'SmoothAgentChat',
-        deps: { alwaysBundle: [/@smooai\/smooth-operator/] },
+        // Bundle the protocol client AND zustand into the standalone global — a
+        // plain `<script>` embed has no module resolver, so every runtime dep must
+        // be inlined or it resolves to an undefined global at load.
+        deps: { alwaysBundle: [/@smooai\/smooth-operator/, /^zustand/] },
         alias: {
             '@smooai/smooth-operator': agentClientEntry,
         },
+        // zustand's persist middleware reads `import.meta.env.MODE` for a dev-only
+        // warning. The IIFE format has no `import.meta`; define it explicitly so the
+        // bundle is deterministic (production) and the EMPTY_IMPORT_META warning is
+        // suppressed, rather than relying on rolldown's `{}` fallback.
+        define: { 'import.meta.env': JSON.stringify({ MODE: 'production' }) },
         dts: false,
         sourcemap: true,
         clean: false,

From 80bc9e7250c401be2308bbad7c321b965c002d24 Mon Sep 17 00:00:00 2001
From: Brent Rager <brent@rager.tech>
Date: Sat, 27 Jun 2026 17:47:38 -0400
Subject: [PATCH 2/3] SMOODEV-2129e: reconcile cross-device +
 fingerprint-resume to chat-ws HTTP routes (engine rejects unknown WS verbs)

---
 .changeset/identity-persistence-consent.md |   6 +-
 e2e/identity-persistence-mock.spec.ts      | 103 +++++-
 src/config.ts                              |  11 +-
 src/conversation.test.ts                   | 189 ++++++++---
 src/conversation.ts                        | 352 ++++++++++-----------
 src/element.ts                             |   8 +-
 src/index.ts                               |   1 +
 7 files changed, 424 insertions(+), 246 deletions(-)

diff --git a/.changeset/identity-persistence-consent.md b/.changeset/identity-persistence-consent.md
index cb2a098..d7e94d6 100644
--- a/.changeset/identity-persistence-consent.md
+++ b/.changeset/identity-persistence-consent.md
@@ -10,8 +10,12 @@ Identity, persistence & consent client layer (ADR-048) — same-session resume,
 
 **Same-session resume.** On load, if a session pointer is persisted the widget calls `get_session`; when the session isn't `ended` it reuses the `sessionId`, replays history (`get_conversation_messages`, newest-first → reversed to chronological), skips the pre-chat form, and continues the conversation. An ended/404 session clears **only** the pointer (identity & consent survive) and starts fresh.
 
+**Returning-visitor resume by fingerprint (HTTP).** When there is no persisted pointer, the widget first `POST`s `/internal/resume-by-fingerprint` on the chat-ws wrapper with the browser fingerprint; if the wrapper resolves (and primes) a recent session it returns `{ resumable: true, sessionId, … }` and the widget adopts that session (then `get_session` + `get_conversation_messages` to hydrate) instead of creating a new one. `{ resumable: false }` falls through to a normal create.
+
 **Pre-chat form: phone + marketing consent.** The phone field is now shown by default (optional; rides session `metadata.userPhone`). Two explicit, default-unchecked consent checkboxes (email + SMS) capture marketing opt-in; ticking one stamps a `consentAt` ISO timestamp, and the consent record (`{ emailOptIn, smsOptIn, consentSource: 'chat-widget-prechat', consentAt }`) threads into the session metadata. New config flags: `collectPhone`, `collectConsent`, `allowChatRestore` (all default `true`).
 
-**Cross-device "Restore my chats."** An explicit footer affordance (not a mid-turn agent pause) runs `request_identity_otp` → `verify_identity_otp` → `resolve_identity`, reusing the existing OTP UI. On a resolved list the visitor picks a conversation to replay (`get_session` + `get_conversation_messages`); the verified email is persisted. The new verbs are sent as raw frames over a shared transport so they integrate the moment the server side (SMOODEV-2129d) lands.
+**Cross-device "Restore my chats."** An explicit footer affordance (not a mid-turn agent pause) runs the identity OTP flow over the chat-ws wrapper's HTTP routes — `POST /internal/identity/request-otp` → `verify-otp` → `resolve` — reusing the existing OTP UI. On a resolved list the visitor picks a conversation to replay (`get_session` + `get_conversation_messages`); the verified email is persisted.
+
+**HTTP, not WS frames.** The smooth-operator engine (1.8.0) owns the `/ws` dispatch and rejects unknown verbs, so the cross-device identity flow and fingerprint resume are `fetch()` (POST, JSON) calls to the chat-ws wrapper, with the HTTP base derived from the WS endpoint (`wss://ai.smoo.ai/ws` → `https://ai.smoo.ai`). The browser sends `Origin` automatically (origin-allowlisted server-side) and each request carries `agentId`/`agentName` plus an optional pre-auth `authContext` (`{ userId, signature, timestamp }`) from the new `authContext` config option.
 
 All server-supplied strings (masked destinations, conversation previews, history) are rendered via `textContent`, keeping the 0.6.0 XSS guarantees intact, and the new UI follows the Aurora-Glass styling.
diff --git a/e2e/identity-persistence-mock.spec.ts b/e2e/identity-persistence-mock.spec.ts
index 742a561..226a12f 100644
--- a/e2e/identity-persistence-mock.spec.ts
+++ b/e2e/identity-persistence-mock.spec.ts
@@ -25,12 +25,15 @@ const AGENT_ID = '2590dfd6-7ed5-484b-bfb4-6d83a97d5a8e';
 const ENDPOINT = 'wss://ai.smoo.ai/ws';
 
 /**
- * The mock WebSocket. Its `send` records frames on window.__sent and routes by
- * action through a window.__script(frame, reply) hook the test can swap per case.
+ * The mock WebSocket (records WS frames on window.__sent, routes via
+ * window.__script) PLUS a mocked fetch for the chat-ws `/internal/*` routes
+ * (records calls on window.__http, routes via window.__httpScript(path, body) →
+ * { status?, json }; default = resume:false).
  */
 const MOCK_WS = `
 (() => {
   window.__sent = [];
+  window.__http = [];
   class MockWS {
     constructor(url) {
       this.url = url; this.readyState = 0;
@@ -50,6 +53,15 @@ const MOCK_WS = `
   }
   MockWS.CONNECTING=0; MockWS.OPEN=1; MockWS.CLOSING=2; MockWS.CLOSED=3;
   window.WebSocket = MockWS;
+
+  window.fetch = async (url, init) => {
+    const u = new URL(url, location.href);
+    const body = init && init.body ? JSON.parse(init.body) : {};
+    window.__http.push({ path: u.pathname, body });
+    const route = (window.__httpScript || (() => ({ json: { resumable: false } })));
+    const { status = 200, json = {} } = route(u.pathname, body) || {};
+    return { ok: status >= 200 && status < 300, status, json: async () => json };
+  };
 })();
 `;
 
@@ -278,20 +290,12 @@ test('cross-device restore: request → verify → resolve → replay', async ({
             } catch {
                 /* ignore */
             }
+            // WS verbs: create the live session + serve the replayed history.
             (window as unknown as { __script: unknown }).__script = (f: Record<string, unknown>, reply: (o: unknown) => void) => {
                 switch (f.action) {
                     case 'create_conversation_session':
                         reply({ type: 'immediate_response', requestId: f.requestId, status: 202, data: { sessionId: 'sess-A', conversationId: 'c', agentId: f.agentId } });
                         break;
-                    case 'request_identity_otp':
-                        reply({ type: 'otp_sent', requestId: f.requestId, data: { requestId: f.requestId, data: { channel: 'email', maskedDestination: 'a***@example.com' } } });
-                        break;
-                    case 'verify_identity_otp':
-                        reply({ type: 'otp_verified', requestId: f.requestId, data: { requestId: f.requestId, data: { message: 'ok' } } });
-                        break;
-                    case 'resolve_identity':
-                        reply({ type: 'immediate_response', requestId: f.requestId, status: 200, data: { resolved: true, crmContactId: 'crm', conversations: [{ conversationId: 'conv-9', sessionId: 'sess-9', lastActivityAt: '2026-01-01T00:00:00Z', preview: 'Past chat about pricing' }] } });
-                        break;
                     case 'get_session':
                         reply({ type: 'immediate_response', requestId: f.requestId, status: 200, data: { sessionId: f.sessionId, status: 'active', agentId } });
                         break;
@@ -300,6 +304,21 @@ test('cross-device restore: request → verify → resolve → replay', async ({
                         break;
                 }
             };
+            // HTTP /internal/* routes: the cross-device identity flow.
+            (window as unknown as { __httpScript: unknown }).__httpScript = (path: string, body: Record<string, unknown>) => {
+                switch (path) {
+                    case '/internal/resume-by-fingerprint':
+                        return { json: { resumable: false } };
+                    case '/internal/identity/request-otp':
+                        return { json: { event: 'otp_sent', maskedDestination: 'a***@example.com' } };
+                    case '/internal/identity/verify-otp':
+                        return { json: body.code === '123456' ? { event: 'otp_verified' } : { event: 'otp_invalid', attemptsRemaining: 2 } };
+                    case '/internal/identity/resolve':
+                        return { json: { resolved: true, crmContactId: 'crm', conversations: [{ conversationId: 'conv-9', sessionId: 'sess-9', lastActivityAt: '2026-01-01T00:00:00Z', preview: 'Past chat about pricing' }] } };
+                    default:
+                        return { json: {} };
+                }
+            };
             // @ts-expect-error injected global
             const el = window.SmoothAgentChat.mount({ endpoint, agentId, greeting: '' });
             const root = (el as { shadowRoot: ShadowRoot }).shadowRoot;
@@ -339,3 +358,65 @@ test('cross-device restore: request → verify → resolve → replay', async ({
     expect(result.verifiedEmailPersisted, 'verifiedEmail persisted after verify').toBe('ada@example.com');
     expect(result.replayed).toContain('Replayed pricing chat');
 });
+
+test('fingerprint resume: no persisted pointer → POST /internal/resume-by-fingerprint → adopt + replay', async ({ page }) => {
+    const pageErrors: string[] = [];
+    page.on('pageerror', (e) => pageErrors.push(`${e.name}: ${e.message}`));
+
+    await page.addInitScript(MOCK_WS);
+    await page.goto(`http://127.0.0.1:${process.env.STATIC_PORT ?? 4830}/e2e/fixtures/demo.html`).catch(async () => {
+        await page.goto('about:blank');
+    });
+    await page.addScriptTag({ content: GLOBAL_BUNDLE });
+
+    const result = await page.evaluate(
+        async ({ endpoint, agentId }) => {
+            const s = (ms: number) => new Promise((r) => setTimeout(r, ms));
+            try {
+                localStorage.clear();
+            } catch {
+                /* ignore */
+            }
+            // No persisted pointer. The wrapper resolves a recent session for this
+            // fingerprint and primes the registry; the widget adopts it.
+            (window as unknown as { __httpScript: unknown }).__httpScript = (path: string) => {
+                if (path === '/internal/resume-by-fingerprint') {
+                    return { json: { resumable: true, sessionId: 'sess-FP', conversationId: 'c', agentId } };
+                }
+                return { json: {} };
+            };
+            (window as unknown as { __script: unknown }).__script = (f: Record<string, unknown>, reply: (o: unknown) => void) => {
+                if (f.action === 'get_session') reply({ type: 'immediate_response', requestId: f.requestId, status: 200, data: { sessionId: f.sessionId, status: 'active', agentId } });
+                else if (f.action === 'get_conversation_messages') reply({ type: 'immediate_response', requestId: f.requestId, status: 200, data: { messages: [{ id: 'fp1', direction: 'outbound', content: { text: 'Welcome back' }, createdAt: '2026-01-01T00:00:00Z' }], hasMore: false } });
+                else if (f.action === 'create_conversation_session') reply({ type: 'immediate_response', requestId: f.requestId, status: 202, data: { sessionId: 'sess-SHOULD-NOT-HAPPEN', conversationId: 'c', agentId: f.agentId } });
+            };
+            // @ts-expect-error injected global
+            const el = window.SmoothAgentChat.mount({ endpoint, agentId, greeting: '' });
+            const root = (el as { shadowRoot: ShadowRoot }).shadowRoot;
+            (root.querySelector('.launcher') as HTMLElement | null)?.click();
+            for (let i = 0; i < 80; i++) {
+                const txt = Array.from(root.querySelectorAll('.bubble')).map((b) => b.textContent ?? '').join(' ');
+                if (/Welcome back/.test(txt)) break;
+                await s(25);
+            }
+            const sent = (window as unknown as { __sent: Record<string, unknown>[] }).__sent;
+            const http = (window as unknown as { __http: { path: string; body: Record<string, unknown> }[] }).__http;
+            return {
+                hitFingerprintRoute: http.some((h) => h.path === '/internal/resume-by-fingerprint'),
+                fingerprintSent: http.find((h) => h.path === '/internal/resume-by-fingerprint')?.body.browserFingerprint,
+                createdSession: sent.some((x) => x.action === 'create_conversation_session'),
+                persistedSession: JSON.parse(localStorage.getItem(`smoo-chat-widget:${agentId}`) ?? '{}').state?.sessionId,
+                replayed: Array.from(root.querySelectorAll('.bubble')).map((b) => b.textContent ?? '').join(' '),
+            };
+        },
+        { endpoint: ENDPOINT, agentId: AGENT_ID },
+    );
+
+    expect(pageErrors, pageErrors.join('\n')).toEqual([]);
+    expect(result.hitFingerprintRoute, 'POST /internal/resume-by-fingerprint was called').toBe(true);
+    expect(typeof result.fingerprintSent).toBe('string');
+    // Adopted the resumed session — did NOT create a fresh one.
+    expect(result.createdSession, 'must NOT create a session when fingerprint resumes').toBe(false);
+    expect(result.persistedSession).toBe('sess-FP');
+    expect(result.replayed).toContain('Welcome back');
+});
diff --git a/src/config.ts b/src/config.ts
index eb76d1c..543aebe 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -71,6 +71,13 @@ export interface ChatWidgetConfig {
     userEmail?: string;
     /** Optional phone number for the user participant (passed via session metadata). */
     userPhone?: string;
+    /**
+     * Optional pre-auth HMAC context. When the host page has a shared secret with
+     * the agent, it can sign `{ userId, signature, timestamp }` so the chat-ws
+     * wrapper's `/internal/*` identity routes (and the WS create path) verify the
+     * caller without an OTP round-trip (ADR-046/ADR-048). Passed through verbatim.
+     */
+    authContext?: { userId: string; signature: string; timestamp: number };
     /** Placeholder text for the message input. */
     placeholder?: string;
     /** Greeting rendered when the conversation opens (before any messages). */
@@ -120,11 +127,12 @@ export interface ChatWidgetConfig {
 /** The fully-resolved theme (canonical keys only — aliases are folded in). */
 export type ResolvedTheme = Required<Omit<ChatWidgetTheme, 'chatBubbleInbound' | 'chatBubbleInboundText' | 'chatBubbleOutbound' | 'chatBubbleOutboundText'>>;
 
-export type ResolvedConfig = Required<Omit<ChatWidgetConfig, 'theme' | 'userName' | 'userEmail' | 'userPhone'>> & {
+export type ResolvedConfig = Required<Omit<ChatWidgetConfig, 'theme' | 'userName' | 'userEmail' | 'userPhone' | 'authContext'>> & {
     theme: ResolvedTheme;
     userName?: string;
     userEmail?: string;
     userPhone?: string;
+    authContext?: { userId: string; signature: string; timestamp: number };
 };
 
 /** Resolve a partial config against the built-in defaults. */
@@ -145,6 +153,7 @@ export function resolveConfig(config: ChatWidgetConfig): ResolvedConfig {
         userName: config.userName,
         userEmail: config.userEmail,
         userPhone: config.userPhone,
+        authContext: config.authContext,
         placeholder: config.placeholder ?? 'Type a message…',
         greeting: config.greeting ?? 'Hi! How can I help you today?',
         connectionErrorMessage: config.connectionErrorMessage ?? "We couldn't reach the chat. Please try again in a moment.",
diff --git a/src/conversation.test.ts b/src/conversation.test.ts
index 49307e8..0a736aa 100644
--- a/src/conversation.test.ts
+++ b/src/conversation.test.ts
@@ -1,18 +1,23 @@
 /**
  * ConversationController integration tests (jsdom + a deterministic mock
- * WebSocket). The controller builds its own browser transport over the global
- * `WebSocket`, so we install a scriptable mock that captures outbound frames and
- * replays operator-shaped responses correlated by `requestId`.
+ * WebSocket + a mocked `fetch`).
  *
- * These cover the 0.7.0 identity / persistence / consent contract (ADR-048):
+ * The engine WS verbs (create/send/get_session/get_conversation_messages) are
+ * exercised through a scriptable mock WebSocket. The 0.7.0 cross-device identity
+ * flow + fingerprint resume are HTTP POST routes on the chat-ws wrapper (the
+ * engine `/ws` rejects unknown verbs — ADR-048), so those are exercised through a
+ * mocked `fetch` that routes by `/internal/*` path.
+ *
+ * Coverage:
  *   - createConversationSession carries browserFingerprint + identity + consent
  *     + phone-on-metadata,
  *   - same-session resume hydrates history and reuses the sessionId,
  *   - an ended session clears the pointer and starts fresh,
- *   - the cross-device request → verify → resolve → replay flow.
+ *   - fingerprint resume (POST /internal/resume-by-fingerprint) adopts a session,
+ *   - cross-device request → verify → resolve → replay over the HTTP routes.
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { ConversationController, type ConversationEvents, type IdentityRestore } from './conversation.js';
+import { ConversationController, type ConversationEvents, httpBaseFromWsEndpoint, type IdentityRestore } from './conversation.js';
 import { createWidgetStore } from './persistence.js';
 
 const ENDPOINT = 'wss://example.test/ws';
@@ -87,6 +92,33 @@ function defaultOnFrame(frame: Record<string, unknown>, reply: (obj: unknown) =>
     }
 }
 
+// --- mocked fetch for the chat-ws `/internal/*` routes -----------------------
+
+interface FetchCall {
+    path: string;
+    body: Record<string, unknown>;
+    origin: string;
+}
+const fetchCalls: FetchCall[] = [];
+/** Per-test responder: path → JSON body (+ optional status). Default = resume:false. */
+let fetchRouter: (path: string, body: Record<string, unknown>) => { status?: number; json: Record<string, unknown> } = () => ({ json: { resumable: false } });
+
+function installMockFetch(): void {
+    fetchCalls.length = 0;
+    fetchRouter = () => ({ json: { resumable: false } });
+    (globalThis as unknown as { fetch: unknown }).fetch = async (url: string, init?: { body?: string }) => {
+        const u = new URL(url);
+        const body = init?.body ? (JSON.parse(init.body) as Record<string, unknown>) : {};
+        fetchCalls.push({ path: u.pathname, body, origin: u.origin });
+        const { status = 200, json } = fetchRouter(u.pathname, body);
+        return {
+            ok: status >= 200 && status < 300,
+            status,
+            json: async () => json,
+        };
+    };
+}
+
 function makeController(events: Partial<ConversationEvents> = {}, config: Record<string, unknown> = {}) {
     const store = createWidgetStore(AGENT);
     const onMessages = vi.fn();
@@ -107,6 +139,7 @@ describe('ConversationController — session creation (ADR-048 §a)', () => {
     beforeEach(() => {
         localStorage.clear();
         installMockWs();
+        installMockFetch();
         MockSocket.onFrame = defaultOnFrame;
     });
     afterEach(() => localStorage.clear());
@@ -170,6 +203,7 @@ describe('ConversationController — same-session resume (ADR-048 §b)', () => {
     beforeEach(() => {
         localStorage.clear();
         installMockWs();
+        installMockFetch();
     });
     afterEach(() => localStorage.clear());
 
@@ -267,37 +301,85 @@ describe('ConversationController — same-session resume (ADR-048 §b)', () => {
     });
 });
 
-describe('ConversationController — cross-device restore (ADR-048 §c)', () => {
+describe('httpBaseFromWsEndpoint', () => {
+    it('derives the HTTP base from a wss /ws endpoint', () => {
+        expect(httpBaseFromWsEndpoint('wss://ai.smoo.ai/ws')).toBe('https://ai.smoo.ai');
+        expect(httpBaseFromWsEndpoint('ws://localhost:8787/ws')).toBe('http://localhost:8787');
+        expect(httpBaseFromWsEndpoint('wss://ai.smoo.ai:9000/ws')).toBe('https://ai.smoo.ai:9000');
+    });
+});
+
+describe('ConversationController — fingerprint resume (ADR-048 §b, HTTP)', () => {
     beforeEach(() => {
         localStorage.clear();
         installMockWs();
+        installMockFetch();
+        MockSocket.onFrame = defaultOnFrame;
     });
     afterEach(() => localStorage.clear());
 
-    it('runs request → verify → resolve → replay and persists verifiedEmail', async () => {
+    it('POSTs /internal/resume-by-fingerprint FIRST when there is no persisted pointer, then adopts the session', async () => {
+        // Wrapper resolves a recent session for this fingerprint and primes the registry.
+        fetchRouter = (path) => {
+            if (path === '/internal/resume-by-fingerprint') {
+                return { json: { resumable: true, sessionId: 'sess-FP', conversationId: 'c', agentId: AGENT } };
+            }
+            return { json: {} };
+        };
+        MockSocket.onFrame = (frame, reply) => {
+            const requestId = frame.requestId;
+            if (frame.action === 'get_session') {
+                reply({ type: 'immediate_response', requestId, status: 200, data: { sessionId: frame.sessionId, status: 'active', agentId: AGENT } });
+            } else if (frame.action === 'get_conversation_messages') {
+                reply({ type: 'immediate_response', requestId, status: 200, data: { messages: [{ id: 'fp1', direction: 'outbound', content: { text: 'Welcome back' }, createdAt: '2026-01-01T00:00:00Z' }], hasMore: false } });
+            } else {
+                defaultOnFrame(frame, reply);
+            }
+        };
+
+        const { controller, store, onMessages } = makeController();
+        await controller.connect();
+
+        // The fingerprint resume route was hit with the persisted fingerprint + agentId.
+        const fpCall = fetchCalls.find((c) => c.path === '/internal/resume-by-fingerprint');
+        expect(fpCall).toBeTruthy();
+        expect(fpCall?.body.browserFingerprint).toBe(store.getState().browserFingerprint);
+        expect(fpCall?.body.agentId).toBe(AGENT);
+
+        // Adopted the session via get_session/get_messages — NOT createConversationSession.
+        expect(MockSocket.sentFrames.find((f) => f.action === 'create_conversation_session')).toBeUndefined();
+        expect(store.getState().sessionId).toBe('sess-FP');
+        const snap = onMessages.mock.calls.at(-1)?.[0] as Array<{ text: string }>;
+        expect(snap.some((m) => m.text === 'Welcome back')).toBe(true);
+    });
+
+    it('falls through to createConversationSession when the fingerprint is not resumable', async () => {
+        fetchRouter = () => ({ json: { resumable: false } });
+        const { controller, store } = makeController();
+        await controller.connect();
+        expect(fetchCalls.some((c) => c.path === '/internal/resume-by-fingerprint')).toBe(true);
+        expect(MockSocket.sentFrames.find((f) => f.action === 'create_conversation_session')).toBeTruthy();
+        expect(store.getState().sessionId).toBe('sess-new');
+    });
+});
+
+describe('ConversationController — cross-device restore (ADR-048 §c, HTTP)', () => {
+    beforeEach(() => {
+        localStorage.clear();
+        installMockWs();
+        installMockFetch();
+    });
+    afterEach(() => localStorage.clear());
+
+    it('runs request → verify → resolve → replay over the HTTP routes and persists verifiedEmail', async () => {
         const restoreStates: IdentityRestore[] = [];
+        // A live session must exist before the cross-device affordance — create one.
         MockSocket.onFrame = (frame, reply) => {
             const requestId = frame.requestId;
             switch (frame.action) {
                 case 'create_conversation_session':
                     reply({ type: 'immediate_response', requestId, status: 202, data: { sessionId: 'sess-new', conversationId: 'c', agentId: AGENT } });
                     break;
-                case 'request_identity_otp':
-                    expect(frame.email).toBe('ada@example.com');
-                    reply({ type: 'otp_sent', requestId, data: { requestId, data: { channel: 'email', maskedDestination: 'a***@example.com' } } });
-                    break;
-                case 'verify_identity_otp':
-                    expect(frame.code).toBe('123456');
-                    reply({ type: 'otp_verified', requestId, data: { requestId, data: { message: 'ok' } } });
-                    break;
-                case 'resolve_identity':
-                    reply({
-                        type: 'immediate_response',
-                        requestId,
-                        status: 200,
-                        data: { resolved: true, crmContactId: 'crm-1', conversations: [{ conversationId: 'conv-9', sessionId: 'sess-9', lastActivityAt: '2026-01-01T00:00:00Z', preview: 'Past chat' }] },
-                    });
-                    break;
                 case 'get_session':
                     reply({ type: 'immediate_response', requestId, status: 200, data: { sessionId: frame.sessionId, status: 'active', agentId: AGENT } });
                     break;
@@ -308,15 +390,33 @@ describe('ConversationController — cross-device restore (ADR-048 §c)', () =>
                     break;
             }
         };
+        fetchRouter = (path, body) => {
+            switch (path) {
+                case '/internal/resume-by-fingerprint':
+                    return { json: { resumable: false } };
+                case '/internal/identity/request-otp':
+                    expect(body.email).toBe('ada@example.com');
+                    expect(body.agentId).toBe(AGENT);
+                    return { json: { event: 'otp_sent', maskedDestination: 'a***@example.com' } };
+                case '/internal/identity/verify-otp':
+                    expect(body.sessionId).toBe('sess-new');
+                    expect(body.code).toBe('123456');
+                    return { json: { event: 'otp_verified' } };
+                case '/internal/identity/resolve':
+                    expect(body.sessionId).toBe('sess-new');
+                    return { json: { resolved: true, crmContactId: 'crm-1', conversations: [{ conversationId: 'conv-9', sessionId: 'sess-9', lastActivityAt: '2026-01-01T00:00:00Z', preview: 'Past chat' }] } };
+                default:
+                    return { json: {} };
+            }
+        };
 
         const { controller, store, onMessages } = makeController({ onIdentityRestore: (s) => restoreStates.push(s) });
         await controller.connect();
 
-        controller.requestIdentityOtp('ada@example.com', 'email');
-        await tick();
+        await controller.requestIdentityOtp('ada@example.com', 'email');
         expect(restoreStates.at(-1)?.phase).toBe('awaiting_code');
 
-        controller.verifyIdentityOtp('123456');
+        await controller.verifyIdentityOtp('123456');
         await tick();
         // verifiedEmail persisted on success.
         expect(store.getState().verifiedEmail).toBe('ada@example.com');
@@ -334,24 +434,37 @@ describe('ConversationController — cross-device restore (ADR-048 §c)', () =>
 
     it('surfaces otp_invalid with attemptsRemaining and stays on the code step', async () => {
         const restoreStates: IdentityRestore[] = [];
-        MockSocket.onFrame = (frame, reply) => {
-            const requestId = frame.requestId;
-            if (frame.action === 'create_conversation_session') {
-                reply({ type: 'immediate_response', requestId, status: 202, data: { sessionId: 'sess-new', conversationId: 'c', agentId: AGENT } });
-            } else if (frame.action === 'request_identity_otp') {
-                reply({ type: 'otp_sent', requestId, data: { requestId, data: { channel: 'email', maskedDestination: 'a***@x.com' } } });
-            } else if (frame.action === 'verify_identity_otp') {
-                reply({ type: 'otp_invalid', requestId, data: { requestId, data: { error: 'INVALID_CODE', attemptsRemaining: 2, message: 'nope' } } });
+        MockSocket.onFrame = defaultOnFrame;
+        fetchRouter = (path) => {
+            switch (path) {
+                case '/internal/resume-by-fingerprint':
+                    return { json: { resumable: false } };
+                case '/internal/identity/request-otp':
+                    return { json: { event: 'otp_sent', maskedDestination: 'a***@x.com' } };
+                case '/internal/identity/verify-otp':
+                    return { json: { event: 'otp_invalid', attemptsRemaining: 2 } };
+                default:
+                    return { json: {} };
             }
         };
         const { controller } = makeController({ onIdentityRestore: (s) => restoreStates.push(s) });
         await controller.connect();
-        controller.requestIdentityOtp('ada@example.com');
-        await tick();
-        controller.verifyIdentityOtp('000000');
+        await controller.requestIdentityOtp('ada@example.com');
+        await controller.verifyIdentityOtp('000000');
         await tick();
         const last = restoreStates.at(-1);
         expect(last?.phase).toBe('awaiting_code');
         expect(last?.phase === 'awaiting_code' ? last.attemptsRemaining : null).toBe(2);
     });
+
+    it('passes authContext through to the identity routes when configured', async () => {
+        MockSocket.onFrame = defaultOnFrame;
+        fetchRouter = () => ({ json: { resumable: false } });
+        const ac = { userId: 'u1', signature: 'sig', timestamp: 123 };
+        const { controller } = makeController({}, { authContext: ac });
+        await controller.connect();
+        await controller.requestIdentityOtp('ada@example.com');
+        const otpCall = fetchCalls.find((c) => c.path === '/internal/identity/request-otp');
+        expect(otpCall?.body.authContext).toEqual(ac);
+    });
 });
diff --git a/src/conversation.ts b/src/conversation.ts
index f7d8f6f..4131f66 100644
--- a/src/conversation.ts
+++ b/src/conversation.ts
@@ -18,101 +18,37 @@
  *   - `browserFingerprint` computed once + sent on every `create_conversation_session`.
  *   - identity + marketing consent threaded into the session `metadata`.
  *   - same-session RESUME on load (no engine change — `get_session` + `get_messages`).
- *   - cross-device "restore my chats" (`request_identity_otp` / `verify_identity_otp`
- *     / `resolve_identity`) sent as raw frames over a shared transport.
+ *   - returning-visitor RESUME via `POST /internal/resume-by-fingerprint`, and
+ *     cross-device "restore my chats" via the `POST /internal/identity/{request-otp,
+ *     verify-otp,resolve}` routes on the chat-ws wrapper. The engine (smooth-operator
+ *     1.8.0) owns the `/ws` dispatch and REJECTS unknown verbs, so these are HTTP
+ *     `fetch()` calls (origin-allowlisted + optional authContext, per ADR-046/048) —
+ *     NOT WS frames.
  *
  * The controller is UI-agnostic: it emits typed events and the view renders them.
  */
-import { type Citation, ProtocolError, type ServerEvent, SmoothAgentClient, type Transport, type TransportState } from '@smooai/smooth-operator';
+import { type Citation, ProtocolError, type ServerEvent, SmoothAgentClient } from '@smooai/smooth-operator';
 import type { StoreApi } from 'zustand/vanilla';
 import type { ChatWidgetConfig } from './config.js';
 import { getOrCreateFingerprint } from './fingerprint.js';
 import { type ConsentState, createWidgetStore, type WidgetStore } from './persistence.js';
 
 /**
- * A tiny browser `WebSocket` transport implementing the engine's {@link Transport}
- * contract. We inject our own (rather than letting the client build its default)
- * for two reasons: (1) it keeps a reference to `send()` so we can emit the custom
- * cross-device frames the engine client doesn't model, and (2) it sidesteps a
- * bundling quirk — the IIFE build aliases `@smooai/smooth-operator` to its
- * `client.js`, which imports but does not RE-export `WebSocketTransport`, so the
- * package's own transport isn't reachable from the global bundle. This class is a
- * faithful, minimal equivalent of `WebSocketTransport` over the global socket.
+ * Derive the HTTP base for the chat-ws wrapper's `/internal/*` REST routes from
+ * the WS endpoint:  `wss://ai.smoo.ai/ws` → `https://ai.smoo.ai`. The engine
+ * (smooth-operator 1.8.0) owns the `/ws` dispatch and REJECTS unknown verbs, so
+ * the cross-device identity flow + fingerprint resume are HTTP POST routes on the
+ * wrapper (origin-allowlisted + authContext, per ADR-046/ADR-048) — NOT WS frames.
  */
-class BrowserWebSocketTransport implements Transport {
-    private socket: WebSocket | null = null;
-    private readonly messageHandlers = new Set<(data: string) => void>();
-    private readonly closeHandlers = new Set<(info: { code?: number; reason?: string }) => void>();
-    private readonly errorHandlers = new Set<(err: unknown) => void>();
-
-    constructor(private readonly url: string) {}
-
-    get state(): TransportState {
-        const s = this.socket;
-        if (!s) return 'closed';
-        switch (s.readyState) {
-            case WebSocket.CONNECTING:
-                return 'connecting';
-            case WebSocket.OPEN:
-                return 'open';
-            case WebSocket.CLOSING:
-                return 'closing';
-            default:
-                return 'closed';
-        }
-    }
-
-    connect(): Promise<void> {
-        return new Promise((resolve, reject) => {
-            try {
-                const socket = new WebSocket(this.url);
-                this.socket = socket;
-                socket.addEventListener('open', () => resolve());
-                socket.addEventListener('error', (ev) => {
-                    for (const h of this.errorHandlers) h(ev);
-                    if (socket.readyState !== WebSocket.OPEN) reject(new Error('WebSocket connection failed'));
-                });
-                socket.addEventListener('message', (ev: MessageEvent) => {
-                    const data = typeof ev.data === 'string' ? ev.data : String(ev.data);
-                    for (const h of this.messageHandlers) h(data);
-                });
-                socket.addEventListener('close', (ev: CloseEvent) => {
-                    for (const h of this.closeHandlers) h({ code: ev.code, reason: ev.reason });
-                });
-            } catch (err) {
-                reject(err instanceof Error ? err : new Error(String(err)));
-            }
-        });
-    }
-
-    send(data: string): void {
-        if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
-            throw new Error('Transport is not open');
-        }
-        this.socket.send(data);
-    }
-
-    close(code?: number, reason?: string): void {
-        try {
-            this.socket?.close(code, reason);
-        } catch {
-            /* closing an already-closed socket is non-fatal */
-        }
-    }
-
-    onMessage(handler: (data: string) => void): () => void {
-        this.messageHandlers.add(handler);
-        return () => this.messageHandlers.delete(handler);
-    }
-
-    onClose(handler: (info: { code?: number; reason?: string }) => void): () => void {
-        this.closeHandlers.add(handler);
-        return () => this.closeHandlers.delete(handler);
-    }
-
-    onError(handler: (err: unknown) => void): () => void {
-        this.errorHandlers.add(handler);
-        return () => this.errorHandlers.delete(handler);
+export function httpBaseFromWsEndpoint(endpoint: string): string {
+    try {
+        const u = new URL(endpoint);
+        u.protocol = u.protocol === 'ws:' ? 'http:' : u.protocol === 'wss:' ? 'https:' : u.protocol;
+        // The REST routes live at the host root (`/internal/*`), not under `/ws`.
+        return `${u.protocol}//${u.host}`;
+    } catch {
+        // Best-effort string fallback for a non-absolute endpoint.
+        return endpoint.replace(/^wss:/, 'https:').replace(/^ws:/, 'http:').replace(/\/ws\/?$/, '');
     }
 }
 
@@ -177,13 +113,14 @@ export interface RestorableConversation {
 }
 
 /**
- * State machine for the cross-device "restore my chats" flow. Mirrors the
- * `request_identity_otp` → `verify_identity_otp` → `resolve_identity` verbs
- * (ADR-048 §c). The view renders a panel off this.
+ * State machine for the cross-device "restore my chats" flow. Driven by the three
+ * HTTP POST routes on the chat-ws wrapper — `/internal/identity/request-otp` →
+ * `/internal/identity/verify-otp` → `/internal/identity/resolve` (ADR-048 §c).
+ * The view renders a panel off this.
  */
 export type IdentityRestore =
     | { phase: 'idle' }
-    /** UI-local: the email-entry step before any frame is sent. */
+    /** UI-local: the email-entry step before any request is sent. */
     | { phase: 'awaiting_email'; error?: string }
     | { phase: 'requesting'; email: string; channel: 'email' | 'sms' }
     | { phase: 'awaiting_code'; email: string; channel: 'email' | 'sms'; maskedDestination?: string; error?: string; attemptsRemaining?: number }
@@ -262,8 +199,6 @@ export class ConversationController {
     private readonly events: ConversationEvents;
     private readonly store: StoreApi<WidgetStore>;
     private client: SmoothAgentClient | null = null;
-    /** Shared transport — kept so we can send the custom cross-device frames. */
-    private transport: BrowserWebSocketTransport | null = null;
     private sessionId: string | null = null;
     private readonly messages: ChatMessage[] = [];
     private status: ConnectionStatus = 'idle';
@@ -272,13 +207,13 @@ export class ConversationController {
     private activeRequestId: string | null = null;
     private interrupt: Interrupt | null = null;
     private identityRestore: IdentityRestore = { phase: 'idle' };
-    /** Pending cross-device verb resolvers, keyed by the requestId we minted. */
-    private readonly identityWaiters = new Map<string, (event: ServerEvent) => void>();
-    private unsubscribeEvents: (() => void) | null = null;
+    /** HTTP base for the chat-ws wrapper's `/internal/*` REST routes. */
+    private readonly httpBase: string;
 
     constructor(config: ChatWidgetConfig, events: ConversationEvents, store?: StoreApi<WidgetStore>) {
         this.config = config;
         this.events = events;
+        this.httpBase = httpBaseFromWsEndpoint(config.endpoint);
         this.store = store ?? createWidgetStore(config.agentId);
         // Seed identity from config into the persisted store (config wins on first
         // load; the persisted values survive across reloads thereafter).
@@ -397,23 +332,24 @@ export class ConversationController {
         return Object.keys(meta).length > 0 ? meta : undefined;
     }
 
-    /** Lazily open the shared transport + client. Idempotent within a connect. */
+    /** Lazily open the WS client (default transport). Idempotent within a connect. */
     private async ensureClient(): Promise<void> {
         if (this.client) return;
-        this.transport = new BrowserWebSocketTransport(this.config.endpoint);
-        this.client = new SmoothAgentClient({ url: this.config.endpoint, transport: this.transport });
-        // Route custom cross-device frames (and any unsolicited event) here.
-        this.unsubscribeEvents = this.client.onEvent((event) => this.handleUnsolicited(event));
+        this.client = new SmoothAgentClient({ url: this.config.endpoint });
         await this.client.connect();
     }
 
     /**
-     * Open the transport and either RESUME a persisted session or create a new one.
+     * Open the connection and either RESUME or create a session.
      *
-     * Resume (ADR-048 §b): if a persisted `sessionId` exists → `get_session`; when
-     * its `status !== 'ended'` we reuse it and hydrate the transcript from
-     * `get_messages` (newest-first page, reversed to chronological). On `ended`/404
-     * we clear ONLY the session pointer (identity/consent survive) and create fresh.
+     * 1. Persisted pointer (ADR-048 §b): `get_session` → if not `ended`, reuse +
+     *    hydrate from `get_messages` (newest-first, reversed). On ended/404 clear
+     *    ONLY the pointer (identity/consent survive).
+     * 2. No persisted pointer: POST `/internal/resume-by-fingerprint` FIRST; if
+     *    `resumable`, adopt the returned session (the wrapper has primed the
+     *    operator registry), reuse the sessionId, and hydrate via get_session/
+     *    get_messages — rather than relying on createConversationSession to resume.
+     * 3. Otherwise create a fresh session.
      */
     async connect(): Promise<void> {
         if (this.status === 'connecting' || this.status === 'ready') return;
@@ -429,6 +365,18 @@ export class ConversationController {
                 }
                 // Resume failed (ended/404/gone) — clear the pointer, keep identity.
                 this.store.getState().clearSession();
+            } else {
+                // Returning anonymous visitor with no stored pointer: ask the
+                // wrapper to resolve a recent session for this fingerprint.
+                const fpSessionId = await this.resumeByFingerprint();
+                if (fpSessionId) {
+                    const resumed = await this.tryResume(fpSessionId);
+                    if (resumed) {
+                        this.store.getState().setSessionId(fpSessionId);
+                        this.setStatus('ready');
+                        return;
+                    }
+                }
             }
             await this.createSession();
             this.setStatus('ready');
@@ -438,6 +386,61 @@ export class ConversationController {
         }
     }
 
+    // ─────────────────────── chat-ws `/internal/*` HTTP ─────────────────────────
+
+    /**
+     * Build the auth fields every `/internal/*` route shares: `agentId` (required
+     * for the agent-policy lookup), `agentName` (used as the OTP email sender), and
+     * the optional pre-auth `authContext` the host page may have configured. The
+     * `Origin` header is sent automatically by the browser and checked server-side.
+     */
+    private authBody(): Record<string, unknown> {
+        const body: Record<string, unknown> = { agentId: this.config.agentId };
+        if (this.config.agentName) body.agentName = this.config.agentName;
+        if (this.config.authContext) body.authContext = this.config.authContext;
+        return body;
+    }
+
+    /** POST JSON to a `/internal/*` route; returns the parsed body (or throws). */
+    private async postInternal(path: string, payload: Record<string, unknown>): Promise<Record<string, unknown>> {
+        const res = await fetch(`${this.httpBase}${path}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            // Identity/origin checks are cookie- and Origin-based; send credentials
+            // so any session cookie the host set rides along.
+            credentials: 'include',
+            body: JSON.stringify({ ...this.authBody(), ...payload }),
+        });
+        let json: Record<string, unknown> = {};
+        try {
+            json = (await res.json()) as Record<string, unknown>;
+        } catch {
+            json = {};
+        }
+        if (!res.ok) {
+            const err = json.error as { code?: string; message?: string } | undefined;
+            throw new Error(err?.message ?? `${path} failed (${res.status})`);
+        }
+        return json;
+    }
+
+    /**
+     * POST `/internal/resume-by-fingerprint`. Returns the resumable sessionId when
+     * the wrapper found (and primed) a recent session for this fingerprint, else
+     * null. Network/route failures are swallowed → null (fall through to create).
+     */
+    private async resumeByFingerprint(): Promise<string | null> {
+        try {
+            const json = await this.postInternal('/internal/resume-by-fingerprint', { browserFingerprint: this.fingerprint() });
+            if (json.resumable === true && typeof json.sessionId === 'string') {
+                return json.sessionId;
+            }
+        } catch {
+            // Resume is best-effort; any failure just means a fresh session.
+        }
+        return null;
+    }
+
     /** `create_conversation_session` with fingerprint + identity + consent metadata. */
     private async createSession(): Promise<void> {
         if (!this.client) throw new Error('Conversation is not connected');
@@ -606,89 +609,72 @@ export class ConversationController {
     }
 
     // ─────────────────── Cross-device "restore my chats" (§c) ───────────────────
+    //
+    // Three HTTP POST routes on the chat-ws wrapper (the engine `/ws` dispatch
+    // rejects unknown verbs): request-otp → verify-otp → resolve. verify-otp and
+    // resolve are session-scoped — they require a live `sessionId` (a uuid), which
+    // is guaranteed because the widget connects (creating/resuming a session)
+    // before exposing the restore affordance.
 
     /**
-     * Send a raw frame over the shared transport for a custom verb the engine
-     * client doesn't model (`request_identity_otp` etc.), then route the matching
-     * response back via {@link handleUnsolicited}. Returns the minted requestId.
-     */
-    private sendIdentityFrame(action: string, payload: Record<string, unknown>, onReply: (event: ServerEvent) => void): string {
-        const requestId = this.nextId('idreq');
-        this.identityWaiters.set(requestId, onReply);
-        this.transport?.send(JSON.stringify({ action, requestId, ...payload }));
-        return requestId;
-    }
-
-    /** Read a field from either the flat event or its nested `data` / `data.data`. */
-    private static readField(event: ServerEvent, key: string): unknown {
-        const top = (event as unknown as Record<string, unknown>)[key];
-        if (top !== undefined) return top;
-        const data = (event as { data?: { data?: Record<string, unknown>; [k: string]: unknown } }).data;
-        if (data) {
-            if (data[key] !== undefined) return data[key];
-            if (data.data && data.data[key] !== undefined) return data.data[key];
-        }
-        return undefined;
-    }
-
-    /**
-     * Begin the cross-device restore: request an OTP to `email` over `channel`.
-     * The view should already have collected the email via an explicit affordance.
+     * Begin the cross-device restore: POST `/internal/identity/request-otp` for
+     * `email` over `channel`. The view collects the email via an explicit affordance.
      */
-    requestIdentityOtp(email: string, channel: 'email' | 'sms' = 'email'): void {
+    async requestIdentityOtp(email: string, channel: 'email' | 'sms' = 'email'): Promise<void> {
         const trimmed = email.trim();
-        if (!trimmed || !this.transport) return;
+        if (!trimmed) return;
         this.setIdentityRestore({ phase: 'requesting', email: trimmed, channel });
-        this.sendIdentityFrame('request_identity_otp', { sessionId: this.sessionId ?? null, email: trimmed, channel }, (event) => {
-            if (event.type === 'otp_sent') {
-                const masked = ConversationController.readField(event, 'maskedDestination');
-                this.setIdentityRestore({ phase: 'awaiting_code', email: trimmed, channel, maskedDestination: typeof masked === 'string' ? masked : undefined });
-            } else if (event.type === 'error') {
-                const msg = ConversationController.readField(event, 'message');
-                this.setIdentityRestore({ phase: 'error', message: typeof msg === 'string' ? msg : 'Could not send a verification code.' });
-            }
-        });
+        try {
+            const json = await this.postInternal('/internal/identity/request-otp', {
+                ...(this.sessionId ? { sessionId: this.sessionId } : {}),
+                email: trimmed,
+                channel,
+            });
+            const masked = typeof json.maskedDestination === 'string' ? json.maskedDestination : undefined;
+            this.setIdentityRestore({ phase: 'awaiting_code', email: trimmed, channel, maskedDestination: masked });
+        } catch (err) {
+            this.setIdentityRestore({ phase: 'error', message: err instanceof Error ? err.message : 'Could not send a verification code.' });
+        }
     }
 
-    /** Submit the code for the cross-device restore. */
-    verifyIdentityOtp(code: string): void {
+    /** Submit the code: POST `/internal/identity/verify-otp`, then resolve on success. */
+    async verifyIdentityOtp(code: string): Promise<void> {
         const state = this.identityRestore;
         const trimmed = code.trim();
-        if (!trimmed || !this.transport) return;
-        if (state.phase !== 'awaiting_code') return;
+        if (!trimmed || state.phase !== 'awaiting_code') return;
         const { email, channel } = state;
+        if (!this.sessionId) {
+            this.setIdentityRestore({ phase: 'error', message: 'No active session to verify against.' });
+            return;
+        }
         this.setIdentityRestore({ phase: 'verifying', email, channel });
-        this.sendIdentityFrame('verify_identity_otp', { sessionId: this.sessionId ?? null, email, code: trimmed }, (event) => {
-            if (event.type === 'otp_verified') {
+        try {
+            const json = await this.postInternal('/internal/identity/verify-otp', { sessionId: this.sessionId, email, code: trimmed });
+            if (json.event === 'otp_verified') {
                 this.store.getState().setVerifiedEmail(email);
-                this.resolveIdentity(email);
-            } else if (event.type === 'otp_invalid') {
-                const remaining = ConversationController.readField(event, 'attemptsRemaining');
-                this.setIdentityRestore({
-                    phase: 'awaiting_code',
-                    email,
-                    channel,
-                    error: 'That code was incorrect.',
-                    attemptsRemaining: typeof remaining === 'number' ? remaining : undefined,
-                });
-            } else if (event.type === 'error') {
-                const msg = ConversationController.readField(event, 'message');
-                this.setIdentityRestore({ phase: 'error', message: typeof msg === 'string' ? msg : 'Verification failed.' });
+                await this.resolveIdentity(email);
+            } else if (json.event === 'otp_invalid') {
+                const remaining = typeof json.attemptsRemaining === 'number' ? json.attemptsRemaining : undefined;
+                this.setIdentityRestore({ phase: 'awaiting_code', email, channel, error: 'That code was incorrect.', attemptsRemaining: remaining });
+            } else {
+                this.setIdentityRestore({ phase: 'error', message: 'Verification failed.' });
             }
-        });
+        } catch (err) {
+            this.setIdentityRestore({ phase: 'error', message: err instanceof Error ? err.message : 'Verification failed.' });
+        }
     }
 
-    /** Resolve the verified identity → list of restorable conversations. */
-    private resolveIdentity(email: string): void {
-        if (!this.transport) return;
+    /** Resolve the verified identity → restorable conversations via POST `/internal/identity/resolve`. */
+    private async resolveIdentity(email: string): Promise<void> {
+        if (!this.sessionId) return;
         this.setIdentityRestore({ phase: 'resolving', email });
-        this.sendIdentityFrame('resolve_identity', { sessionId: this.sessionId ?? null, email }, (event) => {
-            const resolved = ConversationController.readField(event, 'resolved');
-            if (resolved === false) {
+        try {
+            const json = await this.postInternal('/internal/identity/resolve', { sessionId: this.sessionId, email });
+            if (json.resolved !== true) {
                 this.setIdentityRestore({ phase: 'resolved', email, conversations: [] });
                 return;
             }
-            const raw = ConversationController.readField(event, 'conversations');
+            const raw = json.conversations;
             const conversations: RestorableConversation[] = Array.isArray(raw)
                 ? raw
                       .map((c): RestorableConversation | null => {
@@ -707,13 +693,15 @@ export class ConversationController {
                       .filter((c): c is RestorableConversation => c !== null)
                 : [];
             this.setIdentityRestore({ phase: 'resolved', email, conversations });
-        });
+        } catch (err) {
+            this.setIdentityRestore({ phase: 'error', message: err instanceof Error ? err.message : 'Could not load your chats.' });
+        }
     }
 
     /**
      * Replay a chosen restorable conversation: point the live session at its
-     * sessionId, hydrate its transcript, and persist the new pointer so the next
-     * `sendMessage` continues it.
+     * sessionId, hydrate its transcript (get_session + get_messages), and persist
+     * the new pointer so the next `sendMessage` continues it.
      */
     async restoreConversation(sessionId: string): Promise<void> {
         if (!this.client) await this.ensureClient();
@@ -732,32 +720,10 @@ export class ConversationController {
         this.setIdentityRestore({ phase: 'idle' });
     }
 
-    /**
-     * Route an unsolicited / custom-verb frame to its waiting handler. The engine
-     * client surfaces every frame it can't correlate to a pending request or turn
-     * here; we match by the echoed `requestId` of our identity frames.
-     */
-    private handleUnsolicited(event: ServerEvent): void {
-        const requestId = (event as { requestId?: string }).requestId ?? (event as { data?: { requestId?: string } }).data?.requestId;
-        if (typeof requestId === 'string' && this.identityWaiters.has(requestId)) {
-            const handler = this.identityWaiters.get(requestId);
-            // otp_invalid / otp_sent keep the flow alive (retry / interim ack);
-            // other terminals end it, so drop the waiter.
-            if (event.type !== 'otp_invalid' && event.type !== 'otp_sent') {
-                this.identityWaiters.delete(requestId);
-            }
-            handler?.(event);
-        }
-    }
-
     /** Tear down the underlying client. */
     disconnect(): void {
-        this.unsubscribeEvents?.();
-        this.unsubscribeEvents = null;
-        this.identityWaiters.clear();
         this.client?.disconnect('widget closed');
         this.client = null;
-        this.transport = null;
         this.sessionId = null;
         this.activeRequestId = null;
         this.setInterrupt(null);
diff --git a/src/element.ts b/src/element.ts
index 4130d13..7809f45 100644
--- a/src/element.ts
+++ b/src/element.ts
@@ -172,6 +172,7 @@ export class SmoothAgentChatElement extends HTMLElement {
             userName: this.overrides.userName,
             userEmail: this.overrides.userEmail,
             userPhone: this.overrides.userPhone,
+            authContext: this.overrides.authContext,
             placeholder: this.overrides.placeholder ?? this.getAttribute('placeholder') ?? undefined,
             greeting: this.overrides.greeting ?? this.getAttribute('greeting') ?? undefined,
             connectionErrorMessage: this.overrides.connectionErrorMessage,
@@ -180,6 +181,9 @@ export class SmoothAgentChatElement extends HTMLElement {
             requireName: this.overrides.requireName,
             requireEmail: this.overrides.requireEmail,
             requirePhone: this.overrides.requirePhone,
+            collectPhone: this.overrides.collectPhone,
+            collectConsent: this.overrides.collectConsent,
+            allowChatRestore: this.overrides.allowChatRestore,
             allowAnonymous: this.overrides.allowAnonymous,
             theme,
         };
@@ -519,7 +523,7 @@ export class SmoothAgentChatElement extends HTMLElement {
             input.placeholder = 'you@example.com';
             const go = () => {
                 const email = input.value.trim();
-                if (email) this.controller?.requestIdentityOtp(email, 'email');
+                if (email) void this.controller?.requestIdentityOtp(email, 'email');
             };
             input.addEventListener('keydown', (ev) => {
                 if (ev.key === 'Enter') {
@@ -563,7 +567,7 @@ export class SmoothAgentChatElement extends HTMLElement {
             input.placeholder = 'Enter code';
             const submit = () => {
                 const code = input.value.trim();
-                if (code) this.controller?.verifyIdentityOtp(code);
+                if (code) void this.controller?.verifyIdentityOtp(code);
             };
             input.addEventListener('keydown', (ev) => {
                 if (ev.key === 'Enter') {
diff --git a/src/index.ts b/src/index.ts
index 7841454..4cbe437 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -33,6 +33,7 @@ export type { ChatWidgetConfig, ChatWidgetMode, ChatWidgetTheme } from './config
 export { initChatWidgetLoader } from './loader-core.js';
 export {
     ConversationController,
+    httpBaseFromWsEndpoint,
     type ChatMessage,
     type Citation,
     type ConnectionStatus,

From c1a1e15de15b8bb75ab9a6e072e6f864d8e2f01b Mon Sep 17 00:00:00 2001
From: Brent Rager <brent@rager.tech>
Date: Sat, 27 Jun 2026 21:16:33 -0400
Subject: [PATCH 3/3] =?UTF-8?q?SMOODEV-2129e:=20harden=20identity=20client?=
 =?UTF-8?q?=20=E2=80=94=20credentials:omit,=20session-scope=20verifiedEmai?=
 =?UTF-8?q?l,=20await-connect=20on=20restore,=20fail-loud=20URL=20base,=20?=
 =?UTF-8?q?in-memory=20storage=20fallback=20(adversarial=20review)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adversarial-review hardening of the 0.7.0 identity/persistence client layer:

- P1: postInternal now uses `credentials: 'omit'` (was 'include'). Auth is the
  Origin allowlist + authContext body, not cookies; 'include' would force
  Access-Control-Allow-Credentials + a reflected origin and break every
  /internal/* call against a plain origin-allowlisted CORS config.
- P2: verifiedEmail is now session-scoped. It's cleared on clearSession() and is
  NEVER auto-stamped into a brand-new create_conversation_session. A new
  verifiedEmailSessionId binds the OTP proof to the session it was verified for,
  so it can't leak onto another visitor's session on a shared browser. The proof
  is rebound to a restored conversation (the visitor proved ownership in-flow).
- P2: restore-link race fixed. The restore affordance awaits connect(), and
  requestIdentityOtp establishes a session first and always threads sessionId, so
  request-otp/verify-otp are session-consistent and verify can't hit "No active
  session" even if the email is submitted before the initial connect() resolves.
- P2: httpBaseFromWsEndpoint now FAILS LOUD (returns null) on a non-absolute
  endpoint instead of a relative fallback that would POST identity/OTP data to the
  host page origin. The controller goes to error status and postInternal refuses.
- P2: safeStorage returns an explicit in-memory (Map-backed) PersistStorage in
  privacy mode instead of undefined — undefined makes zustand v5 re-engage its own
  createJSONStorage(()=>localStorage), the exact thing the guard avoided.
- P2: resume probe is now idempotent (resumeAttempted guard) — re-entering
  connect() after a transient error no longer re-fires resumeByFingerprint.
- P3: corrected the mergeIdentity seed comment to match actual precedence.

Adds/adjusts unit + mock-e2e coverage for all of the above.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 e2e/identity-persistence-mock.spec.ts |  80 +++++++++++-
 src/conversation.test.ts              | 163 +++++++++++++++++++++++-
 src/conversation.ts                   | 170 ++++++++++++++++++++------
 src/element.ts                        |  15 ++-
 src/persistence.test.ts               |  77 +++++++++++-
 src/persistence.ts                    |  74 +++++++++--
 6 files changed, 524 insertions(+), 55 deletions(-)

diff --git a/e2e/identity-persistence-mock.spec.ts b/e2e/identity-persistence-mock.spec.ts
index 226a12f..79e87eb 100644
--- a/e2e/identity-persistence-mock.spec.ts
+++ b/e2e/identity-persistence-mock.spec.ts
@@ -57,7 +57,7 @@ const MOCK_WS = `
   window.fetch = async (url, init) => {
     const u = new URL(url, location.href);
     const body = init && init.body ? JSON.parse(init.body) : {};
-    window.__http.push({ path: u.pathname, body });
+    window.__http.push({ path: u.pathname, body, origin: u.origin, credentials: init && init.credentials });
     const route = (window.__httpScript || (() => ({ json: { resumable: false } })));
     const { status = 200, json = {} } = route(u.pathname, body) || {};
     return { ok: status >= 200 && status < 300, status, json: async () => json };
@@ -420,3 +420,81 @@ test('fingerprint resume: no persisted pointer → POST /internal/resume-by-fing
     expect(result.persistedSession).toBe('sess-FP');
     expect(result.replayed).toContain('Welcome back');
 });
+
+test("hardening: every /internal/* POST omits credentials, restore-link awaits connect, and request-otp carries a sessionId", async ({ page }) => {
+    const pageErrors: string[] = [];
+    page.on('pageerror', (e) => pageErrors.push(`${e.name}: ${e.message}`));
+
+    await page.addInitScript(MOCK_WS);
+    await page.goto(`http://127.0.0.1:${process.env.STATIC_PORT ?? 4830}/e2e/fixtures/demo.html`).catch(async () => {
+        await page.goto('about:blank');
+    });
+    await page.addScriptTag({ content: GLOBAL_BUNDLE });
+
+    const result = await page.evaluate(
+        async ({ endpoint, agentId }) => {
+            const s = (ms: number) => new Promise((r) => setTimeout(r, ms));
+            try {
+                localStorage.clear();
+            } catch {
+                /* ignore */
+            }
+            (window as unknown as { __script: unknown }).__script = (f: Record<string, unknown>, reply: (o: unknown) => void) => {
+                switch (f.action) {
+                    case 'create_conversation_session':
+                        reply({ type: 'immediate_response', requestId: f.requestId, status: 202, data: { sessionId: 'sess-A', conversationId: 'c', agentId: f.agentId } });
+                        break;
+                    case 'get_session':
+                        reply({ type: 'immediate_response', requestId: f.requestId, status: 200, data: { sessionId: f.sessionId, status: 'active', agentId } });
+                        break;
+                    case 'get_conversation_messages':
+                        reply({ type: 'immediate_response', requestId: f.requestId, status: 200, data: { messages: [], hasMore: false } });
+                        break;
+                }
+            };
+            (window as unknown as { __httpScript: unknown }).__httpScript = (path: string) => {
+                switch (path) {
+                    case '/internal/resume-by-fingerprint':
+                        return { json: { resumable: false } };
+                    case '/internal/identity/request-otp':
+                        return { json: { event: 'otp_sent', maskedDestination: 'a***@example.com' } };
+                    default:
+                        return { json: {} };
+                }
+            };
+            // @ts-expect-error injected global
+            const el = window.SmoothAgentChat.mount({ endpoint, agentId, greeting: '' });
+            const root = (el as { shadowRoot: ShadowRoot }).shadowRoot;
+            (root.querySelector('.launcher') as HTMLElement | null)?.click();
+            await s(30);
+
+            // Click "Restore my chats" then IMMEDIATELY submit the email — racing the
+            // (now awaited) connect(). The hardened flow must still have a sessionId on
+            // the request-otp POST.
+            (root.querySelector('.restore-link') as HTMLElement | null)?.click();
+            await s(10);
+            const emailInput = root.querySelector('.int-card .int-input') as HTMLInputElement;
+            emailInput.value = 'ada@example.com';
+            (root.querySelector('.int-card .int-btn.primary') as HTMLElement).click();
+
+            // Wait for the request-otp call to land.
+            for (let i = 0; i < 80; i++) {
+                if ((window as unknown as { __http: { path: string }[] }).__http.some((h) => h.path === '/internal/identity/request-otp')) break;
+                await s(25);
+            }
+            const http = (window as unknown as { __http: { path: string; body: Record<string, unknown>; credentials?: string }[] }).__http;
+            const otp = http.find((h) => h.path === '/internal/identity/request-otp');
+            return {
+                allOmit: http.length > 0 && http.every((h) => h.credentials === 'omit'),
+                requestOtpHasSession: typeof otp?.body.sessionId === 'string' && (otp.body.sessionId as string).length > 0,
+                sentSession: otp?.body.sessionId,
+            };
+        },
+        { endpoint: ENDPOINT, agentId: AGENT_ID },
+    );
+
+    expect(pageErrors, pageErrors.join('\n')).toEqual([]);
+    expect(result.allOmit, "every /internal/* POST must use credentials: 'omit'").toBe(true);
+    expect(result.requestOtpHasSession, 'request-otp must carry a sessionId even when racing the restore-link connect()').toBe(true);
+    expect(result.sentSession).toBe('sess-A');
+});
diff --git a/src/conversation.test.ts b/src/conversation.test.ts
index 0a736aa..20dc5ae 100644
--- a/src/conversation.test.ts
+++ b/src/conversation.test.ts
@@ -98,6 +98,7 @@ interface FetchCall {
     path: string;
     body: Record<string, unknown>;
     origin: string;
+    credentials?: RequestCredentials;
 }
 const fetchCalls: FetchCall[] = [];
 /** Per-test responder: path → JSON body (+ optional status). Default = resume:false. */
@@ -106,10 +107,10 @@ let fetchRouter: (path: string, body: Record<string, unknown>) => { status?: num
 function installMockFetch(): void {
     fetchCalls.length = 0;
     fetchRouter = () => ({ json: { resumable: false } });
-    (globalThis as unknown as { fetch: unknown }).fetch = async (url: string, init?: { body?: string }) => {
+    (globalThis as unknown as { fetch: unknown }).fetch = async (url: string, init?: { body?: string; credentials?: RequestCredentials }) => {
         const u = new URL(url);
         const body = init?.body ? (JSON.parse(init.body) as Record<string, unknown>) : {};
-        fetchCalls.push({ path: u.pathname, body, origin: u.origin });
+        fetchCalls.push({ path: u.pathname, body, origin: u.origin, credentials: init?.credentials });
         const { status = 200, json } = fetchRouter(u.pathname, body);
         return {
             ok: status >= 200 && status < 300,
@@ -307,6 +308,44 @@ describe('httpBaseFromWsEndpoint', () => {
         expect(httpBaseFromWsEndpoint('ws://localhost:8787/ws')).toBe('http://localhost:8787');
         expect(httpBaseFromWsEndpoint('wss://ai.smoo.ai:9000/ws')).toBe('https://ai.smoo.ai:9000');
     });
+
+    it('FAILS LOUD (returns null) on a non-absolute endpoint instead of a relative base', () => {
+        // A relative base would make fetch(`${base}/internal/...`) POST identity data
+        // to the HOST page origin instead of the operator host. Null forces a refusal.
+        expect(httpBaseFromWsEndpoint('/ws')).toBeNull();
+        expect(httpBaseFromWsEndpoint('not a url')).toBeNull();
+        expect(httpBaseFromWsEndpoint('')).toBeNull();
+    });
+});
+
+describe('ConversationController — fail-loud on a non-absolute endpoint', () => {
+    beforeEach(() => {
+        localStorage.clear();
+        installMockWs();
+        installMockFetch();
+        MockSocket.onFrame = defaultOnFrame;
+    });
+    afterEach(() => localStorage.clear());
+
+    it('enters error status and refuses /internal/* calls (no fetch) when the endpoint is not absolute', async () => {
+        const store = createWidgetStore(AGENT);
+        const onStatus = vi.fn();
+        const onIdentityRestore = vi.fn();
+        const controller = new ConversationController(
+            { endpoint: '/ws', agentId: AGENT },
+            { onMessages: vi.fn(), onStatus, onInterrupt: vi.fn(), onIdentityRestore },
+            store,
+        );
+        await tick();
+        // The constructor flagged the controller in error via a microtask.
+        expect(onStatus).toHaveBeenCalledWith('error', expect.stringContaining('/ws'));
+
+        // request-otp must NOT fire a fetch — it refuses with an identity-restore error.
+        await controller.requestIdentityOtp('ada@example.com');
+        expect(fetchCalls.length).toBe(0);
+        const last = onIdentityRestore.mock.calls.at(-1)?.[0] as IdentityRestore | undefined;
+        expect(last?.phase).toBe('error');
+    });
 });
 
 describe('ConversationController — fingerprint resume (ADR-048 §b, HTTP)', () => {
@@ -468,3 +507,123 @@ describe('ConversationController — cross-device restore (ADR-048 §c, HTTP)',
         expect(otpCall?.body.authContext).toEqual(ac);
     });
 });
+
+describe('ConversationController — adversarial-review hardening (SMOODEV-2129e)', () => {
+    beforeEach(() => {
+        localStorage.clear();
+        installMockWs();
+        installMockFetch();
+        MockSocket.onFrame = defaultOnFrame;
+    });
+    afterEach(() => localStorage.clear());
+
+    it("posts every /internal/* route with credentials: 'omit' (CORS allowlist auth, not cookies)", async () => {
+        fetchRouter = (path) => {
+            if (path === '/internal/identity/request-otp') return { json: { event: 'otp_sent', maskedDestination: 'a***@x.com' } };
+            return { json: { resumable: false } };
+        };
+        const { controller } = makeController();
+        // connect() with no pointer fires /internal/resume-by-fingerprint.
+        await controller.connect();
+        // and the identity route fires too.
+        await controller.requestIdentityOtp('ada@example.com');
+
+        expect(fetchCalls.length).toBeGreaterThan(0);
+        for (const call of fetchCalls) {
+            expect(call.credentials, `${call.path} must omit credentials`).toBe('omit');
+        }
+    });
+
+    it('does NOT thread verifiedEmail into a brand-new create_conversation_session', async () => {
+        // Seed a verifiedEmail bound to some OTHER session — it must not leak onto a
+        // freshly created session (which on a shared browser could be a new visitor).
+        const seed = createWidgetStore(AGENT);
+        seed.getState().setSessionId('sess-other');
+        seed.getState().setVerifiedEmail('verified@example.com', 'sess-other');
+        seed.getState().clearSession(); // clearing leaves no pointer → fresh create path
+
+        // After clearSession the proof is gone; even if it weren't, a fresh create
+        // must never carry it. Re-seed it post-clear to prove the create path itself
+        // refuses to stamp it.
+        seed.getState().setVerifiedEmail('verified@example.com', 'sess-other');
+
+        const { controller } = makeController();
+        await controller.connect();
+        const create = MockSocket.sentFrames.find((f) => f.action === 'create_conversation_session') as Record<string, unknown>;
+        expect(create).toBeTruthy();
+        const meta = (create.metadata ?? {}) as Record<string, unknown>;
+        expect(meta.verifiedEmail).toBeUndefined();
+    });
+
+    it('cross-device verify binds verifiedEmail to the live session id', async () => {
+        MockSocket.onFrame = defaultOnFrame;
+        fetchRouter = (path) => {
+            switch (path) {
+                case '/internal/resume-by-fingerprint':
+                    return { json: { resumable: false } };
+                case '/internal/identity/request-otp':
+                    return { json: { event: 'otp_sent', maskedDestination: 'a***@x.com' } };
+                case '/internal/identity/verify-otp':
+                    return { json: { event: 'otp_verified' } };
+                case '/internal/identity/resolve':
+                    return { json: { resolved: true, conversations: [] } };
+                default:
+                    return { json: {} };
+            }
+        };
+        const { controller, store } = makeController();
+        await controller.connect(); // creates sess-new
+        await controller.requestIdentityOtp('ada@example.com');
+        await controller.verifyIdentityOtp('123456');
+        await tick();
+        expect(store.getState().verifiedEmail).toBe('ada@example.com');
+        // Bound to the live session, not left unbound.
+        expect(store.getState().verifiedEmailSessionId).toBe('sess-new');
+    });
+
+    it('requestIdentityOtp establishes a session first, so request-otp carries a sessionId (no "No active session" on verify)', async () => {
+        // Simulate the restore-link race: the visitor submits the email BEFORE any
+        // prior connect(). requestIdentityOtp must connect, then send sessionId.
+        fetchRouter = (path) => {
+            if (path === '/internal/identity/request-otp') return { json: { event: 'otp_sent', maskedDestination: 'a***@x.com' } };
+            return { json: { resumable: false } };
+        };
+        const { controller } = makeController();
+        // No connect() called first — straight to requestIdentityOtp.
+        await controller.requestIdentityOtp('ada@example.com');
+
+        const otpCall = fetchCalls.find((c) => c.path === '/internal/identity/request-otp');
+        expect(otpCall, 'request-otp was sent').toBeTruthy();
+        // A session was established and threaded through.
+        expect(typeof otpCall?.body.sessionId).toBe('string');
+        expect(otpCall?.body.sessionId).toBe('sess-new');
+    });
+
+    it('resume probe runs at most once: re-entering connect() after an error does not re-POST resume-by-fingerprint', async () => {
+        let createCalls = 0;
+        MockSocket.onFrame = (frame, reply) => {
+            const requestId = frame.requestId;
+            if (frame.action === 'create_conversation_session') {
+                createCalls += 1;
+                if (createCalls === 1) {
+                    // First create fails → controller goes to error.
+                    reply({ type: 'error', requestId, data: { requestId, error: { code: 'BOOM', message: 'transient' } } });
+                } else {
+                    reply({ type: 'immediate_response', requestId, status: 202, data: { sessionId: 'sess-2', conversationId: 'c', agentId: frame.agentId } });
+                }
+            }
+        };
+        fetchRouter = () => ({ json: { resumable: false } });
+
+        const { controller } = makeController();
+        await expect(controller.connect()).rejects.toBeTruthy();
+        // One resume-by-fingerprint probe on the first connect.
+        const probesAfterFirst = fetchCalls.filter((c) => c.path === '/internal/resume-by-fingerprint').length;
+        expect(probesAfterFirst).toBe(1);
+
+        // Re-enter connect() after the error — must NOT re-run the resume probe.
+        await controller.connect();
+        const probesAfterSecond = fetchCalls.filter((c) => c.path === '/internal/resume-by-fingerprint').length;
+        expect(probesAfterSecond, 'resume probe must run at most once').toBe(1);
+    });
+});
diff --git a/src/conversation.ts b/src/conversation.ts
index 4131f66..a090886 100644
--- a/src/conversation.ts
+++ b/src/conversation.ts
@@ -40,15 +40,20 @@ import { type ConsentState, createWidgetStore, type WidgetStore } from './persis
  * the cross-device identity flow + fingerprint resume are HTTP POST routes on the
  * wrapper (origin-allowlisted + authContext, per ADR-046/ADR-048) — NOT WS frames.
  */
-export function httpBaseFromWsEndpoint(endpoint: string): string {
+export function httpBaseFromWsEndpoint(endpoint: string): string | null {
     try {
         const u = new URL(endpoint);
         u.protocol = u.protocol === 'ws:' ? 'http:' : u.protocol === 'wss:' ? 'https:' : u.protocol;
         // The REST routes live at the host root (`/internal/*`), not under `/ws`.
         return `${u.protocol}//${u.host}`;
     } catch {
-        // Best-effort string fallback for a non-absolute endpoint.
-        return endpoint.replace(/^wss:/, 'https:').replace(/^ws:/, 'http:').replace(/\/ws\/?$/, '');
+        // FAIL LOUD on a non-absolute endpoint. A relative fallback (e.g.
+        // `string.replace`) would yield a relative base, and `fetch(\`${base}/internal/...\`)`
+        // would then POST identity/OTP data to the HOST page origin (e.g. smoo.ai)
+        // instead of the operator host (ai.smoo.ai) — leaking it to the wrong origin.
+        // Returning null forces the controller into an error state and refuses the
+        // `/internal/*` calls rather than mis-targeting them.
+        return null;
     }
 }
 
@@ -207,16 +212,41 @@ export class ConversationController {
     private activeRequestId: string | null = null;
     private interrupt: Interrupt | null = null;
     private identityRestore: IdentityRestore = { phase: 'idle' };
-    /** HTTP base for the chat-ws wrapper's `/internal/*` REST routes. */
-    private readonly httpBase: string;
+    /**
+     * True once the resume probe (persisted-pointer get_session OR the
+     * `/internal/resume-by-fingerprint` POST) has run for this controller. Makes
+     * `connect()` idempotent: re-entering after a transient `error` status (e.g. a
+     * retried `send()`) creates a fresh session rather than re-running the resume
+     * probe — which would fire another `resumeByFingerprint` POST and could adopt a
+     * session we already decided not to resume.
+     */
+    private resumeAttempted = false;
+    /**
+     * HTTP base for the chat-ws wrapper's `/internal/*` REST routes. `null` when
+     * the configured WS endpoint could not be parsed into an absolute origin — in
+     * that case the `/internal/*` routes are refused (rather than mis-targeted at
+     * the host page origin). See {@link httpBaseFromWsEndpoint}.
+     */
+    private readonly httpBase: string | null;
 
     constructor(config: ChatWidgetConfig, events: ConversationEvents, store?: StoreApi<WidgetStore>) {
         this.config = config;
         this.events = events;
         this.httpBase = httpBaseFromWsEndpoint(config.endpoint);
+        if (this.httpBase === null) {
+            // A non-absolute endpoint means the identity / resume `/internal/*` routes
+            // have no safe target. Flag the controller in error so the UI surfaces it
+            // and the routes refuse (see postInternal) rather than mis-targeting the
+            // host page origin. Deferred to a microtask so listeners attached after
+            // construction still observe the transition.
+            queueMicrotask(() => this.setStatus('error', `Invalid chat endpoint: ${config.endpoint}`));
+        }
         this.store = store ?? createWidgetStore(config.agentId);
-        // Seed identity from config into the persisted store (config wins on first
-        // load; the persisted values survive across reloads thereafter).
+        // Seed identity from config into the persisted store. `mergeIdentity` is
+        // applied on EVERY construct, so a config-provided field always wins over
+        // the persisted value (config is authoritative when present). Fields the
+        // config does NOT provide keep their persisted value — those survive across
+        // reloads; explicitly-configured ones are re-applied each load.
         const seed: { name?: string; email?: string; phone?: string } = {};
         if (config.userName) seed.name = config.userName;
         if (config.userEmail) seed.email = config.userEmail;
@@ -312,7 +342,16 @@ export class ConversationController {
 
     /**
      * Build the `metadata` payload threaded into `create_conversation_session`:
-     * phone (no first-class engine field), consent, and a verified email when known.
+     * phone (no first-class engine field) and consent.
+     *
+     * NOTE: `verifiedEmail` is deliberately NOT stamped here. It is a per-session
+     * OTP proof bound to the session it was verified against
+     * (`verifiedEmailSessionId`), and the server only treats an actual OTP `verify`
+     * as proof — metadata `verifiedEmail` is just a hint. Auto-stamping it onto
+     * every brand-new `create_conversation_session` would mislabel a fresh
+     * visitor's session with a prior (possibly different) visitor's email on a
+     * shared browser. The verified email is only used when RESUMING the exact
+     * session it was proven for — see {@link verifiedEmailForSession}.
      */
     private sessionMetadata(): Record<string, unknown> | undefined {
         const state = this.store.getState();
@@ -328,10 +367,23 @@ export class ConversationController {
             if (consent.consentAt) c.consentAt = consent.consentAt;
             meta.consent = c;
         }
-        if (state.verifiedEmail) meta.verifiedEmail = state.verifiedEmail;
         return Object.keys(meta).length > 0 ? meta : undefined;
     }
 
+    /**
+     * The verified-email hint, but ONLY when the OTP proof is bound to the session
+     * being resumed (`verifiedEmailSessionId === sessionId`). Returns null
+     * otherwise so a stale/cross-visitor proof is never threaded onto a session it
+     * wasn't proven for.
+     */
+    private verifiedEmailForSession(sessionId: string): string | null {
+        const state = this.store.getState();
+        if (state.verifiedEmail && state.verifiedEmailSessionId === sessionId) {
+            return state.verifiedEmail;
+        }
+        return null;
+    }
+
     /** Lazily open the WS client (default transport). Idempotent within a connect. */
     private async ensureClient(): Promise<void> {
         if (this.client) return;
@@ -356,26 +408,35 @@ export class ConversationController {
         this.setStatus('connecting');
         try {
             await this.ensureClient();
-            const persistedSessionId = this.store.getState().sessionId;
-            if (persistedSessionId) {
-                const resumed = await this.tryResume(persistedSessionId);
-                if (resumed) {
-                    this.setStatus('ready');
-                    return;
-                }
-                // Resume failed (ended/404/gone) — clear the pointer, keep identity.
-                this.store.getState().clearSession();
-            } else {
-                // Returning anonymous visitor with no stored pointer: ask the
-                // wrapper to resolve a recent session for this fingerprint.
-                const fpSessionId = await this.resumeByFingerprint();
-                if (fpSessionId) {
-                    const resumed = await this.tryResume(fpSessionId);
+            // The resume probe (persisted-pointer get_session OR the fingerprint
+            // resume POST) runs AT MOST ONCE per controller lifecycle. Re-entering
+            // connect() after a transient error (e.g. a retried send()) must not
+            // re-run the probe — that would re-fire resumeByFingerprint and could
+            // adopt a session we already chose not to resume. After the first
+            // attempt, fall straight through to creating a fresh session.
+            if (!this.resumeAttempted) {
+                this.resumeAttempted = true;
+                const persistedSessionId = this.store.getState().sessionId;
+                if (persistedSessionId) {
+                    const resumed = await this.tryResume(persistedSessionId);
                     if (resumed) {
-                        this.store.getState().setSessionId(fpSessionId);
                         this.setStatus('ready');
                         return;
                     }
+                    // Resume failed (ended/404/gone) — clear the pointer, keep identity.
+                    this.store.getState().clearSession();
+                } else {
+                    // Returning anonymous visitor with no stored pointer: ask the
+                    // wrapper to resolve a recent session for this fingerprint.
+                    const fpSessionId = await this.resumeByFingerprint();
+                    if (fpSessionId) {
+                        const resumed = await this.tryResume(fpSessionId);
+                        if (resumed) {
+                            this.store.getState().setSessionId(fpSessionId);
+                            this.setStatus('ready');
+                            return;
+                        }
+                    }
                 }
             }
             await this.createSession();
@@ -403,12 +464,22 @@ export class ConversationController {
 
     /** POST JSON to a `/internal/*` route; returns the parsed body (or throws). */
     private async postInternal(path: string, payload: Record<string, unknown>): Promise<Record<string, unknown>> {
+        if (this.httpBase === null) {
+            // No absolute origin could be derived from the WS endpoint — refuse the
+            // call loudly rather than POST identity data to a relative (host-page) URL.
+            throw new Error(`Cannot reach ${path}: the chat endpoint is not an absolute URL.`);
+        }
         const res = await fetch(`${this.httpBase}${path}`, {
             method: 'POST',
             headers: { 'content-type': 'application/json' },
-            // Identity/origin checks are cookie- and Origin-based; send credentials
-            // so any session cookie the host set rides along.
-            credentials: 'include',
+            // Auth is the `Origin` allowlist + the `authContext` body field — NOT
+            // cookies. `credentials: 'include'` would force the server to reply with
+            // `Access-Control-Allow-Credentials: true` AND a reflected origin (a
+            // wildcard `*` is illegal with credentials), so a plain origin-allowlisted
+            // CORS config would fail the preflight and break EVERY `/internal/*` call.
+            // Omit credentials so the cross-origin POST works against an allowlist
+            // that doesn't (and shouldn't need to) opt into credentialed CORS.
+            credentials: 'omit',
             body: JSON.stringify({ ...this.authBody(), ...payload }),
         });
         let json: Record<string, unknown> = {};
@@ -611,10 +682,11 @@ export class ConversationController {
     // ─────────────────── Cross-device "restore my chats" (§c) ───────────────────
     //
     // Three HTTP POST routes on the chat-ws wrapper (the engine `/ws` dispatch
-    // rejects unknown verbs): request-otp → verify-otp → resolve. verify-otp and
-    // resolve are session-scoped — they require a live `sessionId` (a uuid), which
-    // is guaranteed because the widget connects (creating/resuming a session)
-    // before exposing the restore affordance.
+    // rejects unknown verbs): request-otp → verify-otp → resolve. ALL THREE are
+    // session-scoped — they require a live `sessionId` (a uuid). request-otp
+    // establishes the session itself (idempotent connect) before sending, so the
+    // whole flow shares one session and verify-otp can't hit "No active session"
+    // even if the email was submitted before the initial connect() resolved.
 
     /**
      * Begin the cross-device restore: POST `/internal/identity/request-otp` for
@@ -624,9 +696,25 @@ export class ConversationController {
         const trimmed = email.trim();
         if (!trimmed) return;
         this.setIdentityRestore({ phase: 'requesting', email: trimmed, channel });
+        // request-otp must be SESSION-CONSISTENT with verify-otp (which hard-requires
+        // a sessionId). If the restore affordance fired request-otp before connect()
+        // resolved, there'd be no sessionId here and verify-otp would later error
+        // "No active session." Establish a session first (idempotent connect), then
+        // require it — so the whole request → verify flow shares one live session.
+        if (!this.sessionId) {
+            try {
+                await this.connect();
+            } catch {
+                /* fall through: handled by the sessionId check below */
+            }
+        }
+        if (!this.sessionId) {
+            this.setIdentityRestore({ phase: 'error', message: 'No active session to verify against.' });
+            return;
+        }
         try {
             const json = await this.postInternal('/internal/identity/request-otp', {
-                ...(this.sessionId ? { sessionId: this.sessionId } : {}),
+                sessionId: this.sessionId,
                 email: trimmed,
                 channel,
             });
@@ -651,7 +739,9 @@ export class ConversationController {
         try {
             const json = await this.postInternal('/internal/identity/verify-otp', { sessionId: this.sessionId, email, code: trimmed });
             if (json.event === 'otp_verified') {
-                this.store.getState().setVerifiedEmail(email);
+                // Bind the OTP proof to the session it was verified against, so it
+                // can't leak onto a different visitor's session on a shared browser.
+                this.store.getState().setVerifiedEmail(email, this.sessionId);
                 await this.resolveIdentity(email);
             } else if (json.event === 'otp_invalid') {
                 const remaining = typeof json.attemptsRemaining === 'number' ? json.attemptsRemaining : undefined;
@@ -705,9 +795,18 @@ export class ConversationController {
      */
     async restoreConversation(sessionId: string): Promise<void> {
         if (!this.client) await this.ensureClient();
+        // Capture the OTP proof bound to the CURRENT live session BEFORE tryResume
+        // repoints this.sessionId to the restored one. The visitor proved ownership
+        // of this email in this very flow, so the proof legitimately follows the
+        // conversation they chose to restore.
+        const proven = this.sessionId ? this.verifiedEmailForSession(this.sessionId) : null;
         const resumed = await this.tryResume(sessionId);
         if (resumed) {
             this.store.getState().setSessionId(sessionId);
+            // Rebind the proof to the restored session (keeps verifiedEmail
+            // session-scoped, just now to the session it's actually used on). Only a
+            // proof from the just-verified session follows — never an unrelated stale one.
+            if (proven) this.store.getState().setVerifiedEmail(proven, sessionId);
             this.setIdentityRestore({ phase: 'idle' });
             this.setStatus('ready');
         } else {
@@ -726,6 +825,9 @@ export class ConversationController {
         this.client = null;
         this.sessionId = null;
         this.activeRequestId = null;
+        // A full teardown ends the controller lifecycle: a subsequent connect() is a
+        // genuine re-open and may resume again, so re-arm the resume probe.
+        this.resumeAttempted = false;
         this.setInterrupt(null);
         this.setStatus('closed');
     }
diff --git a/src/element.ts b/src/element.ts
index 7809f45..cc7f62a 100644
--- a/src/element.ts
+++ b/src/element.ts
@@ -352,11 +352,18 @@ export class SmoothAgentChatElement extends HTMLElement {
         });
 
         // Cross-device "Restore my chats": open the panel + start the email entry.
+        // AWAIT connect() before showing the email step so a `sessionId` exists by
+        // the time the visitor submits — otherwise request-otp could go out with no
+        // session and verify-otp would then hard-error "No active session." The
+        // request-otp/verify-otp paths in the controller also require a session, so
+        // gating here keeps the affordance race-free.
         container.querySelector('.restore-link')?.addEventListener('click', () => {
-            // Ensure we have a live transport before the OTP request.
-            void this.controller?.connect().catch(() => {});
-            this.identityRestore = { phase: 'awaiting_email' };
-            this.renderInterrupt();
+            void (async () => {
+                this.identityRestore = { phase: 'awaiting_email' };
+                this.renderInterrupt();
+                // Establish a live session before the email entry can fire request-otp.
+                await this.controller?.connect().catch(() => {});
+            })();
         });
 
         // Full-page mode connects eagerly (there's no launcher click to trigger it) —
diff --git a/src/persistence.test.ts b/src/persistence.test.ts
index df5b9ff..977e7df 100644
--- a/src/persistence.test.ts
+++ b/src/persistence.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { createWidgetStore, PERSIST_VERSION, type PersistedWidgetState, storageKey } from './persistence.js';
 
 const AGENT = 'agent-123';
@@ -23,6 +23,7 @@ describe('persistence store', () => {
         expect(s.identity).toEqual({});
         expect(s.consent).toEqual({ emailOptIn: false, smsOptIn: false });
         expect(s.verifiedEmail).toBeNull();
+        expect(s.verifiedEmailSessionId).toBeNull();
         expect(s.browserFingerprint).toBeNull();
     });
 
@@ -48,17 +49,17 @@ describe('persistence store', () => {
         expect(raw).toBeTruthy();
         const parsed = JSON.parse(raw as string) as { state: PersistedWidgetState };
         const keys = Object.keys(parsed.state).sort();
-        expect(keys).toEqual(['browserFingerprint', 'consent', 'identity', 'sessionId', 'verifiedEmail', 'version'].sort());
+        expect(keys).toEqual(['browserFingerprint', 'consent', 'identity', 'sessionId', 'verifiedEmail', 'verifiedEmailSessionId', 'version'].sort());
         // No message/transcript field leaks into storage.
         expect(JSON.stringify(parsed.state)).not.toContain('messages');
     });
 
-    it('clearSession drops the pointer but keeps identity/consent/verifiedEmail/fingerprint', () => {
+    it('clearSession drops the pointer AND the session-scoped verifiedEmail, keeps identity/consent/fingerprint', () => {
         const store = createWidgetStore(AGENT);
         store.getState().setSessionId('sess-1');
         store.getState().mergeIdentity({ name: 'Ada' });
         store.getState().setConsent({ emailOptIn: true, smsOptIn: true });
-        store.getState().setVerifiedEmail('ada@example.com');
+        store.getState().setVerifiedEmail('ada@example.com', 'sess-1');
         store.getState().setBrowserFingerprint('fp-abc');
 
         store.getState().clearSession();
@@ -66,10 +67,29 @@ describe('persistence store', () => {
         expect(s.sessionId).toBeNull();
         expect(s.identity.name).toBe('Ada');
         expect(s.consent.emailOptIn).toBe(true);
-        expect(s.verifiedEmail).toBe('ada@example.com');
+        // verifiedEmail is a PER-SESSION OTP proof — it must NOT survive a clear,
+        // or it would leak onto the next (possibly different) visitor's session.
+        expect(s.verifiedEmail).toBeNull();
+        expect(s.verifiedEmailSessionId).toBeNull();
         expect(s.browserFingerprint).toBe('fp-abc');
     });
 
+    it('setVerifiedEmail binds the proof to a session and clears the binding when nulled', () => {
+        const store = createWidgetStore(AGENT);
+        store.getState().setSessionId('sess-live');
+        // Explicit session binding.
+        store.getState().setVerifiedEmail('ada@example.com', 'sess-X');
+        expect(store.getState().verifiedEmail).toBe('ada@example.com');
+        expect(store.getState().verifiedEmailSessionId).toBe('sess-X');
+        // Omitted session falls back to the live pointer (never left unbound).
+        store.getState().setVerifiedEmail('bob@example.com');
+        expect(store.getState().verifiedEmailSessionId).toBe('sess-live');
+        // Nulling the email also clears the binding.
+        store.getState().setVerifiedEmail(null);
+        expect(store.getState().verifiedEmail).toBeNull();
+        expect(store.getState().verifiedEmailSessionId).toBeNull();
+    });
+
     it('rehydrates a persisted blob on a fresh store (resume across reload)', () => {
         const a = createWidgetStore(AGENT);
         a.getState().setSessionId('sess-keep');
@@ -96,4 +116,51 @@ describe('persistence store', () => {
         // The stray transcript must not survive migration.
         expect((s as unknown as Record<string, unknown>).messages).toBeUndefined();
     });
+
+    it('falls back to an explicit in-memory store when localStorage throws (privacy mode), never touching real localStorage', () => {
+        // Privacy-mode: the probe write throws. The guard must hand zustand an
+        // explicit in-memory store — NOT return undefined (which makes zustand v5
+        // re-engage its own createJSONStorage(()=>localStorage) and throw again).
+        const realSetItem = Storage.prototype.setItem;
+        const setSpy = vi.fn(() => {
+            throw new DOMException('denied', 'SecurityError');
+        });
+        Storage.prototype.setItem = setSpy as unknown as typeof realSetItem;
+        try {
+            // Construction must not throw despite setItem throwing on the probe.
+            const store = createWidgetStore('agent-privacy');
+            // The store still works in memory.
+            store.getState().setSessionId('sess-mem');
+            store.getState().mergeIdentity({ name: 'Ada' });
+            expect(store.getState().sessionId).toBe('sess-mem');
+            expect(store.getState().identity.name).toBe('Ada');
+            // Nothing was persisted to real localStorage (the in-memory fallback
+            // never touches it). getItem returns null for this agent's key.
+            expect(localStorage.getItem(storageKey('agent-privacy'))).toBeNull();
+        } finally {
+            Storage.prototype.setItem = realSetItem;
+        }
+    });
+
+    it('a fresh in-memory-fallback store does NOT see another store\'s persisted blob', () => {
+        // Persist a blob via the normal (working) localStorage path first.
+        const real = createWidgetStore(AGENT);
+        real.getState().setSessionId('sess-real');
+
+        // Now force the fallback for the SAME agent key. Because the fallback is a
+        // private Map (not real localStorage), it must start empty — proving it
+        // truly bypasses real localStorage rather than silently reading it.
+        const realGetItem = Storage.prototype.getItem;
+        const realSetItem = Storage.prototype.setItem;
+        Storage.prototype.setItem = (() => {
+            throw new DOMException('denied', 'SecurityError');
+        }) as unknown as typeof realSetItem;
+        try {
+            const fallback = createWidgetStore(AGENT);
+            expect(fallback.getState().sessionId).toBeNull();
+        } finally {
+            Storage.prototype.getItem = realGetItem;
+            Storage.prototype.setItem = realSetItem;
+        }
+    });
 });
diff --git a/src/persistence.ts b/src/persistence.ts
index 1c096bc..a567e6a 100644
--- a/src/persistence.ts
+++ b/src/persistence.ts
@@ -52,8 +52,16 @@ export interface PersistedWidgetState {
     sessionId: string | null;
     identity: IdentityState;
     consent: ConsentState;
-    /** Email proven via OTP (same-session or cross-device). Survives session clears. */
+    /**
+     * Email proven via OTP for the CURRENT session. Session-scoped: cleared on
+     * `clearSession()` so it can't leak across visitors on a shared browser, and
+     * only threaded into session metadata when {@link verifiedEmailSessionId}
+     * matches the live session (i.e. on resume of the verified session) — never
+     * auto-stamped onto a brand-new session.
+     */
     verifiedEmail: string | null;
+    /** The sessionId the {@link verifiedEmail} was proven against (binds the proof to one session). */
+    verifiedEmailSessionId: string | null;
     /** Stable per-browser correlation token (see fingerprint.ts). */
     browserFingerprint: string | null;
 }
@@ -65,12 +73,16 @@ export interface WidgetStoreActions {
     mergeIdentity: (identity: IdentityState) => void;
     /** Replace consent wholesale (the pre-chat form computes the full record). */
     setConsent: (consent: ConsentState) => void;
-    setVerifiedEmail: (email: string | null) => void;
+    /** Record an OTP-proven email bound to a specific session. */
+    setVerifiedEmail: (email: string | null, sessionId?: string | null) => void;
     setBrowserFingerprint: (fp: string) => void;
     /**
-     * Clear the session pointer but KEEP identity / consent / verifiedEmail /
-     * fingerprint — used when a persisted session has ended or 404s so the next
-     * turn starts a fresh session for a known visitor.
+     * Clear the session pointer (and the session-scoped `verifiedEmail` proof) but
+     * KEEP identity / consent / fingerprint — used when a persisted session has
+     * ended or 404s so the next turn starts a fresh session for a known visitor.
+     * `verifiedEmail` is deliberately cleared here: it is a per-session OTP proof,
+     * not a durable identity, so it must NOT survive onto a new session (which on a
+     * shared browser could be a different visitor).
      */
     clearSession: () => void;
 }
@@ -86,6 +98,7 @@ function initialPersisted(): PersistedWidgetState {
         identity: {},
         consent: { ...EMPTY_CONSENT },
         verifiedEmail: null,
+        verifiedEmailSessionId: null,
         browserFingerprint: null,
     };
 }
@@ -95,13 +108,45 @@ export function storageKey(agentId: string): string {
     return `smoo-chat-widget:${agentId}`;
 }
 
+/**
+ * An explicit in-memory (Map-backed) `PersistStorage`. Used as the fallback when
+ * real localStorage is unavailable.
+ *
+ * IMPORTANT: we must NOT return `undefined` from {@link safeStorage} in that case.
+ * zustand v5's `persist` treats a missing `storage` option by falling back to its
+ * OWN `createJSONStorage(() => localStorage)` — i.e. it re-engages the very
+ * localStorage the guard was trying to avoid (throwing again in privacy mode).
+ * Handing it this no-op storage keeps the store working purely in memory and
+ * guarantees the fallback can't touch real localStorage.
+ */
+function memoryStorage(): PersistStorage<PersistedWidgetState> {
+    const mem = new Map<string, string>();
+    return {
+        getItem: (name) => {
+            const raw = mem.get(name);
+            if (!raw) return null;
+            try {
+                return JSON.parse(raw) as ReturnType<PersistStorage<PersistedWidgetState>['getItem']>;
+            } catch {
+                return null;
+            }
+        },
+        setItem: (name, value) => {
+            mem.set(name, JSON.stringify(value));
+        },
+        removeItem: (name) => {
+            mem.delete(name);
+        },
+    };
+}
+
 /**
  * A `persist` storage adapter that tolerates the *absence* of localStorage
  * (SSR, privacy-mode throwing on access, sandboxed iframes). When storage is
  * unavailable the store still works in-memory; nothing is persisted, but the
  * widget never throws on boot.
  */
-function safeStorage(): PersistStorage<PersistedWidgetState> | undefined {
+function safeStorage(): PersistStorage<PersistedWidgetState> {
     let ls: Storage | null = null;
     try {
         ls = typeof localStorage !== 'undefined' ? localStorage : null;
@@ -114,7 +159,8 @@ function safeStorage(): PersistStorage<PersistedWidgetState> | undefined {
     } catch {
         ls = null;
     }
-    if (!ls) return undefined;
+    // Fall back to an explicit in-memory store — NEVER `undefined` (see memoryStorage).
+    if (!ls) return memoryStorage();
     const storage = ls;
     return {
         getItem: (name) => {
@@ -166,6 +212,7 @@ function migrate(persisted: unknown): PersistedWidgetState {
             consentAt: typeof p.consent?.consentAt === 'string' ? p.consent.consentAt : undefined,
         },
         verifiedEmail: typeof p.verifiedEmail === 'string' ? p.verifiedEmail : null,
+        verifiedEmailSessionId: typeof p.verifiedEmailSessionId === 'string' ? p.verifiedEmailSessionId : null,
         browserFingerprint: typeof p.browserFingerprint === 'string' ? p.browserFingerprint : null,
     };
 }
@@ -191,9 +238,17 @@ export function createWidgetStore(agentId: string): StoreApi<WidgetStore> {
                         },
                     })),
                 setConsent: (consent) => set({ consent: { ...consent } }),
-                setVerifiedEmail: (verifiedEmail) => set({ verifiedEmail }),
+                setVerifiedEmail: (verifiedEmail, sessionId) =>
+                    set((state) => ({
+                        verifiedEmail,
+                        // Bind the proof to the session it was verified against. When the
+                        // caller omits sessionId, fall back to the live pointer so the
+                        // proof is never left unbound.
+                        verifiedEmailSessionId: verifiedEmail === null ? null : (sessionId ?? state.sessionId),
+                    })),
                 setBrowserFingerprint: (browserFingerprint) => set({ browserFingerprint }),
-                clearSession: () => set({ sessionId: null }),
+                // Drop the pointer AND the session-scoped OTP proof; keep durable identity.
+                clearSession: () => set({ sessionId: null, verifiedEmail: null, verifiedEmailSessionId: null }),
             }),
             {
                 name: storageKey(agentId),
@@ -207,6 +262,7 @@ export function createWidgetStore(agentId: string): StoreApi<WidgetStore> {
                     identity: state.identity,
                     consent: state.consent,
                     verifiedEmail: state.verifiedEmail,
+                    verifiedEmailSessionId: state.verifiedEmailSessionId,
                     browserFingerprint: state.browserFingerprint,
                 }),
             },