@repzo/widget-react-native 1.0.0

package/lib/commonjs/state/widget-store.js

@@ -0,0 +1,1682 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.WidgetStore = void 0;
+var _reactNative = require("react-native");
+var _client = require("../api/client.js");
+var _realtime = require("../api/realtime.js");
+var _deviceId = require("../device-id.js");
+var _events = require("../events.js");
+var _pushNotifications = require("../push/push-notifications.js");
+var _storage = require("../storage.js");
+var _types = require("../types.js");
+var _safeUrl = require("../ui/utils/safe-url.js");
+/**
+ * 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.
+ */
+
+const SDK_VERSION = '@repzo/widget-react-native@1.0.0';
+
+/** The platform this session reports — mobile sessions get the Mobile SDKs overrides. */
+function sessionPlatform() {
+  return _reactNative.Platform.OS === 'ios' || _reactNative.Platform.OS === 'android' ? _reactNative.Platform.OS : 'web';
+}
+
+/** CONFIG_KEY entry: the session config plus where it came from. */
+
+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 => Object.values(map).reduce((sum, count) => sum + count, 0);
+const INITIAL_STATE = {
+  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 = {
+  // 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: {}
+};
+class WidgetStore {
+  client = new _client.WidgetApiClient();
+  events = new _events.EventEmitter();
+  push = new _pushNotifications.PushManager(this.client, conversationId => {
+    void this.openConversation(conversationId);
+  });
+  state = INITIAL_STATE;
+  subscribers = new Set();
+  realtime = new _realtime.WidgetRealtime();
+  typingTimer = null;
+  pendingAgentByConversation = {};
+  bootConfig = null;
+  bootPromise = null;
+
+  /** Identity key of the in-flight boot — a boot for someone else is not deduped. */
+  bootingUserKey = null;
+  currentUser = null;
+
+  /** Who the stored token was issued to; null = anonymous. */
+  currentUserKey = null;
+
+  /** True once `currentUserKey` mirrors storage — memory is then authoritative. */
+  userKeyLoaded = false;
+  pendingConversationId = null;
+  appStateSubscription = null;
+  lastTypingPingAt = 0;
+  visitorTypingActive = false;
+  seenMessageIds = [];
+
+  /**
+   * 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.
+   */
+  epoch = 0;
+
+  /** Serializes identity ops (and 401 re-inits) — one init or wipe at a time. */
+  identityQueue = Promise.resolve();
+
+  /** Shared by concurrent 401s: one re-init, not one per failed request. */
+  reauthPromise = null;
+
+  /** Set by logout(); blocks 401 re-init and realtime until the next boot/login. */
+  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.
+   */
+  wiping = false;
+
+  /** Set by a terminal 403 — stops realtime and re-init until a successful init. */
+  terminalErrorCode = null;
+  lastStreamReauthAt = 0;
+
+  /** Queued/running boot, login and logout ops — Retry must not cut in. */
+  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.
+   */
+  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.
+   */
+  conversationCreation = null;
+
+  /** Live events for a thread that may be the one the draft is creating. */
+  draftEvents = [];
+
+  /** False until this stream's first `connected`; later ones are reconnects. */
+  streamConnectedOnce = false;
+
+  /** The stream errored before its first `connected` — that one is a reconnect too. */
+  streamErrored = false;
+  readTimer = null;
+  readConversationId = null;
+  constructor() {
+    this.client.reauthorize = failedToken => this.reauthorize(failedToken);
+    this.client.onTerminalError = error => this.handleTerminalError(error);
+  }
+
+  // ─── Subscription plumbing ──────────────────────────────────────────────
+
+  subscribe = listener => {
+    this.subscribers.add(listener);
+    return () => {
+      this.subscribers.delete(listener);
+    };
+  };
+  getState = () => this.state;
+  setState(patch) {
+    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(_events.RepzoWidgetEvents.UnreadCountDidChange, {
+        count: next.unreadCount
+      });
+    }
+    if (next.isOpen !== previous.isOpen) {
+      this.events.emit(next.isOpen ? _events.RepzoWidgetEvents.WindowDidShow : _events.RepzoWidgetEvents.WindowDidHide, undefined);
+    }
+    this.subscribers.forEach(listener => listener());
+  }
+
+  // ─── Identity queue ─────────────────────────────────────────────────────
+
+  serialize(op) {
+    const run = this.identityQueue.then(op);
+    this.identityQueue = run.catch(() => {});
+    return run;
+  }
+
+  /** Queue a requested identity op; anything older becomes stale right away. */
+  enqueueIdentity(op) {
+    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;
+    });
+  }
+  isStale(epoch) {
+    return epoch !== this.epoch;
+  }
+
+  // ─── Boot / identity ────────────────────────────────────────────────────
+
+  async boot(options) {
+    if (!options?.channelAccountId) {
+      throw new _client.RepzoWidgetError('boot() requires channelAccountId', 0, 'http');
+    }
+    const baseUrl = assertSecureBaseUrl(options.baseUrl?.trim() || _types.DEFAULT_BASE_URL);
+    if (options.onOpenUrl !== undefined) (0, _safeUrl.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 = 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 _client.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;
+  }
+  userChanged(user) {
+    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.
+   */
+  async establishSession(user, epoch) {
+    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
+    });
+  }
+  async runInit(params) {
+    this.setState({
+      loading: true,
+      error: null,
+      errorCode: null
+    });
+    try {
+      await this.initSession(params);
+    } catch (error) {
+      if (!this.isStale(params.epoch)) {
+        if (error instanceof _client.RepzoWidgetError && (0, _client.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 _client.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. */
+  async initSession(params) {
+    const {
+      user,
+      epoch
+    } = params;
+    const trackingVisitorId = await (0, _deviceId.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 = 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 ? _storage.SecureStorage.setItem(_storage.USER_KEY, userKey) : _storage.SecureStorage.removeItem(_storage.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 = {};
+    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.
+   */
+  async seedCachedConfig() {
+    try {
+      void _storage.Storage.removeItem(_storage.LEGACY_CONFIG_KEY);
+      const raw = await _storage.Storage.getItem(_storage.CONFIG_KEY);
+      if (!raw || this.state.config) return;
+      const cached = JSON.parse(raw);
+      // 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.
+    }
+  }
+  persistConfig(config) {
+    if (!this.bootConfig) return;
+    const entry = {
+      v: 2,
+      baseUrl: this.bootConfig.baseUrl,
+      channelAccountId: this.bootConfig.channelAccountId,
+      platform: sessionPlatform(),
+      config
+    };
+    try {
+      void _storage.Storage.setItem(_storage.CONFIG_KEY, JSON.stringify(entry));
+    } catch {
+      // Cache miss next launch at worst.
+    }
+  }
+  async storedUserKey() {
+    if (this.userKeyLoaded) return this.currentUserKey;
+    const stored = await _storage.SecureStorage.getItem(_storage.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.
+   */
+  reauthorize(failedToken) {
+    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 = 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`). */
+  handleTerminalError(error) {
+    this.terminalErrorCode = error.code;
+    this.realtime.close();
+    this.setState({
+      loading: false,
+      error: error.message,
+      errorCode: error.code
+    });
+  }
+  async loginUnidentifiedUser() {
+    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) {
+    this.requireBootConfig();
+    if (!user?.userId && !user?.email) {
+      throw new _client.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) {
+    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() {
+    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).
+   */
+  async wipeSession() {
+    this.wiping = true;
+    try {
+      await this.wipeSessionUnguarded();
+    } finally {
+      this.wiping = false;
+    }
+  }
+  async wipeSessionUnguarded() {
+    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(), _storage.SecureStorage.removeItem(_storage.USER_KEY), _storage.Storage.removeItem(_storage.UNREAD_KEY),
+    // A new anonymous visitor on this device gets a new tracking identity.
+    (0, _deviceId.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() {
+    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. */
+  resetThreadTracking() {
+    this.threadGeneration += 1;
+    this.conversationCreation = null;
+    this.draftEvents = [];
+    this.cancelMarkRead();
+  }
+  requireBootConfig() {
+    if (!this.bootConfig) {
+      throw new _client.RepzoWidgetError('RepzoWidget.boot() must be called first', 0, 'http');
+    }
+  }
+
+  // ─── Realtime ───────────────────────────────────────────────────────────
+
+  connectRealtime(token) {
+    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. */
+  async reauthorizeStream(failedToken) {
+    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);
+    }
+  }
+  watchAppState() {
+    if (this.appStateSubscription) return;
+    this.appStateSubscription = _reactNative.AppState.addEventListener('change', status => {
+      if (status === 'active') {
+        void this.resumeFromBackground();
+      } else if (status === 'background') {
+        this.realtime.close();
+      }
+    });
+  }
+  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.
+   */
+  async refreshConfig() {
+    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 = {
+        ...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.
+    }
+  }
+  handleRealtimeEvent(event, data) {
+    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.
+   */
+  isThreadOnScreen(conversationId) {
+    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.
+   */
+  shouldHoldForDraft(conversationId) {
+    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;
+  }
+  replayDraftEvents() {
+    const held = this.draftEvents;
+    this.draftEvents = [];
+    held.forEach(({
+      event,
+      data
+    }) => this.handleRealtimeEvent(event, data));
+  }
+  persistUnread(map) {
+    void _storage.Storage.setItem(_storage.UNREAD_KEY, JSON.stringify(map));
+  }
+
+  /** Survives a relaunch so a reply received overnight is still marked unread. */
+  async loadUnread() {
+    const raw = await _storage.Storage.getItem(_storage.UNREAD_KEY);
+    if (!raw) return {};
+    try {
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== 'object') return {};
+      const result = {};
+      for (const [id, count] of Object.entries(parsed)) {
+        if (typeof count === 'number' && count > 0) result[id] = count;
+      }
+      return result;
+    } catch {
+      return {};
+    }
+  }
+  clearUnreadFor(conversationId) {
+    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.
+  isReplayedMessage(messageId) {
+    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;
+  }
+  handleNewMessage(data) {
+    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 = data?.messageId || `sse-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const 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 = 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(_events.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. */
+  scheduleMarkRead(conversationId) {
+    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. */
+  flushMarkRead() {
+    const conversationId = this.readConversationId;
+    this.cancelMarkRead();
+    if (!conversationId || !this.state.booted || this.loggedOut || this.terminalErrorCode) return;
+    this.client.markConversationRead(conversationId).catch(() => {});
+  }
+  cancelMarkRead() {
+    if (this.readTimer) clearTimeout(this.readTimer);
+    this.readTimer = null;
+    this.readConversationId = null;
+  }
+  handleConversationEvent(data) {
+    if (!data?.conversationId) return;
+    const 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]
+    });
+  }
+  rememberConversationAgent(data) {
+    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)
+    };
+  }
+  applyConversationAgent(conversation) {
+    const pending = this.pendingAgentByConversation[conversation.id];
+    if (!pending) return conversation;
+    return {
+      ...conversation,
+      agentName: pending.agentName ?? conversation.agentName,
+      agentAvatar: pending.agentAvatar ?? conversation.agentAvatar
+    };
+  }
+  hydrateConversation(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.
+   */
+  hydrateAttachments(attachments, messageId) {
+    if (!Array.isArray(attachments) || attachments.length === 0) return null;
+    const hydrated = attachments.filter(item => !!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;
+  }
+  clearTypingTimer() {
+    if (this.typingTimer) {
+      clearTimeout(this.typingTimer);
+      this.typingTimer = null;
+    }
+    if (this.state.agentTyping) this.setState({
+      agentTyping: false
+    });
+  }
+  scheduleTypingClear(delayMs) {
+    if (this.typingTimer) clearTimeout(this.typingTimer);
+    this.typingTimer = setTimeout(() => {
+      this.typingTimer = null;
+      this.setState({
+        agentTyping: false
+      });
+    }, delayMs);
+  }
+
+  // ─── UI commands ────────────────────────────────────────────────────────
+
+  resolveOpenView(space) {
+    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) {
+    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() {
+    if (!this.state.isOpen) return;
+    this.setState({
+      isOpen: false,
+      view: 'bubble',
+      agentTyping: false
+    });
+    this.clearTypingTimer();
+    this.track('widget_closed');
+  }
+  toggle(space) {
+    if (this.state.isOpen) this.hide();else this.present(space);
+  }
+  setView(view) {
+    this.setState({
+      view,
+      ...(view === 'chat' || view === 'conversations' ? {
+        activeTab: 'messages'
+      } : {}),
+      ...(view === 'home' ? {
+        activeTab: 'home'
+      } : {})
+    });
+  }
+  setActiveTab(tab) {
+    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) {
+    this.setState({
+      locale
+    });
+  }
+  startNewConversation(prefill) {
+    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) {
+    this.setState({
+      prefillText: prefill
+    });
+  }
+  dismissOutboundMessage() {
+    const outbound = this.state.outboundMessage;
+    if (outbound?.id) this.track('widget_outbound_dismissed', {
+      outboundId: outbound.id
+    });
+    this.setState({
+      outboundMessage: null
+    });
+  }
+
+  // ─── Conversations & messages ───────────────────────────────────────────
+
+  async refreshConversations() {
+    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 = {};
+        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) {
+    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(_events.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() {
+    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.
+   */
+  async refreshOpenThread() {
+    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. */
+  hydrateMessages(page) {
+    return page.map(message => ({
+      ...message,
+      attachments: this.hydrateAttachments(message.attachments, message.id)
+    })).reverse();
+  }
+  async sendMessage(body, attachments = [], agentUiAction) {
+    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 = {
+      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 = 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 = 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 = {
+          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) {
+    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) {
+    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, metadata = {}) {
+    if (!this.state.booted || this.state.config?.analyticsEnabled === false) return;
+    this.client.trackEvent({
+      event,
+      visitorId: this.state.identityId,
+      metadata: {
+        locale: this.state.locale,
+        platform: _reactNative.Platform.OS,
+        ...metadata
+      }
+    }).catch(() => {});
+  }
+  loadOutboundMessage() {
+    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() {
+    this.realtime.close();
+    this.clearTypingTimer();
+    this.resetThreadTracking();
+    this.appStateSubscription?.remove();
+    this.appStateSubscription = null;
+    this.subscribers.clear();
+    this.events.removeAllListeners();
+  }
+}
+exports.WidgetStore = WidgetStore;
+function createConversationCreation(generation) {
+  let resolve = () => {};
+  const promise = new Promise(settle => {
+    resolve = settle;
+  });
+  return {
+    generation,
+    promise,
+    resolve
+  };
+}
+
+/** Optimistic visitor bubbles the server hasn't acknowledged (pending/failed). */
+function isLocalMessage(message) {
+  return message.id.startsWith('temp-');
+}
+
+/** Stable, so same-instant rows keep their order; bad dates sort as oldest. */
+function sortByCreatedAt(messages) {
+  const time = message => Date.parse(message.createdAt) || 0;
+  return [...messages].sort((a, b) => time(a) - time(b));
+}
+function identityKey(user) {
+  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) {
+  const match = /^(https?):\/\/(\[[^\]]+\]|[^/?#:]+)(?::\d+)?(?:[/?#]|$)/i.exec(baseUrl);
+  if (!match) {
+    throw new _client.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 _client.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, ms) {
+  return new Promise(resolve => {
+    const timer = setTimeout(resolve, ms);
+    const done = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    promise.then(done, done);
+  });
+}
+function firstEnabledSpace(spaces) {
+  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) {
+  const result = {};
+  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;
+}
+//# sourceMappingURL=widget-store.js.map