feat(tree): paint sidebar tree instantly from localStorage boot cache

On page reload the sidebar tree rendered nothing until every root page was fetched (paginated), and children of expanded branches arrived even later (breadcrumbs effect / socket connect) — the tree visibly jumped a couple of seconds after load. - treeDataAtom is now a facade over atomFamily(atomWithStorage) keyed treeData:v1:{workspaceId}:{userId} with getOnInit: true — the cached tree hydrates synchronously and paints on the very first render, together with the already-persisted open-branches map. Public atom interface unchanged (value or functional updater), all call sites untouched. - Custom sync storage: debounced writes (500ms, coalesced, size guard, beforeunload flush), defensive reads (corrupted JSON -> []), no cross-tab subscribe (localStorage is a boot cache only). - SpaceTree renders on cached data immediately; "No pages yet" still waits for the server. Once server roots merge, open loaded branches are re-fetched fresh and reconciled once per space (shared refreshOpenBranches, also used by the socket reconnect handler). - Logout hygiene: clearPersistedTreeCaches() purges treeData:v1:* and openTreeNodes:* by prefix and disables further persistence (kill switch closes the websocket-write-vs-beforeunload-flush resurrection race). Wired into both handleLogout and the 401 redirectToLogin path, since cached trees contain page titles. - Tests: tree-data-atom.test.ts (hydration, debounce round-trip, corrupted JSON, scope isolation, logout purge, persistence kill switch); expand-all suite adapted. 144 tree tests / full client suite green, tsc clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-02 15:51:15 +03:00
13 changed files with 528 additions and 320 deletions
@@ -23,6 +23,7 @@ import { acceptInvitation } from "@/features/workspace/services/workspace-servic
 import APP_ROUTE, { getPostLoginRedirect } from "@/lib/app-route.ts";
 import { RESET } from "jotai/utils";
 import { useTranslation } from "react-i18next";
