@assistant-ui/react-devtools 1.2.6 → 1.2.7

package/src/data/useDevToolsClient.ts

@@ -0,0 +1,59 @@
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+import { inProcessClient } from "./createInProcessClient";
+import { EMPTY_SNAPSHOT, type ApiInfo, type DevToolsClient } from "./types";
+
+export interface DevToolsClientResult {
+  apiIds: number[];
+  selected: ApiInfo | undefined;
+  clearEvents: (apiId: number) => void;
+  switchToThread: (apiId: number, threadId: string) => void | Promise<void>;
+}
+
+/**
+ * Reads a DevToolsClient snapshot and resolves the selected instance. The panel
+ * depends only on this, so swapping the client swaps the data source without
+ * touching the UI. Pass a stable client reference (the default in-process client
+ * is a module singleton; memoize custom clients).
+ */
+export const useDevToolsClient = (
+  selectedApiId: number | null,
+  client: DevToolsClient = inProcessClient,
+): DevToolsClientResult => {
+  // Bind the client methods so class-based or relay clients that rely on `this`
+  // work, and keep the references stable so useSyncExternalStore does not
+  // resubscribe on every render.
+  const store = useMemo(
+    () => ({
+      subscribe: (listener: () => void) => client.subscribe(listener),
+      getSnapshot: () => client.getSnapshot(),
+      getServerSnapshot: () =>
+        client.getServerSnapshot ? client.getServerSnapshot() : EMPTY_SNAPSHOT,
+    }),
+    [client],
+  );
+
+  const snapshot = useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getServerSnapshot,
+  );
+
+  const selected =
+    selectedApiId !== null ? snapshot.byId.get(selectedApiId) : undefined;
+
+  const clearEvents = useCallback(
+    (apiId: number) => client.clearEvents(apiId),
+    [client],
+  );
+
+  const switchToThread = useCallback(
+    (apiId: number, threadId: string) => {
+      if (client.switchToThread) {
+        return client.switchToThread(apiId, threadId);
+      }
+    },
+    [client],
+  );
+
+  return { apiIds: snapshot.apiIds, selected, clearEvents, switchToThread };
+};

package/src/index.ts

@@ -1,17 +1,20 @@
-export { DevToolsModal } from "./DevToolsModal";
-export { DevToolsFrame } from "./DevToolsFrame";
-export { FrameHost } from "./FrameHost";
-export { DevToolsHost } from "./DevToolsHost";
-export { ExtensionHost } from "./ExtensionHost";
-export { FrameClient } from "./FrameClient";
+export { DevToolsModal, type DevToolsModalProps } from "./DevToolsModal";
+export { DevToolsPanel, type DevToolsPanelProps } from "./shell/DevToolsPanel";
+export { ShadowRoot } from "./shell/ShadowRoot";
+export {
+  builtinPlugins,
+  createDevToolsPlugin,
+  type DevToolsPanelPlugin,
+  type DevToolsTabContext,
+} from "./shell/registry";
+export type { ApiInfo, DevToolsClient, DevToolsSnapshot } from "./data/types";
+export {
+  createInProcessClient,
+  inProcessClient,
+} from "./data/createInProcessClient";
 export {
   normalizeToolList,
   type NormalizedTool,
 } from "./utils/toolNormalization";
-export {
-  sanitizeForMessage,
-  serializeModelContext,
-} from "./utils/serialization";
-// Export types
-export type { SerializedModelContext, TabType, ViewMode } from "./types";
-export * from "./constants";
+export { serializeModelContext } from "./utils/serialization";
+export type { SerializedModelContext } from "./types";

