@carlonicora/nextjs-jsonapi 6.12.2 → 6.13.0

package/pwa/sw.js

@@ -6,12 +6,147 @@
 //
 // Per-app values (appId, offlineRevision, notificationIcon) come from the app's
 // own public/sw-config.js, which sets self.NJA_SW_CONFIG.
+//
+// Offline mode (opt-in; without these keys the worker behaves exactly as before):
+// - offlineShell: { default: "/offline-shell", locales: { it: "/it/offline-shell" } }
+//   At install the worker reads /offline-manifest.json ({ buildId, assets }) and
+//   caches every asset plus each shell URL in `${appId}-shell-${buildId}`, then
+//   a completion marker last; one failed file fails the install and deletes the
+//   half-filled cache, so the previous worker stays in charge and no worker ever
+//   answers from a cache without the marker. A
+//   failed navigation answers the shell of its locale (the first path segment
+//   matched against `locales`, otherwise `default`), then offline.html. GETs
+//   under /_next/static/ are served cache-first from the shell cache; after an
+//   online navigation the worker re-reads the manifest (at most every few
+//   minutes) and precaches a new build's shell in the background, so a deploy
+//   refreshes the shell without a new worker; any other
+//   same-origin GET goes to the network first and, when it fails, is answered
+//   from the shell cache (the device worker and SQLite files). Activate deletes
+//   shell caches of other builds.
+// - offlineImageHosts: ["api.example.com"] (a host or an origin)
+//   A GET to one of these hosts goes to the network; when the network fails it
+//   is answered from `${appId}-images`, where the app stores each artwork image
+//   under its exact URL. That cache is kept across activations.
 
 importScripts("/sw-config.js");
 
 const OFFLINE_URL = "/offline.html";
 const CACHE_NAME = `${self.NJA_SW_CONFIG.appId}-offline-${self.NJA_SW_CONFIG.offlineRevision}`;
 
