@dbx-tools/ui-mastra 0.1.22 → 0.1.24

package/index.ts

@@ -26,7 +26,7 @@ export type { UseMastraChatOptions, MastraChatProps } from "./src/react/mastra-c
 export type { SuggestionPillsProps } from "./src/react/suggestion-pills";
 export type { ThreadSidebarProps } from "./src/react/thread-sidebar";
 export type { ChatStatus, ToolEvent, ToolProgress, ChatModelOption, FeedbackValue, FeedbackSubmission, MessageFeedback, ThreadSummary, ChatViewProps, ApprovalDecision, PendingApproval } from "./src/react/types";
-export type { ExportFormat, EmbedResolver, ExportChatOptions } from "./src/support/export";
+export type { ExportFormat, ExportBrand, EmbedResolver, ExportChatOptions } from "./src/support/export";
 export type { ByIdFetchState } from "./src/support/mastra-client";
 export type { MastraStreamChunk, MastraStreamResponse } from "./src/support/mastra-stream";
 export type { ThreadSession } from "./src/support/thread-sessions";

package/package.json

@@ -26,18 +26,19 @@
     "shiki": "^3.0.0",
     "sql-formatter": "^15.6.9",
     "streamdown": "^2.5.0",
-    "@dbx-tools/shared-core": "0.1.22",
-    "@dbx-tools/shared-genie": "0.1.22",
-    "@dbx-tools/shared-mastra": "0.1.22",
-    "@dbx-tools/shared-model": "0.1.22",
-    "@dbx-tools/ui-appkit": "0.1.22"
+    "@dbx-tools/shared-core": "0.1.24",
+    "@dbx-tools/shared-genie": "0.1.24",
+    "@dbx-tools/shared-mastra": "0.1.24",
+    "@dbx-tools/shared-model": "0.1.24",
+    "@dbx-tools/ui-appkit": "0.1.24",
+    "@dbx-tools/ui-branding": "0.1.24"
   },
   "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.22",
+  "version": "0.1.24",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/react/chat-view.tsx

