feat: persist chat history to backend (debounced PUT, hydrate on mount)

components/chat/AppShell.tsx

@@ -4,24 +4,32 @@ import { Sidebar } from "./Sidebar";
 import { TopBar } from "./TopBar";
 import { Aurora } from "./Aurora";
 import { useChatStore } from "@/lib/chatStore";
+import { useBackendSync } from "@/lib/useBackendSync";
 import clsx from "clsx";
 import { usePathname } from "next/navigation";
 import { useEffect } from "react";
 
 export function AppShell({ children }: { children: React.ReactNode }) {
   const sidebarOpen = useChatStore((s) => s.sidebarOpen);
+  const hydrated = useChatStore((s) => s.hydrated);
   const pathname = usePathname();
   const conversations = useChatStore((s) => s.conversations);
   const activeId = useChatStore((s) => s.activeId);
   const newConversation = useChatStore((s) => s.newConversation);
 
-  // Ensure there is always at least one conversation when on chat route
+  // Backend hydration + auto-save (debounced PUT to /conversations)
+  useBackendSync();
+
+  // Ensure there is always at least one conversation when on chat route.
+  // Wait until hydration completes so we don't create a placeholder before
+  // the remote state arrives (which would cause a flash + redundant save).
   useEffect(() => {
     if (pathname !== "/") return;
+    if (!hydrated) return;
     const hasAny = Object.keys(conversations).length > 0;
     const hasActive = activeId && conversations[activeId];
     if (!hasAny || !hasActive) newConversation();
-  }, [pathname, conversations, activeId, newConversation]);
+  }, [pathname, hydrated, conversations, activeId, newConversation]);
 
   return (
     <div className="relative min-h-screen flex flex-col">

components/chat/TopBar.tsx

@@ -10,6 +10,8 @@ export function TopBar() {
   const [pulse, setPulse] = useState<"alive" | "down" | "loading">("loading");
   const [pingMs, setPingMs] = useState<number | null>(null);
   const toggleSidebar = useChatStore((s) => s.toggleSidebar);
+  const syncStatus = useChatStore((s) => s.syncStatus);
+  const hydrated = useChatStore((s) => s.hydrated);
 
   useEffect(() => {
     let alive = true;
@@ -70,8 +72,9 @@ export function TopBar() {
           </Link>
         </div>
 
-        {/* Right: status pulse */}
-        <div className="flex items-center gap-3">
+        {/* Right: sync + status pulse */}
+        <div className="flex items-center gap-2">
+          <SyncBadge status={syncStatus} hydrated={hydrated} />
           <span
             className="hidden sm:flex items-center gap-2 rounded-pill px-3 py-1.5 bg-glass"
             style={{ boxShadow: "0 0 0 1px rgba(255,255,255,0.08)" }}
@@ -101,6 +104,49 @@ export function TopBar() {
   );
 }
 
+function SyncBadge({
+  status,
+  hydrated,
+}: {
+  status: "idle" | "saving" | "error";
+  hydrated: boolean;
+}) {
+  // Hide once steady-state idle to keep the chrome quiet — show only when
+  // there's something to communicate (loading, saving, error).
+  const visible = !hydrated || status === "saving" || status === "error";
+  if (!visible) return null;
+
+  const label =
+    !hydrated ? "Loading"
+    : status === "saving" ? "Saving"
+    : "Sync error";
+  const tone =
+    status === "error" ? "text-status-err" : "text-ink-50";
+  return (
+    <span
+      className={clsx(
+        "hidden sm:inline-flex items-center gap-1.5 rounded-pill px-2.5 py-1 text-micro font-mono uppercase tracking-[0.14em] transition-opacity",
+        tone
+      )}
+      title={
+        status === "error"
+          ? "Couldn't save chat history to backend"
+          : status === "saving"
+          ? "Saving chat history…"
+          : "Loading chat history…"
+      }
+    >
+      <span
+        className={clsx(
+          "inline-block w-1 h-1 rounded-full",
+          status === "error" ? "bg-status-err" : "bg-amber animate-pulse-soft"
+        )}
+      />
+      {label}
+    </span>
+  );
+}
+
 function Mark() {
   return (
     <span

lib/chatStore.ts

@@ -42,6 +42,11 @@ type ChatStore = {
   settings: Settings;
   sidebarOpen: boolean;
 
+  // sync state
+  hydrated: boolean;
+  syncStatus: "idle" | "saving" | "error";
+  lastSavedAt: number;
+
   // selectors
   active: () => Conversation | null;
   list: () => Conversation[];
@@ -59,6 +64,14 @@ type ChatStore = {
   resetSettings: () => void;
   toggleSidebar: () => void;
   setSidebarOpen: (open: boolean) => void;
+
+  // sync helpers (used by useBackendSync hook)
+  _setHydrated: (v: boolean) => void;
+  _setSyncStatus: (v: "idle" | "saving" | "error") => void;
+  _hydrateFromRemote: (payload: {
+    conversations: Record<string, Conversation>;
+    activeId: string | null;
+  }) => void;
 };
 
 const newId = () =>
@@ -81,6 +94,9 @@ export const useChatStore = create<ChatStore>()(
       activeId: null,
       settings: DEFAULT_SETTINGS,
       sidebarOpen: true,
+      hydrated: false,
+      syncStatus: "idle",
+      lastSavedAt: 0,
 
       active: () => {
         const { activeId, conversations } = get();
@@ -185,6 +201,53 @@ export const useChatStore = create<ChatStore>()(
       resetSettings: () => set({ settings: DEFAULT_SETTINGS }),
       toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
       setSidebarOpen: (open) => set({ sidebarOpen: open }),
+
+      // ── sync helpers ─────────────────────────────────────────────
+      _setHydrated: (v) => set({ hydrated: v }),
+      _setSyncStatus: (v) => set({ syncStatus: v }),
+      _hydrateFromRemote: ({ conversations, activeId }) =>
+        set((s) => {
+          // Merge remote into local: remote wins per-id (server is the
+          // source of truth on hydrate). If remote is empty but local has
+          // pending in-flight turns, keep local — avoids losing a turn
+          // that's mid-flight when hydration races with the request.
+          const remoteIds = Object.keys(conversations);
+          if (remoteIds.length === 0) {
+            // Server is empty — keep local; the next save will populate it.
+            return { hydrated: true };
+          }
+          // Preserve any locally-pending turns that aren't yet on server.
+          const merged: Record<string, Conversation> = { ...conversations };
+          for (const [id, local] of Object.entries(s.conversations)) {
+            if (!merged[id]) {
+              merged[id] = local;
+              continue;
+            }
+            const localPending = local.turns.filter((t) => t.pending);
+            if (localPending.length === 0) continue;
+            const serverTurnIds = new Set(merged[id].turns.map((t) => t.id));
+            const extras = localPending.filter(
+              (t) => !serverTurnIds.has(t.id)
+            );
+            if (extras.length > 0) {
+              merged[id] = {
+                ...merged[id],
+                turns: [...merged[id].turns, ...extras],
+              };
+            }
+          }
+          const nextActive =
+            activeId && merged[activeId]
+              ? activeId
+              : s.activeId && merged[s.activeId]
+              ? s.activeId
+              : Object.keys(merged)[0] ?? null;
+          return {
+            conversations: merged,
+            activeId: nextActive,
+            hydrated: true,
+          };
+        }),
     }),
     {
       name: "etiya-d2l-chat",

lib/sync.ts

@@ -0,0 +1,58 @@
+/**
+ * Backend persistence for chat history.
+ *
+ * Single shared store at /data/conversations.json on the backend Space.
+ * Frontend hydrates on mount and writes back on changes (debounced).
+ * Last-write-wins; no auth beyond the Space-level Bearer.
+ */
+import type { Conversation } from "./chatStore";
+
+const PROXY = "/api/proxy/conversations";
+
+export type RemoteConversationsPayload = {
+  conversations: Record<string, Conversation>;
+  activeId: string | null;
+  updatedAt?: number;
+  version?: number;
+};
+
+export async function loadConversations(): Promise<RemoteConversationsPayload | null> {
+  try {
+    const res = await fetch(PROXY, {
+      method: "GET",
+      headers: { "Content-Type": "application/json" },
+    });
+    if (!res.ok) {
+      console.warn("[sync] load failed", res.status);
+      return null;
+    }
+    const data = (await res.json()) as RemoteConversationsPayload;
+    return data;
+  } catch (err) {
+    console.warn("[sync] load error", err);
+    return null;
+  }
+}
+
+export async function saveConversations(
+  payload: RemoteConversationsPayload,
+  signal?: AbortSignal
+): Promise<boolean> {
+  try {
+    const res = await fetch(PROXY, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal,
+    });
+    if (!res.ok) {
+      console.warn("[sync] save failed", res.status);
+      return false;
+    }
+    return true;
+  } catch (err) {
+    if ((err as { name?: string })?.name === "AbortError") return false;
+    console.warn("[sync] save error", err);
+    return false;
+  }
+}

lib/useBackendSync.ts

@@ -0,0 +1,97 @@
+"use client";
+
+/**
+ * Drives hydration of the chat store from the backend on mount and
+ * pushes changes back up via debounced PUT.
+ *
+ * Behavior:
+ *   - On first mount: GET /conversations → merge into store → mark hydrated.
+ *   - On any change after hydration: schedule a PUT (debounced 1500ms).
+ *   - In-flight saves are aborted by the next save to avoid stale writes.
+ *   - Pending turns are excluded from the saved snapshot — the assistant
+ *     response lands as a normal change after pending=false flips.
+ */
+import { useEffect, useRef } from "react";
+import { useChatStore } from "./chatStore";
+import { loadConversations, saveConversations } from "./sync";
+
+const SAVE_DEBOUNCE_MS = 1500;
+
+export function useBackendSync() {
+  const hydrated = useChatStore((s) => s.hydrated);
+  const conversations = useChatStore((s) => s.conversations);
+  const activeId = useChatStore((s) => s.activeId);
+
+  const initialFetchStarted = useRef(false);
+  const saveTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const inFlight = useRef<AbortController | null>(null);
+
+  // ── 1) Hydrate on mount ───────────────────────────────────────────
+  useEffect(() => {
+    if (initialFetchStarted.current) return;
+    initialFetchStarted.current = true;
+
+    let cancelled = false;
+    (async () => {
+      const remote = await loadConversations();
+      if (cancelled) return;
+      const store = useChatStore.getState();
+      if (remote && remote.conversations) {
+        store._hydrateFromRemote({
+          conversations: remote.conversations,
+          activeId: remote.activeId ?? null,
+        });
+      } else {
+        // No remote / fetch failed — proceed with whatever localStorage had.
+        store._setHydrated(true);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // ── 2) Debounced save on change (only after hydrated) ─────────────
+  useEffect(() => {
+    if (!hydrated) return;
+
+    if (saveTimer.current) clearTimeout(saveTimer.current);
+    saveTimer.current = setTimeout(() => {
+      // Abort any in-flight save before starting a new one
+      if (inFlight.current) inFlight.current.abort();
+      const ctrl = new AbortController();
+      inFlight.current = ctrl;
+
+      // Strip in-flight pending turns from the saved snapshot — those
+      // resolve when the request returns and trigger their own save.
+      const sanitized: Record<string, typeof conversations[string]> = {};
+      for (const [id, conv] of Object.entries(conversations)) {
+        sanitized[id] = {
+          ...conv,
+          turns: conv.turns.filter((t) => !t.pending),
+        };
+      }
+
+      const setStatus = useChatStore.getState()._setSyncStatus;
+      setStatus("saving");
+      saveConversations(
+        {
+          conversations: sanitized,
+          activeId,
+        },
+        ctrl.signal
+      ).then((ok) => {
+        if (ctrl.signal.aborted) return;
+        setStatus(ok ? "idle" : "error");
+        if (ok) {
+          useChatStore.setState({ lastSavedAt: Date.now() });
+        }
+      });
+    }, SAVE_DEBOUNCE_MS);
+
+    return () => {
+      if (saveTimer.current) clearTimeout(saveTimer.current);
+    };
+  }, [hydrated, conversations, activeId]);
+}