sagedesk 2.1.1 → 2.3.0

package/README.md

@@ -23,7 +23,9 @@ All embedding and semantic search runs entirely in the visitor's browser via Web
 
 ### LLM Mode
 
-The widget posts visitor queries to your own backend. Your backend handles embedding, retrieval, and LLM synthesis. The API key lives in your environment variables and never touches the browser. sagedesk provides ready-made server handlers for Next.js and Express - you own your entire stack.
+The widget embeds the visitor's query in the browser (same WASM model as local mode), then posts `{ query, queryVector }` to your own backend. Your backend does retrieval against the prebuilt index and calls your LLM provider for synthesis. The API key lives in your environment variables and never touches the browser. sagedesk provides ready-made server handlers for Next.js and Express - you own your entire stack.
+
+Because the embedder stays in the browser, the server function carries no native ONNX runtime and no model weights. It deploys cleanly on Vercel, AWS Lambda, and any other serverless platform with no special configuration - the built `sagedesk/server` bundle is under 10 KB.
 
 | | Local Mode | LLM Mode |
 |---|---|---|
@@ -38,6 +40,15 @@ The widget posts visitor queries to your own backend. Your backend handles embed
 
 ---
 
+## Framework Support
+
+| | Supported |
+|---|---|
+| **Frontend** | Vanilla HTML/JS, React, Next.js (App Router) |
+| **Backend** (LLM Mode) | Next.js API Routes, Express, any Node.js server, Vercel, AWS Lambda |
+
+---
+
 ## Installation
 
 ```bash
@@ -220,7 +231,7 @@ app.use('/api/sagedesk', createSageDeskMiddleware({
 }));
 ```
 
-> **Serverless & Vercel compatible.** The server handler uses a pure WebAssembly embedding backend with no native binary dependencies. It works out of the box on Vercel, AWS Lambda, and any other serverless platform — no additional configuration required.
+> **Serverless ready.** The handler does no embedding - it only reads the prebuilt index, runs an in-memory dot-product search, and proxies one HTTP call to your LLM provider. There is no `@huggingface/transformers` import, no `onnxruntime-node`, and no native binaries on the server, so no `next.config.js` workarounds, no `outputFileTracingIncludes`, and no Vercel function-size hacks are needed. Just import and mount the handler.
 
 ### Step 3 - Configure the widget
 
