@assistant-ui/react-devtools 1.2.6 → 1.2.7

package/src/DevToolsModal.tsx

@@ -1,183 +1,26 @@
 "use client";
 
-import { useEffect, useMemo, useState, useSyncExternalStore } from "react";
-import { DevToolsFrame } from "./DevToolsFrame";
-import { getStyles, ANIMATION_STYLES } from "./styles/DevToolsModal.styles";
-
-const isDarkMode = (): boolean => {
-  if (typeof document === "undefined") return false;
-  return (
-    document.documentElement.classList.contains("dark") ||
-    document.body.classList.contains("dark")
-  );
-};
-
-const subscribeToThemeChanges = (callback: () => void) => {
-  if (typeof MutationObserver === "undefined") {
-    return () => {};
-  }
-
-  const observer = new MutationObserver(callback);
-
-  observer.observe(document.documentElement, {
-    attributes: true,
-    attributeFilter: ["class"],
-  });
-
-  if (document.body !== document.documentElement) {
-    observer.observe(document.body, {
-      attributes: true,
-      attributeFilter: ["class"],
-    });
-  }
-
-  return () => observer.disconnect();
-};
-
-const DevToolsModalImpl = () => {
-  const [isOpen, setIsOpen] = useState(false);
-  const [buttonHover, setButtonHover] = useState(false);
-  const [closeHover, setCloseHover] = useState(false);
-
-  const darkMode = useSyncExternalStore(
-    subscribeToThemeChanges,
-    isDarkMode,
-    () => false, // Server-side always returns false
-  );
-
-  const styles = useMemo(() => getStyles(darkMode), [darkMode]);
-
-  useEffect(() => {
-    if (typeof document === "undefined") return;
-
-    const styleId = "devtools-modal-animations";
-    if (!document.getElementById(styleId)) {
-      const style = document.createElement("style");
-      style.id = styleId;
-      style.textContent = ANIMATION_STYLES;
-      document.head.appendChild(style);
-    }
-
-    return () => {
-      const style = document.getElementById(styleId);
-      if (style && !document.querySelector("[data-devtools-modal]")) {
-        style.remove();
-      }
-    };
-  }, []);
-
-  useEffect(() => {
-    if (!isOpen) return;
-
-    const handleEscape = (event: KeyboardEvent) => {
-      if (event.key === "Escape") {
-        setIsOpen(false);
-      }
-    };
-
-    document.addEventListener("keydown", handleEscape);
-    return () => document.removeEventListener("keydown", handleEscape);
-  }, [isOpen]);
-
-  return (
-    <>
-      <div style={styles.floatingContainer}>
-        <button
-          type="button"
-          onClick={() => setIsOpen(true)}
-          onMouseEnter={() => setButtonHover(true)}
-          onMouseLeave={() => setButtonHover(false)}
-          style={{
-            ...styles.floatingButton,
-            ...(buttonHover ? styles.floatingButtonHover : {}),
-          }}
-          aria-label="Open assistant-ui DevTools"
-          title="Open assistant-ui DevTools"
-        >
-          <svg
-            aria-hidden="true"
-            width="20"
-            height="20"
-            viewBox="0 0 24 24"
-            fill="none"
-            xmlns="http://www.w3.org/2000/svg"
-            style={{ width: "20px", height: "20px" }}
-          >
-            <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.8"
-              strokeLinecap="round"
-              strokeLinejoin="round"
-              fill="none"
-            />
-          </svg>
-        </button>
-      </div>
-
-      {isOpen && (
-        <>
-          <div style={styles.backdrop} onClick={() => setIsOpen(false)} />
-
-          <div style={styles.modal} data-devtools-modal>
-            <button
-              type="button"
-              onClick={() => setIsOpen(false)}
-              onMouseEnter={() => setCloseHover(true)}
-              onMouseLeave={() => setCloseHover(false)}
-              style={{
-                ...styles.dismissButton,
-                ...(closeHover ? styles.dismissButtonHover : {}),
-              }}
-              aria-label="Close DevTools"
-            >
-              <svg
-                aria-hidden="true"
-                width="14"
-                height="14"
-                viewBox="0 0 24 24"
-                fill="none"
-                xmlns="http://www.w3.org/2000/svg"
-              >
-                <path
-                  d="M18 6L6 18"
-                  stroke="currentColor"
-                  strokeWidth="1.6"
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                />
-                <path
-                  d="M6 6L18 18"
-                  stroke="currentColor"
-                  strokeWidth="1.6"
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                />
-              </svg>
-            </button>
-
-            <div style={styles.modalContent}>
-              <DevToolsFrame
-                style={{
-                  width: "100%",
-                  height: "100%",
-                  border: "none",
-                  borderRadius: "12px",
-                  backgroundColor: "transparent",
-                }}
-              />
-            </div>
-          </div>
-        </>
-      )}
-    </>
-  );
-};
-
-// Export a component that only renders in development
-export const DevToolsModal = () => {
-  // Check if we're in production - most bundlers will replace process.env.NODE_ENV
-  // This allows the entire component to be eliminated via dead code elimination
+import { lazy, Suspense } from "react";
+import type { DevToolsPanelPlugin } from "./shell/registry";
+import type { DevToolsClient } from "./data/types";
+
+export interface DevToolsModalProps {
+  /** Extra inspector tabs appended after the builtins. */
+  plugins?: DevToolsPanelPlugin[];
+  /** Force a theme. Defaults to "system", which follows the host `.dark` class. */
+  theme?: "light" | "dark" | "system";
+  /** Data source. Defaults to the in-process DevToolsHooks client. */
+  client?: DevToolsClient;
+}
+
+const DevToolsModalImpl = lazy(() => import("./DevToolsModalImpl"));
+
+/**
+ * Dev-only. In production the body returns null before the lazy panel chunk is
+ * ever requested, so the panel and its compiled styles stay out of the
+ * production bundle (the dynamic import is also code-split).
+ */
+export const DevToolsModal = (props: DevToolsModalProps = {}) => {
   if (
     typeof process !== "undefined" &&
     process.env?.NODE_ENV === "production"
@@ -185,5 +28,9 @@ export const DevToolsModal = () => {
     return null;
   }
 
-  return <DevToolsModalImpl />;
+  return (
+    <Suspense fallback={null}>
+      <DevToolsModalImpl {...props} />
+    </Suspense>
+  );
 };

package/src/DevToolsModalImpl.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { useMemo, useSyncExternalStore } from "react";
+import { DevToolsOverlay } from "./shell/DevToolsOverlay";
+import { ShadowRoot } from "./shell/ShadowRoot";
+import type { DevToolsModalProps } from "./DevToolsModal";
+
+const isDarkMode = (): boolean => {
+  if (typeof document === "undefined") return false;
+  return (
+    document.documentElement.classList.contains("dark") ||
+    document.body.classList.contains("dark")
+  );
+};
+
+const subscribeToThemeChanges = (callback: () => void) => {
+  if (typeof MutationObserver === "undefined") {
+    return () => {};
+  }
+
+  const observer = new MutationObserver(callback);
+  observer.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ["class"],
+  });
+  if (document.body !== document.documentElement) {
+    observer.observe(document.body, {
+      attributes: true,
+      attributeFilter: ["class"],
+    });
+  }
+
+  return () => observer.disconnect();
+};
+
+const DevToolsModalImpl = ({
+  plugins,
+  theme = "system",
+  client,
+}: DevToolsModalProps) => {
+  const darkMode = useSyncExternalStore(
+    subscribeToThemeChanges,
+    isDarkMode,
+    () => false,
+  );
+  const resolved = theme === "system" ? (darkMode ? "dark" : "light") : theme;
+
+  // Stable element identity so the shadow root only re-renders on real changes,
+  // not on every render of the host tree.
+  const overlay = useMemo(
+    () => (
+      <DevToolsOverlay theme={resolved} plugins={plugins} client={client} />
+    ),
+    [resolved, plugins, client],
+  );
+
+  return <ShadowRoot theme={resolved}>{overlay}</ShadowRoot>;
+};
+
+export default DevToolsModalImpl;

