@usereq/widget 0.2.20 → 0.2.22

package/package.json

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

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

@@ -1,6 +1,5 @@
 import React from "react";
 import { createRoot, type Root } from "react-dom/client";
-import { DEFAULT_START_CONVERSATION_LABEL } from "../chat-widget/chat-widget-defaults";
 import {
   DEFAULT_WIDGET_APPEARANCE,
   DEFAULT_WIDGET_PRESET,
@@ -15,7 +14,10 @@ import {
   type WidgetSessionState,
   type WidgetVariant,
 } from "../types";
-import { widgetTriggerRuleKey } from "../shared/widget-config";
+import {
+  normalizeWidgetMobileHeight,
+  widgetTriggerRuleKey,
+} from "../shared/widget-config";
 import { WidgetRuntime, type WidgetRuntimeStatus } from "../renderer/index";
 import { buildAssistantMessageRevealSteps } from "../chat-widget/message-reveal";
 import { DEFAULT_STOP_CONVERSATION_PROMPT } from "../shared/stop-confirmation";
@@ -23,7 +25,6 @@ import {
   bootstrapWidget,
   resetWidgetSession,
   submitWidgetStopConfirmation,
-  startWidgetConversation,
   submitWidgetMessage,
 } from "../runtime/bootstrap";
 import { getWidgetShadowCss } from "../shared/shadow-css";
@@ -67,7 +68,12 @@ export class AgentWidgetElement extends HTMLElement {
   private sendVersion = 0;
   private confirmationVersion = 0;
   private bootstrapPhase: "idle" | "booting" | "ready" | "blocked" = "idle";
-  private autoStartTriggered = false;
+  // Back-to-back send support. The composer stays enabled while the agent
+  // is replying; new submissions land here and are drained sequentially by
+  // `sendMessage`. Each entry carries the optimistic bubble id so failures
+  // can yank exactly the right row.
+  private pendingQueue: Array<{ content: string; optimisticId: string }> = [];
+  private draining = false;
 
   constructor() {
     super();
@@ -207,6 +213,10 @@ export class AgentWidgetElement extends HTMLElement {
     this.welcomeMessage = null;
     this.errorMessage = null;
     this.status = "idle";
+    // Bumping sendVersion above invalidates the in-flight drain; reset
+    // the queue + flag so the next session starts fresh.
+    this.pendingQueue = [];
+    this.draining = false;
   }
 
   private renderWidget() {
@@ -224,32 +234,7 @@ export class AgentWidgetElement extends HTMLElement {
     const variant = this.getResolvedVariant();
     const preset = this.getResolvedPreset();
     const behavior = this.sessionConfig?.widgetConfig.widgetBehavior;
-    const autoStartEnabled = behavior?.autoStart === true;
     const alwaysOpen = behavior?.alwaysOpen === true;
-    const awaitingConversation =
-      this.status === "booting" ||
-      (this.sessionState != null && !this.sessionState.conversationId);
-    // When auto-start is on we never render the manual CTA — except as a
-    // fallback if the auto-start attempt errored, so the visitor isn't
-    // stranded on a blank panel.
-    const showFallbackCta = autoStartEnabled && this.status === "error";
-    const emptyAction =
-      !autoStartEnabled && awaitingConversation
-        ? {
-            label: DEFAULT_START_CONVERSATION_LABEL,
-            onClick: () => void this.handleStartConversation(),
-            disabled: this.status !== "ready",
-          }
-        : showFallbackCta
-        ? {
-            label: DEFAULT_START_CONVERSATION_LABEL,
-            onClick: () => {
-              this.autoStartTriggered = false;
-              void this.handleStartConversation();
-            },
-            disabled: false,
-          }
-        : undefined;
 
     this.root.render(
       React.createElement(WidgetRuntime, {
@@ -267,19 +252,23 @@ export class AgentWidgetElement extends HTMLElement {
         welcomeMessage: this.getWelcomeMessage(),
         spotlights: this.getSpotlights(),
         ctaLink: this.getCtaLink(),
+        mobileHeight: normalizeWidgetMobileHeight(
+          this.sessionConfig?.widgetConfig.mobileHeight,
+        ),
         open: this.open,
         alwaysOpen,
         status: this.status,
         messages: this.messages,
         errorMessage: this.errorMessage,
         triggerRule: this.sessionConfig?.widgetConfig.triggerRule ?? null,
-        emptyAction,
+        // Lazy session: no "Start a chat" gate. The composer is live from
+        // the moment the panel opens; the conversation is created on the
+        // server the first time the user actually sends something.
+        emptyAction: undefined,
         onStopConversation:
           this.sessionState?.conversationId != null
             ? () => void this.handleStopConversation()
             : undefined,
-        sendDisabled:
-          this.status === "sending" || !this.sessionState?.conversationId,
         onOpenChange: (nextOpen: boolean) => void this.handleOpenChange(nextOpen),
         onSendMessage: (content: string) => void this.sendMessage(content),
         onConfirmationDecision: (confirmationId: string, accepted: boolean) =>
@@ -335,6 +324,11 @@ export class AgentWidgetElement extends HTMLElement {
         this.welcomeMessage = state.session.widgetConfig.welcomeMessage;
         this.status = "ready";
         this.bootstrapPhase = "ready";
+        // Lazy session: when the visitor doesn't already have a running
+        // conversation, seed a client-side welcome bubble from the boot
+        // config so the panel doesn't open on a blank empty state. The
+        // real conversation is only created server-side once they type.
+        this.seedClientWelcomeIfNeeded();
         // Apply the agent's configured open-state on mount. `alwaysOpen`
         // wins (the panel is pinned regardless), and `defaultOpen` opens it
         // once if the visitor hasn't already interacted with the launcher.
@@ -343,17 +337,6 @@ 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;
@@ -374,35 +357,125 @@ export class AgentWidgetElement extends HTMLElement {
     return this.bootstrapPromise;
   }
 
+  /**
+   * Entry point for user-typed sends. Drops the optimistic bubble in
+   * immediately so the user sees their own backlog, then either kicks off
+   * the drain loop (if idle) or appends to `pendingQueue` (if a prior send
+   * is still mid-stream). The drain loop runs at most one POST in flight
+   * at a time — the server-side session memory expects sequential turns,
+   * and the AI engineer confirmed parallel requests are *possible* but
+   * the answers would interleave out-of-order on the wire.
+   */
   private async sendMessage(content: string) {
     const trimmedContent = content.trim();
-    if (!trimmedContent || !this.sessionState?.conversationId) return;
-
-    const runVersion = ++this.sendVersion;
-    const optimisticMessageId = `optimistic:${Date.now()}`;
+    // Lazy session: no `conversationId` check here. If the visitor is
+    // sending their very first message, `submitWidgetMessage` will call
+    // POST /conversations/public/start under the hood before posting.
+    if (!trimmedContent || !this.sessionState) return;
+
+    const optimisticMessageId = `optimistic:${Date.now()}:${Math.random()
+      .toString(36)
+      .slice(2, 8)}`;
     const optimisticMessage: WidgetMessage = {
       id: optimisticMessageId,
-      conversationId: this.sessionState.conversationId,
+      // Empty when no conversation exists yet — the real id lands on the
+      // server row we swap in from `submitWidgetMessage`'s response.
+      conversationId: this.sessionState.conversationId ?? "",
       role: "user",
       content: trimmedContent,
       createdAt: new Date().toISOString(),
     };
 
-    this.status = "sending";
     this.errorMessage = null;
     this.messages = [...this.messages, optimisticMessage];
     this.renderWidget();
 
+    // Drain already running → just join the queue. The drainer will
+    // consume this entry as soon as the in-flight POST + reveal settle.
+    if (this.draining) {
+      this.pendingQueue.push({
+        content: trimmedContent,
+        optimisticId: optimisticMessageId,
+      });
+      return;
+    }
+
+    this.draining = true;
+    this.status = "sending";
+    this.renderWidget();
+
+    const runVersion = this.sendVersion;
+    let succeeded = true;
+
+    try {
+      await this.processSend(trimmedContent, optimisticMessageId, runVersion);
+      while (this.pendingQueue.length > 0 && runVersion === this.sendVersion) {
+        const next = this.pendingQueue.shift()!;
+        await this.processSend(next.content, next.optimisticId, runVersion);
+      }
+    } catch {
+      succeeded = false;
+      if (runVersion === this.sendVersion) {
+        // Drop the rest of the backlog — each queued message expects the
+        // server to have already consumed the prior turn, which didn't
+        // happen. Leaving them queued would silently fire mid-failure.
+        const failedIds = new Set(
+          this.pendingQueue.map((entry) => entry.optimisticId),
+        );
+        this.pendingQueue = [];
+        this.messages = this.messages.filter((m) => !failedIds.has(m.id));
+        // `processSend` already set status="error" + errorMessage; render
+        // once more so the cleared queue is visible.
+        this.renderWidget();
+      }
+    } finally {
+      this.draining = false;
+      if (succeeded && runVersion === this.sendVersion) {
+        this.status = "ready";
+        this.renderWidget();
+      }
+    }
+  }
+
+  /**
+   * One round-trip: POST → swap optimistic → stagger assistant reveal.
+   * Throws on failure so the outer drainer can clear the backlog. The
+   * `runVersion` guard short-circuits late state writes if a hard reset
+   * (agent-id change, conversation reset) bumped `sendVersion` mid-drain.
+   */
+  private async processSend(
+    content: string,
+    optimisticId: string,
+    runVersion: number,
+  ) {
     try {
       const result = await submitWidgetMessage({
         agentId: this.agentId,
-        content: trimmedContent,
+        content,
       });
-      if (runVersion !== this.sendVersion) {
-        return;
-      }
+      if (runVersion !== this.sendVersion) return;
       this.sessionState = result.session;
 
+      // Lazy-start swap: when this was the first send, `submitWidgetMessage`
+      // created the conversation server-side and the server inserted its
+      // own welcome message row. Replace the placeholder client-welcome
+      // bubble with the real server row so ids/timestamps match the DB.
+      if (result.welcomeMessage) {
+        const clientWelcomeId = this.getClientWelcomeId();
+        this.messages = this.messages.map((m) =>
+          m.id === clientWelcomeId
+            ? {
+                id: result.welcomeMessage!.id,
+                conversationId: result.conversationId,
+                role: "assistant",
+                content: result.welcomeMessage!.content,
+                createdAt: result.welcomeMessage!.createdAt,
+              }
+            : m,
+        );
+        this.renderWidget();
+      }
+
       const revealSteps = buildAssistantMessageRevealSteps(
         result.assistantMessages.map((message) => ({
           id: message.id,
@@ -418,10 +491,10 @@ export class AgentWidgetElement extends HTMLElement {
       );
 
       for (const step of revealSteps) {
-        await new Promise((resolve) => window.setTimeout(resolve, step.delayMs));
-        if (runVersion !== this.sendVersion) {
-          return;
-        }
+        await new Promise((resolve) =>
+          window.setTimeout(resolve, step.delayMs),
+        );
+        if (runVersion !== this.sendVersion) return;
         const dto = step.message;
         this.messages = [
           ...this.messages,
@@ -435,22 +508,17 @@ export class AgentWidgetElement extends HTMLElement {
         ];
         this.renderWidget();
       }
-
-      if (runVersion === this.sendVersion) {
-        this.status = "ready";
-        this.renderWidget();
-      }
     } catch (error) {
       if (runVersion !== this.sendVersion) {
+        // The hard reset path already cleared state — swallow.
         return;
       }
-      this.messages = this.messages.filter(
-        (message) => message.id !== optimisticMessageId,
-      );
+      this.messages = this.messages.filter((m) => m.id !== optimisticId);
       this.status = "error";
       this.errorMessage =
         error instanceof Error ? error.message : "Failed to send message";
       this.renderWidget();
+      throw error;
     }
   }
 
@@ -461,55 +529,34 @@ export class AgentWidgetElement extends HTMLElement {
     if (this.open && (this.status === "idle" || !this.sessionState)) {
       await this.ensureBootstrap();
     }
+  }
 
-    this.maybeAutoStartConversation();
+  private getClientWelcomeId(): string {
+    return `client-welcome:${this.agentId}`;
   }
 
   /**
-   * Auto-start opt-in: when the agent has `widgetBehavior.autoStart`
-   * enabled, the first time the visitor opens the launcher we transparently
-   * call /conversations/public/start so they skip the empty state. Fires
-   * once per element lifetime; subsequent opens reuse the existing
-   * conversation via the standard sessionStorage rehydrate.
+   * Lazy session seeding. When bootstrap finishes with no live conversation
+   * and no rehydrated transcript, drop a synthetic assistant bubble carrying
+   * the boot-config welcome copy into `this.messages`. Skipped when there's
+   * already a transcript (rehydrated session) or no welcome copy configured.
+   * The bubble's id is stable (`client-welcome:{agentId}`) so `processSend`
+   * can swap it for the real server row after the first successful send.
    */
-  private maybeAutoStartConversation() {
-    if (this.autoStartTriggered) return;
-    if (!this.open) return;
-    if (this.status !== "ready") return;
-    if (!this.sessionConfig) return;
-    if (!this.sessionConfig.widgetConfig.widgetBehavior?.autoStart) return;
+  private seedClientWelcomeIfNeeded() {
+    if (this.messages.length > 0) return;
     if (this.sessionState?.conversationId) return;
-
-    this.autoStartTriggered = true;
-    void this.handleStartConversation();
-  }
-
-  private async handleStartConversation() {
-    if (!this.sessionState) {
-      await this.ensureBootstrap();
-    }
-    if (!this.sessionState) {
-      return;
-    }
-
-    this.status = "booting";
-    this.errorMessage = null;
-    this.renderWidget();
-
-    try {
-      const result = await startWidgetConversation({
-        agentId: this.agentId,
-      });
-      this.sessionState = result.session;
-      this.messages = result.messages;
-      this.status = "ready";
-      this.renderWidget();
-    } catch (error) {
-      this.status = "error";
-      this.errorMessage =
-        error instanceof Error ? error.message : "Failed to start conversation";
-      this.renderWidget();
-    }
+    const welcome = this.getWelcomeMessage();
+    if (!welcome) return;
+    this.messages = [
+      {
+        id: this.getClientWelcomeId(),
+        conversationId: "",
+        role: "assistant",
+        content: welcome,
+        createdAt: new Date().toISOString(),
+      },
+    ];
   }
 
   private async handleStopConversation() {

package/src/renderer/widget-runtime.tsx

@@ -14,6 +14,7 @@ import type { WidgetMessage } from "../types";
 import {
   splitWidgetPlacement,
   type WidgetAppearance,
+  type WidgetMobileHeight,
   type WidgetPlacement,
   type WidgetPreset,
   type WidgetVariant,
@@ -49,6 +50,11 @@ export type WidgetRuntimeProps = {
   welcomeMessage: string | null;
   spotlights: string[];
   ctaLink?: string | null;
+  /**
+   * How much of the screen the open panel covers on mobile. Ignored on
+   * desktop, where the panel floats above the launcher regardless.
+   */
+  mobileHeight?: WidgetMobileHeight;
   open: boolean;
   /**
    * When true, the embedded panel is pinned open and the launcher is hidden.
@@ -93,6 +99,7 @@ export function WidgetRuntime({
   welcomeMessage,
   spotlights,
   ctaLink,
+  mobileHeight = "full",
   open,
   alwaysOpen = false,
   status,
@@ -142,11 +149,13 @@ export function WidgetRuntime({
       ctaLink,
       actionLabel: appearance.actionText || undefined,
       showStopConversation: Boolean(onStopConversation),
+      mobileHeight,
     }),
     [
       agentAvatarUrl,
       appearance,
       ctaLink,
+      mobileHeight,
       onStopConversation,
       placement,
       preset,

package/src/runtime/bootstrap.ts

@@ -227,6 +227,15 @@ export async function bootstrapWidget(input: {
   return bootstrapWidgetWithDeps(input, defaultBootstrapDeps);
 }
 
+/**
+ * Send a user message. Lazy-starts the conversation on the first send —
+ * `startPublicChat` is called transparently when no `conversationId` is
+ * stored yet, so visitors never create empty conversations by opening
+ * the panel and walking away. When a start happens as part of this call
+ * the server-inserted welcome message rides back on `welcomeMessage`
+ * so the caller can reconcile the client-side placeholder bubble with
+ * the real DB row.
+ */
 export async function submitWidgetMessage(input: {
   agentId: string;
   content: string;
@@ -236,37 +245,52 @@ export async function submitWidgetMessage(input: {
   messages: WidgetMessage[];
   userMessage: WidgetMessage;
   assistantMessages: WidgetMessage[];
+  welcomeMessage?: WidgetMessage;
 }> {
-  const stored = await ensureWidgetSession({
+  let stored = await ensureWidgetSession({
     agentId: input.agentId,
     pageUrl: window.location.href,
     referrer: document.referrer || undefined,
   });
-  if (!stored.conversationId) {
-    throw new Error("Widget conversation not started");
+
+  let welcomeMessage: WidgetMessage | undefined;
+  let conversationId: string;
+  if (stored.conversationId) {
+    conversationId = stored.conversationId;
+  } else {
+    const started = await startPublicChat({
+      agentId: input.agentId,
+      sessionToken: stored.sessionToken,
+    });
+    conversationId = started.conversation.id;
+    stored = { ...stored, conversationId };
+    saveSession(input.agentId, stored);
+    welcomeMessage = started.welcomeMessage;
   }
 
   const response = await sendPublicChatMessage({
-    conversationId: stored.conversationId,
+    conversationId,
     sessionToken: stored.sessionToken,
     content: input.content,
   });
 
   const nextSession: WidgetSessionState = {
     ...stored,
-    conversationId: stored.conversationId,
+    conversationId,
   };
   saveSession(input.agentId, nextSession);
 
   return {
     session: nextSession,
-    conversationId: stored.conversationId,
+    conversationId,
     messages: sortByCreatedAt([
+      ...(welcomeMessage ? [welcomeMessage] : []),
       response.userMessage,
       ...response.assistantMessages,
     ]),
     userMessage: response.userMessage,
     assistantMessages: response.assistantMessages,
+    welcomeMessage,
   };
 }
 
@@ -337,39 +361,6 @@ export async function submitWidgetStopConfirmation(input: {
   };
 }
 
-export async function startWidgetConversation(input: {
-  agentId: string;
-}): Promise<{
-  session: WidgetSessionState;
-  conversationId: string;
-  messages: WidgetMessage[];
-  welcomeMessage: WidgetMessage;
-}> {
-  const stored = await ensureWidgetSession({
-    agentId: input.agentId,
-    pageUrl: window.location.href,
-    referrer: document.referrer || undefined,
-  });
-
-  const response = await startPublicChat({
-    agentId: input.agentId,
-    sessionToken: stored.sessionToken,
-  });
-
-  const nextSession: WidgetSessionState = {
-    ...stored,
-    conversationId: response.conversation.id,
-  };
-  saveSession(input.agentId, nextSession);
-
-  return {
-    session: nextSession,
-    conversationId: response.conversation.id,
-    messages: sortByCreatedAt([response.welcomeMessage]),
-    welcomeMessage: response.welcomeMessage,
-  };
-}
-
 export async function resetWidgetSession(agentId: string): Promise<void> {
   clearSession(agentId);
 }

package/src/shared/widget-config.ts

@@ -18,6 +18,27 @@ export type WidgetPreset = "default" | "facebook_messenger";
 
 export const DEFAULT_WIDGET_PRESET: WidgetPreset = "default";
 
+/**
+ * How much of the screen the open panel covers on mobile. `full` is the
+ * edge-to-edge sheet; the others render a bottom drawer over the host page.
+ */
+export type WidgetMobileHeight = "half" | "three-quarter" | "full";
+
+export const DEFAULT_WIDGET_MOBILE_HEIGHT: WidgetMobileHeight = "full";
+
+export function normalizeWidgetMobileHeight(
+  value: string | null | undefined,
+): WidgetMobileHeight {
+  switch (value) {
+    case "half":
+    case "three-quarter":
+    case "full":
+      return value;
+    default:
+      return DEFAULT_WIDGET_MOBILE_HEIGHT;
+  }
+}
+
 export type WidgetAppearance = ResolvedChatWidgetAppearance;
 
 export const DEFAULT_WIDGET_APPEARANCE: WidgetAppearance =

package/src/types.ts

@@ -1,6 +1,7 @@
 import type {
   WidgetAppearance,
   WidgetBehavior,
+  WidgetMobileHeight,
   WidgetPlacement,
   WidgetPreset,
   WidgetVariant,
@@ -10,14 +11,17 @@ import type {
 export {
   DEFAULT_WIDGET_APPEARANCE,
   DEFAULT_WIDGET_BEHAVIOR,
+  DEFAULT_WIDGET_MOBILE_HEIGHT,
   DEFAULT_WIDGET_PRESET,
   type WidgetAppearance,
   type WidgetBehavior,
+  type WidgetMobileHeight,
   type WidgetPlacement,
   type WidgetPreset,
   type WidgetVariant,
   normalizeWidgetAppearance,
   normalizeWidgetBehavior,
+  normalizeWidgetMobileHeight,
   normalizeWidgetPlacement,
   normalizeWidgetPreset,
   normalizeWidgetVariant,
@@ -41,6 +45,12 @@ export type WidgetSessionConfig = {
     widgetVariant: WidgetVariant;
     widgetPreset: WidgetPreset;
     widgetPlacement: WidgetPlacement;
+    /**
+     * Mobile presentation of the open panel. Optional on the wire so an
+     * embed running against an older API (which doesn't send the field)
+     * still boots — it falls back to the edge-to-edge default.
+     */
+    mobileHeight?: WidgetMobileHeight | null;
     allowedDomains: string[];
     triggerRule: WidgetTriggerRule | null;
   };

package/src/chat-widget/chat-widget-defaults.tsx

@@ -1,6 +0,0 @@
-/**
- * Default values for the chat widget when database / agent config is not set.
- */
-
-/** Default label for the open empty-state "start conversation" CTA. */
-export const DEFAULT_START_CONVERSATION_LABEL = "Start a new conversation";