@dbx-tools/ui-mastra 0.6.219 → 0.6.220

package/README.md

@@ -121,7 +121,9 @@ lock size, `launcher={false}` when every launch comes from
 the conversation pills. With the header enabled those controls move into it and
 the conversation pills remain on their own second row. Replace `icon`, `closeIcon`,
 `newConversationIcon`, `historyIcon`, and `launcher.icon`. Below
-`mobileBreakpoint` the panel becomes a full overlay.
+`mobileBreakpoint` the panel becomes a focus-contained modal overlay with Escape
+dismissal while the covered application is inert. A `storageKey` retains
+horizontal and vertical sizes independently.
 
 ## Render A Drop-In Chat
 

package/index.ts

@@ -3,7 +3,7 @@
 // Hand edits are overwritten on the next watch; this file is read-only.
 
 export const PACKAGE_IDENTIFIER = "@dbx-tools/ui-mastra";
-export const PACKAGE_VERSION = "0.6.219";
+export const PACKAGE_VERSION = "0.6.220";
 export * as reactBubbles from "./src/react/bubbles.tsx";
 export * as reactChatApprovals from "./src/react/chat-approvals.ts";
 export * as reactChatComposer from "./src/react/chat-composer.tsx";
@@ -73,5 +73,5 @@ export type { MastraStreamResponse, MastraMemoryThread, ByIdFetchState } from ".
 export { modelStorageKey, readStoredModel, storeSelectedModel } from "./src/support/model-selection.ts";
 export type { MastraRequestContextInput, MastraRequestContextSource, MastraRequestContextSnapshot } from "./src/support/request-context.ts";
 export { DEFAULT_THREAD_SESSION_KEY } from "./src/support/thread-sessions.ts";
-export type { SessionQueuedSteer, ThreadSession } from "./src/support/thread-sessions.ts";
+export type { SessionQueuedSteer, SessionRun, ThreadSession } from "./src/support/thread-sessions.ts";
 export { THREAD_TAB_SEED_MAX } from "./src/support/thread-tabs.ts";

package/package.json

