@assistant-ui/react-devtools 0.1.1

package/src/DevToolsFrame.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { FrameHost } from "./FrameHost";
+import { DEFAULT_FRAME_URL } from "./constants";
+
+export interface DevToolsFrameProps {
+  frameUrl?: string;
+  className?: string;
+  style?: React.CSSProperties;
+  title?: string;
+}
+
+export const DevToolsFrame: React.FC<DevToolsFrameProps> = ({
+  frameUrl = DEFAULT_FRAME_URL,
+  className,
+  style,
+  title = "assistant-ui DevTools",
+}) => {
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
+  const frameHostRef = useRef<FrameHost | null>(null);
+
+  const resolvedFrameUrl = useMemo(() => frameUrl, [frameUrl]);
+
+  const handleFrameLoad = useCallback(() => {
+    if (frameHostRef.current) {
+      frameHostRef.current.destroy();
+      frameHostRef.current = null;
+    }
+
+    if (iframeRef.current) {
+      frameHostRef.current = new FrameHost(iframeRef.current);
+    }
+  }, []);
+
+  useEffect(() => {
+    return () => {
+      if (frameHostRef.current) {
+        frameHostRef.current.destroy();
+        frameHostRef.current = null;
+      }
+    };
+  }, []);
+
+  return (
+    <iframe
+      ref={iframeRef}
+      src={resolvedFrameUrl}
+      onLoad={handleFrameLoad}
+      className={className}
+      style={style}
+      title={title}
+    />
+  );
+};

package/src/DevToolsHost.ts

@@ -0,0 +1,150 @@
+import { DevToolsHooks } from "@assistant-ui/react";
+import {
+  sanitizeForMessage,
+  serializeModelContext,
+} from "./utils/serialization";
+
+interface FrameToHostMessage {
+  type: "subscription" | "clearEvents";
+  data: {
+    apiList?: boolean;
+    apis?: number[];
+    apiId?: number;
+  };
+}
+
+interface HostToFrameMessage {
+  type: "update";
+  data: {
+    apiList?: Array<{ apiId: number }>;
+    apis?: Array<{
+      apiId: number;
+      state: any;
+      events: any[];
+      modelContext?: any;
+    }>;
+  };
+}
+
+export class DevToolsHost {
+  private subscription: {
+    apiList: boolean;
+    apis: Set<number>;
+  } = {
+    apiList: false,
+    apis: new Set(),
+  };
+  private unsubscribe?: () => void;
+  private onSendMessage: (message: HostToFrameMessage) => void;
+
+  constructor(onSendMessage: (message: HostToFrameMessage) => void) {
+    this.onSendMessage = onSendMessage;
+    this.subscribeToDevTools();
+  }
+
+  onReceiveMessage(message: FrameToHostMessage) {
+    switch (message.type) {
+      case "subscription":
+        this.handleSubscription(message.data);
+        break;
+      case "clearEvents":
+        if (typeof message.data.apiId === "number") {
+          DevToolsHooks.clearEventLogs(message.data.apiId);
+          // The subscription will automatically trigger an update
+        }
+        break;
+    }
+  }
+
+  private handleSubscription(data: FrameToHostMessage["data"]) {
+    const prevApiList = this.subscription.apiList;
+    const prevApis = new Set(this.subscription.apis);
+
+    this.subscription.apiList = data.apiList || false;
+    this.subscription.apis = new Set(data.apis);
+
+    // Only send update if subscription actually changed
+    const apisChanged =
+      prevApis.size !== this.subscription.apis.size ||
+      [...this.subscription.apis].some((id) => !prevApis.has(id));
+
+    if (prevApiList !== this.subscription.apiList || apisChanged) {
+      this.sendUpdate();
+    }
+  }
+
+  private subscribeToDevTools() {
+    this.unsubscribe = DevToolsHooks.subscribe(() => {
+      this.sendUpdate();
+    });
+  }
+
+  private sendUpdate() {
+    const update: HostToFrameMessage = {
+      type: "update",
+      data: {},
+    };
+
+    const allApis = DevToolsHooks.getApis();
+    for (const subscriptionApiId of this.subscription.apis) {
+      if (!allApis.has(subscriptionApiId)) {
+        this.subscription.apis.delete(subscriptionApiId);
+      }
+    }
+
+    if (this.subscription.apiList) {
+      update.data.apiList = [...allApis.keys()].map((apiId) => ({ apiId }));
+
+      if (this.subscription.apis.size === 0 && allApis.size > 0) {
+        this.subscription.apis = new Set([allApis.keys().next().value!]);
+      }
+    }
+
+    if (this.subscription.apis.size > 0) {
+      update.data.apis = [];
+
+      for (const apiId of this.subscription.apis) {
+        const apiEntry = allApis.get(apiId);
+        if (apiEntry) {
+          // Collect state from api scopes (only root source)
+          const state: Record<string, unknown> = {};
+          if (apiEntry.api) {
+            for (const [name, scope] of Object.entries(apiEntry.api)) {
+              if (typeof scope === "function" && "source" in scope) {
+                // Only forward scopes with source === "root"
+                if (scope.source === "root") {
+                  const scopeValue = scope();
+                  state[name] = scopeValue?.getState?.() ?? scopeValue;
+                }
+              }
+            }
+          }
+
+          // Extract model context from thread runtime
+          const modelContext = serializeModelContext(
+            apiEntry.api?.thread?.().getModelContext(),
+          );
+
+          update.data.apis.push({
+            apiId,
+            state: sanitizeForMessage(state),
+            events: sanitizeForMessage(apiEntry.logs) as unknown[],
+            modelContext: modelContext,
+          });
+        }
+      }
+    }
+
+    if (Object.keys(update.data).length === 0) {
+      return;
+    }
+
+    this.onSendMessage(update);
+  }
+
+  destroy() {
+    if (this.unsubscribe) {
+      this.unsubscribe();
+    }
+  }
+}

