fix(offline): address PR #120 review (cross-user leak, Yjs title dup, i18n, docs, guards)

Security:
- Clear the offline IndexedDB cache on sign-in (not only logout) so a previous
  user's persisted query cache and Yjs page bodies cannot leak to the next user
  on a shared device when the prior session ended without an explicit logout.

Regressions:
- Remove the double Yjs title write from the AI title-generation path: the title
  editor is bound to the Yjs `title` fragment and the server REST update reseeds
  it, so the local setContent raced that reseed and doubled/garbled the title.

Conventions / i18n / docs:
- Remove the unused showAiMenuAtom.
- Register the 3 offline-fallback strings in en-US and ru-RU.
- Fix the 5 broken links to the nonexistent docs/offline-sync-plan.md.

Stability / simplification:
- warmInfiniteAll now reports truncation (returns false) when it hits maxPages
  with a cursor still pending instead of silently succeeding.
- space-tree make-offline catch logs the raw error and surfaces the real cause.
- Move the Offline/Mobile/CORS CHANGELOG entries from the released 0.93.0 section
  into [Unreleased] (CORS is a documented breaking change).
- Drop the pass-through sync-flag forwarders in use-page-collab-providers; set the
  atoms directly.
- Collapse the three isSwaggerEnabled true-cases into it.each.

Tests / architecture:
- Extract collabTokenNeedsRefresh (pure) and cover all four token states.
- Extract shouldPropagateTitleChange and cover the collab-origin skip; add a
  TitleEditor render test for the static-h1 vs collaborative-editor switch.
- Add a use-auth test asserting the sign-in cache purge runs before login.
- Add an OFFLINE_PERSIST_ROOTS guard test asserting every persisted root maps to
  an exported query-key factory; route make-offline's currentUser warm through a
  new userKeys factory.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/client/src/features/editor/atoms/editor-atoms.ts

@@ -16,8 +16,6 @@ export const isLocalSyncedAtom = atom<boolean>(false);
 // Remote (Hocuspocus) sync state for the current page's Y.Doc.
 export const isRemoteSyncedAtom = atom<boolean>(false);
 
-export const showAiMenuAtom = atom(false);
-
 export const showLinkMenuAtom = atom(false);
 
 // Current page's edit mode — initialized from the user's saved preference on

apps/client/src/features/editor/hooks/collab-token.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// jwt-decode is mocked so we can drive the four token states deterministically
+// (decode success with a chosen exp, or a thrown decode error).
+const decodeMock = vi.hoisted(() => vi.fn());
+vi.mock("jwt-decode", () => ({
+  jwtDecode: decodeMock,
+}));
+
+import { collabTokenNeedsRefresh } from "./collab-token";
+
+const NOW_MS = 1_000_000_000; // fixed "now" in ms (so NOW_MS/1000 seconds)
+
+beforeEach(() => {
+  decodeMock.mockReset();
+});
+
+describe("collabTokenNeedsRefresh", () => {
+  it("returns true when there is no token (fetch a fresh one)", () => {
+    expect(collabTokenNeedsRefresh(undefined, NOW_MS)).toBe(true);
+    // jwtDecode must not even be called for a missing token.
+    expect(decodeMock).not.toHaveBeenCalled();
+  });
+
+  it("returns true when the token is malformed (jwtDecode throws)", () => {
+    decodeMock.mockImplementation(() => {
+      throw new Error("invalid token");
+    });
+    expect(collabTokenNeedsRefresh("garbage", NOW_MS)).toBe(true);
+  });
+
+  it("returns false for a valid, not-yet-expired token (no reconnect)", () => {
+    // exp is in the future relative to NOW.
+    decodeMock.mockReturnValue({ exp: NOW_MS / 1000 + 60 });
+    expect(collabTokenNeedsRefresh("good", NOW_MS)).toBe(false);
+  });
+
+  it("returns true for a valid but expired token (refresh + reconnect)", () => {
+    // exp is in the past relative to NOW.
+    decodeMock.mockReturnValue({ exp: NOW_MS / 1000 - 60 });
+    expect(collabTokenNeedsRefresh("expired", NOW_MS)).toBe(true);
+  });
+
+  it("treats exp exactly equal to now as expired (>= boundary)", () => {
+    decodeMock.mockReturnValue({ exp: NOW_MS / 1000 });
+    expect(collabTokenNeedsRefresh("boundary", NOW_MS)).toBe(true);
+  });
+});

