@runtypelabs/persona 3.1.0 → 3.2.0

package/README.md

@@ -624,13 +624,15 @@ initAgentWidget({
 
 The `onStateLoaded` hook is called after state is loaded from the storage adapter, but before the widget initializes. Use this to transform or inject messages based on external state (e.g., navigation flags, checkout returns).
 
+Returning `{ state, open: true }` also tells the widget to open the panel after initialization — useful when injecting a post-navigation message that the user should immediately see.
+
 ```ts
+// Plain state transform
 initAgentWidget({
   target: 'body',
   config: {
     storageAdapter: createLocalStorageAdapter('my-chat'),
     onStateLoaded: (state) => {
-      // Check for pending navigation message
       const navMessage = consumeNavigationFlag();
       if (navMessage) {
         return {
@@ -647,10 +649,36 @@ initAgentWidget({
     }
   }
 });
+
+// Return { state, open: true } to also open the panel
+initAgentWidget({
+  target: 'body',
+  config: {
+    storageAdapter: createLocalStorageAdapter('my-chat'),
+    onStateLoaded: (state) => {
+      const navMessage = consumeNavigationFlag();
+      if (navMessage) {
+        return {
+          state: {
+            ...state,
+            messages: [...(state.messages || []), {
+              id: `nav-${Date.now()}`,
+              role: 'assistant',
+              content: navMessage,
+              createdAt: new Date().toISOString()
+            }]
+          },
+          open: true
+        };
+      }
+      return state;
+    }
+  }
+});
 ```
 
 **Use cases:**
-- Inject messages after page navigation (e.g., "Here are our products!")
+- Inject messages after page navigation (e.g., "Here are our products!") and open the panel
 - Add confirmation messages after checkout/payment returns
 - Transform or filter loaded messages
 - Inject system messages based on external state
@@ -1717,6 +1745,7 @@ Controls the floating launcher button and panel.
 | `clearChat` | `AgentWidgetClearChatConfig?` | Clear chat button configuration (enabled, placement, icon, styling). |
 | `border` | `string?` | Border style for the launcher button. Default: `'1px solid #e5e7eb'`. |
 | `shadow` | `string?` | Box shadow for the launcher button. |
+| `collapsedMaxWidth` | `string?` | CSS `max-width` for the floating launcher pill when the panel is closed (title/subtitle truncate with ellipsis; full text in `title` tooltip). Does not affect the open panel (`width`). |
 
 In docked mode, `position`, `fullHeight`, and `sidebarMode` are ignored because the widget fills the dock slot created around the target container.
 
@@ -2019,7 +2048,7 @@ config: {
 | `initialMessages` | `AgentWidgetMessage[]` | Seed the conversation transcript with initial messages. |
 | `persistState` | `boolean \| AgentWidgetPersistStateConfig` | Persist widget state across page navigations. `true` uses defaults (sessionStorage). |
 | `storageAdapter` | `AgentWidgetStorageAdapter` | Custom storage adapter with `load()`, `save(state)`, and `clear()` methods. |
-| `onStateLoaded` | `(state: AgentWidgetStoredState) => AgentWidgetStoredState` | Transform state after loading from storage but before widget initialization. |
+| `onStateLoaded` | `(state: AgentWidgetStoredState) => AgentWidgetStoredState \| { state: AgentWidgetStoredState; open?: boolean }` | Transform state after loading from storage but before widget initialization. Return `{ state, open: true }` to also open the panel. |
 | `clearChatHistoryStorageKey` | `string` | Additional localStorage key to clear on chat reset. The widget clears `"persona-chat-history"` by default. |
 
 **`persistState`** — `AgentWidgetPersistStateConfig`