package/src/DevToolsModal.tsx

@@ -0,0 +1,178 @@
+"use client";
+
+import { useEffect, useMemo, useState } 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 DevToolsModalImpl = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  const [darkMode, setDarkMode] = useState(false);
+  const [buttonHover, setButtonHover] = useState(false);
+  const [closeHover, setCloseHover] = useState(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 (typeof MutationObserver === "undefined") return;
+
+    const checkDarkMode = () => setDarkMode(isDarkMode());
+    const observer = new MutationObserver(checkDarkMode);
+
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["class"],
+    });
+    if (document.body !== document.documentElement) {
+      observer.observe(document.body, {
+        attributes: true,
+        attributeFilter: ["class"],
+      });
+    }
+
+    return () => observer.disconnect();
+  }, []);
+
+  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
+          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
+            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
+              onClick={() => setIsOpen(false)}
+              onMouseEnter={() => setCloseHover(true)}
+              onMouseLeave={() => setCloseHover(false)}
+              style={{
+                ...styles.dismissButton,
+                ...(closeHover ? styles.dismissButtonHover : {}),
+              }}
+              aria-label="Close DevTools"
+            >
+              <svg
+                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
+  if (
+    typeof process !== "undefined" &&
+    process.env?.["NODE_ENV"] === "production"
+  ) {
+    return null;
+  }
+
+  return <DevToolsModalImpl />;
+};

package/src/ExtensionHost.ts

@@ -0,0 +1,57 @@
+import { DevToolsHost } from "./DevToolsHost";
+
+export class ExtensionHost {
+  private devToolsHost: DevToolsHost;
+  private messageListener: (event: MessageEvent) => void;
+
+  constructor() {
+    // Create DevToolsHost with callback to send messages through extension
+    this.devToolsHost = new DevToolsHost((message) => {
+      console.log("[ExtensionHost] Sending message to iframe:", message);
+      window.postMessage(
+        {
+          source: "assistant-ui-devtools-page",
+          payload: message,
+        },
+        "*",
+      );
+    });
+
+    // Setup listener to forward messages from extension to DevToolsHost
+    this.messageListener = (event: MessageEvent) => {
+      if (event.source !== window) return;
+
+      // Log ALL messages to see what's coming through
+      if (event.data.source === "assistant-ui-devtools-iframe") {
+        console.log("[ExtensionHost] Received message from iframe:", {
+          source: event.data.source,
+          payload: event.data.payload,
+          fullData: event.data,
+        });
+        this.devToolsHost.onReceiveMessage(event.data.payload);
+      }
+    };
+
+    window.addEventListener("message", this.messageListener);
+
+    // Announce that a new host has connected
+    // This tells the iframe to re-send its subscription
+    setTimeout(() => {
+      console.log("[ExtensionHost] Announcing connection to iframe");
+      window.postMessage(
+        {
+          source: "assistant-ui-devtools-page",
+          payload: {
+            type: "host-connected",
+          },
+        },
+        "*",
+      );
+    }, 100);
+  }
+
+  destroy() {
+    window.removeEventListener("message", this.messageListener);
+    this.devToolsHost.destroy();
+  }
+}

