@usereq/widget 0.2.15 → 0.2.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usereq/widget",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -76,7 +76,7 @@
   },
   "dependencies": {
     "@streamdown/mermaid": "^1.0.2",
-    "@usereq/ui": "^0.2.21",
+    "@usereq/ui": "^0.2.22",
     "lucide-react": "^0.553.0",
     "motion": "^12.23.24",
     "react": "^19.2.0",

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

@@ -223,8 +223,9 @@ export class AgentWidgetElement extends HTMLElement {
     const placement = this.getResolvedPlacement();
     const variant = this.getResolvedVariant();
     const preset = this.getResolvedPreset();
-    const autoStartEnabled =
-      this.sessionConfig?.widgetConfig.widgetBehavior?.autoStart === true;
+    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);
@@ -267,6 +268,7 @@ export class AgentWidgetElement extends HTMLElement {
         spotlights: this.getSpotlights(),
         ctaLink: this.getCtaLink(),
         open: this.open,
+        alwaysOpen,
         status: this.status,
         messages: this.messages,
         errorMessage: this.errorMessage,
@@ -333,6 +335,13 @@ export class AgentWidgetElement extends HTMLElement {
         this.welcomeMessage = state.session.widgetConfig.welcomeMessage;
         this.status = "ready";
         this.bootstrapPhase = "ready";
+        // 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.
+        const behavior = state.session.widgetConfig.widgetBehavior;
+        if (behavior?.alwaysOpen || behavior?.defaultOpen) {
+          this.open = true;
+        }
         this.renderWidget();
       } catch (error) {
         if (runVersion !== this.bootstrapVersion) {

package/src/renderer/widget-runtime.tsx

@@ -50,6 +50,12 @@ export type WidgetRuntimeProps = {
   spotlights: string[];
   ctaLink?: string | null;
   open: boolean;
+  /**
+   * When true, the embedded panel is pinned open and the launcher is hidden.
+   * Mirrors `WidgetBehavior.alwaysOpen` and short-circuits the trigger-rule
+   * gate (a pinned widget has no "open" event to trigger on).
+   */
+  alwaysOpen?: boolean;
   status: WidgetRuntimeStatus;
   messages: WidgetMessage[];
   errorMessage: string | null;
@@ -88,6 +94,7 @@ export function WidgetRuntime({
   spotlights,
   ctaLink,
   open,
+  alwaysOpen = false,
   status,
   messages,
   errorMessage,
@@ -101,7 +108,10 @@ export function WidgetRuntime({
   portalContainer,
   onLauncherClick,
 }: WidgetRuntimeProps) {
-  const { ready } = useWidgetTriggerGate(triggerRule);
+  // Always-open widgets bypass the trigger-rule gate — the panel renders
+  // unconditionally, so any "open on X seconds / on scroll / on click"
+  // configuration would be meaningless. Pass `null` to short-circuit it.
+  const { ready } = useWidgetTriggerGate(alwaysOpen ? null : triggerRule);
   const { horizontal, vertical } = splitWidgetPlacement(placement);
 
   const { panelMessages, confirmation } = React.useMemo(
@@ -210,6 +220,7 @@ export function WidgetRuntime({
               status={RUNTIME_TO_PANEL_STATUS[status]}
               errorMessage={errorMessage}
               open={open}
+              alwaysOpen={alwaysOpen}
               onOpenChange={onOpenChange}
               onSendMessage={handleSend}
               onStopConversation={

package/src/shared/widget-config.ts

@@ -30,11 +30,21 @@ export type WidgetTriggerRule =
   | { triggerRuleType: "element_displayed"; elementDisplayed: string };
 
 export type WidgetBehavior = {
+  /** Eagerly spin up the server-side conversation when the widget mounts. */
   autoStart: boolean;
+  /** Open the panel as soon as the widget mounts. The launcher stays visible
+   *  and the visitor can still close the panel from there. */
+  defaultOpen: boolean;
+  /** Pin the panel open: launcher is hidden, the close affordance is hidden,
+   *  and the panel is rendered inline as the only thing this widget shows.
+   *  Useful for full-page or dedicated-chat embeds. Implies `defaultOpen`. */
+  alwaysOpen: boolean;
 };
 
 export const DEFAULT_WIDGET_BEHAVIOR: WidgetBehavior = {
   autoStart: false,
+  defaultOpen: false,
+  alwaysOpen: false,
 };
 
 export function normalizeWidgetBehavior(
@@ -42,6 +52,8 @@ export function normalizeWidgetBehavior(
 ): WidgetBehavior {
   return {
     autoStart: Boolean(behavior?.autoStart),
+    defaultOpen: Boolean(behavior?.defaultOpen),
+    alwaysOpen: Boolean(behavior?.alwaysOpen),
   };
 }