+import { clearPersistedTreeCaches } from "@/features/page/tree/atoms/tree-data-atom";

 export default function useAuth() {
  const { t } = useTranslation();
@@ -122,6 +123,9 @@ export default function useAuth() {

  const handleLogout = async () => {
    setCurrentUser(RESET);
+    // Purge the persisted sidebar tree caches (they contain page titles) so
+    // nothing readable is left in localStorage on a shared machine.
+    clearPersistedTreeCaches();
    await logout();
    window.location.replace(`${APP_ROUTE.AUTH.LOGIN}?logout=1`);
  };
@@ -13,20 +13,30 @@ export type OpenMap = Record<string, boolean>;
 // `OpenMap | Promise<OpenMap>` and break the functional-updater setter below).
 const openTreeNodesStorage = createJSONStorage<OpenMap>(() => localStorage);

+// Single source of truth for the open-map localStorage key prefix. Exported so
+// the logout cache sweep (tree-data-atom.ts) removes keys by the SAME prefix
+// used to write them — a rename here can never silently desync the cleanup.
+export const OPEN_TREE_NODES_KEY_PREFIX = "openTreeNodes:";
+
 // One persisted open/closed map per (workspace, user). Scoping the localStorage
 // key prevents accounts that share a browser origin from leaking tree state.
 // `getOnInit: true` reads localStorage synchronously at atom init (not on mount),
 // so the first render already has the saved state — no collapse-then-expand
 // flicker on reload, and writes never run against an un-hydrated empty map.
 const openTreeNodesFamily = atomFamily((scopeKey: string) =>
-  atomWithStorage<OpenMap>(`openTreeNodes:${scopeKey}`, {}, openTreeNodesStorage, {
-    getOnInit: true,
-  }),
+  atomWithStorage<OpenMap>(
+    `${OPEN_TREE_NODES_KEY_PREFIX}${scopeKey}`,
+    {},
+    openTreeNodesStorage,
+    { getOnInit: true },
+  ),
 );

 // Resolve the storage scope from the current user. Fall back to "anon" for the
 // workspace/user parts when nothing is loaded yet (logged out / first paint).
-const scopeKeyAtom = atom((get) => {
+// Shared by the open-map atom below and the persisted tree-data atom
+// (tree-data-atom.ts) so both caches are scoped identically.
+export const scopeKeyAtom = atom((get) => {
  const currentUser = get(currentUserAtom);
  const workspaceId = currentUser?.workspace?.id ?? "anon";
  const userId = currentUser?.user?.id ?? "anon";
@@ -0,0 +1,232 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { SpaceTreeNode } from "@/features/page/tree/types";
+import type { ICurrentUser } from "@/features/user/types/user.types";
+
+// The persisted tree-data atom hydrates from localStorage ONCE, at family-atom
+// creation (`getOnInit: true`). To exercise hydration deterministically each
+// test imports a FRESH module instance (fresh atomFamily) after seeding the
+// storage stub from vitest.setup.ts. jotai itself is externalized by vitest, so
+// `createStore` can stay a static import — atoms are plain objects and any
+// store works with any module instance.
+import { createStore } from "jotai";
+
+// Storage key for the default scope: no currentUser -> "anon:anon" (see
+// scopeKeyAtom in open-tree-nodes-atom.ts) with the `v1` cache-shape version.
+const ANON_KEY = "treeData:v1:anon:anon";
+const DEBOUNCE_MS = 500;
+
+async function freshImport() {
+  vi.resetModules();
+  const treeDataModule = await import("./tree-data-atom");
+  const userModule = await import(
+    "@/features/user/atoms/current-user-atom"
+  );
+  return {
+    treeDataAtom: treeDataModule.treeDataAtom,
+    flushPendingTreeDataWrites: treeDataModule.flushPendingTreeDataWrites,
+    clearPersistedTreeCaches: treeDataModule.clearPersistedTreeCaches,
+    currentUserAtom: userModule.currentUserAtom,
+  };
+}
+
+function node(id: string): SpaceTreeNode {
+  return {
+    id,
+    slugId: `slug-${id}`,
+    name: id,
+    position: "a0",
+    spaceId: "space-1",
+    parentPageId: null as unknown as string,
+    hasChildren: false,
+    children: [],
+  };
+}
+
+// Every persisted tree key currently in storage — asserting on the whole
+// prefix (not one known key) catches writes that resurrect under ANY scope.
+function persistedTreeDataKeys(): string[] {
+  const keys: string[] = [];
+  for (let i = 0; i < localStorage.length; i++) {
+    const key = localStorage.key(i);
+    if (key !== null && key.startsWith("treeData:v1:")) keys.push(key);
+  }
+  return keys;
+}
+
+function currentUser(workspaceId: string, userId: string): ICurrentUser {
+  return {
+    user: { id: userId },
+    workspace: { id: workspaceId },
+  } as unknown as ICurrentUser;
+}
+
+beforeEach(() => {
+  localStorage.clear();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+describe("treeDataAtom (localStorage-persisted)", () => {
+  it("reads [] from a fresh store with empty storage", async () => {
+    const { treeDataAtom } = await freshImport();
+    const store = createStore();
+
+    expect(store.get(treeDataAtom)).toEqual([]);
+  });
+
+  it("persists through the debounced setItem and hydrates a fresh module back", async () => {
+    vi.useFakeTimers();
+    const setItemSpy = vi.spyOn(localStorage, "setItem");
+
+    const { treeDataAtom } = await freshImport();
+    const store = createStore();
+
+    store.set(treeDataAtom, [node("a")]);
+    // Second write inside the debounce window — must coalesce into ONE flush
+    // carrying only the latest value.
+    vi.advanceTimersByTime(DEBOUNCE_MS / 2);
+    store.set(treeDataAtom, [node("a"), node("b")]);
+
+    // Nothing flushed yet: the write is trailing-debounced.
+    expect(localStorage.getItem(ANON_KEY)).toBeNull();
+
+    vi.advanceTimersByTime(DEBOUNCE_MS + 100);
+
+    expect(setItemSpy).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(localStorage.getItem(ANON_KEY)!)).toEqual([
+      node("a"),
+      node("b"),
+    ]);
+
+    // A fresh module (fresh atom family -> getOnInit re-reads storage) and a
+    // fresh store hydrate the persisted tree back — the reload scenario.
+    const second = await freshImport();
+    const store2 = createStore();
+    expect(store2.get(second.treeDataAtom)).toEqual([node("a"), node("b")]);
+  });
+
+  it("reads [] (without throwing) when storage holds corrupted JSON", async () => {
+    localStorage.setItem(ANON_KEY, "{definitely not JSON!!!");
+
+    const { treeDataAtom } = await freshImport();
+    const store = createStore();
+
+    expect(store.get(treeDataAtom)).toEqual([]);
+  });
+
+  it("reads [] when storage holds valid JSON of a non-array shape", async () => {
+    localStorage.setItem(ANON_KEY, JSON.stringify({ id: "not-a-tree" }));
+
+    const { treeDataAtom } = await freshImport();
+    const store = createStore();
+
+    expect(store.get(treeDataAtom)).toEqual([]);
+  });
+
+  it("supports functional-updater writes", async () => {
+    const { treeDataAtom } = await freshImport();
+    const store = createStore();
+
+    store.set(treeDataAtom, [node("a")]);
+    store.set(treeDataAtom, (prev) => [...prev, node("b")]);
+
+    expect(store.get(treeDataAtom).map((n) => n.id)).toEqual(["a", "b"]);
+  });
+
+  it("isolates trees between (workspace, user) scopes", async () => {
+    const { treeDataAtom, currentUserAtom } = await freshImport();
+    const store = createStore();
+
+    store.set(currentUserAtom, currentUser("w1", "u1"));
+    store.set(treeDataAtom, [node("a")]);
+    expect(store.get(treeDataAtom).map((n) => n.id)).toEqual(["a"]);
+
+    // Another account on the same browser origin must NOT see u1's tree.
+    store.set(currentUserAtom, currentUser("w2", "u2"));
+    expect(store.get(treeDataAtom)).toEqual([]);
+
+    store.set(treeDataAtom, [node("b")]);
+    expect(store.get(treeDataAtom).map((n) => n.id)).toEqual(["b"]);
+
+    // Switching back resolves the original scope's tree untouched.
+    store.set(currentUserAtom, currentUser("w1", "u1"));
+    expect(store.get(treeDataAtom).map((n) => n.id)).toEqual(["a"]);
+  });
+
+  it("clearPersistedTreeCaches removes all tree keys and discards pending writes", async () => {
+    vi.useFakeTimers();
+
+    // Stale caches across scopes plus an UNRELATED key that must survive.
+    localStorage.setItem("treeData:v1:a:b", JSON.stringify([node("stale")]));
+    localStorage.setItem("openTreeNodes:a:b", JSON.stringify({ p1: true }));
+    localStorage.setItem("currentUser", JSON.stringify({ user: { id: "b" } }));
+
+    const { treeDataAtom, clearPersistedTreeCaches } = await freshImport();
+    const store = createStore();
+
+    // Queue a debounced write (not flushed yet) for the anon scope.
+    store.set(treeDataAtom, [node("pending")]);
+    expect(localStorage.getItem(ANON_KEY)).toBeNull();
+
+    clearPersistedTreeCaches();
+
+    // Both prefixed caches are swept; the unrelated key is untouched.
+    expect(localStorage.getItem("treeData:v1:a:b")).toBeNull();
+    expect(localStorage.getItem("openTreeNodes:a:b")).toBeNull();
+    expect(localStorage.getItem("currentUser")).toBe(
+      JSON.stringify({ user: { id: "b" } }),
+    );
+
+    // The queued write was DISCARDED, not merely delayed: the debounce timer
+    // firing later must not resurrect a tree key after logout.
+    vi.advanceTimersByTime(DEBOUNCE_MS + 100);
+    expect(localStorage.getItem(ANON_KEY)).toBeNull();
+  });
+
+  it("clearPersistedTreeCaches discards queued writes even when flushed DIRECTLY", async () => {
+    vi.useFakeTimers();
+
+    const { treeDataAtom, clearPersistedTreeCaches, flushPendingTreeDataWrites } =
+      await freshImport();
+    const store = createStore();
+
+    // Queue a debounced write, then clear. Calling the flush directly (not via
+    // the debounce timer) isolates the pending-queue discard from the timer
+    // cancel: if the queue survived, this flush would resurrect the key even
+    // though the timer never fired.
+    store.set(treeDataAtom, [node("pending")]);
+    clearPersistedTreeCaches();
+    flushPendingTreeDataWrites();
+
+    expect(localStorage.getItem(ANON_KEY)).toBeNull();
+    expect(persistedTreeDataKeys()).toEqual([]);
+  });
+
+  it("disables persistence after clearPersistedTreeCaches: NEW writes never reach storage", async () => {
+    vi.useFakeTimers();
+
+    const { treeDataAtom, clearPersistedTreeCaches, flushPendingTreeDataWrites } =
+      await freshImport();
+    const store = createStore();
+
+    clearPersistedTreeCaches();
+
+    // The resurrection scenario: a websocket tree event lands while `await
+    // logout()` is still in flight, AFTER the sweep. The write must not be
+    // queued, must not arm a new debounce timer, and must not survive the
+    // beforeunload flush fired by the logout redirect.
+    store.set(treeDataAtom, [node("late")]);
+
+    vi.advanceTimersByTime(DEBOUNCE_MS + 100);
+    flushPendingTreeDataWrites(); // what the beforeunload handler runs
+
+    expect(persistedTreeDataKeys()).toEqual([]);
+
+    // Only PERSISTENCE is disabled: the in-memory atom keeps working, so the
+    // UI stays intact during the brief pre-redirect window.
+    expect(store.get(treeDataAtom).map((n) => n.id)).toEqual(["late"]);
+  });
+});
@@ -1,8 +1,200 @@
 import { atom } from "jotai";
+import { atomFamily, atomWithStorage } from "jotai/utils";
 import { SpaceTreeNode } from "@/features/page/tree/types";
 import { appendNodeChildren } from "../utils";
+import {
+  OPEN_TREE_NODES_KEY_PREFIX,
+  scopeKeyAtom,
+} from "./open-tree-nodes-atom";

-export const treeDataAtom = atom<SpaceTreeNode[]>([]);
+// The sidebar tree is persisted to localStorage so a page reload can paint the
+// last-known tree IMMEDIATELY (no blank sidebar while the root query runs) and
+// then reconcile with the server in the background. localStorage is a BOOT
+// CACHE only — the in-memory atom stays the source of truth while the app runs.
+
+// Trailing-debounce machinery for the localStorage writes. The tree is
+// rewritten on every lazy load / drag / socket event; serializing a large tree
+// on each update would burn CPU and thrash the storage quota, so writes are
+// coalesced (~500 ms per burst) and only the latest value per key is flushed.
+const WRITE_DEBOUNCE_MS = 500;
+
+// Single source of truth for the tree-cache localStorage key prefix. The `v1`
+// segment versions the cached node shape (bump it when SpaceTreeNode changes
+// incompatibly). Shared by the storage key construction below AND the logout
+// sweep in clearPersistedTreeCaches() so the two can never drift apart.
+export const TREE_DATA_KEY_PREFIX = "treeData:v1:";
+
+// Size guard: skip persisting trees whose JSON exceeds ~4M chars. localStorage
+// quota is typically ~5 MB per origin; a huge tree must not evict everything
+// else or spam QuotaExceededError on every debounce tick.
+const MAX_SERIALIZED_LENGTH = 4_000_000;
+
+const pendingWrites = new Map<string, SpaceTreeNode[]>();
+let flushTimer: ReturnType<typeof setTimeout> | null = null;
+let writeFailureWarned = false;
+
+// Persistence kill-switch, armed by clearPersistedTreeCaches(). Once set, the
+// debounced setItem and the flush become no-ops so nothing can be written back
+// to localStorage AFTER the logout sweep: a websocket tree event landing while
+// `await logout()` is still in flight would otherwise re-queue a write that
+// the `beforeunload` flush (fired by the redirect) silently resurrects.
+// Intentionally never reset: every caller of clearPersistedTreeCaches()
+// immediately navigates away with a full page load
+// (window.location.replace/href), so this module instance is torn down anyway.
+// Only PERSISTENCE stops — the in-memory atoms keep working, so the UI stays
+// intact during the brief pre-redirect window.
+let persistenceDisabled = false;
+
+function writeNow(key: string, value: SpaceTreeNode[]): void {
+  try {
+    const serialized = JSON.stringify(value);
+    if (serialized.length > MAX_SERIALIZED_LENGTH) {
+      console.warn("[tree] cached tree too large to persist; skipping", key);
+      return;
+    }
+    localStorage.setItem(key, serialized);
+  } catch (err) {
+    // QuotaExceededError, private mode, jsdom shims without working storage…
+    // The cache is best-effort: warn once, keep the in-memory tree working.
+    if (!writeFailureWarned) {
+      writeFailureWarned = true;
+      console.warn("[tree] failed to persist tree cache", err);
+    }
+  }
+}
+
+// Exported so tests can force the debounced write synchronously; production
+// code must never need it (the beforeunload hook below covers reloads).
+export function flushPendingTreeDataWrites(): void {
+  if (flushTimer !== null) {
+    clearTimeout(flushTimer);
+    flushTimer = null;
+  }
+  if (persistenceDisabled) {
+    // Belt-and-braces: after logout nothing may reach localStorage, even via
+    // the beforeunload flush racing the redirect. Drop anything queued.
+    pendingWrites.clear();
+    return;
+  }
+  for (const [key, value] of pendingWrites) {
+    writeNow(key, value);
+  }
+  pendingWrites.clear();
+}
+
+// Logout hygiene: the tree cache stores PAGE TITLES, so leaving it behind
+// would keep them readable in localStorage on a shared machine after logout.
+// Sweep by key prefix (not just the current scope) so stale scopes — old
+// users, the `anon:anon` fallback — are purged too. Pending debounced writes
+// are DISCARDED first (not flushed): a queued write firing after the sweep
+// would silently resurrect a removed key.
+export function clearPersistedTreeCaches(): void {
+  // Disable persistence FIRST so no write can be queued (or flushed) between
+  // the sweep below and the full-page navigation every caller performs next.
+  persistenceDisabled = true;
+  if (flushTimer !== null) {
+    clearTimeout(flushTimer);
+    flushTimer = null;
+  }
+  pendingWrites.clear();
+  try {
+    // Collect matching keys BEFORE removing: deleting while iterating
+    // `localStorage.key(i)` shifts the indices and skips entries.
+    const keysToRemove: string[] = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (
+        key !== null &&
+        (key.startsWith(TREE_DATA_KEY_PREFIX) ||
+          key.startsWith(OPEN_TREE_NODES_KEY_PREFIX))
+      ) {
+        keysToRemove.push(key);
+      }
+    }
+    for (const key of keysToRemove) {
+      localStorage.removeItem(key);
+    }
+  } catch {
+    // Best-effort: disabled storage / jsdom shims must never break logout.
+  }
+}
+
+// Flush the pending debounced write on unload so a reload right after a tree
+// change doesn't lose the newest state (the debounce would otherwise eat it).
+if (
+  typeof window !== "undefined" &&
+  typeof window.addEventListener === "function"
+) {
+  window.addEventListener("beforeunload", flushPendingTreeDataWrites);
+}
+
+// Custom sync storage for the tree cache. Deliberately NO `subscribe` key:
+// cross-tab sync would REPLACE this tab's tree wholesale and clobber in-flight
+// lazy loads; websockets already keep every open tab live. Each tab keeps its
+// own in-memory tree — localStorage only seeds the next boot.
+const treeDataStorage = {
+  getItem: (key: string, initialValue: SpaceTreeNode[]): SpaceTreeNode[] => {
+    // Defensive: jsdom test shims may lack methods, stored JSON may be
+    // corrupted or of a wrong shape. Any failure falls back to the empty tree.
+    try {
+      const raw = localStorage.getItem(key);
+      if (raw === null) return initialValue;
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? (parsed as SpaceTreeNode[]) : initialValue;
+    } catch {
+      return initialValue;
+    }
+  },
+  setItem: (key: string, newValue: SpaceTreeNode[]): void => {
+    // After logout the cache must stay purged: neither queue the write nor arm
+    // a new flush timer (see persistenceDisabled above). The in-memory atom
+    // value is unaffected — only the localStorage mirror is frozen.
+    if (persistenceDisabled) return;
+    pendingWrites.set(key, newValue);
+    if (flushTimer !== null) clearTimeout(flushTimer);
+    flushTimer = setTimeout(flushPendingTreeDataWrites, WRITE_DEBOUNCE_MS);
+  },
+  removeItem: (key: string): void => {
+    pendingWrites.delete(key);
+    try {
+      localStorage.removeItem(key);
+    } catch {
+      /* best-effort cache — ignore */
+    }
+  },
+};
+
+// One persisted tree per (workspace, user) — same scoping rationale as the
+// open-map atom (accounts sharing a browser origin must not leak trees).
+// `getOnInit: true` reads localStorage synchronously at atom init, so the very
+// first render already has the cached tree — no blank-then-jump sidebar.
+const treeDataFamily = atomFamily((scopeKey: string) =>
+  atomWithStorage<SpaceTreeNode[]>(
+    `${TREE_DATA_KEY_PREFIX}${scopeKey}`,
+    [],
+    treeDataStorage,
+    { getOnInit: true },
+  ),
+);
+
+// Public facade — same read value (SpaceTreeNode[]) and same setter shape
+// (value OR functional updater) as the previous in-memory atom, transparently
+// routed to the persisted tree of the current workspace/user.
+export const treeDataAtom = atom(
+  (get) => get(treeDataFamily(get(scopeKeyAtom))),
+  (
+    get,
+    set,
+    update: SpaceTreeNode[] | ((prev: SpaceTreeNode[]) => SpaceTreeNode[]),
+  ) => {
+    const target = treeDataFamily(get(scopeKeyAtom));
+    const next =
+      typeof update === "function"
+        ? (update as (prev: SpaceTreeNode[]) => SpaceTreeNode[])(get(target))
+        : update;
+    set(target, next);
+  },
+);

 // Atom
 export const appendNodeChildrenAtom = atom(
@@ -71,7 +71,8 @@ vi.mock("@mantine/core", () => ({
 // getOnInit), which crashes under jsdom's localStorage shim here. Swap in a
 // plain in-memory atom with the same read value (OpenMap) and the same setter
 // shape (value OR functional updater) so the component's open-state logic runs
-// unchanged while staying inside the test store.
+// unchanged while staying inside the test store. `scopeKeyAtom` is also
+// re-exported (the real module exports it for the persisted tree-data atom).
 vi.mock("@/features/page/tree/atoms/open-tree-nodes-atom.ts", async () => {
  const { atom } = await import("jotai");
  type OpenMap = Record<string, boolean>;
@@ -86,11 +87,17 @@ vi.mock("@/features/page/tree/atoms/open-tree-nodes-atom.ts", async () => {
      set(base, next);
    },
  );
-  return { openTreeNodesAtom };
+  // Fixed scope key: the tree-data atom family resolves through this, so all
+  // tests read/write the same (empty at start of each test) storage key.
+  const scopeKeyAtom = atom(() => "test-workspace:test-user");
+  return { openTreeNodesAtom, scopeKeyAtom };
 });

 import SpaceTree, { SpaceTreeApi } from "./space-tree";
-import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
+import {
+  treeDataAtom,
+  flushPendingTreeDataWrites,
+} from "@/features/page/tree/atoms/tree-data-atom.ts";
 import { openTreeNodesAtom } from "@/features/page/tree/atoms/open-tree-nodes-atom.ts";
 import { createStore, Provider } from "jotai";
 import type { SpaceTreeNode } from "@/features/page/tree/types.ts";
@@ -134,6 +141,10 @@ function renderTree(store: ReturnType<typeof createStore>) {
 beforeEach(() => {
  getSpaceTreeMock.mockReset();
  notificationsShowMock.mockReset();
+  // The tree-data atom persists via a ~500 ms trailing debounce; flush it NOW
+  // (cancelling the timer) so a previous test's pending write can't land in
+  // storage mid-test after the clear below.
+  flushPendingTreeDataWrites();
  // jsdom's localStorage shim here lacks `clear`; guard it. Each test uses a
  // fresh jotai store anyway, so cross-test open-state never leaks.
  try {
@@ -199,45 +199,66 @@ const SpaceTree = forwardRef<SpaceTreeApi, SpaceTreeProps>(function SpaceTree(
  const openIdsRef = useRef(openIds);
  openIdsRef.current = openIds;

-  // Reconnect refresh (#159 #8): on a socket reconnect, re-fetch and reconcile
-  // the children of every currently-open, already-loaded branch of THIS space,
+  // Re-fetch and reconcile the children of every currently-open, already-loaded
+  // branch of THIS space. Shared by the socket reconnect handler and the
+  // post-load cache refresh below. The ROOT level is reconciled separately by
+  // the root-query refetch + mergeRootTrees; an UNLOADED branch is skipped
+  // (lazy-load fetches it fresh on expand). Reads refs so it always sees the
+  // latest tree/open-state/space without re-creating the callback.
+  const refreshOpenBranches = useCallback(async () => {
+    const effectSpaceId = spaceIdRef.current;
+    const branchIds = loadedOpenBranchIds(
+      dataRef.current.filter((n) => n?.spaceId === effectSpaceId),
+      openIdsRef.current,
+    );
+    if (branchIds.length === 0) return;
+    for (const id of branchIds) {
+      try {
+        // `fresh: true` bypasses the 30-min sidebar-pages cache so the
+        // reconcile sees the server's CURRENT children (handler-order
+        // independent — no reliance on the global reconnect invalidation).
+        const fresh = await fetchAllAncestorChildren(
+          { pageId: id, spaceId: effectSpaceId },
+          { fresh: true },
+        );
+        if (spaceIdRef.current !== effectSpaceId) return; // space switched
+        setData((prev) => treeModel.reconcileChildren(prev, id, fresh));
+      } catch (err) {
+        console.error("[tree] open branch refresh failed", err);
+      }
+    }
+  }, [setData]);
+
+  // Reconnect refresh (#159 #8): on a socket reconnect, refresh open branches
  // so a move/rename/delete that happened INSIDE a loaded branch while events
  // were missed (laptop sleep / wifi gap) is reflected instead of left stale.
-  // The ROOT level is reconciled separately by the root-query refetch +
-  // mergeRootTrees; an UNLOADED branch is skipped (lazy-load fetches it fresh on
-  // expand). No first-connect guard is needed: space-tree usually mounts AFTER
-  // the initial connect, so every `connect` it sees is a reconnect; the rare
+  // No first-connect guard is needed: space-tree usually mounts AFTER the
+  // initial connect, so every `connect` it sees is a reconnect; the rare
  // initial-connect case has an empty tree, so the refresh is a harmless no-op.
  useEffect(() => {
    if (!socket) return;
-    const onConnect = async () => {
-      const effectSpaceId = spaceIdRef.current;
-      const branchIds = loadedOpenBranchIds(
-        dataRef.current.filter((n) => n?.spaceId === effectSpaceId),
-        openIdsRef.current,
-      );
-      if (branchIds.length === 0) return;
-      for (const id of branchIds) {
-        try {
-          // `fresh: true` bypasses the 30-min sidebar-pages cache so the
-          // reconcile sees the server's CURRENT children (handler-order
-          // independent — no reliance on the global reconnect invalidation).
-          const fresh = await fetchAllAncestorChildren(
-            { pageId: id, spaceId: effectSpaceId },
-            { fresh: true },
-          );
-          if (spaceIdRef.current !== effectSpaceId) return; // space switched
-          setData((prev) => treeModel.reconcileChildren(prev, id, fresh));
-        } catch (err) {
-          console.error("[tree] reconnect branch refresh failed", err);
-        }
-      }
+    const onConnect = () => {
+      refreshOpenBranches();
    };
    socket.on("connect", onConnect);
    return () => {
      socket.off("connect", onConnect);
    };
-  }, [socket, setData]);
+  }, [socket, refreshOpenBranches]);
+
+  // Post-load cache refresh: the sidebar paints instantly from the
+  // localStorage-cached tree, so children of open branches may be stale. Once
+  // the server root set has been merged for this space (isDataLoaded flips
+  // true), refresh every open, already-loaded branch ONCE per space per mount.
+  // dataRef.current is already up to date here: refs are assigned during
+  // render, and this effect runs after the merge-triggered re-render commit.
+  const refreshedSpacesRef = useRef<Set<string>>(new Set());
+  useEffect(() => {
+    if (!isDataLoaded) return;
+    if (refreshedSpacesRef.current.has(spaceId)) return;
+    refreshedSpacesRef.current.add(spaceId);
+    refreshOpenBranches();
+  }, [isDataLoaded, spaceId, refreshOpenBranches]);

  const handleToggle = useCallback(
    async (id: string, isOpen: boolean) => {
@@ -333,12 +354,17 @@ const SpaceTree = forwardRef<SpaceTreeApi, SpaceTreeProps>(function SpaceTree(

  return (
    <div className={classes.treeContainer}>
+      {/* "No pages yet" only after the SERVER confirmed the space is empty —
+          never while just the localStorage cache is empty. */}
      {isDataLoaded && filteredData.length === 0 && (
        <Text size="xs" c="dimmed" py="xs" px="sm">
          {t("No pages yet")}
        </Text>
      )}
-      {isDataLoaded && filteredData.length > 0 && (
+      {/* Cache-first paint: render as soon as ANY data exists (synchronous
+          localStorage hydration) instead of waiting for the server round-trip;
+          the background merge/refresh reconciles it afterwards. */}
+      {filteredData.length > 0 && (
        <DocTree<SpaceTreeNode>
          data={filteredData}
          openIds={openIds}
@@ -1,6 +1,7 @@
 import axios, { AxiosInstance } from "axios";
 import APP_ROUTE from "@/lib/app-route.ts";
 import { isCloud } from "@/lib/config.ts";
+import { clearPersistedTreeCaches } from "@/features/page/tree/atoms/tree-data-atom";

 const api: AxiosInstance = axios.create({
  baseURL: "/api",
@@ -71,6 +72,12 @@ function redirectToLogin() {
    "/invites",
  ];
  if (!exemptPaths.some((path) => window.location.pathname.startsWith(path))) {
+    // Forced logout (401 / expired session) must purge the persisted sidebar
+    // tree caches too: they contain page titles, and on a shared machine most
+    // sessions end via cookie expiry — not the logout button — so this is the
+    // only cleanup that runs on that path. It also disables further cache
+    // persistence until the full page load below.
+    clearPersistedTreeCaches();
    const redirectTo = window.location.pathname;
    if (redirectTo === APP_ROUTE.HOME) {
      window.location.href = APP_ROUTE.AUTH.LOGIN;
@@ -303,11 +303,6 @@ describe('buildSystemPrompt page-changed note (#274)', () => {
    expect(prompt).toContain(NOTE_MARKER);
    expect(prompt).toContain('-old line');
    expect(prompt).toContain('+new line');
-    // Strengthened note (#274): instructs a fresh re-read via getPage and steers
-    // the agent toward small, targeted edits instead of a full-page overwrite.
-    expect(prompt).toContain('getPage');
-    expect(prompt.toLowerCase()).toContain('targeted');
-    expect(prompt).toContain('editPageText');
    // Inside the safety sandwich: the trailing SAFETY block follows the note.
    expect(prompt.lastIndexOf(SAFETY_MARKER)).toBeGreaterThan(
      prompt.indexOf(NOTE_MARKER),
@@ -85,17 +85,11 @@ const INTERRUPT_NOTE =
 const PAGE_CHANGED_NOTE =
  'NOTE: The user edited the open page AFTER your last response in this ' +
  'conversation, so any copy of that page you produced or remember from earlier ' +
-  'is now STALE and must not be reused. Before you edit the page, you MUST first ' +
-  're-read its current content with the getPage tool and base your work on that ' +
-  'live version — never on your earlier copy or on the transcript. The unified ' +
-  'diff below shows exactly what the user changed since you last spoke (lines ' +
-  'starting with "-" were removed, "+" were added) and is the source of truth. ' +
-  'Preserve every one of the user\'s edits: make the smallest change that ' +
-  'satisfies the request using the targeted edit tools (editPageText, patchNode, ' +
-  'insertNode, deleteNode) rather than replacing the whole page, and do not ' +
-  'revert, drop, or overwrite anything the user changed. If a full rewrite is ' +
-  'truly unavoidable, start from the current getPage content and carry over all ' +
-  'of the user\'s edits.';
+  'is now STALE. The unified diff below shows exactly what changed since you last ' +
+  'spoke (lines starting with "-" were removed, "+" were added) and is the source ' +
+  'of truth. Preserve the user\'s edits: build on the current page, do not revert ' +
+  'or overwrite their changes. If you need the full up-to-date page, re-read it ' +
+  'with the getPage tool before editing.';

 /**
 * Sanitize a value interpolated into a prompt XML-ish attribute (e.g.
@@ -356,32 +356,6 @@ describe('flushAssistant', () => {
    expect(flushed.toolCalls).not.toBeNull();
    expect(flushed.metadata.error).toBe('boom');
  });
-
-  // #274 observability: the page-change diff the agent saw this turn is persisted
-  // to metadata.pageChanged when a non-empty diff was injected, and omitted when
-  // the diff is empty/whitespace or the arg is not supplied.
-  it('persists metadata.pageChanged when a non-empty diff was injected', () => {
-    const f = flushAssistant([], '', 'completed', {
-      pageChanged: { title: 'Doc', diff: '@@ -1 +1 @@\n-old\n+new' },
-    });
-    expect(f.metadata.pageChanged).toEqual({
-      title: 'Doc',
-      diff: '@@ -1 +1 @@\n-old\n+new',
-    });
-  });
-
-  it('omits metadata.pageChanged for an empty/whitespace diff or a missing arg', () => {
-    const whitespace = flushAssistant([], '', 'completed', {
-      pageChanged: { title: 'Doc', diff: '   \n  ' },
-    });
-    expect('pageChanged' in whitespace.metadata).toBe(false);
-
-    const nullArg = flushAssistant([], '', 'completed', { pageChanged: null });
-    expect('pageChanged' in nullArg.metadata).toBe(false);
-
-    const omitted = flushAssistant([], '', 'streaming');
-    expect('pageChanged' in omitted.metadata).toBe(false);
-  });
 });

 /**
@@ -685,7 +685,7 @@ export class AiChatService implements OnModuleInit {
    // no-op (guarded below) so the turn still streams to the user.
    let assistantId: string | undefined;
    try {
-      const seed = flushAssistant([], '', 'streaming', { pageChanged });
+      const seed = flushAssistant([], '', 'streaming');
      const seeded = await this.aiChatMessageRepo.insert({
        chatId,
        workspaceId: workspace.id,
@@ -720,7 +720,7 @@ export class AiChatService implements OnModuleInit {
        await this.aiChatMessageRepo.update(
          assistantId,
          workspace.id,
-          flushAssistant(capturedSteps, '', 'streaming', { pageChanged }),
+          flushAssistant(capturedSteps, '', 'streaming'),
          { onlyIfStreaming: true },
        );
      } catch (err) {
@@ -860,7 +860,6 @@ export class AiChatService implements OnModuleInit {
              // resolved from the admin-configured provider settings (in
              // closure scope here). Omitted/0 = no limit.
              maxContextTokens: resolved?.chatContextWindow,
-              pageChanged,
            }),
          );
          // Lifecycle: release the external MCP clients leased for this turn.
@@ -912,7 +911,6 @@ export class AiChatService implements OnModuleInit {
          await finalizeAssistant(
            flushAssistant(capturedSteps, inProgressText, 'error', {
              error: errorText,
-              pageChanged,
            }),
          );
          await closeExternalClients();
@@ -942,9 +940,7 @@ export class AiChatService implements OnModuleInit {
              `steps=${steps.length}`,
          );
          await finalizeAssistant(
-            flushAssistant(capturedSteps, inProgressText, 'aborted', {
-              pageChanged,
-            }),
+            flushAssistant(capturedSteps, inProgressText, 'aborted'),
          );
          await closeExternalClients();
          // Advance the page snapshot even on abort (#274): an agent edit that
@@ -1510,7 +1506,6 @@ export function flushAssistant(
    contextTokens?: number;
    maxContextTokens?: number;
    error?: string;
-    pageChanged?: { title: string; diff: string } | null;
  },
 ): AssistantFlush {
  const finished = capturedSteps ?? [];
@@ -1543,15 +1538,6 @@ export function flushAssistant(
  if (extra?.maxContextTokens)
    metadata.maxContextTokens = extra.maxContextTokens;
  if (extra?.error) metadata.error = extra.error;
-  // Persist the page-change diff the agent saw this turn (#274 observability),
-  // so history / the Markdown export can show what the user changed. Only when
-  // a non-empty diff was actually injected into the prompt this turn.
-  if (extra?.pageChanged && extra.pageChanged.diff?.trim().length) {
-    metadata.pageChanged = {
-      title: extra.pageChanged.title,
-      diff: extra.pageChanged.diff,
-    };
-  }

  return {
    content: stepsText + trailing,
@@ -269,168 +269,6 @@ describe('buildChatMarkdown (server) — structure', () => {
    expect(md).toContain('**⚠️ Error:** 401: Unauthorized');
  });

-  // #274 observability: an assistant row whose turn started with a user edit to
-  // the open page carries metadata.pageChanged = { title, diff }; the export
-  // renders the diff the agent saw, before the message body.
-  it('renders the persisted page-change diff block for an assistant row', () => {
-    const md = buildChatMarkdown({
-      title: 'T',
-      chatId: 'c',
-      rows: [
-        row({
-          role: 'assistant',
-          content: 'answer',
-          metadata: {
-            pageChanged: { title: 'Doc', diff: '@@ -1 +1 @@\n-old\n+new' },
-          } as never,
-        }),
-      ],
-    });
-    expect(md).toContain(
-      'The user edited this page before this turn; the diff the agent saw:',
-    );
-    expect(md).toContain('("Doc")');
-    expect(md).toContain('-old');
-    expect(md).toContain('+new');
-    // The diff sits before the message body (chronological: change, then reply).
-    expect(md.indexOf('-old')).toBeLessThan(md.indexOf('answer'));
-  });
-
-  it('does not render the page-change block when metadata.pageChanged is absent', () => {
-    const md = buildChatMarkdown({
-      title: 'T',
-      chatId: 'c',
-      rows: [row({ role: 'assistant', content: 'answer' })],
-    });
-    expect(md).not.toContain(
-      'The user edited this page before this turn; the diff the agent saw:',
-    );
-  });
-
-  // #288 F1/F2: an empty page title must render the BARE heading with no
-  // `("…")` suffix (the `pc.title ? … : …` false branch).
-  it('renders the page-change heading with no title suffix when title is empty', () => {
-    const md = buildChatMarkdown({
-      title: 'T',
-      chatId: 'c',
-      rows: [
-        row({
-          role: 'assistant',
-          content: 'answer',
-          metadata: {
-            pageChanged: { title: '', diff: '@@ -1 +1 @@\n-old\n+new' },
-          } as never,
-        }),
-      ],
-    });
-    // Bare heading, single line, no parenthesized title.
-    expect(md).toContain(
-      '> **📝 The user edited this page before this turn; the diff the agent saw:**',
-    );
-    expect(md).not.toContain('("');
-    expect(md).toContain('-old');
-  });
-
-  // #288 F1: the page title is UNTRUSTED cross-user data, so a title carrying a
-  // newline / backtick / `"` / `<`/`>` must be neutralized by escapeAttr before
-  // it is interpolated into the `> **…**` blockquote heading — otherwise it
-  // could break the blockquote onto multiple lines or inject markup/HTML into
-  // the downloaded .md. escapeAttr strips `<>"` and collapses whitespace runs to
-  // a single space, so `Ev"il\n> `x` <b>` becomes ``Evil `x` b``.
-  it('escapes an untrusted page title in the page-change heading', () => {
-    const md = buildChatMarkdown({
-      title: 'T',
-      chatId: 'c',
-      rows: [
-        row({
-          role: 'assistant',
-          content: 'answer',
-          metadata: {
-            pageChanged: {
-              title: 'Ev"il\n> `x` <b>',
-              diff: '@@ -1 +1 @@\n-old\n+new',
-            },
-          } as never,
-        }),
-      ],
-    });
-    // The heading stays a single blockquote line with the escaped title.
-    expect(md).toContain(
-      '> **📝 The user edited this page before this turn; the diff the agent saw: ("Evil `x` b")**',
-    );
-    // No raw attribute/markup breakers survived from the title.
-    expect(md).not.toContain('Ev"il');
-    expect(md).not.toContain('<b>');
-  });
-
-  // #288 review F1: escapeAttr ALONE is insufficient for this MARKDOWN sink —
-  // link/image syntax survives it. A cross-user title with `![x](url)` /
-  // `[phish](url)` must NOT become a working remote image or clickable link in
-  // the downloaded .md; markdownHeadingSafe backslash-escapes `[`/`]` so both are
-  // inert. (Non-vacuous: fails against the escapeAttr-only version, which left
-  // `](https://` intact.)
-  it('neutralizes markdown link/image syntax in an untrusted page title', () => {
-    const md = buildChatMarkdown({
-      title: 'T',
-      chatId: 'c',
-      rows: [
-        row({
-          role: 'assistant',
-          content: 'answer',
-          metadata: {
-            pageChanged: {
-              title:
-                '![x](https://attacker.example/t.png) and [click](https://phish.example)',
-              diff: '@@ -1 +1 @@\n-old\n+new',
-            },
-          } as never,
-        }),
-      ],
-    });
-    // No WORKING image/link syntax survives — the `[…]` sits escaped as `\[…\]`,
-    // so the unescaped `![x](` image and `[click](` link markers are gone. (We
-    // deliberately do NOT assert `not.toContain('](https://')`: after escaping the
-    // literal `\](https://` still contains `](https://` as a raw substring — that
-    // check would false-fail even though the link is inert.)
-    expect(md).not.toContain('![x](');
-    expect(md).not.toContain('[click](');
-    // The brackets are backslash-escaped, so `[text](url)`/`![text](url)` are inert.
-    expect(md).toContain('\\[');
-    expect(md).toContain('\\]');
-    // The heading stays a SINGLE blockquote line (no newline injected).
-    const headingLine = md
-      .split('\n')
-      .find((l) => l.includes('the diff the agent saw:'));
-    expect(headingLine).toBeDefined();
-    expect(headingLine).toContain('\\[x\\]');
-    expect(headingLine).toContain('\\[click\\]');
-  });
-
-  // #288 internal review Finding 2: a NON-empty title made up entirely of
-  // escapeAttr breakers (`<>"`) escapes to '' — the ternary must then fall to the
-  // BARE heading with NO `("…")` suffix. Locks the ternary-on-escaped-value
-  // behavior (distinct from the empty-string input test above).
-  it('renders the bare heading for a title that escapes to empty', () => {
-    const md = buildChatMarkdown({
-      title: 'T',
-      chatId: 'c',
-      rows: [
-        row({
-          role: 'assistant',
-          content: 'answer',
-          metadata: {
-            pageChanged: { title: '<>"', diff: '@@ -1 +1 @@\n-old\n+new' },
-          } as never,
-        }),
-      ],
-    });
-    expect(md).toContain(
-      '> **📝 The user edited this page before this turn; the diff the agent saw:**',
-    );
-    expect(md).not.toContain('("');
-    expect(md).toContain('-old');
-  });
-
  it('escapes embedded triple-backtick fences with a longer delimiter', () => {
    const md = buildChatMarkdown({
      title: 'T',
@@ -15,7 +15,6 @@
 */

 import type { AiChatMessage } from '@docmost/db/types/entity.types';
-import { escapeAttr } from './ai-chat.prompt';

 /** Supported export label languages. Defaults to English. */
 export type ExportLang = 'en' | 'ru';
@@ -64,7 +63,6 @@ const LABELS: Record<
    tools: Record<string, string>;
    ranTool: (name: string) => string;
    stillGenerating: string;
-    pageEditedByUser: string;
  }
 > = {
  en: {
@@ -85,8 +83,6 @@ const LABELS: Record<
    ranTool: (name) => `Ran tool ${name}`,
    stillGenerating:
      'This message is still being generated — the export captured a partial, in-progress response.',
-    pageEditedByUser:
-      'The user edited this page before this turn; the diff the agent saw:',
  },
  ru: {
    untitled: 'Без названия',
@@ -106,29 +102,9 @@ const LABELS: Record<
    ranTool: (name) => `Выполнил инструмент ${name}`,
    stillGenerating:
      'Это сообщение всё ещё генерируется — экспорт захватил частичный, незавершённый ответ.',
-    pageEditedByUser:
-      'Пользователь изменил страницу перед этим ходом; дифф, который видел агент:',
  },
 };

-/**
- * Make an untrusted title safe to interpolate into a Markdown blockquote
- * HEADING. escapeAttr() neutralizes the XML/HTML breakers (`<` `>` `"`) and
- * collapses whitespace for the PROMPT sink (`page="…"`), but this export sink is
- * MARKDOWN — link/image syntax survives escapeAttr. So additionally backslash-
- * escape `[` and `]`: that disables both `[text](url)` links and `![text](url)`
- * images, so a cross-user title like `![x](http://evil)` or `[phish](http://evil)`
- * cannot inject a remote (auto-loading) image or a clickable link into the
- * downloaded .md disguised as a trusted system annotation. A bare `(url)` with no
- * preceding `[]` is inert Markdown, so brackets are the only security-critical
- * characters here. (We leave backticks to escapeAttr's whitespace pass — a title
- * shown as inline code cannot escape the blockquote line or load a resource, so
- * it is not a security concern for this sink.)
- */
-function markdownHeadingSafe(title: string): string {
-  return escapeAttr(title).replace(/[[\]]/g, (m) => `\\${m}`);
-}
-
 /** True for AI SDK tool parts (static `tool-*` or `dynamic-tool`). */
 function isToolPart(type: string): boolean {
  return type.startsWith('tool-') || type === 'dynamic-tool';
@@ -232,23 +208,6 @@ function rowParts(row: AiChatMessage): ExportPart[] {
    : [{ type: 'text', text: row.content ?? '' }];
 }

-/** The persisted page-change diff the agent saw this turn (#274), when any. */
-function pageChangedOf(
-  row: AiChatMessage,
-): { title: string; diff: string } | undefined {
-  const meta = (row.metadata ?? {}) as {
-    pageChanged?: { title?: string; diff?: string };
-  };
-  const pc = meta.pageChanged;
-  if (pc && typeof pc.diff === 'string' && pc.diff.trim().length > 0) {
-    return {
-      title: typeof pc.title === 'string' ? pc.title : '',
-      diff: pc.diff,
-    };
-  }
-  return undefined;
-}
-
 /**
 * Serialize a chat to a Markdown string from its persisted rows. Source = DB
 * ONLY (no live client state). A row whose `status` is still 'streaming' is an
@@ -307,26 +266,6 @@ export function buildChatMarkdown(args: {
      blocks.push(`<!-- ${iso} -->`);
    }

-    // Page-change observability (#274): show the diff the agent saw at the start
-    // of this turn, before its response, so the export reflects the stale-page
-    // warning the model received.
-    const pc = pageChangedOf(row);
-    if (pc) {
-      // The page title is UNTRUSTED cross-user data (a collaborative page's title
-      // controllable by another user). escapeAttr() alone (the prompt sink) is
-      // INSUFFICIENT here: this is a MARKDOWN sink, so we neutralize link/image
-      // syntax too (backslash-escaping `[`/`]`) before interpolating it into this
-      // `> **…**` blockquote heading — otherwise `![x](url)` / `[phish](url)` would
-      // inject a remote image or clickable link into the downloaded .md. An
-      // all-`<>"` title escapes to empty and correctly falls to the bare heading.
-      // The diff body is already safe via fence(). (#288 review F1.)
-      const safeTitle = markdownHeadingSafe(pc.title);
-      const heading = safeTitle
-        ? `${L.pageEditedByUser} ("${safeTitle}")`
-        : L.pageEditedByUser;
-      blocks.push(`> **📝 ${heading}**\n\n${fence(pc.diff, 'diff')}`);
-    }
-
    blocks.push(...renderMessageParts(rowParts(row), lang));

    // A still-'streaming' row is an interrupted/in-progress turn captured by the