package/src/data/createInProcessClient.ts

@@ -0,0 +1,66 @@
+import { DevToolsHooks } from "@assistant-ui/react";
+import { projectApi } from "./projectApi";
+import {
+  EMPTY_SNAPSHOT,
+  type ApiInfo,
+  type DevToolsClient,
+  type DevToolsSnapshot,
+} from "./types";
+
+/**
+ * The default transport: reads the in-process DevToolsHooks registry and
+ * re-projects it on every change.
+ *
+ * Projection runs inside the subscribe/change callbacks (outside React render)
+ * because the scope accessors throw when invoked during a render, and
+ * getSnapshot returns the cached result.
+ */
+export const createInProcessClient = (): DevToolsClient => {
+  let snapshot: DevToolsSnapshot = EMPTY_SNAPSHOT;
+
+  const rebuild = () => {
+    const apis = DevToolsHooks.getApis();
+    const byId = new Map<number, ApiInfo>();
+    for (const [id, entry] of apis) {
+      try {
+        byId.set(id, projectApi(id, entry));
+      } catch {
+        // Skip an api that fails to project rather than breaking the panel.
+      }
+    }
+    // apiIds tracks byId so the selector never lists an id without data.
+    snapshot = { apiIds: [...byId.keys()], byId };
+  };
+
+  return {
+    subscribe(listener) {
+      rebuild();
+      return DevToolsHooks.subscribe(() => {
+        rebuild();
+        listener();
+      });
+    },
+    getSnapshot: () => snapshot,
+    getServerSnapshot: () => EMPTY_SNAPSHOT,
+    clearEvents: (apiId) => DevToolsHooks.clearEventLogs(apiId),
+    switchToThread: (apiId, threadId) => {
+      const entry = DevToolsHooks.getApis().get(apiId);
+      const threads = entry?.api.threads;
+      if (!threads || typeof threads !== "function") return;
+      try {
+        const methods = threads() as {
+          switchToThread?: (id: string) => void | Promise<void>;
+        };
+        return Promise.resolve(methods.switchToThread?.(threadId)).catch(
+          () => {},
+        );
+      } catch {
+        // The thread scope can throw when the runtime is not ready; ignore.
+        return;
+      }
+    },
+  };
+};
+
+/** Shared default client used by DevToolsModal and DevToolsPanel. */
+export const inProcessClient = createInProcessClient();

