@oyehello/chat 0.4.0 → 0.5.1

package/dist/index.global.js

@@ -15,6 +15,9 @@ var OyehelloChat = (function (exports) {
     meta;
   };
 
+  // src/protocol.ts
+  var CHAT_PROTOCOL_VERSION = 1;
+
   // src/transport.ts
   async function asError(res, fallbackCode) {
     let body = {};
@@ -25,9 +28,10 @@ var OyehelloChat = (function (exports) {
     return new ChatApiError(body.error ?? `HTTP ${res.status}`, res.status, body.code ?? fallbackCode, body.meta);
   }
   async function openSession(opts) {
-    const body = { agentId: opts.agentId };
+    const body = { agentId: opts.agentId, protocol: CHAT_PROTOCOL_VERSION };
     if (opts.user) body.user = opts.user;
     if (opts.clientTools && opts.clientTools.length > 0) body.clientTools = opts.clientTools;
+    if (opts.fingerprint) body.fingerprint = opts.fingerprint;
     const res = await opts.fetchImpl(`${opts.baseUrl}/chat/sessions`, {
       method: "POST",
       credentials: "omit",
@@ -57,6 +61,15 @@ var OyehelloChat = (function (exports) {
     });
     if (!res.ok) throw await asError(res, res.status === 401 ? "session_expired" : void 0);
   }
+  async function postPageViews(opts) {
+    const res = await opts.fetchImpl(`${opts.baseUrl}/chat/sessions/${opts.sessionId}/page-views`, {
+      method: "POST",
+      credentials: "omit",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${opts.sessionToken}` },
+      body: JSON.stringify({ views: opts.views })
+    });
+    if (!res.ok) throw await asError(res, res.status === 401 ? "session_expired" : void 0);
+  }
   async function endSession(opts) {
     await opts.fetchImpl(`${opts.baseUrl}/chat/sessions/${opts.sessionId}/end`, {
       method: "POST",
@@ -74,6 +87,15 @@ var OyehelloChat = (function (exports) {
     }).catch(() => {
     });
   }
+  async function refreshSessionToken(opts) {
+    const res = await opts.fetchImpl(`${opts.baseUrl}/chat/sessions/${opts.sessionId}/refresh-token`, {
+      method: "POST",
+      credentials: "omit",
+      headers: { Authorization: `Bearer ${opts.sessionToken}` }
+    });
+    if (!res.ok) throw await asError(res, res.status === 401 ? "session_expired" : void 0);
+    return await res.json();
+  }
   async function mintStreamTicket(opts) {
     const res = await opts.fetchImpl(`${opts.baseUrl}/chat/sessions/${opts.sessionId}/stream-ticket`, {
       method: "POST",
@@ -86,15 +108,18 @@ var OyehelloChat = (function (exports) {
   function streamUrl(baseUrl, sessionId, ticket) {
     return `${baseUrl}/chat/sessions/${sessionId}/stream?ticket=${encodeURIComponent(ticket)}`;
   }
-  async function presignAttachment(opts) {
-    const res = await opts.fetchImpl(`${opts.baseUrl}/chat/sessions/${opts.sessionId}/attachments`, {
+  async function uploadAttachment(opts) {
+    const form = new FormData();
+    form.append("file", opts.file, opts.file.name);
+    const res = await opts.fetchImpl(`${opts.baseUrl}/chat/sessions/${opts.sessionId}/upload`, {
       method: "POST",
       credentials: "omit",
-      headers: { "Content-Type": "application/json", Authorization: `Bearer ${opts.sessionToken}` },
-      body: JSON.stringify({ contentType: opts.contentType })
+      headers: { Authorization: `Bearer ${opts.sessionToken}` },
+      body: form
     });
     if (!res.ok) throw await asError(res, res.status === 401 ? "session_expired" : void 0);
-    return await res.json();
+    const j2 = await res.json();
+    return { storageRef: j2.storageRef, contentType: j2.contentType, name: j2.name };
   }
   async function getAttachmentUrl(opts) {
     const res = await opts.fetchImpl(`${opts.baseUrl}/chat/sessions/${opts.sessionId}/attachment-url`, {
@@ -106,9 +131,178 @@ var OyehelloChat = (function (exports) {
     if (!res.ok) throw await asError(res, res.status === 401 ? "session_expired" : void 0);
     return (await res.json()).url;
   }
-  async function uploadToPresigned(uploadUrl, file, fetchImpl) {
-    const res = await fetchImpl(uploadUrl, { method: "PUT", body: file, headers: { "Content-Type": file.type } });
-    if (!res.ok) throw new ChatApiError(`attachment upload failed with HTTP ${res.status}`, res.status);
+
+  // src/fingerprint.ts
+  async function sha256Hex(input) {
+    const g = globalThis;
+    try {
+      if (g.crypto?.subtle && typeof TextEncoder !== "undefined") {
+        const buf = await g.crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+        return Array.from(new Uint8Array(buf)).map((b2) => b2.toString(16).padStart(2, "0")).join("").slice(0, 32);
+      }
+    } catch {
+    }
+    let h = 5381;
+    for (let i = 0; i < input.length; i++) h = (h << 5) + h + input.charCodeAt(i) >>> 0;
+    return h.toString(16).padStart(8, "0");
+  }
+  async function computeDeviceFingerprint() {
+    try {
+      const nav = typeof navigator !== "undefined" ? navigator : null;
+      if (!nav) return null;
+      const scr = typeof screen !== "undefined" ? screen : null;
+      const tz = (() => {
+        try {
+          return Intl.DateTimeFormat().resolvedOptions().timeZone;
+        } catch {
+          return "";
+        }
+      })();
+      const dpr = typeof devicePixelRatio !== "undefined" ? devicePixelRatio : "";
+      const signals = [
+        nav.userAgent,
+        Array.isArray(nav.languages) ? nav.languages.join(",") : "",
+        nav.language,
+        nav.platform,
+        nav.hardwareConcurrency,
+        nav.deviceMemory,
+        scr ? `${scr.width}x${scr.height}x${scr.colorDepth}` : "",
+        dpr,
+        tz
+      ].map((v2) => String(v2 ?? "")).join("|");
+      return await sha256Hex(signals);
+    } catch {
+      return null;
+    }
+  }
+
+  // src/journey.ts
+  var MAX_BUFFER = 25;
+  var storageKey = (agentId) => `oyehello-chat:journey:${agentId}`;
+  var store = () => {
+    try {
+      return globalThis.sessionStorage ?? null;
+    } catch {
+      return null;
+    }
+  };
+  function load(agentId) {
+    const s = store();
+    if (!s) return { views: [], flushed: 0 };
+    try {
+      const raw = s.getItem(storageKey(agentId));
+      if (!raw) return { views: [], flushed: 0 };
+      const parsed = JSON.parse(raw);
+      const views = Array.isArray(parsed?.views) ? parsed.views.filter((v2) => !!v2 && typeof v2.path === "string" && typeof v2.at === "string") : [];
+      const flushedRaw = typeof parsed?.flushed === "number" && parsed.flushed >= 0 ? parsed.flushed : 0;
+      return { views, flushed: Math.min(flushedRaw, views.length) };
+    } catch {
+      return { views: [], flushed: 0 };
+    }
+  }
+  function save(agentId, data) {
+    const s = store();
+    if (!s) return;
+    try {
+      s.setItem(storageKey(agentId), JSON.stringify(data));
+    } catch {
+    }
+  }
+  var sanitizePath = (raw) => (raw || "/").split("?")[0].split("#")[0];
+  function recordView(agentId, path) {
+    try {
+      const p = sanitizePath(path);
+      const data = load(agentId);
+      const last = data.views[data.views.length - 1];
+      if (last && last.path === p) return;
+      data.views.push({ path: p, at: (/* @__PURE__ */ new Date()).toISOString() });
+      if (data.views.length > MAX_BUFFER) {
+        const drop = data.views.length - MAX_BUFFER;
+        data.views = data.views.slice(drop);
+        data.flushed = Math.max(0, data.flushed - drop);
+      }
+      save(agentId, data);
+    } catch {
+    }
+  }
+  function unsentViews(agentId) {
+    try {
+      const data = load(agentId);
+      return data.views.slice(data.flushed);
+    } catch {
+      return [];
+    }
+  }
+  function markFlushed(agentId, count) {
+    if (count <= 0) return;
+    try {
+      const data = load(agentId);
+      data.flushed = Math.min(data.views.length, data.flushed + count);
+      save(agentId, data);
+    } catch {
+    }
+  }
+  function installSpaHooks(onNav) {
+    const originalPush = history.pushState;
+    const originalReplace = history.replaceState;
+    let pushInstalled = false;
+    let replaceInstalled = false;
+    try {
+      history.pushState = function(...args) {
+        const ret = originalPush.apply(this, args);
+        try {
+          onNav();
+        } catch {
+        }
+        return ret;
+      };
+      pushInstalled = true;
+    } catch {
+    }
+    try {
+      history.replaceState = function(...args) {
+        const ret = originalReplace.apply(this, args);
+        try {
+          onNav();
+        } catch {
+        }
+        return ret;
+      };
+      replaceInstalled = true;
+    } catch {
+    }
+    const onPopState = () => {
+      try {
+        onNav();
+      } catch {
+      }
+    };
+    let popstateInstalled = false;
+    try {
+      window.addEventListener("popstate", onPopState);
+      popstateInstalled = true;
+    } catch {
+    }
+    return () => {
+      if (pushInstalled) {
+        try {
+          history.pushState = originalPush;
+        } catch {
+        }
+      }
+      if (replaceInstalled) {
+        try {
+          history.replaceState = originalReplace;
+        } catch {
+        }
+      }
+      if (popstateInstalled) {
+        try {
+          window.removeEventListener("popstate", onPopState);
+        } catch {
+        }
+      }
+    };
   }
 
   // src/client.ts
@@ -131,13 +325,97 @@ var OyehelloChat = (function (exports) {
     let reconnectTimer = null;
     let reconnectAttempts = 0;
     let closed = false;
+    let warnedProtocol = false;
+    let deviceFingerprint;
+    let refreshTimer = null;
     const toolHandlers = /* @__PURE__ */ new Map();
+    let journeyFlushChain = Promise.resolve();
+    let journeyFlushQueued = false;
+    const flushJourney = () => {
+      if (!session) return;
+      if (journeyFlushQueued) return;
+      journeyFlushQueued = true;
+      journeyFlushChain = journeyFlushChain.then(async () => {
+        journeyFlushQueued = false;
+        if (!session) return;
+        const pending = unsentViews(options.agentId);
+        if (pending.length === 0) return;
+        const s = session;
+        try {
+          await postPageViews({ baseUrl: options.baseUrl, sessionId: s.sessionId, sessionToken: s.sessionToken, views: pending, fetchImpl });
+          markFlushed(options.agentId, pending.length);
+        } catch {
+        }
+      });
+    };
     const clearReconnect = () => {
       if (reconnectTimer) {
         clearTimeout(reconnectTimer);
         reconnectTimer = null;
       }
     };
+    const clearRefresh = () => {
+      if (refreshTimer) {
+        clearTimeout(refreshTimer);
+        refreshTimer = null;
+      }
+    };
+    const scheduleRefresh = () => {
+      clearRefresh();
+      if (closed || !session) return;
+      const untilExpiry = Date.parse(session.expiresAt) - Date.now();
+      const delay = Number.isNaN(untilExpiry) ? 10 * 6e4 : Math.max(5e3, untilExpiry - 6e4);
+      refreshTimer = setTimeout(async () => {
+        if (closed || !session) return;
+        try {
+          const r = await refreshSessionToken({ baseUrl: options.baseUrl, sessionId: session.sessionId, sessionToken: session.sessionToken, fetchImpl });
+          session = { ...session, sessionToken: r.sessionToken, expiresAt: r.expiresAt };
+          persistSession(session);
+          scheduleRefresh();
+        } catch (err) {
+          const code = err?.code;
+          if (code === "session_ended" || code === "session_expired") clearStoredSession();
+        }
+      }, delay);
+      refreshTimer.unref?.();
+    };
+    const sessKey = `oyehello-chat-sess:${options.agentId}`;
+    const store2 = (() => {
+      try {
+        return globalThis.sessionStorage ?? null;
+      } catch {
+        return null;
+      }
+    })();
+    const loadStoredSession = () => {
+      if (!store2) return null;
+      try {
+        const raw = store2.getItem(sessKey);
+        if (!raw) return null;
+        const s = JSON.parse(raw);
+        if (!s?.sessionId || !s?.sessionToken || !s?.expiresAt || !s?.agent) return null;
+        const exp = Date.parse(s.expiresAt);
+        if (Number.isNaN(exp) || Date.now() >= exp - 5e3) {
+          store2.removeItem(sessKey);
+          return null;
+        }
+        return s;
+      } catch {
+        return null;
+      }
+    };
+    const persistSession = (s) => {
+      try {
+        store2?.setItem(sessKey, JSON.stringify({ sessionId: s.sessionId, sessionToken: s.sessionToken, expiresAt: s.expiresAt, agent: s.agent }));
+      } catch {
+      }
+    };
+    const clearStoredSession = () => {
+      try {
+        store2?.removeItem(sessKey);
+      } catch {
+      }
+    };
     const emit = (e) => {
       for (const l of listeners) l(e);
     };
@@ -225,6 +503,14 @@ var OyehelloChat = (function (exports) {
         emit({ type: "agentTyping", active: !!ev.active });
       } else if (ev.type === "suggestions") {
         emit({ type: "suggestions", items: Array.isArray(ev.items) ? ev.items : [] });
+      } else if (ev.type === "done") {
+        closed = true;
+        clearReconnect();
+        clearRefresh();
+        es?.close();
+        es = null;
+        clearStoredSession();
+        setState("ended");
       }
     };
     const openStream = async () => {
@@ -256,6 +542,7 @@ var OyehelloChat = (function (exports) {
       reconnectTimer = setTimeout(() => {
         openStream().catch((err) => {
           if (err instanceof ChatApiError && err.code === "session_expired") {
+            clearStoredSession();
             open().catch((e) => {
               emit({ type: "error", error: e });
               scheduleReconnect();
@@ -267,16 +554,32 @@ var OyehelloChat = (function (exports) {
       }, delay);
     };
     const open = async () => {
-      session = await openSession({ baseUrl: options.baseUrl, apiKey: options.apiKey, agentId: options.agentId, user: options.user, clientTools: Array.from(toolHandlers.keys()), fetchImpl });
+      const resumed = loadStoredSession();
+      if (resumed) {
+        session = resumed;
+        emit({ type: "agent", agent: resumed.agent });
+        await openStream();
+        scheduleRefresh();
+        flushJourney();
+        return;
+      }
+      if (deviceFingerprint === void 0) deviceFingerprint = await computeDeviceFingerprint().catch(() => null);
+      session = await openSession({ baseUrl: options.baseUrl, apiKey: options.apiKey, agentId: options.agentId, user: options.user, clientTools: Array.from(toolHandlers.keys()), fingerprint: deviceFingerprint ?? void 0, fetchImpl });
+      persistSession(session);
+      if (!warnedProtocol && typeof session.protocol === "number" && session.protocol !== CHAT_PROTOCOL_VERSION) {
+        warnedProtocol = true;
+        try {
+          console.warn(`[oyehello-chat] SDK protocol v${CHAT_PROTOCOL_VERSION} vs server v${session.protocol} - update @oyehello/chat to the latest version.`);
+        } catch {
+        }
+      }
       emit({ type: "agent", agent: session.agent });
       await openStream();
+      scheduleRefresh();
+      flushJourney();
     };
     const uploadFiles = async (files) => {
-      return Promise.all(files.map(async (file) => {
-        const { storageRef, uploadUrl } = await presignAttachment({ baseUrl: options.baseUrl, sessionId: session.sessionId, sessionToken: session.sessionToken, contentType: file.type, fetchImpl });
-        await uploadToPresigned(uploadUrl, file, fetchImpl);
-        return { storageRef, contentType: file.type, name: file.name };
-      }));
+      return Promise.all(files.map((file) => uploadAttachment({ baseUrl: options.baseUrl, sessionId: session.sessionId, sessionToken: session.sessionToken, file, fetchImpl })));
     };
     return {
       getMessages: () => messages.slice(),
@@ -295,6 +598,13 @@ var OyehelloChat = (function (exports) {
       getWidgetConfig() {
         return getWidgetConfig({ baseUrl: options.baseUrl, apiKey: options.apiKey, agentId: options.agentId, fetchImpl });
       },
+      recordPageView(path) {
+        try {
+          recordView(options.agentId, path);
+          flushJourney();
+        } catch {
+        }
+      },
       async start() {
         if (state === "opening" || state === "ready") return;
         closed = false;
@@ -340,6 +650,7 @@ var OyehelloChat = (function (exports) {
         } catch (err) {
           if (err instanceof ChatApiError && err.code === "session_expired") {
             try {
+              clearStoredSession();
               await open();
               const freshAttachments = fileList.length ? await uploadFiles(fileList) : [];
               await postMessage({ baseUrl: options.baseUrl, sessionId: session.sessionId, sessionToken: session.sessionToken, text: text2, attachments: freshAttachments, fetchImpl });
@@ -351,13 +662,38 @@ var OyehelloChat = (function (exports) {
           }
         }
       },
+      detach() {
+        closed = true;
+        clearReconnect();
+        clearRefresh();
+        es?.close();
+        es = null;
+      },
       async end() {
         closed = true;
         clearReconnect();
+        clearRefresh();
+        clearStoredSession();
         if (session) await endSession({ baseUrl: options.baseUrl, sessionId: session.sessionId, sessionToken: session.sessionToken, fetchImpl });
         es?.close();
         es = null;
         setState("ended");
+      },
+      reset() {
+        clearStoredSession();
+        es?.close();
+        es = null;
+        clearReconnect();
+        clearRefresh();
+        session = null;
+        streamingId = null;
+        handoffState = "ai";
+        messages.length = 0;
+        seenTurnIds.clear();
+        seenCallIds.clear();
+        emit({ type: "messages", messages: [] });
+        emit({ type: "handoff", state: "ai" });
+        setState("idle");
       }
     };
   }
@@ -3319,6 +3655,10 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     --oc-glass-border: rgba(9,13,20,0.12);
 
     position: fixed; right: 24px; bottom: 24px; z-index: 2147483000;
+    /* Explicit display/visibility so a host-page reset or consent/privacy tool that blanket-hides
+     * body children (oyehello-chat { display:none }) can't silently kill the widget. Also pinned
+     * inline with !important at mount (see element.ts) to beat an external !important rule. */
+    display: block; visibility: visible; opacity: 1;
     font-family: 'Geist', system-ui, -apple-system, 'Helvetica Neue', sans-serif;
     -webkit-font-smoothing: antialiased;
   }
@@ -3358,7 +3698,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
   .launcher:hover { transform: scale(1.06); }
   .launcher:active { transform: scale(0.93); }
   .ring { pointer-events: none; position: absolute; inset: -1px; border-radius: var(--oc-r-full); border: 2px solid var(--oc-ac); opacity: 0; }
-  .oc.ring:not(.open) .ring { animation: w-ring 2.4s ease-out 1.1s 3; }
+  .oc.show-ring:not(.open) .ring { animation: w-ring 2.4s ease-out 1.1s 3; }
   .ic-chat, .ic-close { position: absolute; display: flex; align-items: center; justify-content: center; transition: all .3s var(--oc-bounce); }
   .ic-chat { width: 28px; height: 28px; opacity: 1; transform: rotate(0) scale(1); }
   .ic-close { opacity: 0; transform: rotate(90deg) scale(0.6); }
@@ -3380,7 +3720,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     transition: opacity .3s var(--oc-ease), transform .38s var(--oc-bounce);
   }
   .oc.has-teaser .teaser { display: flex; }
-  .oc.teaser:not(.open) .teaser { opacity: 1; transform: none; pointer-events: auto; }
+  .oc.show-teaser:not(.open) .teaser { opacity: 1; transform: none; pointer-events: auto; }
   .teaser-btn {
     max-width: 250px; display: flex; align-items: center; gap: 10px; padding: 11px 15px;
     border-radius: 16px 16px 5px 16px; border: 1px solid var(--oc-glass-border); background: var(--oc-bg);
@@ -3427,6 +3767,12 @@ Please report this to https://github.com/markedjs/marked.`, e) {
   .oc-err-retry { padding: 7px 15px; font-size: 12.5px; font-weight: 500; border-radius: var(--oc-r-full); border: 1px solid var(--oc-border); background: var(--oc-tint-2); color: var(--oc-fg); cursor: pointer; transition: background .18s var(--oc-ease); }
   .oc-err-retry:hover { background: var(--oc-tint-3); }
 
+  /* Session-ended state, inside the chat window */
+  .oc-ended { margin: auto; display: flex; flex-direction: column; align-items: center; gap: 12px; padding: 24px 16px; text-align: center; }
+  .oc-ended-t { font-size: 13.5px; line-height: 1.5; color: var(--oc-fg-muted); text-wrap: pretty; }
+  .oc-newmsg { padding: 9px 18px; font-size: 13px; font-weight: 600; border-radius: var(--oc-r-full); border: 1px solid var(--oc-btn-rim); background: var(--oc-ac); color: #fff; box-shadow: var(--oc-btn-edge); cursor: pointer; transition: filter .18s var(--oc-ease); }
+  .oc-newmsg:hover { filter: brightness(1.08); }
+
   /* \u2500\u2500 Message list \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
   .body { flex: 1 1 auto; min-height: 0; overflow-y: auto; display: flex; flex-direction: column; gap: 16px; padding: 16px 16px 26px; background: var(--oc-bg); scroll-behavior: smooth; }
   .turn { display: flex; flex-direction: column; gap: 6px; animation: w-in .42s var(--oc-ease) both; }
@@ -3471,6 +3817,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
 
   /* \u2500\u2500 Composer \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
   .composer { flex: none; display: flex; flex-direction: column; gap: 9px; padding: 12px 14px 13px; background: var(--oc-bg); }
+  .composer[hidden] { display: none; }
   .field { display: flex; flex-direction: column; gap: 11px; padding: 13px 14px 11px; border-radius: 18px; border: 1px solid var(--oc-field-border); background: var(--oc-field-bg); transition: border-color .18s var(--oc-ease); }
   .oc.focus .field { border-color: var(--oc-ac); }
   .input { width: 100%; border: none; background: transparent; color: var(--oc-fg); font-size: 13.5px; line-height: 1.4; outline: none; padding: 0; resize: none; max-height: 108px; font-family: inherit; }
@@ -3696,14 +4043,29 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     // Server (flow) suggestions for the latest turn; null until the first `suggestions` event, then the
     // widget prefers these over the static `suggestions` attribute.
     serverSuggestions = null;
+    // The live streaming assistant bubble's markdown element + message id — so growing tokens patch just
+    // that element in place instead of rebuilding the whole message list on every token.
+    streamId = null;
+    streamEl = null;
+    audioCtx = null;
     teaserText = "Need a hand? Ask me anything.";
     teaserShownOnce = false;
+    // Staffed-hours: set from widget-config. When offline, the panel shows offlineMessage and the
+    // composer is disabled (opening a session is refused server-side anyway).
+    offline = false;
+    offlineMessage = "We're offline right now. Please check back during business hours.";
+    configLoaded = false;
+    // widget-config resolved (so we know online/offline before starting)
     idleTimer = null;
     idleReset = null;
+    // Uninstaller for the SPA history-navigation hooks (journey tracking), installed in
+    // connectedCallback and torn down in disconnectedCallback alongside everything else.
+    uninstallSpaHooks = null;
     // ── shadow refs ──
     oc;
     bodyEl;
     textareaEl;
+    composerEl;
     fileEl;
     titleEl;
     statusEl;
@@ -3725,7 +4087,16 @@ Please report this to https://github.com/markedjs/marked.`, e) {
         this.pendingTools = {};
       }
       this.off = this.client.on((e) => this.onClientEvent(e));
+      recordView(agentId, location.pathname);
+      try {
+        this.uninstallSpaHooks = installSpaHooks(() => this.client?.recordPageView(location.pathname));
+      } catch {
+        this.uninstallSpaHooks = null;
+      }
       this.renderShell();
+      this.style.setProperty("display", "block", "important");
+      this.style.setProperty("visibility", "visible", "important");
+      this.style.setProperty("opacity", "1", "important");
       this.renderMessages();
       this.updateHeader();
       this.updateStatus();
@@ -3742,7 +4113,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       }
       this.updateClasses(true);
       this.timers.push(setTimeout(() => {
-        this.oc?.classList.remove("ring");
+        this.oc?.classList.remove("show-ring");
       }, 6e3));
       this.armIdleTeaser();
     }
@@ -3795,7 +4166,19 @@ Please report this to https://github.com/markedjs/marked.`, e) {
           }
           if (cfg.brand.logoUrl) this.applyBrandLogo(cfg.brand.logoUrl);
         }
+        if (cfg.offline) {
+          this.offline = true;
+          if (cfg.offlineMessage) this.offlineMessage = cfg.offlineMessage;
+          this.renderMessages();
+          this.updateStatus();
+        }
       } catch {
+      } finally {
+        this.configLoaded = true;
+        if (this.uiOpen && !this.started && !this.offline && this.client) {
+          this.started = true;
+          void this.client.start();
+        }
       }
     }
     applyTeaserText() {
@@ -3817,8 +4200,10 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     }
     disconnectedCallback() {
       this.off?.();
-      void this.client?.end();
+      this.client?.detach();
       this.teardownIdle();
+      this.uninstallSpaHooks?.();
+      this.uninstallSpaHooks = null;
       for (const t of this.timers) clearTimeout(t);
       for (const url of this.imagePreviewCache.values()) {
         if (typeof URL.revokeObjectURL === "function") URL.revokeObjectURL(url);
@@ -3896,6 +4281,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       this.oc = root.querySelector(".oc");
       this.bodyEl = root.querySelector(".body");
       this.textareaEl = root.querySelector("textarea.input");
+      this.composerEl = root.querySelector(".composer");
       this.fileEl = root.querySelector('input[type="file"]');
       this.titleEl = root.querySelector(".hd-title");
       this.statusEl = root.querySelector(".hd-status .t");
@@ -3954,18 +4340,22 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       this.shadowRoot.innerHTML = `<div style="position:fixed;right:16px;bottom:16px;color:#b91c1c;font:12px system-ui;background:#fef2f2;border:1px solid #fecaca;padding:8px 12px;border-radius:8px">${escapeHtml(msg)}</div>`;
     }
     // ── State-class sync ──────────────────────────────────────────────────────────────────────────
+    // State classes on `.oc` MUST NOT share a name with any element class that has a bare base rule
+    // (e.g. `.teaser`, `.ring`): the bare selector would also match `.oc.<state>` and, tying `.oc`'s
+    // own rule on specificity, win on source order — e.g. `.teaser{display:none}` would hide the whole
+    // widget. Hence the `show-` prefix on the teaser/ring state classes.
     updateClasses(initialRing = false) {
       if (!this.oc) return;
       const c = this.oc.classList;
       c.toggle("open", this.uiOpen);
       c.toggle("max", this.uiMax);
       c.toggle("emoji", this.emojiOpen);
-      c.toggle("teaser", this.teaserActive);
+      c.toggle("show-teaser", this.teaserActive);
       c.toggle("away", this.away);
       c.toggle("focus", this.focused);
       c.toggle("ready", (this.textareaEl?.value.trim().length ?? 0) > 0);
       c.toggle("unread", this.unseen > 0);
-      if (initialRing) c.add("ring");
+      if (initialRing) c.add("show-ring");
       const badge = this.oc.querySelector(".badge");
       if (badge) badge.textContent = this.unseen > 9 ? "9+" : String(this.unseen);
       const launcher = this.oc.querySelector(".launcher");
@@ -3984,7 +4374,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
         sessionStorage.setItem(this.key("open"), "1");
       } catch {
       }
-      if (!this.started && this.client) {
+      if (!this.started && this.client && this.configLoaded && !this.offline) {
         this.started = true;
         void this.client.start();
       }
@@ -4032,16 +4422,23 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     }
     updateStatus() {
       if (!this.textareaEl) return;
-      const disabled = this.state !== "ready";
+      const disabled = this.state !== "ready" || this.offline;
       this.textareaEl.disabled = disabled;
+      if (this.composerEl) this.composerEl.hidden = this.state === "ended" || this.offline;
       const handoff = HANDOFF_STATUS[this.handoffState];
-      const text2 = this.state === "opening" ? "Connecting\u2026" : handoff ?? (this.getAttribute("status") ?? DEFAULT_STATUS);
+      const text2 = this.offline ? "Offline" : this.state === "opening" ? "Connecting\u2026" : handoff ?? (this.getAttribute("status") ?? DEFAULT_STATUS);
       if (this.statusEl) this.statusEl.textContent = text2;
     }
     // ── Message list + scroll ─────────────────────────────────────────────────────────────────────
     renderMessages() {
       if (!this.bodyEl) return;
       const body = this.bodyEl;
+      const last = this.messages[this.messages.length - 1];
+      if (this.uiOpen && this.streamEl && last && last.id === this.streamId && last.role === "assistant" && last.streaming && this.messages.length === this.renderedCount) {
+        this.streamEl.innerHTML = renderMarkdown(last.text || "");
+        if (!this.away) this.scrollToBottom();
+        return;
+      }
       const prevTop = body.scrollTop;
       const added = this.messages.length - this.renderedCount;
       const botFinal = this.messages.filter((m2) => m2.role === "assistant" && !m2.streaming).length;
@@ -4061,13 +4458,29 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       if (this.state === "error" && this.lastError) {
         html2 += `<div class="oc-err"><span class="oc-err-t">${escapeHtml(this.lastError)}</span><button type="button" class="oc-err-retry">Try again</button></div>`;
       }
+      if (this.state === "ended") {
+        html2 += `<div class="oc-ended"><span class="oc-ended-t">Your conversation has ended.</span><button type="button" class="oc-newmsg">New message</button></div>`;
+      }
+      if (this.offline && this.messages.length === 0 && this.state !== "ended") {
+        html2 += `<div class="oc-ended"><span class="oc-ended-t">${escapeHtml(this.offlineMessage)}</span></div>`;
+      }
       body.innerHTML = html2;
       this.hydrateAttachmentImages();
       this.bindChips();
       this.renderedCount = this.messages.length;
       this.renderedBotFinal = botFinal;
+      this.streamId = null;
+      this.streamEl = null;
+      if (last && last.role === "assistant" && last.streaming) {
+        const mds = this.bodyEl.querySelectorAll(".turn.bot .md");
+        this.streamEl = mds[mds.length - 1] ?? null;
+        if (this.streamEl) this.streamId = last.id;
+      }
       if (!this.uiOpen) {
-        if (added > 0) this.unseen += added;
+        if (added > 0) {
+          this.unseen += added;
+          this.maybeChime();
+        }
         this.updateClasses();
         return;
       }
@@ -4075,7 +4488,10 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       else if (!this.away) this.scrollToBottom();
       else {
         body.scrollTop = prevTop;
-        if (added > 0) this.unseen += added;
+        if (added > 0) {
+          this.unseen += added;
+          this.maybeChime();
+        }
       }
       this.updateClasses();
     }
@@ -4126,6 +4542,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       }
       this.away = false;
       this.emojiOpen = false;
+      this.serverSuggestions = [];
       void this.client?.sendMessage(text2, files.length > 0 ? files : void 0);
       this.textareaEl.value = "";
       this.textareaEl.style.height = "auto";
@@ -4134,6 +4551,7 @@ Please report this to https://github.com/markedjs/marked.`, e) {
     sendChip(text2) {
       this.away = false;
       this.emojiOpen = false;
+      this.serverSuggestions = [];
       void this.client?.sendMessage(text2);
       this.updateClasses();
     }
@@ -4147,6 +4565,56 @@ Please report this to https://github.com/markedjs/marked.`, e) {
       this.bodyEl.querySelector(".oc-err-retry")?.addEventListener("click", () => {
         void this.client?.start();
       });
+      this.bodyEl.querySelector(".oc-newmsg")?.addEventListener("click", () => this.startFresh());
+    }
+    // Reset the thread and open a brand-new session (the widget's "New message" after a session ended).
+    startFresh() {
+      this.serverSuggestions = null;
+      this.receivedAt.clear();
+      this.mdCache.clear();
+      this.streamId = null;
+      this.streamEl = null;
+      this.renderedCount = 0;
+      this.renderedBotFinal = 0;
+      this.away = false;
+      this.unseen = 0;
+      this.client?.reset();
+      this.started = true;
+      void this.client?.start();
+      setTimeout(() => this.textareaEl?.focus(), 60);
+    }
+    // A short two-tone chime for an incoming message the visitor hasn't seen (panel closed or scrolled
+    // up). Off when the `sound="off"` attribute is set. Uses WebAudio (no asset); silent if unavailable
+    // or the browser hasn't allowed audio yet.
+    maybeChime() {
+      const last = this.messages[this.messages.length - 1];
+      if (last && (last.role === "assistant" || last.role === "human")) this.playChime();
+    }
+    playChime() {
+      if (this.getAttribute("sound") === "off") return;
+      try {
+        const Ctx = window.AudioContext ?? window.webkitAudioContext;
+        if (!Ctx) return;
+        if (!this.audioCtx) this.audioCtx = new Ctx();
+        const ctx = this.audioCtx;
+        if (ctx.state === "suspended") void ctx.resume();
+        const now = ctx.currentTime;
+        [880, 1174.66].forEach((freq, i) => {
+          const osc = ctx.createOscillator();
+          const gain = ctx.createGain();
+          osc.type = "sine";
+          osc.frequency.value = freq;
+          const t = now + i * 0.11;
+          gain.gain.setValueAtTime(1e-4, t);
+          gain.gain.exponentialRampToValueAtTime(0.12, t + 0.02);
+          gain.gain.exponentialRampToValueAtTime(1e-4, t + 0.18);
+          osc.connect(gain);
+          gain.connect(ctx.destination);
+          osc.start(t);
+          osc.stop(t + 0.2);
+        });
+      } catch {
+      }
     }
     // ── Emoji ─────────────────────────────────────────────────────────────────────────────────────
     toggleEmoji() {