package/src/shell/DevToolsOverlay.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { DevToolsPanel } from "./DevToolsPanel";
+import type { DevToolsPanelPlugin } from "./registry";
+import type { DevToolsClient } from "../data/types";
+
+export interface DevToolsOverlayProps {
+  plugins?: DevToolsPanelPlugin[] | undefined;
+  theme: "light" | "dark";
+  client?: DevToolsClient | undefined;
+}
+
+/**
+ * The full devtools surface (floating launcher + window), rendered inside the
+ * shadow root so every element is styled with the package's own Tailwind tokens
+ * and isolated from the host page. The window floats over the live app with no
+ * backdrop; close with the × or Escape.
+ */
+export const DevToolsOverlay = ({
+  plugins,
+  theme,
+  client,
+}: DevToolsOverlayProps) => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setIsOpen(false);
+    };
+    document.addEventListener("keydown", handleEscape);
+    return () => document.removeEventListener("keydown", handleEscape);
+  }, [isOpen]);
+
+  if (!isOpen) {
+    return (
+      <button
+        type="button"
+        onClick={() => setIsOpen(true)}
+        aria-label="Open assistant-ui DevTools"
+        title="Open assistant-ui DevTools"
+        className="bg-foreground text-background fixed end-5 bottom-5 z-[2147483646] flex size-9 [animation:aui-dt-launcher-in_200ms_cubic-bezier(0.175,0.885,0.32,1.1)] items-center justify-center rounded-full shadow-[var(--shadow-launcher)] backdrop-blur-2xl transition-transform duration-150 ease-out hover:scale-105 active:scale-95"
+      >
+        <svg
+          width="18"
+          height="18"
+          viewBox="0 0 24 24"
+          fill="none"
+          aria-hidden="true"
+        >
+          <path
+            d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"
+            stroke="currentColor"
+            strokeWidth="1.75"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          />
+        </svg>
+      </button>
+    );
+  }
+
+  return (
+    <>
+      <div
+        onClick={() => setIsOpen(false)}
+        className="fixed inset-0 z-[2147483646] [animation:aui-dt-fade-in_150ms_ease-out] bg-black/20 backdrop-blur-[3px]"
+      />
+      <div
+        role="dialog"
+        aria-label="assistant-ui DevTools"
+        className="bg-background text-foreground border-border fixed top-1/2 left-1/2 z-[2147483647] flex h-[min(560px,80vh)] w-[min(960px,92vw)] -translate-x-1/2 -translate-y-1/2 [animation:aui-dt-window-in_200ms_cubic-bezier(0.175,0.885,0.32,1.1)] flex-col overflow-hidden rounded-xl border shadow-[var(--shadow-window)]"
+      >
+        <DevToolsPanel
+          theme={theme}
+          plugins={plugins}
+          client={client}
+          onClose={() => setIsOpen(false)}
+        />
+      </div>
+    </>
+  );
+};

package/src/shell/DevToolsPanel.tsx