package/src/data/projectApi.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import { projectApi } from "./projectApi";
+
+type Scope = (() => unknown) & {
+  source: string | null;
+  query: Record<string, unknown> | null;
+};
+
+const scope = (
+  source: string | null,
+  query: Record<string, unknown> | null,
+  value: unknown,
+): Scope => {
+  const fn = (() => value) as Scope;
+  fn.source = source;
+  fn.query = query;
+  return fn;
+};
+
+describe("projectApi", () => {
+  const entry = {
+    api: {
+      thread: scope(
+        "root",
+        {},
+        {
+          getState: () => ({ messages: [], isRunning: false }),
+          append: () => {},
+          getModelContext: () => ({ system: "be nice", tools: [] }),
+        },
+      ),
+      composer: scope(
+        "root",
+        {},
+        {
+          getState: () => ({ text: "hello" }),
+        },
+      ),
+      message: scope(
+        "messages",
+        { index: 0 },
+        {
+          getState: () => ({}),
+        },
+      ),
+    },
+    logs: [{ time: new Date(0), event: "thread.run-start", data: { foo: 1 } }],
+  } as unknown as Parameters<typeof projectApi>[1];
+
+  const result = projectApi(7, entry);
+
+  it("carries the api id", () => {
+    expect(result.id).toBe(7);
+  });
+
+  it("collects root-scope state by scope name", () => {
+    expect(result.state.thread).toEqual({ messages: [], isRunning: false });
+    expect(result.state.composer).toEqual({ text: "hello" });
+  });
+
+  it("omits non-root scopes from state but keeps them in the scope graph", () => {
+    expect(result.state.message).toBeUndefined();
+    const scopes = result.scopes as Array<{
+      name: string;
+      source: string | null;
+      methods: string[];
+    }>;
+    const thread = scopes.find((s) => s.name === "thread");
+    expect(thread?.source).toBe("root");
+    expect(thread?.methods).toEqual(
+      expect.arrayContaining(["getState", "append", "getModelContext"]),
+    );
+    expect(scopes.find((s) => s.name === "message")?.source).toBe("messages");
+  });
+
+  it("normalizes the model context from the thread scope", () => {
+    expect(result.modelContext).toEqual({ system: "be nice" });
+  });
+
+  it("keeps event-log timestamps as Date instances", () => {
+    expect(result.logs[0]?.time).toBeInstanceOf(Date);
+    expect(result.logs[0]?.event).toBe("thread.run-start");
+    expect(result.logs[0]?.data).toEqual({ foo: 1 });
+  });
+
+  it("does not throw on scopes whose accessor throws", () => {
+    const broken = scope("root", {}, undefined);
+    const throwing = (() => {
+      throw new Error("not mounted");
+    }) as unknown as Scope;
+    throwing.source = "derived";
+    throwing.query = null;
+    const result = projectApi(1, {
+      api: { broken, throwing },
+      logs: [],
+    } as unknown as Parameters<typeof projectApi>[1]);
+    const scopes = result.scopes as Array<{ name: string }>;
+    expect(scopes.map((s) => s.name)).toEqual(["broken", "throwing"]);
+  });
+});

