@runtypelabs/persona 3.0.0 → 3.1.1

package/dist/index.d.cts

@@ -2797,11 +2797,15 @@ type AgentWidgetConfig = {
      *
      * This hook runs synchronously and must return the (potentially modified) state.
      *
+     * Returning `{ state, open: true }` also signals that the widget panel should
+     * open after initialization — useful when injecting a post-navigation message
+     * that the user should immediately see.
+     *
      * @example
      * ```typescript
+     * // Plain state transform (existing form, still supported)
      * config: {
      *   onStateLoaded: (state) => {
-     *     // Check for pending navigation message
      *     const navMessage = consumeNavigationFlag();
      *     if (navMessage) {
      *       return {
@@ -2818,8 +2822,36 @@ type AgentWidgetConfig = {
      *   }
      * }
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Return { state, open: true } to also open the panel
+     * config: {
+     *   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;
+     *   }
+     * }
+     * ```
      */
-    onStateLoaded?: (state: AgentWidgetStoredState) => AgentWidgetStoredState;
+    onStateLoaded?: (state: AgentWidgetStoredState) => AgentWidgetStoredState | {
+        state: AgentWidgetStoredState;
+        open?: boolean;
+    };
     /**
      * Registry of custom components that can be rendered from JSON directives.
      * Components are registered by name and can be invoked via JSON responses

package/dist/index.d.ts

@@ -2797,11 +2797,15 @@ type AgentWidgetConfig = {
      *
      * This hook runs synchronously and must return the (potentially modified) state.
      *
+     * Returning `{ state, open: true }` also signals that the widget panel should
+     * open after initialization — useful when injecting a post-navigation message
+     * that the user should immediately see.
+     *
      * @example
      * ```typescript
+     * // Plain state transform (existing form, still supported)
      * config: {
      *   onStateLoaded: (state) => {
-     *     // Check for pending navigation message
      *     const navMessage = consumeNavigationFlag();
      *     if (navMessage) {
      *       return {
@@ -2818,8 +2822,36 @@ type AgentWidgetConfig = {
      *   }
      * }
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Return { state, open: true } to also open the panel
+     * config: {
+     *   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;
+     *   }
+     * }
+     * ```
      */
-    onStateLoaded?: (state: AgentWidgetStoredState) => AgentWidgetStoredState;
+    onStateLoaded?: (state: AgentWidgetStoredState) => AgentWidgetStoredState | {
+        state: AgentWidgetStoredState;
+        open?: boolean;
+    };
     /**
      * Registry of custom components that can be rendered from JSON directives.
      * Components are registered by name and can be invoked via JSON responses