apps/client/src/features/editor/hooks/collab-token.ts

@@ -0,0 +1,26 @@
+import { jwtDecode } from "jwt-decode";
+
+/**
+ * Decide whether a collab token must be refreshed before reconnecting after an
+ * onAuthenticationFailed event. Pure and side-effect free so the four token
+ * states can be unit-tested directly:
+ *   - no token              -> true  (fetch a fresh one and reconnect)
+ *   - undecodable/malformed -> true  (jwtDecode throws -> refresh)
+ *   - valid, not expired    -> false (token is still good; do NOT reconnect)
+ *   - valid, expired        -> true  (refresh + reconnect)
+ *
+ * `nowMs` is injectable for deterministic tests; it defaults to `Date.now()`.
+ */
+export function collabTokenNeedsRefresh(
+  token: string | undefined,
+  nowMs: number = Date.now(),
+): boolean {
+  if (!token) return true;
+  try {
+    const payload = jwtDecode<{ exp: number }>(token);
+    return nowMs / 1000 >= payload.exp;
+  } catch {
+    // malformed/undecodable token -> refresh
+    return true;
+  }
+}

apps/client/src/features/editor/hooks/use-generate-page-title.test.tsx

@@ -139,7 +139,7 @@ describe("useGeneratePageTitle", () => {
     );
   });
 
