@schlessera/brain-ui-react 0.4.0

package/src/components/voice/review-card.tsx

@@ -0,0 +1,66 @@
+import { Mic, Pencil, Send, X } from "lucide-react";
+
+export function ReviewCard({
+  text,
+  onSend,
+  onEdit,
+  onDiscard,
+  onAppend,
+}: {
+  text: string;
+  onSend: () => void;
+  onEdit: () => void;
+  onDiscard: () => void;
+  onAppend: () => void;
+}) {
+  if (!text) return null;
+  return (
+    <div className="mb-2 rounded-2xl border border-primary/30 bg-surface shadow-[0_8px_24px_rgba(0,0,0,0.3)]">
+      <div className="flex items-start gap-3 px-4 pt-3 pb-2">
+        <Mic className="mt-0.5 h-4 w-4 flex-none text-primary" />
+        <p className="max-h-40 flex-1 overflow-y-auto text-sm leading-relaxed text-foreground">
+          {text}
+        </p>
+      </div>
+      <div className="flex items-center justify-between border-t border-border/40 px-2 py-2">
+        <div className="flex items-center gap-1">
+          <button
+            type="button"
+            onClick={onDiscard}
+            title="Discard"
+            className="flex h-9 items-center gap-1.5 rounded-lg px-3 text-xs text-muted-foreground transition-colors hover:bg-surface-raised hover:text-destructive"
+          >
+            <X className="h-3.5 w-3.5" />
+            Discard
+          </button>
+          <button
+            type="button"
+            onClick={onEdit}
+            title="Edit"
+            className="flex h-9 items-center gap-1.5 rounded-lg px-3 text-xs text-muted-foreground transition-colors hover:bg-surface-raised hover:text-foreground"
+          >
+            <Pencil className="h-3.5 w-3.5" />
+            Edit
+          </button>
+          <button
+            type="button"
+            onClick={onAppend}
+            title="Append more voice"
+            className="flex h-9 items-center gap-1.5 rounded-lg px-3 text-xs text-muted-foreground transition-colors hover:bg-surface-raised hover:text-foreground"
+          >
+            <Mic className="h-3.5 w-3.5" />
+            Add
+          </button>
+        </div>
+        <button
+          type="button"
+          onClick={onSend}
+          className="flex h-10 items-center gap-2 rounded-xl bg-primary px-5 text-sm font-semibold text-primary-foreground transition-all duration-150 hover:brightness-110 active:scale-[0.98]"
+        >
+          <Send className="h-4 w-4" />
+          Send
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/config.ts

@@ -0,0 +1,27 @@
+/**
+ * Deployment-tunable branding/copy. A module-level singleton, matching the
+ * renderer/ASR registries: the shell calls `configureBrainUi()` once at boot
+ * (before mounting), components read `uiConfig` at render time. Runtime
+ * plugin-style reconfiguration is deliberately unsupported.
+ */
+export interface BrainUiConfig {
+  /** Product name shown on the login screen and connection status. */
+  appName: string;
+  /** Name the assistant speaks as in the transcript. */
+  assistantName: string;
+  /** Default title for shared artifacts (share cards, rendered PNG/PDF). */
+  shareTitle: string;
+  /** Composer placeholder. */
+  composerPlaceholder: string;
+}
+
+export const uiConfig: BrainUiConfig = {
+  appName: "Brain UI",
+  assistantName: "Brain",
+  shareTitle: "Shared from Brain",
+  composerPlaceholder: "Ask your brain anything...",
+};
+
+export function configureBrainUi(overrides: Partial<BrainUiConfig>): void {
+  Object.assign(uiConfig, overrides);
+}

package/src/hooks/use-vpn-status.ts

@@ -0,0 +1,75 @@
+import { useEffect } from "react";
+import { useConnectionStore } from "../stores/connection-store.js";
+import { getBackendUrl } from "../lib/backend.js";
+
+const POLL_INTERVAL = 15_000;
+// Tighter cadence while offline so recovery is near-immediate
+const OFFLINE_POLL_INTERVAL = 3_000;
+const TIMEOUT_MS = 5_000;
+
+export function useVpnStatus() {
+  const setVpnStatus = useConnectionStore((s) => s.setVpnStatus);
+
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let inFlight = false;
+    let disposed = false;
+
+    async function check() {
+      if (inFlight || disposed) return;
+      inFlight = true;
+      let connected = false;
+      try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+        const res = await fetch(getBackendUrl("/api/vpn-check"), {
+          signal: controller.signal,
+        });
+        clearTimeout(timeout);
+
+        if (res.ok) {
+          setVpnStatus("connected");
+          connected = true;
+        } else if (res.status === 401) {
+          // Auth required (password / proxy mode) but no valid session yet.
+          setVpnStatus("unauthorized");
+          connected = true; // reachable — poll at the relaxed cadence
+        } else if (res.status === 403) {
+          setVpnStatus("forbidden");
+        } else {
+          setVpnStatus("unreachable");
+        }
+      } catch {
+        setVpnStatus("unreachable");
+      } finally {
+        inFlight = false;
+        if (!disposed) {
+          clearTimeout(timer);
+          timer = setTimeout(
+            check,
+            connected ? POLL_INTERVAL : OFFLINE_POLL_INTERVAL
+          );
+        }
+      }
+    }
+
+    // Re-check immediately when the network returns or the PWA is foregrounded
+    // instead of waiting out the poll interval.
+    const recheckNow = () => void check();
+    const onVisible = () => {
+      if (document.visibilityState === "visible") void check();
+    };
+    window.addEventListener("online", recheckNow);
+    document.addEventListener("visibilitychange", onVisible);
+
+    void check();
+
+    return () => {
+      disposed = true;
+      clearTimeout(timer);
+      window.removeEventListener("online", recheckNow);
+      document.removeEventListener("visibilitychange", onVisible);
+    };
+  }, [setVpnStatus]);
+}