@@ -0,0 +1,192 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import clsx from "clsx";
+import { useDevToolsClient } from "../data/useDevToolsClient";
+import { inProcessClient } from "../data/createInProcessClient";
+import type { DevToolsClient } from "../data/types";
+import { CenteredMessage } from "../views/ui";
+import {
+  builtinPlugins,
+  type DevToolsPanelPlugin,
+  type DevToolsTabContext,
+} from "./registry";
+
+export interface DevToolsPanelProps {
+  /** Additional inspector tabs appended after the builtins. */
+  plugins?: DevToolsPanelPlugin[] | undefined;
+  /** Resolved theme, used to style plugin content and the dark variant. */
+  theme?: "light" | "dark";
+  /** When provided, a close control is rendered at the end of the tab bar. */
+  onClose?: (() => void) | undefined;
+  /** Data source. Defaults to the in-process DevToolsHooks client. */
+  client?: DevToolsClient | undefined;
+}
+
+export const DevToolsPanel = ({
+  plugins,
+  theme = "light",
+  onClose,
+  client,
+}: DevToolsPanelProps) => {
+  const resolvedClient = client ?? inProcessClient;
+  const [selectedApiId, setSelectedApiId] = useState<number | null>(null);
+  const [activeTabId, setActiveTabId] = useState<string>("thread");
+  const [selectionByApi, setSelectionByApi] = useState<
+    Record<number, Record<string, string | null>>
+  >({});
+  const { apiIds, selected, clearEvents, switchToThread } = useDevToolsClient(
+    selectedApiId,
+    resolvedClient,
+  );
+
+  useEffect(() => {
+    if (selectedApiId !== null && apiIds.includes(selectedApiId)) return;
+    setSelectedApiId(apiIds[0] ?? null);
+  }, [apiIds, selectedApiId]);
+
+  const allPlugins = useMemo(
+    () =>
+      [...builtinPlugins, ...(plugins ?? [])].sort(
+        (a, b) => (a.order ?? 0) - (b.order ?? 0),
+      ),
+    [plugins],
+  );
+
+  const setSelectionFor = useCallback(
+    (apiId: number, tabId: string, nodeId: string | null) => {
+      setSelectionByApi((prev) => ({
+        ...prev,
+        [apiId]: { ...prev[apiId], [tabId]: nodeId },
+      }));
+    },
+    [],
+  );
+
+  const visiblePlugins =
+    selected && selectedApiId !== null
+      ? allPlugins.filter((plugin) =>
+          plugin.isAvailable
+            ? plugin.isAvailable({
+                apiId: selectedApiId,
+                data: selected,
+                clearEvents,
+                theme,
+                selection: null,
+                setSelection: () => {},
+              })
+            : true,
+        )
+      : allPlugins;
+
+  const activePlugin =
+    visiblePlugins.find((plugin) => plugin.id === activeTabId) ??
+    visiblePlugins[0];
+
+  const ctx: DevToolsTabContext | null =
+    selected && selectedApiId !== null && activePlugin
+      ? {
+          apiId: selectedApiId,
+          data: selected,
+          clearEvents,
+          theme,
+          selection: selectionByApi[selectedApiId]?.[activePlugin.id] ?? null,
+          setSelection: (nodeId) =>
+            setSelectionFor(selectedApiId, activePlugin.id, nodeId),
+          switchToThread: resolvedClient.switchToThread
+            ? (threadId) => switchToThread(selectedApiId, threadId)
+            : undefined,
+        }
+      : null;
+
+  return (
+    <div className="text-foreground flex h-full flex-col text-[13px]">
+      <nav className="border-border flex h-10 shrink-0 items-center justify-between gap-2 border-b px-2 select-none">
+        <div className="flex h-full items-center">
+          {visiblePlugins.map((plugin) => {
+            const active = activePlugin?.id === plugin.id;
+            return (
+              <button
+                type="button"
+                key={plugin.id}
+                onClick={() => setActiveTabId(plugin.id)}
+                className={clsx(
+                  "relative flex h-full items-center px-3 font-medium transition-colors",
+                  active
+                    ? "text-foreground"
+                    : "text-muted-foreground hover:text-foreground",
+                )}
+              >
+                {plugin.label}
+                {active ? (
+                  <span className="bg-foreground absolute inset-x-2 -bottom-px h-0.5 rounded-full" />
+                ) : null}
+              </button>
+            );
+          })}
+        </div>
+
+        <div className="flex items-center gap-2 pe-1">
+          {apiIds.length > 1 ? (
+            <select
+              value={selectedApiId ?? ""}
+              onChange={(event) => {
+                const value = Number(event.target.value);
+                setSelectedApiId(Number.isNaN(value) ? null : value);
+              }}
+              className="border-border text-muted-foreground hover:text-foreground h-7 rounded-md border bg-transparent px-2 text-[12px] transition-colors"
+            >
+              {apiIds.map((id) => (
+                <option key={id} value={id}>
+                  API #{id}
+                </option>
+              ))}
+            </select>
+          ) : null}
+
+          <span className="text-muted-foreground flex items-center gap-1.5 text-[11px]">
+            <span className="size-1.5 rounded-full bg-emerald-500" />
+            {apiIds.length > 0
+              ? `${apiIds.length} instance${apiIds.length > 1 ? "s" : ""}`
+              : "Waiting"}
+          </span>
+
+          {onClose ? (
+            <button
+              type="button"
+              onClick={onClose}
+              aria-label="Close DevTools"
+              className="text-muted-foreground hover:bg-accent hover:text-foreground flex size-7 items-center justify-center rounded-md transition-colors"
+            >
+              <svg
+                width="14"
+                height="14"
+                viewBox="0 0 24 24"
+                fill="none"
+                aria-hidden="true"
+              >
+                <path
+                  d="M18 6 6 18M6 6l12 12"
+                  stroke="currentColor"
+                  strokeWidth="1.75"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                />
+              </svg>
+            </button>
+          ) : null}
+        </div>
+      </nav>
+
+      <section className="bg-background min-h-0 flex-1 overflow-hidden">
+        {ctx && activePlugin ? (
+          <activePlugin.Component {...ctx} />
+        ) : (
+          <CenteredMessage>
+            Waiting for assistant-ui instance...
+          </CenteredMessage>
+        )}
+      </section>
+    </div>
+  );
+};

