@alxxsck/ai-assistant 2.26.0 → 3.1.0

package/README.md

@@ -241,13 +241,18 @@ attachments: {
 
 ## Host handlers
 
-`handlers` is optional and is the only command integration surface. Use it when a
+`handlers` is optional and is the only command execution surface. Use it when a
 backend command must navigate the product, open a product modal, or customize an
-element highlight:
+element highlight. `uiActionPolicies` separately controls trusted presentation
+behavior:
 
 ```ts
 const widget = new ChatWidgetInstance({
   customerInteractionSession: session,
+  uiActionPolicies: {
+    account_page: { mobileDisposition: "collapseOnSuccess" },
+    featured_game_page: { mobileDisposition: "immersive" },
+  },
   handlers: {
     openPage: ({ route }) => productRouter.push(route),
     openModal: ({ modalName }) => productModals.open(modalName),
@@ -267,6 +272,19 @@ const widget = new ChatWidgetInstance({
 });
 ```
 
+`uiActionPolicies` is trusted host configuration keyed by canonical action
+code. `keep` leaves the mobile chat open; `collapseOnSuccess` and `immersive`
+collapse only the chat surface after the handler resolves. A
+`mobileDisposition` value in command payload is ignored. Unregistered page and
+modal actions default to `collapseOnSuccess`.
+
+Navigation and modal handlers should resolve only after the destination is
+ready to own focus, or reject on failure. A mobile handoff never returns focus
+to Lola's launcher; it preserves host focus while manual collapse still returns
+focus to the launcher. `immersive` currently shares the safe surface-collapse
+semantics of `collapseOnSuccess`; hiding all assistant chrome is reserved until
+the host exposes an explicit destination-exit lifecycle.
+
 `reportActivation()` is the authoritative signal that the product accepted the
 user activation. Call it synchronously from the product-owned action handler,
 before navigation can unmount the widget. It records the activation, not the