package/src/data/projectApi.ts

@@ -0,0 +1,169 @@
+import type { AssistantClient } from "@assistant-ui/react";
+import { isRecord, isStringArray } from "../utils/common";
+import {
+  sanitizeAndRedact,
+  sanitizeForMessage,
+  serializeModelContext,
+} from "../utils/serialization";
+import type { ApiInfo, EventLogEntry } from "./types";
+
+interface DevToolsApiEntry {
+  api: Partial<AssistantClient>;
+  logs: ReadonlyArray<EventLogEntry>;
+}
+
+/**
+ * Lists the method names of a client proxy. The client proxy throws from its
+ * `getOwnPropertyDescriptor` trap, so `Object.keys` is best-effort and isolated
+ * from state extraction.
+ */
+const readMethods = (scopeValue: unknown): string[] => {
+  if (!scopeValue || typeof scopeValue !== "object") return [];
+  try {
+    return Object.keys(scopeValue).filter(
+      (key) =>
+        typeof (scopeValue as Record<string, unknown>)[key] === "function",
+    );
+  } catch {
+    return [];
+  }
+};
+
+type ThreadsClientMethods = {
+  __internal_getAssistantRuntime?: () => {
+    threads: {
+      getById: (threadId: string) => {
+        getState: () => {
+          messages: unknown;
+          isRunning?: boolean;
+          isLoading?: boolean;
+          isDisabled?: boolean;
+          suggestions: unknown;
+          capabilities: unknown;
+        };
+        composer: { getState: () => unknown };
+      };
+    };
+  };
+};
+
+/**
+ * Reads cached thread states for every id in the thread list. Only threads whose
+ * runtime has been mounted (visited in the app) return data; unvisited threads
+ * are omitted so DevTools can still list them from `state.threads.threadItems`.
+ */
+const collectThreadSnapshots = (
+  entry: DevToolsApiEntry,
+  state: Record<string, unknown>,
+): Record<string, unknown> | undefined => {
+  const threadsState = state.threads;
+  if (!isRecord(threadsState)) return undefined;
+
+  const threadsScope = entry.api.threads;
+  if (typeof threadsScope !== "function") return undefined;
+
+  let threadsClient: ThreadsClientMethods;
+  try {
+    threadsClient = threadsScope() as ThreadsClientMethods;
+  } catch {
+    return undefined;
+  }
+
+  const assistantRuntime = threadsClient.__internal_getAssistantRuntime?.();
+  if (!assistantRuntime) return undefined;
+
+  const threadIds = [
+    ...isStringArray(threadsState.threadIds),
+    ...isStringArray(threadsState.archivedThreadIds),
+  ];
+  if (threadIds.length === 0) return undefined;
+
+  const snapshots: Record<string, unknown> = {};
+  for (const threadId of threadIds) {
+    try {
+      const threadRuntime = assistantRuntime.threads.getById(threadId);
+      const threadState = threadRuntime.getState();
+      snapshots[threadId] = sanitizeForMessage({
+        messages: threadState.messages,
+        isRunning: threadState.isRunning,
+        isLoading: threadState.isLoading,
+        isDisabled: threadState.isDisabled,
+        suggestions: threadState.suggestions,
+        capabilities: threadState.capabilities,
+        composer: threadRuntime.composer.getState(),
+      });
+    } catch {
+      // Thread runtime not mounted yet (never opened in the app).
+    }
+  }
+
+  return Object.keys(snapshots).length > 0 ? snapshots : undefined;
+};
+
+/**
+ * Projects a live DevToolsHooks api entry into the plain, render-ready shape the
+ * views consume. This is the in-process equivalent of the old
+ * DevToolsHost.sendUpdate(): it walks the scope accessors for root-scope state
+ * and the scope graph, normalizes the model context, and redacts credentials.
+ *
+ * `state` and each `log.data` are passed through sanitizeForMessage so the JSON
+ * renderers cannot crash on circular references or non-serializable values;
+ * `log.time` is kept as a Date for the clock formatter.
+ */
+export const projectApi = (apiId: number, entry: DevToolsApiEntry): ApiInfo => {
+  const state: Record<string, unknown> = {};
+  const scopes: Array<{
+    name: string;
+    source: string | null;
+    query: Record<string, unknown> | null;
+    methods: string[];
+  }> = [];
+
+  for (const [name, scope] of Object.entries(entry.api)) {
+    if (typeof scope !== "function" || !("source" in scope)) continue;
+
+    let methods: string[] = [];
+    try {
+      const scopeValue = scope();
+      if (scope.source === "root") {
+        state[name] = scopeValue?.getState?.() ?? scopeValue;
+      }
+      methods = readMethods(scopeValue);
+    } catch {
+      // scope() may throw for derived scopes before the client is mounted.
+    }
+
+    scopes.push({
+      name,
+      source: scope.source,
+      query: scope.query,
+      methods,
+    });
+  }
+
+  let modelContext: ApiInfo["modelContext"];
+  try {
+    modelContext = serializeModelContext(
+      entry.api.thread?.().getModelContext(),
+    );
+  } catch {
+    // A throwing thread()/getModelContext() should not drop the whole api;
+    // show partial data (state, scopes, logs) without the model context.
+  }
+
+  const sanitizedState = sanitizeForMessage(state) as Record<string, unknown>;
+  const threadSnapshots = collectThreadSnapshots(entry, sanitizedState);
+
+  return {
+    id: apiId,
+    state: sanitizedState,
+    logs: entry.logs.map((log) => ({
+      time: log.time,
+      event: log.event,
+      data: sanitizeForMessage(log.data),
+    })),
+    modelContext,
+    scopes: sanitizeAndRedact(scopes),
+    ...(threadSnapshots ? { threadSnapshots } : {}),
+  };
+};

