@schlessera/brain-ui-react 0.30.1 → 0.31.0

package/src/components/chat/use-chat-commands.ts

@@ -0,0 +1,87 @@
+import { useCallback } from "react";
+import { useChatStore } from "../../stores/chat-store.js";
+import { useConnectionStore } from "../../stores/connection-store.js";
+import { useUIStore } from "../../stores/ui-store.js";
+import { api } from "../../lib/api-client.js";
+
+/**
+ * Slash-command dispatch, shared by the composer's palette and the welcome
+ * screen's shortcut buttons.
+ *
+ * Every piece of state a command needs is read through `getState()` at the
+ * moment it runs rather than subscribed to, so the returned callback is stable
+ * for the life of the component. That matters because the composer is the
+ * component that re-renders on every keystroke: a command handler that changed
+ * identity per character would defeat the memoization around it.
+ */
+export function useChatCommands(): (command: string) => void {
+  return useCallback((command: string) => {
+    const ui = useUIStore.getState();
+
+    // Search and add talk to the brain CLI over REST, not to the agent — they
+    // stay available while a turn streams or the socket is down.
+    switch (command) {
+      case "search":
+        ui.setSearchPanelOpen(true);
+        return;
+      case "add":
+        ui.setAddPanelOpen(true);
+        return;
+    }
+
+    const chat = useChatStore.getState();
+    const sessionId = chat.activeSessionId;
+    const buffer = sessionId ? chat.buffers[sessionId] : chat.draft;
+    const disabled =
+      useConnectionStore.getState().wsStatus !== "connected" ||
+      Boolean(buffer?.isStreaming);
+    if (disabled) return;
+
+    switch (command) {
+      case "sync":
+        ui.setSyncPanelOpen(true);
+        break;
+      case "whatsup":
+        ui.setWhatsupPanelOpen(true);
+        break;
+      case "stats":
+        void runStats(sessionId);
+        break;
+    }
+  }, []);
+}
+
+/** Brain statistics rendered into the transcript as an assistant turn. */
+async function runStats(sessionId: string | null): Promise<void> {
+  const chat = useChatStore.getState();
+  chat.addUserMessage(sessionId, "Stats");
+  chat.startAssistantMessage(sessionId);
+  try {
+    const stats = await api.brainStats();
+    const result = [
+      `**Brain Statistics**`,
+      `- Documents: ${stats.documents}`,
+      `- Tags: ${stats.tags}`,
+      `- Links: ${stats.links}`,
+      ``,
+      `**By Type:** ${Object.entries(stats.byType)
+        .sort(([, a], [, b]) => b - a)
+        .map(([t, n]) => `${t} (${n})`)
+        .join(", ")}`,
+      ``,
+      `**By Status:** ${Object.entries(stats.byStatus)
+        .map(([s, n]) => `${s} (${n})`)
+        .join(", ")}`,
+    ].join("\n");
+    useChatStore.getState().appendText(sessionId, result);
+  } catch (err) {
+    useChatStore
+      .getState()
+      .appendText(
+        sessionId,
+        `**Error:** ${err instanceof Error ? err.message : "Action failed"}`
+      );
+  } finally {
+    useChatStore.getState().finishAssistantMessage(sessionId);
+  }
+}

package/src/components/files/file-panel.tsx

@@ -1,10 +1,20 @@
-import { useEffect } from "react";
+import { Suspense, lazy, useEffect } from "react";
 import { ChevronDown, ChevronRight, X } from "lucide-react";
 import { useFileStore } from "../../stores/file-store.js";
-import { FileTree } from "./file-tree.js";
-import { FileViewer } from "./file-viewer.js";
+import { useDeferredUnmount } from "../../hooks/use-deferred-unmount.js";
 import { cn } from "../../lib/utils.js";
 
