@usereq/widget 0.2.18 → 0.2.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usereq/widget",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/custom-element/agent-widget-element.tsx

@@ -343,6 +343,17 @@ export class AgentWidgetElement extends HTMLElement {
           this.open = true;
         }
         this.renderWidget();
+        // Bootstrap has finished and status is now "ready". If `autoStart`
+        // is on AND the panel is open (either because `defaultOpen` /
+        // `alwaysOpen` just opened it, or because the visitor opened it
+        // before bootstrap finished and `handleOpenChange` is awaiting
+        // this very `ensureBootstrap` call), trigger the auto-start now.
+        // Without this, the `defaultOpen + autoStart` combination renders
+        // an empty panel with no CTA (autoStart suppresses the Start CTA)
+        // and the visitor sees no welcome message ever.
+        // `maybeAutoStartConversation` is idempotent — it guards on
+        // `autoStartTriggered` so calling it from multiple paths is safe.
+        this.maybeAutoStartConversation();
       } catch (error) {
         if (runVersion !== this.bootstrapVersion) {
           return;

package/src/runtime/bootstrap.ts

@@ -14,6 +14,7 @@ import {
   encodeStopConfirmationResult,
   type StopConfirmationDecision,
 } from "../shared/stop-confirmation";
+import { widgetDebug, widgetWarn } from "./debug";
 
 export type WidgetBootstrapState = {
   session: WidgetSessionState;
@@ -21,6 +22,29 @@ export type WidgetBootstrapState = {
   messages: WidgetMessage[];
 };
 
+/**
+ * Compact, JSON-safe error shape for the verbose logs. Strips noisy
+ * stack lines but keeps message + name + (if present) `code` so AppError
+ * responses surface their server-side code in the customer's console.
+ */
+function serializeError(error: unknown): {
+  name: string;
+  message: string;
+  code?: string;
+  status?: number;
+} {
+  if (error instanceof Error) {
+    const err = error as Error & { code?: unknown; status?: unknown };
+    return {
+      name: err.name,
+      message: err.message,
+      code: typeof err.code === "string" ? err.code : undefined,
+      status: typeof err.status === "number" ? err.status : undefined,
+    };
+  }
+  return { name: "Unknown", message: String(error) };
+}
+
 export type WidgetBootstrapDeps = {
   loadSession: typeof loadSession;
   saveSession: typeof saveSession;
@@ -79,7 +103,16 @@ async function ensureWidgetSession(input: {
       };
       deps.saveSession(input.agentId, refreshed);
       return refreshed;
-    } catch {
+    } catch (error) {
+      // Network blip during the refresh is recoverable — the cached
+      // session is still valid, so we fall back to it. But log so the
+      // customer's DevTools shows the underlying API failure (origin
+      // not allowed, agent archived, server 5xx, etc.).
+      widgetWarn(
+        "bootstrap.refreshSession",
+        "config refresh failed, using cached session",
+        { agentId: input.agentId, error: serializeError(error) },
+      );
       return stored;
     }
   }
@@ -119,7 +152,21 @@ export async function bootstrapWidgetWithDeps(input: {
         sessionToken: session.sessionToken,
       });
       messages = sortByCreatedAt(transcript.data);
-    } catch {
+    } catch (error) {
+      // Stored conversation id was orphaned (deleted server-side,
+      // expired session, etc.). Drop it and act as if we're a fresh
+      // visitor. Surface the underlying failure — silent-drop here is
+      // exactly what makes "no welcome message + no send" so hard to
+      // debug from the outside.
+      widgetWarn(
+        "bootstrap.listMessages",
+        "transcript fetch failed, resetting conversation",
+        {
+          agentId: input.agentId,
+          conversationId,
+          error: serializeError(error),
+        },
+      );
       conversationId = undefined;
       messages = [];
     }
@@ -134,7 +181,17 @@ export async function bootstrapWidgetWithDeps(input: {
         });
         messages = sortByCreatedAt(transcript.data);
       }
-    } catch {
+    } catch (error) {
+      // The `current conversation` lookup failed (most commonly a 401
+      // because the session token is stale, or a 403 because the host
+      // origin isn't in the agent's allow-list). Without surfacing
+      // this, the panel renders empty + `sendDisabled=true` and the
+      // visitor has no way to recover or signal something's wrong.
+      widgetWarn(
+        "bootstrap.currentConversation",
+        "no conversation could be resolved, starting fresh",
+        { agentId: input.agentId, error: serializeError(error) },
+      );
       conversationId = undefined;
       messages = [];
     }
