@xbrain-swe/nova-chat-widget 0.1.11 → 0.3.0-dev.16

package/dist/index.js

@@ -1,13 +1,13 @@
 "use client";
 
 // src/provider.tsx
-import { useEffect as useEffect5, useMemo as useMemo2 } from "react";
+import { useEffect as useEffect6, useMemo as useMemo2 } from "react";
 
 // src/client-actions.tsx
-import { useEffect, useRef as useRef2 } from "react";
+import { useEffect as useEffect2, useRef as useRef2 } from "react";
 
 // src/internal-context.tsx
-import { createContext, useContext, useMemo, useRef } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef } from "react";
 import { jsx } from "react/jsx-runtime";
 var DEFAULT_THEME = {
   accentFrom: "#4f46e5",
@@ -25,6 +25,7 @@ function useXbNovaInternal() {
   return ctx;
 }
 var VISITOR_STORAGE_KEY = "xbnova_visitor_id";
+var WIDGET_VIEW_WAIT_MS = 1e4;
 function resolveVisitorId() {
   if (typeof window === "undefined") return "";
   try {
@@ -65,6 +66,44 @@ function InternalProvider({
   if (visitorIdRef.current === null) {
     visitorIdRef.current = resolveVisitorId();
   }
+  const visitorId = auth.userKey || visitorIdRef.current;
+  const sessionId = auth.sessionKey || null;
+  const latestRef = useRef({ auth, visitorId, sessionId });
+  latestRef.current = { auth, visitorId, sessionId };
+  const sendEvent = useCallback((event, properties = {}) => {
+    const { auth: a, visitorId: v, sessionId: sid } = latestRef.current;
+    if (!v) return;
+    const { conversation_id: conversationId, ...rest } = properties;
+    fetch(`${a.apiBaseUrl}/v1/events`, {
+      method: "POST",
+      keepalive: true,
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${a.apiKey}` },
+      body: JSON.stringify({
+        app_id: a.appId,
+        event,
+        visitor_id: v,
+        session_id: sid,
+        conversation_id: conversationId ?? null,
+        properties: { screen: a.screen, ...rest }
+      })
+    }).catch(() => {
+    });
+  }, []);
+  const widgetViewSentRef = useRef(false);
+  useEffect(() => {
+    if (widgetViewSentRef.current) return;
+    const send = () => {
+      if (widgetViewSentRef.current) return;
+      widgetViewSentRef.current = true;
+      sendEvent("widget_view");
+    };
+    if (sessionId) {
+      send();
+      return;
+    }
+    const timer = setTimeout(send, WIDGET_VIEW_WAIT_MS);
+    return () => clearTimeout(timer);
+  }, [sessionId, sendEvent]);
   const value = useMemo(
     () => ({
       auth,
@@ -72,10 +111,12 @@ function InternalProvider({
       factsRegistry,
       contextRegistry,
       clientActionHandlers: clientActionHandlers ?? emptyHandlers,
-      visitorId: visitorIdRef.current,
+      visitorId,
+      sessionId,
+      sendEvent,
       theme
     }),
-    [auth, trackRegistry, factsRegistry, contextRegistry, clientActionHandlers, emptyHandlers, theme]
+    [auth, trackRegistry, factsRegistry, contextRegistry, clientActionHandlers, emptyHandlers, visitorId, sessionId, sendEvent, theme]
   );
   return /* @__PURE__ */ jsx(InternalContext.Provider, { value, children });
 }
@@ -96,7 +137,7 @@ function XbNovaClientActionSync({ actions }) {
   const { auth } = useXbNovaInternal();
   const { apiKey, apiBaseUrl, appId } = auth;
   const lastSyncedRef = useRef2(null);
-  useEffect(() => {
+  useEffect2(() => {
     if (!actions || Object.keys(actions).length === 0) return;
     const serialized = JSON.stringify(toSyncPayload(actions));
     if (serialized === lastSyncedRef.current) return;
@@ -150,7 +191,7 @@ function peekVisitCount(screen) {
 }
 
 // src/nudge-context.tsx
-import { createContext as createContext2, useCallback, useContext as useContext2, useEffect as useEffect2, useRef as useRef3, useState } from "react";
+import { createContext as createContext2, useCallback as useCallback2, useContext as useContext2, useEffect as useEffect3, useRef as useRef3, useState } from "react";
 import { jsx as jsx2 } from "react/jsx-runtime";
 var NudgeContext = createContext2(null);
 var HINTS_DISABLED_KEY = "xbnova_hints_disabled";
@@ -194,43 +235,43 @@ function NudgeStateProvider({ children }) {
   const [hintsEnabled, setHintsEnabled] = useState(() => !readFlag(HINTS_DISABLED_KEY));
   const [barHidden, setBarHidden] = useState(() => readFlag(BAR_HIDDEN_KEY));
   const streakRef = useRef3(readStreak());
-  const disableHints = useCallback(() => {
+  const disableHints = useCallback2(() => {
     setHintsEnabled(false);
     writeFlag(HINTS_DISABLED_KEY, true);
   }, []);
-  const enableHints = useCallback(() => {
+  const enableHints = useCallback2(() => {
     setHintsEnabled(true);
     writeFlag(HINTS_DISABLED_KEY, false);
     streakRef.current = 0;
     writeStreak(0);
   }, []);
-  const hideBar = useCallback(() => {
+  const hideBar = useCallback2(() => {
     setBarHidden(true);
     writeFlag(BAR_HIDDEN_KEY, true);
   }, []);
-  const showBar = useCallback(() => {
+  const showBar = useCallback2(() => {
     setBarHidden(false);
     writeFlag(BAR_HIDDEN_KEY, false);
   }, []);
-  const offerHint = useCallback((next) => {
+  const offerHint = useCallback2((next) => {
     setHint((current) => current ? current : next);
   }, []);
-  useEffect2(() => {
+  useEffect3(() => {
     if (hint) setLastHint(hint);
   }, [hint]);
-  const dismissHint = useCallback(() => {
+  const dismissHint = useCallback2(() => {
     const limit = hint?.autoDisableAfterDismissals ?? DEFAULT_DISMISS_STREAK_LIMIT;
     setHint(null);
     streakRef.current += 1;
     writeStreak(streakRef.current);
     if (streakRef.current >= limit) disableHints();
   }, [hint, disableHints]);
-  const openHint = useCallback(() => {
+  const openHint = useCallback2(() => {
     setHint(null);
     streakRef.current = 0;
     writeStreak(0);
   }, []);
-  const autoHideHint = useCallback(() => {
+  const autoHideHint = useCallback2(() => {
     setHint(null);
   }, []);
   return /* @__PURE__ */ jsx2(
@@ -267,10 +308,10 @@ function useXbNovaSettings() {
 }
 
 // src/nudge-loop.tsx
-import { useCallback as useCallback3, useEffect as useEffect4, useRef as useRef5 } from "react";
+import { useCallback as useCallback4, useEffect as useEffect5, useRef as useRef5 } from "react";
 
 // src/track.tsx
-import { useCallback as useCallback2, useEffect as useEffect3, useRef as useRef4 } from "react";
+import { useCallback as useCallback3, useEffect as useEffect4, useRef as useRef4 } from "react";
 import { jsx as jsx3 } from "react/jsx-runtime";
 var VISIBILITY_THRESHOLD = 0;
 function finalizeIfVisible(registry, region) {
@@ -287,7 +328,7 @@ function useXbNovaTrack(region, data, label) {
   dataRef.current = data;
   const labelRef = useRef4(label);
   labelRef.current = label;
-  useEffect3(() => {
+  useEffect4(() => {
     const entry = trackRegistry.get(region);
     if (entry) {
       entry.data = data;
@@ -296,7 +337,7 @@ function useXbNovaTrack(region, data, label) {
       trackRegistry.set(region, { region, data, label, enteredAt: null, totalMs: 0, node: null });
     }
   }, [region, data, label, trackRegistry]);
-  useEffect3(() => {
+  useEffect4(() => {
     return () => {
       observerRef.current?.disconnect();
       finalizeIfVisible(trackRegistry, region);
@@ -304,7 +345,7 @@ function useXbNovaTrack(region, data, label) {
       if (entry) entry.node = null;
     };
   }, [region, trackRegistry]);
-  return useCallback2(
+  return useCallback3(
     (node) => {
       observerRef.current?.disconnect();
       observerRef.current = null;
@@ -378,7 +419,7 @@ function getFocusedTrackEntry(trackRegistry) {
 }
 
 // src/nudge-loop.tsx
-var EVAL_INTERVAL_MS = 1e3;
+var EVAL_INTERVAL_MS = 250;
 var XBNOVA_EVENT_NAME = "xbnova:event";
 var SESSION_COUNT_KEY_PREFIX = "xbnova_hint_session_count:";
 var SCROLL_SETTLE_MS = 500;
@@ -571,7 +612,7 @@ function clearDebugOverlay(refs) {
   refs.bandLinesRef.current.clear();
 }
 function XbNovaNudgeLoop({ appId }) {
-  const { auth, trackRegistry, factsRegistry, visitorId } = useXbNovaInternal();
+  const { auth, trackRegistry, factsRegistry, sendEvent } = useXbNovaInternal();
   const { apiKey, apiBaseUrl, screen } = auth;
   const { hint, offerHint, autoHideHint, hintsEnabled } = useNudgeState();
   const graphRef = useRef5(null);
@@ -586,7 +627,7 @@ function XbNovaNudgeLoop({ appId }) {
   hintRef.current = hint;
   const hintsEnabledRef = useRef5(hintsEnabled);
   hintsEnabledRef.current = hintsEnabled;
-  useEffect4(() => {
+  useEffect5(() => {
     let cancelled = false;
     fetch(`${apiBaseUrl}/v1/apps/${appId}/nudge-graph`, {
       headers: { Authorization: `Bearer ${apiKey}` }
@@ -598,14 +639,16 @@ function XbNovaNudgeLoop({ appId }) {
       cancelled = true;
     };
   }, [apiBaseUrl, apiKey, appId]);
-  const evaluate = useCallback3(
+  const evaluate = useCallback4(
     (firedEventName) => {
       const graph = graphRef.current;
       const debugEnabled = isDebugEnabled();
       const debugRefs = { panelRef: debugPanelRef, boxesRef: debugBoxesRef, bandLinesRef: debugBandLinesRef };
       if (!debugEnabled && debugPanelRef.current) clearDebugOverlay(debugRefs);
+      const tickDebug = debugEnabled ? (msg) => console.debug(msg) : () => {
+      };
       if (!graph) {
-        console.debug("[XbNova] nudge \uD3C9\uAC00 \uAC74\uB108\uB700: \uADF8\uB798\uD504\uB97C \uC544\uC9C1 \uBABB \uBD88\uB7EC\uC634");
+        tickDebug("[XbNova] nudge \uD3C9\uAC00 \uAC74\uB108\uB700: \uADF8\uB798\uD504\uB97C \uC544\uC9C1 \uBABB \uBD88\uB7EC\uC634");
         return;
       }
       const canOffer = !hintRef.current && hintsEnabledRef.current;
@@ -656,18 +699,7 @@ function XbNovaNudgeLoop({ appId }) {
           autoHideMs: messageNode.auto_hide_ms ?? 2e4,
           quickReplies: messageNode.quick_replies ?? []
         });
-        fetch(`${apiBaseUrl}/v1/nudge-events`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({
-            app_id: appId,
-            nudge_node_id: messageNode.id,
-            kind: "nudge_impression",
-            bot_id: botId,
-            visitor_id: visitorId
-          })
-        }).catch(() => {
-        });
+        sendEvent("nudge_impression", { nudge_node_id: messageNode.id, bot_id: botId });
       };
       const tryFireFrom = (node) => {
         const nextEdge = (edgesFrom.get(node.id) ?? [])[0];
@@ -695,7 +727,7 @@ function XbNovaNudgeLoop({ appId }) {
         const maxPerSession = node.max_per_session === 0 ? Infinity : node.max_per_session ?? 3;
         const sessionCount = peekSessionCount(node.id);
         if (sessionCount >= maxPerSession) {
-          console.debug(`[XbNova] \uD2B8\uB9AC\uAC70 ${node.id}(${node.trigger_type}) \uAC74\uB108\uB700: \uC138\uC158\uB2F9 \uC0C1\uD55C(${maxPerSession}) \uB3C4\uB2EC`);
+          tickDebug(`[XbNova] \uD2B8\uB9AC\uAC70 ${node.id}(${node.trigger_type}) \uAC74\uB108\uB700: \uC138\uC158\uB2F9 \uC0C1\uD55C(${maxPerSession}) \uB3C4\uB2EC`);
           if (debugEnabled && node.trigger_type === "dwell") {
             debugLines.push(`- [${node.id}] \uC138\uC158\uB2F9 \uC0C1\uD55C(${maxPerSession}) \uB3C4\uB2EC \u2014 \uB354 \uC548 \uC7BC`);
           }
@@ -730,7 +762,7 @@ function XbNovaNudgeLoop({ appId }) {
             overlapPx = status.overlapPx;
             statusDetail = `rect=[top=${status.rectTop.toFixed(0)}, bottom=${status.rectBottom.toFixed(0)}] band=[top=${status.bandTop.toFixed(0)}, bottom=${status.bandBottom.toFixed(0)}] overlapPx=${overlapPx.toFixed(0)} inBand=${inBand}`;
           }
-          console.debug(
+          tickDebug(
             `[XbNova] band dwell \uD2B8\uB9AC\uAC70=${node.id} region="${region}" band%=${fromPercent}~${toPercent} | ${statusDetail}`
           );
           dwellRecords.push({ node, state, requiredMs, region, found, screenMatches, inBand, overlapPx });
@@ -739,7 +771,7 @@ function XbNovaNudgeLoop({ appId }) {
         const fires = triggerFires(node, { screen, firedEventName });
         if (!fires) continue;
         if (!canOffer) {
-          console.debug(`[XbNova] \uD2B8\uB9AC\uAC70 ${node.id} \uC870\uAC74\uC740 \uCDA9\uC871\uD588\uC9C0\uB9CC \uC0C8 \uD78C\uD2B8 \uD45C\uC2DC\uB294 \uC7A0\uAE50 \uB9C9\uD798`);
+          tickDebug(`[XbNova] \uD2B8\uB9AC\uAC70 ${node.id} \uC870\uAC74\uC740 \uCDA9\uC871\uD588\uC9C0\uB9CC \uC0C8 \uD78C\uD2B8 \uD45C\uC2DC\uB294 \uC7A0\uAE50 \uB9C9\uD798`);
           continue;
         }
         if (tryFireFrom(node)) {
@@ -839,9 +871,9 @@ function XbNovaNudgeLoop({ appId }) {
         ensureDebugPanel(debugPanelRef, debugCollapsedRef).body.textContent = debugLines.join("\n");
       }
     },
-    [apiBaseUrl, appId, autoHideHint, factsRegistry, offerHint, screen, trackRegistry, visitorId]
+    [apiBaseUrl, appId, autoHideHint, factsRegistry, offerHint, screen, trackRegistry, sendEvent]
   );
-  useEffect4(() => {
+  useEffect5(() => {
     const interval = window.setInterval(() => evaluate(null), EVAL_INTERVAL_MS);
     const onEvent = (e) => evaluate(e.detail.eventName);
     window.addEventListener(XBNOVA_EVENT_NAME, onEvent);
@@ -870,24 +902,36 @@ function XbNovaProvider({
   apiBaseUrl = DEFAULT_API_BASE_URL,
   clientActions,
   theme,
+  userKey,
+  threadKey,
+  sessionKey,
   children
 }) {
-  useEffect5(() => {
+  useEffect6(() => {
     if (apiKey.startsWith("sk_")) {
       console.error(
         "[XbNova] sk_ \uD0A4\uB97C \uBE0C\uB77C\uC6B0\uC800\uC5D0 \uB178\uCD9C\uD588\uC2B5\uB2C8\uB2E4 \u2014 pk_(publishable) \uD0A4\uB97C \uC4F0\uC138\uC694. sk_\uB294 \uC11C\uBC84 \uC804\uC6A9\uC785\uB2C8\uB2E4."
       );
     }
   }, [apiKey]);
-  useEffect5(() => {
+  useEffect6(() => {
     markSessionStart();
   }, []);
-  useEffect5(() => {
+  useEffect6(() => {
     if (screen) bumpVisitCount(screen);
   }, [screen]);
   const auth = useMemo2(
-    () => ({ apiKey, botId, appId, apiBaseUrl, screen }),
-    [apiKey, botId, appId, apiBaseUrl, screen]
+    () => ({
+      apiKey,
+      botId,
+      appId,
+      apiBaseUrl,
+      screen,
+      userKey: userKey || void 0,
+      threadKey: threadKey || void 0,
+      sessionKey: sessionKey || void 0
+    }),
+    [apiKey, botId, appId, apiBaseUrl, screen, userKey, threadKey, sessionKey]
   );
   const resolvedTheme = useMemo2(
     () => ({ ...DEFAULT_THEME, ...theme }),
@@ -916,13 +960,13 @@ function XbNovaProvider({
 }
 
 // src/chat.tsx
-import { useEffect as useEffect8, useRef as useRef8, useState as useState4 } from "react";
+import { useEffect as useEffect9, useRef as useRef8, useState as useState4 } from "react";
 import ReactMarkdown from "react-markdown";
 import remarkBreaks from "remark-breaks";
 import remarkGfm from "remark-gfm";
 
 // src/shadow-root.tsx
-import { useEffect as useEffect6, useRef as useRef6, useState as useState2 } from "react";
+import { useEffect as useEffect7, useRef as useRef6, useState as useState2 } from "react";
 import { createPortal } from "react-dom";
 import { jsx as jsx5 } from "react/jsx-runtime";
 var cssPromise = null;
@@ -938,7 +982,7 @@ function loadCss() {
 }
 function useResolvedScheme(scheme) {
   const [systemDark, setSystemDark] = useState2(false);
-  useEffect6(() => {
+  useEffect7(() => {
     if (scheme !== "system") return;
     const mq = window.matchMedia("(prefers-color-scheme: dark)");
     setSystemDark(mq.matches);
@@ -958,10 +1002,10 @@ function XbNovaShadowRoot({
   const hostRef = useRef6(null);
   const [mountNode, setMountNode] = useState2(null);
   const [portalTarget, setPortalTarget] = useState2(null);
-  useEffect6(() => {
+  useEffect7(() => {
     setPortalTarget(document.body);
   }, []);
-  useEffect6(() => {
+  useEffect7(() => {
     const host = hostRef.current;
     if (!host || host.shadowRoot) return;
     const shadow = host.attachShadow({ mode: "open" });
@@ -976,7 +1020,7 @@ function XbNovaShadowRoot({
     shadow.appendChild(mount);
     setMountNode(mount);
   }, [portalTarget]);
-  useEffect6(() => {
+  useEffect7(() => {
     if (!mountNode) return;
     mountNode.dataset.xbnovaScheme = scheme;
     mountNode.style.colorScheme = scheme;
@@ -989,15 +1033,44 @@ function XbNovaShadowRoot({
 }
 
 // src/use-chat.ts
-import { useEffect as useEffect7, useRef as useRef7, useState as useState3 } from "react";
+import { useEffect as useEffect8, useRef as useRef7, useState as useState3 } from "react";
 
 // src/stream.ts
+function fromStoredMessages(stored) {
+  return stored.map((m) => ({
+    id: m.role === "assistant" ? m.id : void 0,
+    role: m.role === "assistant" ? "assistant" : "user",
+    parts: m.parts.flatMap((p, i) => {
+      const type = String(p.type ?? "");
+      if (type === "text") {
+        const text = typeof p.text === "string" ? p.text : "";
+        return text ? [{ kind: "text", id: `${m.id}:${i}`, text }] : [];
+      }
+      if (type.startsWith("tool-")) {
+        const meta = p.providerMetadata;
+        return [
+          {
+            kind: "tool",
+            toolCallId: String(p.toolCallId ?? `${m.id}:${i}`),
+            toolName: type.slice("tool-".length),
+            state: p.state === "output-error" ? "error" : "output",
+            input: p.input,
+            output: p.output,
+            view: meta?.["kr.dsauto.chat"]?.view ?? null
+          }
+        ];
+      }
+      return [];
+    })
+  }));
+}
 async function consumeSse(response, handlers) {
   if (!response.ok || !response.body) {
     handlers.onError?.(`\uC694\uCCAD \uC2E4\uD328 (${response.status})`);
     return null;
   }
   const conversationId = response.headers.get("x-conversation-id");
+  if (conversationId) handlers.onConversationId?.(conversationId);
   const reader = response.body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
@@ -1102,12 +1175,19 @@ async function resumeToolResult(apiBaseUrl, apiKey, body, handlers) {
 // src/use-chat.ts
 var DEFAULT_CLIENT_ACTION_TIMEOUT_MS = 15e3;
 function useXbNovaChat(options) {
-  const { auth, trackRegistry, contextRegistry, clientActionHandlers, visitorId } = useXbNovaInternal();
+  const { auth, trackRegistry, contextRegistry, clientActionHandlers, visitorId, sessionId, sendEvent } = useXbNovaInternal();
   const botId = options?.botId ?? auth.botId;
   const nudgeNodeId = options?.nudgeNodeId;
-  const { apiKey, apiBaseUrl } = auth;
+  const { apiKey, apiBaseUrl, threadKey } = auth;
+  const userKey = visitorId;
   const [onboarding, setOnboarding] = useState3(null);
   const [messages, setMessages] = useState3([]);
+  const [resumed, setResumed] = useState3(false);
+  const [sentOpening, setSentOpening] = useState3(null);
+  const conversationIdRef = useRef7(null);
+  const pendingOpeningRef = useRef7(null);
+  const messagesRef = useRef7(messages);
+  messagesRef.current = messages;
   const [busy, setBusy] = useState3(false);
   const [error, setError] = useState3(null);
   const [clientResults, setClientResults] = useState3({});
@@ -1117,19 +1197,60 @@ function useXbNovaChat(options) {
   const dispatchedClientActionsRef = useRef7(/* @__PURE__ */ new Set());
   const nudgeNodeIdRef = useRef7(nudgeNodeId);
   nudgeNodeIdRef.current = nudgeNodeId;
-  useEffect7(() => {
+  useEffect8(() => {
+    let cancelled = false;
     setOnboarding(null);
     setMessages([]);
+    setResumed(false);
+    setSentOpening(null);
     setError(null);
     setClientResults({});
     setFeedbackState({});
     dispatchedClientActionsRef.current = /* @__PURE__ */ new Set();
+    conversationIdRef.current = null;
+    pendingOpeningRef.current = null;
     fetch(`${apiBaseUrl}/v1/conversations`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
-      body: JSON.stringify({ bot_id: botId, nudge_node_id: nudgeNodeIdRef.current ?? null })
-    }).then((r) => r.ok ? r.json() : Promise.reject(new Error(`${r.status}`))).then(setOnboarding).catch((e) => setError(`\uBD07\uC744 \uBD88\uB7EC\uC62C \uC218 \uC5C6\uC2B5\uB2C8\uB2E4: ${e.message}`));
-  }, [apiBaseUrl, apiKey, botId]);
+      body: JSON.stringify({
+        bot_id: botId,
+        nudge_node_id: nudgeNodeIdRef.current ?? null,
+        visitor_id: userKey || null,
+        thread_key: threadKey ?? null,
+        session_id: sessionId,
+        defer: true
+      })
+    }).then((r) => r.ok ? r.json() : Promise.reject(new Error(`${r.status}`))).then((data) => {
+      if (cancelled) return;
+      if (conversationIdRef.current || messagesRef.current.length > 0) {
+        setOnboarding(data);
+        return;
+      }
+      conversationIdRef.current = data.conversation_id;
+      const restored = fromStoredMessages(data.messages ?? []);
+      for (const m of restored) {
+        for (const p of m.parts) if (p.kind === "tool") dispatchedClientActionsRef.current.add(p.toolCallId);
+      }
+      setMessages(restored);
+      setResumed(restored.length > 0);
+      setOnboarding(data);
+    }).catch((e) => {
+      if (!cancelled) setError(`\uBD07\uC744 \uBD88\uB7EC\uC62C \uC218 \uC5C6\uC2B5\uB2C8\uB2E4: ${e.message}`);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [apiBaseUrl, apiKey, botId, userKey, threadKey]);
+  const openingMessage = options?.openingMessage;
+  useEffect8(() => {
+    if (!onboarding || !nudgeNodeId || !openingMessage) return;
+    if (messagesRef.current.length === 0) return;
+    setMessages((prev) => [
+      ...prev,
+      { role: "assistant", parts: [{ kind: "text", id: `nudge:${nudgeNodeId}:${prev.length}`, text: openingMessage }] }
+    ]);
+    pendingOpeningRef.current = openingMessage;
+  }, [onboarding, nudgeNodeId, openingMessage]);
   const appendToLastAssistant = (existingParts, newParts) => setMessages((prev) => {
     const next = [...prev];
     next[next.length - 1] = { ...next[next.length - 1], role: "assistant", parts: [...existingParts, ...newParts] };
@@ -1142,7 +1263,7 @@ function useXbNovaChat(options) {
     return next;
   });
   async function setFeedback(messageId, rating, reason) {
-    const conversationId = onboarding?.conversation_id;
+    const conversationId = conversationIdRef.current;
     if (!conversationId || !messageId) return;
     const prevRating = feedbackRef.current[messageId] ?? null;
     const apply = (r) => setFeedbackState((prev) => {
@@ -1162,12 +1283,21 @@ function useXbNovaChat(options) {
         }
       );
       if (!res.ok) throw new Error(`${res.status}`);
+      sendEvent("feedback_submit", { conversation_id: conversationId, message_id: messageId, rating, reason });
       options?.onFeedback?.({ conversationId, messageId, rating, reason });
     } catch (e) {
       console.warn("[xbnova] \uD53C\uB4DC\uBC31 \uC800\uC7A5 \uC2E4\uD328", e);
       apply(prevRating);
     }
   }
+  function postClientActionEvent(kind, action, label) {
+    const conversationId = conversationIdRef.current;
+    if (!conversationId) return;
+    sendEvent(kind, { conversation_id: conversationId, action, label });
+  }
+  function trackClientActionClick(action, label) {
+    postClientActionEvent("cta_click", action, label);
+  }
   async function runClientAction(spec, part, existingParts) {
     if (spec.dismissSheet) options?.onDismissSheet?.();
     let result;
@@ -1191,7 +1321,7 @@ function useXbNovaChat(options) {
       result = e instanceof Error ? `\uC624\uB958: ${e.message}` : "\uC624\uB958\uAC00 \uBC1C\uC0DD\uD588\uC2B5\uB2C8\uB2E4.";
     }
     if (!spec.awaitResult) return;
-    const conversationId = onboarding?.conversation_id;
+    const conversationId = conversationIdRef.current;
     if (!conversationId) return;
     const structured = result && typeof result === "object" ? result : null;
     if (structured?.view) {
@@ -1225,7 +1355,7 @@ function useXbNovaChat(options) {
       setBusy(false);
     }
   }
-  useEffect7(() => {
+  useEffect8(() => {
     if (clientActionHandlers.size === 0) return;
     const last = messages[messages.length - 1];
     if (!last || last.role !== "assistant") return;
@@ -1235,12 +1365,18 @@ function useXbNovaChat(options) {
       if (!spec) continue;
       if (dispatchedClientActionsRef.current.has(part.toolCallId)) continue;
       dispatchedClientActionsRef.current.add(part.toolCallId);
+      if (spec.render) postClientActionEvent("cta_impression", part.toolName, null);
       void runClientAction(spec, part, last.parts);
     }
   }, [messages, clientActionHandlers, onboarding, apiBaseUrl, apiKey, botId]);
   async function send(text) {
     const trimmed = text.trim();
     if (!trimmed || busy) return;
+    sendEvent("message_send", {
+      conversation_id: conversationIdRef.current,
+      is_first: messages.length === 0,
+      length: trimmed.length
+    });
     setError(null);
     setBusy(true);
     setMessages((prev) => [
@@ -1257,6 +1393,14 @@ function useXbNovaChat(options) {
     const notes = collectContextEntries(contextRegistry);
     const screen = focused ? { region: focused.region, data: resolveFactValue(focused.data) } : {};
     const context = focused || notes.length ? { ...screen, ...notes.length ? { notes } : {} } : void 0;
+    let openingMessage2;
+    if (messages.length === 0) {
+      openingMessage2 = (options?.openingMessage ?? onboarding?.greeting) || null;
+      setSentOpening(openingMessage2);
+    } else {
+      openingMessage2 = pendingOpeningRef.current;
+    }
+    pendingOpeningRef.current = null;
     try {
       await streamChat(
         apiBaseUrl,
@@ -1264,12 +1408,22 @@ function useXbNovaChat(options) {
         {
           bot_id: botId,
           message: trimmed,
-          conversation_id: onboarding?.conversation_id ?? null,
+          conversation_id: conversationIdRef.current,
           context,
           nudge_node_id: nudgeNodeId ?? null,
-          opening_message: messages.length === 0 ? (options?.openingMessage ?? onboarding?.greeting) || null : null
+          opening_message: openingMessage2,
+          visitor_id: userKey || null,
+          thread_key: threadKey ?? null,
+          session_id: sessionId
         },
-        { onPart: replaceLast, onMessageId: setLastAssistantId, onError: setError }
+        {
+          onPart: replaceLast,
+          onMessageId: setLastAssistantId,
+          onConversationId: (id) => {
+            conversationIdRef.current = id;
+          },
+          onError: setError
+        }
       );
     } catch (e) {
       setError(e instanceof Error ? e.message : String(e));
@@ -1277,7 +1431,19 @@ function useXbNovaChat(options) {
       setBusy(false);
     }
   }
-  return { onboarding, messages, busy, error, send, clientResults, feedback, setFeedback };
+  const opening = resumed ? null : sentOpening ?? options?.openingMessage ?? onboarding?.greeting ?? null;
+  return {
+    onboarding,
+    opening,
+    messages,
+    busy,
+    error,
+    send,
+    clientResults,
+    feedback,
+    setFeedback,
+    trackClientActionClick
+  };
 }
 
 // src/views.tsx
@@ -1410,6 +1576,13 @@ function hasVisiblePart(parts, clientActionHandlers, clientResults) {
 }
 var DISCLOSURE_SEEN_KEY = "xbnova_disclosure_seen";
 var SUMMARY_FACT_KEY = "xbnova_summary";
+function clickedControl(e) {
+  const target = e.target instanceof Element ? e.target : null;
+  const control = target?.closest("button, a, [role='button']");
+  if (!control || !e.currentTarget.contains(control)) return null;
+  const text = (control.textContent ?? "").replace(/\s+/g, " ").trim();
+  return { label: text || control.getAttribute("aria-label") || null };
+}
 function readDisclosureSeen() {
   if (typeof window === "undefined") return true;
   try {
@@ -1428,7 +1601,7 @@ function markDisclosureSeen() {
 var DESKTOP_MEDIA_QUERY = "(min-width: 640px)";
 function useIsDesktopViewport() {
   const [isDesktop, setIsDesktop] = useState4(false);
-  useEffect8(() => {
+  useEffect9(() => {
     if (typeof window === "undefined") return;
     const mql = window.matchMedia(DESKTOP_MEDIA_QUERY);
     setIsDesktop(mql.matches);
@@ -1452,7 +1625,7 @@ function backdropBaseStyle(isDesktop) {
 }
 function useTypewriter(text, key, speedMs = 28) {
   const [shown, setShown] = useState4("");
-  useEffect8(() => {
+  useEffect9(() => {
     setShown("");
     if (!text) return;
     let i = 0;
@@ -1539,9 +1712,10 @@ function XbNovaChat({
   avatarSize = 28,
   onVerdictAction,
   feedback: feedbackEnabled = true,
-  onFeedback
+  onFeedback,
+  onOpen
 }) {
-  const { auth, trackRegistry, factsRegistry, visitorId, clientActionHandlers, theme } = useXbNovaInternal();
+  const { auth, trackRegistry, factsRegistry, clientActionHandlers, theme, sendEvent } = useXbNovaInternal();
   const themeVars = {
     "--xbnova-accent-1": theme.accentFrom,
     "--xbnova-accent-2": theme.accentTo
@@ -1562,7 +1736,7 @@ function XbNovaChat({
   const [input, setInput] = useState4("");
   const bottomRef = useRef8(null);
   const typedHintText = useTypewriter(hint?.text ?? "", hint?.triggerNodeId ?? "");
-  const { onboarding, messages, busy, error, send, clientResults, feedback, setFeedback } = useXbNovaChat({
+  const { onboarding, opening, messages, busy, error, send, clientResults, feedback, setFeedback, trackClientActionClick } = useXbNovaChat({
     onFeedback,
     botId: activeBotId ?? botId,
     nudgeNodeId: activeNudgeNodeId,
@@ -1571,7 +1745,7 @@ function XbNovaChat({
   });
   const effectiveBotId = activeBotId ?? botId;
   const [cachedBranding, setCachedBranding] = useState4(null);
-  useEffect8(() => {
+  useEffect9(() => {
     try {
       const raw = window.localStorage.getItem(`xbnova_branding:${effectiveBotId}`);
       setCachedBranding(raw ? JSON.parse(raw) : null);
@@ -1579,22 +1753,29 @@ function XbNovaChat({
       setCachedBranding(null);
     }
   }, [effectiveBotId]);
-  useEffect8(() => {
+  useEffect9(() => {
     if (!onboarding?.branding) return;
     try {
       window.localStorage.setItem(
         `xbnova_branding:${effectiveBotId}`,
-        JSON.stringify({ logo_url: onboarding.branding.logo_url, avatar_text: onboarding.branding.avatar_text })
+        JSON.stringify({
+          logo_url: onboarding.branding.logo_url,
+          avatar_text: onboarding.branding.avatar_text,
+          badge_text: onboarding.branding.badge_text,
+          disclaimer: onboarding.branding.disclaimer
+        })
       );
     } catch {
     }
   }, [onboarding?.branding, effectiveBotId]);
   const branding = onboarding?.branding ?? cachedBranding ?? void 0;
+  const badgeText = branding?.badge_text?.trim() ?? "";
+  const disclaimer = branding?.disclaimer?.trim() ?? "";
   const brandingReady = Boolean(onboarding) || cachedBranding !== null || Boolean(error);
-  useEffect8(() => {
+  useEffect9(() => {
     bottomRef.current?.scrollIntoView({ behavior: "smooth" });
   }, [messages]);
-  useEffect8(() => {
+  useEffect9(() => {
     if (!open) {
       setEntered(false);
       return;
@@ -1602,7 +1783,7 @@ function XbNovaChat({
     const raf = requestAnimationFrame(() => setEntered(true));
     return () => cancelAnimationFrame(raf);
   }, [open]);
-  useEffect8(() => {
+  useEffect9(() => {
     if (!hint || hint.autoHideMs <= 0) return;
     console.debug(`[XbNova] \uD78C\uD2B8 "${hint.text}" \uD45C\uC2DC \u2014 ${hint.autoHideMs}ms \uD6C4 \uC790\uB3D9\uC73C\uB85C \uC0AC\uB77C\uC9D0`);
     const timer = window.setTimeout(() => {
@@ -1619,18 +1800,7 @@ function XbNovaChat({
       setOpeningLine(consumed.text);
       setActiveNudgeNodeId(consumed.messageNodeId);
       setNudgeQuickReplies(consumed.quickReplies);
-      fetch(`${auth.apiBaseUrl}/v1/nudge-events`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          app_id: auth.appId,
-          nudge_node_id: consumed.messageNodeId,
-          kind: "nudge_open",
-          bot_id: consumed.botId,
-          visitor_id: visitorId
-        })
-      }).catch(() => {
-      });
+      sendEvent("nudge_open", { nudge_node_id: consumed.messageNodeId, bot_id: consumed.botId });
     } else {
       setNudgeQuickReplies([]);
       setActiveNudgeNodeId(void 0);
@@ -1644,6 +1814,16 @@ function XbNovaChat({
       markDisclosureSeen();
     }
     setOpen(true);
+    sendEvent("chat_open", { from_nudge: Boolean(consumed) });
+    try {
+      onOpen?.({ fromNudge: Boolean(consumed), hintText: consumed?.text });
+    } catch (err) {
+      console.warn("[XbNova] onOpen \uCF5C\uBC31 \uC624\uB958", err);
+    }
+  }
+  function closeSheet() {
+    setOpen(false);
+    sendEvent("chat_close");
   }
   if (!open) {
     if (barHidden) return null;
@@ -1739,7 +1919,6 @@ function XbNovaChat({
   const summary = resolveFactValue(factsRegistry.get(SUMMARY_FACT_KEY));
   const focusedLabel = getFocusedTrackEntry(trackRegistry)?.label;
   const contextLine = summary ?? (focusedLabel ? `${focusedLabel} \uBCF4\uB294 \uC911` : void 0);
-  const firstBubble = openingLine ?? onboarding?.greeting;
   return /* @__PURE__ */ jsxs3(Fragment, { children: [
     !isDesktop ? /* @__PURE__ */ jsx7(
       XbNovaShadowRoot,
@@ -1750,7 +1929,7 @@ function XbNovaChat({
           transition: "opacity 260ms ease-out",
           ...backdropStyle
         },
-        children: /* @__PURE__ */ jsx7("div", { className: "h-full w-full bg-black/45", onClick: () => setOpen(false) })
+        children: /* @__PURE__ */ jsx7("div", { className: "h-full w-full bg-black/45", onClick: closeSheet })
       }
     ) : null,
     /* @__PURE__ */ jsx7(
@@ -1776,14 +1955,17 @@ function XbNovaChat({
               }
             ),
             /* @__PURE__ */ jsxs3("div", { className: "min-w-0 flex-1", children: [
-              /* @__PURE__ */ jsx7("div", { className: "text-sm font-semibold", children: onboarding?.branding?.title ?? "AI \uB3D9\uD589" }),
+              /* @__PURE__ */ jsxs3("div", { className: "flex min-w-0 items-center gap-1.5", children: [
+                /* @__PURE__ */ jsx7("span", { className: "truncate text-sm font-semibold", children: onboarding?.branding?.title ?? "AI \uB3D9\uD589" }),
+                badgeText ? /* @__PURE__ */ jsx7("span", { className: "shrink-0 rounded-full border border-neutral-300 px-1.5 py-px text-[10px] font-semibold leading-4 text-neutral-500 dark:border-neutral-600 dark:text-neutral-400", children: badgeText }) : null
+              ] }),
               contextLine ? /* @__PURE__ */ jsx7("div", { className: "truncate text-[11px] text-neutral-400", children: contextLine }) : null
             ] }),
             /* @__PURE__ */ jsx7(
               "button",
               {
                 type: "button",
-                onClick: () => setOpen(false),
+                onClick: closeSheet,
                 "aria-label": "\uCC44\uD305 \uB2EB\uAE30",
                 className: "shrink-0 text-neutral-400 hover:text-neutral-700 dark:hover:text-neutral-200",
                 children: "\xD7"
@@ -1792,7 +1974,7 @@ function XbNovaChat({
           ] }),
           /* @__PURE__ */ jsxs3("div", { className: "flex-1 space-y-3 overflow-y-auto p-4", children: [
             showDisclosure ? /* @__PURE__ */ jsx7("div", { className: "rounded-lg bg-neutral-50 px-3 py-2 text-[11px] text-neutral-400 dark:bg-neutral-800", children: "\uC9C0\uAE08 \uBCF4\uACE0 \uACC4\uC2E0 \uD654\uBA74\uACFC \uB9E4\uBB3C \uC815\uBCF4\uB97C \uAE30\uC900\uC73C\uB85C \uC548\uB0B4\uD574 \uB4DC\uB824\uC694." }) : null,
-            firstBubble ? /* @__PURE__ */ jsx7(Bubble, { role: "assistant", children: /* @__PURE__ */ jsx7(AssistantMarkdown, { text: firstBubble }) }) : null,
+            opening ? /* @__PURE__ */ jsx7(Bubble, { role: "assistant", children: /* @__PURE__ */ jsx7(AssistantMarkdown, { text: opening }) }) : null,
             messages.map((message, i) => /* @__PURE__ */ jsx7("div", { children: message.role === "user" ? /* @__PURE__ */ jsx7(Bubble, { role: "user", children: message.parts.map((p) => p.kind === "text" ? p.text : "").join("") }) : /* @__PURE__ */ jsxs3(
               AnswerActionsFrame,
               {
@@ -1820,7 +2002,17 @@ function XbNovaChat({
                         );
                       }
                       const spec = clientActionHandlers.get(part.toolName);
-                      return spec?.render ? /* @__PURE__ */ jsx7("div", { children: spec.render(part.input) }, j) : null;
+                      return spec?.render ? /* @__PURE__ */ jsx7(
+                        "div",
+                        {
+                          onClickCapture: (e) => {
+                            const control = clickedControl(e);
+                            if (control) trackClientActionClick(part.toolName, control.label);
+                          },
+                          children: spec.render(part.input)
+                        },
+                        j
+                      ) : null;
                     }
                     return /* @__PURE__ */ jsx7(ToolView, { part, viewRenderers, onVerdictAction }, j);
                   }),
@@ -1891,7 +2083,8 @@ function XbNovaChat({
                 )
               ]
             }
-          )
+          ),
+          disclaimer ? /* @__PURE__ */ jsx7("p", { className: "-mt-1 px-4 pb-2.5 text-center text-[11px] leading-snug text-neutral-400 dark:text-neutral-500", children: disclaimer }) : null
         ] })
       }
     )
@@ -1993,8 +2186,8 @@ function AnswerActions({
     if (timerRef.current) clearTimeout(timerRef.current);
     timerRef.current = null;
   };
-  useEffect8(() => clearTimer, []);
-  useEffect8(() => {
+  useEffect9(() => clearTimer, []);
+  useEffect9(() => {
     if (!menuOpen) {
       setEntered(false);
       return;
@@ -2141,13 +2334,13 @@ function AnswerActionsFrame({
 }
 
 // src/facts.ts
-import { useEffect as useEffect9, useId, useRef as useRef9 } from "react";
+import { useEffect as useEffect10, useId, useRef as useRef9 } from "react";
 function useXbNovaFact(key, value) {
   const { factsRegistry } = useXbNovaInternal();
-  useEffect9(() => {
+  useEffect10(() => {
     factsRegistry.set(key, value);
   });
-  useEffect9(() => {
+  useEffect10(() => {
     return () => {
       factsRegistry.delete(key);
     };
@@ -2156,13 +2349,13 @@ function useXbNovaFact(key, value) {
 function useXbNovaFacts(values) {
   const { factsRegistry } = useXbNovaInternal();
   const keysRef = useRef9([]);
-  useEffect9(() => {
+  useEffect10(() => {
     for (const [key, value] of Object.entries(values)) {
       factsRegistry.set(key, value);
     }
     keysRef.current = Object.keys(values);
   });
-  useEffect9(() => {
+  useEffect10(() => {
     return () => {
       for (const key of keysRef.current) {
         factsRegistry.delete(key);
@@ -2173,10 +2366,10 @@ function useXbNovaFacts(values) {
 function useXbNovaContext(entries) {
   const { contextRegistry } = useXbNovaInternal();
   const id = useId();
-  useEffect9(() => {
+  useEffect10(() => {
     contextRegistry.set(id, entries);
   });
-  useEffect9(() => {
+  useEffect10(() => {
     return () => {
       contextRegistry.delete(id);
     };