package/src/shell/ShadowRoot.tsx

@@ -0,0 +1,85 @@
+"use client";
+
+import { useEffect, useRef, type CSSProperties, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { panelCss } from "../styles/panel.generated";
+
+const PROPERTY_STYLE_ID = "assistant-ui-devtools-properties";
+
+/**
+ * Tailwind registers typed `@property --tw-*` custom properties. These register
+ * globally and are unreliable when declared only inside a shadow root, so a copy
+ * is hoisted to the document head once. The rest of the sheet stays scoped to
+ * the shadow root.
+ */
+const hoistAtProperties = () => {
+  if (document.getElementById(PROPERTY_STYLE_ID)) return;
+  const rules = panelCss.match(/@property\s+--[^{]+\{[^}]*\}/g);
+  if (!rules?.length) return;
+  const style = document.createElement("style");
+  style.id = PROPERTY_STYLE_ID;
+  style.textContent = rules.join("");
+  document.head.appendChild(style);
+};
+
+export interface ShadowRootProps {
+  theme: "light" | "dark";
+  className?: string;
+  style?: CSSProperties;
+  children: ReactNode;
+}
+
+/**
+ * Renders its children into an isolated shadow root with the compiled panel
+ * stylesheet. A dedicated React root is mounted inside the shadow root so
+ * React's event delegation works (a portal from the outer root would leave the
+ * listeners in the light DOM, where shadow retargeting breaks them).
+ */
+export const ShadowRoot = ({
+  theme,
+  className,
+  style,
+  children,
+}: ShadowRootProps) => {
+  const hostRef = useRef<HTMLDivElement | null>(null);
+  const rootRef = useRef<Root | null>(null);
+  const mountRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) return;
+
+    const shadow = host.shadowRoot ?? host.attachShadow({ mode: "open" });
+    if (!shadow.querySelector("style[data-aui-devtools]")) {
+      const styleEl = document.createElement("style");
+      styleEl.setAttribute("data-aui-devtools", "");
+      styleEl.textContent = panelCss;
+      shadow.appendChild(styleEl);
+    }
+    hoistAtProperties();
+
+    const mount = document.createElement("div");
+    mount.style.display = "contents";
+    shadow.appendChild(mount);
+    mountRef.current = mount;
+    rootRef.current = createRoot(mount);
+
+    return () => {
+      const root = rootRef.current;
+      rootRef.current = null;
+      mountRef.current = null;
+      queueMicrotask(() => {
+        root?.unmount();
+        mount.remove();
+      });
+    };
+  }, []);
+
+  useEffect(() => {
+    const mount = mountRef.current;
+    if (mount) mount.className = theme === "dark" ? "dark" : "";
+    rootRef.current?.render(children);
+  }, [children, theme]);
+
+  return <div ref={hostRef} className={className} style={style} />;
+};

package/src/shell/SplitLayout.tsx

@@ -0,0 +1,46 @@
+import clsx from "clsx";
+import type { ReactNode } from "react";
+
+/** Shared nav rail + detail track sizing for the master/detail tabs. */
+export const NAV_COL = "clamp(14rem,28%,18rem)_minmax(0,1fr)";
+
+export interface SplitColumn {
+  key: string;
+  /** Fixed rail header; stays aligned across columns. */
+  header?: ReactNode | undefined;
+  /** Scrollable pane body. */
+  children: ReactNode;
+}
+
+/**
+ * Multi-column split surface. Each column keeps its header fixed and only the
+ * body scrolls, so rail titles and divider lines stay aligned across columns.
+ */
+export const SplitLayout = ({
+  sizes,
+  columns,
+  className,
+}: {
+  /** Underscore-separated CSS grid track list, e.g. `12rem_minmax(0,1fr)`. */
+  sizes: string;
+  columns: SplitColumn[];
+  className?: string | undefined;
+}) => (
+  <div
+    className={clsx("grid h-full min-h-0", className)}
+    style={{ gridTemplateColumns: sizes.split("_").join(" ") }}
+  >
+    {columns.map((column, index) => (
+      <div
+        key={column.key}
+        className={clsx(
+          "flex min-h-0 flex-col overflow-hidden",
+          index < columns.length - 1 && "border-border border-e",
+        )}
+      >
+        {column.header}
+        <div className="min-h-0 flex-1 overflow-y-auto">{column.children}</div>
+      </div>
+    ))}
+  </div>
+);