@@ -307,7 +318,6 @@ createSageDeskHandler({
 | `provider` | `string` | yes | Provider name (e.g., `'openai'`, `'anthropic'`) or full API base URL (e.g., `'https://api.example.com/v1'`). |
 | `apiKey` | `string` | yes | LLM API key (server-side only). |
 | `model` | `string` | yes | Model name passed to the provider. |
-| `embeddingModel` | `string` | no | Must match build-time model. Defaults to `all-MiniLM-L6-v2`. |
 | `topK` | `number` | no | Number of chunks retrieved for context. Defaults to `5`. |
 | `minScore` | `number` | no | Minimum similarity score for a chunk. Defaults to `0.42`. |
 | `systemPrompt` | `string` | no | Override the default system prompt sent to the LLM. |
@@ -325,41 +335,10 @@ sagedesk includes built-in resilience for LLM mode. If the LLM provider fails-wh
 
 2. **Automatic Fallback** - When an LLM request fails, the server returns the best matching knowledge chunks without synthesis. Visitors still get relevant, grounded information.
 
-3. **Developer Transparency** - The browser console logs meaningful warnings for debugging:
-   - `"[sagedesk] Support service authentication failed. Showing relevant knowledge instead."` - Invalid or expired API key
-   - `"[sagedesk] Support service quota exhausted. Showing relevant knowledge instead."` - Rate limit hit
-   - `"[sagedesk] Support service took too long to respond. Showing relevant knowledge instead."` - Timeout
-   - `"[sagedesk] Support service error. Showing relevant knowledge instead."` - Generic API error
-   - `"[sagedesk] Support service returned invalid response. Showing relevant knowledge instead."` - Malformed response
+3. **Developer Transparency** - The browser console logs a `[sagedesk]` warning for each failure class: auth error, quota exhausted, timeout, generic API error, and malformed response. Each message describes the cause and notes that the fallback was triggered.
 
 4. **User Experience** - Visitors always see a fallback message (configured via `agent.fallback` or `agent.fallbackPool`) alongside relevant knowledge chunks. No errors are exposed to users.
 
-### Configuring Timeout
-
-Adjust the LLM request timeout based on your provider's typical response time:
-
-```ts
-// Next.js
-export const POST = createSageDeskHandler({
-  indexPath: './public/support-index.json',
-  provider: 'deepseek',
-  apiKey: process.env.SAGEDESK_LLM_API_KEY!,
-  model: 'deepseek-chat',
-  llmTimeoutMs: 8000,  // 8 seconds
-});
-```
-
-```ts
-// Express
-app.use('/api/sagedesk', createSageDeskMiddleware({
-  indexPath: './public/support-index.json',
-  provider: 'openai',
-  apiKey: process.env.SAGEDESK_LLM_API_KEY!,
-  model: 'gpt-4o-mini',
-  llmTimeoutMs: 10000,  // 10 seconds
-}));
-```
-
 ---
 
 ## Widget Configuration (`AgentConfig`)
@@ -370,7 +349,7 @@ Applies to both modes.
 |---|:---:|:---:|---|
 | `name` | `string` | **Required** | Display name in the chat header. |
 | `theme` | `classic`, `light`, `dark` | `classic` | Visual style of the widget. |
-| `model` | `string` | `all-MiniLM-L6-v2` | Embedding model. Must match build-time model. Local mode only. |
+| `model` | `string` | `all-MiniLM-L6-v2` | Embedding model loaded by the browser. Must match the build-time model. Used by both modes - local mode embeds & searches in-browser; LLM mode embeds in-browser and posts the vector to your handler. |
 | `accentColor` | `string` | `#534AB7` | Hex color for primary UI elements. |
 | `greeting` | `string` | - | Initial message shown to visitors. |
 | `fallback` | `string` | - | Message shown when no answer is found. |
@@ -423,13 +402,13 @@ sagedesk defaults to `all-MiniLM-L6-v2` (~22MB), which offers an excellent balan
 | `paraphrase-multilingual-MiniLM-L12-v2` | 384 | ~45 MB | 50+ languages. |
 | `all-mpnet-base-v2` | 768 | ~85 MB | Maximum semantic quality. |
 
-> **Note:** The `--model` flag in `npx sagedesk build` must match the `agent.model` prop (local mode) or the `embeddingModel` option in your server handler (LLM mode).
+> **Note:** The `--model` flag in `npx sagedesk build` must match the `agent.model` prop on the widget. Both local mode and LLM mode embed in the browser using `agent.model`, and the resulting vectors must live in the same space as the index built by the CLI.
 
 ---
 
 ## Browser Support
 
-Requires **WebAssembly** support (local mode only - LLM mode has no browser requirements beyond `fetch`).
+Requires **WebAssembly** support. Both local and LLM mode embed visitor queries in-browser, so the same WASM-capable browsers are required for both. WASM is supported by all modern browsers (Chrome 57+, Firefox 52+, Safari 11+, Edge 16+).
 
 - Chrome 90+
 - Firefox 89+

package/dist/next/{SageDeskWidget-SJVE6QK3.js → SageDeskWidget-ZJJGXTTC.js}

@@ -1,11 +1,12 @@
 'use client';
 
 // src/react/SageDeskWidget.tsx
-import {
+import React, {
   useState as useState2,
   useRef as useRef2,
   useEffect as useEffect2,
-  useCallback as useCallback2
+  useCallback as useCallback2,
+  useMemo as useMemo2
 } from "react";
 import { createPortal } from "react-dom";
 
@@ -265,6 +266,7 @@ function logFallbackWarning(reason) {
 }
 var initialState = {
   messages: [],
+  userMessages: [],
   isOpen: false,
   isTyping: false,
   engineStatus: "idle",
@@ -277,8 +279,11 @@ function reducer(state, action) {
       return { ...state, isOpen: true };
     case "CLOSE":
       return { ...state, isOpen: false };
-    case "ADD_MESSAGE":
-      return { ...state, messages: [...state.messages, action.payload] };
+    case "ADD_MESSAGE": {
+      const newMessages = [...state.messages, action.payload];
+      const newUserMessages = action.payload.role === "user" ? [...state.userMessages, action.payload] : state.userMessages;
+      return { ...state, messages: newMessages, userMessages: newUserMessages };
+    }
     case "SET_TYPING":
       return { ...state, isTyping: action.payload };
     case "SET_ENGINE_STATUS":
@@ -301,6 +306,7 @@ function useSageDesk(config) {
   const embedderRef = useRef(null);
   const engineStartedRef = useRef(false);
   const msgCounterRef = useRef(0);
+  const engineReadyCallbacksRef = useRef([]);
   const [chips, setChips] = useState([]);
   const makeId = () => `msg-${++msgCounterRef.current}`;
   const addMessage = useCallback(
@@ -312,12 +318,27 @@ function useSageDesk(config) {
     },
     []
   );
+  const notifyEngineReady = useCallback(() => {
+    const callbacks = engineReadyCallbacksRef.current;
+    engineReadyCallbacksRef.current = [];
+    callbacks.forEach((cb) => cb());
+  }, []);
   const startEngine = useCallback(async () => {
     if (engineStartedRef.current) return;
     engineStartedRef.current = true;
     if (config.mode === "llm") {
       setChips(config.agent.suggestedChips ?? []);
-      dispatch({ type: "SET_ENGINE_STATUS", payload: { status: "ready" } });
+      dispatch({ type: "SET_ENGINE_STATUS", payload: { status: "loading-model" } });
+      try {
+        embedderRef.current = new EmbedderRuntime();
+        await embedderRef.current.load(config.agent.model);
+        dispatch({ type: "SET_ENGINE_STATUS", payload: { status: "ready" } });
+        notifyEngineReady();
+      } catch (err) {
+        console.warn("[sagedesk] WASM embedder failed to load - LLM mode will use fallback messages.", err);
+        dispatch({ type: "SET_ENGINE_STATUS", payload: { status: "error-model", error: String(err) } });
+        notifyEngineReady();
+      }
       return;
     }
     dispatch({ type: "SET_ENGINE_STATUS", payload: { status: "loading-index" } });
@@ -329,6 +350,7 @@ function useSageDesk(config) {
         type: "SET_ENGINE_STATUS",
         payload: { status: "error-index", error: String(err) }
       });
+      notifyEngineReady();
       addMessage({
         role: "bot",
         text: "I'm having trouble loading right now. Please try again in a moment."
@@ -341,12 +363,14 @@ function useSageDesk(config) {
       embedderRef.current = new EmbedderRuntime();
       await embedderRef.current.load(config.agent.model);
       dispatch({ type: "SET_ENGINE_STATUS", payload: { status: "ready" } });
+      notifyEngineReady();
     } catch (err) {
       console.warn("[sagedesk] WASM model failed to load, falling back to keyword search -", err);
       embedderRef.current = new EmbedderRuntime();
       dispatch({ type: "SET_ENGINE_STATUS", payload: { status: "degraded" } });
+      notifyEngineReady();
     }
-  }, [config.mode, config.indexUrl, config.agent.suggestedChips, addMessage]);
+  }, [config.mode, config.indexUrl, config.agent.model, config.agent.suggestedChips, addMessage, notifyEngineReady]);
   const greetingShownRef = useRef(false);
   const open = useCallback(() => {
     dispatch({ type: "OPEN" });
@@ -363,16 +387,12 @@ function useSageDesk(config) {
     dispatch({ type: "CLOSE" });
   }, []);
   const waitForEngine = useCallback(() => {
+    const s = engineStatusRef.current;
+    if (s === "ready" || s === "degraded" || s === "error-index" || s === "error-model") {
+      return Promise.resolve();
+    }
     return new Promise((resolve) => {
-      const check = () => {
-        const s = engineStatusRef.current;
-        if (s === "ready" || s === "degraded" || s === "error-index" || s === "error-model") {
-          resolve();
-        } else {
-          setTimeout(check, 100);
-        }
-      };
-      check();
+      engineReadyCallbacksRef.current.push(resolve);
     });
   }, []);
   const submit = useCallback(
@@ -396,12 +416,20 @@ function useSageDesk(config) {
           console.warn('[sagedesk] LLM mode requires an "endpoint" prop.');
           botText = getFallback(config.agent);
           isFallback = true;
+        } else if (!embedderRef.current?.isReady) {
+          console.warn("[sagedesk] Embedder not ready - showing fallback.");
+          botText = getFallback(config.agent);
+          isFallback = true;
         } else {
           try {
+            const vector = await embedderRef.current.embed(trimmed);
             const res = await fetch(config.endpoint, {
               method: "POST",
               headers: { "Content-Type": "application/json" },
-              body: JSON.stringify({ query: trimmed })
+              body: JSON.stringify({
+                query: trimmed,
+                queryVector: Array.from(vector)
+              })
             });
             if (!res.ok) throw new Error(`HTTP ${res.status}`);
             const data = await res.json();
@@ -445,8 +473,8 @@ function useSageDesk(config) {
       }
       if (config.mode !== "llm") {
         const elapsed = Date.now() - typingStart;
-        const delayBase = retrievalMode === "keyword" || isFallback ? 800 : 3e3;
-        const minTypingMs = delayBase + Math.random() * 2e3;
+        const delayBase = retrievalMode === "keyword" || isFallback ? 400 : 800;
+        const minTypingMs = delayBase + Math.random() * 400;
         const remaining = minTypingMs - elapsed;
         if (remaining > 0) await new Promise((r) => setTimeout(r, remaining));
       }
@@ -464,11 +492,9 @@ function useSageDesk(config) {
     return () => document.removeEventListener("keydown", handler);
   }, [state.isOpen, close]);
   const activeChips = useMemo(() => {
-    const askedTexts = new Set(
-      state.messages.filter((m) => m.role === "user").map((m) => m.text.toLowerCase().trim())
-    );
+    const askedTexts = new Set(state.userMessages.map((m) => m.text.toLowerCase().trim()));
     return chips.filter((chip) => !askedTexts.has(chip.toLowerCase().trim()));
-  }, [chips, state.messages]);
+  }, [chips, state.userMessages]);
   return { state, chips: activeChips, open, close, submit };
 }
 
@@ -664,9 +690,9 @@ var PoweredBy = ({ dark = false }) => /* @__PURE__ */ jsxs("div", { style: {
     }
   )
 ] });
-function ClassicMessageBubble({ msg, accent }) {
+var ClassicMessageBubble = React.memo(function ClassicMessageBubble2({ msg, accent }) {
   const isBot = msg.role === "bot";
-  const renderedHtml = isBot ? parseMarkdown(msg.text) : msg.text;
+  const renderedHtml = useMemo2(() => isBot ? parseMarkdown(msg.text) : msg.text, [isBot, msg.text]);
   return /* @__PURE__ */ jsxs("div", { style: { display: "flex", flexDirection: "column", alignItems: isBot ? "flex-start" : "flex-end", gap: "4px" }, children: [
     msg.isFallback && /* @__PURE__ */ jsx("p", { style: { fontSize: "11px", fontWeight: 500, color: "#9b9aa3", margin: 0, padding: "0 4px", fontFamily: "inherit" }, children: "Not sure about that one" }),
     /* @__PURE__ */ jsx("div", { style: {
@@ -691,7 +717,7 @@ function ClassicMessageBubble({ msg, accent }) {
       fontFamily: "inherit"
     }, children: "just now" })
   ] });
-}
+});
 function ClassicTypingIndicator() {
   const dot = { width: 6, height: 6, borderRadius: "50%", background: "#c8c8ce", display: "inline-block" };
   return /* @__PURE__ */ jsx("div", { style: { display: "flex", flexDirection: "column", alignItems: "flex-start", gap: "4px" }, children: /* @__PURE__ */ jsxs("div", { style: {
@@ -709,9 +735,9 @@ function ClassicTypingIndicator() {
     /* @__PURE__ */ jsx("span", { style: dot, className: "sd-r-dot-3" })
   ] }) });
 }
-function LightMessageBubble({ msg, accent, agentName }) {
+var LightMessageBubble = React.memo(function LightMessageBubble2({ msg, accent, agentName }) {
   const isBot = msg.role === "bot";
-  const renderedHtml = isBot ? parseMarkdown(msg.text) : msg.text;
+  const renderedHtml = useMemo2(() => isBot ? parseMarkdown(msg.text) : msg.text, [isBot, msg.text]);
   if (isBot) {
     return /* @__PURE__ */ jsxs("div", { style: { display: "flex", gap: "10px" }, children: [
       /* @__PURE__ */ jsx("div", { style: {
@@ -746,7 +772,7 @@ function LightMessageBubble({ msg, accent, agentName }) {
     wordBreak: "break-word",
     fontFamily: "inherit"
   }, children: msg.text }) });
-}
+});
 function LightTypingIndicator({ accent }) {
   const dot = { width: 6, height: 6, borderRadius: "50%", background: "#c4c4be", display: "inline-block" };
   return /* @__PURE__ */ jsxs("div", { style: { display: "flex", gap: "10px" }, children: [
@@ -774,9 +800,9 @@ function LightTypingIndicator({ accent }) {
     ] })
   ] });
 }
-function DarkMessageBubble({ msg, accent }) {
+var DarkMessageBubble = React.memo(function DarkMessageBubble2({ msg, accent }) {
   const isBot = msg.role === "bot";
-  const renderedHtml = isBot ? parseMarkdown(msg.text) : msg.text;
+  const renderedHtml = useMemo2(() => isBot ? parseMarkdown(msg.text) : msg.text, [isBot, msg.text]);
   return /* @__PURE__ */ jsxs("div", { style: {
     maxWidth: "85%",
     padding: "12px 14px",
@@ -794,7 +820,7 @@ function DarkMessageBubble({ msg, accent }) {
     msg.isFallback && /* @__PURE__ */ jsx("span", { style: { fontSize: "11px", color: "rgba(255,255,255,0.5)", display: "block", marginBottom: "4px" }, children: "Not sure about that one" }),
     isBot ? /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: renderedHtml } }) : /* @__PURE__ */ jsx("div", { style: { whiteSpace: "pre-wrap" }, children: msg.text })
   ] });
-}
+});
 function DarkTypingIndicator() {
   const dot = { width: 6, height: 6, borderRadius: "50%", background: "rgba(255,255,255,0.4)", display: "inline-block" };
   return /* @__PURE__ */ jsxs("div", { style: {
@@ -813,7 +839,7 @@ function DarkTypingIndicator() {
     /* @__PURE__ */ jsx("span", { style: dot, className: "sd-r-dot-3" })
   ] });
 }
-function renderClassic(p) {
+function ClassicTheme(p) {
   const {
     agent,
     state,
@@ -1002,7 +1028,7 @@ function renderClassic(p) {
     ] })
   ] });
 }
-function renderLight(p) {
+function LightTheme(p) {
   const {
     agent,
     state,
@@ -1190,7 +1216,7 @@ function renderLight(p) {
     ] })
   ] });
 }
