@smooai/chat-widget 0.6.0 → 0.9.0

package/src/element.ts

@@ -14,15 +14,41 @@
  *   <smooth-agent-chat endpoint="ws://localhost:8787/ws" agent-id="…"></smooth-agent-chat>
  * or programmatically via {@link mountChatWidget}.
  */
+import { AsYouType, isValidPhoneNumber, parsePhoneNumber } from 'libphonenumber-js/min';
 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';
 
 export const ELEMENT_TAG = 'smooth-agent-chat';
 
+/**
+ * Default region for phone parsing/formatting on the pre-chat form. The widget
+ * is US-first; the backend does the authoritative E.164 normalization (SMOODEV-2153),
+ * so this only governs the as-you-type display + the inline validity hint and the
+ * best-effort E.164 we send when the number already parses as valid.
+ */
+const PHONE_DEFAULT_REGION = 'US' as const;
+
+/**
+ * Best-effort E.164 for an as-typed phone number. Returns the canonical
+ * `+1…` form when the value parses to a valid number in {@link PHONE_DEFAULT_REGION},
+ * otherwise `null` (caller falls back to sending the raw value — the backend
+ * re-parses and normalizes/nulls authoritatively).
+ */
+function phoneToE164(value: string): string | null {
+    const v = value.trim();
+    if (!v) return null;
+    try {
+        if (!isValidPhoneNumber(v, PHONE_DEFAULT_REGION)) return null;
+        return parsePhoneNumber(v, PHONE_DEFAULT_REGION).number;
+    } catch {
+        return null;
+    }
+}
+
 const OBSERVED = ['endpoint', 'agent-id', 'agent-name', 'placeholder', 'greeting', 'start-open', 'mode'] as const;
 
 /**
@@ -73,6 +99,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 +168,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. */
@@ -163,6 +198,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,
@@ -171,6 +207,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,
         };
@@ -186,6 +225,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 +243,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 +292,22 @@ 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, hint = false) =>
+            `<label class="pc-field"><span>${escapeHtml(label)}</span><input name="${name}" type="${type}" autocomplete="${autocomplete}"${required ? ' required' : ''} />${
+                hint ? '<span class="pc-hint" aria-live="polite"></span>' : ''
+            }</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 +315,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, true) : ''}
+                    ${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 +331,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 +379,27 @@ export class SmoothAgentChatElement extends HTMLElement {
             this.handlePrechatSubmit(pcForm as HTMLFormElement);
         });
 
+        // Live phone formatting + validity hint (libphonenumber-js, US default).
+        // The implicit <label>, type="tel", and autocomplete="tel" from field()
+        // are preserved — autofill keeps working — and we also reformat on
+        // `change` so a browser-autofilled value gets formatted/validated too.
+        this.wirePhoneField(pcForm as HTMLFormElement | null);
+
+        // 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', () => {
+            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) —
         // but only once any identity gate is cleared.
         if (fullpage && !gating) void this.controller?.connect().catch(() => {});
@@ -335,6 +422,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 +514,270 @@ 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) void 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) void 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 '';
+        }
+    }
+
+    /**
+     * Wire as-you-type formatting + an inline validity hint onto the pre-chat
+     * phone input (libphonenumber-js, US default region). Autofill is preserved:
+     * the input keeps its `type="tel"` + `autocomplete="tel"` + implicit <label>,
+     * and we also reformat on `change` so a browser-autofilled value gets
+     * formatted/validated too.
+     *
+     * As-you-type caret note: `AsYouType` reformats the entire string, which
+     * moves the caret to the end on a mid-string edit. To avoid fighting the
+     * user, we only rewrite the value when the caret is at the end (the typical
+     * append-a-digit case) and never on a deletion — so backspacing the
+     * formatting characters works naturally.
+     */
+    private wirePhoneField(form: HTMLFormElement | null): void {
+        const input = form?.querySelector('input[name="phone"]') as HTMLInputElement | null;
+        if (!input) return;
+        const hint = input.parentElement?.querySelector('.pc-hint') as HTMLElement | null;
+
+        const updateHint = () => {
+            const v = input.value.trim();
+            const field = input.closest('.pc-field');
+            if (!v) {
+                // Empty is neutral — the field is optional unless requirePhone.
+                field?.classList.remove('valid', 'invalid');
+                if (hint) hint.textContent = '';
+                return;
+            }
+            const ok = isValidPhoneNumber(v, PHONE_DEFAULT_REGION);
+            field?.classList.toggle('valid', ok);
+            field?.classList.toggle('invalid', !ok);
+            if (hint) hint.textContent = ok ? '' : 'Enter a valid phone number';
+        };
+
+        const reformat = () => {
+            const atEnd = input.selectionStart === input.value.length && input.selectionEnd === input.value.length;
+            // Only reformat when appending at the end; never fight a mid-string
+            // edit or a deletion (see the caret note above).
+            if (atEnd) {
+                const formatted = new AsYouType(PHONE_DEFAULT_REGION).input(input.value);
+                // Avoid clobbering when the user is deleting: only grow/normalize,
+                // not when the formatter would re-add a character they just removed.
+                if (formatted.length >= input.value.length) {
+                    input.value = formatted;
+                }
+            }
+            updateHint();
+        };
+
+        input.addEventListener('input', (ev) => {
+            const ie = ev as InputEvent;
+            // Don't reformat while deleting — let the user clear characters freely.
+            if (typeof ie.inputType === 'string' && ie.inputType.startsWith('delete')) {
+                updateHint();
+                return;
+            }
+            reformat();
+        });
+        // Browser autofill / paste-then-blur lands here; format + validate it too.
+        input.addEventListener('change', reformat);
+    }
+
+    /** 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';
+
+        // Phone: when required, block on an invalid number and surface the hint.
+        // When optional, allow submit — the backend normalizes/nulls authoritatively.
+        const rawPhone = val('phone');
+        const phoneInput = form.querySelector('input[name="phone"]') as HTMLInputElement | null;
+        if (rawPhone && phoneInput && !isValidPhoneNumber(rawPhone, PHONE_DEFAULT_REGION)) {
+            const required = phoneInput.hasAttribute('required');
+            const field = phoneInput.closest('.pc-field');
+            field?.classList.add('invalid');
+            const hint = field?.querySelector('.pc-hint');
+            if (hint) hint.textContent = 'Enter a valid phone number';
+            if (required) {
+                phoneInput.focus();
+                return;
+            }
+        }
+        // Prefer canonical E.164 when it parses; fall back to the raw value
+        // otherwise (the backend re-parses + normalizes either way).
+        const phone = rawPhone ? (phoneToE164(rawPhone) ?? rawPhone) : undefined;
+
+        this.controller?.setUserInfo({
+            name: val('name'),
+            email: val('email'),
+            phone,
+            consent: { emailOptIn: checked('emailOptIn'), smsOptIn: checked('smsOptIn') },
+        });
         this.userInfoSatisfied = true;
         this.render();
         void this.controller?.connect().catch(() => {});

package/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;
+}

package/src/index.ts

@@ -33,9 +33,23 @@ export type { ChatWidgetConfig, ChatWidgetMode, ChatWidgetTheme } from './config
 export { initChatWidgetLoader } from './loader-core.js';
 export {
     ConversationController,
+    httpBaseFromWsEndpoint,
     type ChatMessage,
     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';