@repzo/widget-react-native 1.0.0

package/src/state/widget-store.ts

@@ -0,0 +1,1815 @@
+/**
+ * The widget's single source of truth.
+ *
+ * Ported from the web widget's `client/src/widget/hooks/use-widget-state.ts`
+ * plus the routing/tab logic in `client/src/widget/App.tsx`. Unlike the web
+ * version this is a plain store rather than a hook, because the SSE connection
+ * and the unread count must stay alive while the UI is closed — the modal is
+ * only a subscriber.
+ */
+
+import { AppState, type AppStateStatus, Platform } from 'react-native';
+
+import { isTerminalErrorCode, RepzoWidgetError, WidgetApiClient } from '../api/client';
+import { WidgetRealtime } from '../api/realtime';
+import { getDeviceId, rotateDeviceId } from '../device-id';
+import { EventEmitter, RepzoWidgetEvents } from '../events';
+import { PushManager } from '../push/push-notifications';
+import { CONFIG_KEY, LEGACY_CONFIG_KEY, SecureStorage, Storage, UNREAD_KEY, USER_KEY } from '../storage';
+import { DEFAULT_BASE_URL } from '../types';
+import type {
+  AgentUiAction,
+  BootOptions,
+  Conversation,
+  Message,
+  RepzoWidgetErrorCode,
+  WidgetAttachment,
+  WidgetConfig,
+  WidgetCustomAttributes,
+  WidgetSpaceType,
+  WidgetState,
+  WidgetUser,
+  WidgetView,
+} from '../types';
+import { setOpenUrlHandler } from '../ui/utils/safe-url';
+
+const SDK_VERSION = '@repzo/widget-react-native@1.0.0';
+
+/** The platform this session reports — mobile sessions get the Mobile SDKs overrides. */
+function sessionPlatform(): 'ios' | 'android' | 'web' {
+  return Platform.OS === 'ios' || Platform.OS === 'android' ? Platform.OS : 'web';
+}
+
+/** CONFIG_KEY entry: the session config plus where it came from. */
+interface CachedConfig {
+  v: 2;
+  baseUrl: string;
+  channelAccountId: string;
+  platform: 'ios' | 'android' | 'web';
+  config: WidgetConfig;
+}
+const TYPING_CLEAR_MS = 30_000;
+const TYPING_SETTLE_MS = 3_000;
+/** Visitor → agent typing pings are rate limited at 30/min server-side. */
+const TYPING_PING_INTERVAL_MS = 4_000;
+/** Guards against the SSE stream replaying messages after a reconnect. */
+const SEEN_MESSAGE_LIMIT = 100;
+/** Logout's server calls are best-effort — a dead network must not block sign-out. */
+const LOGOUT_REQUEST_TIMEOUT_MS = 5_000;
+/** A server that 401s every fresh stream must not spin init (10/min limit). */
+const STREAM_REAUTH_MIN_INTERVAL_MS = 30_000;
+/** Live replies in the open thread advance the server read cursor, batched. */
+const MARK_READ_DEBOUNCE_MS = 1_000;
+/** Live events held back while a draft's first send is creating its thread. */
+const DRAFT_EVENT_BUFFER_LIMIT = 50;
+/** Plain-http `baseUrl` is only accepted for these (plus `*.local` and `__DEV__`). */
+const LOCAL_DEV_HOSTS = new Set(['localhost', '127.0.0.1', '10.0.2.2']);
+
+const sumUnread = (map: Record<string, number>): number =>
+  Object.values(map).reduce((sum, count) => sum + count, 0);
+
+const INITIAL_STATE: WidgetState = {
+  booted: false,
+  loading: false,
+  error: null,
+  errorCode: null,
+  config: null,
+  identityId: null,
+  isOpen: false,
+  view: 'bubble',
+  activeTab: 'home',
+  conversations: [],
+  activeConversationId: null,
+  messages: [],
+  messagesLoading: false,
+  hasMoreMessages: false,
+  messageCursor: null,
+  agentTyping: false,
+  unreadCount: 0,
+  unreadByConversation: {},
+  locale: 'en',
+  prefillText: '',
+  outboundMessage: null,
+  visitorProfile: {},
+};
+
+/** Everything in state that belongs to the signed-in visitor. */
+const USER_SCOPED_STATE: Partial<WidgetState> = {
+  // A wiped session is not booted until the next init lands.
+  booted: false,
+  identityId: null,
+  conversations: [],
+  activeConversationId: null,
+  messages: [],
+  messagesLoading: false,
+  hasMoreMessages: false,
+  messageCursor: null,
+  agentTyping: false,
+  unreadCount: 0,
+  unreadByConversation: {},
+  prefillText: '',
+  outboundMessage: null,
+  visitorProfile: {},
+};
+
+export class WidgetStore {
+  readonly client = new WidgetApiClient();
+
+  readonly events = new EventEmitter();
+
+  readonly push = new PushManager(this.client, (conversationId) => {
+    void this.openConversation(conversationId);
+  });
+
+  private state: WidgetState = INITIAL_STATE;
+
+  private subscribers = new Set<() => void>();
+
+  private realtime = new WidgetRealtime();
+
+  private typingTimer: ReturnType<typeof setTimeout> | null = null;
+
+  private pendingAgentByConversation: Record<
+    string,
+    { agentName: string | null; agentAvatar: string | null }
+  > = {};
+
+  private bootConfig: { baseUrl: string; channelAccountId: string } | null = null;
+
+  private bootPromise: Promise<void> | null = null;
+
+  /** Identity key of the in-flight boot — a boot for someone else is not deduped. */
+  private bootingUserKey: string | null = null;
+
+  private currentUser: WidgetUser | null = null;
+
+  /** Who the stored token was issued to; null = anonymous. */
+  private currentUserKey: string | null = null;
+
+  /** True once `currentUserKey` mirrors storage — memory is then authoritative. */
+  private userKeyLoaded = false;
+
+  private pendingConversationId: string | null = null;
+
+  private appStateSubscription: { remove(): void } | null = null;
+
+  private lastTypingPingAt = 0;
+
+  private visitorTypingActive = false;
+
+  private seenMessageIds: string[] = [];
+
+  /**
+   * Identity generation. Bumped whenever boot/login/logout is requested; every
+   * async path that writes session state captures it first and bails once it
+   * moved, so a slow init for user A can never land after B logged in or
+   * after logout.
+   */
+  private epoch = 0;
+
+  /** Serializes identity ops (and 401 re-inits) — one init or wipe at a time. */
+  private identityQueue: Promise<unknown> = Promise.resolve();
+
+  /** Shared by concurrent 401s: one re-init, not one per failed request. */
+  private reauthPromise: Promise<string | null> | null = null;
+
+  /** Set by logout(); blocks 401 re-init and realtime until the next boot/login. */
+  private loggedOut = false;
+
+  /**
+   * True during wipeSession(). A 401 from a request still on the wire (a push
+   * registration it waits for) must not queue a re-init behind the wipe.
+   */
+  private wiping = false;
+
+  /** Set by a terminal 403 — stops realtime and re-init until a successful init. */
+  private terminalErrorCode: RepzoWidgetErrorCode | null = null;
+
+  private lastStreamReauthAt = 0;
+
+  /** Queued/running boot, login and logout ops — Retry must not cut in. */
+  private identityOpsInFlight = 0;
+
+  /**
+   * Bumped whenever a different thread (or a fresh draft) takes the screen.
+   * Message loads capture it and drop their result once it moved, so a slow
+   * response for A never paints under B.
+   */
+  private threadGeneration = 0;
+
+  /**
+   * The in-flight first send of a draft, which creates its conversation.
+   * Sends from the same draft wait for its id instead of creating another.
+   */
+  private conversationCreation: ConversationCreation | null = null;
+
+  /** Live events for a thread that may be the one the draft is creating. */
+  private draftEvents: Array<{ event: string; data: any }> = [];
+
+  /** False until this stream's first `connected`; later ones are reconnects. */
+  private streamConnectedOnce = false;
+
+  /** The stream errored before its first `connected` — that one is a reconnect too. */
+  private streamErrored = false;
+
+  private readTimer: ReturnType<typeof setTimeout> | null = null;
+
+  private readConversationId: string | null = null;
+
+  constructor() {
+    this.client.reauthorize = (failedToken) => this.reauthorize(failedToken);
+    this.client.onTerminalError = (error) => this.handleTerminalError(error);
+  }
+
+  // ─── Subscription plumbing ──────────────────────────────────────────────
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.subscribers.add(listener);
+    return () => {
+      this.subscribers.delete(listener);
+    };
+  };
+
+  getState = (): WidgetState => this.state;
+
+  private setState(patch: Partial<WidgetState> | ((current: WidgetState) => Partial<WidgetState>)) {
+    const previous = this.state;
+    const resolved = typeof patch === 'function' ? patch(previous) : patch;
+    const next = { ...previous, ...resolved };
+    // The total is always derived from the per-thread map, so no surface can
+    // zero the badge while threads stay unread.
+    next.unreadCount = sumUnread(next.unreadByConversation);
+    this.state = next;
+
+    if (next.unreadCount !== previous.unreadCount) {
+      this.events.emit(RepzoWidgetEvents.UnreadCountDidChange, { count: next.unreadCount });
+    }
+    if (next.isOpen !== previous.isOpen) {
+      this.events.emit(
+        next.isOpen ? RepzoWidgetEvents.WindowDidShow : RepzoWidgetEvents.WindowDidHide,
+        undefined
+      );
+    }
+
+    this.subscribers.forEach((listener) => listener());
+  }
+
+  // ─── Identity queue ─────────────────────────────────────────────────────
+
+  private serialize<T>(op: () => Promise<T>): Promise<T> {
+    const run = this.identityQueue.then(op);
+    this.identityQueue = run.catch(() => {});
+    return run;
+  }
+
+  /** Queue a requested identity op; anything older becomes stale right away. */
+  private enqueueIdentity<T>(op: (epoch: number) => Promise<T>): Promise<T> {
+    const epoch = ++this.epoch;
+    // A pending boot is superseded — a later boot() must not dedupe onto it.
+    this.bootPromise = null;
+    this.bootingUserKey = null;
+    this.identityOpsInFlight += 1;
+    return this.serialize(() => op(epoch)).finally(() => {
+      this.identityOpsInFlight -= 1;
+    });
+  }
+
+  private isStale(epoch: number): boolean {
+    return epoch !== this.epoch;
+  }
+
+  // ─── Boot / identity ────────────────────────────────────────────────────
+
+  async boot(options: BootOptions): Promise<void> {
+    if (!options?.channelAccountId) {
+      throw new RepzoWidgetError('boot() requires channelAccountId', 0, 'http');
+    }
+    const baseUrl = assertSecureBaseUrl(options.baseUrl?.trim() || DEFAULT_BASE_URL);
+    if (options.onOpenUrl !== undefined) setOpenUrlHandler(options.onOpenUrl ?? null);
+
+    const sameTarget =
+      this.bootConfig?.baseUrl === baseUrl &&
+      this.bootConfig?.channelAccountId === options.channelAccountId;
+    const userKey = options.user ? identityKey(options.user) : null;
+
+    if (sameTarget && this.bootPromise && (!userKey || userKey === this.bootingUserKey)) {
+      return this.bootPromise;
+    }
+    if (sameTarget && this.state.booted && !this.state.error && !this.userChanged(options.user)) {
+      return;
+    }
+
+    this.bootConfig = { baseUrl, channelAccountId: options.channelAccountId };
+    this.client.configure(baseUrl, options.channelAccountId);
+    if (options.push) this.push.configure(options.push);
+
+    // Paint with the last known theme immediately — without this the UI
+    // flashes the built-in defaults (color, labels) until init returns.
+    void this.seedCachedConfig();
+
+    const user = options.user;
+    const promise: Promise<void> = this.enqueueIdentity(async (epoch) => {
+      if (this.isStale(epoch)) return;
+      this.loggedOut = false;
+      this.currentUser = user ?? this.currentUser;
+      try {
+        await this.establishSession(user, epoch);
+      } catch (error) {
+        // Boot failures must not crash the host app — surface through state.
+        if (!this.isStale(epoch)) {
+          this.setState({
+            loading: false,
+            error: error instanceof Error ? error.message : 'Failed to load chat',
+            errorCode: error instanceof RepzoWidgetError ? error.code : 'http',
+          });
+        }
+        throw error;
+      }
+    }).finally(() => {
+      if (this.bootPromise === promise) {
+        this.bootPromise = null;
+        this.bootingUserKey = null;
+      }
+    });
+
+    this.bootPromise = promise;
+    this.bootingUserKey = userKey;
+    return promise;
+  }
+
+  private userChanged(user?: WidgetUser): boolean {
+    if (!user) return false;
+    return identityKey(user) !== this.currentUserKey;
+  }
+
+  /**
+   * Init for `user` — or, when undefined, for whoever the stored token
+   * belongs to. The stored token is only resumed when it is anonymous or
+   * already belongs to `user`: resuming another identified user's token would
+   * hand their conversations to this one, so that case signs them out first.
+   */
+  private async establishSession(user: WidgetUser | undefined, epoch: number): Promise<void> {
+    let resumeToken = true;
+    if (user) {
+      const storedKey = await this.storedUserKey();
+      if (this.isStale(epoch)) return;
+      if (storedKey && storedKey !== identityKey(user)) {
+        await this.wipeSession();
+        if (this.isStale(epoch)) return;
+        resumeToken = false;
+      }
+      this.currentUser = user;
+    }
+    await this.runInit({ user, resumeToken, epoch });
+  }
+
+  private async runInit(params: {
+    user?: WidgetUser;
+    resumeToken: boolean;
+    epoch: number;
+  }): Promise<void> {
+    this.setState({ loading: true, error: null, errorCode: null });
+    try {
+      await this.initSession(params);
+    } catch (error) {
+      if (!this.isStale(params.epoch)) {
+        if (error instanceof RepzoWidgetError && isTerminalErrorCode(error.code)) {
+          this.handleTerminalError(error);
+        } else if (!this.state.booted) {
+          // No usable session: surface it so the UI shows Retry instead of a
+          // chat that looks alive. A failed silent re-init of a booted
+          // session stays quiet — the next request or foreground retries.
+          this.setState({
+            loading: false,
+            error: error instanceof Error ? error.message : 'Failed to load chat',
+            errorCode: error instanceof RepzoWidgetError ? error.code : 'http',
+          });
+        } else {
+          this.setState({ loading: false });
+        }
+        // Foreground resume is how a failed boot recovers on its own.
+        if (!this.loggedOut) this.watchAppState();
+      }
+      throw error;
+    }
+  }
+
+  /** Every `await` is followed by an epoch check: stale results write nothing. */
+  private async initSession(params: {
+    user?: WidgetUser;
+    resumeToken: boolean;
+    epoch: number;
+  }): Promise<void> {
+    const { user, epoch } = params;
+
+    const trackingVisitorId = await getDeviceId();
+    if (this.isStale(epoch)) return;
+    // Read before init: a resumed identified session keeps its key.
+    const priorKey = user ? null : await this.storedUserKey();
+    if (this.isStale(epoch)) return;
+
+    const result = await this.client.init({
+      user,
+      trackingVisitorId,
+      platform: sessionPlatform(),
+      sdkVersion: SDK_VERSION,
+      resumeToken: params.resumeToken,
+    });
+    if (this.isStale(epoch)) return;
+
+    // Only a session the server actually identified (init echoes `user`) is
+    // keyed to a user; anything else is anonymous and safe to resume later.
+    let userKey: string | null = null;
+    if (result.user) {
+      if (user) userKey = identityKey(user);
+      else userKey = priorKey ?? (result.user.email ? identityKey({ email: result.user.email }) : null);
+    }
+
+    this.currentUserKey = userKey;
+    this.userKeyLoaded = true;
+    this.terminalErrorCode = null;
+    // Token and user key land together, before the next stale check — a
+    // queued op must never see one without the other.
+    await Promise.all([
+      this.client.setToken(result.token),
+      userKey ? SecureStorage.setItem(USER_KEY, userKey) : SecureStorage.removeItem(USER_KEY),
+    ]);
+    if (this.isStale(epoch)) return;
+
+    const conversations = result.conversations.map((conversation) =>
+      this.hydrateConversation(conversation)
+    );
+
+    // Server counts win (they include replies pushed while the app was
+    // killed); the locally persisted map only covers older Workstation
+    // deployments that don't send unreadCount yet.
+    const storedUnread = await this.loadUnread();
+    if (this.isStale(epoch)) return;
+    const unreadByConversation: Record<string, number> = {};
+    for (const conversation of conversations) {
+      const count =
+        typeof conversation.unreadCount === 'number'
+          ? conversation.unreadCount
+          : (storedUnread[conversation.id] ?? 0);
+      if (count > 0) unreadByConversation[conversation.id] = count;
+    }
+    // A silent re-init can land while a thread is on screen — never badge it.
+    const onScreenId = this.state.activeConversationId;
+    if (onScreenId && this.isThreadOnScreen(onScreenId)) delete unreadByConversation[onScreenId];
+    this.persistUnread(unreadByConversation);
+
+    this.setState((current) => ({
+      booted: true,
+      loading: false,
+      error: null,
+      errorCode: null,
+      config: result.config,
+      identityId: result.identityId,
+      conversations,
+      // Also seeds the launcher badge, so a reply that landed while the app
+      // was closed still shows on the host's icon.
+      unreadByConversation,
+      locale:
+        current.locale === INITIAL_STATE.locale ? result.config.defaultLocale : current.locale,
+      activeTab: firstEnabledSpace(result.config?.spaces) ?? current.activeTab,
+      visitorProfile: {
+        ...current.visitorProfile,
+        ...(user?.name ? { name: user.name } : {}),
+        ...(user?.email ? { email: user.email } : {}),
+        ...(user?.phone ? { phone: user.phone } : {}),
+        // Init echoes back the identity the backend holds for this visitor.
+        // It is the authority once identity verification has run, so it wins
+        // over whatever the host passed in — and it is the only source when
+        // the host boots without user attributes at all.
+        ...(result.user?.name ? { name: result.user.name } : {}),
+        ...(result.user?.email ? { email: result.user.email } : {}),
+      },
+    }));
+
+    this.persistConfig(result.config);
+    this.connectRealtime(result.token);
+    this.watchAppState();
+    this.loadOutboundMessage();
+    // Re-runs on login switches too — the token moves to the new identity.
+    void this.push.start();
+
+    if (this.pendingConversationId) {
+      const conversationId = this.pendingConversationId;
+      this.pendingConversationId = null;
+      void this.openConversation(conversationId);
+    } else {
+      // A re-init after a 401 means the stream was down: catch the open
+      // thread up (a no-op when nothing is on screen).
+      void this.refreshOpenThread();
+    }
+  }
+
+  /**
+   * The last config this device received, applied before init returns so the
+   * UI opens with the workspace's real theme instead of the built-in defaults.
+   * Skipped once a fresh config is in state — never downgrades live data.
+   */
+  private async seedCachedConfig(): Promise<void> {
+    try {
+      void Storage.removeItem(LEGACY_CONFIG_KEY);
+      const raw = await Storage.getItem(CONFIG_KEY);
+      if (!raw || this.state.config) return;
+      const cached = JSON.parse(raw) as CachedConfig;
+      // Only a config cached by a session init for this same widget, server
+      // and platform is painted — anything else (another channel, the web
+      // design) would flash before init replaces it, so the loading state
+      // shows instead.
+      if (
+        cached?.v === 2 &&
+        cached.config &&
+        typeof cached.config === 'object' &&
+        cached.baseUrl === this.bootConfig?.baseUrl &&
+        cached.channelAccountId === this.bootConfig?.channelAccountId &&
+        cached.platform === sessionPlatform() &&
+        !this.state.config
+      ) {
+        this.setState({ config: cached.config });
+      }
+    } catch {
+      // Corrupt cache — the network config overwrites it shortly.
+    }
+  }
+
+  private persistConfig(config: WidgetConfig): void {
+    if (!this.bootConfig) return;
+    const entry: CachedConfig = {
+      v: 2,
+      baseUrl: this.bootConfig.baseUrl,
+      channelAccountId: this.bootConfig.channelAccountId,
+      platform: sessionPlatform(),
+      config,
+    };
+    try {
+      void Storage.setItem(CONFIG_KEY, JSON.stringify(entry));
+    } catch {
+      // Cache miss next launch at worst.
+    }
+  }
+
+  private async storedUserKey(): Promise<string | null> {
+    if (this.userKeyLoaded) return this.currentUserKey;
+    const stored = await SecureStorage.getItem(USER_KEY);
+    // Another op may have written the key while storage was being read.
+    if (this.userKeyLoaded) return this.currentUserKey;
+    this.currentUserKey = stored || null;
+    this.userKeyLoaded = true;
+    return this.currentUserKey;
+  }
+
+  /**
+   * Called by the API client after a 401. Single-flight: concurrent 401s share
+   * one re-init. Runs in the identity queue but does not bump the epoch, so it
+   * can't cancel a boot/login queued behind it — and it gives up if one was.
+   */
+  private reauthorize(failedToken: string | null): Promise<string | null> {
+    if (this.loggedOut || this.wiping || this.terminalErrorCode || !this.bootConfig) {
+      return Promise.resolve(null);
+    }
+    if (this.reauthPromise) return this.reauthPromise;
+
+    const epoch = this.epoch;
+    const promise: Promise<string | null> = this.serialize(async () => {
+      if (this.loggedOut || this.terminalErrorCode || this.isStale(epoch)) return null;
+      // Someone already replaced the token that failed — just retry with it.
+      const current = await this.client.getToken();
+      if (this.isStale(epoch)) return null;
+      if (current && current !== failedToken) return current;
+      try {
+        await this.runInit({ user: this.currentUser ?? undefined, resumeToken: false, epoch });
+      } catch {
+        return null;
+      }
+      if (this.isStale(epoch)) return null;
+      return this.client.getToken();
+    }).finally(() => {
+      if (this.reauthPromise === promise) this.reauthPromise = null;
+    });
+
+    this.reauthPromise = promise;
+    return promise;
+  }
+
+  /** A terminal 403 (`messenger_api_disabled`, `identity_verification_failed`). */
+  private handleTerminalError(error: RepzoWidgetError): void {
+    this.terminalErrorCode = error.code;
+    this.realtime.close();
+    this.setState({ loading: false, error: error.message, errorCode: error.code });
+  }
+
+  async loginUnidentifiedUser(): Promise<void> {
+    this.requireBootConfig();
+    return this.enqueueIdentity(async (epoch) => {
+      if (this.isStale(epoch)) return;
+      const storedKey = await this.storedUserKey();
+      if (this.isStale(epoch)) return;
+      if (this.state.booted && !this.state.error && !storedKey) return;
+
+      this.loggedOut = false;
+      this.currentUser = null;
+      // A signed-in user is signed out properly; an anonymous session is
+      // just dropped for a fresh one.
+      if (storedKey) await this.wipeSession();
+      else await this.client.clearToken();
+      if (this.isStale(epoch)) return;
+      await this.runInit({ user: undefined, resumeToken: false, epoch });
+    });
+  }
+
+  async loginUserWithUserAttributes(user: WidgetUser): Promise<void> {
+    this.requireBootConfig();
+    if (!user?.userId && !user?.email) {
+      throw new RepzoWidgetError('loginUserWithUserAttributes requires userId or email', 0, 'http');
+    }
+
+    return this.enqueueIdentity(async (epoch) => {
+      if (this.isStale(epoch)) return;
+      this.loggedOut = false;
+
+      const key = identityKey(user);
+      const storedKey = await this.storedUserKey();
+      if (this.isStale(epoch)) return;
+
+      // Same person as the resumed session — the token already points at their
+      // identity, so skip the (rate-limited) init round trip.
+      if (this.state.booted && !this.state.error && storedKey === key) {
+        this.currentUser = user;
+        this.setState((current) => ({
+          visitorProfile: {
+            ...current.visitorProfile,
+            ...(user.name ? { name: user.name } : {}),
+            ...(user.email ? { email: user.email } : {}),
+            ...(user.phone ? { phone: user.phone } : {}),
+          },
+        }));
+        return;
+      }
+
+      await this.establishSession(user, epoch);
+    });
+  }
+
+  async updateUser(attributes: WidgetCustomAttributes): Promise<void> {
+    this.requireBootConfig();
+    if (!this.state.booted) await this.bootPromise;
+
+    const customAttributes = sanitizeAttributes(attributes);
+    if (Object.keys(customAttributes).length === 0) return;
+
+    await this.client.identify({ customAttributes });
+  }
+
+  /**
+   * Signs the visitor out for good — hosts should await this on sign-out.
+   * Synchronously stops realtime, re-init and the UI; then (queued behind any
+   * in-flight init) wipes the session and tells the server.
+   */
+  async logout(): Promise<void> {
+    this.loggedOut = true;
+    this.currentUser = null;
+    this.pendingConversationId = null;
+    this.realtime.close();
+    this.clearTypingTimer();
+    this.resetThreadTracking();
+    this.appStateSubscription?.remove();
+    this.appStateSubscription = null;
+    this.setState({ ...INITIAL_STATE });
+
+    await this.enqueueIdentity(() => this.wipeSession());
+  }
+
+  /**
+   * Full local + server sign-out of the stored session, used by logout() and
+   * by a login that switches to a different user. The local wipe runs first,
+   * so nothing of the old user stays readable even if the network hangs;
+   * then the push registration is removed and the token revoked — both
+   * authenticated with the captured token, time-boxed, and never re-initing.
+   * Only the cached channel theme survives (it carries no visitor data).
+   */
+  private async wipeSession(): Promise<void> {
+    this.wiping = true;
+    try {
+      await this.wipeSessionUnguarded();
+    } finally {
+      this.wiping = false;
+    }
+  }
+
+  private async wipeSessionUnguarded(): Promise<void> {
+    this.realtime.close();
+    this.clearTypingTimer();
+    this.resetThreadTracking();
+    this.appStateSubscription?.remove();
+    this.appStateSubscription = null;
+    this.currentUserKey = null;
+    this.userKeyLoaded = true;
+    this.pendingAgentByConversation = {};
+    this.seenMessageIds = [];
+    this.visitorTypingActive = false;
+    this.lastTypingPingAt = 0;
+    this.setState({ ...USER_SCOPED_STATE });
+
+    const token = await this.client.getToken();
+    await Promise.all([
+      this.client.clearToken(),
+      SecureStorage.removeItem(USER_KEY),
+      Storage.removeItem(UNREAD_KEY),
+      // A new anonymous visitor on this device gets a new tracking identity.
+      rotateDeviceId(),
+    ]);
+
+    // Push DELETE first — it authenticates with the token about to be revoked.
+    await settleWithin(this.push.unregister(token), LOGOUT_REQUEST_TIMEOUT_MS);
+    if (token) {
+      await settleWithin(
+        this.client.logout(token).catch((error) => {
+          console.warn('[repzo-widget] server logout failed', error);
+        }),
+        LOGOUT_REQUEST_TIMEOUT_MS
+      );
+    }
+  }
+
+  /**
+   * Re-runs the last boot after a failure — wired to the error screen's retry
+   * and to foreground resume. Never rejects: the outcome lands in state.
+   */
+  async retry(): Promise<void> {
+    if (!this.bootConfig || this.bootPromise || this.identityOpsInFlight > 0 || this.loggedOut) {
+      return;
+    }
+    try {
+      await this.boot({ ...this.bootConfig, user: this.currentUser ?? undefined });
+    } catch {
+      // Already surfaced through `error` / `errorCode`.
+    }
+  }
+
+  /** Drops every per-thread tracker — the visitor (or their session) changed. */
+  private resetThreadTracking(): void {
+    this.threadGeneration += 1;
+    this.conversationCreation = null;
+    this.draftEvents = [];
+    this.cancelMarkRead();
+  }
+
+  private requireBootConfig() {
+    if (!this.bootConfig) {
+      throw new RepzoWidgetError('RepzoWidget.boot() must be called first', 0, 'http');
+    }
+  }
+
+  // ─── Realtime ───────────────────────────────────────────────────────────
+
+  private connectRealtime(token: string) {
+    if (!this.bootConfig || this.loggedOut || this.terminalErrorCode) return;
+    // Whoever connects explicitly (init, foreground) refreshes on its own;
+    // only the stream's backoff reconnects need the catch-up.
+    this.streamConnectedOnce = false;
+    this.streamErrored = false;
+    this.realtime.connect(
+      this.bootConfig.baseUrl,
+      token,
+      (event, data) => {
+        this.handleRealtimeEvent(event, data);
+      },
+      {
+        onUnauthorized: (failedToken) => {
+          void this.reauthorizeStream(failedToken);
+        },
+        onForbidden: (error) => this.handleTerminalError(error),
+      }
+    );
+  }
+
+  /** The stream got a 401: share the single-flight re-init, then reconnect. */
+  private async reauthorizeStream(failedToken: string): Promise<void> {
+    const now = Date.now();
+    if (now - this.lastStreamReauthAt < STREAM_REAUTH_MIN_INTERVAL_MS) return;
+    this.lastStreamReauthAt = now;
+
+    const epoch = this.epoch;
+    const token = await this.reauthorize(failedToken);
+    // A fresh init already reconnected; this covers a token another caller
+    // minted just before the stream noticed.
+    if (token && !this.isStale(epoch) && !this.realtime.isConnected) {
+      this.connectRealtime(token);
+    }
+  }
+
+  private watchAppState() {
+    if (this.appStateSubscription) return;
+    this.appStateSubscription = AppState.addEventListener('change', (status: AppStateStatus) => {
+      if (status === 'active') {
+        void this.resumeFromBackground();
+      } else if (status === 'background') {
+        this.realtime.close();
+      }
+    });
+  }
+
+  private async resumeFromBackground() {
+    if (this.loggedOut || this.terminalErrorCode) return;
+    if (!this.state.booted) {
+      // A boot that failed (offline at launch, say) retries once the visitor
+      // is back — Retry stays available too.
+      if (this.state.error) await this.retry();
+      return;
+    }
+    const epoch = this.epoch;
+    const token = await this.client.getToken();
+    if (!token || this.isStale(epoch)) return;
+    this.connectRealtime(token);
+    // The stream had a gap: refresh the list so unread/snippets are correct,
+    // and the thread on screen so replies sent meanwhile show up.
+    await Promise.all([this.refreshConversations(), this.refreshOpenThread()]);
+    await this.refreshConfig();
+  }
+
+  /**
+   * Re-read the config so availability and copy do not go stale. `isOnline` is
+   * otherwise a snapshot from boot, which a long-lived app would keep showing
+   * hours after the team went offline.
+   */
+  private async refreshConfig(): Promise<void> {
+    if (!this.state.booted) return;
+    const epoch = this.epoch;
+    try {
+      const fresh = await this.client.getConfig(sessionPlatform());
+      if (!fresh || this.isStale(epoch) || !this.state.config) return;
+      // Only availability is refreshed here. The public config endpoint knows
+      // nothing about the visitor (identified vs anonymous spaces, launcher
+      // rules), so replacing the whole session config with it — as this used
+      // to — swapped the mobile design for the web one until the next init.
+      const config: WidgetConfig = {
+        ...this.state.config,
+        isOnline: fresh.isOnline,
+        ...(typeof fresh.offlineMessage === 'string' ? { offlineMessage: fresh.offlineMessage } : {}),
+      };
+      this.setState({ config });
+      this.persistConfig(config);
+    } catch {
+      // Availability stays as-is; it refreshes again on the next foreground.
+    }
+  }
+
+  private handleRealtimeEvent(event: string, data: any) {
+    if (
+      (event === 'message.new' || event === 'conversation.event') &&
+      this.shouldHoldForDraft(data?.conversationId)
+    ) {
+      this.draftEvents.push({ event, data });
+      return;
+    }
+
+    switch (event) {
+      case 'connected':
+        // The stream reconnected after a drop: anything sent while it
+        // was down never streamed, so re-read the list and the open thread.
+        if (this.streamConnectedOnce || this.streamErrored) {
+          void this.refreshConversations();
+          void this.refreshOpenThread();
+        }
+        this.streamConnectedOnce = true;
+        this.streamErrored = false;
+        break;
+
+      case 'error':
+        this.streamErrored = true;
+        break;
+
+      case 'message.new':
+        this.handleNewMessage(data);
+        break;
+
+      case 'conversation.updated':
+        this.rememberConversationAgent(data);
+        this.setState((current) => ({
+          conversations: current.conversations.map((conversation) =>
+            conversation.id === data?.conversationId
+              ? {
+                  ...conversation,
+                  agentName: data.agentName === undefined ? conversation.agentName : data.agentName,
+                  agentAvatar:
+                    data.agentAvatar === undefined
+                      ? conversation.agentAvatar
+                      : this.client.resolveUrl(data.agentAvatar),
+                }
+              : conversation
+          ),
+        }));
+        break;
+
+      case 'conversation.event':
+        this.handleConversationEvent(data);
+        break;
+
+      case 'typing.start':
+        this.rememberConversationAgent(data);
+        if (this.isThreadOnScreen(data?.conversationId)) {
+          this.setState((current) => ({
+            agentTyping: true,
+            conversations: current.conversations.map((conversation) =>
+              conversation.id === data.conversationId
+                ? this.applyConversationAgent(conversation)
+                : conversation
+            ),
+          }));
+          this.scheduleTypingClear(TYPING_CLEAR_MS);
+        }
+        break;
+
+      case 'typing.stop':
+        if (this.isThreadOnScreen(data?.conversationId)) {
+          this.scheduleTypingClear(TYPING_SETTLE_MS);
+        }
+        break;
+
+      default:
+        break;
+    }
+  }
+
+  /**
+   * The thread the visitor is looking at right now — the only one live
+   * messages, typing and events may paint into. The `isOpen` guard matters on
+   * mobile: the widget spends most of its life closed, and a stale
+   * `view === 'chat'` would otherwise swallow the unread increment. A blank
+   * draft matches nothing; its thread is adopted once the first send answers.
+   */
+  private isThreadOnScreen(conversationId?: string | null): boolean {
+    if (!conversationId) return false;
+    return (
+      this.state.isOpen &&
+      this.state.view === 'chat' &&
+      this.state.activeConversationId === conversationId
+    );
+  }
+
+  /**
+   * While a draft's first send is in flight its conversation id is unknown,
+   * and the server may already stream the thread's first reply (or an "agent
+   * joined" event). Events for a thread this device doesn't know are held
+   * until the send answers, then replayed: into the draft if it is that
+   * thread, otherwise as ordinary unread traffic.
+   */
+  private shouldHoldForDraft(conversationId?: string | null): boolean {
+    const creation = this.conversationCreation;
+    return (
+      !!conversationId &&
+      !!creation &&
+      creation.generation === this.threadGeneration &&
+      !this.state.activeConversationId &&
+      !this.state.conversations.some((conversation) => conversation.id === conversationId) &&
+      this.draftEvents.length < DRAFT_EVENT_BUFFER_LIMIT
+    );
+  }
+
+  private replayDraftEvents(): void {
+    const held = this.draftEvents;
+    this.draftEvents = [];
+    held.forEach(({ event, data }) => this.handleRealtimeEvent(event, data));
+  }
+
+  private persistUnread(map: Record<string, number>): void {
+    void Storage.setItem(UNREAD_KEY, JSON.stringify(map));
+  }
+
+  /** Survives a relaunch so a reply received overnight is still marked unread. */
+  private async loadUnread(): Promise<Record<string, number>> {
+    const raw = await Storage.getItem(UNREAD_KEY);
+    if (!raw) return {};
+    try {
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== 'object') return {};
+      const result: Record<string, number> = {};
+      for (const [id, count] of Object.entries(parsed as Record<string, unknown>)) {
+        if (typeof count === 'number' && count > 0) result[id] = count;
+      }
+      return result;
+    } catch {
+      return {};
+    }
+  }
+
+  private clearUnreadFor(conversationId: string): Record<string, number> {
+    if (!this.state.unreadByConversation[conversationId]) {
+      return this.state.unreadByConversation;
+    }
+    const next = { ...this.state.unreadByConversation };
+    delete next[conversationId];
+    this.persistUnread(next);
+    return next;
+  }
+
+  // Real server ids only: the synthetic `sse-<now>` fallback is never a replay.
+  private isReplayedMessage(messageId?: string): boolean {
+    if (!messageId) return false;
+    if (this.seenMessageIds.includes(messageId)) return true;
+    this.seenMessageIds.push(messageId);
+    if (this.seenMessageIds.length > SEEN_MESSAGE_LIMIT) this.seenMessageIds.shift();
+    return false;
+  }
+
+  private handleNewMessage(data: any) {
+    if (this.isReplayedMessage(data?.messageId)) return;
+
+    // The server id is what history pages and catch-up fetches carry, so it
+    // is what dedupes; the synthetic id only covers an older server.
+    const messageId: string =
+      data?.messageId || `sse-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const message: Message = {
+      id: messageId,
+      messageType: data?.messageType || 'message',
+      direction: data?.direction || 'outbound',
+      senderType: data?.senderType || 'agent',
+      senderName: data?.senderName || null,
+      body: data?.body || null,
+      bodyPlain: data?.bodyPlain || null,
+      attachments: this.hydrateAttachments(data?.attachments, messageId),
+      metadata: data?.metadata || null,
+      status: 'delivered',
+      createdAt: data?.createdAt || new Date().toISOString(),
+    };
+
+    const clearsTyping = message.direction === 'outbound' && message.senderType !== 'visitor';
+    if (clearsTyping) this.clearTypingTimer();
+
+    const conversationId: string | undefined = data?.conversationId;
+    // Only real replies from the team count: never the visitor's own echo,
+    // never system rows like "agent joined" (the server counts the same way).
+    const isTeamReply =
+      message.messageType === 'message' &&
+      message.direction !== 'inbound' &&
+      message.senderType !== 'visitor';
+    const onScreen = this.isThreadOnScreen(conversationId);
+
+    // Set inside the updater, read after: `setState` runs synchronously.
+    let countedAsUnread = false;
+
+    this.setState((current) => {
+      const conversations = conversationId
+        ? current.conversations.map((conversation) =>
+            conversation.id === conversationId
+              ? {
+                  ...conversation,
+                  snippet:
+                    message.messageType === 'message'
+                      ? message.bodyPlain || conversation.snippet
+                      : conversation.snippet,
+                  lastMessageAt: message.createdAt,
+                  messageCount: conversation.messageCount + 1,
+                }
+              : conversation
+          )
+        : current.conversations;
+
+      if (onScreen) {
+        const alreadyPresent = current.messages.some((existing) => existing.id === message.id);
+        return {
+          conversations,
+          messages: alreadyPresent ? current.messages : [...current.messages, message],
+          agentTyping: clearsTyping ? false : current.agentTyping,
+        };
+      }
+
+      if (!isTeamReply || !conversationId) return { conversations };
+
+      const unreadByConversation = {
+        ...current.unreadByConversation,
+        [conversationId]: (current.unreadByConversation[conversationId] ?? 0) + 1,
+      };
+      this.persistUnread(unreadByConversation);
+
+      countedAsUnread = true;
+      return { conversations, unreadByConversation };
+    });
+
+    // The visitor is reading it live — move the server cursor too, or the
+    // next list/init would badge a reply they already saw.
+    if (onScreen && isTeamReply && conversationId) this.scheduleMarkRead(conversationId);
+
+    // Emitted after the state write so a listener reading the unread count sees
+    // the new value. Only unread-counting replies fire it, which keeps the event
+    // in step with the badge: never the visitor's own echo, never a system row,
+    // never the open thread.
+    if (countedAsUnread && conversationId) {
+      this.events.emit(RepzoWidgetEvents.MessageDidArrive, {
+        conversationId,
+        message,
+        conversation: this.state.conversations.find((item) => item.id === conversationId) ?? null,
+      });
+    }
+
+    // A reply can arrive for a conversation this device has never listed.
+    if (conversationId && !this.state.conversations.some((item) => item.id === conversationId)) {
+      void this.refreshConversations();
+    }
+  }
+
+  /** Trailing debounce: one read call per burst of live replies. */
+  private scheduleMarkRead(conversationId: string): void {
+    if (this.readTimer && this.readConversationId !== conversationId) this.flushMarkRead();
+    this.readConversationId = conversationId;
+    if (this.readTimer) clearTimeout(this.readTimer);
+    this.readTimer = setTimeout(() => this.flushMarkRead(), MARK_READ_DEBOUNCE_MS);
+  }
+
+  /** Best effort and never re-inits — a missed cursor move only costs a badge. */
+  private flushMarkRead(): void {
+    const conversationId = this.readConversationId;
+    this.cancelMarkRead();
+    if (!conversationId || !this.state.booted || this.loggedOut || this.terminalErrorCode) return;
+    this.client.markConversationRead(conversationId).catch(() => {});
+  }
+
+  private cancelMarkRead(): void {
+    if (this.readTimer) clearTimeout(this.readTimer);
+    this.readTimer = null;
+    this.readConversationId = null;
+  }
+
+  private handleConversationEvent(data: any) {
+    if (!data?.conversationId) return;
+
+    const message: Message = {
+      id: data.eventId || `event-${data.conversationId}-${Date.now()}`,
+      messageType: 'system',
+      direction: 'outbound',
+      senderType: 'system',
+      senderName: null,
+      body: null,
+      bodyPlain: data.bodyPlain || 'Conversation updated',
+      attachments: null,
+      metadata: data.metadata || null,
+      status: 'delivered',
+      createdAt: data.createdAt || new Date().toISOString(),
+    };
+
+    if (!this.isThreadOnScreen(data.conversationId)) return;
+    this.setState((current) =>
+      current.messages.some((existing) => existing.id === message.id)
+        ? {}
+        : { messages: [...current.messages, message] }
+    );
+  }
+
+  private rememberConversationAgent(data: any) {
+    if (!data?.conversationId) return;
+    if (data.agentName === undefined && data.agentAvatar === undefined) return;
+    this.pendingAgentByConversation[data.conversationId] = {
+      agentName: data.agentName ?? null,
+      agentAvatar: this.client.resolveUrl(data.agentAvatar ?? null),
+    };
+  }
+
+  private applyConversationAgent(conversation: Conversation): Conversation {
+    const pending = this.pendingAgentByConversation[conversation.id];
+    if (!pending) return conversation;
+    return {
+      ...conversation,
+      agentName: pending.agentName ?? conversation.agentName,
+      agentAvatar: pending.agentAvatar ?? conversation.agentAvatar,
+    };
+  }
+
+  private hydrateConversation(conversation: Conversation): Conversation {
+    return this.applyConversationAgent({
+      ...conversation,
+      agentAvatar: this.client.resolveUrl(conversation.agentAvatar),
+    });
+  }
+
+  /**
+   * Normalizes attachments from history pages and live payloads alike. Live
+   * payloads may omit `id`/`size`, so the list still gets a stable key.
+   */
+  private hydrateAttachments(attachments: unknown, messageId?: string): WidgetAttachment[] | null {
+    if (!Array.isArray(attachments) || attachments.length === 0) return null;
+    const hydrated = attachments
+      .filter((item): item is Record<string, unknown> => !!item && typeof item === 'object')
+      .map((attachment, index) => ({
+        ...attachment,
+        id:
+          typeof attachment.id === 'string' || typeof attachment.id === 'number'
+            ? String(attachment.id)
+            : `${messageId ?? 'attachment'}-${index}`,
+        name:
+          typeof attachment.name === 'string' && attachment.name ? attachment.name : 'Attachment',
+        contentType: typeof attachment.contentType === 'string' ? attachment.contentType : '',
+        size: typeof attachment.size === 'number' ? attachment.size : 0,
+        // Empty (never the raw value) when the URL isn't http(s) — the preview
+        // then renders the name only, with nothing to open.
+        url:
+          this.client.resolveUrl(typeof attachment.url === 'string' ? attachment.url : null) ?? '',
+      }));
+    return hydrated.length > 0 ? hydrated : null;
+  }
+
+  private clearTypingTimer() {
+    if (this.typingTimer) {
+      clearTimeout(this.typingTimer);
+      this.typingTimer = null;
+    }
+    if (this.state.agentTyping) this.setState({ agentTyping: false });
+  }
+
+  private scheduleTypingClear(delayMs: number) {
+    if (this.typingTimer) clearTimeout(this.typingTimer);
+    this.typingTimer = setTimeout(() => {
+      this.typingTimer = null;
+      this.setState({ agentTyping: false });
+    }, delayMs);
+  }
+
+  // ─── UI commands ────────────────────────────────────────────────────────
+
+  private resolveOpenView(space?: WidgetSpaceType): WidgetView {
+    const { config, conversations } = this.state;
+    const launchDirectly = config?.launchDirectly ?? false;
+    const enabled = (config?.spaces ?? []).filter((item) => item.enabled);
+    const target =
+      space ?? (launchDirectly ? 'messages' : (firstEnabledSpace(config?.spaces) ?? 'home'));
+
+    if (target === 'messages') {
+      if (conversations.length > 0) return 'conversations';
+      return config?.allowNewConversations === false ? 'conversations' : 'chat';
+    }
+    if (enabled.length > 0 && !enabled.some((item) => item.type === 'home')) return 'conversations';
+    return 'home';
+  }
+
+  present(space?: WidgetSpaceType): void {
+    if (!this.bootConfig) {
+      console.warn('[repzo-widget] present() ignored — RepzoWidget.boot() has not been called');
+      return;
+    }
+    const view = this.resolveOpenView(space);
+    // A fresh "start a conversation" landing must not reuse an old thread.
+    if (view === 'chat') this.threadGeneration += 1;
+    this.setState({
+      isOpen: true,
+      view,
+      activeTab: view === 'home' ? 'home' : 'messages',
+      ...(view === 'chat'
+        ? {
+            activeConversationId: null,
+            messages: [],
+            messagesLoading: false,
+            hasMoreMessages: false,
+            messageCursor: null,
+          }
+        : {}),
+    });
+    this.track('widget_opened');
+  }
+
+  hide(): void {
+    if (!this.state.isOpen) return;
+    this.setState({ isOpen: false, view: 'bubble', agentTyping: false });
+    this.clearTypingTimer();
+    this.track('widget_closed');
+  }
+
+  toggle(space?: WidgetSpaceType): void {
+    if (this.state.isOpen) this.hide();
+    else this.present(space);
+  }
+
+  setView(view: WidgetView): void {
+    this.setState({
+      view,
+      ...(view === 'chat' || view === 'conversations'
+        ? { activeTab: 'messages' as WidgetSpaceType }
+        : {}),
+      ...(view === 'home' ? { activeTab: 'home' as WidgetSpaceType } : {}),
+    });
+  }
+
+  setActiveTab(tab: WidgetSpaceType): void {
+    if (tab === 'home') {
+      this.setState({ activeTab: 'home', view: 'home' });
+      return;
+    }
+    if (this.state.conversations.length > 0) {
+      this.setState({ activeTab: 'messages', view: 'conversations' });
+    } else if (this.state.config?.allowNewConversations === false) {
+      this.setState({ activeTab: 'messages', view: 'conversations' });
+    } else {
+      this.startNewConversation();
+    }
+  }
+
+  setLocale(locale: string): void {
+    this.setState({ locale });
+  }
+
+  startNewConversation(prefill?: string): void {
+    this.threadGeneration += 1;
+    this.setState((current) => ({
+      isOpen: true,
+      activeTab: 'messages',
+      activeConversationId: null,
+      messages: [],
+      // A load still in flight for the previous thread is dropped on arrival.
+      messagesLoading: false,
+      hasMoreMessages: false,
+      messageCursor: null,
+      agentTyping: false,
+      view: current.config?.preChatEnabled ? 'prechat' : 'chat',
+      prefillText: prefill ?? '',
+    }));
+  }
+
+  setPrefillText(prefill: string): void {
+    this.setState({ prefillText: prefill });
+  }
+
+  dismissOutboundMessage(): void {
+    const outbound = this.state.outboundMessage;
+    if (outbound?.id) this.track('widget_outbound_dismissed', { outboundId: outbound.id });
+    this.setState({ outboundMessage: null });
+  }
+
+  // ─── Conversations & messages ───────────────────────────────────────────
+
+  async refreshConversations(): Promise<void> {
+    if (!this.state.booted) return;
+    const epoch = this.epoch;
+    try {
+      const result = await this.client.listConversations();
+      // Never repaint a signed-out (or switched) visitor's list.
+      if (this.isStale(epoch)) return;
+      this.setState((current) => {
+        // Reconcile unread with the server so replies that arrived during a
+        // background gap still count (same rule as the boot-time seeding).
+        const unreadByConversation: Record<string, number> = {};
+        for (const conversation of result.data) {
+          const count =
+            typeof conversation.unreadCount === 'number'
+              ? conversation.unreadCount
+              : (current.unreadByConversation[conversation.id] ?? 0);
+          if (count > 0) unreadByConversation[conversation.id] = count;
+        }
+        // The thread on screen is being read right now — never re-badge it.
+        if (current.activeConversationId && this.isThreadOnScreen(current.activeConversationId)) {
+          delete unreadByConversation[current.activeConversationId];
+        }
+        this.persistUnread(unreadByConversation);
+        return {
+          conversations: result.data.map((conversation) => this.hydrateConversation(conversation)),
+          unreadByConversation,
+        };
+      });
+    } catch {
+      // Keep whatever we already have — the list refreshes again on next open.
+    }
+  }
+
+  async openConversation(conversationId: string): Promise<void> {
+    this.threadGeneration += 1;
+    if (!this.state.booted) {
+      this.pendingConversationId = conversationId;
+      this.setState({ isOpen: true, activeTab: 'messages' });
+      return;
+    }
+
+    const generation = this.threadGeneration;
+    const unreadByConversation = this.clearUnreadFor(conversationId);
+    this.setState({
+      isOpen: true,
+      activeTab: 'messages',
+      activeConversationId: conversationId,
+      messages: [],
+      messagesLoading: true,
+      hasMoreMessages: false,
+      messageCursor: null,
+      view: 'chat',
+      unreadByConversation,
+      agentTyping: false,
+    });
+    // Loading the thread advances the server-side read cursor; hosts listen
+    // to this to dismiss the conversation's push notification from the tray.
+    this.events.emit(RepzoWidgetEvents.ConversationDidRead, { conversationId });
+
+    const epoch = this.epoch;
+    try {
+      const result = await this.client.listMessages(conversationId);
+      // Opening A then B quickly: A's page must never land under B.
+      if (this.isStale(epoch) || this.threadGeneration !== generation) return;
+      this.setState((current) => {
+        // Live replies and optimistic sends may have arrived since this page
+        // was requested. Keep them, preferring the live copy for shared ids.
+        const liveIds = new Set(current.messages.map((message) => message.id));
+        const history = this.hydrateMessages(result.data).filter(
+          (message) => !liveIds.has(message.id)
+        );
+        return {
+          messages: sortByCreatedAt([...history, ...current.messages]),
+          messagesLoading: false,
+          hasMoreMessages: result.meta.hasMore,
+          messageCursor: result.meta.nextCursor,
+        };
+      });
+    } catch {
+      if (!this.isStale(epoch) && this.threadGeneration === generation) {
+        this.setState({ messagesLoading: false });
+      }
+    }
+  }
+
+  async loadMoreMessages(): Promise<void> {
+    const { activeConversationId, hasMoreMessages, messagesLoading, messageCursor } = this.state;
+    if (!activeConversationId || !hasMoreMessages || messagesLoading || !messageCursor) return;
+
+    this.setState({ messagesLoading: true });
+    const epoch = this.epoch;
+    const generation = this.threadGeneration;
+    const isCurrent = () =>
+      !this.isStale(epoch) &&
+      this.threadGeneration === generation &&
+      this.state.activeConversationId === activeConversationId;
+    try {
+      const result = await this.client.listMessages(activeConversationId, messageCursor);
+      // An older page for a thread that is no longer on screen goes nowhere.
+      if (!isCurrent()) return;
+      this.setState((current) => {
+        const known = new Set(current.messages.map((message) => message.id));
+        const older = this.hydrateMessages(result.data).filter((message) => !known.has(message.id));
+        return {
+          messages: [...older, ...current.messages],
+          messagesLoading: false,
+          hasMoreMessages: result.meta.hasMore,
+          messageCursor: result.meta.nextCursor,
+        };
+      });
+    } catch {
+      if (isCurrent()) this.setState({ messagesLoading: false });
+    }
+  }
+
+  /**
+   * Re-reads the newest page of the thread on screen and merges in whatever
+   * the stream missed (reconnect, foreground, re-init). Deduped by server id.
+   * Only for a thread actually on screen: the first page also advances the
+   * server read cursor, which must not happen for a thread nobody is reading.
+   */
+  private async refreshOpenThread(): Promise<void> {
+    const conversationId = this.state.activeConversationId;
+    if (!this.state.booted || !conversationId || !this.isThreadOnScreen(conversationId)) return;
+    // A load already in flight owns the list (and its cursor) — let it land.
+    if (this.state.messagesLoading) return;
+
+    const epoch = this.epoch;
+    const generation = this.threadGeneration;
+    try {
+      const result = await this.client.listMessages(conversationId);
+      if (this.isStale(epoch) || this.threadGeneration !== generation) return;
+      if (this.state.activeConversationId !== conversationId) return;
+
+      const fresh = this.hydrateMessages(result.data);
+      this.setState((current) => {
+        const known = new Set(current.messages.map((message) => message.id));
+        const missing = fresh.filter((message) => !known.has(message.id));
+        if (missing.length === 0) return {};
+
+        const local = current.messages.filter(isLocalMessage);
+        const hasServerMessages = local.length < current.messages.length;
+        // No overlap means the gap is longer than a page: restart from the
+        // newest page (keeping unsent bubbles) rather than leave a hole.
+        if (missing.length === fresh.length || !hasServerMessages) {
+          return {
+            messages: [...fresh, ...local],
+            hasMoreMessages: result.meta.hasMore,
+            messageCursor: result.meta.nextCursor,
+          };
+        }
+        return { messages: sortByCreatedAt([...current.messages, ...missing]) };
+      });
+      // The server just moved the read cursor — mirror it locally.
+      if (this.state.unreadByConversation[conversationId]) {
+        this.setState({ unreadByConversation: this.clearUnreadFor(conversationId) });
+      }
+    } catch {
+      // The next reconnect or foreground tries again.
+    }
+  }
+
+  /** A history page (newest-first) as the oldest-first list the UI renders. */
+  private hydrateMessages(page: Message[]): Message[] {
+    return page
+      .map((message) => ({
+        ...message,
+        attachments: this.hydrateAttachments(message.attachments, message.id),
+      }))
+      .reverse();
+  }
+
+  async sendMessage(
+    body: string,
+    attachments: WidgetAttachment[] = [],
+    agentUiAction?: AgentUiAction
+  ): Promise<void> {
+    const trimmed = body.trim();
+    if (!trimmed && attachments.length === 0) return;
+
+    const { visitorProfile } = this.state;
+    const generation = this.threadGeneration;
+    const tempId = `temp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const optimistic: Message = {
+      id: tempId,
+      messageType: 'message',
+      direction: 'inbound',
+      senderType: 'visitor',
+      senderName: visitorProfile.name || 'You',
+      body: trimmed ? `<p>${trimmed}</p>` : '',
+      bodyPlain: trimmed,
+      attachments: attachments.length > 0 ? attachments : null,
+      metadata: null,
+      status: 'pending',
+      createdAt: new Date().toISOString(),
+    };
+
+    this.setState((current) => ({
+      messages: [...current.messages, optimistic],
+      prefillText: '',
+    }));
+    this.track('widget_message_sent', {
+      hasText: !!trimmed,
+      attachmentCount: attachments.length,
+    });
+
+    const markFailed = () =>
+      this.setState((current) => ({
+        messages: current.messages.map((message) =>
+          message.id === tempId ? { ...message, status: 'failed' } : message
+        ),
+      }));
+
+    const epoch = this.epoch;
+
+    // A draft's first send creates the conversation. Anything sent from the
+    // same draft before that POST answers waits for its id rather than
+    // creating a second thread; the bubble is already on screen meanwhile.
+    let conversationId = this.state.activeConversationId;
+    let ownCreation: ConversationCreation | null = null;
+    while (!conversationId) {
+      const creation = this.conversationCreation;
+      if (!creation || creation.generation !== generation) {
+        ownCreation = createConversationCreation(generation);
+        this.conversationCreation = ownCreation;
+        break;
+      }
+      conversationId = await creation.promise;
+      if (this.isStale(epoch)) return;
+      // The creating send failed and the visitor has since left the draft:
+      // don't open a thread nobody is looking at.
+      if (!conversationId && this.threadGeneration !== generation) {
+        markFailed();
+        return;
+      }
+    }
+
+    let createdId: string | null = null;
+    try {
+      const result = await this.client.sendMessage({
+        conversationId: conversationId || undefined,
+        forceNewConversation: !conversationId,
+        body: trimmed,
+        attachments: attachments.length > 0 ? attachments : undefined,
+        visitorName: visitorProfile.name,
+        visitorEmail: visitorProfile.email,
+        agentUiAction,
+      });
+      if (this.isStale(epoch)) return;
+      if (ownCreation) createdId = result.conversationId;
+
+      this.setState((current) => {
+        // The stream or a catch-up fetch may have delivered this message
+        // already — keep one copy, never two bubbles with the same id.
+        const delivered = current.messages.some((message) => message.id === result.messageId);
+        const messages = delivered
+          ? current.messages.filter((message) => message.id !== tempId)
+          : current.messages.map((message) =>
+              message.id === tempId ? { ...message, id: result.messageId, status: 'sent' } : message
+            );
+
+        if (!createdId) return { messages };
+
+        const known = current.conversations.some((item) => item.id === result.conversationId);
+        const conversation: Conversation = {
+          id: result.conversationId,
+          subject: null,
+          status: 'open',
+          snippet: trimmed
+            ? trimmed.slice(0, 100)
+            : `${attachments.length} attachment${attachments.length === 1 ? '' : 's'}`,
+          messageCount: 1,
+          lastMessageAt: new Date().toISOString(),
+          createdAt: new Date().toISOString(),
+          agentName: null,
+          agentAvatar: null,
+        };
+
+        return {
+          messages,
+          conversations: known
+            ? current.conversations
+            : [this.applyConversationAgent(conversation), ...current.conversations],
+          // Only adopt the thread if the visitor is still on this draft.
+          ...(this.threadGeneration === generation
+            ? { activeConversationId: result.conversationId }
+            : {}),
+        };
+      });
+    } catch (error) {
+      if (this.isStale(epoch)) throw error;
+      markFailed();
+      throw error;
+    } finally {
+      if (ownCreation) {
+        if (this.conversationCreation === ownCreation) this.conversationCreation = null;
+        // Resolves null on failure: the next queued send then creates it.
+        ownCreation.resolve(createdId);
+        // Anything held back for the draft now has a home (or goes to unread).
+        this.replayDraftEvents();
+      }
+    }
+  }
+
+  async identifyVisitor(data: { email?: string; name?: string; phone?: string }): Promise<void> {
+    this.setState((current) => ({
+      visitorProfile: {
+        ...current.visitorProfile,
+        ...(data.name ? { name: data.name } : {}),
+        ...(data.email ? { email: data.email } : {}),
+        ...(data.phone ? { phone: data.phone } : {}),
+      },
+    }));
+    await this.client.identify(data);
+  }
+
+  /** Fire-and-forget visitor typing ping, throttled well under the 30/min cap. */
+  notifyTyping(isTyping: boolean): void {
+    const conversationId = this.state.activeConversationId;
+    if (!conversationId) return;
+
+    const now = Date.now();
+    if (isTyping) {
+      if (now - this.lastTypingPingAt < TYPING_PING_INTERVAL_MS) return;
+      this.lastTypingPingAt = now;
+    } else {
+      // Nothing to stop — skip the round trip rather than burn rate limit.
+      if (!this.visitorTypingActive) return;
+      this.lastTypingPingAt = 0;
+    }
+    this.visitorTypingActive = isTyping;
+
+    this.client.sendTyping(conversationId, isTyping).catch(() => {});
+  }
+
+  // ─── Analytics & outbound ───────────────────────────────────────────────
+
+  track(event: string, metadata: Record<string, unknown> = {}): void {
+    if (!this.state.booted || this.state.config?.analyticsEnabled === false) return;
+    this.client
+      .trackEvent({
+        event,
+        visitorId: this.state.identityId,
+        metadata: { locale: this.state.locale, platform: Platform.OS, ...metadata },
+      })
+      .catch(() => {});
+  }
+
+  private loadOutboundMessage(): void {
+    if (this.state.outboundMessage) return;
+    const epoch = this.epoch;
+    this.client
+      .getOutboundMessage()
+      .then(({ message }) => {
+        if (!message || this.isStale(epoch)) return;
+        this.setState({
+          outboundMessage: {
+            ...message,
+            imageUrl: this.client.resolveUrl(message.imageUrl) ?? undefined,
+          },
+        });
+      })
+      .catch(() => {});
+  }
+
+  // ─── Teardown (tests / hot reload) ──────────────────────────────────────
+
+  destroy(): void {
+    this.realtime.close();
+    this.clearTypingTimer();
+    this.resetThreadTracking();
+    this.appStateSubscription?.remove();
+    this.appStateSubscription = null;
+    this.subscribers.clear();
+    this.events.removeAllListeners();
+  }
+}
+
+interface ConversationCreation {
+  /** The draft (thread generation) whose first send is creating it. */
+  generation: number;
+  /** The new conversation's id, or null when the creating send failed. */
+  promise: Promise<string | null>;
+  resolve: (conversationId: string | null) => void;
+}
+
+function createConversationCreation(generation: number): ConversationCreation {
+  let resolve: (conversationId: string | null) => void = () => {};
+  const promise = new Promise<string | null>((settle) => {
+    resolve = settle;
+  });
+  return { generation, promise, resolve };
+}
+
+/** Optimistic visitor bubbles the server hasn't acknowledged (pending/failed). */
+function isLocalMessage(message: Message): boolean {
+  return message.id.startsWith('temp-');
+}
+
+/** Stable, so same-instant rows keep their order; bad dates sort as oldest. */
+function sortByCreatedAt(messages: Message[]): Message[] {
+  const time = (message: Message) => Date.parse(message.createdAt) || 0;
+  return [...messages].sort((a, b) => time(a) - time(b));
+}
+
+function identityKey(user: WidgetUser): string {
+  return (user.email || user.userId || '').toLowerCase().trim();
+}
+
+/**
+ * The visitor token travels on every request, so plain http is refused except
+ * for local development: localhost, the Android emulator's host alias,
+ * `*.local` hosts, or any host in a `__DEV__` build.
+ */
+function assertSecureBaseUrl(baseUrl: string): string {
+  const match = /^(https?):\/\/(\[[^\]]+\]|[^/?#:]+)(?::\d+)?(?:[/?#]|$)/i.exec(baseUrl);
+  if (!match) {
+    throw new RepzoWidgetError(
+      `boot(): baseUrl must be an absolute https:// URL (got "${baseUrl}")`,
+      0,
+      'http'
+    );
+  }
+  const scheme = match[1].toLowerCase();
+  const host = match[2].toLowerCase();
+  if (scheme === 'https') return baseUrl;
+
+  const isDevBuild = typeof __DEV__ !== 'undefined' && __DEV__;
+  if (isDevBuild || LOCAL_DEV_HOSTS.has(host) || host.endsWith('.local')) return baseUrl;
+  throw new RepzoWidgetError(
+    `boot(): baseUrl must use https:// (got "${baseUrl}"). Plain http is only allowed for ` +
+      'localhost, 127.0.0.1, 10.0.2.2, *.local hosts, or in __DEV__ builds.',
+    0,
+    'http'
+  );
+}
+
+/** Waits for `promise` at most `ms`; never rejects. */
+function settleWithin(promise: Promise<unknown>, ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    const done = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    promise.then(done, done);
+  });
+}
+
+function firstEnabledSpace(
+  spaces: Array<{ type: WidgetSpaceType; enabled: boolean }> | undefined
+): WidgetSpaceType | null {
+  return spaces?.find((space) => space.enabled)?.type ?? null;
+}
+
+/** The server rejects oversized bags; drop junk here so a typo can't 400 a login. */
+function sanitizeAttributes(attributes: WidgetCustomAttributes): WidgetCustomAttributes {
+  const result: WidgetCustomAttributes = {};
+  if (!attributes || typeof attributes !== 'object') return result;
+
+  for (const [key, value] of Object.entries(attributes)) {
+    if (!key || key.length > 64) continue;
+    if (value === null || value === undefined) continue;
+    if (typeof value === 'string') {
+      if (!value.trim()) continue;
+      result[key] = value.slice(0, 512);
+    } else if (typeof value === 'number') {
+      if (!Number.isFinite(value)) continue;
+      result[key] = value;
+    } else if (typeof value === 'boolean') {
+      result[key] = value;
+    }
+    if (Object.keys(result).length >= 30) break;
+  }
+  return result;
+}