@@ -31,12 +31,12 @@
     "react-dom": "~19.2.4"
   },
   "dependencies": {
-    "@dbx-tools/shared-core": "0.6.219",
-    "@dbx-tools/shared-genie": "0.6.219",
-    "@dbx-tools/shared-mastra": "0.6.219",
-    "@dbx-tools/shared-model": "0.6.219",
-    "@dbx-tools/ui-appkit": "0.6.219",
-    "@dbx-tools/ui-branding": "0.6.219",
+    "@dbx-tools/shared-core": "0.6.220",
+    "@dbx-tools/shared-genie": "0.6.220",
+    "@dbx-tools/shared-mastra": "0.6.220",
+    "@dbx-tools/shared-model": "0.6.220",
+    "@dbx-tools/ui-appkit": "0.6.220",
+    "@dbx-tools/ui-branding": "0.6.220",
     "@mastra/client-js": "1.50.0",
     "@tanstack/react-table": "^8.21.3",
     "ai": "^5.0.0",
@@ -52,7 +52,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.6.219",
+  "version": "0.6.220",
   "type": "module",
   "exports": {
     "./react": "./src/react/index.ts",

package/src/react/bubbles.tsx

@@ -135,6 +135,7 @@ const EmailApprovalPreview = ({ email }: { email: EmailApprovalInput }) => {
  * {@link ApprovalDecision} to the parent resume handler.
  */
 const ToolApprovalCard = ({
+  messageId,
   toolName,
   toolCallId,
   runId,
@@ -142,6 +143,7 @@ const ToolApprovalCard = ({
   onResolve,
   disabled,
 }: {
+  messageId: string;
   toolName: string;
   toolCallId: string;
   runId?: string;
@@ -158,9 +160,10 @@ const ToolApprovalCard = ({
     setDecision(approved ? "approved" : "denied");
     Promise.resolve(
       approved
-        ? onResolve({ approved: true, toolName, toolCallId, runId, input })
+        ? onResolve({ approved: true, messageId, toolName, toolCallId, runId, input })
         : onResolve({
             approved: false,
+            messageId,
             toolName,
             toolCallId,
             runId,
@@ -428,6 +431,7 @@ export const AssistantBubble = ({
         {pendingApprovals.map((p) => (
           <ToolApprovalCard
             key={p.toolCallId}
+            messageId={message.id}
             toolName={p.toolName}
             toolCallId={p.toolCallId}
             runId={p.runId}

package/src/react/chat-approvals.ts

@@ -3,7 +3,7 @@ import { useCallback } from "react";
 import type { ThreadSessionReader, ThreadSessionUpdater } from "./chat-sessions.ts";
 import type { ApprovalDecision } from "./types.ts";
 import type { MastraPluginClient, MastraStreamResponse } from "../support/mastra-client.ts";
-import { DEFAULT_THREAD_SESSION_KEY } from "../support/thread-sessions.ts";
+import { DEFAULT_THREAD_SESSION_KEY, type ThreadSession } from "../support/thread-sessions.ts";
 
 const logger = log.logger("ui-mastra/chat");
 
@@ -22,6 +22,35 @@ interface UseChatApprovalsOptions {
   updateSession: ThreadSessionUpdater;
 }
 
+/** Resolve one approval against the exact run and assistant message that created it. */
+export function resolveApprovalContinuation(
+  session: ThreadSession,
+  decision: ApprovalDecision,
+):
+  | {
+      assistantId: string;
+      runId: string;
+      requestContext: ThreadSession["runRequestContext"];
+    }
+  | undefined {
+  const runId = decision.runId ?? session.runId;
+  if (!runId) return undefined;
+  const run = session.runs[runId];
+  const assistantId =
+    decision.messageId ??
+    run?.assistantId ??
+    Object.entries(session.pendingApprovalsByMessage).find(([, approvals]) =>
+      approvals.some((approval) => approval.toolCallId === decision.toolCallId),
+    )?.[0] ??
+    session.assistantId;
+  if (!assistantId) return undefined;
+  return {
+    assistantId,
+    runId,
+    requestContext: run?.requestContext,
+  };
+}
+
 /** Resume an approval-gated tool call and remove its pending UI state. */
 export function useChatApprovals({
   activeKey,
@@ -33,22 +62,19 @@ export function useChatApprovals({
 }: UseChatApprovalsOptions) {
   return useCallback(
     async (decision: ApprovalDecision) => {
-      const { runId: decisionRunId, toolCallId, toolName } = decision;
+      const { toolCallId, toolName } = decision;
       const session = getSession(activeKey);
-      const assistantId =
-        Object.entries(session.pendingApprovalsByMessage).find(([, approvals]) =>
-          approvals.some((approval) => approval.toolCallId === toolCallId),
-        )?.[0] ?? session.assistantId;
-      const runId = decisionRunId ?? session.runId;
-      if (!runId || !assistantId) {
+      const continuation = resolveApprovalContinuation(session, decision);
+      if (!continuation) {
         logger.warn("approval missing runId or assistantId, cannot resume", {
           tool: toolName,
           toolCallId,
-          hasRunId: Boolean(runId),
-          hasAssistantId: Boolean(assistantId),
+          hasRunId: Boolean(decision.runId ?? session.runId),
+          hasAssistantId: Boolean(decision.messageId ?? session.assistantId),
         });
         return;
       }
+      const { assistantId, runId, requestContext } = continuation;
 
       updateSession(activeKey, (current) => {
         const existing = current.pendingApprovalsByMessage[assistantId];
@@ -79,7 +105,7 @@ export function useChatApprovals({
               runId,
               toolCallId,
               threadId: streamThreadId,
-              requestContext: session.runRequestContext,
+              requestContext,
               signal,
             })
           : mastraClient.declineToolCallStream(agentId, {
@@ -87,7 +113,7 @@ export function useChatApprovals({
               toolCallId,
               threadId: streamThreadId,
               reason: decision.reason,
-              requestContext: session.runRequestContext,
+              requestContext,
               signal,
             }),
       );

package/src/react/chat-composer.tsx

@@ -394,9 +394,9 @@ export const ChatComposer = ({
                   >
                     <SelectTrigger
                       size="sm"
-                      aria-label="Model"
                       className="h-7 w-auto max-w-[180px] gap-1 truncate border-0 bg-transparent px-2 text-xs shadow-none hover:bg-accent [&_svg]:size-3"
                     >
+                      <span className="sr-only">Model:</span>
                       <SelectValue placeholder={defaultOptionLabel} />
                     </SelectTrigger>
                     <SelectContent>
@@ -430,7 +430,7 @@ export const ChatComposer = ({
                   size="icon-sm"
                   variant="default"
                   disabled={!input.trim() || isLoadingHistory}
-                  aria-label={isRunning ? "Send now (interrupts)" : "Send message"}
+                  aria-label={isRunning ? "Queue message" : "Send message"}
                   className="shrink-0 rounded-full"
                 >
                   <SendIcon className="size-3" />

package/src/react/mastra-assistant.tsx

@@ -15,6 +15,7 @@ import {
   useCallback,
   useContext,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -157,6 +158,15 @@ const panelClosedClasses: Record<MastraAssistantSide, string> = {
   left: "-translate-x-full",
 };
 
+const FOCUSABLE_SELECTOR = [
+  "a[href]",
+  "button:not([disabled])",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])',
+].join(",");
+
 const resizeHandleClasses: Record<MastraAssistantSide, string> = {
   top: "-bottom-1 inset-x-0 h-2 cursor-row-resize",
   right: "-left-1 inset-y-0 w-2 cursor-col-resize",
@@ -167,6 +177,8 @@ const resizeHandleClasses: Record<MastraAssistantSide, string> = {
 type ResizeState = {
   pointer: number;
   size: number;
+  bodyCursor: string;
+  bodyUserSelect: string;
 } | null;
 
 /**
@@ -201,21 +213,27 @@ export function MastraAssistant<TValues extends Record<string, unknown> = Record
   ...rootProps
 }: MastraAssistantProps<TValues>) {
   const rootRef = useRef<HTMLDivElement>(null);
+  const panelRef = useRef<HTMLElement>(null);
+  const previousFocusRef = useRef<HTMLElement | null>(null);
   const [internalOpen, setInternalOpen] = useState(defaultOpen);
-  const isOpen = available && (openProp ?? internalOpen);
+  const requestedOpen = openProp ?? internalOpen;
+  const isOpen = available && requestedOpen;
   const [launchContext, setLaunchContext] = useState<
     MastraRequestContextInput<TValues> | undefined
   >();
   const requestContext = launchContext ?? requestContextProp;
   const resizeOptions = useMemo(() => (resizable === true ? {} : resizable || {}), [resizable]);
   const vertical = sideIsVertical(side);
+  const sizeStorageKey = resizeOptions.storageKey
+    ? `${resizeOptions.storageKey}:${vertical ? "vertical" : "horizontal"}`
+    : undefined;
   const defaultSize = resizeOptions.defaultSize ?? (vertical ? 360 : 432);
-  const [panelSize, setPanelSize] = useState(
-    () => readStoredSize(resizeOptions.storageKey) ?? defaultSize,
-  );
+  const [panelSize, setPanelSize] = useState(() => readStoredSize(sizeStorageKey) ?? defaultSize);
   const [availableSize, setAvailableSize] = useState(0);
   const [isNarrow, setIsNarrow] = useState(false);
   const resizeState = useRef<ResizeState>(null);
+  const sizeConfigRef = useRef(sizeStorageKey);
+  const skipSizePersistenceRef = useRef(false);
 
   const setOpen = useCallback(
     (next: boolean) => {
@@ -232,7 +250,7 @@ export function MastraAssistant<TValues extends Record<string, unknown> = Record
     [setOpen],
   );
   const close = useCallback(() => setOpen(false), [setOpen]);
-  const toggle = useCallback(() => setOpen(!isOpen), [isOpen, setOpen]);
+  const toggle = useCallback(() => setOpen(!requestedOpen), [requestedOpen, setOpen]);
 
   const controller = useMemo<MastraAssistantController<TValues>>(
     () => ({
@@ -268,13 +286,76 @@ export function MastraAssistant<TValues extends Record<string, unknown> = Record
   }, [mobileBreakpoint, vertical]);
 
   useEffect(() => {
-    if (!resizeOptions.storageKey || typeof window === "undefined") return;
+    if (!isNarrow || !isOpen) return;
+    const panel = panelRef.current;
+    if (!panel) return;
+    previousFocusRef.current =
+      document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    const focusFrame = window.requestAnimationFrame(() => panel.focus());
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        close();
+        return;
+      }
+      if (event.key !== "Tab") return;
+      const focusable = [...panel.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)].filter(
+        (element) => !element.hidden && element.getClientRects().length > 0,
+      );
+      if (focusable.length === 0) {
+        event.preventDefault();
+        panel.focus();
+        return;
+      }
+      const first = focusable[0]!;
+      const last = focusable.at(-1)!;
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener("keydown", handleKeyDown);
+    return () => {
+      window.cancelAnimationFrame(focusFrame);
+      document.removeEventListener("keydown", handleKeyDown);
+      const previous = previousFocusRef.current;
+      previousFocusRef.current = null;
+      window.requestAnimationFrame(() => {
+        window.requestAnimationFrame(() => {
+          if (previous?.isConnected) {
+            previous.focus();
+          } else {
+            rootRef.current
+              ?.querySelector<HTMLElement>("[data-mastra-assistant-launcher]")
+              ?.focus();
+          }
+        });
+      });
+    };
+  }, [close, isNarrow, isOpen]);
+
+  useLayoutEffect(() => {
+    if (sizeConfigRef.current === sizeStorageKey) return;
+    sizeConfigRef.current = sizeStorageKey;
+    skipSizePersistenceRef.current = true;
+    setPanelSize(readStoredSize(sizeStorageKey) ?? defaultSize);
+  }, [defaultSize, sizeStorageKey]);
+
+  useEffect(() => {
+    if (!sizeStorageKey || typeof window === "undefined") return;
+    if (skipSizePersistenceRef.current) {
+      skipSizePersistenceRef.current = false;
+      return;
+    }
     try {
-      window.localStorage.setItem(resizeOptions.storageKey, String(panelSize));
+      window.localStorage.setItem(sizeStorageKey, String(panelSize));
     } catch {
       // Size persistence is best-effort; the panel remains usable without storage.
     }
-  }, [panelSize, resizeOptions.storageKey]);
+  }, [panelSize, sizeStorageKey]);
 
   useEffect(() => {
     const move = (event: PointerEvent) => {
@@ -292,17 +373,21 @@ export function MastraAssistant<TValues extends Record<string, unknown> = Record
       );
     };
     const finish = () => {
+      const current = resizeState.current;
+      if (!current) return;
       resizeState.current = null;
-      document.body.style.removeProperty("user-select");
-      document.body.style.removeProperty("cursor");
+      document.body.style.userSelect = current.bodyUserSelect;
+      document.body.style.cursor = current.bodyCursor;
     };
     window.addEventListener("pointermove", move);
     window.addEventListener("pointerup", finish);
     window.addEventListener("pointercancel", finish);
+    window.addEventListener("blur", finish);
     return () => {
       window.removeEventListener("pointermove", move);
       window.removeEventListener("pointerup", finish);
       window.removeEventListener("pointercancel", finish);
+      window.removeEventListener("blur", finish);
       finish();
     };
   }, [availableSize, resizeOptions, side, vertical]);
@@ -314,6 +399,8 @@ export function MastraAssistant<TValues extends Record<string, unknown> = Record
     resizeState.current = {
       pointer: vertical ? event.clientY : event.clientX,
       size: panelSize,
+      bodyCursor: document.body.style.cursor,
+      bodyUserSelect: document.body.style.userSelect,
     };
     document.body.style.userSelect = "none";
     document.body.style.cursor = vertical ? "row-resize" : "col-resize";
@@ -414,9 +501,14 @@ export function MastraAssistant<TValues extends Record<string, unknown> = Record
 
   const panel = (
     <aside
+      key="assistant-panel"
+      ref={panelRef}
+      role={isNarrow ? "dialog" : undefined}
+      aria-modal={isNarrow && isOpen ? true : undefined}
       aria-label={typeof title === "string" ? title : "Assistant"}
       aria-hidden={!isOpen}
       inert={!isOpen ? true : undefined}
+      tabIndex={isNarrow ? -1 : undefined}
       style={panelStyle}
       className={cn(
         "relative z-40 flex min-h-0 min-w-0 flex-col bg-background text-foreground shadow-xl",
@@ -471,6 +563,7 @@ export function MastraAssistant<TValues extends Record<string, unknown> = Record
   const launchButton =
     available && !isOpen && launcherOptions ? (
       <Button
+        data-mastra-assistant-launcher
         type="button"
         size="icon"
         aria-label={launcherOptions.label ?? "Open assistant"}
@@ -486,7 +579,16 @@ export function MastraAssistant<TValues extends Record<string, unknown> = Record
       </Button>
     ) : null;
 
-  const content = <div className={cn("min-h-0 min-w-0 flex-1", contentClassName)}>{children}</div>;
+  const content = (
+    <div
+      key="assistant-content"
+      aria-hidden={isNarrow && isOpen ? true : undefined}
+      inert={isNarrow && isOpen ? true : undefined}
+      className={cn("min-h-0 min-w-0 flex-1", contentClassName)}
+    >
+      {children}
+    </div>
+  );
   const rootDirection = vertical ? "flex-col" : "flex-row";
   const panelFirst = side === "top" || side === "left";
 

package/src/react/mastra-chat.tsx

@@ -477,6 +477,13 @@ export const useMastraChat = <TValues extends Record<string, unknown> = Record<s
         runId,
         runRequestContext: requestContext,
         lastRequestContext: requestContext,
+        runs: {
+          ...session.runs,
+          [runId]: {
+            assistantId,
+            ...(requestContext ? { requestContext } : {}),
+          },
+        },
       }));
       // Capture this run's thread + model at send time and pass them per
       // call, so a run keeps its own routing even if the user switches

package/src/react/types.ts

@@ -352,6 +352,8 @@ export type ApprovalDecision =
       approved: true;
       toolName: string;
       toolCallId: string;
+      /** Assistant UI message that owns the approval card. */
+      messageId?: string;
       /**
        * Mastra run id required to resume the suspended workflow. Native
        * suspended-run discovery restores it for persisted approvals.
@@ -363,6 +365,8 @@ export type ApprovalDecision =
       approved: false;
       toolName: string;
       toolCallId: string;
+      /** Assistant UI message that owns the approval card. */
+      messageId?: string;
       runId?: string;
       input: unknown;
       reason: string;

package/src/support/thread-sessions.ts

@@ -9,6 +9,12 @@ export type SessionQueuedSteer = QueuedSteer & {
   requestContext?: MastraRequestContextSnapshot;
 };
 
+/** UI target and immutable application context captured for one Mastra run. */
+export type SessionRun = {
+  assistantId: string;
+  requestContext?: MastraRequestContextSnapshot;
+};
+
 /** Session-scoped transcript + stream state for one conversation thread. */
 export type ThreadSession = {
   messages: UIMessage[];
@@ -20,6 +26,8 @@ export type ThreadSession = {
   runToken: number;
   assistantId: string | null;
   runId: string | null;
+  /** Live runs retained by id so older approval cards resume their own context. */
+  runs: Record<string, SessionRun>;
   historyLoaded: boolean;
   hasMoreHistory: boolean;
   historyPage: number;
@@ -45,6 +53,7 @@ export function createThreadSession(): ThreadSession {
     runToken: 0,
     assistantId: null,
     runId: null,
+    runs: {},
     historyLoaded: false,
     hasMoreHistory: false,
     historyPage: 0,