@@ -63,6 +63,30 @@ 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;
+
+/**
+ * `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.
+ */
+const useIsMobile = (): boolean => {
+  const query = `(max-width: ${MOBILE_BREAKPOINT_PX - 1}px)`;
+  const [isMobile, setIsMobile] = useState(() =>
+    typeof window === "undefined" ? false : window.matchMedia(query).matches,
+  );
+  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;
+};
+
 export const ChatView = ({
   messages,
   status,
@@ -101,6 +125,8 @@ export const ChatView = ({
   const [input, setInput] = useState("");
   const scrollRef = useRef<HTMLDivElement>(null);
   const contentRef = useRef<HTMLDivElement>(null);
+  // Composer textarea, auto-grown with its content up to the CSS `max-h`.
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
   const [isAtBottom, setIsAtBottom] = useState(true);
   // Mirror `isAtBottom` into a ref so the ResizeObserver below (created
   // per transcript mount, not per render) reads the latest value
@@ -194,6 +220,16 @@ export const ChatView = ({
     });
   };
 
+  // Grow the composer with its content (up to the textarea's CSS `max-h`,
+  // after which it scrolls internally), then shrink back as text is removed.
+  // Runs on every `input` change so paste / multi-line typing feels native.
+  useLayoutEffect(() => {
+    const el = textareaRef.current;
+    if (!el) return;
+    el.style.height = "auto";
+    el.style.height = `${el.scrollHeight}px`;
+  }, [input]);
+
   // A turn is in flight from the moment the run opens (`submitted`)
   // until the server signals done (`ready`/`error`). Used to gate new
   // submissions and to swap the composer's Send button for Stop.
@@ -208,6 +244,15 @@ export const ChatView = ({
     if (!text) return;
     sendMessage({ text });
     setInput("");
+    // Sending is an explicit "I want to see the response" action, so
+    // re-pin to the bottom even if the user had scrolled up. Without this
+    // the freshly-appended user turn + waiting row can leave `isAtBottom`
+    // false, suppressing auto-scroll and forcing a manual scroll down.
+    setIsAtBottom(true);
+    requestAnimationFrame(() => {
+      const el = scrollRef.current;
+      if (el) el.scrollTop = el.scrollHeight;
+    });
   };
 
   const lastMessage = messages.at(-1);
@@ -233,7 +278,18 @@ export const ChatView = ({
       ? "Working..."
       : "Composing response...";
 
-  const showModelPicker = Boolean(models && models.length > 0 && onModelChange);
+  // Model display is intent-driven, not load-driven: as soon as the host
+  // wires `onModelChange` we reserve the row and show the current model,
+  // so it never "pops in" once the async catalogue lands. It renders as a
+  // clickable picker only when there's an actual choice (models loaded),
+  // otherwise as static text.
+  const showModelDisplay = Boolean(onModelChange);
+  const modelChangeable = Boolean(models && models.length > 0);
+  // Label the current model by its human-readable name when the catalogue
+  // carries one (`displayName`), falling back to the raw endpoint id, then
+  // to "Server default" when no model is pinned.
+  const currentModelLabel =
+    models?.find((m) => m.name === model)?.displayName || model || "Server default";
   const showClear = Boolean(onClear);
   const showExport = Boolean(onExportConversation);
   // The conversation sidebar turns on once the host wires both the
@@ -244,12 +300,35 @@ export const ChatView = ({
   // open flag. Defaults to open.
   const showSidebar = Boolean(threads && onSelectThread);
   const [internalSidebarOpen, setInternalSidebarOpen] = useState(true);
-  const sidebarOpen = sidebarOpenProp ?? internalSidebarOpen;
-  const toggleSidebar = () => {
+  // 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 = () => {
     if (onToggleSidebar) onToggleSidebar();
     else setInternalSidebarOpen((open) => !open);
   };
-  const showHeader = showModelPicker || showClear || showSidebar || showExport;
+  // 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);
+  useEffect(() => {
+    if (!isMobile) setMobileDrawerOpen(false);
+  }, [isMobile]);
+  // Unified state/handlers the render + header use, resolved by viewport.
+  const sidebarOpen = isMobile ? mobileDrawerOpen : desktopSidebarOpen;
+  const toggleSidebar = () => {
+    if (isMobile) setMobileDrawerOpen((open) => !open);
+    else toggleDesktopSidebar();
+  };
+  // Top bar carries only the sidebar toggle + Clear now; the model picker and
+  // export live in a toolbar row just above the composer (Janna-style), closer
+  // to where the user is typing.
+  const showHeader = showClear || showSidebar;
+  const showComposerToolbar = showModelDisplay || showExport;
 
   // Local "in-flight" + confirm latch for the clear button so the
   // user can't double-fire the DELETE and so a stray click doesn't
@@ -283,29 +362,77 @@ export const ChatView = ({
        * with the message column regardless of whether a scrollbar is
        * showing.
        */}
-      <div className={cn("flex h-full", className)}>
-        {showSidebar && sidebarOpen && (
-          <ThreadSidebar
-            threads={threads ?? []}
-            {...(activeThreadId ? { activeThreadId } : {})}
-            streamingThreadIds={streamingThreadIds}
-            isLoading={isLoadingThreads}
-            onSelect={(id) => onSelectThread?.(id)}
-            {...(onNewThread ? { onNew: onNewThread } : {})}
-            {...(onDeleteThread ? { onDelete: onDeleteThread } : {})}
-            {...(onRenameThread ? { onRename: onRenameThread } : {})}
-            onHide={toggleSidebar}
-          />
-        )}
-        <div className="flex h-full min-w-0 flex-1 flex-col py-0 md:py-6">
+      <div className={cn("flex h-full min-h-0", className)}>
+        {showSidebar &&
+          (isMobile ? (
+            /*
+             * 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 closes it so
+             * the transcript comes back into view. Session-only + default
+             * closed (see `mobileDrawerOpen`).
+             */
+            mobileDrawerOpen && (
+              <div className="fixed inset-0 z-40 flex">
+                <div
+                  className="absolute inset-0 bg-black/50"
+                  onClick={toggleSidebar}
+                  aria-hidden="true"
+                />
+                <ThreadSidebar
+                  threads={threads ?? []}
+                  {...(activeThreadId ? { activeThreadId } : {})}
+                  streamingThreadIds={streamingThreadIds}
+                  isLoading={isLoadingThreads}
+                  onSelect={(id) => {
+                    onSelectThread?.(id);
+                    toggleSidebar();
+                  }}
+                  {...(onNewThread
+                    ? {
+                        onNew: () => {
+                          onNewThread();
+                          toggleSidebar();
+                        },
+                      }
+                    : {})}
+                  {...(onDeleteThread ? { onDelete: onDeleteThread } : {})}
+                  {...(onRenameThread ? { onRename: onRenameThread } : {})}
+                  onHide={toggleSidebar}
+                  className="relative z-10 w-[85vw] max-w-xs shadow-xl"
+                />
+              </div>
+            )
+          ) : (
+            /*
+             * Desktop: an inline flex child sharing the row with the chat
+             * column, using the persisted open/hide preference.
+             */
+            desktopSidebarOpen && (
+              <ThreadSidebar
+                threads={threads ?? []}
+                {...(activeThreadId ? { activeThreadId } : {})}
+                streamingThreadIds={streamingThreadIds}
+                isLoading={isLoadingThreads}
+                onSelect={(id) => onSelectThread?.(id)}
+                {...(onNewThread ? { onNew: onNewThread } : {})}
+                {...(onDeleteThread ? { onDelete: onDeleteThread } : {})}
+                {...(onRenameThread ? { onRename: onRenameThread } : {})}
+                onHide={toggleSidebar}
+              />
+            )
+          ))}
+        <div className="flex h-full min-w-0 flex-1 flex-col">
           {showHeader && (
-            <div className="mx-auto flex w-full max-w-4xl items-center justify-between gap-3 px-4 pb-2 pt-1 text-xs text-muted-foreground md:px-6">
-              <div className="flex items-center gap-2">
+            <div className="mx-auto flex w-full max-w-4xl items-center justify-between gap-2 px-3 pb-2 pt-1 text-xs text-muted-foreground md:gap-3 md:px-6">
+              <div className="flex shrink-0 items-center gap-2">
                 {/*
-                 * The hide control lives on the sidebar itself; the header
-                 * only offers a "show" toggle while the sidebar is collapsed.
+                 * Sidebar toggle. On mobile it's a persistent hamburger (the
+                 * overlay drawer has no always-visible hide button). On desktop
+                 * the panel hides itself, so the header only needs a "show"
+                 * affordance while the inline sidebar is collapsed.
                  */}
-                {showSidebar && !sidebarOpen && (
+                {showSidebar && (isMobile || !desktopSidebarOpen) && (
                   <Tooltip>
                     <TooltipTrigger asChild>
                       <Button
@@ -313,47 +440,18 @@ export const ChatView = ({
                         variant="ghost"
                         size="icon-sm"
                         onClick={toggleSidebar}
-                        aria-label="Show conversations"
+                        aria-label={sidebarOpen ? "Hide conversations" : "Show conversations"}
                       >
                         <PanelLeftIcon className="size-4" />
                       </Button>
                     </TooltipTrigger>
-                    <TooltipContent>Show conversations</TooltipContent>
+                    <TooltipContent>
+                      {sidebarOpen ? "Hide conversations" : "Show conversations"}
+                    </TooltipContent>
                   </Tooltip>
                 )}
               </div>
-              <div className="flex items-center gap-3">
-                {showModelPicker && (
-                  <div className="flex items-center gap-2">
-                    <span>Model</span>
-                    <Select
-                      value={model ? model : DEFAULT_MODEL_VALUE}
-                      onValueChange={(v) =>
-                        onModelChange?.(v === DEFAULT_MODEL_VALUE ? "" : v)
-                      }
-                    >
-                      <SelectTrigger size="sm" className="w-[260px]">
-                        <SelectValue placeholder="Server default" />
-                      </SelectTrigger>
-                      <SelectContent>
-                        <SelectItem value={DEFAULT_MODEL_VALUE}>
-                          Server default
-                        </SelectItem>
-                        {models!.map((m) => (
-                          <SelectItem key={m.name} value={m.name}>
-                            {m.name}
-                          </SelectItem>
-                        ))}
-                      </SelectContent>
-                    </Select>
-                  </div>
-                )}
-                {showExport && (
-                  <ExportMenu
-                    onExport={(format) => void onExportConversation?.(format)}
-                    tooltip="Export conversation"
-                  />
-                )}
+              <div className="flex min-w-0 items-center justify-end gap-2 md:gap-3">
                 {showClear && (
                   <Tooltip>
                     <TooltipTrigger asChild>
@@ -397,7 +495,7 @@ export const ChatView = ({
             <div
               ref={scrollRef}
               onScroll={handleScroll}
-              className="flex-1 overflow-y-auto [scrollbar-gutter:stable]"
+              className="flex-1 overflow-y-auto overflow-x-hidden overscroll-contain [scrollbar-gutter:stable]"
             >
               {messages.length === 0 && !isLoadingHistory ? (
                 <Empty className="mx-auto h-full w-full max-w-4xl px-4 md:px-6">
@@ -499,7 +597,7 @@ export const ChatView = ({
               )}
             </div>
             {!isAtBottom && (
-              <div className="pointer-events-none absolute inset-x-0 bottom-4 mx-auto flex w-full max-w-4xl justify-end px-4 md:px-6">
+              <div className="pointer-events-none absolute inset-x-0 bottom-4 z-20 mx-auto flex w-full max-w-4xl justify-end px-4 md:px-6">
                 <Button
                   type="button"
                   variant="outline"
@@ -523,10 +621,11 @@ export const ChatView = ({
 
           <form
             onSubmit={handleSubmit}
-            className="mx-auto w-full max-w-4xl px-4 pb-4 pt-2 md:px-6"
+            className="mx-auto w-full max-w-4xl px-3 pt-2 pb-[max(1rem,env(safe-area-inset-bottom))] md:px-6"
           >
-            <InputGroup>
+            <InputGroup className="rounded-2xl border-border/80 shadow-sm transition-shadow focus-within:shadow-md">
               <InputGroupTextarea
+                ref={textareaRef}
                 value={input}
                 onChange={(e) => setInput(e.target.value)}
                 onKeyDown={(e) => {
@@ -537,6 +636,7 @@ export const ChatView = ({
                 }}
                 placeholder="Send a message..."
                 rows={1}
+                className="max-h-48 text-base md:text-sm"
               />
               <InputGroupAddon align="inline-end">
                 {isRunning && onStop ? (
@@ -566,6 +666,44 @@ export const ChatView = ({
                 )}
               </InputGroupAddon>
             </InputGroup>
+            {showComposerToolbar && (
+              <div className="mt-2 flex items-center gap-2 text-xs text-muted-foreground">
+                {showModelDisplay &&
+                  (modelChangeable ? (
+                    <Select
+                      value={model ? model : DEFAULT_MODEL_VALUE}
+                      onValueChange={(v) =>
+                        onModelChange?.(v === DEFAULT_MODEL_VALUE ? "" : v)
+                      }
+                    >
+                      <SelectTrigger
+                        size="sm"
+                        className="h-7 w-auto max-w-[200px] gap-1 rounded-full px-2.5 text-xs [&_svg]:size-3"
+                      >
+                        <SelectValue placeholder="Server default" />
+                      </SelectTrigger>
+                      <SelectContent>
+                        <SelectItem value={DEFAULT_MODEL_VALUE}>Server default</SelectItem>
+                        {models!.map((m) => (
+                          <SelectItem key={m.name} value={m.name}>
+                            {m.displayName || m.name}
+                          </SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                  ) : (
+                    <span className="max-w-[200px] truncate px-2.5 text-xs text-muted-foreground">
+                      {currentModelLabel}
+                    </span>
+                  ))}
+                {showExport && (
+                  <ExportMenu
+                    onExport={(format) => void onExportConversation?.(format)}
+                    tooltip="Export conversation"
+                  />
+                )}
+              </div>
+            )}
           </form>
         </div>
       </div>

package/src/react/export-menu.tsx

@@ -8,7 +8,7 @@ import {
   TooltipContent,
   TooltipTrigger,
 } from "@dbx-tools/ui-appkit/react";
-import { DownloadIcon } from "lucide-react";
+import { DownloadIcon, FileTextIcon, PrinterIcon } from "lucide-react";
 import type { ExportFormat } from "../support/export";
 
 // Shared export affordance: a download button that opens a small menu of
@@ -16,9 +16,14 @@ import type { ExportFormat } from "../support/export";
 // labelled) and per-message export (bubble action row, icon-only).
 
 /** Menu entries, in display order. */
-const FORMATS: ReadonlyArray<{ format: ExportFormat; label: string }> = [
-  { format: "pdf", label: "PDF" },
-  { format: "markdown", label: "Markdown" },
+const FORMATS: ReadonlyArray<{
+  format: ExportFormat;
+  label: string;
+  Icon: typeof DownloadIcon;
+}> = [
+  { format: "pdf", label: "PDF", Icon: DownloadIcon },
+  { format: "print", label: "Print", Icon: PrinterIcon },
+  { format: "markdown", label: "Markdown", Icon: FileTextIcon },
 ];
 
 /**
@@ -41,7 +46,12 @@ export const ExportMenu = ({
       <DownloadIcon className="size-3" />
     </Button>
   ) : (
-    <Button type="button" size="sm" variant="outline" className="gap-1.5">
+    <Button
+      type="button"
+      size="sm"
+      variant="outline"
+      className="h-7 gap-1 rounded-full px-2.5 text-xs [&_svg]:size-3"
+    >
       <DownloadIcon className="size-3" />
       Export
     </Button>
@@ -60,8 +70,9 @@ export const ExportMenu = ({
         <DropdownMenuTrigger asChild>{trigger}</DropdownMenuTrigger>
       )}
       <DropdownMenuContent align="end">
-        {FORMATS.map(({ format, label }) => (
+        {FORMATS.map(({ format, label, Icon }) => (
           <DropdownMenuItem key={format} onClick={() => onExport(format)}>
+            <Icon className="size-3.5" />
             {label}
           </DropdownMenuItem>
         ))}

package/src/react/mastra-chat.tsx

@@ -7,6 +7,7 @@ import type { UIMessage } from "ai";
 import { nanoid } from "nanoid";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { exportChat, type EmbedResolver, type ExportFormat } from "../support/export";
+import { useBrand } from "@dbx-tools/ui-branding/react";
 import {
   useMastraClient,
   useMastraModels,
@@ -1139,6 +1140,21 @@ export const useMastraChat = (
     const resourceId = threads.find((t) => t.resourceId)?.resourceId;
     return resourceId ? `User (${resourceId})` : "User";
   }, [threads]);
+  // Brand styling for the exported document, resolved from the active
+  // BrandProvider (or the built-in dbx-tools default when the host wired
+  // none). The logo asset id is resolved to a portable data URL so the
+  // export is self-contained; colors/font come straight from the context.
+  const { context: brandContext, resolveAsset: resolveBrandAsset } = useBrand();
+  const exportBrand = useMemo(
+    () => ({
+      logoDataUrl: resolveBrandAsset(brandContext.assets.logo.light),
+      primary: brandContext.colors.primary,
+      accent: brandContext.colors.accent,
+      foreground: brandContext.colors.foreground,
+      fontSans: brandContext.typography.sans,
+    }),
+    [brandContext, resolveBrandAsset],
+  );
   const exportConversation = useCallback(
     async (format: ExportFormat) => {
       const title =
@@ -1151,6 +1167,7 @@ export const useMastraChat = (
           resolver: exportResolver,
           title,
           userLabel: exportUserLabel,
+          brand: exportBrand,
         });
       } catch (error) {
         logger.error("conversation export error", {
@@ -1159,7 +1176,15 @@ export const useMastraChat = (
         });
       }
     },
-    [exportResolver, activeThreadId, activeKey, getSession, threads, exportUserLabel],
+    [
+      exportResolver,
+      activeThreadId,
+      activeKey,
+      getSession,
+      threads,
+      exportUserLabel,
+      exportBrand,
+    ],
   );
   const exportMessage = useCallback(
     async (message: UIMessage, format: ExportFormat) => {
@@ -1171,6 +1196,7 @@ export const useMastraChat = (
           title: "Message",
           filename: "message",
           userLabel: exportUserLabel,
+          brand: exportBrand,
         });
       } catch (error) {
         logger.error("message export error", {
@@ -1179,7 +1205,7 @@ export const useMastraChat = (
         });
       }
     },
-    [exportResolver, exportUserLabel],
+    [exportResolver, exportUserLabel, exportBrand],
   );
 
   // Submit thumbs / comment feedback for an assistant message to MLflow

package/src/react/thread-sidebar.tsx

@@ -111,7 +111,7 @@ export const ThreadSidebar = ({
   return (
     <div
       className={cn(
-        "flex h-full w-64 shrink-0 flex-col border-r border-border bg-muted/30",
+        "flex h-full w-64 shrink-0 flex-col border-r border-border bg-background",
         className,
       )}
     >

package/src/react/types.ts

@@ -33,8 +33,13 @@ export type ToolEvent = {
  */
 export type ToolProgress = GenieWriterEvent;
 
-/** Subset of a Model Serving endpoint surfaced in the model picker. */
-export type ChatModelOption = { name: string };
+/**
+ * Subset of a Model Serving endpoint surfaced in the model picker. `name`
+ * is the invoke id; `displayName` is the optional human-readable label the
+ * `/models` endpoint derives (Databricks-provided name, else a title-cased
+ * rendering of `name`). The picker shows `displayName ?? name`.
+ */
+export type ChatModelOption = { name: string; displayName?: string };
 
 /** Thumbs reaction a user can leave on an assistant turn. */
 export type FeedbackValue = "up" | "down";

package/src/support/export.ts

@@ -5,11 +5,15 @@
  * the single-message or the whole-conversation level, in one of two
  * formats:
  *
- *   - `"pdf"`   - a print-ready HTML document opened in a new tab with
- *                 the browser's print dialog triggered, so the user saves
- *                 a real PDF ("Save as PDF"). Renders reliably offline.
+ *   - `"pdf"`   - a print-ready HTML document rendered in a hidden iframe
+ *                 with the browser's print dialog triggered, so the user
+ *                 saves a real PDF ("Save as PDF") with no popup tab.
+ *   - `"print"` - the same document routed to a paper printer.
  *   - `"markdown"` - a `.md` file download.
  *
+ * The document can be brand-styled (logo, colors, font) via the optional
+ * `brand` option; the driver resolves it from `@dbx-tools/ui-branding`.
+ *
  * Charts are included, not dropped: each `[chart:<id>]` marker is
  * resolved against the plugin's chart cache and rendered to an inline
  * SVG via Echarts' server-side renderer (no DOM needed), so a PDF/HTML
@@ -29,8 +33,33 @@ import * as echarts from "echarts";
 import { marked } from "marked";
 import { normalizeChartOption } from "./chart-option";
 
-/** Output formats {@link exportChat} can produce. */
-export type ExportFormat = "pdf" | "markdown";
+/**
+ * Output formats {@link exportChat} can produce.
+ *   - `"pdf"`   - Save-as-PDF via a hidden print iframe (dialog defaults to
+ *                 "Save as PDF"); no new tab.
+ *   - `"print"` - same rendered document + print dialog, for a paper printer.
+ *   - `"markdown"` - a `.md` file download.
+ */
+export type ExportFormat = "pdf" | "print" | "markdown";
+
+/**
+ * Optional brand styling for the exported document. Plain data (no React /
+ * DOM), so this module stays framework-free; the driver resolves it from
+ * `@dbx-tools/ui-branding` (`useBrand()` + `resolveBrandAsset`) and passes it
+ * through. Any field omitted falls back to the neutral default styling.
+ */
+export interface ExportBrand {
+  /** Logo image src (a data URL) rendered in the document header. */
+  logoDataUrl?: string;
+  /** Primary brand color for the header rule, headings, and role labels. */
+  primary?: string;
+  /** Accent brand color (links). */
+  accent?: string;
+  /** Body text color. */
+  foreground?: string;
+  /** Sans-serif font stack for the document body. */
+  fontSans?: string;
+}
 
 /**
  * Resolves the embeds referenced by `[chart:<id>]` / `[data:<id>]`
@@ -61,6 +90,8 @@ export interface ExportChatOptions {
    * id / email form like `"User (someone@example.com)"`.
    */
   userLabel?: string;
+  /** Optional brand styling for the exported document. */
+  brand?: ExportBrand;
 }
 
 /** Fixed Echarts SSR canvas; the SVG scales to the print column via CSS. */
@@ -71,14 +102,14 @@ const CHART_HEIGHT_PX = 380;
 const PRINT_SETTLE_MS = 300;
 
 /**
- * Export `messages` as a PDF (via a print-ready tab) or a Markdown file.
+ * Export `messages` as a PDF, a print job, or a Markdown file.
  *
- * For `"pdf"` a new tab is opened **synchronously** (before any async
- * embed resolution) so browser popup blockers - which only allow
- * `window.open` inside a user gesture - don't swallow it; the resolved
- * document is written in once charts / tables are ready. If the popup is
- * blocked anyway, the HTML is downloaded as a file instead so the export
- * still succeeds.
+ * `"pdf"` and `"print"` render the same branded, self-contained HTML
+ * document and drive it through a hidden `<iframe>` + `print()` - so the
+ * browser's print dialog (defaulting to "Save as PDF" for `pdf`) opens
+ * directly, with no popup tab. If the iframe path can't run (e.g. no DOM
+ * body), the document is downloaded as a self-contained `.html` file so the
+ * export - charts included - still lands.
  */
 export async function exportChat(options: ExportChatOptions): Promise<void> {
   const { messages, format, resolver } = options;
@@ -92,22 +123,59 @@ export async function exportChat(options: ExportChatOptions): Promise<void> {
     return;
   }
 
-  // Open the tab up-front (user-gesture safe), show a placeholder while
-  // embeds resolve, then swap in the finished document and print.
-  const win = window.open("", "_blank");
-  win?.document.write(PREPARING_HTML);
-  const html = await buildHtmlDocument(messages, resolver, title, userLabel);
-  if (!win) {
-    // Popup blocked: fall back to an HTML file download so the export
-    // (charts included) still lands.
-    downloadTextFile(`${stem}.html`, html, "text/html;charset=utf-8");
+  // pdf / print: build the branded document, then print it from a hidden
+  // iframe so the Save-as-PDF / print dialog opens without a stray tab.
+  const html = await buildHtmlDocument(messages, resolver, title, userLabel, options.brand);
+  printViaHiddenIframe(html, `${stem}.html`);
+}
+
+/**
+ * Render `html` in an off-screen iframe and trigger its print dialog. The
+ * iframe is same-origin via `srcdoc`, so `contentWindow.print()` is allowed;
+ * it's removed after printing. Falls back to a file download when there's no
+ * document body to attach to.
+ */
+function printViaHiddenIframe(html: string, downloadName: string): void {
+  if (typeof document === "undefined" || !document.body) {
+    downloadTextFile(downloadName, html, "text/html;charset=utf-8");
     return;
   }
-  win.document.open();
-  win.document.write(html);
-  win.document.close();
-  win.focus();
-  win.setTimeout(() => win.print(), PRINT_SETTLE_MS);
+  const iframe = document.createElement("iframe");
+  iframe.setAttribute("aria-hidden", "true");
+  iframe.style.position = "fixed";
+  iframe.style.right = "0";
+  iframe.style.bottom = "0";
+  iframe.style.width = "0";
+  iframe.style.height = "0";
+  iframe.style.border = "0";
+  iframe.srcdoc = html;
+
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    window.setTimeout(() => iframe.remove(), 1000);
+  };
+
+  iframe.onload = () => {
+    const win = iframe.contentWindow;
+    if (!win) {
+      iframe.remove();
+      downloadTextFile(downloadName, html, "text/html;charset=utf-8");
+      return;
+    }
+    // Settle so charts / fonts lay out, then print. `afterprint` removes the
+    // iframe once the dialog closes (a timeout backstops browsers that don't
+    // fire it).
+    win.addEventListener("afterprint", cleanup);
+    win.setTimeout(() => {
+      win.focus();
+      win.print();
+      window.setTimeout(cleanup, 60000);
+    }, PRINT_SETTLE_MS);
+  };
+
+  document.body.appendChild(iframe);
 }
 
 /* ------------------------------- segments -------------------------------- */
@@ -168,6 +236,7 @@ async function buildHtmlDocument(
   resolver: EmbedResolver,
   title: string,
   userLabel: string,
+  brand?: ExportBrand,
 ): Promise<string> {
   const articles: string[] = [];
   for (const message of messages) {
@@ -179,11 +248,14 @@ async function buildHtmlDocument(
         `<div class="content">${body}</div></article>`,
     );
   }
+  const logo = brand?.logoDataUrl
+    ? `<img class="doc-logo" src="${escapeHtml(brand.logoDataUrl)}" alt="">`
+    : "";
   return (
     `<!doctype html><html lang="en"><head><meta charset="utf-8">` +
     `<meta name="viewport" content="width=device-width, initial-scale=1">` +
-    `<title>${escapeHtml(title)}</title><style>${PRINT_CSS}</style></head>` +
-    `<body><header class="doc-header"><h1>${escapeHtml(title)}</h1>` +
+    `<title>${escapeHtml(title)}</title><style>${buildDocumentCss(brand)}</style></head>` +
+    `<body><header class="doc-header">${logo}<h1>${escapeHtml(title)}</h1>` +
     `<div class="doc-meta">Exported ${escapeHtml(new Date().toLocaleString())}</div>` +
     `</header><main>${articles.join("")}</main></body></html>`
   );
@@ -417,15 +489,10 @@ function downloadTextFile(filename: string, content: string, mime: string): void
   window.setTimeout(() => URL.revokeObjectURL(url), 1000);
 }
 
-/** Placeholder shown in the print tab while embeds resolve. */
-const PREPARING_HTML =
-  '<!doctype html><html><head><meta charset="utf-8"><title>Preparing export...</title>' +
-  "<style>body{font:14px system-ui,sans-serif;color:#475569;display:flex;" +
-  "height:100vh;margin:0;align-items:center;justify-content:center}</style></head>" +
-  "<body>Preparing export...</body></html>";
-
 /**
- * Inline stylesheet for the exported document. Tuned for print:
+ * Build the inline stylesheet for the exported document, folding in optional
+ * brand color / font overrides (falling back to the neutral slate/blue theme
+ * and a system font stack). Tuned for print:
  *
  *   - A readable measure with role-labelled message blocks.
  *   - Content flows naturally across pages: whole messages are NOT
@@ -436,23 +503,30 @@ const PREPARING_HTML =
  *     rows - while long tables split across pages and repeat their
  *     header (`thead { display: table-header-group }`).
  *   - `@page { margin: 0 }` collapses the page margin box so the
- *     browser's own print header/footer (the `about:blank` URL, the
+ *     browser's own print header/footer (the source URL, the
  *     date, and `n/N` page numbers) have nowhere to render and drop
  *     out; the visible page margin is re-supplied as body padding.
  */
-const PRINT_CSS = `
+function buildDocumentCss(brand?: ExportBrand): string {
+  const fg = brand?.foreground || "#0f172a";
+  const primary = brand?.primary || "#0f172a";
+  const link = brand?.accent || "#2563eb";
+  const font =
+    brand?.fontSans || 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif';
+  return `
   :root { color-scheme: light; }
   * { box-sizing: border-box; }
   body {
-    font: 15px/1.6 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
-    color: #0f172a; margin: 0; padding: 32px; background: #fff;
+    font: 15px/1.6 ${font};
+    color: ${fg}; margin: 0; padding: 32px; background: #fff;
   }
   main { max-width: 820px; margin: 0 auto; }
-  .doc-header { max-width: 820px; margin: 0 auto 24px; border-bottom: 1px solid #e2e8f0; padding-bottom: 12px; }
-  .doc-header h1 { font-size: 22px; margin: 0 0 4px; }
+  .doc-header { max-width: 820px; margin: 0 auto 24px; border-bottom: 2px solid ${primary}; padding-bottom: 12px; }
+  .doc-logo { height: 28px; width: auto; display: block; margin: 0 0 10px; }
+  .doc-header h1 { font-size: 22px; margin: 0 0 4px; color: ${primary}; }
   .doc-meta { font-size: 12px; color: #64748b; }
   .msg { margin: 0 0 20px; }
-  .msg .role { font-size: 12px; font-weight: 600; text-transform: uppercase; letter-spacing: .04em; color: #64748b; margin-bottom: 4px; break-after: avoid; }
+  .msg .role { font-size: 12px; font-weight: 600; text-transform: uppercase; letter-spacing: .04em; color: ${primary}; margin-bottom: 4px; break-after: avoid; }
   .msg-user .content { background: #f1f5f9; border-radius: 8px; padding: 10px 14px; }
   .msg .content > *:first-child { margin-top: 0; }
   .msg .content > *:last-child { margin-bottom: 0; }
@@ -462,7 +536,7 @@ const PRINT_CSS = `
   code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .9em; background: #f1f5f9; padding: .1em .3em; border-radius: 4px; }
   pre { background: #0f172a; color: #e2e8f0; padding: 12px 14px; border-radius: 8px; overflow-x: auto; break-inside: avoid; }
   pre code { background: none; padding: 0; color: inherit; }
-  a { color: #2563eb; }
+  a { color: ${link}; }
   .embed { margin: 12px 0; }
   .embed-chart { border: 1px solid #e2e8f0; border-radius: 8px; padding: 8px; break-inside: avoid; }
   .embed-chart svg { max-width: 100%; height: auto; display: block; margin: 0 auto; }
@@ -478,3 +552,4 @@ const PRINT_CSS = `
     a { color: inherit; text-decoration: none; }
   }
 `;
+}