@helpai/elements 0.25.0 → 0.27.0

package/index.mjs

@@ -476,13 +476,13 @@ var DEFAULT_FEATURES = {
 };
 var DEFAULT_FORMS = { list: [], byTrigger: {} };
 var DEFAULT_TRACKING = {
-  enabled: false,
+  enabled: true,
   sampleRate: 1
 };
 var DEFAULT_ENDPOINTS = {
-  upload: "/ai/agent/upload-file",
-  transcribe: "/ai/agent/transcribe-audio",
-  submitForm: "/submit-form"
+  upload: "/pai/upload-file",
+  transcribe: "/pai/transcribe-audio",
+  submitForm: "/pai/submit-form"
 };
 var DEFAULT_LAUNCHER = {
   variant: "circle",
@@ -525,12 +525,14 @@ function resolveOptions(rawOpts) {
   const locale = i18n.locale ?? resolveDefaultLocale(i18n.defaultLocale);
   const availableLocales = i18n.availableLocales ?? [locale];
   const baseUrl = (opts.baseUrl ?? BRAND.defaultBaseUrl).replace(/\/$/, "");
+  const agentBaseUrl = (opts.agentBaseUrl ?? `${baseUrl}/api/agent`).replace(/\/$/, "");
   const dataBaseUrl = (opts.dataBaseUrl ?? `${baseUrl}/api/data`).replace(/\/$/, "");
   return {
     widgetId: opts.widgetId ?? "default",
     publicKey: opts.publicKey,
     aiAgentDeploymentId: opts.aiAgentDeploymentId,
     baseUrl,
+    agentBaseUrl,
     dataBaseUrl,
     userContext: sanitizeUserContext(opts.userContext),
     pageContext: sanitizePageContext(opts.pageContext),
@@ -613,9 +615,9 @@ function resolveTracking(overrides, dataBaseUrl) {
   const sampleRate = overrides?.sampleRate ?? DEFAULT_TRACKING.sampleRate;
   return {
     enabled: overrides?.enabled ?? DEFAULT_TRACKING.enabled,
-    // The collector rides the data module — `${dataBaseUrl}/elements/px.gif`
-    // (e.g. `https://help.ai/api/data/elements/px.gif`).
-    endpoint: overrides?.endpoint ?? `${dataBaseUrl}/elements/px.gif`,
+    // The collector rides the data module — `${dataBaseUrl}/pai/elements-px.gif`
+    // (e.g. `https://help.ai/api/data/pai/elements-px.gif`).
+    endpoint: overrides?.endpoint ?? `${dataBaseUrl}/pai/elements-px.gif`,
     // Clamp instead of reject — a malformed rate must never turn a
     // disabled tracker on or crash resolve (no Zod on the IIFE path).
     sampleRate: Math.min(1, Math.max(0, Number.isFinite(sampleRate) ? sampleRate : 1)),
@@ -844,6 +846,7 @@ var EMBED_SCALAR_ATTRS = [
   ["public-key", "publicKey"],
   ["ai-agent-deployment-id", "aiAgentDeploymentId"],
   ["base-url", "baseUrl"],
+  ["agent-base-url", "agentBaseUrl"],
   ["data-base-url", "dataBaseUrl"],
   ["theme", "theme", (v) => v]
 ];
@@ -919,7 +922,7 @@ var REACTIVE_ATTRS = [
   ...SPECIAL_REACTIVE_ATTRS
 ];
 
-// src/core/start-conversation-shape.ts
+// src/core/handshake-shape.ts
 function isPlainObject(raw) {
   return !!raw && typeof raw === "object" && !Array.isArray(raw);
 }
@@ -1250,63 +1253,61 @@ function parseWireDate(value) {
 }
 var DEFAULT_PATHS = {
   /** Conversation bootstrap. `POST` → deployment config + per-visitor state. */
-  startConversation: "/ai/agent/start-conversation",
+  handshake: "/pai/handshake",
   /** Send a message + stream the reply (SSE). `POST`. */
-  streamMessage: "/ai/agent/stream-message",
+  streamMessage: "/pai/stream-message",
   /**
    * Resume an interrupted reply. `GET` (envelope rides as query params).
    * Stateless: the server re-streams the whole reply SSE again from the start —
    * there is NO `Last-Event-ID`. The client reconciles by id (`seenIds`), so
    * replayed events are skipped and only the continuation surfaces.
    */
-  streamResume: "/ai/agent/stream-resume",
+  streamResume: "/pai/stream-resume",
   /** Abort the in-flight reply stream. `POST`. */
-  cancelStream: "/ai/agent/cancel-stream",
+  cancelStream: "/pai/cancel-stream",
   /** List the visitor's conversations. `GET`. */
-  listConversations: "/ai/agent/list-conversations",
-  /** Load one conversation's messages. `GET ?conversationId=…`. */
-  listMessages: "/ai/agent/list-messages",
+  listConversations: "/pai/list-conversations",
+  /** Load one conversation's thread (messages + canContinue + suggestions). `GET ?conversationId=…`. */
+  listMessages: "/pai/list-messages",
   /**
    * Persist a user-driven settings change. POST `{ visitorId, userPrefs }` →
    * server persists, returns the merged authoritative copy. Fire-and-forget on
    * the client — a failure leaves the local cache valid; the next
-   * `startConversation()` reconciles.
+   * `handshake()` reconciles.
    */
-  updateSettings: "/ai/agent/update-settings",
+  updateSettings: "/pai/update-settings",
   /**
    * Mark a conversation read. POST `{ visitorId, conversationId }` → the server
    * records `lastReadAt = now` for that (visitor, conversation) and recomputes
    * `unreadCount` (returned on `/list-conversations`) accordingly. Fire-and-forget
    * on the client; a failure just leaves the badge until the next sync.
    */
-  markRead: "/ai/agent/mark-read",
+  markRead: "/pai/mark-read",
   // ── Data API (module-help-ai-data-api, via `dataBaseUrl`) ─────────
-  /** All widget content via one filtered endpoint. `GET /content?tags=…`. */
-  content: "/content",
   /**
-   * Resolved form definitions for the deployment. `GET /forms` →
-   * `{ forms: FormDef[] }`. Fetched once at boot (in parallel with
-   * start-conversation); form gating waits for it. A failure is treated as
-   * "no forms" (non-fatal).
+   * The data module's one ACTIVATION read. `GET
+   * /pai/bootstrap?visitorId=…&conversationId=…` →
+   * `{ forms, formSubmissions }`: the deployment's resolved form
+   * definitions plus the visitor's recorded submissions for the envelope's
+   * conversation (chronological — they rebuild the timeline markers).
+   * Also re-read with an explicit `conversationId` selector on a
+   * history-pane thread switch. A failure is treated as "no forms, no
+   * records" (non-fatal) — the chat works regardless.
+   */
+  bootstrap: "/pai/bootstrap",
+  /**
+   * All widget content via one filtered endpoint — content stays OUT of the
+   * bootstrap because its reads are query-driven (`tags` / `categories` /
+   * `ids` / `search` + pagination). `GET /pai/content?tags=…`.
    */
-  forms: "/forms",
+  content: "/pai/content",
   /**
    * Form submission (the event-driven forms engine). POST `{ visitorId,
    * conversationId, formId, trigger, values, skipped? }` → record the form's answers
    * immediately, keyed by the same `visitorId` + `conversationId` the chat uses.
    * Overridable via `endpoints.submitForm`. Fire-and-forget; 404 is ignored.
    */
-  submitForm: "/submit-form",
-  /**
-   * Visitor interaction records for a conversation. `GET
-   * /activity?visitorId=…&conversationId=…` →
-   * `{ formSubmissions: FormSubmissionRecord[] }` (chronological). Replaces
-   * the former `formSubmissions` echo on start-conversation / list-messages;
-   * deliberately generic — future visitor interaction records ride the same
-   * endpoint. A failure (e.g. 404 `AI_AGENT_PUBLIC_ACCESS_NOT_FOUND` when the
-   * deployment doesn't resolve) is treated as "no records" (non-fatal).
-   */
-  activity: "/activity"
+  submitForm: "/pai/submit-form"
 };
 var CONTEXT_PARAM = "context";
 function buildSendMessageRequest(params) {
@@ -1407,7 +1408,7 @@ function sleep(ms, signal7) {
 var AgentTransport = class {
   constructor(opts) {
     __publicField(this, "opts", opts);
-    // Identity adopted from the start-conversation response; rides the request envelope
+    // Identity adopted from the handshake response; rides the request envelope
     // (see `envelope()`) on every subsequent call so the backend can validate the
     // (visitor, conversation) pair.
     __publicField(this, "visitorId");
@@ -1430,9 +1431,9 @@ var AgentTransport = class {
   }
   /**
    * Seed the visitor + conversation identity from persistence BEFORE the first
-   * `startConversation` resolves. A mount-time `resumeStream()` runs in parallel
-   * with `startConversation`, so without this its envelope would carry no
-   * `conversationId` and the resume GET couldn't identify the thread. `startConversation`
+   * `handshake` resolves. A mount-time `resumeStream()` runs in parallel
+   * with `handshake`, so without this its envelope would carry no
+   * `conversationId` and the resume GET couldn't identify the thread. `handshake`
    * later overwrites these with the server's authoritative ids (rebind-safe).
    */
   primeIdentity(visitorId, conversationId) {
@@ -1449,7 +1450,7 @@ var AgentTransport = class {
     return out;
   }
   /** Merge the envelope into a JSON body (POSTs). Explicit body fields win — e.g.
-   * start-conversation's client-proposed ids, or a mark-read target conversation that
+   * handshake's client-proposed ids, or a mark-read target conversation that
    * differs from the active one. */
   withEnvelope(body) {
     return { ...this.envelope(), ...body };
@@ -1470,28 +1471,22 @@ var AgentTransport = class {
     return url.toString();
   }
   /** One-shot runtime bootstrap. Called once after the widget mounts. */
-  async startConversation(body) {
-    log4.debug("startConversation \u2192", {
+  async handshake(body) {
+    log4.debug("handshake \u2192", {
       visitorId: body.visitorId,
       conversationId: body.conversationId,
       locale: body.locale
     });
-    const res = await this.postJson(
-      DEFAULT_PATHS.startConversation,
-      body,
-      "startConversation"
-    );
-    log4.debug("startConversation \u2190", {
+    const res = await this.postJson(DEFAULT_PATHS.handshake, body, "handshake");
+    log4.debug("handshake \u2190", {
       visitorId: res.visitorId,
       conversationId: res.conversationId,
-      canContinue: res.canContinue,
-      hasMessages: !!res.messages?.length,
       hasWelcome: !!res.welcome,
       hasConfig: !!res.config,
       rebind: res.rebind
     });
-    if (!isStartConversationResponseShape(res)) {
-      log4.warn("startConversation response did not match expected shape; using raw response", { response: res });
+    if (!isHandshakeResponseShape(res)) {
+      log4.warn("handshake response did not match expected shape; using raw response", { response: res });
     }
     this.visitorId = res.visitorId ?? body.visitorId;
     this.conversationId = res.conversationId;
@@ -1601,38 +1596,26 @@ var AgentTransport = class {
     return { ...res, items };
   }
   /**
-   * Fetch the deployment's resolved form definitions. `GET /forms`
-   * (data-API). Replaces the former `config.forms` push on the handshake —
-   * called once at boot, in parallel with `startConversation`; form gating
-   * (pre-chat etc.) waits for it. Callers treat a thrown StreamError as
-   * "no forms" (non-fatal).
-   */
-  async listForms() {
-    log4.debug("listForms \u2192");
-    const res = await this.getJson(this.dataUrl(DEFAULT_PATHS.forms), "listForms");
-    const forms = res.forms ?? [];
-    log4.debug("listForms \u2190", { count: forms.length });
-    return { forms };
-  }
-  /**
-   * Fetch the visitor's recorded activity for a conversation — currently the
-   * form submissions that rebuild the collapsed "form submitted / skipped"
-   * timeline markers on resume. `GET /activity` (data-API); the
-   * envelope carries `visitorId` / `conversationId` as query params.
-   * `conversationId` here is an optional resource selector (a thread that may
-   * differ from the active conversation — the history-pane switch); when
-   * omitted, the envelope's active conversation applies. Callers treat a
-   * thrown StreamError (e.g. 404 on a deployment that doesn't resolve) as
-   * "no activity" (non-fatal).
+   * The data module's ONE activation read. `GET /pai/bootstrap` (data-API)
+   * → the deployment's resolved form definitions + the visitor's recorded
+   * form submissions for the envelope's conversation. The handshake
+   * (agent-API) is completely independent of these surfaces.
+   *
+   * `conversationId` is an optional resource selector (a thread that may
+   * differ from the active conversation — the history-pane switch re-reads
+   * that thread's submissions); when omitted, the envelope's active
+   * conversation applies. Callers treat a thrown StreamError (e.g. 404 on a
+   * deployment that doesn't resolve) as "no forms, no records" (non-fatal).
    */
-  async getActivity(conversationId) {
-    const url = new URL(this.dataUrl(DEFAULT_PATHS.activity));
+  async bootstrap(conversationId) {
+    const url = new URL(this.dataUrl(DEFAULT_PATHS.bootstrap));
     if (conversationId) url.searchParams.set("conversationId", conversationId);
-    log4.debug("getActivity \u2192", { conversationId: conversationId ?? this.conversationId });
-    const res = await this.getJson(url.toString(), "getActivity");
+    log4.debug("bootstrap \u2192", { conversationId: conversationId ?? this.conversationId });
+    const res = await this.getJson(url.toString(), "bootstrap");
+    const forms = res.forms ?? [];
     const formSubmissions = res.formSubmissions ?? [];
-    log4.debug("getActivity \u2190", { count: formSubmissions.length });
-    return { formSubmissions };
+    log4.debug("bootstrap \u2190", { forms: forms.length, formSubmissions: formSubmissions.length });
+    return { forms, formSubmissions };
   }
   async saveUserPrefs(userPrefs) {
     log4.debug("saveUserPrefs \u2192", {
@@ -1645,10 +1628,10 @@ var AgentTransport = class {
     return res;
   }
   get uploadPath() {
-    return this.opts.endpoints?.upload ?? "/ai/agent/upload-file";
+    return this.opts.endpoints?.upload ?? "/pai/upload-file";
   }
   get transcribePath() {
-    return this.opts.endpoints?.transcribe ?? "/ai/agent/transcribe-audio";
+    return this.opts.endpoints?.transcribe ?? "/pai/transcribe-audio";
   }
   get submitFormPath() {
     return this.opts.endpoints?.submitForm ?? DEFAULT_PATHS.submitForm;
@@ -1688,9 +1671,9 @@ var AgentTransport = class {
    * Re-attach to an in-flight reply on a cold page load / refresh.
    *
    * UNCONDITIONAL by design — the caller runs this in parallel with
-   * `startConversation`, never gated on whether there are persisted messages. If
+   * `handshake`, never gated on whether there are persisted messages. If
    * the user refreshed while the assistant was still streaming, the
-   * `startConversation` reply carries no messages (the turn isn't persisted until
+   * `handshake` reply carries no messages (the turn isn't persisted until
    * it finishes) and THIS is the channel that resumes the live reply. When
    * nothing is in flight the server answers 204 and the handle yields nothing
    * (the common case — no bubble is created).
@@ -1717,7 +1700,7 @@ var AgentTransport = class {
    *   - after a POST /stream-message drops mid-reply (`immediate=false` — back
    *     off first, the reply may still be spinning up server-side);
    *   - on a cold page load / refresh (`immediate=true` — hit it at once, in
-   *     parallel with start-conversation, so a reply that was streaming when the
+   *     parallel with handshake, so a reply that was streaming when the
    *     user reloaded keeps flowing).
    *
    * The endpoint ALWAYS opens a 200 SSE stream (mirrors the AI SDK
@@ -1726,7 +1709,7 @@ var AgentTransport = class {
    * nothing ever started) — closes an EMPTY stream. So "nothing to resume" is
    * signalled by a segment that ends without a terminal chunk AND surfaced no
    * NEW events — not by a status code. We stop gracefully there; the completed
-   * turn comes from the DB via start-conversation / list-messages.
+   * turn comes from the DB via the handshake / list-messages.
    *
    * Returns (no throw) on a terminal chunk, an empty/no-new-events segment, or
    * a 204 / non-OK (a backend that signals "nothing" by status, or lacks the
@@ -1791,7 +1774,7 @@ var AgentTransport = class {
     }
     return false;
   }
-  /** Abort + fire-and-forget POST to `/ai/agent/cancel-stream`. Idempotent. */
+  /** Abort + fire-and-forget POST to `/pai/cancel-stream`. Idempotent. */
   cancelStream(ctrl, conversationId) {
     if (ctrl.signal.aborted) return;
     log4.debug("cancel stream", { conversationId, visitorId: this.visitorId });
@@ -1832,7 +1815,7 @@ var AgentTransport = class {
     return url.toString();
   }
   // JSON requests are idempotent (reads, or full-snapshot writes like
-  // update-settings / mark-read / start-conversation), so they auto-retry transient
+  // update-settings / mark-read / handshake), so they auto-retry transient
   // failures. The message POST is NOT in here — re-sending could duplicate the
   // reply, so it surfaces an error for the user to retry (see `openMessageStream`).
   async postJson(path, body, label) {
@@ -1901,23 +1884,22 @@ var AgentTransport = class {
     return await res.json();
   }
   /**
-   * Agent-API URL — resolves a `/ai/agent/*` path against the agent module
-   * base, `${baseUrl}/api/agent`. Absolute URLs pass through unchanged.
+   * Agent-API URL — resolves a `/pai/*` path against the resolved
+   * agent module base. Absolute URLs pass through unchanged.
    */
   url(pathOrUrl) {
     if (/^https?:\/\//i.test(pathOrUrl)) return pathOrUrl;
-    return `${this.opts.baseUrl}/api/agent${pathOrUrl}`;
+    return `${this.opts.agentBaseUrl}${pathOrUrl}`;
   }
   /**
    * Data-API variant of {@link url} — resolves a root-level path (content /
-   * forms / submit-form / activity) against `dataBaseUrl`. Absolute URLs
-   * (e.g. an `endpoints.submitForm` pointing straight at a CRM) pass through
-   * unchanged; with no `dataBaseUrl` configured the data module derives from
-   * the main origin: `${baseUrl}/api/data`.
+   * forms / submit-form / activity) against the resolved data module base.
+   * Absolute URLs (e.g. an `endpoints.submitForm` pointing straight at a
+   * CRM) pass through unchanged.
    */
   dataUrl(pathOrUrl) {
     if (/^https?:\/\//i.test(pathOrUrl)) return pathOrUrl;
-    return `${this.opts.dataBaseUrl ?? `${this.opts.baseUrl}/api/data`}${pathOrUrl}`;
+    return `${this.opts.dataBaseUrl}${pathOrUrl}`;
   }
   get fetchImpl() {
     return this.opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
@@ -1931,10 +1913,10 @@ function extensionFor(mimeType) {
   if (mimeType.includes("wav")) return "wav";
   return "bin";
 }
-function isStartConversationResponseShape(raw) {
+function isHandshakeResponseShape(raw) {
   if (!raw || typeof raw !== "object") return false;
   const r = raw;
-  return typeof r.visitorId === "string" && typeof r.conversationId === "string" && typeof r.canContinue === "boolean";
+  return typeof r.visitorId === "string" && typeof r.conversationId === "string";
 }
 
 // src/stream/messages.ts
@@ -6449,6 +6431,14 @@ function App({ options, hostElement, bus }) {
     resolveInitialPanelState(options, currentViewportWidth(), persistence.loadPanelOpen(), persistence.loadPanelSize())
   );
   const [isOpen, setIsOpen] = useState13(initialPanelRef.current.panelOpen);
+  const [activated, setActivated] = useState13(initialPanelRef.current.panelOpen);
+  const activatedRef = useRef9(activated);
+  activatedRef.current = activated;
+  const pendingThreadRef = useRef9(false);
+  const welcomeRef = useRef9(void 0);
+  useEffect17(() => {
+    if (isOpen) setActivated(true);
+  }, [isOpen]);
   const initialPanelApplied = useRef9(false);
   const [launcherLeaving, setLauncherLeaving] = useState13(false);
   const { dismissed: calloutDismissed, dismissCallout: dismissCalloutRaw } = useLauncherCallout({
@@ -6475,7 +6465,7 @@ function App({ options, hostElement, bus }) {
   const [formContext, setFormContext] = useState13({});
   const [transport] = useState13(
     () => new AgentTransport({
-      baseUrl: options.baseUrl,
+      agentBaseUrl: options.agentBaseUrl,
       dataBaseUrl: options.dataBaseUrl,
       auth: createAuth({
         publicKey: options.publicKey,
@@ -6557,10 +6547,11 @@ function App({ options, hostElement, bus }) {
     },
     [messagesSig]
   );
+  const dataBootRef = useRef9(null);
   const fetchFormMarkers = useCallback6(
     async (conversationId) => {
       try {
-        const { formSubmissions: subs } = await transport.getActivity(conversationId);
+        const { formSubmissions: subs } = await (conversationId ? transport.bootstrap(conversationId) : dataBootRef.current ?? transport.bootstrap());
         const lastIndexByForm = /* @__PURE__ */ new Map();
         subs.forEach((rec, i) => lastIndexByForm.set(rec.formId, i));
         return subs.filter((rec, i) => !rec.skipped || lastIndexByForm.get(rec.formId) === i).map((rec, i) => ({
@@ -6571,14 +6562,53 @@ function App({ options, hostElement, bus }) {
           values: rec.values
         }));
       } catch (err) {
-        log16.debug("getActivity failed \u2014 no form markers (non-fatal)", { err });
+        log16.debug("bootstrap failed \u2014 no form markers (non-fatal)", { err });
         return [];
       }
     },
     [transport]
   );
   const connectGenRef = useRef9(0);
-  const runStartConversation = useCallback6(
+  const loadThread = useCallback6(
+    async (conversationId) => {
+      const myGen = connectGenRef.current;
+      const isStale = () => myGen !== connectGenRef.current;
+      setLoadingMessages(true);
+      try {
+        const [chat, markers] = await Promise.all([transport.loadConversation(conversationId), fetchFormMarkers()]);
+        if (isStale()) return;
+        const loaded = (chat.messages ?? []).map(fromWireMessage);
+        setFormMarkers(markers);
+        const timelineStamps = [...loaded.map((m) => m.createdAt), ...markers.map((m) => m.createdAt)].filter(
+          (n) => n !== void 0
+        );
+        const welcomeAnchor = (timelineStamps.length ? Math.min(...timelineStamps) : Date.now()) - 1;
+        const loadedIds = new Set(loaded.map((m) => m.id));
+        const welcomeRows = (welcomeRef.current?.messages ?? []).filter((w) => !loadedIds.has(w.id)).map((w) => {
+          const row = makeInstantWelcomeMessage(w);
+          row.createdAt = welcomeAnchor;
+          return row;
+        });
+        const tail = resumeBubbleRef.current ? [resumeBubbleRef.current] : [];
+        if (loaded.length || tail.length) {
+          messagesSig.value = [...welcomeRows, ...loaded, ...tail];
+          setCanSend(chat.canContinue ?? true);
+          setSuggestions(chat.suggestions ?? []);
+        } else {
+          messagesSig.value = welcomeRows;
+        }
+      } catch (err) {
+        if (isStale()) return;
+        log16.warn("loadThread failed; resetting conversationId", { err, conversationId });
+        conversationIdSig.value = void 0;
+        persistence.saveConversationId(void 0);
+      } finally {
+        if (!isStale()) setLoadingMessages(false);
+      }
+    },
+    [transport, fetchFormMarkers, messagesSig, conversationIdSig, persistence]
+  );
+  const runHandshake = useCallback6(
     async ({ newConversation }) => {
       const myGen = ++connectGenRef.current;
       const isStale = () => myGen !== connectGenRef.current;
@@ -6590,7 +6620,7 @@ function App({ options, hostElement, bus }) {
       }
       let res;
       try {
-        res = await transport.startConversation({
+        res = await transport.handshake({
           visitorId,
           conversationId,
           userPrefs: persistence.loadUserPrefs(),
@@ -6641,67 +6671,22 @@ function App({ options, hostElement, bus }) {
         if (res.userPrefs.themeMode) setActiveThemeMode(res.userPrefs.themeMode);
         if (res.userPrefs.textSize) setActiveTextSize(res.userPrefs.textSize);
       }
+      welcomeRef.current = res.welcome;
       const isResume = !newConversation && persistedChatId && res.conversationId === persistedChatId;
       if (isResume) {
-        setLoadingMessages(true);
-        try {
-          const chatPromise = res.messages?.length ? Promise.resolve({
-            conversationId: persistedChatId,
-            canContinue: res.canContinue ?? true,
-            messages: res.messages
-          }) : transport.loadConversation(persistedChatId);
-          const [chat, markers] = await Promise.all([chatPromise, fetchFormMarkers()]);
-          if (isStale()) return;
-          const loaded = (chat.messages ?? []).map(fromWireMessage);
-          setFormMarkers(markers);
-          const timelineStamps = [...loaded.map((m) => m.createdAt), ...markers.map((m) => m.createdAt)].filter(
-            (n) => n !== void 0
-          );
-          const welcomeAnchor = (timelineStamps.length ? Math.min(...timelineStamps) : Date.now()) - 1;
-          const loadedIds = new Set(loaded.map((m) => m.id));
-          const welcomeRows = (res.welcome?.messages ?? []).filter((w) => !loadedIds.has(w.id)).map((w) => {
-            const row = makeInstantWelcomeMessage(w);
-            row.createdAt = welcomeAnchor;
-            return row;
-          });
-          const tail = resumeBubbleRef.current ? [resumeBubbleRef.current] : [];
-          if (loaded.length || tail.length) {
-            messagesSig.value = [...welcomeRows, ...loaded, ...tail];
-            setCanSend(chat.canContinue ?? true);
-            setSuggestions(chat.suggestions ?? []);
-          } else {
-            messagesSig.value = welcomeRows;
-          }
-        } catch (err) {
-          if (isStale()) return;
-          log16.warn("loadConversation failed; resetting conversationId", { err, conversationId: persistedChatId });
-          conversationIdSig.value = void 0;
-          persistence.saveConversationId(void 0);
-        } finally {
-          if (!isStale()) setLoadingMessages(false);
-        }
+        if (activatedRef.current) void loadThread(persistedChatId);
+        else pendingThreadRef.current = true;
       } else {
         conversationIdSig.value = res.conversationId;
         persistence.saveConversationId(res.conversationId);
         playWelcome(res.welcome?.messages);
       }
       if (!newConversation) {
-        bus.emit("conversationStarted", res);
+        bus.emit("handshake", res);
         setConversationReady(true);
       }
     },
-    [
-      transport,
-      visitorId,
-      persistence,
-      options,
-      bus,
-      messagesSig,
-      conversationIdSig,
-      feedback,
-      playWelcome,
-      fetchFormMarkers
-    ]
+    [transport, visitorId, persistence, options, bus, conversationIdSig, feedback, playWelcome, loadThread]
   );
   const userSig = JSON.stringify(options.userContext ?? null);
   const pageSig = JSON.stringify(options.pageContext ?? null);
@@ -6754,36 +6739,46 @@ function App({ options, hostElement, bus }) {
     },
     [reducer, messagesSig, feedback, bus, options, homeNav]
   );
+  const resumeHandleRef = useRef9(null);
+  useEffect17(() => {
+    const persistedConversation = conversationIdSig.value;
+    if (persistedConversation) transport.primeIdentity(visitorId, persistedConversation);
+    void runHandshake({ newConversation: false });
+    return () => {
+      connectGenRef.current++;
+      resumeHandleRef.current?.cancel();
+    };
+  }, []);
   useEffect17(() => {
-    void runStartConversation({ newConversation: false });
+    if (!activated) return;
+    dataBootRef.current = transport.bootstrap();
     void (async () => {
       try {
-        const res = await transport.listForms();
-        setRemoteForms(resolveForms(res.forms));
+        const res = await dataBootRef.current;
+        setRemoteForms(resolveForms((res ?? { forms: [] }).forms));
       } catch (err) {
-        log16.debug("listForms failed \u2014 treating as no forms", { err });
+        log16.debug("bootstrap failed \u2014 treating as no forms", { err });
       } finally {
         setFormsReady(true);
       }
     })();
-    const persistedConversation = conversationIdSig.value;
-    let resume = null;
-    if (persistedConversation) {
-      transport.primeIdentity(visitorId, persistedConversation);
-      resume = transport.resumeStream();
-      void runResume(resume);
+    if (pendingThreadRef.current) {
+      pendingThreadRef.current = false;
+      const persisted = conversationIdSig.value;
+      if (persisted) void loadThread(persisted);
     }
-    return () => {
-      connectGenRef.current++;
-      resume?.cancel();
-    };
-  }, []);
+    if (conversationIdSig.value) {
+      const handle = transport.resumeStream();
+      resumeHandleRef.current = handle;
+      void runResume(handle);
+    }
+  }, [activated]);
   const lastUserSig = useRef9(userSig);
   useEffect17(() => {
     if (!conversationReady || lastUserSig.current === userSig) return;
     lastUserSig.current = userSig;
-    void runStartConversation({ newConversation: false });
-  }, [userSig, conversationReady, runStartConversation]);
+    void runHandshake({ newConversation: false });
+  }, [userSig, conversationReady, runHandshake]);
   useEffect17(() => {
     applyMode(hostElement, computeHostMode(options.mode, panelSize, isOpen));
   }, [hostElement, isOpen, panelSize, options.mode]);
@@ -7010,10 +7005,10 @@ function App({ options, hostElement, bus }) {
   }, [transport, options.modules, unreadCountSig]);
   const unreadSeeded = useRef9(false);
   useEffect17(() => {
-    if (!conversationReady || unreadSeeded.current) return;
+    if (!activated || !conversationReady || unreadSeeded.current) return;
     unreadSeeded.current = true;
     refreshUnread();
-  }, [conversationReady, refreshUnread]);
+  }, [activated, conversationReady, refreshUnread]);
   const handleOpen = useCallback6(() => {
     log16.info("open", { mode: options.mode });
     feedback.unlock();
@@ -7035,8 +7030,8 @@ function App({ options, hostElement, bus }) {
     persistence.clearConversation();
     setCanSend(true);
     setFormMarkers([]);
-    void runStartConversation({ newConversation: true });
-  }, [streaming, activeCancel, messagesSig, conversationIdSig, persistence, runStartConversation, bus]);
+    void runHandshake({ newConversation: true });
+  }, [streaming, activeCancel, messagesSig, conversationIdSig, persistence, runHandshake, bus]);
   const handleNewChat = useCallback6(() => {
     handleClear();
     setView("chat");
@@ -7147,6 +7142,20 @@ function App({ options, hostElement, bus }) {
     },
     [transport, messagesSig, conversationIdSig, bus, options, persistence, refreshUnread, fetchFormMarkers]
   );
+  const pendingOpenFormRef = useRef9(null);
+  const openForm = useCallback6(
+    (id) => {
+      if (typeof id !== "string") return;
+      if (formsReady) forms.fire("manual", id);
+      else pendingOpenFormRef.current = id;
+    },
+    [formsReady, forms]
+  );
+  useEffect17(() => {
+    if (!formsReady || !pendingOpenFormRef.current) return;
+    forms.fire("manual", pendingOpenFormRef.current);
+    pendingOpenFormRef.current = null;
+  }, [formsReady, forms]);
   useEffect17(() => {
     const unsub = bindHostCommands(hostElement, {
       open: handleOpen,
@@ -7154,10 +7163,10 @@ function App({ options, hostElement, bus }) {
       expand: handleExpand,
       fullscreen: handleFullscreen,
       popout: handlePopOut,
-      openForm: (id) => forms.fire("manual", typeof id === "string" ? id : void 0)
+      openForm
     });
     return unsub;
-  }, [hostElement, handleOpen, handleClose, handleExpand, handleFullscreen, handlePopOut, forms]);
+  }, [hostElement, handleOpen, handleClose, handleExpand, handleFullscreen, handlePopOut, openForm]);
   const effectiveOptions = useMemo3(
     () => applyOptionOverrides(options, activeLocale, activeThemeMode, activeTextSize),
     [options, activeLocale, activeThemeMode, activeTextSize]
@@ -7452,7 +7461,7 @@ var TRACKED = {
   clear: () => void 0,
   suggestion: () => void 0,
   toggleHistory: (p33) => ({ view: p33.view }),
-  conversationStarted: () => void 0,
+  handshake: () => void 0,
   // Forms + human-in-the-loop — ids and outcomes, never values.
   formSubmit: (p33) => ({ formId: p33.formId, skipped: p33.skipped }),
   toolResult: () => void 0,
@@ -7621,7 +7630,7 @@ var EVENT_NAMES = [
   "calloutDismiss",
   // Lifecycle / errors
   "error",
-  "conversationStarted",
+  "handshake",
   "visitorRebound",
   "conversationRebound"
 ];
@@ -7678,7 +7687,7 @@ function mount(opts) {
     );
   };
   renderApp();
-  bus.on("conversationStarted", (response) => {
+  bus.on("handshake", (response) => {
     if (!response.config) return;
     rawOptions = mergeServerConfig(rawOptions, response.config);
     currentOptions = resolveOptions(rawOptions);