package/src/shell/registry.ts

@@ -0,0 +1,51 @@
+import type { ComponentType } from "react";
+import type { ApiInfo } from "../data/types";
+import { ActivityTab } from "./tabs/ActivityTab";
+import { ContextTab } from "./tabs/ContextTab";
+import { RawTab } from "./tabs/RawTab";
+import { ThreadTab } from "./tabs/ThreadTab";
+
+export interface DevToolsTabContext {
+  /** The id of the assistant instance the panel is currently inspecting. */
+  apiId: number;
+  /** Projected, render-ready data for the inspected instance. */
+  data: ApiInfo;
+  /** Clears the buffered event log for an instance. */
+  clearEvents: (apiId: number) => void;
+  /** The resolved theme of the panel. */
+  theme: "light" | "dark";
+  /**
+   * The selected node id for this tab and instance, or null. Always a stable id
+   * (message id, run id, slice key, …), never an array index, so the detail
+   * pane does not jump as data streams in.
+   */
+  selection: string | null;
+  /** Selects a node in this tab. Pass null to clear. Persisted per instance. */
+  setSelection: (nodeId: string | null) => void;
+  /** Switches the live app to a thread, when the runtime supports thread lists. */
+  switchToThread?: ((threadId: string) => void | Promise<void>) | undefined;
+}
+
+export interface DevToolsPanelPlugin {
+  /** Stable identifier used as the tab key. */
+  id: string;
+  /** Tab label shown in the navigation bar. */
+  label: string;
+  /** Lower numbers sort earlier; builtins occupy 10, 20, 30, 40. */
+  order?: number;
+  /** When provided and it returns false, the tab is hidden for the current instance. */
+  isAvailable?: (ctx: DevToolsTabContext) => boolean;
+  /** The tab body. Receives the tab context as props. */
+  Component: ComponentType<DevToolsTabContext>;
+}
+
+export const createDevToolsPlugin = (
+  plugin: DevToolsPanelPlugin,
+): DevToolsPanelPlugin => plugin;
+
+export const builtinPlugins: DevToolsPanelPlugin[] = [
+  { id: "thread", label: "Thread", order: 10, Component: ThreadTab },
+  { id: "context", label: "Context", order: 20, Component: ContextTab },
+  { id: "activity", label: "Activity", order: 30, Component: ActivityTab },
+  { id: "raw", label: "Raw", order: 40, Component: RawTab },
+];

package/src/shell/tabs/ActivityTab.test.tsx

@@ -0,0 +1,34 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ActivityTab } from "./ActivityTab";
+
+const base = 2_000_000_000_000;
+const t = (ms: number) => new Date(base + ms);
+
+describe("ActivityTab", () => {
+  it("renders a split layout with runs and an event stream", () => {
+    const html = renderToStaticMarkup(
+      <ActivityTab
+        apiId={1}
+        data={{
+          id: 1,
+          logs: [
+            { time: t(0), event: "thread.runStart", data: { threadId: "T1" } },
+            { time: t(150), event: "composer.send", data: { threadId: "T1" } },
+            { time: t(900), event: "thread.runEnd", data: { threadId: "T1" } },
+          ],
+          state: {},
+        }}
+        clearEvents={() => {}}
+        theme="light"
+        selection={null}
+        setSelection={() => {}}
+      />,
+    );
+
+    expect(html).toContain("All events");
+    expect(html).toContain("Run #0");
+    expect(html).toContain("900ms");
+    expect(html).toContain("send");
+  });
+});