package/src/FrameClient.ts

@@ -0,0 +1,98 @@
+interface ApiData {
+  apiId: number;
+  state: any;
+  events: any[];
+  context?: any;
+}
+
+interface UpdateMessage {
+  type: "update";
+  data: {
+    apiList?: Array<{ apiId: number }>;
+    apis?: ApiData[];
+  };
+}
+
+interface HostConnectedMessage {
+  type: "host-connected";
+}
+
+type UpdateListener = (data: {
+  apiList?: Array<{ apiId: number }>;
+  apis?: ApiData[];
+}) => void;
+
+export class FrameClient {
+  private listeners = new Set<UpdateListener>();
+  private connectionListeners = new Set<() => void>();
+  private lastUpdate: {
+    apiList?: Array<{ apiId: number }>;
+    apis?: ApiData[];
+  } = {};
+
+  constructor() {
+    this.setupMessageListener();
+  }
+
+  private setupMessageListener() {
+    window.addEventListener("message", (event) => {
+      const message = event.data as UpdateMessage | HostConnectedMessage;
+
+      if (message.type === "update") {
+        this.lastUpdate = message.data;
+        this.notifyListeners(message.data);
+      } else if (message.type === "host-connected") {
+        // Host has reconnected (page refresh), notify listeners to re-subscribe
+        this.connectionListeners.forEach((listener) => listener());
+      }
+    });
+  }
+
+  onHostConnected(listener: () => void): () => void {
+    this.connectionListeners.add(listener);
+    return () => {
+      this.connectionListeners.delete(listener);
+    };
+  }
+
+  subscribe(listener: UpdateListener): () => void {
+    this.listeners.add(listener);
+
+    // Send the last update to the new listener
+    if (this.lastUpdate.apiList || this.lastUpdate.apis) {
+      listener(this.lastUpdate);
+    }
+
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  setSubscription(options: { apiList?: boolean; apis?: number[] }) {
+    window.parent.postMessage(
+      {
+        type: "subscription",
+        data: options,
+      },
+      "*",
+    );
+  }
+
+  clearEvents(apiId: number) {
+    window.parent.postMessage(
+      {
+        type: "clearEvents",
+        data: { apiId },
+      },
+      "*",
+    );
+  }
+
+  private notifyListeners(data: UpdateMessage["data"]) {
+    this.listeners.forEach((listener) => listener(data));
+  }
+
+  getLastUpdate() {
+    return this.lastUpdate;
+  }
+}

package/src/FrameHost.ts

@@ -0,0 +1,31 @@
+import { DevToolsHost } from "./DevToolsHost";
+
+export class FrameHost {
+  private frame: HTMLIFrameElement;
+  private devToolsHost: DevToolsHost;
+  private messageListener: (event: MessageEvent) => void;
+
+  constructor(frame: HTMLIFrameElement) {
+    this.frame = frame;
+
+    // Create DevToolsHost with callback to send messages to iframe
+    this.devToolsHost = new DevToolsHost((message) => {
+      if (this.frame.contentWindow) {
+        this.frame.contentWindow.postMessage(message, "*");
+      }
+    });
+
+    // Setup listener to forward messages from iframe to DevToolsHost
+    this.messageListener = (event: MessageEvent) => {
+      if (event.source !== this.frame.contentWindow) return;
+      this.devToolsHost.onReceiveMessage(event.data);
+    };
+
+    window.addEventListener("message", this.messageListener);
+  }
+
+  destroy() {
+    window.removeEventListener("message", this.messageListener);
+    this.devToolsHost.destroy();
+  }
+}

package/src/constants.ts

@@ -0,0 +1,2 @@
+export const DEFAULT_FRAME_URL = "https://devtools-frame.assistant-ui.com";
+export const LOCAL_FRAME_URL = "http://localhost:3010";

package/src/index.ts

@@ -0,0 +1,17 @@
+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 {
+  normalizeToolList,
+  type NormalizedTool,
+} from "./utils/toolNormalization";
+export {
+  sanitizeForMessage,
+  serializeModelContext,
+} from "./utils/serialization";
+// Export types
+export type { SerializedModelContext, TabType, ViewMode } from "./types";
+export * from "./constants";