@helpai/elements 0.24.0 → 0.25.0

package/index.d.ts

@@ -1,4 +1,4 @@
-export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, L as Link, S as ServerConfig, b as SiteConfig, c as StartConversationResponse, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial } from './deployment-BP2axIFu.js';
+export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, L as Link, S as ServerConfig, b as SiteConfig, c as StartConversationResponse, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial } from './deployment-B0uvvJYK.js';
 import 'zod';
 
 /**
@@ -180,27 +180,6 @@ type WirePart = {
     errorText?: string;
     approval?: ToolApproval;
 };
-/**
- * One recorded form submission, returned on `/ai/agent/start-conversation`
- * (alongside `messages`) so the widget can re-place the "form submitted /
- * skipped" marker at its chronological spot in the timeline.
- */
-interface FormSubmissionRecord {
-    formId: string;
-    /** The trigger kind that surfaced the form. */
-    trigger: string;
-    /** True when the visitor skipped instead of answering. */
-    skipped?: boolean;
-    /** ISO-8601 — same format + name as {@link WireMessage.createdAt}. */
-    createdAt?: string;
-    /**
-     * The visitor's own answers, echoed back so the submitted marker can offer
-     * a read-only review after a reload. Scoped to the same `visitorId` that
-     * submitted them — this is the visitor seeing their own data, independent
-     * of `submit.toContext` (which governs mirroring into request context).
-     */
-    values?: Record<string, string>;
-}
 /** One-shot bot persona shown in the panel header. */
 interface ConversationAgent {
     name: string;
@@ -262,13 +241,6 @@ interface StartConversationResponse {
     /** Page-mode sidebar blocks (navigation, link cards). Backend ships it whenever the deployment renders the page-shell sidebar. */
     blocks?: Record<string, unknown>;
     messages?: WireMessage[];
-    /**
-     * Form submissions recorded for this conversation (via
-     * `/ai/agent/submit-form`), returned like `messages` so the widget can
-     * reconstruct the timeline on resume — each renders as a collapsed
-     * "form submitted" marker at its chronological position.
-     */
-    formSubmissions?: FormSubmissionRecord[];
     /**
      * Server's authoritative copy of the visitor's preferences. When present,
      * client adopts it (overrides local cache) and re-applies it to the UI
@@ -590,7 +562,7 @@ interface FormDef {
      * answers. Default `true`. Set `false` to keep the marker plain — e.g.
      * sensitive answers that shouldn't linger on screen (pairs with
      * `mirrorToContext: false`; the backend should also omit `values` from the
-     * `formSubmissions` echo for such forms).
+     * `/activity` records for such forms).
      */
     reviewable?: boolean;
 }
@@ -698,7 +670,7 @@ interface LauncherOptions {
  *
  * `modules` is an ordered list of tabs; each picks a UI `layout`, optional
  * content `contentTags` (the scope passed as the `tags` filter to
- * `GET /ai/agent/content`), and a translatable `label`.
+ * `GET /content`), and a translatable `label`.
  */
 /** The UI layouts a tab can render with. `chat` is the conversation; the rest render content. */
 type ModuleLayout = "chat" | "home" | "help" | "news";
@@ -982,9 +954,11 @@ interface PageContext {
     [key: string]: string | number | boolean | undefined;
 }
 /**
- * Override the HTTP endpoints the widget calls. Paths are appended to
- * `baseUrl`. Absolute URLs also work (useful when the upload endpoint
- * lives on a different origin like a CDN presign service).
+ * Override the HTTP endpoints the widget calls. `upload` / `transcribe`
+ * paths are appended to the agent base (`${baseUrl}/api/agent`);
+ * `submitForm` is appended to the data base (`dataBaseUrl`). Absolute URLs
+ * also work (useful when the upload endpoint lives on a different origin
+ * like a CDN presign service).
  */
 interface Endpoints {
     /** File upload endpoint. Default: `'/ai/agent/upload-file'`. */
@@ -992,7 +966,7 @@ interface Endpoints {
     /** Voice transcription endpoint. Default: `'/ai/agent/transcribe-audio'`. */
     transcribe?: string;
     /**
-     * Form submission endpoint. Default: `'/ai/agent/submit-form'`. When any form
+     * Form submission endpoint. Default: `'/submit-form'`. When any form
      * (a pre-chat lead capture, a CSAT survey, etc.) is completed, the widget POSTs
      * the captured values here (fire-and-forget), keyed by the same `visitorId` +
      * `conversationId` the conversation uses; the payload carries `formId` + `trigger`
@@ -1024,8 +998,8 @@ interface TrackingOptions {
      */
     enabled?: boolean;
     /**
-     * Pixel collector URL. Default: `https://t.<brand domain>/api/ai-elements/px.gif`
-     * (e.g. `https://t.help.ai/api/ai-elements/px.gif`).
+     * Pixel collector URL. Default: `${dataBaseUrl}/elements/px.gif`
+     * (e.g. `https://help.ai/api/data/elements/px.gif`).
      */
     endpoint?: string;
     /**
@@ -1090,8 +1064,21 @@ interface ChatWidgetOptions {
     publicKey?: string;
     /** Deployment ID (UUID). Sent as `x-ai-agent-deployment-id`. */
     aiAgentDeploymentId?: string;
-    /** Backend origin (no trailing slash). Defaults to the brand's default. */
+    /**
+     * MAIN site origin (no trailing slash, e.g. `https://help.ai`). The API
+     * modules derive from it: the agent API lives at `${baseUrl}/api/agent`,
+     * the data API at `${baseUrl}/api/data`. Defaults to the brand's origin.
+     */
     baseUrl?: string;
+    /**
+     * Data-API base (no trailing slash) — the `module-help-ai-data-api`
+     * service serving content, form definitions, and form submissions at
+     * root-level paths (`/content`, `/forms`, `/activity`, `/submit-form`).
+     * Precedence: this option > server-pushed `config.dataBaseUrl` > derived
+     * from the main origin (`${baseUrl}/api/data`, e.g.
+     * `https://help.ai/api/data`).
+     */
+    dataBaseUrl?: string;
     /** Host-asserted, informational end-user context (untrusted; not auth). */
     userContext?: UserContext;
     /** Host-asserted, informational page/visit context (untrusted; `area`, url, …). */
@@ -1146,6 +1133,8 @@ interface ResolvedOptions {
     publicKey?: string;
     aiAgentDeploymentId?: string;
     baseUrl: string;
+    /** Resolved data-API base — see {@link ChatWidgetOptions.dataBaseUrl}. */
+    dataBaseUrl: string;
     userContext?: UserContext;
     pageContext?: PageContext;
     position: Position;
@@ -1237,8 +1226,14 @@ interface ResolvedOptions {
  * Matches a subset of {@link ChatWidgetOptions} — anything the server can
  * reasonably dictate (UI, behaviour, routing). Callbacks (`onMessage` etc.)
  * and the public key are deliberately excluded — those are client concerns.
+ *
+ * Form definitions no longer ride this config: the widget fetches them from
+ * the data-API (`GET /forms`). A stale backend still pushing
+ * `config.forms` is ignored.
  */
 interface ServerConfig {
+    /** Data-API base override — adopted only when the host didn't set one. */
+    dataBaseUrl?: string;
     presentation?: PresentationOptions;
     behavior?: BehaviorOptions;
     theme?: ThemePreference | ThemeOverrides;
@@ -1249,7 +1244,6 @@ interface ServerConfig {
     i18n?: I18nOptions;
     footer?: FooterOptions;
     features?: FeatureFlags;
-    forms?: FormsOptions;
     modules?: ModulesOptions;
     tracking?: TrackingOptions;
     endpoints?: Endpoints;

package/index.mjs

@@ -19,7 +19,12 @@ var BRAND = {
   // and @goai builds.
   tagName: true ? "web-ai-chat" : "web-ai-chat",
   cssPrefix: true ? "helpai" : "helpai",
-  defaultBaseUrl: true ? "https://help.ai/api" : "",
+  /**
+   * MAIN site origin (e.g. `https://help.ai`) — module bases derive from it:
+   * agent API at `${defaultBaseUrl}/api/agent`, data API at
+   * `${defaultBaseUrl}/api/data`.
+   */
+  defaultBaseUrl: true ? "https://help.ai" : "",
   standaloneUrl: true ? "https://help.ai/chat" : "",
   /** Public-facing brand label, e.g. "Help AI" / "Go AI". */
   displayName: true ? "Help AI" : "Help AI",
@@ -472,13 +477,12 @@ var DEFAULT_FEATURES = {
 var DEFAULT_FORMS = { list: [], byTrigger: {} };
 var DEFAULT_TRACKING = {
   enabled: false,
-  endpoint: `https://t.${BRAND.domain}/api/ai-elements/px.gif`,
   sampleRate: 1
 };
 var DEFAULT_ENDPOINTS = {
   upload: "/ai/agent/upload-file",
   transcribe: "/ai/agent/transcribe-audio",
-  submitForm: "/ai/agent/submit-form"
+  submitForm: "/submit-form"
 };
 var DEFAULT_LAUNCHER = {
   variant: "circle",
@@ -520,11 +524,14 @@ function resolveOptions(rawOpts) {
   const mode = presentation.mode ?? "floating";
   const locale = i18n.locale ?? resolveDefaultLocale(i18n.defaultLocale);
   const availableLocales = i18n.availableLocales ?? [locale];
+  const baseUrl = (opts.baseUrl ?? BRAND.defaultBaseUrl).replace(/\/$/, "");
+  const dataBaseUrl = (opts.dataBaseUrl ?? `${baseUrl}/api/data`).replace(/\/$/, "");
   return {
     widgetId: opts.widgetId ?? "default",
     publicKey: opts.publicKey,
     aiAgentDeploymentId: opts.aiAgentDeploymentId,
-    baseUrl: (opts.baseUrl ?? BRAND.defaultBaseUrl).replace(/\/$/, ""),
+    baseUrl,
+    dataBaseUrl,
     userContext: sanitizeUserContext(opts.userContext),
     pageContext: sanitizePageContext(opts.pageContext),
     position: presentation.position ?? "bottom-right",
@@ -569,7 +576,7 @@ function resolveOptions(rawOpts) {
     poweredBy: resolvePoweredBy(footer.poweredBy),
     composer: resolveComposer(opts.composer),
     modules: resolveModules(opts.modules),
-    tracking: resolveTracking(opts.tracking),
+    tracking: resolveTracking(opts.tracking, dataBaseUrl),
     storage: opts.storage ?? defaultStorage,
     onMessage: opts.onMessage,
     onOpen: opts.onOpen,
@@ -602,11 +609,13 @@ function resolveHaptics(overrides) {
     events: overrides?.events
   };
 }
-function resolveTracking(overrides) {
+function resolveTracking(overrides, dataBaseUrl) {
   const sampleRate = overrides?.sampleRate ?? DEFAULT_TRACKING.sampleRate;
   return {
     enabled: overrides?.enabled ?? DEFAULT_TRACKING.enabled,
-    endpoint: overrides?.endpoint ?? DEFAULT_TRACKING.endpoint,
+    // 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`,
     // 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)),
@@ -775,7 +784,7 @@ function mergeServerConfig(user, server) {
     out[key] = mergeLeaves(sv, uv);
   }
   if (server.modules !== void 0 && user.modules === void 0) out.modules = server.modules;
-  if (server.forms !== void 0 && user.forms === void 0) out.forms = server.forms;
+  if (server.dataBaseUrl !== void 0 && user.dataBaseUrl === void 0) out.dataBaseUrl = server.dataBaseUrl;
   const userI18n = user.i18n;
   const serverI18n = server.i18n;
   if (userI18n || serverI18n) {
@@ -835,6 +844,7 @@ var EMBED_SCALAR_ATTRS = [
   ["public-key", "publicKey"],
   ["ai-agent-deployment-id", "aiAgentDeploymentId"],
   ["base-url", "baseUrl"],
+  ["data-base-url", "dataBaseUrl"],
   ["theme", "theme", (v) => v]
 ];
 var PRESENTATION_ATTRS = [
@@ -1270,16 +1280,33 @@ var DEFAULT_PATHS = {
    * on the client; a failure just leaves the badge until the next sync.
    */
   markRead: "/ai/agent/mark-read",
-  // ── CMS content (unified — Home / Help / News / docs) ─────────────
-  /** All widget content via one filtered endpoint. `GET /ai/agent/content?tags=…`. */
-  content: "/ai/agent/content",
+  // ── 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).
+   */
+  forms: "/forms",
   /**
    * 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: "/ai/agent/submit-form"
+  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"
 };
 var CONTEXT_PARAM = "context";
 function buildSendMessageRequest(params) {
@@ -1552,14 +1579,17 @@ var AgentTransport = class {
       log4.debug("markRead failed (non-fatal)", { err });
     }
   }
-  // ---- CMS content (unified) --------------------------------------------
+  // ---- Data API (content / forms — module-help-ai-data-api) --------------
   //
-  // One endpoint for every content surface (Home / Help / News / docs).
-  // Callers pass filters; a thrown StreamError (e.g. 404 on an older backend)
-  // is treated as "no content" by the module and the tab degrades gracefully.
-  /** Fetch content rows by filter. `GET /ai/agent/content`. */
+  // The DATA surfaces live on `dataBaseUrl` (default `${baseUrl}/api/data`)
+  // with ROOT-level paths — same auth headers + envelope, same retry
+  // behavior. One endpoint for every content surface (Home / Help / News /
+  // docs); callers pass filters; a thrown StreamError (e.g. 404 on an older
+  // backend) is treated as "no content" by the module and the tab degrades
+  // gracefully.
+  /** Fetch content rows by filter. `GET /content` (data-API). */
   async listContent(query = {}) {
-    const url = new URL(this.url(DEFAULT_PATHS.content));
+    const url = new URL(this.dataUrl(DEFAULT_PATHS.content));
     for (const [key, value] of Object.entries(query)) {
       if (value === void 0) continue;
       url.searchParams.set(key, Array.isArray(value) ? value.join(",") : String(value));
@@ -1570,6 +1600,40 @@ var AgentTransport = class {
     log4.debug("listContent \u2190", { count: items.length, total: res.pagination?.total });
     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).
+   */
+  async getActivity(conversationId) {
+    const url = new URL(this.dataUrl(DEFAULT_PATHS.activity));
+    if (conversationId) url.searchParams.set("conversationId", conversationId);
+    log4.debug("getActivity \u2192", { conversationId: conversationId ?? this.conversationId });
+    const res = await this.getJson(url.toString(), "getActivity");
+    const formSubmissions = res.formSubmissions ?? [];
+    log4.debug("getActivity \u2190", { count: formSubmissions.length });
+    return { formSubmissions };
+  }
   async saveUserPrefs(userPrefs) {
     log4.debug("saveUserPrefs \u2192", {
       visitorId: this.visitorId,
@@ -1590,8 +1654,9 @@ var AgentTransport = class {
     return this.opts.endpoints?.submitForm ?? DEFAULT_PATHS.submitForm;
   }
   /**
-   * Record a completed form (intake, CSAT, claim, …). Fire-and-forget — the
-   * record is captured even if the visitor never sends a message. `conversationId`,
+   * Record a completed form (intake, CSAT, claim, …). `POST
+   * /submit-form` (data-API). Fire-and-forget — the record is
+   * captured even if the visitor never sends a message. `conversationId`,
    * `formId`, and `trigger` are explicit so the backend can tie + route;
    * `visitorId` + context ride the envelope. A failure (e.g. 404 on a backend
    * that doesn't implement the endpoint) is non-fatal, so callers don't await.
@@ -1599,7 +1664,7 @@ var AgentTransport = class {
   async submitForm(body) {
     log4.debug("submitForm \u2192", { formId: body.formId, trigger: body.trigger, fields: Object.keys(body.values).length });
     try {
-      await this.postJson(this.submitFormPath, body, "submitForm");
+      await this.postJson(this.dataUrl(this.submitFormPath), body, "submitForm");
     } catch (err) {
       log4.debug("submitForm failed (non-fatal)", { err });
     }
@@ -1835,9 +1900,24 @@ var AgentTransport = class {
     if (!res.ok) throw new StreamError(`${label} failed: ${res.status}`, "server", res.status);
     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.
+   */
   url(pathOrUrl) {
     if (/^https?:\/\//i.test(pathOrUrl)) return pathOrUrl;
-    return `${this.opts.baseUrl}${pathOrUrl}`;
+    return `${this.opts.baseUrl}/api/agent${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`.
+   */
+  dataUrl(pathOrUrl) {
+    if (/^https?:\/\//i.test(pathOrUrl)) return pathOrUrl;
+    return `${this.opts.dataBaseUrl ?? `${this.opts.baseUrl}/api/data`}${pathOrUrl}`;
   }
   get fetchImpl() {
     return this.opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
@@ -6362,6 +6442,8 @@ function App({ options, hostElement, bus }) {
   const chatTabIdRef = useRef9(void 0);
   chatTabIdRef.current = chatTabId();
   const [conversationReady, setConversationReady] = useState13(false);
+  const [remoteForms, setRemoteForms] = useState13(null);
+  const [formsReady, setFormsReady] = useState13(false);
   const isInlineLike = options.mode === "standalone" || options.mode === "inline";
   const initialPanelRef = useRef9(
     resolveInitialPanelState(options, currentViewportWidth(), persistence.loadPanelOpen(), persistence.loadPanelSize())
@@ -6394,6 +6476,7 @@ function App({ options, hostElement, bus }) {
   const [transport] = useState13(
     () => new AgentTransport({
       baseUrl: options.baseUrl,
+      dataBaseUrl: options.dataBaseUrl,
       auth: createAuth({
         publicKey: options.publicKey,
         aiAgentDeploymentId: options.aiAgentDeploymentId,
@@ -6474,6 +6557,26 @@ function App({ options, hostElement, bus }) {
     },
     [messagesSig]
   );
+  const fetchFormMarkers = useCallback6(
+    async (conversationId) => {
+      try {
+        const { formSubmissions: subs } = await transport.getActivity(conversationId);
+        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) => ({
+          key: `wire:${rec.formId}:${rec.createdAt ?? i}`,
+          formId: rec.formId,
+          outcome: rec.skipped ? "skipped" : "submitted",
+          createdAt: parseWireDate(rec.createdAt),
+          values: rec.values
+        }));
+      } catch (err) {
+        log16.debug("getActivity failed \u2014 no form markers (non-fatal)", { err });
+        return [];
+      }
+    },
+    [transport]
+  );
   const connectGenRef = useRef9(0);
   const runStartConversation = useCallback6(
     async ({ newConversation }) => {
@@ -6542,24 +6645,14 @@ function App({ options, hostElement, bus }) {
       if (isResume) {
         setLoadingMessages(true);
         try {
-          const chat = res.messages?.length ? {
+          const chatPromise = res.messages?.length ? Promise.resolve({
             conversationId: persistedChatId,
             canContinue: res.canContinue ?? true,
-            messages: res.messages,
-            formSubmissions: res.formSubmissions
-          } : await transport.loadConversation(persistedChatId);
+            messages: res.messages
+          }) : transport.loadConversation(persistedChatId);
+          const [chat, markers] = await Promise.all([chatPromise, fetchFormMarkers()]);
           if (isStale()) return;
           const loaded = (chat.messages ?? []).map(fromWireMessage);
-          const subs = chat.formSubmissions ?? res.formSubmissions ?? [];
-          const lastIndexByForm = /* @__PURE__ */ new Map();
-          subs.forEach((rec, i) => lastIndexByForm.set(rec.formId, i));
-          const markers = subs.filter((rec, i) => !rec.skipped || lastIndexByForm.get(rec.formId) === i).map((rec, i) => ({
-            key: `wire:${rec.formId}:${rec.createdAt ?? i}`,
-            formId: rec.formId,
-            outcome: rec.skipped ? "skipped" : "submitted",
-            createdAt: parseWireDate(rec.createdAt),
-            values: rec.values
-          }));
           setFormMarkers(markers);
           const timelineStamps = [...loaded.map((m) => m.createdAt), ...markers.map((m) => m.createdAt)].filter(
             (n) => n !== void 0
@@ -6597,7 +6690,18 @@ function App({ options, hostElement, bus }) {
         setConversationReady(true);
       }
     },
-    [transport, visitorId, persistence, options, bus, messagesSig, conversationIdSig, feedback, playWelcome]
+    [
+      transport,
+      visitorId,
+      persistence,
+      options,
+      bus,
+      messagesSig,
+      conversationIdSig,
+      feedback,
+      playWelcome,
+      fetchFormMarkers
+    ]
   );
   const userSig = JSON.stringify(options.userContext ?? null);
   const pageSig = JSON.stringify(options.pageContext ?? null);
@@ -6652,6 +6756,16 @@ function App({ options, hostElement, bus }) {
   );
   useEffect17(() => {
     void runStartConversation({ newConversation: false });
+    void (async () => {
+      try {
+        const res = await transport.listForms();
+        setRemoteForms(resolveForms(res.forms));
+      } catch (err) {
+        log16.debug("listForms failed \u2014 treating as no forms", { err });
+      } finally {
+        setFormsReady(true);
+      }
+    })();
     const persistedConversation = conversationIdSig.value;
     let resume = null;
     if (persistedConversation) {
@@ -6788,8 +6902,9 @@ function App({ options, hostElement, bus }) {
     [options.features.humanInLoop, handleToolResult, handleToolDecision]
   );
   const userMessageCount = () => messagesSig.value.reduce((n, m) => n + (m.role === "user" ? 1 : 0), 0);
+  const effectiveForms = options.forms.list.length > 0 ? options.forms : remoteForms ?? options.forms;
   const forms = useForms({
-    forms: options.forms,
+    forms: effectiveForms,
     persistence,
     userContext: () => options.userContext,
     messageCount: userMessageCount,
@@ -6822,18 +6937,18 @@ function App({ options, hostElement, bus }) {
   const pageArea = options.pageContext?.area ? String(options.pageContext.area) : void 0;
   const msgCount = useComputed7(() => messagesSig.value.length);
   useEffect17(() => {
-    if (conversationReady) forms.fire("pre-chat");
-  }, [conversationReady, forms]);
+    if (conversationReady && formsReady) forms.fire("pre-chat");
+  }, [conversationReady, formsReady, forms]);
   useEffect17(() => {
-    if (!canSend) forms.fire("conversation-closed");
-  }, [canSend, forms]);
+    if (formsReady && !canSend) forms.fire("conversation-closed");
+  }, [formsReady, canSend, forms]);
   useEffect17(() => {
-    if (conversationReady && pageArea) forms.fire("page-area");
-  }, [conversationReady, pageArea, forms]);
+    if (conversationReady && formsReady && pageArea) forms.fire("page-area");
+  }, [conversationReady, formsReady, pageArea, forms]);
   const idleMs = useMemo3(() => {
-    const secs = options.forms.list.flatMap((f) => f.triggers).filter((t) => t.kind === "idle").map((t) => Number(t.param));
+    const secs = effectiveForms.list.flatMap((f) => f.triggers).filter((t) => t.kind === "idle").map((t) => Number(t.param));
     return secs.length ? Math.min(...secs) * 1e3 : 0;
-  }, [options.forms]);
+  }, [effectiveForms]);
   useEffect17(() => {
     if (!idleMs || !isOpen) return;
     const id = setTimeout(() => forms.fire("idle"), idleMs);
@@ -7010,9 +7125,13 @@ function App({ options, hostElement, bus }) {
       log16.info("selectConversation", { conversationId: targetConversationId });
       bus.emit("selectConversation", { conversationId: targetConversationId });
       try {
-        const res = await transport.loadConversation(targetConversationId);
+        const [res, markers] = await Promise.all([
+          transport.loadConversation(targetConversationId),
+          fetchFormMarkers(targetConversationId)
+        ]);
         const hydrated = res.messages.map(fromWireMessage);
         messagesSig.value = hydrated;
+        setFormMarkers(markers);
         conversationIdSig.value = res.conversationId;
         persistence.saveConversationId(res.conversationId);
         if (res.agent) setAgent(res.agent);
@@ -7026,7 +7145,7 @@ function App({ options, hostElement, bus }) {
         options.onError?.(err);
       }
     },
-    [transport, messagesSig, conversationIdSig, bus, options, persistence, refreshUnread]
+    [transport, messagesSig, conversationIdSig, bus, options, persistence, refreshUnread, fetchFormMarkers]
   );
   useEffect17(() => {
     const unsub = bindHostCommands(hostElement, {
@@ -7045,10 +7164,10 @@ function App({ options, hostElement, bus }) {
   );
   const enrichedFormMarkers = useMemo3(
     () => formMarkers.map((m) => {
-      const def = options.forms.list.find((f) => f.id === m.formId);
+      const def = effectiveForms.list.find((f) => f.id === m.formId);
       return { ...m, title: def?.title, form: def };
     }),
-    [formMarkers, options.forms]
+    [formMarkers, effectiveForms]
   );
   const panelProps = {
     options: effectiveOptions,

package/package.json

@@ -80,5 +80,5 @@
   ],
   "type": "module",
   "types": "./index.d.ts",
-  "version": "0.24.0"
+  "version": "0.25.0"
 }

package/schema.d.ts

@@ -1,4 +1,4 @@
-export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, E as Endpoints, L as Link, P as PAGE_AREA_SUGGESTIONS, g as PageContext, S as ServerConfig, b as SiteConfig, c as StartConversationResponse, U as UserContext, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial, h as assetSchema, i as blocksConfigSchema, j as connectionConfigPartialSchema, k as connectionConfigSchema, l as cssColorSchema, m as cssLengthSchema, n as endpointsSchema, o as linkSchema, p as localeSchema, q as pageContextSchema, s as serverConfigSchema, r as siteConfigSchema, t as startConversationResponseSchema, u as userContextSchema, v as uuid7Schema, w as widgetConfigPartialSchema, x as widgetConfigSchema, y as widgetSettingsPartialSchema, z as widgetSettingsSchema } from './deployment-BP2axIFu.js';
+export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, E as Endpoints, L as Link, P as PAGE_AREA_SUGGESTIONS, g as PageContext, S as ServerConfig, b as SiteConfig, c as StartConversationResponse, U as UserContext, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial, h as assetSchema, i as blocksConfigSchema, j as connectionConfigPartialSchema, k as connectionConfigSchema, l as cssColorSchema, m as cssLengthSchema, n as endpointsSchema, o as linkSchema, p as localeSchema, q as pageContextSchema, s as serverConfigSchema, r as siteConfigSchema, t as startConversationResponseSchema, u as userContextSchema, v as uuid7Schema, w as widgetConfigPartialSchema, x as widgetConfigSchema, y as widgetSettingsPartialSchema, z as widgetSettingsSchema } from './deployment-B0uvvJYK.js';
 import { z } from 'zod';
 
 /**
@@ -776,7 +776,7 @@ type I18nOptions = z.infer<typeof i18nSchema>;
  * meaningful in `floating` / `drawer` / `modal` modes.
  *
  * The list arrives via the start-conversation (`config.modules`); each non-chat
- * tab lazy-fetches its content from `GET /ai/agent/content` scoped by its
+ * tab lazy-fetches its content from `GET /content` scoped by its
  * `category`. See `docs/api/messenger-modules.md` + `docs/api/content.md`.
  */