@dbx-tools/ui-mastra 0.6.14 → 0.6.27

package/README.md

@@ -233,6 +233,41 @@ The UI understands the extra events produced by
 - MLflow trace headers enable per-message feedback controls when the server
   reports feedback is available.
 
+## Chart Theming
+
+An ECharts chart draws to a canvas, so it inherits nothing from CSS the way its
+frame does: a dark theme re-skins the border around the chart while the axis
+labels, grid lines, and tooltip inside keep whatever colors the spec was born
+with. And the spec is born on the server, in
+[`@dbx-tools/appkit-mastra`](../../node/appkit-mastra), which cannot know the
+reader's theme.
+
+So the two halves are split. The planner inlines only what is
+theme-independent - the brand's series palette and font stack. Everything
+theme-dependent is resolved here at render time by `src/support/chart-theme.ts`,
+which reads AppKit's `--chart-axis-label`, `--chart-axis-title`, `--chart-grid`,
+and `--chart-tooltip-bg` (plus `--popover-foreground` and `--border` for the
+tooltip) into a `ChartChrome`, and `normalizeChartOption` paints it onto the
+axes, title, legend, and tooltip. Nothing to configure: a chart follows the
+theme wherever it renders.
+
+Two details worth knowing if you embed the chat:
+
+- Tokens are read off the **chart's own element**, not `:root`, so a theme
+  scoped to a subtree - a chat panel inside an otherwise-light app - wins. The
+  value re-resolves when a `.dark` / `.light` class lands on the document root
+  and when the OS `prefers-color-scheme` flips, so a live theme switch recolors
+  charts in place.
+- AppKit darkens its tokens under `@media (prefers-color-scheme: dark)` for any
+  `:root` that is not explicitly `.light`. If your host renders its own light
+  chrome, pin `.light` (or `.dark`) on `:root` rather than leaving AppKit on the
+  OS preference, or the chat will read as half-dark while everything around it
+  stays light.
+
+The PDF export is the one caller that does not follow the page: it pins
+`LIGHT_CHART_CHROME`, because its document forces `color-scheme: light` on a
+white body for printing.
+
 ## Export Conversations
 
 ```tsx
@@ -283,6 +318,13 @@ touching `navigator.clipboard` or `URL.createObjectURL` again.
 - `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.
+- `src/support/chart-theme.ts` - `ChartChrome`, `LIGHT_CHART_CHROME`,
+  `resolveChartChrome`, and the `useChartChrome` hook that keeps an inline
+  chart's colors in step with the active theme.
+- `src/support/chart-option.ts` - `normalizeChartOption`, the pure pass that
+  patches layout (compact ticks, axis-name placement, title/grid spacing) and
+  an optional `ChartChrome` into a planner spec, shared by the inline chart and
+  the PDF export so both read the same.
 - Types - `ChatViewProps`, `MastraChatProps`, `UseMastraChatOptions`,
   `ThreadPlacement`, `ThreadSummary`, `ToolEvent`, `ToolProgress`,
   `PendingApproval`, `FeedbackSubmission`, and related UI contract types.

package/index.ts

@@ -17,6 +17,7 @@ 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";
+export * as supportChartTheme from "./src/support/chart-theme.ts";
 export * as supportClipboard from "./src/support/clipboard.ts";
 export * as supportDownload from "./src/support/download.ts";
 export * as supportExport from "./src/support/export.ts";
@@ -45,6 +46,8 @@ 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, ThreadPlacement, ChatViewProps, ApprovalDecision, PendingApproval } from "./src/react/types.ts";
+export { LIGHT_CHART_CHROME } from "./src/support/chart-theme.ts";
+export type { ChartChrome } from "./src/support/chart-theme.ts";
 export type { ExportFormat, ExportBrand, EmbedResolver, ExportChatOptions } from "./src/support/export.ts";
 export { MastraPluginClient, useMastraConfig, useMastraClient, useMastraModels, useMastraDefaultModel, useMastraSuggestions, useMastraThreads, useChartFetch, useStatementFetch } from "./src/support/mastra-client.ts";
 export type { ByIdFetchState } from "./src/support/mastra-client.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.14",
