@runtypelabs/persona 3.0.0 → 3.1.1

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
@@ -935,7 +963,7 @@ const dropdown = createDropdownMenu({
   onSelect: (id) => { /* handle */ },
   anchor: myButton,
   position: 'bottom-right',
-  portal: document.querySelector('#persona-root')!,
+  portal: document.querySelector('[data-persona-root]')!,
 });
 // No need to append — portal mode appends automatically
 ```
@@ -2019,7 +2047,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`
@@ -2322,6 +2350,6 @@ Add `RUNTYPE_API_KEY` to your environment. The proxy constructs the Runtype payl
 ### Development notes
 
 - The widget streams results using SSE and mirrors the backend `flow_complete`/`step_chunk` events.
-- Tailwind-esc classes are prefixed with `tvw-` and scoped to `#persona-root`, so they won't collide with the host page.
+- Tailwind-esc classes are prefixed with `tvw-` and scoped to `[data-persona-root]`, so they won't collide with the host page.
 - Run `pnpm dev` from the repository root to boot the example proxy (`examples/proxy`) and the vanilla demo (`examples/embedded-app`).
 - The proxy prefers port `43111` but automatically selects the next free port if needed.