package/src/hooks/use-websocket.ts

@@ -0,0 +1,403 @@
+import { useEffect, useRef, useCallback } from "react";
+import { WSClient } from "../lib/ws-client.js";
+import { useConnectionStore } from "../stores/connection-store.js";
+import { useChatStore, activeChat, type ChatKey } from "../stores/chat-store.js";
+import { useProviderStore } from "../stores/provider-store.js";
+import { getWsUrl } from "../lib/backend.js";
+import type {
+  ServerMessage,
+  ClientMessage,
+  ServerLocationRequest,
+  SessionHistoryMessage,
+  AskUserQuestion,
+} from "@schlessera/brain-ui-sdk/protocol";
+import type { ChatMessage, ToolCall, AskUserExchange } from "../stores/chat-store.js";
+import { isAskUserTool } from "../lib/tool-names.js";
+
+let historyMessageCounter = 0;
+function historyId() {
+  return `hist-${++historyMessageCounter}-${Date.now()}`;
+}
+
+function convertHistoryMessage(msg: SessionHistoryMessage): ChatMessage {
+  // Fallback for history without chronological parts: synthesize the legacy
+  // grouped order (thinking, tools, text).
+  const parts =
+    msg.parts ??
+    [
+      ...(msg.thinking ? [{ kind: "thinking", text: msg.thinking } as const] : []),
+      ...msg.toolCalls.map((_, i) => ({ kind: "tool", toolIndex: i }) as const),
+      ...(msg.content ? [{ kind: "text", text: msg.content } as const] : []),
+    ];
+  const askUserExchanges = reconstructAskUserExchanges(msg.toolCalls);
+  return {
+    id: historyId(),
+    role: msg.role,
+    content: msg.content,
+    thinking: msg.thinking,
+    toolCalls: msg.toolCalls.map((tc): ToolCall => ({
+      id: tc.id,
+      name: tc.name,
+      input: tc.input,
+      inputJson: JSON.stringify(tc.input, null, 2),
+      output: tc.output,
+      isError: tc.isError,
+      status: "complete",
+    })),
+    parts,
+    isStreaming: false,
+    timestamp: Date.now(),
+    ...(askUserExchanges ? { askUserExchanges } : {}),
+    ...(msg.attachmentCount ? { attachmentCount: msg.attachmentCount } : {}),
+  };
+}
+
+/**
+ * Rebuild ask_user exchanges from a resumed message's tool calls. The ask_user
+ * tool's input carries the questions and its output carries the JSON answer
+ * payload, so an answered question survives session resume (rendered in its
+ * chronological slot, collapsed) instead of vanishing.
+ */
+function reconstructAskUserExchanges(
+  toolCalls: SessionHistoryMessage["toolCalls"]
+): AskUserExchange[] | undefined {
+  const exchanges: AskUserExchange[] = [];
+  for (const tc of toolCalls) {
+    if (!isAskUserTool(tc.name)) continue;
+    const questions = (tc.input?.questions as AskUserQuestion[]) ?? [];
+    const exchange: AskUserExchange = { requestId: tc.id, questions };
+    if (tc.output) {
+      try {
+        const payload = JSON.parse(tc.output) as {
+          answers?: Record<string, string>;
+          annotations?: AskUserExchange["annotations"];
+        };
+        exchange.answers = payload.answers;
+        exchange.annotations = payload.annotations;
+      } catch {
+        // Non-JSON output means the question was dismissed or errored out.
+        exchange.cancelled = true;
+      }
+    }
+    if (tc.isError && !exchange.answers) exchange.cancelled = true;
+    exchanges.push(exchange);
+  }
+  return exchanges.length ? exchanges : undefined;
+}
+
+/** Map a frame to the run-state its session should show in the session list. */
+export function runStateForFrame(msg: ServerMessage): "streaming" | "queued" | "idle" {
+  if (msg.type === "result" || msg.type === "error") return "idle";
+  if (msg.type === "status") {
+    if (msg.status === "queued") return "queued";
+    if (msg.status === "idle" || msg.status === "cancelled") return "idle";
+  }
+  return "streaming";
+}
+
+export function handleServerMessage(msg: ServerMessage) {
+  const state = useChatStore.getState();
+
+  // Parallel-session demux (per-session buffers). Every frame is scoped by
+  // sessionId; a scoped frame lands in ITS session's buffer, so a background
+  // session's transcript keeps accumulating while another one is in view.
+  // Frames without a sessionId (legacy single-session servers, or a new
+  // session's pre-binding frames) apply to the buffer in view.
+  const frameSessionId = (msg as { sessionId?: string }).sessionId;
+  if (frameSessionId) {
+    state.setRunState(frameSessionId, runStateForFrame(msg));
+  }
+
+  // Resolve the target buffer key for this frame.
+  let key: ChatKey;
+  if (!frameSessionId) {
+    key = state.activeSessionId; // null = the draft view
+  } else if (state.buffers[frameSessionId]) {
+    key = frameSessionId;
+  } else if (state.draft && (msg.type === "session_info" || msg.type === "result")) {
+    // A draft run just got its server identity: adopt the draft buffer.
+    state.bindDraftSession(frameSessionId);
+    key = frameSessionId;
+  } else if (msg.type === "session_info" && frameSessionId === state.activeSessionId) {
+    // The ACTIVE session announced itself but has no buffer yet — the cold
+    // reattach case (PWA relaunch mid-turn; the server may skip the history
+    // frame when a first turn has no history yet). Materialize the buffer so
+    // this session_info and every following delta land instead of vanishing.
+    state.setActiveSession(frameSessionId);
+    key = frameSessionId;
+  } else if (msg.type === "session_history") {
+    // History replay may create a buffer (cold resume / reattach).
+    key = frameSessionId;
+  } else {
+    // Scoped frame for a session with no buffer (never opened, or evicted):
+    // the badge above is all we track. The transcript heals via
+    // session_resume when the user opens it.
+    return;
+  }
+
+  const buffer = () => {
+    const s = useChatStore.getState();
+    return key === null ? s.draft : s.buffers[key];
+  };
+
+  switch (msg.type) {
+    case "text_delta":
+      if (!buffer()?.isStreaming) {
+        state.startAssistantMessage(key);
+      }
+      state.appendText(key, msg.text);
+      break;
+
+    case "thinking_delta":
+      if (!buffer()?.isStreaming) {
+        state.startAssistantMessage(key);
+      }
+      state.appendThinking(key, msg.text);
+      break;
+
+    case "tool_use_start":
+      state.startToolCall(key, msg.toolUseId, msg.toolName);
+      break;
+
+    case "tool_input_delta":
+      state.appendToolInput(key, msg.partialJson);
+      break;
+
+    case "tool_use_complete":
+      state.completeToolCall(key, msg.toolUseId, msg.toolName, msg.input);
+      break;
+
+    case "tool_approval_request":
+      state.requestToolApproval(key, msg.toolUseId, msg.toolName, msg.input, msg.description);
+      break;
+
+    case "tool_result": {
+      state.setToolResult(key, msg.toolUseId, msg.output, msg.isError);
+      // Once the agent receives the ask_user tool result, the exchange is
+      // complete — drop any leftover ask_user UI state.
+      const chat = buffer();
+      if (chat?.askUser?.answers || chat?.askUser?.cancelled) {
+        state.clearAskUser(key);
+      }
+      break;
+    }
+
+    case "ask_user_request":
+      state.setAskUserRequest(key, msg.requestId, msg.questions);
+      break;
+
+    case "location_request":
+      requestBrowserLocation(msg);
+      break;
+
+    case "result":
+      state.finishAssistantMessage(key);
+      resyncIfNeeded(msg.sessionId);
+      break;
+
+    case "session_info": {
+      // bindDraftSession above handled draft adoption; an info frame may still
+      // re-pin the provider picker when it concerns the session in view.
+      const current = useChatStore.getState();
+      if (frameSessionId && frameSessionId === current.activeSessionId) {
+        useProviderStore.getState().setPinned(msg.providerId ?? null);
+        // Reattachment on a fresh connection: enter streaming mode so deltas
+        // append to a live assistant message instead of vanishing.
+        const chat = current.buffers[frameSessionId];
+        if (chat && !chat.isStreaming && chat.messages.length === 0) {
+          current.startAssistantMessage(frameSessionId);
+        }
+      }
+      break;
+    }
+
+    case "session_history": {
+      const converted = msg.messages.map(convertHistoryMessage);
+      if (msg.append) {
+        state.appendMessages(key, converted);
+      } else {
+        // First (replacing) chunk = fresh authoritative transcript. Cancel any
+        // pending reconnect resync so we don't redundantly re-fetch it, and
+        // mark this session cold-resumed so idle-status handling doesn't loop.
+        state.setMessages(key, converted);
+        if (key !== null && key === resyncSessionId) resyncSessionId = null;
+        coldResumedSessionId = key;
+      }
+      break;
+    }
+
+    case "status": {
+      // Only finish streaming if this buffer actually started it
+      if (
+        (msg.status === "idle" || msg.status === "cancelled") &&
+        buffer()?.isStreaming
+      ) {
+        state.finishAssistantMessage(key);
+      }
+      // A session that finished while we were offline never delivers its
+      // `result` — the idle status on reconnect is the cue to resync. Keyed to
+      // THIS frame's session: a background session settling must not consume
+      // (or trigger) the active session's pending resync.
+      if (msg.status === "idle" || msg.status === "cancelled") {
+        const current = useChatStore.getState();
+        resyncIfNeeded(frameSessionId ?? current.activeSessionId);
+        // Cold load: we hold a stored session id but an empty transcript and
+        // the server is idle (so it sent no snapshot). Fetch the history.
+        // Only the active session's own (or an unscoped legacy) idle counts.
+        if (!frameSessionId || frameSessionId === current.activeSessionId) {
+          coldResumeIfNeeded(current.activeSessionId, activeChat(current).messages.length);
+        }
+      }
+      break;
+    }
+
+    case "error":
+      if (buffer()?.isStreaming) {
+        state.appendText(key, `\n\n**Error:** ${msg.message}`);
+        state.finishAssistantMessage(key);
+      }
+      break;
+  }
+}
+
+/**
+ * The server asked the browser for its location (the agent called
+ * `get_current_location`). Read `navigator.geolocation` and reply over the same
+ * requestId. The browser shows its own permission prompt on first use; a denial,
+ * timeout, or unavailable position comes back as a `location_error` that the
+ * server turns into a tool error for the agent.
+ */
+function requestBrowserLocation(msg: ServerLocationRequest) {
+  const { requestId } = msg;
+  if (typeof navigator === "undefined" || !navigator.geolocation) {
+    wsClient?.send({
+      type: "location_error",
+      requestId,
+      code: 0,
+      message: "Geolocation is not available in this browser.",
+    });
+    return;
+  }
+  const opts = msg.options ?? {};
+  navigator.geolocation.getCurrentPosition(
+    (pos) => {
+      wsClient?.send({
+        type: "location_response",
+        requestId,
+        coords: {
+          latitude: pos.coords.latitude,
+          longitude: pos.coords.longitude,
+          accuracy: pos.coords.accuracy,
+          altitude: pos.coords.altitude,
+          altitudeAccuracy: pos.coords.altitudeAccuracy,
+          heading: pos.coords.heading,
+          speed: pos.coords.speed,
+        },
+        timestamp: pos.timestamp,
+      });
+    },
+    (err) => {
+      wsClient?.send({
+        type: "location_error",
+        requestId,
+        code: err.code,
+        message: err.message || "Failed to retrieve location.",
+      });
+    },
+    {
+      enableHighAccuracy: opts.enableHighAccuracy ?? false,
+      timeout: opts.timeoutMs ?? 15000,
+      maximumAge: opts.maximumAgeMs ?? 60000,
+    }
+  );
+}
+
+// Reconnection bookkeeping: after a WS drop, the rendered transcript may have
+// gaps (deltas streamed while offline are lost). We heal by replaying the
+// authoritative session history — immediately if nothing is streaming, or
+// once the in-flight turn settles (result / idle status). The pending resync
+// is keyed to the session that needs healing (the one that was active at the
+// reconnect), so a background session settling first cannot consume it.
+let wasDisconnected = false;
+let resyncSessionId: string | null = null;
+
+function resyncIfNeeded(sessionId: string | null) {
+  if (!resyncSessionId || !sessionId || sessionId !== resyncSessionId) return;
+  resyncSessionId = null;
+  wsClient?.send({ type: "session_resume", sessionId });
+}
+
+// A cold page / PWA relaunch restores only the stored session id, not the
+// transcript. The server pushes a snapshot on connect only while a session is
+// actively running; when it's idle (the common "agent finished while the phone
+// slept" case) nothing arrives, so the client must fetch the finished
+// session's history itself. Guarded to fire at most once per session id per
+// connection — an empty session would otherwise re-trigger on every idle
+// status and loop.
+let coldResumedSessionId: string | null = null;
+
+function coldResumeIfNeeded(sessionId: string | null, messageCount: number) {
+  if (!sessionId || messageCount > 0) return;
+  if (coldResumedSessionId === sessionId) return;
+  coldResumedSessionId = sessionId;
+  wsClient?.send({ type: "session_resume", sessionId });
+}
+
+function handleStatusChange(status: "connecting" | "connected" | "disconnected") {
+  useConnectionStore.getState().setWsStatus(status);
+
+  if (status === "disconnected") {
+    wasDisconnected = true;
+    // Allow a fresh cold-resume attempt after we reconnect.
+    coldResumedSessionId = null;
+  } else if (status === "connected" && wasDisconnected) {
+    wasDisconnected = false;
+    const chat = useChatStore.getState();
+    const active = activeChat(chat);
+    if (chat.activeSessionId && active.messages.length > 0) {
+      resyncSessionId = chat.activeSessionId;
+      // Not mid-stream: replay right away. Mid-stream: the flag holds until
+      // the running turn finishes (result or idle status).
+      if (!active.isStreaming) {
+        resyncIfNeeded(chat.activeSessionId);
+      }
+    }
+  }
+}
+
+// Singleton client - survives React re-renders
+let wsClient: WSClient | null = null;
+
+export function useWebSocket() {
+  const initialized = useRef(false);
+
+  useEffect(() => {
+    if (initialized.current) return;
+    initialized.current = true;
+
+    wsClient = new WSClient(getWsUrl(), handleServerMessage, handleStatusChange);
+    wsClient.connect();
+
+    // Skip the exponential backoff when the network demonstrably returns.
+    const reconnectNow = () => wsClient?.reconnectNow();
+    const onVisible = () => {
+      if (document.visibilityState === "visible") wsClient?.reconnectNow();
+    };
+    window.addEventListener("online", reconnectNow);
+    document.addEventListener("visibilitychange", onVisible);
+
+    return () => {
+      window.removeEventListener("online", reconnectNow);
+      document.removeEventListener("visibilitychange", onVisible);
+      wsClient?.close();
+      wsClient = null;
+      initialized.current = false;
+    };
+  }, []);
+
+  const send = useCallback((msg: ClientMessage) => {
+    wsClient?.send(msg);
+  }, []);
+
+  return { send };
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+/**
+ * @schlessera/brain-ui-react — the chat UI as a component library.
+ *
+ * The deployment shell owns the document: index.html, the mount point, the
+ * Vite/PWA build, the service worker, and the theme entry (import ./theme.css
+ * into a Tailwind v4 build together with an @source pointing at this package's
+ * src, or use the precompiled ./styles.css export). The shell composes the
+ * pieces below and calls configureBrainUi() before mounting.
+ */
+
+// Branding / copy configuration (module singleton, set once at boot).
+export { configureBrainUi, uiConfig, type BrainUiConfig } from "./config.js";
+
+// Top-level surfaces the shell composes.
+export { ConnectionGate } from "./components/connectivity/connection-gate.js";
+export { AppShell } from "./components/layout/app-shell.js";
+export { ChatPage } from "./components/chat/chat-page.js";
+
+// Markdown renderer (also useful standalone, e.g. for a dev kitchen sink).
+export { BrainMarkdown } from "./components/chat/brain-markdown.js";
+
+// Stores + selectors the shell reads (service-worker busy check, deep links).
+export {
+  useChatStore,
+  activeChat,
+  anyStreaming,
+  type ChatKey,
+  type ChatMessage,
+  type SessionChat,
+  type ToolCall,
+  type AskUserExchange,
+  type MessageAttachment,
+} from "./stores/chat-store.js";
+export { useFileStore } from "./stores/file-store.js";
+export { useUIStore } from "./stores/ui-store.js";
+export { useConnectionStore } from "./stores/connection-store.js";
+export { useProviderStore } from "./stores/provider-store.js";
+export { useVoiceStore } from "./voice/voice-store.js";
+
+// Connectivity probes.
+export { useVpnStatus } from "./hooks/use-vpn-status.js";
+export { useWebSocket, handleServerMessage, runStateForFrame } from "./hooks/use-websocket.js";
+
+// API surface (typed REST client + backend URL helpers).
+export { api } from "./lib/api-client.js";
+export { API_BASE, getWsUrl, getBackendUrl } from "./lib/backend.js";