+
+
{!isMobile ? (
diff --git a/apps/web/src/components/app/center-pane-tab-bar.tsx b/apps/web/src/components/app/center-pane-tab-bar.tsx
index ab17e863..3d5722b9 100644
--- a/apps/web/src/components/app/center-pane-tab-bar.tsx
+++ b/apps/web/src/components/app/center-pane-tab-bar.tsx
@@ -3,18 +3,20 @@ import { memo } from "react";
import type { DiffStats } from "@/components/app/types";
import { cn } from "@/lib/utils";
-type CenterTab = "terminal" | "changes";
+type CenterTab = "terminal" | "changes" | "whiteboard";
type CenterPaneTabBarProps = {
activeTab: CenterTab;
onTabChange: (tab: CenterTab) => void;
diffStats: DiffStats | null | undefined;
+ whiteboardAgentDrew?: boolean;
};
export const CenterPaneTabBar = memo(function CenterPaneTabBar({
activeTab,
onTabChange,
diffStats,
+ whiteboardAgentDrew = false,
}: CenterPaneTabBarProps): JSX.Element {
const hasChanges =
diffStats && (diffStats.added > 0 || diffStats.deleted > 0);
@@ -67,6 +69,32 @@ export const CenterPaneTabBar = memo(function CenterPaneTabBar({
) : null}
+
);
});
diff --git a/apps/web/src/components/app/whiteboard-pane.tsx b/apps/web/src/components/app/whiteboard-pane.tsx
new file mode 100644
index 00000000..1cb1dfb0
--- /dev/null
+++ b/apps/web/src/components/app/whiteboard-pane.tsx
@@ -0,0 +1,49 @@
+import { lazy, Suspense, useEffect, useState } from "react";
+import { useAtom } from "jotai";
+
+import { whiteboardAgentDrewAtomFamily } from "@/lib/store";
+import { cn } from "@/lib/utils";
+
+// Excalidraw is heavy (~MBs); split it out and only load on first tab visit.
+const WhiteboardTab = lazy(() => import("@/components/app/whiteboard-tab"));
+
+type WhiteboardPaneProps = {
+ agentId: string | null;
+ active: boolean;
+};
+
+// Owns all whiteboard pane concerns so agents-view stays a composition root:
+// mount-on-first-visit then keep mounted (Terminal pattern — undo history,
+// zoom, and in-flight strokes survive tab switches), and clearing the
+// "agent drew" dot (lit by SSE in use-sse.ts) while the user is looking.
+export function WhiteboardPane({
+ agentId,
+ active,
+}: WhiteboardPaneProps): JSX.Element | null {
+ const [opened, setOpened] = useState(false);
+ useEffect(() => {
+ if (active) setOpened(true);
+ }, [active]);
+
+ const [agentDrew, setAgentDrew] = useAtom(
+ whiteboardAgentDrewAtomFamily(agentId ?? "")
+ );
+ useEffect(() => {
+ if (active && agentId && agentDrew) setAgentDrew(false);
+ }, [active, agentId, agentDrew, setAgentDrew]);
+
+ if (!opened || !agentId) return null;
+ return (
+
+
+ Loading whiteboard…
+
+ }
+ >
+
+
+
+ );
+}
diff --git a/apps/web/src/components/app/whiteboard-tab.tsx b/apps/web/src/components/app/whiteboard-tab.tsx
new file mode 100644
index 00000000..e7fa43b7
--- /dev/null
+++ b/apps/web/src/components/app/whiteboard-tab.tsx
@@ -0,0 +1,305 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import {
+ Excalidraw,
+ exportToBlob,
+ getSceneVersion,
+} from "@excalidraw/excalidraw";
+import type {
+ ExcalidrawImperativeAPI,
+ ExcalidrawInitialDataState,
+} from "@excalidraw/excalidraw/types";
+import type { ExcalidrawElement } from "@excalidraw/excalidraw/element/types";
+import "@excalidraw/excalidraw/index.css";
+
+import {
+ useWhiteboard,
+ whiteboardQueryKey,
+ type WhiteboardData,
+} from "@/hooks/use-whiteboard";
+import { getThemeMode, useTheme } from "@/hooks/use-theme";
+import { api } from "@/lib/api";
+
+declare global {
+ interface Window {
+ EXCALIDRAW_ASSET_PATH?: string;
+ }
+}
+// Self-hosted fonts (see excalidrawAssets in vite.config.ts); without this
+// Excalidraw fetches them from esm.sh at runtime.
+window.EXCALIDRAW_ASSET_PATH = "/excalidraw/";
+
+const SAVE_DEBOUNCE_MS = 1000;
+const SNAPSHOT_DEBOUNCE_MS = 4000;
+
+type WhiteboardTabProps = {
+ agentId: string;
+ visible: boolean;
+};
+
+export default function WhiteboardTab({
+ agentId,
+ visible,
+}: WhiteboardTabProps): JSX.Element {
+ const { data, isLoading, isError } = useWhiteboard(agentId);
+
+ if (isLoading || (!data && !isError)) {
+ return (
+
+ Loading whiteboard…
+
+ );
+ }
+ if (isError || !data) {
+ return (
+
+ Could not load the whiteboard.
+
+ );
+ }
+ return (
+
+ );
+}
+
+function WhiteboardCanvas({
+ agentId,
+ initial,
+ visible,
+}: {
+ agentId: string;
+ initial: WhiteboardData;
+ visible: boolean;
+}): JSX.Element {
+ const queryClient = useQueryClient();
+ const { theme } = useTheme();
+ const [excalidrawAPI, setExcalidrawAPI] =
+ useState
(null);
+ const [boardEmpty, setBoardEmpty] = useState(
+ initial.scene.elements.length === 0
+ );
+ const { data } = useWhiteboard(agentId);
+
+ // Server board version our last save was based on; bumped on each save.
+ const versionRef = useRef(initial.version);
+ // Content hash of the last persisted (or initial) scene, to skip no-op saves.
+ const sceneVersionRef = useRef(
+ getSceneVersion(initial.scene.elements as readonly ExcalidrawElement[])
+ );
+ const saveTimerRef = useRef(undefined);
+ const snapshotTimerRef = useRef(undefined);
+ const savingRef = useRef(false);
+ // Remote scene waiting to be applied while the user is mid-gesture.
+ const pointerDownRef = useRef(false);
+ const pendingRemoteRef = useRef(null);
+
+ const initialData = useMemo(
+ () => ({
+ elements: initial.scene.elements as readonly ExcalidrawElement[],
+ scrollToContent: true,
+ }),
+ [initial]
+ );
+
+ const persistSnapshot = useCallback(async () => {
+ if (!excalidrawAPI) return;
+ const elements = excalidrawAPI.getSceneElements();
+ if (elements.length === 0) {
+ // An emptied board must also drop its PNG, or whiteboard_get keeps
+ // showing agents the erased drawing.
+ try {
+ await api(`/api/v1/agents/${agentId}/whiteboard/snapshot`, {
+ method: "DELETE",
+ });
+ } catch {}
+ return;
+ }
+ try {
+ const blob = await exportToBlob({
+ elements,
+ appState: {
+ ...excalidrawAPI.getAppState(),
+ exportBackground: true,
+ },
+ files: excalidrawAPI.getFiles(),
+ mimeType: "image/png",
+ });
+ const form = new FormData();
+ form.append("file", blob, "whiteboard.png");
+ await api(`/api/v1/agents/${agentId}/whiteboard/snapshot`, {
+ method: "POST",
+ body: form,
+ });
+ } catch {
+ // Snapshot is best-effort; the scene itself is already persisted.
+ }
+ }, [agentId, excalidrawAPI]);
+
+ const persistScene = useCallback(async () => {
+ if (!excalidrawAPI || savingRef.current) return;
+ const elements = excalidrawAPI.getSceneElements();
+ const sceneVersion = getSceneVersion(elements);
+ if (sceneVersion === sceneVersionRef.current) return;
+ savingRef.current = true;
+ try {
+ const res = await api<{ version: number }>(
+ `/api/v1/agents/${agentId}/whiteboard`,
+ {
+ method: "PUT",
+ body: JSON.stringify({
+ scene: { elements },
+ baseVersion: versionRef.current,
+ }),
+ }
+ );
+ versionRef.current = res.version;
+ sceneVersionRef.current = sceneVersion;
+ queryClient.setQueryData(
+ whiteboardQueryKey(agentId),
+ (old) =>
+ old
+ ? {
+ ...old,
+ scene: { elements: [...elements] },
+ version: res.version,
+ }
+ : old
+ );
+ // Content changed on the server; refresh the agent-facing PNG.
+ if (snapshotTimerRef.current !== undefined) {
+ window.clearTimeout(snapshotTimerRef.current);
+ }
+ snapshotTimerRef.current = window.setTimeout(() => {
+ void persistSnapshot();
+ }, SNAPSHOT_DEBOUNCE_MS);
+ } catch {
+ // Version conflict or transient failure: refetch so the editor
+ // reconciles against the server's copy.
+ void queryClient.invalidateQueries({
+ queryKey: whiteboardQueryKey(agentId),
+ exact: true,
+ });
+ } finally {
+ savingRef.current = false;
+ }
+ }, [agentId, excalidrawAPI, persistSnapshot, queryClient]);
+
+ const scheduleSave = useCallback(() => {
+ if (excalidrawAPI) {
+ setBoardEmpty(excalidrawAPI.getSceneElements().length === 0);
+ }
+ if (saveTimerRef.current !== undefined) {
+ window.clearTimeout(saveTimerRef.current);
+ }
+ saveTimerRef.current = window.setTimeout(() => {
+ saveTimerRef.current = undefined;
+ void persistScene();
+ }, SAVE_DEBOUNCE_MS);
+ }, [excalidrawAPI, persistScene]);
+
+ const applyRemote = useCallback(
+ (remote: WhiteboardData) => {
+ if (!excalidrawAPI) return;
+ versionRef.current = remote.version;
+ sceneVersionRef.current = getSceneVersion(
+ remote.scene.elements as readonly ExcalidrawElement[]
+ );
+ excalidrawAPI.updateScene({
+ elements: remote.scene.elements as ExcalidrawElement[],
+ });
+ setBoardEmpty(remote.scene.elements.length === 0);
+ // Agent edits happen server-side where no PNG can be rendered; this
+ // client just became the renderer — refresh the agent-facing snapshot.
+ if (snapshotTimerRef.current !== undefined) {
+ window.clearTimeout(snapshotTimerRef.current);
+ }
+ snapshotTimerRef.current = window.setTimeout(() => {
+ void persistSnapshot();
+ }, SNAPSHOT_DEBOUNCE_MS);
+ },
+ [excalidrawAPI, persistSnapshot]
+ );
+
+ // Apply remote (agent/SSE-driven) updates; defer while a gesture is live.
+ useEffect(() => {
+ if (!data || data.version <= versionRef.current) return;
+ if (pointerDownRef.current) {
+ pendingRemoteRef.current = data;
+ return;
+ }
+ applyRemote(data);
+ }, [data, applyRemote]);
+
+ useEffect(() => {
+ const onPointerUp = () => {
+ pointerDownRef.current = false;
+ const pending = pendingRemoteRef.current;
+ if (pending) {
+ pendingRemoteRef.current = null;
+ applyRemote(pending);
+ }
+ };
+ window.addEventListener("pointerup", onPointerUp);
+ return () => window.removeEventListener("pointerup", onPointerUp);
+ }, [applyRemote]);
+
+ // Flush pending work when the tab is hidden or the canvas unmounts.
+ useEffect(() => {
+ if (visible) return;
+ if (saveTimerRef.current !== undefined) {
+ window.clearTimeout(saveTimerRef.current);
+ saveTimerRef.current = undefined;
+ void persistScene();
+ }
+ }, [visible, persistScene]);
+
+ useEffect(() => {
+ return () => {
+ if (saveTimerRef.current !== undefined) {
+ window.clearTimeout(saveTimerRef.current);
+ void persistScene();
+ }
+ if (snapshotTimerRef.current !== undefined) {
+ window.clearTimeout(snapshotTimerRef.current);
+ // Flush like the save timer: exportToBlob renders offscreen from
+ // scene data, so it still works during teardown.
+ void persistSnapshot();
+ }
+ };
+ // persistScene is stable per agent/api instance; run cleanup once.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, []);
+
+ return (
+ {
+ pointerDownRef.current = true;
+ }}
+ >
+ {boardEmpty ? (
+
+
+ Sketch here — your agent can see this board. Ask it to “look
+ at the whiteboard” in the terminal.
+
+
+ ) : null}
+
+