+const OFFLINE_SHELL = self.NJA_SW_CONFIG.offlineShell || null;
+const OFFLINE_IMAGE_HOSTS = self.NJA_SW_CONFIG.offlineImageHosts || [];
+const MANIFEST_URL = "/offline-manifest.json";
+const SHELL_CACHE_PREFIX = `${self.NJA_SW_CONFIG.appId}-shell-`;
+const IMAGES_CACHE_NAME = `${self.NJA_SW_CONFIG.appId}-images`;
+// Written last into a shell cache: a shell cache without it is incomplete and never used.
+const SHELL_COMPLETE_URL = "/__nja-offline-shell-complete__";
+
+// The shell cache this worker installed. A worker can be stopped and restarted
+// between events, losing this value; it then falls back to the newest complete
+// shell cache (caches.keys() lists caches in creation order).
+let shellCacheName = null;
+
+async function currentShellCacheName() {
+  if (shellCacheName) return shellCacheName;
+  const keys = await caches.keys();
+  const shells = keys.filter(function (key) {
+    return key.startsWith(SHELL_CACHE_PREFIX);
+  });
+  for (let index = shells.length - 1; index >= 0; index--) {
+    const cache = await caches.open(shells[index]);
+    if (await cache.match(SHELL_COMPLETE_URL)) return shells[index];
+  }
+  return null;
+}
+
+function shellUrls() {
+  const urls = [OFFLINE_SHELL.default];
+  const locales = OFFLINE_SHELL.locales || {};
+  for (const locale of Object.keys(locales)) urls.push(locales[locale]);
+  return urls;
+}
+
+function shellUrlFor(url) {
+  const segment = new URL(url).pathname.split("/")[1] || "";
+  const locales = OFFLINE_SHELL.locales || {};
+  return Object.prototype.hasOwnProperty.call(locales, segment) ? locales[segment] : OFFLINE_SHELL.default;
+}
+
+async function installShell() {
+  const response = await fetch(new Request(MANIFEST_URL, { cache: "no-store" }));
+  if (!response.ok) throw new Error(`${MANIFEST_URL} answered ${response.status}`);
+  const manifest = await response.json();
+  const name = `${SHELL_CACHE_PREFIX}${manifest.buildId}`;
+  try {
+    const cache = await caches.open(name);
+    // cache.addAll rejects when any file fails, so the install fails with it.
+    await cache.addAll(
+      manifest.assets.concat(shellUrls()).map(function (url) {
+        return new Request(url, { cache: "reload" });
+      }),
+    );
+    await cache.put(SHELL_COMPLETE_URL, new Response("", { status: 200 }));
+  } catch (error) {
+    // Never leave a half-filled shell cache behind for any worker to pick.
+    await caches.delete(name);
+    throw error;
+  }
+  shellCacheName = name;
+}
+
+// A deploy changes the app's build, not this file: sw.js is byte-identical across builds, so no
+// new worker is installed. After an online navigation the worker reads the manifest and, when
+// the server runs a build it has no complete shell cache for, precaches that build's shell in
+// the background, then drops the other shell caches. At most one check per few minutes.
+const SHELL_REFRESH_INTERVAL_MS = 5 * 60 * 1000;
+let lastShellRefresh = 0;
+let shellRefresh = null;
+
+async function refreshShellIfStale() {
+  const response = await fetch(new Request(MANIFEST_URL, { cache: "no-store" }));
+  if (!response.ok) return;
+  const manifest = await response.json();
+  const name = `${SHELL_CACHE_PREFIX}${manifest.buildId}`;
+  const keys = await caches.keys();
+  if (keys.indexOf(name) !== -1) {
+    const existing = await caches.open(name);
+    if (await existing.match(SHELL_COMPLETE_URL)) {
+      shellCacheName = name;
+      return;
+    }
+  }
+  await installShell();
+  const others = (await caches.keys()).filter(function (key) {
+    return key.startsWith(SHELL_CACHE_PREFIX) && key !== shellCacheName;
+  });
+  await Promise.all(
+    others.map(function (key) {
+      return caches.delete(key);
+    }),
+  );
+}
+
+function maybeRefreshShell() {
+  const now = Date.now();
+  if (shellRefresh || now - lastShellRefresh < SHELL_REFRESH_INTERVAL_MS) return shellRefresh || Promise.resolve();
+  lastShellRefresh = now;
+  shellRefresh = refreshShellIfStale()
+    .catch(function (error) {
+      // The current shell stays in charge; the next navigation tries again later.
+      console.warn("[sw] refreshing the offline shell failed", error);
+    })
+    .finally(function () {
+      shellRefresh = null;
+    });
+  return shellRefresh;
+}
+
+function isImageHost(url) {
+  if (!OFFLINE_IMAGE_HOSTS.length) return false;
+  const parsed = new URL(url);
+  return OFFLINE_IMAGE_HOSTS.indexOf(parsed.host) !== -1 || OFFLINE_IMAGE_HOSTS.indexOf(parsed.origin) !== -1;
+}
+
 // Served when a navigation fails and the cached offline page is missing too
 // (evicted or cleared). Never answer a navigation with a bare network error.
 const OFFLINE_FALLBACK_HTML = `<!doctype html>
@@ -58,11 +193,16 @@ const OFFLINE_FALLBACK_HTML = `<!doctype html>
 
 self.addEventListener("install", function (event) {
   event.waitUntil(
-    caches.open(CACHE_NAME).then(function (cache) {
-      // cache.add rejects on a network error or a non-2xx response, so the
-      // install fails and the previous worker stays in charge.
-      return cache.add(new Request(OFFLINE_URL, { cache: "reload" }));
-    }),
+    caches
+      .open(CACHE_NAME)
+      .then(function (cache) {
+        // cache.add rejects on a network error or a non-2xx response, so the
+        // install fails and the previous worker stays in charge.
+        return cache.add(new Request(OFFLINE_URL, { cache: "reload" }));
+      })
+      .then(function () {
+        if (OFFLINE_SHELL) return installShell();
+      }),
   );
 });
 
