@carlonicora/nextjs-jsonapi 6.12.1 → 6.13.0

package/src/components/editors/__tests__/BlockNoteEditor.empty-change.spec.tsx

@@ -0,0 +1,205 @@
+import { act, render } from "@testing-library/react";
+import React from "react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * BlockNote emits one change when an empty editor mounts (it inserts its trailing empty
+ * paragraph). Reported to the parent, that no-op became a save on every page view (an autosave
+ * of an empty field), and offline a queued change. The editor reports a change unless the text
+ * went from empty to still empty. Mocks as in BlockNoteEditor.ai.spec.tsx, plus the view's
+ * onChange and the editor's replaceBlocks.
+ */
+const h = vi.hoisted(() => {
+  const AIExtension = vi.fn((options: unknown) => ({ aiFactory: true, options }));
+  return {
+    AIExtension,
+    editorsCreated: 0,
+    company: undefined as { id: string } | undefined,
+    editor: undefined as any,
+    ai: undefined as any,
+    transportConfig: undefined as any,
+    viewOnChange: undefined as undefined | (() => void),
+  };
+});
+
+vi.mock("next-intl", () => ({ useTranslations: () => (key: string) => key }));
+vi.mock("next-themes", () => ({ useTheme: () => ({ resolvedTheme: "light" }) }));
+vi.mock("../../../i18n/config", () => ({ useI18nLocale: () => "en" }));
+vi.mock("../../../client/config", () => ({ getPublicApiUrl: () => "http://api.test/" }));
+vi.mock("../../../client/token", () => ({ getClientToken: async () => "token" }));
+vi.mock("../../../contexts", () => ({
+  useCurrentUserContextOptional: () => (h.company ? { company: h.company } : undefined),
+}));
+
+vi.mock("@blocknote/react", async () => {
+  const React = await import("react");
+  const EditorContext = React.createContext<any>(null);
+  const useBlockNoteEditor = () => React.useContext(EditorContext);
+  const requireAI = (editor: any) => {
+    if (!editor?.getExtension(h.AIExtension)) throw new Error("Extension not found");
+  };
+  return {
+    EditorContext,
+    createReactInlineContentSpec: (config: unknown) => ({ config }),
+    getDefaultReactSlashMenuItems: () => [],
+    SuggestionMenuController: () => null,
+    useBlockNoteEditor,
+    useExtension: () => {
+      const editor = useBlockNoteEditor();
+      requireAI(editor);
+      return editor.getExtension(h.AIExtension);
+    },
+    useExtensionState: () => "closed",
+    useCreateBlockNote: (options: any, deps: React.DependencyList = []) =>
+      React.useMemo(() => {
+        h.editorsCreated += 1;
+        const extensions: any[] = options?.extensions ?? [];
+        // Mirrors xl-ai 0.55: a store holding aiMenuState, and the calls that
+        // move it back to "closed".
+        const store = { state: { aiMenuState: "closed" as any } };
+        const ai = {
+          store,
+          invokeAI: vi.fn(),
+          openAIMenuAtBlock: vi.fn((blockId: string) => {
+            store.state.aiMenuState = { blockId, status: "user-input" };
+          }),
+          abort: vi.fn(async () => {
+            const menu = store.state.aiMenuState;
+            if (menu !== "closed") store.state.aiMenuState = { ...menu, status: "user-reviewing" };
+          }),
+          closeAIMenu: vi.fn(() => {
+            store.state.aiMenuState = "closed";
+          }),
+          rejectChanges: vi.fn(() => {
+            store.state.aiMenuState = "closed";
+          }),
+        };
+        const hasAI = extensions.some((e) => e?.aiFactory);
+        const editor = {
+          document: [] as any[],
+          replaceBlocks: (_old: unknown, blocks: any[]) => {
+            editor.document = blocks;
+          },
+          focus: () => undefined,
+          getSelection: () => undefined,
+          getExtension: (factory: unknown) => (factory === h.AIExtension && hasAI ? ai : undefined),
+        };
+        h.editor = editor;
+        h.ai = hasAI ? ai : undefined;
+        return editor;
+      }, deps),
+    BasicTextStyleButton: () => null,
+    BlockTypeSelect: () => null,
+    CreateLinkButton: () => null,
+    FileCaptionButton: () => null,
+    FileReplaceButton: () => null,
+    TextAlignButton: () => null,
+    FormattingToolbar: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+    FormattingToolbarController: ({ formattingToolbar }: { formattingToolbar: () => React.ReactNode }) => (
+      <>{formattingToolbar()}</>
+    ),
+    // Shared with the xl-ai stubs below.
+    __requireAI: requireAI,
+  };
+});
+
+vi.mock("@blocknote/shadcn", async () => {
+  const { EditorContext } = (await import("@blocknote/react")) as any;
+  return {
+    BlockNoteView: ({
+      editor,
+      children,
+      onChange,
+    }: {
+      editor: unknown;
+      children: React.ReactNode;
+      onChange?: () => void;
+    }) => {
+      h.viewOnChange = onChange;
+      return <EditorContext.Provider value={editor}>{children}</EditorContext.Provider>;
+    },
+  };
+});
+
+vi.mock("@blocknote/xl-ai", async () => {
+  const { useBlockNoteEditor, __requireAI } = (await import("@blocknote/react")) as any;
+  return {
+    AIExtension: h.AIExtension,
+    AIMenuController: () => {
+      __requireAI(useBlockNoteEditor());
+      return <div data-testid="ai-menu" />;
+    },
+    AIToolbarButton: () => {
+      __requireAI(useBlockNoteEditor());
+      return <div data-testid="ai-toolbar-button" />;
+    },
+    getAISlashMenuItems: () => [],
+    getDefaultAIMenuItems: () => [],
+    PromptSuggestionMenu: () => null,
+    useAIDictionary: () => ({}),
+  };
+});
+
+vi.mock("ai", () => ({
+  DefaultChatTransport: function (this: any, config: unknown) {
+    h.transportConfig = config;
+  },
+}));
+vi.mock("@blocknote/core", () => ({
+  BlockNoteSchema: { create: (config: unknown) => ({ config }) },
+  defaultInlineContentSpecs: {},
+  filterSuggestionItems: (items: unknown[]) => items,
+}));
+vi.mock("@blocknote/core/locales", () => ({ en: { core: "en" } }));
+vi.mock("@blocknote/xl-ai/locales", () => ({ en: { ai: "en" } }));
+vi.mock("@blocknote/shadcn/style.css", () => ({}));
+vi.mock("@blocknote/xl-ai/style.css", () => ({}));
+vi.mock("../BlockNoteEditorMentionInlineContent", () => ({ createMentionInlineContentSpec: () => ({}) }));
+
+import BlockNoteEditor from "../BlockNoteEditor";
+
+const emptyParagraph = () => [{ id: "p0", type: "paragraph", props: {}, content: [], children: [] }];
+const textParagraph = (text: string) => [
+  { id: "p1", type: "paragraph", props: {}, content: [{ type: "text", text, styles: {} }], children: [] },
+];
+
+const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+async function emit(document: any[]): Promise<void> {
+  h.editor.document = document;
+  await act(async () => {
+    h.viewOnChange?.();
+    await flush();
+  });
+}
+
+describe("BlockNoteEditor change reports", () => {
+  const onChange = vi.fn();
+
+  beforeEach(() => {
+    onChange.mockReset();
+    h.viewOnChange = undefined;
+  });
+
+  it("does not report the change an empty editor emits when it mounts (empty to still empty)", async () => {
+    render(<BlockNoteEditor id="npc-1" type="npcs" onChange={onChange} />);
+    await emit(emptyParagraph());
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("reports typing into an empty editor, then clearing it again", async () => {
+    render(<BlockNoteEditor id="npc-1" type="npcs" onChange={onChange} />);
+    await emit(textParagraph("Hello"));
+    expect(onChange).toHaveBeenLastCalledWith(textParagraph("Hello"), false, false);
+    await emit(emptyParagraph());
+    expect(onChange).toHaveBeenLastCalledWith(emptyParagraph(), true, false);
+    expect(onChange).toHaveBeenCalledTimes(2);
+  });
+
+  it("reports clearing an editor that started with text, even as its first change", async () => {
+    render(<BlockNoteEditor id="npc-1" type="npcs" initialContent={textParagraph("Old") as any} onChange={onChange} />);
+    await emit(emptyParagraph());
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenLastCalledWith(emptyParagraph(), true, false);
+  });
+});

package/src/contexts/SocketContext.tsx

@@ -3,6 +3,8 @@
 import React, { createContext, useContext, useEffect, useState } from "react";
 import { NotificationInterface } from "../features/notification/data";
 import { useSocket } from "../hooks";
+import { isOfflineConfigured } from "../offline/config";
+import { useOfflineState } from "../offline/state-hooks";
 import type { SessionSnapshot } from "../server/ServerSession";
 
 interface SocketContextProps {
@@ -62,8 +64,12 @@ export const SocketProvider: React.FC<SocketProviderProps> = ({ token, session,
   }, [session]);
 
   const resolvedToken = token ?? sessionToken;
+  // Offline mode (opt-in): the socket stops retrying while the session is offline and connects
+  // again once it is back online. Without offline mode the state stays online: never paused.
+  const offlineState = useOfflineState();
+  const paused = isOfflineConfigured() && !offlineState.online;
   // Called unconditionally: useSocket returns early while the token is falsy.
-  const socketHookData = useSocket({ token: resolvedToken as string });
+  const socketHookData = useSocket({ token: resolvedToken as string, paused });
 
   const sendMessage = (event: string, data: any) => {
     const currentSocket = socketHookData ? socketHookData.socket : defaultContextValue.socket;

package/src/contexts/__tests__/SocketContext.session.spec.tsx

@@ -1,9 +1,9 @@
 import { act, render, screen } from "@testing-library/react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { SessionSnapshot } from "../../server/ServerSession";
 
 const { useSocketMock } = vi.hoisted(() => ({
-  useSocketMock: vi.fn((_options: { token?: string }) => ({
+  useSocketMock: vi.fn((_options: { token?: string; paused?: boolean }) => ({
     socket: null,
     isConnected: false,
     messages: [],
@@ -18,6 +18,9 @@ const { useSocketMock } = vi.hoisted(() => ({
 
 vi.mock("../../hooks/useSocket", () => ({ useSocket: useSocketMock }));
 
+import { configureOffline, resetOfflineConfig } from "../../offline/config";
+import { resetOfflineState, setOfflineState } from "../../offline/state";
+import type { OfflineConfig } from "../../offline/types";
 import { SocketProvider } from "../SocketContext";
 
 function deferred<T>() {
@@ -49,7 +52,7 @@ describe("SocketProvider with a session", () => {
       </SocketProvider>,
     );
     expect(screen.getByText("child")).toBeInTheDocument();
-    expect(useSocketMock).toHaveBeenLastCalledWith({ token: undefined });
+    expect(useSocketMock).toHaveBeenLastCalledWith({ token: undefined, paused: false });
   });
 
   it("connects with the token once the session resolves", async () => {
@@ -63,7 +66,7 @@ describe("SocketProvider with a session", () => {
       pending.resolve(snapshot("t1"));
       await pending.promise;
     });
-    expect(useSocketMock).toHaveBeenLastCalledWith({ token: "t1" });
+    expect(useSocketMock).toHaveBeenLastCalledWith({ token: "t1", paused: false });
   });
 
   it("still accepts a plain token", () => {
@@ -72,6 +75,50 @@ describe("SocketProvider with a session", () => {
         <span>child</span>
       </SocketProvider>,
     );
-    expect(useSocketMock.mock.calls[0][0]).toEqual({ token: "t2" });
+    expect(useSocketMock.mock.calls[0][0]).toEqual({ token: "t2", paused: false });
+  });
+});
+
+describe("SocketProvider and offline mode", () => {
+  const offlineConfig = {
+    getUserId: () => "u1",
+    rootModule: { name: "roots" },
+    types: [],
+    routes: [],
+    listSyncRoots: async () => [],
+    shellPath: () => "/offline-shell",
+    syncIntervalMs: 300000,
+  } as unknown as OfflineConfig;
+
+  afterEach(() => {
+    resetOfflineConfig();
+    resetOfflineState();
+  });
+
+  it("with offline mode configured, pauses the socket while the session is offline and resumes it when back online", () => {
+    configureOffline(offlineConfig);
+    setOfflineState({ online: true });
+    render(
+      <SocketProvider token="t3">
+        <span>child</span>
+      </SocketProvider>,
+    );
+    expect(useSocketMock).toHaveBeenLastCalledWith({ token: "t3", paused: false });
+
+    act(() => setOfflineState({ online: false }));
+    expect(useSocketMock).toHaveBeenLastCalledWith({ token: "t3", paused: true });
+
+    act(() => setOfflineState({ online: true }));
+    expect(useSocketMock).toHaveBeenLastCalledWith({ token: "t3", paused: false });
+  });
+
+  it("without offline mode configured, never pauses the socket", () => {
+    setOfflineState({ online: false });
+    render(
+      <SocketProvider token="t4">
+        <span>child</span>
+      </SocketProvider>,
+    );
+    expect(useSocketMock).toHaveBeenLastCalledWith({ token: "t4", paused: false });
   });
 });

package/src/core/factories/RehydrationFactory.ts

@@ -3,6 +3,30 @@ import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInt
 import { JsonApiHydratedDataInterface } from "../interfaces/JsonApiHydratedDataInterface";
 import { DataClassRegistry } from "../registry/DataClassRegistry";
 
+/**
+ * The resources being rehydrated right now, along the current chain of relationships. A resource
+ * met again inside its own chain (A's relationship leads to B, B's back to A) is a circle in the
+ * `included` data: following it would recurse until the stack overflows, so it is skipped there.
+ */
+const inProgress = new Set<string>();
+
+const keyOf = (data: JsonApiHydratedDataInterface): string | undefined => {
+  const resource = data?.jsonApi;
+  return resource?.type && resource?.id ? `${resource.type}:${resource.id}` : undefined;
+};
+
+function guarded<T>(data: JsonApiHydratedDataInterface, run: () => T): T {
+  const key = keyOf(data);
+  if (!key) return run();
+  if (inProgress.has(key)) return undefined as T;
+  inProgress.add(key);
+  try {
+    return run();
+  } finally {
+    inProgress.delete(key);
+  }
+}
+
 export class RehydrationFactory {
   public static rehydrate<T extends ApiDataInterface>(
     classKey: ApiRequestDataTypeInterface,
@@ -10,8 +34,7 @@ export class RehydrationFactory {
   ): T {
     const factoryClass = DataClassRegistry.get(classKey);
 
-    const instance = new factoryClass();
-    return instance.rehydrate(data) as T;
+    return guarded(data, () => new factoryClass().rehydrate(data) as T);
   }
 
   public static rehydrateList<T extends ApiDataInterface>(
@@ -20,11 +43,8 @@ export class RehydrationFactory {
   ): T[] {
     const factoryClass = DataClassRegistry.get(classKey);
 
-    const response = data.map((item: JsonApiHydratedDataInterface) => {
-      const instance = new factoryClass();
-      return instance.rehydrate(item) as T;
-    });
-
-    return response;
+    return data.map((item: JsonApiHydratedDataInterface) =>
+      guarded(item, () => new factoryClass().rehydrate(item) as T),
+    );
   }
 }

package/src/core/factories/__tests__/RehydrationFactory.spec.ts

@@ -149,4 +149,37 @@ describe("RehydrationFactory", () => {
       expect(results[0]).not.toBe(results[1]);
     });
   });
+
+  describe("circular included data", () => {
+    // A model that reads its "other" relationship from included, as AbstractApiData models do.
+    class Linked implements Partial<ApiDataInterface> {
+      id = "";
+      other?: Linked;
+      rehydrate(data: JsonApiHydratedDataInterface) {
+        this.id = data.jsonApi.id;
+        const ref = data.jsonApi.relationships?.other?.data;
+        const target = ref && data.included.find((item: any) => item.type === ref.type && item.id === ref.id);
+        if (target)
+          this.other = RehydrationFactory.rehydrate(linkedModule as any, { jsonApi: target, included: data.included });
+        return this;
+      }
+    }
+    const linkedModule = { name: "linked", model: Linked };
+
+    it("a relationship that leads back to a resource already being rehydrated is skipped, not followed forever", () => {
+      DataClassRegistry.registerObjectClass(linkedModule as any, Linked as any);
+      const a = { type: "linked", id: "a", relationships: { other: { data: { type: "linked", id: "b" } } } };
+      const b = { type: "linked", id: "b", relationships: { other: { data: { type: "linked", id: "a" } } } };
+
+      const result = RehydrationFactory.rehydrate<any>(linkedModule as any, { jsonApi: a, included: [a, b] });
+
+      expect(result.id).toBe("a");
+      expect(result.other.id).toBe("b");
+      expect(result.other.other).toBeUndefined();
+      // The guard is per chain: the same resource rehydrates again in a new call.
+      expect(RehydrationFactory.rehydrate<any>(linkedModule as any, { jsonApi: b, included: [a, b] }).other.id).toBe(
+        "a",
+      );
+    });
+  });
 });

package/src/core/index.ts

@@ -131,6 +131,9 @@ export * from "../features/referral/referral.module";
 export * from "../features/referral/referral-stats.module";
 export * from "../features/referral/referral-admin.modules";
 export * from "../features/referral/interfaces/referral-admin.interface";
+// Offline mode models and their module bundle (opt-in): exported from core so a
+// bootstrapper can spread offlineModules without loading the ./offline entry.
+export * from "../offline/sync/models";
 // Administrative token-usage reporting modules. Exported from core (not only
 // from the client-marked ./tokenusage barrel) so a consuming app can register
 // them in its bootstrapper without pulling the feature's client bundle —

package/src/core/interfaces/ApiData.ts

@@ -5,4 +5,6 @@ export type ApiData = {
   statusText: string;
   token?: string;
   refreshToken?: string;
+  /** Set by `directFetch` when the API could not be reached at all (the 503 it reports). */
+  networkError?: boolean;
 };

package/src/core/registry/ModuleRegistry.ts

@@ -107,6 +107,9 @@ export interface FoundationModuleDefinitions {
   AnalyticsPageView: ModuleWithPermissions;
   // Account deletion (opt-in: registered only by apps that enable it)
   AccountDeletion: ModuleWithPermissions;
+  // Offline mode (opt-in: registered by apps that spread offlineModules)
+  OfflineChangeSet: ModuleWithPermissions;
+  RootSync: ModuleWithPermissions;
 }
 
 // App-specific modules - apps will augment this interface ONLY

package/src/features/auth/components/forms/Logout.tsx

@@ -12,13 +12,20 @@ interface LogoutProps {
    * library's own `user` key is always cleared and does not need listing.
    */
   storageKeys?: string[];
+  /**
+   * Awaited before anything is cleared (offline mode: warn about changes that
+   * were not sent, then drop the device copy). Returning `false` cancels the
+   * logout: storage, cookies and the current page are left as they are.
+   */
+  beforeLogout?: () => Promise<boolean>;
 }
 
-export function Logout({ storageKeys }: LogoutProps) {
+export function Logout({ storageKeys, beforeLogout }: LogoutProps) {
   const generateUrl = usePageUrlGenerator();
 
   useEffect(() => {
     const logOut = async () => {
+      if (beforeLogout && !(await beforeLogout())) return;
       // `CurrentUserProvider` persists the user in localStorage, so clearing the
       // cookies alone leaves the client believing the session is still alive:
       // the server renders as anonymous while every `useCurrentUserContext()`

package/src/features/auth/components/forms/__tests__/Logout.spec.tsx

@@ -120,4 +120,66 @@ describe("Logout", () => {
       });
     });
   });
+
+  // Offline mode: the app may hold unsent changes on the device, so it gets a
+  // chance to warn (or cancel) before anything is cleared.
+  describe("Scenario: beforeLogout hook", () => {
+    it("awaits beforeLogout and stops when it returns false", async () => {
+      let resolveHook: (value: boolean) => void = () => {};
+      const beforeLogout = vi.fn(
+        () =>
+          new Promise<boolean>((resolve) => {
+            resolveHook = resolve;
+          }),
+      );
+
+      render(<Logout beforeLogout={beforeLogout} />);
+
+      await waitFor(() => {
+        expect(beforeLogout).toHaveBeenCalledTimes(1);
+      });
+      expect(clearClientStorage).not.toHaveBeenCalled();
+      expect(AuthService.logout).not.toHaveBeenCalled();
+
+      resolveHook(false);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+
+      expect(clearClientStorage).not.toHaveBeenCalled();
+      expect(AuthService.logout).not.toHaveBeenCalled();
+      expect(windowLocationHref).toBe("");
+    });
+
+    it("clears storage and logs out when it returns true or is absent", async () => {
+      const callOrder: string[] = [];
+      const beforeLogout = vi.fn(async () => {
+        callOrder.push("beforeLogout");
+        return true;
+      });
+      vi.mocked(clearClientStorage).mockImplementation(() => {
+        callOrder.push("clearClientStorage");
+      });
+      vi.mocked(AuthService.logout).mockImplementation(async () => {
+        callOrder.push("AuthService.logout");
+      });
+
+      const { unmount } = render(<Logout beforeLogout={beforeLogout} storageKeys={["person"]} />);
+
+      await waitFor(() => {
+        expect(windowLocationHref).toBe("/");
+      });
+      expect(callOrder).toEqual(["beforeLogout", "clearClientStorage", "AuthService.logout"]);
+      expect(clearClientStorage).toHaveBeenCalledWith([CURRENT_USER_STORAGE_KEY, "person"]);
+      unmount();
+
+      vi.clearAllMocks();
+      windowLocationHref = "";
+      render(<Logout />);
+
+      await waitFor(() => {
+        expect(windowLocationHref).toBe("/");
+      });
+      expect(clearClientStorage).toHaveBeenCalledWith([CURRENT_USER_STORAGE_KEY]);
+      expect(AuthService.logout).toHaveBeenCalledTimes(1);
+    });
+  });
 });

package/src/hooks/__tests__/useSocket.pause.spec.ts

@@ -0,0 +1,39 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+const { io, fakeSocket } = vi.hoisted(() => {
+  const fakeSocket = {
+    id: undefined,
+    connected: true,
+    on: vi.fn(),
+    off: vi.fn(),
+    emit: vi.fn(),
+    connect: vi.fn(),
+    disconnect: vi.fn(),
+    removeAllListeners: vi.fn(),
+  };
+  return { fakeSocket, io: vi.fn(() => fakeSocket) };
+});
+vi.mock("socket.io-client", () => ({ default: io }));
+
+import { useSocket } from "../useSocket";
+
+describe("useSocket pause (offline mode)", () => {
+  it("disconnects while paused and connects the same socket again when resumed", () => {
+    const { rerender } = renderHook(({ paused }) => useSocket({ token: "t1", paused }), {
+      initialProps: { paused: false },
+    });
+    expect(io).toHaveBeenCalledTimes(1);
+    expect(fakeSocket.disconnect).not.toHaveBeenCalled();
+
+    rerender({ paused: true });
+    expect(fakeSocket.disconnect).toHaveBeenCalledTimes(1);
+    rerender({ paused: true });
+    expect(fakeSocket.disconnect).toHaveBeenCalledTimes(1);
+    expect(fakeSocket.connect).not.toHaveBeenCalled();
+
+    rerender({ paused: false });
+    expect(fakeSocket.connect).toHaveBeenCalledTimes(1);
+    expect(io).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/useSocket.ts

@@ -10,6 +10,8 @@ type Socket = ReturnType<typeof io>;
 
 interface UseSocketOptions {
   token: string;
+  /** While true the socket is disconnected (no reconnect attempts); false connects it again. */
+  paused?: boolean;
 }
 
 interface SocketLike {
@@ -31,7 +33,7 @@ interface UseSocketReturn {
   clearSocketNotifications: () => void;
 }
 
-export function useSocket({ token }: UseSocketOptions): UseSocketReturn {
+export function useSocket({ token, paused = false }: UseSocketOptions): UseSocketReturn {
   const _errorCount = useRef(0);
   const shouldConnect = useRef(true);
 
@@ -168,6 +170,23 @@ export function useSocket({ token }: UseSocketOptions): UseSocketReturn {
     };
   }, [token]);
 
+  // Paused (offline mode, the session is offline): a manual disconnect stops socket.io retrying;
+  // resuming connects the same socket again.
+  const pausedSocket = useRef<Socket | null>(null);
+  useEffect(() => {
+    const current = socketRef.current;
+    if (!current) return;
+    if (paused) {
+      if (pausedSocket.current !== current) {
+        current.disconnect();
+        pausedSocket.current = current;
+      }
+    } else if (pausedSocket.current === current) {
+      pausedSocket.current = null;
+      current.connect();
+    }
+  }, [paused, socket]);
+
   const sendMessage = (event: string, data: any) => {
     if (socketRef.current && isConnected) {
       socketRef.current.emit(event, data);