Merge remote-tracking branch 'gitea/develop' into feat/481-version-coherence

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

AGENTS.md

@@ -463,6 +463,7 @@ Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirro
 - The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, schema, `canonicalizeFootnotes`) — editor schema changes often need to be made in `editor-ext`, not just the client. Server-side markdown import/export no longer lives in `editor-ext`: it goes through the canonical converter (#345, see below). The ProseMirror↔Markdown converter and its Docmost schema mirror now live in a SINGLE package, `@docmost/prosemirror-markdown` (#293), consumed by `mcp`, `git-sync`, `apps/server` (#345), and `apps/client` (#347) — do NOT reintroduce a per-package copy. The client uses the package's `browser` entry (`@docmost/prosemirror-markdown/browser`): markdown paste (`markdown-clipboard.ts`), copy-as-markdown, and AI-chat rendering now all go through the canonical converter, so the hand-written `marked`/`turndown` markdown layer that used to live in `editor-ext` was deleted (#347). The browser entry runs the HTML→DOM stage on the native `DOMParser`, so jsdom stays out of the client bundle. `editor-ext` is the upstream source of the Tiptap schema; the package's `docmost-schema.ts` mirrors it and a serializer-contract test (`packages/prosemirror-markdown/test/serializer-contract.test.ts`) guards the boundary (every schema node must have a converter case), so a drift surfaces as a failing test rather than silent divergence. For the converter's property-testing and counterexample→fixture process (P1–P4 invariants, the `PROPERTY_SEED`/`PROPERTY_NUM_RUNS` knobs, and the nightly fuzz workflow), see `packages/prosemirror-markdown/README.md`.
 - API access goes through `apps/client/src/lib/api-client.ts` (axios). The `@` alias maps to `apps/client/src`.
 - Runtime config is injected at build time by `vite.config.ts` via `define` (`APP_URL`, `COLLAB_URL`, `APP_VERSION`, …) — these come from the root `.env`, not from `import.meta.env`.
+- The build also emits `client/dist/version.json` (`{"version": …}`) from a small `vite.config.ts` plugin using the **same** `appVersion` that feeds `define.APP_VERSION`, so the file and the baked-in bundle version are identical by construction. The server reads it at startup (`ws.gateway.ts` via `readClientBuildVersion`/`resolveClientDistPath`) and announces it to each socket on connect (`app-version` event) so a tab left open across a redeploy can guard-reload before hitting a stale chunk (version-coherence). No runtime env / Dockerfile change — the file already ships in `client/dist`; missing/empty file ⇒ feature inert.
 
 ## Conventions
 

CHANGELOG.md

@@ -142,6 +142,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   snapshots switched from a fixed interval to a trailing idle-flush with a
   max-wait ceiling, and a boundary snapshot is pinned whenever the editing source
   changes (e.g. a person's edits followed by the AI agent). (#370)
+- **Open tabs pick up a new deploy on their own.** After the server is
+  redeployed while a tab is left open for hours, the tab now learns the new
+  build version over the existing WebSocket (announced per-connect, so a natural
+  reconnect delivers it) and shows a "A new version is available" banner with an
+  Update button. To avoid dropping a half-written comment or form, the tab is
+  not reloaded when you merely switch away from it; instead it auto-reloads at
+  the next safe point — the next in-app navigation (or immediately if you click
+  Update) — before it can hit a stale lazy-loaded chunk. At most one automatic
+  reload happens per 5-minute window, shared with the existing chunk-load
+  recovery, so a permanent version skew degrades to the banner rather than a
+  reload loop while a second deploy in the same tab still recovers. When the
+  build carries no version info the feature stays inert. (#481)
 
 - **Place several images side by side in a row.** A new "Inline (side by
   side)" alignment mode in the image bubble menu renders consecutive inline

apps/client/public/locales/en-US/translation.json

@@ -1,4 +1,5 @@
 {
+  "A new version is available": "A new version is available",
   "Account": "Account",
   "Active": "Active",
   "Add": "Add",

apps/client/public/locales/ru-RU/translation.json

@@ -1,4 +1,5 @@
 {
+  "A new version is available": "Доступна новая версия",
   "Account": "Аккаунт",
   "Active": "Активный",
   "Add": "Добавить",

apps/client/src/components/chunk-load-error-boundary.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { isChunkLoadError, shouldAutoReload } from "./chunk-load-error-boundary";
+import { isChunkLoadError } from "./chunk-load-error-boundary";
 
 // The detector decides whether a caught render error is a stale-deploy chunk-404
 // (→ auto-reload to fetch the new manifest) vs a genuine app error (→ generic
@@ -35,31 +35,3 @@ describe("isChunkLoadError", () => {
     expect(isChunkLoadError(err)).toBe(false);
   });
 });
-
-// The window gate replaces the old one-shot flag: it must permit recovery across
-// several deploys in one tab (each > window apart) while still stopping an infinite
-// reload loop when a lazy chunk is permanently broken (a second failure < window).
-describe("shouldAutoReload", () => {
-  const WINDOW = 5 * 60 * 1000;
-  const NOW = 1_000_000_000_000;
-
-  it("allows a reload when we have never auto-reloaded", () => {
-    expect(shouldAutoReload(NOW, null, WINDOW)).toBe(true);
-  });
-
-  it("allows a reload when the last one was 6 minutes ago (outside the window)", () => {
-    expect(shouldAutoReload(NOW, NOW - 6 * 60 * 1000, WINDOW)).toBe(true);
-  });
-
-  it("blocks a reload when the last one was 1 minute ago (inside the window)", () => {
-    expect(shouldAutoReload(NOW, NOW - 1 * 60 * 1000, WINDOW)).toBe(false);
-  });
-
-  it("blocks a reload exactly at the window boundary (not strictly older)", () => {
-    expect(shouldAutoReload(NOW, NOW - WINDOW, WINDOW)).toBe(false);
-  });
-
-  it("allows a reload when the stored timestamp is unparseable (NaN)", () => {
-    expect(shouldAutoReload(NOW, NaN, WINDOW)).toBe(true);
-  });
-});

apps/client/src/components/chunk-load-error-boundary.tsx

@@ -1,26 +1,11 @@
 import { ReactNode } from "react";
 import { ErrorBoundary } from "react-error-boundary";
 import { Button, Center, Stack, Text } from "@mantine/core";
-
-// sessionStorage key holding the epoch-ms timestamp of the last automatic reload.
-const RELOAD_AT_KEY = "chunk-reload-at";
-// Allow at most one automatic reload per this window. A stale-deploy 404 is cured
-// by a single reload, so anything inside the window is treated as a reload loop
-// (permanently-broken chunk) and falls through to the manual UI. A window (rather
-// than a one-shot flag) lets a SECOND deploy in the same tab's lifetime recover too.
-const RELOAD_WINDOW_MS = 5 * 60 * 1000;
-
-// Pure window decision, unit-tested in isolation: auto-reload only if we have never
-// auto-reloaded (lastReloadAt null/NaN) or the last one was strictly older than the
-// window. Anything inside the window is suppressed to break an infinite reload loop.
-export function shouldAutoReload(
-  now: number,
-  lastReloadAt: number | null,
-  windowMs: number,
-): boolean {
-  if (lastReloadAt === null || Number.isNaN(lastReloadAt)) return true;
-  return now - lastReloadAt > windowMs;
-}
+import {
+  hasAutoReloaded,
+  markAutoReloaded,
+  recordReloadBreadcrumb,
+} from "@/lib/reload-guard";
 
 // Heuristic detection of a failed dynamic import. Since the code-splitting work,
 // every route (plus Aside / AiChatWindow) is React.lazy: when a new deploy
@@ -39,24 +24,26 @@ export function isChunkLoadError(error: unknown): boolean {
   );
 }
 
-function handleError(error: unknown) {
+// Exported for tests: the reactive chunk-load reload decision, so the shared
+// window budget (invariant: ≤1 auto-reload per window across this path AND the
+// proactive version-coherence path) can be exercised against the real guard.
+export function handleError(error: unknown) {
   if (!isChunkLoadError(error)) return;
   // A stale-chunk 404 is cured by a full reload that re-fetches index.html and
-  // the new chunk manifest. Auto-reload at most once per RELOAD_WINDOW_MS: this
-  // recovers across multiple deploys in a single tab's lifetime, yet a
-  // permanently-broken lazy chunk (which would loop) is stopped after the first
-  // reload and falls through to the manual recovery UI below.
-  try {
-    const raw = sessionStorage.getItem(RELOAD_AT_KEY);
-    const lastReloadAt = raw === null ? null : Number.parseInt(raw, 10);
-    const now = Date.now();
-    if (!shouldAutoReload(now, lastReloadAt, RELOAD_WINDOW_MS)) return;
-    sessionStorage.setItem(RELOAD_AT_KEY, String(now));
-  } catch {
-    // sessionStorage unavailable (private mode / disabled): skip the automatic
-    // reload rather than risk an unguarded loop; the fallback UI still recovers.
-    return;
-  }
+  // the new chunk manifest. Auto-reload at most once per window via the SHARED
+  // window-based reload guard (see @/lib/reload-guard — the same budget the
+  // proactive version-coherence path consumes, so a mismatch that arrives on
+  // both paths reloads at most once per window across BOTH). This recovers
+  // across multiple deploys in a single tab's lifetime, yet a permanently-broken
+  // lazy chunk (which would loop) is stopped after the first reload and falls
+  // through to the manual recovery UI below. If the shared budget is already
+  // spent this window, or the stamp write fails (storage unavailable), we return
+  // without reloading rather than risk a loop.
+  if (hasAutoReloaded()) return;
+  if (!markAutoReloaded()) return;
+  // Trace before the reload clears the console (same diagnostic breadcrumb the
+  // proactive version-coherence path writes, tagged with this path).
+  recordReloadBreadcrumb({ path: "chunk-boundary" });
   window.location.reload();
 }
 

apps/client/src/features/user/guarded-reload.test.tsx

@@ -0,0 +1,195 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { render, act, cleanup } from "@testing-library/react";
+import { MemoryRouter, useNavigate } from "react-router-dom";
+
+// Mocks for the dirty shell's side-effecting collaborators.
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: vi.fn() },
+}));
+vi.mock("@/i18n.ts", () => ({ default: { t: (k: string) => k } }));
+vi.mock("@/lib/reload-guard", () => ({
+  hasAutoReloaded: vi.fn(() => false),
+  markAutoReloaded: vi.fn(() => true),
+  recordReloadBreadcrumb: vi.fn(),
+  takeReloadBreadcrumb: vi.fn(() => null),
+}));
+
+import { notifications } from "@mantine/notifications";
+import { hasAutoReloaded, markAutoReloaded } from "@/lib/reload-guard";
+import {
+  triggerGuardedReload,
+  useVersionReloadOnNavigation,
+  __resetGuardedReloadForTests,
+} from "./guarded-reload";
+
+const show = notifications.show as unknown as ReturnType<typeof vi.fn>;
+const mockHasAutoReloaded = hasAutoReloaded as unknown as ReturnType<
+  typeof vi.fn
+>;
+const mockMarkAutoReloaded = markAutoReloaded as unknown as ReturnType<
+  typeof vi.fn
+>;
+
+let reload: ReturnType<typeof vi.fn>;
+let visibility: DocumentVisibilityState;
+
+// Test harness mounted inside a router: it installs the navigation hook and
+// exposes `navigate` so a test can drive an in-app router navigation.
+let doNavigate: (to: string) => void;
+function Harness() {
+  useVersionReloadOnNavigation();
+  const navigate = useNavigate();
+  doNavigate = navigate;
+  return null;
+}
+
+function mountHarness() {
+  render(
+    <MemoryRouter initialEntries={["/start"]}>
+      <Harness />
+    </MemoryRouter>,
+  );
+}
+
+function navigateTo(path: string) {
+  act(() => {
+    doNavigate(path);
+  });
+}
+
+beforeEach(() => {
+  __resetGuardedReloadForTests();
+  vi.clearAllMocks();
+  mockHasAutoReloaded.mockReturnValue(false);
+  mockMarkAutoReloaded.mockReturnValue(true);
+
+  vi.stubGlobal("APP_VERSION", "test-A");
+
+  reload = vi.fn();
+  Object.defineProperty(window, "location", {
+    configurable: true,
+    value: { reload },
+  });
+
+  visibility = "visible";
+  Object.defineProperty(document, "visibilityState", {
+    configurable: true,
+    get: () => visibility,
+  });
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+describe("triggerGuardedReload (variant C)", () => {
+  it("noop when versions match: no banner, no reload", () => {
+    triggerGuardedReload("test-A");
+    expect(show).not.toHaveBeenCalled();
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("noop when the server version is empty (fail-safe)", () => {
+    triggerGuardedReload("");
+    triggerGuardedReload(undefined);
+    expect(show).not.toHaveBeenCalled();
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("real mismatch shows the banner but does NOT reload immediately", () => {
+    mountHarness();
+    triggerGuardedReload("test-B");
+    expect(show).toHaveBeenCalledTimes(1);
+    expect(show.mock.calls[0][0]).toMatchObject({
+      id: "app-version-reload",
+      autoClose: false,
+      withCloseButton: true,
+    });
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("reloads EXACTLY ONCE on the first in-app navigation after a mismatch", () => {
+    mountHarness();
+    triggerGuardedReload("test-B");
+    expect(reload).not.toHaveBeenCalled();
+
+    navigateTo("/next");
+    expect(reload).toHaveBeenCalledTimes(1);
+
+    // A second navigation must NOT reload again (one-shot was consumed).
+    navigateTo("/again");
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT reload on a 2nd mismatch after the first was armed/consumed (one-shot)", () => {
+    mountHarness();
+    triggerGuardedReload("test-B");
+    navigateTo("/next");
+    expect(reload).toHaveBeenCalledTimes(1);
+
+    // Another app-version mismatch arrives (reconnect): must not re-arm.
+    triggerGuardedReload("test-C");
+    navigateTo("/again");
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT reload merely from the tab going to the background", () => {
+    mountHarness();
+    triggerGuardedReload("test-B");
+    expect(reload).not.toHaveBeenCalled();
+
+    visibility = "hidden";
+    act(() => {
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("a hidden-at-receipt tab is also NOT reloaded immediately (variant C uniform); reloads on next navigation", () => {
+    visibility = "hidden";
+    mountHarness();
+    triggerGuardedReload("test-B");
+    expect(reload).not.toHaveBeenCalled();
+    expect(show).toHaveBeenCalledTimes(1);
+
+    navigateTo("/next");
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it("the banner's Update button reloads immediately", () => {
+    triggerGuardedReload("test-B");
+    const message = show.mock.calls[0][0].message as {
+      props: { onClick: () => void };
+    };
+    message.props.onClick();
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it("banner-only (auto-reload already spent): banner, never auto-reload on navigation", () => {
+    mockHasAutoReloaded.mockReturnValue(true);
+    mountHarness();
+    triggerGuardedReload("test-B");
+    expect(show).toHaveBeenCalledTimes(1);
+
+    navigateTo("/next");
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("does NOT reload when the flag write fails; falls back to the banner", () => {
+    mockMarkAutoReloaded.mockReturnValue(false);
+    mountHarness();
+    triggerGuardedReload("test-B");
+    navigateTo("/next");
+    expect(reload).not.toHaveBeenCalled();
+    // performAutoReload falls back to showing the banner (initial + fallback).
+    expect(show).toHaveBeenCalled();
+  });
+
+  it("is idempotent within a tab-load: repeated emits do not stack banners", () => {
+    triggerGuardedReload("test-B");
+    triggerGuardedReload("test-B");
+    triggerGuardedReload("test-C");
+    expect(show).toHaveBeenCalledTimes(1);
+  });
+});

apps/client/src/features/user/guarded-reload.tsx

@@ -0,0 +1,188 @@
+import { useEffect, useRef } from "react";
+import { useLocation } from "react-router-dom";
+import { Button } from "@mantine/core";
+import { notifications } from "@mantine/notifications";
+import i18n from "@/i18n.ts";
+import {
+  hasAutoReloaded,
+  markAutoReloaded,
+  recordReloadBreadcrumb,
+  takeReloadBreadcrumb,
+} from "@/lib/reload-guard";
+import { decideVersionAction } from "@/features/user/version-coherence";
+
+// Dirty shell around the pure `decideVersionAction`: it reads globals
+// (APP_VERSION), touches sessionStorage via the shared reload-guard, drives the
+// Mantine notification, and arms the router-navigation reload hook. Kept
+// separate from the pure module so the decision stays unit-testable without a
+// DOM.
+
+// One fixed id so repeated app-version signals (e.g. every reconnect) update a
+// single banner instead of stacking a new one each time.
+const BANNER_ID = "app-version-reload";
+
+// Module-level idempotency for the current tab-load: once a mismatch has been
+// handled we don't re-arm the navigation reload or re-show the banner on
+// subsequent app-version emits.
+let handled = false;
+
+// Variant C: on a real mismatch we do NOT reload the tab when it merely goes to
+// the background (that would silently drop a half-written comment/form). Instead
+// we arm a one-shot reload for the NEXT in-app router navigation — a point where
+// the user is already leaving the current page, so an in-app navigation would
+// discard that unsaved component-state anyway and the reload adds no extra loss.
+let pendingNavReload = false;
+
+// Remembered from the last detected mismatch for the pre-reload breadcrumb and
+// the (already-visible) banner.
+let lastServerVersion = "";
+let lastClientVersion = "";
+
+// Read the build version baked into THIS bundle. The `typeof` guard avoids a
+// ReferenceError where the `APP_VERSION` global is absent (e.g. under vitest,
+// where Vite's `define` did not run) — an unknown client version makes the
+// pure decision no-op (fail-safe).
+function readClientVersion(): string {
+  return (typeof APP_VERSION !== "undefined" ? APP_VERSION : "").trim();
+}
+
+// Perform the actual reload — but only after the shared one-shot flag is
+// persisted. If the write fails (storage unavailable) we must NOT reload
+// (mirrors the reactive chunk-load boundary's `catch → return`), and fall back
+// to the manual banner so the user can still recover.
+function performAutoReload(): void {
+  if (!markAutoReloaded()) {
+    showReloadBanner();
+    return;
+  }
+  // Trace right before the reload (which clears the console): a persistent
+  // breadcrumb + a log line so the auto-reload is observable in a field report.
+  recordReloadBreadcrumb({
+    path: "proactive",
+    serverVersion: lastServerVersion,
+    clientVersion: lastClientVersion,
+  });
+  console.warn(
+    `[version-coherence] auto-reloading: client=${lastClientVersion} -> server=${lastServerVersion}`,
+  );
+  window.location.reload();
+}
+
+function showReloadBanner(): void {
+  notifications.show({
+    id: BANNER_ID,
+    title: i18n.t("A new version is available"),
+    message: (
+      <Button size="xs" mt="xs" onClick={() => performAutoReload()}>
+        {i18n.t("Update")}
+      </Button>
+    ),
+    autoClose: false,
+    withCloseButton: true,
+  });
+}
+
+/**
+ * Handle a server `app-version` announcement: compare it to this bundle's
+ * version and, on a real mismatch, show the banner and arm a guarded reload for
+ * the next in-app navigation (variant C).
+ *
+ * - real mismatch (window budget available) → banner + arm navigation reload.
+ *   The banner's "Update" button reloads immediately (same shared window guard).
+ *   The tab is NOT reloaded on visibility change.
+ * - auto-reload already used this window / storage error → banner only (no arm),
+ *   so there is at most one automatic reload per RELOAD_WINDOW_MS window (loop
+ *   safety).
+ * - in sync / unknown version → noop (fail-safe).
+ */
+export function triggerGuardedReload(
+  rawServerVersion: string | undefined | null,
+): void {
+  const serverVersion = (rawServerVersion ?? "").trim();
+  const clientVersion = readClientVersion();
+
+  // A storage read error surfaces as autoReloadUsed=true → fail toward NOT
+  // reloading (banner only).
+  const autoReloadUsed = hasAutoReloaded();
+
+  const action = decideVersionAction({
+    serverVersion,
+    clientVersion,
+    autoReloadUsed,
+  });
+  if (action === "noop") return;
+
+  // Idempotent per tab-load: don't re-arm or re-stack the banner across repeated
+  // emits (reconnects) once we've already acted.
+  if (handled) return;
+  handled = true;
+
+  lastServerVersion = serverVersion;
+  lastClientVersion = clientVersion;
+
+  if (action === "banner") {
+    // Entered banner-only (permanent skew, node oscillation, or the window's
+    // auto-reload budget already spent). Log for diagnosability; show the banner.
+    console.warn(
+      `[version-coherence] server=${serverVersion} client=${clientVersion}: ` +
+        "auto-reload budget already spent this window — showing manual banner",
+    );
+    showReloadBanner();
+    return;
+  }
+
+  // action === "reload" (variant C): show the banner and defer the auto-reload
+  // to the next in-app navigation instead of reloading now / on visibility.
+  showReloadBanner();
+  pendingNavReload = true;
+}
+
+/**
+ * Consume the armed one-shot navigation reload, if any. Called by
+ * `useVersionReloadOnNavigation` on each in-app router navigation.
+ */
+export function consumeNavigationReload(): void {
+  if (!pendingNavReload) return;
+  pendingNavReload = false;
+  performAutoReload();
+}
+
+/**
+ * Hook (mounted inside the Router) that fires the armed one-shot reload on the
+ * NEXT in-app router navigation after a version mismatch. Skips the initial
+ * render so it only reacts to real navigations, not the first location.
+ */
+export function useVersionReloadOnNavigation(): void {
+  const location = useLocation();
+  const firstRender = useRef(true);
+  useEffect(() => {
+    if (firstRender.current) {
+      firstRender.current = false;
+      return;
+    }
+    consumeNavigationReload();
+  }, [location.key]);
+}
+
+/**
+ * Surface (log once) the breadcrumb left by an auto-reload in the previous page
+ * load — the reload cleared the console, so this makes a "tab reloaded itself"
+ * report diagnosable. Call once on app startup.
+ */
+export function surfacePreviousReloadBreadcrumb(): void {
+  const crumb = takeReloadBreadcrumb();
+  if (!crumb) return;
+  console.info(
+    `[version-coherence] previous auto-reload: path=${crumb.path} ` +
+      `client=${crumb.clientVersion ?? ""} -> server=${crumb.serverVersion ?? ""} ` +
+      `at=${new Date(crumb.at).toISOString()}`,
+  );
+}
+
+// Test-only: reset module-level latches between cases.
+export function __resetGuardedReloadForTests(): void {
+  handled = false;
+  pendingNavReload = false;
+  lastServerVersion = "";
+  lastClientVersion = "";
+}

apps/client/src/features/user/reload-budget.integration.test.tsx

@@ -0,0 +1,171 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { render, act, cleanup } from "@testing-library/react";
+import { MemoryRouter, useNavigate } from "react-router-dom";
+
+// Integration test for the SHARED, window-based auto-reload budget (invariant a):
+// the reactive chunk-load boundary and the proactive version-coherence path both
+// route through the REAL @/lib/reload-guard, so at most one automatic reload
+// happens per RELOAD_WINDOW_MS across BOTH paths combined. Only the two paths'
+// side-effecting collaborators are mocked — the reload guard is intentionally
+// REAL so this exercises the actual shared sessionStorage budget.
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: vi.fn() },
+}));
+vi.mock("@/i18n.ts", () => ({ default: { t: (k: string) => k } }));
+
+import { handleError } from "@/components/chunk-load-error-boundary";
+import {
+  triggerGuardedReload,
+  useVersionReloadOnNavigation,
+  __resetGuardedReloadForTests,
+} from "./guarded-reload";
+import { RELOAD_WINDOW_MS } from "@/lib/reload-guard";
+
+const CHUNK_ERROR = { name: "ChunkLoadError", message: "boom" };
+const T0 = 1_000_000_000_000;
+
+let reload: ReturnType<typeof vi.fn>;
+let nowMock: ReturnType<typeof vi.spyOn>;
+
+// Harness mounted inside a router: installs the navigation hook and exposes
+// `navigate` so a test can drive an in-app router navigation (the point where the
+// proactive path fires its armed reload).
+let doNavigate: (to: string) => void;
+function Harness() {
+  useVersionReloadOnNavigation();
+  doNavigate = useNavigate();
+  return null;
+}
+function mountHarness() {
+  render(
+    <MemoryRouter initialEntries={["/start"]}>
+      <Harness />
+    </MemoryRouter>,
+  );
+}
+function navigateTo(path: string) {
+  act(() => {
+    doNavigate(path);
+  });
+}
+function setNow(t: number) {
+  nowMock.mockReturnValue(t);
+}
+
+beforeEach(() => {
+  sessionStorage.clear();
+  __resetGuardedReloadForTests();
+  vi.clearAllMocks();
+  nowMock = vi.spyOn(Date, "now").mockReturnValue(T0);
+  vi.stubGlobal("APP_VERSION", "test-A");
+  reload = vi.fn();
+  Object.defineProperty(window, "location", {
+    configurable: true,
+    value: { reload },
+  });
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  sessionStorage.clear();
+});
+
+describe("shared window-based reload budget (invariant a)", () => {
+  it("a chunk-load reload spends the budget: a version-coherence mismatch within the window shows the banner but does NOT reload", () => {
+    // Path 1 (reactive): a stale-chunk 404 auto-reloads once and stamps the window.
+    handleError(CHUNK_ERROR);
+    expect(reload).toHaveBeenCalledTimes(1);
+    reload.mockClear();
+
+    // Path 2 (proactive), 1 min later — still inside the window. The shared budget
+    // is spent, so the version mismatch degrades to the banner and never reloads.
+    setNow(T0 + 60_000);
+    mountHarness();
+    triggerGuardedReload("test-B");
+    navigateTo("/next");
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("a version-coherence reload spends the SAME budget: a chunk-load error within the window does NOT reload", () => {
+    // Path 2 (proactive) first: real mismatch → arm → fire on navigation.
+    mountHarness();
+    triggerGuardedReload("test-B");
+    navigateTo("/next");
+    expect(reload).toHaveBeenCalledTimes(1);
+    reload.mockClear();
+
+    // Path 1 (reactive), 2 min later — inside the window. Budget already spent by
+    // the proactive path, so the stale-chunk error must NOT trigger a second reload.
+    setNow(T0 + 2 * 60_000);
+    handleError(CHUNK_ERROR);
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("recovers after the window: a reload strictly older than the window is allowed again (second deploy)", () => {
+    // First auto-reload (reactive) stamps the window.
+    handleError(CHUNK_ERROR);
+    expect(reload).toHaveBeenCalledTimes(1);
+    reload.mockClear();
+
+    // A second deploy arrives after the window has fully elapsed → the proactive
+    // path is allowed to reload again (window, not a permanent one-shot).
+    __resetGuardedReloadForTests();
+    setNow(T0 + RELOAD_WINDOW_MS + 1);
+    mountHarness();
+    triggerGuardedReload("test-B");
+    navigateTo("/next");
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it("reactive path fails closed when storage READS but cannot WRITE (quota / Safari private): no unguarded reload", () => {
+    // getItem→null makes hasAutoReloaded() report the budget as available, so
+    // handleError passes the first guard and reaches `if (!markAutoReloaded())
+    // return;`. setItem throws → the stamp cannot stick, so markAutoReloaded()
+    // returns false and that guard MUST bail — otherwise the reactive path would
+    // reload on every stale-chunk error with no persisted budget (an unguarded
+    // loop). This is the asymmetric gap: the proactive path's equivalent is
+    // covered by guarded-reload.test.tsx "does NOT reload when the flag write
+    // fails".
+    vi.stubGlobal("sessionStorage", {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error("quota exceeded");
+      },
+      removeItem: () => {},
+      clear: () => {},
+    });
+    try {
+      handleError(CHUNK_ERROR);
+      expect(reload).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("sessionStorage unavailable: neither path performs an unguarded reload", () => {
+    // The real guard fails toward NOT reloading when storage throws.
+    vi.stubGlobal("sessionStorage", {
+      getItem: () => {
+        throw new Error("storage disabled");
+      },
+      setItem: () => {
+        throw new Error("storage disabled");
+      },
+      removeItem: () => {},
+      clear: () => {},
+    });
+    try {
+      handleError(CHUNK_ERROR);
+      expect(reload).not.toHaveBeenCalled();
+
+      mountHarness();
+      triggerGuardedReload("test-B");
+      navigateTo("/next");
+      expect(reload).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+});

apps/client/src/features/user/user-provider.tsx

@@ -13,6 +13,12 @@ import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
 import { Error404 } from "@/components/ui/error-404.tsx";
 import { queryClient } from "@/main.tsx";
 import { makeConnectHandler } from "@/features/user/connect-resync.ts";
+import {
+  triggerGuardedReload,
+  useVersionReloadOnNavigation,
+  surfacePreviousReloadBreadcrumb,
+} from "@/features/user/guarded-reload.tsx";
+import type { AppVersionSocketPayload } from "@/features/user/version-coherence.ts";
 
 export function UserProvider({ children }: React.PropsWithChildren) {
   const [, setCurrentUser] = useAtom(currentUserAtom);
@@ -22,6 +28,16 @@ export function UserProvider({ children }: React.PropsWithChildren) {
   // fetch collab token on load
   const { data: collab } = useCollabToken();
 
+  // version-coherence: fire the armed one-shot reload on the next in-app
+  // navigation (variant C — a safe point, not on tab backgrounding).
+  useVersionReloadOnNavigation();
+
+  // Surface any breadcrumb left by an auto-reload in the previous page load
+  // (the reload cleared the console) so a field report stays diagnosable.
+  useEffect(() => {
+    surfacePreviousReloadBreadcrumb();
+  }, []);
+
   useEffect(() => {
     if (isLoading || isError) {
       return;
@@ -47,6 +63,16 @@ export function UserProvider({ children }: React.PropsWithChildren) {
       handleConnect();
     });
 
+    // Register the version-coherence listener SYNCHRONOUSLY, before the socket
+    // connects: the server emits `app-version` immediately in handleConnection,
+    // so a listener attached after connect would miss it on a fast localhost
+    // connect. On a version mismatch the client shows a banner and defers the
+    // auto-reload to the next in-app navigation (variant C — avoids reloading a
+    // backgrounded tab that may hold unsaved input) before it hits a stale chunk.
+    newSocket.on("app-version", (payload?: AppVersionSocketPayload) => {
+      triggerGuardedReload(payload?.version);
+    });
+
     return () => {
       console.log("ws disconnected");
       newSocket.disconnect();

apps/client/src/features/user/version-coherence.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest";
+import { decideVersionAction } from "./version-coherence";
+
+describe("decideVersionAction", () => {
+  it("noop when the server version is empty (fail-safe)", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "",
+        clientVersion: "v1",
+        autoReloadUsed: false,
+      }),
+    ).toBe("noop");
+  });
+
+  it("noop when the client version is empty (fail-safe)", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "v1",
+        clientVersion: "",
+        autoReloadUsed: false,
+      }),
+    ).toBe("noop");
+  });
+
+  it("noop when versions are equal (in sync)", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "v1",
+        clientVersion: "v1",
+        autoReloadUsed: false,
+      }),
+    ).toBe("noop");
+  });
+
+  it("reload on a real mismatch the first time this session", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "test-B",
+        clientVersion: "test-A",
+        autoReloadUsed: false,
+      }),
+    ).toBe("reload");
+  });
+
+  it("banner on a mismatch once the session auto-reload is spent", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "test-B",
+        clientVersion: "test-A",
+        autoReloadUsed: true,
+      }),
+    ).toBe("banner");
+  });
+
+  it("equal versions stay noop even if auto-reload was already used", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "v1",
+        clientVersion: "v1",
+        autoReloadUsed: true,
+      }),
+    ).toBe("noop");
+  });
+});

apps/client/src/features/user/version-coherence.ts

@@ -0,0 +1,32 @@
+// Payload of the per-connect `app-version` socket.io event announced by the
+// server (ws.gateway.ts) after a successful auth. A dedicated event — NOT a
+// member of the room-scoped `WebSocketEvent` union (which is discriminated by
+// `operation`), so it never touches use-query-subscription.
+export type AppVersionSocketPayload = { version: string };
+
+/**
+ * Pure decision for the version-coherence guard.
+ *
+ * All inputs are injected (no globals, no side effects) so it is unit-testable
+ * without a DOM or the build-time `APP_VERSION` global (undefined under vitest).
+ *
+ * - `autoReloadUsed` = an automatic reload has already happened within the
+ *   current ~5-min window, so we must not auto-reload again (loop safety,
+ *   shared window budget with the reactive chunk-load boundary).
+ *
+ * Returns:
+ * - "noop"   — do nothing (unknown version on either side, or already in sync).
+ * - "banner" — show the manual "update available" banner only (no auto-reload).
+ * - "reload" — real first-time mismatch: eligible for a guarded auto-reload.
+ */
+export function decideVersionAction(args: {
+  serverVersion: string;
+  clientVersion: string;
+  autoReloadUsed: boolean;
+}): "reload" | "banner" | "noop" {
+  const { serverVersion, clientVersion, autoReloadUsed } = args;
+  if (!serverVersion || !clientVersion) return "noop"; // fail-safe: unknown version → never act
+  if (serverVersion === clientVersion) return "noop"; // in sync
+  if (autoReloadUsed) return "banner"; // one auto-reload per RELOAD_WINDOW_MS window already spent
+  return "reload"; // real mismatch, window budget available
+}

apps/client/src/lib/reload-guard.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  hasAutoReloaded,
+  markAutoReloaded,
+  shouldAutoReload,
+  recordReloadBreadcrumb,
+  takeReloadBreadcrumb,
+  RELOAD_WINDOW_MS,
+} from "./reload-guard";
+
+// The shared budget is a single sessionStorage timestamp keyed here; both the
+// reactive chunk-load boundary and the proactive version-coherence path read and
+// stamp it, so at most one auto-reload happens per RELOAD_WINDOW_MS across BOTH.
+const RELOAD_AT_KEY = "chunk-reload-at";
+const NOW = 1_000_000_000_000;
+
+describe("reload-guard", () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    sessionStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("hasAutoReloaded is false before any reload, true within the window after mark", () => {
+    expect(hasAutoReloaded(NOW)).toBe(false);
+    expect(markAutoReloaded(NOW)).toBe(true);
+    // Same key both paths share; stores the reload timestamp, not a flag.
+    expect(sessionStorage.getItem(RELOAD_AT_KEY)).toBe(String(NOW));
+    // Inside the window → budget spent → true (fall through to manual UI).
+    expect(hasAutoReloaded(NOW)).toBe(true);
+    expect(hasAutoReloaded(NOW + RELOAD_WINDOW_MS)).toBe(true);
+  });
+
+  it("hasAutoReloaded is false again once the window has elapsed (a later deploy recovers)", () => {
+    markAutoReloaded(NOW);
+    // Strictly older than the window → a new deploy's mismatch may reload again.
+    expect(hasAutoReloaded(NOW + RELOAD_WINDOW_MS + 1)).toBe(false);
+  });
+
+  it("hasAutoReloaded returns true when reading storage throws (fail toward not reloading)", () => {
+    vi.stubGlobal("sessionStorage", {
+      getItem: () => {
+        throw new Error("storage disabled");
+      },
+      setItem: () => {
+        throw new Error("storage disabled");
+      },
+    });
+    try {
+      expect(hasAutoReloaded()).toBe(true);
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("hasAutoReloaded treats an unparseable stored timestamp as never-reloaded", () => {
+    sessionStorage.setItem(RELOAD_AT_KEY, "not-a-number");
+    expect(hasAutoReloaded(NOW)).toBe(false);
+  });
+
+  it("markAutoReloaded returns false when writing storage throws", () => {
+    vi.stubGlobal("sessionStorage", {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error("storage disabled");
+      },
+    });
+    try {
+      expect(markAutoReloaded()).toBe(false);
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("records and then takes a breadcrumb once (cleared on read)", () => {
+    recordReloadBreadcrumb({
+      path: "proactive",
+      serverVersion: "test-B",
+      clientVersion: "test-A",
+    });
+    const crumb = takeReloadBreadcrumb();
+    expect(crumb).toMatchObject({
+      path: "proactive",
+      serverVersion: "test-B",
+      clientVersion: "test-A",
+    });
+    expect(typeof crumb?.at).toBe("number");
+    // Cleared on read → a second take returns null.
+    expect(takeReloadBreadcrumb()).toBeNull();
+  });
+
+  it("takeReloadBreadcrumb returns null when nothing was recorded", () => {
+    expect(takeReloadBreadcrumb()).toBeNull();
+  });
+
+  it("recordReloadBreadcrumb swallows a storage-write error (diagnostics only)", () => {
+    vi.stubGlobal("sessionStorage", {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error("storage disabled");
+      },
+      removeItem: () => {},
+    });
+    try {
+      expect(() =>
+        recordReloadBreadcrumb({ path: "chunk-boundary" }),
+      ).not.toThrow();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+});
+
+// The pure window gate replaces the old one-shot flag: it must permit recovery
+// across several deploys in one tab (each > window apart) while still stopping an
+// infinite reload loop when a lazy chunk is permanently broken (a second failure
+// < window). Moved here from the chunk-load boundary now that it is the shared
+// guard both paths route through.
+describe("shouldAutoReload", () => {
+  const WINDOW = RELOAD_WINDOW_MS;
+
+  it("allows a reload when we have never auto-reloaded", () => {
+    expect(shouldAutoReload(NOW, null, WINDOW)).toBe(true);
+  });
+
+  it("allows a reload when the last one was 6 minutes ago (outside the window)", () => {
+    expect(shouldAutoReload(NOW, NOW - 6 * 60 * 1000, WINDOW)).toBe(true);
+  });
+
+  it("blocks a reload when the last one was 1 minute ago (inside the window)", () => {
+    expect(shouldAutoReload(NOW, NOW - 1 * 60 * 1000, WINDOW)).toBe(false);
+  });
+
+  it("blocks a reload exactly at the window boundary (not strictly older)", () => {
+    expect(shouldAutoReload(NOW, NOW - WINDOW, WINDOW)).toBe(false);
+  });
+
+  it("allows a reload when the stored timestamp is unparseable (NaN)", () => {
+    expect(shouldAutoReload(NOW, NaN, WINDOW)).toBe(true);
+  });
+});

apps/client/src/lib/reload-guard.ts

@@ -0,0 +1,121 @@
+// Shared, window-based auto-reload budget.
+//
+// Both auto-reload paths — the reactive chunk-load-error-boundary (recovers
+// AFTER a stale lazy chunk 404s) and the proactive version-coherence feature
+// (reloads BEFORE the tab hits a stale chunk) — go through these functions so
+// they share ONE window-scoped reload budget: at most a single automatic
+// reload per RELOAD_WINDOW_MS across BOTH paths. A window (rather than a
+// permanent one-shot flag) lets a SECOND deploy in the same tab's lifetime
+// recover too, while a permanent skew, node oscillation, or a genuinely-missing
+// chunk still degrades to a manual banner/UI after the first reload instead of
+// looping. When sessionStorage is unavailable every mismatch degrades to the
+// manual UI — no unguarded reload.
+
+// sessionStorage key holding the epoch-ms timestamp of the last automatic reload
+// (shared by both paths).
+const RELOAD_AT_KEY = "chunk-reload-at";
+
+// Allow at most one automatic reload per this window. A stale-deploy 404 is cured
+// by a single reload, so anything inside the window is treated as a reload loop
+// (permanently-broken chunk / permanent skew) and falls through to the manual UI.
+export const RELOAD_WINDOW_MS = 5 * 60 * 1000;
+
+/**
+ * Pure window decision, unit-tested in isolation: auto-reload only if we have
+ * never auto-reloaded (lastReloadAt null/NaN) or the last one was strictly older
+ * than the window. Anything inside the window is suppressed to break an infinite
+ * reload loop.
+ */
+export function shouldAutoReload(
+  now: number,
+  lastReloadAt: number | null,
+  windowMs: number,
+): boolean {
+  if (lastReloadAt === null || Number.isNaN(lastReloadAt)) return true;
+  return now - lastReloadAt > windowMs;
+}
+
+/**
+ * Has an automatic reload already happened within the current window (so the
+ * shared budget is spent right now)? Both paths check this before reloading; a
+ * `true` return means fall through to the manual banner/UI instead of reloading.
+ *
+ * A storage read error (private mode / disabled) is reported as `true` so the
+ * caller fails toward NOT reloading — an unguarded loop is worse than a stale
+ * tab the user can reload manually. Note a window (not a permanent flag): once
+ * the window elapses a later deploy's mismatch is allowed to reload again.
+ */
+export function hasAutoReloaded(now: number = Date.now()): boolean {
+  try {
+    const raw = sessionStorage.getItem(RELOAD_AT_KEY);
+    const lastReloadAt = raw === null ? null : Number.parseInt(raw, 10);
+    return !shouldAutoReload(now, lastReloadAt, RELOAD_WINDOW_MS);
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Stamp the shared window as consumed now — record that an automatic reload is
+ * being performed within the current RELOAD_WINDOW_MS window.
+ *
+ * Returns whether the write succeeded. A `false` return (storage unavailable)
+ * means the caller MUST NOT reload — otherwise the stamp would never stick and
+ * the reload could loop.
+ */
+export function markAutoReloaded(now: number = Date.now()): boolean {
+  try {
+    sessionStorage.setItem(RELOAD_AT_KEY, String(now));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Diagnostic breadcrumb for an automatic reload. Written right before
+// window.location.reload() (which clears the console) and read back on the next
+// page load, so a "the tab reloaded itself / it's looping" field report is
+// diagnosable: which path fired (proactive version-coherence vs the reactive
+// chunk-load boundary) and which version pair triggered it. sessionStorage
+// survives a same-tab reload, unlike the console.
+const RELOAD_BREADCRUMB_KEY = "reload-breadcrumb";
+
+export type ReloadBreadcrumb = {
+  path: "proactive" | "chunk-boundary";
+  serverVersion?: string;
+  clientVersion?: string;
+  at: number;
+};
+
+/**
+ * Persist a best-effort breadcrumb just before an automatic reload. Failures
+ * (storage unavailable) are swallowed — this is diagnostics only and must never
+ * block or alter the reload decision.
+ */
+export function recordReloadBreadcrumb(
+  entry: Omit<ReloadBreadcrumb, "at">,
+): void {
+  try {
+    sessionStorage.setItem(
+      RELOAD_BREADCRUMB_KEY,
+      JSON.stringify({ ...entry, at: Date.now() }),
+    );
+  } catch {
+    // best-effort diagnostics only
+  }
+}
+
+/**
+ * Read and clear the breadcrumb left by an auto-reload in the previous page
+ * load. Cleared on read so it surfaces exactly once per reload.
+ */
+export function takeReloadBreadcrumb(): ReloadBreadcrumb | null {
+  try {
+    const raw = sessionStorage.getItem(RELOAD_BREADCRUMB_KEY);
+    if (!raw) return null;
+    sessionStorage.removeItem(RELOAD_BREADCRUMB_KEY);
+    return JSON.parse(raw) as ReloadBreadcrumb;
+  } catch {
+    return null;
+  }
+}

apps/client/vite.config.ts

@@ -1,7 +1,8 @@
-import { defineConfig, loadEnv } from "vite";
+import { defineConfig, loadEnv, type Plugin } from "vite";
 import react from "@vitejs/plugin-react";
 import { compression } from "vite-plugin-compression2";
 import * as path from "path";
+import * as fs from "node:fs";
 import { execSync } from "node:child_process";
 
 const envPath = path.resolve(process.cwd(), "..", "..");
@@ -24,7 +25,32 @@ function resolveAppVersion(cwd: string): string {
   }
 }
 
+// Emit <outDir>/version.json = { "version": appVersion } so the server can read
+// the exact same build id the bundle was compiled with. The value is the SAME
+// `appVersion` fed into `define.APP_VERSION`, so version.json and the baked-in
+// global are identical by construction — the single source of truth (no
+// runtime-env second copy that could drift and cause a false version mismatch).
+function versionJsonPlugin(version: string): Plugin {
+  let outDir = "dist";
+  return {
+    name: "emit-version-json",
+    apply: "build",
+    configResolved(config) {
+      outDir = config.build.outDir;
+    },
+    writeBundle() {
+      const root = path.resolve(process.cwd(), outDir);
+      fs.mkdirSync(root, { recursive: true });
+      fs.writeFileSync(
+        path.join(root, "version.json"),
+        JSON.stringify({ version }),
+      );
+    },
+  };
+}
+
 export default defineConfig(({ mode }) => {
+  const appVersion = resolveAppVersion(envPath);
   const {
     APP_URL,
     FILE_UPLOAD_SIZE_LIMIT,
@@ -52,10 +78,11 @@ export default defineConfig(({ mode }) => {
         POSTHOG_HOST,
         POSTHOG_KEY,
       },
-      APP_VERSION: JSON.stringify(resolveAppVersion(envPath)),
+      APP_VERSION: JSON.stringify(appVersion),
     },
     plugins: [
       react(),
+      versionJsonPlugin(appVersion),
       // Emit .br and .gz next to every built asset so the server can serve the
       // precompressed copy (see @fastify/static preCompressed in static.module.ts).
       compression({

apps/server/src/collaboration/collaboration.util.ts

@@ -141,57 +141,7 @@ export function htmlToJson(html: string) {
   }
 }
 
-/**
- * Deterministic text-serializer overrides for the `format:"text"` page read
- * (#502). Non-text nodes render to a STABLE placeholder instead of their
- * (structure-dependent) inner text, so a machine diff of two text reads is
- * driven only by the page's actual prose — output stability across package
- * versions IS the contract (pinned by a snapshot test). Returning a string from
- * a `textSerializer` also stops `generateText` descending into the node, so a
- * table renders as ONE token rather than its flattened cell text.
- *
- * Only nodes with no meaningful flat-text form are overridden; every other node
- * (paragraph/heading/list/code/blockquote/callout/…) keeps its natural text so
- * a config written as markdown reads back byte-identical.
- */
-const TEXT_READ_SERIALIZERS: Record<string, (props: { node: any }) => string> =
-  {
-    // Image atom: no inner text -> a fixed placeholder.
-    image: () => '[image]',
-    // Table: `[table RxC]` where R = row count, C = the first row's cell count
-    // (a table's columns are uniform per the schema). Computed from the PM node,
-    // so it is independent of cell contents.
-    table: ({ node }) => {
-      const rows = node?.childCount ?? 0;
-      const cols = rows > 0 ? (node.child(0)?.childCount ?? 0) : 0;
-      return `[table ${rows}x${cols}]`;
-    },
-  };
-
-/**
- * Serialize a ProseMirror/TipTap document to plain text.
- *
- * Default (no options): the long-standing search-index behavior — bare
- * concatenated node text with `generateText`'s default `\n\n` block separator.
- * This feeds the page `textContent` tsvector and MUST NOT change.
- *
- * `deterministic:true` (#502 `format:"text"` page read): a flat, machine-diffable
- * rendering — one line per block (`\n` block separator; `hardBreak` already
- * serializes to `\n`), inline marks/anchors/autoformat dropped, and non-text
- * nodes replaced by the stable placeholders above (`[image]`, `[table RxC]`).
- */
-export function jsonToText(
-  // `any` (like jsonToHtml/jsonToMarkdown) so a loosely-typed DB `page.content`
-  // (JsonValue) can be passed straight through, as the controller does.
-  tiptapJson: any,
-  options?: { deterministic?: boolean },
-) {
-  if (options?.deterministic) {
-    return generateText(tiptapJson, tiptapExtensions, {
-      blockSeparator: '\n',
-      textSerializers: TEXT_READ_SERIALIZERS,
-    });
-  }
+export function jsonToText(tiptapJson: JSONContent) {
   return generateText(tiptapJson, tiptapExtensions);
 }
 

apps/server/src/collaboration/json-to-text-deterministic.spec.ts

@@ -1,116 +0,0 @@
-import { jsonToText } from './collaboration.util';
-
-// #502 READ contract: `jsonToText(json, { deterministic: true })` — the flat,
-// machine-diffable text rendering behind getPage `format:"text"`. Block-per-line
-// (`\n` separator), inline marks/anchors dropped, hardBreak -> `\n`, and non-text
-// nodes replaced by STABLE placeholders (`[image]`, `[table RxC]`). Output
-// stability across package versions IS the contract, so it is pinned by a
-// snapshot below. The DEFAULT (no options) path is the search-index serializer
-// and MUST be unchanged — asserted separately.
-
-const doc = (...content: any[]) => ({ type: 'doc', content });
-const para = (...content: any[]) => ({ type: 'paragraph', content });
-const text = (t: string, marks?: any[]) =>
-  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
-
-describe('jsonToText — default (search index) behavior is unchanged', () => {
-  it('uses the `\\n\\n` block separator and drops non-text nodes to empty', () => {
-    const d = doc(para(text('alpha')), para(text('beta')));
-    expect(jsonToText(d)).toBe('alpha\n\nbeta');
-  });
-
-  it('an image contributes no text in the default (tsvector) mode', () => {
-    const d = doc(para(text('cap')), { type: 'image', attrs: { src: 's' } });
-    // No `[image]` placeholder leaks into the search index.
-    expect(jsonToText(d)).not.toContain('[image]');
-  });
-});
-
-describe('jsonToText — deterministic:true (getPage format:"text")', () => {
-  it('renders one line per block with `\\n` separators, marks dropped', () => {
-    const d = doc(
-      { type: 'heading', attrs: { level: 2 }, content: [text('Title')] },
-      para(
-        text('hello ', [{ type: 'bold' }]),
-        text('world', [{ type: 'italic' }]),
-      ),
-    );
-    expect(jsonToText(d, { deterministic: true })).toBe('Title\nhello world');
-  });
-
-  it('a hardBreak renders as a newline', () => {
-    const d = doc(para(text('a'), { type: 'hardBreak' }, text('b')));
-    expect(jsonToText(d, { deterministic: true })).toBe('a\nb');
-  });
-
-  it('an image node -> the stable `[image]` placeholder', () => {
-    const d = doc(para(text('before')), { type: 'image', attrs: { src: 's' } });
-    expect(jsonToText(d, { deterministic: true })).toBe('before\n[image]');
-  });
-
-  it('a table -> `[table RxC]` (rows x columns) and its cell text is NOT flattened in', () => {
-    const cell = (t: string) => ({
-      type: 'tableCell',
-      content: [para(text(t))],
-    });
-    const row = (...cells: any[]) => ({ type: 'tableRow', content: cells });
-    const table = {
-      type: 'table',
-      content: [
-        row(cell('CELLONE'), cell('CELLTWO'), cell('CELLTHREE')),
-        row(cell('CELLFOUR'), cell('CELLFIVE'), cell('CELLSIX')),
-      ],
-    };
-    const d = doc(para(text('grid:')), table);
-    const out = jsonToText(d, { deterministic: true });
-    expect(out).toBe('grid:\n[table 2x3]');
-    expect(out).not.toContain('CELL'); // cell text is not flattened into the read
-  });
-
-  it('SNAPSHOT: a mixed document renders to a stable, deterministic string', () => {
-    const cell = (t: string) => ({
-      type: 'tableCell',
-      content: [para(text(t))],
-    });
-    const d = doc(
-      { type: 'heading', attrs: { level: 1 }, content: [text('Config')] },
-      para(text('key = ', [{ type: 'bold' }]), text('value')),
-      {
-        type: 'bulletList',
-        content: [
-          { type: 'listItem', content: [para(text('one'))] },
-          { type: 'listItem', content: [para(text('two'))] },
-        ],
-      },
-      { type: 'image', attrs: { src: 's' } },
-      {
-        type: 'table',
-        content: [{ type: 'tableRow', content: [cell('x'), cell('y')] }],
-      },
-    );
-    expect(jsonToText(d, { deterministic: true })).toMatchInlineSnapshot(`
-     "Config
-     key = value
-
-
-     one
-
-     two
-     [image]
-     [table 1x2]"
-    `);
-  });
-
-  it('SCENARIO: a config written as a code block reads back byte-identical (diff empty)', () => {
-    const config =
-      'export TICKET_LIFETIME=$2592000\nservers:\n  - www.internal.host';
-    const d = doc({
-      type: 'codeBlock',
-      attrs: { language: 'yaml' },
-      content: [text(config)],
-    });
-    // The code block is one block; its text (dollars, bare domain, newlines) is
-    // preserved verbatim, so a read-as-text of a stored config diffs empty.
-    expect(jsonToText(d, { deterministic: true })).toBe(config);
-  });
-});

apps/server/src/common/helpers/client-version.spec.ts

@@ -0,0 +1,52 @@
+import { join } from 'path';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import { readClientBuildVersion } from './client-version';
+
+describe('readClientBuildVersion', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(join(os.tmpdir(), 'client-version-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  const writeVersionJson = (content: string) =>
+    fs.writeFileSync(join(dir, 'version.json'), content);
+
+  it('returns the version from a valid version.json', () => {
+    writeVersionJson(JSON.stringify({ version: 'test-A' }));
+    expect(readClientBuildVersion(dir)).toBe('test-A');
+  });
+
+  it('trims surrounding whitespace in the version', () => {
+    writeVersionJson(JSON.stringify({ version: '  v1.2.3  ' }));
+    expect(readClientBuildVersion(dir)).toBe('v1.2.3');
+  });
+
+  it('returns "" when version.json is missing', () => {
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" on malformed JSON', () => {
+    writeVersionJson('{ not json');
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" when the version field is absent', () => {
+    writeVersionJson(JSON.stringify({ notVersion: 'x' }));
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" when the version field is not a string', () => {
+    writeVersionJson(JSON.stringify({ version: 123 }));
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" when the path does not exist at all', () => {
+    expect(readClientBuildVersion(join(dir, 'nope'))).toBe('');
+  });
+});

apps/server/src/common/helpers/client-version.ts

@@ -0,0 +1,36 @@
+import { join } from 'path';
+import * as fs from 'node:fs';
+
+/**
+ * Resolve the absolute path to the built client bundle directory
+ * (`apps/client/dist`) shipped into the runtime image.
+ *
+ * The `../` depth is anchored on THIS module's compiled location
+ * (`dist/common/helpers`). `integrations/static` sits at the same depth under
+ * the compiled root, so both callers (StaticModule and readClientBuildVersion)
+ * MUST share this single helper rather than duplicating the depth — a copy in a
+ * module at a different depth would silently resolve to the wrong directory.
+ */
+export function resolveClientDistPath(): string {
+  return join(__dirname, '..', '..', '..', '..', 'client/dist');
+}
+
+/**
+ * Read the build version the client bundle was compiled with, from
+ * `<clientDistPath>/version.json` (written by the Vite build — the single
+ * source of truth shared by the baked-in `APP_VERSION` global and this file).
+ *
+ * Fail-safe: any error (missing file, unreadable, bad JSON, non-string
+ * version) yields `''`. The caller treats an empty version as "unknown" and
+ * the whole version-coherence feature stays silently inert — existing deploys
+ * without the file keep working unchanged.
+ */
+export function readClientBuildVersion(clientDistPath: string): string {
+  try {
+    const raw = fs.readFileSync(join(clientDistPath, 'version.json'), 'utf8');
+    const version = (JSON.parse(raw) as { version?: unknown }).version;
+    return typeof version === 'string' ? version.trim() : '';
+  } catch {
+    return '';
+  }
+}

apps/server/src/common/helpers/index.ts

@@ -3,3 +3,4 @@ export * from './nanoid.utils';
 export * from './file.helper';
 export * from './constants';
 export * from './security-headers';
+export * from './client-version';

apps/server/src/core/page/dto/create-page.dto.ts

@@ -10,12 +10,6 @@ import { Transform } from 'class-transformer';
 
 export type ContentFormat = 'json' | 'markdown' | 'html';
 
-// READ-only rendering formats for `getPage` (#502). A superset of the writable
-// `ContentFormat` with `text` — a flat, deterministic, machine-diffable text
-// rendering — added. Kept SEPARATE from `ContentFormat` so the write path
-// (createPage/updatePage `parseProsemirrorContent`) can never be handed `text`.
-export type PageReadFormat = ContentFormat | 'text';
-
 export class CreatePageDto {
   @IsOptional()
   @IsString()

apps/server/src/core/page/dto/page.dto.ts

@@ -8,7 +8,7 @@ import {
 } from 'class-validator';
 import { Transform } from 'class-transformer';
 
-import { PageReadFormat } from './create-page.dto';
+import { ContentFormat } from './create-page.dto';
 import { IsPageIdOrSlugId } from './page-identity.validator';
 
 export class PageIdDto {
@@ -43,8 +43,8 @@ export class PageInfoDto extends PageIdDto {
 
   @IsOptional()
   @Transform(({ value }) => value?.toLowerCase())
-  @IsIn(['json', 'markdown', 'html', 'text'])
-  format?: PageReadFormat;
+  @IsIn(['json', 'markdown', 'html'])
+  format?: ContentFormat;
 }
 
 export class DeletePageDto extends PageIdDto {

apps/server/src/core/page/page.controller.getpage-format.spec.ts

@@ -1,76 +0,0 @@
-import { NotFoundException } from '@nestjs/common';
-import { PageController } from './page.controller';
-import { jsonToText, jsonToMarkdown } from '../../collaboration/collaboration.util';
-
-// #502 READ: getPage `format:"text"` routes through the deterministic jsonToText
-// path (placeholders for non-text nodes, block-per-line), while `format:"json"`
-// (or none) returns the raw content and `format:"markdown"` still converts. This
-// pins the CONTROLLER wiring with lightweight mocks (no DB needed — the jsonToText
-// output contract itself is pinned in json-to-text-deterministic.spec.ts).
-
-const CONTENT = {
-  type: 'doc',
-  content: [
-    { type: 'heading', attrs: { level: 1 }, content: [{ type: 'text', text: 'Config' }] },
-    {
-      type: 'paragraph',
-      content: [
-        { type: 'text', text: 'key=', marks: [{ type: 'bold' }] },
-        { type: 'text', text: 'value' },
-      ],
-    },
-    { type: 'image', attrs: { src: 's' } },
-  ],
-};
-
-function makeController(page: any): PageController {
-  const pageRepo = { findById: jest.fn().mockResolvedValue(page) } as any;
-  const pageAccessService = {
-    validateCanViewWithPermissions: jest
-      .fn()
-      .mockResolvedValue({ canEdit: true, hasRestriction: false }),
-  } as any;
-  // Only pageRepo + pageAccessService are exercised by getPage; the rest are
-  // never touched on this path, so undefined placeholders are fine.
-  return new PageController(
-    undefined as any, // pageService
-    pageRepo,
-    undefined as any, // pageHistoryService
-    undefined as any, // spaceAbility
-    pageAccessService,
-    undefined as any, // backlinkService
-    undefined as any, // labelService
-    undefined as any, // auditService
-  );
-}
-
-const user = { id: 'u1' } as any;
-
-describe('PageController.getPage — format:"text" (#502)', () => {
-  it('returns deterministic flat text with placeholders for non-text nodes', async () => {
-    const controller = makeController({ id: 'p1', content: CONTENT });
-    const res: any = await controller.getPage({ pageId: 'p1', format: 'text' } as any, user);
-    expect(res.content).toBe(jsonToText(CONTENT, { deterministic: true }));
-    expect(res.content).toBe('Config\nkey=value\n[image]');
-    expect(res.permissions).toEqual({ canEdit: true, hasRestriction: false });
-  });
-
-  it('markdown format still converts to markdown (unchanged)', async () => {
-    const controller = makeController({ id: 'p1', content: CONTENT });
-    const res: any = await controller.getPage({ pageId: 'p1', format: 'markdown' } as any, user);
-    expect(res.content).toBe(jsonToMarkdown(CONTENT));
-  });
-
-  it('json / no format returns the raw ProseMirror content object', async () => {
-    const controller = makeController({ id: 'p1', content: CONTENT });
-    const res: any = await controller.getPage({ pageId: 'p1' } as any, user);
-    expect(res.content).toEqual(CONTENT); // untouched object, not a string
-  });
-
-  it('missing page -> NotFoundException', async () => {
-    const controller = makeController(null);
-    await expect(
-      controller.getPage({ pageId: 'nope', format: 'text' } as any, user),
-    ).rejects.toBeInstanceOf(NotFoundException);
-  });
-});

apps/server/src/core/page/page.controller.ts

@@ -49,7 +49,6 @@ import { AddLabelsDto, RemoveLabelDto } from '../label/dto/label.dto';
 import {
   jsonToHtml,
   jsonToMarkdown,
-  jsonToText,
 } from '../../collaboration/collaboration.util';
 import { AuditEvent, AuditResource } from '../../common/events/audit-events';
 import {
@@ -94,16 +93,10 @@ export class PageController {
     const permissions = { canEdit, hasRestriction };
 
     if (dto.format && dto.format !== 'json' && page.content) {
-      let contentOutput: string;
-      if (dto.format === 'markdown') {
-        contentOutput = jsonToMarkdown(page.content);
-      } else if (dto.format === 'text') {
-        // #502: flat, deterministic, machine-diffable text (block-per-line,
-        // inline marks/anchors dropped, non-text nodes -> stable placeholders).
-        contentOutput = jsonToText(page.content, { deterministic: true });
-      } else {
-        contentOutput = jsonToHtml(page.content);
-      }
+      const contentOutput =
+        dto.format === 'markdown'
+          ? jsonToMarkdown(page.content)
+          : jsonToHtml(page.content);
       return {
         ...page,
         content: contentOutput,

apps/server/src/integrations/import/import.controller.ts

@@ -85,14 +85,6 @@ export class ImportController {
       throw new BadRequestException('spaceId is required');
     }
 
-    // #502: optional multipart field. Only the MCP agent `createPage` path sends
-    // `disableMarkdownExtensions=true` (its body is agent-authored plain prose /
-    // config, so a `$…$` span must stay literal and a bare `www.host` must not
-    // autolink). A HUMAN file upload omits the field, so it stays false and math
-    // + autolink remain ON for human imports. Settable ONLY via this API param.
-    const disableMarkdownExtensions =
-      file.fields?.disableMarkdownExtensions?.value === 'true';
-
     const ability = await this.spaceAbility.createForUser(user, spaceId);
     if (ability.cannot(SpaceCaslAction.Edit, SpaceCaslSubject.Page)) {
       throw new ForbiddenException();
@@ -103,7 +95,6 @@ export class ImportController {
       user.id,
       spaceId,
       workspace.id,
-      disableMarkdownExtensions,
     );
 
     const ext = path.extname(file.filename).toLowerCase();

apps/server/src/integrations/import/services/import.service.processMarkdown.spec.ts

@@ -1,67 +0,0 @@
-// Importing ImportService transitively loads import-formatter.ts, which imports
-// the ESM-only @sindresorhus/slugify (not in jest's transform allowlist). It is
-// irrelevant to this path, so mock it to keep the module graph loadable (mirrors
-// the sibling import.service specs).
-jest.mock('@sindresorhus/slugify', () => ({
-  __esModule: true,
-  default: (input: string) => String(input),
-}));
-
-import { ImportService } from './import.service';
-
-// #502 BLOCKER 1: the server markdown import path (`/pages/import`) now accepts an
-// optional `disableMarkdownExtensions` flag threaded into `processMarkdown`.
-//   - MCP agent `createPage` sends it TRUE  -> extensions OFF (a `$…$` config span
-//     stays literal, a schemeless `www.host` is not autolinked).
-//   - a HUMAN file upload omits it (default FALSE) -> extensions ON, so a real
-//     `$x^2$` still becomes a formula (human imports unaffected).
-// `processMarkdown` only uses the imported converter (no injected deps on this
-// path), so the service is constructed with null deps for this focused unit test.
-
-function makeService(): ImportService {
-  return new ImportService(null as any, null as any, null as any, null as any);
-}
-
-function findAll(node: any, type: string, acc: any[] = []): any[] {
-  if (!node || typeof node !== 'object') return acc;
-  if (node.type === type) acc.push(node);
-  if (Array.isArray(node.content)) for (const c of node.content) findAll(c, type, acc);
-  return acc;
-}
-function hasLink(node: any): boolean {
-  return findAll(node, 'text').some((t: any) =>
-    t.marks?.some((m: any) => m.type === 'link'),
-  );
-}
-
-describe('ImportService.processMarkdown — #502 disableMarkdownExtensions', () => {
-  it('disableMarkdownExtensions=true (MCP createPage): `$…$` stays literal, no math', async () => {
-    const svc = makeService();
-    const doc = await svc.processMarkdown('export A=$FOO and B=$BAR done', true);
-    expect(findAll(doc, 'mathInline')).toHaveLength(0);
-  });
-
-  it('disableMarkdownExtensions=true: a schemeless www is NOT autolinked', async () => {
-    const svc = makeService();
-    const doc = await svc.processMarkdown('see www.example.com here', true);
-    expect(hasLink(doc)).toBe(false);
-  });
-
-  it('disableMarkdownExtensions=true: an explicit https:// STILL links', async () => {
-    const svc = makeService();
-    const doc = await svc.processMarkdown('see https://example.com here', true);
-    expect(hasLink(doc)).toBe(true);
-  });
-
-  it('DEFAULT (human upload): a real `$x^2$` DOES become a math node', async () => {
-    const svc = makeService();
-    const doc = await svc.processMarkdown('$x^2$');
-    expect(findAll(doc, 'mathInline')).toHaveLength(1);
-  });
-
-  it('DEFAULT (human upload): a schemeless www IS autolinked', async () => {
-    const svc = makeService();
-    const doc = await svc.processMarkdown('see www.example.com here');
-    expect(hasLink(doc)).toBe(true);
-  });
-});

apps/server/src/integrations/import/services/import.service.ts

@@ -52,12 +52,6 @@ export class ImportService {
     userId: string,
     spaceId: string,
     workspaceId: string,
-    // #502: when true, the markdown importer runs with the two layered
-    // extensions OFF (a `$…$` span stays literal text; a schemeless `www.host` is
-    // NOT autolinked). ONLY the MCP agent `createPage` path sets this; a HUMAN
-    // file upload never passes it, so it defaults false and math/autolink stay ON
-    // for human imports (their `$x^2$` still becomes a formula).
-    disableMarkdownExtensions = false,
   ) {
     const file = await filePromise;
     const fileBuffer = await file.toBuffer();
@@ -72,10 +66,7 @@ export class ImportService {
 
     try {
       if (fileExtension.endsWith('.md')) {
-        prosemirrorState = await this.processMarkdown(
-          fileContent,
-          disableMarkdownExtensions,
-        );
+        prosemirrorState = await this.processMarkdown(fileContent);
       } else if (fileExtension.endsWith('.html')) {
         prosemirrorState = await this.processHTML(fileContent);
       }
@@ -147,12 +138,7 @@ export class ImportService {
     return createdPage;
   }
 
-  async processMarkdown(
-    markdownInput: string,
-    // #502: forwarded to the importer. DEFAULT false keeps math + fuzzy autolink
-    // ON (human uploads unaffected); the MCP agent `createPage` path passes true.
-    disableMarkdownExtensions = false,
-  ): Promise<any> {
+  async processMarkdown(markdownInput: string): Promise<any> {
     // Canonical markdown -> ProseMirror JSON directly via
     // `@docmost/prosemirror-markdown` (issue #345) — no HTML intermediate and no
     // second editor-ext markdown layer. Foreign markdown surfaces the strict
@@ -161,12 +147,7 @@ export class ImportService {
     // The HTML-cleanup pass (`normalizeImportHtml`) is intentionally skipped here:
     // it targets foreign *HTML* (Notion/XWiki), which only ever arrives on the
     // `.html` path (`processHTML`), never as canonical markdown.
-    return markdownToProseMirror(
-      normalizeForeignMarkdown(markdownInput),
-      disableMarkdownExtensions
-        ? { parseMath: false, fuzzyLinkify: false }
-        : undefined,
-    );
+    return markdownToProseMirror(normalizeForeignMarkdown(markdownInput));
   }
 
   async processHTML(htmlInput: string): Promise<any> {

apps/server/src/integrations/static/static.module.ts

@@ -4,6 +4,7 @@ import { join } from 'path';
 import * as fs from 'node:fs';
 import fastifyStatic from '@fastify/static';
 import { EnvironmentService } from '../environment/environment.service';
+import { resolveClientDistPath } from '../../common/helpers/client-version';
 
 /**
  * Resolve the response headers for a statically served client asset.
@@ -56,14 +57,7 @@ export class StaticModule implements OnModuleInit {
     const httpAdapter = this.httpAdapterHost.httpAdapter;
     const app = httpAdapter.getInstance();
 
-    const clientDistPath = join(
-      __dirname,
-      '..',
-      '..',
-      '..',
-      '..',
-      'client/dist',
-    );
+    const clientDistPath = resolveClientDistPath();
 
     const indexFilePath = join(clientDistPath, 'index.html');
 

apps/server/src/ws/ws.gateway.ts

@@ -9,10 +9,14 @@ import {
 import { Server, Socket } from 'socket.io';
 import { TokenService } from '../core/auth/services/token.service';
 import { JwtPayload, JwtType } from '../core/auth/dto/jwt-payload';
-import { OnModuleDestroy } from '@nestjs/common';
+import { Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
 import { SpaceMemberRepo } from '@docmost/db/repos/space/space-member.repo';
 import { WsService } from './ws.service';
 import { getSpaceRoomName, getUserRoomName } from './ws.utils';
+import {
+  readClientBuildVersion,
+  resolveClientDistPath,
+} from '../common/helpers/client-version';
 import * as cookie from 'cookie';
 
 @WebSocketGateway({
@@ -20,17 +24,40 @@ import * as cookie from 'cookie';
   transports: ['websocket'],
 })
 export class WsGateway
-  implements OnGatewayConnection, OnGatewayInit, OnModuleDestroy
+  implements
+    OnGatewayConnection,
+    OnGatewayInit,
+    OnModuleInit,
+    OnModuleDestroy
 {
   @WebSocketServer()
   server: Server;
 
+  private readonly logger = new Logger(WsGateway.name);
+
+  // The build version of the client bundle shipped in this image, read once at
+  // startup from client/dist/version.json (single source of truth, same value
+  // baked into the client's APP_VERSION). Empty string => version.json missing
+  // or empty => the proactive version-coherence reload feature stays inert.
+  private appVersion = '';
+
   constructor(
     private tokenService: TokenService,
     private spaceMemberRepo: SpaceMemberRepo,
     private wsService: WsService,
   ) {}
 
+  onModuleInit(): void {
+    this.appVersion = readClientBuildVersion(resolveClientDistPath());
+    if (this.appVersion) {
+      this.logger.log(`app-version reload: ACTIVE (v=${this.appVersion})`);
+    } else {
+      this.logger.log(
+        'app-version reload: DISABLED (version.json missing/empty)',
+      );
+    }
+  }
+
   afterInit(server: Server): void {
     this.wsService.setServer(server);
   }
@@ -55,6 +82,14 @@ export class WsGateway
       const spaceRooms = userSpaceIds.map((id) => getSpaceRoomName(id));
 
       client.join([userRoom, workspaceRoom, ...spaceRooms]);
+
+      // Announce this container's client build version to the freshly
+      // authenticated socket. On a redeploy the client reconnects to the new
+      // container and receives the new version here, letting it guard-reload
+      // before it hits a stale lazy chunk. Per-connect only (no broadcast):
+      // natural reconnect covers both single-container and cluster without a
+      // thundering-herd fleet reload.
+      client.emit('app-version', { version: this.appVersion });
     } catch (err) {
       client.emit('Unauthorized');
       client.disconnect();

packages/mcp/README.md

@@ -118,10 +118,7 @@ All 41 tools, grouped by what you'd reach for them.
 - **`getPage`** — A page's content as clean **Markdown** (canonical for text; drops only
   block ids, resolved-comment anchors, and a fixed no-Markdown-representation attr set —
   table spans/colwidth/background, indent, `callout.icon`, `orderedList.type`, and link
-  `internal`/`target`/`rel`/`class`; use `getPageJson` when you need those). Pass
-  `format:"text"` for a flat, deterministic plain-text rendering (one line per block,
-  marks dropped, stable `[image]`/`[table RxC]` placeholders) to machine-diff what you
-  wrote against what was stored.
+  `internal`/`target`/`rel`/`class`; use `getPageJson` when you need those).
 - **`getPageJson`** — A page's **lossless ProseMirror/TipTap JSON**, including every
   block's `attrs.id` and the `slugId` used in URLs. This is what the per-block editing
   tools consume.

packages/mcp/README.ru.md

@@ -123,10 +123,7 @@ Docmost-MCP не сочетают:
   лишь id блоков, якоря разрешённых комментариев и фиксированный набор атрибутов без
   markdown-представления — спаны/colwidth/фон ячеек таблиц, отступы (indent),
   `callout.icon`, `orderedList.type` и `internal`/`target`/`rel`/`class` у ссылок;
-  используйте `getPageJson`, когда они нужны). Передайте `format:"text"` для плоского
-  детерминированного plain-text рендера (одна строка на блок, маркировка убрана,
-  стабильные плейсхолдеры `[image]`/`[table RxC]`) — чтобы machine-diff'ом сверить то,
-  что вы записали, с тем, что сохранилось.
+  используйте `getPageJson`, когда они нужны).
 - **`getPageJson`** — **Lossless ProseMirror/TipTap JSON** страницы, включая `attrs.id`
   каждого блока и `slugId`, используемый в URL. Именно его потребляют инструменты
   поблочного редактирования.

packages/mcp/src/client/context.ts

@@ -701,20 +701,10 @@ export abstract class DocmostClientContext {
   }
 
 
-  /**
-   * Raw page info including the ProseMirror JSON content and slugId.
-   *
-   * With `format:"text"` (#502) the server instead renders `content` as a flat,
-   * deterministic text string (its `jsonToText` path — the SAME serializer that
-   * feeds search), so the MCP text read reuses the server's ONE serializer
-   * rather than shipping a second one. Every other caller omits `format` and
-   * gets the JSON content unchanged.
-   */
-  async getPageRaw(pageId: string, format?: "text") {
+  /** Raw page info including the ProseMirror JSON content and slugId. */
+  async getPageRaw(pageId: string) {
     await this.ensureAuthenticated();
-    const body: Record<string, unknown> = { pageId };
-    if (format) body.format = format;
-    const response = await this.client.post("/pages/info", body);
+    const response = await this.client.post("/pages/info", { pageId });
     return response.data?.data ?? response.data;
   }
 

packages/mcp/src/client/pages.ts

@@ -93,13 +93,6 @@ export function PagesMixin<TBase extends GConstructor<DocmostClientContext>>(Bas
     const buildForm = () => {
       const form = new FormData();
       form.append("spaceId", spaceId);
-      // #502: this is an AGENT-authored body (plain prose / config), so tell the
-      // server import path to run the markdown importer with the two layered
-      // extensions OFF — a `$…$` span stays literal text (real math via
-      // `update_page_json`) and a schemeless `www.host`/email is not autolinked
-      // (an explicit `https://…` still links). A human file upload never sends
-      // this field, so human imports keep math + autolink ON.
-      form.append("disableMarkdownExtensions", "true");
       form.append("file", fileContent, {
         filename: `${title || "import"}.md`,
         contentType: "text/markdown",

packages/mcp/src/client/read.ts

@@ -72,7 +72,7 @@ export interface IReadMixin {
   getTree(spaceId: string, rootPageId?: string, maxDepth?: number): any;
   getPageContext(pageId: string): any;
   listSidebarPages(spaceId: string, pageId?: string): any;
-  getPage(pageId: string, format?: "markdown" | "text"): any;
+  getPage(pageId: string): any;
   getPageJson(pageId: string): any;
   getOutline(pageId: string): any;
   getNode(pageId: string, nodeId: string, format?: "markdown" | "json"): any;
@@ -420,34 +420,8 @@ export function ReadMixin<TBase extends GConstructor<DocmostClientContext>>(Base
     return convertProseMirrorToMarkdown(content, options);
   }
 
-  async getPage(pageId: string, format: "markdown" | "text" = "markdown") {
+  async getPage(pageId: string) {
     await this.ensureAuthenticated();
-
-    // #502 `format:"text"`: a flat, deterministic, machine-diffable rendering
-    // (block-per-line, inline marks/comment anchors dropped, non-text nodes ->
-    // stable placeholders like `[image]` / `[table RxC]`). The server produces
-    // it via its `jsonToText` path (the SAME serializer that feeds search), so
-    // there is no second serializer here — we just request it and pass the
-    // string through. Distinct from the markdown default: no PM->markdown walk,
-    // no markdown conversion cache, and no `{{SUBPAGES}}` substitution (the text
-    // renderer emits no such placeholder). Use it to diff a page you wrote as a
-    // config/prose against what was stored.
-    if (format === "text") {
-      const textData = await this.getPageRaw(pageId, "text");
-      let subpages: any[] = [];
-      try {
-        subpages = await this.listSidebarPages(textData.spaceId, textData.id);
-      } catch (e: any) {
-        console.warn("Failed to fetch subpages:", e);
-      }
-      const textContent =
-        typeof textData.content === "string" ? textData.content : "";
-      return {
-        data: filterPage(textData, textContent, subpages),
-        success: true,
-      };
-    }
-
     const resultData = await this.getPageRaw(pageId);
 
     // Agent read: hide resolved-comment anchors so the agent sees only active

packages/mcp/src/lib/collaboration.ts

@@ -14,7 +14,6 @@ import {
   markdownToProseMirror,
   normalizeAgentMarkdown,
 } from "@docmost/prosemirror-markdown";
-import type { MarkdownImportOptions } from "@docmost/prosemirror-markdown";
 import { docmostExtensions, docmostSchema } from "./docmost-schema.js";
 import { withPageLock } from "./page-lock.js";
 import type { PageId } from "./page-id.js";
@@ -112,31 +111,16 @@ global.WebSocket = WebSocket;
  * horizontalRule the serializer emitted, and stripping it would silently drop the
  * page's leading content (#493 review). The front-matter strip stays on the
  * server FILE-import boundary only (`normalizeForeignMarkdown`).
- *
- * #502 IMPORTANT — the two layered markdown extensions (`$…$` math, schemeless
- * fuzzy autolink) are NOT decided here; they are the CALLER's choice via
- * `options`, because the two callers of this wrapper need OPPOSITE behavior:
- *   - AGENT-authored plain markdown (`updatePageMarkdown`) → both OFF, so a
- *     `$…$` config span stays literal and a bare `www.host` is not autolinked
- *     (real math is authored via `update_page_json`).
- *   - FULL-FILE round-trip import (`import_page_markdown`, #328 lossless) →
- *     DEFAULTS (both ON), because the exporter serializes a math node as readable
- *     `$x^2$`; re-importing with math OFF would degrade it to literal text and
- *     BREAK the lossless export→import pair.
- * So `options` DEFAULTS to `undefined` → the package importer's defaults (ON),
- * which is the safe round-trip behavior; the agent-write caller opts OUT
- * explicitly. (The fragment path `importMarkdownFragment` opts out on its own.)
  */
 export async function markdownToProseMirrorCanonical(
   markdownContent: string,
-  options?: MarkdownImportOptions,
 ): Promise<any> {
   // #419: normalize + merge glyph-forked footnote definitions BEFORE
   // canonicalizing, so the canonicalizer re-hangs references and drops the
   // now-orphaned duplicate definitions.
   return canonicalizeFootnotes(
     normalizeAndMergeFootnotes(
-      await markdownToProseMirror(normalizeAgentMarkdown(markdownContent), options),
+      await markdownToProseMirror(normalizeAgentMarkdown(markdownContent)),
     ),
   );
 }
@@ -374,17 +358,7 @@ export async function updatePageContentRealtime(
 ): Promise<MutationResult> {
   // PAGE write: canonicalize footnotes (markdown import builds the bottom list in
   // definition order; numbering is reference-ordered).
-  //
-  // #502: this is the AGENT-authored `updatePageMarkdown` body — plain prose /
-  // config — so the two layered markdown extensions are turned OFF: a `$…$` span
-  // stays literal text (real math via `update_page_json`) and a SCHEMELESS
-  // `www.host`/email is not autolinked (an explicit `https://…` still links).
-  // Contrast `import_page_markdown`, which keeps DEFAULTS for the #328 lossless
-  // round-trip.
-  const tiptapJson = await markdownToProseMirrorCanonical(markdownContent, {
-    parseMath: false,
-    fuzzyLinkify: false,
-  });
+  const tiptapJson = await markdownToProseMirrorCanonical(markdownContent);
   return await mutatePageContent(
     pageId,
     collabToken,

packages/mcp/src/lib/markdown-fragment.ts

@@ -135,17 +135,7 @@ export interface MarkdownFragment {
 export async function importMarkdownFragment(
   markdown: string,
 ): Promise<MarkdownFragment> {
-  // #502: the fragment path is an MCP agent WRITE (patch_node/insert_node
-  // markdown), so it uses the SAME extensions-OFF importer options as the
-  // full-page write (markdownToProseMirrorCanonical): a `$…$` span stays literal
-  // and a schemeless domain/email is not autolinked. This keeps a block written
-  // via markdown canonically identical to the same content in a full-page write
-  // (no "second canon"). Explicit `https://…` links and block structure are
-  // unaffected.
-  const doc = await markdownToProseMirror(markdown, {
-    parseMath: false,
-    fuzzyLinkify: false,
-  });
+  const doc = await markdownToProseMirror(markdown);
   const content: any[] = Array.isArray(doc?.content) ? doc.content : [];
 
   const blocks: any[] = [];

packages/mcp/src/tool-specs.ts

@@ -469,11 +469,7 @@ export const SHARED_TOOL_SPECS = {
       '(markdown). The fragment may be SEVERAL blocks (a "1 → N" splice: rewrite a ' +
       'whole section in one call) — the first block inherits this block id, the ' +
       'rest get fresh ids. `^[...]` footnotes are supported (their definitions ' +
-      "merge into the page's footnote list). Markdown is taken LITERALLY — " +
-      '`$...$`/`$$...$$` are NOT parsed as math and schemeless `www.host` / bare ' +
-      'emails are NOT auto-linked (an explicit `https://` URL still links); for a ' +
-      'real formula pass a `mathInline`/`mathBlock` ProseMirror node via `node` ' +
-      '(or updatePageJson). REJECTED when the target is a table ' +
+      "merge into the page's footnote list). REJECTED when the target is a table " +
       'cell with attributes markdown cannot represent (merged/colored/fixed-width) ' +
       '— use the table tools or `node`. ' +
       '`node` (for precise attr/mark work): a raw ProseMirror node, e.g. a ' +
@@ -539,10 +535,6 @@ export const SHARED_TOOL_SPECS = {
       'Provide EXACTLY ONE of `markdown` or `node`. ' +
       '`markdown` (RECOMMENDED): a canonical markdown fragment — may be SEVERAL ' +
       'blocks, inserted in order at the anchor; `^[...]` footnotes supported. ' +
-      'Markdown is taken LITERALLY — `$...$`/`$$...$$` are NOT parsed as math and ' +
-      'schemeless `www.host` / bare emails are NOT auto-linked (an explicit ' +
-      '`https://` URL still links); for a real formula pass a ' +
-      '`mathInline`/`mathBlock` ProseMirror node via `node` (or updatePageJson). ' +
       '`node` (for precise attr/mark work OR table structure): a raw ProseMirror ' +
       'node. Table structure is JSON-only (not expressible in markdown): to add a ' +
       'tableRow, pass a tableRow node with position before/after and anchor INSIDE ' +
@@ -921,46 +913,28 @@ export const SHARED_TOOL_SPECS = {
     inAppKey: 'getPage',
     writeClass: 'readOnly',
     description:
-      'Fetch a single page by its id. Returns the page title and its content. ' +
-      'format:"markdown" (DEFAULT) returns canonical Markdown (round-trips text ' +
-      'and block structure), sufficient for text edits; use the page-JSON read ' +
-      'tool only when you need what Markdown cannot carry. The Markdown drops ' +
-      'exactly: (1) block ids (not visible in Markdown); (2) resolved-comment ' +
-      'anchors (hidden here; only active <span data-comment-id> anchors remain); ' +
-      '(3) a fixed set of attributes with no Markdown representation — table-cell ' +
-      'colspan/rowspan/colwidth/backgroundColor/backgroundColorName, ' +
-      'heading/paragraph indent, callout.icon, orderedList.type, and link ' +
-      'internal/target/rel/class. Inline <span data-comment-id> tags in the ' +
-      'markdown are comment highlight anchors — treat them as markup, not page ' +
-      'text. format:"text" returns a FLAT, DETERMINISTIC plain-text rendering ' +
-      'for machine diffing: one line per block, ALL inline marks/formatting and ' +
-      'comment anchors dropped, a hardBreak is a newline, and non-text nodes ' +
-      'become STABLE placeholders — an image is "[image]" and a table is ' +
-      '"[table RxC]" (R rows x C columns). This output is stable across versions ' +
-      '(pinned by a snapshot test); use it to diff a config/prose you wrote ' +
-      'against what was stored (an empty diff means it was stored verbatim).',
+      'Fetch a single page as Markdown by its id. Returns the page title and ' +
+      'its Markdown content. The converter is canonical (round-trips text and ' +
+      'block structure), so this is sufficient for text edits; use the ' +
+      'page-JSON read tool only when you need what Markdown cannot carry. The ' +
+      'Markdown drops exactly: (1) block ids (not visible in Markdown); ' +
+      '(2) resolved-comment anchors (hidden here; only active <span ' +
+      'data-comment-id> anchors remain); (3) a fixed set of attributes with no ' +
+      'Markdown representation — table-cell colspan/rowspan/colwidth/' +
+      'backgroundColor/backgroundColorName, heading/paragraph indent, ' +
+      'callout.icon, orderedList.type, and link internal/target/rel/class. ' +
+      'Inline <span data-comment-id> tags in the markdown are comment highlight ' +
+      'anchors — treat them as markup, not page text.',
     tier: 'core',
-    catalogLine:
-      'getPage — fetch a page by its id (format:"markdown" default, or "text" for a flat machine-diffable read).',
+    catalogLine: 'getPage — fetch a page as Markdown by its id.',
     // Reconciled: MCP's stricter .min(1) kept; in-app's more-informative
     // "(or slugId)" describe kept.
     buildShape: (z) => ({
       pageId: z.string().min(1).describe('The id (or slugId) of the page.'),
-      format: z
-        .enum(['markdown', 'text'])
-        .optional()
-        .describe(
-          'Output format: "markdown" (default, canonical round-trippable) or ' +
-            '"text" (flat deterministic plain text for machine diffing).',
-        ),
     }),
     // MCP wraps the raw `{ data, success }` as JSON. The in-app host instead
     // projects a token-efficient `{ title, markdown }` (its long-standing shape).
-    execute: (client, { pageId, format }) =>
-      client.getPage(
-        pageId as string,
-        (format as 'markdown' | 'text' | undefined) ?? 'markdown',
-      ),
+    execute: (client, { pageId }) => client.getPage(pageId as string),
     inAppExecute: async (client, { pageId }) => {
       // getPage(pageId) -> { data: filterPage(page, markdown), success }.
       const result = (await client.getPage(pageId as string)) as {
@@ -1103,12 +1077,8 @@ export const SHARED_TOOL_SPECS = {
     description:
       'Create a new page with a Markdown body in a space, optionally under a ' +
       'parent page (omit parentPageId to create at the space root). Returns ' +
-      'the new page id and title. Body text is taken LITERALLY — ' +
-      '`$...$`/`$$...$$` are NOT parsed into a math formula and schemeless ' +
-      '`www.host` / bare emails are NOT auto-linked (an explicit `https://` URL ' +
-      'still links); for a real formula use updatePageJson with ' +
-      '`mathInline`/`mathBlock` nodes instead. Reversible: a page can be moved ' +
-      'to trash later.',
+      'the new page id and title. Reversible: a page can be moved to trash ' +
+      'later.',
     tier: 'deferred',
     catalogLine: 'createPage — create a new page with a Markdown body in a space.',
     // Reconciled schema DRIFT: the MCP copy pinned `content` to .min(1) while
@@ -1367,11 +1337,7 @@ export const SHARED_TOOL_SPECS = {
       'title). The whole body is re-imported from the markdown (block ids ' +
       'regenerate — for surgical or id-preserving edits use the find/replace, ' +
       'node-patch or page-JSON tools instead). Docmost-flavoured markdown is ' +
-      'parsed, including `^[...]` inline footnotes. Text is taken LITERALLY — ' +
-      '`$...$`/`$$...$$` are NOT parsed into a math formula and schemeless ' +
-      '`www.host` / bare emails are NOT auto-linked (an explicit `https://` URL ' +
-      'still links); for a real formula use updatePageJson with ' +
-      '`mathInline`/`mathBlock` nodes instead. Reversible: the previous ' +
+      'parsed, including `^[...]` inline footnotes. Reversible: the previous ' +
       'version is kept in page history.',
     tier: 'deferred',
     catalogLine:

packages/mcp/test/mock/createpage-import-flag.test.mjs

@@ -1,83 +0,0 @@
-// #502 BLOCKER 1 (client half): the MCP `createPage` tool builds its body as an
-// AGENT-authored markdown file and POSTs it to the server `/pages/import`
-// endpoint. It must send the `disableMarkdownExtensions=true` multipart field so
-// the SERVER importer runs with math + fuzzy-autolink OFF (a human file upload
-// omits the field and keeps them ON). This mock http server captures the raw
-// multipart body and asserts the field is present.
-import { test, after } from "node:test";
-import assert from "node:assert/strict";
-import http from "node:http";
-import { DocmostClient } from "../../build/client.js";
-
-function sendJson(res, status, obj, extra = {}) {
-  res.writeHead(status, { "Content-Type": "application/json", ...extra });
-  res.end(JSON.stringify(obj));
-}
-function readRaw(req) {
-  return new Promise((resolve) => {
-    const chunks = [];
-    req.on("data", (c) => chunks.push(c));
-    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
-  });
-}
-
-const openServers = [];
-after(async () => {
-  await Promise.all(openServers.map((s) => new Promise((r) => s.close(r))));
-});
-
-const NEW_ID = "00000000-0000-4000-8000-000000000042";
-const SPACE = "00000000-0000-4000-8000-0000000000aa";
-
-function spawn(state) {
-  return new Promise((resolve) => {
-    const server = http.createServer(async (req, res) => {
-      const raw = await readRaw(req);
-      if (req.url === "/api/auth/login") {
-        return sendJson(res, 200, { success: true }, { "Set-Cookie": "authToken=t; Path=/; HttpOnly" });
-      }
-      if (req.url === "/api/pages/import") {
-        state.importBody = raw; // the raw multipart payload
-        return sendJson(res, 200, { data: { id: NEW_ID } });
-      }
-      if (req.url === "/api/pages/update") {
-        return sendJson(res, 200, { data: { id: NEW_ID } });
-      }
-      if (req.url === "/api/pages/info") {
-        return sendJson(res, 200, {
-          data: {
-            id: NEW_ID,
-            slugId: "slugnew1234",
-            title: "T",
-            spaceId: SPACE,
-            updatedAt: "2026-01-01T00:00:00Z",
-            content: { type: "doc", content: [{ type: "paragraph", content: [{ type: "text", text: "x" }] }] },
-          },
-        });
-      }
-      if (req.url === "/api/pages/sidebar-pages") {
-        return sendJson(res, 200, { data: { items: [], meta: { hasNextPage: false, nextCursor: null } } });
-      }
-      return sendJson(res, 404, { message: "not found" });
-    });
-    server.listen(0, "127.0.0.1", () => {
-      openServers.push(server);
-      resolve(`http://127.0.0.1:${server.address().port}/api`);
-    });
-  });
-}
-
-test("createPage sends disableMarkdownExtensions=true in the /pages/import multipart", async () => {
-  const state = {};
-  const baseURL = await spawn(state);
-  const client = new DocmostClient(baseURL, "e@x.com", "pw");
-
-  await client.createPage("My Config", "ticket $x=1$ at www.host.com", SPACE);
-
-  assert.ok(state.importBody, "the import endpoint received a body");
-  // The multipart payload carries the field name and its "true" value.
-  assert.match(state.importBody, /name="disableMarkdownExtensions"/);
-  assert.match(state.importBody, /name="disableMarkdownExtensions"[\s\S]*?\r?\n\r?\ntrue\r?\n/);
-  // The agent body itself is still sent as the file part.
-  assert.match(state.importBody, /ticket \$x=1\$ at www\.host\.com/);
-});

packages/mcp/test/mock/getpage-text-format.test.mjs

@@ -1,116 +0,0 @@
-// #502 READ: the getPage tool gains a `format:"text"` mode. It requests the
-// server's flat, deterministic text rendering (the server's jsonToText path — the
-// SAME serializer that feeds search), passing it through unchanged. This mock
-// stands up a local http server (same harness style as getpage-conversion-cache)
-// and asserts end-to-end that:
-//   - format:"text" sends `format:"text"` in the /pages/info body and returns the
-//     server's text string verbatim (no client-side markdown conversion);
-//   - the DEFAULT (no format) still returns markdown-converted content;
-//   - the text read resolves page + subpages like the markdown read.
-import { test, after } from "node:test";
-import assert from "node:assert/strict";
-import http from "node:http";
-import { DocmostClient } from "../../build/client.js";
-
-function readBody(req) {
-  return new Promise((resolve) => {
-    let raw = "";
-    req.on("data", (c) => (raw += c));
-    req.on("end", () => resolve(raw));
-  });
-}
-function sendJson(res, status, obj, extra = {}) {
-  res.writeHead(status, { "Content-Type": "application/json", ...extra });
-  res.end(JSON.stringify(obj));
-}
-
-const openServers = [];
-after(async () => {
-  await Promise.all(openServers.map((s) => new Promise((r) => s.close(r))));
-});
-
-const PAGE_UUID = "00000000-0000-4000-8000-000000000010";
-const SPACE_UUID = "00000000-0000-4000-8000-0000000000aa";
-const CHILD_UUID = "00000000-0000-4000-8000-0000000000bb";
-
-// The deterministic text the SERVER's jsonToText would produce for this page.
-const SERVER_TEXT = "Title line\nsecond block\n[image]\n[table 2x3]";
-
-function makeDoc(text) {
-  return { type: "doc", content: [{ type: "paragraph", content: [{ type: "text", text }] }] };
-}
-
-function spawn(state) {
-  return new Promise((resolve) => {
-    const server = http.createServer(async (req, res) => {
-      const body = await readBody(req);
-      if (req.url === "/api/auth/login") {
-        return sendJson(res, 200, { success: true }, { "Set-Cookie": "authToken=t; Path=/; HttpOnly" });
-      }
-      if (req.url === "/api/pages/info") {
-        const parsed = body ? JSON.parse(body) : {};
-        state.lastInfoBody = parsed;
-        // Emulate the server: when format:"text" is requested, `content` is the
-        // flat text string; otherwise it is the raw ProseMirror JSON.
-        const content = parsed.format === "text" ? SERVER_TEXT : makeDoc("Title line");
-        return sendJson(res, 200, {
-          success: true,
-          data: {
-            id: PAGE_UUID,
-            slugId: "slug123456",
-            title: "Text Page",
-            parentPageId: null,
-            spaceId: SPACE_UUID,
-            updatedAt: "2026-01-01T00:00:00Z",
-            content,
-          },
-        });
-      }
-      if (req.url === "/api/pages/sidebar-pages") {
-        return sendJson(res, 200, {
-          success: true,
-          data: {
-            items: [{ id: CHILD_UUID, title: "Child", hasChildren: false }],
-            meta: { hasNextPage: false, nextCursor: null },
-          },
-        });
-      }
-      return sendJson(res, 404, { message: "not found" });
-    });
-    server.listen(0, "127.0.0.1", () => {
-      openServers.push(server);
-      resolve(`http://127.0.0.1:${server.address().port}/api`);
-    });
-  });
-}
-
-function makeClient(baseURL) {
-  return new DocmostClient({ apiUrl: baseURL, getToken: async () => "access" });
-}
-
-test('getPage(format:"text") requests text and returns the server text verbatim', async () => {
-  const state = {};
-  const client = makeClient(await spawn(state));
-
-  const result = await client.getPage(PAGE_UUID, "text");
-  assert.equal(state.lastInfoBody.format, "text", "the info request carried format:text");
-  assert.equal(result.success, true);
-  assert.equal(result.data.content, SERVER_TEXT, "returns the server's flat text unchanged");
-  // Deterministic placeholders are surfaced to the agent.
-  assert.ok(result.data.content.includes("[image]"));
-  assert.ok(result.data.content.includes("[table 2x3]"));
-  // No client-side markdown artifacts leaked in.
-  assert.ok(!result.data.content.includes("{{SUBPAGES}}"));
-  // Subpages still resolve for context.
-  assert.deepEqual(result.data.subpages, [{ id: CHILD_UUID, title: "Child" }]);
-});
-
-test('getPage default (no format) still returns markdown, not text', async () => {
-  const state = {};
-  const client = makeClient(await spawn(state));
-
-  const result = await client.getPage(PAGE_UUID);
-  assert.equal(state.lastInfoBody.format, undefined, "default read sends no format");
-  assert.ok(result.data.content.includes("Title line"), "markdown content converted client-side");
-  assert.notEqual(result.data.content, SERVER_TEXT);
-});

packages/mcp/test/mock/write-path-extensions-wiring.test.mjs

@@ -1,181 +0,0 @@
-// #502 caller-WIRING: end-to-end through a live Hocuspocus collab stack (same
-// harness style as markdown-patch-insert), driving the REAL client methods and
-// reading the persisted document back, so the test proves each write tool passes
-// the RIGHT importer options — not just that the shared wrapper can:
-//   - updatePageMarkdown (client.updatePage)      -> extensions OFF  (`$…$` literal, www not linked)
-//   - import_page_markdown (client.importPageMarkdown) -> DEFAULTS   (`$x^2$` -> math node, #328)
-// Mutating either caller's option flips the matching assertion (see the coder's
-// mutation note), so this file guards the wiring, not only the wrapper.
-import { test, after } from "node:test";
-import assert from "node:assert/strict";
-import http from "node:http";
-import { WebSocketServer } from "ws";
-import { Hocuspocus } from "@hocuspocus/server";
-import { DocmostClient } from "../../build/client.js";
-import { buildYDoc } from "../../build/lib/collaboration.js";
-import { serializeDocmostMarkdown } from "@docmost/prosemirror-markdown";
-
-const PAGE = "11111111-1111-4111-8111-111111111111";
-
-function findAll(node, type, acc = []) {
-  if (!node || typeof node !== "object") return acc;
-  if (node.type === type) acc.push(node);
-  if (Array.isArray(node.content)) for (const c of node.content) findAll(c, type, acc);
-  return acc;
-}
-function allText(node, acc = []) {
-  if (!node || typeof node !== "object") return acc.join("");
-  if (node.type === "text" && typeof node.text === "string") acc.push(node.text);
-  if (Array.isArray(node.content)) for (const c of node.content) allText(c, acc);
-  return acc.join("");
-}
-function hasLink(node) {
-  return findAll(node, "text").some((t) => t.marks?.some((m) => m.type === "link"));
-}
-
-function fragmentToJson(frag) {
-  const decodeNode = (el) => {
-    if (el.constructor.name === "YXmlText") {
-      const delta = el.toDelta();
-      return delta.map((d) => {
-        const node = { type: "text", text: d.insert };
-        if (d.attributes && Object.keys(d.attributes).length) {
-          node.marks = Object.entries(d.attributes).map(([type, attrs]) =>
-            attrs && typeof attrs === "object" && Object.keys(attrs).length
-              ? { type, attrs }
-              : { type },
-          );
-        }
-        return node;
-      });
-    }
-    const node = { type: el.nodeName };
-    const attrs = el.getAttributes();
-    if (attrs && Object.keys(attrs).length) node.attrs = attrs;
-    const children = [];
-    for (const child of el.toArray()) {
-      const decoded = decodeNode(child);
-      if (Array.isArray(decoded)) children.push(...decoded);
-      else children.push(decoded);
-    }
-    if (children.length) node.content = children;
-    return node;
-  };
-  const content = [];
-  for (const child of frag.toArray()) content.push(decodeNode(child));
-  return { type: "doc", content };
-}
-
-const openStacks = [];
-after(async () => {
-  await Promise.all(
-    openStacks.map(
-      ({ server, hocuspocus }) =>
-        new Promise((resolve) => {
-          server.close(() => {
-            Promise.resolve(hocuspocus.destroy?.()).finally(resolve);
-          });
-        }),
-    ),
-  );
-});
-
-async function spawnCollabStack(seedDoc) {
-  const state = { lastDoc: null };
-  const hocuspocus = new Hocuspocus({
-    quiet: true,
-    async onLoadDocument() {
-      return buildYDoc(seedDoc);
-    },
-    async onChange(data) {
-      try {
-        state.lastDoc = fragmentToJson(data.document.getXmlFragment("default"));
-      } catch {
-        /* ignore teardown-race decode errors */
-      }
-    },
-  });
-  const wss = new WebSocketServer({ noServer: true });
-  const server = http.createServer((req, res) => {
-    let raw = "";
-    req.on("data", (c) => (raw += c));
-    req.on("end", () => {
-      if (req.url === "/api/auth/login") {
-        res.writeHead(200, {
-          "Content-Type": "application/json",
-          "Set-Cookie": "authToken=t; Path=/; HttpOnly",
-        });
-        res.end(JSON.stringify({ success: true }));
-        return;
-      }
-      if (req.url === "/api/auth/collab-token") {
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ data: { token: "collab-jwt" } }));
-        return;
-      }
-      res.writeHead(404, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ message: "not found" }));
-    });
-  });
-  server.on("upgrade", (request, socket, head) => {
-    if (!request.url || !request.url.startsWith("/collab")) {
-      socket.destroy();
-      return;
-    }
-    wss.handleUpgrade(request, socket, head, (ws) => {
-      hocuspocus.handleConnection(ws, request);
-    });
-  });
-  const baseURL = await new Promise((resolve) => {
-    server.listen(0, "127.0.0.1", () => {
-      resolve(`http://127.0.0.1:${server.address().port}/api`);
-    });
-  });
-  openStacks.push({ server, hocuspocus });
-  return { state, baseURL };
-}
-
-function seed() {
-  return {
-    type: "doc",
-    content: [
-      { type: "paragraph", attrs: { id: "p-id" }, content: [{ type: "text", text: "seed" }] },
-    ],
-  };
-}
-
-test("updatePageMarkdown wiring: extensions OFF — `$…$` literal, www not linked, https links", async () => {
-  const { state, baseURL } = await spawnCollabStack(seed());
-  const client = new DocmostClient(baseURL, "e@x.com", "pw");
-
-  await client.updatePage(PAGE, "cfg $x=1$ and www.host.com and https://ex.com");
-
-  assert.ok(state.lastDoc, "a document was persisted");
-  assert.equal(findAll(state.lastDoc, "mathInline").length, 0, "no phantom math from an agent write");
-  assert.ok(allText(state.lastDoc).includes("$x=1$"), "literal dollars preserved");
-  assert.ok(allText(state.lastDoc).includes("www.host.com"), "bare domain preserved as text");
-  // The explicit https URL still links (only the schemeless autolink is off).
-  const links = findAll(state.lastDoc, "text").filter((t) =>
-    t.marks?.some((m) => m.type === "link"),
-  );
-  assert.ok(links.some((t) => t.text?.includes("ex.com")), "explicit https still links");
-});
-
-test("import_page_markdown wiring: DEFAULTS — exported `$x^2$` re-imports AS a math node (#328)", async () => {
-  const { state, baseURL } = await spawnCollabStack(seed());
-  const client = new DocmostClient(baseURL, "e@x.com", "pw");
-
-  // A self-contained docmost markdown file whose body carries a math span (as the
-  // exporter emits it). import_page_markdown must import it with math ON.
-  const meta = { version: 1, pageId: PAGE, slugId: "s", title: "T", spaceId: "sp", parentPageId: null };
-  const fullMd = serializeDocmostMarkdown(meta, "energy is $x^2$ here", []);
-
-  await client.importPageMarkdown(PAGE, fullMd);
-
-  assert.ok(state.lastDoc, "a document was persisted");
-  assert.equal(
-    findAll(state.lastDoc, "mathInline").length,
-    1,
-    "the lossless round-trip is intact: math survives import_page_markdown",
-  );
-});

packages/mcp/test/unit/mcp-write-extensions-off.test.mjs

@@ -1,108 +0,0 @@
-// #502: the two layered markdown extensions (`$…$` math, schemeless fuzzy
-// autolink) are decided PER CALLER of the shared write importer, not hardcoded in
-// the wrapper — because the callers need OPPOSITE behavior:
-//   - AGENT-authored plain markdown (updatePageMarkdown, patch_node/insert_node)
-//     -> extensions OFF: a `$…$` config span stays literal, a bare `www.host` is
-//     not autolinked, an explicit `https://…` still links.
-//   - FULL-FILE round-trip import (import_page_markdown, #328 lossless) ->
-//     DEFAULTS (extensions ON): an exported math node's `$x^2$` re-imports AS a
-//     math node, so the export→import pair is NOT broken.
-// This unit file pins the importer contract at each of those semantics. The
-// caller-WIRING (that each client method passes the right options) is pinned by
-// the collab-backed test in mock/write-path-extensions-wiring.test.mjs.
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { markdownToProseMirrorCanonical } from "../../build/lib/collaboration.js";
-import { importMarkdownFragment } from "../../build/lib/markdown-fragment.js";
-import {
-  markdownToProseMirror,
-  convertProseMirrorToMarkdown,
-} from "@docmost/prosemirror-markdown";
-
-const OFF = { parseMath: false, fuzzyLinkify: false };
-
-function findAll(node, type, acc = []) {
-  if (!node || typeof node !== "object") return acc;
-  if (node.type === type) acc.push(node);
-  if (Array.isArray(node.content)) for (const c of node.content) findAll(c, type, acc);
-  return acc;
-}
-function allText(node, acc = []) {
-  if (!node || typeof node !== "object") return acc.join("");
-  if (node.type === "text" && typeof node.text === "string") acc.push(node.text);
-  if (Array.isArray(node.content)) for (const c of node.content) allText(c, acc);
-  return acc.join("");
-}
-function hasLink(node) {
-  return findAll(node, "text").some((t) => t.marks?.some((m) => m.type === "link"));
-}
-
-// --- AGENT-write semantics (updatePageMarkdown): extensions OFF -----------------
-
-test("agent-write importer (OFF): `$…$` config stays literal, no math node", async () => {
-  const doc = await markdownToProseMirrorCanonical("export A=$FOO and B=$BAR done", OFF);
-  assert.equal(findAll(doc, "mathInline").length, 0);
-  assert.equal(allText(doc), "export A=$FOO and B=$BAR done");
-});
-
-test("agent-write importer (OFF): schemeless www NOT linked; explicit https STILL linked", async () => {
-  const bare = await markdownToProseMirrorCanonical("see www.example.com here", OFF);
-  assert.equal(hasLink(bare), false);
-  assert.equal(allText(bare), "see www.example.com here");
-
-  const explicit = await markdownToProseMirrorCanonical("see https://example.com here", OFF);
-  assert.equal(hasLink(explicit), true);
-});
-
-test("agent-write importer (OFF): heading + list structure preserved", async () => {
-  const doc = await markdownToProseMirrorCanonical("## Heading\n\n- one\n- two", OFF);
-  assert.equal(findAll(doc, "heading").length, 1);
-  assert.equal(findAll(doc, "bulletList").length, 1);
-});
-
-test("fragment importer (patch_node/insert_node) is OFF: `$x=1$` literal, https links", async () => {
-  const { blocks } = await importMarkdownFragment("cfg $x=1$ and https://ex.com");
-  const doc = { type: "doc", content: blocks };
-  assert.equal(findAll(doc, "mathInline").length, 0);
-  assert.equal(hasLink(doc), true);
-  assert.ok(allText(doc).includes("$x=1$"));
-});
-
-// --- FULL-FILE import semantics (import_page_markdown): DEFAULTS (math ON) ------
-
-test("import_page_markdown importer (DEFAULTS): `$x^2$` DOES create a math node", async () => {
-  // markdownToProseMirrorCanonical WITHOUT options == what import_page_markdown
-  // passes. Math must survive (this is the REAL importer, not the package default).
-  const doc = await markdownToProseMirrorCanonical("$x^2$");
-  assert.equal(findAll(doc, "mathInline").length, 1);
-  assert.equal(findAll(doc, "mathInline")[0].attrs.text, "x^2");
-});
-
-test("import_page_markdown (DEFAULTS): #328 lossless export->import keeps math (round-trip)", async () => {
-  // The exporter serializes a math node as readable `$x^2$`; re-importing through
-  // the REAL import_page_markdown importer (markdownToProseMirrorCanonical, no
-  // options) must yield a math node again and be byte-stable. Under the BUGGY code
-  // (canonical hardcoded parseMath:false) doc2 would be literal text -> this test
-  // would REDDEN.
-  const source = {
-    type: "doc",
-    content: [{ type: "paragraph", content: [{ type: "mathInline", attrs: { text: "x^2" } }] }],
-  };
-  const md1 = convertProseMirrorToMarkdown(source);
-  const doc2 = await markdownToProseMirrorCanonical(md1); // real import path, defaults
-  assert.equal(findAll(doc2, "mathInline").length, 1, "math survives the round-trip import");
-  const md2 = convertProseMirrorToMarkdown(doc2);
-  assert.equal(md2, md1, "export is byte-stable across the round-trip");
-});
-
-test("import_page_markdown (DEFAULTS): a schemeless www IS autolinked", async () => {
-  const doc = await markdownToProseMirrorCanonical("see www.example.com here");
-  assert.equal(hasLink(doc), true);
-});
-
-// --- Package default importer (editor/file-import/git-sync) is UNCHANGED --------
-
-test("PACKAGE default importer keeps math ON (editor/file/git-sync path)", async () => {
-  const doc = await markdownToProseMirror("$x^2$");
-  assert.equal(findAll(doc, "mathInline").length, 1);
-});

packages/prosemirror-markdown/src/lib/index.ts

@@ -25,7 +25,6 @@ export {
   markdownToProseMirror,
   markdownToProseMirrorSync,
 } from "./markdown-to-prosemirror.js";
-export type { MarkdownImportOptions } from "./markdown-to-prosemirror.js";
 
 // Foreign-markdown normalizer (#493): the input-liberal pre-pass that rewrites
 // GFM `[^id]` reference footnotes to canonical inline `^[body]`. Two variants:

packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts

@@ -7,7 +7,7 @@
  * natively through the collab gateway, so no websocket/Yjs write-path lives
  * here.
  */
-import { Marked, Tokenizer } from "marked";
+import { Marked } from "marked";
 import { parseHtmlDocument, generateJsonWith } from "./dom-parser.js";
 import type { TokenizerExtension, RendererExtension } from "marked";
 import { docmostExtensions } from "./docmost-schema.js";
@@ -230,88 +230,19 @@ function escapeFootnoteAttr(value: string): string {
   return String(value).replace(/&/g, "&").replace(/"/g, """);
 }
 
-/**
- * Options controlling which of the two *layered* markdown extensions the
- * canonical importer applies. Both default to `true`, so the human editor,
- * file-import and git-sync paths keep their existing behavior byte-for-byte;
- * ONLY the MCP markdown-write path opts OUT (see #502).
- *
- * The extensions are optional because they are the SOURCE of two silent
- * corruptions when an AGENT writes plain prose/config as markdown:
- *   - `parseMath`: a `$…$` span becomes a `mathInline` node. An agent writing a
- *     config like `export A=$FOO and B=$BAR` gets `$FOO and B=$` silently turned
- *     into a formula. With `parseMath:false` the `$` stays literal text (real
- *     formulas go through `update_page_json` with `mathInline`/`mathBlock`).
- *   - `fuzzyLinkify`: marked's GFM autolinker turns a SCHEMELESS `www.foo.com`
- *     (and email) into a link. With `fuzzyLinkify:false` a schemeless domain
- *     stays literal text; an EXPLICIT `https://…` STILL becomes a link (only the
- *     fuzzy, schemeless autolink is suppressed).
- */
-export interface MarkdownImportOptions {
-  /** Apply the `$…$` / `$$…$$` math extensions (default true). */
-  parseMath?: boolean;
-  /** Apply marked's GFM schemeless (fuzzy) autolinker (default true). */
-  fuzzyLinkify?: boolean;
-}
-
-/**
- * `fuzzyLinkify:false` override of marked's built-in GFM `url` inline tokenizer.
- *
- * The stock tokenizer autolinks THREE shapes: a schemeless `www.host` domain, a
- * bare email, and an EXPLICIT `scheme://…` URL. #502 wants only the last kept —
- * a schemeless domain/email an agent typed as prose must stay literal text, but
- * a deliberate `https://…` still links. We delegate to the original tokenizer
- * and, when it matched, DROP the token (returning `undefined`, so the run stays
- * literal text) unless the matched RAW text carries an explicit `scheme:` prefix.
- * `www.`/email matches have no scheme in their raw text, so they are dropped;
- * `https://…`/`ftp://…` keep their link.
- */
-const SCHEME_PREFIX_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
-const noFuzzyUrlTokenizer = {
-  url(this: any, src: string) {
-    const token = Tokenizer.prototype.url.call(this, src) as any;
-    if (!token) return token;
-    // Keep only explicit-scheme URLs; schemeless `www.`/email matches -> literal.
-    return SCHEME_PREFIX_RE.test(token.raw) ? token : undefined;
-  },
-};
-
-/**
- * Build a dedicated `marked` instance for a given extension combination: default
- * (GFM) options plus the `==` highlight and `^[…]` footnote inline extensions
- * ALWAYS, the `$…$`/`$$…$$` math extensions only when `parseMath`, and the
- * schemeless-autolink suppressor only when `!fuzzyLinkify`. Built on a private
- * `Marked` instance so nothing leaks into the global `marked` singleton.
- */
-function buildMarkedInstance(parseMath: boolean, fuzzyLinkify: boolean): Marked {
-  const extensions: (TokenizerExtension & RendererExtension)[] = [
+// Dedicated marked instance: default (GFM) options plus the `==` highlight
+// inline extension, the `$…$` / `$$…$$` math extensions (#293 canon #6), and the
+// `^[…]` inline-footnote extension (#293 canon #2). Constructed once at module
+// load so the extensions are registered exactly once and never mutate the global
+// `marked` singleton.
+const markedInstance = new Marked().use({
+  extensions: [
     highlightMarkExtension,
+    mathInlineExtension,
+    mathBlockExtension,
     footnoteInlineExtension,
-  ];
-  if (parseMath) {
-    extensions.push(mathInlineExtension, mathBlockExtension);
-  }
-  const instance = new Marked().use({ extensions });
-  if (!fuzzyLinkify) {
-    instance.use({ tokenizer: noFuzzyUrlTokenizer as any });
-  }
-  return instance;
-}
-
-// Memoize one instance per (parseMath, fuzzyLinkify) combination so the
-// extensions are registered exactly once per combo (never on the global
-// singleton). The default `(true, true)` instance preserves the pre-#502
-// behavior exactly for the editor/file-import/git-sync paths.
-const markedInstanceCache = new Map<string, Marked>();
-function getMarkedInstance(parseMath: boolean, fuzzyLinkify: boolean): Marked {
-  const key = `${parseMath}:${fuzzyLinkify}`;
-  let instance = markedInstanceCache.get(key);
-  if (!instance) {
-    instance = buildMarkedInstance(parseMath, fuzzyLinkify);
-    markedInstanceCache.set(key, instance);
-  }
-  return instance;
-}
+  ],
+});
 
 // NOTE: this module no longer installs a module-level `global.window`/`document`
 // jsdom shim. The HTML->DOM passes below (bridgeTaskLists / applyCommentDirectives
@@ -370,7 +301,7 @@ const CODE_FENCE_RE = /^(\s*)(`{3,}|~{3,})/;
 // preprocess is sync. Keeping it sync lets a sync converter entry
 // (`markdownToProseMirrorSync`, used by the client's chat renderer which must
 // stay synchronous) share this exact logic with the async entry.
-function preprocessCallouts(markdown: string, markedInstance: Marked): string {
+function preprocessCallouts(markdown: string): string {
   // Defensive cap: skip preprocessing for pathologically large inputs.
   if (markdown.length > MAX_CALLOUT_PREPROCESS_BYTES) {
     return markdown;
@@ -1024,7 +955,7 @@ function applyCommentDirectives(html: string): string {
 // sups stay inert) rather than hang.
 const MAX_FOOTNOTE_ROUNDS = 10000;
 
-function assembleFootnotes(html: string, markedInstance: Marked): string {
+function assembleFootnotes(html: string): string {
   // Cheap early-out: nothing carries a footnote body -> nothing to assemble.
   if (!html.includes("data-fn-text")) return html;
   const document = parseHtmlDocument(html);
@@ -1150,18 +1081,8 @@ function stripEmptyParagraphs(node: any): any {
  * for every existing Node consumer). A sync entry is REQUIRED by the client's
  * chat renderer, which runs inside a React render/useMemo and cannot await.
  */
-export function markdownToProseMirrorSync(
-  markdownContent: string,
-  options?: MarkdownImportOptions,
-): any {
-  // Select the marked instance for this call's extension combination. Defaults
-  // (math + fuzzy autolink ON) preserve the editor/file-import/git-sync paths;
-  // the MCP markdown-write path passes both false (#502).
-  const markedInstance = getMarkedInstance(
-    options?.parseMath ?? true,
-    options?.fuzzyLinkify ?? true,
-  );
-  const withCallouts = preprocessCallouts(markdownContent, markedInstance);
+export function markdownToProseMirrorSync(markdownContent: string): any {
+  const withCallouts = preprocessCallouts(markdownContent);
   const html = markedInstance.parse(withCallouts) as string;
   // Materialize comment directives (#293 #9 attached textAlign; #5 standalone
   // subpages/pageBreak) while the comment nodes still exist, before generateJSON
@@ -1170,7 +1091,7 @@ export function markdownToProseMirrorSync(
   // #293 canon #2: assemble the doc-level footnote list from the `<sup
   // data-fn-text>` markers (from `^[…]` or the raw-HTML column form) before
   // generateJSON, so references + definitions materialize into the schema model.
-  const withFootnotes = assembleFootnotes(withAttrs, markedInstance);
+  const withFootnotes = assembleFootnotes(withAttrs);
   const bridged = bridgeTaskLists(withFootnotes);
   const doc = generateJsonWith(bridged, docmostExtensions);
   return stripEmptyParagraphs(doc);
@@ -1183,7 +1104,6 @@ export function markdownToProseMirrorSync(
  */
 export async function markdownToProseMirror(
   markdownContent: string,
-  options?: MarkdownImportOptions,
 ): Promise<any> {
-  return markdownToProseMirrorSync(markdownContent, options);
+  return markdownToProseMirrorSync(markdownContent);
 }

packages/prosemirror-markdown/test/markdown-import-options.test.ts

@@ -1,170 +0,0 @@
-import { describe, expect, it } from 'vitest';
-// Import DIRECTLY from src (like math.test.ts) so we exercise the real
-// converter and its module-load jsdom setup.
-import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
-import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
-
-// ---------------------------------------------------------------------------
-// #502: the canonical importer is parameterized with `{ parseMath, fuzzyLinkify }`
-// (both DEFAULT true). The MCP markdown-WRITE path passes both false so an agent's
-// plain prose/config is imported LITERALLY:
-//   - parseMath:false  -> a `$…$` span stays literal text (no phantom mathInline)
-//   - fuzzyLinkify:false -> a SCHEMELESS `www.host`/email stays literal text; an
-//     EXPLICIT `https://…` STILL links (only the fuzzy autolink is suppressed).
-// The DEFAULTS (editor/file-import/git-sync) keep math + fuzzy autolink ON, so
-// this file also pins that the defaults are UNCHANGED.
-// ---------------------------------------------------------------------------
-
-const OFF = { parseMath: false, fuzzyLinkify: false } as const;
-
-// Collect the first paragraph's inline children (the common assertion target).
-function firstParaInline(doc: any): any[] {
-  const p = doc.content?.find((n: any) => n.type === 'paragraph');
-  return p?.content ?? [];
-}
-
-function findAll(node: any, type: string, acc: any[] = []): any[] {
-  if (!node || typeof node !== 'object') return acc;
-  if (node.type === type) acc.push(node);
-  if (Array.isArray(node.content)) {
-    for (const c of node.content) findAll(c, type, acc);
-  }
-  return acc;
-}
-
-// Flatten every text node's text (ignoring marks/structure) into one string.
-function allText(node: any, acc: string[] = []): string {
-  if (!node || typeof node !== 'object') return acc.join('');
-  if (node.type === 'text' && typeof node.text === 'string') acc.push(node.text);
-  if (Array.isArray(node.content)) {
-    for (const c of node.content) allText(c, acc);
-  }
-  return acc.join('');
-}
-
-describe('#502 importer options — extensions OFF (MCP write path)', () => {
-  it('a `$…$` config span stays literal text (no mathInline node)', async () => {
-    const md = 'export A=$FOO and B=$BAR done';
-    const doc = await markdownToProseMirror(md, OFF);
-    expect(findAll(doc, 'mathInline')).toHaveLength(0);
-    expect(allText(doc)).toBe('export A=$FOO and B=$BAR done');
-  });
-
-  it('a real-looking `$x=1$` span stays literal text', async () => {
-    const doc = await markdownToProseMirror('$x=1$', OFF);
-    expect(findAll(doc, 'mathInline')).toHaveLength(0);
-    expect(allText(doc)).toBe('$x=1$');
-  });
-
-  it('the reported `($ticket_lifetime=2592000)` config stays literal', async () => {
-    const doc = await markdownToProseMirror('($ticket_lifetime=2592000)', OFF);
-    expect(findAll(doc, 'mathInline')).toHaveLength(0);
-    expect(allText(doc)).toBe('($ticket_lifetime=2592000)');
-  });
-
-  it('a `$$…$$` block stays literal (no mathBlock node)', async () => {
-    const doc = await markdownToProseMirror('$$\nx^2\n$$', OFF);
-    expect(findAll(doc, 'mathBlock')).toHaveLength(0);
-    expect(allText(doc)).toContain('x^2');
-  });
-
-  it('a SCHEMELESS `www.example.com` is NOT autolinked', async () => {
-    const doc = await markdownToProseMirror('see www.example.com here', OFF);
-    const inline = firstParaInline(doc);
-    expect(inline.some((n: any) => n.marks?.some((m: any) => m.type === 'link'))).toBe(false);
-    expect(allText(doc)).toBe('see www.example.com here');
-  });
-
-  it('a bare dotted domain `gitea.vvzvlad.xyz` stays literal text', async () => {
-    const doc = await markdownToProseMirror('see gitea.vvzvlad.xyz here', OFF);
-    expect(findAll(doc, 'text').every((t: any) => !t.marks?.some((m: any) => m.type === 'link'))).toBe(true);
-  });
-
-  it('an EXPLICIT `https://…` STILL becomes a link', async () => {
-    const doc = await markdownToProseMirror('see https://example.com here', OFF);
-    const linked = firstParaInline(doc).find((n: any) =>
-      n.marks?.some((m: any) => m.type === 'link'),
-    );
-    expect(linked?.text).toBe('https://example.com');
-    const link = linked.marks.find((m: any) => m.type === 'link');
-    expect(link.attrs.href).toBe('https://example.com');
-  });
-
-  it('`foo_bar_baz` is not italicized (CommonMark, unaffected by options)', async () => {
-    const doc = await markdownToProseMirror('foo_bar_baz', OFF);
-    expect(findAll(doc, 'text').some((t: any) => t.marks?.some((m: any) => m.type === 'italic' || m.type === 'em'))).toBe(false);
-    expect(allText(doc)).toBe('foo_bar_baz');
-  });
-
-  it('block STRUCTURE (headings, lists, code fence) is preserved with extensions off', async () => {
-    const md = '## Heading\n\n- one\n- two\n\n```\ncode $x$ here\n```';
-    const doc = await markdownToProseMirror(md, OFF);
-    expect(findAll(doc, 'heading')).toHaveLength(1);
-    expect(findAll(doc, 'bulletList')).toHaveLength(1);
-    expect(findAll(doc, 'codeBlock')).toHaveLength(1);
-    // The `$x$` inside the code fence never becomes math regardless.
-    expect(findAll(doc, 'mathInline')).toHaveLength(0);
-  });
-});
-
-describe('#502 importer options — DEFAULTS unchanged (editor/file/git-sync)', () => {
-  it('DEFAULT: `$x^2$` DOES create a mathInline node (file-import unaffected)', async () => {
-    const doc = await markdownToProseMirror('$x^2$');
-    expect(findAll(doc, 'mathInline')).toHaveLength(1);
-    expect(findAll(doc, 'mathInline')[0].attrs.text).toBe('x^2');
-  });
-
-  it('DEFAULT: a schemeless `www.example.com` IS autolinked', async () => {
-    const doc = await markdownToProseMirror('see www.example.com here');
-    const linked = firstParaInline(doc).find((n: any) =>
-      n.marks?.some((m: any) => m.type === 'link'),
-    );
-    expect(linked?.text).toBe('www.example.com');
-  });
-
-  it('DEFAULT: explicitly passing {parseMath:true, fuzzyLinkify:true} equals no-options', async () => {
-    const a = await markdownToProseMirror('$x^2$ and www.foo.com');
-    const b = await markdownToProseMirror('$x^2$ and www.foo.com', {
-      parseMath: true,
-      fuzzyLinkify: true,
-    });
-    expect(JSON.stringify(b)).toBe(JSON.stringify(a));
-  });
-
-  it('round-trip export->import at the PACKAGE-DEFAULT layer keeps math (file-import / #328)', async () => {
-    // The package DEFAULT importer is what the server file-import path uses. A
-    // page holding real math is exported, then re-imported with DEFAULTS (math
-    // ON): the mathInline survives. (The tool-level import_page_markdown round-
-    // trip, which goes through mcp's markdownToProseMirrorCanonical, is pinned
-    // authoritatively in @docmost/mcp's mcp-write-extensions-off test.)
-    const source = {
-      type: 'doc',
-      content: [
-        { type: 'paragraph', content: [{ type: 'mathInline', attrs: { text: 'x^2' } }] },
-      ],
-    };
-    const md1 = convertProseMirrorToMarkdown(source);
-    const doc2 = await markdownToProseMirror(md1); // DEFAULTS -> math on
-    expect(findAll(doc2, 'mathInline')).toHaveLength(1);
-    const md2 = convertProseMirrorToMarkdown(doc2);
-    expect(md2).toBe(md1); // byte-stable
-  });
-});
-
-describe('#502 mutation guard', () => {
-  // If a future change silently flipped the MCP write path back to parseMath:true,
-  // the OFF assertion below would go RED — this pins the discriminating behavior.
-  it('with parseMath:true the same span DOES become math (proves the flag drives it)', async () => {
-    const on = await markdownToProseMirror('$x=1$', { parseMath: true, fuzzyLinkify: false });
-    expect(findAll(on, 'mathInline')).toHaveLength(1);
-    const off = await markdownToProseMirror('$x=1$', OFF);
-    expect(findAll(off, 'mathInline')).toHaveLength(0);
-  });
-
-  it('with fuzzyLinkify:true the same www domain DOES link (proves the flag drives it)', async () => {
-    const on = await markdownToProseMirror('www.example.com', { parseMath: false, fuzzyLinkify: true });
-    expect(findAll(on, 'text').some((t: any) => t.marks?.some((m: any) => m.type === 'link'))).toBe(true);
-    const off = await markdownToProseMirror('www.example.com', OFF);
-    expect(findAll(off, 'text').some((t: any) => t.marks?.some((m: any) => m.type === 'link'))).toBe(false);
-  });
-});