@@ -70,10 +210,16 @@ self.addEventListener("activate", function (event) {
   event.waitUntil(
     (async function () {
       const keys = await caches.keys();
+      const keep = [CACHE_NAME];
+      if (OFFLINE_SHELL) {
+        const shell = await currentShellCacheName();
+        if (shell) keep.push(shell);
+      }
+      if (OFFLINE_SHELL || OFFLINE_IMAGE_HOSTS.length) keep.push(IMAGES_CACHE_NAME);
       await Promise.all(
         keys
           .filter(function (key) {
-            return key !== CACHE_NAME;
+            return keep.indexOf(key) === -1;
           })
           .map(function (key) {
             return caches.delete(key);
@@ -88,28 +234,133 @@ self.addEventListener("activate", function (event) {
 });
 
 self.addEventListener("fetch", function (event) {
-  // Only navigations are intercepted. Everything else goes straight to the
-  // network without respondWith.
-  if (event.request.mode !== "navigate") return;
+  // Only navigations are intercepted, plus (offline mode only) build assets and
+  // artwork images. Everything else goes straight to the network without
+  // respondWith.
+  if (event.request.mode !== "navigate") {
+    if (!OFFLINE_SHELL && !OFFLINE_IMAGE_HOSTS.length) return;
+    const method = event.request.method || "GET";
+    if (method !== "GET") return;
+    // A no-store request (the page's session refresh of the shell) is never answered from a
+    // cache: when the network fails it must fail, so the page knows the app is unreachable.
+    if (event.request.cache === "no-store") return;
+    const url = new URL(event.request.url);
 
-  event.respondWith(
-    (async function () {
-      try {
-        const preload = await event.preloadResponse;
-        if (preload) return preload;
-        // A 4xx/5xx or an opaque redirect is passed through as is.
-        return await fetch(event.request);
-      } catch (error) {
-        const cache = await caches.open(CACHE_NAME);
-        const cached = await cache.match(OFFLINE_URL);
-        if (cached) return cached;
-        return new Response(OFFLINE_FALLBACK_HTML, {
-          status: 200,
-          headers: { "content-type": "text/html; charset=utf-8" },
-        });
+    if (OFFLINE_SHELL && url.origin === self.location.origin && url.pathname.startsWith("/_next/static/")) {
+      event.respondWith(
+        (async function () {
+          const name = await currentShellCacheName();
+          if (name) {
+            const cache = await caches.open(name);
+            const cached = await cache.match(event.request.url);
+            if (cached) return cached;
+          }
+          try {
+            return await fetch(event.request);
+          } catch {
+            // Offline and not in the shell: a plain network error for the page, no uncaught rejection here.
+            return Response.error();
+          }
+        })(),
+      );
+      return;
+    }
+
+    // An image of an offline image host through Next's image optimizer (`/_next/image?url=...`):
+    // network first, then the downloaded original (the images cache keeps it under its own URL).
+    const optimizedSource = url.origin === self.location.origin && url.pathname === "/_next/image" ? url.searchParams.get("url") : null;
+    if (optimizedSource && /^https?:/.test(optimizedSource) && isImageHost(optimizedSource)) {
+      event.respondWith(
+        (async function () {
+          try {
+            return await fetch(event.request);
+          } catch {
+            const cache = await caches.open(IMAGES_CACHE_NAME);
+            const cached = await cache.match(optimizedSource);
+            if (cached) return cached;
+            return Response.error();
+          }
+        })(),
+      );
+      return;
+    }
+
+    // Any other same-origin file the offline manifest precached (the device worker and the
+    // SQLite files it loads): network first, the shell cache when the network fails.
+    if (OFFLINE_SHELL && url.origin === self.location.origin) {
+      event.respondWith(
+        (async function () {
+          try {
+            return await fetch(event.request);
+          } catch {
+            const name = await currentShellCacheName();
+            if (name) {
+              const cache = await caches.open(name);
+              const cached = await cache.match(event.request.url);
+              if (cached) return cached;
+            }
+            return Response.error();
+          }
+        })(),
+      );
+      return;
+    }
+
+    if (isImageHost(event.request.url)) {
+      event.respondWith(
+        (async function () {
+          try {
+            return await fetch(event.request);
+          } catch {
+            const cache = await caches.open(IMAGES_CACHE_NAME);
+            const cached = await cache.match(event.request.url);
+            if (cached) return cached;
+            return Response.error();
+          }
+        })(),
+      );
+    }
+    return;
+  }
+
+  let reachedNetwork = false;
+  const answer = (async function () {
+    try {
+      const preload = await event.preloadResponse;
+      if (preload) {
+        reachedNetwork = true;
+        return preload;
       }
-    })(),
-  );
+      // A 4xx/5xx or an opaque redirect is passed through as is.
+      const response = await fetch(event.request);
+      reachedNetwork = true;
+      return response;
+    } catch (error) {
+      if (OFFLINE_SHELL) {
+        const name = await currentShellCacheName();
+        if (name) {
+          const shellCache = await caches.open(name);
+          const shell = await shellCache.match(shellUrlFor(event.request.url));
+          if (shell) return shell;
+        }
+      }
+      const cache = await caches.open(CACHE_NAME);
+      const cached = await cache.match(OFFLINE_URL);
+      if (cached) return cached;
+      return new Response(OFFLINE_FALLBACK_HTML, {
+        status: 200,
+        headers: { "content-type": "text/html; charset=utf-8" },
+      });
+    }
+  })();
+  event.respondWith(answer);
+  if (OFFLINE_SHELL) {
+    event.waitUntil(
+      answer.then(function () {
+        if (reachedNetwork) return maybeRefreshShell();
+      }),
+    );
+  }
 });
 
 self.addEventListener("message", function (event) {

package/src/client/request.ts

@@ -1,6 +1,9 @@
 "use client";
 
 import { ApiData } from "../core/interfaces/ApiData";
+import { isOfflineConfigured } from "../offline/config";
+import { getOfflineState, reachesNetworkWhileOffline, setOfflineState } from "../offline/state";
+import { OFFLINE_REPLAY_HEADER } from "../offline/types";
 
 export interface DirectFetchParams {
   method: string;
@@ -18,6 +21,39 @@ export interface DirectFetchParams {
  * Use this for client-side API calls.
  */
 export async function directFetch(params: DirectFetchParams): Promise<ApiData> {
+  // Offline mode is opt-in (`configureOffline`). Without it nothing below loads or runs. A request
+  // the server runs as an offline replay always goes to the network, and so do the reads and the
+  // change-set request of a reconnect attempt (the session stays offline until its sync succeeds).
+  const offline = isOfflineConfigured() && !hasReplayHeader(params.additionalHeaders);
+  if (offline && !getOfflineState().online && !reachesNetworkWhileOffline(params.method, params.url)) {
+    return answerLocally(params);
+  }
+
+  const response = await fetchFromApi(params);
+
+  if (offline && response.networkError) {
+    setOfflineState({ online: false });
+    return answerLocally(params);
+  }
+  if (offline && response.ok && params.method.toUpperCase() !== "GET") {
+    const { writeThrough } = await import("../offline/write-through");
+    await writeThrough({ method: params.method, url: params.url }, response);
+  }
+
+  return response;
+}
+
+function hasReplayHeader(headers?: Record<string, string>): boolean {
+  if (!headers) return false;
+  return Object.keys(headers).some((key) => key.toLowerCase() === OFFLINE_REPLAY_HEADER);
+}
+
+async function answerLocally(params: DirectFetchParams): Promise<ApiData> {
+  const { localTransport } = await import("../offline/local-transport");
+  return localTransport({ method: params.method, url: params.url, body: params.body, files: params.files });
+}
+
+async function fetchFromApi(params: DirectFetchParams): Promise<ApiData> {
   const response: ApiData = {
     data: undefined,
     ok: false,
@@ -95,6 +131,7 @@ export async function directFetch(params: DirectFetchParams): Promise<ApiData> {
     response.status = 503;
     response.statusText = "Service Unavailable";
     response.data = undefined;
+    response.networkError = true;
   }
 
   return response;

package/src/components/editors/BlockNoteEditor.tsx

@@ -821,11 +821,21 @@ export default function BlockNoteEditor({
   // initialContent is just an echo of our own emission (form-controlled flow).
   const lastEmittedHashRef = useRef<string | null>(null);
 
+  // Whether the parent's copy of the text is empty: the content it handed in, then each change
+  // reported to it. A change from empty to still empty is not reported: BlockNote emits one when an
+  // empty editor mounts (its trailing empty paragraph), and reported it became a save of nothing on
+  // every view of a page with an empty field.
+  const processedContentRef = useRef<any[]>([]);
+  const parentKnowsEmptyRef = useRef<boolean | null>(null);
+
   const handleChange = useCallback(async () => {
     if (!onChange) return;
     const newBlocks = editor.document;
     lastEmittedHashRef.current = JSON.stringify(newBlocks);
     const isEmpty = isDocumentEmpty(newBlocks);
+    const wasEmpty = parentKnowsEmptyRef.current ?? isDocumentEmpty(processedContentRef.current);
+    if (isEmpty && wasEmpty) return;
+    parentKnowsEmptyRef.current = isEmpty;
 
     function hasUnresolvedDiffsRecursive(block: any): boolean {
       if (!block || typeof block !== "object") return false;
@@ -880,6 +890,8 @@ export default function BlockNoteEditor({
     onChange(newBlocks, isEmpty, hasUnresolvedDiff);
   }, [editor, onChange, id, acceptedChanges, rejectedChanges]);
 
+  processedContentRef.current = processedContent as any[];
+
   // Utility: deep equality for arrays of blocks
   const areBlocksEqual = (a: any[], b: any[]): boolean => {
     return JSON.stringify(a) === JSON.stringify(b);
@@ -912,6 +924,8 @@ export default function BlockNoteEditor({
     if (collaboration) return;
     const hash = JSON.stringify(processedContent);
     if (previousContentHashRef.current === hash) return; // no changes
+    // New content from the parent: that is now the text it knows.
+    parentKnowsEmptyRef.current = isDocumentEmpty(processedContent as any[]);
     // Skip replaceBlocks when the new initialContent is just an echo of what
     // the editor itself emitted. Without this, a form-controlled parent
     // (FormBlockNote) round-trips field.value back as initialContent on every

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;