package/src/data/types.ts

@@ -0,0 +1,54 @@
+import type { SerializedModelContext } from "../types";
+
+export type { SerializedModelContext } from "../types";
+
+export interface EventLogEntry {
+  readonly time: Date;
+  readonly event: string;
+  readonly data: unknown;
+}
+
+export interface ApiInfo {
+  id: number;
+  state: Record<string, unknown>;
+  logs: EventLogEntry[];
+  modelContext?: SerializedModelContext | undefined;
+  scopes?: unknown;
+  /**
+   * Cached thread states keyed by thread id. Populated for threads whose runtime
+   * has been mounted (visited in the app). Unvisited threads only appear in
+   * `state.threads.threadItems`.
+   */
+  threadSnapshots?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A JSON-safe view of every inspected instance. The map values are stable until
+ * the next change so it can be returned directly from useSyncExternalStore.
+ */
+export interface DevToolsSnapshot {
+  apiIds: number[];
+  byId: ReadonlyMap<number, ApiInfo>;
+}
+
+/**
+ * The transport between the data source and the panel UI. The default
+ * implementation reads the in-process DevToolsHooks registry, but the panel only
+ * depends on this interface, so the same UI can be driven by a postMessage
+ * bridge, a browser-extension relay, a remote socket, or a fixture for tests.
+ */
+export interface DevToolsClient {
+  /** Subscribe to snapshot changes; returns an unsubscribe. */
+  subscribe(listener: () => void): () => void;
+  /** The current snapshot. Must return a stable reference until it changes. */
+  getSnapshot(): DevToolsSnapshot;
+  /** Snapshot used during SSR/hydration. Defaults to an empty snapshot. */
+  getServerSnapshot?(): DevToolsSnapshot;
+  /** Clears the buffered event log for an instance. */
+  clearEvents(apiId: number): void;
+  /** Switches the inspected instance to a thread by id, when supported. */
+  switchToThread?(apiId: number, threadId: string): void | Promise<void>;
+}
+
+/** Shared stable empty snapshot identity for the empty/server state. */
+export const EMPTY_SNAPSHOT: DevToolsSnapshot = { apiIds: [], byId: new Map() };