@dbx-tools/ui-mastra 0.6.0 → 0.6.2

package/README.md

@@ -27,6 +27,9 @@ Key features:
   the server plugin.
 - Conversation sidebar with new, select, rename, delete, active-thread, and
   background-streaming states, plus a per-row cancel for a running thread.
+- Placeable conversation UI: dock the list left or right, switch to an
+  editor-style tab strip across the top, turn it off, or let `auto` pick between
+  a side panel and tabs from the chat's own width.
 - Concurrent threads: run several conversations at once, switch between them
   while each keeps streaming, and cancel any one independently (per-thread abort
   - routing, no shared client state).
@@ -80,7 +83,7 @@ export function App() {
     <MastraChat
       agentId="analyst"
       showModelPicker
-      enableThreads
+      threadPlacement="auto"
       enableExport
       enableFeedback
       className="h-dvh"
@@ -100,11 +103,48 @@ Useful options:
 - `showModelPicker` fetches `/models` and sends `X-Mastra-Model` overrides.
 - `suggestions` overrides Genie starter questions; omit it to auto-fetch
   `/suggestions`, or pass `[]` to hide suggestions.
-- `enableThreads` turns on persisted conversation selection and the sidebar.
+- `threadPlacement` chooses where conversation management renders, or turns it
+  off. See [Place The Conversation List](#place-the-conversation-list).
+- `enableThreads: false` is the older shorthand for
+  `threadPlacement: "disabled"`.
 - `enableExport` adds whole-conversation and per-message export affordances.
 - `enableFeedback` enables thumbs/comment controls when the server reports
   MLflow feedback is available and a turn produced a trace id.
 
+## Place The Conversation List
+
+Conversation management is on by default. Where it lives is one option:
+
+```tsx
+<MastraChat threadPlacement="top" />
+```
+
+| `threadPlacement` | Layout                                                                     |
+| ----------------- | -------------------------------------------------------------------------- |
+| `auto` (default)  | `left` while the chat is wide, `top` once it is too narrow for a panel     |
+| `left` / `right`  | List docked to that edge, collapsing to an overlay drawer on a narrow chat |
+| `top`             | Tab strip of open conversations, with a history menu for the rest          |
+| `disabled`        | No thread UI - the classic single-thread chat on the session cookie        |
+
+The docked placements render the sidebar as an inline column with a persisted
+show/hide toggle. Below 768px of chat width the panel becomes an overlay drawer
+on the same edge, so the transcript never loses room; the drawer is
+session-scoped and starts closed, and closes itself after a selection.
+
+The `top` placement is the editor-tab model: each open conversation is a tab with
+its title, a spinner while it streams in the background, and a close affordance
+that only takes the tab off the strip (the conversation stays in history). A `+`
+starts a fresh conversation and a history button opens the full list - the same
+sidebar, framed as a menu - so rename, delete, and cancel still work on anything
+not currently tabbed. Closing the active tab moves to a neighbouring one, or
+starts a fresh conversation when it was the last tab open. The open set is
+session state; the strip reseeds from the most recent conversations on the next
+load.
+
+`auto` measures the chat's own element rather than the viewport, so a chat
+embedded in a split view or side panel switches to tabs on the space it actually
+has instead of waiting for the window to shrink.
+
 ## Use The Headless Driver
 
 ```tsx
@@ -114,7 +154,7 @@ export function CustomChat() {
   const chat = useMastraChat({
     agentId: "analyst",
     showModelPicker: true,
-    enableThreads: true,
+    threadPlacement: "left",
   });
 
   return <ChatView {...chat} className="h-full" />;
@@ -233,11 +273,19 @@ touching `navigator.clipboard` or `URL.createObjectURL` again.
   `useMastraDefaultModel`, `useMastraSuggestions`, `useMastraThreads`,
   `useChartFetch`, `useStatementFetch` - route/config hooks for controlled
   clients.
-- `ThreadSidebar` - controlled conversation list.
+- `ThreadSidebar` - controlled conversation list, dockable to either edge.
+- `ThreadTabs` - conversation tab strip plus history menu for the `top`
+  placement; reuses `ThreadSidebar` for the menu itself.
 - `ExportMenu` - shared export format menu.
+- `src/support/thread-tabs.ts` - pure open-tab bookkeeping (`syncThreadTabs`,
+  `closeThreadTab`, `nextActiveThreadTab`) so the strip's state is testable
+  without a DOM.
+- `src/support/thread-labels.ts` - `threadTitle` / `relativeTime`, shared by
+  the sidebar and the tab strip so a row and a tab never disagree about how an
+  untitled or freshly-updated conversation reads.
 - Types - `ChatViewProps`, `MastraChatProps`, `UseMastraChatOptions`,
-  `ThreadSummary`, `ToolEvent`, `ToolProgress`, `PendingApproval`,
-  `FeedbackSubmission`, and related UI contract types.
+  `ThreadPlacement`, `ThreadSummary`, `ToolEvent`, `ToolProgress`,
+  `PendingApproval`, `FeedbackSubmission`, and related UI contract types.
 
 Server-side routes and event production live in
 [`@dbx-tools/appkit-mastra`](../../node/appkit-mastra). Browser-safe route,

package/index.ts

@@ -13,6 +13,7 @@ export * as reactMastraChat from "./src/react/mastra-chat.tsx";
 export * as reactSuggestionPills from "./src/react/suggestion-pills.tsx";
 export * as reactSuggestions from "./src/react/suggestions.ts";
 export * as reactThreadSidebar from "./src/react/thread-sidebar.tsx";
+export * as reactThreadTabs from "./src/react/thread-tabs.tsx";
 export * as reactToolPill from "./src/react/tool-pill.tsx";
 export * as reactTypes from "./src/react/types.ts";
 export * as supportChartOption from "./src/support/chart-option.ts";
@@ -22,7 +23,9 @@ export * as supportExport from "./src/support/export.ts";
 export * as supportMastraClient from "./src/support/mastra-client.ts";
 export * as supportMastraStream from "./src/support/mastra-stream.ts";
 export * as supportShikiPlugin from "./src/support/shiki-plugin.ts";
+export * as supportThreadLabels from "./src/support/thread-labels.ts";
 export * as supportThreadSessions from "./src/support/thread-sessions.ts";
+export * as supportThreadTabs from "./src/support/thread-tabs.ts";
 export { AssistantBubble, UserBubble } from "./src/react/bubbles.tsx";
 export { ChatView } from "./src/react/chat-view.tsx";
 export { colorizeDelta, renderDataCell, humanizeLabel, TABLE_WRAPPER_CLASSES, DataGrid } from "./src/react/data-grid.tsx";
@@ -38,8 +41,10 @@ export type { SuggestionPillsProps } from "./src/react/suggestion-pills.tsx";
 export { dedupeSuggestions, collectSuggestions } from "./src/react/suggestions.ts";
 export { ThreadSidebar } from "./src/react/thread-sidebar.tsx";
 export type { ThreadSidebarProps } from "./src/react/thread-sidebar.tsx";
+export { ThreadTabs } from "./src/react/thread-tabs.tsx";
+export type { ThreadTabsProps } from "./src/react/thread-tabs.tsx";
 export { humanizeToolName, ToolSessionPill } from "./src/react/tool-pill.tsx";
-export type { ChatStatus, ToolEvent, ToolProgress, ChatModelOption, QueuedSteer, FeedbackValue, FeedbackSubmission, MessageFeedback, ThreadSummary, ChatViewProps, ApprovalDecision, PendingApproval } from "./src/react/types.ts";
+export type { ChatStatus, ToolEvent, ToolProgress, ChatModelOption, QueuedSteer, FeedbackValue, FeedbackSubmission, MessageFeedback, ThreadSummary, ThreadPlacement, ChatViewProps, ApprovalDecision, PendingApproval } from "./src/react/types.ts";
 export { normalizeChartOption } from "./src/support/chart-option.ts";
 export { copyText } from "./src/support/clipboard.ts";
 export { downloadFile } from "./src/support/download.ts";
@@ -50,5 +55,7 @@ export type { ByIdFetchState } from "./src/support/mastra-client.ts";
 export { processMastraStream, asMastraStreamResponse } from "./src/support/mastra-stream.ts";
 export type { MastraStreamChunk, MastraStreamResponse } from "./src/support/mastra-stream.ts";
 export { highlightToHtml, createShikiPlugin } from "./src/support/shiki-plugin.ts";
+export { threadTitle, relativeTime } from "./src/support/thread-labels.ts";
 export { DEFAULT_THREAD_SESSION_KEY, createThreadSession, isSessionRunning, enqueueSteer, removeSteer, reorderSteers, terminateRunningToolEvents, sessionKey } from "./src/support/thread-sessions.ts";
 export type { ThreadSession } from "./src/support/thread-sessions.ts";
+export { THREAD_TAB_SEED_MAX, syncThreadTabs, closeThreadTab, nextActiveThreadTab } from "./src/support/thread-tabs.ts";

package/package.json

@@ -25,18 +25,18 @@
     "shiki": "^3.0.0",
     "sql-formatter": "^15.6.9",
     "streamdown": "^2.5.0",
-    "@dbx-tools/shared-core": "0.6.0",
-    "@dbx-tools/shared-mastra": "0.6.0",
-    "@dbx-tools/ui-branding": "0.6.0",
-    "@dbx-tools/ui-appkit": "0.6.0",
-    "@dbx-tools/shared-genie": "0.6.0",
-    "@dbx-tools/shared-model": "0.6.0"
+    "@dbx-tools/shared-core": "0.6.2",
+    "@dbx-tools/shared-genie": "0.6.2",
+    "@dbx-tools/shared-model": "0.6.2",
+    "@dbx-tools/ui-appkit": "0.6.2",
+    "@dbx-tools/shared-mastra": "0.6.2",
+    "@dbx-tools/ui-branding": "0.6.2"
   },
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.6.0",
+  "version": "0.6.2",
   "type": "module",
   "exports": {
     "./react": "./src/react/index.ts",

package/src/react/chat-view.tsx

@@ -38,6 +38,7 @@ import {
   GripVerticalIcon,
   MessageSquareIcon,
   PanelLeftIcon,
+  PanelRightIcon,
   RefreshCwIcon,
   SendHorizontalIcon,
   SendIcon,
@@ -51,7 +52,9 @@ import { AssistantBubble, UserBubble } from "./bubbles.tsx";
 import { ExportMenu } from "./export-menu.tsx";
 import { SuggestionPills } from "./suggestion-pills.tsx";
 import { ThreadSidebar, type ThreadSidebarProps } from "./thread-sidebar.tsx";
+import { ThreadTabs } from "./thread-tabs.tsx";
 import type { ChatViewProps } from "./types.ts";
+import { closeThreadTab, nextActiveThreadTab, syncThreadTabs } from "../support/thread-tabs.ts";
 
 // Controlled, presentational chat shell: the scroll container, header
 // (model picker + clear), empty state, transcript of message bubbles,
@@ -74,28 +77,41 @@ const TOP_LOAD_MORE_THRESHOLD_PX = 120;
  */
 const DEFAULT_MODEL_VALUE = "__default__";
 
-/** Tailwind's `md` breakpoint (px). Below this the sidebar becomes a drawer. */
-const MOBILE_BREAKPOINT_PX = 768;
+/**
+ * Width (px) below which the chat is too narrow to give up a column to a
+ * docked conversation list. Matches Tailwind's `md` breakpoint. Under it, a
+ * `left` / `right` placement collapses to an overlay drawer and `auto`
+ * switches to the `top` tab strip.
+ */
+const SIDE_PANEL_MIN_WIDTH_PX = 768;
 
 /**
- * `true` on a phone-width viewport (< {@link MOBILE_BREAKPOINT_PX}). Tracks
- * `matchMedia` so the layout switches live on resize/rotate. SSR-safe: defaults
- * to `false` (desktop) when `window` is unavailable.
+ * `true` while the element behind `ref` is narrower than
+ * {@link SIDE_PANEL_MIN_WIDTH_PX}. Measured with a `ResizeObserver` on the
+ * chat itself rather than `matchMedia` on the viewport, so a chat embedded in
+ * a panel or split view reacts to the space it actually has - a wide window
+ * with a 400px chat column is narrow as far as the layout is concerned.
+ * Falls back to the viewport width until the first measurement lands, and is
+ * SSR-safe (assumes wide when `window` is unavailable).
  */
-const useIsMobile = (): boolean => {
-  const query = `(max-width: ${MOBILE_BREAKPOINT_PX - 1}px)`;
-  const [isMobile, setIsMobile] = useState(() =>
-    typeof window === "undefined" ? false : window.matchMedia(query).matches,
+const useIsNarrow = (ref: React.RefObject<HTMLElement | null>): boolean => {
+  const [isNarrow, setIsNarrow] = useState(() =>
+    typeof window === "undefined" ? false : window.innerWidth < SIDE_PANEL_MIN_WIDTH_PX,
   );
   useEffect(() => {
-    if (typeof window === "undefined") return;
-    const mql = window.matchMedia(query);
-    const onChange = () => setIsMobile(mql.matches);
-    onChange();
-    mql.addEventListener("change", onChange);
-    return () => mql.removeEventListener("change", onChange);
-  }, [query]);
-  return isMobile;
+    const el = ref.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver((entries) => {
+      const width = entries[0]?.contentRect.width ?? el.clientWidth;
+      // A zero width means the chat is detached or hidden (a closed tab
+      // panel); keep the last real measurement rather than flipping layout
+      // behind the user's back.
+      if (width > 0) setIsNarrow(width < SIDE_PANEL_MIN_WIDTH_PX);
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [ref]);
+  return isNarrow;
 };
 
 export const ChatView = ({
@@ -124,6 +140,7 @@ export const ChatView = ({
   pendingApprovalsByMessage = {},
   onClear,
   threads,
+  threadPlacement = "auto",
   activeThreadId,
   streamingThreadIds = [],
   isLoadingThreads = false,
@@ -154,6 +171,9 @@ export const ChatView = ({
   // only drives styling and lags a render behind the pointerdown, which on
   // touch dropped the first moves and made the drag feel dead.
   const draggingIdRef = useRef<string | null>(null);
+  // Root layout element, measured to decide whether the chat has room for a
+  // docked conversation list (see `useIsNarrow`).
+  const rootRef = useRef<HTMLDivElement>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
   const contentRef = useRef<HTMLDivElement>(null);
   // Composer textarea, auto-grown with its content up to the CSS `max-h`.
@@ -396,65 +416,97 @@ export const ChatView = ({
   );
   const showClear = Boolean(onClear);
   const showExport = Boolean(onExportConversation);
-  // The conversation sidebar turns on once the host wires both the
-  // thread list and a selection handler. A header toggle lets the user
-  // show/hide it on demand. Open state is controlled when the caller
-  // supplies `sidebarOpen` + `onToggleSidebar` (the driver does this and
-  // persists the choice); otherwise the view manages a session-only
-  // open flag. Defaults to open.
-  const showSidebar = Boolean(threads && onSelectThread);
+  // Conversation management turns on once the host wires both the thread list
+  // and a selection handler, and the placement isn't `disabled`. Where it
+  // renders is `threadPlacement`, resolved below.
+  const showThreads = Boolean(threads && onSelectThread) && threadPlacement !== "disabled";
+  // Is the chat itself too narrow for a docked list? Measured on the root
+  // element, so an embedded/split-pane chat decides on its own width.
+  const isNarrow = useIsNarrow(rootRef);
+  // `auto` picks the layout for the space available: a left panel while the
+  // chat is wide, the tab strip once it is too narrow to spare a column.
+  // Every other value is honoured verbatim.
+  const placement = threadPlacement === "auto" ? (isNarrow ? "top" : "left") : threadPlacement;
+  const tabbedThreads = showThreads && placement === "top";
+  // A docked list. Narrow chats render it as an overlay drawer on the same
+  // edge instead of an inline column, so the transcript keeps its width.
+  const dockedSide = placement === "right" ? "right" : "left";
+  const dockedThreads = showThreads && (placement === "left" || placement === "right");
+  // Docked-panel open state, controlled when the caller supplies
+  // `sidebarOpen` + `onToggleSidebar` (the driver does this and persists the
+  // choice); otherwise the view manages a session-only flag. Defaults to open.
   const [internalSidebarOpen, setInternalSidebarOpen] = useState(true);
-  // Desktop inline-sidebar open state (persisted by the driver when it
-  // supplies `sidebarOpen`/`onToggleSidebar`, else a session-only flag).
-  const desktopSidebarOpen = sidebarOpenProp ?? internalSidebarOpen;
-  const toggleDesktopSidebar = () => {
+  const inlineSidebarOpen = sidebarOpenProp ?? internalSidebarOpen;
+  const toggleInlineSidebar = () => {
     if (onToggleSidebar) onToggleSidebar();
     else setInternalSidebarOpen((open) => !open);
   };
-  // Are we on a phone-width viewport (< md / 768px)? Drives whether the
-  // sidebar renders inline (desktop) or as an overlay drawer (mobile), and
-  // which open-state the header toggle flips.
-  const isMobile = useIsMobile();
-  // Mobile drawer is a SESSION-only, default-closed state so a persisted
-  // "open" desktop preference never auto-opens the drawer over the chat on a
-  // phone. Reset closed whenever we drop back to a mobile viewport.
-  const [mobileDrawerOpen, setMobileDrawerOpen] = useState(false);
+  // The overlay drawer is SESSION-only and default-closed so a persisted
+  // "open" preference never auto-opens a drawer over a narrow chat. Reset
+  // closed whenever the chat widens back out to an inline panel.
+  const [drawerOpen, setDrawerOpen] = useState(false);
   useEffect(() => {
-    if (!isMobile) setMobileDrawerOpen(false);
-  }, [isMobile]);
-  // Unified state/handlers the render + header use, resolved by viewport.
-  const sidebarOpen = isMobile ? mobileDrawerOpen : desktopSidebarOpen;
+    if (!isNarrow) setDrawerOpen(false);
+  }, [isNarrow]);
+  // Unified state/handlers the render + header use, resolved by width.
+  const sidebarOpen = isNarrow ? drawerOpen : inlineSidebarOpen;
   const toggleSidebar = () => {
-    if (isMobile) setMobileDrawerOpen((open) => !open);
-    else toggleDesktopSidebar();
+    if (isNarrow) setDrawerOpen((open) => !open);
+    else toggleInlineSidebar();
   };
   // The top bar carries only the sidebar toggle; the model picker, export, and
   // clear controls live in a toolbar row below the composer, closer to where
-  // the user is typing. The toggle is a mobile hamburger, or a desktop "show"
-  // affordance while the inline sidebar is collapsed - so the bar renders only
-  // when that toggle would actually be visible (an open desktop sidebar has its
-  // own hide button, leaving nothing for the bar to hold).
-  const showSidebarToggle = showSidebar && (isMobile || !desktopSidebarOpen);
+  // the user is typing. The toggle is a narrow-layout hamburger, or a "show"
+  // affordance while the inline panel is collapsed - so the bar renders only
+  // when that toggle would actually be visible (an open inline panel has its
+  // own hide button, leaving nothing for the bar to hold, and the tab strip
+  // needs no toggle at all).
+  const showSidebarToggle = dockedThreads && (isNarrow || !inlineSidebarOpen);
   const showHeader = showSidebarToggle;
   const showComposerToolbar = showModelDisplay || showExport || showClear;
+  // Collapse icon points at the edge the panel lives on, matching the hide
+  // button inside the panel itself.
+  const SidebarToggleIcon = dockedSide === "right" ? PanelRightIcon : PanelLeftIcon;
 
-  // Props shared by the mobile drawer and the desktop inline sidebar - the two
-  // render the SAME `ThreadSidebar`, differing only in framing (overlay vs.
-  // inline) and, on mobile, closing the drawer after select / new. Building
-  // the prop bag once keeps the two call sites from drifting.
-  const sidebarProps: ThreadSidebarProps = {
+  // The conversation list itself, shared by all three thread surfaces - the
+  // overlay drawer, the inline panel, and the tab strip's history menu all
+  // render the SAME `ThreadSidebar`, differing only in framing (and, for the
+  // transient ones, closing themselves after select / new). Building the bag
+  // once keeps the call sites from drifting; framing props (`onHide`, `side`,
+  // `className`) are added per site.
+  const threadListProps: Omit<ThreadSidebarProps, "onHide" | "side" | "className"> = {
     threads: threads ?? [],
     ...(activeThreadId ? { activeThreadId } : {}),
     streamingThreadIds,
     isLoading: isLoadingThreads,
     onSelect: (id) => onSelectThread?.(id),
-    onHide: toggleSidebar,
     ...(onNewThread ? { onNew: onNewThread } : {}),
     ...(onDeleteThread ? { onDelete: onDeleteThread } : {}),
     ...(onRenameThread ? { onRename: onRenameThread } : {}),
     ...(onCancelThread ? { onCancel: onCancelThread } : {}),
   };
 
+  // Which conversations are open as tabs in the `top` placement (session
+  // state; the strip reseeds from the newest conversations on the next load).
+  // The sync keeps the list in step with the thread list and the selection,
+  // and returns the same array when nothing changed so this effect settles.
+  const [openTabIds, setOpenTabIds] = useState<string[]>([]);
+  useEffect(() => {
+    if (!tabbedThreads) return;
+    setOpenTabIds((prev) => syncThreadTabs(prev, threads ?? [], activeThreadId));
+  }, [tabbedThreads, threads, activeThreadId]);
+
+  // Close a tab. Closing the ACTIVE one has to move the selection too, or the
+  // sync above would immediately reopen it: switch to a neighbouring tab, or
+  // start a fresh conversation when that was the last one open.
+  const closeTab = (threadId: string) => {
+    const fallback = nextActiveThreadTab(openTabIds, threadId);
+    setOpenTabIds((prev) => closeThreadTab(prev, threadId));
+    if (threadId !== activeThreadId) return;
+    if (fallback) onSelectThread?.(fallback);
+    else onNewThread?.();
+  };
+
   // Clear confirmation is an AppKit `AlertDialog` (a real modal), plus an
   // in-flight flag so the DELETE can't be double-fired. `clearing` disables
   // the confirm action while `onClear` runs; the dialog closes on settle.
@@ -475,34 +527,47 @@ export const ChatView = ({
   return (
     <TooltipProvider delayDuration={200}>
       {/*
-       * Outer row hosts the optional conversation sidebar beside the
-       * chat column. The chat column owns the vertical layout and the
+       * Outer row hosts the optional docked conversation list beside the
+       * chat column (`flex-row-reverse` puts it on the right edge without a
+       * second render path). The chat column owns the vertical layout and the
        * scroll; the centered `max-w-4xl` framing lives on each section
-       * (header, transcript, suggestions, composer) instead of the
+       * (tabs, header, transcript, suggestions, composer) instead of the
        * outer shell, so the scroll area's scrollbar sits at the far
        * right - outside the centered column - and the composer lines up
        * with the message column regardless of whether a scrollbar is
        * showing.
        */}
-      <div className={cn("flex h-full min-h-0", className)}>
-        {showSidebar &&
-          (isMobile
+      <div
+        ref={rootRef}
+        className={cn(
+          "flex h-full min-h-0",
+          dockedThreads && dockedSide === "right" && "flex-row-reverse",
+          className,
+        )}
+      >
+        {dockedThreads &&
+          (isNarrow
             ? /*
-               * Mobile: a fixed overlay drawer with a tap-to-close backdrop, so
-               * the conversation list never eats horizontal space from the chat
-               * on a phone. Selecting a thread / starting a new one also closes
-               * the drawer so the transcript comes back into view. Session-only
-               * + default closed (see `mobileDrawerOpen`).
+               * Narrow: a fixed overlay drawer on the docked edge with a
+               * tap-to-close backdrop, so the conversation list never eats
+               * horizontal space from an already-cramped chat. Selecting a
+               * thread / starting a new one also closes the drawer so the
+               * transcript comes back into view. Session-only + default closed
+               * (see `drawerOpen`).
                */
-              mobileDrawerOpen && (
-                <div className="fixed inset-0 z-40 flex">
+              drawerOpen && (
+                <div
+                  className={cn("fixed inset-0 z-40 flex", dockedSide === "right" && "justify-end")}
+                >
                   <div
                     className="absolute inset-0 bg-black/50"
                     onClick={toggleSidebar}
                     aria-hidden="true"
                   />
                   <ThreadSidebar
-                    {...sidebarProps}
+                    {...threadListProps}
+                    onHide={toggleSidebar}
+                    side={dockedSide}
                     onSelect={(id) => {
                       onSelectThread?.(id);
                       toggleSidebar();
@@ -520,23 +585,38 @@ export const ChatView = ({
                 </div>
               )
             : /*
-               * Desktop: an inline flex child sharing the row with the chat
-               * column, using the persisted open/hide preference. Same
-               * `sidebarProps` as mobile - only the framing + close-on-select
-               * differ.
+               * Wide: an inline flex child sharing the row with the chat
+               * column, using the persisted open/hide preference. Same list as
+               * the drawer - only the framing + close-on-select differ.
                */
-              desktopSidebarOpen && <ThreadSidebar {...sidebarProps} />)}
+              inlineSidebarOpen && (
+                <ThreadSidebar {...threadListProps} onHide={toggleSidebar} side={dockedSide} />
+              ))}
         <div className="flex h-full min-w-0 flex-1 flex-col">
+          {tabbedThreads && (
+            /*
+             * `top` placement: the open conversations as an editor-style tab
+             * strip, with the rest reachable through its history menu. Takes
+             * the place of both the docked panel and the header toggle.
+             */
+            <ThreadTabs {...threadListProps} openThreadIds={openTabIds} onCloseTab={closeTab} />
+          )}
           {showHeader && (
             /*
-             * Slim top bar holding the sidebar toggle. On mobile the toggle is
-             * a persistent hamburger (the overlay drawer has no always-visible
-             * hide button); on desktop it's a "show" affordance rendered only
-             * while the inline sidebar is collapsed (an open sidebar has its
-             * own hide button). `showHeader` already tracks that visibility, so
-             * the bar never renders empty.
+             * Slim top bar holding the docked panel's toggle. On a narrow chat
+             * it's a persistent hamburger (the overlay drawer has no
+             * always-visible hide button); otherwise it's a "show" affordance
+             * rendered only while the inline panel is collapsed (an open panel
+             * has its own hide button). `showHeader` already tracks that
+             * visibility, so the bar never renders empty.
              */
-            <div className="mx-auto flex w-full max-w-4xl items-center gap-2 px-3 pb-2 pt-1 text-xs text-muted-foreground md:gap-3 md:px-6">
+            <div
+              className={cn(
+                "mx-auto flex w-full max-w-4xl items-center gap-2 px-3 pb-2 pt-1 text-xs text-muted-foreground md:gap-3 md:px-6",
+                // Keep the toggle on the same edge as the panel it opens.
+                dockedSide === "right" && "justify-end",
+              )}
+            >
               <Tooltip>
                 <TooltipTrigger asChild>
                   <Button
@@ -546,7 +626,7 @@ export const ChatView = ({
                     onClick={toggleSidebar}
                     aria-label={sidebarOpen ? "Hide conversations" : "Show conversations"}
                   >
-                    <PanelLeftIcon className="size-4" />
+                    <SidebarToggleIcon className="size-4" />
                   </Button>
                 </TooltipTrigger>
                 <TooltipContent>

package/src/react/index.ts

@@ -27,6 +27,9 @@ export { ExportMenu } from "./export-menu.tsx";
 export { MastraChat, useMastraChat } from "./mastra-chat.tsx";
 export type { MastraChatProps, UseMastraChatOptions } from "./mastra-chat.tsx";
 export { ThreadSidebar } from "./thread-sidebar.tsx";
+export type { ThreadSidebarProps } from "./thread-sidebar.tsx";
+export { ThreadTabs } from "./thread-tabs.tsx";
+export type { ThreadTabsProps } from "./thread-tabs.tsx";
 export type {
   ApprovalDecision,
   ChatModelOption,
@@ -37,6 +40,7 @@ export type {
   FeedbackValue,
   MessageFeedback,
   PendingApproval,
+  ThreadPlacement,
   ThreadSummary,
   ToolEvent,
   ToolProgress,

package/src/react/mastra-chat.tsx

@@ -10,6 +10,7 @@ import type {
   ChatViewProps,
   FeedbackSubmission,
   MessageFeedback,
+  ThreadPlacement,
   ThreadSummary,
   ToolEvent,
   ToolProgress,
@@ -192,8 +193,20 @@ export interface UseMastraChatOptions {
    * them / start new ones / delete them. On by default. Set `false` for
    * the classic single-thread chat anchored to the per-session cookie
    * (no sidebar, no thread tracking).
+   *
+   * Shorthand for {@link threadPlacement}: `false` is `"disabled"`. When both
+   * are passed, `enableThreads: false` wins.
    */
   enableThreads?: boolean;
+  /**
+   * Where conversation management renders: `"left"` / `"right"` dock the list
+   * to that edge, `"top"` shows the open conversations as an editor-style tab
+   * strip with a history menu, `"disabled"` turns thread management off, and
+   * the default `"auto"` picks `"left"` while the chat is wide enough for a
+   * side panel and `"top"` once it gets too narrow for one (measured on the
+   * chat's own width, so an embedded panel decides on its own space).
+   */
+  threadPlacement?: ThreadPlacement;
   /**
    * Enable chat export. Off by default (opt-in). When on, the header
    * shows an "Export" menu for the whole conversation and each assistant
@@ -257,7 +270,11 @@ export const useMastraChat = (
   // conversations a user owns. Each call (stream / history / clear) carries
   // its thread id per request, so many threads can run concurrently without
   // sharing routing state.
-  const enableThreads = options.enableThreads !== false;
+  // `enableThreads: false` is the legacy way to say "no thread management", so
+  // it collapses into the placement rather than living as a second flag.
+  const threadPlacement: ThreadPlacement =
+    options.enableThreads === false ? "disabled" : (options.threadPlacement ?? "auto");
+  const enableThreads = threadPlacement !== "disabled";
   // Export is opt-in (default off): the host turns it on explicitly.
   const enableExport = options.enableExport === true;
   // Feedback defaults to export's setting; an explicit option overrides.
@@ -1427,6 +1444,7 @@ export const useMastraChat = (
     hasMore: activeSession.hasMoreHistory,
     isLoadingHistory,
     onClear: handleClear,
+    threadPlacement,
     // Conversation management: hand ChatView the thread list + handlers
     // only when enabled, so the sidebar stays hidden for the classic
     // single-thread chat (ChatView keys the sidebar off these props).
@@ -1485,8 +1503,9 @@ export interface MastraChatProps extends UseMastraChatOptions {
  * history pagination, and built-in conversation management (a sidebar
  * of the resource's threads with select / new / delete, persisted
  * across reloads) - all with no host wiring. The model picker is opt-in
- * via `showModelPicker`; thread management is on by default and can be
- * turned off with `enableThreads: false`.
+ * via `showModelPicker`; thread management is on by default, laid out per
+ * `threadPlacement` (`auto` docks it left and falls back to a tab strip on a
+ * narrow chat) and turned off with `threadPlacement: "disabled"`.
  */
 export const MastraChat = ({ className, ...options }: MastraChatProps) => {
   const chat = useMastraChat(options);

package/src/react/thread-sidebar.tsx

@@ -12,12 +12,14 @@ import {
   Loader2Icon,
   MessageSquarePlusIcon,
   PanelLeftIcon,
+  PanelRightIcon,
   PencilIcon,
   SquareIcon,
   Trash2Icon,
 } from "lucide-react";
 import { useState } from "react";
 import type { ThreadSummary } from "./types.ts";
+import { relativeTime, threadTitle } from "../support/thread-labels.ts";
 
 // Presentational conversation list. Renders the threads a resource owns
 // so the user can switch between them, start a new one, rename one, and
@@ -51,6 +53,11 @@ export interface ThreadSidebarProps {
   onCancel?: (threadId: string) => void;
   /** Collapse the sidebar. Renders the hide button in the header when provided. */
   onHide?: () => void;
+  /**
+   * Edge the sidebar is docked to. Only affects framing - which side carries
+   * the divider, and which way the collapse icon points. Defaults to `left`.
+   */
+  side?: "left" | "right";
   /** Extra classes merged onto the sidebar root. */
   className?: string;
 }
@@ -76,8 +83,12 @@ export const ThreadSidebar = ({
   onRename,
   onCancel,
   onHide,
+  side = "left",
   className,
 }: ThreadSidebarProps) => {
+  // The collapse icon points at the edge the panel lives on, so the same
+  // button reads as "tuck this away" on either side.
+  const HideIcon = side === "right" ? PanelRightIcon : PanelLeftIcon;
   // Thread id armed for deletion (first trash click). A second click on
   // the same row confirms; clicking elsewhere / another row resets it.
   const [confirmDeleteId, setConfirmDeleteId] = useState<string | null>(null);
@@ -119,7 +130,8 @@ export const ThreadSidebar = ({
   return (
     <div
       className={cn(
-        "flex h-full w-64 shrink-0 flex-col border-r border-border bg-background",
+        "flex h-full w-64 shrink-0 flex-col border-border bg-background",
+        side === "right" ? "border-l" : "border-r",
         className,
       )}
     >
@@ -148,7 +160,7 @@ export const ThreadSidebar = ({
                   aria-label="Hide conversations"
                   className={cn("size-8 shrink-0", !onNew && "ml-auto")}
                 >
-                  <PanelLeftIcon className="size-4" />
+                  <HideIcon className="size-4" />
                 </Button>
               </TooltipTrigger>
               <TooltipContent>Hide conversations</TooltipContent>
@@ -315,28 +327,3 @@ export const ThreadSidebar = ({
     </div>
   );
 };
-
-/** Title for a thread row, falling back to a placeholder when unnamed. */
-function threadTitle(thread: ThreadSummary): string {
-  const title = thread.title?.trim();
-  return title && title.length > 0 ? title : "New conversation";
-}
-
-/**
- * Render an ISO-8601 timestamp as a coarse "time ago" hint
- * (`just now`, `5m ago`, `3h ago`, `2d ago`, or a locale date for
- * anything older than a week). Invalid input renders nothing.
- */
-function relativeTime(iso: string): string {
-  const then = new Date(iso).getTime();
-  if (Number.isNaN(then)) return "";
-  const diffMs = Date.now() - then;
-  const minutes = Math.floor(diffMs / 60_000);
-  if (minutes < 1) return "just now";
-  if (minutes < 60) return `${minutes}m ago`;
-  const hours = Math.floor(minutes / 60);
-  if (hours < 24) return `${hours}h ago`;
-  const days = Math.floor(hours / 24);
-  if (days < 7) return `${days}d ago`;
-  return new Date(then).toLocaleDateString();
-}

package/src/react/thread-tabs.tsx

@@ -0,0 +1,191 @@
+import {
+  Button,
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+  cn,
+} from "@dbx-tools/ui-appkit/react";
+import { HistoryIcon, Loader2Icon, PlusIcon, XIcon } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import { ThreadSidebar, type ThreadSidebarProps } from "./thread-sidebar.tsx";
+import { threadTitle } from "../support/thread-labels.ts";
+
+// Editor-style conversation tabs: the open conversations across the top of the
+// chat, plus a "new chat" button and a history menu holding every other
+// conversation. Used by the `top` thread placement, where a side panel would
+// eat too much of a narrow chat.
+//
+// The history menu reuses `ThreadSidebar` verbatim inside a popover rather than
+// reimplementing a list, so rename / delete / cancel / streaming behave exactly
+// as they do in the docked placements.
+
+/** Props for {@link ThreadTabs}. */
+export interface ThreadTabsProps extends Omit<ThreadSidebarProps, "onHide" | "side"> {
+  /**
+   * Ids of the conversations open as tabs, left to right. Ids without a
+   * matching {@link ThreadSidebarProps.threads} entry still render (a
+   * brand-new conversation isn't in the server list yet).
+   */
+  openThreadIds: string[];
+  /**
+   * Take a conversation off the strip. The conversation itself is kept - use
+   * {@link ThreadSidebarProps.onDelete} to remove it. Per-tab close
+   * affordance hidden when omitted.
+   */
+  onCloseTab?: (threadId: string) => void;
+}
+
+/**
+ * Tab strip for the `top` thread placement. Each open conversation is a tab
+ * showing its title, a spinner while it streams in the background, and a close
+ * affordance; a trailing `+` starts a fresh conversation and a history button
+ * opens the full conversation list (a {@link ThreadSidebar} in a popover) so
+ * anything not currently tabbed is one click away. The active tab is scrolled
+ * into view when the selection changes, so switching from history never leaves
+ * the current conversation off-screen.
+ */
+export const ThreadTabs = ({ openThreadIds, onCloseTab, className, ...list }: ThreadTabsProps) => {
+  const { threads, activeThreadId, streamingThreadIds = [], onSelect, onNew } = list;
+  // Controlled so picking a conversation (or starting one) dismisses the menu
+  // instead of leaving it open over the transcript.
+  const [historyOpen, setHistoryOpen] = useState(false);
+  const activeTabRef = useRef<HTMLDivElement | null>(null);
+  useEffect(() => {
+    activeTabRef.current?.scrollIntoView({ block: "nearest", inline: "nearest" });
+  }, [activeThreadId]);
+
+  return (
+    // The divider spans the whole chat width while the strip's contents stay
+    // in the same centered column as the transcript and composer.
+    <div className={cn("w-full border-b border-border text-xs", className)}>
+      <div className="mx-auto flex w-full max-w-4xl items-center gap-1 px-2 py-1 md:px-4">
+        <div role="tablist" className="flex min-w-0 flex-1 items-center gap-1 overflow-x-auto">
+          {openThreadIds.map((id) => {
+            const thread = threads.find((t) => t.id === id) ?? { id };
+            const isActive = id === activeThreadId;
+            const isStreaming = streamingThreadIds.includes(id);
+            const title = threadTitle(thread);
+            return (
+              <Tooltip key={id}>
+                <TooltipTrigger asChild>
+                  <div
+                    ref={isActive ? activeTabRef : undefined}
+                    role="tab"
+                    aria-selected={isActive}
+                    tabIndex={0}
+                    onClick={() => onSelect(id)}
+                    onKeyDown={(e) => {
+                      if (e.key === "Enter" || e.key === " ") {
+                        e.preventDefault();
+                        onSelect(id);
+                      }
+                    }}
+                    className={cn(
+                      "group flex max-w-[12rem] shrink-0 cursor-pointer items-center gap-1.5",
+                      "rounded-md border border-transparent px-2 py-1",
+                      "hover:bg-accent hover:text-accent-foreground",
+                      isActive && "border-border bg-accent text-accent-foreground",
+                    )}
+                  >
+                    {isStreaming && (
+                      <Loader2Icon
+                        aria-label="Streaming"
+                        className="size-3 shrink-0 animate-spin text-primary"
+                      />
+                    )}
+                    <span className="truncate">{title}</span>
+                    {onCloseTab && (
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="icon"
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          onCloseTab(id);
+                        }}
+                        aria-label="Close tab"
+                        className={cn(
+                          "size-4 shrink-0",
+                          // The active tab always shows its close button; the
+                          // rest reveal one on hover / keyboard focus so the
+                          // strip stays quiet.
+                          !isActive &&
+                            "opacity-0 group-hover:opacity-100 focus-visible:opacity-100",
+                        )}
+                      >
+                        <XIcon className="size-3" />
+                      </Button>
+                    )}
+                  </div>
+                </TooltipTrigger>
+                <TooltipContent>{title}</TooltipContent>
+              </Tooltip>
+            );
+          })}
+        </div>
+        {onNew && (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon"
+                onClick={onNew}
+                aria-label="New chat"
+                className="size-7 shrink-0"
+              >
+                <PlusIcon className="size-4" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>New chat</TooltipContent>
+          </Tooltip>
+        )}
+        <Popover open={historyOpen} onOpenChange={setHistoryOpen}>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <PopoverTrigger asChild>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon"
+                  aria-label="Conversation history"
+                  className="size-7 shrink-0"
+                >
+                  <HistoryIcon className="size-4" />
+                </Button>
+              </PopoverTrigger>
+            </TooltipTrigger>
+            <TooltipContent>Conversation history</TooltipContent>
+          </Tooltip>
+          <PopoverContent align="end" className="w-72 p-0">
+            {/*
+             * The same list the docked placements render, just framed as a menu:
+             * selecting (or starting) a conversation opens it as a tab and
+             * dismisses the popover, while rename / delete / cancel work in
+             * place.
+             */}
+            <ThreadSidebar
+              {...list}
+              onSelect={(id) => {
+                onSelect(id);
+                setHistoryOpen(false);
+              }}
+              {...(onNew
+                ? {
+                    onNew: () => {
+                      onNew();
+                      setHistoryOpen(false);
+                    },
+                  }
+                : {})}
+              className="h-96 w-full border-none"
+            />
+          </PopoverContent>
+        </Popover>
+      </div>
+    </div>
+  );
+};

package/src/react/types.ts

@@ -87,6 +87,21 @@ export type ThreadSummary = {
   updatedAt?: string;
 };
 
+/**
+ * Where conversation management lives in the chat's layout, and whether it
+ * exists at all:
+ *
+ * - `disabled` - no thread UI (the classic single-thread chat).
+ * - `auto` - `left` while the chat is wide enough for a side panel, `top`
+ *   once it gets too narrow for one. Measured off the chat's own width, so
+ *   an embedded panel switches on its own space rather than the viewport's.
+ * - `left` / `right` - a conversation list docked to that edge, collapsing to
+ *   an overlay drawer on the same edge when the chat is narrow.
+ * - `top` - a tab strip of open conversations above the transcript, with a
+ *   history menu listing every other conversation.
+ */
+export type ThreadPlacement = "disabled" | "auto" | "left" | "right" | "top";
+
 export type ChatViewProps = {
   messages: UIMessage[];
   status: ChatStatus;
@@ -217,6 +232,13 @@ export type ChatViewProps = {
    * the classic single-thread chat with no sidebar.
    */
   threads?: ThreadSummary[];
+  /**
+   * Where the conversation list renders (or `"disabled"` to hide it even when
+   * {@link threads} and {@link onSelectThread} are wired). Defaults to
+   * `"auto"`: a left side panel while the chat is wide, a tab strip once it
+   * is too narrow for one. See {@link ThreadPlacement}.
+   */
+  threadPlacement?: ThreadPlacement;
   /** Id of the currently-active thread, highlighted in the sidebar. */
   activeThreadId?: string;
   /**
@@ -265,7 +287,8 @@ export type ChatViewProps = {
    * this together with {@link onToggleSidebar} to control and persist
    * the show/hide choice from the host (the driver does this so the
    * choice survives reloads). The header toggle is shown whenever the
-   * sidebar is enabled, regardless of who owns the state.
+   * sidebar is enabled, regardless of who owns the state. Only applies to
+   * the `left` / `right` placements; the `top` tab strip is always visible.
    */
   sidebarOpen?: boolean;
   /**

package/src/support/thread-labels.ts

@@ -0,0 +1,30 @@
+import type { ThreadSummary } from "../react/types.ts";
+
+// Display formatting for a conversation row, shared by the two surfaces that
+// list threads (`ThreadSidebar` and `ThreadTabs`) so a sidebar row and a tab
+// never disagree about what an untitled or freshly-updated thread reads as.
+
+/** Title for a thread, falling back to a placeholder when unnamed. */
+export function threadTitle(thread: ThreadSummary): string {
+  const title = thread.title?.trim();
+  return title && title.length > 0 ? title : "New conversation";
+}
+
+/**
+ * Render an ISO-8601 timestamp as a coarse "time ago" hint
+ * (`just now`, `5m ago`, `3h ago`, `2d ago`, or a locale date for
+ * anything older than a week). Invalid input renders nothing.
+ */
+export function relativeTime(iso: string): string {
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) return "";
+  const diffMs = Date.now() - then;
+  const minutes = Math.floor(diffMs / 60_000);
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d ago`;
+  return new Date(then).toLocaleDateString();
+}

package/src/support/thread-tabs.ts

@@ -0,0 +1,60 @@
+import type { ThreadSummary } from "../react/types.ts";
+
+// Which conversations are open as tabs in the `top` thread placement, kept as
+// pure functions so the tab strip's bookkeeping is testable without a DOM.
+//
+// A tab is an OPEN conversation, not the conversation itself: closing a tab
+// only takes it off the strip (the thread stays in history and in the list the
+// history menu shows), while deleting a thread removes it everywhere. The set
+// is session-scoped - the strip reseeds from the most recent conversations on
+// the next load - so a reload never resurrects a stale tab for a thread the
+// user has since deleted.
+
+/**
+ * How many of the most recent conversations the strip opens as tabs the first
+ * time the thread list arrives. Sized to fill a typical strip without pushing
+ * the active tab off-screen behind horizontal scroll.
+ */
+export const THREAD_TAB_SEED_MAX = 5;
+
+/**
+ * Reconcile the open tabs against the current thread list and selection:
+ * drop tabs whose conversation no longer exists, seed from the newest
+ * conversations while the strip is empty, and always keep a tab for the active
+ * thread (a brand-new one isn't in the server list yet, so it's kept on the
+ * strength of being active alone).
+ *
+ * Returns `openIds` itself when nothing changed, so a caller can drive this
+ * from an effect without looping on a fresh array every render.
+ */
+export function syncThreadTabs(
+  openIds: string[],
+  threads: ThreadSummary[],
+  activeThreadId?: string,
+  seedMax: number = THREAD_TAB_SEED_MAX,
+): string[] {
+  const known = new Set(threads.map((thread) => thread.id));
+  let next = openIds.filter((id) => known.has(id) || id === activeThreadId);
+  if (next.length === 0) next = threads.slice(0, seedMax).map((thread) => thread.id);
+  if (activeThreadId && !next.includes(activeThreadId)) next = [...next, activeThreadId];
+  const unchanged = next.length === openIds.length && next.every((id, i) => id === openIds[i]);
+  return unchanged ? openIds : next;
+}
+
+/** Take a conversation off the strip, leaving the rest in order. */
+export function closeThreadTab(openIds: string[], id: string): string[] {
+  return openIds.filter((tab) => tab !== id);
+}
+
+/**
+ * Which tab to activate after closing `id`: the one to its right, else its
+ * left neighbour, else `undefined` when it was the only tab open (the caller
+ * then starts a fresh conversation rather than leaving nothing selected).
+ */
+export function nextActiveThreadTab(openIds: string[], id: string): string | undefined {
+  const index = openIds.indexOf(id);
+  if (index === -1) return undefined;
+  if (index + 1 < openIds.length) return openIds[index + 1];
+  if (index > 0) return openIds[index - 1];
+  return undefined;
+}