+/** Matches the `duration-300` slide-out below. */
+const SLIDE_OUT_MS = 300;
+
+/**
+ * The tree and the viewers load the first time the panel is opened. Together
+ * they carry the markdown, HTML, image and PDF viewers, none of which the chat
+ * surface needs to have on hand.
+ */
+const FileTree = lazy(() => import("./file-tree.js").then((m) => ({ default: m.FileTree })));
+const FileViewer = lazy(() => import("./file-viewer.js").then((m) => ({ default: m.FileViewer })));
+
 export function FilePanel({ open, onClose }: { open: boolean; onClose: () => void }) {
   const currentPath = useFileStore((s) => s.currentPath);
   const treeExpanded = useFileStore((s) => s.treeExpanded);
@@ -40,7 +50,10 @@ export function FilePanel({ open, onClose }: { open: boolean; onClose: () => voi
     }
   }, [open, currentPath]);
 
-  const showTree = !currentPath || treeExpanded;
+  // The body outlives `open` by the slide-out, then unmounts: a closed panel
+  // was otherwise keeping the whole file tree mounted behind the chat page.
+  const showContent = useDeferredUnmount(open, SLIDE_OUT_MS);
+  const showTree = showContent && (!currentPath || treeExpanded);
 
   return (
     <>
@@ -73,7 +86,7 @@ export function FilePanel({ open, onClose }: { open: boolean; onClose: () => voi
 
         <div className="flex flex-1 flex-col overflow-hidden">
           {/* Tree toggle strip — visible when a file is open */}
-          {currentPath && (
+          {showContent && currentPath && (
             <div className="flex items-center gap-1 border-b border-border bg-surface-raised/40 px-3 py-1.5">
               <button
                 onClick={() => setTreeExpanded(!treeExpanded)}
@@ -99,14 +112,18 @@ export function FilePanel({ open, onClose }: { open: boolean; onClose: () => voi
                 currentPath ? "max-h-[45vh] border-b border-border" : "flex-1"
               )}
             >
-              <FileTree />
+              <Suspense fallback={null}>
+                <FileTree />
+              </Suspense>
             </div>
           )}
 
           {/* Viewer area */}
-          {currentPath && (
+          {showContent && currentPath && (
             <div className="flex-1 overflow-hidden">
-              <FileViewer />
+              <Suspense fallback={null}>
+                <FileViewer />
+              </Suspense>
             </div>
           )}
         </div>

package/src/components/layout/slide-panel.tsx

@@ -1,7 +1,11 @@
 import { useEffect, type ReactNode } from "react";
 import { X } from "lucide-react";
+import { useDeferredUnmount } from "../../hooks/use-deferred-unmount.js";
 import { cn } from "../../lib/utils.js";
 
+/** Matches the `duration-300` slide-out below. */
+const SLIDE_OUT_MS = 300;
+
 export function SlidePanel({
   open,
   onClose,
@@ -24,6 +28,14 @@ export function SlidePanel({
     return () => document.removeEventListener("keydown", handler);
   }, [open, onClose]);
 
+  /**
+   * A closed panel renders nothing. The shell (the sliding frame and its
+   * header) stays mounted so the CSS transform still animates; the contents do
+   * not. Every panel already rebuilds its state when it opens, so a close never
+   * preserved anything worth keeping.
+   */
+  const showContent = useDeferredUnmount(open, SLIDE_OUT_MS);
+
   return (
     <>
       {/* Backdrop */}
@@ -57,7 +69,7 @@ export function SlidePanel({
         </div>
 
         {/* Content */}
-        <div className="flex-1 overflow-y-auto">{children}</div>
+        <div className="flex-1 overflow-y-auto">{showContent ? children : null}</div>
       </div>
     </>
   );

package/src/components/settings/settings-panel.tsx

@@ -1,10 +1,19 @@
+import { Suspense, lazy } from "react";
 import { KeyRound, Puzzle, SlidersHorizontal } from "lucide-react";
 import { useUIStore, type SettingsTab } from "../../stores/ui-store.js";
 import { SlidePanel } from "../layout/slide-panel.js";
 import { cn } from "../../lib/utils.js";
-import { ModelsTab } from "./models-tab.js";
-import { PasskeyTab } from "./passkey-tab.js";
-import { SkillsTab } from "./skills-tab.js";
+
+/**
+ * Each tab is fetched the first time it is opened. Settings is the largest
+ * surface in the app and most sessions never open it, so none of it belongs in
+ * the bundle that has to arrive before the first message can be shown. The
+ * panel frame and its tab strip stay eager, so opening settings is immediate
+ * and only the body fills in.
+ */
+const ModelsTab = lazy(() => import("./models-tab.js").then((m) => ({ default: m.ModelsTab })));
+const PasskeyTab = lazy(() => import("./passkey-tab.js").then((m) => ({ default: m.PasskeyTab })));
+const SkillsTab = lazy(() => import("./skills-tab.js").then((m) => ({ default: m.SkillsTab })));
 
 const TABS: Array<{ id: SettingsTab; label: string; icon: typeof KeyRound }> = [
   { id: "models", label: "Models", icon: SlidersHorizontal },
@@ -51,13 +60,15 @@ export function SettingsPanel({
         </div>
 
         <div className="min-h-0 flex-1">
-          {tab === "models" ? (
-            <ModelsTab active={open && tab === "models"} />
-          ) : tab === "skills" ? (
-            <SkillsTab active={open && tab === "skills"} />
-          ) : (
-            <PasskeyTab active={open && tab === "security"} />
-          )}
+          <Suspense fallback={null}>
+            {tab === "models" ? (
+              <ModelsTab active={open && tab === "models"} />
+            ) : tab === "skills" ? (
+              <SkillsTab active={open && tab === "skills"} />
+            ) : (
+              <PasskeyTab active={open && tab === "security"} />
+            )}
+          </Suspense>
         </div>
       </div>
     </SlidePanel>

package/src/hooks/use-deferred-unmount.ts

@@ -0,0 +1,24 @@
+import { useEffect, useState } from "react";
+
+/**
+ * True while a panel should render its contents: immediately when it opens,
+ * and until `delayMs` after it closes.
+ *
+ * Panels slide out rather than disappearing, so their contents have to outlive
+ * the `open` flag by the length of that transition — unmounting on the flag
+ * would empty the panel on its way off screen. Everything after that is dead
+ * weight: a panel is a child of the page it opens over, so a mounted one
+ * re-renders with the page and keeps its whole subtree alive for nothing.
+ */
+export function useDeferredUnmount(open: boolean, delayMs: number): boolean {
+  const [mounted, setMounted] = useState(open);
+  useEffect(() => {
+    if (open) {
+      setMounted(true);
+      return;
+    }
+    const timer = setTimeout(() => setMounted(false), delayMs);
+    return () => clearTimeout(timer);
+  }, [open, delayMs]);
+  return mounted;
+}

package/src/hooks/use-websocket.ts

@@ -153,7 +153,76 @@ function ensureActivitySubscription(sessionId: string | null | undefined): void
   void loadSessionActivityHistory(sessionId);
 }
 
+/**
+ * Text and thinking deltas waiting to be applied, per buffer.
+ *
+ * A model streams tokens far faster than the display refreshes, and each socket
+ * frame arrives in its own macrotask, so React cannot batch them: one token was
+ * one store write, one render and one markdown re-parse of the growing message.
+ * Coalescing a frame's worth of tokens into a single write costs nothing
+ * visually — the screen could not have shown the intermediate states anyway.
+ *
+ * Consecutive same-kind chunks merge, so a burst of text becomes ONE appendText
+ * rather than one per token. Kind changes start a new chunk, which is what keeps
+ * interleaved thinking and text in their true chronological order.
+ */
+type PendingDelta = { kind: "text" | "thinking"; text: string };
+const pendingDeltas = new Map<ChatKey, PendingDelta[]>();
+let flushScheduled = false;
+
+/**
+ * Apply every buffered delta, in arrival order, and clear the buffer.
+ *
+ * Exported so tests can force the frame rather than wait for one; production
+ * code never needs to call it, because every path that reads the transcript
+ * flushes first.
+ */
+export function flushChatDeltas(): void {
+  flushDeltas();
+}
+
+function flushDeltas(): void {
+  flushScheduled = false;
+  if (pendingDeltas.size === 0) return;
+  const batches = [...pendingDeltas.entries()];
+  pendingDeltas.clear();
+  const state = useChatStore.getState();
+  for (const [key, chunks] of batches) {
+    for (const chunk of chunks) {
+      if (chunk.kind === "text") state.appendText(key, chunk.text);
+      else state.appendThinking(key, chunk.text);
+    }
+  }
+}
+
+function enqueueDelta(key: ChatKey, kind: PendingDelta["kind"], text: string): void {
+  const chunks = pendingDeltas.get(key);
+  if (!chunks) {
+    pendingDeltas.set(key, [{ kind, text }]);
+  } else {
+    const last = chunks[chunks.length - 1];
+    if (last.kind === kind) last.text += text;
+    else chunks.push({ kind, text });
+  }
+  // Outside a browser (unit tests, SSR) there is no frame to wait for, so apply
+  // straight away and keep the handler's behaviour synchronous.
+  if (typeof requestAnimationFrame !== "function") {
+    flushDeltas();
+    return;
+  }
+  if (!flushScheduled) {
+    flushScheduled = true;
+    requestAnimationFrame(flushDeltas);
+  }
+}
+
 export function handleServerMessage(msg: ServerMessage) {
+  // Every frame that is not itself a delta must see the transcript fully
+  // applied: the demux below reads buffer state, and the store records parts in
+  // arrival order, so a tool call landing ahead of buffered text would reorder
+  // the message.
+  if (msg.type !== "text_delta" && msg.type !== "thinking_delta") flushDeltas();
+
   const state = useChatStore.getState();
 
   // Activity stream frames feed their own store and never touch chat state.
@@ -223,17 +292,19 @@ export function handleServerMessage(msg: ServerMessage) {
 
   switch (msg.type) {
     case "text_delta":
+      // Opening the bubble stays immediate — the first token should show a
+      // message starting, and every later delta needs isStreaming to be true.
       if (!buffer()?.isStreaming) {
         state.startAssistantMessage(key);
       }
-      state.appendText(key, msg.text);
+      enqueueDelta(key, "text", msg.text);
       break;
 
     case "thinking_delta":
       if (!buffer()?.isStreaming) {
         state.startAssistantMessage(key);
       }
-      state.appendThinking(key, msg.text);
+      enqueueDelta(key, "thinking", msg.text);
       break;
 
     case "tool_use_start":
@@ -463,6 +534,12 @@ function coldResumeIfNeeded(sessionId: string | null, messageCount: number) {
 function handleStatusChange(status: "connecting" | "connected" | "disconnected") {
   useConnectionStore.getState().setWsStatus(status);
 
+  // A status change can be followed by a history replay that rewrites the
+  // buffer, so land whatever is still buffered before anything reads it. In a
+  // hidden tab requestAnimationFrame does not run at all, which is exactly the
+  // case where deltas could otherwise sit unapplied across a reconnect.
+  flushDeltas();
+
   if (status === "disconnected") {
     wasDisconnected = true;
     // Allow a fresh cold-resume attempt after we reconnect.

package/src/index.ts

@@ -15,8 +15,9 @@ export { configureBrainUi, uiConfig, type BrainUiConfig } from "./config.js";
 export { ConnectionGate } from "./components/connectivity/connection-gate.js";
 export { AppShell } from "./components/layout/app-shell.js";
 export { ChatPage } from "./components/chat/chat-page.js";
-export { GraphPage } from "./components/graph/graph-page.js";
-export { ActivityPage } from "./components/activity/activity-page.js";
+// Loaded on first use, with their own Suspense boundary, so a shell that
+// renders them keeps working unchanged — see lazy-pages.tsx.
+export { GraphPage, ActivityPage } from "./lazy-pages.js";
 
 // Markdown renderer (also useful standalone, e.g. for a dev kitchen sink).
 export { BrainMarkdown } from "./components/chat/brain-markdown.js";

package/src/lazy-pages.tsx

@@ -0,0 +1,41 @@
+import { Suspense, lazy } from "react";
+
+/**
+ * The two secondary surfaces, loaded on first use.
+ *
+ * Chat is what the app opens on; the graph (which drags in sigma and
+ * graphology) and the activity record are reached from the rail, often never in
+ * a given session. Splitting them keeps their code out of the bundle that has
+ * to arrive before anything can be shown.
+ *
+ * The Suspense boundary lives here rather than in the consuming shell so these
+ * stay drop-in components: the shell renders <GraphPage /> exactly as before
+ * and does not have to know that it suspends. The fallback is deliberately
+ * empty — the chunk resolves in a frame or two on any warm cache, and a
+ * spinner that flashes for one frame reads as a glitch rather than as progress.
+ */
+const GraphPageLazy = lazy(() =>
+  import("./components/graph/graph-page.js").then((m) => ({ default: m.GraphPage }))
+);
+
+const ActivityPageLazy = lazy(() =>
+  import("./components/activity/activity-page.js").then((m) => ({
+    default: m.ActivityPage,
+  }))
+);
+
+export function GraphPage() {
+  return (
+    <Suspense fallback={null}>
+      <GraphPageLazy />
+    </Suspense>
+  );
+}
+
+export function ActivityPage() {
+  return (
+    <Suspense fallback={null}>
+      <ActivityPageLazy />
+    </Suspense>
+  );
+}

package/src/theme.css

@@ -433,3 +433,61 @@
 .brain-tree-highlight {
   animation: brain-tree-flash 1.6s ease-out;
 }
+
+/* Auto-growing composer textarea.
+ *
+ * The wrapper is a one-cell grid holding the textarea and a hidden ::after that
+ * mirrors the draft; the mirror sizes the row, so the textarea follows without
+ * anyone reading scrollHeight. That read is a forced synchronous layout of the
+ * whole document, and it ran on every keystroke — its cost grew with the size
+ * of the transcript rendered behind the composer.
+ *
+ * The mirror and the textarea MUST agree on every box and typography value
+ * below, or the two will disagree about where the text wraps. */
+.composer-grow {
+  display: grid;
+}
+
+.composer-grow::after,
+.composer-grow > textarea {
+  grid-area: 1 / 1 / 2 / 2;
+  min-height: 56px;
+  max-height: 200px;
+  padding: 1rem 1.25rem;
+  font: inherit;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  border: 0;
+}
+
+/* The trailing space the composer appends keeps a trailing newline visible. */
+.composer-grow::after {
+  content: attr(data-value);
+  visibility: hidden;
+  overflow: hidden;
+}
+
+.composer-grow > textarea {
+  resize: none;
+  overflow-y: auto;
+}
+
+/* Offscreen transcript prose is skipped by the browser entirely — no style,
+ * layout or paint until it scrolls near the viewport. A long conversation is
+ * mostly offscreen, so this is where the cost of a big DOM goes.
+ *
+ * Scoped to the message BODY rather than the whole message on purpose:
+ * content-visibility implies paint containment, which clips descendants to the
+ * border box and makes the element a containing block for fixed positioning.
+ * The share dropdown opens past the bottom of its message, so it stays outside
+ * this wrapper. Full-screen viewers are unaffected — they portal to the body.
+ *
+ * The `auto` in contain-intrinsic-size makes the browser remember each block's
+ * real height once measured, so scroll position stays honest after the first
+ * pass; 6rem is only the guess for blocks it has never rendered. */
+.chat-message-body {
+  content-visibility: auto;
+  contain-intrinsic-size: auto 6rem;
+}