@@ -146,6 +203,15 @@ export async function bootstrapWidgetWithDeps(input: {
   };
   deps.saveSession(input.agentId, sessionState);
 
+  widgetDebug("bootstrap.ready", "session resolved", {
+    agentId: input.agentId,
+    hasConversation: Boolean(conversationId),
+    messageCount: messages.length,
+    autoStart: Boolean(sessionState.widgetConfig.widgetBehavior?.autoStart),
+    defaultOpen: Boolean(sessionState.widgetConfig.widgetBehavior?.defaultOpen),
+    alwaysOpen: Boolean(sessionState.widgetConfig.widgetBehavior?.alwaysOpen),
+  });
+
   return {
     session: sessionState,
     conversationId,

package/src/runtime/debug.ts

@@ -0,0 +1,104 @@
+/**
+ * Widget debug logging.
+ *
+ * Two tiers:
+ *
+ *  1. ALWAYS-ON warnings  (`widgetWarn`) — fired on every silent failure
+ *     path that would otherwise leave the visitor with a broken widget
+ *     and no signal in the console. e.g. `/start` returns 403, the
+ *     transcript fetch dies, the session token is stale. Surfaced via
+ *     `console.warn` so a customer running our widget on their site can
+ *     open DevTools and immediately see WHY the chat isn't working —
+ *     no env vars, no rebuilds, no extra steps.
+ *
+ *  2. OPT-IN traces  (`widgetDebug`) — verbose state-transition logs
+ *     ("bootstrap started", "session restored", "auto-start fired"). Off
+ *     by default; turned on by either:
+ *       - `localStorage.setItem("usereq_debug", "1")` (sticky)
+ *       - `?usereq_debug=1` in the embed-host's URL (one-shot)
+ *
+ * Both routes are namespace-prefixed so customer's own console output
+ * doesn't get tangled with ours.
+ */
+
+const PREFIX = "[usereq-widget]";
+
+/** True when verbose-trace logging is enabled. Memoized per page load. */
+let debugEnabled: boolean | null = null;
+
+export function isWidgetDebugEnabled(): boolean {
+  if (debugEnabled !== null) return debugEnabled;
+  debugEnabled = computeDebugEnabled();
+  return debugEnabled;
+}
+
+function computeDebugEnabled(): boolean {
+  if (typeof window === "undefined") return false;
+  try {
+    // Query param is one-shot per page load — handy for "ask the
+    // customer to add `?usereq_debug=1` to their URL and reproduce."
+    const params = new URLSearchParams(window.location.search);
+    if (params.get("usereq_debug") === "1") return true;
+  } catch {
+    /* iframe with restricted location.search — ignore */
+  }
+  try {
+    if (window.localStorage?.getItem("usereq_debug") === "1") return true;
+  } catch {
+    /* incognito / disabled localStorage — ignore */
+  }
+  return false;
+}
+
+/**
+ * Always-on warning. Use for silent-failure paths where we currently
+ * swallow an error but the visitor's chat will visibly break.
+ *
+ * Output shape:
+ *   [usereq-widget] bootstrap.listMessages failed { agentId, sessionToken, error }
+ */
+export function widgetWarn(scope: string, message: string, context?: unknown): void {
+  if (context === undefined) {
+    console.warn(`${PREFIX} ${scope}: ${message}`);
+    return;
+  }
+  console.warn(`${PREFIX} ${scope}: ${message}`, sanitizeForLog(context));
+}
+
+/**
+ * Opt-in trace. Logs state transitions / network calls when debug mode
+ * is on. Production builds keep these as `console.debug` calls; modern
+ * DevTools hide `debug` by default so the warning channel stays clean.
+ */
+export function widgetDebug(scope: string, message: string, context?: unknown): void {
+  if (!isWidgetDebugEnabled()) return;
+  if (context === undefined) {
+    console.debug(`${PREFIX} ${scope}: ${message}`);
+    return;
+  }
+  console.debug(`${PREFIX} ${scope}: ${message}`, sanitizeForLog(context));
+}
+
+/**
+ * Strip session tokens / PII from arbitrary context objects before
+ * logging. Keeps prefixes long enough to recognize the session at a
+ * glance ("eyJh…") without leaking the secret.
+ */
+function sanitizeForLog(context: unknown): unknown {
+  if (context === null || typeof context !== "object") return context;
+  try {
+    const json = JSON.parse(
+      JSON.stringify(context, (_key, value) => {
+        if (typeof value === "string") {
+          if (value.length > 32 && /^[A-Za-z0-9_.\-+/=]+$/.test(value)) {
+            return `${value.slice(0, 8)}…(redacted, len=${value.length})`;
+          }
+        }
+        return value;
+      }),
+    );
+    return json;
+  } catch {
+    return context;
+  }
+}

package/src/shared/shadow-theme.ts

@@ -5,20 +5,32 @@ export const WIDGET_SHADOW_THEME_CSS = `
    * Anchor inherited typography to the design system.
    *
    * Shadow DOM isolates SELECTORS but NOT inherited properties — the
-   * <usereq-agent-widget> custom element inherits color / font-family /
-   * font-size / line-height from the host page's <body>, and form
-   * controls inside (textarea, input, button) re-inherit via Tailwind's
-   * preflight rule \`color: inherit\`. If the host page sets
-   * \`body { color: #fff }\` the widget's textarea becomes invisible.
+   * <usereq-agent-widget> custom element inherits a long list of text
+   * properties from the host page's <body>, and form controls inside
+   * (textarea, input, button) re-inherit via Tailwind's preflight rule
+   * \`color: inherit\`. Host pages set things like:
    *
-   * Setting these here makes :host the canonical source so every
-   * descendant inside the shadow tree uses our tokens regardless of
-   * what the host page is doing.
+   *   body { color: #fff; }                 → textarea text invisible
+   *   body { text-align: center; }          → every message bubble centered
+   *   body { font-family: cursive; }        → widget renders in cursive
+   *   body { text-transform: uppercase; }   → ALL CAPS UI
+   *
+   * Setting these on :host makes the widget the canonical source so
+   * every descendant inside the shadow tree uses our tokens regardless
+   * of what the host page is doing. Each line below addresses a
+   * commonly-reported customer bleed.
    */
   color: var(--foreground);
   font-family: var(--font-geist-sans), system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   font-size: 16px;
+  font-style: normal;
+  font-weight: 400;
   line-height: 1.5;
+  text-align: left;
+  text-decoration: none;
+  text-transform: none;
+  letter-spacing: normal;
+  word-spacing: normal;
   --tw-border-style: solid;
   --radius: 0.625rem;
   --font-geist-sans: Geist, sans-serif;