-    "@dbx-tools/shared-mastra": "0.6.14",
-    "@dbx-tools/shared-genie": "0.6.14",
-    "@dbx-tools/ui-branding": "0.6.14",
-    "@dbx-tools/shared-model": "0.6.14",
-    "@dbx-tools/ui-appkit": "0.6.14"
+    "@dbx-tools/shared-model": "0.6.27",
+    "@dbx-tools/ui-appkit": "0.6.27",
+    "@dbx-tools/shared-mastra": "0.6.27",
+    "@dbx-tools/ui-branding": "0.6.27",
+    "@dbx-tools/shared-core": "0.6.27",
+    "@dbx-tools/shared-genie": "0.6.27"
   },
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.6.14",
+  "version": "0.6.27",
   "type": "module",
   "exports": {
     "./react": "./src/react/index.ts",

package/src/react/chat-view.tsx

@@ -342,6 +342,12 @@ export const ChatView = ({
     e.preventDefault();
     const text = input.trim();
     if (!text) return;
+    // The composer is disabled while history loads, but Enter-to-send routes
+    // here directly and a disabled textarea still receives no keydown only as
+    // long as the browser agrees - so gate the action itself too. Sending now
+    // would race the fetch and append a turn to a transcript that is about to
+    // be replaced by the loaded one.
+    if (isLoadingHistory) return;
     // Submitting while a turn streams is a steer: the driver hands the text
     // to the live run (or interrupts + resends). Idle submits start a turn.
     sendMessage({ text });
@@ -758,6 +764,7 @@ export const ChatView = ({
             <SuggestionPills
               questions={suggestions}
               onSelect={(s) => sendMessage({ text: s })}
+              disabled={isLoadingHistory}
               className="mx-auto w-full max-w-4xl px-4 pb-2 md:px-6"
             />
           )}
@@ -876,8 +883,9 @@ export const ChatView = ({
                     handleSubmit(e as unknown as React.FormEvent);
                   }
                 }}
-                placeholder="Send a message..."
+                placeholder={isLoadingHistory ? "Loading history..." : "Send a message..."}
                 rows={1}
+                disabled={isLoadingHistory}
                 className="max-h-48 text-base md:text-sm"
               />
               <InputGroupAddon align="inline-end">
@@ -904,7 +912,7 @@ export const ChatView = ({
                       type="submit"
                       size="icon-sm"
                       variant="default"
-                      disabled={!input.trim()}
+                      disabled={!input.trim() || isLoadingHistory}
                       aria-label={isRunning ? "Send now (interrupts)" : "Send message"}
                     >
                       <SendIcon className="size-3" />
@@ -920,6 +928,7 @@ export const ChatView = ({
                     <Select
                       value={model ? model : DEFAULT_MODEL_VALUE}
                       onValueChange={(v) => onModelChange?.(v === DEFAULT_MODEL_VALUE ? "" : v)}
+                      disabled={isLoadingHistory}
                     >
                       <SelectTrigger
                         size="sm"
@@ -945,6 +954,7 @@ export const ChatView = ({
                   <ExportMenu
                     onExport={(format) => void onExportConversation?.(format)}
                     tooltip="Export conversation"
+                    disabled={isLoadingHistory}
                   />
                 )}
                 {showClear && (
@@ -956,6 +966,7 @@ export const ChatView = ({
                           variant="outline"
                           size="sm"
                           onClick={() => setClearOpen(true)}
+                          disabled={isLoadingHistory}
                           className="h-7 gap-1 rounded-full px-2.5 text-xs [&_svg]:size-3"
                         >
                           <Trash2Icon className="size-3" />

package/src/react/embed-slots.tsx

@@ -2,10 +2,11 @@ import { marker as markers, type ParsedMarker } from "@dbx-tools/shared-mastra";
 import { Spinner } from "@dbx-tools/ui-appkit/react";
 import ReactECharts from "echarts-for-react";
 import { ClockIcon } from "lucide-react";
-import { useMemo } from "react";
+import { useMemo, useRef } from "react";
 import { DataGrid, humanizeLabel } from "./data-grid.tsx";
 import { AssistantMarkdown } from "./markdown.tsx";
 import { normalizeChartOption } from "../support/chart-option.ts";
+import { useChartChrome } from "../support/chart-theme.ts";
 import { useChartFetch, useStatementFetch } from "../support/mastra-client.ts";
 
 // Inline embed slots: chart / data tables resolved from `[chart:<id>]`
@@ -19,9 +20,16 @@ import { useChartFetch, useStatementFetch } from "../support/mastra-client.ts";
  * is fixed so Echarts has a deterministic canvas regardless of
  * the parent's flex layout. `not-prose` opts out of Tailwind
  * Typography.
+ *
+ * The surface is OPAQUE (`bg-card`, not a translucent
+ * `bg-background/40`). A partially transparent theme token composites
+ * against whatever the host painted underneath, so an embedded chat
+ * whose host surface disagrees with AppKit's resolved theme - a light
+ * app that never opted out of AppKit's `prefers-color-scheme: dark`
+ * fallback, say - renders the chart on a muddy mid-grey plate that
+ * matches neither theme.
  */
-const CHART_FRAME_CLASSES =
-  "not-prose my-3 max-w-full rounded border border-border/60 bg-background/40 p-2";
+const CHART_FRAME_CLASSES = "not-prose my-3 max-w-full rounded border border-border bg-card p-2";
 const CHART_HEIGHT_PX = 320;
 
 /**
@@ -73,44 +81,48 @@ const ExpiredSlot = ({ type }: { type: string }) => (
  */
 const ChartSlot = ({ chartId }: { chartId: string }) => {
   const { data: chart, loading, error } = useChartFetch(chartId);
+  // Resolved off the frame itself, so a theme scoped to this subtree
+  // (an embedded chat panel) wins over the document root's.
+  const frameRef = useRef<HTMLDivElement>(null);
+  const chrome = useChartChrome(frameRef);
   // Patch presentation (compact ticks, axis-name placement, legible
-  // category labels) into the JSON-safe planner spec before rendering,
-  // matching the export path. Memoized on the resolved option identity.
+  // category labels) and the current theme's chrome into the JSON-safe
+  // planner spec before rendering. Memoized on the resolved option and
+  // the theme, so a light/dark switch recolors the chart in place.
   const option = useMemo(
-    () => (chart?.result ? normalizeChartOption(chart.result.option) : undefined),
-    [chart?.result],
+    () => (chart?.result ? normalizeChartOption(chart.result.option, chrome) : undefined),
+    [chart?.result, chrome],
   );
-  if (option) {
-    return (
-      <div className={CHART_FRAME_CLASSES}>
+  // Settled 404 (unknown / TTL-expired id) -> small "expired" notice.
+  // Hard-error / non-terminal payloads render nothing.
+  if (!option && !loading) {
+    return !error && chart === undefined ? <ExpiredSlot type="chart" /> : null;
+  }
+  // One frame for both states: the chart's footprint is known ahead of
+  // time, so an in-flight fetch reserves it with a spinner rather than
+  // collapsing, and the chart fades in without shifting the prose
+  // below. Keeping it a single element also keeps `frameRef` mounted
+  // across the transition, so the theme is already resolved when the
+  // spec lands.
+  return (
+    <div ref={frameRef} className={CHART_FRAME_CLASSES}>
+      {option ? (
         <ReactECharts
           option={option}
           style={{ height: CHART_HEIGHT_PX, width: "100%" }}
           notMerge
           lazyUpdate
         />
-      </div>
-    );
-  }
-  // In-flight fetch: the chart's footprint is known ahead of time, so
-  // reserve the same frame + height with a spinner instead of
-  // collapsing - the chart fades in without shifting the prose below.
-  if (loading) {
-    return (
-      <div className={CHART_FRAME_CLASSES}>
+      ) : (
         <div
           className="flex items-center justify-center"
           style={{ height: CHART_HEIGHT_PX, width: "100%" }}
         >
           <Spinner className="size-5 text-muted-foreground" />
         </div>
-      </div>
-    );
-  }
-  // Settled 404 (unknown / TTL-expired id) -> small "expired" notice.
-  // Hard-error / non-terminal payloads render nothing.
-  if (!error && chart === undefined) return <ExpiredSlot type="chart" />;
-  return null;
+      )}
+    </div>
+  );
 };
 
 /**

package/src/react/export-menu.tsx

@@ -30,18 +30,22 @@ const FORMATS: ReadonlyArray<{
  * {@link ExportFormat}. `iconOnly` renders a compact icon trigger (used
  * inside message bubbles) with the label surfaced as a tooltip; the
  * default renders an icon + "Export" text button (used in the header).
+ * `disabled` renders the trigger inert, for when there is nothing complete
+ * to export yet (a thread whose history is still loading).
  */
 export const ExportMenu = ({
   onExport,
   iconOnly = false,
   tooltip = "Export",
+  disabled = false,
 }: {
   onExport: (format: ExportFormat) => void;
   iconOnly?: boolean;
   tooltip?: string;
+  disabled?: boolean;
 }) => {
   const trigger = iconOnly ? (
-    <Button type="button" size="icon" variant="ghost" className="size-7">
+    <Button type="button" size="icon" variant="ghost" className="size-7" disabled={disabled}>
       <DownloadIcon className="size-3" />
     </Button>
   ) : (
@@ -50,6 +54,7 @@ export const ExportMenu = ({
       size="sm"
       variant="outline"
       className="h-7 gap-1 rounded-full px-2.5 text-xs [&_svg]:size-3"
+      disabled={disabled}
     >
       <DownloadIcon className="size-3" />
       Export

package/src/react/suggestion-pills.tsx

@@ -10,6 +10,12 @@ export interface SuggestionPillsProps {
   questions: string[];
   /** Invoked with the question text when a pill is clicked. */
   onSelect?: (question: string) => void;
+  /**
+   * Render the pills inert. Used while a thread's history is still loading,
+   * where a click would start a turn against a transcript that has not
+   * arrived yet.
+   */
+  disabled?: boolean;
   /** Extra classes for the wrapping flex row (layout / spacing). */
   className?: string;
 }
@@ -18,9 +24,14 @@ export interface SuggestionPillsProps {
  * Render a flex-wrapped row of suggestion pills. Pills grow vertically
  * for long questions (`h-auto` + `whitespace-normal`) and keep a
  * capsule shape that scales cleanly when text wraps to multiple lines.
- * Disabled when no `onSelect` is provided.
+ * Disabled when no `onSelect` is provided, or when `disabled` is set.
  */
-export const SuggestionPills = ({ questions, onSelect, className }: SuggestionPillsProps) => {
+export const SuggestionPills = ({
+  questions,
+  onSelect,
+  disabled = false,
+  className,
+}: SuggestionPillsProps) => {
   if (questions.length === 0) return null;
   return (
     <div className={cn("flex flex-wrap gap-1.5", className)}>
@@ -32,7 +43,7 @@ export const SuggestionPills = ({ questions, onSelect, className }: SuggestionPi
           variant="outline"
           className="h-auto max-w-full whitespace-normal rounded-2xl px-3 py-1.5 text-left text-xs font-normal leading-snug"
           onClick={() => onSelect?.(q)}
-          disabled={!onSelect}
+          disabled={disabled || !onSelect}
         >
           {q}
         </Button>

package/src/support/chart-option.ts

@@ -15,14 +15,20 @@
  *     the axis ends where they collide with the centered title;
  *   - category labels stay legible (shown, rotated, de-overlapped) rather
  *     than silently decimated when many bars share a narrow canvas;
- *   - the title and grid leave room for one another.
+ *   - the title and grid leave room for one another;
+ *   - the chrome (tick labels, axis names, grid lines, tooltip) is painted
+ *     in the reader's current theme, which a canvas cannot inherit from
+ *     CSS the way the chart's frame does.
  *
- * It only fills gaps: any field the spec already sets (an explicit
- * `axisLabel.formatter`, `nameLocation`, etc.) is preserved.
+ * Layout only fills gaps: any field the spec already sets (an explicit
+ * `axisLabel.formatter`, `nameLocation`, etc.) is preserved. Chrome
+ * colors are the exception - they OVERRIDE, because the whole point is
+ * to replace whatever was baked in at plan time with the live theme.
  *
  * @module
  */
 import { object } from "@dbx-tools/shared-core";
+import type { ChartChrome } from "./chart-theme.ts";
 
 /** Compact SI formatter shared across every value-axis tick. */
 const COMPACT_NUMBER = new Intl.NumberFormat("en-US", {
@@ -51,11 +57,30 @@ function hasTitleText(title: unknown): boolean {
   return entries.some((t) => isObj(t) && typeof t.text === "string" && t.text.trim().length > 0);
 }
 
+/**
+ * Shallow-merge `patch` over the object living at `node[key]`, treating a
+ * missing or non-object value as `{}`. Sibling fields survive, so a
+ * chrome color can be painted onto a node the layout pass already
+ * populated (an `axisLabel` that carries a `formatter`, say).
+ */
+function patched(node: unknown, key: string, patch: Obj): Obj {
+  const base = isObj(node) ? node : {};
+  const child = isObj(base[key]) ? (base[key] as Obj) : {};
+  return { ...base, [key]: { ...child, ...patch } };
+}
+
+/** {@link patched} for the `lineStyle.color` one level down. */
+function lineColored(node: unknown, key: string, color: string): Obj {
+  const base = isObj(node) ? node : {};
+  return patched(base, key, patched(base[key], "lineStyle", { color }));
+}
+
 /** Pin a title to the top-center so it clears the plot / axis names. */
-function normalizeTitle(title: unknown): unknown {
-  if (Array.isArray(title)) return title.map(normalizeTitle);
+function normalizeTitle(title: unknown, chrome?: ChartChrome): unknown {
+  if (Array.isArray(title)) return title.map((t) => normalizeTitle(t, chrome));
   if (!isObj(title)) return title;
-  return { left: "center", top: 8, ...title };
+  const next: Obj = { left: "center", top: 8, ...title };
+  return chrome ? patched(next, "textStyle", { color: chrome.axisTitle }) : next;
 }
 
 /**
@@ -78,17 +103,25 @@ function normalizeGrid(grid: unknown, opts: { hasTitle: boolean }): unknown {
 }
 
 /** Patch a single axis node in place-safe fashion (`x` or `y`). */
-function normalizeAxis(axis: Obj, pos: "x" | "y"): Obj {
-  const next: Obj = { ...axis };
+function normalizeAxis(axis: Obj, pos: "x" | "y", chrome?: ChartChrome): Obj {
+  let next: Obj = { ...axis };
   const existingLabel = isObj(next.axisLabel) ? next.axisLabel : {};
 
   if (next.type === "value") {
     // Compact big-number ticks unless the spec pinned its own formatter.
     next.axisLabel = { formatter: compactAxisLabel, ...existingLabel };
   } else if (next.type === "category") {
-    // Show every category, rotated and de-overlapped, rather than
-    // letting Echarts drop labels on a crowded axis.
-    next.axisLabel = { interval: 0, rotate: 30, hideOverlap: true, ...existingLabel };
+    // Show every category and de-overlap rather than letting Echarts
+    // drop labels on a crowded axis. Rotation is x-only: labels on a
+    // category y-axis (a horizontal bar chart, a heatmap's rows) run
+    // along their own row and have the full left margin to sit in, so
+    // tilting them only makes them harder to read.
+    next.axisLabel = {
+      interval: 0,
+      ...(pos === "x" ? { rotate: 30 } : {}),
+      hideOverlap: true,
+      ...existingLabel,
+    };
   }
 
   // Move a set axis name to a conventional spot so it never collides
@@ -102,13 +135,57 @@ function normalizeAxis(axis: Obj, pos: "x" | "y"): Obj {
       next.nameGap = next.nameGap ?? 56;
     }
   }
+
+  if (chrome) {
+    // Echarts defaults every one of these to a near-black that vanishes
+    // on a dark surface, so all four follow the theme together: the
+    // ticks and their labels, the axis name, and the split lines.
+    next = patched(next, "axisLabel", { color: chrome.axisLabel });
+    next = patched(next, "nameTextStyle", { color: chrome.axisTitle });
+    next = lineColored(next, "axisLine", chrome.grid);
+    next = lineColored(next, "axisTick", chrome.grid);
+    next = lineColored(next, "splitLine", chrome.grid);
+  }
   return next;
 }
 
 /** Apply {@link normalizeAxis} across an axis field (object or array). */
-function normalizeAxisField(axis: unknown, pos: "x" | "y"): unknown {
-  if (Array.isArray(axis)) return axis.map((a) => (isObj(a) ? normalizeAxis(a, pos) : a));
-  return isObj(axis) ? normalizeAxis(axis, pos) : axis;
+function normalizeAxisField(axis: unknown, pos: "x" | "y", chrome?: ChartChrome): unknown {
+  if (Array.isArray(axis)) return axis.map((a) => (isObj(a) ? normalizeAxis(a, pos, chrome) : a));
+  return isObj(axis) ? normalizeAxis(axis, pos, chrome) : axis;
+}
+
+/**
+ * Paint the theme onto the option nodes that are not per-axis: the base
+ * text style (which legend and series labels inherit), the legend's own
+ * labels, and the tooltip's surface, outline, and text.
+ *
+ * The base `textStyle` keeps whatever `fontFamily` the planner's brand
+ * theme set - the font is brand identity and the same in either theme;
+ * only the color is theme-dependent, so only the color is replaced.
+ */
+function normalizeChrome(option: Obj, chrome: ChartChrome): Obj {
+  const next = patched(option, "textStyle", { color: chrome.axisTitle });
+  // Legend and tooltip are patched only where the spec already declares
+  // them: in Echarts a bare `legend: {}` is a SHOWN legend, so
+  // conjuring one to hold a color would add a legend to a chart that
+  // deliberately has none.
+  if (isObj(next.legend)) {
+    next.legend = patched(next.legend, "textStyle", { color: chrome.axisLabel });
+  }
+  if (isObj(next.tooltip)) {
+    next.tooltip = {
+      ...patched(next.tooltip, "textStyle", { color: chrome.tooltipForeground }),
+      backgroundColor: chrome.tooltipBackground,
+      borderColor: chrome.tooltipBorder,
+    };
+  }
+  // A heatmap's visualMap prints its range bounds in the same near-black
+  // default as the axes, so it needs the same treatment.
+  if (isObj(next.visualMap)) {
+    next.visualMap = patched(next.visualMap, "textStyle", { color: chrome.axisLabel });
+  }
+  return next;
 }
 
 /**
@@ -117,13 +194,21 @@ function normalizeAxisField(axis: unknown, pos: "x" | "y"): unknown {
  * labels, and title/grid spacing. Pure and shallow-cloning - the input
  * (which may be a shared/cached object) is never mutated. Non-object
  * input is returned untouched.
+ *
+ * Pass `chrome` to also color the chart for a theme (see
+ * {@link ChartChrome}): the live one for an on-screen chart, or
+ * `LIGHT_CHART_CHROME` for output that is always read on white, such as
+ * the PDF export. Omit it and only layout is normalized, leaving
+ * Echarts' own near-black defaults - legible on a light surface,
+ * invisible on a dark one.
  */
-export function normalizeChartOption<T>(option: T): T {
+export function normalizeChartOption<T>(option: T, chrome?: ChartChrome): T {
   if (!isObj(option)) return option;
-  const next: Obj = { ...option };
-  next.title = normalizeTitle(next.title);
+  let next: Obj = { ...option };
+  next.title = normalizeTitle(next.title, chrome);
   next.grid = normalizeGrid(next.grid, { hasTitle: hasTitleText(next.title) });
-  next.xAxis = normalizeAxisField(next.xAxis, "x");
-  next.yAxis = normalizeAxisField(next.yAxis, "y");
+  next.xAxis = normalizeAxisField(next.xAxis, "x", chrome);
+  next.yAxis = normalizeAxisField(next.yAxis, "y", chrome);
+  if (chrome) next = normalizeChrome(next, chrome);
   return next as T;
 }

package/src/support/chart-theme.ts

@@ -0,0 +1,138 @@
+/**
+ * Live theme resolution for planner-produced Echarts specs.
+ *
+ * An Echarts chart draws to a canvas, so none of AppKit's CSS custom
+ * properties reach it the way they reach the styled DOM around it: a
+ * `.dark` root re-skins the chart's frame while the axis labels, grid
+ * lines, and tooltip inside keep whatever colors were baked into the
+ * spec. The planner (`@dbx-tools/appkit-mastra`) runs on the server and
+ * cannot know the reader's theme at all, so the spec deliberately
+ * carries only theme-INDEPENDENT identity (the brand series palette and
+ * font stack) and leaves every chrome color to be resolved here.
+ *
+ * This module reads AppKit's chart tokens off a live element and hands
+ * the result to `normalizeChartOption`, which paints them onto the axes,
+ * title, legend, and tooltip. Reading from the CHART's own element
+ * rather than `:root` matters because a host may scope `.dark` to a
+ * subtree (an embedded chat panel inside an otherwise-light app);
+ * custom properties inherit, so the chart element always sees the theme
+ * that actually applies to it.
+ *
+ * @module
+ */
+import { object } from "@dbx-tools/shared-core";
+import { type RefObject, useEffect, useState } from "react";
+
+/**
+ * The theme-dependent colors an Echarts spec needs, resolved from
+ * AppKit's stylesheet. Deliberately chrome only - series colors are
+ * brand identity and stay as the planner emitted them.
+ */
+export interface ChartChrome {
+  /** Tick labels and legend entries. */
+  axisLabel: string;
+  /** Chart title and axis names - the stronger of the two foregrounds. */
+  axisTitle: string;
+  /** Split lines, axis lines, and ticks. */
+  grid: string;
+  /** Tooltip surface. */
+  tooltipBackground: string;
+  /** Tooltip text. */
+  tooltipForeground: string;
+  /** Tooltip outline. */
+  tooltipBorder: string;
+}
+
+/**
+ * AppKit's light-theme chart chrome (`:root` in
+ * `@databricks/appkit-ui/dist/styles.css`), as literals.
+ *
+ * Two jobs: the fallback for every token that fails to resolve (a host
+ * that never imported AppKit's stylesheet), and the fixed theme for
+ * server-side rendering, where there is no document to read and the
+ * output - a PDF export - is printed on white regardless of the
+ * reader's theme.
+ */
+export const LIGHT_CHART_CHROME: ChartChrome = {
+  axisLabel: "hsla(240, 4%, 46%, 1)",
+  axisTitle: "hsla(240, 6%, 10%, 1)",
+  grid: "hsla(240, 5%, 90%, 1)",
+  tooltipBackground: "hsla(0, 0%, 100%, 1)",
+  tooltipForeground: "hsla(240, 6%, 10%, 1)",
+  tooltipBorder: "hsla(240, 5%, 90%, 1)",
+};
+
+/**
+ * Which AppKit custom property backs each {@link ChartChrome} field.
+ * The first four are AppKit's dedicated chart tokens; the tooltip's text
+ * and outline reuse the generic popover/border tokens, which AppKit
+ * redefines under `.dark` alongside them.
+ */
+const CHROME_TOKENS: Record<keyof ChartChrome, string> = {
+  axisLabel: "--chart-axis-label",
+  axisTitle: "--chart-axis-title",
+  grid: "--chart-grid",
+  tooltipBackground: "--chart-tooltip-bg",
+  tooltipForeground: "--popover-foreground",
+  tooltipBorder: "--border",
+};
+
+/**
+ * Read AppKit's chart tokens as they resolve for `element`, falling back
+ * to {@link LIGHT_CHART_CHROME} per-token when one is unset. Pass the
+ * chart's own container so a theme scoped to a subtree is honored;
+ * `null` (not yet mounted) reads the document root instead.
+ */
+export function resolveChartChrome(element: Element | null): ChartChrome {
+  if (typeof window === "undefined") return LIGHT_CHART_CHROME;
+  const target = element ?? document.documentElement;
+  const styles = window.getComputedStyle(target);
+  const chrome = { ...LIGHT_CHART_CHROME };
+  for (const [field, token] of Object.entries(CHROME_TOKENS)) {
+    const value = styles.getPropertyValue(token).trim();
+    if (value) chrome[field as keyof ChartChrome] = value;
+  }
+  return chrome;
+}
+
+/** Root attributes whose change can re-theme the tokens below them. */
+const THEME_ATTRIBUTES = ["class", "style", "data-theme", "data-brand"];
+
+/**
+ * Resolve the chart chrome for `ref`'s element and keep it current as
+ * the theme changes.
+ *
+ * Two triggers, matching the two ways AppKit's stylesheet switches
+ * themes: an explicit `.dark` / `.light` class (watched with a
+ * `MutationObserver` on the document root, which is where hosts toggle
+ * it) and the OS preference that `:root:not(.light)` falls back to
+ * (watched with `matchMedia`). The resolved value is compared
+ * structurally before being stored, so an unrelated attribute change
+ * does not hand callers a new object and re-render every chart.
+ *
+ * Returns {@link LIGHT_CHART_CHROME} on the first render - the effect
+ * that reads the real tokens runs after mount, by which point the chart
+ * itself is usually still long-polling its spec.
+ */
+export function useChartChrome(ref: RefObject<Element | null>): ChartChrome {
+  const [chrome, setChrome] = useState<ChartChrome>(LIGHT_CHART_CHROME);
+  useEffect(() => {
+    const read = () => {
+      const next = resolveChartChrome(ref.current);
+      setChrome((prev) => (object.deepEqual(prev, next) ? prev : next));
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: THEME_ATTRIBUTES,
+    });
+    const media = window.matchMedia("(prefers-color-scheme: dark)");
+    media.addEventListener("change", read);
+    return () => {
+      observer.disconnect();
+      media.removeEventListener("change", read);
+    };
+  }, [ref]);
+  return chrome;
+}

package/src/support/export.ts

@@ -29,6 +29,7 @@ import type { UIMessage } from "ai";
 import * as echarts from "echarts";
 import { marked } from "marked";
 import { normalizeChartOption } from "./chart-option.ts";
+import { LIGHT_CHART_CHROME } from "./chart-theme.ts";
 import { downloadFile } from "./download.ts";
 
 /**
@@ -295,7 +296,12 @@ function markdownToHtml(md: string): string {
  * via server-side rendering (no DOM). The JSON-safe planner spec is run
  * through {@link normalizeChartOption} first - same as the live inline
  * chart - so the export gets compact value ticks, conventionally-placed
- * axis names, and legible category labels rather than a raw spec. Returns
+ * axis names, and legible category labels rather than a raw spec.
+ *
+ * The theme is pinned LIGHT rather than read from the page: the document
+ * this SVG lands in forces `color-scheme: light` on a white body because
+ * it is headed for a printer or a PDF, so a chart themed for the
+ * reader's dark UI would come out as pale labels on white. Returns
  * `null` when the id is unknown / expired / still processing, or if
  * rendering throws.
  */
@@ -310,7 +316,9 @@ async function chartSvg(resolver: EmbedResolver, id: string): Promise<string | n
       height: CHART_HEIGHT_PX,
     });
     try {
-      instance.setOption(normalizeChartOption(chart.result.option) as echarts.EChartsCoreOption);
+      instance.setOption(
+        normalizeChartOption(chart.result.option, LIGHT_CHART_CHROME) as echarts.EChartsCoreOption,
+      );
       return instance.renderToSVGString();
     } finally {
       instance.dispose();