-function renderDark(p) {
+function DarkTheme(p) {
   const {
     agent,
     state,
@@ -1427,7 +1453,10 @@ function SageDeskWidget({ mode, indexUrl, endpoint, agent, search: search2 }) {
       '[sagedesk] Required prop "endpoint" is missing for llm mode. Provide your backend route, e.g. endpoint="/api/sagedesk".'
     );
   }
-  const config = { mode: resolvedMode, indexUrl, endpoint, agent, search: search2 };
+  const config = useMemo2(
+    () => ({ mode: resolvedMode, indexUrl, endpoint, agent, search: search2 }),
+    [resolvedMode, indexUrl, endpoint, agent, search2]
+  );
   const { state, chips, open, close, submit } = useSageDesk(config);
   const theme = agent.theme ?? "classic";
   const accent = agent.accentColor ?? "#534AB7";
@@ -1506,10 +1535,10 @@ function SageDeskWidget({ mode, indexUrl, endpoint, agent, search: search2 }) {
     open,
     submit
   };
-  const content = theme === "dark" ? renderDark(props) : theme === "light" ? renderLight(props) : renderClassic(props);
+  const content = theme === "dark" ? /* @__PURE__ */ jsx(DarkTheme, { ...props }) : theme === "light" ? /* @__PURE__ */ jsx(LightTheme, { ...props }) : /* @__PURE__ */ jsx(ClassicTheme, { ...props });
   return createPortal(content, document.body);
 }
 export {
   SageDeskWidget
 };
-//# sourceMappingURL=SageDeskWidget-SJVE6QK3.js.map
+//# sourceMappingURL=SageDeskWidget-ZJJGXTTC.js.map