@helpai/elements 0.7.5 → 0.8.1

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 StartSessionResponse, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial } from './deployment-B4_b3Sjy.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 StartSessionResponse, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial } from './deployment-Clv1qhOa.js';
 import 'zod';
 
 /**

package/index.mjs

@@ -1162,6 +1162,17 @@ var AgentTransport = class {
     this.userContext = userContext;
     this.pageContext = pageContext;
   }
+  /**
+   * Seed the visitor + session identity from persistence BEFORE the first
+   * `startSession` resolves. A mount-time `resumeStream()` runs in parallel
+   * with `startSession`, so without this its envelope would carry no
+   * `sessionId` and the resume GET couldn't identify the thread. `startSession`
+   * later overwrites these with the server's authoritative ids (rebind-safe).
+   */
+  primeIdentity(visitorId, sessionId) {
+    if (visitorId) this.visitorId = visitorId;
+    if (sessionId) this.sessionId = sessionId;
+  }
   /** Build the per-request envelope from the current transport state. */
   envelope() {
     const out = {};
@@ -1245,9 +1256,10 @@ var AgentTransport = class {
       cursor: params.cursor
     });
     const res = await this.getJson(url.toString(), "listSessions");
-    log4.debug("listSessions \u2190", { count: res.sessions.length, nextCursor: res.nextCursor });
+    const sessions = res.sessions ?? [];
+    log4.debug("listSessions \u2190", { count: sessions.length, nextCursor: res.nextCursor });
     return {
-      sessions: res.sessions.map((session) => ({
+      sessions: sessions.map((session) => ({
         sessionId: session.sessionId,
         title: session.title,
         lastMessageAt: session.lastMessageAt,
@@ -1263,16 +1275,17 @@ var AgentTransport = class {
     url.searchParams.set("sessionId", sessionId);
     log4.debug("loadSession \u2192", { sessionId, visitorId: this.visitorId });
     const res = await this.getJson(url.toString(), "loadSession");
+    const messages = res.messages ?? [];
     log4.debug("loadSession \u2190", {
       sessionId: res.sessionId,
       canContinue: res.canContinue,
-      messageCount: res.messages.length,
+      messageCount: messages.length,
       hasSuggestions: !!res.suggestions
     });
     return {
       sessionId: res.sessionId,
-      canContinue: res.canContinue,
-      messages: res.messages,
+      canContinue: res.canContinue ?? true,
+      messages,
       agent: res.agent,
       suggestions: res.suggestions
     };
@@ -1306,8 +1319,9 @@ var AgentTransport = class {
     }
     log4.debug("listContent \u2192", query);
     const res = await this.getJson(url.toString(), "listContent");
-    log4.debug("listContent \u2190", { count: res.items.length, total: res.pagination?.total });
-    return res;
+    const items = res.items ?? [];
+    log4.debug("listContent \u2190", { count: items.length, total: res.pagination?.total });
+    return { ...res, items };
   }
   async saveUserPrefs(userPrefs) {
     log4.debug("saveUserPrefs \u2192", {
@@ -1340,12 +1354,62 @@ var AgentTransport = class {
     const cancel = () => this.cancelStream(ctrl, body.sessionId);
     return { iter, cancel };
   }
+  /**
+   * Re-attach to an in-flight reply on a cold page load / refresh.
+   *
+   * UNCONDITIONAL by design — the caller runs this in parallel with
+   * `startSession`, never gated on whether there are persisted messages. If
+   * the user refreshed while the assistant was still streaming, the
+   * `startSession` 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).
+   *
+   * `cancel` only detaches the client (aborts the local read); unlike
+   * `sendMessage` it does NOT POST `/cancel-stream` — the reply may still be
+   * generating for another tab or about to be persisted, and a page-load
+   * resume must never tear that down.
+   */
+  resumeStream() {
+    const ctrl = new AbortController();
+    const seenIds = /* @__PURE__ */ new Set();
+    const iter = this.resumeStreamGen(ctrl, seenIds, true);
+    return { iter, cancel: () => ctrl.abort() };
+  }
   // ---- Stream orchestration ---------------------------------------------
   async *runStream(body, ctrl, seenIds) {
     if (yield* this.drain(this.openMessageStream(body, ctrl.signal), seenIds, ctrl)) return;
+    yield* this.resumeStreamGen(ctrl, seenIds, false);
+  }
+  /**
+   * Re-attach to an in-flight reply via GET /stream-resume, yielding the
+   * (deduped) continuation. Two callers:
+   *   - 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-session, so a reply that was streaming when the
+   *     user reloaded keeps flowing).
+   *
+   * The endpoint ALWAYS opens a 200 SSE stream (mirrors the AI SDK
+   * resumable-stream lib): it replays the in-flight reply from the buffer, or —
+   * when nothing is in flight (reply finished + the buffer was flushed, or
+   * 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-session / 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
+   * endpoint). Retries only a segment that yielded new events but no finish — a
+   * real mid-reply drop. Throws only if every attempt kept yielding new events
+   * yet never finished: a genuinely stuck, incomplete reply.
+   */
+  async *resumeStreamGen(ctrl, seenIds, immediate) {
     for (let attempt = 1; attempt <= MAX_RESUME_ATTEMPTS && !ctrl.signal.aborted; attempt++) {
-      await sleep(RESUME_BACKOFF_MS * attempt, ctrl.signal);
-      if (ctrl.signal.aborted) return;
+      if (!immediate || attempt > 1) {
+        await sleep(RESUME_BACKOFF_MS * attempt, ctrl.signal);
+        if (ctrl.signal.aborted) return;
+      }
       let res;
       try {
         res = await this.fetchImpl(this.resumeUrl(seenIds.size), {
@@ -1363,7 +1427,12 @@ var AgentTransport = class {
         log4.debug("resume \u2192 no in-flight stream", { status: res.status });
         return;
       }
+      const before = seenIds.size;
       if (yield* this.drain(parseChatStream(res, ctrl.signal), seenIds, ctrl)) return;
+      if (seenIds.size === before) {
+        log4.debug("resume \u2192 stream closed with no new events; nothing to resume");
+        return;
+      }
     }
     if (ctrl.signal.aborted) return;
     throw new StreamError("stream incomplete after resume attempts", "server");
@@ -3715,7 +3784,7 @@ function ConversationList({ transport, strings, visitorId, onSelect, onNewChat }
     let cancelled = false;
     transport.listSessions({ visitorId }).then((res) => {
       if (cancelled) return;
-      setChats(res.sessions);
+      setChats(res.sessions ?? []);
       setState("loaded");
     }).catch((err) => {
       if (cancelled) return;
@@ -4606,7 +4675,7 @@ function HelpRoot({ transport, strings, config, nav, panelProps }) {
     setState("loading");
     transport.listContent({ tags, sortBy: "order", limit: 100 }).then((res) => {
       if (cancelled) return;
-      setItems(res.items);
+      setItems(res.items ?? []);
       setState("loaded");
     }).catch((err) => {
       if (cancelled) return;
@@ -4680,7 +4749,7 @@ function HomeRoot(props2) {
   useEffect12(() => {
     if (!config.showRecentMessages) return;
     let cancelled = false;
-    transport.listSessions({ limit: 1 }).then((res) => !cancelled && setRecent(res.sessions[0] ?? null)).catch((err) => !cancelled && log13.warn("listSessions (home) failed", { err }));
+    transport.listSessions({ limit: 1 }).then((res) => !cancelled && setRecent(res.sessions?.[0] ?? null)).catch((err) => !cancelled && log13.warn("listSessions (home) failed", { err }));
     return () => {
       cancelled = true;
     };
@@ -4688,7 +4757,7 @@ function HomeRoot(props2) {
   useEffect12(() => {
     if (!config.contentTags?.length) return;
     let cancelled = false;
-    transport.listContent({ tags: config.contentTags, limit: 6 }).then((res) => !cancelled && setContent(res.items)).catch((err) => !cancelled && log13.warn("listContent (home) failed", { err }));
+    transport.listContent({ tags: config.contentTags, limit: 6 }).then((res) => !cancelled && setContent(res.items ?? [])).catch((err) => !cancelled && log13.warn("listContent (home) failed", { err }));
     return () => {
       cancelled = true;
     };
@@ -4784,7 +4853,7 @@ function NewsRoot({ transport, strings, config, nav, panelProps }) {
     setState("loading");
     transport.listContent({ tags, sortBy: "publishedAt", sortOrder: "desc" }).then((res) => {
       if (cancelled) return;
-      setItems(res.items);
+      setItems(res.items ?? []);
       setState("loaded");
     }).catch((err) => {
       if (cancelled) return;
@@ -5397,10 +5466,11 @@ function App({ options, hostElement, bus }) {
       if (isResume) {
         setLoadingMessages(true);
         try {
-          const chat = res.messages ? { sessionId: persistedChatId, canContinue: res.canContinue ?? true, messages: res.messages } : await transport.loadSession(persistedChatId);
+          const chat = res.messages?.length ? { sessionId: persistedChatId, canContinue: res.canContinue ?? true, messages: res.messages } : await transport.loadSession(persistedChatId);
           if (isStale()) return;
-          messagesSig.value = chat.messages.map(fromWireMessage);
-          setCanSend(chat.canContinue);
+          const loaded = (chat.messages ?? []).map(fromWireMessage);
+          if (loaded.length) messagesSig.value = loaded;
+          setCanSend(chat.canContinue ?? true);
           setSuggestions(chat.suggestions ?? []);
         } catch (err) {
           if (isStale()) return;
@@ -5427,10 +5497,57 @@ function App({ options, hostElement, bus }) {
   useEffect17(() => {
     transport.setContext(options.userContext, toWirePageContext(options.pageContext));
   }, [transport, userSig, pageSig]);
+  const runResume = useCallback8(
+    async (handle) => {
+      let bubble = null;
+      try {
+        for await (const evt of handle.iter) {
+          if (!bubble) {
+            bubble = makeAssistantMessage();
+            reducer.attach(bubble);
+            messagesSig.value = [...messagesSig.value, bubble];
+            setStreaming(true);
+            setActiveCancel(() => handle.cancel);
+            log16.info("resumed in-flight reply on mount");
+          }
+          reducer.apply(evt.chunk);
+          if (evt.chunk.type === "finish" && evt.chunk.canContinue === false) setCanSend(false);
+        }
+        if (bubble) {
+          bubble.status = "complete";
+          feedback.play("messageReceived");
+          emitMessage(bus, options, "assistant", assistantText(bubble));
+        }
+      } catch (err) {
+        if (bubble) {
+          bubble.status = "error";
+          bubble.errorText = errorMessageFor(err, options.strings);
+          feedback.play("error");
+        }
+        log16.debug("mount resume ended without completing", { err });
+      } finally {
+        if (bubble) {
+          reducer.detach();
+          setStreaming(false);
+          setActiveCancel(null);
+          messagesSig.value = [...messagesSig.value];
+        }
+      }
+    },
+    [reducer, messagesSig, feedback, bus, options]
+  );
   useEffect17(() => {
     void runStartSession({ newConversation: false });
+    const persistedSession = sessionIdSig.value;
+    let resume = null;
+    if (persistedSession) {
+      transport.primeIdentity(visitorId, persistedSession);
+      resume = transport.resumeStream();
+      void runResume(resume);
+    }
     return () => {
       connectGenRef.current++;
+      resume?.cancel();
     };
   }, []);
   const lastUserSig = useRef8(userSig);

package/package.json

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

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 StartSessionResponse, 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 startSessionResponseSchema, u as userContextSchema, v as uuid7Schema, w as widgetConfigPartialSchema, x as widgetConfigSchema, y as widgetSettingsPartialSchema, z as widgetSettingsSchema } from './deployment-B4_b3Sjy.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 StartSessionResponse, 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 startSessionResponseSchema, u as userContextSchema, v as uuid7Schema, w as widgetConfigPartialSchema, x as widgetConfigSchema, y as widgetSettingsPartialSchema, z as widgetSettingsSchema } from './deployment-Clv1qhOa.js';
 import { z } from 'zod';
 
 /**
@@ -56,9 +56,9 @@ declare const presentationSchema: z.ZodObject<{
         inset: z.ZodOptional<z.ZodString>;
         initialSize: z.ZodDefault<z.ZodEnum<{
             fullscreen: "fullscreen";
+            normal: "normal";
             expanded: "expanded";
             auto: "auto";
-            normal: "normal";
         }>>;
         autoSizeBreakpoint: z.ZodDefault<z.ZodNumber>;
     }, z.core.$loose>>;
@@ -148,9 +148,9 @@ declare const launcherSizeSchema: z.ZodEnum<{
 }>;
 type LauncherSize = z.infer<typeof launcherSizeSchema>;
 declare const calloutShapeSchema: z.ZodEnum<{
-    callout: "callout";
     pill: "pill";
     bubble: "bubble";
+    callout: "callout";
 }>;
 type CalloutShape = z.infer<typeof calloutShapeSchema>;
 declare const calloutPositionSchema: z.ZodEnum<{
@@ -162,9 +162,9 @@ type CalloutPosition = z.infer<typeof calloutPositionSchema>;
 declare const launcherCalloutSchema: z.ZodObject<{
     text: z.ZodDefault<z.ZodString>;
     shape: z.ZodDefault<z.ZodEnum<{
-        callout: "callout";
         pill: "pill";
         bubble: "bubble";
+        callout: "callout";
     }>>;
     position: z.ZodDefault<z.ZodEnum<{
         auto: "auto";
@@ -195,9 +195,9 @@ declare const launcherOptionsSchema: z.ZodObject<{
     callout: z.ZodOptional<z.ZodObject<{
         text: z.ZodDefault<z.ZodString>;
         shape: z.ZodDefault<z.ZodEnum<{
-            callout: "callout";
             pill: "pill";
             bubble: "bubble";
+            callout: "callout";
         }>>;
         position: z.ZodDefault<z.ZodEnum<{
             auto: "auto";
@@ -240,9 +240,9 @@ type LauncherOptions = z.infer<typeof launcherOptionsSchema>;
 
 declare const initialSizeSchema: z.ZodEnum<{
     fullscreen: "fullscreen";
+    normal: "normal";
     expanded: "expanded";
     auto: "auto";
-    normal: "normal";
 }>;
 declare const resizeOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
@@ -269,9 +269,9 @@ declare const sizeOptionsSchema: z.ZodObject<{
     inset: z.ZodOptional<z.ZodString>;
     initialSize: z.ZodDefault<z.ZodEnum<{
         fullscreen: "fullscreen";
+        normal: "normal";
         expanded: "expanded";
         auto: "auto";
-        normal: "normal";
     }>>;
     autoSizeBreakpoint: z.ZodDefault<z.ZodNumber>;
 }, z.core.$loose>;
@@ -321,38 +321,38 @@ type FeatureFlags = z.infer<typeof featureFlagsSchema>;
  */
 
 declare const actionNameSchema: z.ZodEnum<{
-    close: "close";
     expand: "expand";
     fullscreen: "fullscreen";
     popOut: "popOut";
-    clear: "clear";
-    theme: "theme";
+    close: "close";
     language: "language";
+    theme: "theme";
     history: "history";
+    clear: "clear";
     sound: "sound";
 }>;
 type ActionName = z.infer<typeof actionNameSchema>;
 declare const headerActionsSchema: z.ZodObject<{
     main: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-        close: "close";
         expand: "expand";
         fullscreen: "fullscreen";
         popOut: "popOut";
-        clear: "clear";
-        theme: "theme";
+        close: "close";
         language: "language";
+        theme: "theme";
         history: "history";
+        clear: "clear";
         sound: "sound";
     }>>>;
     overflow: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-        close: "close";
         expand: "expand";
         fullscreen: "fullscreen";
         popOut: "popOut";
-        clear: "clear";
-        theme: "theme";
+        close: "close";
         language: "language";
+        theme: "theme";
         history: "history";
+        clear: "clear";
         sound: "sound";
     }>>>;
 }, z.core.$loose>;
@@ -361,25 +361,25 @@ type HeaderActions = z.infer<typeof headerActionsSchema>;
 declare const headerSchema: z.ZodObject<{
     actions: z.ZodOptional<z.ZodObject<{
         main: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-            close: "close";
             expand: "expand";
             fullscreen: "fullscreen";
             popOut: "popOut";
-            clear: "clear";
-            theme: "theme";
+            close: "close";
             language: "language";
+            theme: "theme";
             history: "history";
+            clear: "clear";
             sound: "sound";
         }>>>;
         overflow: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-            close: "close";
             expand: "expand";
             fullscreen: "fullscreen";
             popOut: "popOut";
-            clear: "clear";
-            theme: "theme";
+            close: "close";
             language: "language";
+            theme: "theme";
             history: "history";
+            clear: "clear";
             sound: "sound";
         }>>>;
     }, z.core.$loose>>;
@@ -396,33 +396,33 @@ type HeaderOptions = z.infer<typeof headerSchema>;
  */
 
 declare const feedbackEventSchema: z.ZodEnum<{
-    voiceStart: "voiceStart";
-    voiceStop: "voiceStop";
     error: "error";
     messageReceived: "messageReceived";
     messageSent: "messageSent";
+    voiceStart: "voiceStart";
+    voiceStop: "voiceStop";
 }>;
 type FeedbackEvent = z.infer<typeof feedbackEventSchema>;
 declare const soundOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     volume: z.ZodDefault<z.ZodNumber>;
     events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-        voiceStart: "voiceStart";
-        voiceStop: "voiceStop";
         error: "error";
         messageReceived: "messageReceived";
         messageSent: "messageSent";
+        voiceStart: "voiceStart";
+        voiceStop: "voiceStop";
     }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
 }, z.core.$loose>;
 type SoundOptions = z.infer<typeof soundOptionsSchema>;
 declare const hapticsOptionsSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-        voiceStart: "voiceStart";
-        voiceStop: "voiceStop";
         error: "error";
         messageReceived: "messageReceived";
         messageSent: "messageSent";
+        voiceStart: "voiceStart";
+        voiceStop: "voiceStop";
     }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodNumber>]>>>;
 }, z.core.$loose>;
 type HapticsOptions = z.infer<typeof hapticsOptionsSchema>;
@@ -431,21 +431,21 @@ declare const feedbackSchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         volume: z.ZodDefault<z.ZodNumber>;
         events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-            voiceStart: "voiceStart";
-            voiceStop: "voiceStop";
             error: "error";
             messageReceived: "messageReceived";
             messageSent: "messageSent";
+            voiceStart: "voiceStart";
+            voiceStop: "voiceStop";
         }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
     }, z.core.$loose>>;
     haptics: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         events: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
-            voiceStart: "voiceStart";
-            voiceStop: "voiceStop";
             error: "error";
             messageReceived: "messageReceived";
             messageSent: "messageSent";
+            voiceStart: "voiceStart";
+            voiceStop: "voiceStop";
         }> & z.core.$partial, z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodNumber>]>>>;
     }, z.core.$loose>>;
 }, z.core.$loose>;
@@ -607,18 +607,18 @@ type I18nOptions = z.infer<typeof i18nSchema>;
  */
 
 declare const moduleLayoutSchema: z.ZodEnum<{
-    home: "home";
     chat: "chat";
     help: "help";
+    home: "home";
     news: "news";
 }>;
 type ModuleLayout = z.infer<typeof moduleLayoutSchema>;
 declare const moduleSchema: z.ZodObject<{
     label: z.ZodString;
     layout: z.ZodEnum<{
-        home: "home";
         chat: "chat";
         help: "help";
+        home: "home";
         news: "news";
     }>;
     contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -644,9 +644,9 @@ type ModuleOptions = z.infer<typeof moduleSchema>;
 declare const modulesSchema: z.ZodArray<z.ZodObject<{
     label: z.ZodString;
     layout: z.ZodEnum<{
-        home: "home";
         chat: "chat";
         help: "help";
+        home: "home";
         news: "news";
     }>;
     contentTags: z.ZodOptional<z.ZodArray<z.ZodString>>;