@helpai/elements 1.8.0 → 1.10.0

package/docs/troubleshooting.md

@@ -0,0 +1,523 @@
+# Troubleshooting
+
+The widget isn't working as expected. Let's diagnose.
+
+---
+
+## Quick diagnostic checklist
+
+Paste this into your browser console on the page where the widget
+should be:
+
+```js
+// 1. Is the bundle loaded?
+console.log('HelpAI:', typeof window.HelpAI);
+// Expected: "function" (after bundle loads)
+
+// 2. Is an instance mounted?
+console.log('instance:', window.HelpAI?.getInstance?.());
+// Expected: an object with open/close/expand methods, not null
+
+// 3. Is the shadow host in the DOM?
+console.log('host:', document.querySelector('helpai-chat-host, web-ai-chat'));
+// Expected: a DOM element
+
+// 4. What's the current data-mode?
+const host = document.querySelector('helpai-chat-host, web-ai-chat');
+console.log('data-mode:', host?.dataset.mode);
+// Expected: "closed" / "open" / "expanded" / "fullscreen" / "inline" / "standalone"
+
+// 5. What storage does the widget have?
+for (const k of Object.keys(localStorage)) {
+  if (k.startsWith('helpai.')) console.log(k, '=', localStorage.getItem(k));
+}
+```
+
+---
+
+## Widget doesn't appear
+
+### Symptom: no bubble in the corner
+
+1. **Check the console for errors** — most commonly a network error
+   loading `cdn.help.ai/sdk/js/elements/latest/elements.js` (note the versioned
+   path — the bare `cdn.help.ai/elements.js` root 404s). Verify the URL in
+   DevTools → Network tab.
+
+2. **Is the deployment identity complete?**
+
+   ```js
+   // In console:
+   window.HelpAI?.getInstance?.();
+   ```
+
+   Returns `null` if no instance mounted. Likely causes:
+   - Missing required `data-ai-agent-deployment-id` on the install script.
+   - `init()` called without `aiAgentDeploymentId`. `publicKey` is optional only for intentional guest mode.
+   - Typo in the key or deployment ID.
+
+3. **Is the host element in the DOM?**
+
+   ```js
+   document.querySelector('helpai-chat-host');
+   ```
+
+   If null, the widget didn't mount. Check the console for init errors.
+
+4. **Is the host hidden by host-page CSS?** — shouldn't happen (the
+   widget uses `all: initial` to reset), but if you've got a very
+   aggressive `* { display: none !important; }` style somewhere:
+
+   ```js
+   const host = document.querySelector('helpai-chat-host');
+   console.log(getComputedStyle(host).display); // should be "block" or "inline-block"
+   ```
+
+5. **Is `launcher.hidden: true` set?** — that hides the FAB. Check
+   your options.
+
+6. **Is `mode` set to `inline` or `standalone`?** — those modes don't
+   show a launcher. Check your options.
+
+### Symptom: bubble shows but clicking does nothing
+
+1. **Check the network tab** — clicking fires `/pai/handshake`.
+   An opaque 404 means the credentials did not match an enabled deployment or
+   the requesting origin was not allowed. 0 (blocked) means a CORS / ad-blocker
+   issue.
+
+2. **Are `x-public-key` and `x-ai-agent-deployment-id` making it through?** —
+   some corporate proxies strip custom headers. Test on a personal network.
+
+3. **Any CSP errors in the console?** — `"Refused to connect to
+   https://help.ai/api/agent because it violates the following Content
+   Security Policy…"` means you need to add `help.ai` to your
+   `connect-src`. See [Security § CSP](./security-privacy.md#content-security-policy).
+
+---
+
+## Widget appears but doesn't behave right
+
+### Symptom: "Failed to fetch" errors on open
+
+Network issue. Common causes:
+
+- **Ad blocker** — uBlock Origin / AdBlock Plus sometimes block
+  `help.ai` API calls as tracking. Whitelist it.
+- **Corporate proxy** — some proxies block `text/event-stream`
+  (streaming responses). Test on a different network.
+- **CSP** — your Content Security Policy is missing
+  `help.ai` in `connect-src`.
+
+### Symptom: panel appears in the wrong spot on mobile
+
+Only in `floating` mode. The widget uses `position: fixed` anchored
+to `presentation.position` (`bottom-right` default). If mobile viewport
+units are behaving oddly (iOS Safari, looking at you):
+
+1. Ensure you have a viewport meta tag:
+
+   ```html
+   <meta name="viewport" content="width=device-width, initial-scale=1" />
+   ```
+
+2. Avoid having `overflow: hidden` on `<html>` or `<body>` — this
+   clips fixed positioning on some browsers.
+
+3. If still stuck, try `presentation.mode: "inline"` inside a dedicated container
+   on mobile breakpoints.
+
+### Symptom: panel doesn't fill its container (inline mode)
+
+The parent container needs explicit dimensions. Inline widgets fill
+100% × 100% of their parent, which falls back to `min-height: 320px`
+if the parent is 0-height.
+
+```css
+/* Parent needs a size */
+.my-chat-container {
+  height: 500px;
+  /* or */
+  display: flex;
+  flex-direction: column;
+  /* with widget set to flex: 1 */
+}
+
+.my-chat-container web-ai-chat {
+  flex: 1 1 0;
+  min-height: 0; /* critical for flex children */
+}
+```
+
+### Symptom: two widgets on the same page overlap or conflict
+
+Use distinct `widgetId` values:
+
+```ts
+init({ widgetId: 'support', publicKey: SUPPORT_KEY, aiAgentDeploymentId: SUPPORT_DEPLOYMENT_ID });
+init({ widgetId: 'sales', publicKey: SALES_KEY, aiAgentDeploymentId: SALES_DEPLOYMENT_ID });
+```
+
+And position them in different corners:
+
+```ts
+init({ widgetId: 'support', presentation: { position: 'bottom-right' } });
+init({ widgetId: 'sales', presentation: { position: 'bottom-left' } });
+```
+
+Without distinct widgetIds, the second `init()` **replaces** the
+first.
+
+---
+
+## Styling issues
+
+### Symptom: widget ignores my CSS
+
+That's by design. The widget lives inside a shadow root — your page
+CSS can't reach inside. Use the [theming options](./theming.md)
+instead.
+
+For advanced customization, override CSS custom properties on the
+host element:
+
+```css
+web-ai-chat,
+helpai-chat-host {
+  --helpai-accent: #ff3e00;
+  --helpai-radius: 16px;
+  --helpai-font: "Söhne", system-ui, sans-serif;
+}
+```
+
+These cascade through the shadow root.
+
+### Symptom: the widget inherits my weird base font
+
+Most likely the host page uses `* { font-family: X !important }`.
+The widget's `all: initial` reset handles most cases, but extreme
+overrides can leak.
+
+Force the widget's font explicitly via option:
+
+```ts
+init({
+  theme: {
+    fontFamily: 'Inter, system-ui, sans-serif',
+  },
+});
+```
+
+### Symptom: launcher bubble is a different color than expected
+
+Check:
+
+1. `theme.accent` in your `init()` options.
+2. The workspace default accent in your Help AI dashboard.
+3. `prefers-color-scheme` — the accent might look different in dark
+   mode vs. light.
+
+To debug:
+
+```js
+const host = document.querySelector('helpai-chat-host');
+console.log('data-theme:', host.dataset.theme); // auto / light / dark
+console.log('computed accent:', getComputedStyle(host).getPropertyValue('--helpai-accent'));
+```
+
+---
+
+## Persistence issues
+
+### Symptom: chat history doesn't persist across reloads
+
+1. **Is localStorage available?** Private/incognito modes may disable it.
+
+   ```js
+   try {
+     localStorage.setItem('_test', '1');
+     console.log('OK');
+   } catch (e) {
+     console.error('Blocked', e);
+   }
+   ```
+
+2. **Check the widget's storage keys:**
+
+   ```js
+   for (const k of Object.keys(localStorage)) {
+     if (k.startsWith('helpai.')) console.log(k);
+   }
+   ```
+
+   You should see at least `helpai.default.visitorId` and (after a
+   chat) `helpai.default.conversationId`.
+
+3. **Is the `widgetId` consistent across reloads?** If you pass a
+   dynamic `widgetId` (e.g., based on current time), each load gets
+   a fresh namespace and history won't carry over.
+
+### Symptom: user switches devices, chat history doesn't follow
+
+That's the designed behavior for the current conversationId (per-device).
+What DOES sync across devices:
+
+- Locale preference.
+- Theme mode.
+- Sound mute toggle.
+- Drag-resized panel dimensions.
+
+These sync via the backend's `userPrefs` store, keyed by the widget's
+own anonymous `visitorId`. Chat messages themselves are tied to that
+`visitorId`, which is per-browser. `userContext` is informational
+context for the AI only — it does not link chats across devices.
+
+---
+
+## React / framework issues
+
+### Symptom: "window is not defined" during build
+
+You're calling `init()` at module scope or during SSR. Move it
+inside a lifecycle hook that only fires in the browser:
+
+```tsx
+// Wrong:
+const chat = init({ publicKey, aiAgentDeploymentId }); // runs during SSR
+
+export function App() { ... }
+
+// Right:
+export function App() {
+  useEffect(() => {
+    const chat = init({ publicKey, aiAgentDeploymentId });
+    return () => chat.destroy();
+  }, []);
+}
+```
+
+### Symptom: widget mounts twice in React
+
+React 18 strict mode intentionally double-invokes `useEffect` in
+development. Your cleanup must be complete:
+
+```tsx
+useEffect(() => {
+  const chat = init({ publicKey, aiAgentDeploymentId });
+  return () => chat.destroy(); // ← this MUST unmount cleanly
+}, []);
+```
+
+If you see "instance already exists at widgetId", your cleanup isn't
+running. Check for missed `return () => …`.
+
+### Symptom: HMR leaves stale widgets on the page
+
+During Vite / Next.js HMR, the module re-runs without the React tree
+being torn down. Symptoms: multiple launchers appear, old styles
+stick around.
+
+Workaround: use `init()` (idempotent) instead of `mount()`. `init()`
+auto-replaces any existing instance at the same `widgetId`.
+
+### Symptom: TypeScript complains about `<web-ai-chat>`
+
+You're using the web component in React < 19. Add a type
+declaration:
+
+```ts
+// src/web-ai-chat.d.ts
+declare namespace JSX {
+  interface IntrinsicElements {
+    'web-ai-chat': React.DetailedHTMLProps<
+      React.HTMLAttributes<HTMLElement> & {
+        'public-key'?: string;
+        mode?: 'floating' | 'inline' | 'standalone';
+        theme?: 'auto' | 'light' | 'dark';
+      },
+      HTMLElement
+    >;
+  }
+}
+```
+
+---
+
+## Event / hook issues
+
+### Symptom: `.on('message', ...)` never fires
+
+1. **Is the instance really mounted?**
+
+   ```js
+   const chat = init({ publicKey: '...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000' });
+   console.log(chat.widgetId); // should log the id
+   ```
+
+2. **Are messages being sent?** Open the Network tab, filter
+   `stream-message`. A send should produce a POST.
+
+3. **Is the listener attached BEFORE you send?** If you attach after
+   the user sent a message, you miss that one.
+
+### Symptom: pre-boot hooks never fire
+
+1. **Is the bundle loading?** Check Network → `elements.js` →
+   status 200.
+
+2. **Is `window.HelpAIHooks` an array?**
+
+   ```js
+   Array.isArray(window.HelpAIHooks); // should be true
+   ```
+
+3. **Is the entry shape correct?**
+   ```js
+   // Tuple form:
+   window.HelpAIHooks.push(['*', '*', (inst, e, d) => console.log(e)]);
+   // Object form:
+   window.HelpAIHooks.push({ widgetId: '*', event: '*', listener: fn });
+   ```
+
+---
+
+## Performance issues
+
+### Symptom: page feels slow when widget loads
+
+1. **Are you using `defer` on the script tag?** Without `defer`, the
+   script blocks HTML parsing.
+
+2. **Check the Network tab** — the bundle should be ~107 KB gzipped (budget 108 KB)
+   and load in well under a second on a good connection.
+
+3. **Are you self-hosting an older version?** Pull the latest.
+   Older versions were larger.
+
+4. **Lighthouse or WebPageTest** — run a test. The widget is
+   deferred and shouldn't affect LCP. If you see CLS spikes, the
+   widget's host element might be affecting layout — ensure
+   `position: fixed` is working (floating mode) or the inline
+   container has a stable size.
+
+### Symptom: streaming feels choppy
+
+1. **Slow backend** — the widget just renders what it receives. Check
+   the stream latency in Network → the `stream-message` entry.
+
+2. **Network conditions** — SSE is sensitive to packet loss. Try a
+   different network.
+
+3. **Buffered response mode** — try `behavior.responseMode: "buffered"` if
+   streaming is unusable on your users' networks. Tradeoff: they wait
+   for the whole reply before seeing anything.
+
+---
+
+## CORS / CSP / networking
+
+### Symptom: CORS errors in the console
+
+Our API is CORS-permissive to every origin. If you're seeing CORS
+errors:
+
+- **Check the URL** — `https://help.ai` (the bare origin — not a
+  relative path; the widget appends `/api/agent` + `/api/data` itself).
+- **Check for browser extensions** blocking `help.ai`.
+- **Check your reverse proxy** — some enterprise proxies strip CORS
+  headers.
+
+### Symptom: CSP blocks the widget
+
+Add to your Content Security Policy:
+
+```
+script-src 'self' https://cdn.help.ai;
+connect-src 'self' https://help.ai;
+style-src 'self' 'unsafe-inline';            # Shadow DOM inline styles
+img-src 'self' data: blob: https:;
+font-src 'self' https:;
+media-src 'self' blob:;                      # For voice recording
+```
+
+Full CSP guide: [Security § CSP](./security-privacy.md#content-security-policy).
+
+---
+
+## Widget-specific behavior questions
+
+### "The widget opens to a stale chat thread — how do I reset?"
+
+Click the trash icon (Clear action) in the panel → "Start new
+conversation". This creates a fresh conversationId.
+
+Programmatic:
+
+```ts
+// Clear the persisted conversationId + unmount, then remount
+for (const k of Object.keys(localStorage)) {
+  if (k.startsWith('helpai.') && k.endsWith('.conversationId')) localStorage.removeItem(k);
+}
+destroy();
+init({ publicKey: 'agent_pk_...', aiAgentDeploymentId: '01900000-0000-7000-8000-000000000000' });
+```
+
+### "Can I send a message programmatically for the user?"
+
+Not via the public API — by design. Messages must come from user
+input (so they see + confirm what's being sent). Use **welcome
+suggestions** in your dashboard for "prefilled" conversation
+starters.
+
+### "Can I get the full chat transcript?"
+
+From the client, no direct API. Subscribe to `message` events and
+build your own log:
+
+```ts
+const transcript = [];
+chat.on('message', (m) => transcript.push(m));
+```
+
+Via the backend, yes — query the chats API with your visitor's
+conversation token. Contact support for the server-side endpoint docs.
+
+### "Why can't I see what the user is typing in real-time?"
+
+Privacy. The widget doesn't emit events for in-progress typing —
+only committed messages (Enter / Send click). If you need
+keystroke-level telemetry, that's not supported.
+
+### "The widget's language is wrong for my user"
+
+Resolution precedence:
+
+1. User's persisted pick (language switcher).
+2. `init({ i18n: { locale: '...' } })`.
+3. `init({ i18n: { defaultLocale: '...' } })`.
+4. `navigator.language` (when `i18n.defaultLocale: "auto"`).
+5. English (`"en"`).
+
+To force: `init({ i18n: { locale: 'fr-CA' } })`. To let the visitor switch,
+provide `i18n.availableLocales` and include `language` in `header.actions`.
+
+---
+
+## Getting more help
+
+1. **Read the [FAQ](./faq.md)** — most common questions answered
+   there.
+
+2. **Check our GitHub issues**: [github.com/help-ai/elements](https://github.com/help-ai/elements/issues).
+
+3. **Email support**: [support@help.ai](mailto:support@help.ai). Include:
+   - The URL of the page where the issue appears.
+   - Browser + version.
+   - Screenshot + console output.
+   - Steps to reproduce.
+
+4. **Status page**: [help.ai/status](https://help.ai/status) — check
+   for ongoing incidents before troubleshooting.
+
+5. **Debug mode**: add `?helpai-debug=1` to your URL. The widget
+   logs its internal state to the console (prefixed with `[helpai]`).