-  it("happy path: applies the title, refreshes cache, writes the field, broadcasts", async () => {
+  it("happy path: applies the title, refreshes cache, broadcasts, and does NOT write the editor", async () => {
     const store = createStore();
     const titleEditor = makeTitleEditor();
     store.set(pageEditorAtom as never, makePageEditor("pageA"));
@@ -157,9 +157,11 @@ describe("useGeneratePageTitle", () => {
       title: "Generated Title",
     });
     expect(updatePageDataMock).toHaveBeenCalledWith(PAGE_A);
-    expect(titleEditor.commands.setContent).toHaveBeenCalledWith(
-      "Generated Title",
-    );
+    // The title editor is bound to the Yjs `title` fragment; the server REST
+    // update reseeds that fragment and the reseed reaches the bound editor on
+    // its own. Writing here too would double/garble the title, so the hook must
+    // NOT touch the editor (regression guard for the Yjs duplication trap).
+    expect(titleEditor.commands.setContent).not.toHaveBeenCalled();
     expect(localEmitMock).toHaveBeenCalled();
     expect(emitMock).toHaveBeenCalled();
     expect(notificationsShowMock).toHaveBeenCalledWith(
@@ -167,7 +169,7 @@ describe("useGeneratePageTitle", () => {
     );
   });
 
-  it("does NOT write the visible title field when the user navigated away during generation", async () => {
+  it("keeps the DB write keyed by the captured pageId and still broadcasts after navigation", async () => {
     const store = createStore();
     const titleEditor = makeTitleEditor(); // persistent across navigation
     store.set(pageEditorAtom as never, makePageEditor("pageA"));
@@ -203,55 +205,9 @@ describe("useGeneratePageTitle", () => {
       pageId: "pageA",
       title: "Generated Title",
     });
-    // ...but we must NOT stamp page A's title into page B's visible field.
+    // ...the hook never writes the editor regardless of navigation...
     expect(titleEditor.commands.setContent).not.toHaveBeenCalled();
-    // The change is still broadcast to other clients.
-    expect(emitMock).toHaveBeenCalled();
-  });
-
-  it("does NOT write the visible title field when the title editor is focused", async () => {
-    const store = createStore();
-    const titleEditor = makeTitleEditor();
-    store.set(pageEditorAtom as never, makePageEditor("pageA"));
-    store.set(titleEditorAtom as never, titleEditor);
-
-    // Resolve generation under our control so we can mark the live title editor
-    // as focused before the post-generation write runs.
-    let resolveTitle!: (t: string) => void;
-    generatePageTitleMock.mockReturnValue(
-      new Promise<string>((res) => {
-        resolveTitle = res;
-      }),
-    );
-    updateTitleMock.mockResolvedValue(PAGE_A);
-    const { result } = setup("pageA", store);
-
-    let pending!: Promise<void>;
-    act(() => {
-      pending = result.current.mutateAsync();
-    });
-
-    // The user clicked into the title field while the model ran — overwriting it
-    // now would clobber what they are actively typing.
-    act(() => {
-      (titleEditor as { isFocused: boolean }).isFocused = true;
-    });
-
-    await act(async () => {
-      resolveTitle("Generated Title");
-      await pending;
-    });
-
-    // The DB write still persists the value...
-    expect(updateTitleMock).toHaveBeenCalledWith({
-      pageId: "pageA",
-      title: "Generated Title",
-    });
-    expect(updatePageDataMock).toHaveBeenCalledWith(PAGE_A);
-    // ...but the visible field is left alone while it is focused.
-    expect(titleEditor.commands.setContent).not.toHaveBeenCalled();
-    // The change is still broadcast to other clients.
-    expect(localEmitMock).toHaveBeenCalled();
+    // ...and the change is still broadcast to other clients.
     expect(emitMock).toHaveBeenCalled();
   });
 

apps/client/src/features/editor/hooks/use-generate-page-title.ts

@@ -1,13 +1,9 @@
-import { useRef } from "react";
 import { useMutation } from "@tanstack/react-query";
 import { useAtomValue } from "jotai";
 import { notifications } from "@mantine/notifications";
 import { useTranslation } from "react-i18next";
 import { htmlToMarkdown } from "@docmost/editor-ext";
-import {
-  pageEditorAtom,
-  titleEditorAtom,
-} from "@/features/editor/atoms/editor-atoms.ts";
+import { pageEditorAtom } from "@/features/editor/atoms/editor-atoms.ts";
 import {
   updatePageData,
   useUpdateTitlePageMutation,
@@ -33,18 +29,9 @@ const MAX_CONTENT_CHARS = 20000;
 export function useGeneratePageTitle(pageId: string) {
   const { t } = useTranslation();
   const pageEditor = useAtomValue(pageEditorAtom);
-  const titleEditor = useAtomValue(titleEditorAtom);
   const { mutateAsync: updateTitle } = useUpdateTitlePageMutation();
   const emit = useQueryEmit();
 
-  // The page/title editors come from GLOBAL atoms that re-point when the user
-  // navigates to another page. The mutation below awaits the model for 1-3s, and
-  // its closure captures the editors from the render that started it. Keep a live
-  // reference so the post-generation write targets whatever page is on screen
-  // *now*, not the page the generation was started from.
-  const editorsRef = useRef({ pageEditor, titleEditor });
-  editorsRef.current = { pageEditor, titleEditor };
-
   return useMutation<void, Error, void>({
     mutationFn: async () => {
       if (!pageEditor || pageEditor.isDestroyed) return;
@@ -70,33 +57,15 @@ export function useGeneratePageTitle(pageId: string) {
       const page = await updateTitle({ pageId, title }); // POST /pages/update
       updatePageData(page); // refresh the react-query cache
 
-      // Reflect the new title in the field immediately. The button lives in the
-      // byline, so the title editor is not focused — setContent is safe and stays
-      // undoable through its History extension (Ctrl/Cmd+Z reverts the change).
-      //
-      // Guard against navigation during generation: if the user switched pages
-      // while the model ran, the (persistent) title editor now shows ANOTHER
-      // page, so writing here would drop page A's title into page B's visible
-      // field. page-editor.tsx stamps the live page editor with its pageId
-      // (`editor.storage.pageId`), mirroring TitleEditor's `activePageId !==
-      // pageId` guard — bail the visible write unless that live editor still
-      // belongs to the page this title was generated for. The DB write above is
-      // already correct (keyed by the captured `pageId`), and the broadcast below
-      // still propagates page A's change to other clients.
-      const livePageEditor = editorsRef.current.pageEditor;
-      const liveTitleEditor = editorsRef.current.titleEditor;
-      // `storage.pageId` is stamped untyped in page-editor.tsx's onCreate.
-      const livePageId = (livePageEditor?.storage as { pageId?: string })
-        ?.pageId;
-      const stillOnPage = livePageId === pageId;
-      if (
-        stillOnPage &&
-        liveTitleEditor &&
-        !liveTitleEditor.isDestroyed &&
-        !liveTitleEditor.isFocused
-      ) {
-        liveTitleEditor.commands.setContent(page.title);
-      }
+      // Do NOT write the title into the editor here. The title editor is bound to
+      // the Yjs `title` fragment and Yjs is the source of truth. The server REST
+      // /pages/update reseeds that fragment (writePageTitle → writeTitleFragment,
+      // a full clear+replace) and the reseed reaches the bound title editor on
+      // its own as a remote provider update. The old REST-era setContent here
+      // would race that reseed and double/garble the title (the "Yjs duplication
+      // trap"), so it is intentionally omitted. The DB write above is keyed by
+      // the captured `pageId`, so it stays correct even if the user navigated
+      // away during generation.
 
       // Broadcast to other clients, mirroring TitleEditor.saveTitle's event shape.
       const event: UpdateEvent = {

apps/client/src/features/editor/hooks/use-page-collab-providers.ts

@@ -24,7 +24,7 @@ import { IPage } from "@/features/page/types/page.types.ts";
 import { useParams } from "react-router-dom";
 import { extractPageSlugId } from "@/lib";
 import { FIVE_MINUTES } from "@/lib/constants.ts";
-import { jwtDecode } from "jwt-decode";
+import { collabTokenNeedsRefresh } from "@/features/editor/hooks/collab-token";
 
 export interface PageCollabProviders {
   ydoc: Y.Doc | null;
@@ -70,16 +70,6 @@ export function usePageCollabProviders(pageId: string): PageCollabProviders {
   } | null>(null);
   const [providersReady, setProvidersReady] = useState(false);
 
-  // Mirror the local/remote sync flags into shared atoms so the header
-  // indicator can read them. These atoms are the single source of truth; the
-  // wrappers keep the existing call sites valid while driving only the atoms.
-  const setLocalSynced = (value: boolean) => {
-    setIsLocalSyncedAtom(value);
-  };
-  const setRemoteSynced = (value: boolean) => {
-    setIsRemoteSyncedAtom(value);
-  };
-
   useEffect(() => {
     if (!providersRef.current) {
       const documentName = `page.${pageId}`;
@@ -89,13 +79,13 @@ export function usePageCollabProviders(pageId: string): PageCollabProviders {
         url: collaborationURL,
       });
       const onLocalSyncedHandler = () => {
-        setLocalSynced(true);
+        setIsLocalSyncedAtom(true);
       };
       const onStatusHandler = (event: onStatusParameters) => {
         setYjsConnectionStatus(event.status);
       };
       const onSyncedHandler = (event: onSyncedParameters) => {
-        setRemoteSynced(event.state);
+        setIsRemoteSyncedAtom(event.state);
       };
       const onStatelessHandler = ({ payload }: onStatelessParameters) => {
         try {
@@ -121,17 +111,7 @@ export function usePageCollabProviders(pageId: string): PageCollabProviders {
         // a refetch. A missing/malformed token must NOT crash the handler —
         // jwtDecode(undefined) throws — so treat any decode failure as "needs
         // refresh" and proceed to refetch + reconnect instead of getting stuck.
-        const token = collabTokenRef.current;
-        let needsRefresh = true; // no/unparseable token -> fetch a fresh one and reconnect
-        if (token) {
-          try {
-            const payload = jwtDecode<{ exp: number }>(token);
-            needsRefresh = Date.now() / 1000 >= payload.exp;
-          } catch {
-            needsRefresh = true; // malformed token -> refresh
-          }
-        }
-        if (!needsRefresh) return;
+        if (!collabTokenNeedsRefresh(collabTokenRef.current)) return;
         refetchCollabToken().then((result) => {
           if (result.data?.token) {
             socket.disconnect();
@@ -166,8 +146,8 @@ export function usePageCollabProviders(pageId: string): PageCollabProviders {
       providersRef.current?.local.destroy();
       providersRef.current = null;
       // Reset shared sync state on page change/unmount.
-      setLocalSynced(false);
-      setRemoteSynced(false);
+      setIsLocalSyncedAtom(false);
+      setIsRemoteSyncedAtom(false);
     };
   }, [pageId]);
 

apps/client/src/features/editor/title-collab.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// isChangeOrigin is mocked so we can simulate local vs remote/collab-origin
+// transactions without constructing a real ProseMirror/Yjs transaction.
+const isChangeOriginMock = vi.hoisted(() => vi.fn());
+vi.mock("@tiptap/extension-collaboration", () => ({
+  isChangeOrigin: isChangeOriginMock,
+}));
+
+import { shouldPropagateTitleChange } from "./title-collab";
+
+beforeEach(() => {
+  isChangeOriginMock.mockReset();
+});
+
+describe("shouldPropagateTitleChange", () => {
+  it("propagates a genuine local edit (isChangeOrigin false)", () => {
+    isChangeOriginMock.mockReturnValue(false);
+    expect(shouldPropagateTitleChange({ local: true })).toBe(true);
+    expect(isChangeOriginMock).toHaveBeenCalledWith({ local: true });
+  });
+
+  it("skips a remote/collab-origin update (isChangeOrigin true)", () => {
+    isChangeOriginMock.mockReturnValue(true);
+    expect(shouldPropagateTitleChange({ remote: true })).toBe(false);
+  });
+
+  it("propagates when there is no transaction (treated as local)", () => {
+    expect(shouldPropagateTitleChange(undefined)).toBe(true);
+    // isChangeOrigin must not be called for a missing transaction.
+    expect(isChangeOriginMock).not.toHaveBeenCalled();
+  });
+});

apps/client/src/features/editor/title-collab.ts

@@ -0,0 +1,19 @@
+import { isChangeOrigin } from "@tiptap/extension-collaboration";
+
+/**
+ * Whether a TitleEditor `onUpdate` should drive URL + tree propagation.
+ *
+ * Only genuine LOCAL edits propagate. Remote/collab-origin Yjs updates
+ * (detected via `isChangeOrigin`) are skipped so a remote title change is not
+ * re-broadcast back, which would create a feedback loop. A missing transaction
+ * is treated as a local edit (propagate).
+ *
+ * Extracted as a pure helper so the skip decision is unit-testable without
+ * mounting the full collaborative editor.
+ */
+export function shouldPropagateTitleChange(transaction: unknown): boolean {
+  return !(
+    transaction &&
+    isChangeOrigin(transaction as Parameters<typeof isChangeOrigin>[0])
+  );
+}

apps/client/src/features/editor/title-editor.test.tsx

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+
+// Drive the fallback-vs-collaborative switch (titleReady = providersReady &&
+// !!ydoc) by controlling what the editor-providers context returns.
+const editorProvidersValue: { ydoc: unknown; providersReady: boolean } = {
+  ydoc: null,
+  providersReady: false,
+};
+vi.mock("@/features/editor/contexts/editor-providers-context", () => ({
+  useEditorProviders: () => editorProvidersValue,
+}));
+
+// Mock the tiptap React bindings so the test does not mount a real editor:
+// useEditor returns a minimal stub and EditorContent renders a marker.
+vi.mock("@tiptap/react", () => ({
+  useEditor: () => ({
+    isInitialized: true,
+    commands: { focus: vi.fn() },
+    setEditable: vi.fn(),
+    getText: () => "",
+  }),
+  EditorContent: () => <div data-testid="collab-editor" />,
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (k: string) => k }),
+}));
+
+const navigateMock = vi.fn();
+vi.mock("react-router-dom", () => ({
+  useNavigate: () => navigateMock,
+}));
+
+vi.mock("@/features/websocket/use-query-emit.ts", () => ({
+  useQueryEmit: () => vi.fn(),
+}));
+
+// page-query transitively imports @/main.tsx; mock it to a pure stub.
+vi.mock("@/features/page/queries/page-query", () => ({
+  updatePageData: vi.fn(),
+}));
+vi.mock("@/main.tsx", () => ({
+  queryClient: { getQueryData: vi.fn(), setQueryData: vi.fn() },
+}));
+
+import { TitleEditor } from "./title-editor";
+
+const baseProps = {
+  pageId: "p1",
+  slugId: "slug-1",
+  title: "My Page Title",
+  spaceSlug: "space",
+  editable: true,
+};
+
+beforeEach(() => {
+  navigateMock.mockReset();
+  editorProvidersValue.ydoc = null;
+  editorProvidersValue.providersReady = false;
+});
+
+describe("TitleEditor fallback vs collaborative switch", () => {
+  it("renders a static <h1> with the title before the shared doc is ready", () => {
+    editorProvidersValue.ydoc = null;
+    editorProvidersValue.providersReady = false;
+
+    render(<TitleEditor {...baseProps} />);
+
+    const heading = screen.getByRole("heading", { level: 1 });
+    expect(heading.textContent).toBe("My Page Title");
+    // The collaborative editor must NOT mount until the doc is ready.
+    expect(screen.queryByTestId("collab-editor")).toBeNull();
+  });
+
+  it("renders the collaborative editor once the shared doc is ready", () => {
+    editorProvidersValue.ydoc = {}; // truthy shared doc
+    editorProvidersValue.providersReady = true;
+
+    render(<TitleEditor {...baseProps} />);
+
+    expect(screen.getByTestId("collab-editor")).toBeDefined();
+    // The static fallback <h1> is gone — Yjs is the single source of truth and
+    // the prop is never seeded into the collaborative editor.
+    expect(screen.queryByRole("heading", { level: 1 })).toBeNull();
+  });
+});

apps/client/src/features/editor/title-editor.tsx

@@ -15,10 +15,8 @@ import { updatePageData } from "@/features/page/queries/page-query";
 import { useDebouncedCallback, getHotkeyHandler } from "@mantine/hooks";
 import { useAtom } from "jotai";
 import { useQueryEmit } from "@/features/websocket/use-query-emit.ts";
-import {
-  Collaboration,
-  isChangeOrigin,
-} from "@tiptap/extension-collaboration";
+import { Collaboration } from "@tiptap/extension-collaboration";
+import { shouldPropagateTitleChange } from "@/features/editor/title-collab";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
 import { useNavigate } from "react-router-dom";
 import { useTranslation } from "react-i18next";
@@ -99,7 +97,7 @@ export function TitleEditor({
       onUpdate({ editor, transaction }) {
         // Drive URL + tree propagation only on genuine local edits; skip
         // remote/collab-origin Yjs updates to avoid feedback loops.
-        if (transaction && isChangeOrigin(transaction)) return;
+        if (!shouldPropagateTitleChange(transaction)) return;
         debouncedPropagateTitle(editor.getText());
       },
       editable: editable,